@reqvire-org/ads 0.3.12 → 0.3.13

package/dist/skills/ads-import/references/captures.md

@@ -0,0 +1,147 @@
+# On-demand visual captures
+
+Use captures when reviewing appearance or a proposed visual change. Discover exact
+scenario IDs with `ads_scenarios`; these are project-owned independently mountable
+token, component, pattern and composition views. A component export alone is not
+a renderable fixture. Controllers/hooks need a scenario demonstrating their visible
+effects. ADS never supplies library-specific renderers, fixtures or capture targets.
+
+## Capture current source
+
+```js
+ads_capture({
+  scenario: "components/Example",
+  theme: "dark",
+  viewport: { width: 1280, height: 800 }
+})
+```
+
+The ID above is illustrative; use one returned by discovery. The default is light
+theme at 1280 × 800 CSS pixels. Capture uses the real sandboxed MCP App with the
+requested viewport and excludes showcase navigation. The default image records
+the complete widget viewport, including its current scroll/state; it does not
+automatically stitch every scroll position into one image.
+
+ADS starts an isolated showcase/compiler and an owned browser process, using the
+connected project's installed `@playwright/test` or `playwright`. It installs no
+dependency/browser. Chromium is the default; optional project configuration is:
+
+```json
+{
+  "mcp": {
+    "capture": {
+      "browser": "chromium",
+      "channel": "chrome",
+      "timeoutMs": 60000
+    }
+  }
+}
+```
+
+Omit `channel` to use Playwright's installed Chromium. Firefox and WebKit are also
+accepted browser choices; channel is Chromium-only. The registered browser must
+be installed locally. This budget bounds the capture runner, including preview
+readiness. Capture does not run the project's entire Playwright suite or require a
+behavior manifest. Readiness uses the App bridge, fonts and settled image loads,
+not `networkidle` (MCP maintains live connections).
+
+## Capture a named element
+
+Declare selectors in the scenario's static metadata:
+
+```tsx
+export const scenario = {
+  title: "Example",
+  covers: ["Example"],
+  captureTargets: {
+    control: '[data-testid="example-control"]'
+  }
+};
+```
+
+Use attributes/selectors already owned by the real UI or its public review pattern.
+Scenarios keep their existing styling/control rules. A target is not permission
+to add demo-only product props, custom CSS or synthetic native controls. Each
+selector is scoped to the App iframe and must match exactly one visible element.
+Select it with `ads_capture({scenario:"<discovered ID>",target:"control"})`.
+`captureTargets` allows up to 20 named CSS selectors. Unknown, hidden, ambiguous
+or unrenderable targets fail explicitly; ADS does not guess a substitute element.
+Arrange a specific interaction state through the scenario's real fixture/adapter;
+capture itself accepts no arbitrary browser script or click sequence.
+
+Screenshots hide the text caret and disable animations by default. Set
+`animations:"allow"` when motion must remain active, and account for nondeterminism.
+The same capture settings are used for both sides of a candidate comparison.
+
+## Review a patch without applying it
+
+Prepare/diff an owner draft normally, then request screenshots during its guarded
+dry run:
+
+```js
+ads_apply_patch({
+  unit: "components/Example",
+  patchFile: ".ds/patches/<returned-name>.patch",
+  dryRun: true,
+  screenshot: true,
+  captures: [{ scenario: "components/Example", target: "control", theme: "light" }]
+})
+```
+
+The placeholder owner/ID/path must come from discovery/preparation. Transactions
+accept the same `screenshot`/`captures` fields. Select 1–8 distinct scenario/target
+pairs explicitly; do not capture every affected scenario by default. Ordinary dry
+runs and patches create no screenshots. `screenshot:true` requires `dryRun:true`.
+
+Core, registered lint/project and affected behavior gates pass first. ADS then
+captures current source and the isolated candidate under matching theme, viewport,
+animation and browser settings. Candidate screenshots survive candidate-directory
+cleanup. Final source/conflict checks still run before the pair is published. A
+failed/cancelled capture does not replace existing image slots or apply source.
+If a scenario/target is newly introduced, `current` is null with an explicit
+`currentAbsent` explanation; only the real candidate image exists.
+
+Review the returned images and diagnostics, fix the draft if necessary, then apply
+with `dryRun:false`. Apply reruns all gates. An image is promoted only when the
+accepted source revision matches the captured candidate; other proposals remain
+stale. Images do not approve a patch or certify interaction/accessibility/parity.
+
+## Two slots, no automatic history
+
+The stable capture key identifies the scenario and optional named target. Theme,
+viewport and revision are metadata, not additional resource identities.
+
+| Successful operation | Result for that target |
+| --- | --- |
+| Standalone `ads_capture` | Fresh current; any earlier candidate removed |
+| Screenshot-enabled dry run | Fresh current + candidate; replaces the old pair |
+| Apply matching proposed source | Candidate becomes current; candidate slot cleared |
+| `ads_capture_clear({scenario,target?,candidateOnly:true})` | Discard candidate, retain current when present |
+| `ads_capture_clear({scenario,target?})` | Remove both slots |
+| Remove scenario/target | Orphan images collected on resource refresh/discovery |
+
+No previous slot, revision history or TTL is kept. Later source changes mark
+images stale rather than silently recapturing them. New proposals replace the
+candidate. Three limits keep storage bounded: at most 4 MiB per PNG, 8 megapixels
+per image and 256 MiB total capture storage. Clear unneeded targets if the store
+reaches its limit. Viewport dimensions range from 100 to 4096 pixels per axis,
+subject to the pixel limit.
+
+## Read resources and freshness
+
+`ads://project/captures` lists existing slots and metadata. Each returned image URI
+uses the template `ads://captures/{key}/{slot}`, with `slot` current or candidate.
+Read the exact returned URI through MCP `resources/read` (or the host's resource
+tool). The result is `image/png` with binary `blob`, not a filesystem or browser
+URL. Use the client's image/resource viewer; do not paste base64 into model text.
+
+Capture metadata records source/build revision, fixture owner file, settings,
+capture time, PNG dimensions/digest and candidate proposal identity. Current is
+stale when its source revision differs; a candidate becomes stale when its base
+source changes. Static freshness does not prove external/live fixture data stayed
+identical. Subscribe to the index and image URIs for `resources/updated`, including
+candidate removal; explicitly reread when the host does not deliver notifications.
+Absent/cleared slots return a resource-not-found diagnostic, not an old image.
+The resource catalogue exposes one index and an image URI template, avoiding a
+resource-list entry for every new revision. Images stay as generated development
+data under `.ds/captures/`; none belongs in product bundles or source patches.

package/dist/skills/ads-import/references/guarded-editing.md

@@ -6,6 +6,64 @@ tools, request `action:"diff"`, then apply the returned patchFile. Discard the
 draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
 preparation nor diff generation validates or changes live source.
 
+To verify a draft before applying it, diff it and dry-run the returned patch:
+
+```js
+ads_prepare_patch({"unit":"components/Example","action":"diff","draft":"<returned draft ID>"})
+ads_apply_patch({"unit":"components/Example","patchFile":"<returned patchFile>","dryRun":true})
+```
+
+The dry run validates the full candidate, including affected registered behavior
+checks in an isolated project copy. Configured browser checks use that candidate's
+managed preview, not the live showcase. Inspect the returned `behavior` failures
+or the registered behavior-check results in `checks`, fix the draft and diff again.
+Keep behavior.json/specs with their owner and use registered checks; a scratchpad
+run against live source cannot verify unapplied changes. After validation, apply
+with `dryRun:false`; ADS revalidates before writing. Dry-run evidence is not saved
+as passing evidence for the live project.
+
+`ads_verify({unit,checks?})` selects checks for current project source; it has no
+draft argument. There is no dedicated selected-check runner for drafts yet.
+Use a dry-run transaction for genuinely coupled draft patches.
+
+Behavior-run performance belongs to both orchestration and project checks. ADS
+selects affected owners, filters registered Playwright case tags and shares one
+candidate host per run. The project owns assertions, browser setup, worker count,
+per-test timeouts and its profile's whole-run `timeoutMs`. The latter covers the
+entire runner process, not each test. Do not rewrite APIs, drop guarantees or
+disable checks to fit the budget. Inspect measured durations before tuning it.
+
+During verification, inspect `ads_status.behaviors.progress`; during candidate
+validation, inspect `ads_status.mutations.progress`. These show completed/active/
+pending checks and timings. MCP clients requesting progress also receive updates.
+A timeout retains reported case outcomes and identifies active/unstarted checks;
+it still blocks the mutation. `reportedStatus:"passed"` within an incomplete run
+is diagnostic information, not a passing guarantee. Reports/artifacts under the
+live project's `.ds/verification/` survive candidate cleanup. Uninstrumented custom
+runners may report an unknown execution state instead of claiming a case started.
+
+For independent browser specs, consider a small parallel worker count and measure
+on the target machine. Use separate contexts/pages, independent state and the
+candidate URLs provided by `openBehaviorScenario`; avoid fixed live-server URLs,
+shared mutable fixtures and test-order assumptions. Files can run in parallel;
+tests in one file remain sequential by default. Prefer readiness assertions over
+blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actual
+gesture/motion/layout guarantees. Project settings belong in guarded configuration
+changes; ADS does not silently raise budgets or override the worker count.
+
+Named barrel imports can narrow affected checks when the project accurately
+declares package `sideEffects`; retain CSS/global effects in that policy. Missing
+or unsupported policies and dynamic/wildcard dependencies stay conservative.
+Do not change the policy merely to suppress verification of real side effects.
+
+For registered measured-geometry style writes, use direct `element.style.transform =
+value` or `element.style.setProperty("--ds-measured-value", value)` with the exact
+file/property boundary. The current guard rejects a style-object alias such as
+`const style = element.style` as an escape; it does not trace the alias to later
+writes. Keep writes explicit when adapting local controller code. This syntax
+constraint is separate from deciding which measured properties belong to the
+controller; it does not authorize unregistered visual writes.
+
 Shared provenance uses the existing `documentation` unit. Read its `filePolicy`
 from `ads_units`: one patch can create `CREDITS.md`, shared `licenses/*.txt` and
 README links together. Conventional root credits/license/notice names support

package/dist/skills/ads-import/references/scenarios.md

@@ -18,6 +18,11 @@ recovers missed atomic replacements. Do not touch source to force freshness;
 inspect build diagnostics. Upgrade the project's compiler dependency together
 with MCP when an older reporter lacks source evidence.
 
+Optional static `captureTargets` names CSS selectors within the scenario's App for
+on-demand element screenshots. It grants no render/behavior coverage and no extra
+styling permission. Use [captures.md](captures.md) for current/candidate review,
+target selection, resource reads and storage lifecycle.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.

package/dist/skills/ads-migrate/SKILL.md

@@ -32,7 +32,10 @@ also list a `ds.config.json` companion: change only that owner's `inlineStyleFil
 and `boundaries.styleWrites` entries together with its source. Unused permissions
 fail the core checks; do not pre-register a boundary without its implementation.
 Use `dryRun: true` to
-inspect validation; applying re-runs the gates. Fix rejected patches in their
+inspect validation, including affected registered behavior checks on the isolated
+candidate. For a prepared draft, request its diff and dry-run the returned
+`patchFile`; `ads_verify` checks current source and accepts no draft argument.
+Applying re-runs the gates. Fix rejected patches in their
 owner. Use `ads_apply_transaction` for genuinely coupled owner patches;
 never bypass a rejection with direct source writes. Shared styles/helpers use `foundation`, root guides use
 `documentation`, and branding/fonts use their discovered `assets/*` unit.
@@ -44,6 +47,8 @@ stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
 For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
+For on-demand current/candidate screenshots and visual dry-run review, read
+[captures.md](references/captures.md).
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,

package/dist/skills/ads-migrate/references/captures.md

@@ -0,0 +1,147 @@
+# On-demand visual captures
+
+Use captures when reviewing appearance or a proposed visual change. Discover exact
+scenario IDs with `ads_scenarios`; these are project-owned independently mountable
+token, component, pattern and composition views. A component export alone is not
+a renderable fixture. Controllers/hooks need a scenario demonstrating their visible
+effects. ADS never supplies library-specific renderers, fixtures or capture targets.
+
+## Capture current source
+
+```js
+ads_capture({
+  scenario: "components/Example",
+  theme: "dark",
+  viewport: { width: 1280, height: 800 }
+})
+```
+
+The ID above is illustrative; use one returned by discovery. The default is light
+theme at 1280 × 800 CSS pixels. Capture uses the real sandboxed MCP App with the
+requested viewport and excludes showcase navigation. The default image records
+the complete widget viewport, including its current scroll/state; it does not
+automatically stitch every scroll position into one image.
+
+ADS starts an isolated showcase/compiler and an owned browser process, using the
+connected project's installed `@playwright/test` or `playwright`. It installs no
+dependency/browser. Chromium is the default; optional project configuration is:
+
+```json
+{
+  "mcp": {
+    "capture": {
+      "browser": "chromium",
+      "channel": "chrome",
+      "timeoutMs": 60000
+    }
+  }
+}
+```
+
+Omit `channel` to use Playwright's installed Chromium. Firefox and WebKit are also
+accepted browser choices; channel is Chromium-only. The registered browser must
+be installed locally. This budget bounds the capture runner, including preview
+readiness. Capture does not run the project's entire Playwright suite or require a
+behavior manifest. Readiness uses the App bridge, fonts and settled image loads,
+not `networkidle` (MCP maintains live connections).
+
+## Capture a named element
+
+Declare selectors in the scenario's static metadata:
+
+```tsx
+export const scenario = {
+  title: "Example",
+  covers: ["Example"],
+  captureTargets: {
+    control: '[data-testid="example-control"]'
+  }
+};
+```
+
+Use attributes/selectors already owned by the real UI or its public review pattern.
+Scenarios keep their existing styling/control rules. A target is not permission
+to add demo-only product props, custom CSS or synthetic native controls. Each
+selector is scoped to the App iframe and must match exactly one visible element.
+Select it with `ads_capture({scenario:"<discovered ID>",target:"control"})`.
+`captureTargets` allows up to 20 named CSS selectors. Unknown, hidden, ambiguous
+or unrenderable targets fail explicitly; ADS does not guess a substitute element.
+Arrange a specific interaction state through the scenario's real fixture/adapter;
+capture itself accepts no arbitrary browser script or click sequence.
+
+Screenshots hide the text caret and disable animations by default. Set
+`animations:"allow"` when motion must remain active, and account for nondeterminism.
+The same capture settings are used for both sides of a candidate comparison.
+
+## Review a patch without applying it
+
+Prepare/diff an owner draft normally, then request screenshots during its guarded
+dry run:
+
+```js
+ads_apply_patch({
+  unit: "components/Example",
+  patchFile: ".ds/patches/<returned-name>.patch",
+  dryRun: true,
+  screenshot: true,
+  captures: [{ scenario: "components/Example", target: "control", theme: "light" }]
+})
+```
+
+The placeholder owner/ID/path must come from discovery/preparation. Transactions
+accept the same `screenshot`/`captures` fields. Select 1–8 distinct scenario/target
+pairs explicitly; do not capture every affected scenario by default. Ordinary dry
+runs and patches create no screenshots. `screenshot:true` requires `dryRun:true`.
+
+Core, registered lint/project and affected behavior gates pass first. ADS then
+captures current source and the isolated candidate under matching theme, viewport,
+animation and browser settings. Candidate screenshots survive candidate-directory
+cleanup. Final source/conflict checks still run before the pair is published. A
+failed/cancelled capture does not replace existing image slots or apply source.
+If a scenario/target is newly introduced, `current` is null with an explicit
+`currentAbsent` explanation; only the real candidate image exists.
+
+Review the returned images and diagnostics, fix the draft if necessary, then apply
+with `dryRun:false`. Apply reruns all gates. An image is promoted only when the
+accepted source revision matches the captured candidate; other proposals remain
+stale. Images do not approve a patch or certify interaction/accessibility/parity.
+
+## Two slots, no automatic history
+
+The stable capture key identifies the scenario and optional named target. Theme,
+viewport and revision are metadata, not additional resource identities.
+
+| Successful operation | Result for that target |
+| --- | --- |
+| Standalone `ads_capture` | Fresh current; any earlier candidate removed |
+| Screenshot-enabled dry run | Fresh current + candidate; replaces the old pair |
+| Apply matching proposed source | Candidate becomes current; candidate slot cleared |
+| `ads_capture_clear({scenario,target?,candidateOnly:true})` | Discard candidate, retain current when present |
+| `ads_capture_clear({scenario,target?})` | Remove both slots |
+| Remove scenario/target | Orphan images collected on resource refresh/discovery |
+
+No previous slot, revision history or TTL is kept. Later source changes mark
+images stale rather than silently recapturing them. New proposals replace the
+candidate. Three limits keep storage bounded: at most 4 MiB per PNG, 8 megapixels
+per image and 256 MiB total capture storage. Clear unneeded targets if the store
+reaches its limit. Viewport dimensions range from 100 to 4096 pixels per axis,
+subject to the pixel limit.
+
+## Read resources and freshness
+
+`ads://project/captures` lists existing slots and metadata. Each returned image URI
+uses the template `ads://captures/{key}/{slot}`, with `slot` current or candidate.
+Read the exact returned URI through MCP `resources/read` (or the host's resource
+tool). The result is `image/png` with binary `blob`, not a filesystem or browser
+URL. Use the client's image/resource viewer; do not paste base64 into model text.
+
+Capture metadata records source/build revision, fixture owner file, settings,
+capture time, PNG dimensions/digest and candidate proposal identity. Current is
+stale when its source revision differs; a candidate becomes stale when its base
+source changes. Static freshness does not prove external/live fixture data stayed
+identical. Subscribe to the index and image URIs for `resources/updated`, including
+candidate removal; explicitly reread when the host does not deliver notifications.
+Absent/cleared slots return a resource-not-found diagnostic, not an old image.
+The resource catalogue exposes one index and an image URI template, avoiding a
+resource-list entry for every new revision. Images stay as generated development
+data under `.ds/captures/`; none belongs in product bundles or source patches.

package/dist/skills/ads-migrate/references/guarded-editing.md

@@ -6,6 +6,64 @@ tools, request `action:"diff"`, then apply the returned patchFile. Discard the
 draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
 preparation nor diff generation validates or changes live source.
 
+To verify a draft before applying it, diff it and dry-run the returned patch:
+
+```js
+ads_prepare_patch({"unit":"components/Example","action":"diff","draft":"<returned draft ID>"})
+ads_apply_patch({"unit":"components/Example","patchFile":"<returned patchFile>","dryRun":true})
+```
+
+The dry run validates the full candidate, including affected registered behavior
+checks in an isolated project copy. Configured browser checks use that candidate's
+managed preview, not the live showcase. Inspect the returned `behavior` failures
+or the registered behavior-check results in `checks`, fix the draft and diff again.
+Keep behavior.json/specs with their owner and use registered checks; a scratchpad
+run against live source cannot verify unapplied changes. After validation, apply
+with `dryRun:false`; ADS revalidates before writing. Dry-run evidence is not saved
+as passing evidence for the live project.
+
+`ads_verify({unit,checks?})` selects checks for current project source; it has no
+draft argument. There is no dedicated selected-check runner for drafts yet.
+Use a dry-run transaction for genuinely coupled draft patches.
+
+Behavior-run performance belongs to both orchestration and project checks. ADS
+selects affected owners, filters registered Playwright case tags and shares one
+candidate host per run. The project owns assertions, browser setup, worker count,
+per-test timeouts and its profile's whole-run `timeoutMs`. The latter covers the
+entire runner process, not each test. Do not rewrite APIs, drop guarantees or
+disable checks to fit the budget. Inspect measured durations before tuning it.
+
+During verification, inspect `ads_status.behaviors.progress`; during candidate
+validation, inspect `ads_status.mutations.progress`. These show completed/active/
+pending checks and timings. MCP clients requesting progress also receive updates.
+A timeout retains reported case outcomes and identifies active/unstarted checks;
+it still blocks the mutation. `reportedStatus:"passed"` within an incomplete run
+is diagnostic information, not a passing guarantee. Reports/artifacts under the
+live project's `.ds/verification/` survive candidate cleanup. Uninstrumented custom
+runners may report an unknown execution state instead of claiming a case started.
+
+For independent browser specs, consider a small parallel worker count and measure
+on the target machine. Use separate contexts/pages, independent state and the
+candidate URLs provided by `openBehaviorScenario`; avoid fixed live-server URLs,
+shared mutable fixtures and test-order assumptions. Files can run in parallel;
+tests in one file remain sequential by default. Prefer readiness assertions over
+blanket sleeps. Fake clocks suit timer-only guarantees; keep real time for actual
+gesture/motion/layout guarantees. Project settings belong in guarded configuration
+changes; ADS does not silently raise budgets or override the worker count.
+
+Named barrel imports can narrow affected checks when the project accurately
+declares package `sideEffects`; retain CSS/global effects in that policy. Missing
+or unsupported policies and dynamic/wildcard dependencies stay conservative.
+Do not change the policy merely to suppress verification of real side effects.
+
+For registered measured-geometry style writes, use direct `element.style.transform =
+value` or `element.style.setProperty("--ds-measured-value", value)` with the exact
+file/property boundary. The current guard rejects a style-object alias such as
+`const style = element.style` as an escape; it does not trace the alias to later
+writes. Keep writes explicit when adapting local controller code. This syntax
+constraint is separate from deciding which measured properties belong to the
+controller; it does not authorize unregistered visual writes.
+
 Shared provenance uses the existing `documentation` unit. Read its `filePolicy`
 from `ads_units`: one patch can create `CREDITS.md`, shared `licenses/*.txt` and
 README links together. Conventional root credits/license/notice names support

package/dist/skills/ads-migrate/references/scenarios.md

@@ -18,6 +18,11 @@ recovers missed atomic replacements. Do not touch source to force freshness;
 inspect build diagnostics. Upgrade the project's compiler dependency together
 with MCP when an older reporter lacks source evidence.
 
+Optional static `captureTargets` names CSS selectors within the scenario's App for
+on-demand element screenshots. It grants no render/behavior coverage and no extra
+styling permission. Use [captures.md](captures.md) for current/candidate review,
+target selection, resource reads and storage lifecycle.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.

package/dist/skills/ads-motion/SKILL.md

@@ -52,7 +52,10 @@ also list a `ds.config.json` companion: change only that owner's `inlineStyleFil
 and `boundaries.styleWrites` entries together with its source. Unused permissions
 fail the core checks; do not pre-register a boundary without its implementation.
 Use `dryRun: true` to
-inspect validation; applying re-runs the gates. Fix rejected patches in their
+inspect validation, including affected registered behavior checks on the isolated
+candidate. For a prepared draft, request its diff and dry-run the returned
+`patchFile`; `ads_verify` checks current source and accepts no draft argument.
+Applying re-runs the gates. Fix rejected patches in their
 owner. Use `ads_apply_transaction` for genuinely coupled owner patches;
 never bypass a rejection with direct source writes. Shared styles/helpers use `foundation`, root guides use
 `documentation`, and branding/fonts use their discovered `assets/*` unit.
@@ -64,6 +67,8 @@ stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
 For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
+For on-demand current/candidate screenshots and visual dry-run review, read
+[captures.md](references/captures.md).
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,

package/dist/skills/ads-motion/references/captures.md

@@ -0,0 +1,147 @@
+# On-demand visual captures
+
+Use captures when reviewing appearance or a proposed visual change. Discover exact
+scenario IDs with `ads_scenarios`; these are project-owned independently mountable
+token, component, pattern and composition views. A component export alone is not
+a renderable fixture. Controllers/hooks need a scenario demonstrating their visible
+effects. ADS never supplies library-specific renderers, fixtures or capture targets.
+
+## Capture current source
+
+```js
+ads_capture({
+  scenario: "components/Example",
+  theme: "dark",
+  viewport: { width: 1280, height: 800 }
+})
+```
+
+The ID above is illustrative; use one returned by discovery. The default is light
+theme at 1280 × 800 CSS pixels. Capture uses the real sandboxed MCP App with the
+requested viewport and excludes showcase navigation. The default image records
+the complete widget viewport, including its current scroll/state; it does not
+automatically stitch every scroll position into one image.
+
+ADS starts an isolated showcase/compiler and an owned browser process, using the
+connected project's installed `@playwright/test` or `playwright`. It installs no
+dependency/browser. Chromium is the default; optional project configuration is:
+
+```json
+{
+  "mcp": {
+    "capture": {
+      "browser": "chromium",
+      "channel": "chrome",
+      "timeoutMs": 60000
+    }
+  }
+}
+```
+
+Omit `channel` to use Playwright's installed Chromium. Firefox and WebKit are also
+accepted browser choices; channel is Chromium-only. The registered browser must
+be installed locally. This budget bounds the capture runner, including preview
+readiness. Capture does not run the project's entire Playwright suite or require a
+behavior manifest. Readiness uses the App bridge, fonts and settled image loads,
+not `networkidle` (MCP maintains live connections).
+
+## Capture a named element
+
+Declare selectors in the scenario's static metadata:
+
+```tsx
+export const scenario = {
+  title: "Example",
+  covers: ["Example"],
+  captureTargets: {
+    control: '[data-testid="example-control"]'
+  }
+};
+```
+
+Use attributes/selectors already owned by the real UI or its public review pattern.
+Scenarios keep their existing styling/control rules. A target is not permission
+to add demo-only product props, custom CSS or synthetic native controls. Each
+selector is scoped to the App iframe and must match exactly one visible element.
+Select it with `ads_capture({scenario:"<discovered ID>",target:"control"})`.
+`captureTargets` allows up to 20 named CSS selectors. Unknown, hidden, ambiguous
+or unrenderable targets fail explicitly; ADS does not guess a substitute element.
+Arrange a specific interaction state through the scenario's real fixture/adapter;
+capture itself accepts no arbitrary browser script or click sequence.
+
+Screenshots hide the text caret and disable animations by default. Set
+`animations:"allow"` when motion must remain active, and account for nondeterminism.
+The same capture settings are used for both sides of a candidate comparison.
+
+## Review a patch without applying it
+
+Prepare/diff an owner draft normally, then request screenshots during its guarded
+dry run:
+
+```js
+ads_apply_patch({
+  unit: "components/Example",
+  patchFile: ".ds/patches/<returned-name>.patch",
+  dryRun: true,
+  screenshot: true,
+  captures: [{ scenario: "components/Example", target: "control", theme: "light" }]
+})
+```
+
+The placeholder owner/ID/path must come from discovery/preparation. Transactions
+accept the same `screenshot`/`captures` fields. Select 1–8 distinct scenario/target
+pairs explicitly; do not capture every affected scenario by default. Ordinary dry
+runs and patches create no screenshots. `screenshot:true` requires `dryRun:true`.
+
+Core, registered lint/project and affected behavior gates pass first. ADS then
+captures current source and the isolated candidate under matching theme, viewport,
+animation and browser settings. Candidate screenshots survive candidate-directory
+cleanup. Final source/conflict checks still run before the pair is published. A
+failed/cancelled capture does not replace existing image slots or apply source.
+If a scenario/target is newly introduced, `current` is null with an explicit
+`currentAbsent` explanation; only the real candidate image exists.
+
+Review the returned images and diagnostics, fix the draft if necessary, then apply
+with `dryRun:false`. Apply reruns all gates. An image is promoted only when the
+accepted source revision matches the captured candidate; other proposals remain
+stale. Images do not approve a patch or certify interaction/accessibility/parity.
+
+## Two slots, no automatic history
+
+The stable capture key identifies the scenario and optional named target. Theme,
+viewport and revision are metadata, not additional resource identities.
+
+| Successful operation | Result for that target |
+| --- | --- |
+| Standalone `ads_capture` | Fresh current; any earlier candidate removed |
+| Screenshot-enabled dry run | Fresh current + candidate; replaces the old pair |
+| Apply matching proposed source | Candidate becomes current; candidate slot cleared |
+| `ads_capture_clear({scenario,target?,candidateOnly:true})` | Discard candidate, retain current when present |
+| `ads_capture_clear({scenario,target?})` | Remove both slots |
+| Remove scenario/target | Orphan images collected on resource refresh/discovery |
+
+No previous slot, revision history or TTL is kept. Later source changes mark
+images stale rather than silently recapturing them. New proposals replace the
+candidate. Three limits keep storage bounded: at most 4 MiB per PNG, 8 megapixels
+per image and 256 MiB total capture storage. Clear unneeded targets if the store
+reaches its limit. Viewport dimensions range from 100 to 4096 pixels per axis,
+subject to the pixel limit.
+
+## Read resources and freshness
+
+`ads://project/captures` lists existing slots and metadata. Each returned image URI
+uses the template `ads://captures/{key}/{slot}`, with `slot` current or candidate.
+Read the exact returned URI through MCP `resources/read` (or the host's resource
+tool). The result is `image/png` with binary `blob`, not a filesystem or browser
+URL. Use the client's image/resource viewer; do not paste base64 into model text.
+
+Capture metadata records source/build revision, fixture owner file, settings,
+capture time, PNG dimensions/digest and candidate proposal identity. Current is
+stale when its source revision differs; a candidate becomes stale when its base
+source changes. Static freshness does not prove external/live fixture data stayed
+identical. Subscribe to the index and image URIs for `resources/updated`, including
+candidate removal; explicitly reread when the host does not deliver notifications.
+Absent/cleared slots return a resource-not-found diagnostic, not an old image.
+The resource catalogue exposes one index and an image URI template, avoiding a
+resource-list entry for every new revision. Images stay as generated development
+data under `.ds/captures/`; none belongs in product bundles or source patches.