@reqvire-org/ads 0.3.18 → 0.3.21
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/README.md +2 -0
- package/dist/behaviors.mjs +19 -9
- package/dist/bootstrap-ds/ADS.md +2 -2
- package/dist/bootstrap-ds/README.md +2 -2
- 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 → Foundation.ads.scenario.tsx} +2 -2
- package/dist/bootstrap-ds/ds.config.json +1 -1
- package/dist/bootstrap-ds/tsconfig.build.json +9 -2
- package/dist/bootstrap-ds/tsconfig.json +18 -3
- package/dist/bootstrap-ds/vite.config.ts +1 -1
- package/dist/boundaries.mjs +6 -2
- package/dist/check.mjs +44 -17
- package/dist/config.mjs +33 -5
- package/dist/contract-migration.mjs +110 -0
- package/dist/contracts.d.mts +22 -0
- package/dist/evidence.mjs +1 -1
- package/dist/index.mjs +1 -0
- package/dist/init.mjs +18 -15
- package/dist/layers.mjs +288 -0
- package/dist/lint-config.mjs +1 -1
- package/dist/mcp/catalog.mjs +9 -2
- package/dist/mcp/context.mjs +2 -1
- package/dist/mcp/edit-preparation.mjs +9 -6
- package/dist/mcp/mutations.mjs +1 -1
- package/dist/mcp/preview-widget.bundle.js +41 -39
- package/dist/mcp/prompts.mjs +1 -1
- package/dist/mcp/server.mjs +9 -3
- package/dist/mcp/widget.bundle.js +1 -1
- package/dist/oxlint.mjs +3 -1
- package/dist/paint-contracts.mjs +124 -0
- package/dist/preview-resources.mjs +12 -2
- package/dist/public-api.mjs +13 -6
- package/dist/public-props.mjs +2 -2
- package/dist/runtime-contracts.mjs +225 -0
- package/dist/scenario-trace.mjs +37 -9
- package/dist/scenarios-vite.mjs +3 -2
- package/dist/scenarios.mjs +89 -30
- package/dist/scoped-tokens.mjs +9 -4
- package/dist/showcase/client.bundle.js +1 -1
- package/dist/showcase/sandbox.bundle.js +1 -1
- package/dist/skills/ads-break-ui/SKILL.md +25 -6
- package/dist/skills/ads-break-ui/references/contracts.md +250 -0
- package/dist/skills/ads-break-ui/references/guarded-editing.md +1 -1
- 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 +26 -7
- package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md +2 -2
- package/dist/skills/ads-designer/assets/bootstrap-ds/README.md +2 -2
- 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 → Foundation.ads.scenario.tsx} +2 -2
- package/dist/skills/ads-designer/assets/bootstrap-ds/ds.config.json +1 -1
- package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.build.json +9 -2
- 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/contracts.md +250 -0
- package/dist/skills/ads-designer/references/guarded-editing.md +1 -1
- 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 +25 -6
- package/dist/skills/ads-import/references/contracts.md +250 -0
- package/dist/skills/ads-import/references/guarded-editing.md +1 -1
- 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 +25 -6
- package/dist/skills/ads-migrate/references/contracts.md +250 -0
- package/dist/skills/ads-migrate/references/guarded-editing.md +1 -1
- 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 +26 -7
- package/dist/skills/ads-motion/references/audit.md +1 -1
- package/dist/skills/ads-motion/references/contracts.md +250 -0
- package/dist/skills/ads-motion/references/guarded-editing.md +1 -1
- 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/token-origins.mjs +24 -0
- package/dist/tokens.mjs +4 -3
- package/dist/unit-contracts.mjs +203 -0
- package/dist/units.mjs +26 -17
- package/dist/verification/browser.mjs +156 -26
- package/dist/verification/playwright-reporter.cjs +13 -3
- package/docs/ADS.md +40 -6
- package/docs/ARCHITECTURE.md +73 -4
- package/docs/BEHAVIORS.md +15 -0
- package/docs/CHANGELOG.md +42 -0
- package/docs/CONTRACTS.md +250 -0
- package/docs/GUIDE.md +29 -3
- package/docs/MCP.md +42 -6
- package/package.json +4 -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/bootstrap-ds/design-system/tokens/{Foundation.fixture.ts → Foundation.ads.fixture.ts} +0 -0
- /package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/{patterns → review}/token-preview/TokenPreview.tsx +0 -0
- /package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/{Foundation.fixture.ts → Foundation.ads.fixture.ts} +0 -0
package/docs/BEHAVIORS.md
CHANGED
|
@@ -25,6 +25,14 @@ These gates inspect supported direct imports, markup and style boundaries.
|
|
|
25
25
|
External package internals and delegated DOM behavior still require source,
|
|
26
26
|
build and browser review; declaring a dependency does not prove it is headless.
|
|
27
27
|
|
|
28
|
+
New owner registrations can live in `<Owner>.ads.contract.ts` with actual API and
|
|
29
|
+
implementation references; legacy JSON remains supported. The
|
|
30
|
+
[contract reference](CONTRACTS.md) covers static authoring, `.ads.behavior.spec.ts`,
|
|
31
|
+
declarative `exercises`, required browser checks and guarded migration.
|
|
32
|
+
A contract declaration alone is not passing evidence. Use
|
|
33
|
+
`auditBehaviorPaints(frame)` after relevant binding updates to repeat the current
|
|
34
|
+
App's generic paint audit, in addition to assertions for the named guarantee.
|
|
35
|
+
|
|
28
36
|
## Development boundary
|
|
29
37
|
|
|
30
38
|
Production includes real components, controllers, tokens and compiled styles.
|
|
@@ -366,3 +374,10 @@ Keep ESM modules and explicit imports. Avoid an eagerly imported controller
|
|
|
366
374
|
registry. Tree shaking and shared chunks follow the project bundler: class methods,
|
|
367
375
|
side effects, global CSS and dynamic maps can retain extra code. Inspect emitted
|
|
368
376
|
resources instead of assuming a controller produces a minimal bundle.
|
|
377
|
+
|
|
378
|
+
Development-only `review/<Owner>` units may register the same guarantee/check
|
|
379
|
+
contracts for review presentation and controls. Subjects can name that owner's
|
|
380
|
+
separate review API or local headless helpers; checks still run registered project
|
|
381
|
+
profiles and can refer to an existing real scenario. This grants no production
|
|
382
|
+
API, catalogue entry, `covers` credit or runtime import permission. See the
|
|
383
|
+
[portable review guide](../skills/ads-designer/references/review.md).
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,47 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
## 0.3.21
|
|
6
|
+
|
|
7
|
+
- Add statically read TypeScript owner contracts and canonical `.ads.` development
|
|
8
|
+
roles, retaining legacy token/behavior registration and stable scenario IDs.
|
|
9
|
+
- Validate constrained paint inputs, source-proven instance binding producers and
|
|
10
|
+
declarative child consumers. Audit current paint bindings/local SVG resources
|
|
11
|
+
inside Apps; registered browser checks remain required for guarantees.
|
|
12
|
+
- Close supported cross-owner TypeScript token-value flows and preserve independent
|
|
13
|
+
render evidence with positioned scenario field/entry diagnostics.
|
|
14
|
+
- Prepare contract/file-role migrations as normal guarded owner drafts; expose
|
|
15
|
+
compact contract/API metadata and portable guidance in all five skills.
|
|
16
|
+
- Expose read-only token-origin analysis for explicit project scale policies.
|
|
17
|
+
- Keep starter production declarations limited to the public runtime dependency
|
|
18
|
+
closure, excluding development contracts, scenarios, review and checks.
|
|
19
|
+
- Reuse contract TypeScript programs during discovery. Match failed Playwright
|
|
20
|
+
steps to the unhandled case error so nested API event order and earlier caught
|
|
21
|
+
failures cannot mislabel an assertion as a runner failure.
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
## 0.3.20
|
|
25
|
+
|
|
26
|
+
- Preserve the motion-review checklist separately from the development review-layer
|
|
27
|
+
guide; both remain self-contained in the motion skill. Version 0.3.19 was tagged
|
|
28
|
+
but publication was cancelled before this correction.
|
|
29
|
+
|
|
30
|
+
- Separate project-owned review UI from production patterns. Add `review/` owners,
|
|
31
|
+
a configurable development entry and derived `/review` alias, guarded companion
|
|
32
|
+
exports and review contracts. Preserve real component/token render evidence,
|
|
33
|
+
block production imports and verify review assets stay out of product bundles.
|
|
34
|
+
Move the working showcase and empty starter helpers to the new layer; publish
|
|
35
|
+
self-contained migration guidance in all skills and `ads://guides/review`.
|
|
36
|
+
- Enable native form validation and submit events across the showcase, diagnostic
|
|
37
|
+
explorer and legacy App iframe layers. Retain opaque App origins and block
|
|
38
|
+
native action requests through CSP. Cover click/Enter submission, custom/native
|
|
39
|
+
validation and no-network behavior in generic React, Preact and HTML Apps.
|
|
40
|
+
- Enforce runtime component dependency direction and public component contracts
|
|
41
|
+
for patterns through aliases, re-exports and helpers. Reject proven private
|
|
42
|
+
style-hook/variable access while preserving ancestor-context layout and documented
|
|
43
|
+
customization. Publish portable layer guidance in every skill and through MCP.
|
|
44
|
+
|
|
3
45
|
## 0.3.18
|
|
4
46
|
|
|
5
47
|
- Preserve complete typed `@property` registrations through atomic css/styled
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
# Static owner contracts and development files
|
|
2
|
+
|
|
3
|
+
Use one optional `<Owner>.ads.contract.ts` for owner-local tokens, constrained
|
|
4
|
+
paint inputs, scoped runtime bindings, declarative parts and behavioral checks.
|
|
5
|
+
The import `import type { UnitContract } from "@reqvire-org/ads/contracts"` supplies
|
|
6
|
+
development typing. ADS reads its AST and resolves real symbols without importing
|
|
7
|
+
or executing project modules. It adds no production runtime.
|
|
8
|
+
|
|
9
|
+
## Files and ownership
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
components/Plot/
|
|
13
|
+
Plot.tsx production API/root
|
|
14
|
+
Series.tsx production declarative API
|
|
15
|
+
renderer.tsx production consumer
|
|
16
|
+
paints.ts production binding producer
|
|
17
|
+
types.ts production prop types
|
|
18
|
+
tokens.css optional production token definitions
|
|
19
|
+
Plot.ads.contract.ts static tool declaration
|
|
20
|
+
Plot.ads.scenario.tsx demonstration
|
|
21
|
+
Plot.ads.fixture.ts demonstration data
|
|
22
|
+
Tokens.ads.scenario.tsx real owner-token samples
|
|
23
|
+
Tokens.ads.fixture.ts sample bindings/probes
|
|
24
|
+
Plot.ads.behavior.spec.ts registered browser checks
|
|
25
|
+
Plot.ads.test.tsx optional unit tests
|
|
26
|
+
Plot.ads.helpers.ts development-only adapters
|
|
27
|
+
README.md API/provenance
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
This is an example, not a required inventory. Use the same roles for patterns,
|
|
31
|
+
controllers and relevant development owners. `review/` remains a separate
|
|
32
|
+
shared development layer; its implementation filenames need no extra marker.
|
|
33
|
+
Runtime components, types and styles cannot import `.ads.` files, tests, fixtures
|
|
34
|
+
or review code through aliases, barrels or helpers. Unknown `.ads.` roles are
|
|
35
|
+
still development-only and are diagnosed. Fixtures/helpers cannot define styles;
|
|
36
|
+
put demo framing in review. Ordinary README/license files retain their names.
|
|
37
|
+
|
|
38
|
+
Scenarios/fixtures/review enter only the selected preview closure. Contracts are
|
|
39
|
+
never executable preview modules; derived audit descriptors are data. Specs run
|
|
40
|
+
only in the configured test runner. Production declaration emission must also
|
|
41
|
+
start from the public runtime entry, rather than include every file under the
|
|
42
|
+
design-system folder. The starter’s `tsconfig.build.json` does this; its normal
|
|
43
|
+
no-emit typecheck still checks development sources. Core import guards protect
|
|
44
|
+
the runtime dependency closure. Review custom emitter configurations through
|
|
45
|
+
the configuration owner before migrating a consuming project. Guards remain tooling. Production prop types
|
|
46
|
+
belong in runtime files, never inferred from a development contract.
|
|
47
|
+
|
|
48
|
+
## A contract uses actual implementation references
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
import type { UnitContract } from "@reqvire-org/ads/contracts";
|
|
52
|
+
import { Plot } from "./Plot";
|
|
53
|
+
import { Series } from "./Series";
|
|
54
|
+
import { Renderer } from "./renderer";
|
|
55
|
+
import { paints } from "./paints";
|
|
56
|
+
|
|
57
|
+
export default {
|
|
58
|
+
schemaVersion: 1,
|
|
59
|
+
tokens: { namespace: "--plot-", stylesheet: "./tokens.css" },
|
|
60
|
+
paintInputs: [
|
|
61
|
+
{ api: Plot, property: "config.*.paint", kind: "paint-reference" },
|
|
62
|
+
{ api: Series, property: "fill", kind: "paint-reference", bindings: ["items"] },
|
|
63
|
+
],
|
|
64
|
+
bindings: {
|
|
65
|
+
items: {
|
|
66
|
+
input: { api: Plot, property: "config" },
|
|
67
|
+
producer: paints,
|
|
68
|
+
valueFrom: "paint",
|
|
69
|
+
variable: "--plot-runtime-${key}",
|
|
70
|
+
scope: { api: Plot, selector: '[data-plot-root=""]' },
|
|
71
|
+
checks: ["isolation"],
|
|
72
|
+
},
|
|
73
|
+
},
|
|
74
|
+
declarativeParts: [
|
|
75
|
+
{ api: Series, parent: Plot, consumer: Renderer, checks: ["isolation"] },
|
|
76
|
+
],
|
|
77
|
+
behavior: {
|
|
78
|
+
subjects: { plot: { api: Plot }, renderer: { implementation: Renderer } },
|
|
79
|
+
guarantees: [{
|
|
80
|
+
id: "scoped-output",
|
|
81
|
+
description: "Changing either instance updates only its own output.",
|
|
82
|
+
subjects: ["plot", "renderer"], checks: ["isolation"],
|
|
83
|
+
}],
|
|
84
|
+
checks: {
|
|
85
|
+
isolation: {
|
|
86
|
+
file: "./Plot.ads.behavior.spec.ts", case: "isolation",
|
|
87
|
+
scenario: "components/Plot", profile: "widget",
|
|
88
|
+
},
|
|
89
|
+
},
|
|
90
|
+
},
|
|
91
|
+
} satisfies UnitContract;
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Keep contracts small; most owners need none or one section. Supported data are
|
|
95
|
+
literal objects/arrays, static constants/spreads, `as const` and `satisfies`.
|
|
96
|
+
Symbol references resolve through normal imports, aliases and re-exports.
|
|
97
|
+
Calls, getters, methods, computed metadata and environment-dependent expressions
|
|
98
|
+
are rejected. Function references are opaque identities, never executed.
|
|
99
|
+
Private implementation subjects may be internal module exports without becoming
|
|
100
|
+
public barrel exports. Producers/consumers must belong to the same owner. Required
|
|
101
|
+
checks must exist, back named guarantees and use a browser profile with the
|
|
102
|
+
corresponding scenario. A relationship is registration, not a passing guarantee.
|
|
103
|
+
|
|
104
|
+
## Typed paints and runtime bindings
|
|
105
|
+
|
|
106
|
+
Production-facing types can use:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
export type Paint = `var(--${string})` | `url(#${string})` | "none" | "currentColor";
|
|
110
|
+
export interface SeriesProps { fill?: Paint }
|
|
111
|
+
export type Config = Readonly<Record<string, { paint: Paint }>>;
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
ADS follows the actual property path/type, including nested maps. A name such as
|
|
115
|
+
`Paint`, an arbitrary `string`, `any` or a forged metadata role grants no waiver.
|
|
116
|
+
Supported references are a single accessible token/binding `var(--name)`, a local
|
|
117
|
+
SVG paint `url(#id)`, `none` or `currentColor`. Fallbacks, raw colours, external
|
|
118
|
+
URLs and arbitrary CSS are outside this role. Raw domain colours need a separately
|
|
119
|
+
reviewed validated input boundary; they are not implicitly supported here.
|
|
120
|
+
|
|
121
|
+
A runtime family is instance data, not an infinite design-token inventory. Its
|
|
122
|
+
source proof requires the declared config map, exact key/value mapping and actual
|
|
123
|
+
root attachment. Supported producers use `Object.entries(config)` with a loop,
|
|
124
|
+
or `Object.fromEntries(...map(...))`; same-owner helper returns are traceable.
|
|
125
|
+
Guard each key before the write/return using
|
|
126
|
+
`if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key")` (a loop may
|
|
127
|
+
`continue`). Return only the computed map. For example:
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
export function paints(config: Config) {
|
|
131
|
+
const result: Record<string, string> = {};
|
|
132
|
+
for (const [key, entry] of Object.entries(config)) {
|
|
133
|
+
if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key");
|
|
134
|
+
result[`--plot-runtime-${key}`] = entry.paint;
|
|
135
|
+
}
|
|
136
|
+
return result;
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The runtime root attaches that returned map using `style={paints(config)}` or a
|
|
141
|
+
traceable local/useMemo result and the declared class/exact data attribute.
|
|
142
|
+
Place spreading props before the explicit scope/style so an unknown spread
|
|
143
|
+
cannot replace them. This grants permission to that binding attachment only;
|
|
144
|
+
it does not authorize arbitrary inline styling, CSSProperties APIs or bulk writes.
|
|
145
|
+
Unsupported dynamic producers/attachment paths fail with an analysis diagnostic.
|
|
146
|
+
Keep the implementation project-owned; there is no required ADS binding helper.
|
|
147
|
+
|
|
148
|
+
Families cannot overlap shared tokens, owner-token namespaces, private runtime
|
|
149
|
+
prefixes or other bindings. A broad family such as `--color-${key}` grants no
|
|
150
|
+
shared-token exception. Use a distinct private family where collision freedom
|
|
151
|
+
cannot be established. Registered paint consumers list their allowed binding IDs;
|
|
152
|
+
borrowing a peer's family or private token remains invalid. Bindings are scoped
|
|
153
|
+
to their actual root; portals outside it need deliberate project integration.
|
|
154
|
+
|
|
155
|
+
The App audit checks current mounted instances, accessible values, local SVG
|
|
156
|
+
resources and computed paint-property responses. Visibility and complete rendered
|
|
157
|
+
output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
|
|
158
|
+
and 1000 elements per instance. Exceeding a budget reports limits and complete: false; it does not invalidate a
|
|
159
|
+
working component. An unobserved paint effect also remains unverified until its
|
|
160
|
+
relevant consumer/state is checked. It does
|
|
161
|
+
not prove every future input, visibility state or interaction. In registered
|
|
162
|
+
Playwright checks, use `auditBehaviorPaints(frame)` from
|
|
163
|
+
`@reqvire-org/ads/verification` after updates. Assert `result.ok` and, when claiming complete current-map
|
|
164
|
+
evidence, `result.complete` and the expected `verified` entries.
|
|
165
|
+
Exercise two instances with identical keys/different paints, key updates/removal,
|
|
166
|
+
themes, local SVG IDs and invalid/inaccessible references. Keep normal runner
|
|
167
|
+
profiles; React StrictMode still needs a project development harness.
|
|
168
|
+
|
|
169
|
+
## Rendered and declarative evidence
|
|
170
|
+
|
|
171
|
+
`covers` names rendered public UI. A null-returning declarative part belongs in
|
|
172
|
+
`exercises`, alongside behavioral APIs:
|
|
173
|
+
|
|
174
|
+
```tsx
|
|
175
|
+
export const scenario = {
|
|
176
|
+
title: "Plot", covers: ["Plot"], exercises: ["Series"],
|
|
177
|
+
};
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
The real part must reach its registered consumer through a rendered parent.
|
|
181
|
+
ADS resolves source identity comparisons (`child.type === Series`, including a
|
|
182
|
+
traceable comparison helper) and reads of that same child’s props traced from the consumer’s children input.
|
|
183
|
+
A comparison against a decoy object gives no evidence. An import, unrelated parent, unused
|
|
184
|
+
child or metadata claim gives no consumption credit. Unknown render branches are
|
|
185
|
+
conservative. Browser checks must verify that adding/removing/changing the part
|
|
186
|
+
changes output. Source relationships and current browser evidence are separate.
|
|
187
|
+
Do not add fake DOM, hide public parts or rewrite a valid API to appease tracing.
|
|
188
|
+
|
|
189
|
+
Scenario metadata is validated by field/entry with positions and reasons.
|
|
190
|
+
A bad entry still blocks acceptance while valid independent render evidence is
|
|
191
|
+
retained. Unreadable prerequisites report coverage as not established. Inspect
|
|
192
|
+
the exact source diagnostic and bounded results; do not assume every subsequent
|
|
193
|
+
missing preview means its runtime API is invalid.
|
|
194
|
+
|
|
195
|
+
## Local tokens and project consistency
|
|
196
|
+
|
|
197
|
+
`tokens.css` remains optional production design data for component/pattern owners,
|
|
198
|
+
imported by the runtime owner. Controllers stay headless; review uses the shared
|
|
199
|
+
vocabulary and its own development presentation state. Only root/theme definitions belong there. Tokens require real sample
|
|
200
|
+
coverage, including independently built owner token scenarios. One namespace
|
|
201
|
+
cannot be shared by peer components. Private references remain private through
|
|
202
|
+
TS constants, re-exports, helper returns, SVG/paint props and property reads/writes.
|
|
203
|
+
Normal composition of a public component using its own tokens remains valid.
|
|
204
|
+
Source analysis covers supported value flows; arbitrary dynamic code is not
|
|
205
|
+
proof of ownership. CSS variables remain browser-visible; namespacing is an
|
|
206
|
+
architecture boundary, not browser encapsulation.
|
|
207
|
+
|
|
208
|
+
Ownership does not establish a project's visual scale:
|
|
209
|
+
|
|
210
|
+
- A component redefining shared `--space-4` fails.
|
|
211
|
+
- Its private `--plot-gap: 7px` can be valid component geometry.
|
|
212
|
+
- `--plot-gap: var(--space-4)` preserves a shared scale with local meaning.
|
|
213
|
+
|
|
214
|
+
Choose project policy explicitly. A registered project check can use tooling-only
|
|
215
|
+
`inspectTokens(root)` and `inspectTokenOrigins(inventory, name, { stopAt: names })`
|
|
216
|
+
from `@reqvire-org/ads`. `aliasOnly` verifies every theme definition follows only
|
|
217
|
+
aliases to the explicitly selected origins; `literals` and `diagnostics` explain
|
|
218
|
+
violations/limits. Select the exact targets and permitted shared origins. Keep
|
|
219
|
+
intentional geometry exceptions exact with documented reasons. ADS neither
|
|
220
|
+
infers spacing meaning from names nor prescribes a global spacing palette.
|
|
221
|
+
|
|
222
|
+
## Migration and MCP editing
|
|
223
|
+
|
|
224
|
+
Legacy `tokens.json`/`<Owner>.tokens.json` and `behavior.json` remain readable.
|
|
225
|
+
Use either authoring form per section; competing declarations fail. New contracts
|
|
226
|
+
normalize into the same discovery, ownership, source revisions, affected-check
|
|
227
|
+
selection and candidate gates. `ads_units` exposes `contractFile`; `ads_catalog`
|
|
228
|
+
reports constrained paint paths and declarative parent/consumer/check references.
|
|
229
|
+
Use bounded file reads and paged detailed results, not repeated whole-project dumps.
|
|
230
|
+
|
|
231
|
+
Install supporting ADS tooling before migrating a consuming project and reconnect
|
|
232
|
+
MCP before replacing a package used by a running server. Then:
|
|
233
|
+
|
|
234
|
+
1. Discover one owner with `ads_units`.
|
|
235
|
+
2. `ads_prepare_patch({ unit, action: "migrate" })` creates a normal local draft.
|
|
236
|
+
3. Review the converted contract, renamed files/imports and migration notes.
|
|
237
|
+
4. `ads_prepare_patch({ unit, action: "diff", draft })` emits its Git patchFile.
|
|
238
|
+
5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
|
|
239
|
+
|
|
240
|
+
Migration never edits live source or bypasses gates. It retains stable scenario
|
|
241
|
+
IDs and check case IDs. An optional static `scenario.id` preserves a legacy
|
|
242
|
+
identity when a renamed filename would otherwise be ambiguous; it must stay
|
|
243
|
+
inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
|
|
244
|
+
in legacy registration with a note until deliberately resolved. Unknown runner
|
|
245
|
+
globs, custom adapters and documentation references require review. Ambiguous
|
|
246
|
+
flat-to-directory renames stay in the legacy form with a migration note so file
|
|
247
|
+
ownership cannot silently change. Preserve
|
|
248
|
+
licenses, pending drafts and unrelated work; keep transactions within their limits.
|
|
249
|
+
There is no alternate JSON contract editor. Do not loosen a guard or make a valid
|
|
250
|
+
API private merely to complete a migration.
|
package/docs/GUIDE.md
CHANGED
|
@@ -494,11 +494,11 @@ export default function Scenario() { return <Button>{fixture.label}</Button>; }
|
|
|
494
494
|
|
|
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
|
-
The starter includes `tokens/Foundation.scenario.tsx` and its local fixture for
|
|
498
|
-
a project-owned token review
|
|
497
|
+
The starter includes `tokens/Foundation.ads.scenario.tsx` and its local fixture for
|
|
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": [],
|
|
@@ -807,3 +808,28 @@ creates the GitHub release. Stable tags publish as `latest`; prerelease tags
|
|
|
807
808
|
publish as `next`. Check the workflow result and npm version before updating
|
|
808
809
|
consumer dependencies. The manual workflow moves a label to an existing
|
|
809
810
|
published version; it does not publish new source.
|
|
811
|
+
|
|
812
|
+
## Owner contracts and migration
|
|
813
|
+
|
|
814
|
+
New colocated development source uses `<Name>.ads.<role>.ts[x]`: contract,
|
|
815
|
+
scenario, fixture, helpers, test, spec or behavior.spec. Optional
|
|
816
|
+
`<Owner>.ads.contract.ts` consolidates token/behavior declarations with typed
|
|
817
|
+
paint and declarative-consumer contracts. Production APIs/types stay in runtime
|
|
818
|
+
files. ADS reads contract data statically; no project import runs during discovery.
|
|
819
|
+
See [CONTRACTS.md](CONTRACTS.md) for exact fields, supported producer forms and
|
|
820
|
+
source/browser limits. Older JSON and unmarked recognized development filenames
|
|
821
|
+
remain supported during migration.
|
|
822
|
+
|
|
823
|
+
With supporting tooling installed and MCP reconnected, discover one owner, call
|
|
824
|
+
`ads_prepare_patch` with `action: "migrate"`, inspect the local draft/notes, and use
|
|
825
|
+
normal diff, dry-run and apply gates. This never changes live source by itself.
|
|
826
|
+
Review custom runner globs and unimportable private subjects before application;
|
|
827
|
+
migrate passing owners in stages and preserve pending agent drafts.
|
|
828
|
+
|
|
829
|
+
Project scale policies remain explicit. A registered check can call
|
|
830
|
+
`inspectTokenOrigins(inspectTokens(root), target, {stopAt: allowedSharedTokens})`
|
|
831
|
+
from the tooling package. Check `aliasOnly` for strict alias-only policies across
|
|
832
|
+
all themes; inspect `literals`/`diagnostics` for raw values, cycles and limits.
|
|
833
|
+
Choose exact targets/origins and documented geometry exceptions in project code;
|
|
834
|
+
register the command in `mcp.mutationChecks` and the normal build. ADS owns no
|
|
835
|
+
universal spacing scale and infers no design meaning from token names.
|
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
|
|
@@ -397,6 +409,7 @@ The same discovery covers the rest of the project ADS:
|
|
|
397
409
|
|
|
398
410
|
| Unit | Scope |
|
|
399
411
|
|------|-------|
|
|
412
|
+
| `review/<Owner>` | Development-only frames, token renderers, demo controls, local checks and review-entry re-exports |
|
|
400
413
|
| `foundation` | Shared ADS entry styles and root helpers |
|
|
401
414
|
| `documentation` | ADS/project guides, shared credits and license notices, and `licenses/` text collections |
|
|
402
415
|
| `assets/brand`, `assets/fonts`, other `assets/*` groups | Original SVG, image, font and other asset files |
|
|
@@ -509,8 +522,8 @@ Install changed dependencies before verification; candidates use the project's
|
|
|
509
522
|
installed `node_modules`.
|
|
510
523
|
|
|
511
524
|
Resolve ownership diagnostics by preserving the required capability in its proper
|
|
512
|
-
layer. Demo-only sizing, borders and framing belong in a
|
|
513
|
-
|
|
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
|
|
514
527
|
geometry uses exact `styleWrites` properties. After migrating JSX inline geometry,
|
|
515
528
|
replace its own boundary entries in the same owner patch and check the final state.
|
|
516
529
|
After the gates pass, verify the behavior in a browser.
|
|
@@ -518,7 +531,7 @@ After the gates pass, verify the behavior in a browser.
|
|
|
518
531
|
A small change needs only its hunk. A complete new component may include its
|
|
519
532
|
implementation, public re-export, scenario and fixture in the same unit patch,
|
|
520
533
|
so coverage is checked against a complete candidate. New units use a new
|
|
521
|
-
`components/`, `patterns/` or `composition/` owner ID following the same colocation
|
|
534
|
+
`components/`, `patterns/`, `controllers/`, `review/` or `composition/` owner ID following the same colocation
|
|
522
535
|
convention. A patch cannot include a peer unit, capture existing peers beneath
|
|
523
536
|
a new directory owner, or change unrelated public-entry statements. Shared
|
|
524
537
|
public-entry changes are limited to re-exports from the selected unit. Alongside
|
|
@@ -652,6 +665,14 @@ origin hosts the sandbox proxy; that proxy creates an opaque inner App iframe
|
|
|
652
665
|
and forwards the standard Apps bridge messages. The diagnostic explorer follows
|
|
653
666
|
the same sandbox model. Only the App materializes and executes project resources.
|
|
654
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
|
+
|
|
655
676
|
For inline documents without an explicit App base URL, ADS supplies
|
|
656
677
|
`<base href="about:srcdoc">` and permits the local `about:` base scheme in CSP.
|
|
657
678
|
Bare and named fragment links retain native in-document navigation and state.
|
|
@@ -1023,7 +1044,7 @@ instruction reads alone do not establish Apps/Skills activation.
|
|
|
1023
1044
|
### Token sample verification
|
|
1024
1045
|
|
|
1025
1046
|
Token scenarios declare `samples: fixture.samples` and render a project-owned public
|
|
1026
|
-
review
|
|
1047
|
+
review renderer with that `samples` input. Each fixture record has `{ token, property,
|
|
1027
1048
|
probe }`; the tool discovers the resulting token names. Plain token lists and empty
|
|
1028
1049
|
covers do not satisfy review coverage. The same bindings travel in the compiled
|
|
1029
1050
|
resource manifest or self-contained App seed.
|
|
@@ -1048,3 +1069,18 @@ Existing projects migrate their token fixtures from name lists to explicit sampl
|
|
|
1048
1069
|
records, pass those records into their public renderer, and add the sample markers.
|
|
1049
1070
|
Rebuild previews with the updated compiler so the contract is included in resources.
|
|
1050
1071
|
Tool updates do not overwrite existing project-owned scenarios or renderers.
|
|
1072
|
+
|
|
1073
|
+
### Static owner contract discovery
|
|
1074
|
+
|
|
1075
|
+
`ads_units` includes `contractFile` for a single `<Owner>.ads.contract.ts`.
|
|
1076
|
+
`ads_catalog` identifies declarative APIs and their parent/consumer/check links,
|
|
1077
|
+
and registered constrained paint-input paths. Read the relevant source range;
|
|
1078
|
+
these summaries establish registration, not completed verification. Detailed
|
|
1079
|
+
results remain bounded and paged.
|
|
1080
|
+
|
|
1081
|
+
`ads_prepare_patch` accepts `action: "migrate"` to prepare marked development
|
|
1082
|
+
filenames and compatible legacy sections in a local draft. Inspect its notes,
|
|
1083
|
+
then use the existing diff and guarded dry-run/apply workflow. It does not write
|
|
1084
|
+
live source, loosen policy or add a second contract-editing protocol. See
|
|
1085
|
+
[CONTRACTS.md](CONTRACTS.md) for the static schema, compatibility and browser audits.
|
|
1086
|
+
The same guide is available at `ads://guides/contracts`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@reqvire-org/ads",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.21",
|
|
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": {
|
|
@@ -104,6 +104,9 @@
|
|
|
104
104
|
},
|
|
105
105
|
"exports": {
|
|
106
106
|
".": "./dist/index.mjs",
|
|
107
|
+
"./contracts": {
|
|
108
|
+
"types": "./dist/contracts.d.mts"
|
|
109
|
+
},
|
|
107
110
|
"./oxlint": "./dist/oxlint.mjs",
|
|
108
111
|
"./linaria": "./dist/linaria.mjs",
|
|
109
112
|
"./tokens": "./dist/contracts/tokens.json",
|
|
File without changes
|
/package/dist/bootstrap-ds/design-system/tokens/{Foundation.fixture.ts → Foundation.ads.fixture.ts}
RENAMED
|
File without changes
|
|
File without changes
|