@narumitw/pi-webui 0.20.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Narumi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# 🌐 pi-webui — Current-session Web Companion for Pi
+
+[![npm](https://img.shields.io/npm/v/@narumitw/pi-webui)](https://www.npmjs.com/package/@narumitw/pi-webui) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+`@narumitw/pi-webui` adds a private, lightweight browser companion to the current terminal-owned [Pi Coding Agent](https://pi.dev) session. It displays Pi's semantic conversation and tool activity as they happen and can send text or sanitized images back into that same session.
+
+This package is intentionally different from the broader, separately maintained `@narumitw/pi-web` application. WebUI has one current-session chat page and no session manager, shell, file browser, git UI, control room, or task board.
+
+## Features
+
+- Streams current-branch user and assistant messages, assistant text updates, tool activity/results, errors, and busy/idle state over Server-Sent Events.
+- Renders a safe Markdown subset for headings, lists, emphasis, code, blockquotes, and HTTP(S) links without executing model-provided HTML.
+- Preserves open tool/thinking disclosures during keyed streaming updates and offers **Jump to latest** when new activity arrives while you read earlier messages.
+- Sends immediately while Pi is idle and automatically queues **Queue next** as a follow-up while Pi is busy.
+- Provides a separate **Steer** action while Pi is working; steering is never the default submit action.
+- Accepts pasted, dropped, or selected PNG, JPEG, WebP, and GIF images, strips metadata server-side, applies Pi-compatible size limits, and provides contained thumbnails plus an enlarged preview.
+- Reconnects from an ordered event cursor and replaces state from an authoritative snapshot after a gap.
+- Keeps a failed browser draft and prevents rapid duplicate submission with request IDs.
+- Uses no frontend framework, build step, browser storage, remote service, or automatically launched browser.
+
+## Install
+
+```bash
+pi install npm:@narumitw/pi-webui
+```
+
+Try the working tree without installing:
+
+```bash
+pi -e ./extensions/pi-webui
+# or
+just try webui
+```
+
+The package targets the latest Pi release.
+
+## Usage
+
+1. Start Pi in a terminal and run `/webui`.
+2. Open the one-time `http://127.0.0.1:<port>/bootstrap?...` link shown by Pi. The extension does not open a browser itself.
+3. Continue typing in either the terminal or browser. Accepted messages from both surfaces appear in the browser transcript.
+4. While Pi is idle, **Send** starts a turn immediately. While Pi is working, **Queue next** queues a follow-up. Use **Steer** only when the new instruction should reach Pi after the current tool batch.
+5. Refreshing or opening the link in another tab takes the editing lease. Older tabs remain readable and clearly become read-only.
+
+If another installed extension also registers `/webui`, Pi assigns numeric command suffixes according to extension load order. Check Pi's command provenance and invoke the WebUI entry.
+
+## Commands
+
+| Command | Behavior |
+| --- | --- |
+| `/webui` | Start or reuse the current session server and display a fresh one-time link. |
+| `/webui settings` | Open the interactive settings screen in TUI mode. Other modes report the manual settings path when notifications are available. |
+| `/webui status` | Show the effective startup preference and source, settings path, and whether the current session server is running. It never issues a bootstrap link. |
+| `/webui help` | Show command and manual-settings help. |
+| `/webui init` | Create the defaults file without overwriting existing content, then open settings in TUI mode. |
+
+Argument completion is available for all subcommands. Bare `/webui` remains the direct browser-link action.
+
+## Settings
+
+WebUI has one optional, **global-only** JSON settings file:
+
+```text
+<getAgentDir()>/pi-webui.json
+```
+
+The normal default path is `~/.pi/agent/pi-webui.json`. Pi installations that use another agent directory are resolved through Pi's `getAgentDir()` API; WebUI adds no environment variable or project override.
+
+```json
+{
+  "startOnSessionStart": false
+}
+```
+
+| Setting | Default | Behavior |
+| --- | --- | --- |
+| `startOnSessionStart` | `false` | Start WebUI and display a fresh one-time link after every Pi session initialization, including startup, reload, new, resume, and fork. It never opens a browser. |
+
+A missing file uses defaults. The file must contain a top-level JSON object, and `startOnSessionStart` must be a boolean when present. Malformed JSON or an invalid recognized value causes the file to be ignored with a warning and leaves it untouched. Unknown fields are accepted and preserved by the settings screen for forward compatibility.
+
+Settings are reloaded on every `session_start`. Changes made in `/webui settings` are saved atomically and update the in-memory preference immediately, but they intentionally do not start or stop the server in the current session; they take effect at the next session initialization or `/reload`. `/webui init` creates formatted defaults once and refuses to overwrite valid or invalid existing content.
+
+In print, JSON, and RPC modes, `/webui settings` does not open custom TUI or write protocol-breaking output. Use `/webui status`, `/webui help`, or edit the reported path manually.
+
+## What synchronization means
+
+WebUI mirrors Pi's semantic session events, not terminal pixels. It displays conversation content, streaming assistant state, tool calls/results, errors, and activity using browser-native presentation. It does not reproduce ANSI colors, terminal wrapping, footer/widgets, built-in dialogs, arbitrary custom TUI components, or unsent terminal editor text.
+
+The initial transcript comes from the active session branch. Browser refresh does not create a second transcript or alter Pi's session tree.
+
+## Images
+
+| Input | Provider-ready output |
+| --- | --- |
+| PNG | PNG |
+| JPEG | JPEG |
+| WebP | WebP |
+| GIF | GIF |
+
+The server checks file signatures instead of trusting browser MIME types. It rejects corrupt/unknown formats, more than 8 images, individual source images over 10 MiB, combined image input over 40 MiB, images over 50 megapixels, and provider-ready Base64 content over Pi's approximately 4.5 MB inline limit. Images over 2,000 pixels on either side are resized when Pi's `images.autoResize` setting is enabled and rejected when it is disabled.
+
+Processing re-encodes images with `sharp`, strips EXIF and other metadata, and does not retain browser source bytes after the message request is accepted. Pi's effective global and trusted-project `images.autoResize` and `images.blockImages` settings plus the current model's image capability are checked at send time.
+
+## Security and privacy
+
+- The server binds only to a random `127.0.0.1` port and is owned by one live Pi session.
+- A rotating bootstrap token is exchanged once for a per-server HttpOnly, `SameSite=Strict` cookie and removed from the URL.
+- Every endpoint requires the cookie. Mutations also require exact Host and Origin values plus the active browser-tab lease.
+- Responses use no-store, no-referrer, MIME-sniffing, frame-denial, same-origin resource, and restrictive Content Security Policy headers.
+- Transcript projection retains at most the newest 500 messages and 500 tool records, event replay keeps 256 updates, and request-id records keep 128 sends. The page uses no localStorage, sessionStorage, IndexedDB, cookies of its own, or image/transcript cache.
+- Tool arguments/results, paths, images, and model thinking can be sensitive. Thinking is collapsed by default; only open a link issued by a Pi process you trust.
+- Reload, session replacement/fork, or Pi shutdown closes sockets, invalidates old callbacks, ends the page, and releases in-memory state.
+
+A loopback page is local to the operating-system network namespace. WebUI does not support LAN/public binding or a cloud relay. For SSH, containers, or devcontainers, forward the exact printed port and preserve the `127.0.0.1:<port>` Host value.
+
+## Accessibility and browsers
+
+The page uses semantic headings, native disclosure/dialog controls, concise status/alert live regions, text labels, visible keyboard focus, at least 44 px controls, keyboard image preview/removal, `Ctrl/Command+Enter` submission, reduced-motion handling, dark mode, and responsive reflow. It targets current stable desktop Chrome, Edge, Firefox, and Safari.
+
+## Limitations
+
+- One active Pi session and one active browser editing tab only.
+- No persistent browser transcript, sent-image history, remote access, PTY/terminal control, model/settings controls, or session switching.
+- No SVG, HEIC/HEIF, TIFF, BMP, AVIF, remote image URL, OCR, annotation, or directory upload support.
+- Browser acknowledgment means Pi accepted or queued the message. Provider failures follow Pi's normal session/retry behavior.
+- Built-in TUI commands and dialogs are not reimplemented in the browser.
+
+## Package layout
+
+```text
+src/webui.ts         Pi extension entrypoint
+src/runtime.ts       Pi lifecycle, commands, event projection, and browser message routing
+src/settings.ts      global WebUI settings validation and atomic persistence
+src/conversation.ts  bounded transcript snapshot and ordered event replay
+src/server.ts        authenticated loopback HTTP/SSE server
+src/images.ts        bounded provider-ready image processing
+src/pi-settings.ts   effective Pi image settings reader
+src/web/             framework-free browser page
+```
+
+## Development
+
+From the repository root:
+
+```bash
+npm --workspace @narumitw/pi-webui run check
+npm test
+just try webui
+just pack webui
+```
+
+The package preview must contain its manifest, license, README, TypeScript source, and static web assets, but no tests, fixtures, cache, or `node_modules`.
+
+## Keywords
+
+Pi extension, Pi Coding Agent, browser companion, local web chat, terminal session sync, Server-Sent Events, image prompt, tool activity, local-first AI coding agent.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@narumitw/pi-webui",
+	"version": "0.20.2",
+	"description": "Lightweight local web companion for the current Pi terminal session.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"web",
+		"chat",
+		"browser"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/webui.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check --vcs-use-ignore-file=false src test package.json tsconfig.json && npm run typecheck",
+		"format": "biome check --write --vcs-use-ignore-file=false src test package.json tsconfig.json",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"sharp": "^0.35.3"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.3",
+		"@earendil-works/pi-ai": "0.80.10",
+		"@earendil-works/pi-coding-agent": "0.80.10",
+		"@earendil-works/pi-tui": "0.80.10",
+		"typescript": "7.0.2"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/narumiruna/pi-extensions",
+		"directory": "extensions/pi-webui"
+	}
+}

package/src/conversation.ts

@@ -0,0 +1,374 @@
+const MAX_TEXT_BYTES = 50_000;
+const MAX_TRANSCRIPT_RECORDS = 500;
+const DEFAULT_REPLAY_LIMIT = 256;
+
+export interface SessionDescriptor {
+	id: string;
+	cwd: string;
+	projectName: string;
+	name?: string;
+}
+
+export type PublicContent =
+	| { type: "text"; text: string }
+	| { type: "thinking"; text: string }
+	| { type: "image"; mimeType?: string }
+	| { type: "toolCall"; id: string; name: string; arguments: unknown };
+
+export interface PublicMessage {
+	id: string;
+	role: string;
+	timestamp?: number;
+	final: boolean;
+	content: PublicContent[];
+	toolCallId?: string;
+	toolName?: string;
+	isError?: boolean;
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+export interface PublicTool {
+	id: string;
+	name: string;
+	phase: "start" | "update" | "end";
+	args?: unknown;
+	result?: unknown;
+	isError?: boolean;
+}
+
+export type ActivityState = "idle" | "running" | "ended";
+
+export interface ConversationSnapshot {
+	sequence: number;
+	session: SessionDescriptor;
+	messages: PublicMessage[];
+	tools: PublicTool[];
+	activity: ActivityState;
+	closed: boolean;
+}
+
+export interface ConversationEvent {
+	sequence: number;
+	type: "message" | "tool" | "activity" | "session-ended" | "snapshot";
+	payload: unknown;
+}
+
+type Listener = (event: ConversationEvent) => void;
+
+export class ConversationProjection {
+	private sequence = 0;
+	private readonly messages = new Map<string, PublicMessage>();
+	private readonly tools = new Map<string, PublicTool>();
+	private readonly replay: ConversationEvent[] = [];
+	private readonly listeners = new Set<Listener>();
+	private activity: ActivityState = "idle";
+	private closed = false;
+
+	constructor(
+		private readonly session: SessionDescriptor,
+		initialMessages: PublicMessage[] = [],
+		private readonly replayLimit = DEFAULT_REPLAY_LIMIT,
+	) {
+		for (const message of initialMessages.slice(-MAX_TRANSCRIPT_RECORDS)) {
+			this.messages.set(message.id, clone(message));
+		}
+	}
+
+	snapshot(): ConversationSnapshot {
+		return {
+			sequence: this.sequence,
+			session: { ...this.session },
+			messages: [...this.messages.values()].map(clone),
+			tools: [...this.tools.values()].map(clone),
+			activity: this.activity,
+			closed: this.closed,
+		};
+	}
+
+	subscribe(listener: Listener): () => void {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+
+	eventsAfter(sequence: number): ConversationEvent[] | undefined {
+		if (!Number.isSafeInteger(sequence) || sequence < 0 || sequence > this.sequence)
+			return undefined;
+		if (sequence === this.sequence) return [];
+		const first = this.replay[0]?.sequence;
+		if (first === undefined || sequence < first - 1) return undefined;
+		return this.replay.filter((event) => event.sequence > sequence).map(clone);
+	}
+
+	replaceBranch(messages: PublicMessage[]): void {
+		this.messages.clear();
+		this.tools.clear();
+		for (const message of messages.slice(-MAX_TRANSCRIPT_RECORDS)) {
+			this.messages.set(message.id, clone(message));
+		}
+		this.publishSnapshot();
+	}
+
+	updateSession(patch: Pick<SessionDescriptor, "name">): void {
+		if (this.session.name === patch.name) return;
+		if (patch.name === undefined) delete this.session.name;
+		else this.session.name = patch.name;
+		this.publishSnapshot();
+	}
+
+	recordMessage(message: unknown, final = true, entryId?: string): void {
+		const projected = projectMessage(message, entryId, final);
+		const previous = this.messages.get(projected.id);
+		if (previous && JSON.stringify(previous) === JSON.stringify(projected)) return;
+		this.messages.set(projected.id, projected);
+		trimOldest(this.messages, MAX_TRANSCRIPT_RECORDS);
+		this.emit("message", projected);
+	}
+
+	recordTool(
+		phase: PublicTool["phase"],
+		id: string,
+		name: string,
+		args?: unknown,
+		result?: unknown,
+		isError?: boolean,
+	): void {
+		const previous = this.tools.get(id);
+		const projectedArgs = args === undefined ? previous?.args : boundedJson(args);
+		const tool: PublicTool = {
+			id,
+			name,
+			phase,
+			...(projectedArgs === undefined ? {} : { args: projectedArgs }),
+			...(result === undefined ? {} : { result: boundedJson(result) }),
+			...(isError === undefined ? {} : { isError }),
+		};
+		if (previous && JSON.stringify(previous) === JSON.stringify(tool)) return;
+		this.tools.set(id, tool);
+		trimOldest(this.tools, MAX_TRANSCRIPT_RECORDS);
+		this.emit("tool", tool);
+	}
+
+	setActivity(activity: ActivityState): void {
+		if (this.activity === activity || this.closed) return;
+		this.activity = activity;
+		this.emit("activity", { activity });
+	}
+
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.activity = "ended";
+		this.emit("session-ended", { activity: this.activity });
+	}
+
+	private emit(type: ConversationEvent["type"], payload: unknown): void {
+		this.rememberAndPublish({ sequence: ++this.sequence, type, payload: clone(payload) });
+	}
+
+	private publishSnapshot(): void {
+		const sequence = ++this.sequence;
+		this.rememberAndPublish({ sequence, type: "snapshot", payload: this.snapshot() });
+	}
+
+	private rememberAndPublish(event: ConversationEvent): void {
+		this.replay.push(event);
+		while (this.replay.length > Math.max(1, this.replayLimit)) this.replay.shift();
+		for (const listener of this.listeners) listener(clone(event));
+	}
+}
+
+export function projectBranchMessages(branch: unknown): PublicMessage[] {
+	if (!Array.isArray(branch)) return [];
+	const messages: PublicMessage[] = [];
+	for (const entry of branch) {
+		if (!isRecord(entry) || entry.type !== "message" || !("message" in entry)) continue;
+		try {
+			messages.push(
+				projectMessage(entry.message, typeof entry.id === "string" ? entry.id : undefined),
+			);
+		} catch {
+			// Unknown extension entries must not prevent the supported transcript from loading.
+		}
+	}
+	return messages;
+}
+
+export function projectMessage(message: unknown, entryId?: string, final = true): PublicMessage {
+	if (!isRecord(message) || typeof message.role !== "string") {
+		throw new Error("Invalid Pi message");
+	}
+	const timestamp = typeof message.timestamp === "number" ? message.timestamp : undefined;
+	const content = projectContent(message.content);
+	const id = entryId ?? messageId(message, timestamp, content);
+	return {
+		id,
+		role: message.role,
+		...(timestamp === undefined ? {} : { timestamp }),
+		final,
+		content,
+		...(typeof message.toolCallId === "string" ? { toolCallId: message.toolCallId } : {}),
+		...(typeof message.toolName === "string" ? { toolName: message.toolName } : {}),
+		...(typeof message.isError === "boolean" ? { isError: message.isError } : {}),
+		...(typeof message.stopReason === "string" ? { stopReason: message.stopReason } : {}),
+		...(typeof message.errorMessage === "string"
+			? { errorMessage: truncateText(message.errorMessage) }
+			: {}),
+	};
+}
+
+function projectContent(content: unknown): PublicContent[] {
+	if (typeof content === "string") return [{ type: "text", text: truncateText(content) }];
+	if (!Array.isArray(content)) return [];
+	const projected: PublicContent[] = [];
+	for (const block of content) {
+		if (!isRecord(block) || typeof block.type !== "string") continue;
+		if (block.type === "text" && typeof block.text === "string") {
+			projected.push({ type: "text", text: truncateText(block.text) });
+		} else if (block.type === "thinking" && typeof block.thinking === "string") {
+			projected.push({ type: "thinking", text: truncateText(block.thinking) });
+		} else if (block.type === "image") {
+			projected.push({
+				type: "image",
+				...(typeof block.mimeType === "string" ? { mimeType: block.mimeType } : {}),
+			});
+		} else if (
+			block.type === "toolCall" &&
+			typeof block.id === "string" &&
+			typeof block.name === "string"
+		) {
+			projected.push({
+				type: "toolCall",
+				id: block.id,
+				name: block.name,
+				arguments: boundedJson(block.arguments),
+			});
+		}
+	}
+	return projected;
+}
+
+function messageId(
+	message: Record<string, unknown>,
+	timestamp: number | undefined,
+	content: unknown,
+): string {
+	if (timestamp !== undefined) return `${message.role}:${timestamp}`;
+	if (typeof message.toolCallId === "string") return `tool-result:${message.toolCallId}`;
+	const toolCall = Array.isArray(message.content)
+		? message.content.find(
+				(block) => isRecord(block) && block.type === "toolCall" && typeof block.id === "string",
+			)
+		: undefined;
+	if (isRecord(toolCall) && typeof toolCall.id === "string") return `assistant:${toolCall.id}`;
+	return `${message.role}:live:${hash(JSON.stringify(content))}`;
+}
+
+function boundedJson(value: unknown): unknown {
+	return sanitizeJson(value, { remaining: MAX_TEXT_BYTES, nodes: 1_000 }, new WeakSet(), 0);
+}
+
+function sanitizeJson(
+	value: unknown,
+	budget: { remaining: number; nodes: number },
+	seen: WeakSet<object>,
+	depth: number,
+): unknown {
+	if (budget.remaining <= 0 || budget.nodes <= 0) return "[Truncated]";
+	budget.nodes -= 1;
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		const text = truncateToBudget(value, budget.remaining);
+		budget.remaining -= Buffer.byteLength(text);
+		return text;
+	}
+	if (typeof value === "number") return Number.isFinite(value) ? value : String(value);
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value !== "object") return String(value ?? "");
+	if (seen.has(value)) return "[Circular]";
+	if (depth >= 8) return "[Depth limit]";
+	seen.add(value);
+	if (Array.isArray(value)) {
+		const result = value.slice(0, 100).map((item) => sanitizeJson(item, budget, seen, depth + 1));
+		if (value.length > 100) result.push(`[${value.length - 100} more items]`);
+		return result;
+	}
+	const result: Record<string, unknown> = {};
+	let scannedKeys = 0;
+	let ownKeys = 0;
+	let omitted = false;
+	for (const rawKey in value) {
+		scannedKeys += 1;
+		if (scannedKeys > 200) {
+			omitted = true;
+			break;
+		}
+		if (!Object.hasOwn(value, rawKey)) continue;
+		if (ownKeys >= 100 || budget.remaining <= 0 || budget.nodes <= 0) {
+			omitted = true;
+			break;
+		}
+		ownKeys += 1;
+		const key = truncateToBudget(rawKey, Math.min(500, budget.remaining));
+		budget.remaining -= Buffer.byteLength(key);
+		try {
+			setOwn(
+				result,
+				key,
+				sanitizeJson((value as Record<string, unknown>)[rawKey], budget, seen, depth + 1),
+			);
+		} catch {
+			setOwn(result, key, "[Unreadable]");
+		}
+	}
+	if (omitted) setOwn(result, "…", "More properties omitted");
+	return result;
+}
+
+function setOwn(target: Record<string, unknown>, key: string, value: unknown): void {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true,
+	});
+}
+
+function truncateToBudget(text: string, maxBytes: number): string {
+	if (Buffer.byteLength(text) <= maxBytes) return text;
+	let end = Math.min(text.length, maxBytes);
+	while (end > 0 && Buffer.byteLength(text.slice(0, end)) > Math.max(0, maxBytes - 16)) end -= 1;
+	return `${text.slice(0, end)}… truncated`;
+}
+
+function truncateText(text: string): string {
+	if (Buffer.byteLength(text) <= MAX_TEXT_BYTES) return text;
+	let end = Math.min(text.length, MAX_TEXT_BYTES);
+	while (end > 0 && Buffer.byteLength(text.slice(0, end)) > MAX_TEXT_BYTES) end -= 1;
+	return `${text.slice(0, end)}\n… output truncated`;
+}
+
+function hash(value: string): string {
+	let result = 2166136261;
+	for (let index = 0; index < value.length; index += 1) {
+		result ^= value.charCodeAt(index);
+		result = Math.imul(result, 16777619);
+	}
+	return (result >>> 0).toString(36);
+}
+
+function trimOldest<T>(values: Map<string, T>, limit: number): void {
+	while (values.size > limit) {
+		const oldest = values.keys().next().value;
+		if (typeof oldest !== "string") return;
+		values.delete(oldest);
+	}
+}
+
+function clone<T>(value: T): T {
+	return structuredClone(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}