@reqvire-org/ads 0.3.3 → 0.3.5

package/dist/scenarios.mjs

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { existsSync } from "node:fs";
 import ts from "typescript";
+import { publicApi } from "./public-api.mjs";
 import { uiOperation } from "./ui-framework.mjs";
 import { isDevelopmentFile, isInside, isScenarioFile, sourceFiles } from "./config.mjs";
 import { projectCompilerOptions } from "./boundaries.mjs";
@@ -27,46 +28,17 @@ function literal(node, checker, seen = new Set()) {
 }
 
 export function publicUi(program, options) {
-  const checker = program.getTypeChecker();
-  const entry = program.getSourceFile(path.join(options.dsRoot, options.config.publicEntry));
-  const module = entry && checker.getSymbolAtLocation(entry);
-  const items = [];
-  for (const exported of module ? checker.getExportsOfModule(module) : []) {
-    let symbol = exported;
-    if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
-    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
-    if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
-    const file = declaration.getSourceFile().fileName;
-    if (isDevelopmentFile(file, options)) continue;
-    const kind = isInside(path.join(options.dsRoot, "components"), file) ? "components" : isInside(path.join(options.dsRoot, "patterns"), file) ? "patterns" : null;
-    if (!kind) continue;
-    let renderable = false;
-    function visit(node) {
-      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) renderable = true;
-      if (ts.isCallExpression(node) && ["createElement", "forwardRef", "memo"].includes(uiOperation(node.expression, checker))) renderable = true;
-      if (ts.isTaggedTemplateExpression(node)) {
-        let tag = node.tag;
-        if (ts.isCallExpression(tag)) tag = tag.expression;
-        let base = tag;
-        while (ts.isPropertyAccessExpression(base)) base = base.expression;
-        const symbol = checker.getSymbolAtLocation(base);
-        if (symbol?.declarations?.some(item => ts.isImportSpecifier(item) && (item.propertyName ?? item.name).text === "styled" && item.parent.parent.parent.moduleSpecifier.text.startsWith("@linaria/") || ts.isNamespaceImport(item) && item.parent.parent.moduleSpecifier.text.startsWith("@linaria/") && /^\.styled(?:\.|$)/.test(tag.getText().slice(base.getText().length)))) renderable = true;
-      }
-      ts.forEachChild(node, visit);
-    }
-    visit(declaration);
-    items.push({ name: exported.name, kind, file, declaration, renderable });
-  }
-  return items;
+  return publicApi(program, options).filter(item => item.kind !== "controllers");
 }
 
 /** Discover metadata statically. The MCP process never imports scenario modules. */
 export function inspectScenarios(options, suppliedProgram) {
   const { root, dsRoot } = options;
   const files = sourceFiles(dsRoot).filter(isScenarioFile);
-  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), ...files], projectCompilerOptions(options));
+  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), ...files], { ...projectCompilerOptions(options), allowJs: true });
   const known = new Map(publicUi(program, options).map((item) => [item.name, item]));
   const checker = program.getTypeChecker();
+  const behaviorApis = new Map(publicApi(program, options).filter(item => !item.renderable && item.behavioral).map(item => [item.name, item]));
   const tokenNames = new Set(inspectTokens(root).tokens.map(token => token.name));
   const scenarios = [];
   const diagnostics = [];
@@ -105,21 +77,22 @@ export function inspectScenarios(options, suppliedProgram) {
     }
     const fixtureBase = path.basename(file).startsWith("Scenario.") ? path.join(path.dirname(file), "fixture") : file.replace(/\.scenario\.[^.]+$/, ".fixture");
     if (![".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].some(extension => existsSync(fixtureBase + extension))) report(file, "Keep this scenario's inputs beside it: fixture.ts (directory entry) or <Owner>.fixture.ts (flat entry). An empty fixture is valid for a component without inputs.");
-    if (!metadata || Object.keys(metadata).some((key) => !["title", "covers", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
+    if (!metadata || Object.keys(metadata).some((key) => !["title", "covers", "exercises", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
+      || Object.hasOwn(metadata, "exercises") && (!Array.isArray(metadata.exercises) || metadata.exercises.some(name => typeof name !== "string" || !behaviorApis.has(name)))
       || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--")))
       || kind === "tokens" && (Object.hasOwn(metadata, "tokens") || !validTokenSamples(metadata.samples) || !metadata.covers.some(name => known.get(name)?.kind === "patterns"))
       || Object.hasOwn(metadata, "samples") && !validTokenSamples(metadata.samples)) {
-      report(file, "Export static metadata with nonempty covers. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
+      report(file, "Export static metadata with nonempty covers naming rendered public UI. Optional exercises names public behavioral APIs, not rendered UI. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
     }
     if (!["composition", "tokens"].includes(kind) && metadata.covers.some((name) => known.get(name).kind !== kind)) report(file, "Component scenarios cover primitives; pattern scenarios cover patterns. Use composition/ for larger interfaces.");
     const tokens = [...new Set([...(metadata.tokens ?? []), ...(metadata.samples ?? []).map(sample => sample.token)])];
     for (const name of tokens) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real foundation token.` });
-    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(metadata.exercises ? { exercises: [...new Set(metadata.exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }
 
-export function inspectScenarioCoverage(options, program, report) {
+export function inspectScenarioCoverage(options, program, report, advise = () => {}) {
   const registry = inspectScenarios(options, program);
   for (const item of registry.diagnostics) report(path.join(options.root, item.file), item.rule, item.message, item.line, item.column);
   const checker = program.getTypeChecker();
@@ -153,7 +126,7 @@ export function inspectScenarioCoverage(options, program, report) {
     return symbol.declarations?.length ? symbol : null;
   }
   const identities = new Map();
-  for (const item of ui) {
+  for (const item of publicApi(program, options)) {
     if (!identities.has(item.declaration)) identities.set(item.declaration, new Set());
     identities.get(item.declaration).add(item.name);
   }
@@ -165,12 +138,16 @@ export function inspectScenarioCoverage(options, program, report) {
   for (const scenario of registry.scenarios) {
     const source = program.getSourceFile(path.join(options.root, scenario.file));
     const rendered = new Set();
+    const exercised = new Set(), referencedApis = new Set();
     const referencedTokens = new Set();
     let samplesPassed = false;
     const visited = new Set();
     function visit(node, reached = false) {
       if (!node || visited.has(node)) return;
-      if (!reached && (ts.isFunctionDeclaration(node) || ts.isVariableDeclaration(node))) return;
+      if (!reached && ts.isFunctionDeclaration(node)) return;
+      // Calls/construction in a mounted adapter execute even when only a result
+      // property is read later. Unused literal fixture fields still do not count.
+      if (!reached && ts.isVariableDeclaration(node) && !(node.initializer && (ts.isCallExpression(node.initializer) || ts.isNewExpression(node.initializer)))) return;
       if (!reached && (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && !ts.isCallExpression(node.parent) && !ts.isJsxExpression(node.parent)) return;
       visited.add(node);
       if (ts.isStringLiteralLike(node) && (isSharedToken(node.text) || scenario.tokens.includes(node.text))) referencedTokens.add(node.text);
@@ -180,18 +157,25 @@ export function inspectScenarioCoverage(options, program, report) {
       if (expression) {
         const symbol = canonical(symbolOf(expression));
         const names = identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]);
-        for (const name of names ?? []) rendered.add(name);
+        for (const name of names ?? []) { rendered.add(name); exercised.add(name); }
         if (scenario.kind === "tokens" && [...names ?? []].some(name => scenario.covers.includes(name))) {
           const attributes = ts.isCallExpression(node) ? literal(node.arguments[1], checker) : Object.assign({}, ...node.attributes.properties.map(attribute => ts.isJsxSpreadAttribute(attribute) ? literal(attribute.expression, checker) : ts.isJsxAttribute(attribute) && ts.isIdentifier(attribute.name) && attribute.initializer && ts.isJsxExpression(attribute.initializer) ? { [attribute.name.text]: literal(attribute.initializer.expression, checker) } : {}));
           if (JSON.stringify(attributes?.samples) === JSON.stringify(scenario.samples)) samplesPassed = true;
         }
       }
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+        let expression = node.expression;
+        if (ts.isPropertyAccessExpression(expression) && ["call", "apply"].includes(expression.name.text)) expression = expression.expression;
+        const symbol = canonical(symbolOf(expression));
+        for (const name of identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]) ?? []) exercised.add(name);
+      }
       // Follow local adapters reachable from the default entry. Unused example
       // functions do not satisfy coverage; production implementations are never
       // traversed to manufacture coverage for their internal dependencies.
       if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node) || ts.isIdentifier(node) && !(ts.isPropertyAccessExpression(node.parent) || ts.isElementAccessExpression(node.parent))) {
         const symbol = canonical(symbolOf(node));
         const declaration = symbol?.valueDeclaration;
+        for (const name of identities.get(declaration ?? symbol?.declarations?.[0]) ?? []) referencedApis.add(name);
         if (declaration && isDevelopmentFile(declaration.getSourceFile().fileName, options)) visit(declaration, true);
       }
       ts.forEachChild(node, child => visit(child, reached && (ts.isExportAssignment(node) || ts.isVariableDeclaration(node))));
@@ -201,6 +185,10 @@ export function inspectScenarioCoverage(options, program, report) {
       if (!rendered.has(name)) report(source.fileName, "scenario-render", `${name} is declared in covers but has no public render reference in this scenario. Render the real API; an import alone does not count.`);
       else covered.add(name);
     }
+    for (const name of scenario.exercises ?? []) {
+      if (!exercised.has(name) && !referencedApis.has(name)) report(source.fileName, "scenario-exercise", `${name} is declared in exercises but has no reachable behavioral use. Imports and unused adapters do not count.`);
+      else if (!exercised.has(name)) advise(source.fileName, "scenario-exercise-review", `${name} is referenced dynamically. Verify its invocation in the registered browser/behavior checks; a reference alone does not prove execution.`);
+    }
     for (const name of referencedTokens) if (!declaredTokens.has(name)) report(source.fileName, "token-scenario-reference", `Reachable scenario input references undeclared token ${name}.`);
     if (scenario.kind === "tokens" && !samplesPassed) report(source.fileName, "token-scenario-render", "Pass the declared fixture.samples into a rendered public review pattern's samples prop. Printing token names or reading unused fixtures is not sample coverage.");
     for (const name of scenario.tokens) {

package/dist/skills/README.md

@@ -3,13 +3,13 @@
 Install the skills you need with `npx skills`:
 
 ```sh
-npx skills add reqvire-org/ads --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-migrate --skill ads-break-ui --skill ads-motion
 ```
 
 For local development, install from this checkout:
 
 ```sh
-npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-migrate --skill ads-break-ui --skill ads-motion
 ```
 
 Each skill includes its own instructions and references. `ads-designer` also
@@ -36,7 +36,7 @@ the browser, and provides a running URL or exact command for review. See the
 |-------|-----|---------|
 | [ads-designer](ads-designer/SKILL.md) | Bootstrap or build UI using the local ADS, with craft/mobile guidance | `$ads-designer build a settings page using this project's ADS` |
 | [ads-import](ads-import/SKILL.md) | Import selected external ADS source, brand artwork, or compatible source token values | `$ads-import /path/to/source-repo component Toast` |
-| [ads-assimilate](ads-assimilate/SKILL.md) | Study an external component library and implement a native counterpart | `$ads-assimilate https://github.com/emilkowalski/sonner` |
+| [ads-migrate](ads-migrate/SKILL.md) | Study an external component library and implement a native counterpart | `$ads-migrate https://github.com/emilkowalski/sonner` |
 | [ads-break-ui](ads-break-ui/SKILL.md) | Stress-test real components/patterns; optionally fix demonstrated failures | `$ads-break-ui AppShell +fix` |
 | [ads-motion](ads-motion/SKILL.md) | Implement, review, audit, or profile motion | `$ads-motion review Toast` |
 

package/dist/skills/ads-break-ui/SKILL.md

@@ -46,6 +46,23 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
 
+
+Controllers are UI behavior owners: private helpers stay with their component or
+pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
+
 Before trusting a preview after edits, check `ads_status.build` or
 `ads://project/build`. Fix build diagnostics in owned source; an older view or
 unreported freshness is not evidence of current code. Notifications may not
@@ -226,6 +243,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 Keep behavior and skin in their runtime owner. Put demo-only sizing and framing
 in a public review/layout pattern; add component props for a deliberate runtime
 API need. Preserve required capabilities while following ownership rules.
+Use tokens for absolute/font-relative lengths, including `ch`, `ex`, `cap`, `ic`
+and `lh`; calculations and fallback values follow the same rule. Structural
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

package/dist/skills/ads-designer/SKILL.md

@@ -78,6 +78,23 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
 
+Controllers are UI behavior owners: private helpers stay with their component or
+pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
+
+
 Check `ads_status.previewWatch` before launching another preview builder. With a
 managed watcher, edit owned sources, wait for the rebuild and invoke the preview
 again; the client already starts and stops the builder through `ads mcp`. Check
@@ -153,7 +170,7 @@ Do not assume it has a particular component, hook, font, or token helper.
 Record the source revision and required dependencies.
 
 Use the ADS import workflow to bring selected existing ADS items into the target,
-or assimilation to create a native component from an upstream library. Follow
+or migration to create a native component from an upstream library. Follow
 those workflows directly if the corresponding skills are unavailable: copy
 selected source and its dependency closure, or study/reproduce the upstream
 contract; integrate local ownership, exports, styles, assets, credits, applicable
@@ -364,6 +381,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 Keep behavior and skin in their runtime owner. Put demo-only sizing and framing
 in a public review/layout pattern; add component props for a deliberate runtime
 API need. Preserve required capabilities while following ownership rules.
+Use tokens for absolute/font-relative lengths, including `ch`, `ex`, `cap`, `ic`
+and `lh`; calculations and fallback values follow the same rule. Structural
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md

@@ -241,3 +241,10 @@ Run `npm run build` after adding or changing components. Add meaningful tests
 for stateful behavior, accessibility, gestures, or async lifecycle where needed.
 Run `npm run dev` to inspect the real showcase. A screenshot alone does not
 verify interaction or animation. Generated output and dependencies are not source.
+
+Shared behavior may live in `controllers/<Name>/`; private controllers stay with
+their component/pattern. Use the configured framework and declared dependencies.
+Behavior contracts/checks are development-only, and scenario `exercises` links
+public hooks to demonstrations separately from rendered `covers`. Read the
+installed ADS package's `docs/BEHAVIORS.md` or MCP `ads://guides/behaviors` before
+registering guarantees, profiles and verification.

package/dist/skills/ads-designer/references/cli.md

@@ -102,7 +102,7 @@ script but does not install the project preview compiler. Integrate its graph
 compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
 then use the same foundation and Linaria extraction as the application. Source discovery,
 selected component/pattern/style/brand imports, explicit theme-value imports, and
-assimilation are agent workflows. There is no CLI `import` command. Core checks
+migration are agent workflows. There is no CLI `import` command. Core checks
 do not copy source, import values, or establish behavior/motion parity; continue
 project type checking, meaningful tests, and browser comparisons.
 

package/dist/skills/ads-designer/references/design-craft.md

@@ -56,7 +56,7 @@ changing them to a generic default.
 
 Keep typed props, examples, state behavior, token hooks, and important tradeoffs
 in the item README. Record concrete upstream influences, authors, revision, and
-applicable notices when importing or assimilating source. Do not describe an
+applicable notices when importing or migrating source. Do not describe an
 adapted implementation as independent solely because it uses native primitives.
 
 Run the actual project's checks after changes and inspect the real consumer

package/dist/skills/ads-import/SKILL.md

@@ -42,6 +42,23 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
 
+Controllers are UI behavior owners: private helpers stay with their component or
+pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
+
+
 Before trusting a preview after edits, check `ads_status.build` or
 `ads://project/build`. Fix build diagnostics in owned source; an older view or
 unreported freshness is not evidence of current code. Notifications may not
@@ -331,6 +348,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 Keep behavior and skin in their runtime owner. Put demo-only sizing and framing
 in a public review/layout pattern; add component props for a deliberate runtime
 API need. Preserve required capabilities while following ownership rules.
+Use tokens for absolute/font-relative lengths, including `ch`, `ex`, `cap`, `ic`
+and `lh`; calculations and fallback values follow the same rule. Structural
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

package/dist/skills/ads-import/references/cli.md

@@ -102,7 +102,7 @@ script but does not install the project preview compiler. Integrate its graph
 compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
 then use the same foundation and Linaria extraction as the application. Source discovery,
 selected component/pattern/style/brand imports, explicit theme-value imports, and
-assimilation are agent workflows. There is no CLI `import` command. Core checks
+migration are agent workflows. There is no CLI `import` command. Core checks
 do not copy source, import values, or establish behavior/motion parity; continue
 project type checking, meaningful tests, and browser comparisons.
 

package/dist/skills/{ads-assimilate → ads-migrate}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: ads-assimilate
-description: "Implement or refine a native design-system component from a component-library URL, studying the original implementation and verifying behavior, visuals, and motion against the real reference. Use for component assimilation, including local documentation and justified usage lint rules; not for simply installing or wrapping a dependency."
+name: ads-migrate
+description: "Implement or refine a native design-system component from a component-library URL, studying the original implementation and verifying behavior, visuals, and motion against the real reference. Use for component migration, including local documentation and justified usage lint rules; not for simply installing or wrapping a dependency."
 ---
 
-# ADS Assimilate
+# ADS Migrate
 
 When ADS MCP is connected, discover public UI and addressable scenarios with
 `ads_status`/`ads_catalog`; use `ads_tokens` for definitions and values, and
@@ -43,6 +43,23 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
 
+
+Controllers are UI behavior owners: private helpers stay with their component or
+pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
+
 Before trusting a preview after edits, check `ads_status.build` or
 `ads://project/build`. Fix build diagnostics in owned source; an older view or
 unreported freshness is not evidence of current code. Notifications may not
@@ -75,8 +92,8 @@ workflows. Do not look for a built-in or optional UI catalogue in the tool.
 Invocation accepts a library/repository/documentation URL as its first argument:
 
 ```text
-$ads-assimilate <library-url> [component-name] [requirements]
-$ads-assimilate https://github.com/emilkowalski/sonner toast
+$ads-migrate <library-url> [component-name] [requirements]
+$ads-migrate https://github.com/emilkowalski/sonner toast
 ```
 
 The URL is the required reference, not a request to install the library into the
@@ -147,7 +164,7 @@ the scenario; larger entries belong under `composition/`. Browsing pages only
 select these entries. The scenario labels, controls and review layouts are public ADS entities with defined
 APIs. The outer shell belongs to the tool client. Showcase/scenario files define no CSS, custom classes, or widget markup.
 Change the owning ADS pattern when a frame layout is missing; do not recreate
-the assimilated UI there or override its internals.
+the migrated UI there or override its internals.
 
 The showcase is a minimal shell plus an MCP client and Apps host, supplied by ADS
 tooling. It discovers Tokens/Components/Patterns/Composition entries through MCP
@@ -274,6 +291,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 Keep behavior and skin in their runtime owner. Put demo-only sizing and framing
 in a public review/layout pattern; add component props for a deliberate runtime
 API need. Preserve required capabilities while following ownership rules.
+Use tokens for absolute/font-relative lengths, including `ch`, `ex`, `cap`, `ic`
+and `lh`; calculations and fallback values follow the same rule. Structural
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

package/dist/skills/ads-migrate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ADS Migrate"
+  short_description: "Adapt reference components into a native design system"
+  default_prompt: "Use $ads-migrate with a component-library URL to implement and verify a native design-system component."

package/dist/skills/{ads-assimilate → ads-migrate}/references/cli.md

@@ -102,7 +102,7 @@ script but does not install the project preview compiler. Integrate its graph
 compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
 then use the same foundation and Linaria extraction as the application. Source discovery,
 selected component/pattern/style/brand imports, explicit theme-value imports, and
-assimilation are agent workflows. There is no CLI `import` command. Core checks
+migration are agent workflows. There is no CLI `import` command. Core checks
 do not copy source, import values, or establish behavior/motion parity; continue
 project type checking, meaningful tests, and browser comparisons.
 

package/dist/skills/{ads-assimilate → ads-migrate}/references/native-implementation.md

@@ -112,3 +112,14 @@ README and in a References and credits section in the component-local README.
 Link the library and the actual source/docs/articles studied, identify the
 version or commit, name the authors, and explain the concrete influences.
 Document material adaptations and agreed deviations beside the public contract.
+
+## Behavioral evidence
+
+Keep private controllers in their owner; extract a shared controller only for a
+real reuse need. Register optional behavior guarantees and real colocated checks;
+see `ads://guides/behaviors` or the installed package's `docs/BEHAVIORS.md`. Link
+public hooks with scenario `exercises`, while `covers` still requires rendered UI.
+Move reviewed scratchpad investigations into maintained owner checks. Disabling
+StrictMode can isolate an upstream lifecycle defect; keep a development StrictMode
+check and verify the native port's setup/cleanup/setup independently. Use first-
+render browser cases for lazy intrinsic sizing, retaining offscreen rendering.

package/dist/skills/ads-motion/SKILL.md

@@ -63,6 +63,23 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
 
+
+Controllers are UI behavior owners: private helpers stay with their component or
+pattern; reusable controllers use discovered `controllers/<Name>` units. Use the
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
+
 Before trusting a preview after edits, check `ads_status.build` or
 `ads://project/build`. Fix build diagnostics in owned source; an older view or
 unreported freshness is not evidence of current code. Notifications may not
@@ -221,6 +238,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 Keep behavior and skin in their runtime owner. Put demo-only sizing and framing
 in a public review/layout pattern; add component props for a deliberate runtime
 API need. Preserve required capabilities while following ownership rules.
+Use tokens for absolute/font-relative lengths, including `ch`, `ex`, `cap`, `ic`
+and `lh`; calculations and fallback values follow the same rule. Structural
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

package/dist/tokens.mjs

@@ -4,6 +4,7 @@ import postcss from "postcss";
 import valueParser from "postcss-value-parser";
 import { loadConfig, sourceFiles } from "./config.mjs";
 import { foundationFiles, isSharedToken, tokenContract } from "./token-policy.mjs";
+import { dimensionValue, numericCssUnit } from "./css-values.mjs";
 import { checkComponentVariable } from "./boundaries.mjs";
 
 export { tokenContract };
@@ -33,8 +34,8 @@ function matchesType(value, type) {
   if (/^(?:inherit|initial|unset|revert(?:-layer)?)$/.test(value)) return true;
   switch (type) {
     case "color": return /^(?:#[\da-f]{3,8}|[a-z][\w-]*|(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix|light-dark)\([\s\S]+\))$/i.test(value);
-    case "dimension": return /^[-+]?(?:\d*\.)?\d+(?:px|r?em|ch|ex|cap|lh|rlh|v[wh]|[sld]v[wh]|vmin|vmax|cm|mm|in|pt|pc|%)$/i.test(value) || /^[-+]?0(?:\.0+)?$/.test(value);
-    case "duration": return /^[-+]?(?:\d*\.)?\d+m?s$/i.test(value);
+    case "dimension": return dimensionValue(value);
+    case "duration": return ["s", "ms"].includes(numericCssUnit(value));
     case "number": return /^[-+]?(?:\d*\.)?\d+$/.test(value);
     case "easing": return /^(?:linear|ease(?:-in|-out|-in-out)?|step-start|step-end|(?:cubic-bezier|steps|linear)\([\s\S]+\))$/.test(value);
     case "shadow": return value === "none" || /(?:\d(?:px|rem|em)|var\()/.test(value);

package/dist/units.mjs

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import ts from "typescript";
 import postcss from "postcss";
-import { isInside } from "./config.mjs";
+import { isDevelopmentFile, isInside } from "./config.mjs";
 import { importResolver } from "./boundaries.mjs";
 import { isProjectDocument, projectGuideFiles } from "./project-documents.mjs";
 import { foundationFiles, foundationImportTarget } from "./token-policy.mjs";
@@ -16,14 +16,21 @@ export function configurationFiles(options) {
   const { root, config, sourceRoot, dsRoot } = options;
   const files = new Set(["ds.config.json", "package.json"]);
   for (const entry of readdirSync(root, { withFileTypes: true })) {
-    if (entry.isFile() && /^(?:(?:ts|js)config[^/]*\.jsonc?|(?:vite|vitest|linaria|babel|postcss|biome|oxlint)[^/]*\.(?:jsonc?|[cm]?[jt]s)|\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?)$/.test(entry.name)) files.add(entry.name);
+    if (entry.isFile() && /^(?:(?:ts|js)config[^/]*\.jsonc?|(?:vite|vitest|playwright|linaria|babel|postcss|biome|oxlint)[^/]*\.(?:jsonc?|[cm]?[jt]s)|\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?)$/.test(entry.name)) files.add(entry.name);
   }
   const resolve = importResolver(options), visited = new Set();
   function visit(file, entrypoint = false, typeConfig = false) {
     if (!isInside(root, file) || file === root || /(?:^|[\\/])(?:node_modules|\.git|\.ds|dist)(?:[\\/]|$)/.test(path.relative(root, file)) || visited.has(file) || !existsSync(file)) return;
+    // Registering a test command must not reassign its colocated checks or
+    // fixtures to configuration. Those remain in the behavior owner's patch.
+    if (isInside(dsRoot, file) && isDevelopmentFile(file, options)) return;
     if (!entrypoint && isInside(sourceRoot, file) && !isInside(dsRoot, file)) return;
-    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|composition|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
-      if (/\.[jt]sx$|\.(?:scenario|fixture)\./.test(file)) return;
+    if (!entrypoint && isInside(dsRoot, file) && /^(?:components|patterns|controllers|composition|tokens)[\\/]/.test(path.relative(dsRoot, file))) {
+      if (isInside(path.join(dsRoot, "controllers"), file) || isDevelopmentFile(file, options)) return;
+      const folder = path.dirname(file), stem = path.basename(file).split(".")[0];
+      const anchored = ["index", path.basename(folder)].some(name => [".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"].some(extension => existsSync(path.join(folder, name + extension))));
+      const sidecar = path.basename(file).split(".").length > 2 && [".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"].some(extension => existsSync(path.join(folder, stem + extension)));
+      if (anchored || sidecar || /\.[jt]sx$/.test(file)) return;
       if (source.test(file) && /(?:from\s*["'](?:react|preact|@linaria\/)|\b(?:require|import)\s*\(\s*["'](?:react|preact|@linaria\/))/.test(readFileSync(file,"utf8"))) return;
     }
     visited.add(file);
@@ -65,6 +72,10 @@ export function configurationFiles(options) {
     if (["npm", "bun"].includes(watch.command) && watch.args[0] === "run") script(watch.args[1]);
     else for (const argument of [watch.command, ...watch.args]) if (/\.[cm]?[jt]sx?$/.test(argument)) visit(path.resolve(root, argument), true);
   }
+  for (const profile of Object.values(config.mcp.behaviorProfiles)) {
+    if (["npm", "bun"].includes(profile.command) && profile.args[0] === "run") script(profile.args[1]);
+    else for (const argument of [profile.command, ...profile.args]) if (/\.[cm]?[jt]sx?$/.test(argument)) visit(path.resolve(root, argument), true);
+  }
   return files;
 }
 
@@ -90,14 +101,14 @@ export function inspectUnits(options) {
   const flatFamilies = new Set(files.filter(file => /\.scenario\.[cm]?[jt]sx?$/.test(file)).map(file => path.posix.dirname(file)));
   const directories = new Set(files.filter(file => /(?:^|\/)Scenario\.[cm]?[jt]sx?$/.test(file)).map(file => slash(path.dirname(file))));
   for (const file of files) {
-    if (!/^(?:components|patterns|composition)\//.test(file) || !source.test(file)) continue;
+    if (!/^(?:components|patterns|controllers|composition)\//.test(file) || !source.test(file)) continue;
     const directory = slash(path.dirname(file)), name = path.basename(file).replace(source, "");
     if (!directory.includes("/") || /\.(?:scenario|fixture|scenario-adapter)$/.test(name)) continue;
     if (flatFamilies.has(directory)) continue;
     if (name === "index" || sameName(name) === sameName(path.posix.basename(directory)) || name === "fixture") directories.add(directory);
   }
   const directoryUnits = [...directories].sort((a, b) => b.length - a.length);
-  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|composition)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
+  const flatUnits = [...new Set(files.filter(file => /^(?:components|patterns|controllers|composition)\//.test(file) && source.test(file) && !directoryUnits.some(directory => file.startsWith(directory + "/"))).map(file => {
     const base = path.basename(file).split(".")[0];
     return slash(path.join(path.dirname(file), base));
   }))].sort((a, b) => b.length - a.length);
@@ -113,7 +124,7 @@ export function inspectUnits(options) {
     if (relative.startsWith(tokenDir + "/")) return "tokens";
     if (relative.startsWith("assets/")) return relative.split("/").length > 2 ? relative.split("/").slice(0, 2).join("/") : "assets";
     if (!relative.includes("/")) return /(?:\.(?:md|txt)$|^LICENSE$)/i.test(relative) ? "documentation" : "foundation";
-    if (!/^(?:components|patterns|composition)\//.test(relative)) return relative.split("/")[0];
+    if (!/^(?:components|patterns|controllers|composition)\//.test(relative)) return relative.split("/")[0];
     for (const directory of directoryUnits) if (relative.startsWith(directory + "/")) return directory;
     for (const unit of flatUnits) if (relative.startsWith(unit + "/") || relative.startsWith(unit + ".")) return unit;
     const base = path.basename(relative).split(".")[0];
@@ -142,7 +153,7 @@ export function inspectUnits(options) {
 function boundaryCompanion(unit) { return !["configuration", "documentation", "assets"].includes(unit.split("/")[0]); }
 
 export function validateUnitId(unit) {
-  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "composition"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
+  if (typeof unit !== "string" || unit.length > 256 || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(unit) || ["components", "patterns", "controllers", "composition"].includes(unit)) throw fail("Select one ADS unit ID from ads_units or an unoccupied owner path following its colocation convention.");
 }
 
 /** Reject arbitrary file batches, even when every path is inside the ADS. */
@@ -207,7 +218,7 @@ export function checkUnitCandidate(afterOptions, unit, changes, before) {
   }
   const exportChange = changes.find(change => before.relative(change.path) === before.publicEntry);
   if (exportChange) {
-    if (!["components", "patterns"].includes(unit.split("/")[0])) throw fail("Only a component/pattern unit may update its public re-exports.", exportChange.path);
+    if (!["components", "patterns", "controllers"].includes(unit.split("/")[0])) throw fail("Only a component/pattern/controller unit may update its public re-exports.", exportChange.path);
     const current = exportChange.originalContent ?? "", proposed = exportChange.content;
     if (proposed === null) throw fail("The shared public entry cannot be deleted.", exportChange.path);
     const resolve = importResolver(afterOptions);