feat: HTML parser

[KnightNiwrem]

Note: Tests and select utility methods written by LLM
Note: Parsing methods are handwritten and deliberately rolled out (i.e. not refactored for DRY) at this moment - i.e. putting all the state transitions on paper first

[Copilot]

Pull request overview

Introduces a new streaming HTML parser (HTMLStreamParser) that converts Telegram HTML-style text into FormattedString instances, along with initial tests and a specification document.

Changes:

• Added HTMLStreamParser state-machine implementation for supported tags/entities and Telegram entity mapping.
• Added test coverage for several core tag mappings and chunk-boundary streaming behavior.
• Exported the new parser from the library entrypoint and added a spec document describing intended completion criteria.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.

File	Description
src/stream-html-to-format.ts	New streaming HTML parser implementation and entity mapping logic.
test/stream-html-to-format.test.ts	New tests validating core tag/entity mappings and streamed chunk handling.
src/mod.ts	Re-exports the new parser module.
specs.md	Adds a detailed refactor/specification document for the parser behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[KnorpelSenf]

What's the deal here? Wanna instruct LLMs to output HTML and then use this to stream formatted drafts?

[KnightNiwrem]

What's the deal here? Wanna instruct LLMs to output HTML and then use this to stream formatted drafts?

Don't really have LLMs as an intended audience for this, though it might coincidentally work (i.e. this parser is somewhat lenient on incomplete HTML strings). The main (and original) audience would be i18n users. Instead of wrangling with HTML parse_mode, we want to locally convert HTML strings (which i18n users are forced to use as they can't do template literals in .ftl) into text+entities.

[KnightNiwrem]

Only works coincidentally because of the chosen architecture of the parser

const s = new HTMLStreamParser();

s.add('This is the start of ');
console.log(s.toFormattedString());

s.add('some <b>bolded content ');
console.log(s.toFormattedString());

s.add('that later</b> end with plain text');
console.log(s.toFormattedString());

=======

parse-mode % deno run src/stream-html-to-format.ts 

FormattedString { rawText: "This is the start of ", rawEntities: [] }
FormattedString {
  rawText: "This is the start of some bolded content ",
  rawEntities: []
}
FormattedString {
  rawText: "This is the start of some bolded content that later end with plain text",
  rawEntities: [ { type: "bold", offset: 26, length: 25 } ]
}

[KnorpelSenf]

That's pretty cool!

[KnightNiwrem]

Merged as unstable/experimental, but good enough for RFC from real world use