@localess/richtext 4.0.0-dev.20260905085556 → 4.0.0-dev.20260906124410

package/SKILL.md

@@ -122,3 +122,38 @@ export type {
 export { richTextFixtures }
 export type { RichTextFixture }
 ```
+
+## Parsing (`@localess/richtext/html-parser`, `/markdown-parser`)
+
+```ts
+import { parseHtmlToRichText } from '@localess/richtext/html-parser';
+import { parseMarkdownToRichText } from '@localess/richtext/markdown-parser';
+
+parseHtmlToRichText(html: string | null | undefined, options?: RichTextParseOptions): RichTextParseResult
+parseMarkdownToRichText(markdown: string | null | undefined, options?: RichTextParseOptions): RichTextParseResult
+```
+
+```ts
+interface RichTextParseOptions { unsupported?: 'unwrap' | 'skip' | 'throw' }  // default 'unwrap'
+interface RichTextParseResult {
+  doc: LocalessRichTextDocument;
+  unsupported: { element: string; action: 'unwrapped' | 'skipped'; count: number }[];
+}
+class RichTextParseError extends Error { element: string }
+```
+
+Both are **subset** parsers matched to the closed model — not HTML5-conformant, not CommonMark.
+HTML covers `p`, `h1`–`h6`, `ul`, `ol` (`start`), `li`, `pre`/`code` (`language-*`) and the marks
+`strong`/`b`, `em`/`i`, `s`/`strike`/`del`, `u`, `code`, `a`; `div`/`span` are transparent and
+`script`/`style` are always dropped. Markdown covers ATX and setext headings, paragraphs, bullet and
+ordered lists (nested, `start`), fenced and indented code blocks, `**bold**`, `*italic*`,
+`~~strike~~`, `` `code` ``, `[text](href)` and backslash escapes.
+
+Anything else goes through `unsupported` and is listed in the result — return the report to the
+caller, do not assume a clean parse. One warning per element type per parse, silent in production.
+
+Link hrefs pass the renderer's `sanitizeUrl` allowlist: `javascript:` and `data:` become `""`.
+
+Never throws except under `unsupported: 'throw'`; `null`, `undefined`, and `''` give an empty doc.
+
+`parseHtmlToRichText` is the exact inverse of `renderRichTextToHtml` over the whole supported model.

package/dist/html-parser/index.d.ts

@@ -0,0 +1,29 @@
+import { RichTextParseOptions, RichTextParseResult } from '../parse-common';
+export type { RichTextParseOptions, RichTextParseResult, RichTextUnsupportedPolicy, RichTextUnsupportedReport } from '../parse-common';
+export { RichTextParseError } from '../parse-common';
+/**
+ * Parses an HTML string into a Localess rich text document.
+ *
+ * The inverse of `renderRichTextToHtml`, and deliberately a **subset** parser:
+ * it understands the tags the Localess model can represent and routes
+ * everything else through {@link RichTextParseOptions.unsupported}. It is not
+ * HTML5-conformant and does not attempt full error recovery — the trade is
+ * identical behaviour across browsers, Node, and edge runtimes with no
+ * dependency.
+ *
+ * Supported: `p`, `h1`–`h6`, `ul`, `ol` (with `start`), `li`, `pre`/`code`
+ * blocks (with `language-*`), and the marks `strong`/`b`, `em`/`i`,
+ * `s`/`strike`/`del`, `u`, `code`, `a`. Structural wrappers such as `div` and
+ * `span` are transparent; `script` and `style` are always dropped.
+ *
+ * Link hrefs pass through the same allowlist the renderer applies, so
+ * `javascript:` and `data:` become `""`.
+ *
+ * Never throws for malformed input — except under `unsupported: 'throw'`.
+ *
+ * @example
+ * ```ts
+ * const { doc, unsupported } = parseHtmlToRichText('<p>Hello <strong>world</strong></p>');
+ * ```
+ */
+export declare function parseHtmlToRichText(html: string | null | undefined, options?: RichTextParseOptions): RichTextParseResult;

package/dist/html-parser/index.js

@@ -0,0 +1,491 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_parse_common = require("../parse-common-DEYhfKnK.js");
+//#region src/html-parser/to-model.ts
+/** Tag → mark, the inverse of `MARK_RENDER_MAP`. `b`/`i`/`del`/`s` are accepted as aliases. */
+var MARK_TAGS = {
+	strong: "bold",
+	b: "bold",
+	em: "italic",
+	i: "italic",
+	s: "strike",
+	strike: "strike",
+	del: "strike",
+	u: "underline",
+	code: "code",
+	a: "link"
+};
+var HEADING_TAGS = {
+	h1: 1,
+	h2: 2,
+	h3: 3,
+	h4: 4,
+	h5: 5,
+	h6: 6
+};
+/** Block tags the model represents directly. */
+var BLOCK_TAGS = /* @__PURE__ */ new Set([
+	"p",
+	"ul",
+	"ol",
+	"li",
+	"pre",
+	...Object.keys(HEADING_TAGS)
+]);
+/** Tags that carry no meaning of their own — their children are simply kept. */
+var TRANSPARENT_TAGS = /* @__PURE__ */ new Set([
+	"html",
+	"body",
+	"head",
+	"div",
+	"section",
+	"article",
+	"main",
+	"span",
+	"font",
+	"tbody",
+	"thead"
+]);
+/** Tags dropped entirely, content and all, regardless of policy. */
+var DROPPED_TAGS = /* @__PURE__ */ new Set([
+	"script",
+	"style",
+	"title",
+	"meta",
+	"link",
+	"base",
+	"noscript"
+]);
+function linkMark(attrs) {
+	return {
+		type: "link",
+		attrs: {
+			href: require_parse_common.sanitizeUrl(attrs.href ?? ""),
+			target: attrs.target ?? null,
+			rel: attrs.rel ?? null,
+			class: attrs.class ?? null
+		}
+	};
+}
+function codeBlockLanguage(attrs) {
+	const className = attrs.class ?? "";
+	const match = /(?:^|\s)language-([^\s]+)/.exec(className);
+	return match ? match[1] : null;
+}
+/** Collapses HTML whitespace the way a browser would for non-preformatted text. */
+function collapseWhitespace(text) {
+	return text.replace(/[\t\n\r ]+/g, " ");
+}
+function isBlockNode(node) {
+	return node.type !== "text";
+}
+/**
+* Folds a token stream into model nodes.
+*
+* Text is only kept where the model can hold it — inside a block node. Text
+* found at the top level is wrapped in a paragraph, matching what the editor
+* would produce.
+*/
+function tokensToNodes(tokens, tracker) {
+	const root = {
+		tag: "",
+		node: null,
+		children: [],
+		marks: [],
+		preformatted: false
+	};
+	const stack = [root];
+	const top = () => stack[stack.length - 1];
+	/** Blocks skipped wholesale; text inside them is discarded. */
+	let skipDepth = 0;
+	let skipTag = "";
+	const appendText = (text) => {
+		const frame = top();
+		if (text === "") return;
+		const node = {
+			type: "text",
+			text,
+			...frame.marks.length ? { marks: [...frame.marks] } : {}
+		};
+		if (frame === root) {
+			const last = root.children[root.children.length - 1];
+			if (last && last.type === "paragraph") (last.content ??= []).push(node);
+			else root.children.push({
+				type: "paragraph",
+				content: [node]
+			});
+			return;
+		}
+		frame.children.push(node);
+	};
+	const closeFrame = () => {
+		const frame = stack.pop();
+		const parent = top();
+		if (frame.node) {
+			if (frame.children.length) frame.node.content = frame.children;
+			parent.children.push(frame.node);
+		} else parent.children.push(...frame.children);
+	};
+	for (const token of tokens) {
+		if (skipDepth > 0) {
+			if (token.kind === "open" && token.name === skipTag && !token.selfClosing) skipDepth++;
+			else if (token.kind === "close" && token.name === skipTag) skipDepth--;
+			continue;
+		}
+		if (token.kind === "text") {
+			const frame = top();
+			const text = frame.preformatted ? token.text : collapseWhitespace(token.text);
+			if (!frame.preformatted && text.trim() === "" && (frame === root || frame.children.every(isBlockNode))) continue;
+			appendText(text);
+			continue;
+		}
+		if (token.kind === "close") {
+			const depth = stack.findIndex((frame) => frame.tag === token.name);
+			if (depth <= 0) continue;
+			while (stack.length > depth) closeFrame();
+			continue;
+		}
+		const { name, attrs, selfClosing } = token;
+		if (DROPPED_TAGS.has(name)) {
+			if (!selfClosing) {
+				skipDepth = 1;
+				skipTag = name;
+			}
+			continue;
+		}
+		if (name === "br") {
+			appendText(" ");
+			continue;
+		}
+		const markType = MARK_TAGS[name];
+		if (markType) {
+			const frame = top();
+			if (name === "code" && frame.tag === "pre" && frame.node?.type === "codeBlock") {
+				const language = codeBlockLanguage(attrs);
+				if (language) frame.node.attrs = { language };
+				if (selfClosing) continue;
+				stack.push({
+					tag: name,
+					node: null,
+					children: [],
+					marks: [...frame.marks],
+					preformatted: true
+				});
+				continue;
+			}
+			const mark = markType === "link" ? linkMark(attrs) : { type: markType };
+			if (selfClosing) continue;
+			stack.push({
+				tag: name,
+				node: null,
+				children: [],
+				marks: [...frame.marks, mark],
+				preformatted: frame.preformatted
+			});
+			continue;
+		}
+		if (TRANSPARENT_TAGS.has(name)) {
+			if (selfClosing) continue;
+			const frame = top();
+			stack.push({
+				tag: name,
+				node: null,
+				children: [],
+				marks: [...frame.marks],
+				preformatted: frame.preformatted
+			});
+			continue;
+		}
+		if (BLOCK_TAGS.has(name)) {
+			const frame = top();
+			let node;
+			let preformatted = frame.preformatted;
+			if (name === "p") node = { type: "paragraph" };
+			else if (name in HEADING_TAGS) node = {
+				type: "heading",
+				attrs: { level: HEADING_TAGS[name] }
+			};
+			else if (name === "ul") node = { type: "bulletList" };
+			else if (name === "ol") {
+				const start = Number.parseInt(attrs.start ?? "", 10);
+				node = Number.isFinite(start) && start !== 1 ? {
+					type: "orderedList",
+					attrs: { start }
+				} : { type: "orderedList" };
+			} else if (name === "li") node = { type: "listItem" };
+			else {
+				node = { type: "codeBlock" };
+				preformatted = true;
+			}
+			if (selfClosing) {
+				frame.children.push(node);
+				continue;
+			}
+			stack.push({
+				tag: name,
+				node,
+				children: [],
+				marks: [...frame.marks],
+				preformatted
+			});
+			continue;
+		}
+		const action = tracker.record(name);
+		if (selfClosing) continue;
+		if (action === "skip") {
+			skipDepth = 1;
+			skipTag = name;
+			continue;
+		}
+		const frame = top();
+		stack.push({
+			tag: name,
+			node: null,
+			children: [],
+			marks: [...frame.marks],
+			preformatted: frame.preformatted
+		});
+	}
+	while (stack.length > 1) closeFrame();
+	return finalize(root.children);
+}
+/**
+* Post-pass matching the model's shape rules:
+* `<pre>` wraps a `<code>` in the renderer, so the parser lifts that `code`
+* mark back onto the `codeBlock`'s `language`, and list items always hold
+* blocks rather than bare text.
+*/
+function finalize(nodes) {
+	return nodes.map((node) => {
+		if (node.type === "text") return node;
+		const content = node.content;
+		if (!content) return node;
+		if (node.type === "codeBlock") {
+			const text = flattenText(content);
+			const next = {
+				type: "codeBlock",
+				...node.attrs ? { attrs: node.attrs } : {}
+			};
+			if (text !== "") next.content = [{
+				type: "text",
+				text
+			}];
+			return next;
+		}
+		const finalized = finalize(content);
+		if (node.type === "listItem" && finalized.some((child) => child.type === "text")) {
+			const wrapped = [];
+			let run = [];
+			for (const child of finalized) if (child.type === "text") run.push(child);
+			else {
+				if (run.length) {
+					wrapped.push({
+						type: "paragraph",
+						content: run
+					});
+					run = [];
+				}
+				wrapped.push(child);
+			}
+			if (run.length) wrapped.push({
+				type: "paragraph",
+				content: run
+			});
+			return {
+				...node,
+				content: wrapped
+			};
+		}
+		return {
+			...node,
+			content: finalized
+		};
+	});
+}
+function flattenText(nodes) {
+	let out = "";
+	for (const node of nodes) if (node.type === "text") out += node.text;
+	else out += flattenText(node.content ?? []);
+	return out;
+}
+//#endregion
+//#region src/html-parser/tokenizer.ts
+/** Elements that never have a closing tag. */
+var VOID_ELEMENTS = /* @__PURE__ */ new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"param",
+	"source",
+	"track",
+	"wbr"
+]);
+/** Elements whose content is raw text, not markup. */
+var RAW_TEXT_ELEMENTS = /* @__PURE__ */ new Set(["script", "style"]);
+var NAMED_ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: "\xA0"
+};
+/**
+* Decodes the named and numeric character references the renderer can emit,
+* plus the few that appear in hand-written HTML. Unknown references are left
+* verbatim rather than dropped, so no text is silently lost.
+*/
+function decodeEntities(text) {
+	if (!text.includes("&")) return text;
+	return text.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (match, body) => {
+		if (body[0] === "#") {
+			const codePoint = body[1] === "x" || body[1] === "X" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+			if (!Number.isFinite(codePoint) || codePoint < 0 || codePoint > 1114111) return match;
+			try {
+				return String.fromCodePoint(codePoint);
+			} catch {
+				return match;
+			}
+		}
+		return NAMED_ENTITIES[body.toLowerCase()] ?? match;
+	});
+}
+function parseAttributes(source) {
+	const attrs = {};
+	const pattern = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+	let match;
+	while ((match = pattern.exec(source)) !== null) {
+		const name = match[1].toLowerCase();
+		const value = match[2] ?? match[3] ?? match[4] ?? "";
+		if (!(name in attrs)) attrs[name] = decodeEntities(value);
+	}
+	return attrs;
+}
+/**
+* Tokenizes HTML into a flat token stream.
+*
+* A deliberate **subset** tokenizer, not an HTML5-conformant one: it handles
+* the tags the Localess model can represent, treats everything else as a
+* generic element for the caller's unsupported policy, and performs no error
+* recovery beyond never throwing. Chosen over branching on `DOMParser` so the
+* result is identical in browsers, Node, and edge runtimes, and so the package
+* keeps its zero-dependency guarantee.
+*
+* A stray `<` that does not begin a valid tag is emitted as text.
+*/
+function tokenizeHtml(html) {
+	const tokens = [];
+	let index = 0;
+	let pendingText = "";
+	const flushText = () => {
+		if (pendingText === "") return;
+		tokens.push({
+			kind: "text",
+			text: decodeEntities(pendingText)
+		});
+		pendingText = "";
+	};
+	while (index < html.length) {
+		const next = html.indexOf("<", index);
+		if (next === -1) {
+			pendingText += html.slice(index);
+			break;
+		}
+		pendingText += html.slice(index, next);
+		const rest = html.slice(next);
+		if (rest.startsWith("<!--")) {
+			const end = html.indexOf("-->", next + 4);
+			index = end === -1 ? html.length : end + 3;
+			continue;
+		}
+		if (rest.startsWith("<!") || rest.startsWith("<?")) {
+			const end = html.indexOf(">", next + 1);
+			index = end === -1 ? html.length : end + 1;
+			continue;
+		}
+		const closeMatch = /^<\/\s*([a-zA-Z][^\s>]*)\s*>/.exec(rest);
+		if (closeMatch) {
+			flushText();
+			tokens.push({
+				kind: "close",
+				name: closeMatch[1].toLowerCase()
+			});
+			index = next + closeMatch[0].length;
+			continue;
+		}
+		const openMatch = /^<([a-zA-Z][^\s/>]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/.exec(rest);
+		if (openMatch) {
+			flushText();
+			const name = openMatch[1].toLowerCase();
+			const raw = openMatch[2] ?? "";
+			const selfClosing = /\/\s*$/.test(raw) || VOID_ELEMENTS.has(name);
+			tokens.push({
+				kind: "open",
+				name,
+				attrs: parseAttributes(raw),
+				selfClosing
+			});
+			index = next + openMatch[0].length;
+			if (RAW_TEXT_ELEMENTS.has(name) && !selfClosing) {
+				const closeTag = `</${name}`;
+				const end = html.toLowerCase().indexOf(closeTag, index);
+				index = end === -1 ? html.length : end;
+			}
+			continue;
+		}
+		pendingText += "<";
+		index = next + 1;
+	}
+	flushText();
+	return tokens;
+}
+//#endregion
+//#region src/html-parser/index.ts
+/**
+* Parses an HTML string into a Localess rich text document.
+*
+* The inverse of `renderRichTextToHtml`, and deliberately a **subset** parser:
+* it understands the tags the Localess model can represent and routes
+* everything else through {@link RichTextParseOptions.unsupported}. It is not
+* HTML5-conformant and does not attempt full error recovery — the trade is
+* identical behaviour across browsers, Node, and edge runtimes with no
+* dependency.
+*
+* Supported: `p`, `h1`–`h6`, `ul`, `ol` (with `start`), `li`, `pre`/`code`
+* blocks (with `language-*`), and the marks `strong`/`b`, `em`/`i`,
+* `s`/`strike`/`del`, `u`, `code`, `a`. Structural wrappers such as `div` and
+* `span` are transparent; `script` and `style` are always dropped.
+*
+* Link hrefs pass through the same allowlist the renderer applies, so
+* `javascript:` and `data:` become `""`.
+*
+* Never throws for malformed input — except under `unsupported: 'throw'`.
+*
+* @example
+* ```ts
+* const { doc, unsupported } = parseHtmlToRichText('<p>Hello <strong>world</strong></p>');
+* ```
+*/
+function parseHtmlToRichText(html, options = {}) {
+	const tracker = new require_parse_common.UnsupportedTracker(options);
+	if (typeof html !== "string" || html === "") return {
+		doc: require_parse_common.emptyDocument(),
+		unsupported: []
+	};
+	return {
+		doc: {
+			type: "doc",
+			content: tokensToNodes(tokenizeHtml(html), tracker)
+		},
+		unsupported: tracker.report()
+	};
+}
+//#endregion
+exports.RichTextParseError = require_parse_common.RichTextParseError;
+exports.parseHtmlToRichText = parseHtmlToRichText;