@one-agent/html 0.0.1-beta.2

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,102 @@
+# @one-agent/html
+
+Streaming HTML → ANSI terminal renderer for ONE agent output.
+
+Parses an HTML stream chunk-by-chunk and emits styled, word-wrapped ANSI text suitable for direct terminal output. Used internally by the `one repl` HTML REPL and available as a standalone library.
+
+## Install
+
+```bash
+npm install @one-agent/html
+# or
+pnpm add @one-agent/html
+```
+
+## Quick start
+
+```typescript
+import { StreamingHtmlRenderer, initSyntaxHighlighting } from "@one-agent/html";
+
+// Optional: pre-warm the syntax highlighter (avoids first-call latency)
+await initSyntaxHighlighting();
+
+const renderer = new StreamingHtmlRenderer({
+  columns: process.stdout.columns ?? 80,
+  onFlush: (text) => {
+    process.stdout.write(text + "\n");
+  },
+});
+
+// Feed chunks as they arrive from the LLM stream
+for await (const chunk of htmlStream) {
+  renderer.write(chunk);
+}
+renderer.end();
+```
+
+## API
+
+### `new StreamingHtmlRenderer(options)`
+
+Creates a new renderer instance.
+
+```typescript
+interface HtmlRendererOptions {
+  /** Terminal column width for word-wrapping. Default: 80. */
+  columns?: number;
+
+  /**
+   * Called when a complete block (paragraph, heading, code block, …) is ready.
+   * If omitted, collect output with flush() instead.
+   */
+  onFlush?: (text: string) => void;
+
+  /**
+   * Called after each chunk with the current in-progress partial line.
+   * Use to rewrite the last line: process.stdout.write('\r\x1b[K' + partial)
+   */
+  onPartial?: (partial: string) => void;
+}
+```
+
+#### `renderer.write(chunk: string)`
+
+Feed a new chunk of HTML. Safe to call with partial tags across chunk boundaries.
+
+#### `renderer.end()`
+
+Signal end-of-stream. Flushes any buffered content.
+
+#### `renderer.flush(): string`
+
+Returns all buffered output as a single string (when no `onFlush` callback is set).
+
+### `initSyntaxHighlighting(): Promise<void>`
+
+Pre-warms the [Shiki](https://shiki.style/) syntax highlighter. Call once at startup to avoid latency on the first code block. Safe to call multiple times (no-op after first load).
+
+### `highlightCode(code: string, lang: string): string`
+
+Highlight a code string synchronously and return ANSI-colored text. Returns the original string if the highlighter is not yet initialised or the language is unsupported.
+
+## Supported HTML elements
+
+| Element | Rendering |
+|---------|-----------|
+| `<p>` | Word-wrapped paragraph |
+| `<h1>`–`<h6>` | Bold + colored headings with `#` prefix |
+| `<pre><code>` | Syntax-highlighted code block with line numbers |
+| `<code>` (inline) | Dimmed monospace |
+| `<strong>`, `<b>` | Bold |
+| `<em>`, `<i>` | Italic |
+| `<s>`, `<del>` | Strikethrough |
+| `<blockquote>` | Indented with `▌` gutter |
+| `<ul>`, `<ol>` | Nested lists with `•` / numbered bullets |
+| `<li>` | List item |
+| `<hr>` | Horizontal rule |
+| `<br>` | Line break |
+| `<a>` | Underlined text (href shown if different from text) |
+
+## License
+
+Apache-2.0 — see `LICENSE` and `NOTICE` at the repository root.

package/dist/index.d.mts

@@ -0,0 +1,81 @@
+//#region src/renderer.d.ts
+interface HtmlRendererOptions {
+  /**
+   * Terminal column width for word-wrapping. Default: 80.
+   */
+  columns?: number;
+  /**
+   * Callback fired when a complete, stable line (or block) is ready.
+   * In streaming mode the host calls this to write to stdout.
+   * If omitted, output is collected and returned by `flush()`.
+   */
+  onFlush?: (text: string) => void;
+  /**
+   * Callback fired after each chunk with the current "in-progress" partial line
+   * that hasn't been finalised yet. Host can use this to rewrite the last line
+   * with `process.stdout.write('\r\x1b[K' + partial)`.
+   */
+  onPartial?: (partial: string) => void;
+}
+declare class StreamingHtmlRenderer {
+  private readonly opts;
+  private parser;
+  /** Output collected when no onFlush provided. */
+  private collected;
+  /** Stack of open block contexts. Innermost block = last element. */
+  private blockStack;
+  /** Stack of list contexts for bullet/number generation. */
+  private listStack;
+  /** Current inline chalk chain (accumulated from open inline tags). */
+  private inlineChain;
+  /** Stack of chalk chains — restored on close tag. */
+  private inlineStack;
+  /** Inside <pre>: true — disables word-wrap, preserves whitespace. */
+  private inPre;
+  /** Table cell buffer: row → cells. */
+  private tableRows;
+  private currentRow;
+  private currentCell;
+  private inTableCell;
+  /** Whether we're inside a <blockquote> (may be nested). */
+  private blockquoteDepth;
+  /**
+   * Buffer for top-level text nodes (text that arrives outside any block tag).
+   * Instead of flushing each streaming chunk immediately (which creates one
+   * line per word/character), we accumulate here and flush at the next block
+   * boundary or on end().
+   */
+  private topLevelBuffer;
+  constructor(opts?: HtmlRendererOptions);
+  /** Feed a chunk of HTML (may be partial/incomplete). */
+  write(chunk: string): void;
+  /** Finalise: flush any remaining partial content and reset state. */
+  end(): void;
+  /** Return all collected output (only useful when no onFlush provided). */
+  flush(): string;
+  private handleOpen;
+  private _pendingHref;
+  private handleText;
+  private handleClose;
+  private appendToCurrentBlock;
+  /** Flush accumulated top-level text as a single wrapped line. */
+  private flushTopLevelBuffer;
+  private flushLine;
+  /** Emit current partial block content (the "live" incomplete block). */
+  private emitPartial;
+}
+//#endregion
+//#region src/syntax.d.ts
+/**
+ * Call this once at REPL startup to warm up the highlighter asynchronously.
+ * `highlightCode` will block briefly on first call if this hasn't resolved yet.
+ */
+declare function initSyntaxHighlighting(): Promise<void>;
+/**
+ * Highlight `code` for the given `lang` and return an ANSI-colored string.
+ * Lines are NOT wrapped or indented — the caller handles that.
+ * Falls back to plain text if shiki is unavailable or lang is unknown.
+ */
+declare function highlightCode(code: string, lang?: string): string;
+//#endregion
+export { type HtmlRendererOptions, StreamingHtmlRenderer, highlightCode, initSyntaxHighlighting };

package/dist/index.mjs

@@ -0,0 +1,475 @@
+import { Parser } from "htmlparser2";
+import { Chalk } from "chalk";
+import wrapAnsi from "wrap-ansi";
+import stringWidth from "string-width";
+
+//#region src/syntax.ts
+const chalk$2 = new Chalk({ level: 3 });
+const FS_ITALIC = 1;
+const FS_BOLD = 2;
+const FS_UNDERLINE = 4;
+/**
+* Common languages pre-loaded at init — small set for fast startup.
+* Unknown languages fall back to plain rendering at highlight time.
+*/
+const PRELOAD_LANGS = [
+	"typescript",
+	"javascript",
+	"tsx",
+	"jsx",
+	"python",
+	"bash",
+	"sh",
+	"json",
+	"yaml",
+	"html",
+	"css",
+	"markdown",
+	"rust",
+	"go",
+	"sql",
+	"toml",
+	"diff",
+	"text"
+];
+const THEME = "github-light";
+let highlighter = null;
+let initPromise = null;
+/**
+* Call this once at REPL startup to warm up the highlighter asynchronously.
+* `highlightCode` will block briefly on first call if this hasn't resolved yet.
+*/
+async function initSyntaxHighlighting() {
+	if (initPromise) return initPromise;
+	initPromise = (async () => {
+		try {
+			const { createHighlighter, bundledLanguages } = await import("shiki");
+			const langs = PRELOAD_LANGS.filter((l) => bundledLanguages[l] != null);
+			highlighter = await createHighlighter({
+				themes: [THEME],
+				langs
+			});
+		} catch {
+			highlighter = null;
+		}
+	})();
+	return initPromise;
+}
+/** Map a hex color string (#rrggbb) to a chalk hex color function. */
+function applyColor(c, hex) {
+	if (!hex) return c;
+	return c.hex(hex);
+}
+/**
+* Highlight `code` for the given `lang` and return an ANSI-colored string.
+* Lines are NOT wrapped or indented — the caller handles that.
+* Falls back to plain text if shiki is unavailable or lang is unknown.
+*/
+function highlightCode(code, lang) {
+	if (!highlighter || !lang) return code;
+	const loaded = highlighter.getLoadedLanguages();
+	const effectiveLang = loaded.includes(lang) ? lang : loaded.includes("text") ? "text" : null;
+	if (!effectiveLang) return code;
+	try {
+		return highlighter.codeToTokens(code, {
+			lang: effectiveLang,
+			theme: THEME
+		}).tokens.map((row) => row.map((token) => {
+			let c = applyColor(chalk$2, token.color);
+			const fs = token.fontStyle ?? 0;
+			if (fs & FS_ITALIC) c = c.italic;
+			if (fs & FS_BOLD) c = c.bold;
+			if (fs & FS_UNDERLINE) c = c.underline;
+			return c(token.content);
+		}).join("")).join("\n");
+	} catch {
+		return code;
+	}
+}
+
+//#endregion
+//#region src/ansi.ts
+/**
+* ANSI style helpers — maps HTML tags to chalk modifiers.
+* Kept separate so renderer.ts stays focused on parsing logic.
+*/
+const chalk$1 = new Chalk({ level: 3 });
+/** Block-level tags that flush output as their own paragraph. */
+const BLOCK_TAGS = new Set([
+	"p",
+	"div",
+	"section",
+	"article",
+	"main",
+	"header",
+	"footer",
+	"aside",
+	"nav",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"ul",
+	"ol",
+	"li",
+	"blockquote",
+	"pre",
+	"table",
+	"thead",
+	"tbody",
+	"tr",
+	"hr",
+	"br"
+]);
+/** Inline tags that only modify chalk styling. */
+const INLINE_STYLE_TAGS = new Set([
+	"b",
+	"strong",
+	"i",
+	"em",
+	"u",
+	"s",
+	"del",
+	"strike",
+	"code",
+	"mark",
+	"small",
+	"sup",
+	"sub",
+	"span",
+	"a",
+	"abbr"
+]);
+/** Apply chalk styling for an opening inline tag. Returns new chalk chain. */
+function applyInlineOpen(tag, c) {
+	switch (tag) {
+		case "b":
+		case "strong": return c.bold;
+		case "i":
+		case "em": return c.italic;
+		case "u": return c.underline;
+		case "s":
+		case "del":
+		case "strike": return c.strikethrough;
+		case "code": return c.cyan;
+		case "mark": return c.bgYellow.black;
+		case "a": return c.blue.underline;
+		default: return c;
+	}
+}
+/** Style a full heading line. */
+function styleHeading(level, text) {
+	return {
+		1: (s) => chalk$1.bold.red(s),
+		2: (s) => chalk$1.bold.cyan(s),
+		3: (s) => chalk$1.bold.yellow(s),
+		4: (s) => chalk$1.bold.yellow(s),
+		5: (s) => chalk$1.bold.cyan(s),
+		6: (s) => chalk$1.bold.gray(s)
+	}[level](text);
+}
+/** Style a blockquote line. */
+function styleBlockquote(text) {
+	return chalk$1.gray("│ ") + chalk$1.italic.gray(text);
+}
+/** Style an <hr>. */
+function styleHr(cols = 60) {
+	return chalk$1.gray("─".repeat(cols));
+}
+/** Style a <pre><code> block. */
+function styleCodeBlock(text, lang) {
+	const header = lang ? chalk$1.gray(`  ${lang}`) : "";
+	const body = highlightCode(text, lang).split("\n").map((line) => chalk$1.gray("│ ") + line).join("\n");
+	return header ? header + "\n" + body : body;
+}
+
+//#endregion
+//#region src/renderer.ts
+const chalk = new Chalk({ level: 3 });
+var StreamingHtmlRenderer = class {
+	opts;
+	parser;
+	/** Output collected when no onFlush provided. */
+	collected = [];
+	/** Stack of open block contexts. Innermost block = last element. */
+	blockStack = [];
+	/** Stack of list contexts for bullet/number generation. */
+	listStack = [];
+	/** Current inline chalk chain (accumulated from open inline tags). */
+	inlineChain = chalk;
+	/** Stack of chalk chains — restored on close tag. */
+	inlineStack = [];
+	/** Inside <pre>: true — disables word-wrap, preserves whitespace. */
+	inPre = false;
+	/** Table cell buffer: row → cells. */
+	tableRows = [];
+	currentRow = [];
+	currentCell = "";
+	inTableCell = false;
+	/** Whether we're inside a <blockquote> (may be nested). */
+	blockquoteDepth = 0;
+	/**
+	* Buffer for top-level text nodes (text that arrives outside any block tag).
+	* Instead of flushing each streaming chunk immediately (which creates one
+	* line per word/character), we accumulate here and flush at the next block
+	* boundary or on end().
+	*/
+	topLevelBuffer = "";
+	constructor(opts = {}) {
+		this.opts = {
+			columns: opts.columns ?? 80,
+			onFlush: opts.onFlush,
+			onPartial: opts.onPartial
+		};
+		this.parser = new Parser({
+			onopentag: (name, attrs) => this.handleOpen(name, attrs),
+			ontext: (text) => this.handleText(text),
+			onclosetag: (name) => this.handleClose(name)
+		}, { decodeEntities: true });
+	}
+	/** Feed a chunk of HTML (may be partial/incomplete). */
+	write(chunk) {
+		this.parser.write(chunk);
+		this.emitPartial();
+	}
+	/** Finalise: flush any remaining partial content and reset state. */
+	end() {
+		this.parser.end();
+		this.flushTopLevelBuffer();
+		this.emitPartial();
+	}
+	/** Return all collected output (only useful when no onFlush provided). */
+	flush() {
+		return this.collected.join("\n");
+	}
+	handleOpen(tag, attrs) {
+		if (INLINE_STYLE_TAGS.has(tag)) {
+			if (tag === "code" && this.inPre) {
+				const m = (attrs["class"] ?? "").match(/language-(\w+)/);
+				if (m) {
+					const preFrame = [...this.blockStack].reverse().find((f) => f.tag === "pre");
+					if (preFrame) preFrame.codeLang = m[1];
+				}
+				this.inlineStack.push(this.inlineChain);
+				return;
+			}
+			this.inlineStack.push(this.inlineChain);
+			this.inlineChain = applyInlineOpen(tag, this.inlineChain);
+			if (tag === "a" && attrs["href"]) this._pendingHref = attrs["href"] ?? void 0;
+			return;
+		}
+		if (tag === "td" || tag === "th") {
+			this.inTableCell = true;
+			this.currentCell = "";
+			if (tag === "th") {
+				this.inlineStack.push(this.inlineChain);
+				this.inlineChain = chalk.bold;
+			}
+			return;
+		}
+		if (BLOCK_TAGS.has(tag)) {
+			this.flushTopLevelBuffer();
+			if (tag === "pre") this.inPre = true;
+			if (tag === "table") this.tableRows = [];
+			if (tag === "tr") this.currentRow = [];
+			if (tag === "ul" || tag === "ol") {
+				const indent = this.listStack.length * 2;
+				this.listStack.push({
+					tag,
+					counter: 0,
+					indent
+				});
+			}
+			if (tag === "blockquote") this.blockquoteDepth++;
+			let headingLevel;
+			let listBullet;
+			if (/^h[1-6]$/.test(tag)) headingLevel = parseInt(tag[1]);
+			if (tag === "li") {
+				const list = this.listStack[this.listStack.length - 1];
+				if (list) if (list.tag === "ol") {
+					list.counter++;
+					listBullet = " ".repeat(list.indent) + chalk.bold(`${list.counter}.`) + " ";
+				} else listBullet = " ".repeat(list.indent) + chalk.bold("•") + " ";
+			}
+			this.blockStack.push({
+				tag,
+				text: "",
+				headingLevel,
+				listBullet
+			});
+			return;
+		}
+		if (tag === "br") this.appendToCurrentBlock("\n");
+	}
+	_pendingHref;
+	handleText(text) {
+		if (!this.inPre) text = text.replace(/\s+/g, " ");
+		if (!text) return;
+		const styled = this.inlineChain(text);
+		if (this.inTableCell) {
+			this.currentCell += styled;
+			return;
+		}
+		this.appendToCurrentBlock(styled);
+	}
+	handleClose(tag) {
+		if (INLINE_STYLE_TAGS.has(tag)) {
+			if (tag === "a" && this._pendingHref) {
+				const frame$1 = this.blockStack[this.blockStack.length - 1];
+				if (frame$1 && this._pendingHref) {
+					const hrefStyled = chalk.dim(` <${this._pendingHref}>`);
+					frame$1.text += hrefStyled;
+				}
+				this._pendingHref = void 0;
+			}
+			const prev = this.inlineStack.pop();
+			if (prev !== void 0) this.inlineChain = prev;
+			return;
+		}
+		if (tag === "td" || tag === "th") {
+			this.currentRow.push(this.currentCell.trim());
+			this.currentCell = "";
+			this.inTableCell = false;
+			if (tag === "th") {
+				const prev = this.inlineStack.pop();
+				if (prev !== void 0) this.inlineChain = prev;
+			}
+			return;
+		}
+		if (tag === "tr") {
+			this.tableRows.push([...this.currentRow]);
+			this.currentRow = [];
+			return;
+		}
+		if (tag === "table") {
+			const tableText = renderTable(this.tableRows);
+			this.tableRows = [];
+			this.flushLine(tableText);
+			if (this.blockStack[this.blockStack.length - 1]?.tag === "table") this.blockStack.pop();
+			return;
+		}
+		if (tag === "ul" || tag === "ol") this.listStack.pop();
+		if (tag === "blockquote") this.blockquoteDepth = Math.max(0, this.blockquoteDepth - 1);
+		if (!BLOCK_TAGS.has(tag)) return;
+		const frame = this.blockStack.pop();
+		if (!frame) return;
+		if (frame.tag === "pre") {
+			this.inPre = false;
+			const code = frame.text.trimEnd();
+			this.flushLine(styleCodeBlock(code, frame.codeLang));
+			return;
+		}
+		if (frame.tag === "hr") {
+			this.flushLine(styleHr(this.opts.columns));
+			return;
+		}
+		const text = frame.text.trim();
+		if (!text && frame.tag !== "br") return;
+		if (frame.headingLevel) {
+			const wrapped = wrapAnsi(text, this.opts.columns - frame.headingLevel - 1, {
+				hard: false,
+				trim: false
+			});
+			this.flushLine(styleHeading(frame.headingLevel, wrapped));
+			return;
+		}
+		if (frame.tag === "li" && frame.listBullet) {
+			const indent = " ".repeat((frame.listBullet.match(/^ +/)?.[0].length ?? 0) + 2);
+			const wrapped = wrapAnsi(text, this.opts.columns - indent.length, {
+				hard: false,
+				trim: false
+			}).split("\n").map((line, i) => i === 0 ? frame.listBullet + line : indent + line).join("\n");
+			if (this.blockquoteDepth > 0) this.flushLine(styleBlockquote(wrapped));
+			else this.flushLine(wrapped);
+			return;
+		}
+		if (frame.tag === "blockquote") {
+			const wrapped = wrapAnsi(text, this.opts.columns - 2, {
+				hard: false,
+				trim: false
+			});
+			this.flushLine(styleBlockquote(wrapped));
+			return;
+		}
+		if ([
+			"p",
+			"div",
+			"section",
+			"article"
+		].includes(frame.tag)) {
+			const wrapped = wrapAnsi(text, this.opts.columns, {
+				hard: false,
+				trim: false
+			});
+			if (this.blockquoteDepth > 0) this.flushLine(styleBlockquote(wrapped));
+			else this.flushLine(wrapped);
+			return;
+		}
+		if (text) {
+			const wrapped = wrapAnsi(text, this.opts.columns, {
+				hard: false,
+				trim: false
+			});
+			this.flushLine(wrapped);
+		}
+	}
+	appendToCurrentBlock(text) {
+		if (this.blockStack.length > 0) this.blockStack[this.blockStack.length - 1].text += text;
+		else this.topLevelBuffer += text;
+	}
+	/** Flush accumulated top-level text as a single wrapped line. */
+	flushTopLevelBuffer() {
+		const raw = this.topLevelBuffer.trim();
+		this.topLevelBuffer = "";
+		if (!raw) return;
+		const wrapped = wrapAnsi(raw, this.opts.columns, {
+			hard: false,
+			trim: false
+		});
+		if (wrapped) this.flushLine(wrapped);
+	}
+	flushLine(text) {
+		if (!text) return;
+		if (this.opts.onFlush) this.opts.onFlush(text);
+		else this.collected.push(text);
+	}
+	/** Emit current partial block content (the "live" incomplete block). */
+	emitPartial() {
+		if (!this.opts.onPartial) return;
+		const top = this.blockStack[this.blockStack.length - 1];
+		if (!top) return;
+		const text = top.text.trim();
+		if (!text) return;
+		this.opts.onPartial(text);
+	}
+};
+function renderTable(rows) {
+	if (rows.length === 0) return "";
+	const colCount = Math.max(...rows.map((r) => r.length));
+	const colWidths = Array(colCount).fill(0);
+	for (const row of rows) for (let c = 0; c < colCount; c++) colWidths[c] = Math.max(colWidths[c], stringWidth(row[c] ?? ""));
+	const lines = [];
+	const sep = chalk.gray("┼" + colWidths.map((w) => "─".repeat(w + 2)).join("┼") + "┼");
+	for (let r = 0; r < rows.length; r++) {
+		const row = rows[r];
+		const cells = colWidths.map((w, c) => {
+			const cell = row[c] ?? "";
+			const pad = w - stringWidth(cell);
+			return " " + cell + " ".repeat(Math.max(0, pad)) + " ";
+		});
+		lines.push(chalk.gray("│") + cells.join(chalk.gray("│")) + chalk.gray("│"));
+		if (r === 0) lines.push(sep);
+	}
+	const top = chalk.gray("┌") + colWidths.map((w) => chalk.gray("─".repeat(w + 2))).join(chalk.gray("┬")) + chalk.gray("┐");
+	const bottom = chalk.gray("└") + colWidths.map((w) => chalk.gray("─".repeat(w + 2))).join(chalk.gray("┴")) + chalk.gray("┘");
+	return [
+		top,
+		...lines,
+		bottom
+	].join("\n");
+}
+
+//#endregion
+export { StreamingHtmlRenderer, highlightCode, initSyntaxHighlighting };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@one-agent/html",
+  "version": "0.0.1-beta.2",
+  "description": "Streaming HTML → ANSI terminal renderer for ONE agent output.",
+  "keywords": [
+    "html",
+    "ansi",
+    "terminal",
+    "streaming",
+    "renderer",
+    "ai-agent",
+    "cli"
+  ],
+  "homepage": "https://github.com/RIA-Spec/one-agent#readme",
+  "bugs": {
+    "url": "https://github.com/RIA-Spec/one-agent/issues"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RIA-Spec/one-agent.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "NOTICE",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "htmlparser2": "^9.1.0",
+    "shiki": "^3.23.0",
+    "string-width": "^7.2.0",
+    "wrap-ansi": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "oxfmt": "^0.28.0",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}