@reqvire-org/ads 0.3.17 → 0.3.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/dist/atomic-composition.mjs +1 -1
  2. package/dist/behaviors.mjs +5 -5
  3. package/dist/bootstrap-ds/ADS.md +2 -2
  4. package/dist/bootstrap-ds/README.md +1 -1
  5. package/dist/bootstrap-ds/design-system/index.ts +0 -1
  6. package/dist/bootstrap-ds/design-system/review/index.ts +1 -0
  7. package/dist/bootstrap-ds/design-system/tokens/Foundation.scenario.tsx +1 -1
  8. package/dist/bootstrap-ds/ds.config.json +1 -1
  9. package/dist/bootstrap-ds/tsconfig.json +18 -3
  10. package/dist/bootstrap-ds/vite.config.ts +1 -1
  11. package/dist/boundaries.mjs +4 -2
  12. package/dist/check.mjs +49 -15
  13. package/dist/config.mjs +13 -2
  14. package/dist/init.mjs +17 -14
  15. package/dist/investigations.mjs +34 -3
  16. package/dist/layers.mjs +288 -0
  17. package/dist/linaria/preserve-values.cjs +21 -2
  18. package/dist/lint-config.mjs +1 -1
  19. package/dist/mcp/behavior-pages.mjs +36 -0
  20. package/dist/mcp/context.mjs +5 -2
  21. package/dist/mcp/edit-preparation.mjs +3 -3
  22. package/dist/mcp/execution-results.mjs +146 -0
  23. package/dist/mcp/mutations.mjs +4 -4
  24. package/dist/mcp/prompts.mjs +1 -1
  25. package/dist/mcp/result-pages.mjs +87 -0
  26. package/dist/mcp/server.mjs +49 -30
  27. package/dist/mcp/widget.bundle.js +1 -1
  28. package/dist/oxlint.mjs +3 -1
  29. package/dist/preview-resources.mjs +11 -1
  30. package/dist/property-registrations.mjs +39 -0
  31. package/dist/public-api.mjs +13 -6
  32. package/dist/scenario-trace.mjs +7 -7
  33. package/dist/scenarios-vite.mjs +2 -1
  34. package/dist/scenarios.mjs +10 -7
  35. package/dist/scoped-tokens.mjs +6 -0
  36. package/dist/showcase/client.bundle.js +1 -1
  37. package/dist/showcase/sandbox.bundle.js +1 -1
  38. package/dist/skills/ads-break-ui/SKILL.md +27 -10
  39. package/dist/skills/ads-break-ui/references/atomic-styles.md +48 -0
  40. package/dist/skills/ads-break-ui/references/captures.md +6 -1
  41. package/dist/skills/ads-break-ui/references/evidence.md +52 -5
  42. package/dist/skills/ads-break-ui/references/guarded-editing.md +9 -6
  43. package/dist/skills/ads-break-ui/references/layers.md +123 -0
  44. package/dist/skills/ads-break-ui/references/review.md +96 -0
  45. package/dist/skills/ads-break-ui/references/scenarios.md +24 -3
  46. package/dist/skills/ads-designer/SKILL.md +28 -11
  47. package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md +2 -2
  48. package/dist/skills/ads-designer/assets/bootstrap-ds/README.md +1 -1
  49. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/index.ts +0 -1
  50. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/review/index.ts +1 -0
  51. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/Foundation.scenario.tsx +1 -1
  52. package/dist/skills/ads-designer/assets/bootstrap-ds/ds.config.json +1 -1
  53. package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.json +18 -3
  54. package/dist/skills/ads-designer/assets/bootstrap-ds/vite.config.ts +1 -1
  55. package/dist/skills/ads-designer/references/atomic-styles.md +48 -0
  56. package/dist/skills/ads-designer/references/captures.md +6 -1
  57. package/dist/skills/ads-designer/references/evidence.md +52 -5
  58. package/dist/skills/ads-designer/references/guarded-editing.md +9 -6
  59. package/dist/skills/ads-designer/references/layers.md +123 -0
  60. package/dist/skills/ads-designer/references/review.md +96 -0
  61. package/dist/skills/ads-designer/references/scenarios.md +24 -3
  62. package/dist/skills/ads-import/SKILL.md +27 -10
  63. package/dist/skills/ads-import/references/atomic-styles.md +48 -0
  64. package/dist/skills/ads-import/references/captures.md +6 -1
  65. package/dist/skills/ads-import/references/evidence.md +52 -5
  66. package/dist/skills/ads-import/references/guarded-editing.md +9 -6
  67. package/dist/skills/ads-import/references/layers.md +123 -0
  68. package/dist/skills/ads-import/references/review.md +96 -0
  69. package/dist/skills/ads-import/references/scenarios.md +24 -3
  70. package/dist/skills/ads-migrate/SKILL.md +27 -10
  71. package/dist/skills/ads-migrate/references/atomic-styles.md +48 -0
  72. package/dist/skills/ads-migrate/references/captures.md +6 -1
  73. package/dist/skills/ads-migrate/references/evidence.md +52 -5
  74. package/dist/skills/ads-migrate/references/guarded-editing.md +9 -6
  75. package/dist/skills/ads-migrate/references/layers.md +123 -0
  76. package/dist/skills/ads-migrate/references/review.md +96 -0
  77. package/dist/skills/ads-migrate/references/scenarios.md +24 -3
  78. package/dist/skills/ads-motion/SKILL.md +28 -11
  79. package/dist/skills/ads-motion/references/atomic-styles.md +48 -0
  80. package/dist/skills/ads-motion/references/audit.md +1 -1
  81. package/dist/skills/ads-motion/references/captures.md +6 -1
  82. package/dist/skills/ads-motion/references/evidence.md +52 -5
  83. package/dist/skills/ads-motion/references/guarded-editing.md +9 -6
  84. package/dist/skills/ads-motion/references/layers.md +123 -0
  85. package/dist/skills/ads-motion/references/motion-review.md +35 -0
  86. package/dist/skills/ads-motion/references/review.md +96 -35
  87. package/dist/skills/ads-motion/references/scenarios.md +24 -3
  88. package/dist/units.mjs +17 -14
  89. package/docs/ADS.md +42 -5
  90. package/docs/ARCHITECTURE.md +64 -4
  91. package/docs/BEHAVIORS.md +21 -2
  92. package/docs/CHANGELOG.md +40 -0
  93. package/docs/GUIDE.md +3 -2
  94. package/docs/MCP.md +87 -20
  95. package/package.json +2 -1
  96. package/dist/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx +0 -4
  97. package/dist/bootstrap-ds/design-system/patterns/token-preview/fixture.ts +0 -8
  98. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx +0 -4
  99. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/fixture.ts +0 -8
  100. /package/dist/bootstrap-ds/design-system/{patterns → review}/token-preview/TokenPreview.tsx +0 -0
  101. /package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/{patterns → review}/token-preview/TokenPreview.tsx +0 -0
@@ -67,6 +67,32 @@ state mechanics. Patterns own reusable layout and composition. Application
67
67
  containers provide domain data, routing, application effects, and callbacks through public
68
68
  APIs.
69
69
 
70
+ A component provides one cohesive UI capability. A pattern arranges capabilities
71
+ into a reusable structure or workflow; a layout part may arrange content slots.
72
+ Components may compose other components/controllers, and patterns may compose
73
+ patterns. Import count, element count and implementation size do not decide the
74
+ layer. Scenarios may compose public UI and development review helpers to demonstrate their
75
+ subject without becoming production patterns.
76
+
77
+ Patterns are production application UI. Development-only framing, demo controls
78
+ and token renderers belong in project-owned `review/`, with a separate
79
+ `reviewEntry` (default `review/index.ts`) and `${publicAlias}/review` import alias.
80
+ They are absent from the product barrel and catalogue. Guards reject production
81
+ dependencies on review code, types and styles; review source keeps normal styling,
82
+ token and public product-contract checks. Scenarios exercise the real production
83
+ implementation through fixtures. The [portable review guide](../skills/ads-designer/references/review.md)
84
+ defines guarded owners, build isolation and migration steps. Review rendering
85
+ stays inside the App iframe; it adds no project execution to the host shell.
86
+
87
+ Core guards reject component runtime dependencies on patterns/composition through
88
+ resolved imports, re-exports and helpers. Patterns consume public component
89
+ contracts rather than private implementation symbols or rendered style hooks;
90
+ documented non-state customization variables remain available. Source tracing
91
+ distinguishes styling a private part from reading ancestor context for the
92
+ pattern's own arrangement. Application and development dependencies retain their
93
+ separate boundaries. The portable skill-local [layer guide](../skills/ads-designer/references/layers.md)
94
+ explains repairs and analysis limits; semantic classification still needs review.
95
+
70
96
  The Data pillar describes design values; business data is a separate input to
71
97
  the UX contract. Application adapters own live business-data loading,
72
98
  authentication, stores, routing, caching and refresh policy. Components and
@@ -155,6 +181,19 @@ values; source guards alone cannot establish extraction correctness. The
155
181
  skill-local [atomic styling guide](../skills/ads-designer/references/atomic-styles.md#preserve-custom-property-arithmetic-during-extraction)
156
182
  documents integration and source-workaround semantics.
157
183
 
184
+ The resolver also preserves complete `@property` registrations and their
185
+ conditional at-rule context for atomic `css`/`styled`. Their descriptors are schema
186
+ metadata, not separate atomic declarations. CSS-tree validates CSS value grammar;
187
+ PostCSS supplies source/at-rule structure. Registered names have one owner and a
188
+ stable schema across its modules, because registration is document-global. Runtime
189
+ variables are registered in owned Linaria; shared or namespaced design tokens are
190
+ registered beside their real value definitions. Base resets and fonts cannot own
191
+ registrations. Descriptor literals are narrowly permitted where CSS requires an
192
+ independent initial value; ordinary visual assignments remain token-governed.
193
+ MCP serves these styles to the sandboxed App document. Registration metadata
194
+ neither creates new token definitions nor replaces token sample coverage.
195
+ Compiled-CSS and browser tests verify interpolation in React and Preact Apps.
196
+
158
197
  ## Public APIs preserve the boundary
159
198
 
160
199
  The application and project-owned preview scenarios consume a project's public ADS entry. Components
@@ -220,6 +259,13 @@ external bases still require declared CSP origins. This belongs to document
220
259
  loading and changes no project link or scenario handler. External hosts control
221
260
  their own document-loading and CSP behavior.
222
261
 
262
+ The proxy and App sandbox permit native forms (`allow-forms`), including the
263
+ legacy nested widget. This lets browser constraint validation and `submit`
264
+ handlers run for clicks, Enter and `requestSubmit()`. Client-side handlers retain
265
+ their own `preventDefault()` behavior. The App stays opaque; CSP
266
+ `form-action 'none'` blocks native action requests without suppressing submit
267
+ handlers. Hosts outside ADS choose their own sandbox and CSP permissions.
268
+
223
269
  The project compiler publishes a versioned dependency graph: shared runtime and
224
270
  foundation assets, plus independently addressable scenario modules. Inside the
225
271
  App, a resource loader obtains the selected dependency closure through MCP,
@@ -289,12 +335,12 @@ real public implementation. It mounts independently, without opening a showcase
289
335
  page or initializing the application's router, store or services first.
290
336
 
291
337
  Scenarios and their fixtures live beside the tokens, component or pattern they exercise.
292
- Demo framing belongs to public review/layout patterns; component props describe
338
+ Demo framing belongs to development-only review helpers; component props describe
293
339
  intentional product behavior and visual variants.
294
340
  Token scenarios choose real token names and sample inputs; a project-owned
295
- review pattern applies the foundation variables. The tool contains no project
341
+ review renderer applies the foundation variables. The tool contains no project
296
342
  token list, sample templates or assumed visual identity. Even an initial token
297
- scenario uses a public project-owned review pattern to apply its declared samples;
343
+ scenario uses a project-owned development review renderer to apply its declared samples;
298
344
  a definitions-only inspector does not establish preview coverage.
299
345
  Larger scenarios live under `composition/`. They use the same public screen
300
346
  patterns as production: application adapters supply live data and effects;
@@ -445,6 +491,20 @@ Another run replaces that check's resource access; candidate evidence never
445
491
  certifies live source. Detailed usage lives in the portable skill-local
446
492
  [evidence guide](../skills/ads-designer/references/evidence.md).
447
493
 
494
+ MCP delivery is separate from validation: verification and mutation controllers
495
+ use complete results to decide acceptance. Their MCP replies contain counts,
496
+ bounded acceptance, at most three failure previews and a result ID in at most
497
+ 4 KiB of UTF-8 JSON. `ads_results` reads saved outcomes, diagnostics and other
498
+ sections without rerunning checks. Pages have at most 20 rows and 8 KiB of JSON;
499
+ truncated records support bounded text ranges. Discovery and investigation
500
+ sections use the same paging budget. Cursors bind the query and result/revision;
501
+ superseded IDs fail explicitly instead of silently returning another run.
502
+ Only the latest verification and mutation snapshots are retained, each at most
503
+ 8 MiB under `.ds/tool-results/`. Oversized reports retain a summary with an
504
+ explicit unavailable-details warning. Storage/notification failure cannot change
505
+ an accepted edit's applied state. These are payload byte budgets, not tokenizer
506
+ estimates; MCP compatibility text may duplicate structured JSON on the wire.
507
+
448
508
  Edits stay focused without requiring entire file bodies in model context. Peer units and
449
509
  unrelated owners remain outside the selected unit's edit boundary. Shared foundation,
450
510
  branding and guides have their own units. Shared credits and text license notices
@@ -511,7 +571,7 @@ For concrete instructions, use:
511
571
 
512
572
  Token preview completeness has two checks. Static guards require explicit fixture
513
573
  bindings (`token`, CSS `property`, and project-selected `probe`) consumed by a public
514
- review pattern. The App then verifies rendered samples in the actual browser by
574
+ review renderer. The App then verifies rendered samples in the actual browser by
515
575
  probing those bindings and restoring them. The tool supplies no token/property
516
576
  classification or visual sample palette. A source build alone is not a rendered
517
577
  verification, and the browser check does not judge design quality.
package/docs/BEHAVIORS.md CHANGED
@@ -308,8 +308,20 @@ Guarantees report passing only when all their checks have current passing eviden
308
308
  Passing applies to those cases and profiles, not every application state.
309
309
 
310
310
  Results expose structured `failure` boundaries and explicit `acceptance` scope.
311
- Use `ads_investigate({unit,check})` for the latest compact investigation, including
312
- isolated dry runs; `ads://project/investigations` lists available entries. Exact
311
+ MCP execution replies contain counts, bounded acceptance, at most three failure
312
+ previews and a `resultId` (4 KiB UTF-8 JSON maximum). Use `ads_results` to read
313
+ selected `outcomes`, `checks`, `diagnostics` or other sections without execution.
314
+ Pages default to 10 rows, allow at most 20 and stay within 8 KiB; follow
315
+ `nextCursor` with identical selection/status. Truncated records provide
316
+ `recordIndex` for exact `offset`/`chars` ranges. Only the latest verification and
317
+ mutation snapshots are retained, independently, at most 8 MiB each. Replaced IDs
318
+ fail explicitly. Validation still uses complete internal outcomes.
319
+
320
+ Use `ads_investigate({unit,check,runId})` with an outcome's exact IDs for its compact
321
+ summary (4 KiB maximum); details, requests, browser errors and artifact metadata are separate
322
+ paged sections (8 KiB maximum). Truncated records support exact text ranges with
323
+ the recorded run ID. Saved outcomes describe completion time; compare current
324
+ `ads_behaviors` revisions for freshness. It includes isolated dry runs; `ads://project/investigations` lists available entries. Exact
313
325
  input and observed preview revisions, failing step/source, startup viewport,
314
326
  failed startup requests and available project-recorded artifacts keep diagnosis
315
327
  separate from an inferred component defect. No artifact is invented or test
@@ -354,3 +366,10 @@ Keep ESM modules and explicit imports. Avoid an eagerly imported controller
354
366
  registry. Tree shaking and shared chunks follow the project bundler: class methods,
355
367
  side effects, global CSS and dynamic maps can retain extra code. Inspect emitted
356
368
  resources instead of assuming a controller produces a minimal bundle.
369
+
370
+ Development-only `review/<Owner>` units may register the same guarantee/check
371
+ contracts for review presentation and controls. Subjects can name that owner's
372
+ separate review API or local headless helpers; checks still run registered project
373
+ profiles and can refer to an existing real scenario. This grants no production
374
+ API, catalogue entry, `covers` credit or runtime import permission. See the
375
+ [portable review guide](../skills/ads-designer/references/review.md).
package/docs/CHANGELOG.md CHANGED
@@ -1,5 +1,45 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased
4
+
5
+ ## 0.3.20
6
+
7
+ - Preserve the motion-review checklist separately from the development review-layer
8
+ guide; both remain self-contained in the motion skill. Version 0.3.19 was tagged
9
+ but publication was cancelled before this correction.
10
+
11
+ - Separate project-owned review UI from production patterns. Add `review/` owners,
12
+ a configurable development entry and derived `/review` alias, guarded companion
13
+ exports and review contracts. Preserve real component/token render evidence,
14
+ block production imports and verify review assets stay out of product bundles.
15
+ Move the working showcase and empty starter helpers to the new layer; publish
16
+ self-contained migration guidance in all skills and `ads://guides/review`.
17
+ - Enable native form validation and submit events across the showcase, diagnostic
18
+ explorer and legacy App iframe layers. Retain opaque App origins and block
19
+ native action requests through CSP. Cover click/Enter submission, custom/native
20
+ validation and no-network behavior in generic React, Preact and HTML Apps.
21
+ - Enforce runtime component dependency direction and public component contracts
22
+ for patterns through aliases, re-exports and helpers. Reject proven private
23
+ style-hook/variable access while preserving ancestor-context layout and documented
24
+ customization. Publish portable layer guidance in every skill and through MCP.
25
+
26
+ ## 0.3.18
27
+
28
+ - Preserve complete typed `@property` registrations through atomic css/styled
29
+ extraction, conditional rules and CSS minification. Validate descriptors with
30
+ CSS-tree, enforce runtime/token ownership and naming conflicts, and retain
31
+ ordinary style-token gates. Verify dummy interpolation in React/Preact MCP Apps.
32
+ - Sync all skill references for registrations and selector-owned native
33
+ composition; keep implementation independent of any imported component library.
34
+
35
+ - Deliver verification and guarded-edit replies as 4 KiB JSON summaries with
36
+ counts, acceptance and result IDs. Page outcomes, diagnostics, logs and captures
37
+ through `ads_results`; retain only the latest verification and mutation snapshots.
38
+ Keep complete internal validation independent of delivery.
39
+ - Page behavior discovery and investigation details; bind cursors to their query
40
+ and recorded run, reject superseded evidence, and document selective retrieval
41
+ in every portable skill. Keep artifacts separate from tool JSON.
42
+
3
43
  ## 0.3.17
4
44
 
5
45
  - Recognize native semantic composition through source-verified runtime Linaria
package/docs/GUIDE.md CHANGED
@@ -495,10 +495,10 @@ export default function Scenario() { return <Button>{fixture.label}</Button>; }
495
495
  IDs derive from filenames; do not maintain another registry or hand-assigned IDs.
496
496
  Token scenarios live beside foundation CSS under the configured token directory.
497
497
  The starter includes `tokens/Foundation.scenario.tsx` and its local fixture for
498
- a project-owned token review pattern. Keep its presentation in that pattern:
498
+ a project-owned token review renderer. Keep its presentation in that pattern:
499
499
 
500
500
  ```tsx
501
- import { TokenSamples } from "@ds";
501
+ import { TokenSamples } from "@ds/review";
502
502
  import { fixture } from "./Typography.fixture";
503
503
  export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };
504
504
  export default function Scenario() { return <TokenSamples {...fixture} />; }
@@ -723,6 +723,7 @@ inspection errors fail the check. These guards read files and never delete them.
723
723
  "dsDir": "design-system",
724
724
  "publicAlias": "@ds",
725
725
  "publicEntry": "index.ts",
726
+ "reviewEntry": "review/index.ts",
726
727
  "stylesEntry": "styles.css",
727
728
  "tokenDir": "tokens",
728
729
  "inlineStyleFiles": [],
package/docs/MCP.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # ADS over MCP
2
2
 
3
+ For component/pattern classification and dependency/style boundary diagnostics,
4
+ read `ads://guides/layers`. A component supplies one cohesive UI capability; a
5
+ pattern arranges capabilities into reusable structures/workflows. Guards enforce
6
+ resolved ownership boundaries, not component counts. Scenarios may compose public
7
+ UI to demonstrate their subject; application adapters own store access and routing.
8
+
3
9
  `ads mcp [directory]` serves a project's local design system over stdio. It uses
4
10
  the same `ds.config.json`, token inspection and core checks as the CLI. It reads
5
11
  source and build artifacts. Optionally it manages one configured project
@@ -54,15 +60,21 @@ managed project compiler on demand and after relevant source changes.
54
60
  Switching entries overlays a centered loading spinner, then reveals the new
55
61
  scenario inside the existing App. Loading and diagnostic overlays do not move the
56
62
  preview. Token presentation comes from project-owned scenarios, fixtures and
57
- public review patterns, using the project's real foundation CSS and extracted
63
+ development-only review helpers, using the project's real foundation CSS and extracted
58
64
  styles. The App runtime contains no token sample templates or named token ordering.
59
65
  The generic definition inspector remains available without a scenario build.
60
66
 
61
67
  There are no required browser-page files in the project. Colocated scenarios and
62
- fixtures, optional public review-layout patterns, and the project's compiler
68
+ fixtures, optional development-only review helpers, and the project's compiler
63
69
  entry supply the presentation. Use the existing runtime URL when MCP is connected
64
70
  instead of starting a second compiler for that project.
65
71
 
72
+ Development review UI lives in `review/`, behind a separate development entry;
73
+ production patterns remain application UI. Discover `ads_status.project.review`
74
+ and read `ads://guides/review` for imports, guarded owners and migration. Review
75
+ exports are not product catalogue entries. They can frame real scenarios and
76
+ render token samples without entering the deployed application's graph.
77
+
66
78
  ## Connect Codex or Claude
67
79
 
68
80
  Use the published package through `npx`. No ADS checkout or global installation
@@ -175,9 +187,10 @@ The server supplies agent guidance through its instructions, tool descriptions,
175
187
  | `ads_show_tokens` | Render a discovered token scenario; legacy compilers retain the definition inspector |
176
188
  | `ads_scenarios` | Bounded token/component/pattern/composition scenario discovery |
177
189
  | `ads_show_scenario` | Render an exact discovered scenario with its own fixtures |
178
- | `ads_behaviors` | Bounded guarantee/evidence discovery; pass an exact unit for contract details |
190
+ | `ads_behaviors` | Paged owner discovery; select a unit and detail section |
179
191
  | `ads_verify` | Execute an owner's registered checks and record revision-bound evidence |
180
- | `ads_investigate` | Read one check's latest compact failure/evidence bundle without rerunning it |
192
+ | `ads_results` | Page saved execution outcomes, diagnostics, logs and captures without rerunning |
193
+ | `ads_investigate` | Read one check's summary, then paged requests/errors/artifacts |
181
194
  | `ads_capture` | On-demand PNG of a discovered scenario or named element; replace current and clear candidate |
182
195
  | `ads_capture_clear` | Remove generated captures or discard only the candidate |
183
196
  | `ads_show_<id>` | Optional explicitly configured grouped App |
@@ -193,8 +206,9 @@ public exports from `components/`, `patterns/` and `controllers/`; it does not e
193
206
  guess component props. Read the exported API and owning guide. An export name
194
207
  alone does not prove that a preview renders that particular element.
195
208
 
196
- `ads://project/status`, `/build`, `/tokens`, `/catalog`, `/scenarios`, `/behaviors`, and `/checks` carry complete JSON
197
- detail. Allowed project documentation/source and skill files are separate
209
+ `ads://project/status`, `/build`, `/tokens`, `/catalog`, `/scenarios` and `/checks`
210
+ carry project JSON detail. Behavior discovery, execution outcomes and investigation
211
+ details are paged; their resource reads use the same bounds as their tools. Allowed project documentation/source and skill files are separate
198
212
  resources. No arbitrary filesystem reader is exposed. Prefer bounded tools for
199
213
  large catalogues; explicit resource reads can enter model context and a client
200
214
  may truncate large payloads.
@@ -215,6 +229,14 @@ informational limit nor a traced target proves a rendered failure or success.
215
229
  Bounded check results put warnings before informational limits; the checks
216
230
  resource retains complete results.
217
231
 
232
+ `property-registration` is a blocking architecture diagnostic for invalid or
233
+ conflicting typed CSS registrations. Keep registrations in their runtime owner
234
+ or beside their real token definitions; `base.css` remains a closed reset contract.
235
+ Use `@reqvire-org/ads/linaria` in both product and preview extraction so each
236
+ registration survives intact in the App's CSS resources. Descriptor literals are
237
+ metadata; normal styling still uses tokens. Read `ads://guides/atomic-styles` for
238
+ ownership, valid initial values, browser checks and examples.
239
+
218
240
  ### Screenshots and candidate comparison
219
241
 
220
242
  `ads_capture({scenario:"<discovered ID>",target?,theme?,viewport?})` renders current
@@ -249,8 +271,10 @@ limits, target declarations and the guarded review workflow.
249
271
 
250
272
  Read `ads://guides/behaviors` or the [behavior guide](BEHAVIORS.md) for the contract
251
273
  and runner schema. `ads_behaviors({ "unit": "components/MessageScroller" })`
252
- returns subjects, guarantees, demonstration links and check IDs for a discovered
253
- owner. `ads_verify({ "unit": "components/MessageScroller", "checks": ["prepend-anchor"] })`
274
+ pages an owner's checks by default; select `section: "subjects"`, `"guarantees"`,
275
+ `"demonstrations"` or `"profiles"` for other details. Without a unit it lists owner
276
+ summaries. Follow `nextCursor` with identical filters. Changed registrations or
277
+ evidence revisions invalidate discovery cursors. `ads_verify({ "unit": "components/MessageScroller", "checks": ["prepend-anchor"] })`
254
278
  runs those registered cases. The names here are examples, never built-in cases.
255
279
 
256
280
  `covers` describes rendered UI; optional `exercises` describes public behavioral
@@ -276,14 +300,47 @@ single failed assertion does not turn the other checks into failures. Overall
276
300
  verification and guarded application still fail. Suite errors, unexplained exits,
277
301
  missing results and interrupted reports cannot certify passing checks.
278
302
 
279
- For diagnosis, call `ads_investigate({ "unit": "components/Example", "check": "keyboard-navigation" })`
280
- with discovered IDs. It reads the latest check bundle without rerunning anything,
281
- including rejected candidates. `ads://project/investigations` lists available
282
- bundles; returned resource URIs expose the bundle and available registered
303
+ Verification and guarded-edit replies are summaries: counts, acceptance, at most
304
+ three failure previews and `resultId`, within 4096 UTF-8 JSON bytes. Use:
305
+
306
+ ```js
307
+ ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed"})
308
+ ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed", cursor: "<nextCursor>"})
309
+ ```
310
+
311
+ Each listing defaults to 10 rows, allows at most 20 and stays within 8192 JSON
312
+ bytes. A byte-limited page can contain fewer than `limit` rows; follow
313
+ `nextCursor` with the same result ID, section and status. Other sections are
314
+ `checks`, `advisories`, `warnings`, `changes`, `captures`, `acceptance`,
315
+ `investigation` and `selection`. No page reruns validation. Rows marked
316
+ `detailTruncated` can be read exactly with `recordIndex`, `offset` and `chars`
317
+ (maximum 2000 UTF-16 characters); follow `nextOffset`. Read full logs only for the
318
+ relevant record. JSON also remains available through `ads://results/<resultId>`;
319
+ use matching query parameters for pages or ranges. `ads://project/results` lists
320
+ the latest IDs. Status embeds summaries, not complete runner reports. Saved
321
+ outcomes are completion-time evidence; compare revisions with `ads_behaviors`
322
+ before claiming current source passed.
323
+
324
+ Only the latest verification snapshot and latest mutation snapshot are retained,
325
+ independently, each up to 8 MiB in `.ds/tool-results/`. Replacing a snapshot makes
326
+ its old ID unavailable; do not mix pages across runs. An oversized report retains
327
+ only its summary and an explicit unavailable-details warning. A failed disk write
328
+ keeps details in server memory until shutdown. Neither condition changes guard
329
+ acceptance or whether source was applied. These are logical payload byte limits;
330
+ compatibility text can duplicate structured JSON in the MCP response.
331
+
332
+ For diagnosis, take one outcome's exact `unit`, `check` and `runId` and call
333
+ `ads_investigate`. The run ID rejects superseded evidence. Without a check, it
334
+ lists available investigations with paging. An exact check returns a summary
335
+ within 4096 JSON bytes; `section: "details"`, `"requests"`, `"browserErrors"` or `"artifacts"`
336
+ returns detail pages with the same 10/20-row and 8192-byte limits. Truncated records support
337
+ `recordIndex`/`offset`/`chars` with the exact `runId`; artifact URIs are read
338
+ separately. It never reruns checks, including rejected candidates.
339
+ `ads://project/investigations` lists available bundles; returned resource URIs expose the bundle and available registered
283
340
  artifacts. Exact input/observed preview revisions, source/failing step, startup
284
341
  viewport and failed requests separate evidence from a suspected cause.
285
- `failure.category` distinguishes architecture, build, transport, runner and
286
- assertion boundaries; `acceptance` names established and unverified scope.
342
+ The summary's `details.failure.category` distinguishes architecture, build,
343
+ transport, runner and assertion boundaries; `acceptance` names established and unverified scope.
287
344
  Only the latest bundle per check remains resource-accessible. Read the portable
288
345
  [evidence guide](../skills/ads-designer/references/evidence.md) for collection
289
346
  limits and project-controlled trace/screenshot recording.
@@ -352,6 +409,7 @@ The same discovery covers the rest of the project ADS:
352
409
 
353
410
  | Unit | Scope |
354
411
  |------|-------|
412
+ | `review/<Owner>` | Development-only frames, token renderers, demo controls, local checks and review-entry re-exports |
355
413
  | `foundation` | Shared ADS entry styles and root helpers |
356
414
  | `documentation` | ADS/project guides, shared credits and license notices, and `licenses/` text collections |
357
415
  | `assets/brand`, `assets/fonts`, other `assets/*` groups | Original SVG, image, font and other asset files |
@@ -424,8 +482,9 @@ Pass that `patchFile` to `ads_apply_patch` with `dryRun:true` to validate before
424
482
  applying. This runs the normal candidate gates, including affected registered
425
483
  behavior checks against an isolated candidate and its configured browser preview.
426
484
  It writes no live source and does not persist passing evidence for live inputs.
427
- Read returned `behavior` failures or behavior-check results in `checks`; update the
428
- draft, diff again and repeat as needed. Apply with `dryRun:false` after validation;
485
+ Read the summary, then use its `resultId` with `ads_results` for failing
486
+ `outcomes`, `diagnostics` or named pipeline `checks`; update the draft, diff again
487
+ and repeat as needed. Apply with `dryRun:false` after validation;
429
488
  the gates run again. `ads_verify({unit,checks?})` checks current source and accepts
430
489
  no draft argument; a selected-check draft runner is not currently exposed.
431
490
  Use `action:"discard"` to remove the draft. Remote clients can continue sending
@@ -463,8 +522,8 @@ Install changed dependencies before verification; candidates use the project's
463
522
  installed `node_modules`.
464
523
 
465
524
  Resolve ownership diagnostics by preserving the required capability in its proper
466
- layer. Demo-only sizing, borders and framing belong in a public review/layout
467
- pattern; a component API addition needs a runtime use case. Measured imperative
525
+ layer. Demo-only sizing, borders and framing belong in a development-only review
526
+ helper; a component API addition needs a runtime use case. Measured imperative
468
527
  geometry uses exact `styleWrites` properties. After migrating JSX inline geometry,
469
528
  replace its own boundary entries in the same owner patch and check the final state.
470
529
  After the gates pass, verify the behavior in a browser.
@@ -472,7 +531,7 @@ After the gates pass, verify the behavior in a browser.
472
531
  A small change needs only its hunk. A complete new component may include its
473
532
  implementation, public re-export, scenario and fixture in the same unit patch,
474
533
  so coverage is checked against a complete candidate. New units use a new
475
- `components/`, `patterns/` or `composition/` owner ID following the same colocation
534
+ `components/`, `patterns/`, `controllers/`, `review/` or `composition/` owner ID following the same colocation
476
535
  convention. A patch cannot include a peer unit, capture existing peers beneath
477
536
  a new directory owner, or change unrelated public-entry statements. Shared
478
537
  public-entry changes are limited to re-exports from the selected unit. Alongside
@@ -606,6 +665,14 @@ origin hosts the sandbox proxy; that proxy creates an opaque inner App iframe
606
665
  and forwards the standard Apps bridge messages. The diagnostic explorer follows
607
666
  the same sandbox model. Only the App materializes and executes project resources.
608
667
 
668
+ Both ADS hosts allow native form validation and submission events through all
669
+ iframe layers. Client-side forms use their intended `submit` handlers and
670
+ `preventDefault()`. CSP `form-action 'none'` blocks native action requests;
671
+ `allow-forms` grants neither host DOM access nor top-level navigation. External
672
+ hosts choose their own permissions. See the portable
673
+ [scenario guide](../skills/ads-designer/references/scenarios.md#forms-inside-apps)
674
+ for verification and diagnosis.
675
+
609
676
  For inline documents without an explicit App base URL, ADS supplies
610
677
  `<base href="about:srcdoc">` and permits the local `about:` base scheme in CSP.
611
678
  Bare and named fragment links retain native in-document navigation and state.
@@ -977,7 +1044,7 @@ instruction reads alone do not establish Apps/Skills activation.
977
1044
  ### Token sample verification
978
1045
 
979
1046
  Token scenarios declare `samples: fixture.samples` and render a project-owned public
980
- review pattern with that `samples` input. Each fixture record has `{ token, property,
1047
+ review renderer with that `samples` input. Each fixture record has `{ token, property,
981
1048
  probe }`; the tool discovers the resulting token names. Plain token lists and empty
982
1049
  covers do not satisfy review coverage. The same bindings travel in the compiled
983
1050
  resource manifest or self-contained App seed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@reqvire-org/ads",
3
- "version": "0.3.17",
3
+ "version": "0.3.20",
4
4
  "type": "module",
5
5
  "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
6
6
  "repository": {
@@ -52,6 +52,7 @@
52
52
  },
53
53
  "dependencies": {
54
54
  "@modelcontextprotocol/server": "2.3.1",
55
+ "css-tree": "3.2.1",
55
56
  "postcss": "^8.5.30",
56
57
  "postcss-selector-parser": "^7.1.6",
57
58
  "postcss-value-parser": "^4.2.0",
@@ -1,4 +0,0 @@
1
- import { TokenPreview } from "@ds";
2
- import { fixture } from "./fixture";
3
- export const scenario = { title: fixture.title, covers: ["TokenPreview"] };
4
- export default function Scenario() { return <TokenPreview {...fixture} />; }
@@ -1,8 +0,0 @@
1
- export const fixture = {
2
- "title": "Token preview",
3
- "text": "Aa",
4
- samples: [
5
- {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
6
- {"token": "--space-4", "property": "width", "probe": "13.375px"},
7
- ]
8
- } as const;
@@ -1,4 +0,0 @@
1
- import { TokenPreview } from "@ds";
2
- import { fixture } from "./fixture";
3
- export const scenario = { title: fixture.title, covers: ["TokenPreview"] };
4
- export default function Scenario() { return <TokenPreview {...fixture} />; }
@@ -1,8 +0,0 @@
1
- export const fixture = {
2
- "title": "Token preview",
3
- "text": "Aa",
4
- samples: [
5
- {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
6
- {"token": "--space-4", "property": "width", "probe": "13.375px"},
7
- ]
8
- } as const;