@reqvire-org/ads 0.0.0-stage → 0.3.0

package/dist/mcp/prompts.mjs

@@ -0,0 +1,28 @@
+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.
+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.
+Check ads_status.previewWatch before launching a separate preview builder. A configured watcher is managed by ads mcp. Check ads_status.build or ads://project/build after changes: running does not mean ready, and unreported freshness is not evidence of current source. Reported preview failures include structured diagnostics; fix the owning source and wait for a successful rebuild, then invoke the preview tool again. Notifications may not reach the agent, so read status explicitly. Build revisions identify reported compilation attempts, not proof of runtime/visual correctness. Do not invent replacement UI to bypass a failed preview.
+Skills: use ads_skills to select a workflow and read its SKILL.md with ads_read_skill. Resolve relative supporting files from that skill URI. Reading instructions does not prove native skill activation or authorize unrelated actions.
+Ask for missing intent only when it changes the outcome. State the proposed behavior, states and difficult content. Preserve lazy loading, workers, caches, cancellation, reduced motion, focus and keyboard behavior. Run ads_check plus the project's registered lint, typecheck, build and relevant tests; inspect the actual browser/rendered app at narrow and wide sizes in both themes. Static success does not establish visual or interaction parity.`;
+
+export function promptDefinitions(skills) {
+  const prompts = [
+    { name: "ads-design", description: "Turn a UI request into an ADS-owned implementation and review workflow.", arguments: [{ name: "request", description: "What to design or change", required: true }] },
+    { name: "ads-inspect", description: "Find public ADS elements, inspect their contract, and select a real preview.", arguments: [{ name: "element", description: "Component, pattern, token or question", required: true }] },
+    { name: "ads-show", description: "Choose project-built token, component, pattern or composition Apps with a text fallback.", arguments: [{ name: "target", description: "What the human wants to inspect", required: true }] },
+  ];
+  for (const skill of skills) prompts.push({ name: skill.frontmatter.name, description: skill.frontmatter.description, arguments: [{ name: "request", description: "Task and any source-library URL or ADS path", required: true }] });
+  return prompts;
+}
+
+export function getWorkflowPrompt(name, args, skills) {
+  const definition = promptDefinitions(skills).find((prompt) => prompt.name === name);
+  if (!definition) throw new Error("Unknown ADS prompt.");
+  const argument = definition.arguments[0].name;
+  if (!args || Object.keys(args).some((key) => key !== argument) || typeof args[argument] !== "string" || !args[argument].trim() || args[argument].length > 8000) throw new Error(`Prompt requires ${argument}, a non-empty string of at most 8000 characters.`);
+  const skill = skills.find((entry) => entry.frontmatter.name === name);
+  return { description: definition.description, messages: [{ role: "user", content: { type: "text", text: `${reasoning}\n\n${skill ? `Use ${skill.frontmatter.name}; first read ${skill.uri} and its relevant supporting references.\n\n` : ""}${argument}: ${args[argument]}` } }] };
+}

package/dist/mcp/resource-loader.js

@@ -0,0 +1,138 @@
+/** Native ES modules keep framework semantics, cycles, and live bindings intact. */
+export class PreviewResourceLoader {
+  constructor(read) {
+    this.read = read;
+    this.records = new Map();
+    this.bytes = new Map();
+    this.urls = new Map();
+    this.styles = new Map();
+    this.styleReady = new Map();
+    this.revisions = new Set();
+    this.importing = Promise.resolve();
+    this.generation = 0;
+    this.closed = false;
+    globalThis.__dsPreviewImport = uri => this.importModule(uri);
+  }
+  register(manifest) {
+    if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.scenarios) || !manifest.assets || typeof manifest.revision !== "string") throw new Error("Unsupported preview manifest. Rebuild previews with the installed ADS version.");
+    this.revisions.add(manifest.revision);
+    if (this.revisions.size > 20) throw Object.assign(new Error("Reopen the preview to release modules retained across 20 build revisions."), { code: "ADS_PREVIEW_REOPEN" });
+    for (const [uri, record] of Object.entries(manifest.assets)) {
+      if (!/^ads:\/\/assets\/[a-f0-9]{64}\.[a-z0-9]+$/.test(uri) || !/^sha256:[a-f0-9]{64}$/.test(record.digest)
+        || !["imports", "dynamicImports", "styles", "references"].every(key => Array.isArray(record[key]) && record[key].every(ref => Object.hasOwn(manifest.assets, ref)))) throw new Error("Invalid preview dependency graph.");
+      if (this.records.has(uri) && this.records.get(uri).digest !== record.digest) throw new Error("An immutable preview resource changed its content.");
+      this.records.set(uri, record);
+    }
+  }
+  async resource(uri) {
+    if (!this.bytes.has(uri)) {
+      const task = (async () => {
+        const record = this.records.get(uri);
+        if (!record) throw new Error(`Unknown preview dependency: ${uri}`);
+        const response = await this.read(uri);
+        if (this.closed) throw new Error("The preview App was closed.");
+        const content = response.contents.find(item => item.uri === uri);
+        if (!content) throw new Error(`Missing preview dependency: ${uri}`);
+        const bytes = typeof content.text === "string" ? new TextEncoder().encode(content.text) : Uint8Array.from(atob(content.blob), letter => letter.charCodeAt(0));
+        const digest = await crypto.subtle.digest("SHA-256", bytes);
+        const actual = "sha256:" + [...new Uint8Array(digest)].map(byte => byte.toString(16).padStart(2, "0")).join("");
+        if (bytes.length !== record.size || actual !== record.digest) throw new Error("Preview resource integrity check failed. Rebuild and reopen the preview.");
+        return bytes;
+      })();
+      this.bytes.set(uri, task);
+      task.catch(() => this.bytes.delete(uri));
+    }
+    return this.bytes.get(uri);
+  }
+  closure(uri) {
+    const ordered = [];
+    const seen = new Set();
+    const visit = id => {
+      if (seen.has(id)) return;
+      seen.add(id);
+      const record = this.records.get(id);
+      if (!record) throw new Error(`Missing preview dependency metadata: ${id}`);
+      for (const dependency of [...record.imports, ...record.styles, ...record.references]) visit(dependency);
+      ordered.push(id);
+    };
+    visit(uri);
+    return ordered;
+  }
+  async materialize(uri) {
+    const ordered = this.closure(uri);
+    await Promise.all(ordered.map(id => this.resource(id)));
+    const imports = {};
+    for (const id of ordered) {
+      if (this.closed) throw new Error("The preview App was closed.");
+      if (this.urls.has(id)) continue;
+      const record = this.records.get(id);
+      let bytes = await this.resource(id);
+      if (record.kind === "module" || record.mimeType === "text/css") {
+        let text = new TextDecoder().decode(bytes);
+        for (const reference of record.references) {
+          const url = this.urls.get(reference);
+          if (!url) throw new Error("Unsupported cyclic asset reference.");
+          text = text.replaceAll(reference, url);
+        }
+        bytes = text;
+      }
+      const url = URL.createObjectURL(new Blob([bytes], { type: record.mimeType }));
+      this.urls.set(id, url);
+      if (record.kind === "module") imports[id] = url;
+    }
+    if (Object.keys(imports).length) {
+      const script = document.createElement("script");
+      script.type = "importmap";
+      script.textContent = JSON.stringify({ imports });
+      document.head.append(script);
+    }
+    return ordered;
+  }
+  async importModule(uri) {
+    const prepare = this.importing.then(() => this.materialize(uri));
+    this.importing = prepare.catch(() => {});
+    const dependencies = await prepare;
+    for (const id of dependencies) {
+      const record = this.records.get(id);
+      if (record.mimeType !== "text/css") continue;
+      if (this.styles.has(id)) { await this.styleReady.get(id); continue; }
+      const style = document.createElement("link");
+      style.rel = "stylesheet";
+      style.href = this.urls.get(id);
+      this.styles.set(id, style);
+      const ready = new Promise((resolve, reject) => { style.onload = resolve; style.onerror = () => reject(new Error("The host CSP blocked a preview stylesheet.")); });
+      this.styleReady.set(id, ready);
+      document.head.append(style);
+      try { await ready; } catch (error) { style.remove(); this.styles.delete(id); this.styleReady.delete(id); throw error; }
+    }
+    return import(/* @vite-ignore */ uri);
+  }
+  async mount(manifest, id, container) {
+    const generation = ++this.generation;
+    this.register(manifest);
+    const scenario = manifest.scenarios.find(entry => entry.id === id);
+    if (!scenario) throw new Error("The selected scenario is no longer registered.");
+    const module = await this.importModule(scenario.module);
+    if (generation !== this.generation) return false;
+    await this.unmount?.();
+    if (generation !== this.generation || this.closed) return false;
+    container.replaceChildren();
+    const keep = new Set(this.closure(scenario.module));
+    for (const [uri, style] of this.styles) if (!keep.has(uri)) { style.remove(); this.styles.delete(uri); this.styleReady.delete(uri); }
+    for (const uri of this.closure(scenario.module)) if (this.styles.has(uri)) document.head.append(this.styles.get(uri));
+    if (typeof module.mount !== "function") throw new Error("The compiled scenario has no mount adapter.");
+    this.unmount = module.mount(container);
+    if (typeof this.unmount !== "function") throw new Error("The scenario mount adapter must return an unmount callback.");
+    return true;
+  }
+  async dispose() {
+    if (this.closed) return;
+    this.closed = true;
+    ++this.generation;
+    await this.unmount?.();
+    for (const style of this.styles.values()) style.remove();
+    for (const url of this.urls.values()) URL.revokeObjectURL(url);
+    this.styles.clear(); this.styleReady.clear(); this.urls.clear(); this.bytes.clear(); this.records.clear();
+    delete globalThis.__dsPreviewImport;
+  }
+}

package/dist/mcp/sandbox-host.mjs

@@ -0,0 +1,22 @@
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+
+/** A different loopback port provides the browser host's separate sandbox origin. */
+export async function startSandboxHost(parentOrigin) {
+  const script = await readFile(new URL("../showcase/sandbox.js", import.meta.url));
+  const web = createServer((req, res) => {
+    const origin = `http://127.0.0.1:${web.address().port}`;
+    const url = new URL(req.url, origin);
+    if (req.headers.host !== new URL(origin).host || req.method !== "GET") { res.writeHead(403); res.end(); return; }
+    const javascript = url.pathname === "/sandbox.js";
+    if (!javascript && (url.pathname !== "/sandbox.html" || url.searchParams.get("parent") !== parentOrigin)) { res.writeHead(404); res.end(); return; }
+    res.writeHead(200, { "Content-Type": javascript ? "text/javascript" : "text/html", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", "Content-Security-Policy": `frame-ancestors ${parentOrigin};object-src 'none'` });
+    res.end(javascript ? script : '<!doctype html><html><head><meta charset="utf-8"><style>html,body,iframe{height:100%;width:100%;margin:0;border:0;display:block;overflow:hidden}</style></head><body><script src="/sandbox.js"></script></body></html>');
+  });
+  await new Promise((resolve, reject) => { web.once("error", reject); web.listen(0, "127.0.0.1", resolve); });
+  return { url: `http://127.0.0.1:${web.address().port}/sandbox.html?parent=${encodeURIComponent(parentOrigin)}`, close() {
+    const stopped = new Promise(resolve => web.close(resolve));
+    web.closeAllConnections();
+    return stopped;
+  } };
+}

package/dist/mcp/server.mjs

@@ -0,0 +1,377 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { Server, ProtocolError, INVALID_PARAMS, ResourceNotFoundError } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { z } from "zod";
+import { checkProject } from "../check.mjs";
+import { loadConfig, sourceFiles } from "../config.mjs";
+import { inspectTokens } from "../tokens.mjs";
+import { inspectScenarios } from "../scenarios.mjs";
+import { startShowcaseHost } from "./showcase-host.mjs";
+import { createSkillStore, page, SKILLS_EXTENSION } from "./skills.mjs";
+import { inspectCatalog, projectDocuments, PROJECT_URI, readProjectDocument } from "./catalog.mjs";
+import { APP_MIME, appMetadata, appUri, projectApp, TOKENS_APP_URI, tokensApp, tokenWidgetData, SCENARIO_APP_URI, scenarioApp, previewApp, PREVIEW_APP_URI } from "./apps.mjs";
+import { PREVIEW_MANIFEST_URI, readPreviewManifest, readPreviewAsset } from "../preview-resources.mjs";
+import { getWorkflowPrompt, promptDefinitions } from "./prompts.mjs";
+import { createReconfigurablePreviewWatch } from "./preview-watch.mjs";
+import { BUILD_URI, buildFailure, inspectBuildStatus, summarizeBuild } from "./build-status.mjs";
+import { GUIDE_URI, projectContext, projectGuide, serverInstructions, workflow } from "./context.mjs";
+import { createMutationController, mutationLimits } from "./mutations.mjs";
+
+const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+class InvalidParamsError extends ProtocolError {
+  constructor(message) { super(INVALID_PARAMS, message); }
+}
+const json = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value });
+const empty = z.object({}).strict();
+const query = z.object({ query: z.string().max(200).optional(), limit: z.number().int().min(1).max(50).default(20) }).strict();
+const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const schemas = { params: z.object({ cursor: z.string().optional() }).passthrough(), result: z.object({ resultType: z.literal("complete") }).passthrough() };
+
+export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollInterval = 1000, previewWatch, showcaseUrl, notifications, inspection, mutations = false } = {}) {
+  const root = path.resolve(directory);
+  const cache = inspection ?? {};
+  const skills = cache.skills ??= createSkillStore(skillDirectory);
+  const edits = cache.edits ??= createMutationController(root);
+  let options = loadConfig(root);
+  const signature = `${root}:${JSON.stringify(options.config)}`;
+  if (cache.signature !== signature) {
+    cache.signature = signature;
+    cache.registry = cache.catalog = cache.documents = undefined;
+  }
+  const getShowcaseUrl = () => showcaseUrl?.() ?? options.config.mcp.showcaseUrl;
+  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."}`,
+    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 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;
+  const resourceAssets = () => {
+    try { return Object.entries(readPreviewManifest(options)?.assets ?? {}).map(([uri, record]) => ({ uri, name: `Preview asset ${uri.slice("ads://assets/".length)}`, mimeType: record.mimeType, size: record.size })); }
+    catch { return []; } // Discovery and diagnostics remain usable after a failed graph.
+  };
+  function graphSelection(id) {
+    if (!options.config.mcp.previewManifest) return {};
+    const manifest = readPreviewManifest(options);
+    if (!manifest?.scenarios.some(entry => entry.id === id)) throw new Error("The preview resource graph is not ready for this scenario. Rebuild previews.");
+    return { manifestUri: PREVIEW_MANIFEST_URI, manifestRevision: manifest.revision };
+  }
+  const getCatalog = () => cache.catalog ??= inspectCatalog(options, getRegistry().scenarios);
+  const getDocuments = () => cache.documents ??= projectDocuments(options);
+  const builds = () => {
+    previewWatch?.setApps(allApps());
+    return previewWatch?.buildStatus() ?? inspectBuildStatus(root, { ...options.config.mcp, apps: allApps() });
+  };
+  const previews = () => options.config.mcp.apps.map((app) => ({ id: app.id, title: app.title, kind: app.kind, tool: `ads_show_${app.id.replaceAll("-", "_")}`, resourceUri: appUri(app.id), available: existsSync(path.resolve(root, app.file)), file: app.file }));
+
+  function resources() {
+    const context = project();
+    const documents = getDocuments();
+    const promoted = new Set([context.publicEntryUri, ...context.guides.map((guide) => guide.uri)]);
+    const skillEntries = new Set(skills.skills.map((skill) => skill.uri));
+    return [
+      { uri: GUIDE_URI, name: "Start here: design-system workflow", description: "Read first for UI/ADS tasks, especially when only resource access is exposed. Explains the exact workspace, tool sequence, skill selection, previews, project commands and fallback.", mimeType: "text/markdown" },
+      { uri: `${PROJECT_URI}/status`, name: "ADS project status", mimeType: "application/json" },
+      { uri: BUILD_URI, name: "Preview build status and diagnostics", mimeType: "application/json" },
+      { uri: `${PROJECT_URI}/tokens`, name: "Project token values and themes", mimeType: "application/json" },
+      { uri: `${PROJECT_URI}/catalog`, name: "Public components and patterns", mimeType: "application/json" },
+      { uri: `${PROJECT_URI}/scenarios`, name: "Independently mountable scenarios", mimeType: "application/json" },
+      { uri: `${PROJECT_URI}/checks`, name: "Current ADS architecture diagnostics", mimeType: "application/json" },
+      { uri: TOKENS_APP_URI, name: "Experimental token widget", mimeType: APP_MIME },
+      { uri: SCENARIO_APP_URI, name: "Experimental scenario widget", mimeType: APP_MIME },
+      ...(options.config.mcp.previewManifest ? [{ uri: PREVIEW_APP_URI, name: "Shared-resource preview App", mimeType: APP_MIME }, { uri: PREVIEW_MANIFEST_URI, name: "Preview dependency graph", mimeType: "application/json" }] : []),
+      ...(options.config.mcp.previewManifest ? resourceAssets() : []),
+      ...allApps().map((app) => ({ uri: appUri(app.id), name: app.title, description: app.description, mimeType: APP_MIME })),
+      ...skills.skills.map(({ uri, frontmatter }) => ({ uri, name: frontmatter.name, description: frontmatter.description, mimeType: "text/markdown" })),
+      ...documents.filter((document) => promoted.has(document.uri)).map(({ file: _file, ...document }) => document),
+      ...documents.filter((document) => !promoted.has(document.uri)).map(({ file: _file, ...document }) => document),
+      ...[...skills.files.values()].filter((file) => !skillEntries.has(file.uri)).map(({ uri, name, mimeType }) => ({ uri, name, mimeType })),
+    ];
+  }
+  function status() {
+    const context = project();
+    return { projectRoot: root, workflow: workflow([...previews(), ...scenarioApps()]), project: context,
+      package: pkg.name, version: pkg.version, dsDir: options.config.dsDir, publicAlias: options.config.publicAlias,
+      components: getCatalog().filter((item) => item.kind === "components").length,
+      patterns: getCatalog().filter((item) => item.kind === "patterns").length,
+      tokenCount: inspectTokens(root).tokens.length, showcaseUrl: getShowcaseUrl(),
+      previewWatch: previewWatch?.status() ?? { state: "disabled" },
+      mutations: mutations ? edits.status() : { enabled: false },
+      build: summarizeBuild(builds()),
+      previews: previews(), skills: skills.skills.map(({ uri, frontmatter }) => ({ uri, name: frontmatter.name, description: frontmatter.description })),
+      scenarios: { count: getRegistry().scenarios.length, diagnostics: getRegistry().diagnostics, resourceUri: `${PROJECT_URI}/scenarios`, tool: "ads_show_scenario" },
+      experimental: { apps: true, nativeSkills: era === "modern", nativeSkillActivation: "host-controlled" } };
+  }
+  async function read(uri, signal) {
+    if (uri === GUIDE_URI) return { contents: [{ uri, mimeType: "text/markdown", text: projectGuide(project(), [...previews(), ...scenarioApps()]) }] };
+    if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
+    let value;
+    if (uri === `${PROJECT_URI}/status`) value = status();
+    else if (uri === BUILD_URI) value = builds();
+    else if (uri === `${PROJECT_URI}/tokens`) value = tokenWidgetData(inspectTokens(root));
+    else if (uri === `${PROJECT_URI}/catalog`) value = { items: getCatalog() };
+    else if (uri === `${PROJECT_URI}/scenarios`) value = getRegistry();
+    else if (uri === `${PROJECT_URI}/checks`) value = checkProject(root);
+    else if (uri === PREVIEW_MANIFEST_URI && options.config.mcp.previewManifest) {
+      value = readPreviewManifest(options);
+      if (!value) throw new Error("Preview resources are not built yet. Invoke ads_show_scenario to start the managed compiler.");
+    }
+    if (value !== undefined) return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(value) }] };
+    if (uri === TOKENS_APP_URI) return { contents: [{ uri, mimeType: APP_MIME, text: tokensApp(tokenWidgetData(inspectTokens(root))), _meta: appMetadata({ nested: true }) }] };
+    if (uri === SCENARIO_APP_URI) return { contents: [{ uri, mimeType: APP_MIME, text: scenarioApp(), _meta: appMetadata({ nested: true }) }] };
+    if (uri === PREVIEW_APP_URI && options.config.mcp.previewManifest) return { contents: [{ uri, mimeType: APP_MIME, text: previewApp(), _meta: appMetadata() }] };
+    if (uri.startsWith("ads://assets/") && options.config.mcp.previewManifest) {
+      try { return { contents: [readPreviewAsset(options, uri)] }; }
+      catch (error) { if (error.code === "ADS_PREVIEW_NOT_FOUND") throw new ResourceNotFoundError(uri, error.message); throw error; }
+    }
+    const app = allApps().find((entry) => appUri(entry.id) === uri);
+    if (app) {
+      if (scenarioApps().some(entry => entry.id === app.id) && getRegistry().diagnostics.length) throw new Error("Scenario registry has errors. Read ads://project/scenarios before opening a preview.");
+      const build = await previewBuild(app, signal);
+      const graph = options.config.mcp.previewManifest && scenarioApps().some(entry => entry.id === app.id);
+      return { contents: [{ uri, mimeType: APP_MIME, text: graph ? previewApp({ id: app.id }) : projectApp(options, app, build), _meta: appMetadata() }] };
+    }
+    const document = getDocuments().find((entry) => entry.uri === uri);
+    if (document) return { contents: [{ uri, mimeType: document.mimeType, text: readProjectDocument(document) }] };
+    throw new ResourceNotFoundError(uri, `Unknown ADS resource: ${uri}`);
+  }
+  async function previewBuild(app, signal) {
+    previewWatch?.setApps(allApps());
+    if (previewWatch) return previewWatch.ensure(path.resolve(root, app.file), signal);
+    const build = builds().previews.find((entry) => entry.id === app.id);
+    if (build?.state === "error") throw buildFailure(build);
+    if (["building", "idle"].includes(build?.state)) throw Object.assign(new Error("Preview build is still pending. Invoke the preview again after rebuilding."), { build: { ...build, resourceUri: BUILD_URI } });
+    return build;
+  }
+
+  function tools() {
+    return [
+      { name: "ads_status", description: "Start here for UI/ADS work: components, patterns, tokens/themes/branding, layout, behavior, motion and showcase review. Returns the exact project root/public API, workflow, project commands, editing mode and build diagnostics. When mutations.enabled, use guarded ads_apply_patch for ADS edits; otherwise use local editing tools.", schema: empty, call: () => json(status()) },
+      { name: "ads_catalog", description: "Before creating/changing UI, find existing public components/patterns with a small query/limit. Returns import alias and exact source/guide URIs so you can reuse or edit the owner. Read ads_status first for workspace/workflow. Metadata only; does not render UI.", schema: query.extend({ kind: z.enum(["components", "patterns"]).optional() }), call: ({ query: search = "", limit, kind }) => {
+        const matches = getCatalog().filter((item) => (!kind || item.kind === kind) && item.name.toLowerCase().includes(search.toLowerCase()));
+        const units = edits.units();
+        return json({ total: matches.length, items: matches.slice(0, limit).map(item => ({ ...item, unit: units.find(unit => unit.files.includes(item.file))?.id ?? null })), resourceUri: `${PROJECT_URI}/catalog` });
+      } },
+      { name: "ads_scenarios", description: "Find an independently mountable token, component, pattern or composition preview. IDs derive from source filenames; covers lists public UI and tokens lists the real token inputs. Use ads_show_scenario with an exact returned id. Showcase and MCP use this same registry.", schema: query.extend({ kind: z.enum(["tokens", "components", "patterns", "composition"]).optional(), offset: z.number().int().min(0).default(0) }), call: ({ query: search = "", limit, kind, offset }) => {
+        const matches = getRegistry().scenarios.filter(item => (!kind || item.kind === kind) && `${item.id} ${item.title} ${item.covers.join(" ")} ${item.tokens.join(" ")}`.toLowerCase().includes(search.toLowerCase()));
+        const units = edits.units();
+        return json({ total: matches.length, scenarios: matches.slice(offset, offset + limit).map(item => ({ ...item, unit: units.find(unit => unit.files.includes(item.file))?.id ?? null })), ...(offset + limit < matches.length ? { nextOffset: offset + limit } : {}), diagnostics: getRegistry().diagnostics, resourceUri: `${PROJECT_URI}/scenarios` });
+      } },
+      { name: "ads_show_scenario", description: "Render one real token, component, pattern or composition scenario with its colocated fixtures and state adapter. First get an exact id from ads_scenarios or ads_catalog.previews. The managed compiler builds it on demand; errors return diagnostics instead of falsely current output. Requires MCP Apps plus host resource forwarding; fallback links to the same scenario in the project showcase.", schema: z.object({ id: z.string().min(1).max(256) }).strict(), _meta: { ui: { resourceUri: scenarioWidget() } }, call: async ({ id }, signal) => {
+        const entry = getRegistry().scenarios.find(item => item.id === id);
+        if (!entry) throw new Error("Unknown scenario id. Read ads_scenarios; IDs must match discovered source entries.");
+        if (getRegistry().diagnostics.length) throw new Error("Scenario registry has errors. Read ads://project/scenarios and fix its diagnostics.");
+        const app = scenarioApps().find(item => item.id === id);
+        const build = await previewBuild(app, signal);
+        const graph = graphSelection(id);
+        if (!options.config.mcp.previewManifest) projectApp(options, app, build);
+        const url = getShowcaseUrl() ? new URL(getShowcaseUrl()) : null;
+        url?.searchParams.delete("category");
+        url?.searchParams.set("scenario", id);
+        return json({ widget: { resourceUri: scenarioWidget() }, scenario: { ...entry, resourceUri: appUri(id) }, ...graph, build, showcaseUrl: url?.href ?? null });
+      } },
+      { name: "ads_tokens", description: "Use before styling, theme, brand or motion-token changes to inspect existing semantic definitions/values. Query specific token names with a small limit. ads_show_tokens renders project token scenarios; definition inspection does not validate component layout.", schema: query, call: ({ query: search = "", limit }) => {
+        const inventory = inspectTokens(root);
+        const matches = inventory.tokens.filter((token) => token.name.toLowerCase().includes(search.toLowerCase()));
+        return json({ total: matches.length, tokens: matches.slice(0, limit), categories: tokenScenarios(), diagnosticCount: inventory.diagnostics.length, resourceUri: `${PROJECT_URI}/tokens` });
+      } },
+      { name: "ads_check", description: "Run read-only core ADS architecture checks. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
+        const result = checkProject(root);
+        return json({ ok: result.ok, total: result.diagnostics.length, diagnostics: result.diagnostics.slice(0, limit), resourceUri: `${PROJECT_URI}/checks` });
+      } },
+      { name: "ads_skills", description: "Select one ADS workflow after ads_status: ads-designer for building/refining/debugging UI; ads-assimilate for a library reference; ads-import for another project's ADS; ads-motion for animation; ads-break-ui for stress testing. Then read that workflow with ads_read_skill. Listing does not activate a native skill.", schema: empty, call: () => json({ skills: skills.skills.map(({ uri, frontmatter }) => ({ uri, ...frontmatter })) }) },
+      { name: "ads_read_skill", description: "Read a selected skill or relative supporting text file in bounded chunks. This is explicit instruction access, not automatic native skill activation/install.", schema: z.object({ name: z.string().max(64), file: z.string().max(300).default("SKILL.md"), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(8000).default(6000) }).strict(), call: ({ name, file, offset, limit }) => {
+        const skill = skills.skills.find((entry) => entry.frontmatter.name === name);
+        if (!skill) throw new Error("Unknown ADS skill name.");
+        const uri = `${skill.uri.slice(0, -"SKILL.md".length)}${file.split("/").map(encodeURIComponent).join("/")}`;
+        const manifest = skill.resources.find((resource) => resource.uri === uri);
+        if (!manifest) throw new Error("Unknown relative skill file. Consult its manifest with native skills/get or the resources catalog.");
+        const content = skills.read(uri);
+        if (!("text" in content)) return json({ ...manifest, mimeType: content.mimeType, binary: true, note: "Read binary bytes via resources/read; this tool does not embed them." });
+        return json({ ...manifest, text: content.text.slice(offset, offset + limit), offset, ...(offset + limit < content.text.length ? { nextOffset: offset + limit } : {}) });
+      } },
+      { name: "ads_show_tokens", description: "Render an exact discovered token scenario with its project-owned templates and fixtures. Pass its id as category, discovered through ads_tokens.categories or ads_scenarios(kind: tokens). Omit category for the first project token scenario, or a generic definition inspector for older compilers.", schema: z.object({ category: z.string().max(256).optional() }).strict(), _meta: { ui: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI } }, call: async ({ category }, signal) => {
+        if (!category && options.config.mcp.previewManifest) category = tokenScenarios()[0]?.id;
+        if (!category && options.config.mcp.previewManifest) throw new Error("No token scenario is registered. Colocate a token scenario and fixture before opening the preview; ads_tokens still inspects definitions.");
+        if (category) {
+          const entry = getRegistry().scenarios.find(item => item.kind === "tokens" && item.id === category);
+          if (!entry) throw new Error("Unknown token scenario. Discover categories with ads_tokens or ads_scenarios(kind: tokens) first.");
+          if (getRegistry().diagnostics.length) throw new Error("Scenario registry has errors. Fix its diagnostics before reviewing.");
+          const app = scenarioApps().find(item => item.id === category);
+          const build = await previewBuild(app, signal);
+          const graph = graphSelection(category);
+          if (!options.config.mcp.previewManifest) projectApp(options, app, build);
+          const url = getShowcaseUrl() ? new URL(getShowcaseUrl()) : null;
+          url?.searchParams.delete("scenario");
+          url?.searchParams.set("category", category);
+          return json({ widget: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI }, category, scenario: { ...entry, resourceUri: appUri(category) }, ...graph, build, showcaseUrl: url?.href ?? null });
+        }
+        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 }) => {
+        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 } : {}) })) });
+      } },
+      { 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.",
+        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) => {
+          const result = await edits.apply(args, signal);
+          if (result.applied) {
+            try {
+              if (result.unit === "configuration") await previewWatch?.reconfigure?.(loadConfig(root).config.mcp, true);
+              await refresh(true);
+            }
+            catch (error) { result.warnings = [...(result.warnings ?? []), { rule: "mutation-notification", message: `Changes were applied, but preview refresh failed: ${error.message.slice(0, 2000)}. Recheck ads_status and reopen the scenario.` }]; }
+          }
+          return { ...json(result), ...(!result.ok ? { isError: true } : {}) };
+        },
+      }] : []),
+      ...options.config.mcp.apps.map((app) => ({ name: `ads_show_${app.id.replaceAll("-", "_")}`, description: `${app.description ?? app.title}. Renders the project's built ${app.kind} examples through MCP Apps; text fallback provides the showcase URL.`, schema: empty, _meta: { ui: { resourceUri: appUri(app.id) } }, call: async (_args, signal) => {
+        // Validate readiness without embedding executable HTML in model results.
+        const build = await previewBuild(app, signal);
+        projectApp(options, app);
+        return json({ widget: { resourceUri: appUri(app.id) }, title: app.title, kind: app.kind, build, showcaseUrl: getShowcaseUrl() });
+      } })),
+    ];
+  }
+  server.setRequestHandler("tools/list", ({ params = {} }) => {
+    previewWatch?.start();
+    const { cursor } = params;
+    const listing = page(tools().map(({ schema, call: _call, ...tool }) => ({ ...tool, inputSchema: z.toJSONSchema(schema), annotations: tool.annotations ?? annotations })), cursor, "tools");
+    return { tools: listing.items, ...(listing.nextCursor ? { nextCursor: listing.nextCursor } : {}) };
+  });
+  server.setRequestHandler("tools/call", async ({ params: { name, arguments: args } }, context) => {
+    const tool = tools().find((entry) => entry.name === name);
+    if (!tool) throw new InvalidParamsError("Unknown ADS tool.");
+    const input = tool.schema.safeParse(args ?? {});
+    if (!input.success) throw new InvalidParamsError(input.error.message);
+    previewWatch?.start();
+    try { return await tool.call(input.data, context.mcpReq.signal); }
+    catch (error) { return { isError: true, content: [{ type: "text", text: error.message }], ...(error.build ? { structuredContent: { message: error.message, build: error.build } } : {}) }; }
+  });
+  server.setRequestHandler("resources/list", ({ params = {} }) => {
+    previewWatch?.start();
+    const { cursor } = params;
+    const listing = page(resources(), cursor, "resources");
+    return { resources: listing.items, ...(listing.nextCursor ? { nextCursor: listing.nextCursor } : {}) };
+  });
+  server.setRequestHandler("resources/templates/list", () => ({ resourceTemplates: [] }));
+  server.setRequestHandler("resources/read", ({ params: { uri } }, context) => read(uri, context.mcpReq.signal));
+  server.setRequestHandler("resources/subscribe", ({ params: { uri } }) => {
+    if (!resources().some((entry) => entry.uri === uri)) throw new ResourceNotFoundError(uri, "Unknown ADS resource subscription.");
+    subscribed.add(uri); return {};
+  });
+  server.setRequestHandler("resources/unsubscribe", ({ params: { uri } }) => { subscribed.delete(uri); return {}; });
+  server.setRequestHandler("prompts/list", () => ({ prompts: promptDefinitions(skills.skills) }));
+  server.setRequestHandler("prompts/get", ({ params: { name, arguments: args } }) => {
+    try { return getWorkflowPrompt(name, args, skills.skills); } catch (error) { throw new InvalidParamsError(error.message); }
+  });
+  if (era === "modern") {
+    server.setRequestHandler("skills/list", schemas, ({ cursor }) => {
+      const listing = page(skills.skills, cursor, "skills", 2);
+      return { resultType: "complete", ttlMs: 300000, cacheScope: "public", skills: listing.items, ...(listing.nextCursor ? { nextCursor: listing.nextCursor } : {}) };
+    });
+    server.setRequestHandler("skills/get", { ...schemas, params: z.object({ uri: z.string() }).passthrough() }, ({ uri }) => {
+      try { return { resultType: "complete", ttlMs: 300000, cacheScope: "public", skill: skills.get(uri) }; } catch (error) { throw new InvalidParamsError(error.message); }
+    });
+    server.setRequestHandler("resources/directory/read", { ...schemas, params: z.object({ uri: z.string(), cursor: z.string().optional() }).passthrough() }, ({ uri, cursor }) => {
+      const children = skills.directories.get(uri);
+      if (!children) throw new ResourceNotFoundError(uri, "Unknown skill directory (no trailing slash).");
+      const listing = page(children, cursor, "directory");
+      return { resultType: "complete", resources: listing.items, ...(listing.nextCursor ? { nextCursor: listing.nextCursor } : {}) };
+    });
+  }
+
+  function fileFingerprint(files) {
+    return files.sort().map((file) => {
+      try { const stat = statSync(file); return `${file}:${stat.mtimeMs}:${stat.size}`; } catch { return `${file}:missing`; }
+    }).join("\n");
+  }
+  const fingerprint = () => fileFingerprint([...sourceFiles(options.dsRoot), ...getDocuments().map((doc) => doc.file), path.join(root, "ds.config.json"), path.join(root, "package.json")]);
+  const artifactFingerprint = () => fileFingerprint(allApps().map(app => path.resolve(root, app.file)));
+  const assetFingerprint = () => resourceAssets().map(asset => asset.uri).sort().join("\n");
+  let previous = fingerprint();
+  let previousArtifacts = artifactFingerprint();
+  let previousAssets = assetFingerprint();
+  let previousBuild = JSON.stringify(builds());
+  async function refresh(force = false) {
+    // Polling covers replaced files and new directories consistently across OSes.
+    cache.documents = undefined;
+    const next = fingerprint();
+    const artifacts = artifactFingerprint();
+    const assets = assetFingerprint();
+    const build = JSON.stringify(builds());
+    const filesChanged = force || next !== previous;
+    const buildChanged = build !== previousBuild;
+    const artifactsChanged = artifacts !== previousArtifacts;
+    const assetsChanged = assets !== previousAssets;
+    if (!filesChanged && !buildChanged && !artifactsChanged && !assetsChanged) return false;
+    if (filesChanged) {
+      const updated = loadConfig(root);
+      await previewWatch?.reconfigure?.(updated.config.mcp);
+      const appsChanged = JSON.stringify(updated.config.mcp.apps) !== JSON.stringify(options.config.mcp.apps) || updated.config.mcp.previewManifest !== options.config.mcp.previewManifest;
+      options = updated;
+      cache.signature = `${root}:${JSON.stringify(options.config)}`;
+      cache.catalog = undefined;
+      cache.registry = undefined;
+      previous = fingerprint();
+      if (appsChanged) { if (notifications) notifications.toolsChanged(); else await server.sendToolListChanged(); }
+    }
+    if (filesChanged || assetsChanged) { if (notifications) notifications.resourcesChanged(); else await server.sendResourceListChanged(); }
+    previousArtifacts = artifactFingerprint();
+    previousAssets = assetFingerprint();
+    previousBuild = JSON.stringify(builds());
+    const targets = filesChanged ? era === "modern" ? resources().map((entry) => entry.uri).filter((uri) => !skills.files.has(uri)) : [...subscribed]
+      : [BUILD_URI, `${PROJECT_URI}/status`, ...(options.config.mcp.previewManifest ? [PREVIEW_MANIFEST_URI] : []), ...(artifactsChanged ? allApps().map(app => appUri(app.id)) : [])].filter((uri) => era === "modern" || subscribed.has(uri));
+    for (const uri of targets) { if (notifications) notifications.resourceUpdated(uri); else await server.sendResourceUpdated({ uri }); }
+    return true;
+  }
+  const timer = pollInterval > 0 ? setInterval(() => { refresh().catch((error) => process.stderr.write(`ads mcp: ${error.message}\n`)); }, pollInterval) : null;
+  timer?.unref();
+  server.oninitialized = () => previewWatch?.start();
+  server.onclose = () => { if (timer) clearInterval(timer); };
+  return { server, refresh, async close() { if (timer) clearInterval(timer); await server.close(); } };
+}
+
+export async function startAdsMcp(directory = process.cwd(), { stdio = true, showcase = true, port = 0, mutations = false } = {}) {
+  // Fail before opening the transport for configuration/distribution errors.
+  const { root, config } = loadConfig(directory);
+  const inspection = { skills: createSkillStore() };
+  const previewWatch = createReconfigurablePreviewWatch(root, config.mcp);
+  let host;
+  const showcaseUrl = () => host?.url;
+  if (showcase) {
+    host = await startShowcaseHost(({ era }) => createAdsMcp(directory, { era, previewWatch, showcaseUrl, inspection, mutations, pollInterval: 0 }).server,
+      { port, observe: notifications => createAdsMcp(directory, { era: "modern", previewWatch, showcaseUrl, inspection, mutations, notifications }) });
+    process.stderr.write(`ADS showcase: ${host.url}\n`);
+  }
+  const handle = stdio ? serveStdio(({ era }) => createAdsMcp(directory, { era, previewWatch, showcaseUrl, inspection, mutations }).server, { legacy: "serve", onerror: (error) => process.stderr.write(`ads mcp: ${error.message}\n`) }) : null;
+  let closing;
+  function close() {
+    return closing ??= (async () => {
+      inspection.edits?.cancel();
+      await host?.close();
+      await previewWatch.stop();
+      await handle?.close();
+      process.stdin.removeListener("end", disconnect);
+      for (const signal of ["SIGINT", "SIGTERM"]) process.removeListener(signal, disconnect);
+      process.removeListener("exit", forceCleanup);
+    })();
+  }
+  function disconnect() { void close(); }
+  function forceCleanup() { previewWatch.kill(); }
+  // Probe instances have no managed child; a real connection activates it.
+  // stdin EOF also cleans up the compiler when the host drops the transport.
+  if (stdio) process.stdin.once("end", disconnect);
+  for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, disconnect);
+  process.once("exit", forceCleanup);
+  return { close, url: host?.url };
+}