@reqvire-org/ads 0.3.1 → 0.3.2

package/dist/bootstrap-ds/ADS.md

@@ -40,6 +40,35 @@ Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
 are rejected. Shared assignments belong in token files. Components own
 `--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
 assign those local variables or override component state.
+
+Foundation roles are enforced by `foundation-role`, `foundation-selector` and
+`foundation-import`, alongside the regular token checks. Shared definitions
+belong on the document root or explicit root themes; ordinary declarations belong
+in `base.css`, and font-face descriptors in optional `fonts.css`. The entry imports
+canonical sheets; those sheets cannot import another styling layer. Component
+classes, IDs, data/ARIA hooks, contextual selectors, keyframes and scoped UI rules
+are rejected in the foundation, including nested functional selectors. Raw visual
+values and undefined token references are checked in native defaults too; literal
+font-face metadata keeps its separate asset role.
+
+`base.css` has three closed roles:
+
+- Document defaults: root/body typography, canvas colors and theme behavior,
+  global text selection and document scrollbars.
+- Native resets: permitted normalization properties and values, such as zero
+  spacing, inherited control typography, list resets and responsive replaced media.
+- Global accessibility: universal `:focus-visible` outline rules, and reduced-motion
+  overrides inside `@media (prefers-reduced-motion: reduce)`.
+
+The `foundation-role` check validates every selector branch, property and value.
+Native selectors are not a bypass: token-backed button backgrounds, flex/grid
+layout, component-specific focus rules and hover/disabled skins are rejected.
+Shared token definitions belong in value sheets, not `base.css`. No project token
+names are embedded in this policy. A zero-specificity `:where()` wrapper does not
+change ownership. Put component design and animation in Linaria owners, and
+scenario layout variations in typed public review-pattern props. Browser review
+still checks the effects and accessibility of permitted defaults.
+
 Own primitive markup, focus, hover, selected, disabled, loading, and motion in
 the primitive. Use typed props for variations. Keep reusable structure and skin
 in colocated Linaria blocks using `css` and `cx` from `@linaria/atomic`.

package/dist/bootstrap-ds/design-system/tokens/base.css

@@ -1,3 +1,6 @@
+:root { color-scheme: light; }
+:root[data-theme="dark"] { color-scheme: dark; }
+
 *,
 *::before,
 *::after {
@@ -5,7 +8,7 @@
 }
 
 body {
-  margin: var(--space-0);
+  margin: 0;
   background: var(--bg-canvas);
   color: var(--text-body);
   font-family: var(--font-sans);

package/dist/bootstrap-ds/design-system/tokens/colors.css

@@ -1,5 +1,5 @@
 :root {
-  color-scheme: light;
+
   --bg-canvas: #faf9f6;
   --bg-surface: #fff;
   --bg-hover: #f1efea;
@@ -15,7 +15,7 @@
 }
 
 :root[data-theme="dark"] {
-  color-scheme: dark;
+
   --bg-canvas: #17191e;
   --bg-surface: #20232a;
   --bg-hover: #2c3039;

package/dist/check.mjs

@@ -14,6 +14,7 @@ import { inspectShowcasePages } from "./showcase.mjs";
 import { inspectShowcaseCoverage } from "./showcase-coverage.mjs";
 import { inspectScenarioCoverage } from "./scenarios.mjs";
 import { uiOperation, importedUiApi } from "./ui-framework.mjs";
+import { foundationDeclaration, foundationSelector } from "./foundation.mjs";
 
 const showcaseControls = new Set(["a", "button", "input", "select", "textarea", "option", "optgroup", "table", "thead", "tbody", "tfoot", "tr", "td", "th", "dialog", "details", "summary", "progress", "meter"]);
 const svgTags = new Set(["svg", "g", "path", "circle", "rect", "ellipse", "line", "polyline", "polygon", "text", "tspan", "use", "defs", "clipPath", "mask", "filter", "linearGradient", "radialGradient", "stop", "marker", "pattern"]);
@@ -54,13 +55,14 @@ export function checkProject(directory, { trackingRoot } = {}) {
     const actual = imports.map(node => foundationImportTarget(node, foundationEntry));
     if (actual.length !== expected.length || actual.some((file, index) => file !== expected[index] || !existsSync(file))) report(foundationEntry, "styles-entry", "Foundation CSS must import only fonts (when present), colors, typography, spacing, elevation, and base, in that order.");
   } catch (error) { report(foundationEntry, "css-syntax", error.reason ?? error.message, error.line ?? 1); }
-  function checkCss(file, text, offset = { line: 1, column: 1 }) {
+  function checkCss(file, text, offset = { line: 1, column: 1 }, foundation = false) {
     let css;
     try { css = postcss.parse(text, { from: file }); }
     catch (error) { report(file, "css-syntax", error.reason ?? error.message, offset.line + (error.line ?? 1) - 1); return; }
-    if (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components or patterns.");
+    if (!foundation && (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry)) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components or patterns.");
     if (isDevelopmentFile(file, options) && css.nodes.some((node) => node.type !== "comment" && !(node.type === "atrule" && node.name === "import"))) report(file, "showcase-style", "Scenarios and fixtures define no styles. Put the frame/layout in a public ADS pattern and product UI in ADS components or patterns.", offset.line);
     css.walkAtRules("import", (rule) => {
+      if (foundation) report(file, "foundation-import", "Import foundation sheets through the configured styles entry. Token sheets cannot import an unchecked styling layer.", rule.source.start.line);
       const first = valueParser(rule.params).nodes.find((node) => node.type !== "space" && node.type !== "comment");
       const specifier = first?.type === "string" ? first.value : first?.type === "function" && first.value === "url" ? first.nodes[0]?.value : null;
       if (!specifier || /^(?:[a-z]+:|\/\/)/i.test(specifier)) return;
@@ -69,19 +71,40 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (showcaseImportViolation(specifier, file, options, resolveImport)) report(file, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.", line);
     });
     css.walkRules((rule) => {
+      if (foundation) {
+        if (rule.parent.type === "rule") report(file, "foundation-role", "Foundation rules cannot nest owner/context selectors. Use root theme conditions or Linaria owners.", rule.source.start.line);
+        const violation = foundationSelector(rule.selector, { definitions: rule.nodes.some(node => node.type === "decl" && node.prop.startsWith("--")) });
+        if (violation) report(file, "foundation-selector", violation, rule.source.start.line, rule.source.start.column);
+      }
       if (isInside(path.join(dsRoot, "showcase"), file) && /:(?:hover|active|focus(?:-visible|-within)?|checked|disabled|enabled)\b|\[(?:aria-(?:selected|pressed|checked|disabled|expanded)|data-state)\b/.test(rule.selector)) report(file, "showcase-state", "Interactive state styling belongs to the real ADS component or pattern, not showcase or mock styles.", offset.line + rule.source.start.line - 1);
       if (/\.ads-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "components"), file)) report(file, "style-ownership", "ADS component internals are owned by components, not app or showcase CSS.", offset.line + rule.source.start.line - 1);
       if (/\.ux-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "patterns"), file)) report(file, "style-ownership", "Pattern internals are owned by patterns, not app or showcase CSS.", offset.line + rule.source.start.line - 1);
       if (/\.showcase-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "showcase"), file)) report(file, "style-ownership", "Showcase internals are owned by showcase scaffolding.", offset.line + rule.source.start.line - 1);
     });
+    if (foundation) css.walkAtRules(rule => {
+      if (/(?:^|-)keyframes$|^(?:scope|custom-selector|starting-style)$/i.test(rule.name)) report(file, "foundation-role", "Animations and scoped UI styles belong in their component/pattern's Linaria source, not the token foundation.", rule.source.start.line);
+      if (rule.name === "font-face" && path.basename(file) !== "fonts.css") report(file, "foundation-role", "Font faces belong in the canonical fonts.css foundation sheet.", rule.source.start.line);
+    });
     css.walkDecls((decl) => {
+      if (foundation && decl.prop.startsWith("--")) {
+        if (path.basename(file) === "base.css") report(file, "foundation-role", "Shared token definitions belong in value sheets, not base.css.", decl.source.start.line, decl.source.start.column);
+        return; // Definition names, values and aliases are validated by inspectTokens.
+      }
+      const fontDescriptor = foundation && path.basename(file) === "fonts.css" && decl.parent.type === "atrule" && decl.parent.name === "font-face";
+      if (foundation && !fontDescriptor && (path.basename(file) !== "base.css" || decl.parent.type !== "rule")) report(file, "foundation-role", "Token sheets contain shared definitions; native defaults belong in base.css, font descriptors in fonts.css, and UI styling in Linaria owners.", decl.source.start.line, decl.source.start.column);
+      if (foundation && path.basename(file) === "base.css" && decl.parent.type === "rule") {
+        const violation = foundationDeclaration(decl.parent, decl);
+        if (violation) report(file, "foundation-role", violation, decl.source.start.line, decl.source.start.column);
+      }
       const variable = checkComponentVariable(decl.prop, file, options);
       if (variable) report(file, variable.rule, variable.message, offset.line + decl.source.start.line - 1, decl.source.start.column);
       for (const ref of references(decl.value)) {
         const local = /^(?:--ds-|--ux-|--showcase-)/.test(ref.name);
+        if (foundation && local) report(file, "foundation-role", "Foundation defaults consume shared tokens, not component, pattern or scenario-local variables.", offset.line + decl.source.start.line - 1, decl.source.start.column);
         if (!local && !isSharedToken(ref.name)) report(file, "token-name", `${ref.name} does not follow ADS's fixed token naming contract.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
         else if (!local && !declaredTokens.has(ref.name) && !ref.fallback) report(file, "token-reference", `Undefined shared token ${ref.name}.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
       }
+      if (fontDescriptor) return; // Font metadata defines source assets, not token-backed UI styles.
       const violations = new Set();
       valueParser(decl.value).walk((node) => {
         if (node.type === "function" && node.value === "url") return false;
@@ -91,12 +114,12 @@ export function checkProject(directory, { trackingRoot } = {}) {
         if (node.type === "word" && /^ease(?:-in|-out|-in-out)?$/.test(node.value)) violations.add("Use a motion token for easing.");
         if (node.type === "word" && /^(?:color|background-color|(?:border|outline|caret|text-decoration|column-rule)(?:-[a-z]+)?-color|fill|stroke)$/.test(decl.prop) && /^[a-z]+$/i.test(node.value) && !/^(?:inherit|initial|unset|revert|currentcolor|transparent|none)$/i.test(node.value)) violations.add("Use a semantic color token.");
       });
-      if (/^(?:font-family|font-weight|z-index)$/.test(decl.prop) && !/^(?:var\(|inherit$|auto$)/.test(decl.value)) violations.add("Use a semantic typography or layering token.");
+      if (/^(?:font-family|font-weight|z-index)$/.test(decl.prop) && !/^(?:var\(|inherit$|initial$|unset$|revert(?:-layer)?$|auto$)/.test(decl.value) && !(foundation && decl.prop === "font-weight" && /^(?:bolder|lighter)$/.test(decl.value))) violations.add("Use a semantic typography or layering token.");
       for (const message of violations) report(file, "style-token", message, offset.line + decl.source.start.line - 1, decl.source.start.column);
     });
   }
   for (const file of files) {
-    if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) continue;
+    if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) { checkCss(file, readFileSync(file, "utf8"), undefined, true); continue; }
     if (file.endsWith(".html")) { inspectHtml(readFileSync(file, "utf8"), (rule, message, line) => report(file, rule, message, line)); continue; }
     if (file.endsWith(".css")) {
       const text = readFileSync(file, "utf8");

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/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) {