@reqvire-org/ads 0.2.9 → 0.3.1

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/Foundation.fixture.ts

@@ -1,47 +1,48 @@
 export const fixture = {
   "title": "Foundation",
-  "tokens": [
-    "--accent",
-    "--accent-fg",
-    "--accent-hover",
-    "--bg-canvas",
-    "--bg-hover",
-    "--bg-surface",
-    "--border-default",
-    "--border-focus",
-    "--border-w",
-    "--dur-fast",
-    "--dur-normal",
-    "--ease-standard",
-    "--focus-offset",
-    "--focus-w",
-    "--font-mono",
-    "--font-sans",
-    "--leading-normal",
-    "--leading-tight",
-    "--radius-lg",
-    "--radius-md",
-    "--radius-sm",
-    "--shadow-raised",
-    "--shadow-xs",
-    "--space-0",
-    "--space-12",
-    "--space-16",
-    "--space-2",
-    "--space-4",
-    "--space-6",
-    "--space-8",
-    "--text-base",
-    "--text-body",
-    "--text-inverse",
-    "--text-lg",
-    "--text-muted",
-    "--text-sm",
-    "--text-strong",
-    "--text-xl",
-    "--weight-medium",
-    "--weight-normal",
-    "--weight-semibold",
-    "--z-overlay"
+  "text": "Aa",
+  samples: [
+    {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--accent-fg", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--accent-hover", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-canvas", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-hover", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-surface", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-default", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-focus", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-w", "property": "width", "probe": "13.375px"},
+    {"token": "--dur-fast", "property": "animation-duration", "probe": "0.375s"},
+    {"token": "--dur-normal", "property": "animation-duration", "probe": "0.375s"},
+    {"token": "--ease-standard", "property": "animation-timing-function", "probe": "cubic-bezier(.13,.27,.61,.83)"},
+    {"token": "--focus-offset", "property": "width", "probe": "13.375px"},
+    {"token": "--focus-w", "property": "width", "probe": "13.375px"},
+    {"token": "--font-mono", "property": "font-family", "probe": "monospace, serif"},
+    {"token": "--font-sans", "property": "font-family", "probe": "monospace, serif"},
+    {"token": "--leading-normal", "property": "line-height", "probe": "2.375"},
+    {"token": "--leading-tight", "property": "line-height", "probe": "2.375"},
+    {"token": "--radius-lg", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--radius-md", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--radius-sm", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--shadow-raised", "property": "box-shadow", "probe": "1px 3px 5px rgb(31, 97, 163)"},
+    {"token": "--shadow-xs", "property": "box-shadow", "probe": "1px 3px 5px rgb(31, 97, 163)"},
+    {"token": "--space-0", "property": "width", "probe": "13.375px"},
+    {"token": "--space-12", "property": "width", "probe": "13.375px"},
+    {"token": "--space-16", "property": "width", "probe": "13.375px"},
+    {"token": "--space-2", "property": "width", "probe": "13.375px"},
+    {"token": "--space-4", "property": "width", "probe": "13.375px"},
+    {"token": "--space-6", "property": "width", "probe": "13.375px"},
+    {"token": "--space-8", "property": "width", "probe": "13.375px"},
+    {"token": "--text-base", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-body", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-inverse", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-lg", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-muted", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-sm", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-strong", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-xl", "property": "font-size", "probe": "41.375px"},
+    {"token": "--weight-medium", "property": "font-weight", "probe": "327"},
+    {"token": "--weight-normal", "property": "font-weight", "probe": "327"},
+    {"token": "--weight-semibold", "property": "font-weight", "probe": "327"},
+    {"token": "--z-overlay", "property": "z-index", "probe": "367"},
   ]
 } as const;

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/Foundation.scenario.tsx

@@ -1,14 +1,4 @@
-import { useEffect, useState } from "react";
+import { TokenPreview } from "@ds";
 import { fixture } from "./Foundation.fixture";
-export const scenario = { title: fixture.title, covers: [], tokens: fixture.tokens };
-export default function Scenario() {
-  const [values, setValues] = useState<Record<string, string>>({});
-  useEffect(() => {
-    const read = () => { const style = getComputedStyle(document.documentElement); setValues(Object.fromEntries(fixture.tokens.map(name => [name, style.getPropertyValue(name).trim()]))); };
-    read();
-    const observer = new MutationObserver(read);
-    observer.observe(document.documentElement, {attributes: true, attributeFilter: ["data-theme"]});
-    return () => observer.disconnect();
-  }, []);
-  return <section><h1>{fixture.title}</h1><dl>{fixture.tokens.map(name => <div key={name}><dt><code>{name}</code></dt><dd>{values[name]}</dd></div>)}</dl></section>;
-}
+export const scenario = { title: fixture.title, covers: ["TokenPreview"], samples: fixture.samples };
+export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/skills/ads-designer/assets/bootstrap-ds/ds.config.json

@@ -9,5 +9,15 @@
         "--watch"
       ]
     }
+  },
+  "boundaries": {
+    "styleWrites": [
+      {
+        "file": "design-system/patterns/token-preview/TokenPreview.tsx",
+        "properties": [
+          "--ux-token-preview-value"
+        ]
+      }
+    ]
   }
 }

package/dist/skills/ads-designer/references/cli.md

@@ -55,7 +55,7 @@ If no published distribution exists, build and pack the tooling checkout with
 From inside an existing test project:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.1.tgz"
 npx --yes --package "$ads_tool_package" ads --help
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
@@ -93,7 +93,7 @@ component rules through the project's plugin adapter and `ds.config.json`, then
 run its actual build. Use `lint-config` directly for custom pipeline integration
 or debugging, not as a separate routine setup step.
 
-Use ADS 0.3 or later for the shared-resource preview compiler. `mcp` starts stdio
+Use ADS 0.3.1 or later for the shared-resource preview compiler. `mcp` starts stdio
 plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
 connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
 The tool client discovers entries and renders MCP Apps. Init adds the launch

package/dist/skills/ads-import/SKILL.md

@@ -21,9 +21,15 @@ relevant ranges with `ads_read_file` and send only a Git unified diff through
 `ads_apply_patch({ unit, patch, dryRun })`. A unit includes its own implementation,
 scenarios and fixtures; imported peers remain separate. `tokens` is the token
 foundation unit. Unit discovery and file ownership are distinct from preview IDs.
-Include only that owner's required re-exports in the public entry. Use
-`dryRun: true` to inspect validation; applying re-runs the gates. Fix rejected
-patches in their owner. Shared styles/helpers use `foundation`, root guides use
+Include only that owner's required re-exports in the public entry; preserve
+unrelated statements. Its real re-export may accompany removal of a redundant
+`export {};` placeholder; do not add empty exports. A `tokens` manifest lists the foundation
+entry in `companionFiles`: when creating/deleting a canonical token file such as
+`fonts.css`, include only its required import change there in the same patch.
+Preserve other imports/comments and the canonical order. Use `dryRun: true` to
+inspect validation; applying re-runs the gates. Fix rejected patches in their
+owner. Report unsupported coupled changes instead of bypassing a rejection with
+direct source writes. Shared styles/helpers use `foundation`, root guides use
 `documentation`, and branding/fonts use their discovered `assets/*` unit.
 Intentional configuration, rule exceptions, registered guard code and compiler
 changes use `configuration`; validate the proposed settings and keep mandatory
@@ -266,15 +272,25 @@ entry independently and verify real behavior at narrow/wide sizes in both themes
 The older `showcase-coverage` policy separately checks application references.
 
 Token previews use that same scenario pipeline. Colocate a token scenario and
-fixture under the configured token directory. Use static metadata
-`{ title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens }` with
-literal const fixture fields; names/sample text are fixture data, values come
-from the real foundation CSS. Reuse a public project review pattern for styled
-samples. The minimal starter's foundation value scenario can have `covers: []`.
-Every declared token needs reachable scenario coverage; adding/removing a token
-requires fixture updates. Fix `token-scenario-reference`, `token-scenario-render`
-and `token-scenario-coverage` findings. Metadata and unused fixture fields do not
-count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
+fixture under the configured token directory. Declare metadata
+`{ title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples }`.
+The renderer name is project-owned; use its real public API. Each literal fixture
+sample declares `{ token, property, probe }`: a real token, the CSS property its
+sample demonstrates, and a valid test value different from that token's current
+value. Pass `samples` into the rendered public review pattern. Names, sample text,
+bindings and probes are fixture data; displayed values come from foundation CSS.
+There is no property catalogue, token-name mapping or probe palette in ADS.
+Every token needs sample coverage; fabricated tokens, missing bindings/probes,
+unused fixtures and value-only lists fail the static gates. `covers: []` is invalid.
+During App rendering, the browser checks sample markers `data-ads-token` and
+`data-ads-property`, validates CSS with its own `CSS.supports`, and temporarily
+probes each token to verify that the declared sample property responds. It restores
+values immediately. Missing, hidden, invalid or hardcoded samples produce a preview
+error instead of a successful review. These browser checks apply to the mounted
+scenario/theme, not every application state or pixel-level design quality.
+Keep styles in the project renderer; do not add inline-style exemptions to scenarios.
+Fix `token-scenario-reference`, `token-scenario-render` and `token-scenario-coverage`
+findings. Metadata and unused fixture fields do not count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
 with `ads_show_scenario({id})` or `ads_show_tokens({category:id})`. With the shared
 resource compiler, omitting category opens the first project token scenario.
 Legacy compilers retain the generic definition inspector. Use `ads_tokens` for

package/dist/skills/ads-import/references/cli.md

@@ -55,7 +55,7 @@ If no published distribution exists, build and pack the tooling checkout with
 From inside an existing test project:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.1.tgz"
 npx --yes --package "$ads_tool_package" ads --help
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
@@ -93,7 +93,7 @@ component rules through the project's plugin adapter and `ds.config.json`, then
 run its actual build. Use `lint-config` directly for custom pipeline integration
 or debugging, not as a separate routine setup step.
 
-Use ADS 0.3 or later for the shared-resource preview compiler. `mcp` starts stdio
+Use ADS 0.3.1 or later for the shared-resource preview compiler. `mcp` starts stdio
 plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
 connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
 The tool client discovers entries and renders MCP Apps. Init adds the launch

package/dist/skills/ads-motion/SKILL.md

@@ -42,9 +42,15 @@ relevant ranges with `ads_read_file` and send only a Git unified diff through
 `ads_apply_patch({ unit, patch, dryRun })`. A unit includes its own implementation,
 scenarios and fixtures; imported peers remain separate. `tokens` is the token
 foundation unit. Unit discovery and file ownership are distinct from preview IDs.
-Include only that owner's required re-exports in the public entry. Use
-`dryRun: true` to inspect validation; applying re-runs the gates. Fix rejected
-patches in their owner. Shared styles/helpers use `foundation`, root guides use
+Include only that owner's required re-exports in the public entry; preserve
+unrelated statements. Its real re-export may accompany removal of a redundant
+`export {};` placeholder; do not add empty exports. A `tokens` manifest lists the foundation
+entry in `companionFiles`: when creating/deleting a canonical token file such as
+`fonts.css`, include only its required import change there in the same patch.
+Preserve other imports/comments and the canonical order. Use `dryRun: true` to
+inspect validation; applying re-runs the gates. Fix rejected patches in their
+owner. Report unsupported coupled changes instead of bypassing a rejection with
+direct source writes. Shared styles/helpers use `foundation`, root guides use
 `documentation`, and branding/fonts use their discovered `assets/*` unit.
 Intentional configuration, rule exceptions, registered guard code and compiler
 changes use `configuration`; validate the proposed settings and keep mandatory
@@ -156,15 +162,25 @@ entry independently and verify real behavior at narrow/wide sizes in both themes
 The older `showcase-coverage` policy separately checks application references.
 
 Token previews use that same scenario pipeline. Colocate a token scenario and
-fixture under the configured token directory. Use static metadata
-`{ title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens }` with
-literal const fixture fields; names/sample text are fixture data, values come
-from the real foundation CSS. Reuse a public project review pattern for styled
-samples. The minimal starter's foundation value scenario can have `covers: []`.
-Every declared token needs reachable scenario coverage; adding/removing a token
-requires fixture updates. Fix `token-scenario-reference`, `token-scenario-render`
-and `token-scenario-coverage` findings. Metadata and unused fixture fields do not
-count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
+fixture under the configured token directory. Declare metadata
+`{ title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples }`.
+The renderer name is project-owned; use its real public API. Each literal fixture
+sample declares `{ token, property, probe }`: a real token, the CSS property its
+sample demonstrates, and a valid test value different from that token's current
+value. Pass `samples` into the rendered public review pattern. Names, sample text,
+bindings and probes are fixture data; displayed values come from foundation CSS.
+There is no property catalogue, token-name mapping or probe palette in ADS.
+Every token needs sample coverage; fabricated tokens, missing bindings/probes,
+unused fixtures and value-only lists fail the static gates. `covers: []` is invalid.
+During App rendering, the browser checks sample markers `data-ads-token` and
+`data-ads-property`, validates CSS with its own `CSS.supports`, and temporarily
+probes each token to verify that the declared sample property responds. It restores
+values immediately. Missing, hidden, invalid or hardcoded samples produce a preview
+error instead of a successful review. These browser checks apply to the mounted
+scenario/theme, not every application state or pixel-level design quality.
+Keep styles in the project renderer; do not add inline-style exemptions to scenarios.
+Fix `token-scenario-reference`, `token-scenario-render` and `token-scenario-coverage`
+findings. Metadata and unused fixture fields do not count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
 with `ads_show_scenario({id})` or `ads_show_tokens({category:id})`. With the shared
 resource compiler, omitting category opens the first project token scenario.
 Legacy compilers retain the generic definition inspector. Use `ads_tokens` for

package/dist/token-policy.mjs

@@ -1,4 +1,6 @@
 import { readFileSync } from "node:fs";
+import path from "node:path";
+import valueParser from "postcss-value-parser";
 
 export const tokenContract = JSON.parse(readFileSync(new URL("./contracts/tokens.json", import.meta.url), "utf8"));
 
@@ -8,3 +10,13 @@ export function isSharedToken(name) {
 }
 
 export const foundationFiles = ["fonts.css", "colors.css", "typography.css", "spacing.css", "elevation.css", "base.css"];
+
+/** The foundation entry accepts only a single, unconditional local import. */
+export function foundationImportTarget(node, file) {
+  if (node.type !== "atrule" || node.name !== "import" || node.nodes) return null;
+  const parts = valueParser(node.params).nodes.filter(part => part.type !== "space" && part.type !== "comment");
+  if (parts.length !== 1) return null;
+  const part = parts[0];
+  const value = part.type === "string" ? part.value : part.type === "function" && part.value === "url" && part.nodes.length === 1 ? part.nodes[0].value : null;
+  return value ? path.resolve(path.dirname(file), value) : null;
+}

package/dist/token-samples.mjs

@@ -0,0 +1,8 @@
+/** Projects declare bindings and verification inputs; ADS supplies no sample catalogue. */
+export function validTokenSamples(samples) {
+  return Array.isArray(samples) && samples.length > 0 && samples.every(sample => sample && typeof sample === "object"
+    && typeof sample.token === "string" && /^--[\w-]+$/.test(sample.token)
+    && typeof sample.property === "string" && /^-?[a-z][a-z0-9-]*$/.test(sample.property)
+    && typeof sample.probe === "string" && sample.probe.trim().length > 0)
+    && new Set(samples.map(sample => `${sample.token}:${sample.property}`)).size === samples.length;
+}

package/dist/units.mjs

@@ -1,9 +1,11 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import ts from "typescript";
+import postcss from "postcss";
 import { isInside } from "./config.mjs";
 import { importResolver } from "./boundaries.mjs";
 import { isProjectDocument, projectGuideFiles } from "./project-documents.mjs";
+import { foundationFiles, foundationImportTarget } from "./token-policy.mjs";
 
 const source = /\.[cm]?[jt]sx?$/;
 const slash = file => file.replaceAll("\\", "/");
@@ -89,6 +91,7 @@ export function inspectUnits(options) {
   }))].sort((a, b) => b.length - a.length);
   const publicEntry = slash(path.relative(dsRoot, path.join(dsRoot, config.publicEntry)));
   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";
@@ -107,6 +110,8 @@ export function inspectUnits(options) {
   const units = new Map();
   units.set("configuration", { id: "configuration", kind: "configuration", files: [...setup].filter(file => existsSync(path.join(root, file))).sort() });
   for (const id of ["foundation", "documentation", "tokens", "assets/brand", "assets/fonts"]) units.set(id, { id, kind: id.split("/")[0], files: [] });
+  units.get("tokens").companionFiles = [{ path: slash(path.relative(root, path.join(dsRoot, stylesEntry))),
+    allowedChanges: "Only add/remove canonical foundation imports required by token foundation files created/deleted in this patch; preserve other imports and comments." }];
   units.get("documentation").files = projectGuideFiles(root);
   for (const relative of files) {
     const id = owner(relative);
@@ -115,7 +120,7 @@ export function inspectUnits(options) {
     const file = slash(path.relative(root, path.join(dsRoot, relative)));
     if (!units.get(id).files.includes(file)) units.get(id).files.push(file);
   }
-  return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry,
+  return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry, stylesEntry, tokenDir,
     relative: file => slash(path.relative(dsRoot, path.resolve(root, file))) };
 }
 
@@ -130,6 +135,7 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
     const relative = inventory.relative(change.path);
     if (allowNew && unit === "configuration") continue; // The candidate must register every setup/extension file.
     if (relative === inventory.publicEntry) 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);
     if (owner !== unit) throw fail(`This patch targets ${unit}; ${change.path} belongs to ${owner ?? "a different ADS layer"}. Submit a separate unit patch.`, change.path);
@@ -147,22 +153,40 @@ export function checkUnitCandidate(afterOptions, unit, changes, before) {
     if (unit === "configuration" && (entry.id === "configuration" || after.owner(relative) === "configuration")) continue;
     if (after.owner(relative) !== entry.id) throw fail("A patch cannot change ownership of existing peer units. Choose an unoccupied owner path.", file);
   }
+  const foundationChange = changes.find(change => before.relative(change.path) === before.stylesEntry);
+  if (unit === "tokens" && foundationChange) {
+    const { originalContent: current, content: proposed } = foundationChange;
+    if (typeof current !== "string" || typeof proposed !== "string") throw fail("A token patch cannot create or delete the foundation entry.", foundationChange.path);
+    const canonical = new Set(foundationFiles.map(name => slash(path.join(before.tokenDir, name))));
+    const affected = new Set(changes.filter(change => (change.originalContent === null || change.content === null) && canonical.has(before.relative(change.path)))
+      .map(change => path.join(afterOptions.dsRoot, before.relative(change.path))));
+    if (!affected.size) throw fail("Foundation companion changes require creating or deleting a canonical token foundation file in the same token patch.", foundationChange.path);
+    const file = path.join(afterOptions.dsRoot, afterOptions.config.stylesEntry);
+    function unrelated(content) {
+      try {
+        return postcss.parse(content, { from: file }).nodes.filter(node => !affected.has(foundationImportTarget(node, file))).map(node => node.toString());
+      } catch (error) { throw fail(`Invalid foundation import companion: ${error.reason ?? error.message}`, foundationChange.path); }
+    }
+    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"].includes(unit.split("/")[0])) throw fail("Only a component/pattern unit may update its public re-exports.", 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);
-    function unrelated(content) {
-      const file = path.join(afterOptions.dsRoot, afterOptions.config.publicEntry);
-      const ast = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
-      return ast.statements.filter(statement => {
-        if (!ts.isExportDeclaration(statement) || !statement.moduleSpecifier || !ts.isStringLiteralLike(statement.moduleSpecifier)) return true;
-        const targets = resolve(statement.moduleSpecifier.text, file);
-        return !targets.length || targets.some(target => !isInside(afterOptions.dsRoot, target) || after.owner(slash(path.relative(afterOptions.dsRoot, target))) !== unit);
-      }).map(statement => statement.getText(ast)).join("\n");
+    const file = path.join(afterOptions.dsRoot, afterOptions.config.publicEntry);
+    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;
+    function ownedExport(statement) {
+      if (!ts.isExportDeclaration(statement) || !statement.moduleSpecifier || !ts.isStringLiteralLike(statement.moduleSpecifier)) return false;
+      const targets = resolve(statement.moduleSpecifier.text, file);
+      return targets.length && targets.every(target => isInside(afterOptions.dsRoot, target) && after.owner(slash(path.relative(afterOptions.dsRoot, target))) === unit);
     }
-    if (unrelated(current) !== unrelated(proposed)) throw fail("Public-entry patches may change only re-exports from the selected unit; preserve all other statements.", exportChange.path);
+    const cleanup = candidate.statements.some(ownedExport) && !candidate.statements.some(emptyExport);
+    const unrelated = ast => ast.statements.filter(statement => !ownedExport(statement) && !(cleanup && emptyExport(statement))).map(statement => statement.getText(ast)).join("\n");
+    if (unrelated(original) !== unrelated(candidate)) throw fail("Public-entry patches may change only re-exports from the selected unit and remove a redundant empty export alongside its real re-export; preserve all other statements.", exportChange.path);
   }
   if (!before.units.some(entry => entry.id === unit) && !after.units.some(entry => entry.id === unit)) throw fail("The patched files do not establish the selected ADS unit.");
 }

package/docs/ADS.md

@@ -13,6 +13,8 @@ before application. This includes
 foundation, documentation, original assets and an explicit configuration unit for
 project settings, registered guard code and compiler integration. Configuration
 patches validate the proposed policy; mandatory core gates remain enabled.
+Required public re-exports and canonical foundation import changes may accompany
+their owner under the narrow companion rules in the MCP editing contract.
 Source checks do not establish visual correctness; normal lint/build gates
 remain required for edits made through other tools.
 See the [MCP editing contract](MCP.md#guarded-editing).
@@ -89,13 +91,24 @@ design-system/
 Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
 `Scenario.tsx` exports a default independently mountable view and literal metadata
 `export const scenario = { title: "Button states", covers: ["Button"] };`.
-Token entries under the configured token directory also declare `tokens`:
-`export const scenario = { title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens };`.
-Metadata may read literal const fixture fields; it cannot run expressions,
-functions, wildcard lists or token discovery. The same fixture list must be
-consumed by the default entry. `covers: []` is valid for a minimal token value
-inspection entry without public UI; styled samples use a real public review
-pattern. Names and sample text belong to the fixture, values to foundation CSS.
+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.
+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
+samples to a rendered public pattern's `samples` prop. No token-name/property mapping
+or sample values are embedded in the tool. Display values come from foundation CSS;
+probes are isolated verification inputs owned by the fixture.
+
+The renderer marks the actual styled element with `data-ads-token` and
+`data-ads-property`. In a browser, the App validates the declared property/value and
+probe using `CSS.supports`, checks the sample is rendered, then temporarily changes
+that token to its fixture probe. Its computed sample property must respond. Values
+are restored before yielding to painting; hardcoded lookalikes fail. Source gates
+prove the contract structure, not successful rendering. The browser check covers
+the mounted scenario and theme; visual quality and other states still need review.
+
 It imports real public UI through `@ds` and its local fixture. The adapter supplies
 initial state, callbacks and simulated services. The default entry needs no
 mandatory caller inputs or prior page initialization. Related parts may share a
@@ -279,8 +292,9 @@ Validate accepted and rejected cases, configuration, and false-positive limits.
 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 component
-and pattern directories, not a catalogue.
+`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
+does not require that name or its styles and ships no product UI catalogue.
 
 Tool releases should version contract changes, rules, skills, bootstrap support,
 and migration guidance. Existing project implementations and external source

package/docs/ARCHITECTURE.md

@@ -273,6 +273,11 @@ replace the managed process while retaining the MCP connection. Normal build gat
 remain in place for source changes made through other editors; preview review remains
 necessary after either editing path.
 
+Required shared-entry bookkeeping can accompany its owner: component/pattern
+re-exports and canonical foundation imports for token files created or deleted in
+the same patch. ADS restricts these companion edits and validates the complete
+candidate before writing, so coupled changes do not need a guard bypass.
+
 The architecture makes that inspection practical. A public export has an owning
 source and addressable preview coverage. Token definitions expose its visual
 vocabulary; local guides explain contracts when present. An agent can discover a
@@ -309,3 +314,10 @@ For concrete instructions, use:
 - [Tool guide](GUIDE.md) for prerequisites, supported formats, configuration, and build wiring.
 - [Working example guide](../design-system/README.md) for Linaria composition, extraction, and project commands.
 - Component-local READMEs for APIs, lifecycle, tests, and provenance.
+
+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
+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.

package/docs/CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
-## Unreleased
+## 0.3.1
+
+- Stop generating redundant empty public exports. Allow an owning unit's public
+  re-export companion to remove an obsolete placeholder without changing peers.
+- Require token fixtures to declare real CSS sample bindings and project-owned
+  probes, consumed by a public review pattern. Reject empty covers and plain lists.
+  Apps verify rendered property dependencies in the browser before reporting ready.
+  The tool infers no token roles and contains no property/probe catalogue. Existing
+  projects need a token scenario migration and preview rebuild.
+- Restore native scrolling inside resource preview Apps for scenarios taller or
+  wider than their viewport, while retaining full-height composition layouts.
+- Allow a `tokens` mutation to add/remove the required foundation import together
+  with its canonical token file. Discover the entry through `ads_units` companion
+  metadata; preserve unrelated imports/comments and validate before writing.
+
+## 0.3.0
 
 - Rebrand the tool as ADS — Agentic Design System: `@reqvire-org/ads`, the `ads`
   CLI, `ads_*` MCP tools, `ads://` resources and `ads-*` skills. Keep project

package/docs/GUIDE.md

@@ -12,7 +12,7 @@ fonts, mock screens, or UI runtime dependency.
 Linaria is required for component and pattern styling. Projects choose their
 UI framework and visual design; `init` preserves framework configuration and
 adds no React runtime dependency. See the
-[architecture](https://github.com/reqvire-org/design-system/blob/main/docs/ARCHITECTURE.md#linaria-is-the-implementation-mechanism)
+[architecture](https://github.com/reqvire-org/ads/blob/main/docs/ARCHITECTURE.md#linaria-is-the-implementation-mechanism)
 for the rationale.
 
 Current source checking supports `.js`, `.jsx`, `.ts`, `.tsx`, their module
@@ -45,9 +45,9 @@ project's existing build:
   result. Static source checks do not establish complete extraction or
   unused-style removal.
 
-The [empty starter's dependencies](https://github.com/reqvire-org/design-system/blob/main/bootstrap-ds/package.json),
-[entry build](https://github.com/reqvire-org/design-system/blob/main/bootstrap-ds/vite.config.ts),
-and [preview compiler](https://github.com/reqvire-org/design-system/blob/main/bootstrap-ds/scripts/build-mcp-previews.mjs)
+The [empty starter's dependencies](https://github.com/reqvire-org/ads/blob/main/bootstrap-ds/package.json),
+[entry build](https://github.com/reqvire-org/ads/blob/main/bootstrap-ds/vite.config.ts),
+and [preview compiler](https://github.com/reqvire-org/ads/blob/main/bootstrap-ds/scripts/build-mcp-previews.mjs)
 provide the React/Vite setup. Merge the needed integration into an existing
 project instead of replacing its configuration.
 
@@ -78,8 +78,8 @@ attributes when the project/file JSX runtime or factory is native Preact. Preact
 and exports DOM types such as `HTMLAttributes` directly; Preact 10's `JSX` type
 namespace is also recognized by guards. See the [Preact upgrade guide](https://preactjs.com/guide/v11/upgrade-guide/).
 
-The [working example](https://github.com/reqvire-org/design-system/tree/main/design-system)
-and its [compiler adapter](https://github.com/reqvire-org/design-system/blob/main/scripts/build-mcp-previews.mjs)
+The [working example](https://github.com/reqvire-org/ads/tree/main/design-system)
+and its [compiler adapter](https://github.com/reqvire-org/ads/blob/main/scripts/build-mcp-previews.mjs)
 show the native setup. When converting the copied React starter to Preact,
 update its runtime dependencies, JSX settings, framework transform, mount adapter,
 and existing `framework` field together. Change the existing foundation scenario's
@@ -215,7 +215,7 @@ refresh generated resource manifests. Existing `DS.md` project guides are still
 discovered; the tool's contract and new scaffold use `ADS.md`.
 
 npm has no in-place package rename: publish `@reqvire-org/ads` as a new package.
-Set up its own trusted publisher for `reqvire-org/design-system`, workflow
+Set up its own trusted publisher for `reqvire-org/ads`, workflow
 `release.yml`, allowing `npm publish` and `npm dist-tag`. Once ADS is available,
 deprecate the old package with a migration message:
 
@@ -302,7 +302,7 @@ For iterative development, use the linking workflow above. From the repository r
 npm install
 npm run build
 npm run pack:tool
-ads_tool_package="$PWD/output/npm/reqvire-org-ads-0.3.0.tgz"
+ads_tool_package="$PWD/output/npm/reqvire-org-ads-0.3.1.tgz"
 ```
 
 Then change into an existing test project containing `package.json`:
@@ -430,19 +430,22 @@ export default function Scenario() { return <Button>{fixture.label}</Button>; }
 IDs derive from filenames; do not maintain another registry or hand-assigned IDs.
 Token scenarios live beside foundation CSS under the configured token directory.
 The starter includes `tokens/Foundation.scenario.tsx` and its local fixture for
-plain value inspection without a component library. For styled samples, use a
-public project review pattern and keep its presentation in that pattern:
+a project-owned token review pattern. Keep its presentation in that pattern:
 
 ```tsx
 import { TokenSamples } from "@ds";
 import { fixture } from "./Typography.fixture";
-export const scenario = { title: fixture.title, covers: ["TokenSamples"], tokens: fixture.tokens };
+export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };
 export default function Scenario() { return <TokenSamples {...fixture} />; }
 ```
 
 `TokenSamples` is an example project-owned pattern, not an npm tool component.
-The fixture defines literal names and sample text, with no copied token values.
-Add/remove names when foundation tokens change. `token-scenario-reference`,
+The fixture defines literal `samples: [{ token, property, probe }]` and sample text.
+Token values come from foundation CSS; the fixture owns a distinct, valid CSS probe
+for verifying each declared property. Add/remove samples when tokens change.
+The renderer marks its styled elements with `data-ads-token` and `data-ads-property`.
+The App probes their computed properties in the browser; name/value labels alone
+do not pass. No CSS-property list or test palette is built into ADS. `token-scenario-reference`,
 `token-scenario-render` and `token-scenario-coverage` enforce real references and
 coverage for every token. The same source/style/import checks apply under tokens/.