@oh-my-pi/pi-coding-agent 15.6.0 → 15.7.1

package/src/modes/setup-wizard/wizard-overlay.ts

@@ -0,0 +1,275 @@
+import { type Component, matchesKey, padding, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
+import { APP_NAME } from "@oh-my-pi/pi-utils";
+import { gradientLogo, PI_LOGO } from "../components/welcome";
+import { theme } from "../theme/theme";
+import type { InteractiveModeContext } from "../types";
+import { renderSetupOutro, SETUP_OUTRO_MS } from "./scenes/outro";
+import { renderSetupSplash, SETUP_SPLASH_MS, SETUP_TICK_MS } from "./scenes/splash";
+import type { SetupScene, SetupSceneController, SetupSceneHost, SetupSceneResult } from "./scenes/types";
+
+type WizardPhase = "splash" | "transition" | "scene" | "outro" | "done";
+
+const SCENE_MARGIN_X = 4;
+const MIN_CONTENT_WIDTH = 20;
+/** Cross-dissolve duration from the splash into the first scene. */
+const SCENE_TRANSITION_MS = 420;
+
+function centerLine(line: string, width: number): string {
+	const lineWidth = visibleWidth(line);
+	if (lineWidth >= width) return truncateToWidth(line, width);
+	const left = Math.floor((width - lineWidth) / 2);
+	return padding(left) + line + padding(width - left - lineWidth);
+}
+
+function clampLine(line: string, width: number): string {
+	const truncated = truncateToWidth(line, width);
+	return truncated + padding(Math.max(0, width - visibleWidth(truncated)));
+}
+
+function indentLine(line: string, width: number, indent: number): string {
+	const prefix = padding(Math.min(indent, Math.max(0, width - 1)));
+	return clampLine(prefix + line, width);
+}
+/** Stable per-row jitter in [0,1) for the dissolve reveal order. */
+function rowNoise(y: number): number {
+	const h = Math.imul(y ^ 0x9e3779b9, 2654435761);
+	return ((h ^ (h >>> 15)) >>> 0) / 4294967296;
+}
+
+/**
+ * Top-biased cross-dissolve between two equal-height frames. As `progress`
+ * (0..1) advances, each row flips from `from` to `to` once it crosses a per-row
+ * threshold — top rows reveal first (so the scene's mark/header materializes
+ * before the splash water below it), with a little jitter for an organic edge.
+ */
+function dissolveFrames(from: string[], to: string[], progress: number, height: number): string[] {
+	const eased = progress * progress * (3 - 2 * progress);
+	const denom = Math.max(1, height - 1);
+	const out: string[] = [];
+	for (let y = 0; y < height; y++) {
+		const threshold = 0.78 * (y / denom) + 0.22 * rowNoise(y);
+		out.push((eased >= threshold ? to[y] : from[y]) ?? "");
+	}
+	return out;
+}
+
+export class SetupWizardComponent implements Component {
+	#phase: WizardPhase = "splash";
+	#phaseStartedAt = performance.now();
+	#sceneIndex = 0;
+	#activeScene: SetupSceneController | undefined;
+	#timer: NodeJS.Timeout | undefined;
+	#done = Promise.withResolvers<void>();
+	#disposed = false;
+
+	constructor(
+		readonly ctx: InteractiveModeContext,
+		readonly scenes: readonly SetupScene[],
+	) {}
+
+	run(): Promise<void> {
+		this.#phase = this.scenes.length === 0 ? "outro" : "splash";
+		this.#phaseStartedAt = performance.now();
+		this.#startTimer();
+		this.ctx.ui.requestRender();
+		return this.#done.promise;
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+		this.#stopTimer();
+		this.#unmountActiveScene();
+	}
+
+	invalidate(): void {
+		this.#activeScene?.invalidate();
+	}
+
+	handleInput(data: string): void {
+		if (this.#phase === "done") return;
+		if (matchesKey(data, "ctrl+c")) {
+			this.#beginOutro();
+			return;
+		}
+		if (this.#phase === "splash") {
+			if (
+				matchesKey(data, "enter") ||
+				matchesKey(data, "return") ||
+				matchesKey(data, "space") ||
+				matchesKey(data, "escape")
+			) {
+				this.#beginScene();
+			}
+			return;
+		}
+		if (this.#phase === "outro") {
+			if (
+				matchesKey(data, "enter") ||
+				matchesKey(data, "return") ||
+				matchesKey(data, "space") ||
+				matchesKey(data, "escape")
+			) {
+				this.#complete();
+			}
+			return;
+		}
+		this.#activeScene?.handleInput?.(data);
+	}
+
+	render(width: number): string[] {
+		const safeWidth = Math.max(1, width);
+		const height = Math.max(1, this.ctx.ui.terminal.rows);
+		let lines: string[];
+		switch (this.#phase) {
+			case "splash":
+				lines = renderSetupSplash(safeWidth, height, performance.now() - this.#phaseStartedAt);
+				break;
+			case "transition": {
+				const elapsed = performance.now() - this.#phaseStartedAt;
+				const progress = Math.min(1, elapsed / SCENE_TRANSITION_MS);
+				const splash = renderSetupSplash(safeWidth, height, SETUP_SPLASH_MS + elapsed);
+				const scene = this.#renderScene(safeWidth, height);
+				lines = dissolveFrames(splash, scene, progress, height);
+				break;
+			}
+			case "outro":
+				lines = renderSetupOutro(safeWidth, height, performance.now() - this.#phaseStartedAt);
+				break;
+			case "scene":
+				lines = this.#renderScene(safeWidth, height);
+				break;
+			case "done":
+				lines = [];
+				break;
+		}
+		return this.#fitToScreen(lines, safeWidth, height);
+	}
+
+	#renderScene(width: number, height: number): string[] {
+		const scene = this.scenes[this.#sceneIndex];
+		const title = this.#activeScene?.title ?? scene?.title ?? "Setup";
+		const subtitle = this.#activeScene?.subtitle;
+		const contentWidth = Math.max(MIN_CONTENT_WIDTH, width - SCENE_MARGIN_X * 2);
+		const logo = gradientLogo(PI_LOGO, 0);
+		const header = [
+			"",
+			...logo.map(line => centerLine(line, width)),
+			centerLine(theme.bold(theme.fg("accent", APP_NAME)), width),
+			centerLine(theme.fg("muted", `Setup step ${this.#sceneIndex + 1} of ${this.scenes.length}`), width),
+			"",
+			indentLine(theme.bold(title), width, SCENE_MARGIN_X),
+		];
+		if (subtitle) {
+			header.push(indentLine(theme.fg("muted", subtitle), width, SCENE_MARGIN_X));
+		}
+		header.push("");
+
+		const footer = [
+			"",
+			centerLine(theme.fg("dim", "↑/↓ select · enter confirm · esc skip · ctrl+c exit setup"), width),
+		];
+		const maxBodyLines = Math.max(0, height - header.length - footer.length);
+		const body = this.#activeScene?.render(contentWidth).slice(0, maxBodyLines) ?? [];
+		const lines = [...header, ...body.map(line => indentLine(line, width, SCENE_MARGIN_X))];
+		while (lines.length + footer.length < height) {
+			lines.push("");
+		}
+		lines.push(...footer);
+		return lines;
+	}
+
+	#fitToScreen(lines: string[], width: number, height: number): string[] {
+		const fitted = lines.slice(0, height).map(line => clampLine(line, width));
+		while (fitted.length < height) {
+			fitted.push(padding(width));
+		}
+		return fitted;
+	}
+
+	#startTimer(): void {
+		if (this.#timer) return;
+		this.#timer = setInterval(() => {
+			if (this.#disposed) return;
+			const elapsed = performance.now() - this.#phaseStartedAt;
+			if (this.#phase === "splash" && elapsed >= SETUP_SPLASH_MS) {
+				this.#beginScene();
+			} else if (this.#phase === "transition" && elapsed >= SCENE_TRANSITION_MS) {
+				this.#phase = "scene";
+				this.#phaseStartedAt = performance.now();
+				this.ctx.ui.requestRender();
+			} else if (this.#phase === "outro" && elapsed >= SETUP_OUTRO_MS) {
+				this.#complete();
+			} else {
+				this.ctx.ui.requestRender();
+			}
+		}, SETUP_TICK_MS);
+	}
+
+	#stopTimer(): void {
+		if (!this.#timer) return;
+		clearInterval(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#mountSceneController(targetPhase: "scene" | "transition"): void {
+		if (this.#disposed) return;
+		this.#unmountActiveScene();
+		if (this.#sceneIndex >= this.scenes.length) {
+			this.#beginOutro();
+			return;
+		}
+		const scene = this.scenes[this.#sceneIndex];
+		const host: SetupSceneHost = {
+			ctx: this.ctx,
+			requestRender: () => this.ctx.ui.requestRender(),
+			finish: (_result: SetupSceneResult) => this.#finishScene(),
+			setFocus: component => this.ctx.ui.setFocus(component),
+			restoreFocus: () => this.ctx.ui.setFocus(this),
+		};
+		this.#activeScene = scene.mount(host);
+		this.#phase = targetPhase;
+		this.#phaseStartedAt = performance.now();
+		this.ctx.ui.setFocus(this);
+		void this.#activeScene.onMount?.();
+		this.ctx.ui.requestRender();
+	}
+
+	/** Enter the first scene through a dissolve from the splash. */
+	#beginScene(): void {
+		this.#mountSceneController("transition");
+	}
+
+	#mountCurrentScene(): void {
+		this.#mountSceneController("scene");
+	}
+
+	#finishScene(): void {
+		if (this.#phase !== "scene" && this.#phase !== "transition") return;
+		this.#unmountActiveScene();
+		this.#sceneIndex += 1;
+		this.#mountCurrentScene();
+	}
+
+	#unmountActiveScene(): void {
+		this.#activeScene?.onUnmount?.();
+		this.#activeScene?.dispose?.();
+		this.#activeScene = undefined;
+	}
+
+	#beginOutro(): void {
+		if (this.#phase === "done") return;
+		this.#unmountActiveScene();
+		this.#phase = "outro";
+		this.#phaseStartedAt = performance.now();
+		this.ctx.ui.setFocus(this);
+		this.#startTimer();
+		this.ctx.ui.requestRender();
+	}
+
+	#complete(): void {
+		if (this.#phase === "done") return;
+		this.#phase = "done";
+		this.#stopTimer();
+		this.#done.resolve();
+	}
+}

package/src/modes/theme/shimmer.ts

@@ -147,6 +147,11 @@ function resolveMode(): ShimmerMode {
 	return settings.get("display.shimmer");
 }
 
+/** Whether shimmer animations are active (any mode other than `disabled`). */
+export function shimmerEnabled(): boolean {
+	return resolveMode() !== "disabled";
+}
+
 /**
  * Apply a shimmer sweep across one or more segments, treating them as a
  * single continuous string for band positioning. Each segment can supply

package/src/modes/theme/theme.ts

@@ -1310,6 +1310,24 @@ export class Theme {
 		return ansi;
 	}
 
+	/**
+	 * Foreground ANSI for text drawn **on top of** `fillColor` used as a solid
+	 * background (e.g. a powerline chip). Picks near-black or near-white by the
+	 * fill's perceived luminance (Rec. 601 luma) so the label stays legible on
+	 * both bright and dark fills, across light and dark themes.
+	 *
+	 * Reads the RGB out of the already-resolved truecolor escape; when the fill
+	 * is encoded as a 256-palette index (limited terminals) the RGB is
+	 * unavailable, so it falls back to the theme `text` color.
+	 */
+	getContrastFgAnsi(fillColor: ThemeColor): string {
+		const ansi = this.#fgColors[fillColor];
+		const match = ansi ? /38;2;(\d+);(\d+);(\d+)/.exec(ansi) : null;
+		if (!match) return this.#fgColors.text;
+		const luma = 0.299 * Number(match[1]) + 0.587 * Number(match[2]) + 0.114 * Number(match[3]);
+		return luma > 140 ? "\x1b[38;2;0;0;0m" : "\x1b[38;2;255;255;255m";
+	}
+
 	getColorMode(): ColorMode {
 		return this.mode;
 	}
@@ -1929,17 +1947,20 @@ export function setThemeInstance(themeInstance: Theme): void {
  */
 export async function setSymbolPreset(preset: SymbolPreset): Promise<void> {
 	currentSymbolPresetOverride = preset;
-	if (currentThemeName) {
-		try {
-			theme = await loadTheme(currentThemeName, getCurrentThemeOptions());
-		} catch {
-			// Fall back to dark theme with new preset
-			theme = await loadTheme("dark", getCurrentThemeOptions());
-		}
-		if (onThemeChangeCallback) {
-			onThemeChangeCallback();
-		}
+	if (!currentThemeName) return;
+
+	const requestId = ++themeLoadRequestId;
+	try {
+		const loadedTheme = await loadTheme(currentThemeName, getCurrentThemeOptions());
+		if (requestId !== themeLoadRequestId) return;
+		theme = loadedTheme;
+	} catch {
+		if (requestId !== themeLoadRequestId) return;
+		// Fall back to dark theme with new preset
+		theme = await loadTheme("dark", getCurrentThemeOptions());
+		if (requestId !== themeLoadRequestId) return;
 	}
+	onThemeChangeCallback?.();
 }
 
 /**
@@ -1955,17 +1976,20 @@ export function getSymbolPresetOverride(): SymbolPreset | undefined {
  */
 export async function setColorBlindMode(enabled: boolean): Promise<void> {
 	currentColorBlindMode = enabled;
-	if (currentThemeName) {
-		try {
-			theme = await loadTheme(currentThemeName, getCurrentThemeOptions());
-		} catch {
-			// Fall back to dark theme
-			theme = await loadTheme("dark", getCurrentThemeOptions());
-		}
-		if (onThemeChangeCallback) {
-			onThemeChangeCallback();
-		}
+	if (!currentThemeName) return;
+
+	const requestId = ++themeLoadRequestId;
+	try {
+		const loadedTheme = await loadTheme(currentThemeName, getCurrentThemeOptions());
+		if (requestId !== themeLoadRequestId) return;
+		theme = loadedTheme;
+	} catch {
+		if (requestId !== themeLoadRequestId) return;
+		// Fall back to dark theme
+		theme = await loadTheme("dark", getCurrentThemeOptions());
+		if (requestId !== themeLoadRequestId) return;
 	}
+	onThemeChangeCallback?.();
 }
 
 /**

package/src/modes/types.ts

@@ -58,6 +58,10 @@ export type TodoPhase = {
 	tasks: TodoItem[];
 };
 
+export interface InteractiveModeInitOptions {
+	suppressWelcomeIntro?: boolean;
+}
+
 export interface InteractiveModeContext {
 	// UI access
 	ui: TUI;
@@ -129,7 +133,8 @@ export interface InteractiveModeContext {
 	todoPhases: TodoPhase[];
 
 	// Lifecycle
-	init(): Promise<void>;
+	init(options?: InteractiveModeInitOptions): Promise<void>;
+	playWelcomeIntro(): void;
 	shutdown(): Promise<void>;
 	checkShutdownRequested(): Promise<void>;
 

package/src/prompts/system/orchestrate-notice.md

@@ -2,7 +2,7 @@
 The user's message above is an **orchestration request**. Execute it as the orchestrator under the contract below. This contract overrides any default tendency to yield early, narrate, or do the work yourself.
 
 <role>
-You decompose, dispatch, verify, and iterate. You do **not** edit code. Every file mutation goes through a `task` subagent. Your tool budget is: reading for planning, `task` for dispatch, verification (`bun check`, `bun test`, `recipe`, `lsp diagnostics`), git via `bash`, and `todo_write` for tracking.
+You decompose, dispatch, verify, and iterate. You do **not** edit code. Every file mutation goes through a `task` subagent. Your tool budget is: reading for planning, `task` for dispatch, verification (`bun check`, `bun test`, `lsp diagnostics`), git via `bash`, and `todo_write` for tracking.
 </role>
 
 <rules>

package/src/prompts/tools/read.md

@@ -46,7 +46,11 @@ Extracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipy
 
 # Images
 
+{{#if INSPECT_IMAGE_ENABLED}}
 Reading an image path returns metadata (mime, bytes, dimensions, channels, alpha). For actual visual analysis, call `inspect_image` with the path and a question describing what to inspect.
+{{else}}
+Reading an image path returns the decoded image inline (PNG, JPEG, GIF, WEBP) for direct visual analysis.
+{{/if}}
 
 # Archives
 

package/src/sdk.ts

@@ -38,6 +38,7 @@ import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from ".
 import { createAutoresearchExtension } from "./autoresearch";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
+import { bucketRules } from "./capability/rule-buckets";
 import { ModelRegistry } from "./config/model-registry";
 import {
 	formatModelString,
@@ -1045,21 +1046,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			options.rules !== undefined
 				? { items: options.rules, warnings: undefined }
 				: await loadCapability<Rule>(ruleCapability.id, { cwd });
-		const rulebookRules: Rule[] = [];
-		const alwaysApplyRules: Rule[] = [];
-		for (const rule of rulesResult.items) {
-			const isTtsrRule = rule.condition && rule.condition.length > 0 ? ttsrManager.addRule(rule) : false;
-			if (isTtsrRule) {
-				continue;
-			}
-			if (rule.alwaysApply === true) {
-				alwaysApplyRules.push(rule);
-				continue;
-			}
-			if (rule.description) {
-				rulebookRules.push(rule);
-			}
-		}
+		const { rulebookRules, alwaysApplyRules } = bucketRules(rulesResult.items, ttsrManager, {
+			builtinRules: ttsrSettings.builtinRules,
+			disabledRules: ttsrSettings.disabledRules,
+		});
 		if (existingSession.injectedTtsrRules.length > 0) {
 			ttsrManager.restoreInjected(existingSession.injectedTtsrRules);
 		}

package/src/slash-commands/builtin-registry.ts

@@ -160,6 +160,14 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "switch",
+		description: "Switch model for this session (same as alt+p)",
+		handleTui: (_command, runtime) => {
+			runtime.ctx.showModelSelector({ temporaryOnly: true });
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "fast",
 		description: "Toggle priority service tier (OpenAI service_tier=priority, Anthropic speed=fast)",

package/src/tiny/device.ts

@@ -0,0 +1,117 @@
+import type { DeviceType } from "@huggingface/transformers";
+import { $env } from "@oh-my-pi/pi-utils";
+
+export type TinyModelDevice = DeviceType;
+
+export interface TinyModelDevicePreference {
+	device: TinyModelDevice;
+	raw: string | undefined;
+}
+
+const CPU_DEVICE: TinyModelDevice = "cpu";
+const CPU_ONLY_ORDER: readonly TinyModelDevice[] = [CPU_DEVICE];
+const DARWIN_WEBGPU_UNSAFE_ORDER: readonly TinyModelDevice[] = [CPU_DEVICE];
+
+const DEVICE_VALUES: Record<TinyModelDevice, true> = {
+	auto: true,
+	gpu: true,
+	cpu: true,
+	wasm: true,
+	webgpu: true,
+	cuda: true,
+	dml: true,
+	coreml: true,
+	webnn: true,
+	"webnn-npu": true,
+	"webnn-gpu": true,
+	"webnn-cpu": true,
+};
+
+function defaultTinyModelDevice(): TinyModelDevice {
+	if (process.platform === "win32") return "dml";
+	if (process.platform === "linux" && process.arch === "x64") return "cuda";
+	return CPU_DEVICE;
+}
+
+function usesDarwinWorkerWebGpu(device: TinyModelDevice): boolean {
+	return process.platform === "darwin" && (device === "gpu" || device === "webgpu" || device === "auto");
+}
+
+export function normalizeTinyModelDevice(value: string | undefined): TinyModelDevice | undefined {
+	const raw = value?.trim().toLowerCase();
+	if (!raw) return undefined;
+	if (raw === "metal") return "webgpu";
+	if (raw in DEVICE_VALUES) return raw as TinyModelDevice;
+	throw new Error(
+		`Unsupported PI_TINY_DEVICE=${JSON.stringify(value)}. Use cpu, gpu, metal, webgpu, auto, cuda, dml, coreml, wasm, webnn, webnn-gpu, webnn-cpu, or webnn-npu.`,
+	);
+}
+
+export function resolveTinyModelDevicePreference(
+	value: string | undefined = $env.PI_TINY_DEVICE,
+): TinyModelDevicePreference {
+	return {
+		device: normalizeTinyModelDevice(value) ?? defaultTinyModelDevice(),
+		raw: value,
+	};
+}
+
+export function tinyModelDeviceLoadOrder(preference: TinyModelDevicePreference): readonly TinyModelDevice[] {
+	if (preference.device === CPU_DEVICE) return CPU_ONLY_ORDER;
+	if (usesDarwinWorkerWebGpu(preference.device)) return DARWIN_WEBGPU_UNSAFE_ORDER;
+	return [preference.device, CPU_DEVICE];
+}
+
+/** Sentinel `providers.tinyModelDevice` value meaning "use the built-in platform default". */
+export const TINY_MODEL_DEVICE_DEFAULT = "default";
+
+/** Accepted values for the `providers.tinyModelDevice` setting (validation + UI). */
+export const TINY_MODEL_DEVICE_SETTING_VALUES = [
+	TINY_MODEL_DEVICE_DEFAULT,
+	"gpu",
+	"cpu",
+	"metal",
+	"webgpu",
+	"cuda",
+	"dml",
+	"coreml",
+	"auto",
+	"wasm",
+	"webnn",
+	"webnn-gpu",
+	"webnn-cpu",
+	"webnn-npu",
+] as const;
+
+/** Submenu metadata for the `providers.tinyModelDevice` setting. */
+export const TINY_MODEL_DEVICE_SETTING_OPTIONS = [
+	{ value: "default", label: "Default", description: "DirectML on Windows, CUDA on Linux x64, CPU elsewhere" },
+	{ value: "gpu", label: "GPU", description: "Accelerated provider (WebGPU/Metal, CUDA, or DirectML)" },
+	{ value: "cpu", label: "CPU", description: "CPU-only inference" },
+	{ value: "metal", label: "Metal", description: "WebGPU alias for Apple GPUs" },
+	{ value: "webgpu", label: "WebGPU", description: "WebGPU/Metal backend" },
+	{ value: "cuda", label: "CUDA", description: "NVIDIA CUDA (Linux x64)" },
+	{ value: "dml", label: "DirectML", description: "DirectML backend (Windows)" },
+	{ value: "coreml", label: "CoreML", description: "Apple CoreML (opt-in; can fail to load)" },
+	{ value: "auto", label: "Auto", description: "Let ONNX Runtime choose a provider" },
+	{ value: "wasm", label: "WASM", description: "WebAssembly backend" },
+	{ value: "webnn", label: "WebNN", description: "WebNN backend" },
+	{ value: "webnn-gpu", label: "WebNN GPU", description: "WebNN GPU device" },
+	{ value: "webnn-cpu", label: "WebNN CPU", description: "WebNN CPU device" },
+	{ value: "webnn-npu", label: "WebNN NPU", description: "WebNN NPU device" },
+] as const satisfies ReadonlyArray<{
+	value: (typeof TINY_MODEL_DEVICE_SETTING_VALUES)[number];
+	label: string;
+	description: string;
+}>;
+
+/**
+ * Map a `providers.tinyModelDevice` setting value onto a `PI_TINY_DEVICE` env
+ * value for the worker. Returns `undefined` for the default sentinel so the
+ * worker keeps its built-in platform default; the worker still validates the
+ * forwarded value via {@link normalizeTinyModelDevice}.
+ */
+export function tinyModelDeviceSettingToEnv(value: string | undefined): string | undefined {
+	if (!value || value === TINY_MODEL_DEVICE_DEFAULT) return undefined;
+	return value;
+}

package/src/tiny/dtype.ts

@@ -0,0 +1,101 @@
+import type { DataType } from "@huggingface/transformers";
+import { $env } from "@oh-my-pi/pi-utils";
+
+/** ONNX quantization / precision for local tiny models (transformers.js `dtype`). */
+export type TinyModelDtype = DataType;
+
+const DTYPE_VALUES: Record<TinyModelDtype, true> = {
+	auto: true,
+	fp32: true,
+	fp16: true,
+	q8: true,
+	int8: true,
+	uint8: true,
+	q4: true,
+	bnb4: true,
+	q4f16: true,
+	q2: true,
+	q2f16: true,
+	q1: true,
+	q1f16: true,
+};
+
+/**
+ * Validate and canonicalize a `PI_TINY_DTYPE` value. Returns `undefined` when
+ * unset/blank so callers fall back to the per-model spec dtype, and throws on an
+ * unrecognized value so a misconfiguration fails loudly instead of silently
+ * loading a different precision than requested.
+ */
+export function normalizeTinyModelDtype(value: string | undefined): TinyModelDtype | undefined {
+	const raw = value?.trim().toLowerCase();
+	if (!raw) return undefined;
+	if (raw in DTYPE_VALUES) return raw as TinyModelDtype;
+	throw new Error(
+		`Unsupported PI_TINY_DTYPE=${JSON.stringify(value)}. Use auto, fp32, fp16, q8, int8, uint8, q4, bnb4, q4f16, q2, q2f16, q1, or q1f16.`,
+	);
+}
+
+/**
+ * Resolve the `PI_TINY_DTYPE` override. `undefined` means "use the per-model spec
+ * dtype" (currently `q4` for every shipped model); a concrete value overrides the
+ * precision for whichever local tiny model loads.
+ */
+export function resolveTinyModelDtypeOverride(
+	value: string | undefined = $env.PI_TINY_DTYPE,
+): TinyModelDtype | undefined {
+	return normalizeTinyModelDtype(value);
+}
+
+/** Sentinel `providers.tinyModelDtype` value meaning "use each model's shipped dtype". */
+export const TINY_MODEL_DTYPE_DEFAULT = "default";
+
+/** Accepted values for the `providers.tinyModelDtype` setting (validation + UI). */
+export const TINY_MODEL_DTYPE_SETTING_VALUES = [
+	TINY_MODEL_DTYPE_DEFAULT,
+	"q4",
+	"q4f16",
+	"q8",
+	"fp16",
+	"fp32",
+	"int8",
+	"uint8",
+	"bnb4",
+	"q2",
+	"q2f16",
+	"q1",
+	"q1f16",
+	"auto",
+] as const;
+
+/** Submenu metadata for the `providers.tinyModelDtype` setting. */
+export const TINY_MODEL_DTYPE_SETTING_OPTIONS = [
+	{ value: "default", label: "Default", description: "Each model's shipped dtype (currently q4)" },
+	{ value: "q4", label: "q4", description: "4-bit weights; smallest and fastest" },
+	{ value: "q4f16", label: "q4f16", description: "4-bit weights with fp16 activations" },
+	{ value: "q8", label: "q8", description: "8-bit quantization" },
+	{ value: "fp16", label: "fp16", description: "16-bit float; higher fidelity, larger" },
+	{ value: "fp32", label: "fp32", description: "Full precision; largest and slowest" },
+	{ value: "int8", label: "int8", description: "Signed 8-bit integer" },
+	{ value: "uint8", label: "uint8", description: "Unsigned 8-bit integer" },
+	{ value: "bnb4", label: "bnb4", description: "bitsandbytes 4-bit" },
+	{ value: "q2", label: "q2", description: "2-bit weights" },
+	{ value: "q2f16", label: "q2f16", description: "2-bit weights with fp16 activations" },
+	{ value: "q1", label: "q1", description: "1-bit weights" },
+	{ value: "q1f16", label: "q1f16", description: "1-bit weights with fp16 activations" },
+	{ value: "auto", label: "Auto", description: "Let transformers.js choose per device" },
+] as const satisfies ReadonlyArray<{
+	value: (typeof TINY_MODEL_DTYPE_SETTING_VALUES)[number];
+	label: string;
+	description: string;
+}>;
+
+/**
+ * Map a `providers.tinyModelDtype` setting value onto a `PI_TINY_DTYPE` env value
+ * for the worker. Returns `undefined` for the default sentinel so the worker keeps
+ * each model's shipped dtype; the worker still validates the forwarded value via
+ * {@link normalizeTinyModelDtype}.
+ */
+export function tinyModelDtypeSettingToEnv(value: string | undefined): string | undefined {
+	if (!value || value === TINY_MODEL_DTYPE_DEFAULT) return undefined;
+	return value;
+}