Jocs · Oct 6, 2026 · Oct 6, 2026
diff --git a/packages/muya/e2e/tests/blocks/html-inline.spec.ts b/packages/muya/e2e/tests/blocks/html-inline.spec.ts
@@ -1,4 +1,5 @@
 import { expect, test } from '../fixtures/muya';
+import { editor } from '../helpers/selectors';
 
 /**
  * Inline HTML tags (`<u>`, `<mark>`, `<sup>`, `<sub>`, `<ruby>`) render via
@@ -78,4 +79,18 @@ test.describe('inline html tags', () => {
         expect(md).toContain('</ruby>');
         expect(md).toContain('<rt>kan</rt>');
     });
+
+    test('the <br/> marker hides once the caret leaves it (#5634)', async ({ page }) => {
+        await page.evaluate(() => {
+            window.muya!.setContent('Line 1<br/>Line 2');
+        });
+        await page.locator(editor.paragraph).first().click();
+        await page.evaluate(() => {
+            window.muya!.editor.scrollPage!.firstContentInDescendant()!.setCursor(14, 14, true);
+        });
+
+        const marker = page.locator(`${editor.htmlTagMarker} .mu-hide`);
+        await expect(marker).toBeHidden();
+        await expect(page.locator(`${editor.htmlTagMarker} br`)).toBeAttached();
+    });
 });
diff --git a/packages/muya/e2e/tests/helpers/selectors.ts b/packages/muya/e2e/tests/helpers/selectors.ts
@@ -84,6 +84,7 @@ export const editor = {
     // Inline html tags wrap their children with `.mu-raw-html`. The tag itself
     // is the actual `<u>`, `<mark>`, `<sup>`, `<sub>` or `<ruby>` element.
     rawHtml: '.mu-raw-html',
+    htmlTagMarker: 'span.mu-html-tag',
 } as const;
 
 // Float root class names confirmed against the `const name = 'mu-...'` lines

diff --git a/packages/muya/src/assets/styles/inlineSyntax.css b/packages/muya/src/assets/styles/inlineSyntax.css
@@ -29,6 +29,12 @@
     white-space: nowrap;
 }
 
+span.mu-html-tag {
+    color: var(--editor-color-50);
+    font-weight: 200;
+    font-family: monospace;
+}
+
 /* link and auto-link and reference link */
 a.mu-inline-rule,
 span.mu-inline-rule.mu-link {

diff --git a/packages/muya/src/inlineRenderer/__tests__/htmlTagMarker.spec.ts b/packages/muya/src/inlineRenderer/__tests__/htmlTagMarker.spec.ts
@@ -0,0 +1,59 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { CLASS_NAMES } from '../../config';
+import { Muya } from '../../muya';
+
+const bootedMuyas: Muya[] = [];
+
+beforeEach(() => {
+    (window as unknown as { MUYA_VERSION?: string }).MUYA_VERSION = 'test';
+});
+
+afterEach(() => {
+    while (bootedMuyas.length)
+        bootedMuyas.pop()!.destroy();
+    document.body.innerHTML = '';
+    delete (window as unknown as { MUYA_VERSION?: string }).MUYA_VERSION;
+});
+
+function boot(markdown: string): Muya {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const muya = new Muya(host, { markdown } as ConstructorParameters<typeof Muya>[1]);
+    muya.init();
+    bootedMuyas.push(muya);
+    return muya;
+}
+
+describe('inline <br> marker', () => {
+    it('collapses the literal marker while keeping a real <br> line break', () => {
+        const muya = boot('Line 1<br/>Line 2');
+        const wrapper = muya.domNode.querySelector<HTMLElement>(
+            `span.${CLASS_NAMES.MU_HTML_TAG}`,
+        )!;
+        const marker = wrapper.querySelector<HTMLElement>(
+            `span.${CLASS_NAMES.MU_HIDE}`,
+        )!;
+
+        expect(marker.textContent).toBe('<br/>');
+        expect(marker.classList.contains(CLASS_NAMES.MU_OUTPUT_REMOVE)).toBe(true);
+        expect(marker.querySelector('br')).toBeNull();
+        expect(wrapper.querySelector('br')).not.toBeNull();
+    });
+
+    it('reveals the marker once the caret sits inside the <br> token', () => {
+        const muya = boot('Line 1<br/>Line 2');
+        muya.editor.scrollPage!.firstContentInDescendant()!.setCursor(7, 7, true);
+
+        const wrapper = muya.domNode.querySelector<HTMLElement>(
+            `span.${CLASS_NAMES.MU_HTML_TAG}`,
+        )!;
+        const marker = wrapper.querySelector<HTMLElement>(
+            `span.${CLASS_NAMES.MU_HTML_TAG}.${CLASS_NAMES.MU_OUTPUT_REMOVE}`,
+        )!;
+
+        expect(marker.textContent).toBe('<br/>');
+        expect(marker.classList.contains(CLASS_NAMES.MU_HIDE)).toBe(false);
+    });
+});
diff --git a/packages/muya/src/inlineRenderer/renderer/htmlTag.ts b/packages/muya/src/inlineRenderer/renderer/htmlTag.ts
@@ -119,7 +119,8 @@ export default function htmlTag(
 ) {
     const { tag, openTag, closeTag, children } = token;
 
-    const className = children?.length
+    // `<br>` is a void tag, but its marker still hides with the cursor.
+    const className = children?.length || tag === 'br'
         ? this.getClassName(outerClass, block, token, cursor)
         : CLASS_NAMES.MU_GRAY;
     const tagClassName
@@ -139,21 +140,27 @@ export default function htmlTag(
     const anchor = renderHtmlTagChildren(this, h, cursor, block, token);
 
     switch (tag) {
-    // Handle html img.
         case 'img': {
-            // `<img>` html_tag tokens and markdown image tokens overlap on the
-            // fields `image()` actually reads (`raw`, `range`, `attrs.src/alt/
-            // title/width/height/'data-align'`), but their static shapes
-            // diverge — HTMLTagToken.attrs is `Record<string, string | null>`,
-            // ImageToken.attrs is the strict `{ src; title; alt }`. Routing
-            // html `<img>` through `image()` is a deliberate runtime contract;
-            // express the structural pun in one place.
             // eslint-disable-next-line no-restricted-syntax
             return this.image({ h, cursor, block, token: token as unknown as ImageToken, outerClass });
         }
 
         case 'br': {
-            return [h(`span.${CLASS_NAMES.MU_HTML_TAG}`, [...openContent, h(tag)])];
+            // Keep the real `<br>` outside the marker so hiding the marker keeps the line break.
+            return [
+                h(`span.${CLASS_NAMES.MU_HTML_TAG}`, [
+                    h(
+                        `span.${tagClassName}.${CLASS_NAMES.MU_OUTPUT_REMOVE}`,
+                        {
+                            attrs: {
+                                spellcheck: 'false',
+                            },
+                        },
+                        openContent,
+                    ),
+                    h(tag),
+                ]),
+            ];
         }
 
         default: