@parity-app/cli 0.3.1 → 0.5.0

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/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-Cf66-n3R.mjs";
+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 { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname, join, normalize, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
@@ -99,6 +99,120 @@ function structuredExec(result) {
 		screenshots: result.screenshots.map(({ png: _png, ...shot }) => shot)
 	};
 }
+const screenshotSchema = {
+	type: "object",
+	properties: {
+		path: {
+			type: "string",
+			description: "Where the PNG was saved."
+		},
+		design: { type: "string" },
+		state: { type: "string" },
+		mode: { type: "string" }
+	},
+	required: [
+		"path",
+		"design",
+		"state",
+		"mode"
+	]
+};
+const strings$1 = {
+	type: "array",
+	items: { type: "string" }
+};
+const discardedSchema = {
+	type: "array",
+	description: "Patches each Replace threw away with the node it swapped out. Present only when there were some; reapply what's still wanted to the replacement with Responsive, Update with a state, or UpdateState.",
+	items: {
+		type: "object",
+		properties: {
+			design: { type: "string" },
+			replaced: {
+				type: "string",
+				description: "The node Replace swapped out."
+			},
+			replacement: {
+				type: "string",
+				description: "The node that took its place."
+			},
+			nodes: {
+				type: "array",
+				items: {
+					type: "object",
+					properties: {
+						id: {
+							type: "string",
+							description: "The old node's id, or instance/inner path."
+						},
+						name: { type: "string" },
+						viewports: {
+							...strings$1,
+							description: "Viewport ids it had responsive patches for."
+						},
+						states: {
+							...strings$1,
+							description: "State ids it had patches in."
+						},
+						variants: {
+							...strings$1,
+							description: "Variant options it had patches in, as param=option."
+						}
+					},
+					required: ["id"]
+				}
+			}
+		},
+		required: [
+			"design",
+			"replaced",
+			"replacement",
+			"nodes"
+		]
+	}
+};
+const warningGroupsSchema = {
+	type: "array",
+	description: "The warnings as data, in the same order: each finding once, with how many places and which. Errors come first, then warnings, then suggestions.",
+	items: {
+		type: "object",
+		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."
+			},
+			severity: {
+				type: "string",
+				enum: [
+					"error",
+					"warning",
+					"suggestion"
+				],
+				description: "error: a render failed, so a check or screenshot is missing. suggestion: worth doing, not wrong."
+			},
+			message: {
+				type: "string",
+				description: "What's wrong and what to do about it."
+			},
+			count: {
+				type: "integer",
+				minimum: 1,
+				description: "How many places it was found."
+			},
+			at: {
+				...strings$1,
+				description: "Every place: a node's design/node path, or a frame. Empty for a whole board."
+			}
+		},
+		required: [
+			"category",
+			"severity",
+			"message",
+			"count",
+			"at"
+		]
+	}
+};
 /** Execute's and screenshot's structured result. */
 const execOutputSchema = {
 	type: "object",
@@ -114,34 +228,19 @@ const execOutputSchema = {
 			description: "Lines from Print."
 		},
 		warnings: {
-			type: "array",
-			items: { type: "string" }
+			...strings$1,
+			description: "One line per warning group, places first."
 		},
+		warningGroups: warningGroupsSchema,
 		created: {
 			type: "object",
 			additionalProperties: { type: "string" },
 			description: "Names of designs and nodes created, mapped to their ids."
 		},
+		discarded: discardedSchema,
 		screenshots: {
 			type: "array",
-			items: {
-				type: "object",
-				properties: {
-					path: {
-						type: "string",
-						description: "Where the PNG was saved."
-					},
-					design: { type: "string" },
-					state: { type: "string" },
-					mode: { type: "string" }
-				},
-				required: [
-					"path",
-					"design",
-					"state",
-					"mode"
-				]
-			}
+			items: screenshotSchema
 		},
 		error: operationErrorSchema
 	},
@@ -287,8 +386,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-DZKi9702.mjs");
-	const { registryDir, registryEntries } = await import("./src-BGF7szJh.mjs");
+	const { applyLibraryEdits, componentNode, generateId, librarySource, parseLibraryEdits, withLibraryContext } = await import("./src-CqmC2-Em.mjs");
+	const { registryDir, registryEntries } = await import("./src-BwTWa2_Y.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;
@@ -416,8 +515,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-Aoey5Uq0.mjs");
-	const { covers, registryDir, registryEntries } = await import("./src-BGF7szJh.mjs");
+	const { appManifestPath, generateLibrary, manifestText, mergeManifest, reviseLibrary } = await import("./src-CpoDOrn3.mjs");
+	const { covers, registryDir, registryEntries } = await import("./src-BwTWa2_Y.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)) {
@@ -428,7 +527,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-Aoey5Uq0.mjs");
+	const { parseLibraryEdits } = await import("./src-CpoDOrn3.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;
@@ -778,6 +877,13 @@ const frameSchema = {
 	state: string,
 	mode: string
 };
+const number = { type: "number" };
+const boxSchema = object({
+	x: number,
+	y: number,
+	width: number,
+	height: number
+});
 const designSchema = object({
 	id: string,
 	name: string,
@@ -899,9 +1005,44 @@ const problemsSchema = object({
 		type: "array",
 		items: object({
 			...frameSchema,
+			kind: {
+				type: "string",
+				enum: [
+					"render-error",
+					"unknown-component",
+					"content-wider",
+					"frame-overflow",
+					"clipped"
+				]
+			},
 			problem: string,
-			node: string
-		}, ["node"])
+			node: string,
+			name: string,
+			box: boxSchema,
+			container: object({
+				node: string,
+				name: string,
+				box: boxSchema
+			}, ["node", "name"]),
+			overflow: object({
+				left: number,
+				right: number,
+				top: number,
+				bottom: number
+			}, [
+				"left",
+				"right",
+				"top",
+				"bottom"
+			])
+		}, [
+			"kind",
+			"node",
+			"name",
+			"box",
+			"container",
+			"overflow"
+		])
 	},
 	frames: integer,
 	warnings: strings
@@ -1002,8 +1143,86 @@ const propsSchema = object({
 			"default",
 			"required"
 		])
-	}
-}, ["path", "import"]);
+	},
+	composition: object({
+		role: {
+			type: "string",
+			enum: [
+				"provider",
+				"wrapper",
+				"component"
+			],
+			description: "provider draws nothing and gives parts inside it context; wrapper draws and holds other parts."
+		},
+		parents: object({
+			status: {
+				type: "string",
+				enum: [
+					"listed",
+					"none",
+					"unknown"
+				],
+				description: "listed: insert it inside chain; none: it needs nothing; unknown: nothing says, see reason."
+			},
+			chain: {
+				type: "array",
+				description: "Outermost first.",
+				items: object({
+					component: string,
+					optional: boolean_
+				}, ["optional"])
+			},
+			from: {
+				...string,
+				description: "What said so, such as the library's examples or the error it throws."
+			},
+			reason: string
+		}, [
+			"chain",
+			"from",
+			"reason"
+		]),
+		holds: {
+			...strings,
+			description: "Parts that go directly inside it."
+		},
+		slots: {
+			type: "array",
+			items: object({
+				name: string,
+				key: string,
+				kind: {
+					type: "string",
+					enum: [
+						"children",
+						"element",
+						"render"
+					]
+				}
+			})
+		},
+		example: object({
+			node: {
+				type: "object",
+				description: "A node Insert takes as it is: the component inside its parents."
+			},
+			status: {
+				type: "string",
+				enum: [
+					"drawn",
+					"failing",
+					"untried"
+				],
+				description: "Whether the component has drawn on the canvas."
+			},
+			reason: string
+		}, ["reason"])
+	})
+}, [
+	"path",
+	"import",
+	"composition"
+]);
 const viewportSchema = object({
 	id: string,
 	name: string,
@@ -1334,13 +1553,13 @@ const tools = [
 		}
 	},
 	operationTool("screenshot", "Capture a design in any of its states and modes, rendered offscreen at real widths. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".", operations.screenshot, (result) => [text(describeExec(result)), ...result.screenshots.map((shot) => image(shot.png))]),
-	operationTool("find_problems", "Find layout problems in a design, rendered offscreen in every state and the modes it shows unless you narrow it: render errors, content wider than the frame, nodes cut off by a parent that clips, and components that aren't the project's. Run it after changes, with screenshot. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".", operations.problems, (result) => [text(describeProblems(result))]),
-	operationTool("check_accessibility", "Check a design's accessibility with axe-core against WCAG 2.2 AA, rendered offscreen in every state and the modes it shows unless you narrow it. Lists each rule broken, worst first, with the layers that break it (ids you can pass to execute), the frames, what's wrong and a link on how to fix it. state and mode take an id, a list, or \"all\"; mode also takes \"shown\". Automated checks find some issues, not all.", operations.accessibility, (result) => [text(describeAccessibility(result))]),
+	operationTool("find_problems", "Find layout problems in a design, rendered offscreen in every state and the modes it shows unless you narrow it: render errors, nodes that stick out of the frame, nodes cut off by an ancestor that clips, and components that aren't the project's. Each layout finding names the node and what it overflows, with both boxes and how far past each edge. Run it after changes, with screenshot. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".", operations.problems, (result) => [text(describeProblems(result))]),
+	operationTool("check_accessibility", "Check a design's accessibility with axe-core against WCAG 2.2 AA, rendered offscreen in every state and the modes it shows unless you narrow it. Lists each rule broken, worst first, with the layers that break it (ids you can pass to execute), the frames, what's wrong and a link on how to fix it. A contrast failure names the color token to set as style.foreground so it passes in every frame checked, when one does. state and mode take an id, a list, or \"all\"; mode also takes \"shown\". Automated checks find some issues, not all.", operations.accessibility, (result) => [text(describeAccessibility(result))]),
 	operationTool("get_console", "Read what the project's own code wrote to the console: errors, warnings and logs from its components on the canvas, including while the person interacts with them, and from offscreen renders such as screenshots. Oldest first; the same message several times in a row is counted once. clear: true empties it after reading, so the next read shows only what's new.", operations.console, (result) => [text(describeConsole(result))]),
 	operationTool("open_project", "Open a project folder in a new Parity tab, or switch to it if it's already open.", operations.open, json),
 	operationTool("get_tokens", "Read tokens filtered by category, source or name, with values in every theme.", operations.tokens, (result) => [text(describeTokens(result))]),
 	operationTool("get_components", "List project components, libraries, icon sets and exports that were left out or failed to render.", operations.components, (result) => [text(describeComponents(result))]),
-	operationTool("get_props", "Read a component's props from source. all includes attributes it passes through.", operations.props, (result) => [text(describeProps(result))]),
+	operationTool("get_props", "Read a component's props from source, and its composition: the parents or provider it goes inside, the parts it holds, its slots and an example node to insert. all includes attributes it passes through.", operations.props, (result) => [text(describeProps(result))]),
 	{
 		name: "read_skill",
 		description: "Read the Parity design skill or a file it references.",
@@ -1465,7 +1684,8 @@ const usage = `parity: drive the Parity app from a terminal or an agent
                                             unless --limit says
   parity components [--tab t]               the components designs can use, by library
   parity props <Component> [--all] [--tab t]
-                                            a component's props from its source; --all adds the attributes it passes on
+                                            a component's props from its source, then what it goes inside and holds,
+                                            with an example to insert; --all adds the attributes it passes on
   parity lib [package] [--root dir] [--out file|-] [--registry] [--id id] [--name n] [--range r] [--json]
        [--only new|all|A,B] [--edits file] [--no-examples] [--no-tags]
                                             write a .lib.par: a package's components, tokens, breakpoints, icons and

package/dist/{client-Cf66-n3R.mjs → client-DgpoM3e7.mjs}

@@ -468,10 +468,45 @@ function describeExec(result) {
 	if (result.output.length > 0) lines.push("", "Output:", ...result.output);
 	const created = Object.entries(result.created);
 	if (created.length > 0) lines.push("", "Created:", ...created.map(([name, id]) => `  ${name} = ${id}`));
-	if (result.warnings.length > 0) lines.push("", "Warnings (fix these next):", ...result.warnings.map((warning) => `  ${warning}`));
+	lines.push(...describeWarnings(result));
+	if (result.discarded?.length) {
+		lines.push("", "Discarded by Replace (reapply what you still want to the new node):");
+		for (const { design, replaced, replacement, nodes } of result.discarded) {
+			lines.push(`  ${design}/${replaced}, now ${replacement}:`);
+			for (const node of nodes) {
+				const where = [
+					node.viewports && `viewports ${node.viewports.join(", ")}`,
+					node.states && `states ${node.states.join(", ")}`,
+					node.variants && `variants ${node.variants.join(", ")}`
+				].filter(Boolean);
+				lines.push(`    ${node.name ? `${node.name} (${node.id})` : node.id}: ${where.join("; ")}`);
+			}
+		}
+	}
 	if (result.screenshots.length > 0) lines.push("", "Screenshots:", ...result.screenshots.map((shot) => `  ${shot.design} / ${shot.state} / ${shot.mode}: ${shot.path}`));
 	return lines.join("\n");
 }
+const warningHeadings = {
+	error: "Render failures (these frames weren't checked):",
+	warning: "Warnings (fix these next):",
+	suggestion: "Suggestions:"
+};
+/**
+* The warnings under a heading for each severity, so a failed render doesn't read like a naming tip. The lines are
+* the app's, one per group in the groups' order; an app older than PAR-460 sends no groups, so they're all warnings.
+*/
+function describeWarnings(result) {
+	const lines = [];
+	for (const severity of [
+		"error",
+		"warning",
+		"suggestion"
+	]) {
+		const matching = result.warnings.filter((_, index) => (result.warningGroups?.[index]?.severity ?? "warning") === severity);
+		if (matching.length > 0) lines.push("", warningHeadings[severity], ...matching.map((warning) => `  ${warning}`));
+	}
+	return lines;
+}
 /** Where a tab's edits stand: the revision, what's applied and undoable, what's on disk, and what failed to write. */
 function describeStatus(result) {
 	const { tab, revision, unsaved, undo, redo, save, errors } = result;
@@ -563,6 +598,7 @@ function describeAccessibility(result) {
 				name: finding.name ?? "The design",
 				nodes: finding.node ? [finding.node] : [],
 				detail: finding.detail,
+				...fixLine(finding) ? { fix: fixLine(finding) } : {},
 				frames: []
 			};
 			layer.frames.push({
@@ -586,6 +622,7 @@ function describeAccessibility(result) {
 			const where = layer.frames.length === frames && frames > 1 ? "every frame" : frameList(layer.frames);
 			const ids = layer.nodes.length > 0 ? ` (${layer.nodes.join(", ")})` : "";
 			lines.push(`  ${layer.name}${ids}, in ${where}: ${layer.detail}`);
+			if (layer.fix) lines.push(`    ${layer.fix}`);
 		}
 		lines.push(`  How to fix it: ${helpUrl}`);
 	}
@@ -593,12 +630,19 @@ function describeAccessibility(result) {
 	lines.push("", "Automated checks find some issues, not all. Try the design with a keyboard and a screen reader too.");
 	return lines.join("\n");
 }
+/** A contrast failure's fix in a sentence, naming the style to set so it can be passed to execute. */
+function fixLine(finding) {
+	const fix = finding.contrast?.fix;
+	if (fix === "none") return "Fix: none of the project's color tokens pass on this background; change the background.";
+	return fix && `Fix: set style.foreground to "${fix.token}", which reaches ${fix.ratio}:1 in every frame checked.`;
+}
 /** A readable account of the layout problems in a design's frames, each once with the frames it's in. */
 function describeProblems(result) {
 	const { design, problems, frames } = result;
 	const checked = `${design.name} (${design.id}), ${frames === 1 ? "1 frame" : `${frames} frames`}`;
 	const grouped = /* @__PURE__ */ new Map();
-	for (const { problem, node, state, mode } of problems) {
+	for (const { problem, node: id, name, state, mode } of problems) {
+		const node = id && name ? `${name} (${id})` : id;
 		const key = `${node ?? ""}\n${problem}`;
 		const entry = grouped.get(key) ?? {
 			problem,
@@ -671,19 +715,47 @@ function describeComponents({ components, iconLibraries = [], leftOut = [], draw
 	}
 	return lines.join("\n").trimEnd();
 }
-/** A component's props, with each variant's options and default. */
+/** A component's props, with each variant's options and default, then what it needs around it and holds. */
 function describeProps(result) {
-	if (!result.known) return `${result.component}'s props haven't been read from its source yet. Try again in a moment.`;
-	const imported = result.import && result.import !== result.path ? `, imported from "${result.import}"` : "";
-	const lines = [`${result.component}, from ${result.path}${imported}:`];
-	for (const prop of result.props) {
-		const options = prop.options ? `: ${prop.options.map((option) => JSON.stringify(option)).join(", ")}` : "";
-		const fallback = prop.default === void 0 ? "" : `, default ${JSON.stringify(prop.default)}`;
-		lines.push(`  ${prop.name} (${prop.kind}${prop.required ? ", required" : ""})${options}${fallback}`);
-	}
-	if (result.props.length === 0) lines.push("  No props of its own. --all lists the attributes it passes on.");
+	const lines = [];
+	if (!result.known) lines.push(`${result.component}'s props haven't been read from its source yet. Try again in a moment.`);
+	else {
+		const imported = result.import && result.import !== result.path ? `, imported from "${result.import}"` : "";
+		lines.push(`${result.component}, from ${result.path}${imported}:`);
+		for (const prop of result.props) {
+			const options = prop.options ? `: ${prop.options.map((option) => JSON.stringify(option)).join(", ")}` : "";
+			const fallback = prop.default === void 0 ? "" : `, default ${JSON.stringify(prop.default)}`;
+			lines.push(`  ${prop.name} (${prop.kind}${prop.required ? ", required" : ""})${options}${fallback}`);
+		}
+		if (result.props.length === 0) lines.push("  No props of its own. --all lists the attributes it passes on.");
+	}
+	if (result.composition) lines.push("", ...describeComposition(result.composition));
 	return lines.join("\n");
 }
+const roles = {
+	provider: "a provider, which draws nothing and gives the parts inside it their context",
+	wrapper: "a wrapper, which other parts go inside",
+	component: "a component"
+};
+const exampleStatus = {
+	drawn: "drawn on the canvas",
+	failing: "failing on the canvas",
+	untried: "not drawn yet"
+};
+/** What a component needs around it, what it holds, its slots, and its example as JSON for `Insert`. */
+function describeComposition({ role, parents, holds, slots, example }) {
+	const lines = [`It's ${roles[role]}.`];
+	if (parents.status === "listed") {
+		const chain = parents.chain.map((parent) => parent.optional ? `${parent.component} (optional)` : parent.component);
+		lines.push(`Goes inside, outermost first: ${chain.join(" > ")}${parents.from ? ` (from its ${parents.from})` : ""}`);
+	} else if (parents.status === "none") lines.push("Needs nothing around it.");
+	else lines.push(`What it needs around it is unknown: ${parents.reason}`);
+	if (holds.length > 0) lines.push(`Holds: ${holds.join(", ")}`);
+	if (slots.length > 0) lines.push(`Slots: ${slots.map((slot) => `${slot.key} (${slot.kind})`).join(", ")}`);
+	const reason = example.reason ? `: ${example.reason}` : "";
+	lines.push(`Example for Insert, ${exampleStatus[example.status]}${reason}:`, `  ${JSON.stringify(example.node)}`);
+	return lines;
+}
 /** Frames as state and mode ids, naming a mode once when they share it: "default, error in desktop-light". */
 function frameList(frames) {
 	const modes = [...new Set(frames.map((frame) => frame.mode))];

package/dist/index.d.mts

@@ -63,15 +63,42 @@ interface Screenshot {
   state: string;
   mode: string;
 }
+/** What one `Replace` threw away: the patches keyed to the old node and what was inside it (PAR-455). */
+interface Discarded {
+  design: string;
+  replaced: string;
+  replacement: string;
+  nodes: {
+    id: string;
+    name?: string;
+    viewports?: string[];
+    states?: string[];
+    variants?: string[];
+  }[];
+}
+/**
+ * Findings with the same category and message, once, with every place they were found (PAR-460). The app's
+ * `warnings` are these as lines, in the same order.
+ */
+interface WarningGroup {
+  category: string;
+  severity: "error" | "warning" | "suggestion";
+  message: string;
+  count: number;
+  at: string[];
+}
 /** The canonical result. Structured output is this without the screenshots' image data. */
 interface ExecResponse {
   ok: boolean;
   applied: boolean;
   output: string[];
   warnings: string[];
+  warningGroups?: WarningGroup[];
   /** Set when the call failed, with the editId to retry a snippet by. */
   error?: OperationError;
   created: Record<string, string>;
+  /** Set when a Replace threw away responsive, state or variant patches. */
+  discarded?: Discarded[];
   screenshots: Screenshot[];
 }
 /**
@@ -225,6 +252,13 @@ export interface AccessibilityFinding {
   node?: string;
   name?: string;
   detail: string;
+  /** For a contrast failure: the token to color the layer's text with, or `"none"` when none of the project's pass. */
+  contrast?: {
+    fix?: {
+      token: string;
+      ratio: number;
+    } | "none";
+  };
 }
 export interface AccessibilityResponse {
   tab: {
@@ -253,15 +287,41 @@ export interface ProblemsResponse {
     id: string;
     name: string;
   };
-  problems: {
-    state: string;
-    mode: string;
-    problem: string;
-    node?: string;
-  }[];
+  problems: Problem[];
   frames: number;
   warnings: string[];
 }
+/** A box in a frame, in CSS pixels from its top left corner. */
+export interface FrameBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/**
+ * One problem in one frame. Layout problems (`frame-overflow`, `clipped`) name the node, what it overflows (the node
+ * that clips it, or the frame, which has none), both boxes, and how far past each edge it reaches.
+ */
+export interface Problem {
+  state: string;
+  mode: string;
+  kind?: "render-error" | "unknown-component" | "content-wider" | "frame-overflow" | "clipped";
+  problem: string;
+  node?: string;
+  name?: string;
+  box?: FrameBox;
+  container?: {
+    node?: string;
+    name?: string;
+    box: FrameBox;
+  };
+  overflow?: {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+  };
+}
 /** A readable account of the layout problems in a design's frames, each once with the frames it's in. */
 export declare function describeProblems(result: ProblemsResponse): string;
 export interface TokenInfo {
@@ -325,8 +385,38 @@ export interface PropsResponse {
     default?: string | number | boolean | null;
     required?: boolean;
   }[];
+  /** What it needs around it and holds inside it, read from its library's metadata (PAR-454). */
+  composition?: Composition;
+}
+/** A component's composition, as `@parity-app/editor`'s `componentComposition` reads it. */
+export interface Composition {
+  role: "provider" | "wrapper" | "component";
+  parents: {
+    status: "listed";
+    chain: {
+      component: string;
+      optional?: true;
+    }[];
+    from?: string;
+  } | {
+    status: "none";
+  } | {
+    status: "unknown";
+    reason: string;
+  };
+  holds: string[];
+  slots: {
+    name: string;
+    key: string;
+    kind: "children" | "element" | "render";
+  }[];
+  example: {
+    node: unknown;
+    status: "drawn" | "failing" | "untried";
+    reason?: string;
+  };
 }
-/** A component's props, with each variant's options and default. */
+/** A component's props, with each variant's options and default, then what it needs around it and holds. */
 export declare function describeProps(result: PropsResponse): string;
 export interface ConsoleEntry {
   level: "info" | "warning" | "error" | "debug";

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-Cf66-n3R.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-DgpoM3e7.mjs";

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

@@ -254,6 +254,58 @@ function generateId(taken, length = 5) {
 	}
 }
 // ../core/src/document.ts
+const canvasObjectKinds = [
+	"table",
+	"operation",
+	"route"
+];
+const linkEndKinds = [
+	"screen",
+	"component",
+	...canvasObjectKinds
+];
+/** Each type of link, and the kinds it may join, from and to. */
+const linkTypes = {
+	/** A screen shown at a route's URL. */
+	shows: {
+		from: ["screen"],
+		to: ["route"]
+	},
+	/** A screen, route or component that calls an operation. */
+	calls: {
+		from: [
+			"screen",
+			"route",
+			"component"
+		],
+		to: ["operation"]
+	},
+	/** An operation that reads a table. */
+	reads: {
+		from: ["operation"],
+		to: ["table"]
+	},
+	/** An operation that writes to a table. */
+	writes: {
+		from: ["operation"],
+		to: ["table"]
+	}
+};
+/** Whether a link of this type may join these two kinds. */
+function linkAllowed(type, from, to) {
+	const allowed = linkTypes[type];
+	return allowed.from.includes(from) && allowed.to.includes(to);
+}
+const lenses = [
+	"data",
+	"api",
+	"routes"
+];
+const containerKinds = [
+	"screen",
+	"component",
+	"frame"
+];
 const textTags = [
 	"p",
 	"span",
@@ -345,16 +397,97 @@ function parseCanvasDocument(value) {
 		"containers",
 		"notes",
 		"modes",
-		"detection"
+		"detection",
+		"objects",
+		"links",
+		"sources"
 	], "");
 	return compact({
 		version: 3,
 		containers: expectArray(document.containers, "/containers").map((item, index) => parseContainer(item, `/containers/${index}`)),
 		modes: optional(document.modes, (value) => parseModeSettings(value)),
 		notes: optional(document.notes, (value) => expectArray(value, "/notes").map((item, index) => parseNote(item, `/notes/${index}`))),
-		detection: optional(document.detection, (value) => parseDetection(value, "/detection"))
+		detection: optional(document.detection, (value) => parseDetection(value, "/detection")),
+		objects: optional(document.objects, (value) => parseObjects(value, "/objects")),
+		links: optional(document.links, (value) => parseLinks(value, "/links")),
+		sources: optional(document.sources, (value) => parseSources(value, "/sources"))
+	});
+}
+function parsePosition(value, path) {
+	const position = expectObject(value, path);
+	expectKnownKeys(position, ["x", "y"], path);
+	return {
+		x: expectNumber(position.x, `${path}/x`),
+		y: expectNumber(position.y, `${path}/y`)
+	};
+}
+function parseObjects(value, path) {
+	const placed = /* @__PURE__ */ new Set();
+	return expectArray(value, path).map((item, index) => {
+		const at = `${path}/${index}`;
+		const object = expectObject(item, at);
+		expectKnownKeys(object, [
+			"kind",
+			"ref",
+			"position"
+		], at);
+		const kind = expectOneOf(object.kind, canvasObjectKinds, `${at}/kind`);
+		const ref = expectString(object.ref, `${at}/ref`);
+		const key = JSON.stringify([kind, ref]);
+		if (placed.has(key)) throw new TypeError(`${at}: the ${kind} "${ref}" is already on the canvas`);
+		placed.add(key);
+		return {
+			kind,
+			ref,
+			position: parsePosition(object.position, `${at}/position`)
+		};
 	});
 }
+function parseLinkEnd(value, path) {
+	const end = expectObject(value, path);
+	expectKnownKeys(end, ["kind", "ref"], path);
+	return {
+		kind: expectOneOf(end.kind, linkEndKinds, `${path}/kind`),
+		ref: expectString(end.ref, `${path}/ref`)
+	};
+}
+function parseLinks(value, path) {
+	const ids = /* @__PURE__ */ new Set();
+	const types = Object.keys(linkTypes);
+	return expectArray(value, path).map((item, index) => {
+		const at = `${path}/${index}`;
+		const link = expectObject(item, at);
+		expectKnownKeys(link, [
+			"id",
+			"type",
+			"from",
+			"to"
+		], at);
+		const id = expectString(link.id, `${at}/id`);
+		if (ids.has(id)) throw new TypeError(`${at}/id: duplicate link id "${id}"`);
+		ids.add(id);
+		const type = expectOneOf(link.type, types, `${at}/type`);
+		const from = parseLinkEnd(link.from, `${at}/from`);
+		const to = parseLinkEnd(link.to, `${at}/to`);
+		if (!linkAllowed(type, from.kind, to.kind)) {
+			const { from: froms, to: tos } = linkTypes[type];
+			throw new TypeError(`${at}: a ${type} link goes from ${froms.join(" or ")} to ${tos.join(" or ")}, not ${from.kind} to ${to.kind}`);
+		}
+		return {
+			id,
+			type,
+			from,
+			to
+		};
+	});
+}
+function parseSources(value, path) {
+	const sources = expectObject(value, path);
+	expectKnownKeys(sources, lenses, path);
+	const chosen = {};
+	for (const lens of lenses) if (sources[lens] !== void 0) chosen[lens] = expectString(sources[lens], `${path}/${lens}`);
+	return chosen;
+}
 function parseDetection(value, path) {
 	const detection = expectObject(value, path);
 	expectKnownKeys(detection, ["include", "exclude"], path);
@@ -399,7 +532,8 @@ function parseContainer(value, path) {
 		"view",
 		"params",
 		"context",
-		"frames"
+		"frames",
+		"size"
 	], path);
 	const position = expectObject(container.position, `${path}/position`);
 	const view = optional(container.view, (v) => {
@@ -440,10 +574,13 @@ function parseContainer(value, path) {
 		};
 	});
 	if (states.length === 0) throw new TypeError(`${path}/states: expected at least one state`);
+	const kind = optional(container.kind, (v) => expectOneOf(v, containerKinds, `${path}/kind`));
+	if (kind === "frame") checkFrame(container, root, states, path);
+	else if (container.size !== void 0) throw new TypeError(`${path}/size: only a frame has a size of its own; size a ${kind ?? "screen"} in frames`);
 	return compact({
 		id: expectString(container.id, `${path}/id`),
 		name: expectString(container.name, `${path}/name`),
-		kind: optional(container.kind, (v) => expectOneOf(v, ["screen", "component"], `${path}/kind`)),
+		kind,
 		context: optional(container.context, (v) => expectArray(v, `${path}/context`).map((item, index) => {
 			const at = `${path}/context/${index}`;
 			const wrapper = expectObject(item, at);
@@ -498,17 +635,10 @@ function parseContainer(value, path) {
 		}),
 		frames: optional(container.frames, (v) => {
 			const frames = {};
-			for (const [viewport, entry] of Object.entries(expectObject(v, `${path}/frames`))) {
-				const at = `${path}/frames/${viewport}`;
-				const size = expectObject(entry, at);
-				expectKnownKeys(size, ["width", "height"], at);
-				frames[viewport] = compact({
-					width: optional(size.width, (w) => expectNumber(w, `${at}/width`)),
-					height: optional(size.height, (h) => expectNumber(h, `${at}/height`))
-				});
-			}
+			for (const [viewport, entry] of Object.entries(expectObject(v, `${path}/frames`))) frames[viewport] = parseFrameSize(entry, `${path}/frames/${viewport}`);
 			return frames;
 		}),
+		size: optional(container.size, (v) => parseFrameSize(v, `${path}/size`)),
 		position: {
 			x: expectNumber(position.x, `${path}/position/x`),
 			y: expectNumber(position.y, `${path}/position/y`)
@@ -518,6 +648,26 @@ function parseContainer(value, path) {
 		view
 	});
 }
+function parseFrameSize(value, path) {
+	const size = expectObject(value, path);
+	expectKnownKeys(size, ["width", "height"], path);
+	return compact({
+		width: optional(size.width, (w) => expectNumber(w, `${path}/width`)),
+		height: optional(size.height, (h) => expectNumber(h, `${path}/height`))
+	});
+}
+/**
+* What a frame may hold: a layout at its root and one state, drawn as its layers are, with no params, no view (it
+* shows only the primary mode and that state) and no sizes per viewport, since it has one of its own.
+*/
+function checkFrame(container, root, states, path) {
+	if (root.type !== "layout") throw new TypeError(`${path}/root: a frame's root is a layout`);
+	if (states.length > 1) throw new TypeError(`${path}/states: a frame has one state`);
+	if (Object.keys(states[0].overrides ?? {}).length > 0) throw new TypeError(`${path}/states/0/overrides: a frame is drawn as its layers are`);
+	if (container.params !== void 0) throw new TypeError(`${path}/params: a frame has no params`);
+	if (container.view !== void 0) throw new TypeError(`${path}/view: a frame shows only the primary mode and its one state`);
+	if (container.frames !== void 0) throw new TypeError(`${path}/frames: a frame's size is in size, not per viewport`);
+}
 function parseNode(value, path, ids) {
 	const node = expectObject(value, path);
 	const type = expectOneOf(node.type, [
@@ -1364,6 +1514,7 @@ function librarySource(library, name, component, path) {
 		library,
 		...component.group ? { group: component.group } : {},
 		...component.parents ? { parents: component.parents.map((parent) => `${library}/${parent}`) } : {},
+		...component.parents && component.parentsFrom ? { parentsFrom: component.parentsFrom } : {},
 		...component.internal ? { internal: true } : {},
 		...component.visual === false ? { visual: false } : {},
 		...component.optionalParents ? { optionalParents: component.optionalParents.map((parent) => `${library}/${parent}`) } : {},
@@ -1403,4 +1554,4 @@ function sampleIds(sample, library) {
 		...sample.children ? { children: sample.children.map(child) } : {}
 	};
 }
-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 };
+export { deviceKinds as A, parseCanvasDocument as C, collectCustomProperties as D, parseModeSettings as E, viewportHeightProperty as O, paramTypes as S, generateId as T, imageFits as _, applyLibraryEdits as a, linkEndKinds as b, isSampleElement as c, parentSignals as d, parseLibraryEdits as f, containerKinds as g, canvasObjectKinds as h, withLibraryContext as i, lengthToPixels as j, viewportWidthProperty as k, 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, lenses as v, styleKeys as w, linkTypes as x, linkAllowed as y };

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

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

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

@@ -1,5 +1,5 @@
-import { T as lengthToPixels, a as applyLibraryEdits, c as isSampleElement, f as parseLibraryEdits, l as isSampleRender, m as renderSlotOf, p as parseLibraryManifest, s as isMadeValue, u as libraryManifestExtension, x as collectCustomProperties } from "./src-lVLSuOgh.mjs";
-import "./src-eso2QXtH.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-BryimTPw.mjs";
+import "./src-D85OVBQL.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";
@@ -601,11 +601,12 @@ function listTheme(selector) {
 	const [only] = names;
 	return names.size === 1 ? only : void 0;
 }
-const simpleSelector = /^(?:(?<root>html|:root|:host)(?![\w(-])|\.(?<className>[\w-]+)|\[\s*[\w-]+\s*(?:=\s*(?:"(?<double>[^"]*)"|'(?<single>[^']*)'|(?<bare>[\w-]+))\s*(?:[is]\s*)?)?\]|(?<functional>:(?:not|where|is|host)\())/;
+const simpleSelector = /^(?:(?<root>html|:root|:host)(?![\w(-])|\.(?<className>[\w-]+)|\[\s*(?<attribute>[\w-]+)\s*(?:=\s*(?:"(?<double>[^"]*)"|'(?<single>[^']*)'|(?<bare>[\w-]+))\s*(?:[is]\s*)?)?\]|(?<functional>:(?:not|where|is|host)\())/;
 /** The theme one compound selector (no combinators) names, or undefined when it isn't a theme's. */
 function compoundTheme(part) {
 	let root = false;
 	const names = [];
+	let attribute;
 	let rest = part;
 	while (rest.length > 0) {
 		const match = simpleSelector.exec(rest);
@@ -623,11 +624,14 @@ function compoundTheme(part) {
 			if (!nested) return void 0;
 			root ||= nested.root;
 			if (nested.name !== void 0) names.push(nested.name);
+			attribute ??= nested.attribute;
 			continue;
 		}
 		rest = rest.slice(match[0].length);
 		if (groups.root) root = true;
-		const name = groups.className ?? groups.double ?? groups.single ?? groups.bare;
+		const value = groups.double ?? groups.single ?? groups.bare;
+		if (value !== void 0) attribute = groups.attribute;
+		const name = groups.className ?? value;
 		if (name !== void 0) names.push(name);
 	}
 	if (names.length > 1) return void 0;
@@ -635,7 +639,8 @@ function compoundTheme(part) {
 	if (!root && names.length === 0) return void 0;
 	return {
 		root: root || names[0] === "light",
-		...name === void 0 ? {} : { name }
+		...name === void 0 ? {} : { name },
+		...name !== void 0 && attribute !== void 0 ? { attribute } : {}
 	};
 }
 function matchingParen(text, open) {

package/dist/src-CqmC2-Em.mjs

@@ -0,0 +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";

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity-app/cli",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "Drive the Parity app from a terminal or an agent: read state, run edits, take screenshots, serve MCP.",

package/skills/SKILL.md

@@ -39,7 +39,7 @@ project, pass `tab: "active"` (`--tab active`) and read `get_app_state` for the
 | `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_props`           | `parity props <Component>`   | Props from source, then what it goes inside and holds, its slots and an example to insert; `all` adds 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.                                                                                                                                                |
@@ -97,7 +97,8 @@ keeping the designs there, so ask before running that in someone's project.
    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"`,
    `mode: "shown"`). Run `find_problems` and `check_accessibility` too, and read the warnings `execute` returns: they're
-   usually a token that doesn't exist or a prop the component doesn't take. Fix what you find, then check again.
+   usually a token that doesn't exist or a prop the component doesn't take. A render failure comes first and means a
+   frame wasn't checked. Fix what you find, then check again.
 6. **Say what you did.** Tell the person what changed and what you couldn't verify. Ask them to try anything interactive
    themselves with the Interact tool (I), which hands their mouse and keyboard to the real components.
 

package/skills/document.md

@@ -5,20 +5,26 @@ change, so you never edit the files by hand. This is the shape `GetDesign` and `
 
 ## Designs
 
-A design is a screen or a component, drawn on the canvas as a board of frames: one frame per state and mode it shows.
+A design is a screen, a component or a frame, drawn on the canvas as a board of frames: one frame per state and mode it
+shows.
 
 | Field     | What it is                                                                                                                                  |
 | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `id`      | Made from the name when the design is created. Stable; use it in paths.                                                                     |
 | `name`    | What people see.                                                                                                                            |
-| `kind`    | `screen` (a page or view) or `component` (a reusable part that screens place as instances).                                                 |
+| `kind`    | `screen` (a page or view), `component` (a reusable part that screens place as instances) or `frame` (a sketch; see below).                  |
 | `root`    | The design itself: one node, usually a layout.                                                                                              |
 | `states`  | Situations the whole design can be in, like loading or empty. The first is the base; the others store only what they change.                |
 | `params`  | A component design's inputs, each with a `type` (`text`, `boolean`, `number`, `value`, `variant`) and a `default`. See Params and bindings. |
-| `frames`  | A fixed size per viewport, when the design isn't as wide as the viewport or as tall as its content.                                         |
+| `frames`  | A screen's or component's fixed size per viewport, when it isn't as wide as the viewport or as tall as its content.                         |
+| `size`    | A frame's own `width` and `height` in pixels. Without a width it's as wide as the primary mode; without a height, as tall as its content.   |
 | `view`    | How the canvas shows it: the main mode, the modes beside it, the state and the variant options shown. Not part of the design.               |
 | `context` | Components a component design is drawn inside on its own board, such as a table around a table row.                                         |
 
+A frame is the light kind, for sketching: a layout at its root, drawn once in the project's primary mode at its own
+`size`, with one state and no `params`, `view` or `frames`. No code is written from it. Make it a screen or a component
+to give it more.
+
 ## Nodes
 
 Every node has an `id` (given when it's inserted), and can have a `name`, `hidden`, `style` and `responsive`. Name the

package/skills/execute.md

@@ -29,6 +29,20 @@ held.
   patches with a nonempty `find`, string `replace` (which can be empty), and optional boolean `all`. Invalid requests
   are rejected before reaching the app.
 
+### Warnings
+
+A call that applies can still return warnings. Each finding comes once, with every place it was found. The text puts
+them under "Render failures", "Warnings" and "Suggestions". The structured result's `warningGroups` gives each one's
+`category`, `severity` (`error`, `warning` or `suggestion`), `message`, `count` and `at`, which lists the places as
+`design/node` paths or frames. A render failure means a screenshot or check is missing for that frame, so look into it
+first. `unnamed_layout` is a suggestion for layouts this call added: give each one a name with `Update`.
+
+```js
+// Unnamed rows come back as one suggestion, such as 12 places (team-members/k3x9a, … and 7 more). Name them:
+const rows = Get("team-members", (node, at) => (node.type === "layout" && !node.name ? at.path : undefined))
+rows.forEach((path, index) => Update(path, { name: `Member row ${index + 1}` }))
+```
+
 ## API
 
 ```ts
@@ -47,8 +61,8 @@ GetModes(design?): { settings, variables, viewports, modes, designs }   // modes
 Selection(): { design?, node?, mode? }           // what the person has selected
 
 // Designs
-CreateDesign({ name, kind?, root?, x?, y?, file?, baseState? }): string   // returns the new design's id
-UpdateDesign(design, { name?, kind?, x?, y?, mode?, showModes?, state?, allStates? }): void
+CreateDesign({ name, kind?, root?, x?, y?, width?, height?, file?, baseState? }): string   // the new design's id
+UpdateDesign(design, { name?, kind?, x?, y?, width?, height?, mode?, showModes?, state?, allStates? }): void
 DeleteDesign(design): void
 
 // Nodes
@@ -91,12 +105,15 @@ A design is named by its id or its name. A node is named by `design/node`, where
 by its id alone when only one design has that id. Names aren't unique, so prefer ids once you have them; `Insert`,
 `Copy` and `CreateDesign` return them, and nodes you create with a `name` are listed under "Created" in the result.
 
+A state is named by its id only, as `Designs()` lists it and `AddState` returns it. A state's name in its place fails
+with `unknown_state`, and the error names the id it belongs to.
+
 ## Reading
 
 ### Designs
 
-Lists every design with its `id`, `name`, `kind` (`screen` or `component`), `states`, and `showing`: the state on the
-canvas, the main mode and the modes beside it. Start here to find ids.
+Lists every design with its `id`, `name`, `kind` (`screen`, `component` or `frame`), `states`, and `showing`: the state
+on the canvas, the main mode and the modes beside it. Start here to find ids.
 
 ### Get
 
@@ -131,8 +148,58 @@ Print(Get((node, at) => (node.type === "component" && node.component === "Button
 ### Components and Props
 
 `Components()` is everything a `component` node can name. `Props("Button")` returns the props found in the component's
-source: variants with their options (`variant`, `size`), its own props, and with `{ all: true }` the attributes it
-passes to its element. A prop that isn't listed, or a variant value outside its options, comes back as a warning.
+source: variants with their options (`variant`, `size`), its own props, including those a library's component adds to
+its element's (Nova's `isActive`), and with `{ all: true }` the attributes it passes to its element. A prop that isn't
+listed, or a variant value outside its options, comes back as a warning.
+
+Its `composition` says what it needs around it and holds, before you insert it:
+
+- `role` is `provider` for one that draws nothing and gives the parts inside it their context (`SidebarProvider`),
+  `wrapper` for one other parts go inside (`Sidebar`), and `component` otherwise.
+- `parents` is `listed`, with the `chain` it goes inside, outermost first, and where its library learned that; `none`;
+  or `unknown`, with the `reason`, such as a project component that hasn't drawn yet or an error asking for a provider.
+  An `optional` parent is left out when the ones outside it are already there.
+- `holds` lists the parts that go directly inside it, and `slots` the `key` each slot's layers go under.
+- `example.node` is the component inside its parents with its sample, as the Assets panel inserts it and the Components
+  panel draws it. `example.status` is `drawn` once the component has drawn on the canvas, `failing` with a `reason`, or
+  `untried`.
+
+```js
+// A sidebar goes inside its provider: insert the example, then fill it in.
+const { composition } = Props("nova/Sidebar")
+Print(composition.parents.chain.map((parent) => parent.component))
+const sidebar = Insert("settings/Content", composition.example.node)
+```
+
+Writing the layers yourself works the same way. A provider draws nothing of its own, so the Components panel leaves it
+out, but `Components()` lists it, since the parts inside it throw without it. A part placed without its provider shows
+in `Problems` as a render error that names it.
+
+```js
+// A Nova sidebar, inside the provider its parts need.
+const part = (component, props, children) => ({ type: "component", component, props, slots: { children } })
+const item = (label, isActive) =>
+  part("nova/SidebarMenuItem", {}, [
+    { type: "component", component: "nova/SidebarMenuButton", props: { isActive, children: label } }
+  ])
+CreateDesign({
+  name: "App sidebar",
+  root: {
+    type: "layout",
+    name: "Frame",
+    style: { width: 280, height: 400 },
+    children: [
+      part("nova/SidebarProvider", {}, [
+        part("nova/Sidebar", { collapsible: "none" }, [
+          part("nova/SidebarContent", {}, [
+            part("nova/SidebarMenu", {}, [item("Dashboard", true), item("Members", false)])
+          ])
+        ])
+      ])
+    ]
+  }
+})
+```
 
 ### Icons
 
@@ -158,8 +225,15 @@ Insert("dashboard/Toolbar", {
 
 Each token has a `name`, a `category` (`color`, `font-size`, `radius`, `shadow`, `spacing`, `font`, `font-weight`,
 `leading`, `tracking` and others), a `source` (`semantic` for the project's own variables, `theme` for its styling
-framework's scale) and its `values` per theme. Filter with `GetTokens({ category: "color", source: "semantic" })` or
-`GetTokens({ search: "radius" })`.
+framework's scale, `keyword` for a framework keyword the style fields also take) and its `values` per theme. Filter with
+`GetTokens({ category: "color", source: "semantic" })` or `GetTokens({ search: "radius" })`.
+
+For a circle or a pill, use `radius-full`, Tailwind's `rounded-full`. It's listed under `radius` with
+`source: "keyword"`, and frames draw it as round as the box allows, at any size:
+
+```js
+Update("avatar", { style: { width: 10, height: 10, radius: "radius-full" } })
+```
 
 ### Selection
 
@@ -175,11 +249,27 @@ foreground colours. Without `x` and `y` it goes into empty space. `kind: "compon
 screens place as instances; most component designs come from `ExtractComponent` instead, because that also gives them
 params.
 
+`kind: "frame"` makes a frame, the light kind for sketching an idea before it's a screen or a component: an empty padded
+layout, drawn once at its own `width` and `height` in the project's primary mode. A frame has one state, no params and
+no modes beside it, and no code is written from it, so `AddState`, `showModes` or another `mode` on one fail with
+`invalid_input`. Turn it into a screen or a component when it needs them.
+
+```js
+const sketch = CreateDesign({ name: "Sketch", kind: "frame", width: 480, height: 320 })
+Insert(sketch, { type: "text", tag: "h2", text: "Pricing ideas" })
+await Screenshot(sketch)
+UpdateDesign(sketch, { kind: "screen" }) // keeps its layers, and its size in the primary viewport
+```
+
 ### UpdateDesign
 
 Renames or moves a design, or changes how it's shown: `mode` sets the main frame's mode, `showModes` the modes beside
 it, `state` the state on the canvas, and `allStates: true` shows every state in its own row. None of these change the
-design itself.
+design itself. `width` and `height` resize a frame.
+
+`kind` turns a design into another kind. Turned into a frame, a design keeps its layers as its board drew them in the
+base state, with its params' values filled in, and drops its other states, the modes beside it, its params and its
+variants; the call's warnings say what went.
 
 ## Nodes
 
@@ -219,6 +309,25 @@ removes the keys as `null` does.
 its design; to move it to another design, `Copy` it there and `Delete` the original. `Copy` gives the copy fresh ids and
 returns the new id. A design's root can't be deleted; use `Replace`.
 
+The new node and everything in it get fresh ids, so `Replace` throws away the patches on the old node and what was
+inside it: its `Responsive` patches, its changes in every state and its variant options' patches. Replacing a design's
+root clears every state's changes. To keep a node's patches, change it with `Update` instead. The result lists what went
+under "Discarded by Replace" (`discarded` in structured output), with each node's viewports, states and variants:
+
+```text
+Discarded by Replace (reapply what you still want to the new node):
+  dashboard/stats, now k3x9a:
+    Stats (stats): viewports mobile
+```
+
+Put back the ones you still want on the new ids, in the same call or the next. A state's changes go back with
+`UpdateState(design, state, { changes: { [id]: … } })`.
+
+```js
+const stats = Replace("dashboard/Stats", { type: "layout", name: "Stats", style: { direction: "row", gap: 16 } })
+Responsive(stats, "mobile", { style: { direction: "column" } })
+```
+
 ### Responsive
 
 Patches a node in one viewport: `Responsive("dashboard/Stats", "mobile", { style: { columns: 1 } })`. The viewport is a
@@ -304,8 +413,29 @@ Frames draw as the canvas does: instances of a library's component designs (from
 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.
+`Measure` lays out one frame and returns its state, mode and size, whether it overflows sideways, and every node's box
+with the node it's drawn inside (`parent`); a node an ancestor cuts off has `clipped` and that ancestor's box in `clip`.
+`Problems` checks frames for render errors, overflow, clipping and unknown components. Each layout problem has its
+`kind`: `frame-overflow` for a node that sticks out of the frame, by its position or its width, or `clipped` for one an
+ancestor that hides overflow cuts off. It names the `node`, its `box`, the `container` it overflows (the clipping node,
+or the frame, which has no `node`) with that box, and the pixels past each edge in `overflow`. A node past a parent that
+doesn't clip, inside the frame, shows, so it isn't a problem; children going no further than a reported parent are left
+out.
+
+```js
+const id = CreateDesign({ name: "Checkout" })
+Insert(id, { type: "component", component: "Button", name: "Pay", props: { children: "Pay" } })
+// Each one, such as { kind: "frame-overflow", node: "pay", name: "Pay", box: { x: 340, y: 100, width: 60, height: 36 },
+// container: { box: { x: 0, y: 0, width: 390, height: 600 } }, overflow: { right: 10 }, problem: "at x 340, …" }
+for (const problem of await Problems(id, { mode: "shown" })) Print(problem.kind, problem.name, problem.overflow)
+const layout = await Measure(id)
+Print(
+  layout.state,
+  layout.mode,
+  layout.nodes.map((node) => `${node.id} in ${node.parent}`)
+)
+```
+
 `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

package/skills/guide/checking.md

@@ -15,8 +15,10 @@ small details.
 
 - **Render errors.** A component threw. Usually a prop with the wrong type, or a part used outside its parent (a
   `TabsTrigger` without `Tabs`). `parity components` lists the components failing anywhere on the canvas, with why.
-- **Overflow.** Content wider than the frame, usually a row that needs to wrap or stack on mobile.
-- **Clipping.** A node cut off by a parent with `overflow: hidden` or a fixed size.
+- **Overflow.** A node that sticks out of the frame, by its width or where it's placed, usually a row that needs to wrap
+  or stack on mobile. The finding gives the node, its box, the frame's, and how many pixels past which edge.
+- **Clipping.** A node cut off by an ancestor with `overflow: hidden` or a fixed size, named in the finding with its
+  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.

package/skills/guide/components.md

@@ -17,7 +17,9 @@ instance follows.
 - Read its props with `Props("Badge")`. Variants and sizes come with their options; use those values exactly. A prop the
   component doesn't declare comes back as a warning.
 - Compose the parts the way the library intends: `Tabs` holds a `TabsList` of `TabsTrigger`s and one `TabsContent` per
-  trigger; `Table` holds `TableHeader` and `TableBody`, each with `TableRow`s of cells.
+  trigger; `Table` holds `TableHeader` and `TableBody`, each with `TableRow`s of cells. `Props("nova/Sidebar")` says
+  what a part goes inside in `composition.parents`, here the `SidebarProvider` it needs, and what goes inside it in
+  `composition.holds`. Start from `composition.example.node`, which already has its parents, when they aren't there.
 - Put children where they go. `slots.children` is what goes between the component's tags. Other slots, when a component
   takes nodes as props, are named after the prop.
 

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

@@ -22,6 +22,20 @@ only its changes, so editing the base updates every state.
 
 Name states for the situation ("No members yet", "Invite failed"), not the change ("Table hidden").
 
+Every call that takes a state takes its id, never its name: `UpdateState`, `DeleteState`, `Update`'s and `Get`'s
+`state`, `UpdateDesign`'s `state` and the checks. `AddState` returns the id, and `Designs()` lists each design's states
+with their ids and names. Names can repeat and change, so an id made from a name stops matching it after a rename. A
+name passed by mistake fails with `unknown_state`, naming the id it belongs to, or every id when states share the name.
+
+```js
+AddState("team-members", { name: "No members yet", changes: { "Members table": { hidden: true } } })
+// Later, find a state's id by its name in Designs(), then pass the id.
+const states = Designs().find((design) => design.id === "team-members").states // [{ id, name }]
+const empty = states.find((state) => state.name === "No members yet").id
+UpdateState("team-members", empty, { name: "No members" })
+await Screenshot("team-members", { state: empty })
+```
+
 ## Modes
 
 Modes are the project's, shared by every design. Each mode picks one option of each variable:

package/dist/src-DZKi9702.mjs

@@ -1,3 +0,0 @@
-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";