@reqvire-org/ads 0.3.20 → 0.3.21

package/dist/scenarios.mjs

@@ -3,13 +3,16 @@ import { existsSync } from "node:fs";
 import ts from "typescript";
 import { publicApi, scenarioApi } from "./public-api.mjs";
 import { uiOperation } from "./ui-framework.mjs";
-import { isDevelopmentFile, isInside, isScenarioFile, sourceFiles } from "./config.mjs";
+import { isDevelopmentFile, isInside, isScenarioFile, scenarioIdentity, sourceFiles } from "./config.mjs";
 import { projectCompilerOptions } from "./boundaries.mjs";
 import { inspectTokens } from "./tokens.mjs";
 import { isSharedToken } from "./token-policy.mjs";
 import { validTokenSamples } from "./token-samples.mjs";
 import { scopedTokens } from "./scoped-tokens.mjs";
 import { createScenarioTrace } from "./scenario-trace.mjs";
+import { inspectRuntimeContracts } from "./runtime-contracts.mjs";
+import { inspectUnitContracts } from "./unit-contracts.mjs";
+import { inspectPaintContracts } from "./paint-contracts.mjs";
 
 export const scenarioArtifact = (root, id) => path.join(root, ".ds/scenarios", id, "index.html");
 
@@ -37,42 +40,53 @@ export function publicUi(program, options) {
 export function inspectScenarios(options, suppliedProgram) {
   const { root, dsRoot } = options;
   const files = sourceFiles(dsRoot).filter(isScenarioFile);
-  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), path.join(dsRoot, options.config.reviewEntry), ...files], { ...projectCompilerOptions(options), allowJs: true });
+  const program = suppliedProgram ?? inspectUnitContracts(options).program ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), path.join(dsRoot, options.config.reviewEntry), ...files], { ...projectCompilerOptions(options), allowJs: true });
   const apis = scenarioApi(program, options);
   const duplicate = apis.find((item, index) => apis.some((other, otherIndex) => index !== otherIndex && item.name === other.name));
   const known = new Map(apis.filter(item => item.kind !== "controllers").map((item) => [item.name, item]));
   const checker = program.getTypeChecker();
+  const declarativeParts = inspectRuntimeContracts(options, program).parts;
+  const contractDeclarations=inspectUnitContracts(options).contracts;
+  const bindingTrace = contractDeclarations.some(contract=>contract.paintInputs?.length) ? createScenarioTrace(program, options) : null;
   const behaviorApis = new Map(publicApi(program, options).filter(item => !item.renderable && item.behavioral).map(item => [item.name, item]));
-  const tokenInventory = inspectTokens(root);
+  const tokenInventory = inspectTokens(root, options);
   const tokenNames = new Set(tokenInventory.tokens.map(token => token.name));
   const scoped = scopedTokens(options);
   const scenarios = [];
-  const diagnostics = [];
+  const diagnostics = [...inspectUnitContracts(options).diagnostics,...inspectRuntimeContracts(options,program).diagnostics,...inspectPaintContracts(options).diagnostics];
   const ids = new Set();
-  function report(file, message) { diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "scenario-contract", line: 1, column: 1, message }); }
+  function report(file, message, node, detail = {}) {
+    const position = node?.getSourceFile().getLineAndCharacterOfPosition(node.getStart());
+    diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "scenario-contract", line: (position?.line ?? 0) + 1, column: (position?.character ?? 0) + 1, message, ...detail });
+  }
   if (duplicate) report(path.join(dsRoot, options.config.reviewEntry), `Review export ${duplicate.name} collides with the production API. Use a distinct development export so scenario coverage is unambiguous.`);
   for (const file of files) {
     const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
     let kind = isInside(path.join(dsRoot, options.config.tokenDir), file) ? "tokens" : relative.split("/")[0];
     if (!["tokens", "components", "patterns", "composition"].includes(kind)) { report(file, "Scenarios live beside tokens/components/patterns or under composition/, not inside showcase pages."); continue; }
-    const id = relative.replace(/(?:\/Scenario|\.scenario)\.[^.]+$/, "");
-    if (id.length > 256) { report(file, "Scenario paths must fit within 256 characters."); continue; }
-    if (ids.has(id)) { report(file, `Duplicate scenario id ${id}. Use one entrypoint per identity.`); continue; }
-    ids.add(id);
+    let id = scenarioIdentity(file, dsRoot);
     const source = program.getSourceFile(file);
     if (!source) { report(file, "Cannot inspect scenario source."); continue; }
-    let metadata;
+    let metadata, metadataExpression;
     let entry = false;
     for (const node of source.statements) {
       if (ts.isExportAssignment(node) || node.modifiers?.some((item) => item.kind === ts.SyntaxKind.DefaultKeyword)) entry = true;
       if (ts.isVariableStatement(node) && node.modifiers?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword)) {
-        for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === "scenario") metadata = literal(declaration.initializer, checker);
+        for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === "scenario") { metadataExpression = declaration.initializer; metadata = literal(metadataExpression, checker); }
       }
     }
+    if(metadata?.id!==undefined) {
+      const owner=scoped.inventory.owner(relative);
+      if(typeof metadata.id!=="string"||metadata.id.length>256||!/^[\w-]+(?:[/.][\w-]+)*$/.test(metadata.id)||!owner||!(metadata.id===owner||metadata.id.startsWith(owner+"/")||metadata.id.startsWith(owner+".")))report(file,"Scenario id must be a safe stable identity inside this owner; it cannot capture another layer/owner.",metadataExpression,{entry:"id"});
+      else id=metadata.id;
+    }
+    if (id.length > 256) { report(file, "Scenario paths must fit within 256 characters."); continue; }
+    if (ids.has(id)) { report(file, `Duplicate scenario id ${id}. Use one entrypoint per identity.`); continue; }
+    ids.add(id);
     if (metadata?.kind !== undefined) {
       const owner = scoped.inventory.owner(relative);
-      if (metadata.kind !== "tokens" || !scoped.definitions.some(entry => entry.unit === owner)) { report(file, "Only an owner with registered local tokens may set kind: tokens for a colocated token preview."); continue; }
-      kind = "tokens";
+      if (metadata.kind !== "tokens" || !scoped.definitions.some(entry => entry.unit === owner)) report(file, "Only an owner with registered local tokens may set kind: tokens for a colocated token preview.",entryNode("kind"),{entry:"kind"});
+      else kind = "tokens";
     }
     if (!entry) report(file, "Export a default independently mountable scenario entrypoint.");
     const module = checker.getSymbolAtLocation(source);
@@ -90,12 +104,45 @@ export function inspectScenarios(options, suppliedProgram) {
     const fixtureBase = path.basename(file).startsWith("Scenario.") ? path.join(path.dirname(file), "fixture") : file.replace(/\.scenario\.[^.]+$/, ".fixture");
     const fixture = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].map(extension => fixtureBase + extension).find(existsSync);
     if (!fixture) report(file, "Keep this scenario's inputs beside it: fixture.ts (directory entry) or <Owner>.fixture.ts (flat entry). An empty fixture is valid for a component without inputs.");
-    if (!metadata || Object.keys(metadata).some((key) => !["title", "kind", "covers", "exercises", "tokens", "samples", "captureTargets"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
-      || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--")))
-      || kind === "tokens" && (Object.hasOwn(metadata, "tokens") || !validTokenSamples(metadata.samples) || !metadata.covers.some(name => ["patterns", "review"].includes(known.get(name)?.kind)))
-      || Object.hasOwn(metadata, "samples") && !validTokenSamples(metadata.samples)) {
-      report(file, "Export static metadata with nonempty covers naming rendered public UI. Optional exercises names public behavioral APIs, not rendered UI. Token scenarios must render a project-owned review renderer (from the separate review entry, or a real product pattern) and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
+    function entryNode(field, index) {
+      let value = metadataExpression;
+      const seen = new Set();
+      while (value && !seen.has(value)) {
+        seen.add(value);
+        if (ts.isSatisfiesExpression(value) || ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
+        else if (ts.isIdentifier(value)) { let symbol = checker.getSymbolAtLocation(value); if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol); value = symbol?.valueDeclaration?.initializer; }
+        else break;
+      }
+      const property = value && ts.isObjectLiteralExpression(value) && value.properties.find(item => ts.isPropertyAssignment(item) && (ts.isIdentifier(item.name) || ts.isStringLiteralLike(item.name)) && item.name.text === field);
+      return index !== undefined && property && ts.isArrayLiteralExpression(property.initializer) ? property.initializer.elements[index] : property?.initializer ?? metadataExpression;
+    }
+    if (!metadata) {
+      report(file, "Scenario metadata is not statically readable. Render coverage is not established until this prerequisite is repaired.", metadataExpression, {coverage:"not-established",owner:scoped.inventory.owner(relative)});
+      continue;
+    }
+    for(const field of Object.keys(metadata))if(!["id","title","kind","covers","exercises","tokens","samples","captureTargets"].includes(field))report(file,`Unknown scenario field ${field}.`,entryNode(field),{entry:field});
+    if(typeof metadata.title!=="string"||!metadata.title.trim()) {
+      report(file,"Scenario title must be a nonempty static string; independent render evidence is retained.",entryNode("title"),{entry:"title"});
+      metadata.title=id;
+    }
+    if(!Array.isArray(metadata.covers)||!metadata.covers.length) {
+      report(file,"Scenario covers must be a nonempty static array naming rendered public UI. Coverage is not established until repaired.",entryNode("covers"),{entry:"covers",coverage:"not-established",owner:scoped.inventory.owner(relative)});
+      metadata.covers=[];
+    }
+    if(Object.hasOwn(metadata,"tokens")&&(!Array.isArray(metadata.tokens)||metadata.tokens.some(name=>typeof name!=="string"||!name.startsWith("--")))) {
+      report(file,"Scenario tokens must be a static list of real token names.",entryNode("tokens"),{entry:"tokens"});metadata.tokens=[];
+    }
+    if(kind==="tokens"&&Object.hasOwn(metadata,"tokens")||kind==="tokens"&&!validTokenSamples(metadata.samples)||Object.hasOwn(metadata,"samples")&&!validTokenSamples(metadata.samples)) {
+      report(file,"Token scenarios need samples: fixture.samples, a literal list of { token, property, probe } real CSS bindings. Printing values or covers: [] is incomplete.",entryNode("samples"),{entry:"samples"});delete metadata.samples;
+    }
+    const covers = [];
+    for (const [index, name] of metadata.covers.entries()) {
+      const api = typeof name === "string" && known.get(name);
+      if (!api?.renderable || declarativeParts.some(part=>part.apiName===name)) report(file, `Scenario covers[${index}] ${JSON.stringify(name) ?? "(unresolved)"} ${api ? "is not independently rendered UI. Use exercises for a behavioral or registered declarative API." : "does not name a known public UI export."} Independent valid render evidence is retained.`, entryNode("covers", index), { entry: `covers[${index}]`, ...(typeof name === "string" ? { api: name } : {}), reason: api ? "wrong-api-role" : "unknown-api" });
+      else covers.push(name);
     }
+    metadata = { ...metadata, covers };
+    if (kind === "tokens" && !covers.some(name => ["patterns", "review"].includes(known.get(name)?.kind))) report(file, "Token covers must name the real development review renderer or product pattern consuming samples.", entryNode("covers"));
     // A bad behavioral entry must fail validation without erasing independent
     // render evidence and manufacturing missing-coverage errors for real UI.
     const exercises = [];
@@ -107,8 +154,8 @@ export function inspectScenarios(options, suppliedProgram) {
     if (Object.hasOwn(metadata, "exercises")) {
       if (!Array.isArray(metadata.exercises)) report(file, "Scenario exercises must be a static array naming public behavioral APIs.");
       else for (const [index, name] of metadata.exercises.entries()) {
-        if (typeof name !== "string") report(file, `Scenario exercises[${index}] must name a public behavioral API, not ${JSON.stringify(name) ?? "an unresolved value"}.`);
-        else if (!behaviorApis.has(name)) report(file, `Scenario exercises[${index}] ${JSON.stringify(name)} is not a recognized public behavioral API. Use a public callable function, hook or controller; rendered UI belongs in covers. Discover the project's exports before declaring exercises.`);
+        if (typeof name !== "string") report(file, `Scenario exercises[${index}] must name a public behavioral API, not ${JSON.stringify(name) ?? "an unresolved value"}.`, entryNode("exercises", index), { entry: `exercises[${index}]` });
+        else if (!behaviorApis.has(name) && !declarativeParts.some(part=>part.apiName===name)) report(file, `Scenario exercises[${index}] ${JSON.stringify(name)} is not a recognized public behavioral API. Use a public callable function, hook or controller; rendered UI belongs in covers. Discover the project's exports before declaring exercises.`, entryNode("exercises", index), { entry: `exercises[${index}]`, api: name });
         else exercises.push(name);
       }
     }
@@ -120,16 +167,22 @@ export function inspectScenarios(options, suppliedProgram) {
       for (const name of tokens) if (tokenInventory.tokens.find(token => token.name === name)?.owner !== owner) report(file, `Token ${name} needs a preview beside its defining owner. Shared tokens belong under the configured token directory; local tokens stay with their component/pattern.`);
     }
     const stylesheets = kind === "tokens" ? scoped.definitions.filter(entry => entry.unit === scoped.inventory.owner(relative)).map(entry => entry.file) : [];
-    scenarios.push({ id, kind, title: metadata.title, ...(fixture ? { fixture: path.relative(root, fixture).replaceAll("\\", "/") } : {}), covers: [...new Set(metadata.covers)], ...(captureTargets ? { captureTargets } : {}), ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), ...(stylesheets.length ? { stylesheets } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    const reachable = new Set(metadata.covers);
+    function findBindings(node) { if(ts.isJsxElement(node)||ts.isJsxSelfClosingElement(node))for(const name of bindingTrace.traceRenders(node).rendered)reachable.add(name);ts.forEachChild(node,findBindings); }
+    if(bindingTrace) findBindings(source);
+    const paintBindings = inspectRuntimeContracts(options,program).bindings.filter(binding=>reachable.has(binding.scope.apiName)).map(binding=>({owner:binding.unit,name:binding.name,scope:binding.scope.selector,prefix:binding.prefix,suffix:binding.suffix,tokens:tokenInventory.tokens.filter(token=>!token.owner||token.owner==="tokens"||token.owner===binding.unit).map(token=>token.name)}));
+    const paintAudit=contractDeclarations.some(contract=>contract.paintInputs?.some(input=>reachable.has(input.apiName)));
+    scenarios.push({ id, kind, title: metadata.title, ...(fixture ? { fixture: path.relative(root, fixture).replaceAll("\\", "/") } : {}), covers: [...new Set(metadata.covers)], ...(captureTargets ? { captureTargets } : {}), ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), ...(stylesheets.length ? { stylesheets } : {}), ...(paintBindings.length?{paintBindings}:{}), ...(paintAudit?{paintAudit:true}:{}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }
 
 export function inspectScenarioCoverage(options, program, report, advise = () => {}, trace = createScenarioTrace(program, options)) {
   const registry = inspectScenarios(options, program);
-  for (const item of registry.diagnostics) report(path.join(options.root, item.file), item.rule, item.message, item.line, item.column);
+  for (const {file,rule,message,line,column,...detail} of registry.diagnostics) report(path.join(options.root, file), rule, message, line, column, detail);
   const checker = program.getTypeChecker();
   const ui = publicUi(program, options);
+  const parts = inspectRuntimeContracts(options, program).parts;
   function symbolOf(expression) {
     while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isNonNullExpression(expression))) expression = expression.expression;
     if (!expression) return null;
@@ -167,12 +220,12 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
 
   const covered = new Set();
   const coveredTokens = new Set();
-  const tokenInventory = inspectTokens(options.root);
+  const tokenInventory = inspectTokens(options.root, options);
   const declaredTokens = new Set(tokenInventory.tokens.map(token => token.name));
   for (const scenario of registry.scenarios) {
     const source = program.getSourceFile(path.join(options.root, scenario.file));
     const rendered = new Set();
-    const exercised = new Set(), referencedApis = new Set();
+    const exercised = new Set(), referencedApis = new Set(), declarative = new Set();
     const referencedTokens = new Set();
     let samplesPassed = false;
     const renderLimits = new Set();
@@ -229,12 +282,14 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
       ts.forEachChild(node, child => visit(child, reached && (ts.isExportAssignment(node) || ts.isVariableDeclaration(node))));
     }
     for (const node of source.statements) if (ts.isExportAssignment(node) || node.modifiers?.some(item => item.kind === ts.SyntaxKind.DefaultKeyword)) visit(node, true);
+    if(parts.some(part=>scenario.exercises?.includes(part.apiName)))for(const name of trace.traceEntry(source).declarative)declarative.add(name);
     for (const name of scenario.covers) {
       if (!rendered.has(name)) report(source.fileName, "scenario-render", `${name} is declared in covers but has no reachable public render reference. Render it directly or through a traced parent with fixture props/defaults selecting that child. Imports, unused JSX and unknown conditional paths do not establish coverage.${renderLimits.size ? ` Source tracing could not establish: ${[...renderLimits].slice(0, 2).join(" ")}` : ""} Review the real scenario in a browser; do not hide a valid public part just to avoid coverage. See ads://guides/scenarios.`);
       else covered.add(name);
     }
     for (const name of scenario.exercises ?? []) {
-      if (!exercised.has(name) && !referencedApis.has(name)) report(source.fileName, "scenario-exercise", `${name} is declared in exercises but has no reachable behavioral use. Imports and unused adapters do not count.`);
+      if (parts.some(part=>part.apiName===name) && !declarative.has(name)) report(source.fileName, "scenario-exercise", `${name} is a registered declarative API, but its child does not reach the declared consumer through a rendered parent. Imports, unused children and unrelated parent renders do not establish consumption.`);
+      else if (!exercised.has(name) && !referencedApis.has(name)) report(source.fileName, "scenario-exercise", `${name} is declared in exercises but has no reachable behavioral use. Imports and unused adapters do not count.`);
       else if (!exercised.has(name)) advise(source.fileName, "scenario-exercise-review", `${name} is referenced dynamically. Verify its invocation in the registered browser/behavior checks; a reference alone does not prove execution.`);
     }
     for (const name of referencedTokens) if (!declaredTokens.has(name)) report(source.fileName, "token-scenario-reference", `Reachable scenario input references undeclared token ${name}.`);
@@ -244,7 +299,8 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
       else if (scenario.kind === "tokens" && samplesPassed && declaredTokens.has(name)) coveredTokens.add(name);
     }
   }
-  for (const item of ui.filter((item) => item.renderable && !covered.has(item.name))) report(item.file, "scenario-coverage", `Public UI ${item.name} needs a colocated, registered scenario render reference. Related parts may share a scenario.`);
+  const blockedOwners=new Set(registry.diagnostics.filter(item=>item.coverage==="not-established").map(item=>item.owner));
+  for (const item of ui.filter((item) => item.renderable && !covered.has(item.name) && !blockedOwners.has(scopedTokens(options).inventory.owner(scopedTokens(options).inventory.relative(path.relative(options.root,item.file)))))) report(item.file, "scenario-coverage", `Public UI ${item.name} needs a colocated, registered scenario render reference. Related parts may share a scenario.`);
   for (const token of tokenInventory.tokens.filter(token => !coveredTokens.has(token.name))) {
     const definition = token.definitions[0];
     report(path.join(options.root, definition.file), "token-scenario-coverage", `Token ${token.name} needs a registered scenario with a reachable token fixture reference.`, definition.line, definition.column);

package/dist/scoped-tokens.mjs

@@ -7,19 +7,24 @@ import { isDevelopmentFile } from "./config.mjs";
 import { foundationSelector } from "./foundation.mjs";
 import { isSharedToken, tokenContract } from "./token-policy.mjs";
 import { propertyRegistration } from "./property-registrations.mjs";
+import { inspectUnitContracts } from "./unit-contracts.mjs";
 
 /** An explicit owner contract, never a heuristic based on a token's name. */
 export function scopedTokens(options) {
   if (options.scopedTokens) return options.scopedTokens;
-  const inventory = inspectUnits(options), definitions = [], diagnostics = [];
+  const inventory = inspectUnits(options), definitions = [], declarations = inspectUnitContracts(options), diagnostics = [...declarations.diagnostics];
   const report = (file, message, line = 1) => diagnostics.push({rule:"scoped-token", file, message, line, column:1});
   for (const unit of inventory.units.filter(unit => ["components", "patterns"].includes(unit.kind))) {
-    for (const manifest of unit.files.filter(file => /(?:^|\/)tokens\.json$|\.tokens\.json$/.test(file))) {
+    const inputs = [
+      ...unit.files.filter(file => /(?:^|\/)tokens\.json$|\.tokens\.json$/.test(file)).map(manifest => ({manifest})),
+      ...declarations.contracts.filter(entry => entry.unit === unit.id && entry.tokens).map(entry => ({manifest:entry.file, contract:entry.tokens})),
+    ];
+    for (const {manifest, contract} of inputs) {
       const absolute = path.join(options.root, manifest);
       try {
         if (statSync(absolute).size > 65536 || realpathSync(absolute) !== absolute) throw new Error("Token manifests must be ordinary files no larger than 64 KiB.");
-        const data = JSON.parse(readFileSync(absolute, "utf8"));
-        const stylesheet = manifest.replace(/\.json$/, ".css");
+        const data = contract ? {schemaVersion:1, namespace:contract.namespace} : JSON.parse(readFileSync(absolute, "utf8"));
+        const stylesheet = contract ? contract.file : manifest.replace(/\.json$/, ".css");
         if (!data || data.schemaVersion !== 1 || Object.keys(data).some(key => !["schemaVersion", "namespace"].includes(key))
           || typeof data.namespace !== "string" || !/^--[a-z][a-z0-9-]*-$/.test(data.namespace)
           || /^(?:--ds-|--ux-|--showcase-)/.test(data.namespace) || isSharedToken(data.namespace + "value")

package/dist/skills/ads-break-ui/SKILL.md

@@ -355,3 +355,7 @@ rendered check.
 
 Source credits and retained MIT terms: [README.md](README.md) and
 [LICENSE.upstream](LICENSE.upstream).
+
+For static owner contracts, `.ads.` development roles, typed paint/binding APIs,
+declarative evidence, token privacy and guarded migration, read
+[contracts.md](references/contracts.md) when the task touches those contracts.

package/dist/skills/ads-break-ui/references/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/dist/skills/ads-designer/SKILL.md

@@ -522,3 +522,7 @@ For visual work, inspect the real project showcase, including keyboard/focus,
 relevant pointer/touch behavior, dark theme, and reduced motion as needed.
 A screenshot alone does not prove behavior or animation. Validate public imports,
 CSS/asset resolution, required setup, and local documentation links.
+
+For static owner contracts, `.ads.` development roles, typed paint/binding APIs,
+declarative evidence, token privacy and guarded migration, read
+[contracts.md](references/contracts.md) when the task touches those contracts.

package/dist/skills/ads-designer/assets/bootstrap-ds/README.md

@@ -56,7 +56,7 @@ Its MCP client discovers entries, invokes preview tools and follows notification
 There are no required TokensPage/ComponentsPage/PatternsPage/CompositionPage
 files, and no separate project browser app to implement or rebuild.
 
-The existing `tokens/Foundation.scenario.tsx` and colocated fixture visually demonstrate all
+The existing `tokens/Foundation.ads.scenario.tsx` and colocated fixture visually demonstrate all
 starter token values. The fixture owns `{ token, property, probe }` bindings;
 the public `TokenPreview` pattern owns their presentation and applies the real CSS
 variables. Add/remove samples alongside token definitions. `ads check` rejects

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/{Foundation.scenario.tsx → Foundation.ads.scenario.tsx}

@@ -1,4 +1,4 @@
 import { TokenPreview } from "@ds/review";
-import { fixture } from "./Foundation.fixture";
+import { fixture } from "./Foundation.ads.fixture";
 export const scenario = { title: fixture.title, covers: ["TokenPreview"], samples: fixture.samples };
 export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.build.json

@@ -7,6 +7,13 @@
     "rootDir": "design-system",
     "outDir": "dist"
   },
-  "include": ["design-system/**/*.ts", "design-system/**/*.tsx"],
-  "exclude": ["design-system/showcase"]
+  "include": [
+    "design-system/index.ts"
+  ],
+  "exclude": [
+    "design-system/showcase",
+    "design-system/review",
+    "design-system/composition",
+    "**/*.ads.*"
+  ]
 }