@reqvire-org/ads 0.3.18 → 0.3.21

package/dist/units.mjs

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import ts from "typescript";
 import postcss from "postcss";
-import { isDevelopmentFile, isInside } from "./config.mjs";
+import { adsFileRole, isDevelopmentFile, isInside } from "./config.mjs";
 import { importResolver } from "./boundaries.mjs";
 import { documentationFilePolicy, isProjectDocument, projectDocumentFiles } from "./project-documents.mjs";
 import { foundationFiles, foundationImportTarget } from "./token-policy.mjs";
@@ -25,7 +25,7 @@ export function configurationFiles(options) {
     // fixtures to configuration. Those remain in the behavior owner's patch.
     if (isInside(dsRoot, file) && isDevelopmentFile(file, options)) return;
     if (!entrypoint && isInside(sourceRoot, file) && !isInside(dsRoot, file)) return;
-    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|controllers|composition|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
+    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|controllers|composition|review|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
       if (isInside(path.join(dsRoot, "controllers"), file) || isDevelopmentFile(file, options)) return;
       const folder = path.dirname(file), stem = path.basename(file).split(".")[0];
       const anchored = ["index", path.basename(folder)].some(name => [".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"].some(extension => existsSync(path.join(folder, name + extension))));
@@ -98,34 +98,39 @@ export function inspectUnits(options) {
   // Runtime entry conventions keep directory ownership stable when an optional
   // preview is removed. A flat scenario family still denotes separate owners.
   const sameName = name => name.replace(/[-_]/g, "").toLowerCase();
-  const flatFamilies = new Set(files.filter(file => /\.scenario\.[cm]?[jt]sx?$/.test(file)).map(file => path.posix.dirname(file)));
+  const flatFamilies = new Set(files.filter(file => !adsFileRole(file) && /\.scenario\.[cm]?[jt]sx?$/.test(file)).map(file => path.posix.dirname(file)));
   const directories = new Set(files.filter(file => /(?:^|\/)Scenario\.[cm]?[jt]sx?$/.test(file)).map(file => slash(path.dirname(file))));
   for (const file of files.filter(file => /^(?:components|patterns)\/.+\/tokens\.json$/.test(file))) directories.add(path.posix.dirname(file));
+  for (const file of files.filter(file => /\.ads\.contract\.[cm]?ts$/.test(file))) {
+    const directory=path.posix.dirname(file);
+    if(directory.includes("/")&&sameName(path.basename(file).split(".")[0])===sameName(path.posix.basename(directory))&&!flatFamilies.has(directory))directories.add(directory);
+  }
   for (const file of files) {
-    if (!/^(?:components|patterns|controllers|composition)\//.test(file) || !source.test(file)) continue;
+    if (!/^(?:components|patterns|controllers|composition|review)\//.test(file) || !source.test(file)) continue;
     const directory = slash(path.dirname(file)), name = path.basename(file).replace(source, "");
-    if (!directory.includes("/") || /\.(?:scenario|fixture|scenario-adapter)$/.test(name)) continue;
+    if (!directory.includes("/") || adsFileRole(file) || /\.(?:scenario|fixture|scenario-adapter)$/.test(name)) continue;
     if (flatFamilies.has(directory)) continue;
     if (name === "index" || sameName(name) === sameName(path.posix.basename(directory)) || name === "fixture") directories.add(directory);
   }
   const directoryUnits = [...directories].sort((a, b) => b.length - a.length);
-  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|controllers|composition)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
+  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|controllers|composition|review)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
     const base = path.basename(file).split(".")[0];
     return slash(path.join(path.dirname(file), base));
   }))].sort((a, b) => b.length - a.length);
   const publicEntry = slash(path.relative(dsRoot, path.join(dsRoot, config.publicEntry)));
+  const reviewEntry = slash(path.relative(dsRoot, path.join(dsRoot, config.reviewEntry)));
   const tokenDir = slash(path.relative(dsRoot, path.join(dsRoot, config.tokenDir)));
   const stylesEntry = slash(path.relative(dsRoot, path.join(dsRoot, config.stylesEntry)));
   function owner(relative) {
     const projectFile = slash(path.relative(root, path.resolve(dsRoot, relative)));
     if (setup.has(projectFile)) return "configuration";
     if (!isInside(dsRoot, path.resolve(dsRoot, relative))) return isProjectDocument(projectFile) ? "documentation" : null;
-    if (relative === publicEntry) return null; // Controlled re-export bookkeeping.
+    if (relative === publicEntry || relative === reviewEntry) return null; // Controlled re-export bookkeeping.
     if (relative.startsWith(tokenDir + "/")) return "tokens";
     if (relative.startsWith("assets/")) return relative.split("/").length > 2 ? relative.split("/").slice(0, 2).join("/") : "assets";
     if (isProjectDocument(relative)) return "documentation";
     if (!relative.includes("/")) return /(?:\.(?:md|txt)$|^LICENSE$)/i.test(relative) ? "documentation" : "foundation";
-    if (!/^(?:components|patterns|controllers|composition)\//.test(relative)) return relative.split("/")[0] === "documentation" ? null : relative.split("/")[0];
+    if (!/^(?:components|patterns|controllers|composition|review)\//.test(relative)) return relative.split("/")[0] === "documentation" ? null : relative.split("/")[0];
     for (const directory of directoryUnits) if (relative.startsWith(directory + "/")) return directory;
     for (const unit of flatUnits) if (relative.startsWith(unit + "/") || relative.startsWith(unit + ".")) return unit;
     const base = path.basename(relative).split(".")[0];
@@ -146,22 +151,25 @@ export function inspectUnits(options) {
     if (!units.get(id).files.includes(file)) units.get(id).files.push(file);
   }
   for (const unit of units.values()) if (boundaryCompanion(unit.id)) {
+    const contracts=unit.files.filter(file=>/\.ads\.contract\.[cm]?ts$/.test(file));
+    if(contracts.length===1)unit.contractFile=contracts[0];
+    if (unit.id.startsWith("review/")) (unit.companionFiles ??= []).push({ path: slash(path.relative(root, path.join(dsRoot, reviewEntry))), allowedChanges: "Only this review owner's re-exports in the separate development entry; never the production public entry." });
     (unit.companionFiles ??= []).push({ path: "ds.config.json", allowedChanges: "Only this owner's inlineStyleFiles and boundaries.styleWrites entries, together with its source change; preserve all other configuration and peer permissions." });
-    if (/^(?:components|patterns|controllers|composition)\//.test(unit.id)) {
+    if (/^(?:components|patterns|controllers|composition|review)\//.test(unit.id)) {
       for (let directory = unit.id; directory !== "."; directory = path.posix.dirname(directory)) {
         const marker = path.join(dsRoot, directory, ".gitkeep");
         if (existsSync(marker) && readFileSync(marker).length === 0) (unit.companionFiles ??= []).push({ path: slash(path.relative(root, marker)), allowedChanges: "Delete this empty placeholder only while adding real source in the selected owner below it." });
       }
     }
   }
-  return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry, stylesEntry, tokenDir,
+  return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry, reviewEntry, stylesEntry, tokenDir,
     relative: file => slash(path.relative(dsRoot, path.resolve(root, file))) };
 }
 
 function boundaryCompanion(unit) { return !["configuration", "documentation", "assets"].includes(unit.split("/")[0]); }
 
 export function validateUnitId(unit) {
-  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "controllers", "composition"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
+  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "controllers", "composition", "review"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
 }
 
 /** Reject arbitrary file batches, even when every path is inside the ADS. */
@@ -171,7 +179,7 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
     const relative = inventory.relative(change.path);
     if (path.posix.basename(relative) === ".gitkeep") {
       const directory = path.posix.dirname(relative);
-      if (change.originalContent !== "" || change.content !== null || !/^(?:components|patterns|controllers|composition)\//.test(relative)
+      if (change.originalContent !== "" || change.content !== null || !/^(?:components|patterns|controllers|composition|review)\//.test(relative)
         || !(unit === directory || unit.startsWith(directory + "/"))
         || !changes.some(item => item.originalContent === null && item.content !== null && source.test(item.path)
           && (inventory.relative(item.path).startsWith(unit + "/") || inventory.relative(item.path).startsWith(unit + ".")))) throw fail("Only delete an existing empty .gitkeep while adding source in the selected owner beneath it. Other hidden-file changes are not allowed.", change.path);
@@ -179,7 +187,7 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
     }
     if (allowNew && unit === "configuration") continue; // The candidate must register every setup/extension file.
     if (change.path === "ds.config.json" && boundaryCompanion(unit)) continue; // Validated against only this owner below.
-    if (relative === inventory.publicEntry) continue;
+    if (relative === inventory.publicEntry || relative === inventory.reviewEntry) continue;
     if (unit === "tokens" && relative === inventory.stylesEntry) continue; // Controlled foundation import bookkeeping.
     if (allowNew && change.originalContent === null && (relative.startsWith(unit + "/") || relative.startsWith(unit + "."))) continue;
     const owner = inventory.owner(relative);
@@ -232,13 +240,14 @@ export function checkUnitCandidate(afterOptions, unit, changes, before) {
     }
     if (JSON.stringify(unrelated(current)) !== JSON.stringify(unrelated(proposed))) throw fail("Foundation companion patches may change only canonical imports for token files created/deleted in this patch; preserve all other imports and comments.", foundationChange.path);
   }
-  const exportChange = changes.find(change => before.relative(change.path) === before.publicEntry);
-  if (exportChange) {
-    if (!["components", "patterns", "controllers"].includes(unit.split("/")[0])) throw fail("Only a component/pattern/controller unit may update its public re-exports.", exportChange.path);
+  for (const entry of [before.publicEntry, before.reviewEntry]) {
+    const exportChange = changes.find(change => before.relative(change.path) === entry);
+    if (!exportChange) continue;
+    if (!(entry === before.reviewEntry ? ["review"] : ["components", "patterns", "controllers"]).includes(unit.split("/")[0])) throw fail("Only its own layer may update re-exports: product owners use the public entry, review owners use the development review entry.", exportChange.path);
     const current = exportChange.originalContent ?? "", proposed = exportChange.content;
     if (proposed === null) throw fail("The shared public entry cannot be deleted.", exportChange.path);
     const resolve = importResolver(afterOptions);
-    const file = path.join(afterOptions.dsRoot, afterOptions.config.publicEntry);
+    const file = path.join(afterOptions.dsRoot, entry);
     const original = ts.createSourceFile(file, current, ts.ScriptTarget.Latest, true);
     const candidate = ts.createSourceFile(file, proposed, ts.ScriptTarget.Latest, true);
     const emptyExport = statement => ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause) && !statement.exportClause.elements.length;

package/dist/verification/browser.mjs

@@ -1,60 +1,190 @@
+// src/verification/browser.mjs
 import { readFileSync } from "node:fs";
 
-/** Development-only Playwright helper. No browser or framework dependency is installed. */
-export function verificationRequest() {
+// preview-client/paint-audit.mjs
+function auditPaintBindings({ container = document.getElementById("root"), bindings = [], auditResources = false } = {}) {
+  const diagnostics = [], verified = [], limits = [];
+  if (!container || !Array.isArray(bindings) || bindings.length > 100) return { ok: false, diagnostics: ["Invalid bounded paint-audit descriptor."], verified };
+  const document2 = container.ownerDocument, view = document2.defaultView;
+  const properties = ["color", "fill", "stroke", "stop-color", "background-color", "border-top-color", "border-right-color", "border-bottom-color", "border-left-color"];
+  function reference(value, node, descriptor, seen = /* @__PURE__ */ new Set()) {
+    value = value.trim();
+    if (["none", "currentColor"].includes(value)) return true;
+    const variable = /^var\(\s*(--[\w-]+)\s*\)$/.exec(value);
+    if (variable) {
+      const name = variable[1];
+      if (!descriptor.tokens.includes(name) || seen.has(name)) return false;
+      const resolved = view.getComputedStyle(node).getPropertyValue(name).trim();
+      return !!resolved && view.CSS.supports("color", resolved);
+    }
+    const resource = /^url\(\s*(["']?)#([^\s"'()#\\\p{Cc}]+)\1\s*\)$/u.exec(value);
+    if (resource && view.CSS.supports("fill", value)) {
+      const candidates = [...document2.querySelectorAll("[id]")].filter((item) => item.id === resource[2]);
+      return candidates.length === 1 && ["linearGradient", "radialGradient", "pattern"].includes(candidates[0].localName) && node.contains(candidates[0]);
+    }
+    return false;
+  }
+  for (const descriptor of bindings) {
+    if (!descriptor || typeof descriptor.scope !== "string" || !Array.isArray(descriptor.tokens) || typeof descriptor.prefix !== "string" || typeof descriptor.suffix !== "string") {
+      diagnostics.push("Invalid paint binding metadata; rebuild previews.");
+      continue;
+    }
+    let roots;
+    try {
+      roots = [...container.querySelectorAll(descriptor.scope)];
+    } catch {
+      diagnostics.push(`${descriptor.owner}: invalid binding scope.`);
+      continue;
+    }
+    if (roots.length > 20) limits.push(`${descriptor.owner}: only the first 20 instances were audited; use a focused scenario for complete evidence.`);
+    for (const root of roots.slice(0, 20)) {
+      const nodes = [root, ...root.querySelectorAll("*")];
+      if (nodes.length > 1e3) {
+        limits.push(`${descriptor.owner}: instance exceeds 1000 elements; paint effects are not established.`);
+        continue;
+      }
+      const names = [...root.style].filter((name) => name.startsWith(descriptor.prefix) && name.endsWith(descriptor.suffix));
+      if (names.length > 100) limits.push(`${descriptor.owner}: only the first 100 binding keys were audited.`);
+      for (const name of names.slice(0, 100)) {
+        const value = root.style.getPropertyValue(name).trim(), key = name.slice(descriptor.prefix.length, descriptor.suffix ? -descriptor.suffix.length : void 0);
+        if (!/^[A-Za-z0-9_-]+$/.test(key) || !reference(value, root, descriptor)) {
+          diagnostics.push(`${descriptor.owner}: invalid or inaccessible paint ${name}: ${value}. Use an accessible token, instance-local SVG paint server, none or currentColor.`);
+          continue;
+        }
+        const previous = root.getAttribute("style");
+        const nodeStyles = nodes.map((node) => node.getAttribute("style"));
+        try {
+          for (const node of nodes) node.style.setProperty("transition", "none", "important");
+          const before = nodes.map((node) => properties.map((property) => view.getComputedStyle(node).getPropertyValue(property)));
+          root.style.setProperty(name, "rgb(17, 103, 211)", "important");
+          let changed = nodes.some((node, index) => properties.some((property, i) => view.getComputedStyle(node).getPropertyValue(property) !== before[index][i]));
+          if (!changed) {
+            root.style.setProperty(name, "rgb(211, 67, 23)", "important");
+            changed = nodes.some((node, index) => properties.some((property, i) => view.getComputedStyle(node).getPropertyValue(property) !== before[index][i]));
+          }
+          if (!changed) limits.push(`${descriptor.owner}: ${name} has no observed paint effect in its current instance. A written variable alone is not rendering evidence; check the relevant selected/visible consumer.`);
+          else verified.push({ owner: descriptor.owner, binding: descriptor.name, variable: name });
+        } finally {
+          nodes.forEach((node, index) => {
+            if (nodeStyles[index] === null) node.removeAttribute("style");
+            else node.setAttribute("style", nodeStyles[index]);
+          });
+          if (previous === null) root.removeAttribute("style");
+          else root.setAttribute("style", previous);
+        }
+      }
+      for (const node of nodes) for (const property of ["fill", "stroke", "stop-color"]) {
+        const value = node.getAttribute(property);
+        if (!value) continue;
+        const variable = /^var\(\s*(--[\w-]+)\s*\)$/.exec(value);
+        if (variable && variable[1].startsWith(descriptor.prefix) && variable[1].endsWith(descriptor.suffix) && !names.includes(variable[1])) diagnostics.push(`${descriptor.owner}: ${variable[1]} is consumed without a value in this instance.`);
+        if (value.startsWith("url(") && !reference(value, root, descriptor)) diagnostics.push(`${descriptor.owner}: missing, duplicated or out-of-instance local paint resource ${value}.`);
+      }
+    }
+  }
+  const resourceNodes = auditResources ? [...container.querySelectorAll("[fill], [stroke], [style]")] : [];
+  if (resourceNodes.length > 1e3) limits.push("Only the first 1000 potential SVG paint consumers were audited.");
+  for (const node of resourceNodes.slice(0, 1e3)) for (const property of ["fill", "stroke"]) {
+    const value = node.getAttribute(property) ?? node.style.getPropertyValue(property);
+    if (!value?.startsWith("url(")) continue;
+    const id = /^url\(\s*(["']?)#([^\s"'()#\\\p{Cc}]+)\1\s*\)$/u.exec(value)?.[2];
+    const resources = id ? [...document2.querySelectorAll("[id]")].filter((item) => item.id === id) : [];
+    const svg = node.ownerSVGElement ?? (node.localName === "svg" ? node : null);
+    if (resources.length !== 1 || !svg?.contains(resources[0]) || !["linearGradient", "radialGradient", "pattern"].includes(resources[0]?.localName)) diagnostics.push(`Invalid, missing, duplicated or nonlocal SVG paint resource ${value}. Keep IDs isolated per rendered instance.`);
+  }
+  return { ok: !diagnostics.length, complete: !limits.length, verified, diagnostics: diagnostics.slice(0, 40), limits: limits.slice(0, 20), scope: "observed App instances and current input; repeat after updates" };
+}
+
+// src/verification/browser.mjs
+async function auditBehaviorPaints(frame) {
+  const bindings = await frame.locator("#root").getAttribute("data-ads-paint-bindings");
+  const auditResources = await frame.locator("#root").getAttribute("data-ads-paint-audit");
+  return frame.evaluate(auditPaintBindings, { bindings: JSON.parse(bindings ?? "[]"), auditResources: auditResources === "true" });
+}
+function verificationRequest() {
   if (!process.env.ADS_VERIFY_REQUEST) throw new Error("Run this check through ads_verify so the request and selected profile are explicit.");
   return JSON.parse(readFileSync(process.env.ADS_VERIFY_REQUEST, "utf8"));
 }
-
-export async function openBehaviorScenario(page, checkId, { timeout = 30000 } = {}) {
+async function openBehaviorScenario(page, checkId, { timeout = 3e4 } = {}) {
   const request = verificationRequest();
-  const check = request.checks.find(check => check.id === checkId);
+  const check = request.checks.find((check2) => check2.id === checkId);
   const url = check && request.scenarios[check.scenario];
   if (!url) throw new Error("This check has no managed browser scenario. StrictMode profiles must supply a project development harness; production preview bundles do not replay React development effects.");
   return openPreviewScenario(page, url, check.scenario, { timeout });
 }
-
-/** Shared readiness for registered verification and on-demand captures. */
-export async function openPreviewScenario(page, url, scenario, { timeout = 30000 } = {}) {
+async function openPreviewScenario(page, url, scenario, { timeout = 3e4 } = {}) {
   const failures = [], requests = [], errors = [];
   let boundary;
   const record = (request, detail) => {
     if (requests.length >= 8) return;
     let resourceUri;
-    try { const payload=request.postDataJSON(); if(payload?.method==="resources/read"&&typeof payload.params?.uri==="string"&&payload.params.uri.startsWith("ads://"))resourceUri=payload.params.uri.slice(0,500); } catch { /* Bodies are never retained. */ }
-    requests.push({method:request.method(),url:request.url().slice(0,300),...detail,...(resourceUri?{resourceUri}:{})});
+    try {
+      const payload = request.postDataJSON();
+      if (payload?.method === "resources/read" && typeof payload.params?.uri === "string" && payload.params.uri.startsWith("ads://")) resourceUri = payload.params.uri.slice(0, 500);
+    } catch {
+    }
+    requests.push({ method: request.method(), url: request.url().slice(0, 300), ...detail, ...resourceUri ? { resourceUri } : {} });
   };
-  const failed = request => {
+  const failed = (request) => {
     if (failures.length < 5) failures.push(`${request.method()} ${request.url().slice(0, 300)}: ${request.failure()?.errorText ?? "request failed"}`);
-    record(request,{error:request.failure()?.errorText??"request failed"});
+    record(request, { error: request.failure()?.errorText ?? "request failed" });
+  };
+  const response = (response2) => {
+    if (response2.status() >= 400) record(response2.request(), { status: response2.status() });
+  };
+  const pageError = (error) => {
+    if (errors.length < 3) errors.push(error.message.slice(0, 500));
   };
-  const response = response => { if(response.status()>=400)record(response.request(),{status:response.status()}); };
-  const pageError = error => { if(errors.length<3)errors.push(error.message.slice(0,500)); };
-  const diagnostic = (outcome, detail={}) => console.warn(JSON.stringify({adsPreviewDiagnostic:{kind:"preview-startup",scenario,outcome,viewport:page.viewportSize(),requests,errors,...detail}}));
+  const diagnostic = (outcome, detail = {}) => console.warn(JSON.stringify({ adsPreviewDiagnostic: { kind: "preview-startup", scenario, outcome, viewport: page.viewportSize(), requests, errors, ...detail } }));
   page.on("requestfailed", failed);
-  page.on("response", response);page.on("pageerror", pageError);
+  page.on("response", response);
+  page.on("pageerror", pageError);
   try {
     await page.goto(url, { waitUntil: "load", timeout });
     const end = Date.now() + timeout;
     while (Date.now() < end) {
-      for (const frame of page.frames().filter(frame => frame !== page.mainFrame())) {
-        const state = await frame.evaluate(() => {const data=document.documentElement.dataset;return {state:data.adsPreviewState,id:data.adsScenario,revision:data.adsPreviewRevision,category:data.adsPreviewErrorCategory,code:data.adsPreviewErrorCode,resourceUri:data.adsPreviewResourceUri,message:document.getElementById("ads-preview-status")?.textContent};}).catch(() => ({}));
+      for (const frame of page.frames().filter((frame2) => frame2 !== page.mainFrame())) {
+        const state = await frame.evaluate(() => {
+          const data = document.documentElement.dataset;
+          return { state: data.adsPreviewState, id: data.adsScenario, revision: data.adsPreviewRevision, category: data.adsPreviewErrorCategory, code: data.adsPreviewErrorCode, resourceUri: data.adsPreviewResourceUri, message: document.getElementById("ads-preview-status")?.textContent };
+        }).catch(() => ({}));
         if (state.id === scenario && state.state === "ready") {
           const retries = await page.evaluate(() => Number(document.documentElement.dataset.adsResourceRetries ?? 0)).catch(() => 0);
           if (retries > 0) console.warn(JSON.stringify({ adsPreviewDiagnostic: { kind: "resource-read-recovery", scenario, retries, failedRequests: failures } }));
-          diagnostic("ready",{previewRevision:state.revision??null});
+          diagnostic("ready", { previewRevision: state.revision ?? null });
           return frame;
         }
-        if (state.id === scenario && state.state === "error") {boundary={category:state.category??"runner",phase:"preview-startup",code:state.code??"ADS_PREVIEW_STARTUP",...(state.resourceUri?{resourceUri:state.resourceUri}:{})};throw new Error(state.message || "The MCP App failed before verification.");}
+        if (state.id === scenario && state.state === "error") {
+          boundary = { category: state.category ?? "runner", phase: "preview-startup", code: state.code ?? "ADS_PREVIEW_STARTUP", ...state.resourceUri ? { resourceUri: state.resourceUri } : {} };
+          throw new Error(state.message || "The MCP App failed before verification.");
+        }
+      }
+      const error = await page.evaluate(() => {
+        const node = document.querySelector('#status[data-error="true"]');
+        return node ? { message: node.textContent, category: node.dataset.errorCategory, code: node.dataset.errorCode } : null;
+      }).catch(() => null);
+      if (error) {
+        boundary = { category: error.category ?? (requests.length ? "transport" : "runner"), phase: "host-startup", code: error.code ?? (requests.length ? "ADS_BROWSER_REQUEST" : "ADS_HOST_STARTUP") };
+        throw new Error(error.message);
       }
-      const error = await page.evaluate(() => {const node=document.querySelector('#status[data-error="true"]');return node?{message:node.textContent,category:node.dataset.errorCategory,code:node.dataset.errorCode}:null;}).catch(() => null);
-      if (error) {boundary={category:error.category??(requests.length?"transport":"runner"),phase:"host-startup",code:error.code??(requests.length?"ADS_BROWSER_REQUEST":"ADS_HOST_STARTUP")};throw new Error(error.message);}
       await page.waitForTimeout(50);
     }
     throw new Error("Timed out waiting for the selected MCP App scenario to become current and ready. Inspect ads_status and ads://project/build.");
   } catch (error) {
-    boundary??={category:requests.length?"transport":"runner",phase:"preview-startup",code:requests.length?"ADS_BROWSER_REQUEST":"ADS_PREVIEW_NOT_READY",certainty:requests.length?"observed-boundary":"unclassified"};
-    diagnostic("failed",{failure:boundary});
-    throw Object.assign(new Error(`Scenario ${scenario}: ${error.message}${failures.length ? `\nFailed browser requests:\n${failures.join("\n")}` : ""}`, { cause: error }),{failure:boundary});
-  } finally { page.off("requestfailed", failed);page.off("response",response);page.off("pageerror",pageError); }
+    boundary ??= { category: requests.length ? "transport" : "runner", phase: "preview-startup", code: requests.length ? "ADS_BROWSER_REQUEST" : "ADS_PREVIEW_NOT_READY", certainty: requests.length ? "observed-boundary" : "unclassified" };
+    diagnostic("failed", { failure: boundary });
+    throw Object.assign(new Error(`Scenario ${scenario}: ${error.message}${failures.length ? `
+Failed browser requests:
+${failures.join("\n")}` : ""}`, { cause: error }), { failure: boundary });
+  } finally {
+    page.off("requestfailed", failed);
+    page.off("response", response);
+    page.off("pageerror", pageError);
+  }
 }
+export {
+  auditBehaviorPaints,
+  openBehaviorScenario,
+  openPreviewScenario,
+  verificationRequest
+};

package/dist/verification/playwright-reporter.cjs

@@ -1,5 +1,7 @@
 const { readFileSync, writeFileSync, renameSync, rmSync } = require("node:fs");
 const path = require("node:path");
+const { stripVTControlCharacters } = require("node:util");
+const errorText=error=>stripVTControlCharacters(String(error?.message||error?.stack||error?.value||"")).trim().slice(0,1000);
 
 /** Case identity is an explicit project test tag: @ads:<case-id>. */
 module.exports = class AdsBehaviorReporter {
@@ -29,13 +31,21 @@ module.exports = class AdsBehaviorReporter {
     return {file,line:value.line,column:value.column};
   }
   onStepEnd(test, _result, step) {
-    if (!step.error || this.steps.has(test.id)) return;
-    this.steps.set(test.id,{title:String(step.title).slice(0,300),category:step.category,location:this.location(step.error.location??step.location),durationMs:step.duration});
+    if (!step.error) return;
+    const steps=this.steps.get(test.id)??[];
+    steps.push({errorText:errorText(step.error),step:{title:String(step.title).slice(0,300),category:step.category,location:this.location(step.error.location??step.location),durationMs:step.duration}});
+    this.steps.set(test.id,steps.slice(-20));
   }
   onTestEnd(test, result) {
     this.active.delete(test.id);
     const diagnostics = this.diagnostics.get(test.id);
-    const step=this.steps.get(test.id),startup=diagnostics?.findLast(item=>item.kind==="preview-startup"),failed=result.status!=="passed"||test.expectedStatus!=="passed";
+    const errors=(result.errors??[]).slice(0,5).map(errorText);
+    const matching=(this.steps.get(test.id)??[]).filter(item=>item.errorText&&errors.some(error=>error===item.errorText||error.length>20&&item.errorText.length>20&&(error.includes(item.errorText)||item.errorText.includes(error))));
+    // Nested API steps may end before their enclosing expect. Match the actual
+    // unhandled case error, then retain its assertion boundary independent of
+    // event order. Earlier caught errors are not the failure's source.
+    const step=(matching.findLast(item=>item.step.category==="expect")??matching[0])?.step;
+    const startup=diagnostics?.findLast(item=>item.kind==="preview-startup"),failed=result.status!=="passed"||test.expectedStatus!=="passed";
     const failure=failed?(startup?.failure??{category:step?.category==="expect"?"assertion":"runner",phase:step?.category==="expect"?"test-assertion":"test-execution",code:result.status==="timedOut"?"ADS_CASE_TIMEOUT":"ADS_CASE_FAILURE",certainty:step?.category==="expect"?"observed-boundary":"unclassified"}):undefined;
     const artifacts=(result.attachments??[]).filter(item=>item.path).slice(0,5).map(item=>({name:String(item.name).slice(0,100),mimeType:String(item.contentType).slice(0,100),path:path.relative(path.dirname(process.env.ADS_VERIFY_REPORT),item.path).replaceAll("\\","/")}));
     for (const entry of this.entries(test)) this.cases.push({ ...entry, status: !failed ? "passed" : ["skipped", "interrupted"].includes(result.status) ? "skipped" : "failed", durationMs: result.duration, workerIndex: result.workerIndex, retry: result.retry, completedAt: new Date().toISOString(), source:step?.location??this.location(result.errors?.[0]?.location??test.location), ...(step?{failingStep:step}:{}),...(failure?{failure}:{}),...(startup?.viewport?{viewport:startup.viewport,viewportSource:"preview-startup"}:{}),...(artifacts.length?{artifacts}:{}), ...(diagnostics?.length ? { diagnostics } : {}), message: result.errors?.map(error => error.message || error.stack || error.value || "The browser runner reported an error without details.").join("\n").slice(0, 1000) });

package/docs/ADS.md

@@ -95,7 +95,8 @@ guarded public re-exports. They may use the configured framework and declared
 dependencies, plain TypeScript and browser APIs; CSS/Linaria and visual DOM belong
 to consumers. They require no artificial visual scenario.
 
-Optional colocated `behavior.json` (flat: `<Owner>.behavior.json`) registers
+Optional `<Owner>.ads.contract.ts` registers behavior with actual symbol references.
+Legacy colocated `behavior.json` (flat: `<Owner>.behavior.json`) also registers
 subjects, guarantees and owner-local checks against project-configured runner
 profiles. `exercises` records public behavioral APIs demonstrated by a scenario;
 `covers` retains its rendered UI contract. ADS validates references and reachable
@@ -114,7 +115,7 @@ are generated development evidence, outside source ownership and product bundles
 See the portable [capture workflow](../skills/ads-designer/references/captures.md).
 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
@@ -184,10 +185,29 @@ instead of assigning shared tokens in JavaScript. Full application harnesses
 belong in application test support. Run ADS/project checks before application,
 preview builds; review meaningful states in both themes and sizes.
 
+## Development review layer
+
+`review/` contains demo framing, demonstration controls and token renderers.
+It has a separate `reviewEntry` (default `review/index.ts`), imported through
+`${publicAlias}/review` (`@ds/review` by default). Product patterns are production
+application UI. The public production barrel and product catalogue exclude review
+exports; production code cannot depend on their implementation, types or styles.
+Review rendering stays inside the App and retains the normal token/style and
+public product-contract gates. See the portable
+[review guide](../skills/ads-designer/references/review.md) for scenarios, guarded
+owners, build aliases and migration. `ads_status.project.review` discovers the
+connected project's actual entry. Older tooling must be upgraded before migration.
+
 ## Shared token contract
 
 ### Owner-local tokens
 
+New owner declarations use `tokens: { namespace, stylesheet }` in
+`<Owner>.ads.contract.ts`. The legacy JSON layout below remains supported.
+Use one authoring form per section; competing registrations fail. See the
+[static contract reference](CONTRACTS.md) for paint bindings, declarative APIs,
+marked development files and guarded migration.
+
 Shared semantics remain in the configured token foundation. Constants specific
 to one component or pattern may live beside it:
 
@@ -198,7 +218,7 @@ components/Notice/
   tokens.css               # :root { --notice-width: 356px; }
   Scenario.tsx
   fixture.ts
-  Tokens.scenario.tsx      # kind: "tokens", public review pattern + samples
+  Tokens.scenario.tsx      # kind: "tokens", development-only review renderer + samples
   Tokens.fixture.ts
 ```
 
@@ -216,7 +236,7 @@ Measured runtime variables retain their existing exact `styleWrites` boundary.
 `ads_tokens` returns each token's owner, definitions and local namespace.
 
 A colocated scenario sets `kind:"tokens"` and declares real fixture `samples`
-consumed by a public review pattern. Its ID still derives from its source path.
+consumed by a development-only review renderer. Its ID still derives from its source path.
 Discovery attaches its owner's registered definition sheet as `stylesheets` on
 the generated scenario record; `previewEntriesPlugin` imports it directly into
 that preview's module graph. CSS-only package side effects can then tree-shake
@@ -294,7 +314,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.
 
 
@@ -394,6 +414,8 @@ The checks enforce the architecture's ownership boundaries:
 |----------|------------------|
 | Tokens and styles | Fixed token vocabulary, required definitions, declared value types and references, raw visual values, shared-token assignments, foundation import order, and component/pattern namespaces |
 | Public API and dependencies | Consumers use public ADS imports; ADS implementations and showcase do not import application source; runtime code does not import showcase fixtures |
+| Component and pattern layers | Component runtime cannot depend on patterns/composition, including through resolved aliases, re-exports and helpers; patterns consume public component symbols, not implementation helpers/types |
+| Component styling contracts | Patterns cannot target proven private component classes/data markers or read known private component variables; public hooks and registered non-state customization variables remain available; ancestor context for a pattern's own styles is allowed |
 | Interaction policy | Primitive state variables stay inside components; non-state customization hooks require explicit registration |
 | Renderer exceptions | Inline styles and imperative writes require used, narrow configured boundaries; stale entries fail; public props omit inherited style and reject open-ended visual strings |
 | Preview ownership | Scenarios define no CSS, custom classes, or standalone native controls; native slot children require public runtime cloning evidence; all declared tokens and public renderable UI have reachable registered scenarios; token references must exist; legacy catalogue pages are checked when present |
@@ -418,6 +440,18 @@ tests. Passing static checks establishes only the policies and source formats
 they cover. Browser review and behavior tests still verify accessibility,
 interaction, responsive layout, themes, and motion.
 
+A component provides one cohesive UI capability; a pattern arranges capabilities
+into a reusable structure or workflow. Component count is not a rule. Components
+may compose components/controllers; layout patterns can arrange content slots;
+component scenarios may use development-only review helpers. Classification is design
+guidance, while `component-dependency`, `component-contract` and `component-style`
+are blocking source-ownership rules. Type-only higher-layer references are not
+runtime edges. Relative component imports inside the ADS are valid when the
+selected symbols are public; a self-import through the root barrel is not required.
+Opaque/computed dependencies and ambiguous/generated style hooks require review.
+See the skill-local [layer guide](../skills/ads-designer/references/layers.md), also
+available through MCP at `ads://guides/layers`.
+
 Component-specific usage rules belong to that component in the receiving
 project. Import applicable rules with the item and register them through
 project configuration or maintained tooling integration. Core tooling must
@@ -448,7 +482,7 @@ Root [bootstrap-ds/](../bootstrap-ds/README.md) is the canonical empty scaffold.
 Its identical copy under `skills/ads-designer/assets/bootstrap-ds/` makes the
 skill self-contained. Run `npm run sync:skill-starter` after edits and
 `npm run check:skill-starter` to verify the copy. Both contain empty product component/composition directories and a minimal project-owned
-token review pattern. The scaffold pattern can be renamed or replaced; the tool
+token review renderer. The scaffold pattern can be renamed or replaced; the tool
 does not require that name or its styles and ships no product UI catalogue.
 
 Tool releases should version contract changes, rules, skills, bootstrap support,

package/docs/ARCHITECTURE.md

@@ -67,6 +67,32 @@ state mechanics. Patterns own reusable layout and composition. Application
 containers provide domain data, routing, application effects, and callbacks through public
 APIs.
 
+A component provides one cohesive UI capability. A pattern arranges capabilities
+into a reusable structure or workflow; a layout part may arrange content slots.
+Components may compose other components/controllers, and patterns may compose
+patterns. Import count, element count and implementation size do not decide the
+layer. Scenarios may compose public UI and development review helpers to demonstrate their
+subject without becoming production patterns.
+
+Patterns are production application UI. Development-only framing, demo controls
+and token renderers belong in project-owned `review/`, with a separate
+`reviewEntry` (default `review/index.ts`) and `${publicAlias}/review` import alias.
+They are absent from the product barrel and catalogue. Guards reject production
+dependencies on review code, types and styles; review source keeps normal styling,
+token and public product-contract checks. Scenarios exercise the real production
+implementation through fixtures. The [portable review guide](../skills/ads-designer/references/review.md)
+defines guarded owners, build isolation and migration steps. Review rendering
+stays inside the App iframe; it adds no project execution to the host shell.
+
+Core guards reject component runtime dependencies on patterns/composition through
+resolved imports, re-exports and helpers. Patterns consume public component
+contracts rather than private implementation symbols or rendered style hooks;
+documented non-state customization variables remain available. Source tracing
+distinguishes styling a private part from reading ancestor context for the
+pattern's own arrangement. Application and development dependencies retain their
+separate boundaries. The portable skill-local [layer guide](../skills/ads-designer/references/layers.md)
+explains repairs and analysis limits; semantic classification still needs review.
+
 The Data pillar describes design values; business data is a separate input to
 the UX contract. Application adapters own live business-data loading,
 authentication, stores, routing, caching and refresh policy. Components and
@@ -233,6 +259,13 @@ external bases still require declared CSP origins. This belongs to document
 loading and changes no project link or scenario handler. External hosts control
 their own document-loading and CSP behavior.
 
+The proxy and App sandbox permit native forms (`allow-forms`), including the
+legacy nested widget. This lets browser constraint validation and `submit`
+handlers run for clicks, Enter and `requestSubmit()`. Client-side handlers retain
+their own `preventDefault()` behavior. The App stays opaque; CSP
+`form-action 'none'` blocks native action requests without suppressing submit
+handlers. Hosts outside ADS choose their own sandbox and CSP permissions.
+
 The project compiler publishes a versioned dependency graph: shared runtime and
 foundation assets, plus independently addressable scenario modules. Inside the
 App, a resource loader obtains the selected dependency closure through MCP,
@@ -302,12 +335,12 @@ real public implementation. It mounts independently, without opening a showcase
 page or initializing the application's router, store or services first.
 
 Scenarios and their fixtures live beside the tokens, component or pattern they exercise.
-Demo framing belongs to public review/layout patterns; component props describe
+Demo framing belongs to development-only review helpers; component props describe
 intentional product behavior and visual variants.
 Token scenarios choose real token names and sample inputs; a project-owned
-review pattern applies the foundation variables. The tool contains no project
+review renderer applies the foundation variables. The tool contains no project
 token list, sample templates or assumed visual identity. Even an initial token
-scenario uses a public project-owned review pattern to apply its declared samples;
+scenario uses a project-owned development review renderer to apply its declared samples;
 a definitions-only inspector does not establish preview coverage.
 Larger scenarios live under `composition/`. They use the same public screen
 patterns as production: application adapters supply live data and effects;
@@ -538,7 +571,7 @@ For concrete instructions, use:
 
 Token preview completeness has two checks. Static guards require explicit fixture
 bindings (`token`, CSS `property`, and project-selected `probe`) consumed by a public
-review pattern. The App then verifies rendered samples in the actual browser by
+review renderer. The App then verifies rendered samples in the actual browser by
 probing those bindings and restoring them. The tool supplies no token/property
 classification or visual sample palette. A source build alone is not a rendered
 verification, and the browser check does not judge design quality.
@@ -551,3 +584,39 @@ sheet directly, so tree-shaking an unused runtime owner cannot remove their valu
 Namespaces, aliases, ownership and actual colocated sample coverage are checked.
 The shared foundation remains the cross-owner vocabulary. See the
 [owner-token contract](ADS.md#owner-local-tokens).
+
+## Static contracts and instance data
+
+Owner-local tooling declarations use optional `<Owner>.ads.contract.ts` modules.
+ADS resolves their data and implementation symbols statically without executing
+project imports. Tokens and behavior share this contract with constrained paint
+inputs, instance binding families and declarative parent/consumer relationships.
+Legacy JSON sections remain supported; duplicate policies fail. The
+[contract reference](CONTRACTS.md) specifies the authoring and analysis limits.
+
+Any `.ads.` source is development-only. Runtime implementation/types/styles cannot
+import it through aliases or barrels. Only the selected scenario/fixture/review
+closure enters a preview; contracts and specs are not widget modules. Derived
+App audit data adds no ADS dependency to production components. New starter
+scenarios and fixtures use the marked names; existing IDs remain stable.
+
+Instance bindings are distinct from static tokens and arbitrary inline styles.
+Source checks trace config origin, key validation, exact map construction and
+attachment to an owner root. Shared/private namespaces and consumer permissions
+remain enforced. Browser audits inspect current scoped values, paint effects and
+local SVG resources; registered checks must cover updates/removal, isolation and
+relevant themes. Registration, source-demonstrated consumption and current browser
+verification are separate evidence. Unknown paths establish no blanket permission.
+
+Declarative child APIs belong in `exercises`, while `covers` retains rendered UI.
+Resolved child identity/prop consumption must reach the declared consumer through
+a rendered parent. Metadata alone cannot turn a null-returning stub into verified
+UI. Invalid scenario fields preserve independent valid coverage; unreadable
+prerequisites report that coverage is not established.
+
+Owner tokens are private across CSS and supported TypeScript value flows, including
+constants, re-exports, helper returns and paint/property sinks. Normal component
+composition remains valid. Namespaces are a source boundary, not CSS isolation.
+Ownership does not mandate a visual scale: projects may register explicit origin
+policies using `inspectTokenOrigins`, without ADS hardcoding spacing meanings.
+Migration prepares ordinary owner drafts; candidate gates and rollback still apply.