@reqvire-org/ads 0.3.0 → 0.3.2

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-compiler.mjs

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import path from "node:path";
 import { loadConfig, isInside } from "./config.mjs";
 import { inspectScenarios } from "./scenarios.mjs";
@@ -71,7 +71,7 @@ export function createPreviewCache(options, compilerFiles = []) {
   }
   return { inputs, reusable, validated: stamp => value.validation === stamp,
     assertCompiler() {
-      if (adapterDigest() !== loadedAdapter) throw new Error("Preview compiler code or dependencies changed. Restart ADS MCP/showcase to load the updated compiler before reviewing previews.");
+      if (adapterDigest() !== loadedAdapter) throw Object.assign(new Error("Preview compiler code or dependencies changed. Invoke the preview again to restart the builder and load current code."), { code: "ADS_PREVIEW_RESTART" });
     },
     validate(stamp) { value.validation = stamp; save(); },
     record(entry, dependencies) {
@@ -93,12 +93,17 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   function registry() {
     options = loadConfig(root);
     const result = inspectScenarios(options);
-    if (result.diagnostics.length) throw new Error(result.diagnostics.map(item => `${item.file}: ${item.message}`).join("\n"));
+    if (result.diagnostics.length) throw Object.assign(new Error(result.diagnostics.map(item => `${item.file}: ${item.message}`).join("\n")), { scenarios: result.scenarios });
     mkdirSync(path.join(root, ".ds/scenarios"), { recursive: true });
     writeFileSync(path.join(root, ".ds/scenarios/manifest.json"), JSON.stringify({ schemaVersion: 1, scenarios: result.scenarios }, null, 2));
     return result.scenarios;
   }
-  let entries = registry();
+  let entries = [], registryFailure;
+  try { entries = registry(); }
+  catch (error) {
+    if (!watched) throw error;
+    registryFailure = error; entries = error.scenarios ?? [];
+  }
   const reporter = createBuildReporter(root, { apps: entries.map(entry => ({ id: entry.id, file: entry.artifact })) });
   const requested = new Set();
   const pending = new Set();
@@ -108,6 +113,12 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   let generation = 0;
   let publishedStamp;
   let validation;
+  function failure(error) {
+    try { reporter.failure(error); } catch (reportError) { console.error(reportError); }
+    console.error(error);
+    if (!watched) process.exitCode = 1;
+  }
+  if (registryFailure) failure(registryFailure);
   function gate(stamp) {
     if (cache.validated(stamp)) return Promise.resolve();
     return validation ??= Promise.resolve().then(validate).then(() => {
@@ -119,8 +130,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     if (buildGraph) return compileGraph();
     const revision = reporter.begin(entry.id);
     const started = generation;
-    const stamp = cache.inputs();
     try {
+      const stamp = cache.inputs();
       cache.assertCompiler();
       const reuse = cache.reusable(entry);
       const dependencies = new Set();
@@ -147,7 +158,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
       cache.assertCompiler();
-      if (started !== generation || stamp !== cache.inputs()) return; // Watch queued a newer revision.
+      if (stopped || started !== generation || stamp !== cache.inputs()) return; // Watch queued a newer revision.
       if (!reuse) cache.record(entry, dependencies);
       reporter.ready(entry.id, revision);
     } catch (error) {
@@ -160,24 +171,24 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   async function compileGraph() {
     const revisions = new Map(entries.map(entry => [entry.id, reporter.begin(entry.id)]));
     const started = generation;
-    const stamp = cache.inputs();
-    const dependencies = new Set();
-    function assets(directory) {
-      for (const item of readdirSync(directory, { withFileTypes: true })) {
-        if (item.isSymbolicLink() || ["node_modules", ".ds", ".vite", "dist"].includes(item.name)) continue;
-        const file = path.join(directory, item.name);
-        if (item.isDirectory()) assets(file);
-        else if (/\.(?:css|svg|png|jpe?g|webp|gif|woff2?|ttf|otf)$/.test(file)) dependencies.add(file);
-      }
-    }
-    assets(options.dsRoot);
-    const track = { name: "ads-preview-graph-dependencies", generateBundle() {
-      for (const id of this.getModuleIds()) {
-        const file = id.split("?")[0];
-        if (path.isAbsolute(file) && existsSync(file)) dependencies.add(file);
-      }
-    } };
     try {
+      const stamp = cache.inputs();
+      const dependencies = new Set();
+      function assets(directory) {
+        for (const item of readdirSync(directory, { withFileTypes: true })) {
+          if (item.isSymbolicLink() || ["node_modules", ".ds", ".vite", "dist"].includes(item.name)) continue;
+          const file = path.join(directory, item.name);
+          if (item.isDirectory()) assets(file);
+          else if (/\.(?:css|svg|png|jpe?g|webp|gif|woff2?|ttf|otf)$/.test(file)) dependencies.add(file);
+        }
+      }
+      assets(options.dsRoot);
+      const track = { name: "ads-preview-graph-dependencies", generateBundle() {
+        for (const id of this.getModuleIds()) {
+          const file = id.split("?")[0];
+          if (path.isAbsolute(file) && existsSync(file)) dependencies.add(file);
+        }
+      } };
       cache.assertCompiler();
       let reusable = entries.every(entry => cache.reusable(entry));
       if (reusable) { try { reusable = Boolean(readPreviewManifest(options, { verify: true })); } catch { reusable = false; } }
@@ -185,7 +196,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
       cache.assertCompiler();
-      if (started !== generation || stamp !== cache.inputs()) return;
+      if (stopped || started !== generation || stamp !== cache.inputs()) return;
       const publication = outcomes[1].value;
       if (publication) {
         publication.publish(reporter.session);
@@ -209,15 +220,16 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     if (compiling) return;
     compiling = true;
     try {
-      while (pending.size && !stopped) {
+      while (pending.size && !registryFailure && !stopped) {
         const id = pending.has(active) ? active : pending.values().next().value;
         pending.delete(id);
         const entry = entries.find(entry => entry.id === id);
         if (entry) await compile(entry);
       }
-    } finally { compiling = false; }
+    } catch (error) { failure(error); }
+    finally { compiling = false; }
   }
-  function request() {
+  function request(startBuild = true) {
     const file = process.env.ADS_MCP_REQUEST_FILE;
     if (!file || !existsSync(file)) return;
     try {
@@ -231,8 +243,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
           if (!buildGraph || publishedStamp !== cache.inputs()) pending.add(entry.id);
         }
       }
-      void drain();
-    } catch (error) { console.error(`Preview requests: ${error.message}`); }
+      if (startBuild) void drain();
+    } catch (error) { failure(error); }
   }
   if (!watched) {
     for (const entry of entries) pending.add(entry.id);
@@ -241,8 +253,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   }
   let timer;
   const changed = new Set();
-  function sourceChanged(_event, file) {
-    if (!file || !/\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) return;
+  function sourceChanged(_event, file, topology = false) {
+    if (!file || !topology && !/\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) return;
     const absolute = path.join(root, file);
     if (file.split(path.sep).some(name => ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(name)) || options.config.assets.generatedPaths.some(base => isInside(path.resolve(root, base), absolute))) return;
     changed.add(absolute);
@@ -253,7 +265,10 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const changes = [...changed]; changed.clear();
       try {
         entries = registry();
+        registryFailure = undefined;
         reporter.setApps(entries.map(entry => ({ id: entry.id, file: entry.artifact })));
+        reporter.clearFailure();
+        request(false);
         for (const id of requested) if (!entries.some(entry => entry.id === id)) { requested.delete(id); pending.delete(id); }
         // Every source change needs validation; unaffected artifacts need no
         // compilation. Check active first, then rebuild only changed dependencies.
@@ -263,25 +278,53 @@ export async function runScenarioCompiler(directory, { watched = false, validate
         }
         if (changes.length) void drain();
       } catch (error) {
-        for (const id of requested) { const revision = reporter.begin(id); reporter.error(id, revision, error); }
-        console.error(error);
+        registryFailure = error; failure(error);
       }
     }, 100);
   }
   // Do not allocate recursive OS watches for node_modules or generated trees.
-  const watchers = [watch(root, sourceChanged)];
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    const directory = path.join(root, entry.name);
-    if (!entry.isDirectory() || entry.isSymbolicLink() || ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(entry.name)
-      || options.config.assets.generatedPaths.some(base => isInside(path.resolve(root, base), directory))) continue;
-    watchers.push(watch(directory, { recursive: true }, (event, file) => sourceChanged(event, file && path.join(entry.name, file))));
+  const watchers = new Map();
+  function addWatch(directory, callback, recursive = false) {
+    if (stopped) return false;
+    try {
+      const stat = statSync(directory), identity = `${stat.dev}:${stat.ino}`;
+      if (watchers.get(directory)?.identity === identity) return false;
+      watchers.get(directory)?.watcher.close();
+      const watcher = watch(directory, { recursive }, callback);
+      watchers.set(directory, { watcher, identity });
+      watcher.on("error", error => {
+        watcher.close();
+        if (watchers.get(directory)?.watcher === watcher) watchers.delete(directory);
+        failure(error);
+      });
+      return true;
+    } catch (error) { failure(error); }
   }
-  const requestWatch = watch(path.join(root, ".ds"), (_event, file) => {
-    if (file === path.basename(process.env.ADS_MCP_REQUEST_FILE ?? "")) request();
-  });
+  function reconcileWatches(initial = false) {
+    if (stopped) return;
+    try {
+      addWatch(root, sourceChanged);
+      const wanted = new Set([root, path.join(root, ".ds")]);
+      for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const directory = path.join(root, entry.name);
+        if (!entry.isDirectory() || entry.isSymbolicLink() || ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(entry.name)
+          || options.config.assets.generatedPaths.some(base => isInside(path.resolve(root, base), directory))) continue;
+        wanted.add(directory);
+        if (addWatch(directory, (event, file) => sourceChanged(event, file && path.join(entry.name, file)), true) && !initial) sourceChanged("rename", entry.name, true);
+      }
+      mkdirSync(path.join(root, ".ds"), { recursive: true });
+      addWatch(path.join(root, ".ds"), (_event, file) => { if (file === path.basename(process.env.ADS_MCP_REQUEST_FILE ?? "")) request(); });
+      for (const [directory, { watcher }] of watchers) if (!wanted.has(directory) || !existsSync(directory)) {
+        watcher.close(); watchers.delete(directory);
+        if (!initial && directory !== root && directory !== path.join(root, ".ds")) sourceChanged("rename", path.relative(root, directory), true);
+      }
+    } catch (error) { failure(error); }
+  }
+  reconcileWatches(true);
+  const reconcileTimer = setInterval(reconcileWatches, 1000);
   request();
   console.log(`Scenario compiler ready: ${entries.length} entries; builds are requested on demand.`);
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => {
-    stopped = true; clearTimeout(timer); for (const watcher of watchers) watcher.close(); requestWatch.close();
+    stopped = true; clearTimeout(timer); clearInterval(reconcileTimer); for (const { watcher } of watchers.values()) watcher.close();
   });
 }

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
@@ -235,6 +251,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/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.2.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,8 @@ 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.2 or later for the closed foundation contract and recoverable
+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
@@ -187,6 +203,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/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.