@reqvire-org/ads 0.3.20 → 0.3.21

package/dist/unit-contracts.mjs

@@ -0,0 +1,203 @@
+import { existsSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { z } from "zod";
+import { isContractFile, isDevelopmentFile, isInside, isReviewFile, sourceFiles } from "./config.mjs";
+import { projectCompilerOptions } from "./boundaries.mjs";
+import { inspectUnits } from "./units.mjs";
+import { publicApi, reviewApi } from "./public-api.mjs";
+
+const identities = new WeakSet();
+const ref = z.custom(value => value && typeof value === "object" && identities.has(value), "Use a resolved implementation symbol, not its name or an object describing it.");
+const id = z.string().regex(/^[A-Za-z0-9][\w.-]{0,99}$/);
+const checks = z.array(id).min(1).max(100);
+const field = z.string().regex(/^[A-Za-z_$][\w$]*(?:\.(?:[A-Za-z_$][\w$]*|\*))*$/).max(200);
+const paint = z.object({ api: ref, property: field, kind: z.literal("paint-reference"), bindings: z.array(id).max(20).optional() }).strict();
+const binding = z.object({ input: z.object({ api: ref, property: field }).strict(), producer: ref, valueFrom: field,
+  variable: z.string().regex(/^--[a-z][\w-]*\$\{key\}[\w-]*$/), scope: z.object({ api: ref, selector: z.string().min(1).max(200) }).strict(), checks }).strict();
+const part = z.object({ api: ref, parent: ref, consumer: ref, checks }).strict();
+const schema = z.object({ schemaVersion: z.literal(1),
+  tokens: z.object({ namespace: z.string(), stylesheet: z.string().min(1).max(256) }).strict().optional(),
+  paintInputs: z.array(paint).max(100).optional(), bindings: z.record(id, binding).optional(),
+  declarativeParts: z.array(part).max(100).optional(), behavior: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+const slash = file => file.replaceAll("\\", "/");
+export function implementationIdentity(declaration, root) {
+  return `${slash(path.relative(root, declaration.getSourceFile().fileName))}:${declaration.pos}`;
+}
+
+export function implementationNode(program, reference, root) {
+  const source = program.getSourceFile(path.resolve(root, reference.source));
+  let found;
+  function visit(node) {
+    if (node.pos === reference.position && (ts.isFunctionDeclaration(node) || ts.isVariableDeclaration(node) || ts.isClassDeclaration(node))) found = node;
+    else if (!found) ts.forEachChild(node, visit);
+  }
+  if (source) visit(source);
+  return found;
+}
+
+/** Pure AST evaluation. Functions are opaque identities; project code never runs. */
+export function staticContractValue(expression, checker, options, locations = new Map()) {
+  let visits = 0;
+  function read(node, key = "", seen = new Set()) {
+    if (++visits > 12000 || seen.size > 60) throw new Error("Static contract expansion exceeded its bounded limit.");
+    while (node && (ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node))) node = node.expression;
+    if (!node || seen.has(node)) throw new Error(`Unresolved or cyclic contract value at ${key || "default export"}.`);
+    locations.set(key, node);
+    seen = new Set([...seen, node]);
+    if (ts.isStringLiteralLike(node) || ts.isNumericLiteral(node)) return ts.isNumericLiteral(node) ? Number(node.text) : node.text;
+    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+    if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) return -Number(node.operand.text);
+    if (ts.isArrayLiteralExpression(node)) {
+      const result = [];
+      for (const item of node.elements) {
+        if (ts.isSpreadElement(item)) { const values = read(item.expression, key, seen); if (!Array.isArray(values)) throw new Error("Contract array spreads require a static array."); result.push(...values); }
+        else result.push(read(item, `${key}.${result.length}`, seen));
+      }
+      return result;
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+      const result = Object.create(null);
+      for (const item of node.properties) {
+        if (ts.isSpreadAssignment(item)) {
+          const value = read(item.expression, key, seen);
+          if (!value || Array.isArray(value) || typeof value !== "object" || identities.has(value)) throw new Error("Contract object spreads require a plain static object.");
+          for (const [name, valueItem] of Object.entries(value)) { if (Object.hasOwn(result, name)) throw new Error(`Duplicate contract field ${key}.${name}.`); result[name] = valueItem; }
+          continue;
+        }
+        if (!ts.isPropertyAssignment(item) && !ts.isShorthandPropertyAssignment(item)) throw new Error("Contracts contain data fields, not getters, methods or executable expressions.");
+        if (!ts.isIdentifier(item.name) && !ts.isStringLiteralLike(item.name)) throw new Error("Contract property keys must be literal names.");
+        const name = item.name.text;
+        if (["__proto__", "prototype", "constructor"].includes(name) || Object.hasOwn(result, name)) throw new Error(`Invalid or duplicate contract field ${key}.${name}.`);
+        const input = ts.isShorthandPropertyAssignment(item) ? checker.getShorthandAssignmentValueSymbol(item)?.valueDeclaration : null;
+        result[name] = read(input?.initializer ?? (ts.isPropertyAssignment(item) ? item.initializer : item.name), key ? `${key}.${name}` : name, seen);
+      }
+      return result;
+    }
+    if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node)) {
+      let symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+      if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+      const declaration = symbol?.valueDeclaration;
+      if (!declaration) throw new Error(`Cannot resolve contract symbol ${node.getText()}.`);
+      const runtime = !isDevelopmentFile(declaration.getSourceFile().fileName, options)||isReviewFile(declaration.getSourceFile().fileName,options);
+      const initializer = ts.isVariableDeclaration(declaration) ? declaration.initializer : ts.isPropertyAssignment(declaration) ? declaration.initializer : null;
+      const callable = ts.isFunctionDeclaration(declaration) || ts.isClassDeclaration(declaration) || initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer) || ts.isCallExpression(initializer));
+      if (runtime && callable) {
+        const value = { source: slash(path.relative(options.root, declaration.getSourceFile().fileName)), symbol: symbol.name, position: declaration.pos, identity: implementationIdentity(declaration, options.root) };
+        identities.add(value); return value;
+      }
+      if (initializer && (!ts.isVariableDeclaration(declaration) || declaration.parent.flags & ts.NodeFlags.Const)) return read(initializer, key, seen);
+    }
+    throw new Error(`Unsupported static contract expression at ${key || "default export"}: ${ts.SyntaxKind[node.kind]}. Calls, getters and environment-dependent code are not evaluated.`);
+  }
+  return read(expression);
+}
+
+export function inspectUnitContracts(options) {
+  if (options.unitContracts) return options.unitContracts;
+  const files = sourceFiles(options.dsRoot).filter(isContractFile);
+  const result = { contracts: [], diagnostics: [], program: null };
+  options.unitContracts = result;
+  if (!files.length) return result;
+  const inventory = inspectUnits(options);
+  const program = ts.createProgram(sourceFiles(options.dsRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file)), { ...projectCompilerOptions(options), allowJs: true });
+  result.program = program;
+  const checker = program.getTypeChecker();
+  const publicItems = [...publicApi(program, options), ...reviewApi(program, options)];
+  const publicByIdentity = new Map(publicItems.map(api => [implementationIdentity(api.declaration, options.root), api]));
+  const seen = new Set();
+  for (const file of files) {
+    const relative = slash(path.relative(options.root, file));
+    const unit = inventory.owner(inventory.relative(relative));
+    const source = program.getSourceFile(file), locations = new Map();
+    function report(message, fieldName = "") {
+      const node = locations.get(fieldName) ?? source;
+      const position = node?.getSourceFile().getLineAndCharacterOfPosition(node.getStart());
+      result.diagnostics.push({ file: relative, rule: "unit-contract", message, line: (position?.line ?? 0) + 1, column: (position?.character ?? 0) + 1, ...(fieldName ? { entry: fieldName } : {}) });
+    }
+    try {
+      if (!source || statSync(file).size > 128 * 1024 || realpathSync(file) !== file) throw new Error("Contracts must be real owner-local files of at most 128 KiB.");
+      if (!/^(?:components|patterns|controllers|review)\//.test(unit ?? "")) throw new Error("Contracts belong to a component, pattern, controller or review owner.");
+      if (seen.has(unit)) throw new Error(`Only one TypeScript contract may describe ${unit}.`);
+      seen.add(unit);
+      for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement) || ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isExportAssignment(statement) || ts.isEmptyStatement(statement)) continue;
+        if (ts.isVariableStatement(statement) && statement.declarationList.flags & ts.NodeFlags.Const) continue;
+        throw new Error("Contract modules contain imports, types, static constants and one default data export; executable statements are forbidden.");
+      }
+      const exports = source.statements.filter(ts.isExportAssignment);
+      if (exports.length !== 1 || exports[0].isExportEquals) throw new Error("Export one default contract data object.");
+      const value = staticContractValue(exports[0].expression, checker, options, locations);
+      for(const statement of source.statements.filter(ts.isVariableStatement))for(const declaration of statement.declarationList.declarations)staticContractValue(declaration.initializer,checker,options);
+      const parsed = schema.safeParse(value);
+      if (!parsed.success) { for (const issue of parsed.error.issues.slice(0, 12)) report(`${issue.path.join(".")}: ${issue.message}`, issue.path.join(".")); continue; }
+      const data = parsed.data;
+      const apiName = (reference, fieldName) => {
+        const owner = inventory.owner(inventory.relative(reference.source));
+        const api = publicByIdentity.get(reference.identity);
+        if (owner !== unit || !api) { report(`${fieldName} must reference a real public API owned by ${unit}.`, fieldName); return null; }
+        return api.name;
+      };
+      function implementation(reference, fieldName) {
+        const absolute = path.resolve(options.root, reference.source);
+        if (!isInside(options.dsRoot, absolute) || inventory.owner(inventory.relative(reference.source)) !== unit || isDevelopmentFile(absolute, options)&&!isReviewFile(absolute,options)) report(`${fieldName} must reference runtime or review implementation inside ${unit}, not a contract, fixture or spec.`, fieldName);
+      }
+      if (data.tokens) {
+        if(!/^(?:components|patterns)\//.test(unit))report("Owner-local design token namespaces belong to components or patterns. Controllers remain headless; review uses the shared vocabulary and its own presentation state.","tokens");
+        const absolute = path.resolve(path.dirname(file), data.tokens.stylesheet);
+        if (!isInside(options.dsRoot, absolute) || inventory.owner(inventory.relative(slash(path.relative(options.root, absolute)))) !== unit || !absolute.endsWith(".css") || !existsSync(absolute)) report("Token stylesheet must be a real CSS file in this owner.", "tokens.stylesheet");
+        data.tokens.file = slash(path.relative(options.root, absolute));
+      }
+      for (const [index, input] of (data.paintInputs ?? []).entries()) {
+        if(data.paintInputs.slice(0,index).some(prior=>prior.api.identity===input.api.identity&&prior.property===input.property))report("Duplicate paint-input registration is ambiguous.",`paintInputs.${index}`);
+        input.apiName = apiName(input.api, `paintInputs.${index}.api`);
+        for (const name of input.bindings ?? []) if (!Object.hasOwn(data.bindings ?? {}, name)) report(`Unknown binding ${name}.`, `paintInputs.${index}.bindings`);
+      }
+      for (const [name, entry] of Object.entries(data.bindings ?? {})) {
+        entry.apiName = apiName(entry.input.api, `bindings.${name}.input.api`);
+        entry.scope.apiName = apiName(entry.scope.api, `bindings.${name}.scope.api`);
+        if(!publicByIdentity.get(entry.scope.api.identity)?.renderable)report("Binding scopes require a real public rendering API.",`bindings.${name}.scope.api`);
+        implementation(entry.producer, `bindings.${name}.producer`);
+        if (entry.apiName !== entry.scope.apiName) report("The binding input and attachment scope must belong to the same public API.", `bindings.${name}`);
+      }
+      for (const [index, entry] of (data.declarativeParts ?? []).entries()) {
+        if(data.declarativeParts.slice(0,index).some(prior=>prior.api.identity===entry.api.identity))report("A declarative API needs one unambiguous parent/consumer relationship.",`declarativeParts.${index}`);
+        entry.apiName = apiName(entry.api, `declarativeParts.${index}.api`);
+        entry.parentName = apiName(entry.parent, `declarativeParts.${index}.parent`);
+        if(!publicByIdentity.get(entry.parent.identity)?.renderable)report("Declarative parents require a real public rendering API.",`declarativeParts.${index}.parent`);
+        implementation(entry.consumer, `declarativeParts.${index}.consumer`);
+      }
+      let behavior;
+      if (data.behavior) {
+        if(Object.hasOwn(data.behavior,"schemaVersion"))report("Behavior inherits the owner contract's schemaVersion; remove the competing nested version.","behavior.schemaVersion");
+        behavior = { ...data.behavior, schemaVersion: 1 };
+        behavior.subjects = Object.fromEntries(Object.entries(behavior.subjects ?? {}).map(([name, subject]) => {
+          if (subject?.api && identities.has(subject.api)) return [name, { api: apiName(subject.api, `behavior.subjects.${name}.api`) ?? "" }];
+          if (subject?.implementation && identities.has(subject.implementation)) {
+            implementation(subject.implementation, `behavior.subjects.${name}.implementation`);
+            return [name, { source: `./${slash(path.relative(path.dirname(file), path.resolve(options.root, subject.implementation.source)))}`, symbol: subject.implementation.symbol }];
+          }
+          report("Behavior subjects must use an actual public api or owner-local implementation symbol.", `behavior.subjects.${name}`);
+          return [name, subject];
+        }));
+      }
+      for (const entry of [...Object.values(data.bindings ?? {}), ...(data.declarativeParts ?? [])]) for (const check of entry.checks) if (!behavior?.checks?.[check]) report(`Required check ${check} is not registered in this contract's behavior checks.`);
+      result.contracts.push({ ...data, ...(behavior ? { behavior } : {}), unit, file: relative });
+    } catch (error) { report(error.message); }
+  }
+  return result;
+}
+
+/** An ownership lookup, not source/browser certification of the declaration. */
+export function runtimeBindingOwner(options, name) {
+  for (const contract of inspectUnitContracts(options).contracts) for (const [id, binding] of Object.entries(contract.bindings ?? {})) {
+    const [prefix, suffix] = binding.variable.split("${key}");
+    const key = name.slice(prefix.length, suffix ? -suffix.length : undefined);
+    if (name.startsWith(prefix) && name.endsWith(suffix) && /^[A-Za-z0-9_-]+$/.test(key)) return { ...binding, id, unit: contract.unit };
+  }
+  return null;
+}

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";
@@ -98,13 +98,17 @@ 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|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);
   }
@@ -147,6 +151,8 @@ 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|review)\//.test(unit.id)) {

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
@@ -201,6 +202,12 @@ connected project's actual entry. Older tooling must be upgraded before migratio
 
 ### 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:
 

package/docs/ARCHITECTURE.md

@@ -584,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.

package/docs/BEHAVIORS.md

@@ -25,6 +25,14 @@ These gates inspect supported direct imports, markup and style boundaries.
 External package internals and delegated DOM behavior still require source,
 build and browser review; declaring a dependency does not prove it is headless.
 
+New owner registrations can live in `<Owner>.ads.contract.ts` with actual API and
+implementation references; legacy JSON remains supported. The
+[contract reference](CONTRACTS.md) covers static authoring, `.ads.behavior.spec.ts`,
+declarative `exercises`, required browser checks and guarded migration.
+A contract declaration alone is not passing evidence. Use
+`auditBehaviorPaints(frame)` after relevant binding updates to repeat the current
+App's generic paint audit, in addition to assertions for the named guarantee.
+
 ## Development boundary
 
 Production includes real components, controllers, tokens and compiled styles.

package/docs/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.3.21
+
+- Add statically read TypeScript owner contracts and canonical `.ads.` development
+  roles, retaining legacy token/behavior registration and stable scenario IDs.
+- Validate constrained paint inputs, source-proven instance binding producers and
+  declarative child consumers. Audit current paint bindings/local SVG resources
+  inside Apps; registered browser checks remain required for guarantees.
+- Close supported cross-owner TypeScript token-value flows and preserve independent
+  render evidence with positioned scenario field/entry diagnostics.
+- Prepare contract/file-role migrations as normal guarded owner drafts; expose
+  compact contract/API metadata and portable guidance in all five skills.
+- Expose read-only token-origin analysis for explicit project scale policies.
+- Keep starter production declarations limited to the public runtime dependency
+  closure, excluding development contracts, scenarios, review and checks.
+- Reuse contract TypeScript programs during discovery. Match failed Playwright
+  steps to the unhandled case error so nested API event order and earlier caught
+  failures cannot mislabel an assertion as a runner failure.
+
+
 ## 0.3.20
 
 - Preserve the motion-review checklist separately from the development review-layer