@reqvire-org/ads 0.3.21 → 0.3.24

package/dist/skills/ads-break-ui/references/contracts.md

@@ -152,6 +152,13 @@ cannot be established. Registered paint consumers list their allowed binding IDs
 borrowing a peer's family or private token remains invalid. Bindings are scoped
 to their actual root; portals outside it need deliberate project integration.
 
+A registered binding producer may combine two accessible color references as
+`light-dark(var(--light-token), var(--dark-token))`. The App paint audit checks
+both branches and their observed effect in the active color scheme. Raw colors,
+unknown/private tokens and SVG URLs inside this color function remain invalid.
+This derived binding form does not widen public paint-input types; use constrained
+references for each theme input and verify both color schemes in browser checks.
+
 The App audit checks current mounted instances, accessible values, local SVG
 resources and computed paint-property responses. Visibility and complete rendered
 output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
@@ -238,7 +245,10 @@ MCP before replacing a package used by a running server. Then:
 5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
 
 Migration never edits live source or bypasses gates. It retains stable scenario
-IDs and check case IDs. An optional static `scenario.id` preserves a legacy
+IDs, check case IDs and directory ownership. A canonical `<Owner>.ads.scenario.tsx` is the same
+development entry as `Scenario.tsx`, even without a production entry or owner
+contract. Explicit flat IDs and existing flat peer families remain separate.
+An optional static `scenario.id` preserves a legacy
 identity when a renamed filename would otherwise be ambiguous; it must stay
 inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
 in legacy registration with a note until deliberately resolved. Unknown runner

package/dist/skills/ads-break-ui/references/guarded-editing.md

@@ -28,6 +28,16 @@ as passing evidence for the live project.
 draft argument. There is no dedicated selected-check runner for drafts yet.
 Use a dry-run transaction for genuinely coupled draft patches.
 
+Build notifications are deferred until the showcase finishes initial discovery;
+a preview cannot be opened with an incomplete tool list. A missing App tool is a
+host-startup failure, not evidence that component behavior failed. Preserve the
+draft and inspect the host diagnostic.
+
+Registered project scripts default to 60 seconds each. A guarded configuration
+change can set `mcp.mutationCheckTimeoutMs` (100–300000 ms) after measuring build
+duration and contention. Timeouts name the command, budget and elapsed time;
+behavior-profile budgets are separate. Do not drop checks to fit either budget.
+
 Behavior-run performance belongs to both orchestration and project checks. ADS
 selects affected owners, filters registered Playwright case tags and shares one
 candidate host per run. The project owns assertions, browser setup, worker count,

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

@@ -152,6 +152,13 @@ cannot be established. Registered paint consumers list their allowed binding IDs
 borrowing a peer's family or private token remains invalid. Bindings are scoped
 to their actual root; portals outside it need deliberate project integration.
 
+A registered binding producer may combine two accessible color references as
+`light-dark(var(--light-token), var(--dark-token))`. The App paint audit checks
+both branches and their observed effect in the active color scheme. Raw colors,
+unknown/private tokens and SVG URLs inside this color function remain invalid.
+This derived binding form does not widen public paint-input types; use constrained
+references for each theme input and verify both color schemes in browser checks.
+
 The App audit checks current mounted instances, accessible values, local SVG
 resources and computed paint-property responses. Visibility and complete rendered
 output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
@@ -238,7 +245,10 @@ MCP before replacing a package used by a running server. Then:
 5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
 
 Migration never edits live source or bypasses gates. It retains stable scenario
-IDs and check case IDs. An optional static `scenario.id` preserves a legacy
+IDs, check case IDs and directory ownership. A canonical `<Owner>.ads.scenario.tsx` is the same
+development entry as `Scenario.tsx`, even without a production entry or owner
+contract. Explicit flat IDs and existing flat peer families remain separate.
+An optional static `scenario.id` preserves a legacy
 identity when a renamed filename would otherwise be ambiguous; it must stay
 inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
 in legacy registration with a note until deliberately resolved. Unknown runner

package/dist/skills/ads-designer/references/guarded-editing.md

@@ -28,6 +28,16 @@ as passing evidence for the live project.
 draft argument. There is no dedicated selected-check runner for drafts yet.
 Use a dry-run transaction for genuinely coupled draft patches.
 
+Build notifications are deferred until the showcase finishes initial discovery;
+a preview cannot be opened with an incomplete tool list. A missing App tool is a
+host-startup failure, not evidence that component behavior failed. Preserve the
+draft and inspect the host diagnostic.
+
+Registered project scripts default to 60 seconds each. A guarded configuration
+change can set `mcp.mutationCheckTimeoutMs` (100–300000 ms) after measuring build
+duration and contention. Timeouts name the command, budget and elapsed time;
+behavior-profile budgets are separate. Do not drop checks to fit either budget.
+
 Behavior-run performance belongs to both orchestration and project checks. ADS
 selects affected owners, filters registered Playwright case tags and shares one
 candidate host per run. The project owns assertions, browser setup, worker count,

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

@@ -152,6 +152,13 @@ cannot be established. Registered paint consumers list their allowed binding IDs
 borrowing a peer's family or private token remains invalid. Bindings are scoped
 to their actual root; portals outside it need deliberate project integration.
 
+A registered binding producer may combine two accessible color references as
+`light-dark(var(--light-token), var(--dark-token))`. The App paint audit checks
+both branches and their observed effect in the active color scheme. Raw colors,
+unknown/private tokens and SVG URLs inside this color function remain invalid.
+This derived binding form does not widen public paint-input types; use constrained
+references for each theme input and verify both color schemes in browser checks.
+
 The App audit checks current mounted instances, accessible values, local SVG
 resources and computed paint-property responses. Visibility and complete rendered
 output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
@@ -238,7 +245,10 @@ MCP before replacing a package used by a running server. Then:
 5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
 
 Migration never edits live source or bypasses gates. It retains stable scenario
-IDs and check case IDs. An optional static `scenario.id` preserves a legacy
+IDs, check case IDs and directory ownership. A canonical `<Owner>.ads.scenario.tsx` is the same
+development entry as `Scenario.tsx`, even without a production entry or owner
+contract. Explicit flat IDs and existing flat peer families remain separate.
+An optional static `scenario.id` preserves a legacy
 identity when a renamed filename would otherwise be ambiguous; it must stay
 inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
 in legacy registration with a note until deliberately resolved. Unknown runner

package/dist/skills/ads-import/references/guarded-editing.md

@@ -28,6 +28,16 @@ as passing evidence for the live project.
 draft argument. There is no dedicated selected-check runner for drafts yet.
 Use a dry-run transaction for genuinely coupled draft patches.
 
+Build notifications are deferred until the showcase finishes initial discovery;
+a preview cannot be opened with an incomplete tool list. A missing App tool is a
+host-startup failure, not evidence that component behavior failed. Preserve the
+draft and inspect the host diagnostic.
+
+Registered project scripts default to 60 seconds each. A guarded configuration
+change can set `mcp.mutationCheckTimeoutMs` (100–300000 ms) after measuring build
+duration and contention. Timeouts name the command, budget and elapsed time;
+behavior-profile budgets are separate. Do not drop checks to fit either budget.
+
 Behavior-run performance belongs to both orchestration and project checks. ADS
 selects affected owners, filters registered Playwright case tags and shares one
 candidate host per run. The project owns assertions, browser setup, worker count,

package/dist/skills/ads-migrate/references/contracts.md

@@ -152,6 +152,13 @@ cannot be established. Registered paint consumers list their allowed binding IDs
 borrowing a peer's family or private token remains invalid. Bindings are scoped
 to their actual root; portals outside it need deliberate project integration.
 
+A registered binding producer may combine two accessible color references as
+`light-dark(var(--light-token), var(--dark-token))`. The App paint audit checks
+both branches and their observed effect in the active color scheme. Raw colors,
+unknown/private tokens and SVG URLs inside this color function remain invalid.
+This derived binding form does not widen public paint-input types; use constrained
+references for each theme input and verify both color schemes in browser checks.
+
 The App audit checks current mounted instances, accessible values, local SVG
 resources and computed paint-property responses. Visibility and complete rendered
 output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
@@ -238,7 +245,10 @@ MCP before replacing a package used by a running server. Then:
 5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
 
 Migration never edits live source or bypasses gates. It retains stable scenario
-IDs and check case IDs. An optional static `scenario.id` preserves a legacy
+IDs, check case IDs and directory ownership. A canonical `<Owner>.ads.scenario.tsx` is the same
+development entry as `Scenario.tsx`, even without a production entry or owner
+contract. Explicit flat IDs and existing flat peer families remain separate.
+An optional static `scenario.id` preserves a legacy
 identity when a renamed filename would otherwise be ambiguous; it must stay
 inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
 in legacy registration with a note until deliberately resolved. Unknown runner

package/dist/skills/ads-migrate/references/guarded-editing.md

@@ -28,6 +28,16 @@ as passing evidence for the live project.
 draft argument. There is no dedicated selected-check runner for drafts yet.
 Use a dry-run transaction for genuinely coupled draft patches.
 
+Build notifications are deferred until the showcase finishes initial discovery;
+a preview cannot be opened with an incomplete tool list. A missing App tool is a
+host-startup failure, not evidence that component behavior failed. Preserve the
+draft and inspect the host diagnostic.
+
+Registered project scripts default to 60 seconds each. A guarded configuration
+change can set `mcp.mutationCheckTimeoutMs` (100–300000 ms) after measuring build
+duration and contention. Timeouts name the command, budget and elapsed time;
+behavior-profile budgets are separate. Do not drop checks to fit either budget.
+
 Behavior-run performance belongs to both orchestration and project checks. ADS
 selects affected owners, filters registered Playwright case tags and shares one
 candidate host per run. The project owns assertions, browser setup, worker count,

package/dist/skills/ads-motion/references/contracts.md

@@ -152,6 +152,13 @@ cannot be established. Registered paint consumers list their allowed binding IDs
 borrowing a peer's family or private token remains invalid. Bindings are scoped
 to their actual root; portals outside it need deliberate project integration.
 
+A registered binding producer may combine two accessible color references as
+`light-dark(var(--light-token), var(--dark-token))`. The App paint audit checks
+both branches and their observed effect in the active color scheme. Raw colors,
+unknown/private tokens and SVG URLs inside this color function remain invalid.
+This derived binding form does not widen public paint-input types; use constrained
+references for each theme input and verify both color schemes in browser checks.
+
 The App audit checks current mounted instances, accessible values, local SVG
 resources and computed paint-property responses. Visibility and complete rendered
 output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
@@ -238,7 +245,10 @@ MCP before replacing a package used by a running server. Then:
 5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
 
 Migration never edits live source or bypasses gates. It retains stable scenario
-IDs and check case IDs. An optional static `scenario.id` preserves a legacy
+IDs, check case IDs and directory ownership. A canonical `<Owner>.ads.scenario.tsx` is the same
+development entry as `Scenario.tsx`, even without a production entry or owner
+contract. Explicit flat IDs and existing flat peer families remain separate.
+An optional static `scenario.id` preserves a legacy
 identity when a renamed filename would otherwise be ambiguous; it must stay
 inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
 in legacy registration with a note until deliberately resolved. Unknown runner

package/dist/skills/ads-motion/references/guarded-editing.md

@@ -28,6 +28,16 @@ as passing evidence for the live project.
 draft argument. There is no dedicated selected-check runner for drafts yet.
 Use a dry-run transaction for genuinely coupled draft patches.
 
+Build notifications are deferred until the showcase finishes initial discovery;
+a preview cannot be opened with an incomplete tool list. A missing App tool is a
+host-startup failure, not evidence that component behavior failed. Preserve the
+draft and inspect the host diagnostic.
+
+Registered project scripts default to 60 seconds each. A guarded configuration
+change can set `mcp.mutationCheckTimeoutMs` (100–300000 ms) after measuring build
+duration and contention. Timeouts name the command, budget and elapsed time;
+behavior-profile budgets are separate. Do not drop checks to fit either budget.
+
 Behavior-run performance belongs to both orchestration and project checks. ADS
 selects affected owners, filters registered Playwright case tags and shares one
 candidate host per run. The project owns assertions, browser setup, worker count,

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 { adsFileRole, isDevelopmentFile, isInside } from "./config.mjs";
+import { adsFileRole, isDevelopmentFile, isInside, scenarioIdentity } from "./config.mjs";
 import { importResolver } from "./boundaries.mjs";
 import { documentationFilePolicy, isProjectDocument, projectDocumentFiles } from "./project-documents.mjs";
 import { foundationFiles, foundationImportTarget } from "./token-policy.mjs";
@@ -98,8 +98,33 @@ export function inspectUnits(options) {
   // Runtime entry conventions keep directory ownership stable when an optional
   // preview is removed. A flat scenario family still denotes separate owners.
   const sameName = name => name.replace(/[-_]/g, "").toLowerCase();
-  const flatFamilies = new Set(files.filter(file => !adsFileRole(file) && /\.scenario\.[cm]?[jt]sx?$/.test(file)).map(file => path.posix.dirname(file)));
+  const legacyFlatFamilies = new Set(files.filter(file => !adsFileRole(file) && /\.scenario\.[cm]?[jt]sx?$/.test(file)).map(file => path.posix.dirname(file)));
+  const canonicalDefaults = new Set();
   const directories = new Set(files.filter(file => /(?:^|\/)Scenario\.[cm]?[jt]sx?$/.test(file)).map(file => slash(path.dirname(file))));
+  // A canonical marked default is the development entry of the same directory
+  // owner as Scenario.tsx. It needs no production module or empty contract to
+  // retain that boundary. Preserve explicit flat IDs and existing peer families.
+  for (const file of files.filter(file => adsFileRole(file) === "scenario")) {
+    const directory = path.posix.dirname(file);
+    if (legacyFlatFamilies.has(directory) || scenarioIdentity(path.join(dsRoot,file),dsRoot) !== directory) continue;
+    const ast = ts.createSourceFile(file,readFileSync(path.join(dsRoot,file),"utf8"),ts.ScriptTarget.Latest,true);
+    const declaration = ast.statements.filter(ts.isVariableStatement).flatMap(statement=>statement.declarationList.declarations)
+      .find(declaration=>ts.isIdentifier(declaration.name)&&declaration.name.text==="scenario");
+    let metadata = declaration?.initializer;
+    while (metadata && (ts.isAsExpression(metadata)||ts.isSatisfiesExpression(metadata)||ts.isParenthesizedExpression(metadata))) metadata=metadata.expression;
+    if (!metadata || !ts.isObjectLiteralExpression(metadata)) continue;
+    const id = metadata.properties.find(property=>property.name && (ts.isIdentifier(property.name)||ts.isStringLiteralLike(property.name)) && property.name.text==="id");
+    if (id && (!ts.isPropertyAssignment(id)||!ts.isStringLiteralLike(id.initializer)||id.initializer.text!==directory)) continue;
+    // An unresolved spread/computed key may supply or overwrite an explicit ID.
+    if (metadata.properties.some((property,index)=>ts.isSpreadAssignment(property) && (!id || index>metadata.properties.indexOf(id))
+      || property.name && ts.isComputedPropertyName(property.name))) continue;
+    directories.add(directory);
+    canonicalDefaults.add(directory);
+  }
+  // Marked flat siblings still outrank a directory index/runtime barrel. Losing
+  // the final legacy spelling must not merge otherwise unrelated peer owners.
+  const flatFamilies = new Set(files.filter(file => /\.scenario\.[cm]?[jt]sx?$/.test(file)
+    && (!adsFileRole(file) || !canonicalDefaults.has(path.posix.dirname(file)))).map(file => path.posix.dirname(file)));
   for (const file of files.filter(file => /^(?:components|patterns)\/.+\/tokens\.json$/.test(file))) directories.add(path.posix.dirname(file));
   for (const file of files.filter(file => /\.ads\.contract\.[cm]?ts$/.test(file))) {
     const directory=path.posix.dirname(file);

package/dist/verification/browser.mjs

@@ -17,6 +17,8 @@ function auditPaintBindings({ container = document.getElementById("root"), bindi
       const resolved = view.getComputedStyle(node).getPropertyValue(name).trim();
       return !!resolved && view.CSS.supports("color", resolved);
     }
+    const themed = /^light-dark\(\s*(var\(\s*--[\w-]+\s*\)|currentColor)\s*,\s*(var\(\s*--[\w-]+\s*\)|currentColor)\s*\)$/.exec(value);
+    if (themed) return view.CSS.supports("color", value) && reference(themed[1], node, descriptor, seen) && reference(themed[2], node, descriptor, seen);
     const resource = /^url\(\s*(["']?)#([^\s"'()#\\\p{Cc}]+)\1\s*\)$/u.exec(value);
     if (resource && view.CSS.supports("fill", value)) {
       const candidates = [...document2.querySelectorAll("[id]")].filter((item) => item.id === resource[2]);

package/docs/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.3.24
+
+- Audit derived `light-dark()` bindings when both branches are accessible
+  constrained color references; verify both schemes without allowing raw colors.
+
+- Defer showcase build notifications until initial discovery completes, preventing
+  false missing-App-tool startup failures in candidate verification.
+- Allow a bounded, explicit `mcp.mutationCheckTimeoutMs` for registered project
+  scripts; retain the 60-second default and report command/budget/elapsed time.
+
+## 0.3.23
+
+- Preserve directory ownership when its last legacy composition/scenario entries
+  migrate to canonical `.ads.` roles. Require no artificial runtime entry or
+  empty contract; retain explicit flat IDs and existing flat peer families.
+- Keep fully migrated flat scenario siblings separate beside directory export
+  barrels. Version 0.3.22 was tagged; publication was cancelled before these
+  additional full-migration checks completed.
+
 ## 0.3.21
 
 - Add statically read TypeScript owner contracts and canonical `.ads.` development

package/docs/CONTRACTS.md

@@ -238,7 +238,10 @@ MCP before replacing a package used by a running server. Then:
 5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
 
 Migration never edits live source or bypasses gates. It retains stable scenario
-IDs and check case IDs. An optional static `scenario.id` preserves a legacy
+IDs, check case IDs and directory ownership. A canonical `<Owner>.ads.scenario.tsx` is the same
+development entry as `Scenario.tsx`, even without a production entry or owner
+contract. Explicit flat IDs and existing flat peer families remain separate.
+An optional static `scenario.id` preserves a legacy
 identity when a renamed filename would otherwise be ambiguous; it must stay
 inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
 in legacy registration with a note until deliberately resolved. Unknown runner

package/docs/GUIDE.md

@@ -403,7 +403,9 @@ input/configuration or execution errors.
 
 Guarded MCP editing is opt-in. Its mandatory checks and optional project
 `mcp.mutationChecks` scripts run in a temporary project copy with installed
-dependencies. See the [editing contract](MCP.md#guarded-editing) for unit ownership,
+dependencies. Project scripts default to 60 seconds each; use the explicit
+`mcp.mutationCheckTimeoutMs` budget (100–300000 ms) for measured slower builds.
+Behavior profiles have a separate whole-run budget. See the [editing contract](MCP.md#guarded-editing) for unit ownership,
 Git patches, bounded reads and preview review. Keep normal build gates enabled
 for edits made by other tools.
 

package/docs/MCP.md

@@ -547,7 +547,7 @@ rules, including warnings. By default it also runs available `lint:project`
 additional list through project-owned configuration:
 
 ```json
-{ "mcp": { "mutationChecks": ["lint", "typecheck", "build:mcp-previews"] } }
+{ "mcp": { "mutationChecks": ["lint", "typecheck", "build:mcp-previews"], "mutationCheckTimeoutMs": 120000 } }
 ```
 
 Every listed script must exist. An empty list still runs mandatory ADS and Oxlint
@@ -557,8 +557,11 @@ sandbox. An explicit `configuration` patch can change project commands, register
 rules and reviewed exceptions; validation runs the proposed configuration and
 scripts. Mandatory core and generated Oxlint checks still run on every write.
 Configuration changes cannot bundle unrelated component edits. Checks that
-rewrite source are rejected. Each command has a 60-second limit; the diagnostic
-explorer allows up to 15 minutes for the complete request.
+rewrite source are rejected. Each registered project script defaults to a
+60-second limit. `mcp.mutationCheckTimeoutMs` sets its explicit budget
+(100–300000 ms); it does not change mandatory gates or behavior-profile budgets.
+Timeout diagnostics identify the command, configured budget and elapsed time.
+The diagnostic explorer allows up to 15 minutes for the complete request.
 
 Ordinary source and asset files owned by the selected unit are editable. Generated
 outputs, dependency directories, Git metadata and symlink/hardlink targets are
@@ -1084,3 +1087,10 @@ then use the existing diff and guarded dry-run/apply workflow. It does not write
 live source, loosen policy or add a second contract-editing protocol. See
 [CONTRACTS.md](CONTRACTS.md) for the static schema, compatibility and browser audits.
 The same guide is available at `ads://guides/contracts`.
+
+A registered binding producer may combine two accessible color references as
+`light-dark(var(--light-token), var(--dark-token))`. The App paint audit checks
+both branches and their observed effect in the active color scheme. Raw colors,
+unknown/private tokens and SVG URLs inside this color function remain invalid.
+This derived binding form does not widen public paint-input types; use constrained
+references for each theme input and verify both color schemes in browser checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.21",
+  "version": "0.3.24",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {