@reqvire-org/ads 0.3.18 → 0.3.20

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";
@@ -25,8 +25,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"]);
@@ -52,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);
@@ -82,7 +86,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 +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; }
+    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 +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 => {
@@ -190,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);
@@ -234,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);
     }
@@ -295,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);
       }
@@ -310,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")));