@lanexio/parser-grammar-html

This page documents @lanexio/parser-grammar-html, the HTML grammar package implementing the full WHATWG HTML parsing algorithm, including all 23 insertion modes, adoption agency, foster parenting, and foreign content (SVG, MathML).

Version: Stable
Module name: parser-grammar-html
Package: @lanexio/parser-grammar-html
Import path: @lanexio/parser-grammar-html
Layer: 2 (Grammar)
Runtime: Universal (browser, server, edge worker)
Module format: ESM
Stability: Stable
Primary use case: Parse HTML documents and fragments into a flat AST.

Layer contract

When to use this module

You need to parse HTML documents or fragments (innerHTML) into a traversable AST.
You need to serialize a parsed HTML tree back to HTML source.
You need to sanitize HTML content against a configurable policy.
You need to extract text content or decode HTML entities.

Module boundary

Boundary	Description
Inputs	`Uint8Array` (source bytes) + optional `ParseHtmlOptions`
Outputs	`LexTree` (flat AST rooted at `HtmlKind.Document` or `HtmlKind.Fragment`)
Side effects	None
Determinism	Yes (same bytes + same options produce identical tree)
External dependencies	`@lanexio/parser-core`
Never-throw guarantee	Yes for all parse entry points
Security surface	`serializeHtml()` emits raw HTML (XSS risk if caller passes output to innerHTML). `sanitizeHtml()` mitigates this.

Installation

Install the package.
- pnpm
- npm
- yarn
Terminal window
pnpm add @lanexio/parser-grammar-html
Terminal window
npm install @lanexio/parser-grammar-html
Terminal window
yarn add @lanexio/parser-grammar-html

Import the named export.

import { parseHtml } from '@lanexio/parser-grammar-html';

Peer dependencies

Requirement	Required	Layer	Notes
`@lanexio/parser-core`	Yes	1	`^1.0.0`

Basic Usage

Headless usage (pure TypeScript)

import { parseHtml } from '@lanexio/parser-grammar-html';

const encoder = new TextEncoder();
const bytes = encoder.encode('<!doctype html><p>Hello <strong>world</strong></p>');

const tree = parseHtml(bytes);

console.log(tree.nodeCount);   // total nodes in the flat AST
console.log(tree.root.kind);   // HtmlKind.Document

Fragment parsing

import { parseHtml, HtmlParseMode } from '@lanexio/parser-grammar-html';

const encoder = new TextEncoder();
const tree = parseHtml(
  encoder.encode('<li>Item one</li><li>Item two</li>'),
  { mode: HtmlParseMode.Fragment, contextElement: 'ul' }
);

Serialize back to HTML

import { parseHtml, serializeHtml } from '@lanexio/parser-grammar-html';

const encoder = new TextEncoder();
const tree = parseHtml(encoder.encode('<p>Hello <b>world</b>'));
const html = serializeHtml(tree);
// "<html><head></head><body><p>Hello <b>world</b></p></body></html>"

Exports

Export	Type	Description
`parseHtml`	`(source: Uint8Array, options?: ParseHtmlOptions) => LexTree`	Parse HTML. Never throws.
`serializeHtml`	`(input: LexTree \| LexNode, options?: SerializeHtmlOptions) => string`	Serialize tree back to HTML string.
`sanitizeHtml`	`(tree: LexTree, policy?: SanitizePolicy) => LexTree`	Produce a safe projection of a parsed HTML tree.
`sanitizeHtmlToString`	`(tree: LexTree, policy?: SanitizePolicy) => string`	Serialize safe content to string via inline AST filtering.
`HtmlKind`	`const object`	Numeric kind IDs for all HTML node types.
`HtmlField`	`const object`	Numeric field IDs for HTML attributes and slots.
`HTML_FIELD_NAMES_BY_ID`	`readonly string[]`	Field name lookup by numeric field ID.
`HtmlParseMode`	`const object`	`Document`, `Fragment`
`HtmlParseErrorCode`	`const object`	Parse error code constants.
`DEFAULT_POLICY`	`SanitizePolicy`	Default sanitization policy (allows most safe HTML).
`resolvePolicy`	`(policy?: SanitizePolicy) => SanitizePolicy`	Resolve a policy, falling back to DEFAULT_POLICY.
`isSafeUrl`	`(url: string) => boolean`	Check if a URL scheme is considered safe.
`isSafeSrcset`	`(srcset: string) => boolean`	Check if a srcset attribute value is safe.
`isAttributeSafe`	`(name: string, value: string) => boolean`	Check if an attribute name/value pair is safe.
`isTagAllowed`	`(tag: string) => boolean`	Check if a tag is allowed by the default policy.
`textContent`	`(node: LexNode) => string`	Extract plain text from an HTML tree.
`decodeEntities`	`(text: string) => string`	Decode HTML character references.
`RAWTEXT_ELEMENT_NAMES`	`readonly string[]`	Names of raw-text elements (script, style).
`TokenKind`	`const object`	Token type constants from the tokenizer.
`tokenize`	`(source: Uint8Array, options?: TokenizeOptions) => Token[]`	Tokenize HTML source bytes.
`DEFAULT_CONTENT_MODES`	`object`	Default tokenizer content modes.
`htmlGrammar`	`LanexioParserPureGrammar`	Grammar descriptor for use with parser-pure.
`htmlRegistration`	`GrammarRegistration`	Registration for the unified grammar registry.

Options

ParseHtmlOptions

Field	Type	Required	Default	Description
`mode`	`HtmlParseMode`	No	`HtmlParseMode.Document`	Parse as a full document or as a fragment.
`contextElement`	`string`	No	`undefined`	Context element name for fragment parsing (e.g. `"div"`, `"td"`, `"svg"`).
`contextElementLeaf`	`string`	No	`undefined`	Leaf element within the foreign-namespace context for fragment parsing.
`scriptingEnabled`	`boolean`	No	`false`	Scripting flag. When `true`, `<noscript>` is raw-text content.
`wasmTokenizer`	`(source: Uint8Array) => Token[]`	No	`undefined`	Optional WASM-backed tokenizer fast-path.

SerializeHtmlOptions

Field	Type	Required	Default	Description
`outer`	`boolean`	No	`true`	When `true`, serialize the root node and all children (outerHTML). When `false`, serialize only children (innerHTML).

Return shape

Property	Type	Description
`root`	`LexNode`	Root node (`HtmlKind.Document` or `HtmlKind.Fragment`).
`nodeCount`	`number`	Total nodes in the tree.
`source`	`Uint8Array`	Original parsed bytes.

Exported types

Type	Purpose	Notes
`ParseHtmlOptions`	Options for `parseHtml`	See options table above.
`HtmlParseMode`	Union of parse mode values	`HtmlParseMode.Document` \| `HtmlParseMode.Fragment`
`SerializeHtmlOptions`	Options for `serializeHtml`	See options table above.
`SanitizePolicy`	Sanitization policy	Defines which tags, attributes, and URLs are allowed.
`HtmlParseError`	Parse error descriptor	Returned via error codes.
`WasmScanExports`	Type for WASM tokenizer exports	Internal.

Configuration and Extension

ParseModes

parseHtml supports two modes:

Document mode (default): parses as a full HTML document with implied <html>, <head>, <body>.
Fragment mode: parses as an HTML fragment in the context of a specific element (like innerHTML).

WASM tokenizer

Pass a wasmTokenizer option to use the WASM-backed tokenizer as a fast-path. When the source contains no character references, the WASM tokenizer is used instead of the TypeScript tokenizer.

Accessibility

Accessibility requirements

The HTML parser preserves semantic HTML structure (headings, landmarks, lists, image alt attributes). The serializer outputs raw HTML that can be directly injected into a browser — consuming code is responsible for ensuring semantic output.

Accessibility checklist

Concern	Status
Generated output semantics	Preserves HTML semantics (headings, landmarks, lists, alt text)
ARIA attributes in serialized output	Preserved
Semantic element round-trip	Yes

Security

Security considerations

parseHtml never throws on any byte sequence. Malformed input produces LexError nodes.
serializeHtml() emits raw HTML. Callers must not pass the output directly to innerHTML without escaping.
sanitizeHtml() and sanitizeHtmlToString() provide configurable sanitization against XSS.

Threat	Mitigation	Status
Malformed input byte sequence	Panic-free guarantee: all inputs accepted, errors produce `LexError` AST nodes	Implemented
XSS via serializer output	`serializeHtml()` emits raw HTML — caller is responsible for safe insertion. `sanitizeHtml()` provides policy-based filtering	Documented

Companion packages

Package	Relationship	Layer	Notes
`@lanexio/parser-core`	Requires	1	Provides `LexTree`, `LexNode`, `LexCursor`
`@lanexio/parser-pure`	Consumes	4	Wraps `parseHtml` in a unified bridge
`@lanexio/parser`	Consumes	6	Re-exports `parseHtml` as an optional grammar

Integration example

import { parseHtml, HtmlKind } from '@lanexio/parser-grammar-html';
import { LexQuery } from '@lanexio/parser-query';

const encoder = new TextEncoder();
const tree = parseHtml(encoder.encode('<ul><li>one</li><li>two</li></ul>'));

const resolver = (name: string) => (HtmlKind as Record<string, number | undefined>)[name];
const query = LexQuery.compile('Element', resolver);

for (const node of query.matches(tree)) {
  console.log(node.kind, node.range);
}

Changelog

Version	Date	Status	Notable changes
`1.0.0`	`2026-05-29`	Current	Initial stable release. Apache-2.0.

Migration notes

None.

Flat AST How the 16-byte node layout works and how to traverse it efficiently.

Parsing HTML Guide: parse HTML documents with full options and serialization.

HTML Conformance HTML test suite results and conformance status.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.