pk-annotator 0.6.0

package/dist/pka.mjs

@@ -0,0 +1,1678 @@
+#!/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-CpEDddkZ.mjs";
+import { createRequire } from "node:module";
+import { createWriteStream } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { z } from "zod";
+import { tmpdir } from "node:os";
+import { setTimeout } from "node:timers/promises";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+//#region src/shared/verdict.ts
+const LabMetric = z.enum([
+	"LCP",
+	"INP",
+	"CLS"
+]);
+const NetworkPreset = z.enum([
+	"slow4g",
+	"fast4g",
+	"none"
+]);
+const LoafScript = z.strictObject({
+	url: z.string(),
+	function: z.string(),
+	invoker: z.string(),
+	subpart: z.string(),
+	durationMs: z.number()
+});
+const HotFunction = z.strictObject({
+	function: z.string(),
+	url: z.string(),
+	line: z.number().int().positive(),
+	column: z.number().int().positive(),
+	selfMs: z.number()
+});
+const Culprit = z.strictObject({
+	run: z.number().int().positive(),
+	page: z.string(),
+	element: z.string().optional(),
+	resource: z.string().optional(),
+	breakdown: z.record(z.string(), z.number()),
+	script: LoafScript.optional(),
+	hotFunction: HotFunction.optional(),
+	insight: z.string().optional()
+});
+const MetricVerdict = z.strictObject({
+	unit: z.enum(["ms", "score"]),
+	values: z.array(z.number().nullable()).describe("Per run; null when the run did not report it"),
+	median: z.number().nullable(),
+	min: z.number().nullable(),
+	max: z.number().nullable(),
+	band: z.number().nullable().describe("max minus min"),
+	budget: z.number(),
+	status: z.enum([
+		"pass",
+		"fail",
+		"unmeasured"
+	]),
+	culprit: Culprit.optional().describe("From the run whose value is the median"),
+	note: z.string().optional()
+});
+const InsightVerdict = z.strictObject({
+	name: z.string(),
+	page: z.string(),
+	state: z.enum([
+		"pass",
+		"fail",
+		"informative"
+	]),
+	runs: z.number().int().nonnegative(),
+	failed: z.number().int().nonnegative(),
+	summary: z.string()
+});
+const Verdict = z.strictObject({
+	version: z.literal(1),
+	createdAt: Timestamp,
+	status: z.enum([
+		"pass",
+		"fail",
+		"incomplete"
+	]),
+	conditions: z.strictObject({
+		url: z.string(),
+		flow: z.string(),
+		steps: z.number().int().nonnegative(),
+		runs: z.number().int().positive(),
+		measurementTracing: z.literal(false).optional(),
+		diagnosticRuns: z.number().int().nonnegative().max(1).optional(),
+		cpuRate: z.number().positive(),
+		network: NetworkPreset,
+		networkConditions: z.strictObject({
+			latencyMs: z.number(),
+			downloadBytesPerSec: z.number(),
+			uploadBytesPerSec: z.number()
+		}).nullable(),
+		cache: z.literal("cold"),
+		chromium: z.string(),
+		viewport: z.string()
+	}),
+	metrics: z.strictObject({
+		LCP: MetricVerdict,
+		INP: MetricVerdict,
+		CLS: MetricVerdict
+	}),
+	insights: z.array(InsightVerdict),
+	unavailable: z.array(z.strictObject({
+		name: z.string(),
+		reason: z.string()
+	})),
+	failures: z.array(z.strictObject({
+		run: z.number().int().positive(),
+		step: z.number().int().nonnegative().optional(),
+		message: z.string()
+	})),
+	traces: z.array(z.string())
+});
+//#endregion
+//#region src/lab/insights.ts
+const REQUESTED_INSIGHTS = [
+	"LCPBreakdown",
+	"INPBreakdown",
+	"CLSCulprits",
+	"RenderBlocking",
+	"ForcedReflow",
+	"DocumentLatency",
+	"NetworkDependencyTree"
+];
+const SUMMARY_CAP = 400;
+/** A trace that could not be recorded, saved, or parsed; it costs the insights, not the verdict. */
+var TraceError = class extends Error {};
+let engine;
+var NodeDOMRect = class {
+	x;
+	y;
+	width;
+	height;
+	constructor(x = 0, y = 0, width = 0, height = 0) {
+		this.x = x;
+		this.y = y;
+		this.width = width;
+		this.height = height;
+	}
+	get left() {
+		return this.x + Math.min(0, this.width);
+	}
+	get right() {
+		return this.x + Math.max(0, this.width);
+	}
+	get top() {
+		return this.y + Math.min(0, this.height);
+	}
+	get bottom() {
+		return this.y + Math.max(0, this.height);
+	}
+};
+function loadEngine() {
+	if (!("DOMRect" in globalThis)) Object.defineProperty(globalThis, "DOMRect", {
+		value: NodeDOMRect,
+		configurable: true
+	});
+	engine ??= import("@paulirish/trace_engine");
+	return engine;
+}
+const ms = (micro) => Math.round(micro / 1e3);
+function cap(text) {
+	return text.length <= SUMMARY_CAP ? text : `${text.slice(0, 399)}…`;
+}
+function uiText(text) {
+	return text.i18nId.replace(/\{(\w+)\}/g, (match, key) => {
+		const value = text.values?.[key];
+		return value === void 0 ? match : String(value);
+	});
+}
+function frameLabel(frame) {
+	if (frame === null) return "(unknown)";
+	return `${frame.functionName || "(anonymous)"} ${frame.url}:${frame.lineNumber + 1}`;
+}
+function lcpSummary(model) {
+	if (model.lcpMs === void 0 || model.subparts === void 0) return "No LCP in this page";
+	const parts = Object.entries(model.subparts).filter(([, subpart]) => subpart !== void 0).map(([part, subpart]) => `${part} ${ms(subpart.range)} ms`);
+	const request = model.lcpRequest === void 0 ? "text" : model.lcpRequest.args.data.url;
+	return `LCP ${Math.round(model.lcpMs)} ms (${request}): ${parts.join(", ")}`;
+}
+function inpSummary(model) {
+	const event = model.longestInteractionEvent;
+	if (event === void 0) return "No interactions in this page";
+	return `Longest interaction ${event.type} ${ms(event.dur)} ms: input delay ${ms(event.inputDelay)} ms, processing ${ms(event.mainThreadHandling)} ms, presentation ${ms(event.presentationDelay)} ms`;
+}
+function clsSummary(model) {
+	const worst = model.worstCluster;
+	if (worst === void 0) return "No layout shifts";
+	const culprits = (model.topCulpritsByCluster.get(worst) ?? []).map((item) => uiText(item.description));
+	return `Worst cluster ${Math.round(worst.clusterCumulativeScore * 1e4) / 1e4}; ${culprits.length > 0 ? `culprits: ${culprits.join("; ")}` : "no culprit identified"}`;
+}
+function renderBlockingSummary(model) {
+	const requests = model.renderBlockingRequests;
+	if (requests.length === 0) return "No render-blocking requests";
+	const saving = model.metricSavings?.FCP;
+	const urls = requests.map((request) => request.args.data.url).join(", ");
+	return `${requests.length} render-blocking: ${urls}${saving === void 0 ? "" : `; FCP saving ~${Math.round(saving)} ms`}`;
+}
+function forcedReflowSummary(model) {
+	const top = model.topLevelFunctionCallData;
+	const sites = model.aggregatedBottomUpData.slice(0, 3).map((site) => `${frameLabel(site.bottomUpData)} ${ms(site.totalTime)} ms`);
+	if (top === void 0 && sites.length === 0) return "No forced reflow";
+	return `${top === void 0 ? "" : `${ms(top.totalReflowTime)} ms forced reflow; `}${sites.join("; ")}`;
+}
+function documentLatencySummary(model) {
+	const data = model.data;
+	if (data === void 0) return "No document request";
+	const failed = Object.values(data.checklist).filter((item) => !item.value).map((item) => uiText(item.label));
+	const timing = `Server response ${Math.round(data.serverResponseTime)} ms, redirects ${Math.round(data.redirectDuration)} ms`;
+	return failed.length > 0 ? `${timing}; failed: ${failed.join("; ")}` : timing;
+}
+function dependencySummary(model) {
+	let chain = [];
+	let nodes = model.rootNodes;
+	while (nodes.length > 0) {
+		const next = nodes.find((node) => node.isLongest) ?? nodes[0];
+		if (next === void 0) break;
+		chain.push(new URL(next.request.args.data.url).pathname);
+		nodes = next.children;
+	}
+	if (chain.length > 6) chain = [
+		...chain.slice(0, 3),
+		"…",
+		...chain.slice(-2)
+	];
+	return `Critical chain ${ms(model.maxTime)} ms: ${chain.join(" → ") || "none"}`;
+}
+function genericSummary(model) {
+	const savings = Object.entries(model.metricSavings ?? {}).map(([metric, value]) => `${metric} ${Math.round(Number(value))}`).join(", ");
+	return `${uiText(model.title)}${savings === "" ? "" : ` (savings: ${savings})`}`;
+}
+function summarize(name, models) {
+	switch (name) {
+		case "LCPBreakdown": return models.LCPBreakdown && lcpSummary(models.LCPBreakdown);
+		case "INPBreakdown": return models.INPBreakdown && inpSummary(models.INPBreakdown);
+		case "CLSCulprits": return models.CLSCulprits && clsSummary(models.CLSCulprits);
+		case "RenderBlocking": return models.RenderBlocking && renderBlockingSummary(models.RenderBlocking);
+		case "ForcedReflow": return models.ForcedReflow && forcedReflowSummary(models.ForcedReflow);
+		case "DocumentLatency": return models.DocumentLatency && documentLatencySummary(models.DocumentLatency);
+		case "NetworkDependencyTree": return models.NetworkDependencyTree && dependencySummary(models.NetworkDependencyTree);
+		default: {
+			const model = models[name];
+			return model && genericSummary(model);
+		}
+	}
+}
+function longestInteraction(sets) {
+	let longest;
+	for (const set of sets) {
+		const event = set.model.INPBreakdown?.longestInteractionEvent;
+		if (event !== void 0 && (longest === void 0 || event.dur > longest.dur)) longest = event;
+	}
+	return longest;
+}
+function hotFunction(parsed, interaction) {
+	const thread = parsed.data.Renderer.processes.get(interaction.pid)?.threads.get(interaction.tid);
+	if (thread === void 0) return void 0;
+	const start = interaction.ts;
+	const end = interaction.ts + interaction.dur;
+	const totals = /* @__PURE__ */ new Map();
+	for (const call of thread.profileCalls) {
+		if (call.ts < start || call.ts >= end || call.callFrame.url === "") continue;
+		const self = parsed.data.Renderer.entryToNode.get(call)?.selfTime ?? 0;
+		const frame = call.callFrame;
+		const key = `${frame.url}:${frame.lineNumber}:${frame.columnNumber}:${frame.functionName}`;
+		const total = totals.get(key) ?? {
+			function: frame.functionName || "(anonymous)",
+			url: frame.url,
+			line: frame.lineNumber + 1,
+			column: frame.columnNumber + 1,
+			selfMs: 0
+		};
+		total.selfMs += self / 1e3;
+		totals.set(key, total);
+	}
+	let top;
+	for (const total of totals.values()) if (top === void 0 || total.selfMs > top.selfMs) top = total;
+	if (top === void 0 || Math.round(top.selfMs) === 0) return void 0;
+	return {
+		...top,
+		selfMs: Math.round(top.selfMs)
+	};
+}
+/** Parses one trace with the DevTools trace engine and reduces its insights to short summaries. */
+async function analyzeTrace(events) {
+	const model = (await loadEngine()).TraceModel.Model.createWithAllHandlers();
+	try {
+		await model.parse(events);
+	} catch (thrown) {
+		throw new TraceError(`trace_engine could not parse the trace: ${thrown instanceof Error ? thrown.message : String(thrown)}`, { cause: thrown });
+	}
+	const parsed = model.parsedTrace();
+	if (parsed === null) throw new Error("trace_engine parsed the trace but returned no data");
+	const sets = [...parsed.insights?.values() ?? []].filter((set) => set.url.protocol.startsWith("http"));
+	const insights = [];
+	const unavailable = [];
+	if (sets.length === 0) for (const name of REQUESTED_INSIGHTS) unavailable.push({
+		name,
+		reason: "the trace has no page navigation to compute insights for"
+	});
+	for (const set of sets) {
+		const requested = new Set(REQUESTED_INSIGHTS);
+		for (const name of Object.keys(set.model)) {
+			const insight = set.model[name];
+			if (insight === void 0) continue;
+			if (!requested.has(name) && insight.state !== "fail") continue;
+			const summary = summarize(name, set.model);
+			if (summary === void 0) continue;
+			insights.push({
+				name,
+				page: set.url.href,
+				state: insight.state,
+				summary: cap(summary)
+			});
+		}
+		for (const name of REQUESTED_INSIGHTS) {
+			if (set.model[name] !== void 0) continue;
+			const error = set.modelErrors[name];
+			unavailable.push({
+				name,
+				reason: error === void 0 ? `not produced for ${set.url.pathname}` : `failed for ${set.url.pathname}: ${error.message}`
+			});
+		}
+	}
+	const longest = longestInteraction(sets);
+	return {
+		insights,
+		unavailable,
+		longestInteraction: longest === void 0 ? void 0 : {
+			id: longest.interactionId,
+			hotFunction: hotFunction(parsed, longest)
+		}
+	};
+}
+//#endregion
+//#region src/lab/verdict.ts
+const DEFAULT_BUDGETS = {
+	LCP: 2500,
+	INP: 200,
+	CLS: .1
+};
+/** Parses `lcp=2500,inp=200,cls=0.1`; metrics left out keep the Core Web Vitals "good" threshold. */
+const BudgetOption = z.string().optional().transform((text, ctx) => {
+	const budgets = { ...DEFAULT_BUDGETS };
+	if (text === void 0) return budgets;
+	const seen = /* @__PURE__ */ new Set();
+	for (const part of text.split(",")) {
+		const match = /^(lcp|inp|cls)=(\d+(?:\.\d+)?)$/.exec(part.trim());
+		if (match === null || match[1] === void 0 || match[2] === void 0) {
+			ctx.addIssue({
+				code: "custom",
+				message: `budget entry ${JSON.stringify(part)} must look like lcp=2500, inp=200, or cls=0.1`
+			});
+			return z.NEVER;
+		}
+		if (seen.has(match[1])) {
+			ctx.addIssue({
+				code: "custom",
+				message: `budget names ${match[1]} twice`
+			});
+			return z.NEVER;
+		}
+		seen.add(match[1]);
+		budgets[LabMetric.parse(match[1].toUpperCase())] = Number(match[2]);
+	}
+	return budgets;
+});
+const CULPRIT_INSIGHT = {
+	LCP: "LCPBreakdown",
+	INP: "INPBreakdown",
+	CLS: "CLSCulprits"
+};
+function round(metric, value) {
+	return metric === "CLS" ? Math.round(value * 1e4) / 1e4 : Math.round(value);
+}
+function median(sorted) {
+	const middle = Math.floor(sorted.length / 2);
+	const upper = sorted[middle];
+	if (upper === void 0) throw new Error("median of an empty list");
+	if (sorted.length % 2 === 1) return upper;
+	const lower = sorted[middle - 1];
+	if (lower === void 0) throw new Error("median index out of range");
+	return (lower + upper) / 2;
+}
+function pagePath(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.pathname + parsed.search;
+	} catch {
+		return url;
+	}
+}
+function culpritFor(metric, result, measured, diagnostic) {
+	const insights = diagnostic.insights.filter((insight) => insight.name === CULPRIT_INSIGHT[metric]);
+	const insight = insights.find((candidate) => pagePath(candidate.page) === pagePath(measured.page)) ?? (insights.length === 1 ? insights[0] : void 0);
+	const culprit = {
+		run: result.run,
+		page: measured.page,
+		breakdown: Object.fromEntries(Object.entries(measured.breakdown).map(([name, value]) => [name, round(metric, value)]))
+	};
+	if (measured.element !== void 0) culprit.element = measured.element;
+	if (measured.resource !== void 0) culprit.resource = measured.resource;
+	if (measured.script !== void 0) culprit.script = {
+		...measured.script,
+		durationMs: Math.round(measured.script.durationMs)
+	};
+	if (insight !== void 0) culprit.insight = insight.summary;
+	return culprit;
+}
+function metricVerdict(metric, input) {
+	const byRun = new Map(input.runs.map((result) => [result.run, result]));
+	const values = Array.from({ length: input.conditions.runs }, (_, index) => {
+		const measured = byRun.get(index + 1)?.metrics[metric];
+		return measured === void 0 ? null : round(metric, measured.value);
+	});
+	const budget = input.budgets[metric];
+	const unit = metric === "CLS" ? "score" : "ms";
+	const present = values.filter((value) => value !== null).sort((a, b) => a - b);
+	if (present.length === 0) return {
+		unit,
+		values,
+		median: null,
+		min: null,
+		max: null,
+		band: null,
+		budget,
+		status: "unmeasured",
+		note: input.runs.length === 0 ? "No run completed; see failures" : metric === "INP" ? "No interaction of 16 ms or longer was reported; the flow may have no clicks, keys, or taps" : `No run reported ${metric}`
+	};
+	const middle = round(metric, median(present));
+	const min = present[0] ?? middle;
+	const max = present.at(-1) ?? middle;
+	let representative;
+	let distance = Number.POSITIVE_INFINITY;
+	for (const result of input.runs) {
+		const measured = result.metrics[metric];
+		if (measured === void 0) continue;
+		const gap = Math.abs(round(metric, measured.value) - middle);
+		const current = representative?.metrics[metric]?.value ?? Number.NEGATIVE_INFINITY;
+		if (gap < distance || gap === distance && measured.value > current) {
+			representative = result;
+			distance = gap;
+		}
+	}
+	const measured = representative?.metrics[metric];
+	if (representative === void 0 || measured === void 0) throw new Error(`no representative run for ${metric} although values exist`);
+	return {
+		unit,
+		values,
+		median: middle,
+		min,
+		max,
+		band: round(metric, max - min),
+		budget,
+		status: middle <= budget ? "pass" : "fail",
+		culprit: culpritFor(metric, representative, measured, input.diagnostic)
+	};
+}
+function aggregateInsights(insights) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const insight of insights) {
+		const page = pagePath(insight.page);
+		const key = `${insight.name}\u0000${page}`;
+		const group = groups.get(key) ?? {
+			name: insight.name,
+			page,
+			state: insight.state,
+			runs: 0,
+			failed: 0,
+			summary: insight.summary
+		};
+		group.runs += 1;
+		if (insight.state === "fail") {
+			group.failed += 1;
+			group.state = "fail";
+			group.summary = insight.summary;
+		} else if (group.failed === 0) {
+			group.state = insight.state;
+			group.summary = insight.summary;
+		}
+		groups.set(key, group);
+	}
+	return [...groups.values()];
+}
+function formatValue(metric, value) {
+	return metric === "CLS" ? value.toFixed(3) : `${value} ms`;
+}
+/** One line for the perf attachment summary and the first line of the CLI output. */
+function summarizeVerdict(verdict) {
+	const metrics = LabMetric.options.map((metric) => {
+		const result = verdict.metrics[metric];
+		if (result.median === null) return `${metric} unmeasured`;
+		const over = result.status === "fail" ? ` > ${formatValue(metric, result.budget)}` : "";
+		return `${metric} ${formatValue(metric, result.median)} ${result.status}${over}`;
+	});
+	const { conditions } = verdict;
+	const failed = verdict.failures.length > 0 ? `, ${verdict.failures.length} failed` : "";
+	return `lab ${verdict.status}: ${metrics.join(", ")} (median of ${conditions.runs} runs${failed}, ${conditions.cpuRate}x CPU, ${conditions.network})`;
+}
+function computeVerdict(input) {
+	const metrics = {
+		LCP: metricVerdict("LCP", input),
+		INP: metricVerdict("INP", input),
+		CLS: metricVerdict("CLS", input)
+	};
+	const computed = new Set(input.diagnostic.insights.map((insight) => insight.name));
+	const unavailable = /* @__PURE__ */ new Map();
+	for (const missing of input.diagnostic.unavailable) if (!computed.has(missing.name)) unavailable.set(`${missing.name}\u0000${missing.reason}`, missing);
+	const culprit = metrics.INP.culprit;
+	const hot = input.diagnostic.hot;
+	if (culprit !== void 0 && hot !== void 0) {
+		if (hot.element !== void 0 && hot.element === culprit.element && pagePath(hot.page) === pagePath(culprit.page)) culprit.hotFunction = hot.hotFunction;
+		else {
+			const missing = {
+				name: "hotFunction",
+				reason: `the traced run's INP was ${`${hot.element ?? "an unnamed element"} on ${pagePath(hot.page)}`}, not the INP culprit's interaction`
+			};
+			unavailable.set(`${missing.name}\u0000${missing.reason}`, missing);
+		}
+	}
+	const statuses = Object.values(metrics).map((metric) => metric.status);
+	const status = statuses.includes("fail") ? "fail" : statuses.includes("unmeasured") || input.failures.length > 0 ? "incomplete" : "pass";
+	return {
+		version: 1,
+		createdAt: input.createdAt,
+		status,
+		conditions: input.conditions,
+		metrics,
+		insights: aggregateInsights(input.diagnostic.insights),
+		unavailable: [...unavailable.values()],
+		failures: input.failures,
+		traces: input.traces
+	};
+}
+//#endregion
+//#region src/lab/lab.ts
+const NETWORK_PRESETS = {
+	slow4g: {
+		latencyMs: 562.5,
+		downloadBytesPerSec: 18e4,
+		uploadBytesPerSec: 84375
+	},
+	fast4g: {
+		latencyMs: 165,
+		downloadBytesPerSec: 1012500,
+		uploadBytesPerSec: 168750
+	},
+	none: null
+};
+const TRACE_CATEGORIES = [
+	"blink.console",
+	"blink.user_timing",
+	"loading",
+	"devtools.timeline",
+	"disabled-by-default-devtools.target-rundown",
+	"disabled-by-default-devtools.timeline.frame",
+	"disabled-by-default-devtools.timeline.stack",
+	"disabled-by-default-devtools.timeline",
+	"disabled-by-default-devtools.v8-source-rundown-sources",
+	"disabled-by-default-devtools.v8-source-rundown",
+	"disabled-by-default-layout_shift.debug",
+	"disabled-by-default-v8.inspector",
+	"disabled-by-default-v8.cpu_profiler.hires",
+	"disabled-by-default-lighthouse",
+	"v8.execute",
+	"v8",
+	"cppgc",
+	"navigation",
+	"rail",
+	"disabled-by-default-v8.cpu_profiler"
+];
+const VIEWPORT = {
+	width: 1280,
+	height: 720
+};
+const NAVIGATION_TIMEOUT_MS = 6e4;
+const LOCATE_TIMEOUT_MS = 15e3;
+const QUIET_MS = 500;
+const SETTLE_MAX_MS = 1e4;
+const TEXT_CAP = 40;
+const BINDING = "__pkaLabReport";
+const NAVIGATION_BINDING = "__pkaLabNavigate";
+/** A step that could not be replayed; it fails the run, not the command. */
+var StepError = class extends Error {
+	step;
+	constructor(step, message, options) {
+		super(message, options);
+		this.step = step;
+	}
+};
+/** Keeps the actions and navigations of a timeline, in seq order. */
+function flowFromTimeline(entries) {
+	const steps = entries.filter((entry) => entry.kind === "action" || entry.kind === "navigation").sort((a, b) => a.seq - b.seq);
+	if (!steps.some((step) => step.kind === "action")) throw new PkaError("The flow has no actions; record a flow that clicks or types something.");
+	return steps;
+}
+async function readFlowFile(file) {
+	return flowFromTimeline((await readFile(file, "utf8")).split("\n").flatMap((line, index) => {
+		if (line.trim() === "") return [];
+		let data;
+		try {
+			data = JSON.parse(line);
+		} catch (thrown) {
+			throw new PkaError(`Invalid JSON in ${file}:${index + 1}`, { cause: thrown });
+		}
+		const parsed = TimelineEntry.safeParse(data);
+		if (!parsed.success) throw new PkaError(`Invalid timeline entry in ${file}:${index + 1}:\n${z.prettifyError(parsed.error)}`);
+		return [parsed.data];
+	}));
+}
+/**
+* Reads the flow from an annotation's recording. The recording attachment
+* points at capture/summary.md; timeline.jsonl and manifest.json sit in the same
+* directory. A recording started on an already loaded page has no navigation
+* before its first action, so the replay starts with a load of the manifest's
+* start URL, rebased onto --url like every recorded navigation.
+*/
+async function readAnnotationFlow(store, id) {
+	const { annotation } = await get(store, {
+		id,
+		detail: "concise"
+	});
+	const recording = annotation.attachments.find((item) => item.kind === "recording");
+	if (recording === void 0) throw new PkaError(`Annotation ${id} has no recording; record a flow in the overlay or pass a timeline file to --flow.`);
+	const dir = path.posix.dirname(recording.path);
+	const file = resolveInside(annotation.dir, dir, "timeline.jsonl");
+	const entries = await readJsonLines(store, file, TimelineEntry);
+	if (entries.length === 0) throw new PkaError(`Annotation ${id}'s ${path.relative(annotation.dir, file)} is missing or empty; record the flow again or pass a timeline file to --flow.`);
+	const steps = flowFromTimeline(entries);
+	const first = steps[0];
+	if (first === void 0 || first.kind === "navigation") return steps;
+	const manifestFile = resolveInside(annotation.dir, dir, "manifest.json");
+	let manifest;
+	try {
+		manifest = await readJson(store, manifestFile, RecordingManifest);
+	} catch (thrown) {
+		if (!isErrno(thrown, "ENOENT")) throw thrown;
+		throw new PkaError(`Annotation ${id}'s ${path.relative(annotation.dir, manifestFile)} is missing, so the start page is unknown; record the flow again or pass a timeline file to --flow.`, { cause: thrown });
+	}
+	return [{
+		kind: "navigation",
+		seq: Math.max(0, first.seq - 1),
+		at: manifest.startedAt,
+		type: "load",
+		to: manifest.url
+	}, ...steps];
+}
+const PageMetric = z.strictObject({
+	doc: z.string(),
+	navigation: z.string(),
+	name: LabMetric,
+	value: z.number(),
+	url: z.string(),
+	target: z.string().optional(),
+	resource: z.string().optional(),
+	breakdown: z.record(z.string(), z.number()),
+	script: LoafScript.optional(),
+	interaction: z.number().int().optional()
+});
+const PageReport = z.string().transform((text, ctx) => {
+	try {
+		return JSON.parse(text);
+	} catch {
+		ctx.addIssue({
+			code: "custom",
+			message: "the report is not JSON"
+		});
+		return z.NEVER;
+	}
+}).pipe(PageMetric);
+const HistoryChange = z.enum([
+	"push",
+	"replace",
+	"reload",
+	"traverse"
+]);
+const NavigationReport = z.strictObject({
+	type: HistoryChange,
+	url: z.url()
+});
+function webVitalsSource() {
+	const entry = createRequire(import.meta.url).resolve("web-vitals/attribution");
+	return path.join(path.dirname(entry), "web-vitals.attribution.iife.js");
+}
+async function pageScript() {
+	return `(() => {
+if (window !== window.top) return;
+${(await readFile(webVitalsSource(), "utf8")).replace(/\/\/# sourceMappingURL=.*$/m, "")}
+const doc = Math.random().toString(36).slice(2);
+const describe = (node) => {
+  if (!(node instanceof Element)) return undefined;
+  const tag = node.localName;
+  const testId = node.getAttribute("data-testid");
+  if (testId) return tag + '[data-testid="' + testId + '"]';
+  if (node.id) return tag + "#" + node.id;
+  return undefined;
+};
+const send = (metric, extra) => {
+  const report = window[${JSON.stringify(BINDING)}];
+  if (typeof report !== "function") return;
+  report(JSON.stringify({
+    doc,
+    navigation: String(metric.navigationId ?? ""),
+    name: metric.name,
+    value: metric.value,
+    url: metric.navigationURL || location.href,
+    ...extra,
+  }));
+};
+navigation.addEventListener("navigate", (event) => {
+  const report = window[${JSON.stringify(NAVIGATION_BINDING)}];
+  if (typeof report === "function") report(event.navigationType, event.destination.url);
+});
+const options = { reportAllChanges: true, reportSoftNavs: true, generateTarget: describe };
+webVitals.onLCP((metric) => {
+  const a = metric.attribution;
+  send(metric, {
+    target: a.target,
+    resource: a.url,
+    breakdown: {
+      timeToFirstByte: a.timeToFirstByte,
+      resourceLoadDelay: a.resourceLoadDelay,
+      resourceLoadDuration: a.resourceLoadDuration,
+      elementRenderDelay: a.elementRenderDelay,
+    },
+  });
+}, options);
+webVitals.onINP((metric) => {
+  const a = metric.attribution;
+  const longest = a.longestScript;
+  send(metric, {
+    target: a.interactionTarget,
+    interaction: metric.entries[0]?.interactionId,
+    breakdown: {
+      inputDelay: a.inputDelay,
+      processingDuration: a.processingDuration,
+      presentationDelay: a.presentationDelay,
+    },
+    script: longest && {
+      url: longest.entry.sourceURL,
+      function: longest.entry.sourceFunctionName,
+      invoker: longest.entry.invoker,
+      subpart: longest.subpart,
+      durationMs: longest.intersectingDuration,
+    },
+  });
+}, { ...options, durationThreshold: 16 });
+webVitals.onCLS((metric) => {
+  const a = metric.attribution;
+  send(metric, {
+    target: a.largestShiftTarget,
+    breakdown: a.largestShiftValue === undefined ? {} : { largestShiftValue: a.largestShiftValue },
+  });
+}, options);
+})();`;
+}
+function escapeRegExp(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function nameMatcher(text) {
+	const escaped = escapeRegExp(text).replace(/ /g, "\\s+");
+	return new RegExp(text.length >= TEXT_CAP ? `^\\s*${escaped}` : `^\\s*${escaped}\\s*$`);
+}
+const IMPLICIT_ROLES = /* @__PURE__ */ new Map([
+	["a", "link"],
+	["button", "button"],
+	["select", "combobox"],
+	["textarea", "textbox"],
+	["summary", "button"],
+	["h1", "heading"],
+	["h2", "heading"],
+	["h3", "heading"]
+]);
+function candidates(page, target) {
+	const found = [];
+	if (target.testId !== void 0) found.push(["testId", page.getByTestId(target.testId)]);
+	if (target.id !== void 0) found.push(["id", page.locator(`[id="${target.id.replace(/["\\]/g, "\\$&")}"]`)]);
+	const name = target.text ?? target.label;
+	const role = target.role ?? IMPLICIT_ROLES.get(target.tag);
+	if (role !== void 0 && name !== void 0) found.push(["role", page.getByRole(role, { name: nameMatcher(name) })]);
+	if (target.label !== void 0) found.push(["label", page.getByLabel(nameMatcher(target.label))]);
+	if (target.text !== void 0) found.push(["text", page.locator(target.tag).filter({
+		hasText: nameMatcher(target.text),
+		visible: true
+	})]);
+	return found;
+}
+/** Finds the one element a recorded descriptor names, waiting for it to render. */
+async function locate(page, target, step) {
+	const strategies = candidates(page, target);
+	if (strategies.length === 0) throw new StepError(step, `Step ${step}: the target ${JSON.stringify(target)} has no test id, id, role, label, or text to find it by`);
+	const deadline = Date.now() + LOCATE_TIMEOUT_MS;
+	let notes = [];
+	for (;;) {
+		notes = [];
+		for (const [strategy, locator] of strategies) {
+			let count;
+			try {
+				count = await locator.count();
+			} catch (thrown) {
+				if (page.isClosed()) throw thrown;
+				notes.push(`${strategy} rejected: ${thrown instanceof Error ? thrown.message.split("\n")[0] : String(thrown)}`);
+				continue;
+			}
+			if (count === 1) return locator;
+			if (count > 1) notes.push(`${strategy} matched ${count}`);
+		}
+		if (Date.now() >= deadline) break;
+		await setTimeout(100);
+	}
+	const why = notes.length > 0 ? notes.join(", ") : "nothing matched";
+	throw new StepError(step, `Step ${step}: cannot find ${JSON.stringify(target)} (${why})`);
+}
+function placeholder(type) {
+	if (type === "number" || type === "range") return "1";
+	if (type === "email") return "lab@example.com";
+	if (type === "url") return "https://example.com";
+	if (type === "tel") return "5550100";
+	return "pka lab";
+}
+function sameTarget(a, b) {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+function trackRequests(page) {
+	const inflight = /* @__PURE__ */ new Set();
+	let lastChange = Date.now();
+	page.on("request", (request) => {
+		if (request.resourceType() === "eventsource" || request.resourceType() === "websocket") return;
+		inflight.add(request);
+		lastChange = Date.now();
+	});
+	const done = (request) => {
+		if (inflight.delete(request)) lastChange = Date.now();
+	};
+	page.on("requestfinished", done);
+	page.on("requestfailed", done);
+	return { quiet: (since) => inflight.size === 0 && Date.now() - Math.max(lastChange, since) >= QUIET_MS };
+}
+async function settle(page, tracker) {
+	const since = Date.now();
+	const deadline = since + SETTLE_MAX_MS;
+	while (!tracker.quiet(since) && Date.now() < deadline) await setTimeout(50);
+	await page.waitForLoadState("load", { timeout: NAVIGATION_TIMEOUT_MS });
+}
+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;
+}
+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;
+		return entered || got.search === want.search;
+	});
+}
+async function fieldOf(locator) {
+	const { tag, inputType } = await locator.evaluate((element) => ({
+		tag: element.localName,
+		inputType: element instanceof HTMLInputElement ? element.type : ""
+	}));
+	if (inputType === "checkbox" || inputType === "radio") return {
+		kind: "checkable",
+		inputType
+	};
+	return {
+		kind: tag === "select" ? "select" : "text",
+		inputType
+	};
+}
+function alreadyCaused(step, previous, field) {
+	if (previous?.kind !== "action" || !sameTarget(previous.target, step.target)) return false;
+	if (field.kind === "checkable") return step.type !== "click" && previous.type !== "change";
+	return field.kind === "select" && step.type === "change" && previous.type === "input";
+}
+async function enterValue(locator, field) {
+	if (field.kind === "checkable") await locator.click({ timeout: LOCATE_TIMEOUT_MS });
+	else if (field.kind === "select") await selectAnother(locator);
+	else {
+		await locator.fill("", { timeout: LOCATE_TIMEOUT_MS });
+		await locator.pressSequentially(placeholder(field.inputType));
+	}
+}
+async function replayAction(page, step, previous, index, state) {
+	if (step.type === "submit" && previous?.kind === "action") {
+		if (previous.type === "click" || previous.type === "keydown" && previous.key === "Enter") return;
+	}
+	const locator = await locate(page, step.target, index);
+	const field = await fieldOf(locator);
+	if (alreadyCaused(step, previous, field)) return;
+	state.changes.length = 0;
+	switch (step.type) {
+		case "click":
+			await locator.click({ timeout: LOCATE_TIMEOUT_MS });
+			return;
+		case "input":
+			state.entered = true;
+			await enterValue(locator, field);
+			return;
+		case "change":
+			if (field.kind === "text") await locator.blur();
+			else {
+				state.entered = true;
+				await enterValue(locator, field);
+			}
+			return;
+		case "submit":
+			await locator.evaluate((element) => {
+				if (!(element instanceof HTMLFormElement)) throw new Error(`submit target is <${element.localName}>, not a form`);
+				element.requestSubmit();
+			});
+			return;
+		case "keydown":
+			if (step.key === void 0) throw new StepError(index, `Step ${index}: keydown without Enter or Escape`);
+			await locator.press(step.key, { timeout: LOCATE_TIMEOUT_MS });
+			return;
+	}
+}
+async function selectAnother(locator) {
+	const next = await locator.evaluate((element) => {
+		if (!(element instanceof HTMLSelectElement)) throw new Error("not a select");
+		const other = [...element.options].filter((option) => !option.disabled).find((option) => option.index !== element.selectedIndex);
+		if (other === void 0) throw new Error("the select has no other enabled option");
+		return other.value;
+	});
+	await locator.selectOption(next);
+}
+/** Maps a recorded URL onto the build under test when it points at the recorded app. */
+function rebase(recorded, appOrigin, base) {
+	const url = new URL(recorded, base);
+	if (appOrigin !== void 0 && url.origin !== appOrigin) return url.href;
+	return new URL(url.pathname + url.search + url.hash, base).href;
+}
+/**
+* Replays the steps in order. `state.changes` receives the page's navigations
+* as they start; the replay empties it before each step it performs.
+*/
+async function replay(page, tracker, state, steps, base) {
+	const first = steps.find((step) => step.kind === "navigation");
+	const appOrigin = first === void 0 ? void 0 : new URL(first.to, base).origin;
+	if (steps[0]?.kind !== "navigation") {
+		await page.goto(base.href, { timeout: NAVIGATION_TIMEOUT_MS });
+		await settle(page, tracker);
+	}
+	for (const [index, step] of steps.entries()) try {
+		if (step.kind === "navigation") {
+			const target = rebase(step.to, appOrigin, base);
+			if (step.type === "reload") {
+				await flushVitals(page);
+				state.changes.length = 0;
+				await page.reload({ timeout: NAVIGATION_TIMEOUT_MS });
+			} else if (step.type === "load" || !producedByReplay(step, target, state) && !samePage(page.url(), target)) {
+				await flushVitals(page);
+				state.changes.length = 0;
+				await page.goto(target, { timeout: NAVIGATION_TIMEOUT_MS });
+			}
+		} else await replayAction(page, step, steps[index - 1], index, state);
+		await settle(page, tracker);
+	} catch (thrown) {
+		if (thrown instanceof StepError) throw thrown;
+		throw new StepError(index, `Step ${index} (${step.kind === "action" ? `${step.type} ${JSON.stringify(step.target)}` : `${step.type} ${step.to}`}) failed: ${thrown instanceof Error ? thrown.message.split("\n")[0] : String(thrown)}`, { cause: thrown });
+	}
+	await flushVitals(page);
+}
+async function flushVitals(page) {
+	await page.evaluate(() => new Promise((resolve) => {
+		requestIdleCallback(() => resolve(), { timeout: 2e3 });
+	}));
+}
+async function startTrace(cdp) {
+	await cdp.send("Tracing.start", {
+		transferMode: "ReturnAsStream",
+		traceConfig: {
+			includedCategories: TRACE_CATEGORIES,
+			excludedCategories: ["*"]
+		}
+	});
+}
+/** Ends the trace and returns the handle of the stream Chrome wrote it to. */
+async function endTrace(cdp) {
+	const complete = new Promise((resolve, reject) => {
+		cdp.once("Tracing.tracingComplete", (event) => {
+			if (event.stream === void 0) reject(/* @__PURE__ */ new Error("Chrome returned no trace stream"));
+			else resolve(event.stream);
+		});
+	});
+	await cdp.send("Tracing.end");
+	return await complete;
+}
+async function saveTrace(cdp, handle, file) {
+	const chunks = [];
+	await pipeline(async function* () {
+		for (;;) {
+			const read = await cdp.send("IO.read", { handle });
+			const chunk = Buffer.from(read.data, read.base64Encoded === true ? "base64" : "utf8");
+			chunks.push(chunk);
+			yield chunk;
+			if (read.eof) return;
+		}
+	}, createGzip(), createWriteStream(file));
+	await cdp.send("IO.close", { handle });
+	return Buffer.concat(chunks).toString("utf8");
+}
+const TraceFile = z.union([z.array(z.unknown()), z.looseObject({ traceEvents: z.array(z.unknown()) }).transform((file) => file.traceEvents)]);
+function worstPerMetric(reports) {
+	const metrics = {};
+	for (const report of reports.values()) {
+		const current = metrics[report.name];
+		if (current !== void 0 && current.value >= report.value) continue;
+		const measured = {
+			value: report.value,
+			page: report.url,
+			element: report.target,
+			resource: report.resource,
+			breakdown: report.breakdown,
+			script: report.script,
+			interaction: report.interaction
+		};
+		metrics[report.name] = measured;
+	}
+	return metrics;
+}
+async function openSession(options) {
+	const { context } = options;
+	const reports = /* @__PURE__ */ new Map();
+	const state = {
+		changes: [],
+		entered: false
+	};
+	const invalid = [];
+	await context.exposeBinding(BINDING, (_source, report) => {
+		const parsed = PageReport.safeParse(report);
+		if (!parsed.success) {
+			invalid.push(z.prettifyError(parsed.error));
+			return;
+		}
+		const metric = parsed.data;
+		reports.set(`${metric.doc}:${metric.navigation}:${metric.name}`, metric);
+	});
+	await context.exposeBinding(NAVIGATION_BINDING, (_source, type, url) => {
+		const parsed = NavigationReport.safeParse({
+			type,
+			url
+		});
+		if (parsed.success) state.changes.push({
+			...parsed.data,
+			entered: state.entered
+		});
+		else invalid.push(z.prettifyError(parsed.error));
+	});
+	await context.addInitScript({ content: await pageScript() });
+	const page = await context.newPage();
+	page.on("domcontentloaded", () => {
+		state.entered = false;
+	});
+	const cdp = await context.newCDPSession(page);
+	await cdp.send("Emulation.setCPUThrottlingRate", { rate: options.cpuRate });
+	const network = NETWORK_PRESETS[options.network];
+	await cdp.send("Network.enable");
+	if (network !== null) await cdp.send("Network.emulateNetworkConditions", {
+		offline: false,
+		latency: network.latencyMs,
+		downloadThroughput: network.downloadBytesPerSec,
+		uploadThroughput: network.uploadBytesPerSec
+	});
+	return {
+		page,
+		cdp,
+		tracker: trackRequests(page),
+		state,
+		reports,
+		invalid
+	};
+}
+function checkReports(session, label) {
+	if (session.invalid.length > 0) throw new Error(`${label}: the page script sent an invalid report:\n${session.invalid[0]}`);
+}
+/** One untraced replay; its metrics are a verdict sample. */
+async function measure(run, options) {
+	const session = await openSession(options);
+	await replay(session.page, session.tracker, session.state, options.steps, options.base);
+	checkReports(session, `Run ${run}`);
+	return {
+		run,
+		metrics: worstPerMetric(session.reports)
+	};
+}
+async function traceStep(what, work) {
+	try {
+		return await work();
+	} catch (thrown) {
+		throw new TraceError(`${what}: ${thrown instanceof Error ? thrown.message.split("\n")[0] : String(thrown)}`, { cause: thrown });
+	}
+}
+async function diagnose(options, file) {
+	const session = await openSession(options);
+	const { cdp } = session;
+	await traceStep("starting the trace failed", () => startTrace(cdp));
+	try {
+		await replay(session.page, session.tracker, session.state, options.steps, options.base);
+	} catch (thrown) {
+		const traceError = await endTrace(cdp).then((handle) => cdp.send("IO.close", { handle })).then(() => void 0, (failure) => failure.message);
+		if (thrown instanceof StepError && traceError !== void 0) throw new StepError(thrown.step, `${thrown.message} (trace discarded: ${traceError})`, { cause: thrown });
+		throw thrown;
+	}
+	const handle = await traceStep("ending the trace failed", () => endTrace(cdp));
+	checkReports(session, "The traced run");
+	const trace = await traceStep(`saving the trace to ${file} failed`, () => saveTrace(cdp, handle, file));
+	const analysis = await analyzeTrace(await traceStep(`the trace in ${file} is not Chrome trace JSON`, async () => {
+		const parsed = TraceFile.safeParse(JSON.parse(trace));
+		if (!parsed.success) throw new Error("it is neither an event array nor an object with a traceEvents array");
+		return parsed.data;
+	}));
+	const diagnostic = {
+		insights: analysis.insights,
+		unavailable: analysis.unavailable,
+		hot: void 0
+	};
+	const longest = analysis.longestInteraction;
+	if (longest?.hotFunction === void 0) return diagnostic;
+	const inp = worstPerMetric(session.reports).INP;
+	if (inp?.interaction === longest.id) diagnostic.hot = {
+		hotFunction: longest.hotFunction,
+		page: inp.page,
+		element: inp.element
+	};
+	else diagnostic.unavailable.push({
+		name: "hotFunction",
+		reason: "the traced run's longest interaction is not the INP interaction it reported"
+	});
+	return diagnostic;
+}
+async function loadPlaywright() {
+	try {
+		return await import("playwright");
+	} catch (thrown) {
+		if (thrown instanceof Error && "code" in thrown && thrown.code === "ERR_MODULE_NOT_FOUND") throw new PkaError("pka lab needs Playwright, an optional peer dependency: pnpm add -D playwright && pnpm exec playwright install chromium", { cause: thrown });
+		throw thrown;
+	}
+}
+/**
+* Replays the flow `runs` times untraced in fresh contexts, then once more under
+* a DevTools trace for insights, and writes <out>/verdict.json.
+*/
+async function runLab(options) {
+	const { chromium } = await loadPlaywright();
+	const base = new URL(options.url);
+	const out = path.resolve(options.out);
+	await mkdir(out, { recursive: true });
+	const browser = await chromium.launch({
+		channel: "chromium",
+		args: ["--disable-blink-features=AutomationControlled"]
+	});
+	const results = [];
+	const failures = [];
+	const conditions = {
+		steps: options.flow,
+		base,
+		cpuRate: options.cpuRate,
+		network: options.network
+	};
+	try {
+		for (let run = 1; run <= options.runs; run += 1) {
+			const context = await browser.newContext({ viewport: VIEWPORT });
+			try {
+				results.push(await measure(run, {
+					context,
+					...conditions
+				}));
+				options.onRun(run, void 0);
+			} catch (thrown) {
+				if (!(thrown instanceof StepError)) throw thrown;
+				const failure = {
+					run,
+					step: thrown.step,
+					message: thrown.message
+				};
+				failures.push(failure);
+				options.onRun(run, failure);
+			} finally {
+				await context.close();
+			}
+		}
+		const traces = [];
+		let diagnostic = {
+			insights: [],
+			unavailable: [],
+			hot: void 0
+		};
+		if (results.length > 0) {
+			const trace = path.join(out, "trace.json.gz");
+			const context = await browser.newContext({ viewport: VIEWPORT });
+			try {
+				diagnostic = await diagnose({
+					context,
+					...conditions
+				}, trace);
+				traces.push(trace);
+				options.onRun("trace", void 0);
+			} catch (thrown) {
+				if (!(thrown instanceof StepError) && !(thrown instanceof TraceError)) throw thrown;
+				diagnostic.unavailable.push({
+					name: "trace",
+					reason: `the traced run failed: ${thrown.message}`
+				});
+				options.onRun("trace", { message: thrown.message });
+			} finally {
+				await context.close();
+			}
+		}
+		const network = NETWORK_PRESETS[options.network];
+		const verdict = Verdict.parse(computeVerdict({
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			conditions: {
+				url: base.href,
+				flow: options.flowLabel,
+				steps: options.flow.length,
+				runs: options.runs,
+				measurementTracing: false,
+				diagnosticRuns: results.length > 0 ? 1 : 0,
+				cpuRate: options.cpuRate,
+				network: options.network,
+				networkConditions: network === null ? null : { ...network },
+				cache: "cold",
+				chromium: browser.version(),
+				viewport: `${VIEWPORT.width}x${VIEWPORT.height}`
+			},
+			budgets: options.budgets,
+			runs: results,
+			failures,
+			diagnostic,
+			traces
+		}));
+		const file = path.join(out, "verdict.json");
+		await writeFile(file, `${JSON.stringify(verdict, null, 2)}\n`);
+		return {
+			verdict,
+			file
+		};
+	} finally {
+		await browser.close();
+	}
+}
+//#endregion
+//#region src/cli/main.ts
+const USAGE = `Usage: pka [--root DIR] [--json] <command>
+
+  list [--status pending|acknowledged|resolved|dismissed|all] [--limit N] [--cursor ID] [--detail concise|full]
+  get <id> [--detail concise|full]
+  watch [--once] [--timeout SECONDS]    one line per new pending annotation
+  status <id> <acknowledged|resolved|dismissed> [--note TEXT]
+  reply <id> <text>
+  errors [--since ISO-TIME] [--limit N] [--detail concise|full]
+  prune                                 remove resolved and dismissed annotations older than 7 days
+  lab --url URL --flow FILE|ID [--runs 5] [--cpu 4] [--network slow4g|fast4g|none]
+      [--budget lcp=2500,inp=200,cls=0.1] [--attach ID] [--out DIR]
+                                        replay a recorded flow against a production build
+                                        and write <out>/verdict.json (needs playwright)
+
+The store is <root>/_interim/annotations. Without --root or PKA_ROOT, pka uses
+CLAUDE_PROJECT_DIR, then the nearest parent of the working directory that has one.
+status acknowledged claims an annotation as $PKA_CLAIMANT (default pka-cli); later
+status changes, replies, and lab --attach must come from the same claimant.
+pka lab: --flow is a timeline.jsonl file or an annotation id with a recording
+(its timeline.jsonl sits beside capture/summary.md). Budgets left out use the Core Web Vitals "good"
+thresholds. --out defaults to $TMPDIR/pka-lab/<time>. --attach adds the
+verdict to that annotation as a perf attachment.
+Exit codes: 0 ok, 1 operation error, 2 usage error, 3 lab verdict is fail or incomplete.`;
+const COMMAND_OPTIONS = {
+	list: [
+		"status",
+		"limit",
+		"cursor",
+		"detail"
+	],
+	get: ["detail"],
+	watch: ["once", "timeout"],
+	status: ["note"],
+	reply: [],
+	errors: [
+		"since",
+		"limit",
+		"detail"
+	],
+	prune: [],
+	lab: [
+		"url",
+		"flow",
+		"runs",
+		"cpu",
+		"network",
+		"budget",
+		"attach",
+		"out"
+	]
+};
+const POSITIONALS = {
+	list: 0,
+	get: 1,
+	watch: 0,
+	status: 2,
+	reply: 2,
+	errors: 0,
+	prune: 0,
+	lab: 0
+};
+const Command = z.enum([
+	"list",
+	"get",
+	"watch",
+	"status",
+	"reply",
+	"errors",
+	"prune",
+	"lab"
+]);
+const WatchInput = z.strictObject({
+	once: z.boolean(),
+	timeout: z.number().positive().max(86400).optional()
+});
+const LabInput = z.strictObject({
+	url: z.url({ protocol: /^https?$/ }),
+	flow: z.string().min(1),
+	runs: z.number().int().min(1).max(50).default(5),
+	cpu: z.number().min(1).max(20).default(4),
+	network: NetworkPreset.default("slow4g"),
+	budget: BudgetOption,
+	attach: Id.optional(),
+	out: z.string().min(1).optional()
+});
+var UsageError = class extends Error {
+	name = "UsageError";
+};
+function cliClaimant() {
+	const parsed = z.string().trim().min(1).max(200).safeParse(process.env.PKA_CLAIMANT ?? "pka-cli");
+	if (!parsed.success) throw new UsageError("PKA_CLAIMANT must be 1 to 200 characters");
+	return parsed.data;
+}
+function parseInput(schema, input) {
+	const parsed = schema.safeParse(input);
+	if (!parsed.success) throw new UsageError(z.prettifyError(parsed.error));
+	return parsed.data;
+}
+function numberOption(value) {
+	return value === void 0 ? void 0 : Number(value);
+}
+function parseCommandLine(argv) {
+	const { values, positionals, tokens } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		tokens: true,
+		strict: true,
+		options: {
+			root: { type: "string" },
+			json: {
+				type: "boolean",
+				default: false
+			},
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			},
+			status: { type: "string" },
+			limit: { type: "string" },
+			cursor: { type: "string" },
+			detail: { type: "string" },
+			once: {
+				type: "boolean",
+				default: false
+			},
+			timeout: { type: "string" },
+			note: { type: "string" },
+			since: { type: "string" },
+			url: { type: "string" },
+			flow: { type: "string" },
+			runs: { type: "string" },
+			cpu: { type: "string" },
+			network: { type: "string" },
+			budget: { type: "string" },
+			attach: { type: "string" },
+			out: { type: "string" }
+		}
+	});
+	const [name, ...rest] = positionals;
+	const command = Command.safeParse(name);
+	if (!command.success) throw new UsageError(name === void 0 ? "Missing command" : `Unknown command ${name}`);
+	const allowed = /* @__PURE__ */ new Set([
+		"root",
+		"json",
+		"help",
+		...COMMAND_OPTIONS[command.data]
+	]);
+	const unexpected = tokens.flatMap((token) => token.kind === "option" && !allowed.has(token.name) ? [token.name] : []);
+	if (unexpected.length > 0) throw new UsageError(`${command.data} does not take --${unexpected.join(", --")}`);
+	if (rest.length !== POSITIONALS[command.data]) throw new UsageError(`${command.data} takes ${POSITIONALS[command.data]} positional argument(s), got ${rest.length}`);
+	return {
+		command: command.data,
+		args: rest,
+		values
+	};
+}
+function line(text) {
+	process.stdout.write(`${text}\n`);
+}
+function firstLine(text) {
+	return text.split("\n", 1)[0] ?? "";
+}
+function printAnnotation(view) {
+	line(`${view.id}  ${view.status}${view.claimedBy === void 0 ? "" : ` (${view.claimedBy})`}`);
+	line(`route: ${view.route}`);
+	line(`dir: ${view.dir}`);
+	line(`prompt: ${view.prompt}`);
+	for (const element of view.elements) {
+		const label = [element.selector.role, element.selector.name].filter(Boolean).join(" ");
+		line(`  [${element.n}] ${element.source ?? "(no source)"}${element.usedAt === void 0 ? "" : ` usedAt ${element.usedAt}`}  ${element.owners.join(" > ")}  ${label || element.selector.css}`);
+	}
+	for (const attachment of view.attachments) line(`  ${attachment.kind}: ${attachment.path}${attachment.summary ? `  ${attachment.summary}` : ""}`);
+	for (const entry of view.thread ?? []) line(`  ${entry.at} ${entry.from}: ${entry.text}`);
+	if (view.omitted !== void 0) line(view.omitted.note);
+}
+function printList(result) {
+	if (result.items.length === 0) line("No annotations.");
+	for (const item of result.items) line(`${item.id}  ${item.status}  ${item.route}  ${firstLine(item.prompt)}`);
+	if (result.nextCursor !== void 0) line(`more: --cursor ${result.nextCursor}`);
+}
+function printErrors(result) {
+	if (result.updatedAt === null) line("No error snapshot yet.");
+	else if (result.groups.length === 0) line("No open errors.");
+	for (const group of result.groups) {
+		line(`${group.count}x ${group.type}: ${firstLine(group.message)}  ${group.topFrame ?? ""}`);
+		if (group.stack !== void 0) line(group.stack);
+	}
+}
+async function watchCommand(store, values, json) {
+	const input = parseInput(WatchInput, {
+		once: values.once,
+		timeout: numberOption(values.timeout)
+	});
+	const deadline = input.timeout === void 0 ? void 0 : Date.now() + input.timeout * 1e3;
+	const delivered = /* @__PURE__ */ new Set();
+	for (;;) {
+		const timeoutMs = deadline === void 0 ? void 0 : deadline - Date.now();
+		const result = timeoutMs !== void 0 && timeoutMs <= 0 ? { timedOut: true } : await wait(store, {
+			timeoutMs,
+			signal: void 0,
+			onProgress: void 0,
+			skip: delivered
+		});
+		const annotation = "annotation" in result ? result.annotation : void 0;
+		if (annotation === void 0) {
+			line(json ? JSON.stringify({ timedOut: true }) : "Timed out.");
+			return;
+		}
+		delivered.add(annotation.id);
+		line(json ? JSON.stringify({
+			timedOut: false,
+			annotation
+		}) : `${annotation.id}  ${annotation.route}  ${firstLine(annotation.prompt)}`);
+		if (input.once) return;
+	}
+}
+function openStore(values) {
+	return findStore({
+		explicit: values.root ?? (process.env.PKA_ROOT || void 0),
+		claudeProjectDir: process.env.CLAUDE_PROJECT_DIR || void 0,
+		cwd: process.cwd()
+	});
+}
+async function isFile(file) {
+	try {
+		return (await stat(file)).isFile();
+	} catch (thrown) {
+		if (isErrno(thrown, "ENOENT")) return false;
+		throw thrown;
+	}
+}
+function formatMetric(metric, value) {
+	if (value === null) return "-";
+	return metric === "CLS" ? value.toFixed(3) : `${value} ms`;
+}
+function printVerdict(verdict, file) {
+	line(summarizeVerdict(verdict));
+	for (const metric of LabMetric.options) {
+		const result = verdict.metrics[metric];
+		line(`  ${metric}  ${formatMetric(metric, result.median)}  range ${formatMetric(metric, result.min)}..${formatMetric(metric, result.max)}  budget ${formatMetric(metric, result.budget)}  ${result.status}`);
+		const culprit = result.culprit;
+		if (culprit !== void 0) {
+			const where = [culprit.element, culprit.resource].filter(Boolean).join(" ");
+			line(`      run ${culprit.run} ${culprit.page}${where === "" ? "" : `  ${where}`}`);
+			if (culprit.script !== void 0) {
+				const script = culprit.script;
+				line(`      LoAF script ${script.durationMs} ms in ${script.subpart}: ${script.invoker} → ${script.function || "(anonymous)"} ${script.url}`);
+			}
+			if (culprit.hotFunction !== void 0) {
+				const hot = culprit.hotFunction;
+				line(`      hot ${hot.function} ${hot.url}:${hot.line}:${hot.column} (${hot.selfMs} ms self)`);
+			}
+			if (culprit.insight !== void 0) line(`      ${culprit.insight}`);
+		}
+		if (result.note !== void 0) line(`      ${result.note}`);
+	}
+	for (const insight of verdict.insights.filter((item) => item.state === "fail")) line(`  insight ${insight.name} ${insight.page} (${insight.failed}/${insight.runs}): ${insight.summary}`);
+	for (const missing of verdict.unavailable) line(`  no ${missing.name}: ${missing.reason}`);
+	for (const failure of verdict.failures) line(`  run ${failure.run} failed: ${failure.message}`);
+	line(`verdict: ${file}`);
+}
+async function labCommand(values) {
+	const input = parseInput(LabInput, {
+		url: values.url,
+		flow: values.flow,
+		runs: numberOption(values.runs),
+		cpu: numberOption(values.cpu),
+		network: values.network,
+		budget: values.budget,
+		attach: values.attach,
+		out: values.out
+	});
+	let flow;
+	let flowLabel;
+	if (await isFile(input.flow)) {
+		flow = await readFlowFile(input.flow);
+		flowLabel = path.resolve(input.flow);
+	} else if (ID_PATTERN.test(input.flow)) {
+		flow = await readAnnotationFlow(await openStore(values), input.flow);
+		flowLabel = `annotation ${input.flow}`;
+	} else throw new UsageError(`--flow ${input.flow} is neither a timeline file nor an annotation id`);
+	const store = input.attach === void 0 ? void 0 : await openStore(values);
+	const claimant = cliClaimant();
+	if (store !== void 0 && input.attach !== void 0) await validateAttachTarget(store, input.attach, claimant);
+	const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+	const { verdict, file } = await runLab({
+		url: input.url,
+		flow,
+		flowLabel,
+		runs: input.runs,
+		cpuRate: input.cpu,
+		network: input.network,
+		budgets: input.budget,
+		out: input.out ?? path.join(tmpdir(), "pka-lab", stamp),
+		onRun: (run, failure) => {
+			const phase = run === "trace" ? "diagnostic trace" : `run ${run}/${input.runs}`;
+			process.stderr.write(`pka lab: ${phase} ${failure === void 0 ? "done" : `failed: ${failure.message}`}\n`);
+		}
+	});
+	let attached;
+	if (store !== void 0 && input.attach !== void 0) {
+		const attachment = {
+			kind: "perf",
+			path: `capture/perf/lab-${stamp}.json`,
+			summary: summarizeVerdict(verdict),
+			data: Buffer.from(`${JSON.stringify(verdict, null, 2)}\n`)
+		};
+		try {
+			await attach(store, input.attach, [attachment], claimant);
+		} catch (cause) {
+			const message = `Lab verdict written to ${file}; attachment failed`;
+			if (!(cause instanceof PkaError)) throw new Error(message, { cause });
+			throw new PkaError(`${message}: ${cause.message}`, { cause });
+		}
+		attached = {
+			id: input.attach,
+			path: attachment.path
+		};
+	}
+	if (values.json) line(JSON.stringify({
+		file,
+		attached,
+		verdict
+	}));
+	else {
+		printVerdict(verdict, file);
+		if (attached !== void 0) line(`attached: ${attached.id} ${attached.path}`);
+	}
+	return verdict.status === "pass" ? 0 : 3;
+}
+async function run(command, args, values) {
+	const json = values.json;
+	const store = await openStore(values);
+	const output = (result, human) => {
+		if (json) line(JSON.stringify(result));
+		else human();
+	};
+	switch (command) {
+		case "list": {
+			const input = parseInput(ListInput, {
+				status: values.status,
+				limit: numberOption(values.limit),
+				cursor: values.cursor,
+				detail: values.detail
+			});
+			const result = await list(store, input);
+			output(result, () => printList(result));
+			return;
+		}
+		case "get": {
+			const input = parseInput(GetInput, {
+				id: args[0],
+				detail: values.detail
+			});
+			const result = await get(store, input);
+			output(result, () => printAnnotation(result.annotation));
+			return;
+		}
+		case "watch": return watchCommand(store, values, json);
+		case "status": {
+			const input = parseInput(SetStatusInput, {
+				id: args[0],
+				status: args[1],
+				note: values.note
+			});
+			const result = await setStatus(store, input, cliClaimant());
+			output(result, () => line(`${result.id}  ${result.status}${result.changed ? "" : " (unchanged)"}`));
+			return;
+		}
+		case "reply": {
+			const input = parseInput(ReplyInput, {
+				id: args[0],
+				text: args[1]
+			});
+			const result = await reply(store, input, cliClaimant());
+			output(result, () => line(`Replied to ${result.id}.`));
+			return;
+		}
+		case "errors": {
+			const input = parseInput(ErrorsInput, {
+				since: values.since,
+				limit: numberOption(values.limit),
+				detail: values.detail
+			});
+			const result = await errors(store, input);
+			output(result, () => printErrors(result));
+			return;
+		}
+		case "prune": {
+			const result = await prune(store);
+			output(result, () => line(`Removed ${result.removed.length}: ${result.removed.join(" ")}`));
+			return;
+		}
+		case "lab": throw new Error("lab is dispatched before run()");
+	}
+}
+async function main(argv) {
+	try {
+		const { command, args, values } = parseCommandLine(argv);
+		if (values.help) {
+			line(USAGE);
+			return 0;
+		}
+		if (command === "lab") return await labCommand(values);
+		await run(command, args, values);
+		return 0;
+	} catch (cause) {
+		if (argv.includes("--help") || argv.includes("-h")) {
+			line(USAGE);
+			return 0;
+		}
+		if (cause instanceof UsageError || cause instanceof Error && "code" in cause && String(cause.code).startsWith("ERR_PARSE_ARGS")) {
+			process.stderr.write(`pka: ${cause.message}\n\n${USAGE}\n`);
+			return 2;
+		}
+		if (cause instanceof PkaError) {
+			process.stderr.write(`pka: ${cause.message}\n`);
+			return 1;
+		}
+		throw cause;
+	}
+}
+process.exitCode = await main(process.argv.slice(2));
+//#endregion
+export {};