@reqvire-org/ads 0.2.9 → 0.3.1

package/README.md

@@ -202,7 +202,7 @@ app's bundler. With no icon source, generation is skipped. See the
 Install skills with `npx skills`:
 
 ```sh
-npx skills add reqvire-org/design-system --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+npx skills add reqvire-org/ads --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
 ```
 
 For local development, install from this checkout:
@@ -272,7 +272,7 @@ The [dummy project](tests/fixtures/guard-project/README.md) tests the generic gu
 There are two different starting points in this checkout:
 
 - [bootstrap-ds/](bootstrap-ds/README.md) is an empty React application starter:
-  token defaults, build setup, empty component/pattern folders, and a project preview compiler adapter. It is bundled with `ads-designer` so an agent can copy it when starting
+  token defaults, build setup, empty product component folders, a project-owned token review pattern, and a project preview compiler adapter. It is bundled with `ads-designer` so an agent can copy it when starting
   from zero. `ads init` uses its empty foundation files when a project has no ADS.
 - [design-system/](design-system/README.md) is this repository's working example,
   with real components, patterns, and scenarios inspected through the built-in showcase. It demonstrates the architecture

package/dist/bootstrap-ds/ADS.md

@@ -5,7 +5,7 @@ token values, and branding. Tool updates preserve those values and customized
 code; source and theme imports are explicit operations.
 
 For the architectural rationale, see the
-[ADS architecture](https://github.com/reqvire-org/design-system/blob/main/docs/ARCHITECTURE.md).
+[ADS architecture](https://github.com/reqvire-org/ads/blob/main/docs/ARCHITECTURE.md).
 The rules and commands needed to use this starter are included locally.
 
 ## Ownership
@@ -114,13 +114,24 @@ design-system/
 Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
 `Scenario.tsx` exports a default independently mountable view and literal metadata
 `export const scenario = { title: "Button states", covers: ["Button"] };`.
-Token entries under the configured token directory also declare `tokens`:
-`export const scenario = { title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens };`.
-Metadata may read literal const fixture fields; it cannot run expressions,
-functions, wildcard lists or token discovery. The same fixture list must be
-consumed by the default entry. `covers: []` is valid for a minimal token value
-inspection entry without public UI; styled samples use a real public review
-pattern. Names and sample text belong to the fixture, values to foundation CSS.
+Token entries under the configured token directory declare
+`export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };`.
+`TokenSamples` is any project-owned public review pattern, not a required name.
+Its colocated fixture declares literal `samples: [{ token, property, probe }]`.
+Each token must exist and have sample coverage; duplicate bindings, missing probes,
+empty covers and value-only inspectors fail. The default entry passes the declared
+samples to a rendered public pattern's `samples` prop. No token-name/property mapping
+or sample values are embedded in the tool. Display values come from foundation CSS;
+probes are isolated verification inputs owned by the fixture.
+
+The renderer marks the actual styled element with `data-ads-token` and
+`data-ads-property`. In a browser, the App validates the declared property/value and
+probe using `CSS.supports`, checks the sample is rendered, then temporarily changes
+that token to its fixture probe. Its computed sample property must respond. Values
+are restored before yielding to painting; hardcoded lookalikes fail. Source gates
+prove the contract structure, not successful rendering. The browser check covers
+the mounted scenario and theme; visual quality and other states still need review.
+
 It imports real public UI through `@ds` and its local fixture. The adapter supplies
 initial state, callbacks and simulated services. The default entry needs no
 mandatory caller inputs or prior page initialization. Related parts may share a

package/dist/bootstrap-ds/README.md

@@ -1,19 +1,19 @@
 # Empty native design system
 
-This private React/TypeScript workspace contains semantic CSS tokens, an empty
-public barrel, Linaria extraction and a project preview compiler adapter. It has
-no components, patterns, icons, fonts or example screens. The minimal showcase
+This private React/TypeScript workspace contains semantic CSS tokens, a project-owned
+token review pattern, a public barrel, Linaria extraction and a preview compiler
+adapter. It has no product components, icons, fonts or example screens. The minimal showcase
 shell and MCP client come from ADS tooling.
 
 Read the local [contract](ADS.md) and the
-[architecture](https://github.com/reqvire-org/design-system/blob/main/docs/ARCHITECTURE.md).
+[architecture](https://github.com/reqvire-org/ads/blob/main/docs/ARCHITECTURE.md).
 
 ## Start
 
 Copy the contents of `bootstrap-ds/`, including dotfiles, into a new project.
 The installed `ads-designer` skill contains the same files in
 `assets/bootstrap-ds/`. Set the project name in `package.json`. Use Node 22.12 or
-newer and ADS 0.3 or later for the shared-resource preview compiler.
+newer and ADS 0.3.1 or later for the shared-resource preview compiler.
 
 ```sh
 npx @reqvire-org/ads init --framework react
@@ -25,7 +25,7 @@ npm run dev:showcase
 For unreleased tooling, run init using the real local package:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.1.tgz"
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
 npm run build
@@ -44,7 +44,7 @@ native Preact app without a saved ADS framework, use `ads init --framework preac
 Init records that choice and generates native hook imports without migrating the
 app or rewriting its compiler. Subsequent init runs reuse the saved choice.
 Init adds missing foundation files and connects architectural checks; it does
-not configure Linaria or generate component source. Generated `.ds/` files are
+not configure Linaria or generate product component source. Generated `.ds/` files are
 ignored; original artwork and provenance belong in `assets/brand/`.
 
 ## Inspect and add UI
@@ -56,10 +56,12 @@ Its MCP client discovers entries, invokes preview tools and follows notification
 There are no required TokensPage/ComponentsPage/PatternsPage/CompositionPage
 files, and no separate project browser app to implement or rebuild.
 
-The existing `tokens/Foundation.scenario.tsx` and colocated fixture inspect all
-starter token values. Add/remove fixture names alongside token definitions;
-`ads check` rejects missing coverage and invented names. Styled token samples
-belong to your public review patterns and mount through the same scenario pipeline.
+The existing `tokens/Foundation.scenario.tsx` and colocated fixture visually demonstrate all
+starter token values. The fixture owns `{ token, property, probe }` bindings;
+the public `TokenPreview` pattern owns their presentation and applies the real CSS
+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.
 
 Create a component under `design-system/components/`, export it through `@ds`,
 and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and

package/dist/bootstrap-ds/design-system/index.ts

@@ -2,4 +2,4 @@
 import "./styles.css";
 
 // Add public component and pattern exports here as they are implemented.
-export {};
+export { TokenPreview } from "./patterns/token-preview/TokenPreview";

package/dist/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx

@@ -0,0 +1,4 @@
+import { TokenPreview } from "@ds";
+import { fixture } from "./fixture";
+export const scenario = { title: fixture.title, covers: ["TokenPreview"] };
+export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/bootstrap-ds/design-system/patterns/token-preview/TokenPreview.tsx

@@ -0,0 +1,31 @@
+import { useLayoutEffect, useRef } from "react";
+import { css, cx } from "@linaria/atomic";
+
+export interface TokenSample { token: `--${string}`; property: string; }
+export interface TokenPreviewProps { title: string; samples: readonly TokenSample[]; text: string; }
+const sampleStyle = css`
+  display: inline-block;
+  position: relative;
+  white-space: pre-line;
+  &[data-ads-property="animation-duration"] { animation-duration: var(--ux-token-preview-value); }
+  &[data-ads-property="animation-timing-function"] { animation-timing-function: var(--ux-token-preview-value); }
+  &[data-ads-property="background-color"] { background-color: var(--ux-token-preview-value); }
+  &[data-ads-property="border-radius"] { border-radius: var(--ux-token-preview-value); }
+  &[data-ads-property="box-shadow"] { box-shadow: var(--ux-token-preview-value); }
+  &[data-ads-property="color"] { color: var(--ux-token-preview-value); }
+  &[data-ads-property="font-family"] { font-family: var(--ux-token-preview-value); }
+  &[data-ads-property="font-size"] { font-size: var(--ux-token-preview-value); }
+  &[data-ads-property="font-weight"] { font-weight: var(--ux-token-preview-value); }
+  &[data-ads-property="line-height"] { line-height: var(--ux-token-preview-value); }
+  &[data-ads-property="width"] { width: var(--ux-token-preview-value); }
+  &[data-ads-property="z-index"] { z-index: var(--ux-token-preview-value); }
+`;
+function Sample({ sample, text }: { sample: TokenSample; text: string }) {
+  const ref = useRef<HTMLSpanElement>(null);
+  useLayoutEffect(() => { ref.current?.style.setProperty("--ux-token-preview-value", `var(${sample.token})`); }, [sample.token]);
+  return <span ref={ref} className={cx("ux-token-preview__sample", sampleStyle)} data-ads-token={sample.token} data-ads-property={sample.property}>{text}</span>;
+}
+/** Project-owned review UI. Values always come from the real foundation CSS. */
+export function TokenPreview({ title, samples, text }: TokenPreviewProps) {
+  return <section className="ux-token-preview"><h1>{title}</h1>{samples.map(sample => <div key={`${sample.token}:${sample.property}`} className="ux-token-preview__item"><code className="ux-token-preview__name">{sample.token}</code><Sample sample={sample} text={text}/></div>)}</section>;
+}

package/dist/bootstrap-ds/design-system/patterns/token-preview/fixture.ts

@@ -0,0 +1,8 @@
+export const fixture = {
+  "title": "Token preview",
+  "text": "Aa",
+  samples: [
+    {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--space-4", "property": "width", "probe": "13.375px"},
+  ]
+} as const;

package/dist/bootstrap-ds/design-system/tokens/Foundation.fixture.ts

@@ -1,47 +1,48 @@
 export const fixture = {
   "title": "Foundation",
-  "tokens": [
-    "--accent",
-    "--accent-fg",
-    "--accent-hover",
-    "--bg-canvas",
-    "--bg-hover",
-    "--bg-surface",
-    "--border-default",
-    "--border-focus",
-    "--border-w",
-    "--dur-fast",
-    "--dur-normal",
-    "--ease-standard",
-    "--focus-offset",
-    "--focus-w",
-    "--font-mono",
-    "--font-sans",
-    "--leading-normal",
-    "--leading-tight",
-    "--radius-lg",
-    "--radius-md",
-    "--radius-sm",
-    "--shadow-raised",
-    "--shadow-xs",
-    "--space-0",
-    "--space-12",
-    "--space-16",
-    "--space-2",
-    "--space-4",
-    "--space-6",
-    "--space-8",
-    "--text-base",
-    "--text-body",
-    "--text-inverse",
-    "--text-lg",
-    "--text-muted",
-    "--text-sm",
-    "--text-strong",
-    "--text-xl",
-    "--weight-medium",
-    "--weight-normal",
-    "--weight-semibold",
-    "--z-overlay"
+  "text": "Aa",
+  samples: [
+    {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--accent-fg", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--accent-hover", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-canvas", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-hover", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-surface", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-default", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-focus", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-w", "property": "width", "probe": "13.375px"},
+    {"token": "--dur-fast", "property": "animation-duration", "probe": "0.375s"},
+    {"token": "--dur-normal", "property": "animation-duration", "probe": "0.375s"},
+    {"token": "--ease-standard", "property": "animation-timing-function", "probe": "cubic-bezier(.13,.27,.61,.83)"},
+    {"token": "--focus-offset", "property": "width", "probe": "13.375px"},
+    {"token": "--focus-w", "property": "width", "probe": "13.375px"},
+    {"token": "--font-mono", "property": "font-family", "probe": "monospace, serif"},
+    {"token": "--font-sans", "property": "font-family", "probe": "monospace, serif"},
+    {"token": "--leading-normal", "property": "line-height", "probe": "2.375"},
+    {"token": "--leading-tight", "property": "line-height", "probe": "2.375"},
+    {"token": "--radius-lg", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--radius-md", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--radius-sm", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--shadow-raised", "property": "box-shadow", "probe": "1px 3px 5px rgb(31, 97, 163)"},
+    {"token": "--shadow-xs", "property": "box-shadow", "probe": "1px 3px 5px rgb(31, 97, 163)"},
+    {"token": "--space-0", "property": "width", "probe": "13.375px"},
+    {"token": "--space-12", "property": "width", "probe": "13.375px"},
+    {"token": "--space-16", "property": "width", "probe": "13.375px"},
+    {"token": "--space-2", "property": "width", "probe": "13.375px"},
+    {"token": "--space-4", "property": "width", "probe": "13.375px"},
+    {"token": "--space-6", "property": "width", "probe": "13.375px"},
+    {"token": "--space-8", "property": "width", "probe": "13.375px"},
+    {"token": "--text-base", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-body", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-inverse", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-lg", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-muted", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-sm", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-strong", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-xl", "property": "font-size", "probe": "41.375px"},
+    {"token": "--weight-medium", "property": "font-weight", "probe": "327"},
+    {"token": "--weight-normal", "property": "font-weight", "probe": "327"},
+    {"token": "--weight-semibold", "property": "font-weight", "probe": "327"},
+    {"token": "--z-overlay", "property": "z-index", "probe": "367"},
   ]
 } as const;

package/dist/bootstrap-ds/design-system/tokens/Foundation.scenario.tsx

@@ -1,14 +1,4 @@
-import { useEffect, useState } from "react";
+import { TokenPreview } from "@ds";
 import { fixture } from "./Foundation.fixture";
-export const scenario = { title: fixture.title, covers: [], tokens: fixture.tokens };
-export default function Scenario() {
-  const [values, setValues] = useState<Record<string, string>>({});
-  useEffect(() => {
-    const read = () => { const style = getComputedStyle(document.documentElement); setValues(Object.fromEntries(fixture.tokens.map(name => [name, style.getPropertyValue(name).trim()]))); };
-    read();
-    const observer = new MutationObserver(read);
-    observer.observe(document.documentElement, {attributes: true, attributeFilter: ["data-theme"]});
-    return () => observer.disconnect();
-  }, []);
-  return <section><h1>{fixture.title}</h1><dl>{fixture.tokens.map(name => <div key={name}><dt><code>{name}</code></dt><dd>{values[name]}</dd></div>)}</dl></section>;
-}
+export const scenario = { title: fixture.title, covers: ["TokenPreview"], samples: fixture.samples };
+export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/bootstrap-ds/ds.config.json

@@ -9,5 +9,15 @@
         "--watch"
       ]
     }
+  },
+  "boundaries": {
+    "styleWrites": [
+      {
+        "file": "design-system/patterns/token-preview/TokenPreview.tsx",
+        "properties": [
+          "--ux-token-preview-value"
+        ]
+      }
+    ]
   }
 }

package/dist/check.mjs

@@ -5,7 +5,7 @@ import postcss from "postcss";
 import valueParser from "postcss-value-parser";
 import { importViolation, isInside, loadConfig, sourceFiles, isDevelopmentFile, isTestFile } from "./config.mjs";
 import { inspectTokens, references } from "./tokens.mjs";
-import { foundationFiles, isSharedToken } from "./token-policy.mjs";
+import { foundationFiles, foundationImportTarget, isSharedToken } from "./token-policy.mjs";
 import { inspectAssets } from "./assets.mjs";
 import { appImportViolation, showcaseImportViolation, checkComponentVariable, importResolver, projectCompilerOptions, isUiCssProperties, styleWriteViolation } from "./boundaries.mjs";
 import { inspectPublicProps } from "./public-props.mjs";
@@ -51,14 +51,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     const css = postcss.parse(readFileSync(foundationEntry, "utf8"), { from: foundationEntry });
     const imports = css.nodes.filter((node) => node.type !== "comment");
     const expected = foundationFiles.filter((name) => name !== "fonts.css" || existsSync(path.join(dsRoot, config.tokenDir, name))).map((name) => path.join(dsRoot, config.tokenDir, name));
-    const actual = imports.map((node) => {
-      if (node.type !== "atrule" || node.name !== "import" || node.nodes) return null;
-      const parts = valueParser(node.params).nodes.filter((part) => part.type !== "space" && part.type !== "comment");
-      if (parts.length !== 1) return null;
-      const part = parts[0];
-      const value = part.type === "string" ? part.value : part.type === "function" && part.value === "url" && part.nodes.length === 1 ? part.nodes[0].value : null;
-      return value ? path.resolve(path.dirname(foundationEntry), value) : null;
-    });
+    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 }) {

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/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.