@reqvire-org/ads 0.3.20 → 0.3.21

package/docs/CONTRACTS.md

@@ -0,0 +1,250 @@
+# Static owner contracts and development files
+
+Use one optional `<Owner>.ads.contract.ts` for owner-local tokens, constrained
+paint inputs, scoped runtime bindings, declarative parts and behavioral checks.
+The import `import type { UnitContract } from "@reqvire-org/ads/contracts"` supplies
+development typing. ADS reads its AST and resolves real symbols without importing
+or executing project modules. It adds no production runtime.
+
+## Files and ownership
+
+```text
+components/Plot/
+  Plot.tsx                     production API/root
+  Series.tsx                   production declarative API
+  renderer.tsx                 production consumer
+  paints.ts                    production binding producer
+  types.ts                     production prop types
+  tokens.css                   optional production token definitions
+  Plot.ads.contract.ts         static tool declaration
+  Plot.ads.scenario.tsx         demonstration
+  Plot.ads.fixture.ts           demonstration data
+  Tokens.ads.scenario.tsx       real owner-token samples
+  Tokens.ads.fixture.ts         sample bindings/probes
+  Plot.ads.behavior.spec.ts     registered browser checks
+  Plot.ads.test.tsx             optional unit tests
+  Plot.ads.helpers.ts           development-only adapters
+  README.md                    API/provenance
+```
+
+This is an example, not a required inventory. Use the same roles for patterns,
+controllers and relevant development owners. `review/` remains a separate
+shared development layer; its implementation filenames need no extra marker.
+Runtime components, types and styles cannot import `.ads.` files, tests, fixtures
+or review code through aliases, barrels or helpers. Unknown `.ads.` roles are
+still development-only and are diagnosed. Fixtures/helpers cannot define styles;
+put demo framing in review. Ordinary README/license files retain their names.
+
+Scenarios/fixtures/review enter only the selected preview closure. Contracts are
+never executable preview modules; derived audit descriptors are data. Specs run
+only in the configured test runner. Production declaration emission must also
+start from the public runtime entry, rather than include every file under the
+design-system folder. The starter’s `tsconfig.build.json` does this; its normal
+no-emit typecheck still checks development sources. Core import guards protect
+the runtime dependency closure. Review custom emitter configurations through
+the configuration owner before migrating a consuming project. Guards remain tooling. Production prop types
+belong in runtime files, never inferred from a development contract.
+
+## A contract uses actual implementation references
+
+```ts
+import type { UnitContract } from "@reqvire-org/ads/contracts";
+import { Plot } from "./Plot";
+import { Series } from "./Series";
+import { Renderer } from "./renderer";
+import { paints } from "./paints";
+
+export default {
+  schemaVersion: 1,
+  tokens: { namespace: "--plot-", stylesheet: "./tokens.css" },
+  paintInputs: [
+    { api: Plot, property: "config.*.paint", kind: "paint-reference" },
+    { api: Series, property: "fill", kind: "paint-reference", bindings: ["items"] },
+  ],
+  bindings: {
+    items: {
+      input: { api: Plot, property: "config" },
+      producer: paints,
+      valueFrom: "paint",
+      variable: "--plot-runtime-${key}",
+      scope: { api: Plot, selector: '[data-plot-root=""]' },
+      checks: ["isolation"],
+    },
+  },
+  declarativeParts: [
+    { api: Series, parent: Plot, consumer: Renderer, checks: ["isolation"] },
+  ],
+  behavior: {
+    subjects: { plot: { api: Plot }, renderer: { implementation: Renderer } },
+    guarantees: [{
+      id: "scoped-output",
+      description: "Changing either instance updates only its own output.",
+      subjects: ["plot", "renderer"], checks: ["isolation"],
+    }],
+    checks: {
+      isolation: {
+        file: "./Plot.ads.behavior.spec.ts", case: "isolation",
+        scenario: "components/Plot", profile: "widget",
+      },
+    },
+  },
+} satisfies UnitContract;
+```
+
+Keep contracts small; most owners need none or one section. Supported data are
+literal objects/arrays, static constants/spreads, `as const` and `satisfies`.
+Symbol references resolve through normal imports, aliases and re-exports.
+Calls, getters, methods, computed metadata and environment-dependent expressions
+are rejected. Function references are opaque identities, never executed.
+Private implementation subjects may be internal module exports without becoming
+public barrel exports. Producers/consumers must belong to the same owner. Required
+checks must exist, back named guarantees and use a browser profile with the
+corresponding scenario. A relationship is registration, not a passing guarantee.
+
+## Typed paints and runtime bindings
+
+Production-facing types can use:
+
+```ts
+export type Paint = `var(--${string})` | `url(#${string})` | "none" | "currentColor";
+export interface SeriesProps { fill?: Paint }
+export type Config = Readonly<Record<string, { paint: Paint }>>;
+```
+
+ADS follows the actual property path/type, including nested maps. A name such as
+`Paint`, an arbitrary `string`, `any` or a forged metadata role grants no waiver.
+Supported references are a single accessible token/binding `var(--name)`, a local
+SVG paint `url(#id)`, `none` or `currentColor`. Fallbacks, raw colours, external
+URLs and arbitrary CSS are outside this role. Raw domain colours need a separately
+reviewed validated input boundary; they are not implicitly supported here.
+
+A runtime family is instance data, not an infinite design-token inventory. Its
+source proof requires the declared config map, exact key/value mapping and actual
+root attachment. Supported producers use `Object.entries(config)` with a loop,
+or `Object.fromEntries(...map(...))`; same-owner helper returns are traceable.
+Guard each key before the write/return using
+`if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key")` (a loop may
+`continue`). Return only the computed map. For example:
+
+```ts
+export function paints(config: Config) {
+  const result: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(config)) {
+    if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key");
+    result[`--plot-runtime-${key}`] = entry.paint;
+  }
+  return result;
+}
+```
+
+The runtime root attaches that returned map using `style={paints(config)}` or a
+traceable local/useMemo result and the declared class/exact data attribute.
+Place spreading props before the explicit scope/style so an unknown spread
+cannot replace them. This grants permission to that binding attachment only;
+it does not authorize arbitrary inline styling, CSSProperties APIs or bulk writes.
+Unsupported dynamic producers/attachment paths fail with an analysis diagnostic.
+Keep the implementation project-owned; there is no required ADS binding helper.
+
+Families cannot overlap shared tokens, owner-token namespaces, private runtime
+prefixes or other bindings. A broad family such as `--color-${key}` grants no
+shared-token exception. Use a distinct private family where collision freedom
+cannot be established. Registered paint consumers list their allowed binding IDs;
+borrowing a peer's family or private token remains invalid. Bindings are scoped
+to their actual root; portals outside it need deliberate project integration.
+
+The App audit checks current mounted instances, accessible values, local SVG
+resources and computed paint-property responses. Visibility and complete rendered
+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
+and 1000 elements per instance. Exceeding a budget reports limits and complete: false; it does not invalidate a
+working component. An unobserved paint effect also remains unverified until its
+relevant consumer/state is checked. It does
+not prove every future input, visibility state or interaction. In registered
+Playwright checks, use `auditBehaviorPaints(frame)` from
+`@reqvire-org/ads/verification` after updates. Assert `result.ok` and, when claiming complete current-map
+evidence, `result.complete` and the expected `verified` entries.
+Exercise two instances with identical keys/different paints, key updates/removal,
+themes, local SVG IDs and invalid/inaccessible references. Keep normal runner
+profiles; React StrictMode still needs a project development harness.
+
+## Rendered and declarative evidence
+
+`covers` names rendered public UI. A null-returning declarative part belongs in
+`exercises`, alongside behavioral APIs:
+
+```tsx
+export const scenario = {
+  title: "Plot", covers: ["Plot"], exercises: ["Series"],
+};
+```
+
+The real part must reach its registered consumer through a rendered parent.
+ADS resolves source identity comparisons (`child.type === Series`, including a
+traceable comparison helper) and reads of that same child’s props traced from the consumer’s children input.
+A comparison against a decoy object gives no evidence. An import, unrelated parent, unused
+child or metadata claim gives no consumption credit. Unknown render branches are
+conservative. Browser checks must verify that adding/removing/changing the part
+changes output. Source relationships and current browser evidence are separate.
+Do not add fake DOM, hide public parts or rewrite a valid API to appease tracing.
+
+Scenario metadata is validated by field/entry with positions and reasons.
+A bad entry still blocks acceptance while valid independent render evidence is
+retained. Unreadable prerequisites report coverage as not established. Inspect
+the exact source diagnostic and bounded results; do not assume every subsequent
+missing preview means its runtime API is invalid.
+
+## Local tokens and project consistency
+
+`tokens.css` remains optional production design data for component/pattern owners,
+imported by the runtime owner. Controllers stay headless; review uses the shared
+vocabulary and its own development presentation state. Only root/theme definitions belong there. Tokens require real sample
+coverage, including independently built owner token scenarios. One namespace
+cannot be shared by peer components. Private references remain private through
+TS constants, re-exports, helper returns, SVG/paint props and property reads/writes.
+Normal composition of a public component using its own tokens remains valid.
+Source analysis covers supported value flows; arbitrary dynamic code is not
+proof of ownership. CSS variables remain browser-visible; namespacing is an
+architecture boundary, not browser encapsulation.
+
+Ownership does not establish a project's visual scale:
+
+- A component redefining shared `--space-4` fails.
+- Its private `--plot-gap: 7px` can be valid component geometry.
+- `--plot-gap: var(--space-4)` preserves a shared scale with local meaning.
+
+Choose project policy explicitly. A registered project check can use tooling-only
+`inspectTokens(root)` and `inspectTokenOrigins(inventory, name, { stopAt: names })`
+from `@reqvire-org/ads`. `aliasOnly` verifies every theme definition follows only
+aliases to the explicitly selected origins; `literals` and `diagnostics` explain
+violations/limits. Select the exact targets and permitted shared origins. Keep
+intentional geometry exceptions exact with documented reasons. ADS neither
+infers spacing meaning from names nor prescribes a global spacing palette.
+
+## Migration and MCP editing
+
+Legacy `tokens.json`/`<Owner>.tokens.json` and `behavior.json` remain readable.
+Use either authoring form per section; competing declarations fail. New contracts
+normalize into the same discovery, ownership, source revisions, affected-check
+selection and candidate gates. `ads_units` exposes `contractFile`; `ads_catalog`
+reports constrained paint paths and declarative parent/consumer/check references.
+Use bounded file reads and paged detailed results, not repeated whole-project dumps.
+
+Install supporting ADS tooling before migrating a consuming project and reconnect
+MCP before replacing a package used by a running server. Then:
+
+1. Discover one owner with `ads_units`.
+2. `ads_prepare_patch({ unit, action: "migrate" })` creates a normal local draft.
+3. Review the converted contract, renamed files/imports and migration notes.
+4. `ads_prepare_patch({ unit, action: "diff", draft })` emits its Git patchFile.
+5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
+
+Migration never edits live source or bypasses gates. It retains stable scenario
+IDs and check case IDs. An optional static `scenario.id` preserves a legacy
+identity when a renamed filename would otherwise be ambiguous; it must stay
+inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
+in legacy registration with a note until deliberately resolved. Unknown runner
+globs, custom adapters and documentation references require review. Ambiguous
+flat-to-directory renames stay in the legacy form with a migration note so file
+ownership cannot silently change. Preserve
+licenses, pending drafts and unrelated work; keep transactions within their limits.
+There is no alternate JSON contract editor. Do not loosen a guard or make a valid
+API private merely to complete a migration.

package/docs/GUIDE.md

@@ -494,7 +494,7 @@ export default function Scenario() { return <Button>{fixture.label}</Button>; }
 
 IDs derive from filenames; do not maintain another registry or hand-assigned IDs.
 Token scenarios live beside foundation CSS under the configured token directory.
-The starter includes `tokens/Foundation.scenario.tsx` and its local fixture for
+The starter includes `tokens/Foundation.ads.scenario.tsx` and its local fixture for
 a project-owned token review renderer. Keep its presentation in that pattern:
 
 ```tsx
@@ -808,3 +808,28 @@ creates the GitHub release. Stable tags publish as `latest`; prerelease tags
 publish as `next`. Check the workflow result and npm version before updating
 consumer dependencies. The manual workflow moves a label to an existing
 published version; it does not publish new source.
+
+## Owner contracts and migration
+
+New colocated development source uses `<Name>.ads.<role>.ts[x]`: contract,
+scenario, fixture, helpers, test, spec or behavior.spec. Optional
+`<Owner>.ads.contract.ts` consolidates token/behavior declarations with typed
+paint and declarative-consumer contracts. Production APIs/types stay in runtime
+files. ADS reads contract data statically; no project import runs during discovery.
+See [CONTRACTS.md](CONTRACTS.md) for exact fields, supported producer forms and
+source/browser limits. Older JSON and unmarked recognized development filenames
+remain supported during migration.
+
+With supporting tooling installed and MCP reconnected, discover one owner, call
+`ads_prepare_patch` with `action: "migrate"`, inspect the local draft/notes, and use
+normal diff, dry-run and apply gates. This never changes live source by itself.
+Review custom runner globs and unimportable private subjects before application;
+migrate passing owners in stages and preserve pending agent drafts.
+
+Project scale policies remain explicit. A registered check can call
+`inspectTokenOrigins(inspectTokens(root), target, {stopAt: allowedSharedTokens})`
+from the tooling package. Check `aliasOnly` for strict alias-only policies across
+all themes; inspect `literals`/`diagnostics` for raw values, cycles and limits.
+Choose exact targets/origins and documented geometry exceptions in project code;
+register the command in `mcp.mutationChecks` and the normal build. ADS owns no
+universal spacing scale and infers no design meaning from token names.

package/docs/MCP.md

@@ -1069,3 +1069,18 @@ Existing projects migrate their token fixtures from name lists to explicit sampl
 records, pass those records into their public renderer, and add the sample markers.
 Rebuild previews with the updated compiler so the contract is included in resources.
 Tool updates do not overwrite existing project-owned scenarios or renderers.
+
+### Static owner contract discovery
+
+`ads_units` includes `contractFile` for a single `<Owner>.ads.contract.ts`.
+`ads_catalog` identifies declarative APIs and their parent/consumer/check links,
+and registered constrained paint-input paths. Read the relevant source range;
+these summaries establish registration, not completed verification. Detailed
+results remain bounded and paged.
+
+`ads_prepare_patch` accepts `action: "migrate"` to prepare marked development
+filenames and compatible legacy sections in a local draft. Inspect its notes,
+then use the existing diff and guarded dry-run/apply workflow. It does not write
+live source, loosen policy or add a second contract-editing protocol. See
+[CONTRACTS.md](CONTRACTS.md) for the static schema, compatibility and browser audits.
+The same guide is available at `ads://guides/contracts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -104,6 +104,9 @@
   },
   "exports": {
     ".": "./dist/index.mjs",
+    "./contracts": {
+      "types": "./dist/contracts.d.mts"
+    },
     "./oxlint": "./dist/oxlint.mjs",
     "./linaria": "./dist/linaria.mjs",
     "./tokens": "./dist/contracts/tokens.json",