@oh-my-pi/pi-utils 18.14.1 → 18.15.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [18.15.0] - 2026-11-01
+
+### Added
+
+- Added abortable `sleepUntil` for wall-clock deadline waits that include system sleep, with bounded timer slices to recheck deadlines after resume ([#17606](https://github.com/can1357/oh-my-pi/pull/17606) by [@zhiland](https://github.com/zhiland)).
+
+### Fixed
+
+- Importing pi-utils no longer installs process-wide signal and fatal handlers in embedding hosts; exit-time cleanup stays installed ([#17674](https://github.com/can1357/oh-my-pi/issues/17674)).
+
+## [18.14.2] - 2026-10-31
+
+### Added
+
+- Added `oklabDistance`, the perceptual distance between two hex colors ([#17520](https://github.com/can1357/oh-my-pi/pull/17520))
+
 ## [18.14.1] - 2026-10-31
 
 ### Added

package/dist/types/async.d.ts

@@ -16,6 +16,11 @@ export declare const MAX_TIMER_DELAY_MS = 2147483647;
  * the unelapsed duration instead of shortening the requested sleep.
  */
 export declare function sleepLong(delayMs: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Wait for a wall-clock deadline, including time spent suspended. Some platforms
+ * exclude suspend from relative timers, so recheck at least once per second.
+ */
+export declare function sleepUntil(deadlineMs: number, signal?: AbortSignal): Promise<void>;
 /**
  * Wrap a promise with a timeout and optional abort signal.
  * Rejects with the given error or a new error containing the given message if

package/dist/types/color.d.ts

@@ -99,6 +99,8 @@ export interface OKLCH {
  * hues, so carrying them between colors preserves the palette's "weight".
  */
 export declare function hexToOklch(hex: string): OKLCH;
+/** Perceptual distance between two hex colors: Euclidean OKLab, 0 when identical, 1 from black to white. */
+export declare function oklabDistance(a: string, b: string): number;
 /**
  * The sRGB gamut cusp for an OKLCH hue: the lightness/chroma point where the
  * hue reaches its maximum chroma inside sRGB.

package/dist/types/postmortem.d.ts

@@ -178,6 +178,8 @@ export declare function registerFatalRecoveryHint(provider: FatalRecoveryHintPro
  * Reports a caught top-level failure after terminal owners restore their display, then exits.
  */
 export declare function fatal(error: unknown): Promise<never>;
+/** Installs OMP's process-wide signal and fatal handlers for a CLI-owned process. */
+export declare function installProcessHandlers(): void;
 /** Controls when a registered cleanup callback participates in cleanup passes. */
 export interface CleanupRegistrationOptions {
     /**
@@ -201,8 +203,7 @@ export interface CleanupRegistrationOptions {
     waitMessage?: string;
 }
 /**
- * Registers a cleanup callback for shutdown, signals, fatal errors, and
- * repeatable manual cleanup passes.
+ * Registers a cleanup callback for manual passes and, when installed, process shutdown.
  *
  * Registrations persist across keep-alive {@link cleanup} passes and run at
  * most once per pass. Set `exitOnly` for resources the continuing process still

package/package.json

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

package/src/async.ts

@@ -29,6 +29,19 @@ export async function sleepLong(delayMs: number, signal?: AbortSignal): Promise<
 	}
 }
 
+/**
+ * Wait for a wall-clock deadline, including time spent suspended. Some platforms
+ * exclude suspend from relative timers, so recheck at least once per second.
+ */
+export async function sleepUntil(deadlineMs: number, signal?: AbortSignal): Promise<void> {
+	while (true) {
+		signal?.throwIfAborted();
+		const remaining = deadlineMs - Date.now();
+		if (!(remaining > 0)) return;
+		await scheduler.wait(Math.min(remaining, 1_000), { signal });
+	}
+}
+
 /**
  * Wrap a promise with a timeout and optional abort signal.
  * Rejects with the given error or a new error containing the given message if

package/src/color.ts

@@ -311,6 +311,12 @@ function oklabToLinearRgb(L: number, a: number, b: number): { r: number; g: numb
 	};
 }
 
+/** Convert a hex color to OKLab. */
+function hexToOklab(hex: string): { L: number; a: number; b: number } {
+	const rgb = hexToRgb(hex);
+	return linearRgbToOklab(linearizeChannel(rgb.r), linearizeChannel(rgb.g), linearizeChannel(rgb.b));
+}
+
 /**
  * Convert a hex color to OKLCH (perceptual lightness/chroma/hue).
  *
@@ -318,14 +324,20 @@ function oklabToLinearRgb(L: number, a: number, b: number): { r: number; g: numb
  * hues, so carrying them between colors preserves the palette's "weight".
  */
 export function hexToOklch(hex: string): OKLCH {
-	const rgb = hexToRgb(hex);
-	const lab = linearRgbToOklab(linearizeChannel(rgb.r), linearizeChannel(rgb.g), linearizeChannel(rgb.b));
+	const lab = hexToOklab(hex);
 	const c = Math.hypot(lab.a, lab.b);
 	let h = (Math.atan2(lab.b, lab.a) * 180) / Math.PI;
 	if (h < 0) h += 360;
 	return { l: lab.L, c, h };
 }
 
+/** Perceptual distance between two hex colors: Euclidean OKLab, 0 when identical, 1 from black to white. */
+export function oklabDistance(a: string, b: string): number {
+	const x = hexToOklab(a);
+	const y = hexToOklab(b);
+	return Math.hypot(x.L - y.L, x.a - y.a, x.b - y.b);
+}
+
 /**
  * Max OKLab saturation (C/L) that stays inside sRGB for the hue direction
  * `(a, b)`, via Björn Ottosson's polynomial fit plus one Halley refinement.

package/src/postmortem.ts

@@ -307,9 +307,7 @@ function runCleanup(reason: Reason, keepAlive = false): Promise<void> {
 	return cleanupPromise;
 }
 
-// Register signal and error event handlers to trigger cleanup before exit.
-// Main thread: full signal handling (SIGINT, SIGTERM, SIGHUP) + exceptions + exit
-// Worker thread: exit only (workers use self.addEventListener for exceptions)
+// CLI-owned main threads handle signals and fatal errors; workers handle exit only.
 let inspectorOpened = false;
 
 /** Origin of an EPIPE raised by a process communication channel. */
@@ -558,13 +556,47 @@ export function isExpectedCleanupError(reason: unknown): boolean {
 /** Interceptors consulted by the global `unhandledRejection` handler before the fatal path. */
 const rejectionInterceptors = new Set<(reason: unknown) => boolean>();
 
+function interceptRejection(reason: unknown): boolean {
+	for (const interceptor of rejectionInterceptors) {
+		try {
+			if (interceptor(reason)) return true;
+		} catch (interceptorErr) {
+			logger.warn("Unhandled-rejection interceptor threw; continuing with fatal path", { err: interceptorErr });
+		}
+	}
+	return false;
+}
+
+/**
+ * Without the CLI's handlers (SDK embedding), interceptors still need a listener. It exists only while
+ * interceptors do, and rethrows what none consumes unless the host listens too, keeping Bun's default.
+ */
+let embeddedRejectionListener: ((reason: unknown) => void) | undefined;
+
 /**
  * Register an interceptor consulted before an unhandled rejection tears the
  * process down. A consuming interceptor owns reporting and keeps the process alive.
  */
 export function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void {
 	rejectionInterceptors.add(interceptor);
-	return () => rejectionInterceptors.delete(interceptor);
+	if (!processHandlersInstalled && Bun.isMainThread && !embeddedRejectionListener) {
+		const listener = (reason: unknown) => {
+			if (interceptRejection(reason) || process.listenerCount("unhandledRejection") > 1) return;
+			throw reason;
+		};
+		embeddedRejectionListener = listener;
+		process.on("unhandledRejection", listener);
+	}
+	return () => {
+		rejectionInterceptors.delete(interceptor);
+		if (rejectionInterceptors.size === 0) removeEmbeddedRejectionListener();
+	};
+}
+
+function removeEmbeddedRejectionListener(): void {
+	if (!embeddedRejectionListener) return;
+	process.off("unhandledRejection", embeddedRejectionListener);
+	embeddedRejectionListener = undefined;
 }
 
 /**
@@ -685,7 +717,22 @@ export async function fatal(error: unknown): Promise<never> {
 	return exitAfterFatal(report, "Fatal error", err, Reason.UNHANDLED_REJECTION);
 }
 
-if (Bun.isMainThread) {
+// Exit-time cleanup is safe in any host: it neither delays nor triggers an exit. Signal and fatal
+// handlers change the process lifecycle, so only {@link installProcessHandlers} adds them.
+process.on("exit", () => {
+	void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
+});
+
+let processHandlersInstalled = false;
+
+/** Installs OMP's process-wide signal and fatal handlers for a CLI-owned process. */
+export function installProcessHandlers(): void {
+	if (processHandlersInstalled) return;
+	processHandlersInstalled = true;
+	removeEmbeddedRejectionListener();
+	// Workers report failures through their own error listeners to the parent.
+	if (!Bun.isMainThread) return;
+
 	process
 		.on("SIGINT", async () => {
 			await runCleanup(Reason.SIGINT);
@@ -745,15 +792,7 @@ if (Bun.isMainThread) {
 				logger.warn("Ignoring expected cleanup rejection", { err });
 				return;
 			}
-			for (const interceptor of rejectionInterceptors) {
-				try {
-					if (interceptor(reason)) return;
-				} catch (interceptorErr) {
-					logger.warn("Unhandled-rejection interceptor threw; continuing with fatal path", {
-						err: interceptorErr,
-					});
-				}
-			}
+			if (interceptRejection(reason)) return;
 			await exitAfterFatal(
 				formatFatalError("Unhandled Rejection", err),
 				"Unhandled rejection",
@@ -761,9 +800,6 @@ if (Bun.isMainThread) {
 				Reason.UNHANDLED_REJECTION,
 			);
 		})
-		.on("exit", async () => {
-			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
-		})
 		.on("SIGTERM", async () => {
 			// A stopped session otherwise leaves its last frame above the shell prompt,
 			// which reads as a crash. A repeated SIGTERM joins the same cleanup and the
@@ -777,14 +813,6 @@ if (Bun.isMainThread) {
 			await runCleanup(Reason.SIGHUP);
 			exitProcess(129); // 128 + SIGHUP (1)
 		});
-} else {
-	// Worker thread: only register exit handler for cleanup.
-	// DO NOT register uncaughtException/unhandledRejection handlers here -
-	// they would swallow errors before the worker's own handlers (self.addEventListener)
-	// can report failures back to the parent thread.
-	process.on("exit", () => {
-		void runCleanup(Reason.EXIT);
-	});
 }
 
 /** Controls when a registered cleanup callback participates in cleanup passes. */
@@ -811,8 +839,7 @@ export interface CleanupRegistrationOptions {
 }
 
 /**
- * Registers a cleanup callback for shutdown, signals, fatal errors, and
- * repeatable manual cleanup passes.
+ * Registers a cleanup callback for manual passes and, when installed, process shutdown.
  *
  * Registrations persist across keep-alive {@link cleanup} passes and run at
  * most once per pass. Set `exitOnly` for resources the continuing process still