@oh-my-pi/pi-utils 18.7.0 → 18.8.0

package/src/turndown/gfm.ts

@@ -1,17 +1,25 @@
 import type { TurndownNode, TurndownPlugin, TurndownServiceLike } from "./types";
 
-function descendantElements(node: TurndownNode, name: string): TurndownNode[] {
+/** Elements named `name` below `node` in document order, not descending into nested tables. */
+function descendantElements(node: TurndownNode, name: string, limit = Number.POSITIVE_INFINITY): TurndownNode[] {
 	const matches: TurndownNode[] = [];
-	for (const child of Array.from(node.children)) {
+	const stack: TurndownNode[] = [];
+	const pushChildren = (parent: TurndownNode): void => {
+		const children = parent.children;
+		for (let index = children.length - 1; index >= 0; index--) stack.push(children[index]!);
+	};
+	pushChildren(node);
+	while (stack.length > 0 && matches.length < limit) {
+		const child = stack.pop()!;
 		if (child.nodeName === name) matches.push(child);
-		if (child.nodeName !== "TABLE") matches.push(...descendantElements(child, name));
+		if (child.nodeName !== "TABLE") pushChildren(child);
 	}
 	return matches;
 }
 
 function isHeadingTable(node: TurndownNode): boolean {
 	if (node.nodeName !== "TABLE") return false;
-	const firstRow = descendantElements(node, "TR")[0];
+	const firstRow = descendantElements(node, "TR", 1)[0];
 	if (!firstRow) return false;
 	const cells = Array.from(firstRow.children);
 	return cells.length > 0 && cells.every(cell => cell.nodeName === "TH");
@@ -50,12 +58,13 @@ function renderTable(service: TurndownServiceLike, table: TurndownNode): string
 /** Install GitHub fenced code blocks selected by `highlight-source-*` wrappers. */
 export const highlightedCodeBlock: TurndownPlugin = service => {
 	service.addRule("highlightedCodeBlock", {
+		skipContent: true,
 		filter(node) {
 			return node.nodeName === "DIV" && /(?:^|\s)highlight-source-([^\s]+)/.test(node.getAttribute("class") ?? "");
 		},
 		replacement(_content, node, options) {
 			const language = /(?:^|\s)highlight-source-([^\s]+)/.exec(node.getAttribute("class") ?? "")?.[1] ?? "";
-			const text = descendantElements(node, "PRE")[0]?.textContent ?? "";
+			const text = descendantElements(node, "PRE", 1)[0]?.textContent ?? "";
 			return `\n\n${options.fence}${language}\n${text}\n${options.fence}\n\n`;
 		},
 	});
@@ -74,6 +83,7 @@ export const strikethrough: TurndownPlugin = service => {
 /** Install GFM task-list checkbox conversion. */
 export const taskListItems: TurndownPlugin = service => {
 	service.addRule("taskListItems", {
+		skipContent: true,
 		filter(node) {
 			return (
 				node.nodeName === "INPUT" &&
@@ -90,6 +100,7 @@ export const taskListItems: TurndownPlugin = service => {
 /** Install GFM table conversion for tables with a heading row. */
 export const tables: TurndownPlugin = service => {
 	service.addRule("table", {
+		skipContent: true,
 		filter: isHeadingTable,
 		replacement(_content, node) {
 			return renderTable(service, node);

package/src/turndown/html.ts

@@ -56,11 +56,16 @@ function escapeAttribute(value: string): string {
 abstract class HtmlNode implements TurndownNode {
 	parentNode: HtmlNode | null = null;
 	readonly childNodes: HtmlNode[] = [];
+	/** Position in the parent's `childNodes`; assigned on append (the tree is immutable after parse). */
+	index = -1;
+	/** Position in the parent's `children`; -1 for non-element nodes. */
+	elementIndex = -1;
+	readonly #elements: HtmlNode[] = [];
 	abstract readonly nodeType: number;
 	abstract readonly nodeName: string;
 
-	get children(): HtmlNode[] {
-		return this.childNodes.filter(child => child.nodeType === 1);
+	get children(): readonly HtmlNode[] {
+		return this.#elements;
 	}
 
 	get firstChild(): HtmlNode | null {
@@ -72,19 +77,29 @@ abstract class HtmlNode implements TurndownNode {
 	}
 
 	get previousSibling(): HtmlNode | null {
-		if (!this.parentNode) return null;
-		const index = this.parentNode.childNodes.indexOf(this);
-		return index > 0 ? (this.parentNode.childNodes[index - 1] ?? null) : null;
+		if (!this.parentNode || this.index <= 0) return null;
+		return this.parentNode.childNodes[this.index - 1] ?? null;
 	}
 
 	get nextSibling(): HtmlNode | null {
 		if (!this.parentNode) return null;
-		const index = this.parentNode.childNodes.indexOf(this);
-		return index >= 0 ? (this.parentNode.childNodes[index + 1] ?? null) : null;
+		return this.parentNode.childNodes[this.index + 1] ?? null;
 	}
 
 	get textContent(): string {
-		return this.childNodes.map(child => child.textContent).join("");
+		const parts: string[] = [];
+		const stack: HtmlNode[] = [];
+		for (let index = this.childNodes.length - 1; index >= 0; index--) stack.push(this.childNodes[index]!);
+		while (stack.length > 0) {
+			const node = stack.pop()!;
+			if (node instanceof HtmlText) {
+				parts.push(node.value);
+				continue;
+			}
+			const childNodes = node.childNodes;
+			for (let index = childNodes.length - 1; index >= 0; index--) stack.push(childNodes[index]!);
+		}
+		return parts.join("");
 	}
 
 	abstract get outerHTML(): string;
@@ -99,7 +114,12 @@ abstract class HtmlNode implements TurndownNode {
 
 	append(child: HtmlNode): void {
 		child.parentNode = this;
+		child.index = this.childNodes.length;
 		this.childNodes.push(child);
+		if (child.nodeType === 1) {
+			child.elementIndex = this.#elements.length;
+			this.#elements.push(child);
+		}
 	}
 }
 

package/src/turndown/service.ts

@@ -75,7 +75,8 @@ const NONBLANK_EMPTY_ELEMENTS: Readonly<Record<string, true>> = {
 	VIDEO: true,
 };
 
-type RuleEntry = { key: string; rule: TurndownRule };
+/** `filter` is `rule.filter` with string tag names lowercased once at registration. */
+type RuleEntry = { key: string; rule: TurndownRule; filter: RuleFilter };
 type Reference = { destination: string };
 
 const DEFAULT_OPTIONS: ResolvedTurndownOptions = {
@@ -91,11 +92,37 @@ const DEFAULT_OPTIONS: ResolvedTurndownOptions = {
 	preformattedCode: false,
 };
 
-function matchesFilter(filter: RuleFilter, node: TurndownNode, options: ResolvedTurndownOptions): boolean {
+function normalizeFilter(filter: RuleFilter): RuleFilter {
+	if (typeof filter === "function") return filter;
+	if (typeof filter === "string") return filter.toLowerCase();
+	return filter.map(tag => tag.toLowerCase());
+}
+
+function matchesFilter(
+	filter: RuleFilter,
+	node: TurndownNode,
+	name: string,
+	options: ResolvedTurndownOptions,
+): boolean {
 	if (typeof filter === "function") return filter(node, options);
-	const name = node.nodeName.toLowerCase();
-	if (typeof filter === "string") return name === filter.toLowerCase();
-	return filter.some(tag => name === tag.toLowerCase());
+	if (typeof filter === "string") return name === filter;
+	return filter.includes(name);
+}
+
+/** Equivalent to `node.textContent.trim() !== ""` without building the subtree text. */
+function hasNonWhitespaceText(node: TurndownNode): boolean {
+	const stack: TurndownNode[] = [node];
+	while (stack.length > 0) {
+		const current = stack.pop()!;
+		const type = current.nodeType;
+		if (type === 3 || type === 4) {
+			if (/\S/.test(current.textContent ?? "")) return true;
+		} else if (type === 1 || type === 9 || type === 11) {
+			const childNodes = current.childNodes;
+			for (let index = 0; index < childNodes.length; index++) stack.push(childNodes[index]!);
+		}
+	}
+	return false;
 }
 
 function contentWithFlankingWhitespace(content: string, delimiter: string): string {
@@ -115,8 +142,8 @@ function listItemPrefix(node: TurndownNode, options: ResolvedTurndownOptions): s
 	const parent = node.parentNode;
 	if (parent?.nodeName !== "OL") return `${options.bulletListMarker}   `;
 	const start = Number(parent.getAttribute("start") ?? "1");
-	const siblings = Array.from(parent.children);
-	return `${(Number.isFinite(start) ? start : 1) + siblings.indexOf(node)}.  `;
+	const index = node.elementIndex ?? Array.prototype.indexOf.call(parent.children, node);
+	return `${(Number.isFinite(start) ? start : 1) + index}.  `;
 }
 function hasNonblankDescendant(node: TurndownNode): boolean {
 	for (const child of Array.from(node.children)) {
@@ -142,19 +169,19 @@ export default class TurndownService {
 	addRule(key: string, rule: TurndownRule): this {
 		const previous = this.#rules.findIndex(entry => entry.key === key);
 		if (previous >= 0) this.#rules.splice(previous, 1);
-		this.#rules.unshift({ key, rule });
+		this.#rules.unshift({ key, rule, filter: normalizeFilter(rule.filter) });
 		return this;
 	}
 
 	/** Preserve matching elements as HTML when no custom rule handles them. */
 	keep(filter: RuleFilter): this {
-		this.#keepFilters.unshift(filter);
+		this.#keepFilters.unshift(normalizeFilter(filter));
 		return this;
 	}
 
 	/** Drop matching elements and all of their converted content. */
 	remove(filter: RuleFilter): this {
-		this.#removeFilters.unshift(filter);
+		this.#removeFilters.unshift(normalizeFilter(filter));
 		return this;
 	}
 
@@ -216,23 +243,24 @@ export default class TurndownService {
 			return node.parentNode?.nodeName === "CODE" ? collapsed : this.escape(collapsed);
 		}
 		if (node.nodeType !== 1) return this.#convertChildren(node);
-		if (!(node.textContent ?? "").trim() && !NONBLANK_EMPTY_ELEMENTS[node.nodeName] && !hasNonblankDescendant(node)) {
+		if (!hasNonWhitespaceText(node) && !NONBLANK_EMPTY_ELEMENTS[node.nodeName] && !hasNonblankDescendant(node)) {
 			return (
 				this.options.blankReplacement?.("", node, this.options) ?? (BLOCK_ELEMENTS[node.nodeName] ? "\n\n" : "")
 			);
 		}
 
+		const name = node.nodeName.toLowerCase();
+		const custom = this.#rules.find(entry => matchesFilter(entry.filter, node, name, this.options));
 		const block = Boolean(BLOCK_ELEMENTS[node.nodeName]);
 		if (block) this.#previousSourceWhitespace = false;
-		const content = this.#convertChildren(node);
+		const content = custom?.rule.skipContent ? "" : this.#convertChildren(node);
 		if (block) this.#previousSourceWhitespace = false;
 		if (node.nodeName === "CODE") this.#previousSourceWhitespace = false;
-		const custom = this.#rules.find(entry => matchesFilter(entry.rule.filter, node, this.options));
 		if (custom) return custom.rule.replacement(content, node, this.options);
-		if (this.#keepFilters.some(filter => matchesFilter(filter, node, this.options))) {
+		if (this.#keepFilters.some(filter => matchesFilter(filter, node, name, this.options))) {
 			return this.options.keepReplacement?.(content, node, this.options) ?? serializeNode(node);
 		}
-		if (this.#removeFilters.some(filter => matchesFilter(filter, node, this.options))) return "";
+		if (this.#removeFilters.some(filter => matchesFilter(filter, node, name, this.options))) return "";
 		return this.#defaultReplacement(content, node);
 	}
 

package/src/turndown/types.ts

@@ -13,6 +13,8 @@ export interface TurndownNode {
 	readonly previousSibling: TurndownNode | null;
 	readonly textContent: string | null;
 	readonly outerHTML?: string;
+	/** Position among the parent's element children, when the node implementation tracks it. */
+	readonly elementIndex?: number;
 	getAttribute(name: string): string | null;
 	hasAttribute(name: string): boolean;
 }
@@ -64,6 +66,11 @@ export type ReplacementFunction = (content: string, node: TurndownNode, options:
 export interface TurndownRule {
 	filter: RuleFilter;
 	replacement: ReplacementFunction;
+	/**
+	 * Set when `replacement` ignores its `content` argument; the service then skips
+	 * converting the node's children before calling it.
+	 */
+	skipContent?: boolean;
 }
 
 /** A plugin that installs one or more conversion rules. */

package/src/vterm/buffer.ts

@@ -13,11 +13,15 @@ export interface CellAttributes {
 	bg: number;
 }
 
-/** A mutable terminal grid cell. */
+/**
+ * A terminal grid cell. Cells written by the terminal are frozen and may be
+ * shared between grid positions (blank cells, repeated ASCII glyphs), so the
+ * type is readonly: replace a cell instead of mutating it.
+ */
 export interface CellData {
-	chars: string;
-	width: number;
-	attrs: CellAttributes;
+	readonly chars: string;
+	readonly width: number;
+	readonly attrs: Readonly<CellAttributes>;
 }
 
 /** Creates the default rendition. */
@@ -37,18 +41,33 @@ export function defaultAttributes(): CellAttributes {
 	};
 }
 
-function cloneAttributes(attrs: CellAttributes): CellAttributes {
-	return { ...attrs };
-}
+/** Frozen default rendition shared by every unstyled cell. */
+export const DEFAULT_CELL_ATTRIBUTES: Readonly<CellAttributes> = Object.freeze(defaultAttributes());
 
 /** Creates an empty cell with the supplied rendition. */
 export function blankCell(attrs: CellAttributes = defaultAttributes()): CellData {
-	return { chars: "", width: 1, attrs: cloneAttributes(attrs) };
+	return { chars: "", width: 1, attrs: { ...attrs } };
+}
+
+const sharedBlankCells = new WeakMap<Readonly<CellAttributes>, CellData>();
+
+/**
+ * Returns the frozen empty cell shared by every blank position with `attrs`.
+ * Frozen renditions are interned; a mutable one is snapshotted first.
+ */
+export function sharedBlankCell(attrs: Readonly<CellAttributes> = DEFAULT_CELL_ATTRIBUTES): CellData {
+	if (!Object.isFrozen(attrs)) return Object.freeze({ chars: "", width: 1, attrs: Object.freeze({ ...attrs }) });
+	let cell = sharedBlankCells.get(attrs);
+	if (!cell) {
+		cell = Object.freeze({ chars: "", width: 1, attrs });
+		sharedBlankCells.set(attrs, cell);
+	}
+	return cell;
 }
 
 /** Proposed xterm-compatible cell readback object. */
 export class BufferCell {
-	#cell: CellData = blankCell();
+	#cell: CellData = sharedBlankCell();
 
 	/** Reuses this object for another grid cell. */
 	setFrom(cell: CellData): this {
@@ -137,8 +156,9 @@ export class BufferLine {
 	cells: CellData[];
 	isWrapped = false;
 
-	constructor(columns: number, attrs: CellAttributes = defaultAttributes()) {
-		this.cells = Array.from({ length: columns }, () => blankCell(attrs));
+	constructor(columns: number, attrs: Readonly<CellAttributes> = DEFAULT_CELL_ATTRIBUTES) {
+		const blank = sharedBlankCell(attrs);
+		this.cells = Array.from({ length: columns }, () => blank);
 	}
 
 	/** Number of grid columns in the line. */