@parity-app/cli 0.1.0 → 0.3.0

package/dist/{src-DYi23Ypb.mjs → src-BGF7szJh.mjs}

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

package/dist/{src-FF8eY6EI.mjs → src-DZKi9702.mjs}

@@ -1,2 +1,3 @@
-export { a as applyLibraryEdits, t as componentNode, y as generateId, n as librarySource, f as parseLibraryEdits, i as withLibraryContext } from "./src-D9EMN48r.mjs";
-import "./src-8MhDV_sA.mjs";
+import "./client-Cf66-n3R.mjs";
+export { a as applyLibraryEdits, t as componentNode, y as generateId, n as librarySource, f as parseLibraryEdits, i as withLibraryContext } from "./src-lVLSuOgh.mjs";
+import "./src-Aoey5Uq0.mjs";

package/dist/{src-DXZqtm6z.mjs → src-eso2QXtH.mjs}

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

package/dist/{src-D9EMN48r.mjs → src-lVLSuOgh.mjs}

@@ -1,11 +1,3 @@
-// ../core/src/css.ts
-/**
-* Custom properties holding 1% of a frame's viewport width and height, which viewport units are rewritten to: in a frame,
-* `100vh` is the height of the screen the frame stands for, not of Parity's window.
-*/
-const viewportWidthProperty = "--canvas-vw";
-const viewportHeightProperty = "--canvas-vh";
-new RegExp(String.raw`"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|url\([^)]*\)|var\((?:${viewportWidthProperty}|${viewportHeightProperty}),[^)]*\)`, "g");
 // ../core/src/devices.ts
 const deviceKinds = [
 	"phone",
@@ -24,6 +16,110 @@ function lengthToPixels(value) {
 	if (!Number.isFinite(number)) return void 0;
 	return match[2] === "rem" || match[2] === "em" ? number * 16 : number;
 }
+// ../core/src/css.ts
+/**
+* Custom properties holding 1% of a frame's viewport width and height, which viewport units are rewritten to: in a frame,
+* `100vh` is the height of the screen the frame stands for, not of Parity's window.
+*/
+const viewportWidthProperty = "--canvas-vw";
+const viewportHeightProperty = "--canvas-vh";
+/** Every custom property declaration in a stylesheet, in source order. */
+function collectCustomProperties(css) {
+	const declarations = [];
+	const visit = (nodes, selector, atRules) => {
+		for (const node of nodes) if (node.kind === "block") {
+			const prelude = node.prelude.trim();
+			const atRule = /^@([\w-]+)\s*([\s\S]*)$/.exec(prelude);
+			if (atRule) visit(node.children, selector, [...atRules, {
+				name: atRule[1].toLowerCase(),
+				prelude: atRule[2].trim()
+			}]);
+			else visit(node.children, prelude, atRules);
+		} else if (selector !== void 0 || atRules.length > 0) for (const match of node.text.matchAll(/--([\w-]+)\s*:\s*([^;]+)/g)) declarations.push({
+			selector: selector ?? "",
+			atRules,
+			name: match[1],
+			value: match[2].trim()
+		});
+	};
+	visit(parse(css), void 0, []);
+	return declarations;
+}
+function parse(css) {
+	let index = 0;
+	function parseLevel() {
+		const nodes = [];
+		let buffer = "";
+		let afterLastSemicolon = 0;
+		let parens = 0;
+		while (index < css.length) {
+			const char = css[index];
+			if (char === "/" && css[index + 1] === "*") {
+				const end = css.indexOf("*/", index + 2);
+				index = end === -1 ? css.length : end + 2;
+				continue;
+			}
+			if (char === "\\") {
+				buffer += css.slice(index, index + 2);
+				index += 2;
+				continue;
+			}
+			if (char === "\"" || char === "'") {
+				const end = findStringEnd(css, index);
+				buffer += css.slice(index, end);
+				index = end;
+				continue;
+			}
+			index++;
+			if (char === "(") parens++;
+			if (char === ")") parens = Math.max(0, parens - 1);
+			if (parens > 0) {
+				buffer += char;
+				continue;
+			}
+			if (char === ";") {
+				buffer += char;
+				afterLastSemicolon = buffer.length;
+			} else if (char === "{") {
+				const text = buffer.slice(0, afterLastSemicolon);
+				if (text) nodes.push({
+					kind: "text",
+					text
+				});
+				nodes.push({
+					kind: "block",
+					prelude: buffer.slice(afterLastSemicolon),
+					children: parseLevel()
+				});
+				buffer = "";
+				afterLastSemicolon = 0;
+			} else if (char === "}") {
+				if (buffer) nodes.push({
+					kind: "text",
+					text: buffer
+				});
+				return nodes;
+			} else buffer += char;
+		}
+		if (buffer) nodes.push({
+			kind: "text",
+			text: buffer
+		});
+		return nodes;
+	}
+	const nodes = [];
+	while (index < css.length) nodes.push(...parseLevel());
+	return nodes;
+}
+function findStringEnd(css, start) {
+	const quote = css[start];
+	let index = start + 1;
+	while (index < css.length) if (css[index] === "\\") index += 2;
+	else if (css[index] === quote) return index + 1;
+	else index++;
+	return css.length;
+}
+new RegExp(String.raw`"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|url\([^)]*\)|var\((?:${viewportWidthProperty}|${viewportHeightProperty}),[^)]*\)`, "g");
 // ../core/src/validate.ts
 function expectObject(value, path) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(`${path || "/"}: expected an object`);
@@ -270,10 +366,7 @@ function parseDetection(value, path) {
 			export: expectString(ref.export, `${at}/${index}/export`)
 		};
 	});
-	return compact({
-		include: optional(detection.include, (list) => refs(list, `${path}/include`)),
-		exclude: optional(detection.exclude, (list) => refs(list, `${path}/exclude`))
-	});
+	return compact({ include: optional(detection.include, (list) => refs(list, `${path}/include`)) });
 }
 function parseNote(value, path) {
 	const note = expectObject(value, path);
@@ -575,13 +668,24 @@ function parsePatch(value, path) {
 		"hidden",
 		"text",
 		"props",
-		"style"
+		"style",
+		"unset"
 	], path);
 	return compact({
 		hidden: optional(patch.hidden, (v) => expectBoolean(v, `${path}/hidden`)),
 		text: optional(patch.text, (v) => expectString(v, `${path}/text`)),
 		props: optional(patch.props, (v) => expectObject(v, `${path}/props`)),
-		style: optional(patch.style, (v) => parseStyle(v, `${path}/style`))
+		style: optional(patch.style, (v) => parseStyle(v, `${path}/style`)),
+		unset: optional(patch.unset, (v) => parseUnset(v, `${path}/unset`))
+	});
+}
+function parseUnset(value, path) {
+	const unset = expectObject(value, path);
+	expectKnownKeys(unset, ["props", "style"], path);
+	const keys = (key, item) => optional(unset[key], (v) => expectArray(v, `${path}/${key}`).map((entry, index) => item(entry, `${path}/${key}/${index}`)));
+	return compact({
+		props: keys("props", expectString),
+		style: keys("style", (v, where) => expectOneOf(v, styleKeys, where))
 	});
 }
 function parseStyle(value, path) {
@@ -729,7 +833,7 @@ const decoratorKeys = [
 const libraryManifestExtension = ".lib.par";
 function parseLibraryManifest(value) {
 	const manifest = expectObject(value, "");
-	const keys = [
+	expectKnownKeys(manifest, [
 		"$schema",
 		"version",
 		"id",
@@ -738,13 +842,16 @@ function parseLibraryManifest(value) {
 		"styles",
 		"breakpoints",
 		"tokens",
-		"canvas"
-	];
-	if (manifest.version === 3) keys.push("package", "components", "icons", "decorators", "edits");
-	expectKnownKeys(manifest, keys, "");
-	if (manifest.version !== 1 && manifest.version !== 2 && manifest.version !== 3) throw new TypeError("/version: expected 1, 2 or 3");
+		"canvas",
+		"package",
+		"components",
+		"icons",
+		"decorators",
+		"edits"
+	], "");
+	if (manifest.version !== 3) throw new TypeError("/version: expected 3");
 	return compact({
-		version: manifest.version,
+		version: 3,
 		id: optional(manifest.id, (v) => expectString(v, "/id")),
 		name: expectString(manifest.name, "/name"),
 		description: optional(manifest.description, (v) => expectString(v, "/description")),
@@ -1074,7 +1181,7 @@ function expectStringRecord(value, path) {
 const named = /* @__PURE__ */ new WeakSet();
 /**
 * A new node for a component, ready to show something: required props get their default or first option, and a
-* component that takes children gets its own name as text, so it isn't an empty box.
+* component that takes children gets its own name as text, so it isn't an empty box, unless `given` has its own.
 */
 function componentNode(component, info, taken, given = {}) {
 	const props = { ...given };
@@ -1086,7 +1193,7 @@ function componentNode(component, info, taken, given = {}) {
 		else if (prop.kind === "number") props[prop.name] = 0;
 		else if (prop.kind === "string") props[prop.name] = prop.name;
 	}
-	const labelled = info?.props.some((prop) => prop.name === "children" && prop.kind === "node");
+	const labelled = !("children" in given) && info?.props.some((prop) => prop.name === "children" && prop.kind === "node");
 	if (labelled) props.children = component.split("/").at(-1) ?? component;
 	const node = {
 		type: "component",
@@ -1247,10 +1354,10 @@ function withLibraryContext(node, sources, around, taken) {
 	}
 }
 /**
-* A library file's component as the canvas inserts it, but for where it's declared: its import, its parents and sample
-* by component id (`nova/AccordionItem`), and `imported` naming the package the way the project depends on it.
+* A library file's component as the canvas inserts it, with its parents and sample named by component id.
+* Discovery has already rewritten module imports for the name the project installed the package under.
 */
-function librarySource(library, name, component, path, imported = (specifier) => specifier) {
+function librarySource(library, name, component, path) {
 	return {
 		path,
 		export: name,
@@ -1261,14 +1368,13 @@ function librarySource(library, name, component, path, imported = (specifier) =>
 		...component.visual === false ? { visual: false } : {},
 		...component.optionalParents ? { optionalParents: component.optionalParents.map((parent) => `${library}/${parent}`) } : {},
 		...component.parentParts ? { parentParts: true } : {},
-		...component.sample ? { sample: sampleIds(component.sample, library, imported) } : {}
+		...component.sample ? { sample: sampleIds(component.sample, library) } : {}
 	};
 }
 /**
-* A sample with its children's components named by id, as `nova/AccordionItem`; HTML elements keep their tag. A value the
-* package makes (`{ $call: { import: "@chakra-ui/react", ... } }`) imports it by the name the project depends on.
+* A sample with its children's components named by id, as `nova/AccordionItem`; HTML elements keep their tag.
 */
-function sampleIds(sample, library, imported = (specifier) => specifier) {
+function sampleIds(sample, library) {
 	const child = (node) => {
 		if (typeof node === "string") return node;
 		if (isSampleRender(node)) return {
@@ -1288,13 +1394,7 @@ function sampleIds(sample, library, imported = (specifier) => specifier) {
 			$render: item.$render.map(child)
 		};
 		if (isSampleElement(item)) return { $element: item.$element.map(child) };
-		return isMadeValue(item) ? {
-			...item,
-			$call: {
-				...item.$call,
-				import: imported(item.$call.import)
-			}
-		} : item;
+		return item;
 	};
 	const propIds = (props) => Object.fromEntries(Object.entries(props).map(([key, item]) => [key, propId(item)]));
 	return {
@@ -1303,4 +1403,4 @@ function sampleIds(sample, library, imported = (specifier) => specifier) {
 		...sample.children ? { children: sample.children.map(child) } : {}
 	};
 }
-export { viewportHeightProperty as C, lengthToPixels as S, parseCanvasDocument as _, applyLibraryEdits as a, parseModeSettings as b, isSampleElement as c, parentSignals as d, parseLibraryEdits as f, paramTypes as g, imageFits as h, withLibraryContext as i, isSampleRender as l, renderSlotOf as m, librarySource as n, componentEvidence as o, parseLibraryManifest as p, sampleIds as r, isMadeValue as s, componentNode as t, libraryManifestExtension as u, styleKeys as v, viewportWidthProperty as w, deviceKinds as x, generateId as y };
+export { viewportWidthProperty as C, viewportHeightProperty as S, lengthToPixels as T, parseCanvasDocument as _, applyLibraryEdits as a, parseModeSettings as b, isSampleElement as c, parentSignals as d, parseLibraryEdits as f, paramTypes as g, imageFits as h, withLibraryContext as i, isSampleRender as l, renderSlotOf as m, librarySource as n, componentEvidence as o, parseLibraryManifest as p, sampleIds as r, isMadeValue as s, componentNode as t, libraryManifestExtension as u, styleKeys as v, deviceKinds as w, collectCustomProperties as x, generateId as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity-app/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Drive the Parity app from a terminal or an agent: read state, run edits, take screenshots, serve MCP.",
@@ -34,6 +34,11 @@
     "dist",
     "skills"
   ],
+  "scripts": {
+    "build": "vp pack",
+    "prepack": "vp pack",
+    "try-packed": "node scripts/try-packed.ts"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -42,12 +47,9 @@
     "typescript": "6.0.3"
   },
   "devDependencies": {
+    "@parity-app/agent": "0.0.0",
     "@parity-app/core": "0.0.0",
     "@parity-app/libgen": "0.0.0",
     "@parity-app/registry": "0.0.0"
-  },
-  "scripts": {
-    "build": "vp pack",
-    "try-packed": "node scripts/try-packed.ts"
   }
-}
+}

package/skills/SKILL.md

@@ -22,25 +22,62 @@ it.
 
 ## Tools
 
-The same tools are MCP tools and `parity` commands in a terminal. They act on a tab, which is one open project; the
-active tab is the default.
+The same tools are MCP tools and `parity` commands in a terminal. They act on a tab, which is one open project. Without
+`tab`, they act on the open project your working folder is in, and otherwise on `active`: what the person is looking at,
+the active tab of the Parity window they used last. When the person says "this" or "what I've selected" without naming a
+project, pass `tab: "active"` (`--tab active`) and read `get_app_state` for the selection.
 
 | MCP                   | CLI                          | What it does                                                                                                                                               |
 | --------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `get_app_state`       | `parity state`               | Designs, the selection, modes, components and token names, and what Parity detected (builder and config, package manager, installed versions). Start here. |
-| `execute`             | `parity exec`                | Runs a JavaScript snippet against the designs. All changes land as one undo step.                                                                          |
+| `get_status`          | `parity status`              | The revision, whether anything is unsaved and which files and tokens, the last save, and undo and redo; `summary` names them.                              |
+| `get_modes`           | `parity modes [design]`      | Viewports (the ids `Responsive` takes), modes (the ids renders take) and what each design shows; a design adds its frames.                                 |
+| `execute`             | `parity exec`                | Runs a JavaScript snippet against the designs. Its changes land as one undo step, merged per design with edits made meanwhile.                             |
 | `screenshot`          | `parity screenshot <design>` | Renders a design in its states and modes, offscreen, and returns the images.                                                                               |
 | `find_problems`       | `parity problems <design>`   | Render errors, overflow, clipping and unknown components, per frame.                                                                                       |
 | `check_accessibility` | `parity a11y <design>`       | axe-core against WCAG 2.2 AA, per frame, on the layers that break each rule.                                                                               |
 | `get_console`         | `parity console`             | What the project's own code wrote to the console, on the canvas and offscreen.                                                                             |
+| `get_tokens`          | `parity tokens`              | Tokens filtered by category, source or name, with values in every theme.                                                                                   |
+| `get_components`      | `parity components`          | Components, libraries, icon sets and exports left out or failing to render.                                                                                |
+| `get_props`           | `parity props <Component>`   | Props from source; `all` includes passed-through attributes.                                                                                               |
 | `get_tabs`            | `parity tabs`                | The open projects.                                                                                                                                         |
 | `open_project`        | `parity open <folder>`       | Opens a project in a new tab.                                                                                                                              |
 | `read_skill`          | `parity skill [file]`        | This skill.                                                                                                                                                |
 
-In a terminal, `parity tokens`, `parity components` and `parity props <Component>` read what designs can use without
-writing a snippet. `parity components` also says which of the app's exports aren't components and why, which components
-fail to draw on the canvas and why (often a missing provider, which a decorator adds), and what the person listed or
-took off the list by hand.
+The token, component and prop tools read what designs can use without writing a snippet in either transport.
+`parity components` also says which of the app's exports aren't components and why, which components fail to draw on the
+canvas and why (often a missing provider, which a decorator adds), and what the person listed or took off the list by
+hand.
+
+CLI commands and MCP tools share validation and defaults. Screenshot scale defaults to 1 and accepts 0.25 to 3. Audits
+check every state and shown mode unless narrowed; a single-element selector list is equivalent to a string. Screenshot
+failures and audit findings exit with 1 in the CLI and set MCP `isError`, with details retained. `get_console` defaults
+`clear` to false; `get_props` defaults `all` to false. MCP project paths must be absolute; the CLI resolves relative
+folders from its working directory. Skill reading is local and needs no running app.
+
+Several copies of Parity can run at once, each with its own projects open. Each call goes to the copy that has its
+project open, so naming the project is enough; `get_tabs` lists every copy's projects. A project open in two copies goes
+to the one that has been running longest. A copy kept apart with `PARITY_AGENT_FILE` is reached only through that file:
+
+```sh
+parity tabs                                         # every project open in any copy
+parity state --tab active                           # what the person is looking at, and their selection
+PARITY_AGENT_FILE=copy/agent.json pnpm dev &        # a copy of Parity kept apart
+PARITY_AGENT_FILE=copy/agent.json parity tabs       # just that copy
+```
+
+Every tool returns its result as data too: MCP `structuredContent`, or `--json` in the CLI. Read that rather than the
+text. A failure has `error.code` to branch on, `retryable` (send it again unchanged), `path` (the input at fault) and
+`alternatives` (valid ids for one it didn't know), so a mistyped id is fixed in one retry:
+
+```sh
+parity problems button --state loading --json
+# {"error": {"code": "unknown_state", "path": "/state", "alternatives": ["default", "outline", "destructive", "disabled"], ...}}
+parity problems button --state disabled --json
+```
+
+`get_tokens` returns the first 100 tokens and `get_console` the newest 50 messages, with `total` and `truncated`; narrow
+the read or raise `limit` when `truncated` is true.
 
 When a library's components, tokens or icons don't show, `parity lib <package> --root <project>` describes the package
 in a `.lib.par`: its components, tokens and the providers its frames need. It writes `./<id>.lib.par` in the current
@@ -54,7 +91,8 @@ keeping the designs there, so ask before running that in someone's project.
 2. **Look before you change.** Read the design with `Get("design-id", { depth: 3 })` in `execute`, and take a screenshot
    of what's there. Find the components you need with `Components()` and their props with `Props()`.
 3. **Change it in one snippet.** Build or edit the design with `Insert`, `Update`, `Replace`, `Move` and the rest. A
-   snippet either applies whole, as one step the person can undo, or changes nothing. Name the layouts you make.
+   snippet either applies whole, as one step the person can undo, or changes nothing. Name the layouts you make. If it
+   fails because the person changed a design it changes, run it again by its `editId`.
 4. **Cover every state.** A screen that loads has a loading state, a list has an empty one, a form has an error one. Add
    them with `AddState`, as changes to the base design, not as copies.
 5. **Check every frame.** Screenshot the design in all its states and the modes it shows (`state: "all"`,
@@ -65,7 +103,15 @@ keeping the designs there, so ask before running that in someone's project.
 
 Your changes to designs are on the canvas but not saved: the person saves (Ctrl+S) or undoes them, as with their own
 edits. Don't say they're saved. Token values from `SetTokens` are the same: they show at once, and go into the project's
-stylesheet when the person saves.
+stylesheet when the person saves. `get_status` says what's saved and what isn't, and its `revision` (also in
+`get_app_state`) stays the same until something changes, so compare it before reading the board again:
+
+```sh
+parity status --summary
+# shadcn-vite is at revision 7c612c04:1.
+# 1 file isn't saved. They wait for the person to save; agents can't.
+#   shadcn-vite.par: changed button
+```
 
 ## Rules
 
@@ -86,11 +132,12 @@ stylesheet when the person saves.
 - **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.
+  collide, sizing boards the canvas hasn't drawn yet from their frames (`estimated: true`).
 
 ## When something fails
 
-`execute` returns an `editId` when a snippet throws, and nothing changes. Fix it with `editId` and `edits` (exact find
-and replace on the snippet) instead of sending it all again. The error names the line. Common causes: a node path that
-matches two designs (write it as `design/node`), a node property that doesn't exist, and a state change to something
-states can't change (only `hidden`, `text`, `props` and `style`).
+`execute` returns an `editId` when a snippet throws, and nothing changes; `error.code` says why, and
+`error.alternatives` names the valid ids when a design, state, mode or component wasn't found. Fix it with `editId` and
+`edits` (exact find and replace on the snippet) instead of sending it all again. The error names the line. Common
+causes: a node path that matches two designs (write it as `design/node`), a node property that doesn't exist, and a
+state change to something states can't change (only `hidden`, `text`, `props` and `style`).

package/skills/document.md

@@ -132,6 +132,15 @@ Type set on a layout applies to the text inside it. A component's own look comes
 A state's `overrides` map node ids to patches of `hidden`, `text`, `props` and `style`. A node a state doesn't mention
 looks as it does in the base. States win over responsive patches.
 
+A patch can also take values away with `unset`, which lists prop names and style keys to drop from what's under it, so a
+state can turn off a prop the base sets or leave a layout without the base's gap:
+
+```json
+{ "fields": { "style": { "padding": 4 }, "unset": { "style": ["gap"], "props": ["disabled"] } } }
+```
+
+A key a patch sets isn't also in its `unset`. Taking away an instance's param value gives the param its default.
+
 ## Responsive
 
 A node's `responsive` maps a viewport option's id (such as `tablet` or `mobile`) to a patch of the same four things,
@@ -154,7 +163,8 @@ or hides the node. `ExtractComponent` sets all of this up from the occurrences i
 A **variant** is a param whose `options` each patch the component design, the way a state does: a size or a tone the
 instance chooses. Its `default` is an option's id, else the first option. An instance picks one in its `args`, and
 `view.variants` picks which one the component's own board shows. Patches apply in this order: the viewport's, the
-variant options', the state's, then the instance's overrides.
+variant options', the state's, then the instance's overrides. `Get` returns the stored node, with the text it was given;
+`Get(path, { state })` returns it as the board shows it, the param's value filled in and `bind` kept (see execute.md).
 
 ```json
 "params": {

package/skills/execute.md

@@ -4,12 +4,30 @@
 `await` works at the top level. When the snippet finishes, every change lands on the canvas as one step the person can
 undo; when it throws, nothing changes and you get an `editId` to fix it with.
 
-- Pass `description`: 3 to 8 words the person sees while it runs, such as "Add a pricing section".
+The person, and other agents, can change the tab while your snippet runs. Only the designs your snippet changed, created
+or deleted are applied, over what's there by then, so their edits to other designs, even in the same file, stay. If a
+design you changed was changed or deleted in the meantime, or the modes were and you set them, nothing is applied and
+the call fails naming it:
+
+```text
+Failed, nothing changed: Not applied: since this call read the tab, "Pricing" (app.par) was changed in the editor, and
+this call changes it too. Run the call again to work from what's there now.
+```
+
+Run it again with its `editId` and no edits (`parity exec --edit-id <id>`, or `execute` with just `editId`): the snippet
+reads the tab afresh, so it works from their change. Read the design again first if your snippet depends on what it
+held.
+
+- Prefer a `description` of 3 to 8 words, such as "Add a pricing section". CLI `exec` calls it `--label`. Both default
+  to "Edit designs" if omitted.
 - `Print(...)` (or `console.log`) is how you see values. Objects print as JSON.
 - Values assigned without `const` or `let` carry over to your next snippet in the same tab.
 - A snippet has 5 seconds of computing time. Rendering (screenshots and checks) doesn't count against it.
 - To retry a failed snippet, send `editId` with `edits`, each an exact `{ find, replace }` on the snippet text (`all` to
-  replace every match).
+  replace every match). Omitted edits default to an empty list. Do not send a new snippet with `editId`.
+- Both CLI and MCP validate the same request: a nonblank snippet or `editId`, nonblank label and tab when supplied, and
+  patches with a nonempty `find`, string `replace` (which can be empty), and optional boolean `all`. Invalid requests
+  are rejected before reaching the app.
 
 ## API
 
@@ -17,14 +35,15 @@ undo; when it throws, nothing changes and you get an `editId` to fix it with.
 // Reading
 Designs(): DesignSummary[]                       // every design: id, name, kind, states, what it shows, size
 GetDesign(design): Design                        // a whole design, as in document.md
-Get(path, { depth?, state? }?): Node             // a design's root or a node; depth cuts children off with "…"
+Get(path, { depth?, state?, mode? }?): Node      // a design's root or a node; depth cuts children off with "…"
 Get(path?, visit): any[]                         // walks nodes, collecting what visit returns
+Get(path, visit, { state?, mode? }): any[]       // walks nodes as a frame draws them
 Components(): string[]                           // the components designs can use
 Props(component, { all? }?): PropsInfo           // a component's props, from its source
 Icons(): IconSet[]                               // the project's icon sets, with their styles
 Icons(set, { search?, style?, limit? }): Icon[]  // async: a set's icons, as component nodes name them
 GetTokens({ category?, source?, search? }?): Token[]
-GetModes(): { settings, modes }                  // the project's modes, and each resolved
+GetModes(design?): { settings, variables, viewports, modes, designs }   // modes resolved; what each design shows
 Selection(): { design?, node?, mode? }           // what the person has selected
 
 // Designs
@@ -34,7 +53,7 @@ DeleteDesign(design): void
 
 // Nodes
 Insert(parent, node, { index?, slot? }?): string // returns the new node's id
-Update(path, change, { state? }?): void          // change: name, text, tag, hidden, props, args, style, component
+Update(path, change, { state? }?): void          // change: name, text, tag, hidden, props, args, style, unset, component
 Replace(path, node): string
 Move(path, parent, { index?, slot? }?): void     // within one design
 Copy(path, parent, { index?, slot?, name? }?): string
@@ -82,11 +101,27 @@ canvas, the main mode and the modes beside it. Start here to find ids.
 ### Get
 
 `Get("dashboard", { depth: 2 })` returns the design's root with two levels of children; deeper ones show as `"…"`. Read
-a branch with a node path, as in `Get("dashboard/Stats", { depth: 2 })`. With `state`, the result shows the nodes as
-that state changes them.
+a branch with a node path, as in `Get("dashboard/Stats", { depth: 2 })`. Without `state` or `mode`, Get returns the
+nodes as stored, which is what `Update` and the other edits change.
+
+With `state`, `mode` or both, Get returns the nodes as that frame of the board draws them: the design's variant options
+(`view.variants`), its params' defaults filled into bound values, its responsive patches for the mode, then the state's
+patches. `mode` is a mode id from `GetModes()`, as Screenshot takes. A state alone is read in the design's main mode,
+and a mode alone in the state the design shows. A bound value comes back filled in, with its `bind` kept so you can tell
+it comes from a param. An instance comes back as its own node with the args it's drawn with; read what's inside it by
+its path, `design/instance/inner`, which only works with `state` or `mode`.
+
+```js
+// A component whose title is bound to its "title" param: stored, then as the board shows it.
+Print(Get("card/title").text) // "Title"
+Print(Get("card/title", { state: "base" }).text) // "Card title", the param's default
+// A copy of the card on a screen, inside the instance, in a state and on mobile.
+Print(Get("profile/person/title", { state: "selected", mode: "mobile-light" }).text) // "Selected"
+```
 
 `Get(path, visit)` walks the nodes under `path`, or every design without one, and returns what `visit` returns for each.
-`visit(node, { design, path, depth, index, parent, skipChildren })`. Return `undefined` to collect nothing.
+`visit(node, { design, path, depth, index, parent, skipChildren })`. Return `undefined` to collect nothing. Given a
+path, `Get(path, visit, { state, mode })` visits the nodes as that frame draws them, as above.
 
 ```js
 // Every Button in the project, with where it is.
@@ -169,11 +204,14 @@ const form = Insert("settings/Content", {
 
 ### Update
 
-Changes a node. `change` takes `name`, `text`, `tag`, `hidden`, `props`, `args` (an instance's values), `style` and
-`component`. `props`, `args` and `style` merge with what's there; set a key to `null` to remove it.
+Changes a node. `change` takes `name`, `text`, `tag`, `hidden`, `props`, `args` (an instance's values), `style`, `unset`
+and `component`. `props`, `args` and `style` merge with what's there; set a key to `null` to remove it.
 
-With `{ state: "loading" }` the change belongs to that state instead of the base design. A state can change only
-`hidden`, `text`, `props` and `style`.
+With `{ state: "loading" }` the change belongs to that state instead of the base design, and `null` takes back the
+state's change to that key. A state can change only `hidden`, `text`, `props`, `style` and `unset`. To turn off in one
+state what the base sets, list it in `unset`:
+`Update(button, { unset: { props: ["disabled"], style: ["gap"] } }, { state: "ready" })`. In the base design, `unset`
+removes the keys as `null` does.
 
 ### Replace, Move, Copy and Delete
 
@@ -239,6 +277,18 @@ ExtractComponent("team-members", rows.nodes, { name: "Member row", params: { [ro
 `SetModes(settings)` replaces the project's modes: take `GetModes().settings`, change it, and pass it back. Modes are
 shared by every design.
 
+`GetModes()` also gives `viewports`, the ids `Responsive` takes, each with its width and window height; `modes`, the ids
+`Screenshot` and the checks take, each with its `values` (one option per variable), width, window height, classes and
+attributes; and `designs`, each design's `state` (or `states` when it shows every state), `main` mode and `beside`
+modes. `GetModes("dashboard")` gives just that design, with each frame's width, fixed `height` if it has one, and
+`window`.
+
+```js
+const { viewports, designs } = GetModes("dashboard")
+Print(viewports.map((viewport) => viewport.id)) // ["desktop", "tablet", "mobile"]: for Responsive
+Print(designs[0].frames.map((frame) => `${frame.mode} ${frame.window.width}x${frame.window.height}`))
+```
+
 `SetTokens` changes token values in the project's stylesheets: `SetTokens({ primary: "oklch(0.55 0.2 260)" })` for every
 theme, or `SetTokens({ primary: { default: "…", dark: "…" } })` per theme. Every frame shows the new values at once, and
 saving writes them into the project's code, so do it only when the person asks to change the design system, not to style
@@ -250,15 +300,34 @@ one design. They're undone with the call's other changes.
 result. `state` and `mode` take an id, a list, or `"all"`; `mode` also takes `"shown"`, the modes the design shows. The
 defaults are the state on the canvas and the main mode.
 
+Frames draw as the canvas does: instances of a library's component designs (from its `.lib.par`) draw that design, and
+token values not yet saved show, the person's edits and this call's own `SetTokens` alike, so
+`SetTokens({ primary: "red" }); await Screenshot(id)` shows the new value in the same call.
+
 `Measure` lays out one frame and returns its size, whether it overflows sideways, and every node's box (`clipped` when a
 parent cuts it off). `Problems` checks frames for render errors, overflow, clipping and unknown components.
 `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
+height for the viewport, else the viewport's screen height, else the device nearest its width. So `100vh` and window
+size checks measure the same in `Measure` and `Screenshot` as on the canvas, even when the frame grows past that height.
+
 ## 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 })`.
+`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`.
+
+```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.
+const dashboard = CreateDesign({ name: "Dashboard", x: 0, y: 0 })
+UpdateDesign(dashboard, { showModes: ["desktop-dark", "mobile-light"] })
+CreateDesign({ name: "Settings", x: 2200, y: 0 })
+Print(Overlaps(dashboard)) // Dashboard and Settings, 305 across, estimated: true
+```
 
 ## Examples
 

package/skills/guide/states-and-modes.md

@@ -30,9 +30,11 @@ Modes are the project's, shared by every design. Each mode picks one option of e
 - **Theme:** a class on the frame, such as `dark`, that switches the project's tokens.
 - **Locale:** `lang` and `dir` attributes, for languages and right-to-left scripts.
 
-`GetModes()` lists them. A design shows its main mode and, beside it, any others you choose with
-`UpdateDesign(design, { showModes: ["desktop-dark", "mobile-light"] })`. Show the modes that matter for the design: a
-dashboard in desktop and mobile, a component in light and dark.
+`get_modes` (`parity modes`) lists them, and `get_modes` with a design gives its frames: run it before a responsive
+change, since the ids `Responsive` takes are viewports (`mobile`) and the ids screenshots take are modes
+(`mobile-light`). `GetModes()` gives the same in a snippet. A design shows its main mode and, beside it, any others you
+choose with `UpdateDesign(design, { showModes: ["desktop-dark", "mobile-light"] })`. Show the modes that matter for the
+design: a dashboard in desktop and mobile, a component in light and dark.
 
 ## Viewports and responsive patches