@linxiraos/pi-utils 1.1.27 → 1.2.0

package/src/stream.ts

@@ -6,6 +6,10 @@ import { parseStreamingJson } from "./json-parse";
 const LF = 0x0a;
 const CR = 0x0d;
 
+// Capacity above this is released once the buffered bytes no longer need it,
+// so one oversized frame does not pin its peak buffer for the stream's life.
+const CONCAT_SINK_RETAIN_BYTES = 1024 * 1024;
+
 /**
  * Split a byte stream on LF boundaries.
  *
@@ -89,6 +93,21 @@ export class ConcatSink {
 		return next;
 	}
 
+	/** Drop or right-size an oversized buffer after the buffered length shrank. */
+	#releaseCapacity(): void {
+		const space = this.#space;
+		if (!space || space.length <= CONCAT_SINK_RETAIN_BYTES) return;
+		const length = this.#length;
+		if (length === 0) {
+			this.#space = undefined;
+			return;
+		}
+		if (length * 4 > space.length) return;
+		const next = Buffer.allocUnsafe(length);
+		space.copy(next, 0, 0, length);
+		this.#space = next;
+	}
+
 	append(chunk: Uint8Array) {
 		const n = chunk.length;
 		if (!n) return;
@@ -99,11 +118,10 @@ export class ConcatSink {
 	}
 
 	reset(chunk: Uint8Array) {
+		this.#length = 0;
+		this.#releaseCapacity();
 		const n = chunk.length;
-		if (!n) {
-			this.#length = 0;
-			return;
-		}
+		if (!n) return;
 		const space = this.#ensureCapacity(n);
 		space.set(chunk, 0);
 		this.#length = n;
@@ -127,14 +145,16 @@ export class ConcatSink {
 		if (count <= 0) return;
 		if (count >= this.#length) {
 			this.#length = 0;
-			return;
+		} else {
+			this.#space!.copyWithin(0, count, this.#length);
+			this.#length -= count;
 		}
-		this.#space!.copyWithin(0, count, this.#length);
-		this.#length -= count;
+		this.#releaseCapacity();
 	}
 
 	clear() {
 		this.#length = 0;
+		this.#releaseCapacity();
 	}
 
 	/**
@@ -229,13 +249,14 @@ export class ConcatSink {
 		if (error) throw error;
 		if (done) {
 			this.#length = 0;
-			return;
-		}
-		const rem = total - read;
-		if (rem < total) {
-			space.copyWithin(0, read, total);
+		} else {
+			const rem = total - read;
+			if (rem < total) {
+				space.copyWithin(0, read, total);
+			}
+			this.#length = rem;
 		}
-		this.#length = rem;
+		this.#releaseCapacity();
 	}
 }
 

package/src/temp.ts

@@ -3,6 +3,13 @@ import * as fsPromises from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 
+/**
+ * Owned temporary directory, removed via `remove()` or `using`/`await using`.
+ *
+ * Prefixes follow `mkdtemp`: `"@name-"` creates under the OS temp dir, any other
+ * prefix is a path (a bare `"name-"` lands in the process cwd), and no prefix
+ * means `"@pi-temp-"`.
+ */
 export class TempDir {
 	#path: string;
 	private constructor(path: string) {

package/src/template.ts

@@ -226,7 +226,9 @@ function findTagEnd(source: string, start: number, triple: boolean): number {
 
 function parseTemplate(source: string): Node[] {
 	const root: Node[] = [];
-	const stack: { node: BlockNode; target: Node[]; inverted: boolean }[] = [];
+	// `chained` marks a block opened by `{{else name …}}`: it has no closing tag of
+	// its own and closes with the block it chains from, as in Handlebars.
+	const stack: { node: BlockNode; target: Node[]; inverted: boolean; chained: boolean }[] = [];
 	let target = root;
 	let cursor = 0;
 	while (cursor < source.length) {
@@ -263,7 +265,7 @@ function parseTemplate(source: string): Node[] {
 				};
 				target.push(nested);
 				target = nested.body;
-				stack.push({ node: nested, target: parentTarget, inverted: false });
+				stack.push({ node: nested, target: parentTarget, inverted: false, chained: true });
 			}
 			continue;
 		}
@@ -277,12 +279,13 @@ function parseTemplate(source: string): Node[] {
 				inverted,
 			};
 			target.push(node);
-			stack.push({ node, target, inverted });
+			stack.push({ node, target, inverted, chained: false });
 			target = node.body;
 			continue;
 		}
 		if (raw.startsWith("/")) {
-			const current = stack.pop();
+			let current = stack.pop();
+			while (current?.chained) current = stack.pop();
 			if (!current || current.node.expression.name !== raw.slice(1).trim())
 				throw new Error(`Parse error: mismatched ${raw}`);
 			if (current.inverted) [current.node.body, current.node.inverse] = [current.node.inverse, current.node.body];

package/src/timing-buffer.ts

@@ -22,7 +22,7 @@ export interface ModuleLoadEvent {
  * Registry-global key under which the preload accumulates module-load events.
  * `Symbol.for` so both modules resolve the same symbol independently.
  */
-const KEY: symbol = Symbol.for("omp.moduleLoadBuffer");
+const KEY: symbol = Symbol.for("zeta.moduleLoadBuffer");
 
 type Store = Record<symbol, ModuleLoadEvent[] | undefined>;
 

package/src/tls-fetch.ts

@@ -52,7 +52,7 @@ type BunTlsOptions = {
 
 type BunTlsRequestInit = RequestInit & { tls?: BunTlsOptions };
 
-const EXTRA_CA_FETCH_MARKER = Symbol("omp.extraCaFetch");
+const EXTRA_CA_FETCH_MARKER = Symbol("zeta.extraCaFetch");
 type ExtraCaFetch = FetchImpl & { [EXTRA_CA_FETCH_MARKER]?: true };
 
 /**

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. */