@oh-my-pi/pi-utils 18.8.8 → 18.9.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [18.9.0] - 2026-10-11
+
+### Breaking Changes
+
+- Renamed `takeRecentLoopPhase()` to `takeLoopPhaseAttribution()`. The new API returns a `LoopPhaseAttribution` object (`{ label, ms }`) and reports a label only when it accounts for more time than unlabeled work within an armed measurement window.
+
+### Added
+
+- Added `withLoopPhase(label, fn)` for attributing synchronous work to a named loop phase, with automatic cleanup even when the callback throws.
+
+### Changed
+
+- Improved streaming JSON parsing performance for long tool-argument payloads.
+
+### Fixed
+
+- Fixed archive extraction on Windows systems without symlink privileges by allowing symlink entries to be extracted using supported fallbacks, while skipping unresolvable dangling links instead of failing the entire archive.
+
+## [18.8.9] - 2026-10-10
+
+### Added
+
+- Added `hueDistance`, the angular distance between two OKLCH hues
+
 ## [18.8.8] - 2026-10-10
 
 ### Fixed

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/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.8.8",
+	"version": "18.9.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.8.8"
+		"@oh-my-pi/pi-natives": "18.9.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

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

@@ -399,6 +399,12 @@ export function oklchCusp(h: number): { l: number; c: number } {
 	return { l: lCusp, c: lCusp * sCusp };
 }
 
+/** Angular distance between two hues in degrees (0–180), wrapping at 360. */
+export function hueDistance(a: number, b: number): number {
+	const d = Math.abs(a - b) % 360;
+	return Math.min(d, 360 - d);
+}
+
 /** Slack allowed on linear channels before a color counts as out of sRGB gamut. */
 const GAMUT_EPSILON = 1e-4;
 

package/src/json-lexer.ts

@@ -32,6 +32,16 @@ export const LBRACKET = 0x5b;
 export const RBRACKET = 0x5d;
 const U = 0x75;
 
+/**
+ * Minimum remaining string length for bulk-skipping ordinary characters in
+ * {@link JsonLexer.string} with two engine `indexOf` scans (nearest quote or
+ * backslash) instead of one `charCodeAt` per character. Below this the
+ * `indexOf` setup costs more than the per-char loop on quote-dense input;
+ * long string runs — the multi-KB tool-argument payloads that dominate
+ * streaming re-parses — scan several times faster above it.
+ */
+const STRING_BULK_SCAN_MIN = 32;
+
 /** Valid chars after `\` in a strict JSON escape: `" \ / b f n r t u`. */
 export const VALID_ESCAPE_CHAR = new Uint8Array(128);
 for (const ch of '"\\/bfnrtu') VALID_ESCAPE_CHAR[ch.charCodeAt(0)] = 1;
@@ -218,7 +228,33 @@ export class JsonLexer {
 		// malformed structure fails loudly instead of silently swallowing
 		// commas/colons or sibling members.
 		const lenient = quote === SQUOTE || this.mode === "streaming";
+		const quoteChar = quote === QUOTE ? '"' : "'";
+		// Next quote / backslash at or after the cursor, cached across iterations
+		// and re-searched only once the cursor passes them, so every character is
+		// scanned at most once per kind and the bulk path stays linear even on
+		// escape-dense input (re-searching the far closing quote after each
+		// escape would be quadratic). `n` means "none before end of input".
+		let nextQuote = -1;
+		let nextBackslash = -1;
 		while (i < n) {
+			// Bulk-skip a run of ordinary characters: jump to the nearest quote or
+			// backslash instead of one `charCodeAt` per character. Only entered on
+			// an ordinary character, so back-to-back escapes never pay an `indexOf`;
+			// short tails keep the per-char loop. Landing on a special char falls
+			// through to the unchanged handling below, so tokens are identical.
+			const c0 = s.charCodeAt(i);
+			if (c0 !== BACKSLASH && c0 !== quote && n - i > STRING_BULK_SCAN_MIN) {
+				if (nextQuote < i) {
+					const q = s.indexOf(quoteChar, i);
+					nextQuote = q === -1 ? n : q;
+				}
+				if (nextBackslash < i) {
+					const b = s.indexOf("\\", i);
+					nextBackslash = b === -1 ? n : b;
+				}
+				i = nextQuote < nextBackslash ? nextQuote : nextBackslash;
+				if (i >= n) break;
+			}
 			const cc = s.charCodeAt(i);
 			if (cc !== BACKSLASH && cc !== quote) {
 				i++;

package/src/loop-phase.ts

@@ -1,8 +1,16 @@
+/** 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;
+}
+
 /**
- * Live event-loop phase breadcrumb. Hot synchronous paths push a short label
- * before running and pop it after (via `try`/`finally`); the loop watchdog
- * reads {@link takeRecentLoopPhase} when it detects a block, so a stall is
- * logged with the work that caused it instead of an opaque "unknown".
+ * Process-global synchronous loop phases. The watchdog arms a late window and
+ * reads attribution via {@link takeLoopPhaseAttribution}; attribution totals
+ * only the innermost label's time inside that window. A label is named only
+ * when its total outweighs all unlabeled time, otherwise the block remains
+ * "unknown". Disarmed push/pop do not read the clock.
  *
  * This is deliberately a process-global stack and not part of the logger span
  * machinery: `main.ts` ends timing spans before the interactive TUI starts, so
@@ -16,19 +24,31 @@
  * work, push/pop around each synchronous chunk, not across the await.
  */
 const stack: string[] = [];
-// The most recent label pushed, retained after it is popped. A hot path pushes
-// and pops a phase entirely within one synchronous macrotask, so by the time
-// the watchdog's delayed tick runs the stack is already empty; this slot keeps
-// the culprit available for that one tick. Consumed (cleared) on read so it
-// only attributes the just-elapsed interval.
-let recentPhase: string | undefined;
+const defaultClock = () => performance.now();
+let windowStart = Number.POSITIVE_INFINITY;
+let segmentStart = windowStart;
+let clock = defaultClock;
+const totals = new Map<string, number>();
+let labeledMs = 0;
+
+function boundary(t: number): void {
+	const ms = Math.max(0, t - Math.max(segmentStart, windowStart));
+	const label = stack[stack.length - 1];
+	if (label !== undefined && ms > 0) {
+		totals.set(label, (totals.get(label) ?? 0) + ms);
+		labeledMs += ms;
+	}
+	segmentStart = t;
+}
 
 export function pushLoopPhase(label: string): void {
+	if (windowStart !== Number.POSITIVE_INFINITY) boundary(clock());
 	stack.push(label);
-	recentPhase = label;
 }
 
 export function popLoopPhase(): void {
+	if (stack.length === 0) return;
+	if (windowStart !== Number.POSITIVE_INFINITY) boundary(clock());
 	stack.pop();
 }
 
@@ -36,14 +56,39 @@ export function currentLoopPhase(): string | undefined {
 	return stack[stack.length - 1];
 }
 
-/**
- * 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 function takeRecentLoopPhase(): string | undefined {
-	const phase = stack[stack.length - 1] ?? recentPhase;
-	recentPhase = undefined;
-	return phase;
+/** Run `fn` under `label`. For an async `fn`, only its synchronous prefix (up to its first await) is labeled; label each continuation separately. */
+export function withLoopPhase<T>(label: string, fn: () => T): T {
+	pushLoopPhase(label);
+	try {
+		return fn();
+	} finally {
+		popLoopPhase();
+	}
+}
+
+/** Arm an attribution window starting at `start` (a deadline on `now`'s clock). Called with no arguments it disarms and clears. */
+export function resetLoopPhaseWindow(start = Number.POSITIVE_INFINITY, now: () => number = defaultClock): void {
+	windowStart = segmentStart = start;
+	clock = now;
+	totals.clear();
+	labeledMs = 0;
+}
+
+/** Attribute the window [start, end] and disarm it. Returns undefined when no window is armed or no label outweighs unlabeled time. */
+export function takeLoopPhaseAttribution(end?: number): LoopPhaseAttribution | undefined {
+	if (windowStart === Number.POSITIVE_INFINITY) return undefined;
+	const t = end ?? clock();
+	boundary(t);
+	const unknownMs = Math.max(0, t - windowStart - labeledMs);
+	let winner: string | undefined;
+	let winnerMs = 0;
+	for (const [label, ms] of totals) {
+		if (ms >= winnerMs) {
+			winner = label;
+			winnerMs = ms;
+		}
+	}
+	const result = winner !== undefined && winnerMs > unknownMs ? { label: winner, ms: winnerMs } : undefined;
+	resetLoopPhaseWindow();
+	return result;
 }