@readme/markdown 14.6.0 → 14.7.1

package/dist/main.js

@@ -12273,11 +12273,20 @@ const Image = (Props) => {
             lightboxOverlay));
     }
     if (children || caption) {
-        return (external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.createElement("figure", null,
-            closedLightbox(alt || 'Expand image', external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.createElement(external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.Fragment, null,
-                imgElement,
-                external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.createElement("figcaption", null, children || caption))),
-            lightboxOverlay));
+        // Mirrors the framed pattern: left/right captioned figures float and shrink
+        // to fit so a long caption doesn't widen the float past the image.
+        const isFloating = (align === 'left' || align === 'right') && !noWrap;
+        const figureClass = [
+            (align === 'left' || align === 'right') && `img-figure-${align}`,
+            noWrap && 'img-no-wrap',
+        ]
+            .filter(Boolean)
+            .join(' ');
+        const figureStyle = isFloating && typeof width === 'string' && width.endsWith('%') ? { width } : undefined;
+        return (external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.createElement("figure", { className: figureClass || undefined, style: figureStyle },
+            closedLightbox(alt || 'Expand image', imgElement),
+            lightboxOverlay,
+            external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.createElement("figcaption", null, children || caption)));
     }
     return (external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.createElement(external_amd_react_commonjs_react_commonjs2_react_root_React_umd_react_.Fragment, null,
         closedLightbox('Expand image', imgElement),
@@ -13109,6 +13118,7 @@ const INLINE_COMPONENT_TAGS = new Set(['Anchor', 'Glossary']);
 /**
  * PascalCase tags that have their own dedicated tokenizer / transformer
  * and must not be claimed by the generic `mdxComponent` construct.
+ * Subject to change as we add more dedicated tokenizers.
  */
 const DEDICATED_COMPONENT_TAGS = ['HTMLBlock', 'Table'];
 /**
@@ -13119,6 +13129,14 @@ const GENERIC_MDX_COMPONENT_EXCLUDED_TAGS = new Set([
     ...DEDICATED_COMPONENT_TAGS,
     ...INLINE_COMPONENT_TAGS,
 ]);
+/**
+ * Tags the micromark `mdxComponent` tokenizer must not claim, which
+ * are inline components and those that have their own dedicated tokenizer
+ */
+const TOKENIZER_MDX_COMPONENT_EXCLUDED_TAGS = new Set([
+    'Table',
+    ...INLINE_COMPONENT_TAGS,
+]);
 /**
  * Lowercased variant of {@link INLINE_COMPONENT_TAGS} for consumers that
  * run after rehype (where hast `tagName` is normalized to lowercase).
@@ -54513,18 +54531,28 @@ const isMDXEsm = (node) => {
  * Takes an HTML string and formats it for display in the editor. Removes leading/trailing newlines
  * and unindents the HTML.
  *
- * @param {string} html - HTML content from template literal
+ * @param {string} html - cooked HTML payload (callers strip any template-literal backticks first)
+ * @param {number} [openingTagIndent=0] - column the `<HTMLBlock>` opening tag sits at, used to
+ *   dedent each content line so its indentation reads relative to the tag, not the line start
  * @returns {string} processed HTML
  */
-function formatHtmlForMdxish(html) {
-    // Remove leading/trailing backticks if present, since they're used to keep the HTML
-    // from being parsed prematurely
-    let processed = html;
-    if (processed.startsWith('`') && processed.endsWith('`')) {
-        processed = processed.slice(1, -1);
-    }
+function formatHtmlForMdxish(html, openingTagIndent = 0) {
     // Removes the leading/trailing newlines
-    let cleaned = processed.replace(/^\s*\n|\n\s*$/g, '');
+    let cleaned = html.replace(/^\s*\n|\n\s*$/g, '');
+    // Strip / deindent the lines in the HTML string so that the indents are relative
+    // to the opening HTMLBlock tag, not the literal line start
+    // Keep any deeper indent
+    if (openingTagIndent > 0) {
+        cleaned = cleaned
+            .split('\n')
+            .map(line => {
+            let i = 0;
+            while (i < openingTagIndent && (line[i] === ' ' || line[i] === '\t'))
+                i += 1;
+            return line.slice(i);
+        })
+            .join('\n');
+    }
     // Convert literal \n sequences to actual newlines only inside <pre> and <code>.
     // Because <pre> needs to respect the newline visual and
     // escape characters should be processed in the <code> tag.
@@ -75681,11 +75709,15 @@ const symmetrizePair = (html, { openStart, openEnd, closeStart, closeEnd }) => {
     const postCloser = html.slice(closeEnd, closeLine.end);
     const openerHasExtras = preOpener.trim().length > 0 || postOpener.trim().length > 0;
     const closerHasExtras = preCloser.trim().length > 0 || postCloser.trim().length > 0;
-    // Both match (both bare or both attached) — mdxjs parses this fine.
-    if (openerHasExtras === closerHasExtras)
+    // A blank line splits opener/closer into separate paragraphs.
+    // If either tag is attached to surrounding text, mdxjs can fail to match.
+    const spansBlankLine = /\n[^\S\n]*\n/.test(html.slice(openEnd, closeStart));
+    // If both sides are already symmetric, keep as-is.
+    // Exception: attached + blank-line-split pairs still need normalization.
+    if (openerHasExtras === closerHasExtras && !(openerHasExtras && spansBlankLine))
         return [];
-    // Asymmetric. Push non-tag content on the offending side to its own line,
-    // visually aligning the inserted line with the existing whitespace prefix.
+    // For asymmetric (or attached-but-split) pairs, move side content to its own
+    // line so opener/closer become line-symmetric.
     const indentFor = (linePrefix) => linePrefix.match(/^\s*/)?.[0] ?? '';
     const inserts = [];
     if (openerHasExtras) {
@@ -76131,6 +76163,7 @@ const repairUnclosedTags = (html) => {
 
 
 
+
 
 
 const isTableCell = (node) => isMDXElement(node) && ['th', 'td'].includes(node.name);
@@ -76231,6 +76264,15 @@ const processTableNode = (node, index, parent, documentPosition) => {
     const { align: alignAttr } = getAttrs(node);
     const align = Array.isArray(alignAttr) ? alignAttr : null;
     let tableHasFlowContent = false;
+    // An `<HTMLBlock>` (still a JSX element here; converted to `html-block` by
+    // `mdxishHtmlBlocks` after this transformer) is block-level content that a
+    // markdown table cell can't represent, so keep the table as a JSX `<Table>`.
+    visit(node, candidate => candidate.type === NodeTypes.htmlBlock ||
+        ((candidate.type === 'mdxJsxFlowElement' || candidate.type === 'mdxJsxTextElement') &&
+            candidate.name === 'HTMLBlock'), () => {
+        tableHasFlowContent = true;
+        return EXIT;
+    });
     // Re-parse text-only cells through markdown and detect flow content
     visit(node, isTableCell, (cell) => {
         if (!isTextOnly(cell.children))
@@ -76313,13 +76355,32 @@ const processTableNode = (node, index, parent, documentPosition) => {
     // remarkMdx wraps inline `<tr>`s in a paragraph; unwrap one level so the
     // hasRow check below sees them.
     const flattenSectionChildren = (nodes) => nodes.flatMap(n => n.type === 'paragraph' && 'children' in n && Array.isArray(n.children) ? n.children : [n]);
-    visit(node, isMDXElement, (child) => {
-        if (child.name !== 'thead' && child.name !== 'tbody')
+    // Iterate the table's direct children in document order. Rows may live
+    // inside a `<thead>`/`<tbody>` section, or sit bare directly under the table
+    // with no section wrapper — both are collected here so the first row becomes
+    // the markdown table header.
+    const tableChildren = flattenSectionChildren(node.children);
+    tableChildren.forEach(child => {
+        if (!isMDXElement(child))
+            return;
+        const childElement = child;
+        // Path for a `<tr>` directly under the table, without a `<thead>`/`<tbody>` wrapper.
+        if (childElement.name === 'tr') {
+            children.push({
+                type: 'tableRow',
+                children: collectCells(childElement),
+                position: childElement.position,
+            });
+            return;
+        }
+        // Path for when the rows are wrapped in a `<thead>`/`<tbody>`
+        // We visit & collect the entire rows under them directly here
+        if (childElement.name !== 'thead' && childElement.name !== 'tbody')
             return;
-        const sectionChildren = flattenSectionChildren(child.children);
+        const sectionChildren = flattenSectionChildren(childElement.children);
         const hasRow = sectionChildren.some(c => isMDXElement(c) && c.name === 'tr');
         if (hasRow) {
-            visit(child, isMDXElement, (row) => {
+            visit(childElement, isMDXElement, (row) => {
                 if (row.name !== 'tr')
                     return;
                 children.push({
@@ -76333,7 +76394,7 @@ const processTableNode = (node, index, parent, documentPosition) => {
             // No `<tr>`, chunk bare cells into rows using the prior row's column
             // count (e.g. from `<thead>`), so 4 bare `<td>`s under a 2-col header
             // become 2 rows of 2.
-            const cells = collectCells(child);
+            const cells = collectCells(childElement);
             if (cells.length === 0)
                 return;
             const cols = children[0]?.children?.length || cells.length;
@@ -76341,11 +76402,12 @@ const processTableNode = (node, index, parent, documentPosition) => {
                 children.push({
                     type: 'tableRow',
                     children: cells.slice(i, i + cols),
-                    position: child.position,
+                    position: childElement.position,
                 });
             }
         }
     });
+    // Output the markdown table node
     const firstRow = children[0];
     const columnCount = firstRow?.children?.length || 0;
     const alignArray = align && columnCount > 0
@@ -100871,7 +100933,7 @@ function createTokenize(mode) {
                 return tagNameRest;
             }
             // Tag name complete — check exclusions
-            if (GENERIC_MDX_COMPONENT_EXCLUDED_TAGS.has(tagName)) {
+            if (TOKENIZER_MDX_COMPONENT_EXCLUDED_TAGS.has(tagName)) {
                 return nok(code);
             }
             depth = 1;
@@ -102962,557 +103024,158 @@ const magicBlockTransformer = (options = {}) => tree => {
 };
 /* harmony default export */ const magic_block_transformer = (magicBlockTransformer);
 
-;// ./lib/micromark/jsx-comment/pattern.ts
-/**
- * Matches a JSX comment: `{/*`, content, `*\/}` — no whitespace tolerated
- * between the braces and the comment markers.
- *
- * This grammar is mirrored by the flow tokenizer in ./syntax.ts. Any change
- * here needs a mirror change in the state machine; the parity test in
- * __tests__/lib/micromark/jsx-comment-pattern-parity.test.ts locks the two
- * together so they can't silently drift.
- */
-const JSX_COMMENT_REGEX = /\{\/\*[^*]*(?:\*(?!\/)[^*]*)*\*\/\}/g;
+;// ./processor/transform/mdxish/mdxish-html-blocks.ts
 
-;// ./processor/transform/mdxish/preprocess-jsx-expressions.ts
 
 
-// Base64 encode (Node.js + browser compatible)
-function base64Encode(str) {
-    if (typeof Buffer !== 'undefined') {
-        return Buffer.from(str, 'utf-8').toString('base64');
-    }
-    return btoa(unescape(encodeURIComponent(str)));
-}
-// Base64 decode (Node.js + browser compatible)
-function base64Decode(str) {
-    if (typeof Buffer !== 'undefined') {
-        return Buffer.from(str, 'base64').toString('utf-8');
-    }
-    return decodeURIComponent(escape(atob(str)));
-}
-// Markers for protected HTMLBlock content (HTML comments avoid markdown parsing issues)
-const HTML_BLOCK_CONTENT_START = '<!--RDMX_HTMLBLOCK:';
-const HTML_BLOCK_CONTENT_END = ':RDMX_HTMLBLOCK-->';
+// `<HTMLBlock …>{`…`}</HTMLBlock>` embedded inside a raw HTML block (e.g. a
+// single-line `<div>…</div>`). CommonMark slurps the whole div as one `html`
+// node, so the tokenizer never sees the HTMLBlock — we recover it here.
+const RAW_HTML_BLOCK_RE = /<HTMLBlock\b([^>]*)>\s*\{\s*`((?:[^`\\]|\\.)*)`\s*\}\s*<\/HTMLBlock>/g;
+// Opening `<HTMLBlock …>` as its own `html` node — produced inside a paragraph
+// when an HTMLBlock appears inline alongside text.
+const HTML_BLOCK_OPEN_RE = /^<HTMLBlock\b([^>]*)>$/;
 /**
- * Base64 encodes HTMLBlock template literal content to prevent markdown parser from consuming <script>/<style> tags.
- *
- * @param content
- * @returns Content with HTMLBlock template literals base64 encoded in HTML comments
- * @example
- * ```typescript
- * const input = '<HTMLBlock>{`<script>alert("xss")</script>`}</HTMLBlock>';
- * protectHTMLBlockContent(input)
- * // Returns: '<HTMLBlock><!--RDMX_HTMLBLOCK:PHNjcmlwdD5hbGVydCgieHNzIik8L3NjcmlwdD4=:RDMX_HTMLBLOCK--></HTMLBlock>'
- * ```
+ * Builds the canonical `html-block` MDAST node the renderer expects.
  */
-function protectHTMLBlockContent(content) {
-    return content.replace(/(<HTMLBlock[^>]*>)\{\s*`((?:[^`\\]|\\.)*)`\s*\}(<\/HTMLBlock>)/g, (_match, openTag, templateContent, closeTag) => {
-        const encoded = base64Encode(templateContent);
-        return `${openTag}${HTML_BLOCK_CONTENT_START}${encoded}${HTML_BLOCK_CONTENT_END}${closeTag}`;
-    });
-}
+const createHtmlBlockNode = (html, position, runScripts, safeMode) => ({
+    position,
+    children: [{ type: 'text', value: html }],
+    type: NodeTypes.htmlBlock,
+    data: {
+        hName: 'html-block',
+        hProperties: {
+            html,
+            ...(runScripts !== undefined && { runScripts }),
+            ...(safeMode !== undefined && { safeMode }),
+        },
+    },
+});
 /**
- * Removes JSX-style comments (e.g., { /* comment *\/ }) from content.
- *
- * @param content
- * @returns Content with JSX comments removed
- * @example
- * ```typescript
- * removeJSXComments('Text { /* comment *\/ } more text')
- * // Returns: 'Text  more text'
- * ```
+ * Reads the cooked string out of a brace expression wrapping a single template
+ * literal (`` `<p>n</p>` `` → `<p>n</p>`).
  */
-function removeJSXComments(content) {
-    return content.replace(JSX_COMMENT_REGEX, '');
-}
-const HTML_ELEM_PLACEHOLDER_PREFIX = '___MDXISH_HTML_ELEM_';
-const HTML_ELEM_PLACEHOLDER = new RegExp(`${HTML_ELEM_PLACEHOLDER_PREFIX}(\\d+)___`, 'g');
-// Matches an HTML element that starts at a line boundary and ends at a line boundary.
-// Allows optional leading indentation and lazily matches until the same closing tag.
-const BLOCK_HTML_RE = /(?<=^|\n)[ \t]*<([a-z][a-zA-Z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>[ \t]*(?=\n|$)/g;
+const extractTemplateLiteral = (value) => {
+    if (!value)
+        return '';
+    const match = value.trim().match(/^`([\s\S]*)`$/);
+    // Non-template-literal bodies (e.g. `{someVar}`) are malformed mdxish input;
+    // returning '' beats shipping JS identifier source as an HTML payload.
+    return match ? match[1] : '';
+};
+const toRunScripts = (raw) => raw === 'true' ? true : raw === 'false' ? false : raw;
+/** Reads an attribute from a raw `<HTMLBlock …>` attribute string. */
+const rawAttr = (attrs, name) => {
+    const quoted = attrs.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+    if (quoted)
+        return quoted[1];
+    const expr = attrs.match(new RegExp(`\\b${name}\\s*=\\s*\\{(true|false)\\}`));
+    if (expr)
+        return expr[1];
+    return new RegExp(`\\b${name}\\b`).test(attrs) ? 'true' : undefined;
+};
+/** Reads an attribute from a parsed `<HTMLBlock>` JSX element. */
+const jsxAttr = (element, name) => {
+    const attr = element.attributes.find(a => a.type === 'mdxJsxAttribute' && a.name === name);
+    if (!attr || attr.type !== 'mdxJsxAttribute')
+        return undefined;
+    if (typeof attr.value === 'string')
+        return attr.value;
+    if (attr.value && typeof attr.value === 'object' && 'value' in attr.value)
+        return attr.value.value;
+    return 'true'; // bare boolean attribute, e.g. <HTMLBlock runScripts />
+};
+/** Builds an `html-block` from a raw attribute string and (unparsed) body. */
+const htmlBlockFromRaw = (attrs, html, position, openingTagIndent = 0) => createHtmlBlockNode(formatHtmlForMdxish(html, openingTagIndent), position, toRunScripts(rawAttr(attrs, 'runScripts')), rawAttr(attrs, 'safeMode'));
 /**
- * Hides line-anchored HTML elements from the brace-escaping pass so we don't leak `\{`
- * into rendered output (rehypeRaw renders the `\` literally, e.g. `<div>{foo</div>`).
+ * Splits a raw `html` node that embeds one or more `<HTMLBlock>`s into
+ * `[html before, html-block, html after, …]`. Returns null when there is none.
  *
- * One carve-out: if an interior line at column 0 has bare text containing `{`, mdxish
- * parses that line as a paragraph and the mdxExpression step would throw without an
- * escape — so we leave that case to the brace balancer.
- */
-function protectHTMLElements(content) {
-    const htmlElements = [];
-    const protectedContent = content.replace(BLOCK_HTML_RE, match => {
-        // Look at the lines between the open and close tags. If any of them starts
-        // at column 0 with bare text (not whitespace, not another tag) and contains
-        // `{`, mdxish will parse that line as a paragraph and the brace as an MDX
-        // expression, which would throw an error. So we let the brace balancer escape it.
-        // Otherwise, we need to extract the sequence to protect it from the brace escaping.
-        const interior = match.split('\n').slice(1, -1);
-        const hazard = interior.some(line => line.length > 0 && line[0] !== ' ' && line[0] !== '\t' && line[0] !== '<' && line.includes('{'));
-        if (hazard)
-            return match;
-        htmlElements.push(match);
-        return `${HTML_ELEM_PLACEHOLDER_PREFIX}${htmlElements.length - 1}___`;
-    });
-    return { htmlElements, protectedContent };
-}
-function restoreHTMLElements(content, htmlElements) {
-    if (htmlElements.length === 0)
-        return content;
-    return content.replace(HTML_ELEM_PLACEHOLDER, (_m, idx) => htmlElements[parseInt(idx, 10)]);
-}
-/**
- * Escapes unbalanced and paragraph-spanning braces so MDX doesn't trip on them.
+ * `String.split` on a regex with capture groups interleaves the captures into
+ * the result, so segments arrive as `[text, attrs, body, text, attrs, body, …]`.
  */
-function escapeProblematicBraces(content) {
-    const { htmlElements, protectedContent } = protectHTMLElements(content);
-    let strDelim = null;
-    let strEscaped = false;
-    // Track position of last newline (outside strings) to detect blank lines
-    // -2 means no recent newline
-    let lastNewlinePos = -2;
-    // Character state machine trackers
-    const toEscape = new Set();
-    // Convert to array of Unicode code points so that emojis and multi-byte characters are correctly tracked
-    const chars = Array.from(protectedContent);
-    const openStack = [];
-    for (let i = 0; i < chars.length; i += 1) {
-        const ch = chars[i];
-        // Track string delimiters inside expressions to ignore braces within them
-        if (openStack.length > 0) {
-            if (strDelim) {
-                if (strEscaped)
-                    strEscaped = false;
-                else if (ch === '\\')
-                    strEscaped = true;
-                else if (ch === strDelim)
-                    strDelim = null;
-                // eslint-disable-next-line no-continue
-                continue;
-            }
-            if (ch === '"' || ch === "'" || ch === '`') {
-                strDelim = ch;
-                // eslint-disable-next-line no-continue
-                continue;
-            }
-            if (ch === '\n') {
-                if (lastNewlinePos >= 0) {
-                    const between = chars.slice(lastNewlinePos + 1, i).join('');
-                    if (/^[ \t]*$/.test(between)) {
-                        openStack.forEach(entry => { entry.hasBlankLine = true; });
-                    }
-                }
-                lastNewlinePos = i;
-            }
-        }
-        // Skip already-escaped braces (odd run of preceding backslashes).
-        if (ch === '{' || ch === '}') {
-            let bs = 0;
-            for (let j = i - 1; j >= 0 && chars[j] === '\\'; j -= 1)
-                bs += 1;
-            if (bs % 2 === 1) {
-                // eslint-disable-next-line no-continue
-                continue;
-            }
-        }
-        if (ch === '{') {
-            // `=` (after whitespace) before `{` ⇒ JSX attribute expression. The
-            // mdxComponent tokenizer captures the whole component, so blank lines
-            // inside attribute values are harmless. Nested `{` inherits the flag.
-            let isAttrExpr = false;
-            for (let j = i - 1; j >= 0; j -= 1) {
-                const pc = chars[j];
-                if (pc === '=') {
-                    isAttrExpr = true;
-                    break;
-                }
-                if (pc !== ' ' && pc !== '\t')
-                    break;
-            }
-            // Nested `{ ... }` inside an attribute value (e.g. `data={[{ ... }]}` or
-            // `data={{ a: { b: 1 } }}`) must inherit the same exemption; only the
-            // outer `{` is directly after `=`.
-            if (!isAttrExpr && openStack.length > 0 && openStack[openStack.length - 1].isAttrExpr) {
-                isAttrExpr = true;
-            }
-            openStack.push({ pos: i, hasBlankLine: false, isAttrExpr });
-            lastNewlinePos = -2;
-        }
-        else if (ch === '}') {
-            if (openStack.length > 0) {
-                const entry = openStack.pop();
-                // Pure `{/* ... */}` comments are handled downstream by the jsxComment
-                // tokenizer — escaping their braces would prevent it from running.
-                const isPureJsxComment = chars[entry.pos + 1] === '/' &&
-                    chars[entry.pos + 2] === '*' &&
-                    chars[i - 1] === '/' &&
-                    chars[i - 2] === '*';
-                if (entry.hasBlankLine && !isPureJsxComment && !entry.isAttrExpr) {
-                    toEscape.add(entry.pos);
-                    toEscape.add(i);
-                }
-            }
-            else {
-                toEscape.add(i);
-            }
-        }
-    }
-    // Anything still open is unbalanced.
-    openStack.forEach(entry => toEscape.add(entry.pos));
-    // Reconstruct the content with the escaped braces.
-    const escapedContent = toEscape.size === 0 ? protectedContent : chars.map((ch, i) => (toEscape.has(i) ? `\\${ch}` : ch)).join('');
-    return restoreHTMLElements(escapedContent, htmlElements);
-}
+const splitRawHtmlBlocks = (node) => {
+    const segments = node.value.split(RAW_HTML_BLOCK_RE);
+    if (segments.length === 1)
+        return null; // no <HTMLBlock> present
+    const parts = [];
+    for (let i = 0; i < segments.length; i += 3) {
+        const [text, attrs, body] = segments.slice(i, i + 3);
+        if (text)
+            parts.push({ type: 'html', value: text });
+        if (body !== undefined) {
+            // The opening tag's column equals the length of the line it starts on
+            // (the text run since the previous newline preceding the match).
+            const openingTagIndent = text.slice(text.lastIndexOf('\n') + 1).length;
+            parts.push(htmlBlockFromRaw(attrs, body, node.position, openingTagIndent));
+        }
+    }
+    return parts;
+};
 /**
- * Preprocesses JSX-like markdown content before parsing.
+ * Converts every `<HTMLBlock>` shape that survives parsing into the canonical
+ * `html-block` MDAST node, reading the body from the tokenizer's template-literal
+ * expression. Three shapes occur:
  *
- * JSX attribute expressions (`href={baseUrl}`) are no longer rewritten here —
- * they flow through the tokenizer as `mdxJsxAttributeValueExpression` nodes
- * and are evaluated at the hast handler step.
+ *   1. JSX element (`mdxJsxFlowElement`/`mdxJsxTextElement`) — multiline/block
+ *      context and table cells (after their remarkMdx re-parse).
+ *   2. Raw `html` blob (`splitRawHtmlBlocks`) — single-line top-level, or nested
+ *      in raw HTML like an inline `<div>`.
+ *   3. Inline-in-paragraph — split into `html` + expression + `html` siblings.
  *
- * @param content
- * @returns Preprocessed content ready for markdown parsing
- */
-function preprocessJSXExpressions(content) {
-    let processed = protectHTMLBlockContent(content);
-    const { protectedCode, protectedContent } = protectCodeBlocks(processed);
-    processed = escapeProblematicBraces(protectedContent);
-    processed = restoreCodeBlocks(processed, protectedCode);
-    return processed;
-}
-
-;// ./processor/transform/mdxish/mdxish-html-blocks.ts
-
-
-
-
-/**
- * Decodes HTMLBlock content that was protected during preprocessing.
- * Content is wrapped in <!--RDMX_HTMLBLOCK:base64:RDMX_HTMLBLOCK-->
- */
-function decodeProtectedContent(content) {
-    // Escape special regex characters in the markers
-    const startEscaped = HTML_BLOCK_CONTENT_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const endEscaped = HTML_BLOCK_CONTENT_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const markerRegex = new RegExp(`${startEscaped}([A-Za-z0-9+/=]+)${endEscaped}`, 'g');
-    return content.replace(markerRegex, (_match, encoded) => {
-        try {
-            return base64Decode(encoded);
-        }
-        catch {
-            return encoded;
-        }
-    });
-}
-/**
- * Collects text content from a node and its children recursively
- */
-function collectTextContent(node) {
-    const parts = [];
-    if (node.type === 'text' && node.value) {
-        parts.push(node.value);
-    }
-    else if (node.type === 'html' && node.value) {
-        parts.push(node.value);
-    }
-    else if (node.type === 'inlineCode' && node.value) {
-        parts.push(node.value);
-    }
-    else if (node.type === 'code' && node.value) {
-        // Reconstruct code fence syntax (markdown parser consumes opening ```)
-        const lang = node.lang || '';
-        const fence = `\`\`\`${lang ? `${lang}\n` : ''}`;
-        parts.push(fence);
-        parts.push(node.value);
-        // Add newline before closing fence if missing
-        const closingFence = node.value.endsWith('\n') ? '```' : '\n```';
-        parts.push(closingFence);
-    }
-    else if (node.children && Array.isArray(node.children)) {
-        node.children.forEach(child => {
-            if (typeof child === 'object' && child !== null) {
-                parts.push(collectTextContent(child));
-            }
-        });
-    }
-    return parts.join('');
-}
-/**
- * Extracts boolean attribute from HTML tag. Handles JSX (safeMode={true}) and string (safeMode="true") syntax.
- * Returns "true"/"false" string to survive rehypeRaw serialization.
- */
-function extractBooleanAttr(attrs, name) {
-    // Try JSX syntax: name={true|false}
-    const jsxMatch = attrs.match(new RegExp(`${name}=\\{(true|false)\\}`));
-    if (jsxMatch) {
-        return jsxMatch[1];
-    }
-    // Try string syntax: name="true"|true
-    const stringMatch = attrs.match(new RegExp(`${name}="?(true|false)"?`));
-    if (stringMatch) {
-        return stringMatch[1];
-    }
-    return undefined;
-}
-/**
- * Extracts runScripts attribute from HTML tag. Returns boolean for "true"/"false", string for other values, or undefined if not found.
- */
-function extractRunScriptsAttr(attrs) {
-    const runScriptsMatch = attrs.match(/runScripts="?([^">\s]+)"?/);
-    if (!runScriptsMatch) {
-        return undefined;
-    }
-    const value = runScriptsMatch[1];
-    if (value === 'true') {
-        return true;
-    }
-    if (value === 'false') {
-        return false;
-    }
-    return value;
-}
-/**
- * Creates an HTMLBlock node from HTML string and optional attributes
- */
-function createHTMLBlockNode(htmlString, position, runScripts, safeMode) {
-    return {
-        position,
-        children: [{ type: 'text', value: htmlString }],
-        type: NodeTypes.htmlBlock,
-        data: {
-            hName: 'html-block',
-            hProperties: {
-                html: htmlString,
-                ...(runScripts !== undefined && { runScripts }),
-                ...(safeMode !== undefined && { safeMode }),
-            },
-        },
-    };
-}
-/**
- * Checks for opening tag only (for split detection)
- */
-function hasOpeningTagOnly(node) {
-    let hasOpening = false;
-    let hasClosed = false;
-    let attrs = '';
-    const check = (n) => {
-        if (n.type === 'html' && n.value) {
-            if (n.value === '<HTMLBlock>') {
-                hasOpening = true;
-            }
-            else {
-                const match = n.value.match(/^<HTMLBlock(\s[^>]*)?>$/);
-                if (match) {
-                    hasOpening = true;
-                    attrs = match[1] || '';
-                }
-            }
-            if (n.value === '</HTMLBlock>' || n.value.includes('</HTMLBlock>')) {
-                hasClosed = true;
-            }
-        }
-        if (n.children && Array.isArray(n.children)) {
-            n.children.forEach(child => {
-                check(child);
-            });
-        }
-    };
-    check(node);
-    // Return true only if opening without closing (split case)
-    return { attrs, found: hasOpening && !hasClosed };
-}
-/**
- * Checks if a node contains an HTMLBlock closing tag
- */
-function hasClosingTag(node) {
-    if (node.type === 'html' && node.value) {
-        if (node.value === '</HTMLBlock>' || node.value.includes('</HTMLBlock>'))
-            return true;
-    }
-    if (node.children && Array.isArray(node.children)) {
-        return node.children.some(child => hasClosingTag(child));
-    }
-    return false;
-}
-/**
- * Transforms HTMLBlock MDX JSX to html-block nodes. Handles <HTMLBlock>{`...`}</HTMLBlock> syntax.
+ * Runs *after* `mdxishTables` so table cells are re-parsed first;
+ * `mdxishTables` recognizes the still-JSX `<HTMLBlock>` element when deciding to
+ * keep a table as a JSX `<Table>`. This replaces the old base64-comment marker
+ * machinery — the #1455 tokenizer hands the body over already parsed.
  */
 const mdxishHtmlBlocks = () => tree => {
-    // Handle HTMLBlock split across root children (caused by newlines)
-    visit(tree, 'root', (root) => {
-        const children = root.children;
-        let i = 0;
-        while (i < children.length) {
-            const child = children[i];
-            const { attrs, found: hasOpening } = hasOpeningTagOnly(child);
-            if (hasOpening) {
-                // Find closing tag in subsequent siblings
-                let closingIdx = -1;
-                for (let j = i + 1; j < children.length; j += 1) {
-                    if (hasClosingTag(children[j])) {
-                        closingIdx = j;
-                        break;
-                    }
-                }
-                if (closingIdx !== -1) {
-                    // Collect inner content between tags
-                    const contentParts = [];
-                    for (let j = i; j <= closingIdx; j += 1) {
-                        const node = children[j];
-                        contentParts.push(collectTextContent(node));
-                    }
-                    // Remove the opening/closing tags and template literal syntax from content
-                    let content = contentParts.join('');
-                    content = content.replace(/^<HTMLBlock[^>]*>\s*\{?\s*`?/, '').replace(/`?\s*\}?\s*<\/HTMLBlock>$/, '');
-                    // Decode protected content that was base64 encoded during preprocessing
-                    content = decodeProtectedContent(content);
-                    const htmlString = formatHtmlForMdxish(content);
-                    const runScripts = extractRunScriptsAttr(attrs);
-                    const safeMode = extractBooleanAttr(attrs, 'safeMode');
-                    // Replace range with single HTMLBlock node
-                    const mdNode = createHTMLBlockNode(htmlString, children[i].position, runScripts, safeMode);
-                    root.children.splice(i, closingIdx - i + 1, mdNode);
-                }
-            }
-            i += 1;
-        }
+    // Shape 1: tokenized JSX element.
+    visit(tree, node => node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement', (node, index, parent) => {
+        const element = node;
+        if (element.name !== 'HTMLBlock' || !parent || index === undefined)
+            return;
+        const exprChild = element.children.find(child => child.type === 'mdxFlowExpression' || child.type === 'mdxTextExpression');
+        const openingTagIndent = (element.position?.start.column ?? 1) - 1;
+        parent.children[index] = createHtmlBlockNode(formatHtmlForMdxish(extractTemplateLiteral(exprChild?.value), openingTagIndent), element.position, toRunScripts(jsxAttr(element, 'runScripts')), jsxAttr(element, 'safeMode'));
     });
-    // Handle HTMLBlock parsed as HTML elements (when template literal contains block-level HTML tags)
+    // Shape 2: raw HTML blob.
     visit(tree, 'html', (node, index, parent) => {
         if (!parent || index === undefined)
             return;
-        const value = node.value;
-        if (!value)
-            return;
-        // Case 1: Full HTMLBlock in single node
-        const fullMatch = value.match(/^<HTMLBlock(\s[^>]*)?>([\s\S]*)<\/HTMLBlock>$/);
-        if (fullMatch) {
-            const attrs = fullMatch[1] || '';
-            let content = fullMatch[2] || '';
-            // Remove template literal syntax if present: {`...`}
-            content = content.replace(/^\s*\{\s*`/, '').replace(/`\s*\}\s*$/, '');
-            // Decode protected content that was base64 encoded during preprocessing
-            content = decodeProtectedContent(content);
-            const htmlString = formatHtmlForMdxish(content);
-            const runScripts = extractRunScriptsAttr(attrs);
-            const safeMode = extractBooleanAttr(attrs, 'safeMode');
-            parent.children[index] = createHTMLBlockNode(htmlString, node.position, runScripts, safeMode);
-            return;
-        }
-        // Case 2: Opening tag only (split by blank lines)
-        if (value === '<HTMLBlock>' || value.match(/^<HTMLBlock\s[^>]*>$/)) {
-            const siblings = parent.children;
-            let closingIdx = -1;
-            // Find closing tag in siblings
-            for (let i = index + 1; i < siblings.length; i += 1) {
-                const sibling = siblings[i];
-                if (sibling.type === 'html') {
-                    const sibVal = sibling.value;
-                    if (sibVal === '</HTMLBlock>' || sibVal?.includes('</HTMLBlock>')) {
-                        closingIdx = i;
-                        break;
-                    }
-                }
-            }
-            if (closingIdx === -1)
-                return;
-            // Collect content between tags, skipping template literal delimiters
-            const contentParts = [];
-            for (let i = index + 1; i < closingIdx; i += 1) {
-                const sibling = siblings[i];
-                // Skip template literal delimiters
-                if (sibling.type === 'text') {
-                    const textVal = sibling.value;
-                    if (textVal === '{' || textVal === '}' || textVal === '{`' || textVal === '`}') {
-                        // eslint-disable-next-line no-continue
-                        continue;
-                    }
-                }
-                contentParts.push(collectTextContent(sibling));
-            }
-            // Decode protected content that was base64 encoded during preprocessing
-            const decodedContent = decodeProtectedContent(contentParts.join(''));
-            const htmlString = formatHtmlForMdxish(decodedContent);
-            const runScripts = extractRunScriptsAttr(value);
-            const safeMode = extractBooleanAttr(value, 'safeMode');
-            // Replace opening tag with HTMLBlock node, remove consumed siblings
-            parent.children[index] = createHTMLBlockNode(htmlString, node.position, runScripts, safeMode);
-            parent.children.splice(index + 1, closingIdx - index);
-        }
+        const replacement = splitRawHtmlBlocks(node);
+        if (replacement)
+            parent.children.splice(index, 1, ...replacement);
     });
-    // Handle HTMLBlock inside paragraphs (parsed as inline elements)
-    visit(tree, 'paragraph', (node, index, parent) => {
-        if (!parent || index === undefined)
-            return;
-        const children = node.children || [];
-        let htmlBlockStartIdx = -1;
-        let htmlBlockEndIdx = -1;
-        let templateLiteralStartIdx = -1;
-        let templateLiteralEndIdx = -1;
+    // Shape 3: inline within a paragraph — `<HTMLBlock>` open/close arrive as
+    // separate `html` siblings with the template-literal expression between them.
+    visit(tree, 'paragraph', (paragraph) => {
+        // An html-block is block content, so it isn't a valid PhrasingContent child;
+        // widen to RootContent (which HTMLBlock belongs to) for the in-place splice.
+        const children = paragraph.children;
         for (let i = 0; i < children.length; i += 1) {
-            const child = children[i];
-            if (child.type === 'html' && typeof child.value === 'string') {
-                const value = child.value;
-                if (value === '<HTMLBlock>' || value.match(/^<HTMLBlock\s[^>]*>$/)) {
-                    htmlBlockStartIdx = i;
-                }
-                else if (value === '</HTMLBlock>') {
-                    htmlBlockEndIdx = i;
+            const open = children[i];
+            const openMatch = open.type === 'html' ? open.value.match(HTML_BLOCK_OPEN_RE) : null;
+            if (!openMatch)
+                continue; // eslint-disable-line no-continue
+            const closeIdx = children.findIndex((child, j) => j > i && child.type === 'html' && child.value === '</HTMLBlock>');
+            if (closeIdx === -1)
+                continue; // eslint-disable-line no-continue
+            const body = children
+                .slice(i + 1, closeIdx)
+                .map(child => {
+                if (child.type === 'mdxTextExpression' || child.type === 'mdxFlowExpression') {
+                    return extractTemplateLiteral(child.value);
                 }
-            }
-            // Find opening brace after HTMLBlock start
-            if (htmlBlockStartIdx !== -1 && templateLiteralStartIdx === -1 && child.type === 'text') {
-                const value = child.value;
-                if (value === '{') {
-                    templateLiteralStartIdx = i;
-                }
-            }
-            // Find closing brace before HTMLBlock end
-            if (htmlBlockStartIdx !== -1 && htmlBlockEndIdx === -1 && child.type === 'text') {
-                const value = child.value;
-                if (value === '}') {
-                    templateLiteralEndIdx = i;
-                }
-            }
-        }
-        if (htmlBlockStartIdx !== -1 &&
-            htmlBlockEndIdx !== -1 &&
-            templateLiteralStartIdx !== -1 &&
-            templateLiteralEndIdx !== -1 &&
-            templateLiteralStartIdx < templateLiteralEndIdx) {
-            const openingTag = children[htmlBlockStartIdx];
-            // Collect content between braces (handles code blocks)
-            const templateContent = [];
-            for (let i = templateLiteralStartIdx + 1; i < templateLiteralEndIdx; i += 1) {
-                const child = children[i];
-                templateContent.push(collectTextContent(child));
-            }
-            // Decode protected content that was base64 encoded during preprocessing
-            const decodedContent = decodeProtectedContent(templateContent.join(''));
-            const htmlString = formatHtmlForMdxish(decodedContent);
-            const runScripts = openingTag.value ? extractRunScriptsAttr(openingTag.value) : undefined;
-            const safeMode = openingTag.value ? extractBooleanAttr(openingTag.value, 'safeMode') : undefined;
-            const mdNode = createHTMLBlockNode(htmlString, node.position, runScripts, safeMode);
-            parent.children[index] = mdNode;
-        }
-    });
-    // Ensure html-block nodes have HTML in children as text node
-    visit(tree, 'html-block', (node) => {
-        const html = node.data?.hProperties?.html;
-        if (html &&
-            (!node.children ||
-                node.children.length === 0 ||
-                (node.children.length === 1 && node.children[0].type === 'text' && node.children[0].value !== html))) {
-            node.children = [
-                {
-                    type: 'text',
-                    value: html,
-                },
-            ];
+                // Preserve raw text from any other phrasing sibling (e.g. stray
+                // whitespace or content the tokenizer didn't claim) so it isn't
+                // silently dropped from the html payload.
+                return 'value' in child && typeof child.value === 'string' ? child.value : '';
+            })
+                .join('');
+            const openingTagIndent = (open.position?.start.column ?? 1) - 1;
+            children.splice(i, closeIdx - i + 1, htmlBlockFromRaw(openMatch[1], body, open.position, openingTagIndent));
         }
     });
-    return tree;
 };
 /* harmony default export */ const mdxish_html_blocks = (mdxishHtmlBlocks);
 
@@ -104293,6 +103956,189 @@ const normalizeMdxJsxNodes = () => tree => {
 };
 /* harmony default export */ const normalize_mdx_jsx_nodes = (normalizeMdxJsxNodes);
 
+;// ./lib/micromark/jsx-comment/pattern.ts
+/**
+ * Matches a JSX comment: `{/*`, content, `*\/}` — no whitespace tolerated
+ * between the braces and the comment markers.
+ *
+ * This grammar is mirrored by the flow tokenizer in ./syntax.ts. Any change
+ * here needs a mirror change in the state machine; the parity test in
+ * __tests__/lib/micromark/jsx-comment-pattern-parity.test.ts locks the two
+ * together so they can't silently drift.
+ */
+const JSX_COMMENT_REGEX = /\{\/\*[^*]*(?:\*(?!\/)[^*]*)*\*\/\}/g;
+
+;// ./processor/transform/mdxish/preprocess-jsx-expressions.ts
+
+
+/**
+ * Removes JSX-style comments (e.g., { /* comment *\/ }) from content.
+ *
+ * @param content
+ * @returns Content with JSX comments removed
+ * @example
+ * ```typescript
+ * removeJSXComments('Text { /* comment *\/ } more text')
+ * // Returns: 'Text  more text'
+ * ```
+ */
+function removeJSXComments(content) {
+    return content.replace(JSX_COMMENT_REGEX, '');
+}
+const HTML_ELEM_PLACEHOLDER_PREFIX = '___MDXISH_HTML_ELEM_';
+const HTML_ELEM_PLACEHOLDER = new RegExp(`${HTML_ELEM_PLACEHOLDER_PREFIX}(\\d+)___`, 'g');
+// Matches an HTML element that starts at a line boundary and ends at a line boundary.
+// Allows optional leading indentation and lazily matches until the same closing tag.
+const BLOCK_HTML_RE = /(?<=^|\n)[ \t]*<([a-z][a-zA-Z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>[ \t]*(?=\n|$)/g;
+/**
+ * Hides line-anchored HTML elements from the brace-escaping pass so we don't leak `\{`
+ * into rendered output (rehypeRaw renders the `\` literally, e.g. `<div>{foo</div>`).
+ *
+ * One carve-out: if an interior line at column 0 has bare text containing `{`, mdxish
+ * parses that line as a paragraph and the mdxExpression step would throw without an
+ * escape — so we leave that case to the brace balancer.
+ */
+function protectHTMLElements(content) {
+    const htmlElements = [];
+    const protectedContent = content.replace(BLOCK_HTML_RE, match => {
+        // Look at the lines between the open and close tags. If any of them starts
+        // at column 0 with bare text (not whitespace, not another tag) and contains
+        // `{`, mdxish will parse that line as a paragraph and the brace as an MDX
+        // expression, which would throw an error. So we let the brace balancer escape it.
+        // Otherwise, we need to extract the sequence to protect it from the brace escaping.
+        const interior = match.split('\n').slice(1, -1);
+        const hazard = interior.some(line => line.length > 0 && line[0] !== ' ' && line[0] !== '\t' && line[0] !== '<' && line.includes('{'));
+        if (hazard)
+            return match;
+        htmlElements.push(match);
+        return `${HTML_ELEM_PLACEHOLDER_PREFIX}${htmlElements.length - 1}___`;
+    });
+    return { htmlElements, protectedContent };
+}
+function restoreHTMLElements(content, htmlElements) {
+    if (htmlElements.length === 0)
+        return content;
+    return content.replace(HTML_ELEM_PLACEHOLDER, (_m, idx) => htmlElements[parseInt(idx, 10)]);
+}
+/**
+ * Escapes unbalanced and paragraph-spanning braces so MDX doesn't trip on them.
+ */
+function escapeProblematicBraces(content) {
+    const { htmlElements, protectedContent } = protectHTMLElements(content);
+    let strDelim = null;
+    let strEscaped = false;
+    // Track position of last newline (outside strings) to detect blank lines
+    // -2 means no recent newline
+    let lastNewlinePos = -2;
+    // Character state machine trackers
+    const toEscape = new Set();
+    // Convert to array of Unicode code points so that emojis and multi-byte characters are correctly tracked
+    const chars = Array.from(protectedContent);
+    const openStack = [];
+    for (let i = 0; i < chars.length; i += 1) {
+        const ch = chars[i];
+        // Track string delimiters inside expressions to ignore braces within them
+        if (openStack.length > 0) {
+            if (strDelim) {
+                if (strEscaped)
+                    strEscaped = false;
+                else if (ch === '\\')
+                    strEscaped = true;
+                else if (ch === strDelim)
+                    strDelim = null;
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            if (ch === '"' || ch === "'" || ch === '`') {
+                strDelim = ch;
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            if (ch === '\n') {
+                if (lastNewlinePos >= 0) {
+                    const between = chars.slice(lastNewlinePos + 1, i).join('');
+                    if (/^[ \t]*$/.test(between)) {
+                        openStack.forEach(entry => { entry.hasBlankLine = true; });
+                    }
+                }
+                lastNewlinePos = i;
+            }
+        }
+        // Skip already-escaped braces (odd run of preceding backslashes).
+        if (ch === '{' || ch === '}') {
+            let bs = 0;
+            for (let j = i - 1; j >= 0 && chars[j] === '\\'; j -= 1)
+                bs += 1;
+            if (bs % 2 === 1) {
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+        }
+        if (ch === '{') {
+            // `=` (after whitespace) before `{` ⇒ JSX attribute expression. The
+            // mdxComponent tokenizer captures the whole component, so blank lines
+            // inside attribute values are harmless. Nested `{` inherits the flag.
+            let isAttrExpr = false;
+            for (let j = i - 1; j >= 0; j -= 1) {
+                const pc = chars[j];
+                if (pc === '=') {
+                    isAttrExpr = true;
+                    break;
+                }
+                if (pc !== ' ' && pc !== '\t')
+                    break;
+            }
+            // Nested `{ ... }` inside an attribute value (e.g. `data={[{ ... }]}` or
+            // `data={{ a: { b: 1 } }}`) must inherit the same exemption; only the
+            // outer `{` is directly after `=`.
+            if (!isAttrExpr && openStack.length > 0 && openStack[openStack.length - 1].isAttrExpr) {
+                isAttrExpr = true;
+            }
+            openStack.push({ pos: i, hasBlankLine: false, isAttrExpr });
+            lastNewlinePos = -2;
+        }
+        else if (ch === '}') {
+            if (openStack.length > 0) {
+                const entry = openStack.pop();
+                // Pure `{/* ... */}` comments are handled downstream by the jsxComment
+                // tokenizer — escaping their braces would prevent it from running.
+                const isPureJsxComment = chars[entry.pos + 1] === '/' &&
+                    chars[entry.pos + 2] === '*' &&
+                    chars[i - 1] === '/' &&
+                    chars[i - 2] === '*';
+                if (entry.hasBlankLine && !isPureJsxComment && !entry.isAttrExpr) {
+                    toEscape.add(entry.pos);
+                    toEscape.add(i);
+                }
+            }
+            else {
+                toEscape.add(i);
+            }
+        }
+    }
+    // Anything still open is unbalanced.
+    openStack.forEach(entry => toEscape.add(entry.pos));
+    // Reconstruct the content with the escaped braces.
+    const escapedContent = toEscape.size === 0 ? protectedContent : chars.map((ch, i) => (toEscape.has(i) ? `\\${ch}` : ch)).join('');
+    return restoreHTMLElements(escapedContent, htmlElements);
+}
+/**
+ * Preprocesses JSX-like markdown content before parsing.
+ *
+ * JSX attribute expressions (`href={baseUrl}`) are no longer rewritten here —
+ * they flow through the tokenizer as `mdxJsxAttributeValueExpression` nodes
+ * and are evaluated at the hast handler step.
+ *
+ * @param content
+ * @returns Preprocessed content ready for markdown parsing
+ */
+function preprocessJSXExpressions(content) {
+    const { protectedCode, protectedContent } = protectCodeBlocks(content);
+    let processed = escapeProblematicBraces(protectedContent);
+    processed = restoreCodeBlocks(processed, protectedCode);
+    return processed;
+}
+
 ;// ./processor/transform/mdxish/restore-snake-case-component-name.ts
 
 
@@ -105409,7 +105255,7 @@ function mdxishAstProcessor(mdContent, opts = {}) {
         .use(inline_html, { safeMode })
         .use(restore_snake_case_component_name, { mapping: snakeCaseMapping })
         .use(mdxish_tables)
-        .use(mdxish_html_blocks)
+        .use(mdxish_html_blocks) // Convert every <HTMLBlock> shape → html-block
         // The next few transformers must appear after mdxishMdxComponentBlocks
         // so nodes produced by the inline re-parse of component bodies
         // (e.g. code/image/embed inside <Tabs>) get visited too