@linxiraos/pi-utils 1.1.27 → 1.2.1

package/CHANGELOG.md

@@ -1,14 +1,12 @@
-# Changelog
-
 ## [Unreleased]
 
-## [1.1.27] - 2026-10-07
+## [1.2.0] - 2026-10-12
 
-- 版本线推进至 1.1.27；本版无独立用户可见变化。
+- Added `getNativeGrammarsDir()`, where the native addon loads downloaded tree-sitter grammars from (`~/.zeta/natives/grammars`).
 
-### Breaking Changes
+## [1.1.27] - 2026-10-07
 
-- Replaced the `cursorPosition` option of `TerminalQueryResponder` with `hostCursorHandshake`, which leaves only the PTY host's own session-start cursor query unanswered instead of every cursor-position query
+- 版本线推进至 1.1.27；本版无独立用户可见变化。
 
 ## [1.1.25] - 2026-10-03
 

package/README.md

@@ -8,7 +8,7 @@ Shared utilities for [omp](https://github.com/can1357/oh-my-pi) packages. Zero c
 | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
 | `logger`                                                                                                           | Centralized logger writing to `~/.zeta/logs/` with rotation (TUI-safe — never stdout)         |
 | `prompt`                                                                                                           | Handlebars-based prompt templating and formatting helpers                                    |
-| `dirs`                                                                                                             | Path helpers for omp config directories (`~/.zeta`, XDG-aware on Linux)                       |
+| `dirs`                                                                                                             | Path helpers for zetacode config directories (`~/.zeta`, XDG-aware on Linux)                       |
 | `stream`                                                                                                           | `readStream` / `readLines` helpers over `ReadableStream`                                     |
 | `ptree` / `procmgr`                                                                                                | Process trees, `ChildProcess` wrapper, process lifecycle management                          |
 | `postmortem`                                                                                                       | Cleanup callbacks on exit, signals, and fatal exceptions                                     |

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/color.d.ts

@@ -111,6 +111,8 @@ export declare function oklchCusp(h: number): {
     l: number;
     c: number;
 };
+/** Angular distance between two hues in degrees (0–180), wrapping at 360. */
+export declare function hueDistance(a: number, b: number): number;
 /**
  * Convert OKLCH to a CSS hex string, gamut-mapping by chroma reduction.
  *

package/dist/types/dirs.d.ts

@@ -1,22 +1,23 @@
 /**
- * Centralized path helpers for zeta-c config directories.
+ * Centralized path helpers for zetacode config directories.
  *
  * Uses PI_CONFIG_DIR (default ".zeta") for the config root and
+ * Uses ZETA_CONFIG_DIR (default ".zeta") for the config root and
  * ZETA_CODING_AGENT_DIR to override the agent directory.
  *
  * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
  * variables are set, paths are redirected to XDG-compliant locations under
- * $XDG_*_HOME/zeta/. This requires running `zeta-c config migrate` first to
+ * $XDG_*_HOME/zeta/. This requires running `zetacode config migrate` first to
  * move data to the new locations. No filesystem existence checks are performed
  * — if the env var is set, zeta trusts that the migration has been done.
  */
 /** App name (e.g. "zeta") — product-level identity: config-dir root, log file
  * names, provider attribution headers, splash wordmark. NOT the CLI command. */
 export declare const APP_NAME: string;
-/** CLI binary name (`npm i -g @linxiraos/zeta` installs `zeta-c`, with
- * `zeta-cli` and `zetacode` as aliases). Every user-facing "run this command"
- * string and process title uses this; the bare `zeta` name belongs to the
- * @linxiraos/main workspace product, not this package. */
+/** CLI binary name (`npm i -g @linxiraos/zeta` installs `zetacode`, with
+ * `zetacode` and `zeta-cli` as compatibility aliases). Every user-facing "run
+ * this command" string and process title uses this; the bare `zeta` name
+ * belongs to the @linxiraos/main workspace product, not this package. */
 export declare const CLI_BIN_NAME: string;
 /** Public homepage that inference gateways (OpenRouter, Vercel AI Gateway) credit our traffic to. */
 export declare const APP_URL: string;
@@ -91,7 +92,7 @@ export declare function directoryIsEnterableSync(dir: string): boolean;
  * Used by spawns that must preserve project-relative behavior when healthy.
  */
 export declare function getSafeProjectCwd(): string;
-/** Get the config directory name relative to home (e.g. ".zeta" or PI_CONFIG_DIR override). */
+/** Get the config directory name relative to home (e.g. ".zeta" or ZETA_CONFIG_DIR override). */
 export declare function getConfigDirName(): string;
 /** Get the config agent directory name relative to home (e.g. ".zeta/agent" or PI_CONFIG_DIR + "/agent"). */
 export declare function getConfigAgentDirName(): string;
@@ -166,10 +167,21 @@ export declare function getPluginsDir(home?: string): string;
 export declare function getPluginsNodeModules(home?: string): string;
 /** Plugin manifest (~/.zeta/plugins/package.json). */
 export declare function getPluginsPackageJson(home?: string): string;
-/** Plugin lock file (~/.zeta/plugins/omp-plugins.lock.json). The on-disk
- * filename stays upstream-compatible so existing installs keep their runtime
- * state (enabled features, versions) across upgrades — never rebrand it. */
+/**
+ * Plugin lock file (~/.zeta/plugins/omp-plugins.lock.json).
+ *
+ * The on-disk filename stays upstream-compatible: it carries per-plugin runtime
+ * state (enabled flag, version), so renaming it would reset every existing
+ * install's plugins on upgrade. That is the reason for the compat, not a
+ * general rule — see `document/brand-surface-rules.md`, which classifies this
+ * surface as DUAL (read both spellings, write the Zeta one) rather than
+ * permanently frozen.
+ */
 export declare function getPluginsLockfile(home?: string): string;
+/** Zeta-named lockfile, written going forward; `getPluginsLockfile` is read first. */
+export declare const PLUGINS_LOCKFILE_CANONICAL = "zeta-plugins.lock.json";
+/** Pre-rename lockfile name still produced by earlier installs. */
+export declare const PLUGINS_LOCKFILE_LEGACY = "omp-plugins.lock.json";
 /**
  * Normalize a plugin id into a safe single path segment (spec §4.2): lowercased,
  * every character outside `[a-z0-9._-]` (including `/` and `\`, so scoped npm
@@ -204,11 +216,11 @@ export declare function adoptLegacyFileOnce(legacyPath: string, targetPath: stri
 export declare function getRemoteDir(): string;
 /**
  * Relocate the base directory for agent-managed worktrees (PR checkouts, task
- * isolation, and `zeta worktree` cleanup all read the same base). Driven by the
+ * isolation, and `zetacode worktree` cleanup all read the same base). Driven by the
  * `worktree.base` setting in coding-agent; pass `undefined`/empty to clear and
  * fall back to `OMP_WORKTREE_DIR` or the `~/.zeta/wt` default.
  *
- * `~` is expanded and a relative path is rejected (see {@link resolveWorktreeBase}).
+ * `~` is expanded and a relative path is rejected (see {@link resolveAbsoluteDir}).
  * Returns the absolute path that took effect, or `undefined` if the input was
  * cleared or rejected — callers can warn on a non-empty input that returns
  * `undefined`.
@@ -283,6 +295,13 @@ export declare function getFastembedCacheDir(): string;
 /** Get the on-demand fastembed runtime install root (~/.zeta/cache/fastembed-runtime). */
 export declare function getFastembedRuntimeDir(): string;
 /** Get the natives directory (~/.zeta/natives). */
+/**
+ * Get the directory the native addon loads downloaded tree-sitter wasm
+ * grammars from (`<natives dir>/grammars`, `~/.zeta/natives/grammars`). The
+ * natives loader configures the addon with the same path.
+ */
+export declare function getNativeGrammarsDir(): string;
+/** Get the natives directory. PI_NATIVES_DIR overrides the usual cache root; relative values are ignored. */
 export declare function getNativesDir(): string;
 /** Get the stats database path (~/.zeta/stats.db). */
 export declare function getStatsDbPath(): string;

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/index.d.ts

@@ -29,6 +29,7 @@ export * as procmgr from "./procmgr.js";
 export * as prompt from "./prompt.js";
 export * as ptree from "./ptree.js";
 export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree.js";
+export * from "./release-assets.js";
 export * from "./runtime-install.js";
 export * from "./sanitize-text.js";
 export * from "./snowflake.js";

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/loop-phase.d.ts

@@ -1,10 +1,15 @@
+/** A label and its exclusive in-window time, as named by {@link takeLoopPhaseAttribution}. */
+export interface LoopPhaseAttribution {
+    readonly label: string;
+    /** Total time this label was the innermost active phase inside the late window [start, end]. */
+    readonly ms: number;
+}
 export declare function pushLoopPhase(label: string): void;
 export declare function popLoopPhase(): void;
 export declare function currentLoopPhase(): string | undefined;
-/**
- * Phase to blame for a just-detected loop block: the live top phase if one is
- * still held, else the most recent phase pushed since the last call. Clears the
- * recent slot so a block in a later, phase-less interval is not misattributed
- * to a phase that already finished.
- */
-export declare function takeRecentLoopPhase(): string | undefined;
+/** Run `fn` under `label`. For an async `fn`, only its synchronous prefix (up to its first await) is labeled; label each continuation separately. */
+export declare function withLoopPhase<T>(label: string, fn: () => T): T;
+/** Arm an attribution window starting at `start` (a deadline on `now`'s clock). Called with no arguments it disarms and clears. */
+export declare function resetLoopPhaseWindow(start?: number, now?: () => number): void;
+/** Attribute the window [start, end] and disarm it. Returns undefined when no window is armed or no label outweighs unlabeled time. */
+export declare function takeLoopPhaseAttribution(end?: number): LoopPhaseAttribution | undefined;

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 `@linxiraos/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/release-assets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Published CLI release-asset naming — the one contract shared by the release
+ * build (`scripts/ci-release-build-binaries.ts` outfiles), the CI upload matrix
+ * (`.github/workflows/ci.yml` `release_binary.binary_path`), the installers
+ * (`scripts/install.sh` / `install.ps1`) and the updater's binary fallback.
+ *
+ * Assets are `zeta-cli-<os>-<arch>[.exe]`. `zeta-cli` is the *file-name* face
+ * of the package and deliberately does NOT follow {@link CLI_BIN_NAME}
+ * (`zetacode`, the user-visible command face): the brand cutover moved the
+ * command name, and the updater's asset name drifted with it, so every binary
+ * fallback asked GitHub for `zetacode-*` assets no release carries (v1.1.27 /
+ * main). `scripts/check-release-asset-names.ts` pins both sides together.
+ */
+/**
+ * Leading token of every published CLI binary asset, separator included:
+ * assets are `<prefix><os>[-musl]-<arch>[.exe]`.
+ */
+export declare const RELEASE_CLI_ASSET_PREFIX = "zeta-cli-";
+/** Release asset for a CLI binary, e.g. `zeta-cli-windows-x64.exe`. */
+export declare function releaseCliAssetName(platform: NodeJS.Platform, arch: string, options?: {
+    musl?: boolean;
+}): string;

package/dist/types/temp.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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 declare class TempDir {
     #private;
     private constructor();

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": "@linxiraos/pi-utils",
-	"version": "1.1.27",
+	"version": "1.2.1",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"utilities",
@@ -54,10 +54,10 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.1.27"
+		"@linxiraos/pi-natives": "1.2.1"
 	},
 	"devDependencies": {
-		"@types/bun": "^1.3.14"
+		"@types/bun": "1.4.3"
 	},
 	"engines": {
 		"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/open.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { formatBytes } from "../format";
+import { hasFsCode } from "../fs-error";
 import { UTF8_DECODER } from "./bytes";
 import { ArchiveError } from "./error";
 import { type ArchiveLimits, assertInMemorySize, DEFAULT_ARCHIVE_LIMITS } from "./limits";
@@ -179,17 +180,15 @@ export async function extractArchive(
 		if (outputPath !== extractRoot && !outputPath.startsWith(extractRoot + path.sep)) {
 			throw new ArchiveError(`Archive entry escapes extraction dir: ${entry.path}`);
 		}
-		if (entry.isDirectory) {
-			if (entry.storage?.type !== "link") {
-				await fs.mkdir(outputPath, { recursive: true });
-				count++;
-			}
-			continue;
-		}
 		if (entry.storage?.type === "link") {
 			links.push({ path: entry.path, target: entry.storage.targetPath });
 			continue;
 		}
+		if (entry.isDirectory) {
+			await fs.mkdir(outputPath, { recursive: true });
+			count++;
+			continue;
+		}
 		files.push({ path: entry.path, mode: entry.mode });
 	}
 
@@ -217,7 +216,29 @@ export async function extractArchive(
 			throw new ArchiveError(`Archive symlink escapes extraction dir: ${link.path} -> ${link.target}`);
 		}
 		await fs.mkdir(path.dirname(outputPath), { recursive: true });
-		await fs.symlink(path.relative(path.dirname(outputPath), resolvedTarget) || ".", outputPath);
+		const relativeTarget = path.relative(path.dirname(outputPath), resolvedTarget) || ".";
+		const linkType = process.platform === "win32" && archive.getNode(link.path)?.isDirectory ? "dir" : "file";
+		try {
+			await fs.symlink(relativeTarget, outputPath, linkType);
+		} catch (error) {
+			if (process.platform !== "win32" || !hasFsCode(error, "EPERM")) throw error;
+			// Windows without the symlink privilege: degrade to a directory
+			// junction or a file copy so extraction still yields usable
+			// content instead of failing the whole archive.
+			if (linkType === "dir") {
+				await fs.symlink(resolvedTarget, outputPath, "junction");
+			} else {
+				// Resolve through the archive, not the extraction order: this
+				// link may target another link that has not materialized yet.
+				// A dangling target cannot be copied without the symlink
+				// privilege; skip the entry so the rest still extracts.
+				const extracted = await archive.readFile(link.path).catch(() => undefined);
+				if (!extracted) continue;
+				await Bun.write(outputPath, extracted.bytes);
+				const permissions = (extracted.mode ?? 0) & 0o777;
+				if (permissions) await fs.chmod(outputPath, permissions);
+			}
+		}
 		count++;
 	}
 

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;
+	}
+}