highlight-native.ts#

Splices replacements back over the blocks the native pass left pending.

Entry i is the highlighted <pre> for pending block i, or an empty string to leave that block alone. This keeps a page that needs one exotic grammar — a Vue SFC, a Mermaid diagram — off the HTML round trip, rather than surrendering the whole document for it.

Extract text content from a hast node.

The native tree-sitter highlighting path, plus the small hast helpers both engines read code blocks with.

Kept apart from the Shiki plumbing so the two engines stay legible on their own, and arranged as a leaf: highlight.ts reaches in here, never the other way round.

Highlights every code block in a rendered document in one native call.

Returns the rewritten HTML and the languages it declined, so the caller knows whether Shiki still has to run over the result. Returns null when the native module is unavailable.

This exists because the plumbing dwarfed the work: walking each page through an HTML parser and serializer to find <pre> elements cost 139 ms over the documentation corpus, and re-parsing each highlighted block to splice it back cost another 38 ms, against 14 ms of actual highlighting.

It runs off the main thread. The synchronous binding held the event loop for the whole pass, so a build asking for several pages at once still got them one at a time — Promise.all over the corpus measured the same as awaiting each page in turn.

Highlights with the native tree-sitter engine, or null when it has no grammar for lang.

Parsing once and walking the tree is roughly eight times faster than matching TextMate patterns line by line — 10.5 ms against 81.5 ms over the documentation corpus's code blocks — and it emits the same --octc-shiki-* markup, so themes are unaffected.

The language-* class on a <code> element, if it carries one.

What highlightDocumentNatively produced for a page.

Whether the native engine claims lang.

A block the native pass left for another highlighter.

Whether any block in this tree still needs Shiki.

Creating a Shiki highlighter parses two dozen TextMate grammars, about 190 ms, so a document whose languages are all covered natively must not touch it at all.