@reqvire-org/ads 0.3.5 → 0.3.7

package/dist/skills/ads-motion/references/atomic-styles.md

@@ -0,0 +1,121 @@
+# Atomic style composition
+
+Use this guide when creating or migrating component/pattern styles, changing
+base/size/state combinations, or reviewing `atomic-composition-review` warnings.
+It is also available as `ads://guides/atomic-styles` through ADS MCP.
+
+## Why valid tokens can still render incorrectly
+
+Atomic Linaria extracts declarations into reusable classes. `cx` from
+`@linaria/atomic` or `@linaria/core` replaces earlier atoms with the same property
+and selector/condition key. It does not expand every CSS shorthand or resolve
+every overlap between physical and logical properties.
+
+For example, these declarations have different atomic keys:
+
+```tsx
+const base = css`
+  padding: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+
+cx(base, small);
+```
+
+Both classes survive. Both declarations can affect horizontal padding in a
+horizontal writing mode. In the inspected Linaria implementation, `padding` and
+`padding-inline` receive equal specificity. If a reset atom is emitted later,
+it can override the intended size. Shared atom reuse and CSS splitting can make
+this visible in a larger build even when an isolated view appears correct.
+The order of class names in HTML does not decide equal-specificity rule order.
+Valid tokens, successful extraction and a passing source check do not establish
+the intended computed value.
+
+See Linaria's [class merging implementation](https://github.com/callstack/linaria/blob/master/packages/core/src/cx.ts)
+and [property priority implementation](https://github.com/callstack/linaria/blob/master/packages/atomic/src/processors/helpers/propertyPriority.ts).
+Inspect the project's installed version when investigating its output.
+
+## Prefer matching properties across composed blocks
+
+Express the reset and overrides using the same property vocabulary:
+
+```tsx
+const base = css`
+  padding-block: 0;
+  padding-inline: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+const regular = css`
+  padding-block: var(--space-4);
+  padding-inline: var(--space-8);
+`;
+
+cx(base, compact ? small : regular);
+```
+
+Now each selected size replaces the corresponding base atom through `cx`.
+Review every size, including the default and icon-only variants. Changing only
+one size can leave another size mixing shorthand and logical properties.
+The names and tokens above are illustrative: use the project's real API and
+declared tokens. Preserve its intended dimensions and supported writing modes.
+
+The same reasoning applies to margin, inset, logical borders/corners, dimensions
+and overflow. For example, prefer `margin-inline: 0` plus a size's
+`margin-inline: var(...)` over combining `margin: 0` with that logical override.
+Choose consistent physical properties when the product deliberately positions
+against physical edges; logical properties are not mandatory.
+
+An intentional state override may have a different selector or condition:
+
+```tsx
+const treatment = css`
+  padding-inline: var(--space-6);
+  &:hover { padding-inline: var(--space-8); }
+`;
+```
+
+This is a distinct state, not two competing base atoms. Whether changing padding
+on hover is desirable remains a product decision.
+
+## Respond to a warning
+
+1. Follow the warning's related file/line locations and inspect the actual `cx`
+   composition. Variant lookups may contribute several possible combinations.
+2. In a current built preview, inspect computed properties and the winning CSS
+   rules. Establish whether extraction order, specificity, writing mode or an
+   intentional override explains the result.
+3. For accidental overlap, align property names/granularity across the base and
+   affected variants. Use Linaria's `cx`, preserve tokens and fix the owning
+   component/pattern. Reordering class strings does not remove overlapping keys.
+4. Verify the affected sizes/states and supported directions in the normal app
+   and preview build. Add a registered rendered check when a specific geometry
+   or computed-style guarantee matters.
+
+Increasing specificity, adding `!important`, copying styles into scenarios or
+moving component styling into `base.css` can hide the symptom while retaining
+the conflict. Prefer resolving the composition itself. If an overlap is
+intentional, document why its precedence is stable and verify the resulting
+behavior rather than changing product capabilities to silence a warning.
+
+## What ADS checks
+
+`atomic-composition-review` is a nonblocking warning, returned under `advisories`
+with `severity: "warning"`. CLI checks still exit successfully when there are no
+errors; MCP checks and mutations preserve the warning and its guidance URI.
+
+The source review examines atomic Linaria templates and statically traceable
+`cx` arguments, including aliases, local imports, nested composition, conditional
+expressions and variant-object lookups. It checks known overlaps involving box
+spacing, inset, borders/corners, dimensions, overflow, backgrounds, typography,
+motion and common layout shorthands, plus `all` resets. It compares shared selector/condition contexts; separate alternatives
+within one conditional or lookup are not assumed to apply together.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. An empty warning list does not establish
+visual correctness. Actual failed registered browser/behavior checks remain
+blocking; potentially intentional source overlaps remain warnings.

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

@@ -0,0 +1,44 @@
+# Advanced guarded editing
+
+Use `ads_apply_patch` for independent owner edits. `ads_prepare_patch` can create a
+local draft of one owner and its companions; edit that directory with local file
+tools, request `action:"diff"`, then apply the returned patchFile. Discard the
+draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
+preparation nor diff generation validates or changes live source.
+
+For genuinely coupled changes, `ads_apply_transaction` accepts 2–8 distinct owner
+patches (32 distinct files and 16 MiB combined). Each patch keeps its ownership and
+companion restrictions. Patches apply in order; later shared-entry hunks match the
+earlier candidate. All guards, registered checks and affected behavior checks run
+on the final candidate before live source is written. Dry-run first. Rejection,
+conflict and cancellation publish nothing. Dependency installation remains local;
+the candidate uses installed node_modules. Never bypass a rejected gate directly.
+
+A component/pattern can own constants without expanding the shared vocabulary:
+colocate `tokens.json` with `{ "schemaVersion":1, "namespace":"--<owner>-" }`
+and a definition-only `tokens.css`, imported by its runtime source. Flat owners use
+`<Owner>.tokens.json`/`<Owner>.tokens.css`. Namespaces are unique and cannot overlap
+shared or --ds-/--ux-/--showcase- variables. Only that owner consumes/defines its
+local tokens; aliases can use shared or own tokens. UI styles stay in Linaria.
+Add a colocated token scenario with `kind:"tokens"`, real fixture `samples` and a
+public review pattern. These inputs belong to the same owner and need real sample
+coverage. Manifests and fixtures stay out of the product bundle.
+
+`ads_prepare_token_samples({id, bindings?})` preserves existing project samples,
+removes undeclared names and returns an owner patchFile. Supply explicit
+`{token,property,probe}` bindings for new samples; unresolved tokens stay reported.
+ADS does not infer visual meaning or fabricate renderers. Apply through the guard,
+then inspect the actual App sample effects.
+
+An empty .gitkeep can be deleted alongside new source beneath it in the selected
+owner. Nonempty markers and other hidden files stay protected. A redundant
+Scenario.tsx can be deleted when real coverage remains elsewhere; removing a
+scenario does not erase ownership of the unit's runtime source.
+
+Keep contextual public parts public when they are intended consumer API. Demonstrate
+them through their actual public composition/customization path and list their real
+render references in covers. Do not count internal production renders as public API
+coverage. Behavioral APIs use exercises and registered guarantees instead.
+Scenario controls still use public UI; native link/button markup belongs in an
+owned public primitive/pattern or an owner-local test, including polymorphic/slot
+adaptation. Do not add demo-only component props or global styles for review glue.

package/dist/token-fixtures.mjs

@@ -0,0 +1,30 @@
+import { inspectTokens } from "./tokens.mjs";
+import { inspectScenarios, tokenSampleSource } from "./scenarios.mjs";
+import { inspectUnits } from "./units.mjs";
+import { validTokenSamples } from "./token-samples.mjs";
+import { textDiff } from "./mcp/text-diff.mjs";
+
+/** Preserve project bindings; new meanings always need project-selected inputs. */
+export function reconcileTokenSamples(options, {id, bindings = []}) {
+  if (bindings.length && !validTokenSamples(bindings)) throw new Error("Bindings need distinct {token, property, probe} CSS samples.");
+  const inventory = inspectTokens(options.root), registry = inspectScenarios(options), units = inspectUnits(options);
+  const scenario = registry.scenarios.find(entry => entry.id === id && entry.kind === "tokens");
+  if (!scenario) throw new Error("Select an exact token scenario ID from ads_scenarios.");
+  const owner = units.owner(units.relative(scenario.file));
+  const owned = new Set(inventory.tokens.filter(token => token.owner === owner).map(token => token.name));
+  if (bindings.some(sample => !owned.has(sample.token))) throw new Error("New sample bindings must name real tokens from this scenario's owner.");
+  const removed = scenario.samples.filter(sample => !owned.has(sample.token)).map(sample => sample.token);
+  const samples = new Map(scenario.samples.filter(sample => owned.has(sample.token)).map(sample => [`${sample.token}:${sample.property}`, sample]));
+  for (const sample of bindings) samples.set(`${sample.token}:${sample.property}`, sample);
+  if (!samples.size) throw new Error("A token scenario needs at least one real sample; supply a binding or remove the obsolete scenario with an owner patch.");
+  const represented = new Set(registry.scenarios.filter(entry => entry.kind === "tokens" && entry.id !== id).flatMap(entry => entry.samples.map(sample => sample.token)));
+  for (const sample of samples.values()) represented.add(sample.token);
+  const unresolved = [...owned].filter(name => !represented.has(name));
+  const source = tokenSampleSource(options,scenario);
+  const list = [...samples.values()];
+  const current = scenario.samples;
+  const next = JSON.stringify(current) === JSON.stringify(list) ? source.content : source.content.slice(0,source.start) + JSON.stringify(list,null,2) + source.content.slice(source.end);
+  return {unit:owner,id,file:source.file,sampleCount:list.length,removed,unresolved,
+    patch:textDiff(source.file,source.content,next),
+    guidance:"Bindings and probes belong to the project. No token-name/type heuristic chooses a renderer or probe. Apply the proposed owner patch through ads_apply_patch, then verify its real preview."};
+}

package/dist/tokens.mjs

@@ -6,6 +6,7 @@ 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";
+import { scopedTokens, scopedTokenOwner } from "./scoped-tokens.mjs";
 
 export { tokenContract };
 
@@ -49,7 +50,10 @@ export function inspectTokens(directory) {
   const { root, dsRoot, config } = options;
   const definitions = new Map();
   const diagnostics = [];
+  const scoped = scopedTokens(options);
+  diagnostics.push(...scoped.diagnostics);
   const files = sourceFiles(path.join(dsRoot, config.tokenDir)).filter((file) => file.endsWith(".css"));
+  files.push(...scoped.definitions.map(entry => path.join(root, entry.file)));
   files.sort((a, b) => foundationFiles.indexOf(path.basename(a)) - foundationFiles.indexOf(path.basename(b)) || a.localeCompare(b));
   for (const file of files) {
     let css;
@@ -68,6 +72,7 @@ export function inspectTokens(directory) {
         column: decl.source.start.column,
         scope: context(decl),
         value: decl.value,
+        ...(scoped.definitions.some(entry => entry.file === path.relative(root, file).replaceAll("\\", "/")) ? { owner:scoped.definitions.find(entry => entry.file === path.relative(root, file).replaceAll("\\", "/")).unit } : {}),
       };
       if (!definitions.has(decl.prop)) definitions.set(decl.prop, []);
       definitions.get(decl.prop).push(definition);
@@ -107,7 +112,8 @@ export function inspectTokens(directory) {
       }
       const resolvedReferences = new Map();
       for (const ref of references(entry.value)) {
-        if (!isSharedToken(ref.name)) report("token-name", name, entry, `${name} references ${ref.name}, which does not follow ADS's fixed token naming contract.`);
+        const local = scopedTokenOwner(options, ref.name);
+        if (local ? entry.owner !== local.unit : !isSharedToken(ref.name)) report("token-name", name, entry, `${name} references ${ref.name} outside its shared/owner token contract.`);
         if (!scope.has(ref.name) && !ref.fallback) report("token-reference", name, entry, `${name} references undefined ${ref.name}.`);
         else if (scope.has(ref.name)) resolvedReferences.set(ref.name, resolveAlias(ref.name, [...chain, name]));
       }
@@ -137,7 +143,7 @@ export function inspectTokens(directory) {
   }
   return {
     contractVersion: tokenContract.version,
-    tokens: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, entries]) => ({ name, ...tokenContract.tokens[name], definitions: entries })),
+    tokens: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, entries]) => ({ name, ...tokenContract.tokens[name], ...(scopedTokenOwner(options, name) ? {owner:scopedTokenOwner(options, name).unit, namespace:scopedTokenOwner(options, name).namespace} : {owner:"tokens"}), definitions: entries })),
     diagnostics,
   };
 }

package/dist/units.mjs

@@ -100,6 +100,7 @@ export function inspectUnits(options) {
   const sameName = name => name.replace(/[-_]/g, "").toLowerCase();
   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.filter(file => /^(?:components|patterns)\/.+\/tokens\.json$/.test(file))) directories.add(path.posix.dirname(file));
   for (const file of files) {
     if (!/^(?:components|patterns|controllers|composition)\//.test(file) || !source.test(file)) continue;
     const directory = slash(path.dirname(file)), name = path.basename(file).replace(source, "");
@@ -145,6 +146,12 @@ export function inspectUnits(options) {
   }
   for (const unit of units.values()) if (boundaryCompanion(unit.id)) {
     (unit.companionFiles ??= []).push({ path: "ds.config.json", allowedChanges: "Only this owner's inlineStyleFiles and boundaries.styleWrites entries, together with its source change; preserve all other configuration and peer permissions." });
+    if (/^(?:components|patterns|controllers|composition)\//.test(unit.id)) {
+      for (let directory = unit.id; directory !== "."; directory = path.posix.dirname(directory)) {
+        const marker = path.join(dsRoot, directory, ".gitkeep");
+        if (existsSync(marker) && readFileSync(marker).length === 0) (unit.companionFiles ??= []).push({ path: slash(path.relative(root, marker)), allowedChanges: "Delete this empty placeholder only while adding real source in the selected owner below it." });
+      }
+    }
   }
   return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry, stylesEntry, tokenDir,
     relative: file => slash(path.relative(dsRoot, path.resolve(root, file))) };
@@ -161,6 +168,14 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
   validateUnitId(unit);
   for (const change of changes) {
     const relative = inventory.relative(change.path);
+    if (path.posix.basename(relative) === ".gitkeep") {
+      const directory = path.posix.dirname(relative);
+      if (change.originalContent !== "" || change.content !== null || !/^(?:components|patterns|controllers|composition)\//.test(relative)
+        || !(unit === directory || unit.startsWith(directory + "/"))
+        || !changes.some(item => item.originalContent === null && item.content !== null && source.test(item.path)
+          && (inventory.relative(item.path).startsWith(unit + "/") || inventory.relative(item.path).startsWith(unit + ".")))) throw fail("Only delete an existing empty .gitkeep while adding source in the selected owner beneath it. Other hidden-file changes are not allowed.", change.path);
+      continue;
+    }
     if (allowNew && unit === "configuration") continue; // The candidate must register every setup/extension file.
     if (change.path === "ds.config.json" && boundaryCompanion(unit)) continue; // Validated against only this owner below.
     if (relative === inventory.publicEntry) continue;

package/dist/verification.mjs

@@ -193,7 +193,7 @@ export function createVerificationController(root) {
             if (!current) status = "stale";
             if (signal.aborted) status = "cancelled";
             results.push({ unit: check.unit, check: check.id, file: check.file, case: check.case, profile: profileName, status, current, revision: check.inputRevision, runId, completedAt: new Date().toISOString(),
-              previewRevision: profile.mode === "browser" ? readPreviewManifest(options)?.revision ?? null : null,
+              previewRevision: profile.mode === "browser" ? host?.previewRevision() ?? readPreviewManifest(options)?.revision ?? null : null,
               message: runnerError?.message ?? (!matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : matches.filter(item => item.status !== "passed").map(item => String(item.message ?? item.status).slice(0, 2000)).join("\n")), report: slash(path.relative(root, report)) });
           }
           if (signal.aborted) break;

package/docs/ADS.md

@@ -7,7 +7,8 @@ UX, and Skin pillars. [GUIDE.md](GUIDE.md) gives setup and configuration steps.
 ## Ownership boundary
 
 MCP source editing is opt-in through `ads mcp --mutations`. Its write operation
-accepts a Git unified diff for one ADS unit and validates its source, scenario and
+accepts a Git unified diff for one ADS unit (or bounded owner patches for coupled
+transactions) and validates its source, scenario and
 fixture changes against core checks, registered Oxlint rules and project checks
 before application. This includes
 foundation, documentation, original assets and an explicit configuration unit for
@@ -146,7 +147,7 @@ mounting, correct props, every branch/state or visual parity. The older
 
 `token-scenario-reference` rejects undeclared token names in metadata and reachable
 inputs. `token-scenario-render` rejects claimed tokens with no reachable input
-reference; `token-scenario-coverage` requires every discovered foundation token
+reference; `token-scenario-coverage` requires every discovered shared or owner-local token
 to have coverage. A new or removed token therefore needs a scenario/fixture
 update. All three are errors in `ads check`, run by `lint:ds` and the build.
 Coverage is static reachability, not proof that every branch actually renders
@@ -168,6 +169,48 @@ preview builds; review meaningful states in both themes and sizes.
 
 ## Shared token contract
 
+### Owner-local tokens
+
+Shared semantics remain in the configured token foundation. Constants specific
+to one component or pattern may live beside it:
+
+```text
+components/Notice/
+  Notice.tsx                 # imports ./tokens.css; UI styling stays in Linaria
+  tokens.json              # {"schemaVersion":1,"namespace":"--notice-"}
+  tokens.css               # :root { --notice-width: 356px; }
+  Scenario.tsx
+  fixture.ts
+  Tokens.scenario.tsx      # kind: "tokens", public review pattern + samples
+  Tokens.fixture.ts
+```
+
+Flat owners use `<Owner>.tokens.json` and `<Owner>.tokens.css`. A unit has one
+explicit namespace, unique across owners and separate from shared/runtime-variable
+prefixes. The stylesheet contains only namespaced custom-property definitions
+under root/theme conditions; imports, selectors for UI, ordinary declarations,
+font faces and animations remain outside it. Its runtime owner imports it, so
+product and preview consume the same values. Raw UI styling remains token-backed.
+
+Local token aliases may reference shared tokens or their own namespace, with
+undefined references and cycles rejected. Other owners consume shared tokens;
+they cannot redefine, write or directly consume another owner's local namespace.
+Measured runtime variables retain their existing exact `styleWrites` boundary.
+`ads_tokens` returns each token's owner, definitions and local namespace.
+
+A colocated scenario sets `kind:"tokens"` and declares real fixture `samples`
+consumed by a public review pattern. Its ID still derives from its source path.
+Every local token needs this real sample coverage, just like shared tokens.
+Definitions, metadata, fixture and token scenario belong to the same edit unit.
+Manifests/fixtures are development inputs; production includes the runtime's
+imported CSS definitions, never the preview adapter or tooling manifest.
+
+Use `ads_prepare_token_samples` to propose sample reconciliation from explicit
+project property/probe bindings. The tool preserves project sample meaning and
+reports missing mappings instead of choosing them from token prefixes.
+
+### Shared definitions
+
 Keep compatible token names, meanings, value types, and alias relationships;
 project values and theme overrides may differ. The
 [Data pillar](ARCHITECTURE.md#data-gives-implementations-a-common-language)
@@ -324,6 +367,13 @@ Pointer capture without locally visible capture-loss cleanup produces a
 nonblocking advisory. Review delegated cleanup and browser behavior; neither a
 warning nor a handler's presence establishes lifecycle correctness.
 
+Potential atomic CSS overlaps produce `atomic-composition-review` warnings with
+related declarations and a guidance URI. They are nonblocking, including during
+guarded mutations: valid CSS can intentionally overlap. Read
+[atomic style composition](../skills/ads-designer/references/atomic-styles.md) for causes, matching-property fixes
+and the source review's limits. Registered rendered checks can enforce a
+project's intended computed geometry; token validity alone cannot establish it.
+
 Document a new ownership exception with its guard/configuration change and
 tests. Passing static checks establishes only the policies and source formats
 they cover. Browser review and behavior tests still verify accessibility,
@@ -347,6 +397,13 @@ Validate accepted and rejected cases, configuration, and false-positive limits.
 
 ## Bootstrap and updates
 
+The atomic composition guide lives in each skill's `references/atomic-styles.md`.
+The maintained copy is in `skills/ads-designer/references/atomic-styles.md`;
+MCP serves that packaged skill reference. `npm run sync:skill-references` copies
+it to the other skills for standalone use; `npm run check:skill-references`
+rejects drift during the tool build. Published packages include these references
+under `dist/skills/`.
+
 Root [bootstrap-ds/](../bootstrap-ds/README.md) is the canonical empty scaffold.
 Its identical copy under `skills/ads-designer/assets/bootstrap-ds/` makes the
 skill self-contained. Run `npm run sync:skill-starter` after edits and

package/docs/ARCHITECTURE.md

@@ -122,6 +122,12 @@ Linaria's [colocation and extraction model](https://github.com/callstack/linaria
 and [atomic composition model](https://github.com/callstack/linaria/blob/master/docs/ATOMIC_CSS.md)
 support this combination of local ownership and compiled styling.
 
+Atomic merging matches property/selector/condition keys; it does not resolve
+every shorthand/logical-property overlap. ADS reports detectable composition
+risks as nonblocking warnings with guidance, while registered rendered checks
+can enforce actual geometry. See the skill-local
+[atomic style composition guide](../skills/ads-designer/references/atomic-styles.md).
+
 Airbnb's 2022 [migration report](https://medium.com/airbnb-engineering/airbnbs-trip-to-linaria-dc169230bd12)
 provides practical evidence for this choice: performance was its leading
 criterion, with separate CSS caching and colocated authoring among the benefits.
@@ -205,6 +211,13 @@ scenarios unmounts the previous view while keeping unchanged dependencies cached
 Persistence is a host lifecycle choice; a new external widget loads the same
 resources independently. Resource sharing is scoped to an App instance.
 
+Managed graph builders publish into a private session directory beside the
+configured manifest. Logical scenario IDs and resource URIs stay unchanged;
+standalone builds retain the configured output and cannot overwrite a live
+session's success record. Verified compiled snapshots form a bounded shared
+warm-start cache. Source, compiler, dependency and output hashes still gate reuse.
+Ordinary shutdown removes owned session output while retaining that cache.
+
 ```mermaid
 flowchart LR
   Host[Minimal host: navigation and MCP client] --> Proxy[Separate-origin sandbox proxy]
@@ -342,6 +355,13 @@ replace the managed process while retaining the MCP connection. Normal build gat
 remain in place for source changes made through other editors; preview review remains
 necessary after either editing path.
 
+For genuinely coupled changes, a bounded transaction accepts one Git patch per
+distinct owner and validates a single complete candidate before publication.
+Each patch retains its ownership and companion rules. Local owner drafts remove
+the need for a separate project mirror; token-sample reconciliation preserves
+project bindings and reports unresolved mappings. Neither preparation changes live
+source or substitutes for guarded application and rendered review.
+
 Required shared-entry bookkeeping can accompany its owner: component/pattern
 re-exports, canonical foundation imports for token files created or deleted, and
 only that owner’s style-boundary entries in project configuration in the same
@@ -391,3 +411,10 @@ review pattern. The App then verifies rendered samples in the actual browser by
 probing those bindings and restoring them. The tool supplies no token/property
 classification or visual sample palette. A source build alone is not a rendered
 verification, and the browser check does not judge design quality.
+
+An optional owner-local token namespace keeps component/pattern constants beside
+their consumer. Its definition-only stylesheet contains root/theme custom
+properties and is imported by the runtime owner; UI styling remains in Linaria.
+Namespaces, aliases, ownership and actual colocated sample coverage are checked.
+The shared foundation remains the cross-owner vocabulary. See the
+[owner-token contract](ADS.md#owner-local-tokens).

package/docs/BEHAVIORS.md

@@ -95,6 +95,15 @@ metadata string does not count. Dynamically passed behavior references produce a
 review advisory when a direct call cannot be established; verify those through
 registered execution checks rather than changing the API for the analyzer.
 
+Callable exports may be functions, callable objects with attached methods, or
+factory results. ADS uses their TypeScript call/construct signatures, including
+the project's library declarations; it does not execute modules or maintain a
+list of recognized factory names. The fast source guard resolves ambiguous public
+values lazily and shares that type discovery within the check. Untyped `any`
+values and objects containing methods do not establish a callable API.
+An invalid `exercises` entry names the offending value and fails validation while
+retaining independent render evidence for `covers`.
+
 Public APIs appear in `ads_catalog` with `apiKind: "ui"` or `"behavior"` and their
 scenario links. `ads_behaviors` joins contracts to demonstrations and evidence.
 A demonstrated API is not automatically a verified guarantee.
@@ -145,6 +154,17 @@ Write meaningful assertions for the registered guarantee. The helper waits for
 the current selected scenario inside the real sandboxed MCP App. It uses `load`
 and explicit readiness, not `networkidle`: MCP keeps event connections open.
 
+Compare reference and candidate under equivalent framing. In a reported Chrome
+comparison, `content-visibility` initially used placeholder geometry inside a
+cross-origin App iframe for both ADS and the upstream reference; the same content
+measured differently as a top-level page. This is an observed browser/layout
+condition, not evidence of an ADS defect. App readiness does not imply that every
+off-screen item has rendered. For geometry assertions, bring the relevant content
+into view and wait for its measured layout to settle. Record the framing and
+visibility state; test initial placeholder behavior separately when it matters to
+the guarantee. Wait for focus and positioning readiness before normal keyboard
+comparisons, and test rapid input separately rather than hiding it behind delays.
+
 `mode: "browser"` starts an isolated managed showcase on an automatic port. Test
 requests contain its scenario URLs, and cleanup closes its host/compiler tree.
 Mutation candidates use their own source, generated graph and server; a passing

package/docs/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.3.7
+
+- Warn about statically traceable atomic CSS property overlaps without blocking
+  checks or guarded edits. Include source pairs, concrete correction guidance and
+  a guide inside every ADS skill's references folder, also served by MCP.
+  Keep regression cases
+  generic and validate computed geometry in a dummy compiled preview.
+
+- Preserve callable-object and factory-result recognition in the fast source
+  guard using lazy project type discovery. Name invalid scenario `exercises`
+  entries without discarding independent UI render coverage.
+
+## 0.3.6
+
+- Isolate managed resource-graph output by session; reuse verified compiled
+  snapshots across warm starts without letting standalone builds overwrite live
+  preview success records.
+- Add component/pattern-owned token namespaces, closed definition-only sheets,
+  discovery, alias/ownership checks and real colocated token-preview coverage.
+- Add owner draft/diff preparation and project-directed token sample reconciliation.
+  Keep all source writes behind guarded Git patches.
+- Add bounded coupled-owner transactions, validating all guards, registered checks
+  and affected behavior checks against the final candidate before publication.
+- Permit empty .gitkeep deletion alongside real new owner source. Retain hidden
+  file restrictions, render coverage and public scenario-control ownership.
+- Document framed content-visibility geometry as a browser comparison condition,
+  with observable layout/focus readiness and separate rapid-input checks.
+
+- Use MCP display titles throughout the diagnostic explorer, with annotation-title
+  and tool-name fallbacks. Publish configured App titles in tool metadata and keep
+  machine-readable names for protocol calls.
+
 ## 0.3.5
 
 - Bound preview-watch test teardown, publish selection requests atomically and

package/docs/GUIDE.md

@@ -364,7 +364,11 @@ for edits made by other tools.
 categories, undefined aliases, alias cycles, and individual theme/media
 overrides. Project-specific values and additional definitions within ADS's fixed
 naming contract are allowed. The contract's `naming` section lists the fixed
-shared families and names; projects cannot configure alternative prefixes.
+shared families and names; projects cannot rename those shared semantics.
+Component/pattern constants can use an explicit unique owner-local namespace and
+definition-only stylesheet, with the same real-token preview completeness rules.
+See [owner-local tokens](ADS.md#owner-local-tokens). Unregistered foreign names
+remain rejected.
 `--ds-*`, `--ux-*`, and `--showcase-*` variables remain owned by their layers,
 including when a file is inside `tokens/`. Shared token assignments outside
 `tokens/` fail. Source styles also check shared references for undeclared names.
@@ -498,8 +502,9 @@ in owned component/pattern styles, with tokens supplying visual values.
 
 ADS has fixed token names and ownership namespaces. Change values in the existing
 token files; `--accent`, `--font-sans`, `--radius-md`, and the other shared roles
-keep their meanings across projects. Foreign prefixes such as `--nuv-*` or
-`--brand-*` fail. Components own `--ds-*`, patterns own `--ux-*`, and the showcase
+keep their meanings across projects. Foreign shared prefixes such as `--nuv-*` or
+`--brand-*` fail; a registered owner-local constant namespace is separate from
+the shared branding vocabulary. Components own `--ds-*`, patterns own `--ux-*`, and the showcase
 reserves `--showcase-*` for showcase boundaries. Fixture files still define no
 custom styling; the frame pattern uses `--ux-*`. Branding never assigns
 component state variables.