@reqvire-org/ads 0.0.0-stage → 0.3.0

package/dist/scenarios-compiler.mjs

@@ -0,0 +1,287 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
+import path from "node:path";
+import { loadConfig, isInside } from "./config.mjs";
+import { inspectScenarios } from "./scenarios.mjs";
+import { artifactDigest, createBuildReporter } from "./mcp/build-status.mjs";
+import { readPreviewManifest } from "./preview-resources.mjs";
+
+const digest = value => createHash("sha256").update(value).digest("hex");
+const fileDigest = file => { try { return digest(readFileSync(file)); } catch { return null; } };
+
+/** Cache only successful validation + matching source/dependency/output content.
+ * Cache state is development output, never proof that a failed build is current. */
+export function createPreviewCache(options, compilerFiles = []) {
+  const { root, config } = options;
+  const adapterFiles = [import.meta.filename, path.join(import.meta.dirname, "preview-resources.mjs"), path.join(import.meta.dirname, "scenarios-vite.mjs"), ...compilerFiles,
+    ...["package.json", "package-lock.json", "bun.lock", "bun.lockb", "node_modules/.package-lock.json"].map(file => path.join(root, file))];
+  const adapterDigest = () => digest(JSON.stringify(adapterFiles.map(file => [file, fileDigest(file)])));
+  const loadedAdapter = adapterDigest();
+  const target = path.join(root, ".ds/preview-cache.json");
+  let value = { schemaVersion: 1, validation: null, entries: {} };
+  try {
+    if (realpathSync(target) === target) {
+      const stored = JSON.parse(readFileSync(target, "utf8"));
+      if (stored.schemaVersion === 1 && stored.entries && typeof stored.entries === "object") value = stored;
+    }
+  } catch { /* Missing or corrupt cache means validate and rebuild. */ }
+  function inputs() {
+    const rows = [];
+    const generated = config.assets.generatedPaths.map(file => path.resolve(root, file));
+    function visit(directory) {
+      for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (entry.isSymbolicLink() || ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(entry.name)) continue;
+        const file = path.join(directory, entry.name);
+        if (generated.some(base => isInside(base, file))) continue;
+        if (entry.isDirectory()) visit(file);
+        else if (entry.isFile() && /\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) rows.push([path.relative(root, file), fileDigest(file)]);
+      }
+    }
+    visit(root);
+    rows.push(["installed-packages", fileDigest(path.join(root, "node_modules/.package-lock.json"))]);
+    rows.push(["node-runtime", `${process.version}/${process.platform}/${process.arch}`]);
+    for (const file of compilerFiles) rows.push([file, fileDigest(file)]);
+    // Tool upgrades invalidate validation even when the project's lockfile is unchanged.
+    for (const name of readdirSync(import.meta.dirname).filter(name => name.endsWith(".mjs"))) {
+      rows.push([`ads-tool/${name}`, fileDigest(path.join(import.meta.dirname, name))]);
+    }
+    return digest(JSON.stringify(rows.sort((a, b) => a[0].localeCompare(b[0]))));
+  }
+  function save() {
+    mkdirSync(path.dirname(target), { recursive: true });
+    if (realpathSync(path.dirname(target)) !== path.dirname(target)) throw new Error("Preview cache cannot resolve through a symlink.");
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try { writeFileSync(temporary, JSON.stringify(value)); renameSync(temporary, target); }
+    finally { rmSync(temporary, { force: true }); }
+  }
+  const compilerDigest = () => digest(JSON.stringify([
+    ["adapter", adapterDigest()],
+    ...compilerFiles.map(file => [file, fileDigest(file)]),
+    ...readdirSync(root).filter(name => !/^(?:biome|oxlint|\.oxlint)/.test(name) && (/\.(?:json|lock|lockb)$/.test(name) || /^(?:vite|babel)\.config\./.test(name))).map(name => [name, fileDigest(path.join(root, name))]),
+    ["installed-packages", fileDigest(path.join(root, "node_modules/.package-lock.json"))],
+    ["scheduler", fileDigest(import.meta.filename)],
+    ["node-runtime", `${process.version}/${process.platform}/${process.arch}`],
+  ]));
+  function reusable(entry) {
+    const cached = value.entries[entry.id];
+    if (!cached || cached.metadata !== JSON.stringify(entry) || cached.compiler !== compilerDigest()) return false;
+    if (!cached.dependencies || !Object.keys(cached.dependencies).length) return false;
+    if (Object.entries(cached.dependencies).some(([file, hash]) => fileDigest(path.resolve(root, file)) !== hash)) return false;
+    try { return cached.artifact === artifactDigest(path.join(root, entry.artifact)); } catch { return false; }
+  }
+  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.");
+    },
+    validate(stamp) { value.validation = stamp; save(); },
+    record(entry, dependencies) {
+      value.entries[entry.id] = { metadata: JSON.stringify(entry), compiler: compilerDigest(),
+        dependencies: Object.fromEntries([...new Set([path.join(root, entry.file), ...dependencies])]
+          .filter(file => isInside(root, file) && !file.includes(`${path.sep}node_modules${path.sep}`)).map(file => [path.relative(root, file), fileDigest(file)])),
+        artifact: artifactDigest(path.join(root, entry.artifact)) };
+      save();
+    },
+  };
+}
+
+/** Shared scheduling and cache; the project supplies its own React/Preact build. */
+export async function runScenarioCompiler(directory, { watched = false, validate, build, buildGraph, compilerFiles = [] }) {
+  const root = path.resolve(directory);
+  let options = loadConfig(root);
+  if (buildGraph && (!options.config.mcp.previewManifest || !options.config.framework)) throw new Error("Resource preview builds require an explicit framework and mcp.previewManifest in ds.config.json.");
+  const cache = createPreviewCache(options, compilerFiles);
+  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"));
+    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();
+  const reporter = createBuildReporter(root, { apps: entries.map(entry => ({ id: entry.id, file: entry.artifact })) });
+  const requested = new Set();
+  const pending = new Set();
+  let active;
+  let compiling = false;
+  let stopped = false;
+  let generation = 0;
+  let publishedStamp;
+  let validation;
+  function gate(stamp) {
+    if (cache.validated(stamp)) return Promise.resolve();
+    return validation ??= Promise.resolve().then(validate).then(() => {
+      if (stamp !== cache.inputs()) throw new Error("Sources changed during preview validation. Waiting for the current build.");
+      cache.validate(stamp);
+    });
+  }
+  async function compile(entry) {
+    if (buildGraph) return compileGraph();
+    const revision = reporter.begin(entry.id);
+    const started = generation;
+    const stamp = cache.inputs();
+    try {
+      cache.assertCompiler();
+      const reuse = cache.reusable(entry);
+      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);
+        }
+      }
+      // CSS url() inputs may be inlined without becoming Rollup JS modules.
+      // Shared foundation/styles/assets conservatively invalidate all previews.
+      assets(options.dsRoot);
+      const track = { name: "ads-preview-dependencies", generateBundle() {
+        // Include modules used during extraction, even when their final JS was
+        // tree-shaken. A stylesheet evaluation can depend on those exports.
+        for (const id of this.getModuleIds()) {
+          const file = id.split("?")[0];
+          if (path.isAbsolute(file) && existsSync(file)) dependencies.add(file);
+        }
+      } };
+      const outcomes = await Promise.allSettled([gate(stamp), reuse ? Promise.resolve() : build(entry, options, track)]);
+      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 (!reuse) cache.record(entry, dependencies);
+      reporter.ready(entry.id, revision);
+    } catch (error) {
+      if (started !== generation) return;
+      reporter.error(entry.id, revision, error);
+      console.error(error);
+      if (!watched) process.exitCode = 1;
+    }
+  }
+  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 {
+      cache.assertCompiler();
+      let reusable = entries.every(entry => cache.reusable(entry));
+      if (reusable) { try { reusable = Boolean(readPreviewManifest(options, { verify: true })); } catch { reusable = false; } }
+      const outcomes = await Promise.allSettled([gate(stamp), reusable ? Promise.resolve(null) : buildGraph(entries, options, track)]);
+      const failure = outcomes.find(outcome => outcome.status === "rejected");
+      if (failure) throw failure.reason;
+      cache.assertCompiler();
+      if (started !== generation || stamp !== cache.inputs()) return;
+      const publication = outcomes[1].value;
+      if (publication) {
+        publication.publish(reporter.session);
+        for (const entry of entries) cache.record(entry, [...dependencies, ...publication.assetFiles]);
+      } else {
+        const file = path.join(root, options.config.mcp.previewManifest);
+        const manifest = readPreviewManifest(options);
+        writeFileSync(`${file}.tmp`, JSON.stringify({ ...manifest, session: reporter.session }));
+        renameSync(`${file}.tmp`, file);
+      }
+      for (const entry of entries) { pending.delete(entry.id); reporter.ready(entry.id, revisions.get(entry.id)); }
+      publishedStamp = stamp;
+    } catch (error) {
+      if (started !== generation) return;
+      for (const entry of entries) { pending.delete(entry.id); reporter.error(entry.id, revisions.get(entry.id), error); }
+      console.error(error);
+      if (!watched) process.exitCode = 1;
+    }
+  }
+  async function drain() {
+    if (compiling) return;
+    compiling = true;
+    try {
+      while (pending.size && !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; }
+  }
+  function request() {
+    const file = process.env.ADS_MCP_REQUEST_FILE;
+    if (!file || !existsSync(file)) return;
+    try {
+      const value = JSON.parse(readFileSync(file, "utf8"));
+      if (value.session !== process.env.ADS_MCP_BUILD_SESSION) return;
+      active = entries.find(entry => entry.artifact === value.active)?.id;
+      for (const file of value.files) {
+        const entry = entries.find(entry => entry.artifact === file);
+        if (entry && !requested.has(entry.id)) {
+          requested.add(entry.id);
+          if (!buildGraph || publishedStamp !== cache.inputs()) pending.add(entry.id);
+        }
+      }
+      void drain();
+    } catch (error) { console.error(`Preview requests: ${error.message}`); }
+  }
+  if (!watched) {
+    for (const entry of entries) pending.add(entry.id);
+    await drain();
+    return;
+  }
+  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;
+    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);
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      ++generation;
+      validation = undefined;
+      const changes = [...changed]; changed.clear();
+      try {
+        entries = registry();
+        reporter.setApps(entries.map(entry => ({ id: entry.id, file: entry.artifact })));
+        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.
+        for (const id of requested) {
+          const entry = entries.find(entry => entry.id === id);
+          if (entry) { reporter.begin(id); pending.add(id); }
+        }
+        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);
+      }
+    }, 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 requestWatch = watch(path.join(root, ".ds"), (_event, file) => {
+    if (file === path.basename(process.env.ADS_MCP_REQUEST_FILE ?? "")) request();
+  });
+  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();
+  });
+}

package/dist/scenarios-vite.d.mts

@@ -0,0 +1,3 @@
+import type { Plugin } from "vite";
+export function scenarioRegistryPlugin(directory?: string): Plugin;
+export function inlineScenarioHtml(): Plugin;

package/dist/scenarios-vite.mjs

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { loadConfig, isInside } from "./config.mjs";
+import { inspectScenarios } from "./scenarios.mjs";
+export { createPreviewResources, previewEntriesPlugin } from "./preview-resources.mjs";
+
+/** Project-owned rendering; this plugin supplies only discoverable module entries. */
+export function scenarioRegistryPlugin(directory = process.cwd()) {
+  const options = loadConfig(directory);
+  const virtual = "virtual:ads-scenarios";
+  const resolved = "\0virtual:ads-scenarios";
+  function registry() {
+    const value = inspectScenarios(options);
+    if (value.diagnostics.length) throw new Error(value.diagnostics.map((item) => `${item.file}: ${item.message}`).join("\n"));
+    mkdirSync(path.join(options.root, ".ds/scenarios"), { recursive: true });
+    writeFileSync(path.join(options.root, ".ds/scenarios/manifest.json"), JSON.stringify({ schemaVersion: 1, scenarios: value.scenarios }, null, 2) + "\n");
+    return `export const scenarios = [${value.scenarios.map((item) => `{...${JSON.stringify(item)}, load: () => import(${JSON.stringify(path.join(options.root, item.file).replaceAll("\\", "/"))})}`).join(",\n")}];`;
+  }
+  return { name: "ads-scenario-registry", resolveId(id) { if (id === virtual) return resolved; },
+    load(id) { if (id === resolved) return registry(); },
+    handleHotUpdate({ file, server }) {
+      if (!isInside(options.dsRoot, file)) return;
+      const module = server.moduleGraph.getModuleById(resolved);
+      if (module) server.moduleGraph.invalidateModule(module);
+    },
+    configureServer(server) {
+      const changed = (file) => {
+        if (!isInside(options.dsRoot, file) || !/\.(?:scenario\.[jt]sx?|[jt]sx?)$/.test(file)) return;
+        const module = server.moduleGraph.getModuleById(resolved);
+        if (module) { server.moduleGraph.invalidateModule(module); server.ws.send({ type: "full-reload" }); }
+      };
+      server.watcher.on("add", changed); server.watcher.on("unlink", changed);
+      server.httpServer?.once("close", () => { server.watcher.off("add", changed); server.watcher.off("unlink", changed); });
+    },
+  };
+}
+
+/** Optional Vite adapter for self-contained, focused MCP scenario artifacts. */
+export function inlineScenarioHtml() {
+  return { name: "ads-inline-scenario", enforce: "post", generateBundle(_options, bundle) {
+    const embedded = new Map();
+    for (const asset of Object.values(bundle)) {
+      if (asset.type === "asset" && asset.fileName.endsWith(".js")) {
+        embedded.set(asset.fileName, `data:application/javascript;base64,${Buffer.from(asset.source).toString("base64")}`);
+      }
+    }
+    // Vite emits worker bundles separately. Preserve their compiled code as a
+    // data URL, so workers still run inside an opaque-origin MCP Apps frame.
+    for (const chunk of Object.values(bundle)) if (chunk.type === "chunk") {
+      for (const [file, url] of embedded) {
+        const relative = path.posix.relative(path.posix.dirname(chunk.fileName), file);
+        for (const reference of new Set([file, `./${file}`, `/${file}`, relative, `./${relative}`])) {
+          chunk.code = chunk.code.replaceAll(JSON.stringify(reference), JSON.stringify(url));
+        }
+      }
+    }
+    for (const asset of Object.values(bundle)) {
+      if (asset.type !== "asset" || !asset.fileName.endsWith(".html")) continue;
+      asset.source = asset.source.toString().replace(/<script\b[^>]*\bsrc="([^"]+)"[^>]*><\/script>/g, (_match, src) => {
+        const chunk = bundle[src.replace(/^\.\//, "").replace(/^\//, "")];
+        if (!chunk || chunk.type !== "chunk") throw new Error(`Cannot inline scenario module: ${src}`);
+        return `<script type="module">${chunk.code.replaceAll("</script", "<\\/script")}</script>`;
+      }).replace(/<link\b[^>]*\bhref="([^"]+)"[^>]*>/g, (_match, href) => {
+        const style = bundle[href.replace(/^\.\//, "").replace(/^\//, "")];
+        if (!style || style.type !== "asset" || !style.fileName.endsWith(".css")) throw new Error(`Cannot inline scenario style: ${href}`);
+        return `<style>${style.source.toString().replaceAll("</style", "<\\/style")}</style>`;
+      });
+    }
+    for (const key of Object.keys(bundle)) if (!key.endsWith(".html")) delete bundle[key];
+  } };
+}

package/dist/scenarios.mjs

@@ -0,0 +1,212 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import ts from "typescript";
+import { uiOperation } from "./ui-framework.mjs";
+import { isDevelopmentFile, isInside, isScenarioFile, sourceFiles } from "./config.mjs";
+import { projectCompilerOptions } from "./boundaries.mjs";
+import { inspectTokens } from "./tokens.mjs";
+import { isSharedToken } from "./token-policy.mjs";
+
+export const scenarioArtifact = (root, id) => path.join(root, ".ds/scenarios", id, "index.html");
+
+function literal(node, checker, seen = new Set()) {
+  while (node && (ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node))) node = node.expression;
+  if (!node || seen.has(node)) return undefined;
+  seen = new Set([...seen, node]);
+  if (node && ts.isStringLiteralLike(node)) return node.text;
+  if (node && ts.isArrayLiteralExpression(node)) return node.elements.map(item => literal(item, checker, seen));
+  if (node && ts.isObjectLiteralExpression(node)) return Object.fromEntries(node.properties.map((item) => ts.isPropertyAssignment(item) && item.name && (ts.isIdentifier(item.name) || ts.isStringLiteralLike(item.name)) ? [item.name.text, literal(item.initializer, checker, seen)] : ["invalid", undefined]));
+  if (checker && (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node))) {
+    let symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+    if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    if (declaration && (ts.isPropertyAssignment(declaration) || ts.isVariableDeclaration(declaration) && declaration.parent.flags & ts.NodeFlags.Const)) return literal(declaration.initializer, checker, seen);
+  }
+  return undefined;
+}
+
+export function publicUi(program, options) {
+  const checker = program.getTypeChecker();
+  const entry = program.getSourceFile(path.join(options.dsRoot, options.config.publicEntry));
+  const module = entry && checker.getSymbolAtLocation(entry);
+  const items = [];
+  for (const exported of module ? checker.getExportsOfModule(module) : []) {
+    let symbol = exported;
+    if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+    if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
+    const file = declaration.getSourceFile().fileName;
+    if (isDevelopmentFile(file, options)) continue;
+    const kind = isInside(path.join(options.dsRoot, "components"), file) ? "components" : isInside(path.join(options.dsRoot, "patterns"), file) ? "patterns" : null;
+    if (!kind) continue;
+    let renderable = false;
+    function visit(node) {
+      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) renderable = true;
+      if (ts.isCallExpression(node) && ["createElement", "forwardRef", "memo"].includes(uiOperation(node.expression, checker))) renderable = true;
+      if (ts.isTaggedTemplateExpression(node)) {
+        let tag = node.tag;
+        if (ts.isCallExpression(tag)) tag = tag.expression;
+        let base = tag;
+        while (ts.isPropertyAccessExpression(base)) base = base.expression;
+        const symbol = checker.getSymbolAtLocation(base);
+        if (symbol?.declarations?.some(item => ts.isImportSpecifier(item) && (item.propertyName ?? item.name).text === "styled" && item.parent.parent.parent.moduleSpecifier.text.startsWith("@linaria/") || ts.isNamespaceImport(item) && item.parent.parent.moduleSpecifier.text.startsWith("@linaria/") && /^\.styled(?:\.|$)/.test(tag.getText().slice(base.getText().length)))) renderable = true;
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(declaration);
+    items.push({ name: exported.name, kind, file, declaration, renderable });
+  }
+  return items;
+}
+
+/** Discover metadata statically. The MCP process never imports scenario modules. */
+export function inspectScenarios(options, suppliedProgram) {
+  const { root, dsRoot } = options;
+  const files = sourceFiles(dsRoot).filter(isScenarioFile);
+  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), ...files], projectCompilerOptions(options));
+  const known = new Map(publicUi(program, options).map((item) => [item.name, item]));
+  const checker = program.getTypeChecker();
+  const tokenNames = new Set(inspectTokens(root).tokens.map(token => token.name));
+  const scenarios = [];
+  const diagnostics = [];
+  const ids = new Set();
+  function report(file, message) { diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "scenario-contract", line: 1, column: 1, message }); }
+  for (const file of files) {
+    const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
+    const kind = isInside(path.join(dsRoot, options.config.tokenDir), file) ? "tokens" : relative.split("/")[0];
+    if (!["tokens", "components", "patterns", "composition"].includes(kind)) { report(file, "Scenarios live beside tokens/components/patterns or under composition/, not inside showcase pages."); continue; }
+    const id = relative.replace(/(?:\/Scenario|\.scenario)\.[^.]+$/, "");
+    if (id.length > 256) { report(file, "Scenario paths must fit within 256 characters."); continue; }
+    if (ids.has(id)) { report(file, `Duplicate scenario id ${id}. Use one entrypoint per identity.`); continue; }
+    ids.add(id);
+    const source = program.getSourceFile(file);
+    if (!source) { report(file, "Cannot inspect scenario source."); continue; }
+    let metadata;
+    let entry = false;
+    for (const node of source.statements) {
+      if (ts.isExportAssignment(node) || node.modifiers?.some((item) => item.kind === ts.SyntaxKind.DefaultKeyword)) entry = true;
+      if (ts.isVariableStatement(node) && node.modifiers?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword)) {
+        for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === "scenario") metadata = literal(declaration.initializer, checker);
+      }
+    }
+    if (!entry) report(file, "Export a default independently mountable scenario entrypoint.");
+    const module = checker.getSymbolAtLocation(source);
+    const defaultExport = module && checker.getExportsOfModule(module).find(item => item.name === "default");
+    if (defaultExport) {
+      const type = checker.getTypeOfSymbolAtLocation(defaultExport, source);
+      const calls = [...type.getCallSignatures(), ...type.getConstructSignatures()];
+      if (!calls.length && !(type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))) report(file, "Export a mountable component as default, not an already-created element or data object.");
+      for (const call of calls) {
+        const props = call.parameters[0];
+        const optional = props?.declarations?.some(item => item.initializer || item.questionToken);
+        if (props && !optional && checker.getTypeOfSymbolAtLocation(props, source).getProperties().some(item => !(item.flags & ts.SymbolFlags.Optional))) report(file, "Scenario entrypoints cannot require caller props. Supply required inputs in the colocated fixture adapter.");
+      }
+    }
+    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 (!["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("\\", "/") });
+  }
+  return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
+}
+
+export function inspectScenarioCoverage(options, program, report) {
+  const registry = inspectScenarios(options, program);
+  for (const item of registry.diagnostics) report(path.join(options.root, item.file), item.rule, item.message, item.line, item.column);
+  const checker = program.getTypeChecker();
+  const ui = publicUi(program, options);
+  function symbolOf(expression) {
+    while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isNonNullExpression(expression))) expression = expression.expression;
+    if (!expression) return null;
+    if (ts.isElementAccessExpression(expression) && expression.argumentExpression && ts.isStringLiteralLike(expression.argumentExpression)) {
+      return checker.getPropertyOfType(checker.getTypeAtLocation(expression.expression), expression.argumentExpression.text);
+    }
+    return checker.getSymbolAtLocation(expression);
+  }
+  function canonical(symbol, seen = new Set()) {
+    if (!symbol || seen.has(symbol)) return null;
+    seen.add(symbol);
+    if (symbol.flags & ts.SymbolFlags.Alias) return canonical(checker.getAliasedSymbol(symbol), seen);
+    for (const declaration of symbol.declarations ?? []) {
+      if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+        const target = symbolOf(declaration.initializer);
+        if (target) return canonical(target, seen);
+      }
+      if (ts.isBindingElement(declaration) && ts.isObjectBindingPattern(declaration.parent) && ts.isVariableDeclaration(declaration.parent.parent)) {
+        const initializer = declaration.parent.parent.initializer;
+        const key = declaration.propertyName ?? declaration.name;
+        if (initializer && (ts.isIdentifier(key) || ts.isStringLiteralLike(key))) {
+          const target = checker.getPropertyOfType(checker.getTypeAtLocation(initializer), key.text);
+          if (target) return canonical(target, seen);
+        }
+      }
+    }
+    return symbol.declarations?.length ? symbol : null;
+  }
+  const identities = new Map();
+  for (const item of ui) {
+    if (!identities.has(item.declaration)) identities.set(item.declaration, new Set());
+    identities.get(item.declaration).add(item.name);
+  }
+
+  const covered = new Set();
+  const coveredTokens = new Set();
+  const tokenInventory = inspectTokens(options.root);
+  const declaredTokens = new Set(tokenInventory.tokens.map(token => token.name));
+  for (const scenario of registry.scenarios) {
+    const source = program.getSourceFile(path.join(options.root, scenario.file));
+    const rendered = new Set();
+    const referencedTokens = new Set();
+    const visited = new Set();
+    function visit(node, reached = false) {
+      if (!node || visited.has(node)) return;
+      if (!reached && (ts.isFunctionDeclaration(node) || ts.isVariableDeclaration(node))) return;
+      if (!reached && (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && !ts.isCallExpression(node.parent) && !ts.isJsxExpression(node.parent)) return;
+      visited.add(node);
+      if (ts.isStringLiteralLike(node) && (isSharedToken(node.text) || scenario.tokens.includes(node.text))) referencedTokens.add(node.text);
+      let expression;
+      if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) expression = node.tagName;
+      if (ts.isCallExpression(node) && uiOperation(node.expression, checker) === "createElement") expression = node.arguments[0];
+      if (expression) {
+        const symbol = canonical(symbolOf(expression));
+        const names = identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]);
+        for (const name of names ?? []) rendered.add(name);
+      }
+      // Follow local adapters reachable from the default entry. Unused example
+      // functions do not satisfy coverage; production implementations are never
+      // traversed to manufacture coverage for their internal dependencies.
+      if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node) || ts.isIdentifier(node) && !(ts.isPropertyAccessExpression(node.parent) || ts.isElementAccessExpression(node.parent))) {
+        const symbol = canonical(symbolOf(node));
+        const declaration = symbol?.valueDeclaration;
+        if (declaration && isDevelopmentFile(declaration.getSourceFile().fileName, options)) visit(declaration, true);
+      }
+      ts.forEachChild(node, child => visit(child, reached && (ts.isExportAssignment(node) || ts.isVariableDeclaration(node))));
+    }
+    for (const node of source.statements) if (ts.isExportAssignment(node) || node.modifiers?.some(item => item.kind === ts.SyntaxKind.DefaultKeyword)) visit(node, true);
+    for (const name of scenario.covers) {
+      if (!rendered.has(name)) report(source.fileName, "scenario-render", `${name} is declared in covers but has no public render reference in this scenario. Render the real API; an import alone does not count.`);
+      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}.`);
+    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);
+    }
+  }
+  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.`);
+  for (const token of tokenInventory.tokens.filter(token => !coveredTokens.has(token.name))) {
+    const definition = token.definitions[0];
+    report(path.join(options.root, definition.file), "token-scenario-coverage", `Token ${token.name} needs a registered scenario with a reachable token fixture reference.`, definition.line, definition.column);
+  }
+}
+
+export function writeScenarioRegistry(options, write) {
+  const registry = inspectScenarios(options);
+  if (registry.diagnostics.length) throw new Error(registry.diagnostics.map((item) => `${item.file}: ${item.message}`).join("\n"));
+  write({ schemaVersion: 1, scenarios: registry.scenarios });
+  return registry.scenarios;
+}