@reqvire-org/ads 0.3.18 → 0.3.21

package/README.md

@@ -31,6 +31,8 @@ uses Preact. See [implementation support](docs/GUIDE.md#implementation-support).
   proposed candidates, exposed as MCP image resources.
 - **Verify behavior** through project-owned guarantees and registered tests,
   with progress, timings and evidence tied to current source.
+- **Keep contracts explicit** for typed paint inputs, scoped data bindings and
+  declarative APIs, without adding ADS to production components.
 - **Guide agents** with prompts and portable skills for building, importing,
   migrating, motion and UI stress testing.
 

package/dist/behaviors.mjs

@@ -3,12 +3,13 @@ import path from "node:path";
 import { isBuiltin } from "node:module";
 import ts from "typescript";
 import { z } from "zod";
-import { isBehaviorFile, isDevelopmentFile, isInside, sourceFiles } from "./config.mjs";
+import { isBehaviorFile, isDevelopmentFile, isInside, sourceFiles, isReviewFile } from "./config.mjs";
 import { importResolver, projectCompilerOptions } from "./boundaries.mjs";
 import { inspectUnits } from "./units.mjs";
-import { publicApi } from "./public-api.mjs";
+import { scenarioApi } from "./public-api.mjs";
 import { inspectScenarios } from "./scenarios.mjs";
 import { uiOperation } from "./ui-framework.mjs";
+import { inspectUnitContracts } from "./unit-contracts.mjs";
 
 const id = z.string().regex(/^[a-zA-Z0-9][\w.-]{0,99}$/);
 const reference = z.string().min(1).max(500);
@@ -27,25 +28,27 @@ export const behaviorSchema = z.object({
 export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
   const { root, dsRoot, config } = options;
   const inventory = inspectUnits(options);
-  const files = sourceFiles(dsRoot).filter(isBehaviorFile);
+  const declarations = inspectUnitContracts(options);
+  const typed = declarations.contracts.filter(entry => entry.behavior);
+  const files = [...sourceFiles(dsRoot).filter(isBehaviorFile), ...typed.map(entry => path.resolve(root, entry.file))];
   if (!files.length) return { contracts: [], diagnostics: [] };
-  const program = suppliedProgram ?? ts.createProgram(sourceFiles(dsRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file)), { ...projectCompilerOptions(options), allowJs: true });
+  const program = suppliedProgram ?? declarations.program ?? ts.createProgram(sourceFiles(dsRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file)), { ...projectCompilerOptions(options), allowJs: true });
   const checker = program.getTypeChecker();
-  const apis = new Map(publicApi(program, options).map(item => [item.name, item]));
+  const apis = new Map(scenarioApi(program, options).map(item => [item.name, item]));
   const scenarios = (suppliedRegistry ?? inspectScenarios(options, program)).scenarios;
-  const diagnostics = [], contracts = [], owners = new Set();
+  const diagnostics = [...declarations.diagnostics], contracts = [], owners = new Set();
   const relative = file => path.relative(root, file).replaceAll("\\", "/");
   for (const file of files) {
     const report = message => diagnostics.push({ file: relative(file), rule: "behavior-contract", line: 1, column: 1, message });
     let value;
     try {
       if (statSync(file).size > 128 * 1024 || realpathSync(file) !== file) throw new Error("Behavior contracts must be regular files of at most 128 KiB.");
-      const parsed = behaviorSchema.safeParse(JSON.parse(readFileSync(file, "utf8")));
+      const parsed = behaviorSchema.safeParse(typed.find(entry => path.resolve(root, entry.file) === file)?.behavior ?? JSON.parse(readFileSync(file, "utf8")));
       if (!parsed.success) throw new Error(parsed.error.issues.slice(0, 5).map(issue => `${issue.path.join(".")}: ${issue.message}`).join("; "));
       value = parsed.data;
     } catch (error) { report(error.message); continue; }
     const unit = inventory.owner(inventory.relative(relative(file)));
-    if (!["components", "patterns", "controllers"].includes(unit?.split("/")[0])) { report("Behavior contracts belong to a component, pattern or controller unit."); continue; }
+    if (!["components", "patterns", "controllers", "review"].includes(unit?.split("/")[0])) { report("Behavior contracts belong to a component, pattern, controller or development review unit."); continue; }
     if (owners.has(unit)) { report(`Only one behavior contract may describe ${unit}.`); continue; }
     owners.add(unit);
     function owned(target, field) {
@@ -61,7 +64,7 @@ export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
         if (!api || inventory.owner(inventory.relative(relative(api.file))) !== unit) report(`Subject ${name} must resolve to a public API owned by ${unit}: ${entry.api}`);
       } else {
         const source = owned(entry.source, `Subject ${name}`);
-        if (source && isDevelopmentFile(source, options)) report(`Subject ${name} must identify runtime implementation, not a fixture, scenario or check.`);
+        if (source && isDevelopmentFile(source, options) && !isReviewFile(source, options)) report(`Subject ${name} must identify runtime implementation, not a fixture, scenario or check.`);
         if (source && entry.symbol) {
           const ast = program.getSourceFile(source);
           if (!ast || !checker.getSymbolsInScope(ast, ts.SymbolFlags.Value).some(symbol => symbol.name === entry.symbol && symbol.declarations?.some(declaration => declaration.getSourceFile() === ast))) report(`Subject ${name}: symbol ${entry.symbol} is not declared in ${entry.source}.`);
@@ -85,6 +88,13 @@ export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
       if (cases.has(identity)) report(`Duplicate execution identity for check ${name}. Use one check ID and reference it from several guarantees.`);
       cases.add(identity);
     }
+    const declaration=typed.find(entry=>entry.unit===unit);
+    for(const entry of [...Object.values(declaration?.bindings??{}),...(declaration?.declarativeParts??[])])for(const name of entry.checks) {
+      const check=value.checks[name],scenario=check&&scenarios.find(scenario=>scenario.id===check.scenario);
+      const parent=entry.parentName??entry.scope.apiName;
+      if(!check||config.mcp.behaviorProfiles[check.profile]?.mode!=="browser"||!scenario?.covers.includes(parent)||entry.parentName&&!scenario.exercises?.includes(entry.apiName))report(`Required contract check ${name} must use a browser profile and a scenario covering ${parent}${entry.parentName?` and exercising ${entry.apiName}`:""}. Source registration does not establish rendered behavior.`);
+      if(!value.guarantees.some(guarantee=>guarantee.checks.includes(name)))report(`Required contract check ${name} must back a named guarantee, not remain an unclaimed execution.`);
+    }
     contracts.push({ ...value, unit, file: relative(file), demonstrations: Object.fromEntries(Object.entries(value.subjects).filter(([, item]) => item.api).map(([name, item]) => [name, scenarios.filter(scenario => scenario.exercises?.includes(item.api)).map(scenario => scenario.id)])) });
   }
   return { contracts, diagnostics };

package/dist/bootstrap-ds/ADS.md

@@ -72,7 +72,7 @@ layout, component-specific focus rules and hover/disabled skins are rejected.
 Shared token definitions belong in value sheets, not `base.css`. No project token
 names are embedded in this policy. A zero-specificity `:where()` wrapper does not
 change ownership. Put component design and animation in Linaria owners, and
-scenario layout variations in typed public review-pattern props. Browser review
+scenario layout variations in typed review-helper props. Browser review
 still checks the effects and accessibility of permitted defaults.
 
 Own primitive markup, focus, hover, selected, disabled, loading, and motion in
@@ -151,7 +151,7 @@ Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
 `export const scenario = { title: "Button states", covers: ["Button"] };`.
 Token entries under the configured token directory declare
 `export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };`.
-`TokenSamples` is any project-owned public review pattern, not a required name.
+`TokenSamples` is any project-owned development-only review renderer, not a required name.
 Its colocated fixture declares literal `samples: [{ token, property, probe }]`.
 Each token must exist and have sample coverage; duplicate bindings, missing probes,
 empty covers and value-only inspectors fail. The default entry passes the declared

package/dist/bootstrap-ds/README.md

@@ -1,7 +1,7 @@
 # Empty native design system
 
 This private React/TypeScript workspace contains semantic CSS tokens, a project-owned
-token review pattern, a public barrel, Linaria extraction and a preview compiler
+token review renderer, a public barrel, Linaria extraction and a preview compiler
 adapter. It has no product components, icons, fonts or example screens. The minimal showcase
 shell and MCP client come from ADS tooling.
 
@@ -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/bootstrap-ds/design-system/index.ts

@@ -2,4 +2,3 @@
 import "./styles.css";
 
 // Add public component and pattern exports here as they are implemented.
-export { TokenPreview } from "./patterns/token-preview/TokenPreview";

package/dist/bootstrap-ds/design-system/review/index.ts

@@ -0,0 +1 @@
+export { TokenPreview } from "./token-preview/TokenPreview";

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

@@ -1,4 +1,4 @@
-import { TokenPreview } from "@ds";
-import { fixture } from "./Foundation.fixture";
+import { TokenPreview } from "@ds/review";
+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/bootstrap-ds/ds.config.json

@@ -13,7 +13,7 @@
   "boundaries": {
     "styleWrites": [
       {
-        "file": "design-system/patterns/token-preview/TokenPreview.tsx",
+        "file": "design-system/review/token-preview/TokenPreview.tsx",
         "properties": [
           "--ux-token-preview-value"
         ]

package/dist/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.*"
+  ]
 }

package/dist/bootstrap-ds/tsconfig.json

@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
     "module": "ESNext",
     "moduleResolution": "bundler",
     "skipLibCheck": true,
@@ -14,7 +18,18 @@
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
     "baseUrl": ".",
-    "paths": { "@ds": ["design-system/index.ts"] }
+    "paths": {
+      "@ds/review": [
+        "design-system/review/index.ts"
+      ],
+      "@ds": [
+        "design-system/index.ts"
+      ]
+    }
   },
-  "include": ["src", "design-system", "vite.config.ts"]
+  "include": [
+    "src",
+    "design-system",
+    "vite.config.ts"
+  ]
 }

package/dist/bootstrap-ds/vite.config.ts

@@ -7,7 +7,7 @@ import { linariaTagResolver } from "@reqvire-org/ads/linaria";
 export default defineConfig({
   plugins: [wyw({ tagResolver: linariaTagResolver }), react()],
   resolve: {
-    alias: { "@ds": path.resolve(import.meta.dirname, "design-system/index.ts") },
+    alias: { "@ds/review": path.resolve(import.meta.dirname, "design-system/review/index.ts"), "@ds": path.resolve(import.meta.dirname, "design-system/index.ts") },
   },
   build: {
     outDir: "dist",

package/dist/boundaries.mjs

@@ -4,15 +4,18 @@ import { importedUiName } from "./ui-framework.mjs";
 import { isInside, isStateVariable, isTestFile, isDevelopmentFile } from "./config.mjs";
 import { isSharedToken } from "./token-policy.mjs";
 import { scopedTokenOwner } from "./scoped-tokens.mjs";
+import { runtimeBindingOwner } from "./unit-contracts.mjs";
 
-export function projectCompilerOptions({ root }) {
+export function projectCompilerOptions({ root, config, dsRoot }) {
   const file = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json");
   let compiler = {};
   if (file && isInside(root, file)) {
     const parsed = ts.readConfigFile(file, ts.sys.readFile);
     if (!parsed.error) compiler = ts.parseJsonConfigFileContent(parsed.config, ts.sys, path.dirname(file)).options;
   }
-  return compiler;
+  return config && dsRoot ? { ...compiler, paths: { ...compiler.paths,
+    [config.publicAlias]: [path.join(dsRoot, config.publicEntry)],
+    [`${config.publicAlias}/review`]: [path.join(dsRoot, config.reviewEntry)] } } : compiler;
 }
 
 export function importResolver(options) {
@@ -62,6 +65,7 @@ export function checkComponentVariable(name, filename, options) {
   const showcase = development;
   const owned = scopedTokenOwner(options, name);
   if (owned) return path.resolve(options.root, owned.file) === filename ? null : { rule: "token-ownership", message: `Define ${name} only in ${owned.file}, owned by ${owned.unit}. Consume it with var(); runtime geometry remains a separate styleWrites boundary.` };
+  if (runtimeBindingOwner(options, name)) return { rule: "binding-ownership", message: `${name} belongs to a declared runtime producer. Do not redefine instance bindings in CSS or arbitrary style objects.` };
   if (isSharedToken(name)) return tokens ? null : { rule: "token-ownership", message: `Define ${name} in ADS tokens, not component, pattern, showcase, or app styles.` };
   if (name.startsWith("--ux-")) return patterns || showcase ? null : { rule: "variable-ownership", message: "--ux-* variables belong to ADS patterns and showcase composition." };
   if (name.startsWith("--showcase-")) return showcase ? null : { rule: "variable-ownership", message: "--showcase-* variables belong to the ADS showcase." };

package/dist/check.mjs

@@ -3,12 +3,16 @@ import path from "node:path";
 import ts from "typescript";
 import postcss from "postcss";
 import valueParser from "postcss-value-parser";
-import { importViolation, isInside, loadConfig, sourceFiles, isDevelopmentFile, isTestFile } from "./config.mjs";
+import { importViolation, isInside, loadConfig, sourceFiles, isDevelopmentFile, isTestFile, isReviewFile } from "./config.mjs";
 import { inspectTokens, references } from "./tokens.mjs";
 import { foundationFiles, foundationImportTarget, isSharedToken } from "./token-policy.mjs";
 import { inspectAssets } from "./assets.mjs";
 import { appImportViolation, showcaseImportViolation, checkComponentVariable, importResolver, projectCompilerOptions, isUiCssProperties, styleWriteViolation } from "./boundaries.mjs";
 import { inspectPublicProps } from "./public-props.mjs";
+import { adsFileRole } from "./config.mjs";
+import { inspectPaintContracts, inspectTokenValueFlows } from "./paint-contracts.mjs";
+import { runtimeBindingOwner } from "./unit-contracts.mjs";
+import { inspectRuntimeContracts } from "./runtime-contracts.mjs";
 import { inspectHtml, isMountCss } from "./html.mjs";
 import { inspectShowcasePages } from "./showcase.mjs";
 import { inspectShowcaseCoverage } from "./showcase-coverage.mjs";
@@ -25,8 +29,9 @@ import { createScenarioSlots } from "./scenario-slots.mjs";
 import { createScenarioSelectors } from "./scenario-selectors.mjs";
 import { architectureEvidence, failure } from "./evidence.mjs";
 import { propertyRegistration } from "./property-registrations.mjs";
+import { createLayerBoundaries, layerSourceFiles } from "./layers.mjs";
 
-const scenarioLayoutGuidance = "Put demo-only sizing and framing in a public review/layout pattern. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
+const scenarioLayoutGuidance = "Put demo-only sizing and framing in the development-only review/ layer, imported through the separate review entry. Patterns are production UI. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
 const inlineStyleGuidance = `Own visual styles in component/pattern Linaria. ${scenarioLayoutGuidance} Reserve inlineStyleFiles for documented measured geometry, not demo layout.`;
 
 const showcaseControls = new Set(["a", "button", "input", "select", "textarea", "option", "optgroup", "table", "thead", "tbody", "tfoot", "tr", "td", "th", "dialog", "details", "summary", "progress", "meter"]);
@@ -42,7 +47,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     if (!existsSync(file) || (field === "dsDir" ? !statSync(file).isDirectory() : !statSync(file).isFile())) diagnostics.push({ rule: "project-structure", file: path.relative(root, file), line: 1, column: 1, message: `Missing or invalid ${field}. Bootstrap an empty ADS or configure its actual path.` });
   }
   if (diagnostics.length) return architectureEvidence({ ok: false, diagnostics });
-  const tokenInventory = inspectTokens(root);
+  const tokenInventory = inspectTokens(root, options);
   const declaredTokens = new Set(tokenInventory.tokens.map((token) => token.name));
   diagnostics.push(...tokenInventory.diagnostics);
   diagnostics.push(...inspectAssets(options));
@@ -52,16 +57,25 @@ export function checkProject(directory, { trackingRoot } = {}) {
   const rootHtml = path.join(root, "index.html");
   const files = [...new Set([...sourceFiles(sourceRoot), ...sourceFiles(dsRoot), ...(existsSync(rootHtml) ? [rootHtml] : [])])];
   const boundaryFiles = [...config.inlineStyleFiles, ...config.boundaries.styleWrites.map(entry => entry.file)].map(file => path.resolve(root, file)).filter(file => existsSync(file) && statSync(file).isFile());
-  const scriptFiles = [...new Set([...files, ...boundaryFiles])].filter((file) => /\.[cm]?[jt]sx?$/.test(file));
+  const scriptFiles = layerSourceFiles([...new Set([...files, ...boundaryFiles])].filter((file) => /\.[cm]?[jt]sx?$/.test(file)), options);
   const compiler = projectCompilerOptions(options);
   const program = ts.createProgram(scriptFiles, { ...compiler, paths: { ...compiler.paths, [config.publicAlias]: [path.join(dsRoot, config.publicEntry)] }, allowJs: true, noResolve: true, noLib: true, types: [], target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, jsx: ts.JsxEmit.Preserve });
   const checker = program.getTypeChecker();
+  const paintContracts = inspectPaintContracts(options);
+  diagnostics.push(...paintContracts.diagnostics);
+  const runtimeContracts = inspectRuntimeContracts(options, program);
+  diagnostics.push(...runtimeContracts.diagnostics);
+  for (const binding of runtimeContracts.bindings) if (scoped.definitions.some(entry=>entry.namespace.startsWith(binding.prefix)||binding.prefix.startsWith(entry.namespace))) diagnostics.push({file:binding.file,rule:"binding-collision",line:1,column:1,message:`Runtime family ${binding.variable} overlaps an owner-local design-token namespace. Keep instance bindings separate from token definitions.`});
   const atomicCompositionReview = createAtomicCompositionReview(program, options);
   const scenarioTrace = createScenarioTrace(program, options);
   let scenarioSlot, scenarioSelector;
-  function report(file, rule, message, line = 1, column = 1) {
-    diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column });
+  function report(file, rule, message, line = 1, column = 1, detail = {}) {
+    diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column, ...detail });
   }
+  const layers = createLayerBoundaries(program, options, report), layerStyles = [];
+  layers.inspectDependencies();
+  inspectTokenValueFlows(program, options, tokenInventory, scoped, report);
+  for (const file of layers.runtimeHelpers()) if (!files.includes(file)) files.push(file);
   inspectStyleBoundaries(options, program, report);
   inspectShowcasePages(options, program, resolveImport, report);
   inspectShowcaseCoverage(options, program, report);
@@ -82,7 +96,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
           let defined=false;css.walkDecls(registration.name,()=>{defined=true;});
           if(!isSharedToken(registration.name)||!declaredTokens.has(registration.name)||!defined||["base.css","fonts.css"].includes(path.basename(file)))throw new Error("Shared @property registrations belong beside their real token definitions in foundation value sheets, not base.css or fonts.css.");
         }else{
-          if(!owner||!/^(?:components|patterns)\//.test(owner))throw new Error("@property belongs to its runtime component/pattern or real token value sheet, never application, scenario, controller or shared reset styling.");
+          if(!owner||!/^(?:components|patterns|review)\//.test(owner))throw new Error("@property belongs to its component/pattern/review implementation or real token value sheet, never application, scenario, controller or shared reset styling.");
           const violation=checkComponentVariable(registration.name,file,options);if(violation)throw new Error(violation.message);
         }
         for(const descriptor of rule.nodes??[])if(descriptor.type==="decl")for(const ref of references(descriptor.value)){
@@ -106,9 +120,11 @@ export function checkProject(directory, { trackingRoot } = {}) {
     let css;
     try { css = postcss.parse(text, { from: file }); }
     catch (error) { report(file, "css-syntax", error.reason ?? error.message, offset.line + (error.line ?? 1) - 1); return; }
+    layers.collectComponentStyles(file, css);
+    layerStyles.push({ file, css, offset });
     checkRegistrations(file,css,offset);
-    if (!foundation && (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry)) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components or patterns.");
-    if (isDevelopmentFile(file, options) && css.nodes.some((node) => node.type !== "comment" && !(node.type === "atrule" && node.name === "import"))) report(file, "showcase-style", `Scenarios and fixtures define no styles. ${scenarioLayoutGuidance}`, offset.line);
+    if (!foundation && !isReviewFile(file, options) && (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry)) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components/patterns or development review implementations.");
+    if (isDevelopmentFile(file, options) && !isReviewFile(file, options) && css.nodes.some((node) => node.type !== "comment" && !(node.type === "atrule" && node.name === "import"))) report(file, "showcase-style", `Scenarios and fixtures define no styles. ${scenarioLayoutGuidance}`, offset.line);
     css.walkAtRules("import", (rule) => {
       if (foundation) report(file, "foundation-import", "Import foundation sheets through the configured styles entry. Token sheets cannot import an unchecked styling layer.", rule.source.start.line);
       const first = valueParser(rule.params).nodes.find((node) => node.type !== "space" && node.type !== "comment");
@@ -126,7 +142,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
       }
       if (isInside(path.join(dsRoot, "showcase"), file) && /:(?:hover|active|focus(?:-visible|-within)?|checked|disabled|enabled)\b|\[(?:aria-(?:selected|pressed|checked|disabled|expanded)|data-state)\b/.test(rule.selector)) report(file, "showcase-state", "Interactive state styling belongs to the real ADS component or pattern, not showcase or mock styles.", offset.line + rule.source.start.line - 1);
       if (/\.ads-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "components"), file)) report(file, "style-ownership", "ADS component internals are owned by components, not app or showcase CSS.", offset.line + rule.source.start.line - 1);
-      if (/\.ux-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "patterns"), file)) report(file, "style-ownership", "Pattern internals are owned by patterns, not app or showcase CSS.", offset.line + rule.source.start.line - 1);
+      if (/\.ux-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "patterns"), file) && !isReviewFile(file, options)) report(file, "style-ownership", "Pattern internals are owned by patterns, not app or scenario CSS.", offset.line + rule.source.start.line - 1);
       if (/\.showcase-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "showcase"), file)) report(file, "style-ownership", "Showcase internals are owned by showcase scaffolding.", offset.line + rule.source.start.line - 1);
     });
     if (foundation) css.walkAtRules(rule => {
@@ -148,6 +164,11 @@ export function checkProject(directory, { trackingRoot } = {}) {
       const variable = checkComponentVariable(decl.prop, file, options);
       if (variable) report(file, variable.rule, variable.message, offset.line + decl.source.start.line - 1, decl.source.start.column);
       for (const ref of references(decl.value)) {
+        const binding = runtimeBindingOwner(options, ref.name);
+        if (binding) {
+          if (scoped.inventory.owner(scoped.inventory.relative(path.relative(root, file))) !== binding.unit) report(file, "binding-ownership", `${ref.name} is an instance binding owned by ${binding.unit}, not a shared design token.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
+          continue;
+        }
         const owned = scopedTokenOwner(options, ref.name);
         if (owned) {
           if (scoped.inventory.owner(scoped.inventory.relative(path.relative(root, file))) !== owned.unit || !declaredTokens.has(ref.name)) report(file, "token-reference", `${ref.name} belongs to ${owned.unit}. Use shared tokens across owners; owner-local tokens must be defined and consumed by their owner.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
@@ -173,6 +194,9 @@ export function checkProject(directory, { trackingRoot } = {}) {
     });
   }
   for (const file of files) {
+    const role = adsFileRole(file);
+    const roleExtension=role==="contract"?/\.[cm]?ts$/.test(file):["fixture","fixtures"].includes(role)?/\.(?:[cm]?[jt]sx?|json)$/.test(file):/\.[cm]?[jt]sx?$/.test(file);
+    if (role && (!["contract", "scenario", "fixture", "fixtures", "helpers", "test", "spec", "behavior.spec"].includes(role)||!roleExtension)) report(file, "development-role", `Unknown .ads. role or unsupported extension: ${role}. Use a TypeScript contract, a script scenario/fixture/helpers/test/behavior.spec, or JSON fixture; marking development code does not grant styling or mutation permissions.`);
     if (scopedFiles.has(file)) { try{checkRegistrations(file,postcss.parse(readFileSync(file,"utf8"),{from:file}));}catch{/* Token inspection reports malformed sheets. */} continue; } // Closed definition-only contract checked by inspectTokens.
     if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) { checkCss(file, readFileSync(file, "utf8"), undefined, true); continue; }
     if (file.endsWith(".html")) { inspectHtml(readFileSync(file, "utf8"), (rule, message, line) => report(file, rule, message, line)); continue; }
@@ -190,7 +214,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
       report(file, "source-syntax", ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"), position.line + 1, position.character + 1);
     }
     const inlineAllowed = config.inlineStyleFiles.some((allowed) => path.resolve(root, allowed) === file);
-    const showcase = isDevelopmentFile(file, options) && !isTestFile(file);
+    const showcase = isDevelopmentFile(file, options) && !isTestFile(file) && !isReviewFile(file, options);
     function nodeReport(node, rule, message, detail) {
       const position = source.getLineAndCharacterOfPosition(node.getStart(source));
       report(file, rule, message, position.line + 1, position.character + 1);
@@ -206,7 +230,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
       const selector = native ? (scenarioSelector ??= createScenarioSelectors(program, options))(node) : { ok: false, reasons: ["A selector cannot establish custom widget behavior or keyboard semantics."] };
       if (!selector.ok) nodeReport(node, "showcase-control", `Scenario controls must compose public ADS runtime UI. Native semantics require source evidence of owned cloning props or an attached runtime Linaria selector addressing that native tag or a verified runtime-owned part in that position. A prop name, broad selector or scenario-authored marker grants no permission. ${selector.reasons.join(" ")} Preserve valid APIs when tracing is inconclusive; report the limitation instead of changing the API to satisfy coverage. ${scenarioLayoutGuidance} See ads://guides/scenarios.`, { failure: failure("architecture", "source-ownership", "ownership-not-proven", { certainty: "inconclusive" }) });
     }
-    if (!showcase && (isInside(path.join(dsRoot, "components"), file) || isInside(path.join(dsRoot, "patterns"), file))) inspectPublicProps(source, checker, nodeReport);
+    if (!showcase && (isInside(path.join(dsRoot, "components"), file) || isInside(path.join(dsRoot, "patterns"), file))) inspectPublicProps(source, checker, nodeReport, paintContracts.allowedProperties);
     function isLinariaTag(tag) {
       if (ts.isCallExpression(tag)) tag = tag.expression;
       let symbolNode = tag;
@@ -234,8 +258,8 @@ export function checkProject(directory, { trackingRoot } = {}) {
     function inspectClass(value) {
       if (ts.isStringLiteralLike(value)) {
         if (/(?:^|\s)ads-[\w-]+/.test(value.text) && !isInside(path.join(dsRoot, "components"), file)) nodeReport(value, "style-ownership", "Primitive ads-* classes must be emitted by components, not consumers.");
-        if (/(?:^|\s)ux-[\w-]+/.test(value.text) && !isInside(path.join(dsRoot, "patterns"), file)) nodeReport(value, "style-ownership", "Pattern ux-* classes must be emitted by patterns, not consumers.");
-        if (/(?:^|\s)showcase-[\w-]+/.test(value.text) && !isInside(path.join(dsRoot, "showcase"), file)) nodeReport(value, "style-ownership", "Showcase hooks must be emitted by the showcase, not runtime implementations.");
+        if (/(?:^|\s)ux-[\w-]+/.test(value.text) && !isInside(path.join(dsRoot, "patterns"), file) && !isReviewFile(file, options)) nodeReport(value, "style-ownership", "Pattern ux-* classes must be emitted by patterns, not consumers.");
+        if (/(?:^|\s)showcase-[\w-]+/.test(value.text) && !isInside(path.join(dsRoot, "showcase"), file) && !isReviewFile(file, options)) nodeReport(value, "style-ownership", "Showcase hooks must be emitted by development review code, not runtime implementations.");
       }
       ts.forEachChild(value, inspectClass);
     }
@@ -289,13 +313,14 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (specifier && resolveImport(specifier, file).some((target) => (specifier.startsWith(".") || existsSync(target)) && target.endsWith(".css") && isInside(root, target) && !isInside(dsRoot, target) && target !== path.join(sourceRoot, "app-mount.css") && !isInside(path.join(root, "node_modules"), target))) nodeReport(node, "style-ownership", "Imported project CSS belongs to ADS components, patterns, or the foundation. Only structural app-mount.css is allowed outside the ADS.");
       if (specifier && appImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "no-app-import", "ADS implementations and showcase fixtures must not import app code. Use public ADS APIs with local fixture data; keep application integration harnesses in application tests.");
       if (specifier && showcaseImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.");
-      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(node, "no-inline-style", showcase ? `Scenarios define no inline styles. ${scenarioLayoutGuidance}` : inlineStyleGuidance);
+      const boundStyle = runtimeContracts.allowedStyles.has(`${file}:${node.pos}`);
+      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase) && !boundStyle) nodeReport(node, "no-inline-style", showcase ? `Scenarios define no inline styles. ${scenarioLayoutGuidance}` : inlineStyleGuidance);
       if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && node.initializer) {
         inspectProperty(node.initializer);
       }
       const mutation = styleWriteViolation(node, file, options);
       if (mutation) nodeReport(node, "style-mutation", mutation);
-      if (!inlineAllowed && isUiCssProperties(node, checker)) nodeReport(node, "css-properties", "Keep CSSProperties out of the public API. Use deliberate component contracts or a documented measured-geometry renderer boundary; demo layout belongs in a public review pattern.");
+      if (!inlineAllowed && isUiCssProperties(node, checker) && !runtimeContracts.allowedStyleTypes.has(`${file}:${node.pos}`)) nodeReport(node, "css-properties", "Keep CSSProperties out of the public API. Use deliberate component contracts or a documented measured-geometry renderer boundary; demo layout belongs in a development-only review/ helper.");
       if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className" && node.initializer) {
         inspectClass(node.initializer);
       }
@@ -310,6 +335,8 @@ export function checkProject(directory, { trackingRoot } = {}) {
     visit(source);
   }
   // Bounded clients should see actionable warnings before source-analysis limits.
+  for (const { file, css, offset } of layerStyles) layers.inspectStyles(file, css, offset);
   advisories.sort((first, second) => Number(first.severity === "info") - Number(second.severity === "info"));
-  return architectureEvidence({ ok: diagnostics.length === 0, diagnostics, ...(advisories.length ? { advisories } : {}) });
+  const uniqueDiagnostics=[...new Map(diagnostics.map(diagnostic=>[JSON.stringify([diagnostic.file,diagnostic.rule,diagnostic.line,diagnostic.column,diagnostic.message]),diagnostic])).values()];
+  return architectureEvidence({ ok: uniqueDiagnostics.length === 0, diagnostics:uniqueDiagnostics, ...(advisories.length ? { advisories } : {}) });
 }

package/dist/config.mjs

@@ -11,6 +11,7 @@ export const defaultConfig = {
   dsDir: "design-system",
   publicAlias: "@ds",
   publicEntry: "index.ts",
+  reviewEntry: "review/index.ts",
   stylesEntry: "styles.css",
   tokenDir: "tokens",
   inlineStyleFiles: [],
@@ -54,7 +55,8 @@ export function loadConfig(directory = process.cwd()) {
   if (!Array.isArray(config.inlineStyleFiles)) throw new Error("inlineStyleFiles must be an array of relative paths.");
   const sourceRoot = projectPath(root, config.sourceDir, "sourceDir");
   const dsRoot = projectPath(root, config.dsDir, "dsDir");
-  for (const field of ["publicEntry", "stylesEntry", "tokenDir"]) projectPath(dsRoot, config[field], field);
+  for (const field of ["publicEntry", "reviewEntry", "stylesEntry", "tokenDir"]) projectPath(dsRoot, config[field], field);
+  if (!isInside(path.join(dsRoot, "review"), path.resolve(dsRoot, config.reviewEntry)) || path.resolve(dsRoot, config.reviewEntry) === path.join(dsRoot, "review") || !/\.[cm]?[jt]sx?$/.test(config.reviewEntry)) throw new Error("reviewEntry must name a script entry inside the ADS review/ development layer.");
   for (const file of config.inlineStyleFiles) projectPath(root, file, "inlineStyleFiles");
   if (!Array.isArray(config.boundaries.componentVariables) || config.boundaries.componentVariables.some((name) => typeof name !== "string" || !/^--ds-[\w-]+$/.test(name) || isStateVariable(name))) throw new Error("boundaries.componentVariables must name non-state --ds-* customization variables.");
   if (!Array.isArray(config.boundaries.styleWrites)) throw new Error("boundaries.styleWrites must be an array.");
@@ -161,15 +163,37 @@ export function isTokenManifestFile(file) {
   return /(?:^|[\\/])tokens\.json$|\.tokens\.json$/.test(file);
 }
 
+/** A visible development boundary, independent of whether its role is supported. */
+export function adsFileRole(file) {
+  const match = path.basename(file).match(/\.ads\.(.+)\.[^.]+$/);
+  return match ? match[1] : null;
+}
+
+export function isContractFile(file) {
+  return /\.ads\.contract\.[cm]?ts$/.test(file);
+}
+
+/** Filenames may change without changing the identity used by clients/checks. */
+export function scenarioIdentity(file, dsRoot) {
+  let id = path.relative(dsRoot, file).replaceAll("\\", "/").replace(/\.ads(?=\.)/, "").replace(/(?:\/Scenario|\.scenario)\.[^.]+$/, "");
+  if (adsFileRole(file) === "scenario" && path.posix.basename(id) === path.posix.basename(path.posix.dirname(id))) id = path.posix.dirname(id);
+  return id;
+}
+
 export function isDevelopmentFile(file, { dsRoot }) {
-  if (!isInside(dsRoot, file)) return isTestFile(file);
+  if (!isInside(dsRoot, file)) return isTestFile(file) || adsFileRole(file) !== null;
   const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
-  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file) || isTokenManifestFile(file)
-    || /^(?:showcase|composition)\//.test(relative)
+  return adsFileRole(file) !== null || isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file) || isTokenManifestFile(file)
+    || /^(?:showcase|composition|review)\//.test(relative)
     || /(?:^|\/)(?:scenario|fixtures)(?:\/|$)/.test(relative)
     || /\.scenario(?:-adapter)?\.[cm]?[jt]sx?$/.test(relative);
 }
 
+/** Review implementations may own demo presentation; scenarios/fixtures may not. */
+export function isReviewFile(file, { dsRoot }) {
+  return isInside(path.join(dsRoot, "review"), file) && adsFileRole(file) === null && !isTestFile(file) && !isScenarioFile(file) && !isFixtureFile(file) && !isBehaviorFile(file) && !isTokenManifestFile(file);
+}
+
 const ignored = new Set(["node_modules", "dist", "dist-showcase", "dist-kit", ".git", ".vite", ".ds", "coverage"]);
 
 export function sourceFiles(root) {
@@ -187,7 +211,8 @@ export function sourceFiles(root) {
 export function importViolation(specifier, filename, options, resolve) {
   const { root, dsRoot, config } = options;
   // ADS implementation code needs its private imports; the showcase is a consumer.
-  if (isInside(dsRoot, filename) && !isDevelopmentFile(filename, options)) return false;
+  if (isInside(dsRoot, filename) && (!isDevelopmentFile(filename, options) || isContractFile(filename))) return false; // Contract symbol ownership is checked without executing imports.
+  if (specifier === `${config.publicAlias}/review`) return !isDevelopmentFile(filename, options) && !isTestFile(filename);
   if (specifier.startsWith(`${config.publicAlias}/`)) return true;
   if (specifier === config.publicAlias) return false;
   const imported = resolve ? resolve(specifier, filename)
@@ -195,6 +220,9 @@ export function importViolation(specifier, filename, options, resolve) {
     : specifier.startsWith(`${config.dsDir}/`) ? [path.resolve(root, specifier)] : [];
   return imported.some((file) => {
     if (!isInside(dsRoot, file)) return false;
+    // Review implementations can reuse local foundation helpers. Resolved public
+    // UI/controller contracts are enforced by the layer inspector, as for patterns.
+    if (isReviewFile(filename, options)) return false;
     // Owner-local white-box tests may exercise private helpers without making
     // those helpers public API. Scenarios remain public-API consumers.
     if (isTestFile(filename) && isInside(dsRoot, filename) && isInside(path.dirname(filename), file)) return false;