@reqvire-org/ads 0.3.11 → 0.3.13

package/docs/MCP.md

@@ -177,6 +177,8 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | `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_capture` | On-demand PNG of a discovered scenario or named element; replace current and clear candidate |
+| `ads_capture_clear` | Remove generated captures or discard only the candidate |
 | `ads_show_<id>` | Optional explicitly configured grouped App |
 | `ads_units` | Discover edit owners and the files belonging to one unit |
 | `ads_prepare_patch` | Prepare a local draft of one owner, then generate its Git patch |
@@ -212,6 +214,36 @@ informational limit nor a traced target proves a rendered failure or success.
 Bounded check results put warnings before informational limits; the checks
 resource retains complete results.
 
+### Screenshots and candidate comparison
+
+`ads_capture({scenario:"<discovered ID>",target?,theme?,viewport?})` renders current
+source in the real sandboxed App using project-local Playwright/browser. It returns
+PNG resource URIs and revision/settings metadata. The default is the full widget
+viewport; optional `captureTargets` metadata names an element within the scenario.
+Token/component/pattern/composition scenarios share this path. The tool adds no
+project-specific renderer or fixture assumptions.
+
+Patch and transaction dry runs accept `screenshot:true` plus an explicit 1–8-entry
+`captures:[{scenario,target?,theme?,viewport?}]` selection. Existing gates run first;
+current and candidate use matching capture settings. Source/conflict checks remain
+mandatory. No screenshots are created by ordinary patches/dry runs. A newly added
+scenario has a candidate with an explicit absent current baseline.
+
+`ads://project/captures` lists current/candidate slots, metadata and freshness.
+Read returned `ads://captures/{key}/{slot}` resources as `image/png` binary content;
+the resource template is advertised without per-revision catalogue growth.
+Subscriptions receive `resources/updated` for replacement/removal. Successful
+standalone capture replaces current and clears any prior candidate. Applying
+matching proposed source promotes candidate; explicit `ads_capture_clear` can
+discard the candidate or both slots. There is no previous/history/TTL. Source
+changes mark stale images; deleted targets are collected. Capture data is bounded
+generated output under `.ds/captures/`, not a source mutation or behavior pass.
+
+Optional `mcp.capture` selects browser, Chromium channel and runner timeout.
+ADS installs no browser dependencies. See `ads://guides/captures` or the portable
+[capture reference](../skills/ads-designer/references/captures.md) for setup, precise
+limits, target declarations and the guarded review workflow.
+
 ### Behavioral verification
 
 Read `ads://guides/behaviors` or the [behavior guide](BEHAVIORS.md) for the contract
@@ -229,6 +261,15 @@ 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.
 
+During a run, `ads_status.behaviors.progress` exposes completed/active/pending
+checks, timings and the profile's whole-run timeout. Candidate mutation checks use
+`ads_status.mutations.progress`. Requested MCP progress notifications also report
+runner activity. Playwright uses the project's workers and filters selected case
+tags; ADS does not silently change timeout or parallelism policy. Timeout results
+retain partial outcomes and reports under `.ds/verification/`, but incomplete
+runs still block application and cannot establish passing guarantees. See the
+[runner and evidence details](BEHAVIORS.md#register-execution-profiles).
+
 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
@@ -294,10 +335,23 @@ The same discovery covers the rest of the project ADS:
 | Unit | Scope |
 |------|-------|
 | `foundation` | Shared ADS entry styles and root helpers |
-| `documentation` | ADS guides/licenses and the project's README, GUIDE, MCP, Architecture and ADS Markdown guides |
+| `documentation` | ADS/project guides, shared credits and license notices, and `licenses/` text collections |
 | `assets/brand`, `assets/fonts`, other `assets/*` groups | Original SVG, image, font and other asset files |
 | `configuration` | `ds.config.json`, package/TypeScript/bundler/lint configuration, registered ADS guard modules, compiler/check entrypoints and their static local dependencies |
 
+The `documentation` manifest includes `filePolicy` for paths that can be created
+before they exist. One documentation patch can add `CREDITS.md`,
+`licenses/example.txt` and the required README links together. Conventional root
+`LICENSE`/`LICENCE`, `NOTICE`, `COPYING`, `COPYRIGHT` and `CREDITS` notices accept
+`.md`, `.txt`, or extensionless names, with optional `-`/`_` qualifiers. Shared
+`licenses/` collections may also live under `docs/`, `doc/`, or the configured ADS
+root. Their entries use `.md`/`.txt` or conventional extensionless notice names.
+Content must be UTF-8 without NUL bytes; Git patches preserve exact text, Unicode,
+line endings and final-newline state. Code/configuration, hidden/generated paths
+and peer-owned files retain their boundaries. A component's colocated notice stays
+in that component unit. Shared notices are listed as readable MCP resources, while
+workflow guide discovery omits provenance inventories. No asset unit is needed.
+
 Configuration ownership follows the project's registrations. It does not absorb
 components merely because a guard or compiler reads them. Guard registration,
 implementation, helpers and the associated check script can change together.
@@ -348,7 +402,14 @@ directory containing only the owner and declared companions. Edit that directory
 using the client's local file tools, then call
 `ads_prepare_patch({unit, action:"diff", draft})`. It checks source/baseline
 freshness and owner paths and returns a `patchFile`; it changes no live source.
-Apply the result through `ads_apply_patch`, which runs the normal candidate gates.
+Pass that `patchFile` to `ads_apply_patch` with `dryRun:true` to validate before
+applying. This runs the normal candidate gates, including affected registered
+behavior checks against an isolated candidate and its configured browser preview.
+It writes no live source and does not persist passing evidence for live inputs.
+Read returned `behavior` failures or behavior-check results in `checks`; update the
+draft, diff again and repeat as needed. Apply with `dryRun:false` after validation;
+the gates run again. `ads_verify({unit,checks?})` checks current source and accepts
+no draft argument; a selected-check draft runner is not currently exposed.
 Use `action:"discard"` to remove the draft. Remote clients can continue sending
 inline Git diffs. Drafts are local conveniences, not an alternative mutation API.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {