@reqvire-org/ads 0.3.17 → 0.3.20

package/dist/atomic-composition.mjs

@@ -168,7 +168,7 @@ export function createAtomicCompositionReview(program, options) {
           if (parent.type === "atrule") conditions.unshift(`${parent.name} ${parent.params}`.trim().replace(/\s+/g, " "));
         }
         // Animation frames describe different instants, not combined classes.
-        if (conditions.some(condition => /^(?:-\w+-)?keyframes\b/.test(condition))) return;
+        if (conditions.some(condition => /^(?:(?:-\w+-)?keyframes|property)\b/.test(condition))) return;
         result.push({ property: decl.prop.toLowerCase(), value: decl.value, important: !!decl.important, selectors: JSON.stringify(selectors), conditions: JSON.stringify(conditions),
           file: path.relative(options.root, source.fileName).replaceAll("\\", "/"), line: position.line + decl.source.start.line, column: decl.source.start.column + (decl.source.start.line === 1 ? position.character : 0) });
       });

package/dist/behaviors.mjs

@@ -3,10 +3,10 @@ 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";
 
@@ -31,7 +31,7 @@ export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
   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 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 relative = file => path.relative(root, file).replaceAll("\\", "/");
@@ -45,7 +45,7 @@ export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
       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 +61,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}.`);

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.
 

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

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

@@ -5,14 +5,16 @@ import { isInside, isStateVariable, isTestFile, isDevelopmentFile } from "./conf
 import { isSharedToken } from "./token-policy.mjs";
 import { scopedTokenOwner } from "./scoped-tokens.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) {

package/dist/check.mjs

@@ -3,7 +3,7 @@ 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";
@@ -24,8 +24,10 @@ import { createScenarioTrace } from "./scenario-trace.mjs";
 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"]);
@@ -51,16 +53,19 @@ 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 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();
+  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);
@@ -70,6 +75,30 @@ export function checkProject(directory, { trackingRoot } = {}) {
   inspectControllers(options, program, report, behaviors.contracts);
   // The foundation remains a fixed import-only entry, not an extra styling layer.
   const foundationEntry = path.join(dsRoot, config.stylesEntry);
+  const registeredProperties=new Map();
+  function checkRegistrations(file,css,offset={line:1}){
+    css.walkAtRules(/^property$/i,rule=>{
+      const line=offset.line+(rule.source?.start.line??1)-1;
+      try{
+        const registration=propertyRegistration(rule),relative=scoped.inventory.relative(path.relative(root,file));
+        const owner=scoped.inventory.owner(relative),foundation=isInside(path.join(dsRoot,config.tokenDir),file);
+        if(foundation){
+          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|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)){
+          const tokenOwner=scopedTokenOwner(options,ref.name);
+          if(tokenOwner&&(tokenOwner.unit!==owner||!declaredTokens.has(ref.name))||!tokenOwner&&!/^(?:--ds-|--ux-|--showcase-)/.test(ref.name)&&(!isSharedToken(ref.name)||!declaredTokens.has(ref.name)&&!ref.fallback))throw new Error(`Invalid or cross-owner token reference ${ref.name} in registration metadata.`);
+        }
+        const previous=registeredProperties.get(registration.name);
+        if(previous&&(previous.owner!==owner||previous.signature!==registration.signature))throw new Error(`Conflicting @property registration for ${registration.name}; ${path.relative(root,previous.file)} already registers it. Keep one owner and identical descriptors across that owner's modules.`);
+        registeredProperties.set(registration.name,{...registration,owner,file});
+      }catch(error){report(file,"property-registration",`${error.message} See ads://guides/atomic-styles.`,line,rule.source?.start.column??1);diagnostics.at(-1).guidanceUri="ads://guides/atomic-styles";}
+    });
+  }
   try {
     const css = postcss.parse(readFileSync(foundationEntry, "utf8"), { from: foundationEntry });
     const imports = css.nodes.filter((node) => node.type !== "comment");
@@ -81,8 +110,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; }
-    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);
+    layers.collectComponentStyles(file, css);
+    layerStyles.push({ file, css, offset });
+    checkRegistrations(file,css,offset);
+    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");
@@ -100,7 +132,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 => {
@@ -108,12 +140,13 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (rule.name === "font-face" && path.basename(file) !== "fonts.css") report(file, "foundation-role", "Font faces belong in the canonical fonts.css foundation sheet.", rule.source.start.line);
     });
     css.walkDecls((decl) => {
+      const propertyDescriptor=decl.parent.type==="atrule"&&decl.parent.name.toLowerCase()==="property";
       if (foundation && decl.prop.startsWith("--")) {
         if (path.basename(file) === "base.css") report(file, "foundation-role", "Shared token definitions belong in value sheets, not base.css.", decl.source.start.line, decl.source.start.column);
         return; // Definition names, values and aliases are validated by inspectTokens.
       }
       const fontDescriptor = foundation && path.basename(file) === "fonts.css" && decl.parent.type === "atrule" && decl.parent.name === "font-face";
-      if (foundation && !fontDescriptor && (path.basename(file) !== "base.css" || decl.parent.type !== "rule")) report(file, "foundation-role", "Token sheets contain shared definitions; native defaults belong in base.css, font descriptors in fonts.css, and UI styling in Linaria owners.", decl.source.start.line, decl.source.start.column);
+      if (foundation && !fontDescriptor && !propertyDescriptor && (path.basename(file) !== "base.css" || decl.parent.type !== "rule")) report(file, "foundation-role", "Token sheets contain shared definitions; native defaults belong in base.css, font descriptors in fonts.css, and UI styling in Linaria owners.", decl.source.start.line, decl.source.start.column);
       if (foundation && path.basename(file) === "base.css" && decl.parent.type === "rule") {
         const violation = foundationDeclaration(decl.parent, decl);
         if (violation) report(file, "foundation-role", violation, decl.source.start.line, decl.source.start.column);
@@ -131,7 +164,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
         if (!local && !isSharedToken(ref.name)) report(file, "token-name", `${ref.name} does not follow ADS's fixed token naming contract.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
         else if (!local && !declaredTokens.has(ref.name) && !ref.fallback) report(file, "token-reference", `Undefined shared token ${ref.name}.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
       }
-      if (fontDescriptor) return; // Font metadata defines source assets, not token-backed UI styles.
+      if (fontDescriptor || propertyDescriptor) return; // Font metadata defines source assets, not token-backed UI styles.
       const violations = new Set();
       valueParser(decl.value).walk((node) => {
         if (node.type === "function" && node.value === "url") return false;
@@ -146,7 +179,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     });
   }
   for (const file of files) {
-    if (scopedFiles.has(file)) continue; // Closed definition-only contract checked by inspectTokens.
+    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; }
     if (file.endsWith(".css")) {
@@ -163,7 +196,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);
@@ -207,8 +240,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);
     }
@@ -268,7 +301,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
       }
       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)) 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);
       }
@@ -283,6 +316,7 @@ 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 } : {}) });
 }

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.");
@@ -165,11 +167,16 @@ export function isDevelopmentFile(file, { dsRoot }) {
   if (!isInside(dsRoot, file)) return isTestFile(file);
   const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
   return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file) || isTokenManifestFile(file)
-    || /^(?:showcase|composition)\//.test(relative)
+    || /^(?: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) && !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) {
@@ -188,6 +195,7 @@ 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 (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 +203,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;

package/dist/init.mjs

@@ -153,15 +153,15 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
   });
   if (!existingTokens.length) {
     for (const name of ["Foundation.scenario.tsx", "Foundation.fixture.ts"]) {
-      const content = readFileSync(path.join(starter, "design-system/tokens", name), "utf8").replaceAll('"@ds"', JSON.stringify(config.publicAlias));
+      const content = readFileSync(path.join(starter, "design-system/tokens", name), "utf8").replaceAll('"@ds/review"', JSON.stringify(`${config.publicAlias}/review`)).replaceAll('"@ds"', JSON.stringify(config.publicAlias));
       addMissing(path.join(tokenRoot, name), content);
     }
-    for (const name of ["TokenPreview.tsx", "Scenario.tsx", "fixture.ts"]) {
-      let content = readFileSync(path.join(starter, "design-system/patterns/token-preview", name), "utf8");
+    for (const name of ["TokenPreview.tsx"]) {
+      let content = readFileSync(path.join(starter, "design-system/review/token-preview", name), "utf8");
       if (selectedFramework === "preact") content = content.replace('from "react"', 'from "preact/hooks"');
-      addMissing(path.join(dsRoot, "patterns/token-preview", name), content.replaceAll('"@ds"', JSON.stringify(config.publicAlias)));
+      addMissing(path.join(dsRoot, "review/token-preview", name), content.replaceAll('"@ds"', JSON.stringify(config.publicAlias)));
     }
-    const reviewFile = path.relative(root, path.join(dsRoot, "patterns/token-preview/TokenPreview.tsx")).replaceAll("\\", "/");
+    const reviewFile = path.relative(root, path.join(dsRoot, "review/token-preview/TokenPreview.tsx")).replaceAll("\\", "/");
     if (!config.boundaries.styleWrites.some(item => item.file === reviewFile)) config.boundaries.styleWrites.push({ file: reviewFile, properties: ["--ux-token-preview-value"] });
   }
   tokenFiles.sort((a, b) => foundationFiles.indexOf(path.basename(a)) - foundationFiles.indexOf(path.basename(b)) || a.localeCompare(b));
@@ -172,16 +172,19 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
   };
   addMissing(stylesFile, tokenFiles.map((file) => `@import ${JSON.stringify(relativeImport(stylesFile, file))};`).join("\n") + "\n");
   const entryFile = path.join(dsRoot, config.publicEntry);
-  const reviewExport = !existingTokens.length ? `export { TokenPreview } from ${JSON.stringify(relativeImport(entryFile, path.join(dsRoot, "patterns/token-preview/TokenPreview")))};\n` : "";
-  addMissing(entryFile, `// Export your project's public components and types here.\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\n${reviewExport}`);
-  if (reviewExport && existsSync(entryFile) && !readFileSync(entryFile, "utf8").includes("patterns/token-preview/TokenPreview")) {
-    let current = readFileSync(entryFile, "utf8");
-    if (/\bTokenPreview\b/.test(current)) throw new Error("TokenPreview is already owned by this project. Add a token review scenario using its public API before initializing the foundation.");
-    const ast = ts.createSourceFile(entryFile, current, ts.ScriptTarget.Latest, true);
-    for (const statement of [...ast.statements].reverse()) if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause) && !statement.exportClause.elements.length) {
-      current = current.slice(0, statement.getStart(ast)) + current.slice(statement.end);
+  addMissing(entryFile, `// Export your project's public components and types here.\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\n`);
+  if (!existingTokens.length) {
+    const reviewEntry = path.join(dsRoot, config.reviewEntry);
+    const reviewExport = `export { TokenPreview } from ${JSON.stringify(relativeImport(reviewEntry, path.join(dsRoot, "review/token-preview/TokenPreview")))};\n`;
+    addMissing(reviewEntry, reviewExport);
+    if (existsSync(reviewEntry) && !readFileSync(reviewEntry, "utf8").includes("token-preview/TokenPreview")) throw new Error("The project owns an existing review entry. Add the new token renderer through that development API before initializing the foundation.");
+    if (existsSync(entryFile)) {
+      let current = readFileSync(entryFile, "utf8");
+      const ast = ts.createSourceFile(entryFile, current, ts.ScriptTarget.Latest, true);
+      for (const statement of [...ast.statements].reverse()) if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause) && !statement.exportClause.elements.length) current = current.slice(0, statement.getStart(ast)) + current.slice(statement.end);
+      if (!ast.statements.some(statement => ts.isImportDeclaration(statement) || statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword))) current += `\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\n`;
+      if (current !== readFileSync(entryFile, "utf8")) updates.set(entryFile, current);
     }
-    updates.set(entryFile, current + "\n" + reviewExport);
   }
   for (const section of ["components", "patterns", "controllers", "composition"]) addMissing(path.join(dsRoot, section, ".gitkeep"), "");
   addMissing(path.join(dsRoot, "assets/brand/README.md"), readFileSync(path.join(starter, "design-system/assets/brand/README.md")));

package/dist/investigations.mjs

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
+import { compactAcceptance, compactRow, jsonBytes, resultBudgets, resultPage, resultRecord } from "./mcp/result-pages.mjs";
 
 export const INVESTIGATIONS_URI = "ads://project/investigations";
 const indexFile = root => path.join(root,".ds/investigations.json");
@@ -32,7 +33,7 @@ export function saveInvestigations(root, entries, registered) {
 }
 
 export function investigationIndex(root) {
-  return {retention:"latest-per-check",entries:Object.values(saved(root)).map(({unit,check,status,completedAt,inputRevision,resourceUri,failure})=>({unit,check,status,completedAt,inputRevision,resourceUri,...(failure?{failure}:{})}))};
+  return {retention:"latest-per-check",entries:Object.values(saved(root)).map(({unit,check,status,runId,target,completedAt,inputRevision,resourceUri,failure})=>({unit,check,status,runId,target,completedAt,inputRevision,resourceUri,...(failure?{failure}:{})}))};
 }
 
 export function readInvestigation(root,{unit,check}) {
@@ -41,6 +42,35 @@ export function readInvestigation(root,{unit,check}) {
   return {...bundle,artifacts:(bundle.artifacts??[]).map(artifact=>({...artifact,available:!!artifactPath(root,artifact.path)}))};
 }
 
+export const investigationSections=["summary","details","requests","browserErrors","artifacts"];
+export function investigationPage(root,{unit,check,runId,section="summary",cursor,limit,recordIndex,offset,chars}={}) {
+  if(check===undefined){
+    if(runId!==undefined||section!=="summary"||recordIndex!==undefined||offset!==undefined||chars!==undefined)throw new Error("Select an exact unit/check before reading investigation details.");
+    const entries=investigationIndex(root).entries.filter(entry=>!unit||entry.unit===unit);
+    return resultPage(entries,{cursor,limit,identity:["investigations",unit,entries],key:"entries",header:{retention:"latest-per-check"}});
+  }
+  if(!unit||!investigationSections.includes(section))throw new Error("Select an exact unit/check and a known investigation section.");
+  const bundle=readInvestigation(root,{unit,check});
+  if(runId!==undefined&&bundle.runId!==runId)throw new Error("Investigation was superseded by a different run. Do not mix it with the earlier result.");
+  const details={source:bundle.source,failingStep:bundle.failingStep,viewport:bundle.viewport,viewportSource:bundle.viewportSource,failure:bundle.failure};
+  if(section!=="summary"){
+    const rows=(section==="details"?[details]:bundle[section]??[]).map((row,recordIndex)=>({recordIndex,...(row&&typeof row==="object"?row:{value:row})})),header={unit,check,runId:bundle.runId,section};
+    if(recordIndex!==undefined){if(cursor!==undefined||!runId)throw new Error("Read investigation record ranges with the exact runId and without a cursor.");return resultRecord(rows,{recordIndex,offset,chars,header});}
+    if(offset!==undefined||chars!==undefined)throw new Error("Select a recordIndex before reading text ranges.");
+    return resultPage(rows,{cursor,limit,identity:["investigation",unit,check,bundle.runId,bundle.inputRevision,section,rows],header});
+  }
+  if(recordIndex!==undefined||offset!==undefined||chars!==undefined)throw new Error("Select an investigation detail section before reading record ranges.");
+  if(cursor!==undefined)throw new Error("The investigation summary has no continuation; select a detail section.");
+  const result={unit,check,runId:bundle.runId,status:bundle.status,target:bundle.target,inputRevision:bundle.inputRevision,inputsCurrentAtCompletion:bundle.inputsCurrentAtCompletion,
+    framework:bundle.framework,profile:bundle.profile,mode:bundle.mode,scenario:bundle.scenario,observedPreviewRevision:bundle.observedPreviewRevision,
+    details:compactRow(details,1536),
+    acceptance:compactAcceptance(bundle.acceptance),counts:Object.fromEntries(investigationSections.slice(2).map(key=>[key,bundle[key]?.length??0])),resourceUri:bundle.resourceUri,byteLimit:resultBudgets.summary};
+  if(jsonBytes(result)>resultBudgets.summary){delete result.resourceUri;result.resourceUriOmitted=true;result.details=compactRow(result.details,512);}
+  if(jsonBytes(result)>resultBudgets.summary){result.acceptance={status:bundle.acceptance?.status,detailTruncated:true};delete result.scenario;delete result.observedPreviewRevision;result.detailTruncated=true;}
+  if(jsonBytes(result)>resultBudgets.summary)throw new Error("Investigation identity exceeds the summary budget.");
+  return result;
+}
+
 export function investigationArtifacts(root,report,attachments=[]) {
   return attachments.slice(0,5).flatMap(attachment=>{
     if(typeof attachment?.path!=="string")return [];
@@ -57,9 +87,10 @@ export function investigationArtifacts(root,report,attachments=[]) {
 /** Only files explicitly registered by the latest bundles are resource-readable. */
 export function readInvestigationResource(root,uri) {
   if(uri.startsWith("ads://investigations/")) {
-    const parts=uri.slice("ads://investigations/".length).split("/").map(decodeURIComponent);
+    const url=new URL(uri),parts=url.pathname.slice(1).split("/").map(decodeURIComponent);
     if(parts.length!==2)throw new Error("Invalid investigation URI.");
-    return {uri,mimeType:"application/json",text:JSON.stringify(readInvestigation(root,{unit:parts[0],check:parts[1]}))};
+    if([...url.searchParams.keys()].some(key=>!["section","runId","cursor","limit","recordIndex","offset","chars"].includes(key)))throw new Error("Unknown investigation resource query.");
+    return {uri,mimeType:"application/json",text:JSON.stringify(investigationPage(root,{unit:parts[0],check:parts[1],section:url.searchParams.get("section")??"summary",runId:url.searchParams.get("runId")??undefined,cursor:url.searchParams.get("cursor")??undefined,...Object.fromEntries(["limit","recordIndex","offset","chars"].filter(key=>url.searchParams.has(key)).map(key=>[key,Number(url.searchParams.get(key))]))}))};
   }
   const artifact=Object.values(saved(root)).flatMap(bundle=>bundle.artifacts??[]).find(artifact=>artifact.resourceUri===uri);
   const file=artifact&&artifactPath(root,artifact.path);