From 9e0146f083b3e5d063aed30aa3b239aa4607bb7c Mon Sep 17 00:00:00 2001
From: Minsu Lee <amond@amond.net>
Date: Fri, 13 Nov 2026 12:32:30 +0900
Subject: [PATCH 1/2] feat(ui-sdk): add ui-sdk plugin

Adds the ui-sdk skill from vercel-labs/ui (installed via skills.sh) as a built-in plugin, with marketplace entry and relevance signal for @ui-sdk/* deps, generated Codex/Antigravity/Cursor manifests, release-please config, and README entry.
---
 .agents/plugins/marketplace.json              |  12 +
 .claude-plugin/marketplace.json               |  19 ++
 .cursor-plugin/marketplace.json               |   5 +
 .release-please-manifest.json                 |   3 +-
 README.md                                     |   6 +
 plugins/ui-sdk/.agents/skills/ui-sdk/SKILL.md |  56 ++++
 .../skills/ui-sdk/references/agent-ready.md   | 136 ++++++++++
 .../ui-sdk/references/build-interface.md      | 187 +++++++++++++
 .../ui-sdk/references/create-component.md     |  88 +++++++
 .../skills/ui-sdk/references/patterns.md      | 246 ++++++++++++++++++
 .../skills/ui-sdk/references/styles.md        |  66 +++++
 .../skills/ui-sdk/references/testing.md       | 172 ++++++++++++
 .../ui-sdk/references/web-components.md       |  78 ++++++
 plugins/ui-sdk/.claude-plugin/plugin.json     |  26 ++
 plugins/ui-sdk/.codex-plugin/plugin.json      |  40 +++
 plugins/ui-sdk/.cursor-plugin/plugin.json     |  31 +++
 plugins/ui-sdk/plugin.json                    |  26 ++
 plugins/ui-sdk/skills-lock.json               |  11 +
 release-please-config.json                    |  26 ++
 19 files changed, 1233 insertions(+), 1 deletion(-)
 create mode 100644 plugins/ui-sdk/.agents/skills/ui-sdk/SKILL.md
 create mode 100644 plugins/ui-sdk/.agents/skills/ui-sdk/references/agent-ready.md
 create mode 100644 plugins/ui-sdk/.agents/skills/ui-sdk/references/build-interface.md
 create mode 100644 plugins/ui-sdk/.agents/skills/ui-sdk/references/create-component.md
 create mode 100644 plugins/ui-sdk/.agents/skills/ui-sdk/references/patterns.md
 create mode 100644 plugins/ui-sdk/.agents/skills/ui-sdk/references/styles.md
 create mode 100644 plugins/ui-sdk/.agents/skills/ui-sdk/references/testing.md
 create mode 100644 plugins/ui-sdk/.agents/skills/ui-sdk/references/web-components.md
 create mode 100644 plugins/ui-sdk/.claude-plugin/plugin.json
 create mode 100644 plugins/ui-sdk/.codex-plugin/plugin.json
 create mode 100644 plugins/ui-sdk/.cursor-plugin/plugin.json
 create mode 100644 plugins/ui-sdk/plugin.json
 create mode 100644 plugins/ui-sdk/skills-lock.json

diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
index ccec2508..c9647365 100644
--- a/.agents/plugins/marketplace.json
+++ b/.agents/plugins/marketplace.json
@@ -1052,6 +1052,18 @@
       },
       "category": "Tooling"
     },
+    {
+      "name": "ui-sdk",
+      "source": {
+        "source": "local",
+        "path": "./plugins/ui-sdk"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "UI"
+    },
     {
       "name": "skill-optimizer",
       "source": {
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 31dc5d47..c06b0613 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1427,6 +1427,25 @@
       "tags": ["skills", "vercel"],
       "source": "./plugins/eve"
     },
+    {
+      "name": "ui-sdk",
+      "description": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/core behaviors, make interfaces agent-ready with createAgent and WebMCP, and test keyboard, focus, ARIA, SSR and RTL.",
+      "category": "ui",
+      "keywords": ["ui-sdk", "ui", "components", "accessibility", "react", "vue", "svelte", "solid", "web-components", "webmcp"],
+      "tags": ["skills", "vercel", "frontend"],
+      "source": "./plugins/ui-sdk",
+      "relevance": {
+        "topic": "ui-sdk",
+        "signals": {
+          "manifestDeps": [
+            {
+              "file": "[/\\\\]package\\.json$",
+              "pattern": "\"@ui-sdk/[a-z-]+\"\\s*:"
+            }
+          ]
+        }
+      }
+    },
     {
       "name": "skill-optimizer",
       "description": "Measure and improve how well a plugin's skills help agents solve real tasks. Runs activation and content evals, diagnoses gaps, fixes instructions, and re-runs until scores improve.",
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
index 1662329f..0478e2c6 100644
--- a/.cursor-plugin/marketplace.json
+++ b/.cursor-plugin/marketplace.json
@@ -359,6 +359,11 @@
       "source": "./plugins/eve",
       "description": "Build durable backend AI agents with the eve framework. Use when creating, editing, or debugging an eve project — agent instructions, skills, tools, connections, channels, sandboxes, subagents, schedules, or evals."
     },
+    {
+      "name": "ui-sdk",
+      "source": "./plugins/ui-sdk",
+      "description": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/core behaviors, make interfaces agent-ready with createAgent and WebMCP, and test keyboard, focus, ARIA, SSR and RTL."
+    },
     {
       "name": "skill-optimizer",
       "source": "./plugins/skill-optimizer",
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index 85502e82..85533c4a 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -75,5 +75,6 @@
   "plugins/orpc": "1.1.3",
   "plugins/deno": "1.1.2",
   "plugins/genkit": "1.1.3",
-  "plugins/evlog": "1.1.0"
+  "plugins/evlog": "1.1.0",
+  "plugins/ui-sdk": "1.0.0"
 }
diff --git a/README.md b/README.md
index 2aa5b156..1d2a74bc 100644
--- a/README.md
+++ b/README.md
@@ -439,6 +439,12 @@ Build durable backend AI agents with the eve framework. Use when creating, editi
 
 **Install:** `/plugin install eve@pleaseai` | **Source:** [plugins/eve](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/eve)
 
+#### ui-sdk
+
+Build interfaces with [ui-sdk](https://github.com/vercel-labs/ui) in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from `@ui-sdk/core` behaviors, make interfaces agent-ready with `createAgent` and WebMCP, and test keyboard, focus, ARIA, server rendering and right-to-left layout.
+
+**Install:** `/plugin install ui-sdk@pleaseai` | **Source:** [plugins/ui-sdk](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/ui-sdk)
+
 #### Skill Optimizer
 
 Measure and improve how well a plugin's skills help agents solve real tasks. Runs activation and content evals, diagnoses gaps, fixes instructions, and re-runs until scores improve.
diff --git a/plugins/ui-sdk/.agents/skills/ui-sdk/SKILL.md b/plugins/ui-sdk/.agents/skills/ui-sdk/SKILL.md
new file mode 100644
index 00000000..35009a16
--- /dev/null
+++ b/plugins/ui-sdk/.agents/skills/ui-sdk/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: ui-sdk
+description: Builds interfaces with ui-sdk in React, Vue, Svelte, Solid or web components. Covers choosing and composing its components, building a component or behavior it doesn't ship from @ui-sdk/core (like a stepper, splitter, transfer list or emoji picker), making the interface usable by agents through createAgent, agent tools and WebMCP, and testing keyboard, focus, ARIA, server rendering and right to left, including writing tests for an existing component. Use whenever a project has @ui-sdk/* installed or the user mentions ui-sdk.
+---
+
+# Build with ui-sdk
+
+ui-sdk is a library of UI behaviors: keyboard navigation, focus, selection, dismissal, popups, drag and drop and the ARIA they need. Its components are built from those behaviors and render no styles of their own, in React, Vue, Svelte, Solid and web components. `@ui-sdk/core/web.css` gives them an optional default look. When a component is missing, you build it from the same behaviors in `@ui-sdk/core`, and it gets the same keyboard, focus, server rendering and right to left support.
+
+## Read first
+
+The docs for the installed version ship in each package, as Markdown:
+
+- `node_modules/@ui-sdk/<framework>/docs/llms.txt` is the index. Read it first. `<framework>` is `react`, `vue`, `svelte`, `solid` or `web`.
+- Then read only the pages your task needs, like `docs/components/select.md`. Don't read the whole `docs/` folder; it's large.
+- An interface built from our components doesn't need `docs/core.md`. Only path 2 below does, and even then you search it by heading: it's over 300 KB. `docs/rendering.md` sits next to it in the same `docs/` folder.
+- Don't read compiled JavaScript in `dist/*.js`, even to debug. The docs and the `.d.ts` types are the API; when they don't answer, write a small test that tries it.
+
+The same docs are online at https://ui-sdk.dev/docs. Prefer the installed copy: it matches the version in the project.
+
+A page with no build step, like an Artifact, installs nothing: it loads `https://ui-sdk.dev/web.js` and `web.css` with two tags. Read https://ui-sdk.dev/web.md instead of `llms.txt`. It's the web components docs in one file, for that page, and [references/web-components.md](references/web-components.md#without-a-bundler) has the rest.
+
+Otherwise, if no `@ui-sdk` package is installed yet, install `@ui-sdk/core` and the framework's package with the project's package manager.
+
+## Pick your path
+
+1. **Build an interface from our components**, like a settings page, a form or a command palette: read [references/build-interface.md](references/build-interface.md).
+2. **Build a component or behavior ui-sdk doesn't ship**, or extend one of ours: read [references/create-component.md](references/create-component.md).
+
+Most interfaces only need path 1. When one part of it needs a component we don't have, follow path 2 for that part.
+
+Every path ends the same way:
+
+3. **Make it agent-ready**: [references/agent-ready.md](references/agent-ready.md).
+4. **Test it**: [references/testing.md](references/testing.md).
+
+## Rules for every path
+
+- **Import from entries.** Each component has its own entry, like `@ui-sdk/react/select`. There's no root import from a framework package. Never import `@ui-sdk/core/internal/*`.
+- **One shape everywhere.** A root and its parts, nested as the component page's Composition shows. Change a part's element with `render`, never an `as` prop.
+- **Default or controlled.** `defaultValue` to start, or `value` with `onValueChange(value, details)` to control it (each framework's idiom: `v-model` in Vue, `bind:value` in Svelte, properties and events in web components). `details` has `reason`, `source` and `cancel()`.
+- **Name every control.** Use the component's label part (`FieldLabel`, `SelectLabel`, `DialogTitle`), or `aria-label` when there's no visible text. People using screen readers and agents both find controls by name.
+- **Style from state.** Target `data-slot` and state attributes like `data-open` or `data-pressed`, and the CSS variables each component lists. Never inline styles for state, and never generated ids. When the app uses `web.css`, read [references/styles.md](references/styles.md) first: it draws icons and sets sizes you can't see in the markup.
+- **Declare the ui-sdk layer.** Put `@layer ui-sdk;` at the top of the global stylesheet, above `@import "tailwindcss"` if there is one.
+- **Check color.** Text needs 4.5:1 against what's behind it, and control edges, focus rings and state fills 3:1. jsdom can't see color, so check it in a real browser.
+- **Key lists by value or id**, never by index.
+- **Right to left needs no provider.** Components read the direction from the page.
+- **Comments are rare.** Write one only when a reader would get the code wrong without it, like a browser quirk or a trade-off, in one or two lines. Never comment what the code does, what a value is, or which section starts here, and no JSDoc blocks on app code.
+- **Don't hand-roll what we ship.** Before you write any `role=` attribute, look for the component in the table in [references/build-interface.md](references/build-interface.md). A `div` with `role="listbox"`, `"menu"`, `"dialog"`, `"tablist"`, `"separator"`, `"switch"`, `"slider"`, `"radiogroup"`, `"toolbar"` or `"tree"` next to an installed ui-sdk package is almost always a bug.
+
+## When you're done
+
+1. **Typecheck.** If the root `tsconfig.json` has `"files": []` and `references`, `npx tsc --noEmit` checks nothing: run `npx tsc -b` or `npx tsc --noEmit -p <app config>`. For Svelte, run `svelte-check`; for Vue, `vue-tsc`.
+2. **Write and run tests** (see testing.md). Every task gets tests, and every interface gets at least the agent test from agent-ready.md. If a test finds a bug in code you were asked only to test, mark it `test.fails` (or `it.fails`) with a one-line reason, report the bug, and leave the suite green.
+3. **Read every comment in your diff.** Delete it unless it names a browser quirk, an APG rule or a trade-off, and cut what's left to two lines. Turn JSDoc on app code into a plain comment or delete it. Never tell the reader to replace something.
+4. **Report** each command you ran with its exit code, anything you couldn't check, and anything the docs or types got wrong or left out.
diff --git a/plugins/ui-sdk/.agents/skills/ui-sdk/references/agent-ready.md b/plugins/ui-sdk/.agents/skills/ui-sdk/references/agent-ready.md
new file mode 100644
index 00000000..2ab89c09
--- /dev/null
+++ b/plugins/ui-sdk/.agents/skills/ui-sdk/references/agent-ready.md
@@ -0,0 +1,136 @@
+# Make it agent-ready
+
+An app built with ui-sdk can let an agent read its components and call their actions directly, through `createAgent`, instead of clicking through the page. An interface is agent-ready when an agent can find every control by name, call what it needs, and the app sees each change as the agent's and can refuse it.
+
+The full docs are the Agents pages: `docs/agents.md` in each package, or https://ui-sdk.dev/docs/agents.
+
+## The checklist
+
+1. **Every control has a name.** The bridge's `label` is the accessible name: `FieldLabel`, the component's label part, or `aria-label`. Labels should be unique where they sit, because a step finds its component by label (`{ ref: "Project name", … }`). Two "Name" fields in two sections are fine only if a step can still tell them apart by ref or row text.
+   - A label matches every label that holds its words, and an exact match doesn't win, since labels are page text other people can write. "Tip" and "Custom tip" collide, and so do a "Water the plants" button and a "Done today: Water the plants" checkbox. Give each control in a row a verb of its own ("Open Water the plants"), so none is the bare title.
+   - Items and tabs are named by their visible text. `aria-label` on an item is ignored.
+   - A part like a password's Show toggle or a number input's step buttons belongs to its component's entry, and doesn't need a name unique on the page.
+   - Components that only support another still show up. Give a shared Tooltip its own `aria-label`, an Avatar `role="img"` with `aria-label`, and an Accordion with more than one section `aria-label` on its root. Put `aria-hidden="true"` on a decorative one, which hides it from agents too, and `data-agent-hidden` on a toast region (it drops its label while it's empty).
+   - A Dialog with several triggers has no name while it's closed: put `keepMounted` on its content, so its title names it. A Menu can't take a name of its own, so don't share one Menu between rows: give each row its own Menu, with a trigger named for its row, like `aria-label="Actions for Jane Doe"`. Labels inside a dialog should differ from the page's too: the bridge still sees the page behind an open modal.
+2. **Every control an agent should use is one of our parts.** `snapshot()` lists only ui-sdk components. These are invisible, so an agent can't fill or press them:
+   - a plain `<button>`: use `Button` (`<ui-button><button>…</button></ui-button>` in web components), including submit buttons and a wizard's Back and Continue;
+   - a bare `<input>`, `<textarea>` or `<select>`, and `FieldControl`: use `Input`, `Textarea`, `NumberInput` or `Select` inside a `Field`. In web components that's `<ui-field>` with `<ui-input><input /></ui-input>` inside, never a bare `<input>`;
+   - a custom primitive's step it can't take, like a linear stepper's next step: make the action that completes it (the Continue button) one of ours too.
+3. **State flows through change callbacks.** Keep app state in sync through `onValueChange` (and the other `on<Key>Change` callbacks), not through DOM listeners. Agent changes call the component's API, not keyboard or pointer handlers, so checks in `onKeyDown` or `onClick` never see them. In the callback, `details.source === "agent"` tells an agent's change apart, and `details.cancel()` refuses it.
+   - What a popup shows comes from its `payload` or app state, not a trigger's `onClick`: an agent can open it with `setOpen`, which runs no click. When a popup has several triggers, a `press` with one's text, like "Edit Beta", clicks it.
+   - `minLength` doesn't stop a value an agent sets, since browsers only check it while a person types. Use `pattern=".{8,}"` or your own validation.
+4. **Mark what needs a person.** Three attributes, and only these three:
+   - `data-agent-confirm="<what it does>"` on anything an agent must not do alone, like delete, pay or send. It covers the element and everything inside it. Write the sentence for the person who'll be asked, "Deletes the project and all its files", from app state, not from a dialog's `payload`, which is gone while the dialog is closed. For a confirm dialog, put it on the button that confirms, `<AlertDialogClose value="confirm">`, not on the trigger (opening the dialog is harmless) or the content (that gates Cancel too). Give that button text that isn't part of the trigger's, like "Delete forever" for a "Delete project" trigger: a press looks among the buttons already on the page first, so "Delete" would match the trigger. The same goes for a menu item and the buttons inside its context menu's area.
+   - `data-agent-secret` on a field whose value an agent may fill but never read. Password, card and one-time-code fields are already secret.
+   - `data-agent-hidden` on a region an agent shouldn't see at all, like recovery codes.
+5. **Your own primitives say what they do.** Every `definePrimitive` ends with an `agent` key:
+
+   ```ts
+   agent: { actions: ["rate"] },
+   ```
+
+   | Key                         | Use it when                                                                                                                         |
+   | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+   | `actions`                   | Always. The api methods an agent may call. Without it, only methods named like `setValue`, `open`, `toggle` or `clear` are offered. |
+   | `closed: true`              | The value is always one of its items, like a size picker. A step that names another item is refused with the real ones.             |
+   | `items: (api) => …`         | The items aren't in the state's `items`. Return `{ value, label }` objects.                                                         |
+   | `reveals: true`             | Closed items hide other components, like tabs or an accordion.                                                                      |
+   | `shown: (state) => boolean` | It only matters sometimes, like a field wrapper while it has errors.                                                                |
+   | `secret: true`              | Its value must never be read, like a PIN.                                                                                           |
+
+## Connect the bridge
+
+Create the bridge once, in the browser, from the same package as the components:
+
+| Framework      | Import                                               |
+| -------------- | ---------------------------------------------------- |
+| React          | `import { createAgent } from "@ui-sdk/react/agent"`  |
+| Vue            | `import { createAgent } from "@ui-sdk/vue/agent"`    |
+| Svelte         | `import { createAgent } from "@ui-sdk/svelte/agent"` |
+| Solid          | `import { createAgent } from "@ui-sdk/solid/agent"`  |
+| Web components | `import { createAgent } from "@ui-sdk/web/agent"`    |
+
+```ts
+import { agentTools, createAgent, registerTools } from "@ui-sdk/react/agent"
+
+const agent = createAgent({
+  allow: (step, { signal }) =>
+    step.confirm ? askThePerson(step.confirm, { signal }) : true,
+})
+
+export { agent }
+```
+
+- `agent.snapshot()` lists the components, their state and their `actions`. `agent.act({ steps })` runs steps in order. `agent.query({ text, within, kind })` finds components and list items.
+- **Your own model:** `agentTools` has the three tools' names, descriptions and JSON Schemas. Route each tool call to the matching method on `agent` and return its result.
+- **A browser agent (WebMCP):** `const unregister = registerTools(agent, { allow })`. It does nothing in a browser without `document.modelContext`. `allow` is required here, since you didn't write that agent. Ask the person in one place: when the bridge's own `allow` already asks, as above, pass `allow: () => true` here, or every marked step asks twice.
+- `allow` returns `true`, `false`, or a `Promise<boolean>` for your own confirmation UI. Without it, steps on `data-agent-confirm` fail with "Needs a person".
+- In Next.js and other server rendering setups, create the bridge in client code only, like a `"use client"` module imported by a client component.
+
+## Prove it with a test
+
+Write this test for every interface you build. It runs in jsdom with the framework's testing library, after the [jsdom stubs](testing.md#jsdom), since a Select opens to resolve an item by its label. This is React; the other frameworks render the same way their own tests do:
+
+```tsx
+import { render, screen } from "@testing-library/react"
+import { createAgent } from "@ui-sdk/react/agent"
+import { expect, test } from "vitest"
+import { ProjectSettings } from "./project-settings"
+
+test("an agent can find and change every setting", async () => {
+  const agent = createAgent()
+  render(<ProjectSettings />)
+
+  const components = agent
+    .snapshot()
+    .filter((entry) => !entry.offPage && entry.component !== "more")
+  for (const entry of components) {
+    expect(
+      entry.label,
+      `${entry.component} ${entry.ref} has no name`
+    ).toBeTruthy()
+  }
+  const labels = components.map((entry) => entry.label)
+  for (const label of ["Project name", "Visibility", "Weekly digest"]) {
+    expect(labels, `${label} is missing from the snapshot`).toContain(label)
+  }
+
+  const result = await agent.act({
+    steps: [
+      { ref: "Project name", action: "setValue", args: ["Atlas"] },
+      { ref: "Visibility", action: "setValue", args: ["Internal"] },
+    ],
+  })
+  expect(result.ok, result.error?.message).toBe(true)
+  expect(screen.getByLabelText<HTMLInputElement>("Project name").value).toBe(
+    "Atlas"
+  )
+})
+```
+
+- The entry with `component: "more"` comes last when the page has more than 100 components, and says how many `query` can find.
+- Create one bridge per test file: it has no `destroy`, and it remembers components earlier tests removed as `offPage`. Unmount between tests: with Vitest, Testing Library only cleans up when `globals: true` is set, so otherwise add `afterEach(cleanup)`.
+- Don't filter entries out of the label check. An unnamed entry is a control an agent can't find: name it or hide it.
+- List every control the task names in the `labels` check, so a control the bridge can't see fails the test. Add one `act` step for every control the task names, using the words a person would use. If a step fails, its `error.message` says why, like an ambiguous label with each match's ref.
+- For a `data-agent-confirm` control, give the file's one bridge an `allow` you can flip, and assert the step is refused, then runs:
+
+  ```ts
+  let approve = false
+  const agent = createAgent({ allow: (step) => !step.confirm || approve })
+  const remove = {
+    steps: [
+      { ref: "Delete project", action: "press", args: ["Delete forever"] },
+    ],
+  }
+
+  expect((await agent.act(remove)).ok).toBe(false)
+  approve = true
+  expect((await agent.act(remove)).ok).toBe(true)
+  ```
+
+- A refused press closes the dialog it opened before `act` returns.
+- `press` with a button's text opens a closed dialog or menu to find it, and `press` with no text opens it through its trigger. Once a dialog is open, its label is its title, not the trigger's text.
+- `act` can return `ok: true` while a change callback cancelled a value. Check `result.values` or the DOM, not only `ok`.
+- **An agent needs to find the choices an action takes.** The snapshot lists a component's `items` with it: the item and tab parts on the page, named by their text, or else its data when there are 10 or fewer. Data comes from the state's `items`, or from `agent.items` for any action, like a stepper's `goTo`. Longer lists come back from `query({ within: "<label>" })`. In the agent test, take the value from `snapshot()` or `query`, not from your own data. `query` resolves to a list of components or `{ error }`, so check which before you destructure it.
+
+Also look at the snapshot once by hand (`console.log(JSON.stringify(agent.snapshot(), null, 2))`): every entry should have a label a person would recognize, the actions you expect, and no `"actions": []` on a custom primitive that should do something.
diff --git a/plugins/ui-sdk/.agents/skills/ui-sdk/references/build-interface.md b/plugins/ui-sdk/.agents/skills/ui-sdk/references/build-interface.md
new file mode 100644
index 00000000..e3fab99a
--- /dev/null
+++ b/plugins/ui-sdk/.agents/skills/ui-sdk/references/build-interface.md
@@ -0,0 +1,187 @@
+# Build an interface from ui-sdk components
+
+## 1. Find the components
+
+Read `node_modules/@ui-sdk/<framework>/docs/llms.txt` for the list, or https://ui-sdk.dev/web.md on a page with no build step, then pick from this table. Read each picked component's page, `docs/components/<name>.md` (the page `web.md` links), before writing it: its Composition shows the parts and how they nest, and its API lists props, state attributes and change reasons.
+
+| The person needs to                                  | Use                                                                      |
+| ---------------------------------------------------- | ------------------------------------------------------------------------ |
+| Run an action                                        | Button                                                                   |
+| Turn a setting on or off                             | Switch                                                                   |
+| Keep a button pressed, or a group of pressed buttons | Toggle                                                                   |
+| Choose one or more independent options               | Checkbox                                                                 |
+| Choose one of a few options, all visible             | Radio, or Segmented Control for a compact row                            |
+| Choose one or several from a popup list              | Select                                                                   |
+| Choose from an always-visible list                   | Listbox                                                                  |
+| Search a list and choose one or several              | Combobox                                                                 |
+| Type free text with suggestions                      | Autocomplete                                                             |
+| Search and run commands                              | Command                                                                  |
+| Mention or tag with @, / or # while typing           | Trigger Menu                                                             |
+| Mix text with tokens for people, files or tags       | Token Input                                                              |
+| Enter text                                           | Input, or Textarea for several lines                                     |
+| Enter a number                                       | Number Input (for money, `step={0.01}`: a step of 1 rounds the cents)    |
+| Enter a password                                     | Password Input                                                           |
+| Enter a one-time code                                | OTP Input                                                                |
+| Enter a date                                         | Date Input, or Date Picker with a calendar                               |
+| Pick dates from a month grid                         | Calendar                                                                 |
+| Enter a time                                         | Time Input                                                               |
+| Pick a number or range by dragging                   | Slider                                                                   |
+| Pick a score                                         | Rating                                                                   |
+| Pick a color                                         | Color Picker                                                             |
+| Choose, drop or paste files                          | File Input                                                               |
+| Crop an image                                        | Image Cropper                                                            |
+| Label a control, with a description and errors       | Field, with Label                                                        |
+| Confirm before an action                             | Alert Dialog (`AlertDialogClose value="confirm"` is the agreeing answer) |
+| Do a focused task over the page                      | Dialog, or Drawer from an edge                                           |
+| Edit or explore something beside its trigger         | Popover                                                                  |
+| Choose actions from a button or a right click        | Menu                                                                     |
+| An application menu bar                              | Menubar                                                                  |
+| Group buttons and toggles with one tab stop          | Toolbar                                                                  |
+| Name a control or add a short hint                   | Tooltip                                                                  |
+| Preview a link                                       | Hover Card                                                               |
+| Site navigation with panels                          | Navigation Menu                                                          |
+| Switch between panels                                | Tabs                                                                     |
+| Show and hide sections                               | Accordion, or Collapsible for one                                        |
+| Browse a hierarchy                                   | Tree                                                                     |
+| Pick from a grid, like seats                         | Your own component on `createGridFocus`                                  |
+| Drag to reorder a list, or cards between columns     | Your own component on `createReorder` or `createTransfer`                |
+| Show a trace or request timings on a time axis       | Waterfall                                                                |
+| Page through results                                 | Pagination                                                               |
+| Page through slides                                  | Carousel                                                                 |
+| Resizable panels                                     | Resizable                                                                |
+| Styled scrolling                                     | Scroll Area                                                              |
+| Notifications                                        | Toast                                                                    |
+| Progress of a task                                   | Progress                                                                 |
+| A measurement in a range                             | Meter                                                                    |
+| A user's image with a fallback                       | Avatar                                                                   |
+| Divide content                                       | Separator                                                                |
+
+If nothing fits, build that one piece with [create-component.md](create-component.md), from the behaviors in the Core docs. Don't hand-roll it in markup.
+
+## 2. Put the parts together
+
+- Nest the parts as the page's Composition shows. Roots like `Popover` share state without rendering an element; others like `Tabs` render one.
+- Use `render` to change a part's element, like a menu item that's a link. A custom component passed to `render` must forward its props and ref.
+- For content that depends on state, pass a function as `children` (React, Solid), or use the slot props the page shows.
+- Options from data: most list components take `items`, as strings or `{ value, label }` objects.
+- To change a component from outside its tree, use its controller (see the Controllers page).
+
+## 3. State
+
+Use the default prop to start (`defaultValue`, `defaultOpen`, `defaultChecked`, `defaultPressed`). Control it only when the app needs the value:
+
+| Framework      | Controlled value                                     | Change callback                         |
+| -------------- | ---------------------------------------------------- | --------------------------------------- |
+| React          | `value={value} onValueChange={setValue}`             | `onValueChange(value, details)`         |
+| Vue            | `v-model="value"`, or `v-model:open` for another key | `@value-change="(value, details) => …"` |
+| Svelte         | `bind:value` on `$state`                             | `onValueChange(value, details)`         |
+| Solid          | `value={value()} onValueChange={setValue}`           | `onValueChange(value, details)`         |
+| Web components | `element.value = …`                                  | `valuechange` event, `event.detail`     |
+
+`details.reason` says what asked for the change (`outside-press`, `escape-key`, `item-press`…), `details.source` says how (`keyboard`, `mouse`, `agent`…), and `details.cancel()` refuses it. In web components, call `event.preventDefault()` instead. Select, Tabs and Radio report `null` when nothing is selected; multiple Select and Combobox use arrays.
+
+## 4. Forms
+
+- Give a control a `name` and it submits with its form, Select and Combobox included.
+- Wrap controls in `Field` with `FieldLabel`, `FieldDescription` and `FieldError`. For text, put an `Input` (or `Textarea`, `NumberInput`, `PasswordInput`) inside the Field. Don't use `FieldControl` for text: it's a plain native input, so agents can't see or change it. A Checkbox, Switch, Radio Group or Select inside a Field uses the Field's label the same way; the Field page shows how each connects.
+- `required`, `disabled`, `readOnly` and `form` work like native ones. For a server error, pass `invalid` to the Field and show the message in `FieldError`.
+
+## 5. Styles
+
+- With `web.css`, read [styles.md](styles.md) first: its tokens, the icons it draws and the sizes it sets.
+- Every part has `data-slot`: the component's name on a root (`switch`), `<component>-<part>` on a part (`switch-thumb`). Read it from the rendered DOM before you write a selector, since a few differ. State shows as attributes like `data-open`, `data-pressed`, `data-disabled`, `data-side="top"`. Each component page lists its attributes and CSS variables.
+- Tailwind: `data-pressed:bg-neutral-100`. CSS: `[data-slot="select-trigger"][data-open]`.
+- Popups get `data-starting-style` before they enter and `data-ending-style` while they exit, and stay mounted until the exit finishes. Put exit styles on `data-ending-style`.
+- Popups expose `--anchor-width`, `--available-height` and `--transform-origin`.
+- `@layer ui-sdk;` goes at the top of the global stylesheet so your styles win.
+
+## 6. Framework rules
+
+**React.** Components work in server components; their modules already say `"use client"`. Your own file needs `"use client"` when it uses state, effects or event handlers, or calls `createParts`.
+
+**Vue.** Props and events are kebab-case in templates (`default-value`, `@open-change`). Use `v-model` for the main value.
+
+**Svelte.** Use `bind:` for values the parent keeps. Share state between components through `setContext` and `getContext`, created in a parent. Never put `$state` at module level: on the server it's shared across every request. Type props with an `interface Props` above `let { ... }: Props = $props()`, not an inline object type. On Svelte 5.56 or later, declare a value inside a block with a declaration tag, `{const label = $derived(labelOf(id))}`, not `{@const}`.
+
+**Solid.** Keep reads reactive: read signals and props in JSX or a getter, never save their value in a variable first. `@ui-sdk/solid` needs Solid 2. With Vite, add `optimizeDeps: { exclude: ["@ui-sdk/core"] }` to the config, so the app and `@ui-sdk/solid` share one copy of the core in development.
+
+**Web components.** `import "@ui-sdk/web/<name>"` defines its elements, like `<ui-select>`. Many parts wrap a native element you write, like `<ui-toggle><button>Bold</button></ui-toggle>`. A text field is `<ui-field>` with `<ui-field-label>` and `<ui-input><input /></ui-input>`; a button is `<ui-button><button>Save</button></ui-button>`. Never leave a bare `<input>` or `<button>` where an agent or a Field should see it. Read and set state through properties after the element upgrades (`await customElements.whenDefined("ui-select")`). Change events are lowercase (`valuechange`, `openchange`) and don't bubble: listen on the element, or with `{ capture: true }` on an ancestor. [web-components.md](web-components.md) covers tag names and required inner markup.
+
+## 7. Example
+
+A settings form in React:
+
+```tsx
+"use client"
+
+import {
+  AlertDialog,
+  AlertDialogClose,
+  AlertDialogContent,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@ui-sdk/react/alert-dialog"
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { Input } from "@ui-sdk/react/input"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@ui-sdk/react/select"
+import { Switch, SwitchThumb } from "@ui-sdk/react/switch"
+
+function ProjectSettings() {
+  return (
+    <>
+      <form>
+        <Field name="name">
+          <FieldLabel>Project name</FieldLabel>
+          <Input defaultValue="Apollo" required />
+        </Field>
+        <Field>
+          <FieldLabel>Visibility</FieldLabel>
+          <Select name="visibility" defaultValue="private">
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="private">Private</SelectItem>
+              <SelectItem value="internal">Internal</SelectItem>
+              <SelectItem value="public">Public</SelectItem>
+            </SelectContent>
+          </Select>
+        </Field>
+        <Field>
+          <Switch name="digest" defaultChecked>
+            <SwitchThumb />
+          </Switch>
+          <FieldLabel>Weekly digest</FieldLabel>
+        </Field>
+      </form>
+      <AlertDialog>
+        <AlertDialogTrigger>Delete project</AlertDialogTrigger>
+        <AlertDialogContent>
+          <AlertDialogTitle>Delete Apollo?</AlertDialogTitle>
+          <AlertDialogClose>Cancel</AlertDialogClose>
+          <AlertDialogClose
+            value="confirm"
+            data-agent-confirm="Deletes the project and all its data"
+          >
+            Delete forever
+          </AlertDialogClose>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  )
+}
+
+export { ProjectSettings }
+```
+
+Check each part name against the component pages; they're the source of truth.
+
+## 8. Test it
+
+Every interface gets tests, and at least the agent test from [agent-ready.md](agent-ready.md#prove-it-with-a-test). Follow [testing.md](testing.md) for the rest.
diff --git a/plugins/ui-sdk/.agents/skills/ui-sdk/references/create-component.md b/plugins/ui-sdk/.agents/skills/ui-sdk/references/create-component.md
new file mode 100644
index 00000000..b2f668aa
--- /dev/null
+++ b/plugins/ui-sdk/.agents/skills/ui-sdk/references/create-component.md
@@ -0,0 +1,88 @@
+# Build a component from @ui-sdk/core
+
+ui-sdk ships its behavior layer as public API. A component it doesn't have is one primitive, written once with `definePrimitive`, and one small file per framework that renders it. It gets the same keyboard handling, focus, server rendering and right to left layout as ui-sdk's own components.
+
+## Read first
+
+1. **The Core docs.** Every package ships them in `docs/`: `docs/core.md` is the whole Core section in one file, the same in every package, since no framework changes it. Each framework's package adds `docs/rendering.md`, how its adapter renders a primitive, and `docs/components/<name>.md` and `docs/utilities/<name>.md` (React's are `docs/hooks/<name>.md`) for the rest. Read `docs/core.md` and `docs/rendering.md` from the package of the framework you render in, like `node_modules/@ui-sdk/react/docs/`. In `core.md`, read the overview, "Build a component" (a star rating, the template to copy), "Popups and layers" under Behaviors if anything opens, and the Behaviors page for each one you use. Search it by heading rather than reading it top to bottom. For another framework, see [Other frameworks](#other-frameworks).
+2. **The types.** Every export has JSDoc in `node_modules/@ui-sdk/core/dist/**/*.d.ts` and in each framework's `.d.ts`. A component entry's types point into its folder, like `dist/components/input/input.d.ts`. Read them there. Those JSDoc blocks document the library; your primitive gets none.
+3. **What ui-sdk already has.** List the entries in `node_modules/@ui-sdk/<framework>/package.json`. If one covers part of what you're building, compose it (see [Compose ours](#compose-ours)) rather than rewriting its behavior. If the user named the blocks to use, build from those blocks.
+
+Don't read compiled JavaScript in `dist/*.js`. When the docs and types don't say how something of ours behaves, probe it instead (below), and mention the missing docs in your report.
+
+### Probe what the docs don't say
+
+Write a throwaway test that renders our component in jsdom, fires events, and logs the DOM and the callbacks' arguments. Run it with `--silent=false` to see the logs, then delete it. This is how to learn, for example, whether a part hides when it's empty, which reason a change reports, where focus goes, or which tag names a web components entry defines. Two things every probe needs:
+
+- **Wait a tick after mounting.** Some state, like an input group's `filled`, arrives after mount: `await act(() => new Promise((r) => setTimeout(r, 0)))`.
+- **Stub what jsdom lacks before anything opens:** see [testing.md](testing.md#jsdom).
+
+## Steps
+
+### 1. Write the spec before any code
+
+Pick the WAI-ARIA pattern from the Authoring Practices (https://www.w3.org/WAI/ARIA/apg/patterns/) and write down its roles, states and keys. Then decide each of these in writing, since they're where components go wrong:
+
+- **Focus on open and on Tab.** Where does focus land when the component opens or is tabbed into? Is the group one tab stop?
+- **Selection and focus.** Does selection follow focus (radio group, single-select listbox), or do arrows only move focus and Space selects (multi-select listbox, data grid)?
+- **Escape.** Who owns it? Inside a popup, the popup closes on it. A field that clears on Escape should only claim it when there's something to clear.
+- **Parts that leave.** When the focused part is removed or moves out, where does focus go? Use `createFocusRecovery`.
+- **Pick the pattern.** [patterns.md](patterns.md) has the roles for common shapes: a set of choices in two dimensions is a `grid`, a stepper is buttons with `aria-current="step"`.
+- **Declare it on the slots.** Each part's role goes on its slot (`role: "option"`), never in `attrs`. TypeScript then requires what the role needs: `focus` for roles that take it, `press` for roles that activate, `keys` with an `on.keydown` for roles that move with keys, or `{ none: "why" }` when another element does it. Its `attrs` returns the role's required states, like `aria-checked`, and only the ARIA the role takes. Don't cast past these errors; set `globalThis.__UI_SDK_STRICT__ = true` in tests so development warnings fail them (declare it first: `declare global { var __UI_SDK_STRICT__: boolean | undefined }`).
+- **Controls that stop applying.** A button that can't act right now should be `aria-disabled`, not `disabled`, if it may hold focus at the time. `disabled` drops focus to the page.
+- **Keys with no APG rule.** Like Enter to move items between lists. Pick one, and say which in your report.
+- **What an agent may call.** Which api methods are actions a person takes, like `rate` or `moveToTarget`? They go in `agent.actions` (step 2).
+
+### 2. Write the primitive in `<name>.ts`
+
+- **Options:** controlled keys as `<key>`, `default<Key>` and `on<Key>Change(value, details: ChangeDetails<Reason>)`.
+- **Schema:** `options` names every option with its kind, and each slot's `props` every prop: `"string"`, `"number"`, `"boolean"`, `"list"`, `"value"` (any other value), `"callback"`, `"action"` (a callback whose return value counts, like a Promise), `"id"` (made when left out), `"key"` (a list item's value of any type, which keys the part and reaches nested parts as that key), or `{ kind, from: "item" }` for a prop a nested part takes from its parent, with `required: true` when it must sit inside it. Renderers read it to tell the primitive's props from the element's. TypeScript checks it names every key.
+- **State:** `state` reads the default. `sync` maps controlled options onto state, or they're silently ignored. Copy any option a part renders into state.
+- **Changes:** `api` builds `change` with `createChange(context)` and returns the api. Every change a user sees goes through `change` with a reason. Internal state, like a selection that starts over, can use `store.set`.
+- **Reasons:** use the shared vocabulary (`ReasonVocabulary` in `@ui-sdk/core`) when one fits. When none does, like "select all" or "move to the other list", declare your own in the `on<Key>Change` type.
+- **Slots:** `attrs` for ARIA and `data-*` (pure, server safe), `press` for activation, `on` for other events, `bind` for anything that touches the DOM (return a cleanup).
+- **`press` hears only clicks on parts that aren't buttons.** For a `div` or `td` part, handle Space and Enter in `on.keydown`.
+- **Every element gets its `data-slot` from a slot.** The adapter never sets one directly. Wrappers, like a row of buttons, get a slot of their own.
+- **Agents:** end the definition with `agent: { actions: [...] }`, the api methods an agent may call. Keep it after `slots`. Give the root a name, with `aria-label` or a label part: the bridge names the component after it. [agent-ready.md](agent-ready.md) covers `closed`, `items`, `reveals`, `shown` and `secret`.
+
+### 3. Use the blocks, don't rewrite them
+
+`createRovingFocus` for one tab stop and arrow keys (`move` for grids and trees), `createListbox` for a highlight that moves through options and filters them as someone types (a search box over a list, a picker of your own), `createGridFocus` for cells by row and column, `createCellRange` for a spreadsheet's block of cells with `cellsToText` and `textToCells` to copy and paste it, `createSelection`, `createTypeahead`, `createInputHistory` for ArrowUp and ArrowDown through earlier messages in a chat box or a command line, `createFocusRecovery`, `bindPanel`, `announce` for screen reader messages, `createReorder` for reordering by drag and keyboard, `bindScrollPicker` for a listbox you scroll to pick from, like a time wheel or a strip of pages, with `--picker-offset` on each option to draw it in CSS, `bindDrag` for a drag of your own, `createPopup` with `popupState`, `popupTrigger` and `popupContent` for anything that opens, `elements`, `selects`, `isRTL`, `idPart`, `@ui-sdk/core/text-match`, `@ui-sdk/core/date`, `createTreeCollection`. The Behaviors page's "Which behavior for which job" tables map jobs to them, with a demo for each. [patterns.md](patterns.md) has tested snippets for what the blocks leave to you: grid `move`, derived state, internal selection, a `createFocusRecovery` fallback, and more.
+
+### A new behavior
+
+When the same interaction repeats across several components, like a "press and hold to repeat" or a "drag to select a range", write it once as a behavior shaped like ours instead of copying it into each primitive: a `create<Thing>(context, options)` function that returns what the api needs, and binds to elements through a slot's `bind` with a cleanup. Read two of ours on the Behaviors pages first and copy their shape: options in, an object of methods and slot pieces out, no framework code. Give it its own tests with `mount`.
+
+### 4. Render it
+
+`createParts(primitive, { root: "div", item: "div" })` from `@ui-sdk/<framework>/primitive` returns `Root` and one part per tagged slot, typed from the primitive (`@ui-sdk/web` has `createParts`). Write your own part with `usePart` only when it renders something of its own, like a list from data, and a root with `usePrimitive`. The adapter only renders: no key handlers, focus moves, ARIA or `data-slot` in it. In React, the file that calls `createParts` starts with `"use client"`.
+
+### 5. Make it agent-ready and test it
+
+Follow [agent-ready.md](agent-ready.md), then [testing.md](testing.md). The mutation check there is not optional for a new component.
+
+## Compose ours
+
+Two seams, both public:
+
+- **Render ours inside yours, controlled from your state.** For a picker that opens in a Popover, your primitive owns `open`, ours renders with `open={state.open}`, and its `onOpenChange` forwards `reason`, `event` and `source` into your `change`. Use its props for the rest, like `initialFocus` on `PopoverContent`. Pass `initialFocus` explicitly when a specific field should take focus: in jsdom, the default focused the popup itself. See "Popups and layers" under Behaviors.
+- **Wrap ours and add behavior from outside.** For an input that clears on Escape, render our Input inside a root slot of yours that hears keydown as it bubbles, and change ours through its public controller (`createInputController()`, or the element's `.api` in web components). Check `event.target` so only the part you mean counts.
+
+Never bind a slot of yours to an element one of ours already binds. In React our attributes win, but in web components two owners write `data-slot` onto the same element.
+
+## Rules
+
+- Import only `@ui-sdk/core`, `@ui-sdk/core/<entry>`, each framework's primitive entry, and component entries. Never `@ui-sdk/core/internal/*`: only the ui-sdk repo resolves it. A type you can see only under `dist/foundation/<layer>/*.d.ts` and not in an entry, like `fuzzyFilter` in `foundation/text/fuzzy`, isn't public: rewrite it and record it as a gap.
+- Key collection parts by a string `value` or `id` prop, never an index. Composite keys, like a grid cell's, join ids with a separator ids can't contain. Structural parts, like rows, need keys too.
+- Expose state as ARIA and `data-*` attributes, never inline styles.
+- No direction provider: read `isRTL(el)` when a key is pressed. `createRovingFocus` passes `rtl` to `move`.
+
+## Other frameworks
+
+Each needs its own adapter package at the same version as `@ui-sdk/core`. Install it if it's missing, and say so. Its `docs/rendering.md` shows how that adapter renders a primitive.
+
+**Web components** have no `primitive` entry. `createParts` comes from `@ui-sdk/web` itself. [web-components.md](web-components.md) covers what the types don't: component entries define their elements on import, how to find tag names and required inner markup, and how hidden parts differ from React.
+
+## When you're done
+
+Besides SKILL.md's checklist, say in your report what you needed that only `@ui-sdk/core/internal/*` or `dist/*.js` had, and any behavior you wrote yourself that a block should have covered.
diff --git a/plugins/ui-sdk/.agents/skills/ui-sdk/references/patterns.md b/plugins/ui-sdk/.agents/skills/ui-sdk/references/patterns.md
new file mode 100644
index 00000000..62bf2f60
--- /dev/null
+++ b/plugins/ui-sdk/.agents/skills/ui-sdk/references/patterns.md
@@ -0,0 +1,246 @@
+# Patterns the blocks leave to you
+
+Each snippet comes from a component that passes its tests. Adapt the names. When a block grows to cover one of these, delete the pattern.
+
+## Grid arrows with `createRovingFocus` and `move`
+
+A set of choices in two dimensions, like emoji, colors or dates, is a `grid` of `row`s and `gridcell`s, and the root has a name. Use `createGridFocus` only when every row has the same columns, like a calendar. A spreadsheet adds `createCellRange` for a block of cells, and copies and pastes it with `range.text`, `cellsToText` and `textToCells` rather than its own tab-separated parser. Emoji, swatches and other lists that wrap into rows are a flowing grid: `createRovingFocus` with the `move` below. A set in one dimension is a `listbox` of `option`s. Don't use plain buttons for the cells.
+
+For a grid whose rows and columns are in state. Keys find cells by id, not by index. Past an edge, return `from.key` so the arrow is handled and the page doesn't scroll.
+
+```ts
+type CellProps = { value: string; row: string; column: string }
+const cellKey = (row: string, column: string) => `${row}\u001f${column}`
+
+const roving = createRovingFocus<State, CellProps>(context, {
+  slot: "cell",
+  key: "focused",
+  move: (event, { from, rtl }) => {
+    const { rows, columns } = store.get()
+    const row = rows.findIndex((r) => r.id === from.props.row)
+    const column = columns.findIndex((c) => c.id === from.props.column)
+    const corner = event.ctrlKey || event.metaKey
+    const lastRow = rows.length - 1
+    const lastColumn = columns.length - 1
+    const to = (
+      {
+        ArrowRight: [row, column + (rtl ? -1 : 1)],
+        ArrowLeft: [row, column + (rtl ? 1 : -1)],
+        ArrowDown: [row + 1, column],
+        ArrowUp: [row - 1, column],
+        Home: corner ? [0, 0] : [row, 0],
+        End: corner ? [lastRow, lastColumn] : [row, lastColumn],
+      } as Record<string, [number, number]>
+    )[event.key]
+    if (!to) return undefined
+    return rows[to[0]] && columns[to[1]]
+      ? cellKey(rows[to[0]].id, columns[to[1]].id)
+      : from.key
+  },
+})
+```
+
+For a grid that flows items into rows, like an emoji or swatch grid, work from the index in `items` and a `columns` count instead. Down from a column the short last row lacks should land on its last item.
+
+Shift is never swallowed, so a grid that selects rows extends from what `roving.keydown` returns:
+
+```ts
+const moved = roving.keydown(event, el)
+if (moved?.shift && rowOf(moved.key) !== rowOf(moved.from)) {
+  selection.extend(rowOf(moved.key), {
+    from: rowOf(moved.from),
+    reason: "list-navigation",
+    event,
+  })
+}
+```
+
+## `createRovingFocus`: `remember: false`
+
+With `remember: false`, the stop stays on the `preferred` item even while focus moves elsewhere in the group, so the focused item can have `tabindex="-1"`. That's right for a radio group, where selection follows focus. Anywhere else, keep the default and move focus explicitly with `roving.focus(key)`.
+
+## State derived from options and state
+
+`sync` sees only options. When derived state depends on both, like lists split by an option (`items`) and a value that may be controlled, recompute in a store subscription that compares references. That covers every way either input changes:
+
+```ts
+let derivedFrom = { items: store.get().items, value: store.get().value }
+context.onDestroy(
+  store.subscribe(() => {
+    const { items, value } = store.get()
+    if (items === derivedFrom.items && value === derivedFrom.value) return
+    derivedFrom = { items, value }
+    store.set(split(items, value))
+  })
+)
+```
+
+Storing the derived arrays, rather than computing them in a slot's `state`, is the safe choice: whether a part compares arrays by value isn't documented.
+
+## Selection in internal state
+
+`createSelection` infers its reasons from an `on<Key>Change` option. Internal state has none, so spell out the generics, and write with `store.set`:
+
+```ts
+type SelectionReason = "item-press" | "list-navigation" | "select-all"
+const selection = createSelection<Options, State, "selected", SelectionReason>(
+  context,
+  {
+    key: "selected",
+    set: (selected) => (store.set({ selected }), true),
+    order: () => store.get().ids,
+    multiple: () => true,
+    selectable: (id) => !itemById(id)?.disabled,
+  }
+)
+```
+
+Clicks map to it like this. `press` gets the click, so read its modifiers:
+
+```ts
+const mouse = event as MouseEvent | undefined
+if (mouse?.shiftKey)
+  selection.extend(id, {
+    from: store.get().focused,
+    reason: "item-press",
+    event: mouse,
+  })
+else if (mouse?.ctrlKey || mouse?.metaKey)
+  selection.toggle(id, { reason: "item-press", event: mouse })
+else selection.choose(id, { reason: "item-press", event: mouse })
+```
+
+`selects` on an array key takes an array of values: `selects({ selected: ({ key }) => [key] })`. On a scalar key, a value or a pair: `selects({ focused: ({ key }) => [key, null] })`.
+
+## Typeahead in a roving group
+
+`createTypeahead()` returns the search function itself, with `reset()` and `active()` on it. Let Space continue a query in progress, else let it toggle:
+
+```ts
+if (isTypeaheadKey(event) && (event.key !== " " || typeahead.active())) {
+  const items = roving.items()
+  const index = typeahead(
+    event.key,
+    items.map((item) => labelOf(item.el)),
+    items.findIndex((item) => item.el === el)
+  )
+  if (index !== -1) {
+    event.preventDefault()
+    roving.focus(items[index].key)
+  }
+  return
+}
+```
+
+## A search box over options with `createListbox`
+
+Keep focus in the input and highlight options with `aria-activedescendant`. The input is a `combobox`, each option an `option`, and choosing is a value you write with `createChange`:
+
+```ts
+const listbox = createListbox(context, {
+  key: "highlighted",
+  focus: "virtual",
+  query: () => context.store.get().query,
+})
+```
+
+```ts
+input: slot({
+  attrs: (state, { id, api }) => ({
+    role: "combobox",
+    "aria-expanded": "true",
+    "aria-controls": `${id}-list`,
+    "aria-activedescendant": api.listbox.activeId(state),
+  }),
+  on: {
+    input: (event, { api }) => api.search((event.target as HTMLInputElement).value),
+    keydown: (event, { api }) => api.keydown(event),
+  },
+}),
+option: slot<{ value: string }>({
+  role: "option",
+  focus: "active-descendant",
+  props: { value: "string" },
+  selects: selects({ highlighted: ({ key }) => [key, null] }),
+  present: (_state, part) => part.api.listbox.shows(part),
+  attrs: (state, part) => ({
+    ...part.api.listbox.attrs(state, part),
+    "aria-selected": String(state.value === part.key),
+  }),
+  press: ({ key, api }, event) => api.choose(key, event),
+  on: {
+    pointerdown: (event) => event.preventDefault(),
+    pointermove: (event, { key, api }) => api.listbox.highlight(key, { event }),
+  },
+  bind: (el, part) => part.api.listbox.bind(el, part),
+}),
+```
+
+`api.search` writes the query and calls `listbox.move("first")`, and `api.keydown` chooses the highlighted key on Enter before passing other keys to `listbox.keydown`. `pointerdown` keeps focus in the input. For options from data, pass `items` and render `listbox.items()`.
+
+## A `createFocusRecovery` fallback
+
+`fallback` runs after the state change, so the part that left is already gone from your lists. Walk a stable order from its key to find the neighbor that's still there, the next one first:
+
+```ts
+const recovery = createFocusRecovery<{ value: string; list: string }>({
+  fallback: (lost) => {
+    const { items } = store.get()
+    const list = store.get()[lost.props.list]
+    const at = items.findIndex((item) => item.id === lost.key)
+    const next =
+      items.slice(at + 1).find((item) => list.includes(item.id)) ??
+      items
+        .slice(0, Math.max(at, 0))
+        .reverse()
+        .find((item) => list.includes(item.id))
+    // `slotOf` maps a list to its option slot. Return nothing to let focus go.
+    return next ? context.element(slotOf(lost.props.list), next.id) : undefined
+  },
+})
+// Bind it next to the roving group in the item slot:
+bind: (el, part) => {
+  const cleanups = [
+    part.api.roving.bind(el, part),
+    part.api.recovery.bind(el, part),
+  ]
+  return () => cleanups.forEach((cleanup) => cleanup())
+}
+```
+
+## Two groups of the same kind
+
+Two lists side by side need two `createRovingFocus` groups, and a group is one slot. So give each list its own option slot, built by one function inside `slots`, and keep each block on the api by side:
+
+```ts
+slots: (slot) => {
+  const option = (side: Side) =>
+    slot<OptionProps>({
+      role: "option",
+      props: { value: "string" },
+      attrs: (state, part) => ({
+        tabindex: part.api.blocks[side].roving.tabIndex(state, part),
+      }),
+      // …
+    })
+  return { available: option("available"), chosen: option("chosen") /* … */ }
+}
+```
+
+## Focus into a field from a grid
+
+To let typing in a grid go back to its search field, focus the field on keydown and don't prevent the default. The browser types the character into the newly focused field. jsdom doesn't, so check this one in a real browser.
+
+## Reasons the vocabulary lacks
+
+Declare them in the callback's type, with a one-line comment naming which aren't shared:
+
+```ts
+// "select-all" isn't in the shared vocabulary.
+export type DataGridValueChangeReason =
+  "item-press" | "list-navigation" | "select-all"
+```
+
+## Stepper
+
+A stepper is a list of buttons with one tab stop, and the current step has `aria-current="step"`. Don't use radio or tab roles for it. A step a person can't go to yet is `aria-disabled`.
diff --git a/plugins/ui-sdk/.agents/skills/ui-sdk/references/styles.md b/plugins/ui-sdk/.agents/skills/ui-sdk/references/styles.md
new file mode 100644
index 00000000..558a57c2
--- /dev/null
+++ b/plugins/ui-sdk/.agents/skills/ui-sdk/references/styles.md
@@ -0,0 +1,66 @@
+# Style it
+
+Components render no styles of their own. `@ui-sdk/core/web.css` is an optional stylesheet that gives every component a default look. The setup prompt imports it, so most apps start with it.
+
+## web.css
+
+- Everything in it sits in `@layer ui-sdk`, so any rule outside a layer wins. Keep `@layer ui-sdk;` at the top of the global stylesheet so that's true with Tailwind too.
+- Work one of two ways: theme it by setting its `--ui-*` tokens on `:root`, or restyle a part with your own CSS on top. Don't fight it with `!important`.
+- It sets `color-scheme: light dark` and writes colors with `light-dark()`, so it follows the system theme. A light-only design sets `color-scheme: light` on `:root`.
+- Read `node_modules/@ui-sdk/core/dist/web.css`, or https://ui-sdk.dev/web.css on a page with no build step, when a part looks wrong. It's the only place its sizes and icons are written down.
+
+### Tokens
+
+| Token                                                                                                        | What it drives                                                                          |
+| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `--ui-background`, `--ui-foreground`                                                                         | Page, field and popup surfaces, and their text                                          |
+| `--ui-muted`, `--ui-muted-foreground`                                                                        | Hover and selected fills; hints, placeholders and secondary text                        |
+| `--ui-border`                                                                                                | Dividers and popup edges                                                                |
+| `--ui-input`                                                                                                 | Borders of inputs, selects, checkboxes, buttons and the empty part of a track or rating |
+| `--ui-primary`, `--ui-primary-foreground`                                                                    | Checked, pressed and filled states, and the text on them                                |
+| `--ui-destructive`                                                                                           | Errors and invalid borders                                                              |
+| `--ui-ring`, `--ui-ring-border`                                                                              | The focus outline, and a field's border while it has focus                              |
+| `--ui-overlay`, `--ui-shadow`                                                                                | A modal's backdrop, and popup shadows                                                   |
+| `--ui-radius`                                                                                                | Corners. Above 0, switch and slider thumbs turn fully round                             |
+| `--ui-spacing`                                                                                               | The unit every height, padding and gap is a multiple of                                 |
+| `--ui-font-size`, `--ui-line-height`                                                                         | Control text                                                                            |
+| `--ui-font-sans`, `--ui-font-mono`                                                                           | Fonts                                                                                   |
+| `--ui-icon-chevron`, `-check`, `-minus`, `-plus`, `-x`, `-eye`, `-eye-off`, `-calendar`, `-pipette`, `-star` | The default icons below, as `url()` images used as masks                                |
+
+### Icons it draws
+
+These parts draw an icon in `::before` or `::after` unless they hold an `<svg>` of their own. A text glyph like `−` doesn't count, so you get two. Either render an `<svg>`, keep the default, swap it through its `--ui-icon-*` token, or set `content: none`.
+
+- Chevrons: `select-trigger`, `combobox-trigger`, `navigation-menu-trigger`, `accordion-trigger`, `collapsible-trigger`, a submenu's `menu-trigger`.
+- Checks: `checkbox-indicator` (a minus while indeterminate), `select-item-indicator`, `combobox-item-indicator`, `listbox-item-indicator`, `menu-item-indicator`.
+- Minus and plus: `number-input-decrement`, `number-input-increment`.
+- Others: `calendar-previous` and `-next`, `carousel-previous` and `-next`, `pagination-previous` and `-next`, `tree-indicator`, `password-input-toggle`, `date-picker-trigger`, `date-picker-clear`, `color-picker-eye-dropper`, `file-input-item-remove`, `token-input-token-remove`, `toast-close`, `otp-input-separator`.
+- `rating-item` draws its star in `::before`. Draw your own star on the item, not on its radio, which is a transparent hit area.
+
+### Sizes it sets
+
+Reset these when a design needs other sizes:
+
+- Buttons, triggers, inputs and select triggers: `height: calc(var(--ui-spacing) * 8)`. Set `height: auto` for a taller one.
+- Textarea: `min-height: calc(var(--ui-spacing) * 20)`.
+- Slider, Progress and Meter: `min-width: 12rem`.
+- Accordion, Carousel and Image Cropper: `max-width: 28rem`. Carousel is also a three-column grid.
+- `resizable-panel`: `padding: calc(var(--ui-spacing) * 4)`.
+- `field`: a column. A checkbox beside its label inside a Field needs `flex-direction: row`.
+- A button with `aria-label` and only an `<svg>` inside is sized as a square icon button. Don't put `aria-label` on a button with visible text: its name should be that text.
+
+## Slots
+
+- A root's `data-slot` is the component's name, like `switch`, `slider` or `button`. A part's is `<component>-<part>`, like `switch-thumb` or `select-trigger`.
+- Some don't follow that, like a submenu's trigger, which is `menu-trigger`, and a part rendered as another component through `render`, which can carry that component's slot. Read the slot from the rendered DOM before you write a selector.
+
+## State
+
+- Style `data-selected`, `data-highlighted`, `data-checked` and the rest so the state reads on its own, at 3:1 against what's around it: a fill change, a full outline or a weight change. A faint tint alone doesn't. Don't default to a stripe down one edge.
+
+## Color
+
+- Text needs 4.5:1 against what's behind it, and 3:1 when it's large (WCAG 1.4.3). That includes placeholders, `::before` and `::after` text, and text over gradients or images.
+- Control edges, focus indicators and state fills need 3:1 (WCAG 1.4.11).
+- When you set tokens, check these pairs: `--ui-foreground` on `--ui-background`; `--ui-muted-foreground` on `--ui-background` and on `--ui-muted`; `--ui-primary-foreground` on `--ui-primary`; `--ui-input`, `--ui-ring` and `--ui-ring-border` on `--ui-background`.
+- jsdom can't measure color. Check contrast in a real browser, as [testing.md](testing.md#contrast) says.
diff --git a/plugins/ui-sdk/.agents/skills/ui-sdk/references/testing.md b/plugins/ui-sdk/.agents/skills/ui-sdk/references/testing.md
new file mode 100644
index 00000000..12f91d35
--- /dev/null
+++ b/plugins/ui-sdk/.agents/skills/ui-sdk/references/testing.md
@@ -0,0 +1,172 @@
+# Test it
+
+`@ui-sdk/core/testing` checks keyboard behavior, focus, ARIA, server output and reading direction. The full page is "Testing" in `docs/core.md`, or https://ui-sdk.dev/docs/core/testing.
+
+Test what you built, not what ui-sdk already tests: for an interface, check that the right components are wired with names, values and callbacks; for a new component, check every key and state.
+
+Wiring includes what a person does with the keyboard: press Space on every switch or checkbox you placed, not just one, and check that closing a dialog or menu returns focus where it should. Press each button in every dialog, Cancel as well as the confirming one, and check what happened. Submit each required field empty. Assert every button's name in the page's own markup, not in a fixture, and assert that state attributes you don't set, like `aria-disabled`, are absent. The same goes when you're asked to add tests to existing code: tests that pass on a broken page don't count.
+
+## Set up tests
+
+For React with Vite and Vitest. Other frameworks swap the testing library, like `@testing-library/vue`:
+
+```bash
+npm i -D vitest jsdom @testing-library/react @testing-library/dom @testing-library/user-event
+```
+
+`vitest.config.ts`:
+
+```ts
+import { defineConfig, mergeConfig } from "vitest/config"
+import viteConfig from "./vite.config.ts"
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      environment: "jsdom",
+      setupFiles: ["./src/test/setup.ts"],
+      css: false,
+    },
+  })
+)
+```
+
+`src/test/setup.ts` holds the [jsdom stubs](#jsdom), strict mode and cleanup:
+
+```ts
+import { cleanup } from "@testing-library/react"
+import { afterEach } from "vitest"
+
+declare global {
+  var __UI_SDK_STRICT__: boolean | undefined
+}
+globalThis.__UI_SDK_STRICT__ = true
+
+// The jsdom stubs below go here.
+
+afterEach(cleanup)
+```
+
+## Which tool for what
+
+| You built                                                   | Test with                                                                                                                                                                                                                                                                                                                                    |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| An interface from our components                            | The framework's testing library for what you wired (names, values, callbacks, what submits), and the [agent test](agent-ready.md#prove-it-with-a-test). Our components are tested already: don't run `checkPattern` on them.                                                                                                                 |
+| A primitive                                                 | `mount` with `keys`, `type`, `click`, `hover` and `drag`, then `checkPattern`, `checkServer` and `checkDirection`. If a page in the app uses it, also render that page: press its keys there, click each of its buttons that moves between steps (Next, Back), assert where focus lands after each, and assert its name in the page's markup |
+| Anything with popups, layout or focus moving between fields | Also a real browser                                                                                                                                                                                                                                                                                                                          |
+
+## Check a pattern
+
+`checkPattern(element, pattern)` checks roles, names, states, references between parts and the keyboard interactions of a WAI-ARIA pattern, and throws one error that lists every problem:
+
+```ts
+import { checkPattern } from "@ui-sdk/core/testing"
+
+await checkPattern(screen.getByRole("tablist").parentElement!, "tabs")
+```
+
+Patterns: `listbox`, `menu`, `menubar`, `tabs`, `radio-group`, `toolbar`, `tree`, `dialog`, `alertdialog`, `disclosure`, `accordion`, `combobox`, `slider`, `switch`, `checkbox`. Open a menu or dialog before checking it. A menu check activates an item, so use safe actions in tests.
+
+## Test a primitive
+
+```ts
+import { checkDirection, checkServer, mount } from "@ui-sdk/core/testing"
+import { expect, test } from "vitest"
+import { stepper } from "./stepper"
+
+test("arrows move between steps and Enter opens one", async () => {
+  const view = mount(
+    stepper,
+    {},
+    `<root><step value="a">A</step><step value="b">B</step></root>`
+  )
+  try {
+    await view.keys("Tab", "ArrowRight", "Enter")
+    expect(view.state.value).toBe("b")
+    expect(view.changes.at(-1)).toMatchObject({
+      key: "value",
+      source: "keyboard",
+    })
+  } finally {
+    view.unmount()
+  }
+})
+
+test("renders on the server and works in both directions", async () => {
+  checkServer(stepper, {}, `<root><step value="a">A</step></root>`)
+  await checkDirection(
+    stepper,
+    {},
+    `<root><step value="a">A</step><step value="b">B</step></root>`
+  )
+})
+```
+
+- In `mount`'s markup, tags named after slots become parts and their attributes become part props. `root` is the first element; `view.part("step", "b")` finds another.
+- Focus an input before `type`. `keys` takes `Tab`, `Shift+Tab`, `Space` and combinations.
+- `view.announced` holds what screen readers heard. Call `await view.settle()` before reading delayed work.
+- Always `unmount`.
+- Set `globalThis.__UI_SDK_STRICT__ = true` in the test setup so development warnings fail the test. Declare it first: `declare global { var __UI_SDK_STRICT__: boolean | undefined }`.
+
+## Break it on purpose
+
+For each key behavior of a new component, break it (return early, skip a call), run the tests, confirm one fails, then restore the file. A test that still passes is testing nothing. Report how many breaks your tests caught. When a page uses the component, break the page too, like a Back button that no longer moves focus, or the component's name.
+
+For a composite widget, test both arrow directions, that exactly one item is tabbable, Space and Enter, and every state attribute you set, like `aria-current` or `aria-disabled`.
+
+## jsdom
+
+Framework renderers don't fill jsdom's gaps. Before anything opens, add these to the test setup:
+
+```ts
+HTMLElement.prototype.showPopover = function () {}
+HTMLElement.prototype.hidePopover = function () {}
+Element.prototype.getAnimations = () => []
+Element.prototype.scrollIntoView = function () {}
+Element.prototype.checkVisibility = () => true
+Element.prototype.getClientRects = () => [] as unknown as DOMRectList
+document.elementFromPoint = () => null
+document.elementsFromPoint = () => []
+globalThis.ResizeObserver ??= class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+document.head.append(
+  Object.assign(document.createElement("style"), {
+    textContent: "[popover] { display: block !important }",
+  })
+)
+```
+
+Assign these rather than using `??=`: jsdom has some of them without the parts that matter. Web components in jsdom also need `ElementInternals`: jsdom's `attachInternals` lacks `setFormValue`, `setValidity`, `checkValidity`, `reportValidity` and `states`, so wrap `HTMLElement.prototype.attachInternals` and add them (no-ops, `() => true` for the checks, a `Set` for `states`). jsdom also never calls `formResetCallback`, and its `FormData` leaves custom elements out, so check form reset and submitted values in a real browser. Stub `URL.createObjectURL` for file previews. File Input's native input has `pointer-events: none`, so upload with `userEvent.setup({ pointerEventsCheck: 0 })`. Some parts render a status region of their own, like `SliderValue`'s `<output>`, so name yours and query by name: `getByRole("status", { name: "Total" })`. `mount` already does the popover and animation stubs, and it keeps a part that isn't present as a detached node, so `view.part()` still returns it: check `isConnected` to tell whether it's on the page. Some state arrives a tick after mounting; wait with `await new Promise((r) => setTimeout(r, 0))` (inside `act` in React).
+
+## WebMCP
+
+`registerTools` calls `document.modelContext.registerTool` once per tool and expects a Promise back. A mock:
+
+```ts
+const tools = new Map<string, { execute: (input: object) => unknown }>()
+Object.assign(document, {
+  modelContext: {
+    registerTool: async (tool: {
+      name: string
+      execute: (input: object) => unknown
+    }) => {
+      tools.set(tool.name, tool)
+    },
+  },
+})
+const unregister = registerTools(agent, { allow: () => true })
+expect(await tools.get("snapshot")!.execute({})).toBeInstanceOf(Array)
+unregister()
+```
+
+## A real browser
+
+Check what jsdom can't show: top layer popups and their placement, layout, a key that moves focus so the next typed character lands in another field, typeahead timing. A browser tool's "type" may insert text without key events, so press real keys to test keyboard handling. Tab through the whole interface once and confirm every control is reachable and named.
+
+### Contrast
+
+Measure the color pairs in [styles.md](styles.md#color) in every state a person can reach: hover, focus, selected, disabled, open, invalid, and each theme. Read the colors that are painted, not the ones you set: a tint over another fill, a gradient or a sliding indicator changes what's behind the text. Measure in a visible window with a size, after animations finish: a hidden tab paints nothing and runs no animations, so it gives wrong numbers.
diff --git a/plugins/ui-sdk/.agents/skills/ui-sdk/references/web-components.md b/plugins/ui-sdk/.agents/skills/ui-sdk/references/web-components.md
new file mode 100644
index 00000000..d5f0729e
--- /dev/null
+++ b/plugins/ui-sdk/.agents/skills/ui-sdk/references/web-components.md
@@ -0,0 +1,78 @@
+# Web components
+
+What the `@ui-sdk/web` types don't say, learned by probing.
+
+## Setup
+
+- Install `@ui-sdk/web` at the same version as `@ui-sdk/core` if it's missing.
+- There's no `primitive` entry. `createParts`, `wrappedButton` and the element types, like `UiInputElement`, come from `@ui-sdk/web` itself.
+- A component entry, like `@ui-sdk/web/input`, defines its elements when imported. Its types are `export {}`. A `define…Elements()` function you may find in another `.d.ts` isn't what the entry exports, and calling it fails.
+
+## Without a bundler
+
+A plain HTML page, like an Artifact, loads our elements and their default styles with two tags in its `<head>`:
+
+```html
+<script type="module" src="https://ui-sdk.dev/web.js"></script>
+<link rel="stylesheet" href="https://ui-sdk.dev/web.css" />
+```
+
+Read https://ui-sdk.dev/web.md first: the web components docs in one file, for a page like this. `web.js` defines each element the first time its tag appears, so leave out imports that only define elements, like `import "@ui-sdk/web/popover"`. What an entry exports comes from its own file, like `createPopoverController` from `https://ui-sdk.dev/web/popover.js`. To build elements of your own, import the behaviors, `definePrimitive` and `createParts` from `https://ui-sdk.dev/web/core.js`. It has everything in `@ui-sdk/core`'s root, but not subpaths like `@ui-sdk/core/tabs` or helpers like `toast()`. Use the `/web/` paths with `web.js` and the `/web@0/` paths with `web@0.js`, so the page loads one release.
+
+## Tag names and markup
+
+Each component's page, like `node_modules/@ui-sdk/web/docs/components/input.md`, shows its tags and markup. `node_modules/@ui-sdk/web/custom-elements.json` lists every tag each entry defines, with its attributes and their types, properties, the controller's methods on `.api`, events, parts and data attributes. Search it for a tag, like `"tagName": "ui-input-group"`, before probing. To confirm what an entry defines, probe it:
+
+```ts
+import "@ui-sdk/web/input"
+for (const tag of ["ui-input", "ui-input-group", "ui-input-clear"])
+  console.log(tag, !!customElements.get(tag))
+```
+
+Parts that keep native behavior need the native element inside them. The console says which: `<ui-input> needs its native element inside it for "root"`. For example:
+
+```html
+<ui-input-group>
+  <ui-input><input aria-label="Search" /></ui-input>
+  <ui-input-clear><button aria-label="Clear">×</button></ui-input-clear>
+</ui-input-group>
+```
+
+## Elements of your own
+
+`createParts` reads attributes and properties from the primitive's `options` schema, so give `definePrimitive` one, like `options: { clearOnEscape: "boolean", input: "value" }`. Every attribute option gets a property that reflects it, like `el.clearOnEscape = true`. Name booleans that start on in the root's `defaults`, like `defaults: { loop: true }`, so the property reads `true` without the attribute. Options the page provides go in the root's `options`:
+
+```ts
+createParts(clearableInput, {
+  root: {
+    tag: "ui-clearable-input",
+    display: "block",
+    // Read lazily: elements inside may upgrade after this one.
+    options: (el) => ({
+      input: () => el.querySelector<UiInputElement>("ui-input")?.api,
+    }),
+  },
+})
+```
+
+- Our elements expose their controller as `.api` and may not take a `controller` property, unlike their React components. If your primitive drives one of ours through a controller, take the controller as an option (a function, read when needed), so React can pass its own and web components can pass `.api`.
+- Don't bind a slot of yours to a native element one of ours binds. Both roots would write `data-slot` to it. Listen from a wrapper slot instead.
+
+## Differences from React
+
+- **Parts that aren't present stay in written markup, with `hidden`.** React removes them. A test helper that checks presence should treat `hidden` as absent.
+- **Changes fire events,** like `valuechange` on `<ui-input>`, with `{ value, reason }` in `detail`. `preventDefault()` cancels the change.
+- **Rendering custom elements from React JSX** needs their tags in `React.JSX.IntrinsicElements`. Don't name the props type `Element` inside `namespace JSX`: it shadows `JSX.Element`.
+
+## Testing
+
+Import the module that defines your elements in `beforeAll`, mount markup with `innerHTML`, and wait a tick before asserting, since parts register and sync after they connect. Dispatch real events with `bubbles: true`:
+
+```ts
+const event = new KeyboardEvent("keydown", {
+  key: "Escape",
+  bubbles: true,
+  cancelable: true,
+})
+field.dispatchEvent(event)
+```
diff --git a/plugins/ui-sdk/.claude-plugin/plugin.json b/plugins/ui-sdk/.claude-plugin/plugin.json
new file mode 100644
index 00000000..4923cffd
--- /dev/null
+++ b/plugins/ui-sdk/.claude-plugin/plugin.json
@@ -0,0 +1,26 @@
+{
+  "name": "ui-sdk",
+  "version": "1.0.0",
+  "description": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/core behaviors, make interfaces agent-ready with createAgent and WebMCP, and test keyboard, focus, ARIA, SSR and RTL.",
+  "author": {
+    "name": "Vercel Labs",
+    "url": "https://github.com/vercel-labs/ui"
+  },
+  "homepage": "https://github.com/vercel-labs/ui",
+  "repository": "https://github.com/vercel-labs/ui",
+  "license": "Apache-2.0",
+  "keywords": [
+    "ui-sdk",
+    "ui",
+    "components",
+    "accessibility",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "web-components",
+    "webmcp",
+    "vercel"
+  ],
+  "skills": "./.agents/skills/"
+}
diff --git a/plugins/ui-sdk/.codex-plugin/plugin.json b/plugins/ui-sdk/.codex-plugin/plugin.json
new file mode 100644
index 00000000..d44d2dbd
--- /dev/null
+++ b/plugins/ui-sdk/.codex-plugin/plugin.json
@@ -0,0 +1,40 @@
+{
+  "name": "ui-sdk",
+  "version": "1.0.0",
+  "description": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/core behaviors, make interfaces agent-ready with createAgent and WebMCP, and test keyboard, focus, ARIA, SSR and RTL.",
+  "author": {
+    "name": "Vercel Labs",
+    "url": "https://github.com/vercel-labs/ui"
+  },
+  "interface": {
+    "displayName": "Ui Sdk",
+    "shortDescription": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/co...",
+    "longDescription": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/core behaviors, make interfaces agent-ready with createAgent and WebMCP, and test keyboard, focus, ARIA, SSR and RTL.",
+    "developerName": "Vercel Labs",
+    "category": "UI",
+    "capabilities": [
+      "Skill"
+    ],
+    "defaultPrompt": [
+      "Help me use Ui Sdk for my current task."
+    ],
+    "websiteURL": "https://github.com/vercel-labs/ui"
+  },
+  "homepage": "https://github.com/vercel-labs/ui",
+  "repository": "https://github.com/vercel-labs/ui",
+  "license": "Apache-2.0",
+  "keywords": [
+    "ui-sdk",
+    "ui",
+    "components",
+    "accessibility",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "web-components",
+    "webmcp",
+    "vercel"
+  ],
+  "skills": "./.agents/skills/"
+}
diff --git a/plugins/ui-sdk/.cursor-plugin/plugin.json b/plugins/ui-sdk/.cursor-plugin/plugin.json
new file mode 100644
index 00000000..472a5933
--- /dev/null
+++ b/plugins/ui-sdk/.cursor-plugin/plugin.json
@@ -0,0 +1,31 @@
+{
+  "name": "ui-sdk",
+  "displayName": "Ui Sdk",
+  "description": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/core behaviors, make interfaces agent-ready with createAgent and WebMCP, and test keyboard, focus, ARIA, SSR and RTL.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Vercel Labs"
+  },
+  "category": "UI",
+  "homepage": "https://github.com/vercel-labs/ui",
+  "repository": "https://github.com/vercel-labs/ui",
+  "license": "Apache-2.0",
+  "keywords": [
+    "ui-sdk",
+    "ui",
+    "components",
+    "accessibility",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "web-components",
+    "webmcp",
+    "vercel"
+  ],
+  "tags": [
+    "skills",
+    "vercel",
+    "frontend"
+  ]
+}
diff --git a/plugins/ui-sdk/plugin.json b/plugins/ui-sdk/plugin.json
new file mode 100644
index 00000000..045275f4
--- /dev/null
+++ b/plugins/ui-sdk/plugin.json
@@ -0,0 +1,26 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "ui-sdk",
+  "version": "1.0.0",
+  "description": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/core behaviors, make interfaces agent-ready with createAgent and WebMCP, and test keyboard, focus, ARIA, SSR and RTL.",
+  "author": {
+    "name": "Vercel Labs",
+    "url": "https://github.com/vercel-labs/ui"
+  },
+  "homepage": "https://github.com/vercel-labs/ui",
+  "repository": "https://github.com/vercel-labs/ui",
+  "license": "Apache-2.0",
+  "keywords": [
+    "ui-sdk",
+    "ui",
+    "components",
+    "accessibility",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "web-components",
+    "webmcp",
+    "vercel"
+  ]
+}
diff --git a/plugins/ui-sdk/skills-lock.json b/plugins/ui-sdk/skills-lock.json
new file mode 100644
index 00000000..f63e3374
--- /dev/null
+++ b/plugins/ui-sdk/skills-lock.json
@@ -0,0 +1,11 @@
+{
+  "version": 2,
+  "skills": {
+    "ui-sdk": {
+      "source": "vercel-labs/ui",
+      "sourceType": "github",
+      "skillPath": "packages/core/skills/ui-sdk/SKILL.md",
+      "computedHash": "fd6d1a85ce608430e8b77b005e6263eaa7cda9e92c5c5ef0c669132906103bd2"
+    }
+  }
+}
diff --git a/release-please-config.json b/release-please-config.json
index 70fb8b89..f0c50b7f 100644
--- a/release-please-config.json
+++ b/release-please-config.json
@@ -1427,6 +1427,32 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/ui-sdk": {
+      "release-type": "simple",
+      "component": "ui-sdk",
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".codex-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": "plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".cursor-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "release-type": "node",

From 9e6a539dd35fc97c562a171dfb545c99a87fb394 Mon Sep 17 00:00:00 2001
From: Minsu Lee <amond@amond.net>
Date: Fri, 13 Nov 2026 13:00:19 +0900
Subject: [PATCH 2/2] chore(ui-sdk): apply AI code review suggestions

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index c06b0613..a550c505 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1431,7 +1431,7 @@
       "name": "ui-sdk",
       "description": "Build interfaces with ui-sdk in React, Vue, Svelte, Solid or web components — compose its unstyled, accessible components, build missing ones from @ui-sdk/core behaviors, make interfaces agent-ready with createAgent and WebMCP, and test keyboard, focus, ARIA, SSR and RTL.",
       "category": "ui",
-      "keywords": ["ui-sdk", "ui", "components", "accessibility", "react", "vue", "svelte", "solid", "web-components", "webmcp"],
+      "keywords": ["ui-sdk", "ui", "components", "accessibility", "react", "vue", "svelte", "solid", "web-components", "webmcp", "vercel"],
       "tags": ["skills", "vercel", "frontend"],
       "source": "./plugins/ui-sdk",
       "relevance": {