@linxiraos/pi-utils 1.1.26 → 1.2.0

package/CHANGELOG.md

@@ -1,10 +1,12 @@
-# Changelog
-
 ## [Unreleased]
 
-## [1.1.26] - 2026-10-03
+## [1.2.0] - 2026-10-12
+
+- Added `getNativeGrammarsDir()`, where the native addon loads downloaded tree-sitter grammars from (`~/.zeta/natives/grammars`).
+
+## [1.1.27] - 2026-10-07
 
-- 版本线推进至 1.1.26；本版无独立用户可见变化。
+- 版本线推进至 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;
@@ -357,6 +376,12 @@ export declare function getDaemonRuntimeDir(projectDir: string): string;
 export declare function getGlobalDaemonRuntimeRoot(): string;
 /** Get a profile-independent runtime directory for a machine-global daemon service. */
 export declare function getGlobalDaemonRuntimeDir(service: string): string;
+/**
+ * Directory naming session ownership leases (~/.zeta/run/session-owners; XDG
+ * default: $XDG_STATE_HOME/zeta/run/session-owners). Shared across profiles:
+ * every omp process that opens a session must meet the same lease.
+ */
+export declare function getSessionOwnersDir(): string;
 /** Get the provider in-flight root directory (~/.zeta/run/provider-inflight; XDG default: $XDG_STATE_HOME/zeta/run/provider-inflight). */
 export declare function getProviderInFlightRoot(): string;
 /** Get the marketplaces registry path (~/.zeta/marketplaces.json; XDG default: $XDG_DATA_HOME/zeta/marketplaces.json). Adopts a legacy registry on first XDG resolution. */

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

@@ -6,6 +6,8 @@
  */
 /** Opening delimiter. Each closer (`$`, `$$`, `\)`, `\]`) is as wide as its opener. */
 export type MathOpener = "$" | "$$" | "\\(" | "\\[";
+/** Opener of an own-line display block. */
+export type MathBlockOpener = "$$" | "\\[";
 /** A closed math span found in the source. */
 export interface MathSpan {
     opener: MathOpener;
@@ -65,3 +67,49 @@ export declare function mathSpanInContext(context: {
 }, src: string): MathSpan | undefined;
 /** The own-line display block starting at offset 0, or `undefined`. */
 export declare function mathBlockAt(source: string): MathBlock | undefined;
+/**
+ * {@link mathBlockAt} for many offsets of one `source`. An own-line opener
+ * whose closer line is missing means every later opener of the same kind
+ * misses one too, since its search covers a suffix of that search. The scan
+ * keeps that answer, so asking at every block start takes linear time instead
+ * of a scan to the end of `source` per unclosed opener.
+ */
+export declare class MathBlockScan {
+    #private;
+    constructor(source: string);
+    /** 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
+ * `undefined`.
+ */
+export declare function mathBlockOpenerAt(source: string, from?: number): MathBlockOpener | undefined;
+/**
+ * Whether the own-line display block opened at `from` in `source` is closed,
+ * or could still close once more text is appended: the text from `from`
+ * onward is a streaming prefix whose real closer may not have arrived. A
+ * closer on the unterminated last line has not arrived either, since the next
+ * append may extend it into text (`$$ E = mc^2 $$`). With no opener line at
+ * `from` it returns false before scanning, so a caller can ask at every block
+ * start.
+ */
+export declare function mathBlockMayCloseAt(source: string, from?: number): boolean;
+/**
+ * Offset of the first line of `source`, from the line start `from` on, that
+ * holds the closer of `opener` alone (up to 3 leading spaces, trailing spaces
+ * or tabs), the unterminated last line included, or `undefined`: the first
+ * line at which a block `opener` opened before `from` could close.
+ */
+export declare function mathBlockCloserIndex(source: string, from: number, opener: MathBlockOpener): number | undefined;

package/dist/types/procmgr.d.ts

@@ -36,26 +36,6 @@ export declare function isPosixShell(shell: string): boolean;
  * Resolve a basic shell (bash or sh) as fallback.
  */
 export declare function resolveBasicShell(): string | undefined;
-/**
- * Resolve the external shell to advertise on Windows.
- *
- * A host bash is OPTIONAL: bash tool commands always execute in the embedded
- * brush-core shell. The resolved binary only serves the spawn-a-shell paths
- * (interactive PTY sessions, ACP client terminals, SHELL env), so this
- * prefers a real Git Bash when one exists and otherwise falls back to
- * cmd.exe — it never fails.
- *
- * Search order:
- * 1. Git for Windows install roots (machine + per-user installers)
- * 2. scoop installs — scoop's git manifest sets GIT_INSTALL_ROOT and shims
- *    sh.exe/git.exe but never bash.exe, so PATH lookup alone misses it
- * 3. bash.exe on PATH (Cygwin, MSYS2, ...)
- * 4. sh.exe on PATH (Git for Windows' sh.exe is bash; prefer a sibling
- *    bash.exe when present)
- * 5. cmd.exe from ComSpec
- *
- * Exported for tests; `env` overrides Bun.env-based discovery.
- */
 export declare function resolveWindowsShell(env?: Record<string, string | undefined>): string;
 /**
  * Get shell configuration based on platform.
@@ -70,6 +50,20 @@ export declare function resolveWindowsShell(env?: Record<string, string | undefi
  * `shellPath` mid-process immediately falls back to the platform default.
  */
 export declare function getShellConfig(customShellPath?: string, options?: ShellConfigOptions): ShellConfig;
+/**
+ * Capture the current process environment for child shells and drop both cached
+ * shell configs, so the next {@link getShellConfig} builds the spawn environment
+ * from that capture. Call right after code that changed `process.env` in a way
+ * child shells must see, such as extension session lifecycle handlers exporting
+ * session-scoped variables; later writes reach child shells only at the next call.
+ */
+export declare function refreshShellConfigCache(): void;
+/**
+ * Test-only: forget the capture and both cached shell configs, so the next
+ * {@link getShellConfig} builds from the live environment again. Production code
+ * MUST NOT call this; the capture's lifecycle is owned by {@link refreshShellConfigCache}.
+ */
+export declare function __resetShellConfigCacheForTests(): void;
 /**
  * Check if a process is running.
  */

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/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/dist/types/vterm/query-responder.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Options for {@link TerminalQueryResponder}.
+ */
+export interface TerminalQueryResponderOptions {
+    /**
+     * The PTY host opens the session with its own cursor-position query
+     * (`CSI 6 n`), which the PTY layer has already answered — ConPTY's
+     * `PSEUDOCONSOLE_INHERIT_CURSOR` handshake. Leave that first cursor query
+     * unanswered: the host consumes exactly one report, so a second one would
+     * reach the program as input it never asked for. Every later cursor query
+     * is answered. Defaults to `false`.
+     */
+    hostCursorHandshake?: boolean;
+}
 /**
  * Answers terminal capability queries emitted by programs on a headless PTY.
  *
@@ -16,6 +30,7 @@
  */
 export declare class TerminalQueryResponder {
     #private;
+    constructor(options?: TerminalQueryResponderOptions);
     /**
      * Feed one raw PTY output chunk. Returns the reply bytes to write back into
      * the PTY, or an empty string when the chunk held no answerable query.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-utils",
-	"version": "1.1.26",
+	"version": "1.2.0",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"utilities",
@@ -54,7 +54,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.1.26"
+		"@linxiraos/pi-natives": "1.2.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";