@reqvire-org/ads 0.3.0 → 0.3.2

package/dist/contracts/foundation.json

@@ -0,0 +1,211 @@
+{
+  "document": [
+    "color",
+    "background",
+    "background-color",
+    "font",
+    "font-family",
+    "font-size",
+    "font-weight",
+    "font-style",
+    "font-stretch",
+    "line-height",
+    "letter-spacing",
+    "word-spacing",
+    "text-rendering",
+    "font-synthesis",
+    "font-kerning",
+    "font-feature-settings",
+    "font-variation-settings",
+    "font-optical-sizing",
+    "-webkit-font-smoothing",
+    "-moz-osx-font-smoothing",
+    "-webkit-text-size-adjust",
+    "text-size-adjust",
+    "color-scheme",
+    "scrollbar-color",
+    "scrollbar-width"
+  ],
+  "reset": {
+    "box-sizing": [
+      "border-box",
+      "content-box"
+    ],
+    "font": [
+      "inherit"
+    ],
+    "font-family": [
+      "inherit"
+    ],
+    "font-size": [
+      "inherit",
+      "100%"
+    ],
+    "font-weight": [
+      "inherit",
+      "bolder",
+      "lighter"
+    ],
+    "font-style": [
+      "inherit",
+      "normal"
+    ],
+    "line-height": [
+      "inherit",
+      "normal"
+    ],
+    "letter-spacing": [
+      "inherit",
+      "normal"
+    ],
+    "word-spacing": [
+      "inherit",
+      "normal"
+    ],
+    "text-align": [
+      "inherit",
+      "start"
+    ],
+    "text-transform": [
+      "inherit",
+      "none"
+    ],
+    "text-decoration": [
+      "inherit",
+      "none"
+    ],
+    "text-indent": [
+      "0"
+    ],
+    "color": [
+      "inherit",
+      "currentcolor"
+    ],
+    "background": [
+      "transparent",
+      "none"
+    ],
+    "background-color": [
+      "transparent"
+    ],
+    "border": [
+      "0",
+      "none"
+    ],
+    "border-width": [
+      "0"
+    ],
+    "border-style": [
+      "none"
+    ],
+    "border-color": [
+      "inherit",
+      "currentcolor",
+      "transparent"
+    ],
+    "border-radius": [
+      "0"
+    ],
+    "border-collapse": [
+      "collapse",
+      "separate"
+    ],
+    "border-spacing": [
+      "0"
+    ],
+    "list-style": [
+      "none"
+    ],
+    "list-style-type": [
+      "none"
+    ],
+    "list-style-image": [
+      "none"
+    ],
+    "vertical-align": [
+      "baseline",
+      "middle"
+    ],
+    "box-shadow": [
+      "none"
+    ],
+    "text-shadow": [
+      "none"
+    ],
+    "appearance": [
+      "none",
+      "auto"
+    ],
+    "-webkit-appearance": [
+      "none",
+      "auto"
+    ],
+    "overflow": [
+      "visible"
+    ],
+    "cursor": [
+      "inherit",
+      "default"
+    ],
+    "-webkit-tap-highlight-color": [
+      "transparent"
+    ]
+  },
+  "replacedElements": [
+    "img",
+    "svg",
+    "video",
+    "canvas",
+    "audio",
+    "iframe",
+    "embed",
+    "object"
+  ],
+  "replacedReset": {
+    "display": [
+      "block",
+      "inline-block"
+    ],
+    "max-width": [
+      "100%"
+    ],
+    "width": [
+      "auto"
+    ],
+    "height": [
+      "auto"
+    ]
+  },
+  "focus": [
+    "outline",
+    "outline-width",
+    "outline-style",
+    "outline-color",
+    "outline-offset"
+  ],
+  "reducedMotion": [
+    "animation-duration",
+    "animation-delay",
+    "animation-iteration-count",
+    "transition-duration",
+    "transition-delay",
+    "scroll-behavior"
+  ],
+  "selection": [
+    "color",
+    "background",
+    "background-color"
+  ],
+  "scrollbar": [
+    "width",
+    "height",
+    "background",
+    "background-color",
+    "background-clip",
+    "border",
+    "border-width",
+    "border-style",
+    "border-color",
+    "border-radius"
+  ]
+}

package/dist/foundation.mjs

@@ -0,0 +1,114 @@
+import selectorParser from "postcss-selector-parser";
+import { readFileSync } from "node:fs";
+
+// CSS-language policy, not a project token catalogue or renderer classification.
+const policy = JSON.parse(readFileSync(new URL("./contracts/foundation.json", import.meta.url), "utf8"));
+const cssWide = /^(?:inherit|initial|unset|revert|revert-layer)$/i;
+
+function rootAnchor(nodes) {
+  return nodes.some(node => node.type === "tag" && !node.namespace && node.value.toLowerCase() === "html"
+    || node.type === "pseudo" && node.value.toLowerCase() === ":root"
+    || node.type === "pseudo" && /^:(?:is|where)$/i.test(node.value) && node.nodes.length && node.nodes.every(selector => !selector.nodes.some(node => node.type === "combinator") && rootAnchor(selector.nodes)));
+}
+
+function rootCompound(node) {
+  for (let current = node; current.parent; current = current.parent) {
+    const parent = current.parent;
+    if (parent.type !== "selector") continue;
+    const index = parent.nodes.indexOf(current);
+    let start = index, end = index + 1;
+    while (start && parent.nodes[start - 1].type !== "combinator") --start;
+    while (end < parent.nodes.length && parent.nodes[end].type !== "combinator") ++end;
+    // A negative/relational argument cannot establish root context, but an
+    // explicit root outside it still can: :root:not([data-theme=light]).
+    const argument = parent.parent?.type === "pseudo" && !/^:(?:is|where)$/i.test(parent.parent.value);
+    if (!argument && rootAnchor(parent.nodes.slice(start, end))) return true;
+  }
+  return false;
+}
+
+/** Global defaults may address native elements and explicit document themes, not UI owners. */
+export function foundationSelector(selector, { definitions = false } = {}) {
+  try {
+    let violation = false;
+    selectorParser(root => {
+      if (definitions && root.nodes.some(selector => selector.nodes.some(node => node.type === "combinator") || !rootAnchor(selector.nodes))) violation = true;
+      root.walk(node => {
+        if (["class", "id"].includes(node.type) && !rootCompound(node)) violation = true;
+        if (node.type === "tag" && node.value.includes("-")) violation = true;
+        if (node.type === "attribute" && /^(?:class|id|style|data-.+|aria-.+)$/i.test(node.attribute) && !rootCompound(node)) violation = true;
+        if (node.type === "pseudo" && node.value.toLowerCase() === ":has") violation = true;
+        if (node.type === "combinator") {
+          const before = node.parent.nodes.slice(0, node.parent.nodes.indexOf(node));
+          if (before.some(node => node.type === "combinator") || !rootAnchor(before)) violation = true;
+        }
+      });
+    }).processSync(selector);
+    return violation ? "Foundation defaults address native elements or explicit document-root themes. Component/pattern hooks, contextual layout and relational state selectors belong to their Linaria owner." : null;
+  } catch (error) { return `Invalid foundation selector: ${error.message}`; }
+}
+
+function subjects(nodes) {
+  let variants = [[]];
+  for (const node of nodes) {
+    if (node.type === "pseudo" && /^:(?:where|is)$/i.test(node.value)) {
+      variants = variants.flatMap(prefix => node.nodes.flatMap(selector => subjects(selector.nodes).map(subject => [...prefix, ...subject])));
+    } else variants.forEach(subject => subject.push(node));
+  }
+  return variants;
+}
+
+function reducedMotion(rule) {
+  for (let parent = rule.parent; parent; parent = parent.parent) {
+    if (parent.type === "atrule" && parent.name.toLowerCase() === "media"
+      && /^\(\s*prefers-reduced-motion\s*:\s*reduce\s*\)$/i.test(parent.params.trim())) return true;
+  }
+  return false;
+}
+
+function reset(property, value, nodes) {
+  const words = value.toLowerCase().split(/\s+/);
+  if (/^(?:margin|padding)(?:-(?:top|right|bottom|left|block|inline)(?:-(?:start|end))?)?$/.test(property)) return words.every(word => word === "0") || cssWide.test(value);
+  const tag = nodes.find(node => node.type === "tag")?.value.toLowerCase();
+  if (property === "font-weight" && /^(?:bolder|lighter)$/.test(value)) return ["b", "strong"].includes(tag);
+  if (policy.reset[property]) return policy.reset[property].includes(value.toLowerCase()) || cssWide.test(value);
+  if (policy.replacedElements.includes(tag) && policy.replacedReset[property]) return policy.replacedReset[property].includes(value.toLowerCase()) || cssWide.test(value);
+  return tag === "textarea" && property === "resize" && /^(?:vertical|inherit|initial|unset|revert(?:-layer)?)$/.test(value);
+}
+
+function roleAllows(rule, nodes, property, value) {
+  const pseudos = nodes.filter(node => node.type === "pseudo");
+  const tag = nodes.find(node => node.type === "tag")?.value.toLowerCase();
+  const universal = nodes.every(node => node.type === "universal" || node.type === "pseudo" || node.type === "comment");
+  if (universal && pseudos.some(node => node.value === ":focus-visible") && pseudos.every(node => node.value === ":focus-visible")) return policy.focus.includes(property) && !/^(?:none|0)$/.test(value);
+  if (universal && pseudos.some(node => node.value === "::selection") && pseudos.every(node => node.value === "::selection")) return policy.selection.includes(property);
+  if (universal && pseudos.every(node => ["::before", "::after"].includes(node.value)) && reducedMotion(rule)) {
+    if (policy.reducedMotion.includes(property)) return property !== "scroll-behavior" || value === "auto";
+    if (["animation", "transition"].includes(property) && value === "none") return true;
+  }
+  const document = (rootAnchor(nodes) || tag === "body") && pseudos.every(node => [":root", ":not"].includes(node.value));
+  if (document && policy.document.includes(property)) return true;
+  const documentScrollbar = (rootAnchor(nodes) || tag === "body") && pseudos.some(node => /^::-webkit-scrollbar(?:-thumb|-track)?$/.test(node.value))
+    && pseudos.every(node => node.value === ":root" || /^::-webkit-scrollbar(?:-thumb|-track)?$/.test(node.value) || node.value === ":hover");
+  if (documentScrollbar) return policy.scrollbar.includes(property);
+  if (pseudos.some(node => node.value === "::placeholder") && pseudos.every(node => node.value === "::placeholder")) return property === "color" || property === "opacity" && value === "1";
+  if (pseudos.some(node => ![":root", ":not", "::before", "::after"].includes(node.value))) return false;
+  if (pseudos.some(node => node.value === ":not") && !rootAnchor(nodes)) return false;
+  return reset(property, value, nodes);
+}
+
+/** Closed foundation roles apply even when a native selector uses valid tokens. */
+export function foundationDeclaration(rule, declaration) {
+  try {
+    const selectors = selectorParser().astSync(rule.selector);
+    const property = declaration.prop.toLowerCase(), value = declaration.value.trim();
+    for (const selector of selectors.nodes) {
+      const lastCombinator = selector.nodes.findLastIndex(node => node.type === "combinator");
+      for (let nodes of subjects(selector.nodes.slice(lastCombinator + 1))) {
+        nodes = nodes.slice(nodes.findLastIndex(node => node.type === "combinator") + 1);
+        if (!roleAllows(rule, nodes, property, value)) return "base.css permits document-root/body typography and canvas defaults, limited native normalization, global focus indicators and reduced-motion rules. Put control skins, layout and state styling in their Linaria owner.";
+      }
+    }
+    return null;
+  } catch (error) { return `Invalid foundation declaration context: ${error.message}`; }
+}

package/dist/init.mjs

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, writeFileSync, chmodSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import ts from "typescript";
 import { isInside, loadConfig, sourceFiles, supportedFrameworks } from "./config.mjs";
 import { createLintConfig } from "./lint-config.mjs";
 import { foundationFiles } from "./token-policy.mjs";
@@ -152,10 +153,16 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
   });
   if (!existingTokens.length) {
     for (const name of ["Foundation.scenario.tsx", "Foundation.fixture.ts"]) {
-      let content = readFileSync(path.join(starter, "design-system/tokens", name), "utf8");
-      if (selectedFramework === "preact" && name === "Foundation.scenario.tsx") content = content.replace('from "react"', 'from "preact/hooks"');
+      const content = readFileSync(path.join(starter, "design-system/tokens", name), "utf8").replaceAll('"@ds"', JSON.stringify(config.publicAlias));
       addMissing(path.join(tokenRoot, name), content);
     }
+    for (const name of ["TokenPreview.tsx", "Scenario.tsx", "fixture.ts"]) {
+      let content = readFileSync(path.join(starter, "design-system/patterns/token-preview", name), "utf8");
+      if (selectedFramework === "preact") content = content.replace('from "react"', 'from "preact/hooks"');
+      addMissing(path.join(dsRoot, "patterns/token-preview", name), content.replaceAll('"@ds"', JSON.stringify(config.publicAlias)));
+    }
+    const reviewFile = path.relative(root, path.join(dsRoot, "patterns/token-preview/TokenPreview.tsx")).replaceAll("\\", "/");
+    if (!config.boundaries.styleWrites.some(item => item.file === reviewFile)) config.boundaries.styleWrites.push({ file: reviewFile, properties: ["--ux-token-preview-value"] });
   }
   tokenFiles.sort((a, b) => foundationFiles.indexOf(path.basename(a)) - foundationFiles.indexOf(path.basename(b)) || a.localeCompare(b));
   const stylesFile = path.join(dsRoot, config.stylesEntry);
@@ -165,7 +172,17 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
   };
   addMissing(stylesFile, tokenFiles.map((file) => `@import ${JSON.stringify(relativeImport(stylesFile, file))};`).join("\n") + "\n");
   const entryFile = path.join(dsRoot, config.publicEntry);
-  addMissing(entryFile, `// Export your project's public components and types here.\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\nexport {};\n`);
+  const reviewExport = !existingTokens.length ? `export { TokenPreview } from ${JSON.stringify(relativeImport(entryFile, path.join(dsRoot, "patterns/token-preview/TokenPreview")))};\n` : "";
+  addMissing(entryFile, `// Export your project's public components and types here.\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\n${reviewExport}`);
+  if (reviewExport && existsSync(entryFile) && !readFileSync(entryFile, "utf8").includes("patterns/token-preview/TokenPreview")) {
+    let current = readFileSync(entryFile, "utf8");
+    if (/\bTokenPreview\b/.test(current)) throw new Error("TokenPreview is already owned by this project. Add a token review scenario using its public API before initializing the foundation.");
+    const ast = ts.createSourceFile(entryFile, current, ts.ScriptTarget.Latest, true);
+    for (const statement of [...ast.statements].reverse()) if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause) && !statement.exportClause.elements.length) {
+      current = current.slice(0, statement.getStart(ast)) + current.slice(statement.end);
+    }
+    updates.set(entryFile, current + "\n" + reviewExport);
+  }
   for (const section of ["components", "patterns", "composition"]) addMissing(path.join(dsRoot, section, ".gitkeep"), "");
   addMissing(path.join(dsRoot, "assets/brand/README.md"), readFileSync(path.join(starter, "design-system/assets/brand/README.md")));
   addMissing(path.join(dsRoot, "assets/fonts/.gitkeep"), "");
@@ -175,9 +192,9 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
   else {
     const original = readFileSync(configFile, "utf8");
     const saved = JSON.parse(original);
-    if (saved.framework === undefined) {
+    if (saved.framework === undefined || !existingTokens.length) {
       const indent = original.match(/\n([\t ]+)"/)?.[1] ?? "  ";
-      updates.set(configFile, `${JSON.stringify({ ...saved, framework: selectedFramework }, null, indent)}\n`);
+      updates.set(configFile, `${JSON.stringify({ ...saved, framework: selectedFramework, ...(!existingTokens.length ? { boundaries: config.boundaries } : {}) }, null, indent)}\n`);
     }
   }
   const lintConfigFile = path.join(root, ".ds/oxlintrc.json");

package/dist/mcp/apps.mjs

@@ -12,7 +12,7 @@ const bridge = (project = false) => readFileSync(new URL(project ? "./project-wi
 
 export function previewApp(selection) {
   const script = readFileSync(new URL("./preview-widget.bundle.js", import.meta.url), "utf8").replaceAll("</script", "<\\/script");
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>ADS preview</title><style>html,body,#root{height:100%;margin:0}body{overflow:hidden}#ads-preview-status{position:fixed;inset:12px 12px auto;z-index:2147483647;padding:12px;border:1px solid GrayText;background:Canvas;color:CanvasText;font:13px system-ui;white-space:pre-wrap}#ads-preview-status[hidden]{display:none}</style></head><body><aside id="ads-preview-status" role="status" hidden></aside><div id="root"></div>${selection ? `<script type="application/json" id="ads-preview-selection">${safeJson(selection)}</script>` : ""}<script type="module">${script}</script></body></html>`;
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>ADS preview</title><style>html,body,#root{height:100%;margin:0}body{overflow:auto}#ads-preview-status{position:fixed;inset:12px 12px auto;z-index:2147483647;padding:12px;border:1px solid GrayText;background:Canvas;color:CanvasText;font:13px system-ui;white-space:pre-wrap}#ads-preview-status[hidden]{display:none}</style></head><body><aside id="ads-preview-status" role="status" hidden></aside><div id="root"></div>${selection ? `<script type="application/json" id="ads-preview-selection">${safeJson(selection)}</script>` : ""}<script type="module">${script}</script></body></html>`;
 }
 
 export function tokenWidgetData(inventory) {
@@ -44,7 +44,7 @@ export function projectApp(options, app, build) {
   if (statSync(file).size > 2 * 1024 * 1024) throw new Error("Preview exceeds 2 MiB. Build a focused component/pattern example.");
   const html = readFileSync(file, "utf8");
   if (!/<\/body\s*>/i.test(html) || /<script\b[^>]*\bsrc\s*=|<link\b[^>]*\brel\s*=\s*["']?stylesheet\b/i.test(html)) throw new Error("Preview must be built as self-contained HTML, with JavaScript and styles inlined.");
-  const seed = { id: app.id, session: build?.session ?? null, revision: build?.current ? build.revision : null, state: build?.state ?? "unreported" };
+  const seed = { id: app.id, kind: app.kind, ...(app.samples ? { samples: app.samples } : {}), session: build?.session ?? null, revision: build?.current ? build.revision : null, state: build?.state ?? "unreported" };
   return html.replace(/<\/body\s*>/i, () => `<script type="application/json" id="ads-preview-seed">${safeJson(seed)}</script><script type="module">${bridge(true)}</script></body>`);
 }
 

package/dist/mcp/build-status.mjs

@@ -8,9 +8,9 @@ import { readPreviewManifest } from "../preview-resources.mjs";
 export const BUILD_URI = "ads://project/build";
 export const buildStatusFile = (root) => path.join(root, ".ds/build-status.json");
 const maxBytes = 256 * 1024;
-const diagnostic = z.object({ message: z.string().max(4000), file: z.string().max(1000).optional(), line: z.number().int().positive().optional(), column: z.number().int().positive().optional(), plugin: z.string().max(200).optional() }).strict();
+const diagnostic = z.object({ message: z.string().max(4000), file: z.string().max(1000).optional(), line: z.number().int().positive().optional(), column: z.number().int().positive().optional(), plugin: z.string().max(200).optional(), code: z.string().max(100).optional() }).strict();
 const preview = z.object({ id: z.string().max(256), state: z.enum(["idle", "building", "ready", "error"]), revision: z.number().int().nonnegative(), lastSuccessfulRevision: z.number().int().positive().nullable(), artifactDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(), diagnostics: z.array(diagnostic).max(20), diagnosticSet: z.number().int().nonnegative().optional() }).strict();
-const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), previews: z.array(preview), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
+const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), previews: z.array(preview), diagnostics: z.array(diagnostic).max(20).optional(), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
 export const artifactDigest = (file) => {
   if (realpathSync(file) !== file) throw new Error("Preview output cannot resolve through a symlink.");
   if (statSync(file).size > 2 * 1024 * 1024) throw new Error("Preview exceeds 2 MiB.");
@@ -26,7 +26,7 @@ function normalizeDiagnostic(root, error) {
   return { message: String(error?.message ?? error).slice(0, 4000),
     ...(file ? { file: (path.isAbsolute(file) ? path.relative(root, file) : file).replaceAll("\\", "/").slice(0, 1000) } : {}),
     ...(Number.isInteger(line) && line > 0 ? { line } : {}), ...(Number.isInteger(column) && column > 0 ? { column } : {}),
-    ...(typeof error?.plugin === "string" ? { plugin: error.plugin.slice(0, 200) } : {}) };
+    ...(typeof error?.plugin === "string" ? { plugin: error.plugin.slice(0, 200) } : {}), ...(typeof error?.code === "string" ? { code: error.code.slice(0, 100) } : {}) };
 }
 
 /** One publisher per project compiler; no dependency on a UI framework. */
@@ -36,8 +36,9 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
   if (!isInside(root, target)) throw new Error("Build status must stay inside the project.");
   const entries = new Map(apps.map((app) => [app.id, { id: app.id, state: "idle", revision: 0, lastSuccessfulRevision: null, artifactDigest: null, diagnostics: [] }]));
   let sequence = 0;
+  let diagnostics = [];
   function save() {
-    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()] };
+    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()], ...(diagnostics.length ? { diagnostics } : {}) };
     let text = JSON.stringify(snapshot.parse(value));
     // A shared graph failure applies to every scenario. Store repeated details
     // once only when necessary; ordinary reports retain inline diagnostics.
@@ -66,6 +67,17 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
   save();
   return {
     session,
+    failure(error) {
+      diagnostics = (Array.isArray(error) ? error : [error]).slice(0, 20).map(error => normalizeDiagnostic(root, error));
+      for (const value of entries.values()) { value.state = "error"; ++value.revision; value.diagnostics = []; }
+      save();
+    },
+    clearFailure() {
+      if (!diagnostics.length) return;
+      diagnostics = [];
+      for (const value of entries.values()) if (value.state === "error" && !value.diagnostics.length) value.state = "idle";
+      save();
+    },
     setApps(next) {
       const ids = new Set(next.map(app => app.id));
       for (const id of entries.keys()) if (!ids.has(id)) entries.delete(id);
@@ -104,11 +116,11 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
 }
 
 /** Read durable build events; a running process alone never means a fresh build. */
-export function inspectBuildStatus(root, config, { session, processState } = {}) {
+export function inspectBuildStatus(root, config, { session, processState, file = buildStatusFile(root) } = {}) {
   let report;
   let reportError;
-  const file = buildStatusFile(root);
   try {
+    if (!isInside(root, path.resolve(file))) throw new Error("Build status must stay inside the project.");
     if (existsSync(file)) {
       if (realpathSync(file) !== file || statSync(file).size > maxBytes) throw new Error("Build status must be a real project file under 256 KiB.");
       report = snapshot.parse(JSON.parse(readFileSync(file, "utf8")));
@@ -125,6 +137,7 @@ export function inspectBuildStatus(root, config, { session, processState } = {})
     const value = report?.previews.find((entry) => entry.id === app.id);
     let state = value?.state ?? "unreported";
     let diagnostics = value?.diagnosticSet !== undefined ? report.diagnosticSets[value.diagnosticSet] : value?.diagnostics ?? [];
+    if (report?.diagnostics?.length) { state = "error"; diagnostics = [...report.diagnostics, ...diagnostics].slice(0, 20); }
     const available = existsSync(path.resolve(root, app.file));
     if (reportError) { state = "error"; diagnostics = [{ message: reportError }]; }
     if (graphError && app.id.includes("/")) { state = "error"; diagnostics = [{ message: graphError }]; }
@@ -139,8 +152,8 @@ export function inspectBuildStatus(root, config, { session, processState } = {})
     return { id: app.id, state, session: report?.session ?? null, revision: value?.revision ?? null, lastSuccessfulRevision: value?.lastSuccessfulRevision ?? null,
       current, stale: state === "unreported" ? null : !current, available, diagnostics };
   });
-  const state = previews.some((entry) => entry.state === "error") ? "error" : previews.some((entry) => entry.state === "building") ? "building" : previews.some((entry) => entry.state === "unreported") ? "unreported" : previews.some(entry => entry.current) ? "ready" : previews.length ? "idle" : "disabled";
-  return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, previews, resourceUri: BUILD_URI };
+  const state = reportError || report?.diagnostics?.length || previews.some((entry) => entry.state === "error") ? "error" : previews.some((entry) => entry.state === "building") ? "building" : previews.some((entry) => entry.state === "unreported") ? "unreported" : previews.some(entry => entry.current) ? "ready" : previews.length ? "idle" : "disabled";
+  return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, previews, ...(report?.diagnostics?.length ? { diagnostics: report.diagnostics } : {}), resourceUri: BUILD_URI };
 }
 
 export class PreviewBuildError extends Error {
@@ -154,7 +167,7 @@ export function summarizeBuild(build) {
     return { ...value, diagnostics, diagnosticCount: value.diagnostics.length,
       diagnosticsTruncated: value.diagnostics.length > 3 || value.diagnostics.some((entry) => entry.message.length > 1000) };
   }
-  return build.previews ? { ...build, previews: build.previews.map(bounded) } : { ...bounded(build), resourceUri: BUILD_URI };
+  return build.previews ? { ...build, ...(build.diagnostics ? bounded(build) : {}), previews: build.previews.map(bounded) } : { ...bounded(build), resourceUri: BUILD_URI };
 }
 
 export function buildFailure(build) {

package/dist/mcp/context.mjs

@@ -56,7 +56,7 @@ Use this server for UI components/patterns, tokens/themes/branding, layout, inte
 3. Select one workflow with ads_skills, then ads_read_skill. ${route.skills.map((skill) => `${skill.task}: ${skill.name}`).join("; ")}. Native skill activation is host-controlled. Relative skill references resolve from its SKILL.md URI. Read support files only when relevant.
 4. ${route.preview} Token samples: ads_scenarios(kind: tokens), then ads_show_scenario or ads_show_tokens(category: id). Token source inspection: ads_tokens with a focused query. Registered previews: ${previews.map((preview) => `${preview.id}: ${preview.tool ?? "ads_show_scenario"}`).join(", ") || "none"}. Showcase URL: ${context.showcase.url ?? "not configured; use the project's showcase command"}.
    Inspection connects a public export to its owning source, available guides, token values and discovered preview IDs. Bounded tools keep discovery focused; explicit resource reads supply detail. Source metadata does not prove layout, interaction or motion. A scenario renders the real public implementation and its fixture context in either review surface.
-5. Check ads_status.mutations. When enabled, discover one owner with ads_units, read relevant source ranges with ads_read_file and submit only a Git unified diff through ads_apply_patch({unit, patch, dryRun}). Include that owner's scenarios, fixtures and required public re-exports, never peer units. tokens is the foundation unit. Dry-run to inspect validation; apply only a passing patch. Fix rejected patches in the owning unit. Intentional project setup, registered guard/compiler code and exceptions use configuration; shared globals use foundation, guides documentation and assets their discovered assets/* unit. Keep mandatory ADS gates. Binary/large Git diffs may use patchFile under .ds/patches/ to avoid model-context bytes. In read-only mode, source edits use the client editor/filesystem tools. Reuse the local public API (${context.publicEntry}). Edit presentation in its ADS owner; keep application data/services/routing in application code and development fixtures beside their scenario; larger scenarios live in composition/. Linaria extracts owned styling. Inspect relevant tokens with ads_tokens and source/owning guides before edits.
+5. Check ads_status.mutations. When enabled, discover one owner with ads_units, read relevant source ranges with ads_read_file and submit only a Git unified diff through ads_apply_patch({unit, patch, dryRun}). Include that owner's scenarios, fixtures and required public re-exports, never peer units. tokens is the foundation unit; its manifest lists companionFiles for required canonical foundation imports when token files are created/deleted in the same patch. Preserve unrelated imports/comments and public-entry statements, including export {};. Dry-run to inspect validation; apply only a passing patch. Fix rejected patches in the owning unit; report unsupported coupled changes instead of bypassing rejection with direct writes. Intentional project setup, registered guard/compiler code and exceptions use configuration; shared globals use foundation, guides documentation and assets their discovered assets/* unit. Keep mandatory ADS gates. Binary/large Git diffs may use patchFile under .ds/patches/ to avoid model-context bytes. In read-only mode, source edits use the client editor/filesystem tools. Reuse the local public API (${context.publicEntry}). Edit presentation in its ADS owner; keep application data/services/routing in application code and development fixtures beside their scenario; larger scenarios live in composition/. Linaria extracts owned styling. Inspect relevant tokens with ads_tokens and source/owning guides before edits.
 6. ${route.validation} Registered commands: ${context.commands.map((command) => command.args?.join(" ") ?? `choose the project package manager for ${command.script}`).join("; ") || "none discovered; inspect the project's build setup"}. Run them from ${context.projectRoot}.
 7. After edits, inspect ads_status.build or ads://project/build explicitly. Running/unreported/old output is not a current successful preview. Fix diagnostics in owned source, wait for rebuilding and invoke the preview tool again. Notifications may not start an agent turn.
 

package/dist/mcp/preview-watch.mjs

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { statSync, mkdirSync, writeFileSync, renameSync, rmSync, realpathSync } from "node:fs";
 import path from "node:path";
-import { buildFailure, buildStatusFile, inspectBuildStatus } from "./build-status.mjs";
+import { buildFailure, inspectBuildStatus } from "./build-status.mjs";
 
 function stamp(file) {
   try { const stat = statSync(file); return `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`; }
@@ -13,7 +13,7 @@ function stamp(file) {
 export function createPreviewWatch(root, config, { log = process.stderr, buildTimeout = 30000 } = {}) {
   config = { ...config, apps: [...config.apps] };
   const command = config.previewWatch;
-  const session = randomUUID();
+  let session = randomUUID();
   let state = command ? "idle" : "disabled";
   let child;
   let error;
@@ -21,11 +21,14 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
   let childClosed = false;
   let killTimer;
   let stopping;
+  let restarting;
+  let disposed = false;
   const baselines = new Map();
   const ready = new Set();
   const requests = new Set();
   let active;
-  const requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
+  let requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
+  let reportFile = path.join(root, ".ds", `build-status-${session}.json`);
   function request(file) {
     if (!command || requests.has(file) && active === file) return;
     requests.add(file);
@@ -48,7 +51,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     } catch (failure) { if (failure.code !== "ESRCH") throw failure; }
   }
   function start() {
-    if (state !== "idle") return;
+    if (disposed || state !== "idle") return;
     for (const app of config.apps) {
       const file = path.resolve(root, app.file);
       baselines.set(file, stamp(file));
@@ -57,7 +60,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     // No shell: configured arguments remain literal. Child stdin cannot consume
     // the MCP channel, and both output streams go exclusively to diagnostics.
     const executable = command.command === "node" ? process.execPath : command.command;
-    const env = { ...process.env, ADS_MCP_BUILD_SESSION: session, ADS_MCP_BUILD_STATUS: buildStatusFile(root), ADS_MCP_REQUEST_FILE: requestFile, PATH: [path.join(root, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) };
+    const env = { ...process.env, ADS_MCP_BUILD_SESSION: session, ADS_MCP_BUILD_STATUS: reportFile, ADS_MCP_REQUEST_FILE: requestFile, PATH: [path.join(root, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) };
     try {
       child = spawn(executable, command.args, { cwd: root, env, shell: false, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
     } catch (failure) {
@@ -76,7 +79,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
       clearTimeout(killTimer);
       if (state !== "stopping") {
         state = "failed";
-        error ??= `Preview watcher exited (${signal ?? code}). Restart MCP after fixing the configured command.`;
+        error ??= `Preview watcher exited (${signal ?? code}). Fix the builder and invoke the preview again to restart it; MCP inspection remains available.`;
         log.write(`ads mcp: ${error}\n`);
       } else state = "stopped";
       resolve();
@@ -91,16 +94,36 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     child.once("error", (failure) => { error = `Cannot start preview watcher: ${failure.message}`; });
   }
 
+  function restart() {
+    return restarting ??= (async () => {
+      await stopChild();
+      if (disposed) return;
+      session = randomUUID();
+      requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
+      reportFile = path.join(root, ".ds", `build-status-${session}.json`);
+      state = "idle"; error = undefined; child = closed = stopping = undefined; childClosed = false;
+      ready.clear(); baselines.clear(); active = undefined;
+      start();
+    })().finally(() => { restarting = undefined; });
+  }
+
   async function ensure(file, signal) {
+    if (signal?.aborted) throw new Error("Preview request cancelled.");
+    if (state === "failed" || restarting) await restart();
+    if (disposed) throw new Error("Preview watcher is stopped.");
     start();
     request(file);
     if (signal?.aborted) throw new Error("Preview request cancelled.");
     const app = config.apps.find((entry) => path.resolve(root, entry.file) === file);
-    const baseline = baselines.get(file) ?? null;
+    let baseline = baselines.get(file) ?? null;
     const deadline = Date.now() + buildTimeout;
+    let restarted = false;
     while (Date.now() < deadline) {
       if (signal?.aborted) throw new Error("Preview request cancelled.");
       const build = buildStatus().previews.find((entry) => entry.id === app?.id);
+      if (!restarted && build?.diagnostics.some(item => item.code === "ADS_PREVIEW_RESTART")) {
+        restarted = true; await restart(); request(file); baseline = baselines.get(file) ?? null; continue;
+      }
       if (build?.state === "error") throw buildFailure(build);
       if (command && state !== "running") throw new Error(error ?? "Preview watcher is stopped.");
       if (build?.current) return build;
@@ -113,23 +136,23 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
   }
 
   const status = () => ({ state, ...(child?.pid ? { pid: child.pid } : {}), ...(error ? { error } : {}) });
-  const buildStatus = () => inspectBuildStatus(root, config, command ? { session, processState: status() } : {});
+  const buildStatus = () => inspectBuildStatus(root, config, command ? { session, file: reportFile, processState: status() } : {});
 
-  async function stop() {
+  async function stopChild() {
     rmSync(requestFile, { force: true });
     if (stopping) return stopping;
-    if (!child || childClosed) { if (command) state = "stopped"; return; }
+    if (!child || childClosed) { if (command) state = "stopped"; rmSync(reportFile, { force: true }); return; }
     if (state === "stopped") return;
     state = "stopping";
     stopping = (async () => {
       kill("SIGTERM");
       clearTimeout(killTimer);
       const timer = setTimeout(() => kill("SIGKILL"), 1500);
-      try { await closed; } finally { clearTimeout(timer); }
+      try { await closed; } finally { clearTimeout(timer); rmSync(reportFile, { force: true }); }
     })();
     return stopping;
   }
-  return { start, ensure, stop, kill: () => kill("SIGKILL"), status, buildStatus, setApps(apps) {
+  return { start, ensure, async stop() { disposed = true; await restarting; return stopChild(); }, kill: () => kill("SIGKILL"), status, buildStatus, setApps(apps) {
     for (const app of apps) {
       const file = path.resolve(root, app.file);
       if (!baselines.has(file)) baselines.set(file, stamp(file));