@reqvire-org/ads 0.3.0 → 0.3.2

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
@@ -182,6 +198,25 @@ Use local simulated services in fixtures. Tests may import fixtures; load real
 foundation CSS rather than assigning shared token values in JavaScript. Keep
 full-app integration harnesses and workflow coverage in application test support.
 
+Foundation CSS is checked, not an escape hatch. Value sheets define shared tokens
+on the document root/themes; `fonts.css` holds font-face metadata. `base.css` has
+three closed roles: root/body typography, canvas and theme defaults; limited native
+normalization; and global focus indicators/reduced-motion rules. Every selector
+branch, property and value must fit its role. Token-backed control skins, layout,
+interactive state rules and owner hooks are rejected even through `:where()`.
+Do not copy an unchecked upstream preflight or turn a component repair into a reset.
+Put skin/state/animation in the Linaria owner, and scenario layout variations in
+the public review pattern's typed API. Browser review still verifies the effects.
+
+Invalid metadata and source failures keep the managed compiler alive for repairs.
+Read `ads_status.build` or `ads://project/build`, fix the owner, then wait for current
+successful output. If the builder exited, fix its command and invoke the preview
+again; ADS starts one fresh child without an MCP reconnect. Compiler-code changes
+also reload on the next preview invocation. Reconnect the client when upgrading
+the ADS server package itself. Persistent SSE/notification streams make
+`networkidle` unsuitable: wait for the App's current ready/error state instead.
+
+
 
 
 Register component/project Oxlint plugins and rules in `ds.config.json`. Use

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
@@ -156,6 +169,35 @@ custom styling in fixture files. The ADS frame pattern uses `--ux-*`. Foreign br
 CSS imports the approved token files in order; shared assignments belong in
 those token files, never in consumer styles or component state overrides.
 
+Foundation roles are enforced by `foundation-role`, `foundation-selector` and
+`foundation-import`, alongside the regular token checks. Shared definitions
+belong on the document root or explicit root themes; ordinary declarations belong
+in `base.css`, and font-face descriptors in optional `fonts.css`. The entry imports
+canonical sheets; those sheets cannot import another styling layer. Component
+classes, IDs, data/ARIA hooks, contextual selectors, keyframes and scoped UI rules
+are rejected in the foundation, including nested functional selectors. Raw visual
+values and undefined token references are checked in native defaults too; literal
+font-face metadata keeps its separate asset role.
+
+`base.css` has three closed roles:
+
+- Document defaults: root/body typography, canvas colors and theme behavior,
+  global text selection and document scrollbars.
+- Native resets: permitted normalization properties and values, such as zero
+  spacing, inherited control typography, list resets and responsive replaced media.
+- Global accessibility: universal `:focus-visible` outline rules, and reduced-motion
+  overrides inside `@media (prefers-reduced-motion: reduce)`.
+
+The `foundation-role` check validates every selector branch, property and value.
+Native selectors are not a bypass: token-backed button backgrounds, flex/grid
+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
+still checks the effects and accessibility of permitted defaults.
+
+
 Store original branding and its usage, credits, and licenses in
 `assets/brand/`, and fonts in `assets/fonts/`. Configure generated icons and
 asset mounts as described in the [branding guide](GUIDE.md#branding).
@@ -279,8 +321,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

@@ -191,6 +191,29 @@ and the UI rendered inside Apps belong to the project. This keeps the tool usefu
 with an empty ADS while making every implementation addressable once its scenario
 exists.
 
+### The foundation has a narrow styling role
+
+Shared token sheets define values on the document root and its themes. The
+import-only entry loads them in canonical order. `fonts.css` declares font faces;
+`base.css` establishes shared native defaults and normalization. Components and
+patterns own their layout, skin, states and animations in Linaria.
+
+`base.css` has a closed contract with three roles: root/body typography, canvas
+colors and theme behavior; limited native normalization; and global accessibility
+through focus indicators and reduced-motion rules. Selector, property and value
+checks reject component skins and layout even when they use native selectors and
+valid tokens. A `button` background or `body` grid belongs to a Linaria owner.
+Document defaults also cover shared text selection and document scrollbars;
+local control/scroll-container styling stays with its owner.
+
+Foundation CSS passes the ordinary token-reference and visual-value checks too.
+Parsed selectors reject component hooks, local shared-token overrides and
+contextual selectors, including hooks concealed in `:where()` or `:is()`. The
+policy describes CSS roles and normalization keywords, with no project classes,
+token catalogue or sample templates. Lower specificity cannot bypass ownership.
+Static gates establish this source contract; browser review still checks its
+actual effects and accessibility.
+
 ### A preview scenario is the unit of review
 
 A component export alone may need inputs, parent context, local state or callbacks
@@ -201,8 +224,9 @@ page or initializing the application's router, store or services first.
 Scenarios and their fixtures live beside the tokens, component or pattern they exercise.
 Token scenarios choose real token names and sample inputs; a project-owned
 review pattern applies the foundation variables. The tool contains no project
-token list, sample templates or assumed visual identity. A minimal foundation
-scenario can inspect values before a project has any components.
+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;
+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;
 scenario adapters supply fixture data, local state and simulated services.
@@ -222,7 +246,12 @@ After source changes, validation and compilation must both succeed before a new
 graph becomes current. MCP announces build/resource updates. The built-in client
 refreshes discovery and sends the current selection to the existing App, whose
 loader mounts the new module graph. Failed builds retain the previous view with
-visible stale diagnostics. Compilation remains necessary for TSX and Linaria;
+visible stale diagnostics. Invalid scenario metadata at startup and later source
+failures stay in the watcher's recoverable diagnostic path. Fixing source triggers validation again.
+If the compiler process exits, the next preview request starts one fresh child;
+MCP inspection remains available. Each child generation has its own status report,
+so independent MCP clients do not overwrite each other's build state.
+Compilation remains necessary for TSX and Linaria;
 there is one preview pipeline with automatic updates.
 
 Scenario entries, adapters and fixtures are development source even when
@@ -273,6 +302,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 +343,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,37 @@
 # Changelog
 
-## Unreleased
+## 0.3.2
+
+- Enforce foundation CSS roles, parsed selector boundaries, root-only shared token
+  assignments, token references and visual values. Keep native defaults in
+  `base.css`, definitions in value sheets and font-face metadata in `fonts.css`;
+  reject hidden owner styling, extra imports and animation/scoping escapes.
+  Close `base.css` to document defaults, limited normalization and global
+  accessibility; native selectors and valid tokens cannot hide component skins
+  or layout. Move the demo link hover styling into its TextLink owner.
+- Keep scenario discovery and build failures recoverable in the watcher, including
+  invalid metadata at startup. Reattach replaced source-directory watches.
+- Retry exited builders on the next preview request without reconnecting MCP;
+  reload changed compiler code through a fresh child and preserve inspection.
+  Isolate status reports per child session across concurrent MCP clients.
+- Align the starter, example foundation and skills with the enforced boundaries.
+
+## 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

@@ -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.2.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/.
 
@@ -494,6 +497,14 @@ import-only: fonts (when present), colors, typography, spacing, elevation, base.
 Fixed artwork colors and geometry are permitted inside SVG assets; they do not
 permit raw visual values in component or pattern styles.
 
+Foundation sheets are checked source. Keep root token definitions in value sheets,
+font faces in `fonts.css`, and closed-role defaults in `base.css` (document
+typography/canvas/theme, limited native resets, global focus/reduced motion).
+Owner hooks, contextual UI selectors, keyframes, extra CSS imports, raw visual
+values and missing token references fail checks there too. Move component-specific
+repairs into their Linaria owner; see the [foundation contract](ADS.md#shared-token-contract).
+
+
 Select one SVG master with an ADS-relative path:
 
 ```json

package/docs/MCP.md

@@ -43,7 +43,7 @@ Switching entries overlays a centered loading spinner, then reveals the new
 scenario inside the existing App. Loading and diagnostic overlays do not move the
 preview. Token presentation comes from project-owned scenarios, fixtures and
 public review patterns, using the project's real foundation CSS and extracted
-styles. The tool contains no token sample templates or named token ordering.
+styles. The App runtime contains no token sample templates or named token ordering.
 The generic definition inspector remains available without a scenario build.
 
 There are no required browser-page files in the project. Colocated scenarios and
@@ -200,6 +200,15 @@ remain separate owners. `tokens` is one foundation unit covering token definitio
 themes and token scenarios/fixtures, whose coverage spans shared source files.
 Preview IDs remain separate: several token previews belong to `tokens`.
 
+The `tokens` manifest also returns `companionFiles` with the configured foundation
+entry path. When creating or deleting a canonical token foundation file, include
+its required import change in the same `tokens` patch. For example, add
+`tokens/fonts.css` and its first import in `styles.css` together; remove both
+together when removing that font stylesheet. This companion may only change
+imports for canonical files created/deleted in that patch. Preserve other imports
+and comments, retain the foundation entry, and follow the required import order.
+Both files pass the same candidate checks before either is written.
+
 The same discovery covers the rest of the project ADS:
 
 | Unit | Scope |
@@ -259,7 +268,11 @@ so coverage is checked against a complete candidate. New units use a new
 `components/`, `patterns/` or `composition/` owner ID following the same colocation
 convention. A patch cannot include a peer unit, capture existing peers beneath
 a new directory owner, or change unrelated public-entry statements. Shared
-public-entry changes are limited to re-exports from the selected unit.
+public-entry changes are limited to re-exports from the selected unit. Alongside
+its real re-export, a patch can remove an obsolete `export {};` placeholder;
+it cannot add one or change unrelated statements. Init generates no empty-export
+placeholder. Report unsupported coupled changes rather than bypassing a rejected
+mutation with direct source writes.
 
 Set `dryRun` to `false` to apply. ADS reconstructs complete candidate files locally
 and validates a temporary project copy with core guards and registered Oxlint
@@ -485,11 +498,17 @@ success cache is republished in the new watcher session without recompilation;
 merely finding an older HTML file is insufficient. A timeout leaves the watcher running: inspect the
 logs and invoke the preview again. `ads_status` distinguishes watcher process
 state from reported build state. Token inspection and other ordinary tools
-remain available after a build failure. An exited watcher needs reconnection;
-an active watcher can recover on the next successful rebuild. Changes to
-`previewWatch`, the compiler adapter or ADS tooling require reconnection to load
-new process code. The shared scheduler rejects publication if its loaded adapter
-files change; normal component, fixture and style edits remain automatic.
+remain available after a build failure. Invalid scenario metadata at startup and
+later source/validation failures remain reported while the compiler watches for
+repairs. A successful edit recovers without reconnecting MCP. If the child process
+exits, fix the builder and invoke the preview again: concurrent requests share one
+fresh child and session. ADS does not run an unattended crash/restart loop.
+
+Changes to loaded compiler code or dependencies produce `ADS_PREVIEW_RESTART`;
+the next preview invocation restarts only the builder and validates current inputs.
+Managed configuration changes replace the compiler through the same supervisor.
+Updating ADS server code itself still requires reconnecting the MCP client to load
+the new package. Normal component, fixture and style edits remain automatic.
 
 ADS stops the managed watcher and its compiler subprocesses when stdin closes or
 it receives SIGINT/SIGTERM. The project must keep its watcher in the foreground,
@@ -516,7 +535,10 @@ No ADS package release or skill reinstall is needed for project component change
 ### When code or styles break
 
 A preview publisher reports `building`, `ready` or `error` to
-`.ds/build-status.json`. `ads_status.build` and the `ads://project/build` resource
+`.ds/build-status.json` for standalone builds. A managed compiler receives its own
+`.ds/build-status-<session>.json` through `ADS_MCP_BUILD_STATUS`; publishers must
+honor that path and `ADS_MCP_BUILD_SESSION`. Independent MCP clients therefore do
+not clobber each other's reports. `ads_status.build` and the `ads://project/build` resource
 expose those states, each preview's build revision, last successful revision,
 availability, freshness and diagnostics. Diagnostic positions are one-based.
 Tool summaries include the first three diagnostics per preview, capped at 1,000
@@ -540,7 +562,9 @@ failed build even when older output remains on disk. The reusable bootstrap and
 retained immutable assets stay readable so an existing App can report freshness;
 readability alone does not establish a current preview. After a successful rebuild the same
 tool works again without restarting MCP. If the watcher itself exits, its
-failure is reported and the client must reconnect after fixing the command.
+failure is reported; after fixing the command, invoke the preview again to start
+a fresh builder. Partial or empty scenario discovery also exposes project-level
+diagnostics through `ads://project/build`.
 
 Already-mounted Apps show rebuilding, failure or a newer available revision
 when the host permits server resource reads. They check build status every two
@@ -688,3 +712,32 @@ verify tools, explicit resources, an App entry tool and its UI handshake,
 Refresh/theme behavior, notifications, prompts, then native Skills separately.
 Record the client build and negotiated protocol; HTML delivery or ordinary
 instruction reads alone do not establish Apps/Skills activation.
+
+### Token sample verification
+
+Token scenarios declare `samples: fixture.samples` and render a project-owned public
+review pattern with that `samples` input. Each fixture record has `{ token, property,
+probe }`; the tool discovers the resulting token names. Plain token lists and empty
+covers do not satisfy review coverage. The same bindings travel in the compiled
+resource manifest or self-contained App seed.
+
+The renderer identifies its styled sample elements through `data-ads-token` and
+`data-ads-property`. After mounting and font loading, the App uses the browser's CSS
+engine to validate each declared binding and project-supplied probe, then checks
+that changing the token changes the sample's computed property. It restores token
+values synchronously. Failures remain visible and are emitted through App logging
+when the host supports it; a failed sample is not reported as ready.
+
+Source checks establish structural coverage. Browser verification happens when the
+App actually renders, for the active scenario and theme. It is not a pre-write
+browser test in the mutation server and does not establish every interaction or
+pixel-level visual quality. Hosts without Apps retain static diagnostics and the
+showcase URL; they cannot claim rendered verification from a source check alone.
+For browser automation, wait for the selected App's ready/error state. The
+showcase's live notification stream makes `networkidle` unsuitable. Tall previews
+scroll inside the App document; verify their last sample remains reachable.
+
+Existing projects migrate their token fixtures from name lists to explicit sample
+records, pass those records into their public renderer, and add the sample markers.
+Rebuild previews with the updated compiler so the contract is included in resources.
+Tool updates do not overwrite existing project-owned scenarios or renderers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -35,7 +35,7 @@
     "sync:skill-starter": "node scripts/sync-skill-starter.mjs",
     "check:skill-starter": "node scripts/sync-skill-starter.mjs --check",
     "lint": "npm run lint:tool",
-    "lint:tool": "npm run check:skill-starter && oxlint --deny-warnings src showcase-client mcp-explorer tests/*.test.mjs scripts/build-ads-tool.mjs scripts/pack-ads-tool.mjs",
+    "lint:tool": "npm run check:skill-starter && oxlint --deny-warnings src preview-client showcase-client mcp-explorer tests/*.test.mjs scripts/build-ads-tool.mjs scripts/pack-ads-tool.mjs",
     "lint:project": "npm run lint:ds && npm run lint:style && npm run check:skill-starter",
     "lint:ds": "node dist/cli.mjs lint-config && node dist/cli.mjs check && oxlint --deny-warnings --config .ds/oxlintrc.json src design-system",
     "lint:style": "biome lint --config-path=biome.css.json .",
@@ -51,6 +51,7 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.3.1",
     "postcss": "^8.5.30",
+    "postcss-selector-parser": "^7.1.6",
     "postcss-value-parser": "^4.2.0",
     "sharp": "^0.35.5",
     "typescript": "^5.9.3",