pk-annotator 0.6.0

package/dist/vite.mjs

@@ -0,0 +1,729 @@
+import { A as createStore, B as Id, C as agentsDir, D as MissingAnnotationError, H as State, I as resolveInside, L as AnnotationDraft, M as isErrno, N as listIds, O as PkaError, R as ErrorGroup, T as AgentPresence, U as ThreadEntry, V as RelativePath, b as upsertErrorGroups, d as checkCaptureFiles, f as create, g as loadAnnotationUpdates, k as checkStoreSize, r as RecordingManifestDraft, t as RecordingErrors, w as liveAgents, z as ID_PATTERN } from "./recording-CpEDddkZ.mjs";
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { constants, watch } from "node:fs";
+import { lstat, mkdir, open, readFile, readdir, realpath, rm, stat } from "node:fs/promises";
+import path, { posix } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { Visitor, normalizePath, parseSync, searchForWorkspaceRoot } from "vite";
+import { z } from "zod";
+import MagicString from "magic-string";
+import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping";
+//#region src/shared/channel.ts
+const CHANNEL = {
+	create: "pka:create",
+	file: "pka:file",
+	errors: "pka:errors",
+	created: "pka:created",
+	createFailed: "pka:create-failed",
+	state: "pka:state",
+	thread: "pka:thread",
+	errorsAck: "pka:errors-ack",
+	sync: "pka:sync",
+	synced: "pka:synced",
+	symbolicate: "pka:symbolicate",
+	symbolicated: "pka:symbolicated",
+	presence: "pka:presence",
+	agent: "pka:agent",
+	setup: "pka:setup",
+	setupInfo: "pka:setup-info"
+};
+const MAX_CHUNK_BYTES = 524288;
+const CreateMessage = z.strictObject({
+	requestId: Id,
+	draft: AnnotationDraft,
+	files: z.array(z.strictObject({
+		path: RelativePath,
+		bytes: z.number().int().nonnegative().max(1073741824)
+	})).max(500)
+});
+const FileChunkMessage = z.strictObject({
+	requestId: Id,
+	path: RelativePath,
+	offset: z.number().int().nonnegative(),
+	data: z.base64().max(Math.ceil(MAX_CHUNK_BYTES / 3) * 4)
+});
+const ErrorsMessage = z.strictObject({ groups: z.array(ErrorGroup).min(1).max(50) });
+const SyncMessage = z.strictObject({ ids: z.array(Id).max(200) });
+const SymbolicateMessage = z.strictObject({
+	requestId: Id,
+	stacks: z.array(z.string().max(16100)).max(150)
+});
+const PresenceMessage = z.strictObject({});
+const SetupMessage = z.strictObject({ requestId: Id });
+z.strictObject({
+	requestId: Id,
+	id: Id,
+	dir: z.string().min(1).max(4096)
+});
+z.strictObject({
+	requestId: Id,
+	message: z.string()
+});
+z.strictObject({
+	id: Id,
+	state: State
+});
+z.strictObject({
+	id: Id,
+	entry: ThreadEntry
+});
+z.strictObject({ groups: z.array(z.strictObject({
+	fingerprint: z.string().min(1).max(200),
+	stack: z.string(),
+	topFrame: z.string().optional()
+})) });
+z.strictObject({
+	requestId: Id,
+	stacks: z.array(z.string())
+});
+z.strictObject({ annotations: z.array(z.strictObject({
+	id: Id,
+	state: State,
+	thread: z.array(ThreadEntry)
+})) });
+z.strictObject({
+	requestId: Id,
+	root: z.string().min(1),
+	store: z.string().min(1),
+	command: z.array(z.string().min(1)).min(1).nullable()
+});
+z.strictObject({
+	agent: AgentPresence.pick({
+		name: true,
+		version: true,
+		connectedAt: true
+	}).nullable(),
+	cause: z.enum(["presence", "change"])
+});
+//#endregion
+//#region src/vite/source.ts
+const ATTRIBUTE = "data-pka-src";
+function isHostElement(name) {
+	return name.type === "JSXIdentifier" && /^[a-z]/.test(name.name);
+}
+function lineStarts(code) {
+	const starts = [0];
+	for (let index = 0; index < code.length; index++) if (code.charCodeAt(index) === 10) starts.push(index + 1);
+	return starts;
+}
+function location(starts, offset) {
+	let low = 0;
+	let high = starts.length - 1;
+	while (low < high) {
+		const middle = low + high + 1 >> 1;
+		if ((starts[middle] ?? Infinity) <= offset) low = middle;
+		else high = middle - 1;
+	}
+	return `${low + 1}:${offset - (starts[low] ?? 0) + 1}`;
+}
+/** Adds data-pka-src="<relativePath>:<line>:<column>" (1-based) to every host JSX element. */
+function stampSource(code, file, relativePath) {
+	const result = parseSync(file, code, { sourceType: "module" });
+	if (result.errors.length > 0) return null;
+	const starts = lineStarts(code);
+	const output = new MagicString(code);
+	const escaped = relativePath.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+	new Visitor({ JSXOpeningElement(node) {
+		if (!isHostElement(node.name)) return;
+		if (node.attributes.some((attribute) => attribute.type === "JSXAttribute" && attribute.name.type === "JSXIdentifier" && attribute.name.name === ATTRIBUTE)) return;
+		output.appendLeft(node.name.end, ` ${ATTRIBUTE}="${escaped}:${location(starts, node.start)}"`);
+	} }).visit(result.program);
+	if (!output.hasChanged()) return null;
+	return {
+		code: output.toString(),
+		map: output.generateMap({ hires: "boundary" })
+	};
+}
+/**
+* Runs before every other transform (hook order "pre") in every environment,
+* so client, route-split client chunks (?tsr-split=…), and SSR stamp the
+* untouched source and hydrate with identical attributes.
+*/
+function sourcePlugin() {
+	let workspaceRoot = "";
+	return {
+		name: "pk-annotator:source",
+		apply: "serve",
+		enforce: "pre",
+		configResolved(config) {
+			workspaceRoot = normalizePath(searchForWorkspaceRoot(config.root));
+		},
+		transform: {
+			order: "pre",
+			filter: { id: {
+				include: /\.[jt]sx(?:\?|$)/,
+				exclude: /\/node_modules\//
+			} },
+			handler(code, id) {
+				const file = id.split("?", 1)[0] ?? id;
+				if (!file.startsWith(`${workspaceRoot}/`)) return null;
+				return stampSource(code, file, posix.relative(workspaceRoot, file));
+			}
+		}
+	};
+}
+//#endregion
+//#region src/vite/symbolicate.ts
+const FRAME = /^(?<head>.*?)(?<url>https?:\/\/[^\s()]+?):(?<line>\d+):(?<column>\d+)(?<tail>\)?\s*)$/;
+const VENDOR = /\/node_modules\/|\/\.vite\/deps\/|\/@vite\//;
+const traceMaps = /* @__PURE__ */ new WeakMap();
+async function traceMapFor(environment, url) {
+	const module = await environment.moduleGraph.getModuleByUrl(url);
+	const result = module?.transformResult;
+	if (module?.file == null || result == null || result.map == null) return void 0;
+	if (result.map.mappings === "") return void 0;
+	let map = traceMaps.get(result);
+	if (map === void 0) {
+		map = new TraceMap(JSON.stringify(result.map), module.file);
+		traceMaps.set(result, map);
+	}
+	return map;
+}
+/**
+* Maps every frame of a browser stack whose URL is a module in the client
+* module graph back to its original file, line, and column, relative to the
+* workspace root. Dependency and Vite client frames stay as they are.
+*/
+async function symbolicate(environment, workspaceRoot, stack) {
+	const base = environment.config.base;
+	let topFrame;
+	const lines = [];
+	for (const line of stack.split("\n")) {
+		const frame = FRAME.exec(line)?.groups;
+		if (frame === void 0) {
+			lines.push(line);
+			continue;
+		}
+		const { head = "", url = "", tail = "" } = frame;
+		const parsed = URL.parse(url);
+		const requested = parsed === null ? "" : `${parsed.pathname}${parsed.search}`;
+		if (!requested.startsWith(base) || VENDOR.test(requested)) {
+			lines.push(line);
+			continue;
+		}
+		const map = await traceMapFor(environment, `/${requested.slice(base.length)}`);
+		const original = map === void 0 ? void 0 : originalPositionFor(map, {
+			line: Number(frame["line"]),
+			column: Number(frame["column"]) - 1
+		});
+		if (original?.source == null) {
+			lines.push(line);
+			continue;
+		}
+		const resolved = original.source.startsWith("file://") ? new URL(original.source).pathname : original.source;
+		const source = resolved.split("?", 1)[0] ?? resolved;
+		const relative = path.relative(workspaceRoot, source);
+		const inWorkspace = !relative.startsWith("..") && !path.isAbsolute(relative);
+		const file = inWorkspace ? relative.split(path.sep).join("/") : source;
+		lines.push(`${head}${file}:${original.line}:${original.column + 1}${tail}`);
+		if (topFrame === void 0 && inWorkspace && !VENDOR.test(`/${file}`)) topFrame = `${file}:${original.line}`;
+	}
+	return {
+		stack: lines.join("\n"),
+		topFrame
+	};
+}
+//#endregion
+//#region src/vite/index.ts
+const AnnotatorOptions = z.strictObject({
+	bodies: z.array(z.string().startsWith("/")).optional(),
+	maxStoreBytes: z.number().int().positive().optional(),
+	storeRoot: z.string().min(1).optional()
+});
+/**
+* The overlay reads `bodies` from this global. Vite's client sets every
+* `define` key on globalThis in dev, so it reaches a pre-bundled overlay too.
+*/
+const BODIES_GLOBAL = "__PKA_BODIES__";
+const STAGING_DIR = ".staging";
+const MB = 1048576;
+const MAX_RECORDING_JSON_BYTES = 4 * MB;
+const execFileAsync = promisify(execFile);
+/** A staging directory named <pid>-<hex> belongs to a running process unless that pid is gone. */
+function ownerAlive(name) {
+	const pid = Number(name.split("-", 1)[0]);
+	if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (cause) {
+		return !isErrno(cause, "ESRCH");
+	}
+}
+function describeError(cause) {
+	return cause instanceof Error ? cause.message : String(cause);
+}
+async function writeChunk(file, offset, data) {
+	const handle = await open(file, constants.O_WRONLY | constants.O_NOFOLLOW);
+	try {
+		const { bytesWritten } = await handle.write(data, 0, data.length, offset);
+		if (bytesWritten !== data.length) throw new Error(`Short write to ${file}: ${bytesWritten} of ${data.length} bytes`);
+	} finally {
+		await handle.close();
+	}
+}
+async function createEmpty(file) {
+	await mkdir(path.dirname(file), { recursive: true });
+	await (await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 420)).close();
+}
+async function rewrite(file, text) {
+	const handle = await open(file, constants.O_WRONLY | constants.O_TRUNC | constants.O_NOFOLLOW);
+	try {
+		await handle.writeFile(text);
+	} finally {
+		await handle.close();
+	}
+}
+/** HEAD of the workspace when the annotation is stored, so the SHA matches the code it was taken against. */
+async function headSha(cwd) {
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"rev-parse",
+			"--verify",
+			"HEAD"
+		], {
+			cwd,
+			timeout: 5e3
+		});
+		return stdout.trim();
+	} catch (cause) {
+		const stderr = cause instanceof Error && "stderr" in cause ? String(cause.stderr) : "";
+		if (isErrno(cause, "ENOENT") || /not a git repository|Needed a single revision/.test(stderr)) return null;
+		throw new Error(`git rev-parse HEAD failed in ${cwd}: ${describeError(cause)}`, { cause });
+	}
+}
+/**
+* The command that launches pka-mcp: the workspace's bin, which survives version bumps, else
+* this package's own build, beside the built plugin or, for this repository's fixture, which
+* loads the plugin from src/vite, in dist. Null when none exists.
+*/
+async function mcpCommand(workspaceRoot) {
+	const bin = path.join(workspaceRoot, "node_modules/.bin/pka-mcp");
+	const builds = ["./pka-mcp.mjs", "../../dist/pka-mcp.mjs"].map((relative) => fileURLToPath(new URL(relative, import.meta.url)));
+	for (const [file, command] of [[bin, [normalizePath(bin)]], ...builds.map((build) => [build, ["node", normalizePath(build)]])]) if (await stat(file).catch((cause) => {
+		if (isErrno(cause, "ENOENT")) return void 0;
+		throw cause;
+	}) !== void 0) return [...command];
+	return null;
+}
+/** Opens the store, serves the overlay's channel events, and pushes store changes. Returns the closer. */
+async function serve(server, maxStoreBytes, storeRoot) {
+	const workspaceRoot = normalizePath(searchForWorkspaceRoot(server.config.root));
+	let projectRoot = workspaceRoot;
+	if (storeRoot !== void 0) {
+		projectRoot = normalizePath(path.resolve(server.config.root, storeRoot));
+		if (!(await stat(projectRoot).catch((cause) => {
+			if (isErrno(cause, "ENOENT")) return void 0;
+			throw cause;
+		}))?.isDirectory()) throw new PkaError(`storeRoot ${projectRoot} is not an existing directory`);
+	}
+	const store = await createStore(projectRoot);
+	const fromWorkspace = path.relative(await realpath(workspaceRoot), store);
+	const storeDisplay = fromWorkspace.startsWith("..") || path.isAbsolute(fromWorkspace) ? normalizePath(store) : normalizePath(fromWorkspace);
+	const stagingRoot = resolveInside(store, STAGING_DIR);
+	const serverStaging = resolveInside(stagingRoot, `${process.pid}-${randomBytes(4).toString("hex")}`);
+	const environment = server.environments.client;
+	const { hot } = environment;
+	const { logger } = server.config;
+	const uploads = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Map();
+	const listeners = [];
+	let errorsQueue = Promise.resolve();
+	let pushQueue = Promise.resolve();
+	const changed = /* @__PURE__ */ new Set();
+	let flushScheduled = false;
+	let closed = false;
+	/** Pending and acknowledged annotations only; resolved and dismissed ones are not watched. */
+	const annotationWatchers = /* @__PURE__ */ new Map();
+	const warn = (line) => logger.warn(`pk-annotator: ${line}`, { timestamp: true });
+	const error = (line) => logger.error(`pk-annotator: ${line}`, { timestamp: true });
+	/** Removes this server's abandoned requests and the staging directories of exited processes. */
+	async function removeStaleStaging() {
+		for (const name of await readdir(serverStaging)) if (!uploads.has(name)) await rm(resolveInside(serverStaging, name), {
+			recursive: true,
+			force: true
+		});
+		for (const name of await readdir(stagingRoot)) if (!ownerAlive(name)) await rm(resolveInside(stagingRoot, name), {
+			recursive: true,
+			force: true
+		});
+	}
+	async function abort(upload, cause) {
+		upload.done = true;
+		uploads.delete(upload.requestId);
+		await rm(upload.dir, {
+			recursive: true,
+			force: true
+		});
+		if (!(cause instanceof PkaError)) error(`storing annotation ${upload.requestId} failed: ${describeError(cause)}`);
+		upload.client.send(CHANNEL.createFailed, {
+			requestId: upload.requestId,
+			message: describeError(cause)
+		});
+	}
+	function enqueue(upload, step) {
+		upload.queue = upload.queue.then(async () => {
+			if (upload.done) return;
+			try {
+				await step();
+			} catch (thrown) {
+				await abort(upload, thrown);
+			}
+		}).catch((cause) => error(`cleaning up ${upload.requestId} failed: ${describeError(cause)}`));
+	}
+	/** Replaces the page's raw stack and top frame with source positions. */
+	async function symbolicateGroup(group) {
+		const { topFrame: _pageTopFrame, ...rest } = group;
+		const result = await symbolicate(environment, workspaceRoot, group.stack);
+		return result.topFrame === void 0 ? {
+			...rest,
+			stack: result.stack
+		} : {
+			...rest,
+			stack: result.stack,
+			topFrame: result.topFrame
+		};
+	}
+	async function readStagedJson(upload, relative, schema) {
+		const bytes = upload.files.get(relative)?.bytes ?? 0;
+		if (bytes > MAX_RECORDING_JSON_BYTES) throw new PkaError(`${relative} is ${Math.round(bytes / MB)} MB; the limit is 4 MB`);
+		const text = await readFile(resolveInside(upload.dir, relative), "utf8");
+		let value;
+		try {
+			value = JSON.parse(text);
+		} catch (cause) {
+			throw new PkaError(`${relative} is not JSON: ${describeError(cause)}`);
+		}
+		const parsed = schema.safeParse(value);
+		if (!parsed.success) {
+			const issue = parsed.error.issues[0];
+			throw new PkaError(`${relative} does not match its schema: ${issue === void 0 ? "invalid" : `${issue.path.join(".")}: ${issue.message}`}`);
+		}
+		return parsed.data;
+	}
+	/** Stamps the git SHA into a recording's manifest and symbolicates its error groups. */
+	async function completeRecording(upload, directory) {
+		const manifestPath = path.posix.join(directory, "manifest.json");
+		const errorsPath = path.posix.join(directory, "errors.json");
+		const manifest = {
+			...await readStagedJson(upload, manifestPath, RecordingManifestDraft),
+			gitSha: await headSha(workspaceRoot)
+		};
+		await rewrite(resolveInside(upload.dir, manifestPath), `${JSON.stringify(manifest, null, 2)}\n`);
+		if (!upload.files.has(errorsPath)) return;
+		const errors = await readStagedJson(upload, errorsPath, RecordingErrors);
+		const groups = await Promise.all(errors.groups.map(symbolicateGroup));
+		await rewrite(resolveInside(upload.dir, errorsPath), `${JSON.stringify({ groups }, null, 2)}\n`);
+	}
+	async function finish(upload) {
+		const recordingDirectories = new Set(upload.draft.attachments.filter((attachment) => attachment.kind === "recording").map((attachment) => path.posix.dirname(attachment.path)));
+		for (const directory of recordingDirectories) await completeRecording(upload, directory);
+		const { id } = await create(store, upload.draft, {
+			dir: upload.dir,
+			paths: [...upload.files.keys()]
+		});
+		upload.done = true;
+		uploads.delete(upload.requestId);
+		seen.set(id, {
+			history: 1,
+			thread: 0
+		});
+		upload.client.send(CHANNEL.created, {
+			requestId: upload.requestId,
+			id,
+			dir: path.posix.join(storeDisplay, id)
+		});
+	}
+	async function prepare(upload, declaredBytes) {
+		if ([...upload.files.keys()].some((file) => file.endsWith(".webm") || file.endsWith(".gif")) || upload.draft.attachments.some((attachment) => attachment.kind === "video")) {
+			const size = await checkStoreSize(store, maxStoreBytes);
+			if (size.bytes + declaredBytes > maxStoreBytes) throw new PkaError(`The annotation store holds ${Math.round(size.bytes / MB)} MB; this ${Math.round(declaredBytes / MB)} MB recording would pass the ${Math.round(maxStoreBytes / MB)} MB cap. Run pka prune or remove old annotations, or send it without video.`);
+		}
+		await removeStaleStaging();
+		await mkdir(upload.dir);
+		for (const file of upload.files.keys()) await createEmpty(resolveInside(upload.dir, file));
+	}
+	function listen(event, schema, handle) {
+		const listener = (data, client) => {
+			const parsed = schema.safeParse(data);
+			if (!parsed.success) {
+				const issue = parsed.error.issues[0];
+				warn(`dropped ${event}: ${issue === void 0 ? "invalid" : `${issue.path.join(".") || "payload"}: ${issue.message}`}` + (parsed.error.issues.length > 1 ? ` (+${parsed.error.issues.length - 1} more)` : ""));
+				return;
+			}
+			handle(parsed.data, client).catch((cause) => error(`${event} failed: ${describeError(cause)}`));
+		};
+		hot.on(event, listener);
+		listeners.push([event, listener]);
+	}
+	listen(CHANNEL.create, CreateMessage, async (message, client) => {
+		const { requestId } = message;
+		const refuse = (reason) => client.send(CHANNEL.createFailed, {
+			requestId,
+			message: reason
+		});
+		if (uploads.has(requestId)) {
+			refuse(`Request ${requestId} is already in progress`);
+			return;
+		}
+		try {
+			checkCaptureFiles(message.draft, message.files.map((file) => file.path));
+		} catch (thrown) {
+			if (!(thrown instanceof PkaError)) throw thrown;
+			refuse(thrown.message);
+			return;
+		}
+		const declaredBytes = message.files.reduce((total, file) => total + file.bytes, 0);
+		const upload = {
+			requestId,
+			client,
+			dir: resolveInside(serverStaging, requestId),
+			draft: message.draft,
+			files: new Map(message.files.map((file) => [file.path, {
+				bytes: file.bytes,
+				received: 0
+			}])),
+			remaining: declaredBytes,
+			done: false,
+			queue: Promise.resolve()
+		};
+		uploads.set(requestId, upload);
+		enqueue(upload, () => prepare(upload, declaredBytes));
+		if (declaredBytes === 0) enqueue(upload, () => finish(upload));
+	});
+	listen(CHANNEL.file, FileChunkMessage, async (message, client) => {
+		const upload = uploads.get(message.requestId);
+		if (upload === void 0 || upload.client !== client) {
+			warn(`dropped ${CHANNEL.file}: no upload ${message.requestId} in progress for this page`);
+			return;
+		}
+		const file = upload.files.get(message.path);
+		const data = Buffer.from(message.data, "base64");
+		if (file === void 0 || message.offset !== file.received || file.received + data.length > file.bytes) {
+			const reason = new PkaError(file === void 0 ? `Chunk for ${message.path}, which the request did not declare` : `Chunk for ${message.path} at offset ${message.offset} does not continue the ${file.received} of ${file.bytes} bytes received`);
+			enqueue(upload, () => Promise.reject(reason));
+			return;
+		}
+		file.received += data.length;
+		upload.remaining -= data.length;
+		const target = resolveInside(upload.dir, message.path);
+		enqueue(upload, () => writeChunk(target, message.offset, data));
+		if (upload.remaining === 0) enqueue(upload, () => finish(upload));
+	});
+	listen(CHANNEL.errors, ErrorsMessage, async (message, client) => {
+		const groups = await Promise.all(message.groups.map(symbolicateGroup));
+		const write = errorsQueue.then(() => upsertErrorGroups(store, groups));
+		errorsQueue = write.then(() => void 0, () => void 0);
+		await write;
+		const ack = { groups: groups.map((group) => group.topFrame === void 0 ? {
+			fingerprint: group.fingerprint,
+			stack: group.stack
+		} : {
+			fingerprint: group.fingerprint,
+			stack: group.stack,
+			topFrame: group.topFrame
+		}) };
+		client.send(CHANNEL.errorsAck, ack);
+	});
+	listen(CHANNEL.symbolicate, SymbolicateMessage, async (message, client) => {
+		const stacks = await Promise.all(message.stacks.map(async (stack) => (await symbolicate(environment, workspaceRoot, stack)).stack));
+		const reply = {
+			requestId: message.requestId,
+			stacks
+		};
+		client.send(CHANNEL.symbolicated, reply);
+	});
+	listen(CHANNEL.setup, SetupMessage, async (message, client) => {
+		const reply = {
+			requestId: message.requestId,
+			root: projectRoot,
+			store: normalizePath(store),
+			command: await mcpCommand(workspaceRoot)
+		};
+		client.send(CHANNEL.setupInfo, reply);
+	});
+	listen(CHANNEL.sync, SyncMessage, async (message, client) => {
+		const synced = { annotations: [] };
+		for (const id of message.ids) try {
+			const record = await loadAnnotationUpdates(store, id);
+			synced.annotations.push({
+				id,
+				state: record.state,
+				thread: record.thread
+			});
+		} catch (thrown) {
+			if (!(thrown instanceof MissingAnnotationError)) throw thrown;
+		}
+		client.send(CHANNEL.synced, synced);
+	});
+	const onDisconnect = (_data, client) => {
+		for (const upload of uploads.values()) if (upload.client === client) enqueue(upload, () => Promise.reject(new PkaError("The page disconnected before the upload finished")));
+	};
+	hot.on("vite:client:disconnect", onDisconnect);
+	listeners.push(["vite:client:disconnect", onDisconnect]);
+	let agentPushed = "";
+	let agentQueue = Promise.resolve();
+	let agentScheduled = false;
+	async function readAgent() {
+		const { agents, invalid } = await liveAgents(store);
+		for (const { file, reason } of invalid) warn(`ignored agent presence ${file}: ${reason}`);
+		const latest = agents[0];
+		return latest === void 0 ? null : {
+			name: latest.name,
+			version: latest.version,
+			connectedAt: latest.connectedAt
+		};
+	}
+	/** Broadcasts the active agent when it differs from the last broadcast. */
+	function pushAgent(agent) {
+		const text = JSON.stringify(agent);
+		if (text === agentPushed || closed) return;
+		agentPushed = text;
+		const message = {
+			agent,
+			cause: "change"
+		};
+		hot.send(CHANNEL.agent, message);
+	}
+	function refreshAgent() {
+		agentScheduled = false;
+		agentQueue = agentQueue.then(async () => pushAgent(await readAgent())).catch((cause) => error(`reading agent presence failed: ${describeError(cause)}`));
+	}
+	listen(CHANNEL.presence, PresenceMessage, async (_message, client) => {
+		const answered = agentQueue.then(async () => {
+			const agent = await readAgent();
+			pushAgent(agent);
+			if (agent !== null) {
+				const message = {
+					agent,
+					cause: "presence"
+				};
+				client.send(CHANNEL.agent, message);
+			}
+		});
+		agentQueue = answered.catch(() => void 0);
+		await answered;
+	});
+	function schedule(id) {
+		changed.add(id);
+		if (flushScheduled) return;
+		flushScheduled = true;
+		setImmediate(flush);
+	}
+	function unwatch(id) {
+		annotationWatchers.get(id)?.close();
+		annotationWatchers.delete(id);
+	}
+	/**
+	* Brings one annotation's watch and broadcasts up to date. An annotation
+	* seen for the first time sets the baseline without broadcasting.
+	*/
+	async function sync(id) {
+		let record;
+		try {
+			record = await loadAnnotationUpdates(store, id);
+		} catch (thrown) {
+			if (!(thrown instanceof MissingAnnotationError)) throw thrown;
+			unwatch(id);
+			seen.delete(id);
+			return;
+		}
+		if (closed) return;
+		const known = seen.get(id);
+		if (known !== void 0) {
+			if (record.state.history.length !== known.history) hot.send(CHANNEL.state, {
+				id,
+				state: record.state
+			});
+			for (const entry of record.thread.slice(known.thread)) hot.send(CHANNEL.thread, {
+				id,
+				entry
+			});
+		}
+		seen.set(id, {
+			history: record.state.history.length,
+			thread: record.thread.length
+		});
+		if (record.state.status === "resolved" || record.state.status === "dismissed") {
+			unwatch(id);
+			return;
+		}
+		if (annotationWatchers.has(id)) return;
+		const watcher = watch(record.dir, (_event, filename) => {
+			if (filename === "state.json" || filename === "thread.jsonl") schedule(id);
+		});
+		watcher.on("error", (cause) => {
+			error(`watching annotation ${id} failed: ${describeError(cause)}`);
+			unwatch(id);
+		});
+		annotationWatchers.set(id, watcher);
+		schedule(id);
+	}
+	function flush() {
+		flushScheduled = false;
+		const ids = [...changed];
+		changed.clear();
+		pushQueue = pushQueue.then(async () => {
+			for (const id of ids) await sync(id).catch((cause) => error(`reading annotation ${id} failed: ${describeError(cause)}`));
+		});
+	}
+	await mkdir(stagingRoot, { recursive: true });
+	if ((await lstat(stagingRoot)).isSymbolicLink()) throw new PkaError(`Refusing symlink in the annotation store: ${stagingRoot}`);
+	await mkdir(serverStaging);
+	await removeStaleStaging();
+	const storeWatcher = watch(store, (_event, filename) => {
+		if (filename !== null && ID_PATTERN.test(filename)) schedule(filename);
+	});
+	storeWatcher.on("error", (cause) => error(`store watcher failed: ${describeError(cause)}`));
+	for (const id of await listIds(store)) schedule(id);
+	await mkdir(agentsDir(store), { recursive: true });
+	const agentWatcher = watch(agentsDir(store), () => {
+		if (agentScheduled) return;
+		agentScheduled = true;
+		setImmediate(refreshAgent);
+	});
+	agentWatcher.on("error", (cause) => error(`agent watcher failed: ${describeError(cause)}`));
+	agentPushed = JSON.stringify(await readAgent());
+	return async () => {
+		closed = true;
+		storeWatcher.close();
+		agentWatcher.close();
+		for (const watcher of annotationWatchers.values()) watcher.close();
+		annotationWatchers.clear();
+		for (const [event, listener] of listeners) hot.off(event, listener);
+		for (const upload of uploads.values()) upload.done = true;
+		uploads.clear();
+		await rm(serverStaging, {
+			recursive: true,
+			force: true
+		});
+	};
+}
+function channelPlugin(maxStoreBytes, bodies, storeRoot) {
+	let close;
+	return {
+		name: "pk-annotator:channel",
+		apply: "serve",
+		config() {
+			return { define: { [BODIES_GLOBAL]: JSON.stringify(bodies) } };
+		},
+		async configureServer(server) {
+			close = await serve(server, maxStoreBytes, storeRoot);
+		},
+		async buildEnd() {
+			const closing = close;
+			close = void 0;
+			await closing?.();
+		}
+	};
+}
+/** Dev-server plugins: source attributes, the overlay channel, symbolication, and the store watcher. Nothing runs in builds or under Vitest. */
+function annotator(options = {}) {
+	const parsed = AnnotatorOptions.parse(options);
+	if (process.env.VITEST) return [];
+	return [sourcePlugin(), channelPlugin(parsed.maxStoreBytes ?? 524288e3, parsed.bodies ?? [], parsed.storeRoot)];
+}
+//#endregion
+export { BODIES_GLOBAL, annotator };