diff --git a/__tests__/extensions/MarkdownV2.spec.ts b/__tests__/extensions/MarkdownV2.spec.ts
index 6b037cb1..b2709863 100644
--- a/__tests__/extensions/MarkdownV2.spec.ts
+++ b/__tests__/extensions/MarkdownV2.spec.ts
@@ -1,96 +1,846 @@
-import { MarkdownV2Parser } from "../../gramjs/extensions/markdownv2";
+import {
+    MarkdownV2Parser,
+    markdownV2ToHtml,
+    htmlToMarkdownV2,
+} from "../../gramjs/extensions/markdownv2";
 import { Api as types } from "../../gramjs/tl/api";
 
 describe("MarkdownV2Parser", () => {
-  describe(".parse", () => {
-    test("it should parse bold entities", () => {
-      const [text, entities] = MarkdownV2Parser.parse("Hello *world*");
-      expect(text).toEqual("Hello world");
-      expect(entities.length).toEqual(1);
-      expect(entities[0]).toBeInstanceOf(types.MessageEntityBold);
-    });
-
-    test("it should parse italic entities", () => {
-      const [text, entities] = MarkdownV2Parser.parse("Hello -world-");
-      expect(text).toEqual("Hello world");
-      expect(entities.length).toEqual(1);
-      expect(entities[0]).toBeInstanceOf(types.MessageEntityItalic);
-    });
-
-    test("it should parse code entities", () => {
-      const [text, entities] = MarkdownV2Parser.parse("Hello `world`");
-      expect(text).toEqual("Hello world");
-      expect(entities.length).toEqual(1);
-      expect(entities[0]).toBeInstanceOf(types.MessageEntityCode);
-    });
-
-    test("it should parse pre entities", () => {
-      const [text, entities] = MarkdownV2Parser.parse("Hello ```world```");
-      expect(text).toEqual("Hello world");
-      expect(entities.length).toEqual(1);
-      expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
-    });
-
-    test("it should parse strike entities", () => {
-      const [text, entities] = MarkdownV2Parser.parse("Hello ~world~");
-      expect(text).toEqual("Hello world");
-      expect(entities.length).toEqual(1);
-      expect(entities[0]).toBeInstanceOf(types.MessageEntityStrike);
-    });
-
-    test("it should parse link entities", () => {
-      const [text, entities] = MarkdownV2Parser.parse(
-        "Hello [world](https://hello.world)"
-      );
-      expect(text).toEqual("Hello world");
-      expect(entities.length).toEqual(1);
-      expect(entities[0]).toBeInstanceOf(types.MessageEntityTextUrl);
-      expect((entities[0] as types.MessageEntityTextUrl).url).toEqual(
-        "https://hello.world"
-      );
-    });
-
-    test("it should parse custom emoji", () => {
-      const [text, entities] = MarkdownV2Parser.parse(
-        "![👍](tg://emoji?id=5368324170671202286)"
-      );
-      expect(text).toEqual("👍");
-      expect(entities.length).toEqual(1);
-      expect(entities[0]).toBeInstanceOf(types.MessageEntityCustomEmoji);
-      expect(
-        (entities[0] as types.MessageEntityCustomEmoji).documentId
-      ).toEqual("5368324170671202286");
-    });
-
-    test("it should parse multiple entities", () => {
-      const [text, entities] = MarkdownV2Parser.parse("-Hello- *world*");
-      expect(text).toEqual("Hello world");
-      expect(entities.length).toEqual(2);
-      expect(entities[0]).toBeInstanceOf(types.MessageEntityItalic);
-      expect(entities[1]).toBeInstanceOf(types.MessageEntityBold);
-    });
-  });
-
-  describe(".unparse", () => {
-    // skipped until MarkDownV2
-    test.skip("it should create a markdown string from raw text and entities", () => {
-      const unparsed =
-        "*hello* -hello- ~hello~ `hello` ```hello``` [hello](https://hello.world)";
-      const strippedText = "hello hello hello hello hello hello";
-      const rawEntities = [
-        new types.MessageEntityBold({ offset: 0, length: 5 }),
-        new types.MessageEntityItalic({ offset: 6, length: 5 }),
-        new types.MessageEntityStrike({ offset: 12, length: 5 }),
-        new types.MessageEntityCode({ offset: 18, length: 5 }),
-        new types.MessageEntityPre({ offset: 24, length: 5, language: "" }),
-        new types.MessageEntityTextUrl({
-          offset: 30,
-          length: 5,
-          url: "https://hello.world",
-        }),
-      ];
-      const text = MarkdownV2Parser.unparse(strippedText, rawEntities);
-      expect(text).toEqual(unparsed);
-    });
-  });
+    describe(".parse — span markup basics", () => {
+        test("bold", () => {
+            const [text, entities] = MarkdownV2Parser.parse("Hello *world*");
+            expect(text).toEqual("Hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityBold);
+        });
+
+        test("italic", () => {
+            const [text, entities] = MarkdownV2Parser.parse("Hello _world_");
+            expect(text).toEqual("Hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityItalic);
+        });
+
+        test("underline", () => {
+            const [text, entities] = MarkdownV2Parser.parse("Hello __world__");
+            expect(text).toEqual("Hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityUnderline);
+        });
+
+        test("strikethrough", () => {
+            const [text, entities] = MarkdownV2Parser.parse("Hello ~world~");
+            expect(text).toEqual("Hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityStrike);
+        });
+
+        test("spoiler", () => {
+            const [text, entities] = MarkdownV2Parser.parse("Hello ||world||");
+            expect(text).toEqual("Hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntitySpoiler);
+        });
+
+        test("bold spans multiple words", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("*hello world*");
+            expect(text).toEqual("hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0].length).toEqual(11);
+        });
+
+        test("italic spans newlines", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("_line1\nline2_");
+            expect(text).toEqual("line1\nline2");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityItalic);
+            expect(entities[0].length).toEqual(11);
+        });
+    });
+
+    describe(".parse — span combinations", () => {
+        test("multiple separate spans on one line", () => {
+            const [text, entities] = MarkdownV2Parser.parse("_a_ *b*");
+            expect(text).toEqual("a b");
+            expect(entities.length).toEqual(2);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityItalic);
+            expect(entities[1]).toBeInstanceOf(types.MessageEntityBold);
+        });
+
+        test("five distinct spans in a row", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "*a* _b_ ~c~ ||d|| __e__"
+            );
+            expect(text).toEqual("a b c d e");
+            expect(entities.length).toEqual(5);
+            const has = (cls: any) =>
+                entities.some((e) => e instanceof cls);
+            expect(has(types.MessageEntityBold)).toBe(true);
+            expect(has(types.MessageEntityItalic)).toBe(true);
+            expect(has(types.MessageEntityStrike)).toBe(true);
+            expect(has(types.MessageEntitySpoiler)).toBe(true);
+            expect(has(types.MessageEntityUnderline)).toBe(true);
+        });
+
+        test("italic nested inside bold", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "*hello _world_ end*"
+            );
+            expect(text).toEqual("hello world end");
+            expect(entities.length).toEqual(2);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityItalic);
+            expect(entities[1]).toBeInstanceOf(types.MessageEntityBold);
+            expect(entities[0].offset).toEqual(6);
+            expect(entities[0].length).toEqual(5);
+            expect(entities[1].offset).toEqual(0);
+            expect(entities[1].length).toEqual(15);
+        });
+
+        test("bold nested inside underline", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "__hello *bold* end__"
+            );
+            expect(text).toEqual("hello bold end");
+            expect(entities.length).toEqual(2);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityBold);
+            expect(entities[1]).toBeInstanceOf(types.MessageEntityUnderline);
+            expect(entities[0].offset).toEqual(6);
+            expect(entities[0].length).toEqual(4);
+            expect(entities[1].offset).toEqual(0);
+            expect(entities[1].length).toEqual(14);
+        });
+    });
+
+    describe(".parse — inline code", () => {
+        test("basic code", () => {
+            const [text, entities] = MarkdownV2Parser.parse("Hello `world`");
+            expect(text).toEqual("Hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityCode);
+        });
+
+        test("code with markup chars stays literal", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("`*not bold*`");
+            expect(text).toEqual("*not bold*");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityCode);
+        });
+
+        test("code with escaped backtick", () => {
+            const [text, entities] = MarkdownV2Parser.parse("`a\\`b`");
+            expect(text).toEqual("a`b");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityCode);
+        });
+
+        test("code with escaped backslash", () => {
+            const [text, entities] = MarkdownV2Parser.parse("`a\\\\b`");
+            expect(text).toEqual("a\\b");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityCode);
+        });
+
+        test("code preserves backslash before non-special char", () => {
+            // Inside code, only \\ and \` are escapes. \X for any other X
+            // stays as a literal backslash followed by X.
+            const [text, entities] = MarkdownV2Parser.parse("`a\\bc`");
+            expect(text).toEqual("a\\bc");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityCode);
+        });
+
+        test("code with HTML special chars renders as literal text", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse('`a < b & "c"`');
+            expect(text).toEqual('a < b & "c"');
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityCode);
+        });
+    });
+
+    describe(".parse — pre block", () => {
+        test("basic pre", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("Hello ```world```");
+            expect(text).toEqual("Hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
+        });
+
+        test("pre with language tag", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("```python\nfoo```");
+            expect(text).toEqual("foo");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
+            expect((entities[0] as types.MessageEntityPre).language).toEqual(
+                "python"
+            );
+        });
+
+        test("pre with non-identifier first line keeps it as content", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("```hello world\nfoo```");
+            expect(text).toEqual("hello world\nfoo");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
+            expect((entities[0] as types.MessageEntityPre).language).toEqual(
+                ""
+            );
+        });
+
+        test("pre with backslash-escaped backtick inside", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("```a\\`b```");
+            expect(text).toEqual("a`b");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
+        });
+
+        test("pre preserves markup chars literally", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("```*not bold*```");
+            expect(text).toEqual("*not bold*");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
+        });
+
+        test("pre with HTML special chars", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("```<script>&```");
+            expect(text).toEqual("<script>&");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
+        });
+    });
+
+    describe(".parse — links and mentions", () => {
+        test("basic inline URL", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "Hello [world](https://hello.world)"
+            );
+            expect(text).toEqual("Hello world");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityTextUrl);
+            expect(
+                (entities[0] as types.MessageEntityTextUrl).url
+            ).toEqual("https://hello.world");
+        });
+
+        test("URL with escaped close-paren", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "[hi](http://x.y/foo\\))"
+            );
+            expect(text).toEqual("hi");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityTextUrl);
+            expect(
+                (entities[0] as types.MessageEntityTextUrl).url
+            ).toEqual("http://x.y/foo)");
+        });
+
+        test("URL with escaped backslash", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "[hi](http://x.y/foo\\\\bar)"
+            );
+            expect(text).toEqual("hi");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityTextUrl);
+            expect(
+                (entities[0] as types.MessageEntityTextUrl).url
+            ).toEqual("http://x.y/foo\\bar");
+        });
+
+        test("URL keeps backslash before non-special char literal", () => {
+            // Inside (URL), only \\ and \) are escapes. \. stays literal.
+            const [text, entities] = MarkdownV2Parser.parse(
+                "[hi](http://x.y/foo\\.bar)"
+            );
+            expect(text).toEqual("hi");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityTextUrl);
+            expect(
+                (entities[0] as types.MessageEntityTextUrl).url
+            ).toEqual("http://x.y/foo\\.bar");
+        });
+
+        test("link with markup inside label", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "[*bold*](http://x.y)"
+            );
+            expect(text).toEqual("bold");
+            expect(entities.length).toEqual(2);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityBold);
+            expect(entities[1]).toBeInstanceOf(types.MessageEntityTextUrl);
+        });
+
+        test("user mention emits TextUrl with tg://user URL", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "[name](tg://user?id=12345)"
+            );
+            expect(text).toEqual("name");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityTextUrl);
+            expect(
+                (entities[0] as types.MessageEntityTextUrl).url
+            ).toEqual("tg://user?id=12345");
+        });
+
+        test("malformed link without close-paren stays literal", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("[hi](no-close");
+            expect(text).toEqual("[hi](no-close");
+            expect(entities.length).toEqual(0);
+        });
+    });
+
+    describe(".parse — custom emoji", () => {
+        test("basic custom emoji", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "![👍](tg://emoji?id=5368324170671202286)"
+            );
+            expect(text).toEqual("👍");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(
+                types.MessageEntityCustomEmoji
+            );
+            expect(
+                (entities[0] as types.MessageEntityCustomEmoji).documentId
+            ).toEqual("5368324170671202286");
+        });
+
+        test("non-emoji bang-link parses as literal `!` then a link", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "![hi](http://x.y)"
+            );
+            expect(text).toEqual("!hi");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityTextUrl);
+            expect(entities[0].offset).toEqual(1);
+            expect(entities[0].length).toEqual(2);
+        });
+
+        test("custom emoji with markup inside label", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "![*emoji*](tg://emoji?id=123)"
+            );
+            expect(text).toEqual("emoji");
+            expect(entities.length).toEqual(2);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityBold);
+            expect(entities[1]).toBeInstanceOf(
+                types.MessageEntityCustomEmoji
+            );
+        });
+    });
+
+    describe(".parse — blockquotes", () => {
+        test("single-line blockquote", () => {
+            const [text, entities] = MarkdownV2Parser.parse(">hello");
+            expect(text).toEqual("hello");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+            expect(
+                (entities[0] as types.MessageEntityBlockquote).collapsed
+            ).toBeFalsy();
+        });
+
+        test("multi-line blockquote", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse(">hello\n>world");
+            expect(text).toEqual("hello\nworld");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+        });
+
+        test("blockquote with markup inside", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                ">this is *bold*"
+            );
+            expect(text).toEqual("this is bold");
+            expect(entities.length).toEqual(2);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityBold);
+            expect(entities[1]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+        });
+
+        test("> mid-line is literal, not a blockquote", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("Hello >world");
+            expect(text).toEqual("Hello >world");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("two blockquote groups separated by a plain line", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse(">a\nplain\n>b");
+            expect(text).toEqual("a\nplain\nb");
+            expect(entities.length).toEqual(2);
+            expect(entities[0]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+            expect(entities[1]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+        });
+
+        test("escaped > at line start is NOT a blockquote", () => {
+            const [text, entities] = MarkdownV2Parser.parse("\\>line");
+            expect(text).toEqual(">line");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("blockquote starting with span markup", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse(">*bold*");
+            expect(text).toEqual("bold");
+            expect(entities.length).toEqual(2);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityBold);
+            expect(entities[1]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+        });
+    });
+
+    describe(".parse — expandable blockquotes", () => {
+        test("single-line expandable blockquote", () => {
+            const [text, entities] = MarkdownV2Parser.parse(">hello||");
+            expect(text).toEqual("hello");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+            expect(
+                (entities[0] as types.MessageEntityBlockquote).collapsed
+            ).toEqual(true);
+        });
+
+        test("multi-line expandable blockquote", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse(">hello\n>world||");
+            expect(text).toEqual("hello\nworld");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+            expect(
+                (entities[0] as types.MessageEntityBlockquote).collapsed
+            ).toEqual(true);
+        });
+
+        test("expandable blockquote with spoiler inside is unambiguous", () => {
+            // ||spoil|| matches first as spoiler; the trailing || becomes
+            // the expandable marker.
+            const [text, entities] = MarkdownV2Parser.parse(
+                ">hi ||spoil|| more||"
+            );
+            expect(text).toEqual("hi spoil more");
+            expect(entities.length).toEqual(2);
+            const has = (cls: any) =>
+                entities.some((e) => e instanceof cls);
+            expect(has(types.MessageEntitySpoiler)).toBe(true);
+            expect(has(types.MessageEntityBlockquote)).toBe(true);
+            const blockquote = entities.find(
+                (e) => e instanceof types.MessageEntityBlockquote
+            ) as types.MessageEntityBlockquote;
+            expect(blockquote.collapsed).toEqual(true);
+        });
+    });
+
+    describe(".parse — backslash escapes", () => {
+        test("unescapes spec-listed special chars", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "1\\.5 \\(approx\\) \\#1\\!"
+            );
+            expect(text).toEqual("1.5 (approx) #1!");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("escapes block markup detection for *, _, ~, |, __", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "\\*not bold\\* \\_not italic\\_ \\~not strike\\~ \\|\\|not spoiler\\|\\|"
+            );
+            expect(text).toEqual(
+                "*not bold* _not italic_ ~not strike~ ||not spoiler||"
+            );
+            expect(entities.length).toEqual(0);
+        });
+
+        test("escape backslash with backslash", () => {
+            const [text, entities] = MarkdownV2Parser.parse("\\\\");
+            expect(text).toEqual("\\");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("trailing lone backslash stays literal", () => {
+            const [text, entities] = MarkdownV2Parser.parse("hello\\");
+            expect(text).toEqual("hello\\");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("escape of non-special char yields the bare char", () => {
+            // Spec: any character with code 1..126 can be backslash-escaped.
+            const [text, entities] = MarkdownV2Parser.parse("\\a\\b\\c");
+            expect(text).toEqual("abc");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("escape inside pre is restricted to backslash and backtick", () => {
+            // \* inside ``` stays as \* (not unescaped to *).
+            const [text, entities] = MarkdownV2Parser.parse("```\\*x```");
+            expect(text).toEqual("\\*x");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
+        });
+
+        test("escape inside link URL is restricted to backslash and close-paren", () => {
+            // \. inside (URL) stays as \. (not unescaped to .).
+            const [text, entities] = MarkdownV2Parser.parse(
+                "[hi](http://x.y/\\.foo)"
+            );
+            expect(text).toEqual("hi");
+            expect(entities.length).toEqual(1);
+            expect(
+                (entities[0] as types.MessageEntityTextUrl).url
+            ).toEqual("http://x.y/\\.foo");
+        });
+
+        test("escaped < and & in plain text round-trip as literal chars", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("\\<\\&");
+            expect(text).toEqual("<&");
+            expect(entities.length).toEqual(0);
+        });
+    });
+
+    describe(".parse — HTML chars in plain text", () => {
+        test("literal < is rendered as text, not interpreted as HTML", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("a < b & c");
+            expect(text).toEqual("a < b & c");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("literal HTML-looking content in plain text", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("<b>not bold</b>");
+            expect(text).toEqual("<b>not bold</b>");
+            expect(entities.length).toEqual(0);
+        });
+    });
+
+    describe(".parse — edge cases", () => {
+        test("empty input", () => {
+            const [text, entities] = MarkdownV2Parser.parse("");
+            expect(text).toEqual("");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("plain text with no markup", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("hello world");
+            expect(text).toEqual("hello world");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("lone delimiter chars stay literal", () => {
+            const [text, entities] = MarkdownV2Parser.parse("* _ ~ |");
+            expect(text).toEqual("* _ ~ |");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("malformed code with no closing backtick stays literal", () => {
+            const [text, entities] = MarkdownV2Parser.parse("`code");
+            expect(text).toEqual("`code");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("input with literal NUL/SOH does not corrupt placeholders", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("a\u0000b\u0001c");
+            // NUL/SOH are stripped to avoid clashing with internal
+            // placeholder markers; surviving content is unaffected.
+            expect(text).toEqual("abc");
+            expect(entities.length).toEqual(0);
+        });
+
+        test("ambiguous ___text___ produces both italic and underline", () => {
+            // Per spec this construct is ambiguous; users are advised to
+            // write `___italic underline_**__` instead. Our parser yields
+            // both an underline and an italic spanning the text.
+            const [text, entities] =
+                MarkdownV2Parser.parse("___text___");
+            expect(text).toEqual("text");
+            expect(entities.length).toEqual(2);
+            const has = (cls: any) =>
+                entities.some((e) => e instanceof cls);
+            expect(has(types.MessageEntityItalic)).toBe(true);
+            expect(has(types.MessageEntityUnderline)).toBe(true);
+        });
+
+        test("lone >|| produces an empty expandable blockquote", () => {
+            const [text, entities] = MarkdownV2Parser.parse(">||");
+            expect(text).toEqual("");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(
+                types.MessageEntityBlockquote
+            );
+            expect(
+                (entities[0] as types.MessageEntityBlockquote).collapsed
+            ).toEqual(true);
+        });
+
+        test("pre with c++ as language", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("```c++\nfoo```");
+            expect(text).toEqual("foo");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(types.MessageEntityPre);
+            expect((entities[0] as types.MessageEntityPre).language).toEqual(
+                "c++"
+            );
+        });
+
+        test("pre with c# as language", () => {
+            const [text, entities] =
+                MarkdownV2Parser.parse("```c#\nfoo```");
+            expect(text).toEqual("foo");
+            expect((entities[0] as types.MessageEntityPre).language).toEqual(
+                "c#"
+            );
+        });
+
+        test("custom emoji URL with extra query params", () => {
+            const [text, entities] = MarkdownV2Parser.parse(
+                "![👍](tg://emoji?v=1&id=42)"
+            );
+            expect(text).toEqual("👍");
+            expect(entities.length).toEqual(1);
+            expect(entities[0]).toBeInstanceOf(
+                types.MessageEntityCustomEmoji
+            );
+            expect(
+                (entities[0] as types.MessageEntityCustomEmoji).documentId
+            ).toEqual("42");
+        });
+    });
+});
+
+describe("markdownV2ToHtml — standalone function", () => {
+    test("converts bold to <b>", () => {
+        expect(markdownV2ToHtml("*hi*")).toEqual("<b>hi</b>");
+    });
+
+    test("converts italic to <i>", () => {
+        expect(markdownV2ToHtml("_hi_")).toEqual("<i>hi</i>");
+    });
+
+    test("converts underline to <u>", () => {
+        expect(markdownV2ToHtml("__hi__")).toEqual("<u>hi</u>");
+    });
+
+    test("converts strike to <s>", () => {
+        expect(markdownV2ToHtml("~hi~")).toEqual("<s>hi</s>");
+    });
+
+    test("converts spoiler to <tg-spoiler>", () => {
+        expect(markdownV2ToHtml("||hi||")).toEqual(
+            "<tg-spoiler>hi</tg-spoiler>"
+        );
+    });
+
+    test("converts blockquote", () => {
+        expect(markdownV2ToHtml(">hi")).toEqual(
+            "<blockquote>hi</blockquote>"
+        );
+    });
+
+    test("converts expandable blockquote", () => {
+        expect(markdownV2ToHtml(">hi||")).toEqual(
+            "<blockquote expandable>hi</blockquote>"
+        );
+    });
+
+    test("converts inline code", () => {
+        expect(markdownV2ToHtml("`x`")).toEqual("<code>x</code>");
+    });
+
+    test("converts pre block", () => {
+        expect(markdownV2ToHtml("```x```")).toEqual("<pre>x</pre>");
+    });
+
+    test("converts pre with language", () => {
+        expect(markdownV2ToHtml("```py\nfoo```")).toEqual(
+            '<pre><code class="language-py">foo</code></pre>'
+        );
+    });
+
+    test("converts inline link", () => {
+        expect(markdownV2ToHtml("[hi](http://x.y)")).toEqual(
+            '<a href="http://x.y">hi</a>'
+        );
+    });
+
+    test("converts custom emoji", () => {
+        expect(
+            markdownV2ToHtml("![👍](tg://emoji?id=42)")
+        ).toEqual('<tg-emoji emoji-id="42">👍</tg-emoji>');
+    });
+
+    test("strips backslash escapes from plain text", () => {
+        expect(markdownV2ToHtml("1\\.5")).toEqual("1.5");
+    });
+
+    test("HTML-escapes plain-text < and &", () => {
+        expect(markdownV2ToHtml("a < b & c")).toEqual(
+            "a &lt; b &amp; c"
+        );
+    });
+
+    test("HTML-escapes pre body", () => {
+        expect(markdownV2ToHtml("```<x>```")).toEqual(
+            "<pre>&lt;x&gt;</pre>"
+        );
+    });
+
+    test("empty input → empty output", () => {
+        expect(markdownV2ToHtml("")).toEqual("");
+    });
+});
+
+describe("htmlToMarkdownV2 — standalone function", () => {
+    test("converts <b> and <strong>", () => {
+        expect(htmlToMarkdownV2("<b>hi</b>")).toEqual("*hi*");
+        expect(htmlToMarkdownV2("<strong>hi</strong>")).toEqual("*hi*");
+    });
+
+    test("converts <i> and <em>", () => {
+        expect(htmlToMarkdownV2("<i>hi</i>")).toEqual("_hi_");
+        expect(htmlToMarkdownV2("<em>hi</em>")).toEqual("_hi_");
+    });
+
+    test("converts <u> and <ins>", () => {
+        expect(htmlToMarkdownV2("<u>hi</u>")).toEqual("__hi__");
+        expect(htmlToMarkdownV2("<ins>hi</ins>")).toEqual("__hi__");
+    });
+
+    test("converts <s>, <strike>, <del>", () => {
+        expect(htmlToMarkdownV2("<s>hi</s>")).toEqual("~hi~");
+        expect(htmlToMarkdownV2("<strike>hi</strike>")).toEqual("~hi~");
+        expect(htmlToMarkdownV2("<del>hi</del>")).toEqual("~hi~");
+    });
+
+    test("converts spoiler in three forms", () => {
+        expect(htmlToMarkdownV2("<tg-spoiler>x</tg-spoiler>")).toEqual(
+            "||x||"
+        );
+        expect(
+            htmlToMarkdownV2('<span class="tg-spoiler">x</span>')
+        ).toEqual("||x||");
+        expect(htmlToMarkdownV2("<spoiler>x</spoiler>")).toEqual("||x||");
+    });
+
+    test("converts inline code", () => {
+        expect(htmlToMarkdownV2("<code>x</code>")).toEqual("`x`");
+    });
+
+    test("converts pre with language", () => {
+        expect(
+            htmlToMarkdownV2(
+                '<pre><code class="language-py">foo</code></pre>'
+            )
+        ).toEqual("```py\nfoo```");
+    });
+
+    test("converts pre without language", () => {
+        expect(htmlToMarkdownV2("<pre>foo</pre>")).toEqual("```foo```");
+    });
+
+    test("converts inline link", () => {
+        expect(
+            htmlToMarkdownV2('<a href="http://x.y">hi</a>')
+        ).toEqual("[hi](http://x.y)");
+    });
+
+    test("converts blockquote", () => {
+        expect(
+            htmlToMarkdownV2("<blockquote>line1\nline2</blockquote>")
+        ).toEqual(">line1\n>line2");
+    });
+
+    test("converts expandable blockquote", () => {
+        expect(
+            htmlToMarkdownV2(
+                "<blockquote expandable>hi</blockquote>"
+            )
+        ).toEqual(">hi||");
+        expect(
+            htmlToMarkdownV2(
+                '<blockquote expandable="">hi</blockquote>'
+            )
+        ).toEqual(">hi||");
+    });
+
+    test("converts custom emoji", () => {
+        expect(
+            htmlToMarkdownV2(
+                '<tg-emoji emoji-id="42">👍</tg-emoji>'
+            )
+        ).toEqual("![👍](tg://emoji?id=42)");
+    });
+
+    test("decodes named HTML entities in tag content", () => {
+        expect(htmlToMarkdownV2("<b>a &amp; b</b>")).toEqual("*a & b*");
+        expect(htmlToMarkdownV2("a &lt; b &gt; c")).toEqual("a < b > c");
+        expect(htmlToMarkdownV2("&quot;hi&quot;")).toEqual('"hi"');
+    });
+});
+
+describe("MarkdownV2 round-trip via .parse and .unparse", () => {
+    const cases: Array<{ name: string; md: string }> = [
+        { name: "bold", md: "*hi*" },
+        { name: "italic", md: "_hi_" },
+        { name: "underline", md: "__hi__" },
+        { name: "strike", md: "~hi~" },
+        { name: "spoiler", md: "||hi||" },
+        { name: "code", md: "`x`" },
+        { name: "pre", md: "```foo```" },
+        { name: "pre with language", md: "```py\nfoo```" },
+        { name: "inline link", md: "[hi](http://x.y)" },
+        { name: "blockquote", md: ">hi" },
+    ];
+
+    for (const c of cases) {
+        test(`round-trips ${c.name}`, () => {
+            const [text, entities] = MarkdownV2Parser.parse(c.md);
+            const back = MarkdownV2Parser.unparse(text, entities);
+            const [text2, entities2] = MarkdownV2Parser.parse(back);
+            expect(text2).toEqual(text);
+            expect(entities2.length).toEqual(entities.length);
+            for (let i = 0; i < entities.length; i++) {
+                expect(entities2[i].constructor).toBe(
+                    entities[i].constructor
+                );
+            }
+        });
+    }
+
+    test("expandable blockquote round-trips with collapsed flag preserved", () => {
+        const [text, entities] = MarkdownV2Parser.parse(">hi||");
+        const back = MarkdownV2Parser.unparse(text, entities);
+        const [text2, entities2] = MarkdownV2Parser.parse(back);
+        expect(text2).toEqual(text);
+        expect(entities2.length).toEqual(1);
+        expect(entities2[0]).toBeInstanceOf(types.MessageEntityBlockquote);
+        expect(
+            (entities2[0] as types.MessageEntityBlockquote).collapsed
+        ).toEqual(true);
+    });
 });
diff --git a/gramjs/extensions/html.ts b/gramjs/extensions/html.ts
index 4c73250a..b6e50476 100644
--- a/gramjs/extensions/html.ts
+++ b/gramjs/extensions/html.ts
@@ -36,13 +36,17 @@ class HTMLToTelegramParser implements Handler {
         const args: any = {};
         if (name == "strong" || name == "b") {
             EntityType = Api.MessageEntityBold;
-        } else if (name == "spoiler") {
+        } else if (
+            name == "spoiler" ||
+            name == "tg-spoiler" ||
+            (name == "span" && attributes.class === "tg-spoiler")
+        ) {
             EntityType = Api.MessageEntitySpoiler;
         } else if (name == "em" || name == "i") {
             EntityType = Api.MessageEntityItalic;
-        } else if (name == "u") {
+        } else if (name == "u" || name == "ins") {
             EntityType = Api.MessageEntityUnderline;
-        } else if (name == "del" || name == "s") {
+        } else if (name == "del" || name == "s" || name == "strike") {
             EntityType = Api.MessageEntityStrike;
         } else if (name == "blockquote") {
             EntityType = Api.MessageEntityBlockquote;
@@ -197,7 +201,7 @@ export class HTMLParser {
             if (entity instanceof Api.MessageEntityBold) {
                 html.push(`<strong>${entityText}</strong>`);
             } else if (entity instanceof Api.MessageEntitySpoiler) {
-                html.push(`<spoiler>${entityText}</spoiler>`);
+                html.push(`<tg-spoiler>${entityText}</tg-spoiler>`);
             } else if (entity instanceof Api.MessageEntityItalic) {
                 html.push(`<em>${entityText}</em>`);
             } else if (entity instanceof Api.MessageEntityCode) {
@@ -207,7 +211,13 @@ export class HTMLParser {
             } else if (entity instanceof Api.MessageEntityStrike) {
                 html.push(`<del>${entityText}</del>`);
             } else if (entity instanceof Api.MessageEntityBlockquote) {
-                html.push(`<blockquote>${entityText}</blockquote>`);
+                if ((entity as any).collapsed) {
+                    html.push(
+                        `<blockquote expandable>${entityText}</blockquote>`
+                    );
+                } else {
+                    html.push(`<blockquote>${entityText}</blockquote>`);
+                }
             } else if (entity instanceof Api.MessageEntityPre) {
                 if (entity.language) {
                     html.push(
diff --git a/gramjs/extensions/index.ts b/gramjs/extensions/index.ts
index a2766ef4..575f4223 100644
--- a/gramjs/extensions/index.ts
+++ b/gramjs/extensions/index.ts
@@ -5,3 +5,4 @@ export { PromisedWebSockets } from "./PromisedWebSockets";
 export { PromisedNetSockets } from "./PromisedNetSockets";
 export { MessagePacker } from "./MessagePacker";
 export { AsyncQueue } from "./AsyncQueue";
+export { markdownV2ToHtml, htmlToMarkdownV2 } from "./markdownv2";
diff --git a/gramjs/extensions/markdownv2.ts b/gramjs/extensions/markdownv2.ts
index fc67fac2..a20afd2d 100644
--- a/gramjs/extensions/markdownv2.ts
+++ b/gramjs/extensions/markdownv2.ts
@@ -1,81 +1,400 @@
 import { Api } from "../tl";
 import { HTMLParser } from "./html";
 
-export class MarkdownV2Parser {
-    static parse(message: string): [string, Api.TypeMessageEntity[]] {
-        // Bold
-        message = message.replace(/\*(.*?)\*/g, "<b>$1</b>");
+const escapeHtmlAll = (s: string): string =>
+    s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+
+// HTML-escape only `&` and `<` (not `>`, since blockquote detection still
+// needs literal `>` at line start; not `"`, which is harmless in text content).
+const escapeHtmlText = (s: string): string =>
+    s.replace(/&/g, "&amp;").replace(/</g, "&lt;");
+
+function processBlockquotes(text: string): string {
+    const lines = text.split("\n");
+    const out: string[] = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (lines[i].startsWith(">")) {
+            const block: string[] = [];
+            while (i < lines.length && lines[i].startsWith(">")) {
+                block.push(lines[i].slice(1));
+                i++;
+            }
+            const lastIdx = block.length - 1;
+            let expandable = false;
+            if (block[lastIdx].endsWith("||")) {
+                expandable = true;
+                block[lastIdx] = block[lastIdx].slice(0, -2);
+            }
+            const tag = expandable ? "<blockquote expandable>" : "<blockquote>";
+            out.push(`${tag}${block.join("\n")}</blockquote>`);
+        } else {
+            out.push(lines[i]);
+            i++;
+        }
+    }
+    return out.join("\n");
+}
 
-        // underline
-        message = message.replace(/__(.*?)__/g, "<u>$1</u>");
+/**
+ * Convert a Telegram MarkdownV2-formatted string to its HTML equivalent
+ * (the dialect understood by {@link HTMLParser}, which is also valid
+ * Telegram Bot API HTML).
+ *
+ * Implements the spec at https://core.telegram.org/bots/api#markdownv2-style:
+ *   - Span markup: `*bold*`, `_italic_`, `__underline__`, `~strike~`,
+ *     `||spoiler||`.
+ *   - Inline `\`code\`` and ` ```pre``` ` (optionally
+ *     ` ```language\nbody``` `).
+ *   - Inline link `[label](url)` and custom emoji
+ *     `![label](tg://emoji?id=N)`.
+ *   - Blockquotes (`>line`); the last line ending in `||` marks the
+ *     blockquote as expandable.
+ *   - Backslash escapes: `\X` for any X is treated as the literal X. Inside
+ *     pre/code only `\\` and `` \` `` apply; inside a link/emoji `(URL)` only
+ *     `\\` and `\)` apply.
+ *
+ * Plain-text `&` and `<` are HTML-escaped so the output is safe to feed to
+ * any HTML parser.
+ */
+export function markdownV2ToHtml(message: string): string {
+    // Sanitize: strip raw NUL / SOH from the input. We use these two
+    // control characters internally as placeholder delimiters; if they
+    // appeared verbatim in user content the regexes in stages 5/6 could
+    // splice in arbitrary protected HTML or look up undefined indices.
+    // Telegram messages disallow these control chars anyway.
+    message = message.replace(/[\u0000\u0001]/g, "");
 
-        // strikethrough
-        message = message.replace(/~(.*?)~/g, "<s>$1</s>");
+    // Stage 1 — Extract protected regions (pre, code, links, custom emoji)
+    // up front. Inside these, only their own escape rules apply, and outer
+    // markup must NOT re-process them. Each region is converted to its final
+    // HTML, HTML-escaped where necessary, and stored behind a placeholder
+    // that survives stages 2-5 unchanged.
+    const protectedHtml: string[] = [];
+    const protect = (html: string): string => {
+        const idx = protectedHtml.push(html) - 1;
+        return `\u0000${idx}\u0000`;
+    };
 
-        // italic
-        message = message.replace(/-(.*?)-/g, "<i>$1</i>");
+    let processed = "";
+    let i = 0;
+    while (i < message.length) {
+        const c = message[i];
 
-        // pre
-        message = message.replace(/```([\s\S]*?)```/g, "<pre>$1</pre>");
+        // Backslash escape: keep both characters verbatim so stage 2 can
+        // mask them away from the markup regexes.
+        if (c === "\\" && i + 1 < message.length) {
+            processed += message.slice(i, i + 2);
+            i += 2;
+            continue;
+        }
 
-        // code
-        message = message.replace(/`(.*?)`/g, "<code>$1</code>");
+        // Pre block: ```[language\n]body```
+        if (message.startsWith("```", i)) {
+            let j = i + 3;
+            while (j < message.length) {
+                if (message[j] === "\\" && j + 1 < message.length) {
+                    j += 2;
+                    continue;
+                }
+                if (message.startsWith("```", j)) break;
+                j++;
+            }
+            if (j < message.length) {
+                let body = message.slice(i + 3, j);
+                let language = "";
+                const nlIdx = body.indexOf("\n");
+                if (nlIdx > 0) {
+                    const candidate = body.slice(0, nlIdx);
+                    // Accept any non-empty first line that contains no
+                    // whitespace as the language tag (covers c++, c#,
+                    // objective-c++, asp.net, etc.). If the first line
+                    // contains a space/tab, treat it as content.
+                    if (/^\S+$/.test(candidate)) {
+                        language = candidate;
+                        body = body.slice(nlIdx + 1);
+                    }
+                }
+                body = body.replace(/\\([`\\])/g, "$1");
+                const html = language
+                    ? `<pre><code class="language-${escapeHtmlAll(
+                          language
+                      )}">${escapeHtmlAll(body)}</code></pre>`
+                    : `<pre>${escapeHtmlAll(body)}</pre>`;
+                processed += protect(html);
+                i = j + 3;
+                continue;
+            }
+        }
 
-        // Spoiler
-        message = message.replace(/\|\|(.*?)\|\|/g, "<spoiler>$1</spoiler>");
+        // Inline code: `body`
+        if (c === "`") {
+            let j = i + 1;
+            while (j < message.length) {
+                if (message[j] === "\\" && j + 1 < message.length) {
+                    j += 2;
+                    continue;
+                }
+                if (message[j] === "`") break;
+                j++;
+            }
+            if (j < message.length && message[j] === "`") {
+                let body = message.slice(i + 1, j);
+                body = body.replace(/\\([`\\])/g, "$1");
+                processed += protect(`<code>${escapeHtmlAll(body)}</code>`);
+                i = j + 1;
+                continue;
+            }
+        }
 
-        // Inline URL
-        message = message.replace(
-            /(?<!\!)\[([^\]]+)\]\(([^)]+)\)/g,
-            '<a href="$2">$1</a>'
-        );
+        // Link [label](url) or custom emoji ![label](tg://emoji?id=N).
+        // The label is left exposed so subsequent markup/unescape stages
+        // still apply to it; only the surrounding tag is protected.
+        if (c === "[" || (c === "!" && message[i + 1] === "[")) {
+            const isEmoji = c === "!";
+            const labelStart = i + (isEmoji ? 2 : 1);
 
-        // Emoji
-        message = message.replace(
-            /!\[([^\]]+)\]\(tg:\/\/emoji\?id=(\d+)\)/g,
-            '<tg-emoji emoji-id="$2">$1</tg-emoji>'
-        );
+            let labelEnd = labelStart;
+            while (labelEnd < message.length) {
+                if (
+                    message[labelEnd] === "\\" &&
+                    labelEnd + 1 < message.length
+                ) {
+                    labelEnd += 2;
+                    continue;
+                }
+                if (message[labelEnd] === "]") break;
+                labelEnd++;
+            }
 
-        //
-        return HTMLParser.parse(message);
+            if (
+                labelEnd < message.length &&
+                message[labelEnd] === "]" &&
+                message[labelEnd + 1] === "("
+            ) {
+                let urlEnd = labelEnd + 2;
+                let urlBody = "";
+                while (urlEnd < message.length) {
+                    if (
+                        message[urlEnd] === "\\" &&
+                        urlEnd + 1 < message.length
+                    ) {
+                        const next = message[urlEnd + 1];
+                        if (next === ")" || next === "\\") {
+                            urlBody += next;
+                            urlEnd += 2;
+                            continue;
+                        }
+                    }
+                    if (message[urlEnd] === ")") break;
+                    urlBody += message[urlEnd];
+                    urlEnd++;
+                }
+                if (urlEnd < message.length && message[urlEnd] === ")") {
+                    const label = message.slice(labelStart, labelEnd);
+                    if (isEmoji) {
+                        // Accept any tg://emoji URL with an `id=N`
+                        // parameter (other query params allowed).
+                        const m = urlBody.match(
+                            /^tg:\/\/emoji\?(?:[^&]*&)*id=(\d+)(?:&|$)/
+                        );
+                        if (m) {
+                            const open = protect(
+                                `<tg-emoji emoji-id="${escapeHtmlAll(
+                                    m[1]
+                                )}">`
+                            );
+                            const close = protect(`</tg-emoji>`);
+                            processed += open + label + close;
+                            i = urlEnd + 1;
+                            continue;
+                        }
+                        // Not a recognized emoji URL — emit `!` literal and
+                        // let the next iteration parse `[...](...)` as a
+                        // regular link.
+                        processed += "!";
+                        i += 1;
+                        continue;
+                    }
+                    const open = protect(
+                        `<a href="${escapeHtmlAll(urlBody)}">`
+                    );
+                    const close = protect(`</a>`);
+                    processed += open + label + close;
+                    i = urlEnd + 1;
+                    continue;
+                }
+            }
+        }
+
+        processed += c;
+        i++;
     }
 
-    static unparse(
-        text: string,
-        entities: Api.TypeMessageEntity[] | undefined
-    ) {
-        text = HTMLParser.unparse(text, entities);
+    // Stage 2 — Mask backslash-escapes FIRST (before HTML-escaping). Each
+    // \X is replaced with a placeholder containing only control characters,
+    // so the markup regexes in stage 3 cannot consume the escaped char as a
+    // delimiter. Stage 5 will substitute the bare char back. Masking must
+    // happen before stage 2.5's HTML escape so that an escaped `<` is
+    // captured as `<` (not as `&` from `&lt;`).
+    const maskedEscapes: string[] = [];
+    processed = processed.replace(/\\([\s\S])/g, (_match, ch) => {
+        const idx = maskedEscapes.push(ch) - 1;
+        return `\u0001${idx}\u0001`;
+    });
+
+    // Stage 2.5 — HTML-escape user content. Placeholders for protected
+    // regions and masked escapes contain only NUL/SOH + digits, so they
+    // are unaffected. We escape `&` and `<` only: `>` must stay literal so
+    // stage 4 can detect line-start blockquote markers, and `"` is harmless
+    // in text content.
+    processed = escapeHtmlText(processed);
+
+    // Stage 3 — Span-level markup. Order matters: `__` (underline) is
+    // resolved before `_` (italic) per the spec's left-to-right greediness
+    // for ambiguous `__`.
+    processed = processed.replace(/__([\s\S]+?)__/g, "<u>$1</u>");
+    processed = processed.replace(/\*([\s\S]+?)\*/g, "<b>$1</b>");
+    processed = processed.replace(/_([\s\S]+?)_/g, "<i>$1</i>");
+    processed = processed.replace(/~([\s\S]+?)~/g, "<s>$1</s>");
+    processed = processed.replace(
+        /\|\|([\s\S]+?)\|\|/g,
+        "<tg-spoiler>$1</tg-spoiler>"
+    );
+
+    // Stage 4 — Blockquotes (line-level). Runs after span markup so inline
+    // formatting inside a quoted line is already converted to HTML tags.
+    processed = processBlockquotes(processed);
+
+    // Stage 5 — Unmask escapes: each placeholder becomes its bare char,
+    // dropping the leading backslash. If the bare char is `<` or `&` we
+    // re-escape so HTMLParser still sees it as user content.
+    processed = processed.replace(/\u0001(\d+)\u0001/g, (_m, n) => {
+        const ch = maskedEscapes[Number(n)];
+        if (ch === "<") return "&lt;";
+        if (ch === "&") return "&amp;";
+        return ch;
+    });
+
+    // Stage 6 — Restore protected regions.
+    processed = processed.replace(
+        /\u0000(\d+)\u0000/g,
+        (_m, n) => protectedHtml[Number(n)]
+    );
 
-        // Bold
-        text = text.replace(/<b>(.*?)<\/b>/g, "*$1*");
+    return processed;
+}
+
+/**
+ * Convert a Telegram-flavored HTML string back to MarkdownV2 source.
+ *
+ * Accepts every tag listed in the Telegram Bot API HTML spec
+ * (https://core.telegram.org/bots/api#html-style):
+ *   - bold: `<b>` / `<strong>`
+ *   - italic: `<i>` / `<em>`
+ *   - underline: `<u>` / `<ins>`
+ *   - strike: `<s>` / `<strike>` / `<del>`
+ *   - spoiler: `<tg-spoiler>` / `<span class="tg-spoiler">` / `<spoiler>`
+ *     (the last is what {@link HTMLParser.unparse} produces internally)
+ *   - code, pre, blockquote (with optional `expandable` attribute),
+ *     `<a href>`, `<tg-emoji emoji-id>`
+ *
+ * This is a best-effort textual transform; it does not yet emit MarkdownV2
+ * backslash escapes for special characters in surrounding plain text, so
+ * round-tripping plain text containing literal `*_~|...` is not guaranteed.
+ */
+export function htmlToMarkdownV2(html: string): string {
+    let text = html;
+
+    // Pre with optional language (must come before bare <pre>).
+    text = text.replace(
+        /<pre><code class="language-([^"]*)">([\s\S]*?)<\/code><\/pre>/g,
+        "```$1\n$2```"
+    );
+
+    // Pre
+    text = text.replace(/<pre>([\s\S]*?)<\/pre>/g, "```$1```");
+
+    // Code
+    text = text.replace(/<code>([\s\S]*?)<\/code>/g, "`$1`");
+
+    // Bold
+    text = text.replace(/<(?:b|strong)>([\s\S]*?)<\/(?:b|strong)>/g, "*$1*");
+
+    // Italic
+    text = text.replace(/<(?:i|em)>([\s\S]*?)<\/(?:i|em)>/g, "_$1_");
+
+    // Underline
+    text = text.replace(/<(?:u|ins)>([\s\S]*?)<\/(?:u|ins)>/g, "__$1__");
 
-        // Underline
-        text = text.replace(/<u>(.*?)<\/u>/g, "__$1__");
+    // Strike
+    text = text.replace(
+        /<(?:s|strike|del)>([\s\S]*?)<\/(?:s|strike|del)>/g,
+        "~$1~"
+    );
 
-        // Code
-        text = text.replace(/<code>(.*?)<\/code>/g, "`$1`");
+    // Spoiler — accept all three spec/internal forms.
+    text = text.replace(
+        /<tg-spoiler>([\s\S]*?)<\/tg-spoiler>/g,
+        "||$1||"
+    );
+    text = text.replace(
+        /<span class="tg-spoiler">([\s\S]*?)<\/span>/g,
+        "||$1||"
+    );
+    text = text.replace(/<spoiler>([\s\S]*?)<\/spoiler>/g, "||$1||");
 
-        // Pre
-        text = text.replace(/<pre>(.*?)<\/pre>/g, "```$1```");
+    // Blockquote — render line-by-line with leading `>` and append `||` to
+    // the last line if expandable.
+    text = text.replace(
+        /<blockquote(\s+expandable(?:="[^"]*")?)?>([\s\S]*?)<\/blockquote>/g,
+        (_match, expandable, body) => {
+            const lines = String(body).split("\n");
+            const quoted = lines.map((l) => `>${l}`).join("\n");
+            return expandable ? `${quoted}||` : quoted;
+        }
+    );
 
-        // strikethrough
-        text = text.replace(/<s>(.*?)<\/s>/g, "~$1~");
+    // Inline URL
+    text = text.replace(/<a href="([^"]*)">([\s\S]*?)<\/a>/g, "[$2]($1)");
 
-        // Italic
-        text = text.replace(/<i>(.*?)<\/i>/g, "-$1-");
+    // Custom emoji
+    text = text.replace(
+        /<tg-emoji emoji-id="(\d+)">([\s\S]*?)<\/tg-emoji>/g,
+        "![$2](tg://emoji?id=$1)"
+    );
 
-        // Spoiler
-        text = text.replace(/<spoiler>(.*?)<\/spoiler>/g, "||$1||");
+    // Decode the four named HTML entities supported by Telegram's HTML
+    // parse mode. Done last so partial entities introduced by earlier
+    // substitutions (impossible in practice, but defensive) aren't double-
+    // decoded.
+    const namedEntities: Record<string, string> = {
+        amp: "&",
+        lt: "<",
+        gt: ">",
+        quot: '"',
+    };
+    text = text.replace(
+        /&(amp|lt|gt|quot);/g,
+        (_m, n: string) => namedEntities[n]
+    );
 
-        // Inline URL
-        text = text.replace(/<a href="([^"]+)">([^<]+)<\/a>/g, "[$2]($1)");
+    return text;
+}
 
-        // Emoji
-        text = text.replace(
-            /<tg-emoji emoji-id="(\d+)">([^<]+)<\/tg-emoji>/g,
-            "![$2](tg://emoji?id=$1)"
-        );
+export class MarkdownV2Parser {
+    static parse(message: string): [string, Api.TypeMessageEntity[]] {
+        return HTMLParser.parse(markdownV2ToHtml(message));
+    }
 
-        return text;
+    static unparse(
+        text: string,
+        entities: Api.TypeMessageEntity[] | undefined
+    ) {
+        return htmlToMarkdownV2(HTMLParser.unparse(text, entities));
     }
 }