pk-annotator 0.7.0 → 0.8.0

package/dist/pka.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { B as Id, F as readJsonLines, I as resolveInside, M as isErrno, O as PkaError, P as readJson, S as wait, W as Timestamp, _ as prune, a as ErrorsInput, c as ReplyInput, h as list, i as TimelineEntry, j as findStore, l as SetStatusInput, m as get, n as RecordingManifest, o as GetInput, p as errors, s as ListInput, u as attach, v as reply, x as validateAttachTarget, y as setStatus, z as ID_PATTERN } from "./recording-82fajWWq.mjs";
+import { B as Id, F as readJsonLines, I as resolveInside, M as isErrno, O as PkaError, P as readJson, S as wait, W as Timestamp, _ as prune, a as ErrorsInput, c as ReplyInput, h as list, i as TimelineEntry, j as findStore, l as SetStatusInput, m as get, n as RecordingManifest, o as GetInput, p as errors, s as ListInput, u as attach, v as reply, x as validateAttachTarget, y as setStatus, z as ID_PATTERN } from "./recording-D_Qkyq0N.mjs";
 import { createRequire } from "node:module";
 import { createWriteStream } from "node:fs";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
@@ -798,6 +798,7 @@ async function locate(page, target, step) {
 	let notes = [];
 	for (;;) {
 		notes = [];
+		let ambiguous = false;
 		for (const [strategy, locator] of strategies) {
 			let count;
 			try {
@@ -808,7 +809,25 @@ async function locate(page, target, step) {
 				continue;
 			}
 			if (count === 1) return locator;
-			if (count > 1) notes.push(`${strategy} matched ${count}`);
+			if (count > 1) {
+				ambiguous = true;
+				notes.push(`${strategy} matched ${count}`);
+			}
+		}
+		if (!ambiguous && target.label !== void 0) {
+			const fields = page.locator(target.tag);
+			const matches = await fields.evaluateAll((elements, { label, cap }) => elements.flatMap((element, index) => {
+				if (!(element instanceof HTMLInputElement) && !(element instanceof HTMLTextAreaElement) && !(element instanceof HTMLSelectElement) && !(element instanceof HTMLFormElement) && !(element instanceof HTMLElement && element.isContentEditable)) return [];
+				const labels = element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement ? element.labels : null;
+				if (element.hasAttribute("aria-label") || element.hasAttribute("aria-labelledby") || labels !== null && labels.length > 0) return [];
+				return (element.getAttribute("name") ?? element.getAttribute("placeholder"))?.replace(/\s+/g, " ").trim().slice(0, cap) === label ? [index] : [];
+			}), {
+				label: target.label,
+				cap: TEXT_CAP
+			});
+			const index = matches[0];
+			if (matches.length === 1 && index !== void 0) return fields.nth(index);
+			if (matches.length > 1) notes.push(`name or placeholder matched ${matches.length}`);
 		}
 		if (Date.now() >= deadline) break;
 		await setTimeout(100);
@@ -850,14 +869,14 @@ async function settle(page, tracker) {
 function samePage(current, target) {
 	const a = new URL(current);
 	const b = new URL(target);
-	return a.origin === b.origin && a.pathname === b.pathname && a.search === b.search;
+	return a.origin === b.origin && a.pathname === b.pathname && a.search === b.search && a.hash === b.hash;
 }
 function producedByReplay(step, target, state) {
 	const want = new URL(target);
 	return state.changes.some(({ type, url, entered }) => {
 		if (type === "reload" || type === "traverse" !== (step.type === "traverse")) return false;
 		const got = new URL(url);
-		if (got.origin !== want.origin || got.pathname !== want.pathname) return false;
+		if (got.origin !== want.origin || got.pathname !== want.pathname || got.hash !== want.hash) return false;
 		return entered || got.search === want.search;
 	});
 }

package/dist/{recording-82fajWWq.mjs → recording-D_Qkyq0N.mjs}

@@ -28,6 +28,11 @@ const Selector = z.strictObject({
 	testId: z.string().optional(),
 	css: z.string()
 });
+const Quote = z.strictObject({
+	exact: z.string().min(1),
+	prefix: z.string(),
+	suffix: z.string()
+});
 const ElementRef = z.strictObject({
 	n: z.number().int().positive(),
 	url: z.string().optional(),
@@ -39,7 +44,8 @@ const ElementRef = z.strictObject({
 	box: Box,
 	crop: RelativePath.optional(),
 	text: z.string().optional(),
-	nearbyText: z.string().optional()
+	nearbyText: z.string().optional(),
+	quote: Quote.optional()
 });
 const AttachmentKind = z.enum([
 	"recording",
@@ -528,6 +534,11 @@ async function withAnnotationLock(store, id, act) {
 	const files = await requireAnnotation(store, id);
 	return withLock(store, resolveInside(files.dir, "state.lock"), Date.now() + LOCK_WAIT_MS, () => act(files));
 }
+async function withLiveErrorsLock(store, act) {
+	const lock = resolveInside(store, "live", "errors.lock");
+	await refuseSymlinks(store, lock);
+	return withLock(store, lock, Date.now() + LOCK_WAIT_MS, act);
+}
 async function readClaim(store, id) {
 	const files = annotationFiles(store, id);
 	try {
@@ -753,6 +764,11 @@ const ElementView = z.strictObject({
 	}),
 	crop: z.string().optional(),
 	text: z.string().optional(),
+	quote: z.strictObject({
+		exact: z.string(),
+		prefix: z.string(),
+		suffix: z.string()
+	}).optional().describe("Text the human selected inside the element, with the text just before and after it"),
 	nearbyText: z.string().optional(),
 	html: z.string().optional(),
 	box: Box.optional()
@@ -829,6 +845,11 @@ function elementView(element, detail) {
 		crop: element.crop,
 		text: optionalPageText(element.text, full ? CAP.text : CAP.short)
 	};
+	if (element.quote !== void 0) view.quote = {
+		exact: pageText(element.quote.exact, full ? CAP.html : CAP.text),
+		prefix: pageText(element.quote.prefix, CAP.short),
+		suffix: pageText(element.quote.suffix, CAP.short)
+	};
 	if (full) {
 		view.nearbyText = optionalPageText(element.nearbyText, CAP.text);
 		view.html = pageText(element.html, CAP.html);
@@ -1324,14 +1345,16 @@ async function errors(store, input) {
 }
 /** Merges new or changed groups into live/errors.json by fingerprint. Used by the Vite plugin. */
 async function upsertErrorGroups(store, groups) {
-	const merged = new Map(((await readErrors(store))?.groups ?? []).map((group) => [group.fingerprint, group]));
-	for (const group of groups) merged.set(group.fingerprint, group);
-	const snapshot = {
-		updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		groups: [...merged.values()].sort((a, b) => Date.parse(b.lastSeen) - Date.parse(a.lastSeen)).slice(0, MAX_ERROR_GROUPS)
-	};
-	await writeJsonAtomic(store, liveErrorsFile(store), snapshot);
-	return snapshot;
+	return withLiveErrorsLock(store, async () => {
+		const merged = new Map(((await readErrors(store))?.groups ?? []).map((group) => [group.fingerprint, group]));
+		for (const group of groups) merged.set(group.fingerprint, group);
+		const snapshot = {
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			groups: [...merged.values()].sort((a, b) => Date.parse(b.lastSeen) - Date.parse(a.lastSeen)).slice(0, MAX_ERROR_GROUPS)
+		};
+		await writeJsonAtomic(store, liveErrorsFile(store), snapshot);
+		return snapshot;
+	});
 }
 /**
 * Checks the capture files an annotation declares: each under capture/, listed

package/dist/vite.mjs

@@ -1,4 +1,4 @@
-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-82fajWWq.mjs";
+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-D_Qkyq0N.mjs";
 import { createRequire } from "node:module";
 import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
@@ -15,6 +15,9 @@ import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping";
 const CHANNEL = {
 	create: "pka:create",
 	file: "pka:file",
+	uploadReady: "pka:upload-ready",
+	fileWritten: "pka:file-written",
+	cancelUpload: "pka:cancel-upload",
 	errors: "pka:errors",
 	created: "pka:created",
 	createFailed: "pka:create-failed",
@@ -48,6 +51,7 @@ const FileChunkMessage = z.strictObject({
 	offset: z.number().int().nonnegative(),
 	data: z.base64().max(Math.ceil(MAX_CHUNK_BYTES / 3) * 4)
 });
+const CancelUploadMessage = z.strictObject({ requestId: Id });
 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({
@@ -61,6 +65,12 @@ const InstallUpdateMessage = z.strictObject({
 	requestId: Id,
 	version: Version
 });
+z.strictObject({ requestId: Id });
+z.strictObject({
+	requestId: Id,
+	path: RelativePath,
+	offset: z.number().int().nonnegative()
+});
 z.strictObject({
 	requestId: Id,
 	id: Id,
@@ -468,6 +478,7 @@ const BODIES_GLOBAL = "__PKA_BODIES__";
 const STAGING_DIR = ".staging";
 const MB = 1048576;
 const MAX_RECORDING_JSON_BYTES = 4 * MB;
+const MAX_UPLOADS = 8;
 const execFileAsync = promisify(execFile);
 /** A staging directory named <pid>-<hex> belongs to a running process unless that pid is gone. */
 function ownerAlive(name) {
@@ -597,10 +608,17 @@ async function serve(server, maxStoreBytes, storeRoot) {
 			try {
 				await step();
 			} catch (thrown) {
-				await abort(upload, thrown);
+				if (!upload.done) await abort(upload, thrown);
 			}
 		}).catch((cause) => error(`cleaning up ${upload.requestId} failed: ${describeError(cause)}`));
 	}
+	function cancel(upload, reason) {
+		if (upload.done) return;
+		upload.done = true;
+		upload.queue = upload.queue.then(async () => {
+			if (uploads.get(upload.requestId) === upload) await abort(upload, reason);
+		}).catch((cause) => error(`upload cleanup failed: ${describeError(cause)}`));
+	}
 	/** Replaces the page's raw stack and top frame with source positions. */
 	async function symbolicateGroup(group) {
 		const { topFrame: _pageTopFrame, ...rest } = group;
@@ -647,7 +665,11 @@ async function serve(server, maxStoreBytes, storeRoot) {
 	}
 	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);
+		for (const directory of recordingDirectories) {
+			await completeRecording(upload, directory);
+			if (upload.done) return;
+		}
+		if (upload.done) return;
 		const { id } = await create(store, upload.draft, {
 			dir: upload.dir,
 			paths: [...upload.files.keys()]
@@ -696,6 +718,10 @@ async function serve(server, maxStoreBytes, storeRoot) {
 			refuse(`Request ${requestId} is already in progress`);
 			return;
 		}
+		if (uploads.size >= MAX_UPLOADS || [...uploads.values()].some((upload) => upload.client === client)) {
+			refuse("Another upload is in progress; wait for it to finish and retry");
+			return;
+		}
 		try {
 			checkCaptureFiles(message.draft, message.files.map((file) => file.path));
 		} catch (thrown) {
@@ -715,11 +741,19 @@ async function serve(server, maxStoreBytes, storeRoot) {
 			}])),
 			remaining: declaredBytes,
 			done: false,
+			busy: true,
 			queue: Promise.resolve()
 		};
 		uploads.set(requestId, upload);
-		enqueue(upload, () => prepare(upload, declaredBytes));
-		if (declaredBytes === 0) enqueue(upload, () => finish(upload));
+		enqueue(upload, async () => {
+			await prepare(upload, declaredBytes);
+			if (upload.done) return;
+			if (declaredBytes === 0) await finish(upload);
+			else {
+				upload.busy = false;
+				client.send(CHANNEL.uploadReady, { requestId });
+			}
+		});
 	});
 	listen(CHANNEL.file, FileChunkMessage, async (message, client) => {
 		const upload = uploads.get(message.requestId);
@@ -727,18 +761,36 @@ async function serve(server, maxStoreBytes, storeRoot) {
 			warn(`dropped ${CHANNEL.file}: no upload ${message.requestId} in progress for this page`);
 			return;
 		}
+		if (upload.done) return;
+		if (upload.busy) {
+			cancel(upload, new PkaError("Wait for the upload acknowledgement before sending another chunk; reload the page and retry"));
+			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));
+		if (file === void 0 || data.length === 0 || message.offset !== file.received || file.received + data.length > file.bytes) {
+			cancel(upload, 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`));
 			return;
 		}
 		file.received += data.length;
 		upload.remaining -= data.length;
+		upload.busy = true;
 		const target = resolveInside(upload.dir, message.path);
-		enqueue(upload, () => writeChunk(target, message.offset, data));
-		if (upload.remaining === 0) enqueue(upload, () => finish(upload));
+		enqueue(upload, async () => {
+			await writeChunk(target, message.offset, data);
+			if (upload.done) return;
+			if (upload.remaining !== 0) upload.busy = false;
+			client.send(CHANNEL.fileWritten, {
+				requestId: upload.requestId,
+				path: message.path,
+				offset: file.received
+			});
+			if (upload.remaining === 0) await finish(upload);
+		});
+	});
+	listen(CHANNEL.cancelUpload, CancelUploadMessage, async (message, client) => {
+		const upload = uploads.get(message.requestId);
+		if (upload?.client === client) cancel(upload, new PkaError("The page cancelled the upload"));
 	});
 	listen(CHANNEL.errors, ErrorsMessage, async (message, client) => {
 		const groups = await Promise.all(message.groups.map(symbolicateGroup));
@@ -808,7 +860,7 @@ async function serve(server, maxStoreBytes, storeRoot) {
 		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")));
+		for (const upload of uploads.values()) if (upload.client === client) cancel(upload, new PkaError("The page disconnected before the upload finished"));
 	};
 	hot.on("vite:client:disconnect", onDisconnect);
 	listeners.push(["vite:client:disconnect", onDisconnect]);
@@ -946,6 +998,7 @@ async function serve(server, maxStoreBytes, storeRoot) {
 		annotationWatchers.clear();
 		for (const [event, listener] of listeners) hot.off(event, listener);
 		for (const upload of uploads.values()) upload.done = true;
+		await Promise.all([...uploads.values()].map((upload) => upload.queue));
 		uploads.clear();
 		await rm(serverStaging, {
 			recursive: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pk-annotator",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Dev-only browser annotation overlay for Vite apps that sends picked elements, captures, and prompts to Claude Code and Codex through an MCP server.",
   "keywords": [
     "annotation",