@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.
- package/dist/atomic-composition.mjs +1 -1
- package/dist/behaviors.mjs +5 -5
- package/dist/bootstrap-ds/ADS.md +2 -2
- package/dist/bootstrap-ds/README.md +1 -1
- package/dist/bootstrap-ds/design-system/index.ts +0 -1
- package/dist/bootstrap-ds/design-system/review/index.ts +1 -0
- package/dist/bootstrap-ds/design-system/tokens/Foundation.scenario.tsx +1 -1
- package/dist/bootstrap-ds/ds.config.json +1 -1
- package/dist/bootstrap-ds/tsconfig.json +18 -3
- package/dist/bootstrap-ds/vite.config.ts +1 -1
- package/dist/boundaries.mjs +4 -2
- package/dist/check.mjs +49 -15
- package/dist/config.mjs +13 -2
- package/dist/init.mjs +17 -14
- package/dist/investigations.mjs +34 -3
- package/dist/layers.mjs +288 -0
- package/dist/linaria/preserve-values.cjs +21 -2
- package/dist/lint-config.mjs +1 -1
- package/dist/mcp/behavior-pages.mjs +36 -0
- package/dist/mcp/context.mjs +5 -2
- package/dist/mcp/edit-preparation.mjs +3 -3
- package/dist/mcp/execution-results.mjs +146 -0
- package/dist/mcp/mutations.mjs +4 -4
- package/dist/mcp/prompts.mjs +1 -1
- package/dist/mcp/result-pages.mjs +87 -0
- package/dist/mcp/server.mjs +49 -30
- package/dist/mcp/widget.bundle.js +1 -1
- package/dist/oxlint.mjs +3 -1
- package/dist/preview-resources.mjs +11 -1
- package/dist/property-registrations.mjs +39 -0
- package/dist/public-api.mjs +13 -6
- package/dist/scenario-trace.mjs +7 -7
- package/dist/scenarios-vite.mjs +2 -1
- package/dist/scenarios.mjs +10 -7
- package/dist/scoped-tokens.mjs +6 -0
- package/dist/showcase/client.bundle.js +1 -1
- package/dist/showcase/sandbox.bundle.js +1 -1
- package/dist/skills/ads-break-ui/SKILL.md +27 -10
- package/dist/skills/ads-break-ui/references/atomic-styles.md +48 -0
- package/dist/skills/ads-break-ui/references/captures.md +6 -1
- package/dist/skills/ads-break-ui/references/evidence.md +52 -5
- package/dist/skills/ads-break-ui/references/guarded-editing.md +9 -6
- package/dist/skills/ads-break-ui/references/layers.md +123 -0
- package/dist/skills/ads-break-ui/references/review.md +96 -0
- package/dist/skills/ads-break-ui/references/scenarios.md +24 -3
- package/dist/skills/ads-designer/SKILL.md +28 -11
- package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md +2 -2
- package/dist/skills/ads-designer/assets/bootstrap-ds/README.md +1 -1
- package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/index.ts +0 -1
- package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/review/index.ts +1 -0
- package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/Foundation.scenario.tsx +1 -1
- package/dist/skills/ads-designer/assets/bootstrap-ds/ds.config.json +1 -1
- package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.json +18 -3
- package/dist/skills/ads-designer/assets/bootstrap-ds/vite.config.ts +1 -1
- package/dist/skills/ads-designer/references/atomic-styles.md +48 -0
- package/dist/skills/ads-designer/references/captures.md +6 -1
- package/dist/skills/ads-designer/references/evidence.md +52 -5
- package/dist/skills/ads-designer/references/guarded-editing.md +9 -6
- package/dist/skills/ads-designer/references/layers.md +123 -0
- package/dist/skills/ads-designer/references/review.md +96 -0
- package/dist/skills/ads-designer/references/scenarios.md +24 -3
- package/dist/skills/ads-import/SKILL.md +27 -10
- package/dist/skills/ads-import/references/atomic-styles.md +48 -0
- package/dist/skills/ads-import/references/captures.md +6 -1
- package/dist/skills/ads-import/references/evidence.md +52 -5
- package/dist/skills/ads-import/references/guarded-editing.md +9 -6
- package/dist/skills/ads-import/references/layers.md +123 -0
- package/dist/skills/ads-import/references/review.md +96 -0
- package/dist/skills/ads-import/references/scenarios.md +24 -3
- package/dist/skills/ads-migrate/SKILL.md +27 -10
- package/dist/skills/ads-migrate/references/atomic-styles.md +48 -0
- package/dist/skills/ads-migrate/references/captures.md +6 -1
- package/dist/skills/ads-migrate/references/evidence.md +52 -5
- package/dist/skills/ads-migrate/references/guarded-editing.md +9 -6
- package/dist/skills/ads-migrate/references/layers.md +123 -0
- package/dist/skills/ads-migrate/references/review.md +96 -0
- package/dist/skills/ads-migrate/references/scenarios.md +24 -3
- package/dist/skills/ads-motion/SKILL.md +28 -11
- package/dist/skills/ads-motion/references/atomic-styles.md +48 -0
- package/dist/skills/ads-motion/references/audit.md +1 -1
- package/dist/skills/ads-motion/references/captures.md +6 -1
- package/dist/skills/ads-motion/references/evidence.md +52 -5
- package/dist/skills/ads-motion/references/guarded-editing.md +9 -6
- package/dist/skills/ads-motion/references/layers.md +123 -0
- package/dist/skills/ads-motion/references/motion-review.md +35 -0
- package/dist/skills/ads-motion/references/review.md +96 -35
- package/dist/skills/ads-motion/references/scenarios.md +24 -3
- package/dist/units.mjs +17 -14
- package/docs/ADS.md +42 -5
- package/docs/ARCHITECTURE.md +64 -4
- package/docs/BEHAVIORS.md +21 -2
- package/docs/CHANGELOG.md +40 -0
- package/docs/GUIDE.md +3 -2
- package/docs/MCP.md +87 -20
- package/package.json +2 -1
- package/dist/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx +0 -4
- package/dist/bootstrap-ds/design-system/patterns/token-preview/fixture.ts +0 -8
- package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx +0 -4
- package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/fixture.ts +0 -8
- /package/dist/bootstrap-ds/design-system/{patterns → review}/token-preview/TokenPreview.tsx +0 -0
- /package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/{patterns → review}/token-preview/TokenPreview.tsx +0 -0
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
312
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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` |
|
|
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
|
-
| `
|
|
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
|
|
197
|
-
detail.
|
|
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
|
-
|
|
253
|
-
|
|
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
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
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,
|
|
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
|
|
428
|
-
|
|
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
|
|
467
|
-
|
|
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
|
|
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.
|
|
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",
|
|
File without changes
|