@rtif-sdk/formats 3.0.0

package/README.md

@@ -0,0 +1,111 @@
+# @rtif-sdk/formats
+
+Format codecs for RTIF documents. Three subpath exports, each returning a
+`FormatCodec` (from `@rtif-sdk/core`): `serialize(doc) → string` and
+`parse(input) → Document`, where `parse` **never throws** and always returns a
+valid normalized document.
+
+```bash
+npm install @rtif-sdk/formats @rtif-sdk/core
+```
+
+```ts
+import { createHtmlCodec } from '@rtif-sdk/formats/html';
+import { createMarkdownCodec } from '@rtif-sdk/formats/markdown';
+import { createPlaintextCodec } from '@rtif-sdk/formats/plaintext';
+```
+
+There is no root export — import the codec you need.
+
+## HTML
+
+```ts
+const html = createHtmlCodec();
+html.serialize(doc);   // '<p>Hello <strong>world</strong></p>'
+html.parse(clipboard); // Document
+```
+
+**DOM-free and SSR-safe.** Parsing uses a hand-rolled tokenizer with zero DOM
+dependency — the codec behaves identically in Node, workers, and browsers, so
+you can parse untrusted HTML server-side.
+
+**Sanitization guarantees** (applied during parse):
+
+- Protocol allowlist — `http:`, `https:`, `mailto:`, and relative URLs — on
+  *every* URL-bearing attribute: `href` **and** `src`. Anything else
+  (`javascript:`, `data:`, `vbscript:`, …) is dropped.
+- `<script>`, `<style>`, `<iframe>`, `<object>`, `<embed>` subtrees stripped.
+- All `on*` event-handler attributes removed.
+
+Default rules cover the canonical types: `p`/`div`, `h1`–`h6`, `blockquote`,
+`pre > code` (with `language-*` class), `li` (one `list` block per item),
+`hr`, and the marks `strong`/`b`, `em`/`i`, `u`, `s`/`strike`/`del`, `code`,
+`a[href]`.
+
+Extend per name with `HtmlRules` — this is how custom features join the
+clipboard story:
+
+```ts
+const html = createHtmlCodec({
+  rules: {
+    marks: {
+      highlight: { tag: 'mark', parse: { tags: ['mark'] } },
+    },
+    blocks: {
+      callout: {
+        serialize: (block, inner) => `<aside class="callout">${inner}</aside>`,
+        parse: { tags: ['aside'] },
+      },
+    },
+  },
+});
+```
+
+`HtmlMarkRule`: `{ tag, attrs?(value), parse?: { tags, getValue?(attrs) } }`.
+`HtmlBlockRule`: `{ serialize(block, inner), parse?: { tags, getAttrs?(attrs, tag) } }`.
+User rules merge over the defaults per name. Structural tags (`ul`/`ol`/`li`,
+`blockquote`, `pre`, `br`, `hr`) are handled by the parser itself and cannot be
+remapped. Pass the codec to the editor via `createEditor({ codecs: { html } })`.
+
+## Markdown
+
+```ts
+const md = createMarkdownCodec();
+md.serialize(doc);  // '# Title\n\nHello **world**'
+md.parse(source);   // Document
+```
+
+A pragmatic CommonMark subset matching the canonical types:
+
+| RTIF | Markdown |
+|---|---|
+| `heading` (level 1–6) | `#`–`######` |
+| `blockquote` | `> ` (consecutive `>` lines merge into one block) |
+| `code_block` | fenced ``` (fence sized past inner backticks; `attrs.language` on the fence) |
+| `list` bulleted / ordered | `- ` / `1.` `2.` … (numbered per consecutive group) |
+| `horizontal_rule` | `---` |
+| `bold` / `italic` / `strikethrough` / `code` | `**` / `*` / `~~` / backticks |
+| `link` | `[text](href)` — destinations pass the same protocol allowlist |
+
+Known limits: **underline has no markdown form** and serializes as plain text;
+block ids are not preserved across a round trip; single-level only (no nested
+lists or quotes); no reference links, titles, or autolinks. Unparseable
+constructs degrade to literal text.
+
+## Plaintext
+
+```ts
+const txt = createPlaintextCodec();
+txt.serialize(doc);   // blocks joined by '\n'; marks and structure discarded
+txt.parse('a\nb');    // one paragraph per line; '' → one empty paragraph
+```
+
+Handles LF, CRLF, and lone CR on parse. That's the whole format.
+
+## Notes
+
+- Parsers generate fresh block ids (`b1`, `b2`, … per call). Use
+  `assertDocEqual` from `@rtif-sdk/test-kit` (ids ignored by default) when testing
+  round trips.
+- A custom codec is just an object satisfying `FormatCodec` — nothing here is
+  special-cased by the editor.

package/dist/html/codec.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The HTML codec factory. Serialization is pure string building; parsing
+ * uses a hand-rolled tokenizer with zero DOM dependency, so the codec is
+ * SSR-safe and behaves identically in Node, workers, and browsers.
+ */
+import type { FormatCodec } from '@rtif-sdk/core';
+import type { HtmlRules } from './rules.js';
+/** Options for {@link createHtmlCodec}. */
+export interface HtmlCodecOptions {
+    /** Extra mark/block rules, merged over the canonical defaults per name. */
+    readonly rules?: HtmlRules;
+}
+/**
+ * Create an HTML codec.
+ *
+ * Parsing sanitizes aggressively: protocol allowlist (`http:`, `https:`,
+ * `mailto:`, relative) on every `href`/`src`; `<script>`/`<style>`/`<iframe>`/
+ * `<object>`/`<embed>` subtrees stripped; all `on*` attributes dropped.
+ * It never throws and always returns a valid normalized document.
+ */
+export declare function createHtmlCodec(options?: HtmlCodecOptions): FormatCodec;
+//# sourceMappingURL=codec.d.ts.map

package/dist/html/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/html/codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,WAAW,CAOvE"}

package/dist/html/codec.js

@@ -0,0 +1,25 @@
+/**
+ * The HTML codec factory. Serialization is pure string building; parsing
+ * uses a hand-rolled tokenizer with zero DOM dependency, so the codec is
+ * SSR-safe and behaves identically in Node, workers, and browsers.
+ */
+import { parseHtml } from './parse.js';
+import { resolveRules } from './rules.js';
+import { serializeHtml } from './serialize.js';
+/**
+ * Create an HTML codec.
+ *
+ * Parsing sanitizes aggressively: protocol allowlist (`http:`, `https:`,
+ * `mailto:`, relative) on every `href`/`src`; `<script>`/`<style>`/`<iframe>`/
+ * `<object>`/`<embed>` subtrees stripped; all `on*` attributes dropped.
+ * It never throws and always returns a valid normalized document.
+ */
+export function createHtmlCodec(options) {
+    const rules = resolveRules(options?.rules);
+    return {
+        format: 'html',
+        serialize: (doc) => serializeHtml(doc, rules),
+        parse: (input) => parseHtml(input, rules),
+    };
+}
+//# sourceMappingURL=codec.js.map

package/dist/html/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/html/codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAQ/C;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3C,OAAO;QACL,MAAM,EAAE,MAAM;QACd,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC;QAC7C,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC;KAC1C,CAAC;AACJ,CAAC"}

package/dist/html/entities.d.ts

@@ -0,0 +1,14 @@
+/**
+ * HTML entity decoding and text/attribute escaping. Pure string functions —
+ * no DOM, so the codec is SSR-safe.
+ */
+/**
+ * Decode named and numeric (decimal and hex) character references.
+ * Unknown references pass through literally — never throws.
+ */
+export declare function decodeEntities(text: string): string;
+/** Escape text content for HTML output (`&`, `<`, `>`). */
+export declare function escapeText(text: string): string;
+/** Escape an attribute value for quoted HTML output (`&`, `<`, `>`, `"`, `'`). */
+export declare function escapeAttr(value: string): string;
+//# sourceMappingURL=entities.d.ts.map

package/dist/html/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/html/entities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+CH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD;AAcD,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/html/entities.js

@@ -0,0 +1,80 @@
+/**
+ * HTML entity decoding and text/attribute escaping. Pure string functions —
+ * no DOM, so the codec is SSR-safe.
+ */
+/** Practical subset of named entities seen in real-world pasted HTML. */
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: '\u00a0',
+    copy: '©',
+    reg: '®',
+    trade: '™',
+    deg: '°',
+    plusmn: '±',
+    middot: '·',
+    bull: '•',
+    hellip: '…',
+    ndash: '–',
+    mdash: '—',
+    lsquo: '‘',
+    rsquo: '’',
+    ldquo: '“',
+    rdquo: '”',
+    laquo: '«',
+    raquo: '»',
+    sect: '§',
+    para: '¶',
+    times: '×',
+    divide: '÷',
+    cent: '¢',
+    pound: '£',
+    yen: '¥',
+    euro: '€',
+};
+const ENTITY_PATTERN = /&(#[0-9]+|#[xX][0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g;
+/** Decode one numeric entity body (`#65` or `#x1F600`); invalid code points become U+FFFD. */
+const decodeNumeric = (body) => {
+    const hex = body[1] === 'x' || body[1] === 'X';
+    const codePoint = Number.parseInt(body.slice(hex ? 2 : 1), hex ? 16 : 10);
+    if (Number.isNaN(codePoint) || codePoint <= 0 || codePoint > 0x10ffff)
+        return '\ufffd';
+    if (codePoint >= 0xd800 && codePoint <= 0xdfff)
+        return '\ufffd'; // lone surrogate
+    return String.fromCodePoint(codePoint); // handles astral-plane code points
+};
+/**
+ * Decode named and numeric (decimal and hex) character references.
+ * Unknown references pass through literally — never throws.
+ */
+export function decodeEntities(text) {
+    if (!text.includes('&'))
+        return text;
+    return text.replace(ENTITY_PATTERN, (full, body) => {
+        if (body.startsWith('#'))
+            return decodeNumeric(body);
+        return NAMED_ENTITIES[body] ?? NAMED_ENTITIES[body.toLowerCase()] ?? full;
+    });
+}
+const TEXT_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+};
+const ATTR_ESCAPES = {
+    ...TEXT_ESCAPES,
+    '"': '&quot;',
+    "'": '&#39;',
+};
+/** Escape text content for HTML output (`&`, `<`, `>`). */
+export function escapeText(text) {
+    return text.replace(/[&<>]/g, (ch) => TEXT_ESCAPES[ch]);
+}
+/** Escape an attribute value for quoted HTML output (`&`, `<`, `>`, `"`, `'`). */
+export function escapeAttr(value) {
+    return value.replace(/[&<>"']/g, (ch) => ATTR_ESCAPES[ch]);
+}
+//# sourceMappingURL=entities.js.map

package/dist/html/entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../src/html/entities.ts"],"names":[],"mappings":"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"}

package/dist/html/index.d.ts

@@ -0,0 +1,5 @@
+/** @rtif-sdk/formats/html — DOM-free, SSR-safe HTML codec with sanitization. */
+export { createHtmlCodec } from './codec.js';
+export type { HtmlCodecOptions } from './codec.js';
+export type { HtmlBlockRule, HtmlMarkRule, HtmlRules } from './rules.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/html/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/html/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/html/index.js

@@ -0,0 +1,3 @@
+/** @rtif-sdk/formats/html — DOM-free, SSR-safe HTML codec with sanitization. */
+export { createHtmlCodec } from './codec.js';
+//# sourceMappingURL=index.js.map

package/dist/html/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/html/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/html/parse-tree.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hand-rolled HTML tokenizer and tree builder — zero DOM dependency, so the
+ * codec runs identically in browsers, Node, workers, and SSR. It covers the
+ * practical subset rich-text paste needs: tags with every attribute-quoting
+ * variant, entity decoding, void elements, comments/doctype, unclosed tags,
+ * and mismatched close tags (matched by name against the open-element stack).
+ *
+ * Sanitization starts here:
+ * - `<script>`/`<style>`/`<iframe>` and other raw-text containers are
+ *   skipped together with their entire content.
+ * - `on*` event-handler attributes are dropped.
+ * - `href`/`src` values failing the protocol allowlist are removed.
+ *
+ * Known limitation: attribute values containing a literal `>` require quotes
+ * (the tag scanner honors quotes, so quoted values are handled correctly).
+ */
+/** An element in the parsed tree; attribute names are lowercased, values entity-decoded. */
+export interface HtmlElementNode {
+    readonly kind: 'element';
+    readonly tag: string;
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly children: readonly HtmlNode[];
+}
+/** A text node; entities are already decoded. */
+export interface HtmlTextNode {
+    readonly kind: 'text';
+    readonly text: string;
+}
+/** A node in the parsed HTML tree. */
+export type HtmlNode = HtmlElementNode | HtmlTextNode;
+/** Parse an HTML string into a tree of nodes. Total: never throws. */
+export declare function parseHtmlTree(html: string): readonly HtmlNode[];
+//# sourceMappingURL=parse-tree.d.ts.map

package/dist/html/parse-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-tree.d.ts","sourceRoot":"","sources":["../../src/html/parse-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,4FAA4F;AAC5F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAC;CACxC;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,sCAAsC;AACtC,MAAM,MAAM,QAAQ,GAAG,eAAe,GAAG,YAAY,CAAC;AAuCtD,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE,CAyB/D"}

package/dist/html/parse-tree.js

@@ -0,0 +1,191 @@
+/**
+ * Hand-rolled HTML tokenizer and tree builder — zero DOM dependency, so the
+ * codec runs identically in browsers, Node, workers, and SSR. It covers the
+ * practical subset rich-text paste needs: tags with every attribute-quoting
+ * variant, entity decoding, void elements, comments/doctype, unclosed tags,
+ * and mismatched close tags (matched by name against the open-element stack).
+ *
+ * Sanitization starts here:
+ * - `<script>`/`<style>`/`<iframe>` and other raw-text containers are
+ *   skipped together with their entire content.
+ * - `on*` event-handler attributes are dropped.
+ * - `href`/`src` values failing the protocol allowlist are removed.
+ *
+ * Known limitation: attribute values containing a literal `>` require quotes
+ * (the tag scanner honors quotes, so quoted values are handled correctly).
+ */
+import { sanitizeUrl } from '../shared/url.js';
+import { decodeEntities } from './entities.js';
+const VOID_TAGS = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
+]);
+/** Tags whose content is raw text we never want — skipped to the matching close tag. */
+const RAW_SKIP_TAGS = new Set([
+    'script',
+    'style',
+    'iframe',
+    'noscript',
+    'textarea',
+    'title',
+]);
+const URL_ATTRS = new Set(['href', 'src']);
+/** name, ="double", ='single', or =bare — in that alternation order. */
+const ATTR_PATTERN = /([^\s=/>"']+)\s*(?:=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]*)))?/g;
+/** Parse an HTML string into a tree of nodes. Total: never throws. */
+export function parseHtmlTree(html) {
+    const root = [];
+    const stack = [{ tag: '', children: root }];
+    let i = 0;
+    while (i < html.length) {
+        if (html[i] !== '<') {
+            const next = html.indexOf('<', i);
+            const end = next === -1 ? html.length : next;
+            pushText(stack, html.slice(i, end));
+            i = end;
+            continue;
+        }
+        const after = html[i + 1];
+        if (after === '!' || after === '?') {
+            i = skipDeclaration(html, i);
+        }
+        else if (after === '/') {
+            i = closeTag(html, i, stack);
+        }
+        else if (after === undefined || !/[a-zA-Z]/.test(after)) {
+            pushText(stack, '<'); // a lone '<' is text, e.g. "a < b"
+            i++;
+        }
+        else {
+            i = openTag(html, i, stack);
+        }
+    }
+    return root;
+}
+/** Append decoded text, merging with a preceding text node. */
+const pushText = (stack, raw) => {
+    if (raw === '')
+        return;
+    const text = decodeEntities(raw);
+    const children = stack[stack.length - 1].children;
+    const last = children[children.length - 1];
+    if (last !== undefined && last.kind === 'text') {
+        children[children.length - 1] = { kind: 'text', text: last.text + text };
+    }
+    else {
+        children.push({ kind: 'text', text });
+    }
+};
+/** Skip `<!-- comments -->`, `<!doctype>`, and `<? ... >`. */
+const skipDeclaration = (html, i) => {
+    if (html.startsWith('<!--', i)) {
+        const end = html.indexOf('-->', i + 4);
+        return end === -1 ? html.length : end + 3;
+    }
+    const end = html.indexOf('>', i);
+    return end === -1 ? html.length : end + 1;
+};
+/** Handle `</tag>`: pop the stack to the named element; ignore when unmatched. */
+const closeTag = (html, i, stack) => {
+    const end = html.indexOf('>', i);
+    if (end === -1)
+        return html.length;
+    const name = /[a-zA-Z][a-zA-Z0-9-]*/.exec(html.slice(i + 2, end))?.[0]?.toLowerCase();
+    if (name !== undefined) {
+        for (let frame = stack.length - 1; frame >= 1; frame--) {
+            if (stack[frame].tag === name) {
+                stack.length = frame; // pop the element and everything left open inside it
+                break;
+            }
+        }
+    }
+    return end + 1;
+};
+/** Find the index of the `>` ending the tag that starts at `from`, honoring quoted values. */
+const scanTagEnd = (html, from) => {
+    let quote = null;
+    for (let j = from; j < html.length; j++) {
+        const ch = html[j];
+        if (quote !== null) {
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === '>') {
+            return j;
+        }
+    }
+    return -1;
+};
+/** Parse an opening tag, push the element, and descend unless void/self-closing. */
+const openTag = (html, i, stack) => {
+    const tagEnd = scanTagEnd(html, i + 1);
+    if (tagEnd === -1) {
+        pushText(stack, html.slice(i)); // malformed trailing tag — keep as text
+        return html.length;
+    }
+    const content = html.slice(i + 1, tagEnd);
+    const selfClosing = content.endsWith('/');
+    const body = selfClosing ? content.slice(0, -1) : content;
+    const nameMatch = /^[a-zA-Z][a-zA-Z0-9-]*/.exec(body);
+    if (nameMatch === null)
+        return tagEnd + 1;
+    const tag = nameMatch[0].toLowerCase();
+    if (RAW_SKIP_TAGS.has(tag))
+        return skipRawContent(html, tagEnd + 1, tag);
+    const children = [];
+    const element = {
+        kind: 'element',
+        tag,
+        attrs: parseAttrs(body.slice(nameMatch[0].length)),
+        children,
+    };
+    stack[stack.length - 1].children.push(element);
+    if (!selfClosing && !VOID_TAGS.has(tag))
+        stack.push({ tag, children });
+    return tagEnd + 1;
+};
+/** Skip everything up to and including `</tag>` (case-insensitive); to EOF when unclosed. */
+const skipRawContent = (html, from, tag) => {
+    const close = html.toLowerCase().indexOf(`</${tag}`, from);
+    if (close === -1)
+        return html.length;
+    const end = html.indexOf('>', close);
+    return end === -1 ? html.length : end + 1;
+};
+/** Parse attributes, dropping `on*` handlers and disallowed `href`/`src` URLs. */
+const parseAttrs = (raw) => {
+    const attrs = {};
+    ATTR_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = ATTR_PATTERN.exec(raw)) !== null) {
+        const name = match[1].toLowerCase();
+        const value = decodeEntities(match[2] ?? match[3] ?? match[4] ?? '');
+        if (name.startsWith('on'))
+            continue; // event handlers never survive
+        if (URL_ATTRS.has(name)) {
+            const safe = sanitizeUrl(value);
+            if (safe !== null && !(name in attrs))
+                attrs[name] = safe;
+            continue;
+        }
+        if (!(name in attrs))
+            attrs[name] = value;
+    }
+    return attrs;
+};
+//# sourceMappingURL=parse-tree.js.map

package/dist/html/parse-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-tree.js","sourceRoot":"","sources":["../../src/html/parse-tree.ts"],"names":[],"mappings":"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"}

package/dist/html/parse.d.ts

@@ -0,0 +1,28 @@
+/**
+ * HTML → Document. Walks the sanitized tree from parse-tree.ts and
+ * accumulates normalized blocks. Best-effort: never throws, always returns
+ * a valid document with ≥ 1 block. No DOM dependency — SSR-safe.
+ *
+ * Documented behavior:
+ * - `<br>` ends the current block and starts a new one of the *same* type
+ *   (so `<p>a<br>b</p>` yields two paragraphs; `<br><br>` keeps the empty
+ *   block between them).
+ * - Nested `<ul>`/`<ol>` flatten to consecutive `list` blocks; nesting depth
+ *   is recorded as `attrs.indent` (absent at the top level). `indent` is
+ *   parse-only metadata — serialization ignores it.
+ * - Unknown elements are transparent (children are parsed in place); loose
+ *   text at block level becomes a paragraph.
+ * - Inside `<blockquote>` and `<li>`, paragraph-ish children adopt the
+ *   container's block type: `<blockquote><p>a</p><p>b</p></blockquote>`
+ *   yields two blockquote blocks.
+ * - Whitespace collapses per HTML semantics except inside `<pre>`;
+ *   block-edge whitespace is trimmed; whitespace-only text between blocks
+ *   is dropped. `&nbsp;` (U+00A0) never collapses.
+ * - Styles are ignored: Google-Docs-style `<b style="font-weight:normal">`
+ *   parses as bold.
+ */
+import type { Document } from '@rtif-sdk/core';
+import type { ResolvedHtmlRules } from './rules.js';
+/** Parse an HTML string into a valid normalized document. Never throws. */
+export declare function parseHtml(input: string, rules: ResolvedHtmlRules): Document;
+//# sourceMappingURL=parse.d.ts.map

package/dist/html/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/html/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAgB,QAAQ,EAAe,MAAM,gBAAgB,CAAC;AAK1E,OAAO,KAAK,EAA+B,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAyRjF,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,QAAQ,CAuB3E"}