@parity-app/cli 0.0.0-stage → 0.0.0

package/dist/src-uPmBVSsB.mjs

@@ -0,0 +1,53 @@
+import { p as parseLibraryManifest, u as libraryManifestExtension } from "./src-CSeISXoZ.mjs";
+import { createRequire } from "node:module";
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import semver from "semver";
+// ../registry/src/index.ts
+const require = createRequire(import.meta.url);
+/**
+* The folder the registry's files are in. The published CLI bundles this module and ships the files beside it, where
+* the package can't be resolved. Otherwise they're found through the package's own `package.json`, so it's the same
+* whether this module runs from source or bundled into the app.
+*/
+function registryDir() {
+	const bundled = join(import.meta.dirname, "libraries");
+	if (existsSync(bundled)) return bundled;
+	return join(dirname(require.resolve("@parity-app/registry/package.json")), "libraries");
+}
+let cache;
+/** Every file in the registry, read once. One that doesn't parse is skipped with a warning. */
+function registryEntries(dir = registryDir()) {
+	if (dir !== registryDir()) return readEntries(dir);
+	cache ??= readEntries(dir);
+	return cache;
+}
+async function readEntries(dir) {
+	const files = (await readdir(dir).catch(() => [])).filter((file) => file.endsWith(libraryManifestExtension)).sort();
+	const entries = [];
+	for (const file of files) {
+		const path = join(dir, file);
+		try {
+			const manifest = parseLibraryManifest(JSON.parse(await readFile(path, "utf8")));
+			if (!manifest.package) throw new TypeError("/package: a registry file names the package it describes");
+			entries.push({
+				file,
+				path,
+				manifest
+			});
+		} catch (error) {
+			console.warn(`Skipping registry file ${file}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return entries;
+}
+/** Whether a manifest describes this version of its package. A manifest without a range covers every version. */
+function covers(manifest, version) {
+	const range = manifest.package?.range;
+	if (!range) return true;
+	if (!version) return false;
+	const parsed = semver.coerce(version, { includePrerelease: true });
+	return parsed !== null && semver.satisfies(parsed, range, { includePrerelease: true });
+}
+export { registryDir as n, registryEntries as r, covers as t };

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@parity-app/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Drive the Parity app from a terminal or an agent: read state, run edits, take screenshots, serve MCP.",
+  "keywords": [
+    "parity",
+    "design",
+    "components",
+    "mcp",
+    "cli"
+  ],
+  "homepage": "https://github.com/betterapps-hq/parity/tree/main/packages/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/betterapps-hq/parity.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/betterapps-hq/parity/issues",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "parity": "./dist/bin.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "semver": "^7.8.5",
+    "typescript": "6.0.3"
+  },
+  "devDependencies": {
+    "@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

@@ -0,0 +1,96 @@
+# Parity
+
+Parity is a design canvas that draws a project's real components, from its own source, styled only with its own tokens.
+A design here isn't a picture of the app: every button, card and table on the canvas is the project's component,
+rendered by its builder. What you design is what the code can build, and the files are the source of truth.
+
+Read this file first. Read `execute.md` and `document.md` before your first change; read a guide when the task calls for
+it.
+
+## Files
+
+| Read                        | When                                                                                   |
+| --------------------------- | -------------------------------------------------------------------------------------- |
+| `execute.md`                | Before any change: the functions a snippet can call, with examples. Required.          |
+| `document.md`               | Before any change: designs, nodes, styles, states and responsive patches. Required.    |
+| `guide/components.md`       | Using the project's components, making component designs, instances and params, icons. |
+| `guide/states-and-modes.md` | Loading, empty, error and other states; themes, viewports and locales.                 |
+| `guide/checking.md`         | Screenshots, layout problems, accessibility, the console, and trying a design.         |
+| `guide/design-system.md`    | Composing screens from the project's components and tokens.                            |
+| `guide/web-app.md`          | Designing web app screens: dashboards, settings, lists, forms.                         |
+| `guide/mobile.md`           | Designing for phones and small viewports.                                              |
+
+## 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.
+
+| 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.                                                                          |
+| `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_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.
+
+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
+folder, or prints with `--out -`. With no package it describes the app at `--root` into the `.lib.par` at its root,
+keeping the designs there, so ask before running that in someone's project.
+
+## How to work
+
+1. **Get your bearings.** Call `get_app_state`. Note the designs, which one is selected (the person usually means that
+   one), the modes, and the components. Designs, states and nodes have ids; use them.
+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.
+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"`,
+   `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.
+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.
+
+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.
+
+## Rules
+
+- **Use the project's components.** `Components()` lists them; library components are namespaced, as in `nova/Button`,
+  and icons too, as in `lucide/Heart`. A name that isn't in the list renders as a placeholder. Don't rebuild a button,
+  card or input out of layouts and text when the project has one.
+- **Use the project's tokens.** Colours, radii, shadows, fonts, sizes, leading and tracking name a token, such as
+  `muted-foreground`, `radius-lg` or `text-sm`, without the `--`. Lengths are steps of the spacing scale: `4` is four
+  spacing units (1rem in a default Tailwind project). `GetTokens()` lists them. Never write a raw colour or pixel value.
+- **Prefer semantic colours** (`background`, `foreground`, `card`, `muted`, `muted-foreground`, `primary`, `border`,
+  `destructive`) over palette ones (`color-blue-500`). They change with the theme; palette colours don't.
+- **Layout is auto layout.** A `layout` node is a flex box (or a grid with `display: "grid"`); children fill, hug or
+  take a fixed length. Avoid absolute positioning unless something truly overlaps, such as a badge on an avatar.
+- **One design, every viewport.** Don't copy a screen for mobile. Patch it with `Responsive(node, "mobile", patch)`:
+  hide the sidebar, stack the columns, shrink the padding.
+- **Real content.** Write the words the screen would show: names, numbers, dates and messages that fit the product.
+  Lorem ipsum hides layout problems.
+- **Reuse what repeats.** When a row, card or list item appears more than twice, make it a component design with
+  `ExtractComponent`, so each copy is an instance with its own content.
+- **Leave the canvas tidy.** New designs go into empty space (`FindEmptySpace`); `Overlaps()` tells you if boards
+  collide.
+
+## 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`).

package/skills/document.md

@@ -0,0 +1,166 @@
+# Designs and nodes
+
+A project's designs live in `.par` files at its root, as JSON. You change them through `execute`, which validates every
+change, so you never edit the files by hand. This is the shape `GetDesign` and `Get` return and `Insert` takes.
+
+## 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.
+
+| 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).                                                 |
+| `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.                                         |
+| `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.                                         |
+
+## Nodes
+
+Every node has an `id` (given when it's inserted), and can have a `name`, `hidden`, `style` and `responsive`. Name the
+layouts that group things ("Header", "Stats", "Actions"): the layers panel, state changes and paths all read better.
+
+### `layout`
+
+A box that lays out its `children`: a flex box by default, or a grid. Most structure is layouts.
+
+```json
+{ "type": "layout", "name": "Actions", "style": { "direction": "row", "gap": 2, "justify": "end" }, "children": [] }
+```
+
+### `component`
+
+One of the project's components. `component` is a name from `Components()`; `props` are its props; `slots` hold child
+nodes, where `children` is what goes between its tags and any other slot becomes a prop that takes nodes.
+
+```json
+{
+  "type": "component",
+  "component": "Button",
+  "props": { "variant": "outline", "size": "sm" },
+  "slots": {
+    "children": [
+      { "type": "component", "component": "lucide/Download" },
+      { "type": "text", "text": "Export" }
+    ]
+  }
+}
+```
+
+Text that's only a component's label can be its `children` prop instead: `"props": { "children": "Export" }`.
+
+### `instance`
+
+A copy of one of the project's component designs. `design` is the component design's id, `args` give its params values
+(an option's id for a variant), and `state` picks which of its states this copy shows.
+
+```json
+{ "type": "instance", "design": "stat-card", "args": { "label": "Active users", "value": "1,284" } }
+```
+
+`overrides` holds what this copy changes inside the component, keyed by the inner node's id, or `nested/inner` for a
+node inside a nested instance. Each is a patch like a state's (`hidden`, `text`, `props`, `style`). Everything the copy
+doesn't override keeps following the component.
+
+```json
+{ "type": "instance", "design": "stat-card", "overrides": { "trend": { "hidden": true } } }
+```
+
+A state's patches can reach inside an instance the same way, keyed `instance/inner`, so one copy can change in one
+state.
+
+### `text`
+
+Words. `tag` is `p` (the default), `span`, `h1` to `h4` or `strong`, and sets what the text is, not how it looks; size
+and weight come from `style`.
+
+```json
+{ "type": "text", "tag": "h2", "text": "Recent activity", "style": { "size": "text-lg", "weight": 600 } }
+```
+
+### `image`
+
+A picture: `src` is a path the project serves (`/images/team.jpg`) or a URL; `alt` describes it, or is empty when it's
+decoration; `fit` is `cover` (the default), `contain` or `fill`; `credit` names its maker when a photo asks for it.
+
+## Style
+
+Every value comes from the project. Lengths are steps of the spacing scale or the name of a length token; colours and
+type name a token from `GetTokens()`, without the `--`.
+
+| Key                                              | Takes                                                                     |
+| ------------------------------------------------ | ------------------------------------------------------------------------- |
+| `display`                                        | `flex` (the default) or `grid`                                            |
+| `direction`                                      | `column` (the default) or `row`                                           |
+| `columns`, `rows`                                | A grid's column or row count; all the same size                           |
+| `gap`, `rowGap`                                  | A length                                                                  |
+| `padding`, `margin`                              | A length, `[vertical, horizontal]` or `[top, right, bottom, left]`        |
+| `align`                                          | Children across: `start`, `center`, `end`, `stretch`                      |
+| `justify`                                        | Children along: `start`, `center`, `end`, `between`, `around`, `evenly`   |
+| `wrap`                                           | `true` to wrap a row                                                      |
+| `width`, `height`                                | A length, `fill` (take the room the parent gives) or `hug` (fit content)  |
+| `minWidth`, `maxWidth`, `minHeight`, `maxHeight` | A length                                                                  |
+| `grow`                                           | `true` to fill along the parent's direction                               |
+| `self`                                           | This node across its parent, overriding the parent's `align`              |
+| `colSpan`, `rowSpan`                             | Grid cells to span                                                        |
+| `position`, `top`, `right`, `bottom`, `left`     | `absolute`, placed against the parent's edges by lengths                  |
+| `background`, `foreground`, `border`             | A colour token                                                            |
+| `borderWidth`                                    | Pixels: 0, 1, 2, 4 or 8                                                   |
+| `borderStyle`                                    | `solid`, `dashed` or `dotted`                                             |
+| `radius`, `shadow`                               | A radius or shadow token, such as `radius-lg` or `shadow-sm`              |
+| `opacity`                                        | Percent, 0 to 100                                                         |
+| `overflow`                                       | `visible`, `hidden` or `scroll`                                           |
+| `font`, `size`, `leading`, `tracking`            | A token, such as `font-mono`, `text-sm`, `leading-tight`, `tracking-wide` |
+| `weight`                                         | A number: 400, 500, 600, 700                                              |
+| `textAlign`                                      | `start`, `center`, `end` or `justify`                                     |
+| `transform`, `decoration`, `italic`              | `uppercase` and the like, `underline` or `line-through`, `true`           |
+| `lines`                                          | Lines of text before an ellipsis                                          |
+
+Type set on a layout applies to the text inside it. A component's own look comes from its props, so reach for a variant
+(`variant: "secondary"`) before styling a component from outside.
+
+## States
+
+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.
+
+## Responsive
+
+A node's `responsive` maps a viewport option's id (such as `tablet` or `mobile`) to a patch of the same four things,
+applied in every mode on that viewport:
+
+```json
+{ "name": "Sidebar", "type": "instance", "design": "app-sidebar", "responsive": { "mobile": { "hidden": true } } }
+```
+
+## Params and bindings
+
+Inside a component design, a node's `bind` takes its values from the component's params, so each instance shows its own:
+`bind.text` names a text param, `bind.props` maps a prop to a param, and `bind.visible` names a boolean param that shows
+or hides the node. `ExtractComponent` sets all of this up from the occurrences it replaces.
+
+```json
+{ "type": "text", "text": "Revenue", "bind": { "text": "label" } }
+```
+
+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.
+
+```json
+"params": {
+  "size": {
+    "type": "variant",
+    "default": "medium",
+    "options": [
+      { "id": "medium", "name": "Medium" },
+      { "id": "small", "name": "Small", "overrides": { "card": { "style": { "padding": 3 } } } }
+    ]
+  }
+}
+```

package/skills/execute.md

@@ -0,0 +1,276 @@
+# The `execute` tool
+
+`execute` runs a JavaScript snippet against a working copy of one tab's designs. The functions below are globals.
+`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".
+- `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).
+
+## API
+
+```ts
+// 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?, visit): any[]                         // walks nodes, collecting what visit returns
+Components(): string[]                           // the components designs can use
+Props(component, { all? }?): PropsInfo           // a component's props, from its source
+GetTokens({ category?, source?, search? }?): Token[]
+GetModes(): { settings, modes }                  // the project's modes, and each resolved
+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
+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
+Replace(path, node): string
+Move(path, parent, { index?, slot? }?): void     // within one design
+Copy(path, parent, { index?, slot?, name? }?): string
+Delete(path): void
+Responsive(path, viewport, patch | null): void   // a patch for one viewport, or null to remove it
+
+// States
+AddState(design, { name, changes? }): string     // changes keyed by node id or name
+UpdateState(design, state, { name?, changes? }): void
+DeleteState(design, state): void
+
+// Components
+FindRepeats(design): Repeat[]                    // parts that repeat with the same structure
+ExtractComponent(design, nodes, { name, params?, file? }): string
+
+// Modes and tokens
+SetModes(settings): void                         // replaces the project's modes
+SetTokens({ name: value | { theme: value } }): void
+
+// Checking
+Screenshot(design, { state?, mode?, scale? }?): number
+Measure(design, { state?, mode? }?): Layout
+Problems(design, { state?, mode? }?): Problem[]
+Accessibility(design, { state?, mode? }?): Finding[]
+
+// The canvas
+FindEmptySpace({ width, height, direction?, near?, padding? }): { x, y }
+Overlaps(design?): Overlap[]
+Print(...values): void
+```
+
+## Paths
+
+A design is named by its id or its name. A node is named by `design/node`, where `node` is the node's id or its name, or
+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.
+
+## 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.
+
+### 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.
+
+`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.
+
+```js
+// Every Button in the project, with where it is.
+Print(Get((node, at) => (node.type === "component" && node.component === "Button" ? at.path : undefined)))
+```
+
+### 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.
+
+### GetTokens
+
+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" })`.
+
+### Selection
+
+What the person has selected: the design's id, and the node and mode when they picked one. "This", "here" and "the
+selected one" usually mean it.
+
+## Designs
+
+### CreateDesign
+
+Makes a design and returns its id. Without `root` it starts as a page layout with padding, a gap and the background and
+foreground colours. Without `x` and `y` it goes into empty space. `kind: "component"` makes a component design, which
+screens place as instances; most component designs come from `ExtractComponent` instead, because that also gives them
+params.
+
+### 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.
+
+## Nodes
+
+### Insert
+
+Adds a node, with everything inside it, as the last child of `parent` or at `index`. Into a component node, it goes into
+the `children` slot unless `slot` names another. Every node gets a fresh id; don't pass ids. `parent` can be a design,
+meaning its root.
+
+```js
+const form = Insert("settings/Content", {
+  type: "layout",
+  name: "Profile form",
+  style: { gap: 4, maxWidth: 120 },
+  children: [
+    { type: "component", component: "Label", props: { htmlFor: "name", children: "Name" } },
+    { type: "component", component: "Input", props: { id: "name", defaultValue: "Avery Chen" } },
+    { type: "component", component: "Button", props: { children: "Save changes" }, style: { self: "start" } }
+  ]
+})
+```
+
+### 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.
+
+With `{ state: "loading" }` the change belongs to that state instead of the base design. A state can change only
+`hidden`, `text`, `props` and `style`.
+
+### Replace, Move, Copy and Delete
+
+`Replace` swaps a node for a new one in the same place and returns its id. `Move` reorders or reparents a node within
+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`.
+
+### Responsive
+
+Patches a node in one viewport: `Responsive("dashboard/Stats", "mobile", { style: { columns: 1 } })`. The viewport is a
+viewport option's id from the modes (such as `desktop`, `tablet` and `mobile`), not a mode's id. Patches take `hidden`,
+`text`, `props` and `style`, and merge with the viewport's earlier patch. `null` removes it.
+
+## States
+
+A state is a situation the whole design is in, like a story: loading, empty, error, signed out. It stores only what
+differs from the base. `changes` maps node ids or names to patches (`hidden`, `text`, `props`, `style`); `null` clears a
+node's patch. The first state is the base.
+
+```js
+AddState("team-members", {
+  name: "Empty",
+  changes: {
+    "Members table": { hidden: true },
+    "Empty state": { hidden: false },
+    seats: { props: { children: "1 of 10 seats used" } }
+  }
+})
+```
+
+Put the parts only some states show into the base design with `hidden: true`, then show them in those states. A text
+node's words are its `text`; a component's are usually its `children` prop.
+
+## Components
+
+### FindRepeats
+
+Returns parts of a design that repeat with the same structure: each has the root ids of its occurrences (`nodes`), a
+starting `name`, and the `params`, which are what differs between occurrences (texts, props, whether a node shows).
+
+### ExtractComponent
+
+Turns occurrences into a component design and replaces each with an instance that keeps its own content as args. Returns
+the component's id. `params` renames the params found, by the name they were given. It refuses when the result wouldn't
+render the same in every state and viewport.
+
+Look at what `FindRepeats` found before extracting, because the params' names are only a start:
+
+```js
+repeats = FindRepeats("team-members")
+Print(repeats)
+```
+
+Then, in the next snippet, extract with names that say what each param is:
+
+```js
+const [rows] = repeats
+ExtractComponent("team-members", rows.nodes, { name: "Member row", params: { [rows.params[0].name]: "name" } })
+```
+
+## Modes and tokens
+
+`SetModes(settings)` replaces the project's modes: take `GetModes().settings`, change it, and pass it back. Modes are
+shared by every design.
+
+`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
+one design. They're undone with the call's other changes.
+
+## Checking
+
+`Screenshot` renders frames offscreen at their real widths and returns how many it took; the images come back with the
+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.
+
+`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.
+
+## 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 })`.
+
+## Examples
+
+A new screen, checked in every state and mode:
+
+```js
+const id = CreateDesign({ name: "Billing" })
+Insert(id, { type: "text", tag: "h1", text: "Billing", style: { size: "text-2xl", weight: 600 } })
+Insert(id, {
+  type: "component",
+  component: "Card",
+  name: "Plan",
+  slots: {
+    children: [
+      {
+        type: "component",
+        component: "CardHeader",
+        slots: {
+          children: [
+            { type: "component", component: "CardTitle", props: { children: "Pro plan" } },
+            { type: "component", component: "CardDescription", props: { children: "$24 per seat, billed monthly" } }
+          ]
+        }
+      }
+    ]
+  }
+})
+await Screenshot(id, { state: "all", mode: "shown" })
+Print(await Problems(id, { state: "all", mode: "shown" }))
+```
+
+A loading state that swaps content for skeletons:
+
+```js
+Update("dashboard/Stats loading", { hidden: true })
+AddState("dashboard", { name: "Loading", changes: { Stats: { hidden: true }, "Stats loading": { hidden: false } } })
+```