@parity-app/cli 0.5.0 → 0.6.0

package/dist/bin.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { _ as errorDetails, a as describeExec, c as describeProps, f as setCaller, g as errorCodes, h as closest, i as describeConsole, l as describeStatus, m as CodedError, n as describeAccessibility, o as describeModes, p as mcpCallerName, r as describeComponents, s as describeProblems, t as call, u as describeTokens, v as readErrorDetails } from "./client-DgpoM3e7.mjs";
+import { a as errorCodes, i as closest, o as errorDetails, r as CodedError, s as readErrorDetails } from "./schema-BpGSCLEu.mjs";
+import { a as describeExec, c as describeProps, f as setCaller, i as describeConsole, l as describeStatus, n as describeAccessibility, o as describeModes, p as mcpCallerName, r as describeComponents, s as describeProblems, t as call, u as describeTokens } from "./client-CoW-KcnT.mjs";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname, join, normalize, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
@@ -179,7 +180,7 @@ const warningGroupsSchema = {
 		properties: {
 			category: {
 				type: "string",
-				description: "Stable: render_failed, unknown_component, unknown_component_design, unknown_prop, invalid_option, not_a_token, not_a_length_token, overlap, kind_changed or unnamed_layout."
+				description: "Stable: render_failed, unknown_component, unknown_component_design, unknown_prop, invalid_option, not_a_token, not_a_length_token, overlap, title_clearance, canvas_overlaps, kind_changed or unnamed_layout. overlap and title_clearance cover boards this call created, changed or moved: overlap when two boards collide, title_clearance when they're clear but one's title covers the other. canvas_overlaps counts the rest of the canvas's; call Overlaps() to check every board."
 			},
 			severity: {
 				type: "string",
@@ -386,8 +387,8 @@ const executeOperation = {
 */
 async function runCheck(library, options) {
 	if (!library) throw new Error("parity lib check <library> [--tab t] [--mode m]");
-	const { applyLibraryEdits, componentNode, generateId, librarySource, parseLibraryEdits, withLibraryContext } = await import("./src-CqmC2-Em.mjs");
-	const { registryDir, registryEntries } = await import("./src-BwTWa2_Y.mjs");
+	const { applyLibraryEdits, componentNode, generateId, librarySource, parseLibraryEdits, withLibraryContext } = await import("./src-p0vFxRBz.mjs");
+	const { registryDir, registryEntries } = await import("./src-Cr8pfFJE.mjs");
 	const entry = (await registryEntries()).find((item) => item.manifest.id === library);
 	if (!entry) throw new Error(`The registry has no library "${library}"`);
 	let manifest = entry.manifest;
@@ -515,8 +516,8 @@ function describeCheck(report) {
 * because it reads the project's files and its own copy of TypeScript.
 */
 async function runLib(packageName, options) {
-	const { appManifestPath, generateLibrary, manifestText, mergeManifest, reviseLibrary } = await import("./src-CpoDOrn3.mjs");
-	const { covers, registryDir, registryEntries } = await import("./src-BwTWa2_Y.mjs");
+	const { appManifestPath, generateLibrary, manifestText, mergeManifest, reviseLibrary } = await import("./src-Zm_PYFFH.mjs");
+	const { covers, registryDir, registryEntries } = await import("./src-Cr8pfFJE.mjs");
 	const spec = packageName === void 0 ? void 0 : packageSpec(packageName);
 	let root = resolve(options.root ?? ".");
 	if (spec && (spec.version !== void 0 || options.registry && !options.root)) {
@@ -527,7 +528,7 @@ async function runLib(packageName, options) {
 		console.error(`Installing ${spec.name} ${version} on its own…`);
 		root = await installedVersion(spec.name, version);
 	}
-	const { parseLibraryEdits } = await import("./src-CpoDOrn3.mjs");
+	const { parseLibraryEdits } = await import("./src-Zm_PYFFH.mjs");
 	const trialEdits = options.edits ? parseLibraryEdits(JSON.parse(await readFile(resolve(options.edits), "utf8"))) : void 0;
 	const recordedId = options.registry && spec ? options.id ?? (await registryEntries()).find((entry) => entry.manifest.package?.name === spec.name)?.manifest.id : void 0;
 	const appErrors = recordedId ? await readAppErrors(registryDir(), recordedId) : void 0;
@@ -921,10 +922,29 @@ const stateSchema = object({
 	},
 	overlaps: {
 		type: "array",
+		description: "Every pair of boards on the canvas that's too close, as execute's Overlaps() lists them. A pair with titleOnly doesn't collide: the lower board's title covers the upper one.",
 		items: object({
 			designs: strings,
-			names: strings
-		})
+			names: strings,
+			width: {
+				...number,
+				description: "How far they share, title band included."
+			},
+			height: number,
+			titleOnly: {
+				...boolean_,
+				description: "Only the lower board's title covers the other; the boards are clear."
+			},
+			estimated: {
+				...boolean_,
+				description: "One isn't drawn yet, so its size is estimated from its frames. Absent: both measured."
+			}
+		}, [
+			"width",
+			"height",
+			"titleOnly",
+			"estimated"
+		])
 	},
 	modes: {
 		type: "array",

package/dist/{client-DgpoM3e7.mjs → client-CoW-KcnT.mjs}

@@ -1,35 +1,38 @@
+import { c as unknownReference, n as nonBlankString, r as CodedError, s as readErrorDetails, t as jsonText } from "./schema-BpGSCLEu.mjs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
+import { z } from "zod";
+// ../agent/src/routing.ts
+/**
+* Which running copy of Parity an agent's call goes to (PAR-514). Several copies can run at once, each with its own
+* projects open: the person's app, a dev session, `pnpm perf`. Agents care about the project, not the copy, so every
+* call is sent to the copy that has its project open. The CLI decides, once, with these rules, and sends that copy the
+* exact tab it chose; the app matches a tab reference with the same `matchTab`. Nothing here touches files or the
+* network, so the app's renderer can use it too.
+*/
+/** How to reach one running copy: what it writes to its registry entry. A number an entry lacks reads as 0. */
+const copyEntry = z.object({
+	version: z.number().catch(0),
+	url: z.string(),
+	token: z.string(),
+	/** The app's main process, which names the copy and its entry. A service the app restarts is the same copy. */
+	app: z.number(),
+	/** When the copy started, in milliseconds since the epoch. A project open in two copies goes to the older one. */
+	startedAt: z.number().catch(0)
+});
+/** An entry's text. The file from before the registry names the app's main process `pid`. */
+const entryText = jsonText(copyEntry.extend({
+	app: z.number().optional().catch(void 0),
+	pid: z.number().optional().catch(void 0)
+}).transform(({ app, pid, ...entry }) => ({
+	...entry,
+	app: app ?? pid ?? 0
+})));
 /** Reads a registry entry's text, or nothing when it isn't one. A file from before the registry stands for its copy. */
 function readCopyEntry(text) {
-	if (text === void 0) return void 0;
-	let value;
-	try {
-		value = JSON.parse(text);
-	} catch {
-		return;
-	}
-	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
-	const fields = new Map(Object.entries(value));
-	const [version, url, token, app, pid, startedAt] = [
-		"version",
-		"url",
-		"token",
-		"app",
-		"pid",
-		"startedAt"
-	].map((key) => fields.get(key));
-	if (typeof url !== "string" || typeof token !== "string") return void 0;
-	const number = (field) => typeof field === "number" ? field : void 0;
-	return {
-		version: number(version) ?? 0,
-		url,
-		token,
-		app: number(app) ?? number(pid) ?? 0,
-		startedAt: number(startedAt) ?? 0
-	};
+	return entryText.safeParse(text).data;
 }
 /**
 * A project folder as routing compares it: forward slashes, no trailing slash, and on Windows (a drive letter or a
@@ -160,15 +163,21 @@ function byAge(a, b) {
 	return a.entry.startedAt - b.entry.startedAt || a.entry.app - b.entry.app;
 }
 // ../agent/src/registry.ts
+/** The settings that place the registry. One that's blank counts as unset. */
+const registrySettings = z.object({
+	PARITY_AGENT_FILE: nonBlankString.optional().catch(void 0),
+	PARITY_AGENT_DIR: nonBlankString.optional().catch(void 0)
+});
 /** The registry these settings name: `PARITY_AGENT_FILE`, else `PARITY_AGENT_DIR`, else `~/.parity/agents`. */
 function agentRegistry(env, home) {
-	if (env.PARITY_AGENT_FILE) return {
+	const { PARITY_AGENT_FILE: file, PARITY_AGENT_DIR: folder } = registrySettings.parse(env);
+	if (file) return {
 		kind: "file",
-		path: env.PARITY_AGENT_FILE
+		path: file
 	};
 	return {
 		kind: "folder",
-		path: env.PARITY_AGENT_DIR || join(home, ".parity", "agents")
+		path: folder ?? join(home, ".parity", "agents")
 	};
 }
 /** The file before the registry, where an app from before it says how to reach it. */
@@ -221,105 +230,10 @@ function readText(path) {
 		return;
 	}
 }
-// ../core/src/errors.ts
-/**
-* Why an agent's call failed, as a stable code it can act on without reading the message. The CLI and MCP publish
-* these; the app throws them where it knows the cause.
-*/
-const errorCodes = [
-	"invalid_input",
-	"not_running",
-	"not_answering",
-	"unknown_tab",
-	"tab_not_ready",
-	"unknown_design",
-	"unknown_node",
-	"ambiguous_reference",
-	"unknown_state",
-	"unknown_mode",
-	"unknown_viewport",
-	"unknown_component",
-	"unknown_icon_set",
-	"unknown_edit_id",
-	"conflict",
-	"execution_failed",
-	"app_error"
-];
-/** An error with a stable code, the field it's about and what to use instead. */
-var CodedError = class extends Error {
-	details;
-	constructor(message, details) {
-		super(message);
-		this.name = "CodedError";
-		this.details = {
-			...details,
-			retryable: details.retryable ?? false
-		};
-	}
-};
-/** An unknown reference, naming the valid ones closest to what was asked for, up to `alternativeLimit`. */
-function unknownReference(code, message, reference, candidates, field) {
-	return new CodedError(message, {
-		code,
-		...field === void 0 ? {} : { field },
-		alternatives: closest(reference, candidates)
-	});
-}
-/**
-* Candidates sharing text with the reference first, ignoring case, then the rest by how few single-character edits
-* away they are, so a typo's intended id makes the cut; ties keep their own order. All of them when they fit.
-*/
-function closest(reference, candidates, limit = 20) {
-	const unique = [...new Set(candidates)];
-	if (unique.length <= limit) return unique;
-	const wanted = reference.toLowerCase();
-	const ranked = unique.map((candidate, index) => {
-		const lower = candidate.toLowerCase();
-		const near = wanted.length > 0 && (lower.includes(wanted) || wanted.includes(lower));
-		return {
-			candidate,
-			index,
-			near: near ? 0 : 1,
-			distance: near ? 0 : editDistance(wanted, lower)
-		};
-	});
-	ranked.sort((a, b) => a.near - b.near || a.distance - b.distance || a.index - b.index);
-	return ranked.slice(0, limit).map(({ candidate }) => candidate);
-}
-/** How many single-character insertions, deletions or substitutions turn one string into the other. */
-function editDistance(a, b) {
-	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
-	for (let i = 1; i <= a.length; i++) {
-		const row = [i];
-		for (let j = 1; j <= b.length; j++) row[j] = Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
-		previous = row;
-	}
-	return previous[b.length];
-}
-/** A thrown value's details, when it carries them. */
-function errorDetails(error) {
-	return error instanceof CodedError ? error.details : void 0;
-}
-/** Details that came from another process, checked before they're trusted. Anything malformed reads as none. */
-function readErrorDetails(value) {
-	if (!value || typeof value !== "object") return void 0;
-	const code = "code" in value ? value.code : void 0;
-	const known = errorCodes.find((candidate) => candidate === code);
-	if (!known) return void 0;
-	const retryable = "retryable" in value && value.retryable === true;
-	const field = "field" in value && typeof value.field === "string" && value.field ? value.field : void 0;
-	const alternatives = "alternatives" in value && Array.isArray(value.alternatives) ? value.alternatives.filter((item) => typeof item === "string").slice(0, 20) : void 0;
-	return {
-		code: known,
-		retryable,
-		...field === void 0 ? {} : { field },
-		...alternatives === void 0 ? {} : { alternatives }
-	};
-}
 // src/caller.ts
 /** Declared caller names are displayed verbatim apart from surrounding whitespace. */
 function declaredName(value) {
-	return typeof value === "string" ? value.trim() || void 0 : void 0;
+	return nonBlankString.safeParse(value).data;
 }
 /** Reserve the session suffix inside the desktop boundary's 80-character caller-id limit. */
 function sessionCallerId(name, session) {
@@ -405,10 +319,13 @@ async function runningCopies() {
 			report
 		}] : [];
 	}))).flat();
-	if (entries.length > 0 && copies.length === 0) throw new CodedError(`Parity isn't answering at ${entries.map((entry) => entry.url).join(", ")}. Is the app still running?`, {
-		code: "not_answering",
-		retryable: true
-	});
+	if (entries.length > 0 && copies.length === 0) {
+		const where = entries.map((entry) => entry.url).join(", ");
+		throw new CodedError(`Parity isn't answering at ${where}. Is the app still running?`, {
+			code: "not_answering",
+			retryable: true
+		});
+	}
 	if (copies.length === 0) throw new CodedError(`Parity isn't running (nothing in ${registry.path}). Start the app, then try again.`, {
 		code: "not_running",
 		retryable: true
@@ -793,4 +710,4 @@ function scriptPath(url) {
 		return url || "an unknown script";
 	}
 }
-export { errorDetails as _, describeExec as a, describeProps as c, registry as d, setCaller as f, errorCodes as g, closest as h, describeConsole as i, describeStatus as l, CodedError as m, describeAccessibility as n, describeModes as o, mcpCallerName as p, describeComponents as r, describeProblems as s, call as t, describeTokens as u, readErrorDetails as v, unknownReference as y };
+export { describeExec as a, describeProps as c, registry as d, setCaller as f, describeConsole as i, describeStatus as l, describeAccessibility as n, describeModes as o, mcpCallerName as p, describeComponents as r, describeProblems as s, call as t, describeTokens as u };

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /**
  * Where running copies of Parity say how to reach them (PAR-514): one entry per copy, named by its main process, in
  * `~/.parity/agents`. Each copy writes and removes only its own. The app and the CLI both go through here, so the

package/dist/index.mjs

@@ -1 +1 @@
-export { t as call, n as describeAccessibility, r as describeComponents, i as describeConsole, a as describeExec, o as describeModes, s as describeProblems, c as describeProps, l as describeStatus, u as describeTokens, d as registry, f as setCaller } from "./client-DgpoM3e7.mjs";
+export { t as call, n as describeAccessibility, r as describeComponents, i as describeConsole, a as describeExec, o as describeModes, s as describeProblems, c as describeProps, l as describeStatus, u as describeTokens, d as registry, f as setCaller } from "./client-CoW-KcnT.mjs";

package/dist/schema-BpGSCLEu.mjs

@@ -0,0 +1,113 @@
+import { z } from "zod";
+// ../core/src/errors.ts
+/**
+* Why an agent's call failed, as a stable code it can act on without reading the message. The CLI and MCP publish
+* these; the app throws them where it knows the cause.
+*/
+const errorCodes = [
+	"invalid_input",
+	"not_running",
+	"not_answering",
+	"unknown_tab",
+	"tab_not_ready",
+	"unknown_design",
+	"unknown_node",
+	"ambiguous_reference",
+	"unknown_state",
+	"unknown_mode",
+	"unknown_viewport",
+	"unknown_component",
+	"unknown_icon_set",
+	"unknown_edit_id",
+	"conflict",
+	"execution_failed",
+	"app_error"
+];
+/** Details as another process sends them. Each field that's malformed falls back on its own; only the code must hold. */
+const errorDetailsSchema = z.object({
+	code: z.enum(errorCodes),
+	/** Whether sending the same request again, unchanged, can succeed. */
+	retryable: z.boolean().catch(false),
+	/** The request field at fault, as a path: `design`, `state`, `edits/0/find`. */
+	field: z.string().min(1).optional().catch(void 0),
+	/** Valid references to use instead of an unknown or ambiguous one, at most `alternativeLimit` of them. */
+	alternatives: z.array(z.unknown()).transform((items) => items.filter((item) => typeof item === "string").slice(0, 20)).optional().catch(void 0)
+});
+/** An error with a stable code, the field it's about and what to use instead. */
+var CodedError = class extends Error {
+	details;
+	constructor(message, details) {
+		super(message);
+		this.name = "CodedError";
+		this.details = {
+			...details,
+			retryable: details.retryable ?? false
+		};
+	}
+};
+/** An unknown reference, naming the valid ones closest to what was asked for, up to `alternativeLimit`. */
+function unknownReference(code, message, reference, candidates, field) {
+	return new CodedError(message, {
+		code,
+		...field === void 0 ? {} : { field },
+		alternatives: closest(reference, candidates)
+	});
+}
+/**
+* Candidates sharing text with the reference first, ignoring case, then the rest by how few single-character edits
+* away they are, so a typo's intended id makes the cut; ties keep their own order. All of them when they fit.
+*/
+function closest(reference, candidates, limit = 20) {
+	const unique = [...new Set(candidates)];
+	if (unique.length <= limit) return unique;
+	const wanted = reference.toLowerCase();
+	const ranked = unique.map((candidate, index) => {
+		const lower = candidate.toLowerCase();
+		const near = wanted.length > 0 && (lower.includes(wanted) || wanted.includes(lower));
+		return {
+			candidate,
+			index,
+			near: near ? 0 : 1,
+			distance: near ? 0 : editDistance(wanted, lower)
+		};
+	});
+	ranked.sort((a, b) => a.near - b.near || a.distance - b.distance || a.index - b.index);
+	return ranked.slice(0, limit).map(({ candidate }) => candidate);
+}
+/** How many single-character insertions, deletions or substitutions turn one string into the other. */
+function editDistance(a, b) {
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= a.length; i++) {
+		const row = [i];
+		for (let j = 1; j <= b.length; j++) row[j] = Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+		previous = row;
+	}
+	return previous[b.length];
+}
+/** A thrown value's details, when it carries them. */
+function errorDetails(error) {
+	return error instanceof CodedError ? error.details : void 0;
+}
+/** Details that came from another process, checked before they're trusted. Anything malformed reads as none. */
+function readErrorDetails(value) {
+	return errorDetailsSchema.safeParse(value).data;
+}
+z.record(z.string(), z.unknown());
+/** Text with something besides whitespace, trimmed. */
+const nonBlankString = z.string().trim().min(1, "can't be blank");
+z.number();
+/** JSON text holding what `schema` checks. Text that isn't JSON fails as `expected JSON`. */
+function jsonText(schema) {
+	return z.string().transform((text, context) => {
+		try {
+			return JSON.parse(text);
+		} catch {
+			context.addIssue({
+				code: "custom",
+				message: "expected JSON"
+			});
+			return z.NEVER;
+		}
+	}).pipe(schema);
+}
+export { errorCodes as a, unknownReference as c, closest as i, nonBlankString as n, errorDetails as o, CodedError as r, readErrorDetails as s, jsonText as t };

package/dist/{src-D85OVBQL.mjs → src-5CrSA_RX.mjs}

@@ -1,4 +1,4 @@
-import { p as parseLibraryManifest, u as libraryManifestExtension } from "./src-BryimTPw.mjs";
+import { p as parseLibraryManifest, u as libraryManifestExtension } from "./src-C4faIpux.mjs";
 import { createRequire } from "node:module";
 import { readFile, readdir } from "node:fs/promises";
 import { dirname, join } from "node:path";

package/dist/{src-BryimTPw.mjs → src-C4faIpux.mjs}

@@ -1,3 +1,13 @@
+import "./schema-BpGSCLEu.mjs";
+import { z } from "zod";
+// ../core/src/adapters.ts
+const packageVersions = z.record(z.string(), z.string());
+z.looseObject({
+	name: z.string().optional(),
+	dependencies: packageVersions.optional(),
+	devDependencies: packageVersions.optional(),
+	scripts: z.record(z.string(), z.string()).optional()
+});
 // ../core/src/devices.ts
 const deviceKinds = [
 	"phone",

package/dist/{src-BwTWa2_Y.mjs → src-Cr8pfFJE.mjs}

@@ -1 +1 @@
-export { t as covers, n as registryDir, r as registryEntries } from "./src-D85OVBQL.mjs";
+export { t as covers, n as registryDir, r as registryEntries } from "./src-5CrSA_RX.mjs";

package/dist/{src-CpoDOrn3.mjs → src-Zm_PYFFH.mjs}

@@ -1,5 +1,5 @@
-import { D as collectCustomProperties, a as applyLibraryEdits, c as isSampleElement, f as parseLibraryEdits, j as lengthToPixels, l as isSampleRender, m as renderSlotOf, p as parseLibraryManifest, s as isMadeValue, u as libraryManifestExtension } from "./src-BryimTPw.mjs";
-import "./src-D85OVBQL.mjs";
+import { D as collectCustomProperties, a as applyLibraryEdits, c as isSampleElement, f as parseLibraryEdits, j as lengthToPixels, l as isSampleRender, m as renderSlotOf, p as parseLibraryManifest, s as isMadeValue, u as libraryManifestExtension } from "./src-C4faIpux.mjs";
+import "./src-5CrSA_RX.mjs";
 import { a as publishedVersions, n as packageFile, o as repositoryFiles, r as publishedSource } from "./published-CdXoUgfD.mjs";
 import { createRequire } from "node:module";
 import { mkdir, readFile, readdir, realpath, rm, stat, writeFile } from "node:fs/promises";

package/dist/{src-CqmC2-Em.mjs → src-p0vFxRBz.mjs}

@@ -1,3 +1,3 @@
-import "./client-DgpoM3e7.mjs";
-export { a as applyLibraryEdits, t as componentNode, T as generateId, n as librarySource, f as parseLibraryEdits, i as withLibraryContext } from "./src-BryimTPw.mjs";
-import "./src-CpoDOrn3.mjs";
+import "./schema-BpGSCLEu.mjs";
+export { a as applyLibraryEdits, t as componentNode, T as generateId, n as librarySource, f as parseLibraryEdits, i as withLibraryContext } from "./src-C4faIpux.mjs";
+import "./src-Zm_PYFFH.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity-app/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "type": "module",
   "description": "Drive the Parity app from a terminal or an agent: read state, run edits, take screenshots, serve MCP.",
@@ -44,7 +44,8 @@
   },
   "dependencies": {
     "semver": "^7.8.5",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@parity-app/agent": "0.0.0",

package/skills/SKILL.md

@@ -132,8 +132,9 @@ parity status --summary
   Lorem ipsum hides layout problems.
 - **Reuse what repeats.** When a row, card or list item appears more than twice, make it a component design with
   `ExtractComponent`, so each copy is an instance with its own content.
-- **Leave the canvas tidy.** New designs go into empty space (`FindEmptySpace`); `Overlaps()` tells you if boards
-  collide, sizing boards the canvas hasn't drawn yet from their frames (`estimated: true`).
+- **Leave the canvas tidy.** New designs go into empty space (`FindEmptySpace`). A call warns only about the boards it
+  moves; `Overlaps()` checks every board, telling collisions from a title too close (`titleOnly`) and boards sized from
+  their frames because the canvas hasn't drawn them (`estimated: true`).
 
 ## When something fails
 

package/skills/execute.md

@@ -89,7 +89,7 @@ SetTokens({ name: value | { theme: value } }): void
 
 // Checking
 Screenshot(design, { state?, mode?, scale? }?): number
-Measure(design, { state?, mode? }?): Layout
+Measure(design, { state?, mode? }?): Layout      // one frame: one state id, one mode id
 Problems(design, { state?, mode? }?): Problem[]
 Accessibility(design, { state?, mode? }?): Finding[]
 
@@ -436,6 +436,21 @@ Print(
 )
 ```
 
+`Measure` takes one state id and one mode id, because it returns one frame's layout. A list, `"all"` or `"shown"` fails
+with `invalid_input`, naming the ids it takes. To measure several frames, call it once for each; every layout says which
+state and mode it drew:
+
+```js
+const signup = Designs().find((design) => design.id === "signup")
+const layouts = []
+for (const state of signup.states) {
+  for (const mode of [signup.showing.mode, ...signup.showing.beside]) {
+    layouts.push(await Measure("signup", { state: state.id, mode }))
+  }
+}
+for (const layout of layouts) Print(`${layout.state} in ${layout.mode}: ${layout.width} × ${layout.height}`)
+```
+
 `Accessibility` returns axe-core's findings per node and frame, with the rule, its impact and what's wrong.
 
 These frames are drawn in the same window as the canvas's: as wide as the frame, and as tall as the design's fixed
@@ -444,12 +459,22 @@ size checks measure the same in `Measure` and `Screenshot` as on the canvas, eve
 
 ## The canvas
 
-`FindEmptySpace({ width, height })` finds room for a new board, to the right of the others unless `direction: "below"`,
-or next to the design named in `near`. `Overlaps()` lists boards that collide, titles included; move one with
-`UpdateDesign(design, { x, y })`. A board is as big as the canvas last drew it. One it hasn't drawn yet is sized from
-its frames, laid out as the canvas lays them out: each shown mode's frame size (`frames` on the design, else the mode's
-width), companions shrunk to 640 wide, and a frame without a fixed height as tall as its window. Those overlaps say
-`estimated: true`.
+`FindEmptySpace({ width, height })` finds room for a board that size, to the right of the others unless
+`direction: "below"`, or next to the design named in `near`. Its default `padding` of 240 leaves room for the board's
+title. Give it the size the board will be: `Designs()` has a drawn board's `width` and `height`.
+
+`Overlaps()` checks every board on the canvas and lists each pair that's too close, in one of two kinds:
+
+- **A collision:** the boards themselves overlap.
+- **Title clearance:** `titleOnly: true`. The boards are clear, but the lower one starts less than 160 below the upper
+  one, so the title the canvas draws above it covers the upper board.
+
+`width` and `height` are the area they share, title band included. Move one with `UpdateDesign(design, { x, y })`.
+
+A board is as big as the canvas last drew it, so its size is measured. One it hasn't drawn yet is sized from its frames,
+laid out as the canvas lays them out: each shown mode's frame size (`frames` on the design, else the mode's width),
+companions shrunk to 640 wide, and a frame without a fixed height as tall as its window. A pair with an estimated board
+says `estimated: true`; without it, both sizes are measured.
 
 ```js
 // With the default modes: a 1280 main frame, the dark one beside it at half size and the 390 phone, 2505 wide in all.
@@ -459,6 +484,20 @@ CreateDesign({ name: "Settings", x: 2200, y: 0 })
 Print(Overlaps(dashboard)) // Dashboard and Settings, 305 across, estimated: true
 ```
 
+An execute call's own warnings cover only the boards it creates, changes or moves: `overlap` for a collision and
+`title_clearance` for a title too close. Other crowded boards are counted in one `canvas_overlaps` suggestion, so a call
+that changes nothing, or only reads, doesn't make a crowded canvas look clear. To audit the canvas, call `Overlaps()`:
+
+```js
+for (const { names, titleOnly, estimated } of Overlaps()) {
+  const kind = titleOnly ? "a title covers a board" : "the boards collide"
+  Print(`${names.join(" and ")}: ${kind}, ${estimated ? "estimated" : "measured"}`)
+}
+// Room below Settings for a board 1400 wide and 1000 tall, and its title above it.
+const room = FindEmptySpace({ width: 1400, height: 1000, near: "settings", direction: "below" })
+CreateDesign({ name: "Plans", x: room.x, y: room.y })
+```
+
 ## Examples
 
 A new screen, checked in every state and mode:

package/skills/guide/checking.md

@@ -21,7 +21,8 @@ small details.
   box. A node that only spills past a parent that doesn't clip still shows, so it isn't listed.
 - **Unknown components.** A name that isn't in `Components()`; it draws as a placeholder.
 
-`Measure` gives every node's box in one frame, for checking alignment or sizes by numbers.
+`Measure` gives every node's box in one frame, for checking alignment or sizes by numbers. It takes one state and one
+mode; to compare frames, call it for each, as the execute skill shows.
 
 ## Accessibility