@reqvire-org/ads 0.3.0 → 0.3.1

package/dist/mcp/prompts.mjs

@@ -1,6 +1,6 @@
 export const reasoning = `ADS is development tooling. The project owns its components, patterns, token values and branding.
 Start with ads_status and use its projectRoot, workflow and project commands; the MCP workspace may be nested inside the client repository. If ADS tools are not exposed, read ads://project/guide then ads://project/status. Find existing public UI with ads_catalog and load one relevant ADS workflow via ads_skills/ads_read_skill. UI implementation/refinement uses ads-designer; library adaptation ads-assimilate; ADS transfer ads-import; motion ads-motion; stress testing ads-break-ui. Domain-model workflows are separate. Inspect the relevant public API, local guide, token definitions and real showcase fixture before proposing changes. Keep source/instruction discovery scoped to the target project, ancestry and selected external sources; broad scans of /mnt or home are not needed to discover this ADS.
-When ads_status.mutations.enabled, discover one owner with ads_units, read 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 scenarios/fixtures; imported peers remain separate. tokens is the token foundation unit. Only that owner's public re-exports may change in the shared entry. Use dryRun to review validation. Rejected patches leave source unchanged; fix diagnostics rather than bypassing checks with direct writes. Shared globals use foundation; guides use documentation; assets use discovered assets/* units. Intentional configuration, registered project guards/builders and rule exceptions use configuration, which validates the proposed settings and refreshes its compiler. Keep mandatory ADS gates. For large/binary diffs, pass patchFile pointing to .ds/patches/<name>.patch rather than loading bytes into context; Git binary patches require installed Git. When editing is disabled, use local editing tools.
+When ads_status.mutations.enabled, discover one owner with ads_units, read 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 scenarios/fixtures; imported peers remain separate. tokens is the token foundation unit. Only that owner's public re-exports may change in the shared entry; preserve unrelated statements including export {};. Token manifests list companionFiles: include required foundation import changes only for canonical token files created/deleted in the same patch, preserving other imports/comments and canonical order. Use dryRun to review validation. Rejected patches leave source unchanged; fix diagnostics rather than bypassing checks with direct writes. Shared globals use foundation; guides use documentation; assets use discovered assets/* units. Intentional configuration, registered project guards/builders and rule exceptions use configuration, which validates the proposed settings and refreshes its compiler. Keep mandatory ADS gates. For large/binary diffs, pass patchFile pointing to .ds/patches/<name>.patch rather than loading bytes into context; Git binary patches require installed Git. When editing is disabled, use local editing tools.
 Reason through Data (design-token values, semantic roles and relationships), UX (structure, behavior, accessibility, states and layout), and Skin (token-backed identity and visual states). Business data is a separate application-owned input, supplied through typed props or injected callbacks/services. The project uses Linaria extraction for owned styles; MCP adds no production runtime.
 Choose an existing public component or pattern first. Keep application data/routing/effects in the application and fixture data/state beside its scenario. Change presentation in its owning ADS implementation, then demonstrate the same public API in the showcase. Do not create a widget-only replica or override component internals.
 For token source inspection, call ads_tokens with a focused query. For token samples, components, patterns and composition, use ads_scenarios to select a path-derived id and invoke ads_show_scenario. Showcase and MCP mount that exact entry and its colocated fixture; no page initialization is required. The showcase is a minimal tool-owned shell plus an MCP client and Apps host. Its menus come from tools; it invokes the same entry tools and refreshes the active scenario through notifications. The reusable App loads framework runtime, foundation CSS, fonts and selected modules via MCP resources inside its sandbox. Keep project execution and styles out of the outer host; preserve mount/unmount cleanup and lazy dependencies. Use the existing ads_status showcase URL, or ads showcase when no MCP runtime is connected. Projects supply scenarios/fixtures and the compiler, not browser page files or another shell. Tool metadata selects an MCP App; a resources/read of HTML alone is not proof of rendered UI. If the host has no Apps view, give the configured showcase URL and use text/resources.

package/dist/mcp/server.mjs

@@ -43,12 +43,12 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   const project = () => { const context = projectContext(options); context.showcase.url = getShowcaseUrl(); return context; };
   const subscribed = new Set();
   const server = new Server({ name: "reqvire-ads", version: pkg.version }, {
-    instructions: `${serverInstructions} ${mutations ? "Guarded editing is enabled: discover one owner with ads_units, read relevant ranges with ads_read_file and send only a Git unified diff to ads_apply_patch with that unit ID. Include its own scenarios/fixtures and required re-exports together, never unrelated units. The server validates architecture, registered Oxlint and project checks before writing. Fix rejected patches in their owner. Intentional settings, project guards and builders use the configuration unit; mandatory ADS gates still run." : "Source mutation tools are disabled; source edits use the client's editor/filesystem tools."}`,
+    instructions: `${serverInstructions} ${mutations ? "Guarded editing is enabled: discover one owner with ads_units, read relevant ranges with ads_read_file and send only a Git unified diff to ads_apply_patch with that unit ID. Include its own scenarios/fixtures and required re-exports together, never unrelated units. Token manifests list companionFiles for canonical foundation import changes required by token files created/deleted in the same patch. The server validates architecture, registered Oxlint and project checks before writing. Fix rejected patches in their owner. Intentional settings, project guards and builders use the configuration unit; mandatory ADS gates still run." : "Source mutation tools are disabled; source edits use the client's editor/filesystem tools."}`,
     capabilities: { tools: { listChanged: true }, resources: { listChanged: true, subscribe: true }, prompts: {},
       extensions: { "io.modelcontextprotocol/ui": { mimeTypes: [APP_MIME] }, ...(era === "modern" ? { [SKILLS_EXTENSION]: { directoryRead: true } } : {}) } },
   });
   const getRegistry = () => cache.registry ??= inspectScenarios(options);
-  const scenarioApps = () => getRegistry().scenarios.map(item => ({ id: item.id, title: item.title, kind: item.kind, file: item.artifact }));
+  const scenarioApps = () => getRegistry().scenarios.map(item => ({ id: item.id, title: item.title, kind: item.kind, ...(item.samples ? { samples: item.samples } : {}), file: item.artifact }));
   const tokenScenarios = () => getRegistry().scenarios.filter(item => item.kind === "tokens").map(item => ({ id: item.id, title: item.title, count: item.tokens.length }));
   const allApps = () => [...options.config.mcp.apps, ...scenarioApps()];
   const scenarioWidget = () => options.config.mcp.previewManifest ? PREVIEW_APP_URI : SCENARIO_APP_URI;
@@ -214,12 +214,12 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         }
         return json({ widget: { resourceUri: TOKENS_APP_URI }, category: null, tokenCount: inspectTokens(root).tokens.length, dataUri: `${PROJECT_URI}/tokens`, showcaseUrl: getShowcaseUrl() });
       } },
-      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; composition; tokens; foundation shared files; documentation; assets/brand, assets/fonts and asset groups; configuration with ds.config.json, package/build/lint configuration and registered project guard/compiler sources. List summaries with query, or pass an exact unit ID for its manifest. Imported peers stay separate. New owners follow the existing colocation convention.", schema: query.extend({ unit: z.string().min(1).max(256).optional() }), call: ({ unit, query: search = "", limit }) => {
+      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; composition; tokens; foundation shared files; documentation; assets/brand, assets/fonts and asset groups; configuration with ds.config.json, package/build/lint configuration and registered project guard/compiler sources. List summaries with query, or pass an exact unit ID for its manifest. Token manifests include companionFiles with the foundation entry path and allowed import changes. Imported peers stay separate. New owners follow the existing colocation convention.", schema: query.extend({ unit: z.string().min(1).max(256).optional() }), call: ({ unit, query: search = "", limit }) => {
         const matches = edits.units().filter(item => unit ? item.id === unit : item.id.toLowerCase().includes(search.toLowerCase()));
-        return json({ total: matches.length, units: matches.slice(0, limit).map(item => ({ id: item.id, kind: item.kind, fileCount: item.files.length, ...(unit ? { files: item.files.slice(0, 200), filesTruncated: item.files.length > 200 } : {}) })) });
+        return json({ total: matches.length, units: matches.slice(0, limit).map(item => ({ id: item.id, kind: item.kind, fileCount: item.files.length, ...(unit ? { files: item.files.slice(0, 200), filesTruncated: item.files.length > 200, ...(item.companionFiles ? { companionFiles: item.companionFiles } : {}) } : {}) })) });
       } },
       { name: "ads_read_file", description: "Read a bounded range of ADS or registered configuration/extension source. Returns unit, full-file digest, startLine and nextOffset; default/max is 12000 UTF-16 characters. Binary assets return byte count/digest and no encoded content. Paths come from ads_units or discovery. Missing new paths return digest null. Read only relevant context before preparing a Git patch.", schema: z.object({ path: z.string().min(1).max(500), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(mutationLimits.readChars).default(mutationLimits.readChars) }).strict(), call: ({ path: file, ...range }) => json(edits.read(file, range)) },
-      ...(mutations ? [{ name: "ads_apply_patch", description: "Apply one Git diff to one ADS unit from ads_units. Pass exactly one of patch (inline) or patchFile (a regular .patch/.diff under .ds/patches/, for large/binary diffs without model-context bytes). Text uses --- a/path, +++ b/path and exact @@ hunks; /dev/null creates/deletes. Git binary patches require git diff --binary --full-index and installed Git. A unit owns its implementation, previews and fixtures; imported peers are separate. Foundation, documentation, assets and configuration are editable too. Configuration changes may register/edit project guards and builders; the proposed schema, mandatory core/Oxlint and candidate project checks must pass. Only selected-unit public re-exports may change. Set dryRun true to validate without writing. Fix rejected patches and inspect current previews after acceptance.",
+      ...(mutations ? [{ name: "ads_apply_patch", description: "Apply one Git diff to one ADS unit from ads_units. Pass exactly one of patch (inline) or patchFile (a regular .patch/.diff under .ds/patches/, for large/binary diffs without model-context bytes). Text uses --- a/path, +++ b/path and exact @@ hunks; /dev/null creates/deletes. Git binary patches require git diff --binary --full-index and installed Git. A unit owns its implementation, previews and fixtures; imported peers are separate. Foundation, documentation, assets and configuration are editable too. Configuration changes may register/edit project guards and builders; the proposed schema, mandatory core/Oxlint and candidate project checks must pass. Only selected-unit public re-exports may change; preserve unrelated statements including export {};. A tokens patch may include its companionFiles foundation entry only to add/remove canonical imports required by token files created/deleted in this patch, preserving other imports/comments and canonical order. Set dryRun true to validate without writing. Fix rejected patches and inspect current previews after acceptance.",
         schema: z.object({ unit: z.string().min(1).max(256), dryRun: z.boolean(), patch: z.string().min(1).max(mutationLimits.patchBytes).optional(), patchFile: z.string().min(1).max(500).optional() }).strict().refine(args => (args.patch !== undefined) !== (args.patchFile !== undefined), "Provide exactly one of patch or patchFile."),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }, _meta: { ui: { visibility: ["model"] } },
         call: async (args, signal) => {

package/dist/preview-resources.mjs

@@ -113,7 +113,7 @@ export function createPreviewResources(output, options, entries) {
   const scenarios = entries.map((entry, index) => {
     const chunk = bundle.find(item => item.type === "chunk" && item.facadeModuleId === `\0ads-preview-entry:${index}`);
     if (!chunk) throw new Error(`Missing compiled scenario entry: ${entry.id}`);
-    return { id: entry.id, title: entry.title, kind: entry.kind, module: uris.get(chunk.fileName) };
+    return { id: entry.id, title: entry.title, kind: entry.kind, ...(entry.samples ? { samples: entry.samples } : {}), module: uris.get(chunk.fileName) };
   });
   const graph = { schemaVersion: 1, framework: options.config.framework, assets: records, scenarios };
   const revision = hash(JSON.stringify(graph));

package/dist/scenarios.mjs

@@ -6,6 +6,7 @@ import { isDevelopmentFile, isInside, isScenarioFile, sourceFiles } from "./conf
 import { projectCompilerOptions } from "./boundaries.mjs";
 import { inspectTokens } from "./tokens.mjs";
 import { isSharedToken } from "./token-policy.mjs";
+import { validTokenSamples } from "./token-samples.mjs";
 
 export const scenarioArtifact = (root, id) => path.join(root, ".ds/scenarios", id, "index.html");
 
@@ -104,12 +105,16 @@ export function inspectScenarios(options, suppliedProgram) {
     }
     const fixtureBase = path.basename(file).startsWith("Scenario.") ? path.join(path.dirname(file), "fixture") : file.replace(/\.scenario\.[^.]+$/, ".fixture");
     if (![".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].some(extension => existsSync(fixtureBase + extension))) report(file, "Keep this scenario's inputs beside it: fixture.ts (directory entry) or <Owner>.fixture.ts (flat entry). An empty fixture is valid for a component without inputs.");
-    if (!metadata || Object.keys(metadata).some((key) => !["title", "covers", "tokens"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || kind !== "tokens" && !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable) || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--"))) || kind === "tokens" && !metadata.tokens?.length) {
-      report(file, "Export static scenario metadata: { title: string, covers: [public UI names], tokens?: [token names] }. Token scenarios need tokens; their covers may be empty. Literal const fixture lists are supported; runtime expressions are not."); continue;
+    if (!metadata || Object.keys(metadata).some((key) => !["title", "covers", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
+      || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--")))
+      || kind === "tokens" && (Object.hasOwn(metadata, "tokens") || !validTokenSamples(metadata.samples) || !metadata.covers.some(name => known.get(name)?.kind === "patterns"))
+      || Object.hasOwn(metadata, "samples") && !validTokenSamples(metadata.samples)) {
+      report(file, "Export static metadata with nonempty covers. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
     }
     if (!["composition", "tokens"].includes(kind) && metadata.covers.some((name) => known.get(name).kind !== kind)) report(file, "Component scenarios cover primitives; pattern scenarios cover patterns. Use composition/ for larger interfaces.");
-    for (const name of metadata.tokens ?? []) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real foundation token.` });
-    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], tokens: [...new Set(metadata.tokens ?? [])], file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    const tokens = [...new Set([...(metadata.tokens ?? []), ...(metadata.samples ?? []).map(sample => sample.token)])];
+    for (const name of tokens) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real foundation token.` });
+    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }
@@ -161,6 +166,7 @@ export function inspectScenarioCoverage(options, program, report) {
     const source = program.getSourceFile(path.join(options.root, scenario.file));
     const rendered = new Set();
     const referencedTokens = new Set();
+    let samplesPassed = false;
     const visited = new Set();
     function visit(node, reached = false) {
       if (!node || visited.has(node)) return;
@@ -175,6 +181,10 @@ export function inspectScenarioCoverage(options, program, report) {
         const symbol = canonical(symbolOf(expression));
         const names = identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]);
         for (const name of names ?? []) rendered.add(name);
+        if (scenario.kind === "tokens" && [...names ?? []].some(name => scenario.covers.includes(name))) {
+          const attributes = ts.isCallExpression(node) ? literal(node.arguments[1], checker) : Object.assign({}, ...node.attributes.properties.map(attribute => ts.isJsxSpreadAttribute(attribute) ? literal(attribute.expression, checker) : ts.isJsxAttribute(attribute) && ts.isIdentifier(attribute.name) && attribute.initializer && ts.isJsxExpression(attribute.initializer) ? { [attribute.name.text]: literal(attribute.initializer.expression, checker) } : {}));
+          if (JSON.stringify(attributes?.samples) === JSON.stringify(scenario.samples)) samplesPassed = true;
+        }
       }
       // Follow local adapters reachable from the default entry. Unused example
       // functions do not satisfy coverage; production implementations are never
@@ -192,9 +202,10 @@ export function inspectScenarioCoverage(options, program, report) {
       else covered.add(name);
     }
     for (const name of referencedTokens) if (!declaredTokens.has(name)) report(source.fileName, "token-scenario-reference", `Reachable scenario input references undeclared token ${name}.`);
+    if (scenario.kind === "tokens" && !samplesPassed) report(source.fileName, "token-scenario-render", "Pass the declared fixture.samples into a rendered public review pattern's samples prop. Printing token names or reading unused fixtures is not sample coverage.");
     for (const name of scenario.tokens) {
       if (!referencedTokens.has(name)) report(source.fileName, "token-scenario-render", `${name} is declared in tokens but has no reachable reference from the default scenario entry. Consume the real token fixture; metadata alone does not count.`);
-      else if (declaredTokens.has(name)) coveredTokens.add(name);
+      else if (scenario.kind === "tokens" && samplesPassed && declaredTokens.has(name)) coveredTokens.add(name);
     }
   }
   for (const item of ui.filter((item) => item.renderable && !covered.has(item.name))) report(item.file, "scenario-coverage", `Public UI ${item.name} needs a colocated, registered scenario render reference. Related parts may share a scenario.`);

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

@@ -22,9 +22,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
@@ -209,15 +215,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-assimilate/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-break-ui/SKILL.md

@@ -25,9 +25,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
@@ -161,15 +167,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-break-ui/references/verification.md

@@ -22,6 +22,10 @@ Select checks that match the item:
   touch/scroll interaction, and reduced motion for animated controls.
 
 Use an isolated browser context. Preserve the user's open pages and settings.
+The showcase keeps a notification stream open. Wait for document loading and the
+selected App's ready/error state; `networkidle` is not a readiness condition.
+For tall previews, scroll the App document to its last example and verify it is
+reachable without the host shell scrolling or clipping the preview.
 Capture the fixture, viewport/container size, theme, zoom, and actions alongside
 each failure. CSS viewport emulation is useful; it is not evidence of real
 mobile keyboard, browser chrome, or assistive-technology behavior.

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

@@ -57,9 +57,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
@@ -92,8 +98,8 @@ checks; do not fetch the unpublished package.
 
 Read [assets/bootstrap-ds/README.md](assets/bootstrap-ds/README.md) and its
 [contract](assets/bootstrap-ds/ADS.md). The scaffold contains semantic token
-defaults, React/TypeScript/Linaria configuration, general lint, an empty public
-barrel, empty component/pattern directories, and a project preview compiler adapter. The browser shell is supplied by ADS tooling.
+defaults, React/TypeScript/Linaria configuration, general lint, a public
+barrel, empty product component directories, a project-owned token review pattern, and a project preview compiler adapter. The browser shell is supplied by ADS tooling.
 It contains no components, shell patterns, vendored fonts, or example screens.
 
 Resolve assets relative to this skill's `SKILL.md`, including after installation
@@ -299,15 +305,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-designer/assets/bootstrap-ds/ADS.md

@@ -114,13 +114,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

package/dist/skills/ads-designer/assets/bootstrap-ds/README.md

@@ -1,8 +1,8 @@
 # Empty native design system
 
-This private React/TypeScript workspace contains semantic CSS tokens, an empty
-public barrel, Linaria extraction and a project preview compiler adapter. It has
-no components, patterns, icons, fonts or example screens. The minimal showcase
+This private React/TypeScript workspace contains semantic CSS tokens, a project-owned
+token review pattern, a public barrel, Linaria extraction and a preview compiler
+adapter. It has no product components, icons, fonts or example screens. The minimal showcase
 shell and MCP client come from ADS tooling.
 
 Read the local [contract](ADS.md) and the
@@ -13,7 +13,7 @@ Read the local [contract](ADS.md) and the
 Copy the contents of `bootstrap-ds/`, including dotfiles, into a new project.
 The installed `ads-designer` skill contains the same files in
 `assets/bootstrap-ds/`. Set the project name in `package.json`. Use Node 22.12 or
-newer and ADS 0.3 or later for the shared-resource preview compiler.
+newer and ADS 0.3.1 or later for the shared-resource preview compiler.
 
 ```sh
 npx @reqvire-org/ads init --framework react
@@ -25,7 +25,7 @@ npm run dev:showcase
 For unreleased tooling, run init using the real local package:
 
 ```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 init --framework react --tool-package "$ads_tool_package"
 npm install
 npm run build
@@ -44,7 +44,7 @@ native Preact app without a saved ADS framework, use `ads init --framework preac
 Init records that choice and generates native hook imports without migrating the
 app or rewriting its compiler. Subsequent init runs reuse the saved choice.
 Init adds missing foundation files and connects architectural checks; it does
-not configure Linaria or generate component source. Generated `.ds/` files are
+not configure Linaria or generate product component source. Generated `.ds/` files are
 ignored; original artwork and provenance belong in `assets/brand/`.
 
 ## Inspect and add UI
@@ -56,10 +56,12 @@ Its MCP client discovers entries, invokes preview tools and follows notification
 There are no required TokensPage/ComponentsPage/PatternsPage/CompositionPage
 files, and no separate project browser app to implement or rebuild.
 
-The existing `tokens/Foundation.scenario.tsx` and colocated fixture inspect all
-starter token values. Add/remove fixture names alongside token definitions;
-`ads check` rejects missing coverage and invented names. Styled token samples
-belong to your public review patterns and mount through the same scenario pipeline.
+The existing `tokens/Foundation.scenario.tsx` and colocated fixture visually demonstrate all
+starter token values. The fixture owns `{ token, property, probe }` bindings;
+the public `TokenPreview` pattern owns their presentation and applies the real CSS
+variables. Add/remove samples alongside token definitions. `ads check` rejects
+missing coverage and invented names; the App verifies the declared CSS bindings
+in the browser. Extend or replace the project-owned pattern as your tokens evolve.
 
 Create a component under `design-system/components/`, export it through `@ds`,
 and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/index.ts

@@ -2,4 +2,4 @@
 import "./styles.css";
 
 // Add public component and pattern exports here as they are implemented.
-export {};
+export { TokenPreview } from "./patterns/token-preview/TokenPreview";

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx

@@ -0,0 +1,4 @@
+import { TokenPreview } from "@ds";
+import { fixture } from "./fixture";
+export const scenario = { title: fixture.title, covers: ["TokenPreview"] };
+export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/TokenPreview.tsx

@@ -0,0 +1,31 @@
+import { useLayoutEffect, useRef } from "react";
+import { css, cx } from "@linaria/atomic";
+
+export interface TokenSample { token: `--${string}`; property: string; }
+export interface TokenPreviewProps { title: string; samples: readonly TokenSample[]; text: string; }
+const sampleStyle = css`
+  display: inline-block;
+  position: relative;
+  white-space: pre-line;
+  &[data-ads-property="animation-duration"] { animation-duration: var(--ux-token-preview-value); }
+  &[data-ads-property="animation-timing-function"] { animation-timing-function: var(--ux-token-preview-value); }
+  &[data-ads-property="background-color"] { background-color: var(--ux-token-preview-value); }
+  &[data-ads-property="border-radius"] { border-radius: var(--ux-token-preview-value); }
+  &[data-ads-property="box-shadow"] { box-shadow: var(--ux-token-preview-value); }
+  &[data-ads-property="color"] { color: var(--ux-token-preview-value); }
+  &[data-ads-property="font-family"] { font-family: var(--ux-token-preview-value); }
+  &[data-ads-property="font-size"] { font-size: var(--ux-token-preview-value); }
+  &[data-ads-property="font-weight"] { font-weight: var(--ux-token-preview-value); }
+  &[data-ads-property="line-height"] { line-height: var(--ux-token-preview-value); }
+  &[data-ads-property="width"] { width: var(--ux-token-preview-value); }
+  &[data-ads-property="z-index"] { z-index: var(--ux-token-preview-value); }
+`;
+function Sample({ sample, text }: { sample: TokenSample; text: string }) {
+  const ref = useRef<HTMLSpanElement>(null);
+  useLayoutEffect(() => { ref.current?.style.setProperty("--ux-token-preview-value", `var(${sample.token})`); }, [sample.token]);
+  return <span ref={ref} className={cx("ux-token-preview__sample", sampleStyle)} data-ads-token={sample.token} data-ads-property={sample.property}>{text}</span>;
+}
+/** Project-owned review UI. Values always come from the real foundation CSS. */
+export function TokenPreview({ title, samples, text }: TokenPreviewProps) {
+  return <section className="ux-token-preview"><h1>{title}</h1>{samples.map(sample => <div key={`${sample.token}:${sample.property}`} className="ux-token-preview__item"><code className="ux-token-preview__name">{sample.token}</code><Sample sample={sample} text={text}/></div>)}</section>;
+}

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/fixture.ts

@@ -0,0 +1,8 @@
+export const fixture = {
+  "title": "Token preview",
+  "text": "Aa",
+  samples: [
+    {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--space-4", "property": "width", "probe": "13.375px"},
+  ]
+} as const;