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

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [18.8.0] - 2026-10-07
+
+### Added
+
+- Added `ZipPackage` to `@oh-my-pi/pi-utils/ar` for lazily reading ZIP-based document packages with a configurable total-inflation limit, plus `DocxImage.readBytes()` for accessing raw DOCX image data.
+
+### Changed
+
+- Improved DOCX conversion to inflate only the package contents it needs, reducing unnecessary work and memory use.
+- Improved performance across HTML-to-Markdown conversion, Readability extraction, Markdown lexing, terminal emulation, terminal styling, streaming tool-argument parsing, and log writing. Large-page processing and terminal workloads now use substantially less time and memory.
+
+### Fixed
+
+- Fixed memory growth in long-lived child processes, streaming readers, prompt template compilation, and retried HTTP requests by releasing buffers, cache entries, and discarded response bodies promptly.
+- Fixed prompt templates rejecting `{{else if …}}` chains as unclosed blocks; a chain now closes with its opening block's single closing tag, as in Handlebars.
+
 ## [18.6.3] - 2026-10-06
 
 ### Breaking Changes

package/dist/types/ar/index.d.ts

@@ -9,3 +9,4 @@ export * from "./registry.js";
 export * from "./source.js";
 export * from "./types.js";
 export * from "./write.js";
+export * from "./zip-package.js";

package/dist/types/ar/zip-package.d.ts

@@ -0,0 +1,21 @@
+import type { ArchiveReader } from "./reader.js";
+/**
+ * A ZIP-based document package (OOXML, EPUB) whose members are inflated only
+ * when read. Lookups use exact member paths, so a converter sees the same
+ * members a fully materialized `path → bytes` map would expose. Each member's
+ * size counts once toward a cap on total inflated bytes, like a fully
+ * materialized archive, so a crafted package cannot amplify past the in-memory
+ * limit one member at a time.
+ */
+export declare class ZipPackage {
+    #private;
+    constructor(archive: ArchiveReader, maxTotalBytes?: number);
+    /** Index a ZIP buffer without inflating any member. */
+    static open(bytes: Uint8Array, maxTotalBytes?: number): Promise<ZipPackage>;
+    /** Exact paths of every file member. */
+    get members(): ReadonlySet<string>;
+    /** Inflate one member, or `undefined` when absent. Throws once distinct inflated bytes exceed the cap. */
+    readBytes(memberPath: string): Promise<Uint8Array | undefined>;
+    /** Inflate one member as UTF-8 text, or `undefined` when absent. */
+    readText(memberPath: string): Promise<string | undefined>;
+}

package/dist/types/docx/converter.d.ts

@@ -22,6 +22,8 @@ export interface DocxImage {
     readonly altText: string;
     /** Read the image payload using mammoth's used encoding surface. */
     read(encoding: "base64"): Promise<string>;
+    /** Read the raw image bytes without a base64 round trip. */
+    readBytes(): Promise<Uint8Array>;
 }
 /** HTML attributes returned by a custom image converter. */
 export type ImageAttributes = Readonly<Record<string, string>>;

package/dist/types/dom/core.d.ts

@@ -59,6 +59,7 @@ export declare class EventTarget {
 }
 /** Base class for the implemented DOM tree. */
 export declare class Node extends EventTarget {
+    #private;
     static readonly ELEMENT_NODE = NodeType.ELEMENT;
     static readonly ATTRIBUTE_NODE = NodeType.ATTRIBUTE;
     static readonly TEXT_NODE = NodeType.TEXT;
@@ -69,8 +70,12 @@ export declare class Node extends EventTarget {
     readonly nodeName: string;
     parentNode: Node | null;
     ownerDocument: Document | null;
-    childNodes: Node[];
     constructor(nodeType: number, nodeName: string, ownerDocument?: Document | null);
+    /** Child nodes in tree order. */
+    get childNodes(): Node[];
+    set childNodes(value: Node[]);
+    /** Whether this node has any children (without allocating a child list). */
+    hasChildNodes(): boolean;
     /** First child node, if present. */
     get firstChild(): Node | null;
     /** Last child node, if present. */
@@ -196,14 +201,20 @@ export declare class CSSStyleDeclaration {
 }
 /** DOM element with attributes, selectors, and HTML serialization. */
 export declare class Element extends Node {
+    #private;
     readonly localName: string;
     readonly tagName: string;
     readonly namespaceURI: string | null;
     readonly qualifiedName: string;
-    readonly attributes: NamedNodeMap;
-    readonly classList: DOMTokenList;
-    readonly style: CSSStyleDeclaration;
     constructor(tagName: string, ownerDocument?: Document | null, namespaceURI?: string | null);
+    /** Attribute collection. */
+    get attributes(): NamedNodeMap;
+    /** Class token list over the `class` attribute. */
+    get classList(): DOMTokenList;
+    /** Inline style declaration. */
+    get style(): CSSStyleDeclaration;
+    /** Whether the element has any attribute objects (without allocating the collection). */
+    hasAttributes(): boolean;
     /** Element children. */
     get children(): Element[];
     /** First element child. */

package/dist/types/dom/parser.d.ts

@@ -1,7 +1,9 @@
-import { Document, type DocumentFragment } from "./core.js";
+import { Document, type DocumentFragment, Element } from "./core.js";
 /** Decode common named entities and all valid numeric character references. */
 export declare function decodeEntities(value: string): string;
-/** Parse markup into a document fragment. */
-export declare function parseFragment(html: string, document: Document, contextTag?: string): DocumentFragment;
+/** Parse markup, appending the resulting nodes to `root` (a document, fragment, or element). */
+export declare function parseInto(html: string, document: Document, root: Document | DocumentFragment | Element): void;
+/** Parse markup into a document fragment. `_contextTag` is accepted for compatibility and ignored. */
+export declare function parseFragment(html: string, document: Document, _contextTag?: string): DocumentFragment;
 /** Parse markup directly into a document. */
 export declare function parseDocument(html: string): Document;

package/dist/types/dom/selector.d.ts

@@ -1,5 +1,11 @@
 import { type Document, type DocumentFragment, Element } from "./core.js";
+/** Whether a whitespace-separated class string contains a token, without splitting it. */
+export declare function hasClassToken(className: string, token: string): boolean;
 /** Whether an element matches a CSS selector list. */
 export declare function matchesSelector(element: Element, selector: string): boolean;
+/** Nearest inclusive ancestor of an element matching a CSS selector list. */
+export declare function closestMatching(element: Element, selector: string): Element | null;
 /** Query descendants of a node in document order. */
-export declare function querySelectorAllFrom(root: Document | DocumentFragment | Element, selector: string, includeRoot: boolean): Element[];
+export declare function querySelectorAllFrom(root: Document | DocumentFragment | Element, selector: string, _includeRoot: boolean): Element[];
+/** First descendant of a node in document order matching a selector, stopping at the first match. */
+export declare function querySelectorFrom(root: Document | DocumentFragment | Element, selector: string): Element | null;

package/dist/types/logger/rotating-file.d.ts

@@ -47,9 +47,11 @@ export declare class RotatingFileSink {
     /**
      * Append one already-formatted log record. A batching sink buffers it unless
      * `flushNow` is set or the buffer reached its size threshold; either way the
-     * whole buffer, this record included, is then written in order.
+     * whole buffer, this record included, is then written in order. `day` is the
+     * record's `localDay` key, so callers that already took the record's `Date`
+     * reuse it.
      */
-    write(line: string, flushNow?: boolean): void;
+    write(line: string, flushNow?: boolean, day?: string): void;
     /** Write every buffered record to the active file now. */
     flush(): void;
     /** Write buffered records, then stop accepting records. */

package/dist/types/marked/core.d.ts

@@ -185,14 +185,15 @@ export type TokensList = Token[] & {
 export interface TokenizerThis {
     lexer: Lexer;
     /**
-     * For an inline tokenizer, the whole inline source, such as a paragraph's text. The `src` it receives is the part
-     * of it before `end` that starts at `end - src.length`: inside a link label or the text of emphasis, `end` is where
-     * that text ends, right before its closer, and a token there must not reach past it. Inline tokenizers get one
-     * context object per inline source, the same for every call while the lexer works through it and the labels and
-     * emphasis inside it, so a tokenizer can keep state for it in a `WeakMap`.
+     * The whole source the lexer works through. The `src` a tokenizer receives is the part of it before `end` that
+     * starts at `end - src.length`. For a block tokenizer, `source` is the text passed to one `blockTokens` call and
+     * `end` its length. For an inline tokenizer, it is the inline source, such as a paragraph's text: inside a link
+     * label or the text of emphasis, `end` is where that text ends, right before its closer, and a token there must
+     * not reach past it. Tokenizers get one context object per source, the same for every call while the lexer works
+     * through it (and, inline, the labels and emphasis inside it), so a tokenizer can keep state for it in a `WeakMap`.
      */
     source?: string;
-    /** For an inline tokenizer, where the text the lexer works through ends in `source` (see `source`). */
+    /** Where the text the lexer works through ends in `source` (see `source`). */
     end?: number;
 }
 /** A tokenizer extension callback. */

package/dist/types/marked-list.d.ts

@@ -0,0 +1,38 @@
+/**
+ * List-continuation grammar of `@oh-my-pi/pi-utils/marked`, for streaming
+ * renderers that freeze a lexed prefix at blank-line boundaries (TUI and
+ * collab web).
+ *
+ * marked's list tokenizer (Tokenizer.list, marked v18) continues a list across
+ * blank lines only when the remaining source matches
+ * `listItemRegex(marker)` = `^( {0,3}${marker})((?:[\t ][^\n]*)?(?:\n|$))`,
+ * where `marker` is the exact bullet char for unordered lists (`\${char}`) or
+ * 1-9 digits plus the exact delimiter for ordered lists (`\d{1,9}\${delim}`).
+ * The marker is derived from the list's FIRST item (`n = t[1].trim()`), which
+ * sits at the start of a top-level list token's raw.
+ */
+/**
+ * Whether a same-marker item could still continue the list `listRaw` at
+ * `tailStart` (directly after the blank line ending the list), now or after
+ * any append to `text`.
+ *
+ * Streaming-freeze equivalence invariant: lex(prefix) ++ lex(tail) must equal
+ * lex(full text) for the current text and every append-only extension of it,
+ * because a frozen prefix is sticky. At a blank-line cut directly after a
+ * top-level `list` token, the only construct that can straddle the cut is a
+ * continuation item of that list: marked consumed the blank line into the last
+ * item's raw and re-ran `listItemRegex` at exactly `tailStart`, merging a
+ * same-marker item into one renumbered loose list. The cut is safe only when
+ * that regex can NEVER match at `tailStart`, no matter what is appended later.
+ *
+ * Append-only growth means "closed" may only be concluded from a present
+ * character that contradicts every possible continuation (tail "1x" can never
+ * grow into an ordered item, but tail "1" can become "1. c"). Running out of
+ * text mid-marker therefore answers "may continue".
+ *
+ * Returns true when the tail could still continue the list (or the list's
+ * marker is unrecognizable) — the conservative "don't freeze" answer. marked
+ * may break the list anyway when the matching line is also an hr (`- - -`);
+ * treating that as "may continue" merely skips a freeze, never corrupts one.
+ */
+export declare function listMayContinueAt(text: string, tailStart: number, listRaw: string): boolean;

package/dist/types/math-delimiters.d.ts

@@ -80,6 +80,16 @@ export declare class MathBlockScan {
     /** The own-line display block starting at `from`, or `undefined`. */
     at(from: number): MathBlock | undefined;
 }
+/**
+ * The own-line display block at the start of `src`, for a marked block tokenizer: `src` is the part of
+ * `context.source` that starts at `context.end - src.length`. One {@link MathBlockScan} is kept per context, which
+ * marked keeps for one `blockTokens` source, so asking at every block start takes linear time even when an opener
+ * never closes. Without `context.source` it is {@link mathBlockAt}.
+ */
+export declare function mathBlockInContext(context: {
+    source?: string;
+    end?: number;
+}, src: string): MathBlock | undefined;
 /**
  * The display opener alone on the line at `from` (up to 3 leading spaces,
  * trailing spaces or tabs; the source's last line may be unterminated), or

package/dist/types/readability/types.d.ts

@@ -13,6 +13,8 @@ export interface ReadabilityNode {
     appendChild(node: ReadabilityNode): ReadabilityNode;
     cloneNode(deep?: boolean): ReadabilityNode;
     remove(): void;
+    /** Detach all children; used when present to move or reset children in one step. */
+    replaceChildren?(): void;
 }
 /** Minimal standards-shaped DOM element accepted by the readability extractor. */
 export interface ReadabilityElement extends ReadabilityNode {

package/dist/types/turndown/types.d.ts

@@ -12,6 +12,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;
 }
@@ -55,6 +57,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. */
 export type TurndownPlugin = (service: TurndownServiceLike) => void;

package/dist/types/vterm/buffer.d.ts

@@ -12,16 +12,27 @@ export interface CellAttributes {
     bgMode: 0 | 1 | 2;
     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. */
 export declare function defaultAttributes(): CellAttributes;
+/** Frozen default rendition shared by every unstyled cell. */
+export declare const DEFAULT_CELL_ATTRIBUTES: Readonly<CellAttributes>;
 /** Creates an empty cell with the supplied rendition. */
 export declare function blankCell(attrs?: 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 declare function sharedBlankCell(attrs?: Readonly<CellAttributes>): CellData;
 /** Proposed xterm-compatible cell readback object. */
 export declare class BufferCell {
     #private;
@@ -62,7 +73,7 @@ export declare class BufferCell {
 export declare class BufferLine {
     cells: CellData[];
     isWrapped: boolean;
-    constructor(columns: number, attrs?: CellAttributes);
+    constructor(columns: number, attrs?: Readonly<CellAttributes>);
     /** Number of grid columns in the line. */
     get length(): number;
     /** Reads a cell, optionally reusing the caller's object. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.6.3",
+	"version": "18.8.0",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.6.3"
+		"@oh-my-pi/pi-natives": "18.8.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/ar/index.ts

@@ -14,3 +14,4 @@ export * from "./registry";
 export * from "./source";
 export * from "./types";
 export * from "./write";
+export * from "./zip-package";

package/src/ar/zip-package.ts

@@ -0,0 +1,57 @@
+import { UTF8_DECODER } from "./bytes";
+import { type ArchiveLimits, assertInMemorySize, DEFAULT_ARCHIVE_LIMITS } from "./limits";
+import { openArchive } from "./open";
+import type { ArchiveReader } from "./reader";
+
+/**
+ * A ZIP-based document package (OOXML, EPUB) whose members are inflated only
+ * when read. Lookups use exact member paths, so a converter sees the same
+ * members a fully materialized `path → bytes` map would expose. Each member's
+ * size counts once toward a cap on total inflated bytes, like a fully
+ * materialized archive, so a crafted package cannot amplify past the in-memory
+ * limit one member at a time.
+ */
+export class ZipPackage {
+	#archive: ArchiveReader;
+	#members = new Set<string>();
+	#limits: ArchiveLimits;
+	/** Members already counted toward {@link #inflated}; re-reading one is free against the cap. */
+	#counted = new Set<string>();
+	#inflated = 0;
+
+	constructor(archive: ArchiveReader, maxTotalBytes = DEFAULT_ARCHIVE_LIMITS.maxInMemorySize) {
+		this.#archive = archive;
+		this.#limits = { ...DEFAULT_ARCHIVE_LIMITS, maxInMemorySize: maxTotalBytes };
+		for (const entry of archive.indexEntries()) {
+			if (!entry.isDirectory) this.#members.add(entry.path);
+		}
+	}
+
+	/** Index a ZIP buffer without inflating any member. */
+	static async open(bytes: Uint8Array, maxTotalBytes?: number): Promise<ZipPackage> {
+		return new ZipPackage(await openArchive({ bytes, format: "zip" }), maxTotalBytes);
+	}
+
+	/** Exact paths of every file member. */
+	get members(): ReadonlySet<string> {
+		return this.#members;
+	}
+
+	/** Inflate one member, or `undefined` when absent. Throws once distinct inflated bytes exceed the cap. */
+	async readBytes(memberPath: string): Promise<Uint8Array | undefined> {
+		if (!this.#members.has(memberPath)) return undefined;
+		const { bytes } = await this.#archive.readFile(memberPath);
+		if (!this.#counted.has(memberPath)) {
+			this.#counted.add(memberPath);
+			this.#inflated += bytes.length;
+			assertInMemorySize(this.#inflated, this.#limits);
+		}
+		return bytes;
+	}
+
+	/** Inflate one member as UTF-8 text, or `undefined` when absent. */
+	async readText(memberPath: string): Promise<string | undefined> {
+		const bytes = await this.readBytes(memberPath);
+		return bytes ? UTF8_DECODER.decode(bytes) : undefined;
+	}
+}

package/src/chalk.ts

@@ -257,14 +257,74 @@ function applyStyles(input: string, styles: readonly Style[]): string {
 	for (let index = styles.length - 1; index >= 0; index--) {
 		const style = styles[index];
 		if (!style) continue;
-		output = output.split(style.close).join(style.close + style.open);
+		if (output.includes(style.close)) output = output.split(style.close).join(style.close + style.open);
 		opening = style.open + opening;
 		closing += style.close;
 	}
-	output = output.replace(/\r?\n/g, match => `${closing}${match}${opening}`);
+	if (output.includes("\n")) output = output.replace(/\r?\n/g, match => `${closing}${match}${opening}`);
 	return opening + output + closing;
 }
 
+const BUILDER_CONTEXT = Symbol("chalk.context");
+const BUILDER_STYLES = Symbol("chalk.styles");
+const BUILDER_HEX_CACHE = Symbol("chalk.hexCache");
+// Bounds per-builder hex children when callers derive colors dynamically.
+const MAX_CACHED_HEX_BUILDERS = 256;
+
+interface BuilderState {
+	[BUILDER_CONTEXT]: ChalkContext;
+	[BUILDER_STYLES]: readonly Style[];
+	[BUILDER_HEX_CACHE]?: Map<string, ChalkInstance>;
+}
+
+type Builder = ChalkInstance & BuilderState;
+
+/** Child builders are created on first access and cached on the parent builder. */
+function defineStyleGetter(proto: object, name: string, style: Style): void {
+	Object.defineProperty(proto, name, {
+		get(this: Builder) {
+			const child = createBuilder(this[BUILDER_CONTEXT], [...this[BUILDER_STYLES], style]);
+			Object.defineProperty(this, name, { value: child });
+			return child;
+		},
+	});
+}
+
+const builderPrototype: object = Object.create(Function.prototype);
+Object.defineProperty(builderPrototype, "level", {
+	get(this: Builder) {
+		return this[BUILDER_CONTEXT].level;
+	},
+	set(this: Builder, level: number) {
+		this[BUILDER_CONTEXT].level = level;
+	},
+});
+for (const name in STYLES) {
+	const style = STYLES[name];
+	if (style) defineStyleGetter(builderPrototype, name, style);
+}
+defineStyleGetter(builderPrototype, "grey", STYLES.gray!);
+defineStyleGetter(builderPrototype, "bgGray", STYLES.bgBlackBright!);
+defineStyleGetter(builderPrototype, "bgGrey", STYLES.bgBlackBright!);
+Object.defineProperty(builderPrototype, "hex", {
+	value(this: Builder, color: string): ChalkInstance {
+		const context = this[BUILDER_CONTEXT];
+		const key = `${context.level}:${color}`;
+		let cache = this[BUILDER_HEX_CACHE];
+		const cached = cache?.get(key);
+		if (cached) return cached;
+		const child = createBuilder(context, [...this[BUILDER_STYLES], hexStyle(color, context.level)]);
+		if (!cache) {
+			cache = new Map();
+			this[BUILDER_HEX_CACHE] = cache;
+		} else if (cache.size >= MAX_CACHED_HEX_BUILDERS) {
+			cache.clear();
+		}
+		cache.set(key, child);
+		return child;
+	},
+});
+
 function createBuilder(context: ChalkContext, styles: readonly Style[]): ChalkInstance {
 	const builder = ((...values: unknown[]) => {
 		let text = "";
@@ -274,27 +334,10 @@ function createBuilder(context: ChalkContext, styles: readonly Style[]): ChalkIn
 		}
 		if (text.length === 0 || context.level === 0) return text;
 		return applyStyles(text, styles);
-	}) as ChalkInstance;
-	Object.defineProperty(builder, "level", {
-		get: () => context.level,
-		set: (level: number) => {
-			context.level = level;
-		},
-	});
-	for (const name in STYLES) {
-		const style = STYLES[name];
-		if (style) Object.defineProperty(builder, name, { get: () => createBuilder(context, [...styles, style]) });
-	}
-	Object.defineProperty(builder, "grey", { get: () => createBuilder(context, [...styles, STYLES.gray!]) });
-	Object.defineProperty(builder, "bgGray", {
-		get: () => createBuilder(context, [...styles, STYLES.bgBlackBright!]),
-	});
-	Object.defineProperty(builder, "bgGrey", {
-		get: () => createBuilder(context, [...styles, STYLES.bgBlackBright!]),
-	});
-	Object.defineProperty(builder, "hex", {
-		value: (color: string) => createBuilder(context, [...styles, hexStyle(color, context.level)]),
-	});
+	}) as Builder;
+	Object.setPrototypeOf(builder, builderPrototype);
+	builder[BUILDER_CONTEXT] = context;
+	builder[BUILDER_STYLES] = styles;
 	return builder;
 }
 

package/src/docx/converter.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { archiveEntryText, readArchiveEntries } from "../ar";
+import { ZipPackage } from "../ar";
 import { attribute, childElements, descendants, firstChild, localName, parseXml, type XmlElement } from "./xml";
 
 /** A mammoth-compatible diagnostic emitted while converting a document. */
@@ -26,6 +26,8 @@ export interface DocxImage {
 	readonly altText: string;
 	/** Read the image payload using mammoth's used encoding surface. */
 	read(encoding: "base64"): Promise<string>;
+	/** Read the raw image bytes without a base64 round trip. */
+	readBytes(): Promise<Uint8Array>;
 }
 
 /** HTML attributes returned by a custom image converter. */
@@ -119,7 +121,8 @@ interface NumberingLevel {
 }
 
 interface ConversionContext {
-	readonly entries: ReadonlyMap<string, Uint8Array>;
+	/** Lazily inflated DOCX members, capped on total inflated bytes. */
+	readonly package: ZipPackage;
 	readonly relationships: ReadonlyMap<string, Relationship>;
 	readonly contentTypes: ReadonlyMap<string, string>;
 	readonly styles: ReadonlyMap<string, Style>;
@@ -373,8 +376,8 @@ async function renderImage(element: XmlElement, context: ConversionContext): Pro
 	const relationship = relationshipId ? context.relationships.get(relationshipId) : undefined;
 	if (!relationship || relationship.external) return "";
 	const memberPath = relationshipPath(relationship.target);
-	const bytes = context.entries.get(memberPath);
-	if (!bytes) {
+	const docx = context.package;
+	if (!docx.members.has(memberPath)) {
 		context.messages.push({ type: "warning", message: `Could not find image ${memberPath}` });
 		return "";
 	}
@@ -391,8 +394,12 @@ async function renderImage(element: XmlElement, context: ConversionContext): Pro
 		altText,
 		async read(encoding: "base64"): Promise<string> {
 			if (encoding !== "base64") throw new Error(`Unsupported image encoding: ${encoding}`);
+			const bytes = await readImageMember(docx, memberPath);
 			return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
 		},
+		readBytes(): Promise<Uint8Array> {
+			return readImageMember(docx, memberPath);
+		},
 	};
 	const converted = await context.convertImage.convert(image);
 	const attributes = Object.entries(converted)
@@ -403,6 +410,13 @@ async function renderImage(element: XmlElement, context: ConversionContext): Pro
 	return attributes ? `<img ${attributes} />` : "<img />";
 }
 
+/** Bytes of an image member already known to exist. */
+async function readImageMember(docx: ZipPackage, memberPath: string): Promise<Uint8Array> {
+	const bytes = await docx.readBytes(memberPath);
+	if (!bytes) throw new Error(`Could not find image ${memberPath}`);
+	return bytes;
+}
+
 function renderFootnoteReference(element: XmlElement, context: ConversionContext): string {
 	const id = attribute(element, "w:id");
 	if (!id || !context.footnotes.has(id)) return "";
@@ -655,21 +669,21 @@ function defaultImageConverter(): ImageConverter {
 /** Convert a DOCX buffer or path to mammoth-compatible HTML. */
 export async function convertToHtml(input: DocxInput, options: ConvertToHtmlOptions = {}): Promise<DocxResult> {
 	const bytes = "buffer" in input && input.buffer ? input.buffer : await fs.readFile(input.path);
-	const entries = await readArchiveEntries({ bytes, format: "zip" });
-	const documentXml = archiveEntryText(entries, "word/document.xml");
+	const docx = await ZipPackage.open(bytes);
+	const documentXml = await docx.readText("word/document.xml");
 	if (!documentXml) throw new Error("Invalid DOCX: missing word/document.xml");
 	const context: ConversionContext = {
-		entries,
-		relationships: parseRelationships(archiveEntryText(entries, "word/_rels/document.xml.rels")),
-		contentTypes: parseContentTypes(archiveEntryText(entries, "[Content_Types].xml")),
-		styles: parseStyles(archiveEntryText(entries, "word/styles.xml")),
-		numbering: parseNumbering(archiveEntryText(entries, "word/numbering.xml")),
+		package: docx,
+		relationships: parseRelationships(await docx.readText("word/_rels/document.xml.rels")),
+		contentTypes: parseContentTypes(await docx.readText("[Content_Types].xml")),
+		styles: parseStyles(await docx.readText("word/styles.xml")),
+		numbering: parseNumbering(await docx.readText("word/numbering.xml")),
 		messages: [],
 		warnedStyles: new Set(),
 		customStyles: parseCustomStyles(options.styleMap),
 		includeDefaultStyleMap: options.includeDefaultStyleMap !== false,
 		convertImage: options.convertImage ?? defaultImageConverter(),
-		footnotes: parseFootnotes(archiveEntryText(entries, "word/footnotes.xml")),
+		footnotes: parseFootnotes(await docx.readText("word/footnotes.xml")),
 		usedFootnotes: [],
 		footnoteOrdinals: new Map(),
 	};