@reqvire-org/ads 0.3.5 → 0.3.7

package/README.md

@@ -91,7 +91,11 @@ for config files and Claude Desktop setup.
 To let the agent edit the ADS through enforced checks, append `--mutations` to
 the MCP command. It accepts a Git patch for one ADS unit, including its owned scenarios and
 fixtures, and runs the guards before applying it. Foundation styles, original
-assets, guides and project configuration/guard extensions have editable units too. See [guarded editing](docs/MCP.md#guarded-editing).
+assets, guides and project configuration/guard extensions have editable units too.
+Coupled changes use bounded owner transactions with checks on the complete final
+candidate. Local owner drafts and token-sample preparation reduce patch setup;
+they keep source writes behind the same guards. See
+[guarded editing](docs/MCP.md#guarded-editing).
 
 The server exposes public components/patterns, token values,
 source guides, controllers/hooks, architecture checks, behavioral verification,

package/dist/atomic-composition.mjs

@@ -0,0 +1,183 @@
+import path from "node:path";
+import ts from "typescript";
+import postcss from "postcss";
+import { isInside } from "./config.mjs";
+
+export const atomicStyleGuide = "ads://guides/atomic-styles";
+
+const sides = ["top", "right", "bottom", "left"];
+const logicalSides = ["block-start", "block-end", "inline-start", "inline-end"];
+const intersects = (a, b) => a.some(value => b.includes(value));
+const previewValue = value => value.length > 200 ? value.slice(0, 197) + "..." : value;
+const shorthands = {
+  background: ["background-attachment", "background-clip", "background-color", "background-image", "background-origin", "background-position", "background-repeat", "background-size"],
+  "background-position": ["background-position-x", "background-position-y"],
+  "background-repeat": ["background-repeat-x", "background-repeat-y"],
+  font: ["font-family", "font-size", "font-stretch", "font-style", "font-variant", "font-weight", "line-height"],
+  animation: ["animation-name", "animation-duration", "animation-timing-function", "animation-delay", "animation-iteration-count", "animation-direction", "animation-fill-mode", "animation-play-state"],
+  transition: ["transition-property", "transition-duration", "transition-timing-function", "transition-delay", "transition-behavior"],
+  flex: ["flex-grow", "flex-shrink", "flex-basis"],
+  "flex-flow": ["flex-direction", "flex-wrap"],
+  gap: ["row-gap", "column-gap"],
+  outline: ["outline-color", "outline-style", "outline-width"],
+  columns: ["column-count", "column-width"],
+  "column-rule": ["column-rule-color", "column-rule-style", "column-rule-width"],
+  "list-style": ["list-style-image", "list-style-position", "list-style-type"],
+  "text-decoration": ["text-decoration-color", "text-decoration-style", "text-decoration-line", "text-decoration-thickness"],
+};
+const expand = property => shorthands[property]?.flatMap(expand) ?? [property];
+const longhands = new Map(Object.keys(shorthands).map(property => [property, expand(property)]));
+
+// CSS-language relationships, independent of components, tokens and frameworks.
+function footprint(property) {
+  const box = /^(padding|margin|scroll-padding|scroll-margin|inset)(?:-(top|right|bottom|left|block|inline|block-start|block-end|inline-start|inline-end))?$/.exec(property);
+  if (box) {
+    const side = box[2];
+    const logical = !!side && !sides.includes(side);
+    return { family: box[1], logical, slots: !side ? logicalSides : /^(block|inline)$/.test(side) ? [`${side}-start`, `${side}-end`] : [side], whole: !side };
+  }
+  if (sides.includes(property)) return { family: "inset", logical: false, slots: [property] };
+  const border = /^border(?:-(top|right|bottom|left|block|inline|block-start|block-end|inline-start|inline-end))?(?:-(color|style|width))?$/.exec(property);
+  if (border) {
+    const side = border[1];
+    return { family: "border", logical: !!side && !sides.includes(side), slots: !side ? logicalSides : /^(block|inline)$/.test(side) ? [`${side}-start`, `${side}-end`] : [side], whole: !side, fields: border[2] ? [border[2]] : ["color", "style", "width"] };
+  }
+  const corner = /^border-(?:(top-left|top-right|bottom-left|bottom-right|start-start|start-end|end-start|end-end)-)?radius$/.exec(property);
+  if (corner) return { family: "radius", logical: /^(start|end)-/.test(corner[1] ?? ""), whole: !corner[1], slots: [corner[1]] };
+  const dimension = /^(min-|max-)?(width|height|inline-size|block-size)$/.exec(property);
+  if (dimension) return { family: `${dimension[1] ?? ""}size`, logical: dimension[2].endsWith("-size"), slots: [dimension[2]] };
+  const overflow = /^(overflow|overscroll-behavior)(?:-(x|y|block|inline))?$/.exec(property);
+  if (overflow) return { family: overflow[1], logical: ["block", "inline"].includes(overflow[2]), whole: !overflow[2], slots: [overflow[2]] };
+  return null;
+}
+
+function overlaps(a, b) {
+  if (a === b || a.startsWith("--") || b.startsWith("--")) return false;
+  if ([a, b].includes("all")) return ![a, b].some(value => ["direction", "unicode-bidi"].includes(value));
+  const first = footprint(a), second = footprint(b);
+  if (first && second && first.family === second.family) {
+    if (first.fields && !intersects(first.fields, second.fields)) return false;
+    return first.whole || second.whole || first.logical !== second.logical || intersects(first.slots, second.slots);
+  }
+  return intersects(longhands.get(a) ?? [a], longhands.get(b) ?? [b]);
+}
+
+function unwrap(node) {
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
+  return node;
+}
+
+/** Review only: valid CSS can intentionally overlap. Never rewrite project CSS. */
+export function createAtomicCompositionReview(program, options) {
+  const checker = program.getTypeChecker(), templates = new Map();
+  function declaration(node) {
+    let symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+    if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    return symbol?.valueDeclaration;
+  }
+  function imported(node, names, modules, seen = new Set()) {
+    node = unwrap(node);
+    if (!node || seen.has(node)) return false;
+    seen = new Set([...seen, node]);
+    const base = ts.isPropertyAccessExpression(node) ? node.expression : node;
+    const symbol = checker.getSymbolAtLocation(base);
+    for (const item of symbol?.declarations ?? []) {
+      if (ts.isImportSpecifier(item) && names.includes((item.propertyName ?? item.name).text) && modules.includes(item.parent.parent.parent.moduleSpecifier.text)) return true;
+      if (ts.isNamespaceImport(item) && ts.isPropertyAccessExpression(node) && names.includes(node.name.text) && modules.includes(item.parent.parent.moduleSpecifier.text)) return true;
+      if (ts.isVariableDeclaration(item) && imported(item.initializer, names, modules, seen)) return true;
+    }
+    return false;
+  }
+  const isCx = node => imported(node, ["cx"], ["@linaria/atomic", "@linaria/core"]);
+  function isAtomic(tag) {
+    if (ts.isCallExpression(tag)) tag = tag.expression;
+    if (imported(tag, ["css", "styled"], ["@linaria/atomic"])) return true;
+    return ts.isPropertyAccessExpression(tag) && imported(tag.expression, ["styled"], ["@linaria/atomic"]);
+  }
+  function entries(node) {
+    if (templates.has(node)) return templates.get(node);
+    const result = [];
+    templates.set(node, result);
+    const source = node.getSourceFile(), template = node.template;
+    const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text : template.head.text + template.templateSpans.map(span => `__ads_expression__${"\n".repeat(span.expression.getText(source).split("\n").length - 1)}${span.literal.text}`).join("");
+    const position = source.getLineAndCharacterOfPosition(template.getStart(source) + 1);
+    try {
+      postcss.parse(text).walkDecls(decl => {
+        const selectors = [], conditions = [];
+        for (let parent = decl.parent; parent?.type !== "root"; parent = parent?.parent) {
+          if (!parent) break;
+          if (parent.type === "rule") selectors.unshift(parent.selector.trim().replace(/\s+/g, " "));
+          if (parent.type === "atrule") conditions.unshift(`${parent.name} ${parent.params}`.trim().replace(/\s+/g, " "));
+        }
+        // Animation frames describe different instants, not combined classes.
+        if (conditions.some(condition => /^(?:-\w+-)?keyframes\b/.test(condition))) return;
+        result.push({ property: decl.prop.toLowerCase(), value: decl.value, important: !!decl.important, selectors: JSON.stringify(selectors), conditions: JSON.stringify(conditions),
+          file: path.relative(options.root, source.fileName).replaceAll("\\", "/"), line: position.line + decl.source.start.line, column: decl.source.start.column + (decl.source.start.line === 1 ? position.character : 0) });
+      });
+    } catch { /* The core CSS syntax diagnostic owns malformed templates. */ }
+    return result;
+  }
+  function object(node, seen = new Set()) {
+    node = unwrap(node);
+    if (!node || seen.has(node)) return null;
+    if (ts.isObjectLiteralExpression(node) || ts.isArrayLiteralExpression(node)) return node;
+    const owner = declaration(node);
+    return owner?.initializer ? object(owner.initializer, new Set([...seen, node])) : null;
+  }
+  function styles(node, seen = new Set()) {
+    node = unwrap(node);
+    if (!node || seen.has(node)) return [];
+    seen = new Set([...seen, node]);
+    if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) return entries(node);
+    if (ts.isConditionalExpression(node)) return [...styles(node.whenTrue, seen), ...styles(node.whenFalse, seen)];
+    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return [...(node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ? [] : styles(node.left, seen)), ...styles(node.right, seen)];
+    if (ts.isCallExpression(node) && isCx(node.expression)) return node.arguments.flatMap(argument => styles(argument, seen));
+    if (ts.isSpreadElement(node)) {
+      const value = object(node.expression);
+      return value && ts.isArrayLiteralExpression(value) ? value.elements.flatMap(element => styles(element, seen)) : [];
+    }
+    const owner = declaration(node);
+    if (owner?.initializer) return styles(owner.initializer, seen);
+    if (ts.isElementAccessExpression(node) || ts.isPropertyAccessExpression(node)) {
+      const value = object(node.expression);
+      if (!value || !ts.isObjectLiteralExpression(value)) return [];
+      const key = ts.isPropertyAccessExpression(node) ? node.name.text : node.argumentExpression && ts.isStringLiteralLike(node.argumentExpression) ? node.argumentExpression.text : null;
+      return value.properties.flatMap(property => {
+        const name = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
+        return key !== null && name !== key ? [] : ts.isPropertyAssignment(property) ? styles(property.initializer, seen) : ts.isShorthandPropertyAssignment(property) ? styles(property.name, seen) : [];
+      });
+    }
+    return [];
+  }
+  return source => {
+    const warnings = [], seen = new Set();
+    function compare(first, second, location) {
+      for (const a of first) for (const b of second) {
+        if (a === b || a.selectors !== b.selectors || a.conditions !== b.conditions || a.important !== b.important || a.value === "0" && b.value === "0" || !overlaps(a.property, b.property)) continue;
+        const key = JSON.stringify([a, b].map(entry => [entry.file, entry.line, entry.column]).sort());
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const position = source.getLineAndCharacterOfPosition(location.getStart(source));
+        warnings.push({ rule: "atomic-composition-review", severity: "warning", line: position.line + 1, column: position.character + 1,
+          message: `Atomic declarations ${a.property}: ${previewValue(a.value)} and ${b.property}: ${previewValue(b.value)} may overlap without matching cx merge keys. Their winner can depend on extraction order, specificity or writing mode. Use consistent property names/granularity across the base and variants, compose with Linaria cx, and verify computed styles in the built preview. Review all affected variants; valid tokens do not establish cascade correctness. See ${atomicStyleGuide}.`,
+          guidanceUri: atomicStyleGuide, related: [a, b].map(({ selectors: _selectors, conditions: _conditions, important: _important, ...entry }) => ({...entry,value:previewValue(entry.value)})) });
+      }
+    }
+    function visit(node) {
+      if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) {
+        const declarations = entries(node);
+        for (let index = 0; index < declarations.length; index++) compare([declarations[index]], declarations.slice(index + 1), node);
+      }
+      if (ts.isCallExpression(node) && isCx(node.expression)) {
+        const groups = node.arguments.flatMap(argument => {
+          const value = ts.isSpreadElement(argument) ? object(argument.expression) : null;
+          return value && ts.isArrayLiteralExpression(value) ? value.elements.map(element => styles(element)) : [styles(argument)];
+        });
+        for (let index = 0; index < groups.length; index++) for (let next = index + 1; next < groups.length; next++) compare(groups[index], groups[next], node);
+      }
+      ts.forEachChild(node, visit);
+    }
+    if (isInside(options.dsRoot, source.fileName)) visit(source);
+    return warnings;
+  };
+}

package/dist/bootstrap-ds/ADS.md

@@ -36,8 +36,14 @@ Projects sharing this ADS use the same token names, meanings, and value types;
 their concrete values and theme overrides can differ. Reuse existing local values
 when importing components/patterns, add missing shared definitions, and import
 source token values only when adopting that theme is requested.
-Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
-are rejected. Shared assignments belong in token files. Components own
+Shared token names and prefixes follow the ADS contract. A component/pattern may
+register one unique local namespace in colocated `tokens.json` and define it in
+`tokens.css`, imported by its runtime. Flat owners use `<Owner>.tokens.json` and
+`<Owner>.tokens.css`. These definition-only sheets contain root/theme custom
+properties, not UI selectors or ordinary styles. Other owners consume shared
+tokens; they cannot override or consume a peer's local namespace. A colocated
+`kind:"tokens"` scenario needs real samples for every local token. Shared
+assignments remain in the shared token files. Components own
 `--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
 assign those local variables or override component state.
 
@@ -183,7 +189,7 @@ mounting, correct props, every branch/state or visual parity. The older
 
 `token-scenario-reference` rejects undeclared token names in metadata and reachable
 inputs. `token-scenario-render` rejects claimed tokens with no reachable input
-reference; `token-scenario-coverage` requires every discovered foundation token
+reference; `token-scenario-coverage` requires every discovered shared or owner-local token
 to have coverage. A new or removed token therefore needs a scenario/fixture
 update. All three are errors in `ads check`, run by `lint:ds` and the build.
 Coverage is static reachability, not proof that every branch actually renders

package/dist/bootstrap-ds/README.md

@@ -62,6 +62,10 @@ the public `TokenPreview` pattern owns their presentation and applies the real C
 variables. Add/remove samples alongside token definitions. `ads check` rejects
 missing coverage and invented names; the App verifies the declared CSS bindings
 in the browser. Extend or replace the project-owned pattern as your tokens evolve.
+`ads_prepare_token_samples` can prepare a fixture patch from explicit project
+property/probe bindings. It preserves existing samples and reports unmapped tokens;
+it does not guess how a new value should look. Component/pattern constants can use
+the colocated namespace contract in [ADS.md](ADS.md), with their own token scenario.
 
 Create a component under `design-system/components/`, export it through `@ds`,
 and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and
@@ -79,6 +83,8 @@ stale retained output. Switching or rebuilding a scenario unmounts its previous
 state. `showcase/mcp/main.tsx` exports `mountScenario(Scenario, container)` and
 returns an unmount callback; it is not the shell. Keep the saved `framework`,
 compiler and mount adapter consistent.
+Managed sessions own their graph output; standalone prebuilds cannot replace it.
+Verified generated graph snapshots preserve warm-start reuse across sessions.
 
 The application and previews use the same foundation CSS and Linaria pipeline.
 The source barrel loads the foundation once. The private `build:lib` script uses
@@ -98,3 +104,7 @@ from a user-selected external repository, preserving revisions and licenses.
 inspection builds it automatically, then loads selected entries. Browser review
 still checks layout, accessibility, keyboard/focus, states, themes and motion. A clean
 build or delivered HTML alone does not establish those behaviors.
+Opt-in MCP editing uses owner Git patches. `ads_prepare_patch` creates a temporary
+owner draft/diff; `ads_apply_transaction` validates bounded coupled owner patches
+against one final candidate. Preparation changes no live source. Keep all guards
+and review the rendered result after applying.

package/dist/boundaries.mjs

@@ -3,6 +3,7 @@ import ts from "typescript";
 import { importedUiName } from "./ui-framework.mjs";
 import { isInside, isStateVariable, isTestFile, isDevelopmentFile } from "./config.mjs";
 import { isSharedToken } from "./token-policy.mjs";
+import { scopedTokenOwner } from "./scoped-tokens.mjs";
 
 export function projectCompilerOptions({ root }) {
   const file = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json");
@@ -59,6 +60,8 @@ export function checkComponentVariable(name, filename, options) {
   const components = !development && isInside(path.join(dsRoot, "components"), filename);
   const patterns = !development && isInside(path.join(dsRoot, "patterns"), filename);
   const showcase = development;
+  const owned = scopedTokenOwner(options, name);
+  if (owned) return path.resolve(options.root, owned.file) === filename ? null : { rule: "token-ownership", message: `Define ${name} only in ${owned.file}, owned by ${owned.unit}. Consume it with var(); runtime geometry remains a separate styleWrites boundary.` };
   if (isSharedToken(name)) return tokens ? null : { rule: "token-ownership", message: `Define ${name} in ADS tokens, not component, pattern, showcase, or app styles.` };
   if (name.startsWith("--ux-")) return patterns || showcase ? null : { rule: "variable-ownership", message: "--ux-* variables belong to ADS patterns and showcase composition." };
   if (name.startsWith("--showcase-")) return showcase ? null : { rule: "variable-ownership", message: "--showcase-* variables belong to the ADS showcase." };

package/dist/check.mjs

@@ -18,6 +18,8 @@ import { inspectStyleBoundaries, pointerCaptureAdvisories } from "./style-bounda
 import { inspectBehaviors, inspectControllers } from "./behaviors.mjs";
 import { numericCssUnit, tokenLengthLiteral } from "./css-values.mjs";
 import { foundationDeclaration, foundationSelector } from "./foundation.mjs";
+import { scopedTokens, scopedTokenOwner } from "./scoped-tokens.mjs";
+import { createAtomicCompositionReview } from "./atomic-composition.mjs";
 
 const scenarioLayoutGuidance = "Put demo-only sizing and framing in a public review/layout pattern. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
 const inlineStyleGuidance = `Own visual styles in component/pattern Linaria. ${scenarioLayoutGuidance} Reserve inlineStyleFiles for documented measured geometry, not demo layout.`;
@@ -40,6 +42,8 @@ export function checkProject(directory, { trackingRoot } = {}) {
   diagnostics.push(...tokenInventory.diagnostics);
   diagnostics.push(...inspectAssets(options));
   const resolveImport = importResolver(options);
+  const scoped = scopedTokens(options);
+  const scopedFiles = new Set(scoped.definitions.map(entry => path.resolve(root, entry.file)));
   const rootHtml = path.join(root, "index.html");
   const files = [...new Set([...sourceFiles(sourceRoot), ...sourceFiles(dsRoot), ...(existsSync(rootHtml) ? [rootHtml] : [])])];
   const boundaryFiles = [...config.inlineStyleFiles, ...config.boundaries.styleWrites.map(entry => entry.file)].map(file => path.resolve(root, file)).filter(file => existsSync(file) && statSync(file).isFile());
@@ -47,6 +51,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
   const compiler = projectCompilerOptions(options);
   const program = ts.createProgram(scriptFiles, { ...compiler, paths: { ...compiler.paths, [config.publicAlias]: [path.join(dsRoot, config.publicEntry)] }, allowJs: true, noResolve: true, noLib: true, types: [], target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, jsx: ts.JsxEmit.Preserve });
   const checker = program.getTypeChecker();
+  const atomicCompositionReview = createAtomicCompositionReview(program, options);
   function report(file, rule, message, line = 1, column = 1) {
     diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column });
   }
@@ -110,6 +115,11 @@ export function checkProject(directory, { trackingRoot } = {}) {
       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 owned = scopedTokenOwner(options, ref.name);
+        if (owned) {
+          if (scoped.inventory.owner(scoped.inventory.relative(path.relative(root, file))) !== owned.unit || !declaredTokens.has(ref.name)) report(file, "token-reference", `${ref.name} belongs to ${owned.unit}. Use shared tokens across owners; owner-local tokens must be defined and consumed by their owner.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
+          continue;
+        }
         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);
@@ -130,6 +140,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     });
   }
   for (const file of files) {
+    if (scopedFiles.has(file)) continue; // Closed definition-only contract checked by inspectTokens.
     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")) {
@@ -140,6 +151,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     const source = program.getSourceFile(file);
     if (!source) continue;
     advisories.push(...pointerCaptureAdvisories(source).map(entry => ({ file: path.relative(root, file).replaceAll("\\", "/"), ...entry })));
+    advisories.push(...atomicCompositionReview(source).map(entry => ({ file: path.relative(root, file).replaceAll("\\", "/"), ...entry })));
     for (const diagnostic of program.getSyntacticDiagnostics(source)) {
       const position = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
       report(file, "source-syntax", ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"), position.line + 1, position.character + 1);
@@ -223,6 +235,10 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
       if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) specifier = node.arguments[0].text;
       if (specifier && importViolation(specifier, file, options, resolveImport)) nodeReport(node, "public-import", `Import through ${config.publicAlias}, not ADS implementation paths.`);
+      if (specifier) for (const target of resolveImport(specifier, file)) {
+        const tokenOwner = scoped.definitions.find(entry => path.resolve(root, entry.file) === target);
+        if (tokenOwner && scoped.inventory.owner(scoped.inventory.relative(path.relative(root, file))) !== tokenOwner.unit) nodeReport(node, "token-ownership", `Only ${tokenOwner.unit} imports its token sheet. Import the public component/pattern to consume its design.`);
+      }
       if (specifier && resolveImport(specifier, file).some((target) => (specifier.startsWith(".") || existsSync(target)) && target.endsWith(".css") && isInside(root, target) && !isInside(dsRoot, target) && target !== path.join(sourceRoot, "app-mount.css") && !isInside(path.join(root, "node_modules"), target))) nodeReport(node, "style-ownership", "Imported project CSS belongs to ADS components, patterns, or the foundation. Only structural app-mount.css is allowed outside the ADS.");
       if (specifier && appImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "no-app-import", "ADS implementations and showcase fixtures must not import app code. Use public ADS APIs with local fixture data; keep application integration harnesses in application tests.");
       if (specifier && showcaseImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.");

package/dist/cli.mjs

@@ -113,7 +113,7 @@ async function main(args) {
   if (!json && result.diagnostics?.length) {
     for (const diagnostic of result.diagnostics) console.error(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.rule}] ${diagnostic.message}`);
   }
-  if (!json) for (const advisory of result.advisories ?? []) console.error(`${advisory.file}:${advisory.line}:${advisory.column} [advisory:${advisory.rule}] ${advisory.message}`);
+  if (!json) for (const advisory of result.advisories ?? []) console.error(`${advisory.file}:${advisory.line}:${advisory.column} [${advisory.severity ?? "advisory"}:${advisory.rule}] ${advisory.message}`);
   if (result.ok === false || result.diagnostics?.length) process.exitCode = 1;
 }
 

package/dist/config.mjs

@@ -152,10 +152,14 @@ export function isBehaviorFile(file) {
   return /(?:^|[\\/])behavior\.json$|\.behavior\.json$/.test(file);
 }
 
+export function isTokenManifestFile(file) {
+  return /(?:^|[\\/])tokens\.json$|\.tokens\.json$/.test(file);
+}
+
 export function isDevelopmentFile(file, { dsRoot }) {
   if (!isInside(dsRoot, file)) return isTestFile(file);
   const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
-  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file)
+  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file) || isTokenManifestFile(file)
     || /^(?:showcase|composition)\//.test(relative)
     || /(?:^|\/)(?:scenario|fixtures)(?:\/|$)/.test(relative)
     || /\.scenario(?:-adapter)?\.[cm]?[jt]sx?$/.test(relative);
@@ -170,7 +174,7 @@ export function sourceFiles(root) {
     if (ignored.has(entry.name) || entry.isSymbolicLink()) continue;
     const file = path.join(root, entry.name);
     if (entry.isDirectory()) files.push(...sourceFiles(file));
-    else if (entry.isFile() && (/\.(css|html|[cm]?[jt]sx?)$/.test(entry.name) || isBehaviorFile(entry.name))) files.push(file);
+    else if (entry.isFile() && (/\.(css|html|[cm]?[jt]sx?)$/.test(entry.name) || isBehaviorFile(entry.name) || isTokenManifestFile(entry.name))) files.push(file);
   }
   return files.sort();
 }

package/dist/mcp/build-status.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { z } from "zod";
 import { isInside, projectPath } from "../config.mjs";
 import { readPreviewManifest } from "../preview-resources.mjs";
+import { previewArtifactPath, withPreviewSession } from "../preview-scope.mjs";
 
 export const BUILD_URI = "ads://project/build";
 export const buildStatusFile = (root) => path.join(root, ".ds/build-status.json");
@@ -123,7 +124,8 @@ 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, file = buildStatusFile(root) } = {}) {
+export function inspectBuildStatus(root, config, { session, previewSession, processState, file = buildStatusFile(root) } = {}) {
+  const options = withPreviewSession({ root, config: { mcp: config } }, previewSession);
   let report;
   let reportError;
   try {
@@ -137,7 +139,7 @@ export function inspectBuildStatus(root, config, { session, processState, file =
   let graphError;
   if (config.previewManifest && report?.previews.some(entry => entry.state === "ready")) {
     try {
-      if (!readPreviewManifest({ root, config: { mcp: config } }, { verify: true })) throw new Error("Preview resource manifest is missing.");
+      if (!readPreviewManifest(options, { verify: true })) throw new Error("Preview resource manifest is missing.");
     } catch (error) { graphError = `Invalid preview resource graph: ${error.message}`; }
   }
   const previews = config.apps.map((app) => {
@@ -145,12 +147,13 @@ export function inspectBuildStatus(root, config, { session, processState, file =
     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));
+    const artifact = path.resolve(root, previewArtifactPath(options, app.file));
+    const available = existsSync(artifact);
     if (reportError) { state = "error"; diagnostics = [{ message: reportError }]; }
     if (graphError && app.id.includes("/")) { state = "error"; diagnostics = [{ message: graphError }]; }
     if (state === "ready") {
       try {
-        if (value.lastSuccessfulRevision !== value.revision || artifactDigest(path.resolve(root, app.file)) !== value.artifactDigest) throw new Error("Preview output does not match its successful build. Rebuild before reviewing it.");
+        if (value.lastSuccessfulRevision !== value.revision || artifactDigest(artifact) !== value.artifactDigest) throw new Error("Preview output does not match its successful build. Rebuild before reviewing it.");
       } catch (error) { state = "error"; diagnostics = [{ message: error.message }]; }
     }
     if (processState?.state === "failed") { state = "error"; diagnostics = [{ message: processState.error ?? "Preview watcher exited." }, ...diagnostics].slice(0, 20); }

package/dist/mcp/context.mjs

@@ -5,7 +5,7 @@ import { projectGuideFiles } from "../project-documents.mjs";
 
 export const GUIDE_URI = "ads://project/guide";
 // Put the task triggers and entry path first: some hosts shorten server guidance.
-export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner at a time. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
+export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner; use ads_apply_transaction only for coupled owner patches. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
 
 function manager(root, pkg) {
   if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];
@@ -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; 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.
+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; a real selected-owner re-export can remove its redundant export {};. Dry-run to inspect validation; apply only a passing patch. Fix rejected patches in the owning unit; use ads_apply_transaction for coupled owners instead of bypassing rejection with direct writes. ads_prepare_patch creates a local owner draft/diff; ads_prepare_token_samples reconciles explicit project bindings without guessing visual meaning. 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/edit-preparation.mjs

@@ -0,0 +1,111 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isInside } from "../config.mjs";
+import { checkUnitFiles, inspectUnits, validateUnitId } from "../units.mjs";
+import { textDiff } from "./text-diff.mjs";
+
+const hash = value => createHash("sha256").update(value).digest("hex");
+const binary = bytes => bytes?.includes(0) || bytes && !Buffer.from(bytes.toString("utf8")).equals(bytes);
+function generated(options, relative) {
+  const target = path.join(options.root, ".ds", relative);
+  mkdirSync(path.dirname(target), {recursive:true});
+  if (realpathSync(path.dirname(target)) !== path.dirname(target)) throw new Error("Patch preparation output cannot resolve through symlinks.");
+  return target;
+}
+export function storePreparedPatch(options, patch) {
+  if (Buffer.byteLength(patch) > 16 * 1024 * 1024) throw new Error("Prepared Git patch exceeds 16 MiB.");
+  if (!patch) return {patch:null,patchFile:null};
+  const file = `.ds/patches/${randomUUID()}.patch`;
+  writeFileSync(generated(options,file.slice(4)),patch);
+  return {patchFile:file,bytes:Buffer.byteLength(patch)};
+}
+
+/** A temporary copy of just one owner and its declared companions, not a project mirror. */
+export function prepareUnitPatch(options, {unit, action = "create", draft}) {
+  validateUnitId(unit);
+  const inventory = inspectUnits(options);
+  if (action === "create") {
+    const owner = inventory.units.find(entry => entry.id === unit);
+    const files = [...new Set([...(owner?.files ?? []), ...(owner?.companionFiles ?? []).map(entry => entry.path),
+      ...(!owner ? ["ds.config.json"] : []),
+      ...(/^(?:components|patterns|controllers)\//.test(unit) ? [path.relative(options.root,path.join(options.dsRoot,options.config.publicEntry)).replaceAll("\\","/")] : [])])];
+    if (!owner && !/^(?:components|patterns|controllers|composition)\/.+/.test(unit)) throw new Error("Discover an existing unit or choose a new unoccupied component/pattern/controller/composition owner.");
+    if (/^(?:components|patterns|controllers|composition)\//.test(unit)) for (let directory=unit;directory!==".";directory=path.posix.dirname(directory)) {
+      const marker=path.join(options.dsRoot,directory,".gitkeep");
+      if (existsSync(marker) && realpathSync(marker)===marker && lstatSync(marker).isFile() && lstatSync(marker).size===0) {
+        const relative=path.relative(options.root,marker).replaceAll("\\","/");
+        if (!files.includes(relative)) files.push(relative);
+      }
+    }
+    draft = randomUUID();
+    const base = generated(options,`patch-drafts/${draft}/manifest.json`), folder = path.join(path.dirname(base),"work");
+    const entries = [];
+    let bytes = 0;
+    for (const file of files) {
+      const absolute = path.resolve(options.root,file);
+      if (!isInside(options.root,absolute) || realpathSync(absolute) !== absolute || !lstatSync(absolute).isFile()) throw new Error("Draft inputs must be ordinary project source files.");
+      if (lstatSync(absolute).size > 16 * 1024 * 1024) throw new Error("Draft input exceeds 16 MiB.");
+      const content = readFileSync(absolute);
+      bytes += content.length;
+      if (entries.length >= 256 || bytes > 32 * 1024 * 1024) throw new Error("Owner draft exceeds 256 files/32 MiB. Prepare a targeted Git patch instead.");
+      for (const name of ["work","base"]) {
+        const target = path.join(path.dirname(base),name,file);
+        mkdirSync(path.dirname(target),{recursive:true}); writeFileSync(target,content);
+      }
+      entries.push({file,digest:hash(content)});
+    }
+    mkdirSync(folder,{recursive:true});
+    writeFileSync(base,JSON.stringify({schemaVersion:1,unit,entries}));
+    return {draft,unit,directory:folder,files, next:"Edit only this draft, then call ads_prepare_patch with action: diff and this draft ID. Live source is unchanged; the resulting Git patch still requires ads_apply_patch and all its gates."};
+  }
+  if (!/^[a-f0-9-]{36}$/.test(draft ?? "")) throw new Error("Use the draft ID returned by ads_prepare_patch.");
+  const base = path.join(options.root,".ds/patch-drafts",draft);
+  if (realpathSync(base) !== base) throw new Error("Draft paths cannot resolve through symlinks.");
+  const metadata = JSON.parse(readFileSync(path.join(base,"manifest.json"),"utf8"));
+  if (metadata.schemaVersion !== 1 || metadata.unit !== unit) throw new Error("Draft and selected unit do not match.");
+  if (action === "discard") {rmSync(base,{recursive:true});return {discarded:true,draft,unit};}
+  if (action !== "diff") throw new Error("Choose create, diff or discard.");
+  const files = new Set(metadata.entries.map(entry => entry.file));
+  function walk(directory) {
+    if (realpathSync(directory) !== directory) throw new Error("Draft directories cannot resolve through symlinks.");
+    for (const entry of readdirSync(directory,{withFileTypes:true})) {
+      const file = path.join(directory,entry.name);
+      if (entry.isDirectory()) walk(file);
+      else if (!entry.isFile() || lstatSync(file).nlink !== 1) throw new Error("Drafts contain ordinary unlinked source files only.");
+      else files.add(path.relative(path.join(base,"work"),file).replaceAll("\\","/"));
+      if (files.size > 256) throw new Error("Draft exceeds 256 files.");
+    }
+  }
+  walk(path.join(base,"work"));
+  const changes = [];
+  let patch = "", bytes = 0;
+  for (const file of files) {
+    if (!file || path.isAbsolute(file) || file.includes("\\") || file.split("/").some(part => !part || part === "." || part === ".." || part.startsWith(".") && part !== ".gitkeep" && !/^\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?$/.test(part))) throw new Error("Drafts use ordinary project-relative source paths.");
+    const original = path.join(base,"base",file), next = path.join(base,"work",file), live = path.join(options.root,file);
+    const read = file => {
+      if (!existsSync(file)) return null;
+      const stat = lstatSync(file);
+      if (realpathSync(file) !== file || !stat.isFile() || stat.nlink !== 1 || stat.size > 16 * 1024 * 1024) throw new Error("Draft inputs must be ordinary unlinked files no larger than 16 MiB.");
+      return readFileSync(file);
+    };
+    const expected = metadata.entries.find(entry => entry.file === file)?.digest ?? null;
+    const left = read(original), right = read(next), source = read(live);
+    if ((left && hash(left)) !== expected || (source && hash(source)) !== expected) throw new Error(`Source/baseline changed for ${file}; create a fresh owner draft.`);
+    if (left !== null && right !== null && left.equals(right) || left === null && right === null) continue;
+    bytes += (left?.length ?? 0) + (right?.length ?? 0);
+    if (bytes > 32 * 1024 * 1024) throw new Error("Draft changes exceed 32 MiB.");
+    const change = {path:file,originalContent:left === null ? null : binary(left) ? left : left.toString(),content:right === null ? null : binary(right) ? right : right.toString()};
+    changes.push(change);
+    if (!binary(left) && !binary(right)) patch += textDiff(file,change.originalContent,change.content);
+    else {
+      let diff;
+      try { diff = execFileSync("git",["diff","--no-index","--binary","--no-ext-diff","--no-textconv","--",left === null ? "/dev/null" : original,right === null ? "/dev/null" : next],{encoding:"utf8",maxBuffer:16*1024*1024}); }
+      catch (error) { if (error.status !== 1) throw error; diff=error.stdout; }
+      patch += diff.replace(/^diff --git .+$/m,`diff --git a/${file} b/${file}`);
+    }
+  }
+  if (changes.length) checkUnitFiles(options,unit,changes,inventory,true);
+  return {unit,draft,changes:changes.map(entry=>entry.path),...storePreparedPatch(options,patch),next:"Apply with ads_apply_patch using this unit and patchFile. Preparation is not validation or publication."};
+}