@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.
Files changed (104) hide show
  1. package/README.md +2 -0
  2. package/dist/behaviors.mjs +19 -9
  3. package/dist/bootstrap-ds/ADS.md +2 -2
  4. package/dist/bootstrap-ds/README.md +2 -2
  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 → Foundation.ads.scenario.tsx} +2 -2
  8. package/dist/bootstrap-ds/ds.config.json +1 -1
  9. package/dist/bootstrap-ds/tsconfig.build.json +9 -2
  10. package/dist/bootstrap-ds/tsconfig.json +18 -3
  11. package/dist/bootstrap-ds/vite.config.ts +1 -1
  12. package/dist/boundaries.mjs +6 -2
  13. package/dist/check.mjs +44 -17
  14. package/dist/config.mjs +33 -5
  15. package/dist/contract-migration.mjs +110 -0
  16. package/dist/contracts.d.mts +22 -0
  17. package/dist/evidence.mjs +1 -1
  18. package/dist/index.mjs +1 -0
  19. package/dist/init.mjs +18 -15
  20. package/dist/layers.mjs +288 -0
  21. package/dist/lint-config.mjs +1 -1
  22. package/dist/mcp/catalog.mjs +9 -2
  23. package/dist/mcp/context.mjs +2 -1
  24. package/dist/mcp/edit-preparation.mjs +9 -6
  25. package/dist/mcp/mutations.mjs +1 -1
  26. package/dist/mcp/preview-widget.bundle.js +41 -39
  27. package/dist/mcp/prompts.mjs +1 -1
  28. package/dist/mcp/server.mjs +9 -3
  29. package/dist/mcp/widget.bundle.js +1 -1
  30. package/dist/oxlint.mjs +3 -1
  31. package/dist/paint-contracts.mjs +124 -0
  32. package/dist/preview-resources.mjs +12 -2
  33. package/dist/public-api.mjs +13 -6
  34. package/dist/public-props.mjs +2 -2
  35. package/dist/runtime-contracts.mjs +225 -0
  36. package/dist/scenario-trace.mjs +37 -9
  37. package/dist/scenarios-vite.mjs +3 -2
  38. package/dist/scenarios.mjs +89 -30
  39. package/dist/scoped-tokens.mjs +9 -4
  40. package/dist/showcase/client.bundle.js +1 -1
  41. package/dist/showcase/sandbox.bundle.js +1 -1
  42. package/dist/skills/ads-break-ui/SKILL.md +25 -6
  43. package/dist/skills/ads-break-ui/references/contracts.md +250 -0
  44. package/dist/skills/ads-break-ui/references/guarded-editing.md +1 -1
  45. package/dist/skills/ads-break-ui/references/layers.md +123 -0
  46. package/dist/skills/ads-break-ui/references/review.md +96 -0
  47. package/dist/skills/ads-break-ui/references/scenarios.md +24 -3
  48. package/dist/skills/ads-designer/SKILL.md +26 -7
  49. package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md +2 -2
  50. package/dist/skills/ads-designer/assets/bootstrap-ds/README.md +2 -2
  51. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/index.ts +0 -1
  52. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/review/index.ts +1 -0
  53. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/{Foundation.scenario.tsx → Foundation.ads.scenario.tsx} +2 -2
  54. package/dist/skills/ads-designer/assets/bootstrap-ds/ds.config.json +1 -1
  55. package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.build.json +9 -2
  56. package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.json +18 -3
  57. package/dist/skills/ads-designer/assets/bootstrap-ds/vite.config.ts +1 -1
  58. package/dist/skills/ads-designer/references/contracts.md +250 -0
  59. package/dist/skills/ads-designer/references/guarded-editing.md +1 -1
  60. package/dist/skills/ads-designer/references/layers.md +123 -0
  61. package/dist/skills/ads-designer/references/review.md +96 -0
  62. package/dist/skills/ads-designer/references/scenarios.md +24 -3
  63. package/dist/skills/ads-import/SKILL.md +25 -6
  64. package/dist/skills/ads-import/references/contracts.md +250 -0
  65. package/dist/skills/ads-import/references/guarded-editing.md +1 -1
  66. package/dist/skills/ads-import/references/layers.md +123 -0
  67. package/dist/skills/ads-import/references/review.md +96 -0
  68. package/dist/skills/ads-import/references/scenarios.md +24 -3
  69. package/dist/skills/ads-migrate/SKILL.md +25 -6
  70. package/dist/skills/ads-migrate/references/contracts.md +250 -0
  71. package/dist/skills/ads-migrate/references/guarded-editing.md +1 -1
  72. package/dist/skills/ads-migrate/references/layers.md +123 -0
  73. package/dist/skills/ads-migrate/references/review.md +96 -0
  74. package/dist/skills/ads-migrate/references/scenarios.md +24 -3
  75. package/dist/skills/ads-motion/SKILL.md +26 -7
  76. package/dist/skills/ads-motion/references/audit.md +1 -1
  77. package/dist/skills/ads-motion/references/contracts.md +250 -0
  78. package/dist/skills/ads-motion/references/guarded-editing.md +1 -1
  79. package/dist/skills/ads-motion/references/layers.md +123 -0
  80. package/dist/skills/ads-motion/references/motion-review.md +35 -0
  81. package/dist/skills/ads-motion/references/review.md +96 -35
  82. package/dist/skills/ads-motion/references/scenarios.md +24 -3
  83. package/dist/token-origins.mjs +24 -0
  84. package/dist/tokens.mjs +4 -3
  85. package/dist/unit-contracts.mjs +203 -0
  86. package/dist/units.mjs +26 -17
  87. package/dist/verification/browser.mjs +156 -26
  88. package/dist/verification/playwright-reporter.cjs +13 -3
  89. package/docs/ADS.md +40 -6
  90. package/docs/ARCHITECTURE.md +73 -4
  91. package/docs/BEHAVIORS.md +15 -0
  92. package/docs/CHANGELOG.md +42 -0
  93. package/docs/CONTRACTS.md +250 -0
  94. package/docs/GUIDE.md +29 -3
  95. package/docs/MCP.md +42 -6
  96. package/package.json +4 -1
  97. package/dist/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx +0 -4
  98. package/dist/bootstrap-ds/design-system/patterns/token-preview/fixture.ts +0 -8
  99. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx +0 -4
  100. package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/fixture.ts +0 -8
  101. /package/dist/bootstrap-ds/design-system/{patterns → review}/token-preview/TokenPreview.tsx +0 -0
  102. /package/dist/bootstrap-ds/design-system/tokens/{Foundation.fixture.ts → Foundation.ads.fixture.ts} +0 -0
  103. /package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/{patterns → review}/token-preview/TokenPreview.tsx +0 -0
  104. /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 pattern. Keep its presentation in that pattern:
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
- 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
@@ -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 public review/layout
513
- 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
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 pattern with that `samples` input. Each fixture record has `{ token, property,
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.18",
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",
@@ -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;