@reqvire-org/ads 0.3.3 → 0.3.5

package/docs/GUIDE.md

@@ -29,6 +29,20 @@ template strings and Shadow DOM style constructs lack equivalent coverage.
 Retain framework-specific checks; a clean ADS check does not validate those
 unchecked surfaces.
 
+### Controllers and behavior checks
+
+Keep private controllers with their consumer; share reusable behavior through
+`design-system/controllers/<Name>/`. Use the configured framework and declared
+project dependencies. Controllers own lifecycle/measurements while components and
+patterns own presentation. A shared context provider is a behavioral API too.
+
+Optional owner-local `behavior.json` registers guarantees and maintained checks.
+Scenario `exercises` records demonstrations separately from rendered `covers`.
+Use `ads behaviors --json` for discovery and `ads verify --unit <discovered-id>`
+to run registered cases; MCP exposes `ads_behaviors` and `ads_verify`. Tests and
+contracts stay outside production exports. See the [complete schema and runner
+integration](BEHAVIORS.md), including browser and React development StrictMode profiles.
+
 ### Linaria integration
 
 Before authoring components or patterns, integrate Linaria extraction with the
@@ -558,6 +572,7 @@ Application manifest metadata and other platform exports remain project-owned.
 | Asset ownership | ADS/public mount collisions, configured generated assets in source, and tracked generated output |
 | Product patterns | CSS/JSX namespace ownership; ADS implementations and showcase cannot import app source |
 | Primitive state | State-variable overrides outside components; undocumented non-state component variables |
+| Literal visual values | Absolute/font-relative lengths (including `ch` and root font units), durations and color/effect formulas require tokens; geometry angles and responsive viewport/container relationships remain available |
 | Fixed token ownership | Foreign token names, shared token overrides, misplaced component/pattern/showcase variables, and noncanonical foundation imports |
 | Showcase ownership | Fixture CSS/Linaria definitions, custom JSX classes, native controls/widget roles, state styling, private CSS/aliased imports, legacy catalogue dependencies and source ownership, and runtime imports of fixtures/test helpers |
 | Scenario coverage | All public renderable UI has path-discovered entries, colocated fixtures, literal metadata and reachable public render references; runtime imports of scenarios/fixtures are rejected |
@@ -717,7 +732,7 @@ Retain unrelated lint, type checking, and framework build commands.
 ## External content
 
 Use the repository's `ads-import` skill for selected external ADS source or theme
-values, and `ads-assimilate` for a native implementation inspired by an upstream
+values, and `ads-migrate` for a native implementation inspired by an upstream
 library. These agent workflows handle dependency closure, token mapping, motion
 comparisons, source credits, applicable notices, and local documentation.
 They are agent workflows, rather than CLI import/design subcommands. Install

package/docs/MCP.md

@@ -17,7 +17,11 @@ preview watcher and artifacts. Stdout remains exclusively JSON-RPC.
 
 For browser-only work, run `ads showcase` inside the project. It starts the same
 runtime without stdio. `--port 4185` selects a port; otherwise the OS chooses an
-available one. `ads mcp --no-showcase` disables the website for headless clients.
+available one. For a stable address, add `"--port", "4191"` to the server's `args`
+in `.mcp.json` (or the corresponding client configuration). An occupied explicit
+port fails startup; ADS does not silently switch ports or terminate another live
+client. Reuse the connected server's showcase instead of launching another one.
+`ads mcp --no-showcase` disables the website for headless clients.
 The website binds to 127.0.0.1 and accepts its own origin only. It serves packaged
 client assets and MCP, with no arbitrary file reader or command launcher.
 Shutdown closes both transports, subscriptions and the managed compiler.
@@ -155,7 +159,7 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | Tool | Purpose |
 |------|---------|
 | `ads_status` | Project paths, watcher/build states, preview revisions and diagnostics, skills |
-| `ads_catalog` | Bounded search for real public components/patterns and source/guide URIs |
+| `ads_catalog` | Bounded search for public UI, controllers and hooks, with source/guide URIs |
 | `ads_tokens` | Bounded token-definition and theme inspection |
 | `ads_check` | Current core architectural diagnostics; registered Oxlint/build tests remain separate |
 | `ads_skills` | Workflow names/descriptions without loading instructions |
@@ -163,22 +167,50 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | `ads_show_tokens` | Render a discovered token scenario; legacy compilers retain the definition inspector |
 | `ads_scenarios` | Bounded token/component/pattern/composition scenario discovery |
 | `ads_show_scenario` | Render an exact discovered scenario with its own fixtures |
+| `ads_behaviors` | Bounded guarantee/evidence discovery; pass an exact unit for contract details |
+| `ads_verify` | Execute an owner's registered checks and record revision-bound evidence |
 | `ads_show_<id>` | Optional explicitly configured grouped App |
 | `ads_units` | Discover edit owners and the files belonging to one unit |
 | `ads_read_file` | Read bounded source ranges, with owning unit and full-file digest |
 | `ads_apply_patch` | Opt-in Git unified diff for one ADS unit, with dry-run validation |
 
 Listings have bounded pages and opaque cursors. The source catalogue exposes
-public exports from `components/` and `patterns/`; it does not execute TSX to
+public exports from `components/`, `patterns/` and `controllers/`; it does not execute TSX to
 guess component props. Read the exported API and owning guide. An export name
 alone does not prove that a preview renders that particular element.
 
-`ads://project/status`, `/build`, `/tokens`, `/catalog`, `/scenarios`, and `/checks` carry complete JSON
+`ads://project/status`, `/build`, `/tokens`, `/catalog`, `/scenarios`, `/behaviors`, and `/checks` carry complete JSON
 detail. Allowed project documentation/source and skill files are separate
 resources. No arbitrary filesystem reader is exposed. Prefer bounded tools for
 large catalogues; explicit resource reads can enter model context and a client
 may truncate large payloads.
 
+### Behavioral verification
+
+Read `ads://guides/behaviors` or the [behavior guide](BEHAVIORS.md) for the contract
+and runner schema. `ads_behaviors({ "unit": "components/MessageScroller" })`
+returns subjects, guarantees, demonstration links and check IDs for a discovered
+owner. `ads_verify({ "unit": "components/MessageScroller", "checks": ["prepend-anchor"] })`
+runs those registered cases. The names here are examples, never built-in cases.
+
+`covers` describes rendered UI; optional `exercises` describes public behavioral
+APIs used through reachable scenario code. Neither metadata nor README prose is
+passing evidence. Verification runs trusted project commands from configured
+profiles, without installing dependencies. It is available in read-only source
+mode too and is annotated as executing commands/writing generated evidence.
+Missing/skipped cases, unavailable runners and changed inputs cannot pass.
+Results and subscribed resource notifications are available through
+`ads://project/behaviors`; explicitly re-read evidence when notifications are absent.
+
+Browser profiles start an isolated showcase and verify its sandboxed App using
+the selected candidate's sources. StrictMode profiles need a project React
+development harness. Profiles describe the execution environment, not a proof
+that every possible interaction or lifecycle has been tested.
+
+Guarded mutations also run affected registered behavior checks, including contracts
+that depend on changed shared controllers. Failures reject the candidate before
+writing real source. Projects without contracts retain their existing checks.
+
 ## Guarded editing
 
 Enable editing in the MCP launch arguments and reconnect:
@@ -540,8 +572,15 @@ Managed configuration changes replace the compiler through the same supervisor.
 Updating ADS server code itself still requires reconnecting the MCP client to load
 the new package. Normal component, fixture and style edits remain automatic.
 
-ADS stops the managed watcher and its compiler subprocesses when stdin closes or
-it receives SIGINT/SIGTERM. The project must keep its watcher in the foreground,
+ADS closes both network hosts and stops the managed watcher and its compiler
+subprocesses when the stdio wire closes, including EOF or broken output, or it
+receives SIGINT/SIGTERM. Active browser subscriptions do not retain the runtime.
+A small independent ownership guard watches a pipe from MCP; owner death closes
+that pipe even after SIGKILL. The guard terminates the owned compiler process
+group, escalates for stubborn descendants, then exits. It is disarmed on ordinary
+shutdown; `previewWatch.guardPid` identifies it while running. This requires no
+second user command and applies to custom builders too.
+The project must keep its watcher in the foreground,
 rather than launching detached background processes. The configuration is
 trusted project setup; MCP tools accept no executable or command arguments.
 To manage builds yourself, omit `previewWatch` or set it to `null`, then run the
@@ -680,7 +719,7 @@ See the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-app
 | Each of the five ADS skill names | `request` | Select that workflow and its skill resource |
 
 Example: get `ads-inspect` with `element="Button states in both themes"`, or
-`ads-assimilate` with `request` containing the upstream component-library URL.
+`ads-migrate` with `request` containing the upstream component-library URL.
 Prompts explain Data/UX/Skin ownership, public API reuse, fixture boundaries,
 which tools select widgets, progressive skill reads and validation. They guide
 reasoning rather than inventing another component implementation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -69,6 +69,7 @@
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/ext-apps": "2.0.3",
     "@modelcontextprotocol/sdk": "1.32.1",
+    "@playwright/test": "1.64.1",
     "@preact/signals": "2.11.3",
     "@types/node": "^25.9.2",
     "@types/react": "^19.2.17",
@@ -98,7 +99,8 @@
     "./mcp/build": "./dist/mcp/build-status.mjs",
     "./scenarios": "./dist/scenarios.mjs",
     "./scenarios/vite": "./dist/scenarios-vite.mjs",
-    "./scenarios/compiler": "./dist/scenarios-compiler.mjs"
+    "./scenarios/compiler": "./dist/scenarios-compiler.mjs",
+    "./verification": "./dist/verification/browser.mjs"
   },
   "files": [
     "dist",

package/dist/skills/ads-assimilate/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "ADS Assimilate"
-  short_description: "Adapt reference components into a native design system"
-  default_prompt: "Use $ads-assimilate with a component-library URL to implement and verify a native design-system component."