@reqvire-org/ads 0.3.8 → 0.3.10

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

@@ -44,11 +44,18 @@ use the client's normal source-editing tools.
 For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
-For atomic base/variant styling, helper/wrapper class composition, or an
+For parent/child `covers`, public style-helper use in scenarios, or
+`scenario-render` / `showcase-class` findings, read
+[scenario contracts](references/scenarios.md). Traced parents can cover declared
+public children; verified public Linaria helpers do not grant custom scenario CSS.
+
+For atomic base/variant styling, helper/wrapper class composition, extracted
+custom-property arithmetic, or an
 `atomic-composition-review` / `atomic-composition-limit` advisory, read
 [atomic style composition](references/atomic-styles.md). The same guide is served
 as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
-matching-property fixes. Review warnings in the real `cx` composition and verify
+matching-property fixes, plus the build resolver for preserving opaque custom
+properties through extraction. Review warnings in the real `cx` composition and verify
 computed styles across affected sizes/states; retain intentional product behavior.
 
 Controllers are UI behavior owners: private helpers stay with their component or

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

@@ -81,6 +81,56 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Preserve custom-property arithmetic during extraction
+
+Custom properties can hold an unevaluated token stream that becomes arithmetic
+only after substitution into a later `calc()`. For example:
+
+```css
+--i: 2;
+--scale: var(--i) * 0.05 + 1;
+transform: scale(calc(-1 * var(--scale)));
+```
+
+The result is scale `0.9`: substitution does not add parentheses around the
+custom property. Some Linaria/Stylis extraction versions strip the whitespace
+around the bare `+`, leaving `0.05+1`. The browser then treats the transform as
+invalid. This can happen with CSS minification disabled. Source guards cannot
+prove what a later extractor emits.
+
+Use ADS's build-only resolver in **both** the application's Linaria configuration
+and its separately configured MCP preview builder:
+
+```js
+import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
+
+// In the project's Vite plugins:
+wyw({ tagResolver: linariaTagResolver });
+```
+
+The resolver keeps the project's installed atomic processor and preserves opaque
+custom-property values through its nesting/atomization pass. It does not add a
+browser runtime or alter token ownership. Existing projects must adopt it in
+each extraction pipeline; upgrading ADS alone does not rewrite custom builders.
+If an existing `tagResolver` handles other tags, delegate atomic imports to
+`linariaTagResolver(source, tag)` and retain the existing fallback. WyW config
+files also support this resolver when a build integration requires serializable
+inline options.
+
+For a source workaround, write a self-contained formula and consume it directly:
+
+```css
+--scale: calc(1 - var(--i) * 0.05);
+transform: scale(var(--scale));
+```
+
+This also produces `0.9`. Simply wrapping the old value in `calc()` while keeping
+the outer `-1 *` changes its grouping and result. Verify extracted CSS text and a
+computed style after any rewrite, including nested `var()` fallbacks/transforms.
+Do not globally insert spaces into already extracted CSS: that can change valid
+signed numbers, identifiers, strings or URLs.
+
 ## Follow helpers and forwarded classes
 
 Composition can cross a helper or a component boundary. For example, in component

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

@@ -0,0 +1,98 @@
+# Scenario rendering, token previews and public class helpers
+
+Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
+diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
+
+## Owner-local token previews load their own definitions
+
+Keep the registered token sheet imported by its runtime owner for product use.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
+## Public children can share their parent's scenario
+
+Declare the public parts actually demonstrated in `covers`, even when their
+parent renders them internally:
+
+```tsx
+// Runtime owner
+export function Part() { return <span>Content</span>; }
+export function Frame({ visible = true } = {}) {
+  return <section>{visible && <Part />}</section>;
+}
+
+// Colocated Scenario.tsx
+import { Frame } from "@ds";
+export const scenario = { title: "Frame", covers: ["Frame", "Part"] };
+export default function Scenario() { return <Frame />; }
+```
+
+ADS follows returned JSX through local components/helpers, aliases, registered
+framework factories, memo/ref wrappers and context providers. Fixture props,
+spreads and destructuring defaults select the child path. An explicit
+`visible={false}` does not cover `Part`. When a condition remains unknown, only
+parts returned on every possible path receive transitive credit. Imports, unused
+JSX, event-handler bodies and uncalled functions do not establish child rendering.
+Only the explicitly declared `covers` entries acquire coverage; dependencies are
+not silently added to metadata or the catalogue.
+
+Tracing is bounded and does not execute the project. Recursion, written/escaped inputs,
+opaque external wrappers and unsupported control flow can prevent proof. The
+diagnostic explains known limits. Use meaningful fixture states or another real
+scenario; do not make a valid public part private or duplicate it in a parent
+just to satisfy a guard. Static evidence does not establish successful mounting,
+visibility, interaction, every state or visual parity. Verify those in the built
+App and registered browser checks.
+
+## Scenarios may consume verified public style helpers
+
+A deliberately public helper can expose its owner's Linaria treatment:
+
+```tsx
+// Runtime owner
+const treatment = css`padding-inline: var(--space-4);`;
+export function controlClasses() {
+  return cx("control-hook", treatment);
+}
+
+// Scenario: consume the public API; define no styles here
+<PublicLink className={controlClasses()}>Documentation</PublicLink>
+```
+
+The sample token and APIs are illustrative; use the project's real exports and
+tokens. Import helpers through the public ADS entry. ADS traces helper calls,
+returns, local aliases, finite known selections and Linaria `cx` composition.
+Styling must originate in component/pattern Linaria through a public callable
+helper. A literal stable hook authored in that runtime owner may accompany the
+verified styles. Each nonempty return path needs actual Linaria declarations;
+empty templates and hook-only/string-only returns do not qualify.
+
+These are still rejected:
+
+```tsx
+<PublicLink className="custom-layout" />
+<PublicLink className={arbitraryPublicFunctionReturningAString()} />
+<PublicLink className={controlClasses({ className: "custom-layout" })} />
+```
+
+Scenario-supplied strings, generated styles in fixtures, private style imports,
+spoofed Linaria functions and untraceable results acquire no permission by being
+passed through a public function. Known className values in props/spreads receive
+the same provenance check. Opaque spreads remain outside complete source proof.
+An `exercises` entry records behavioral use; it never grants styling permission.
+
+Keep helper signatures compatible with the product API. Fix ownership/provenance
+in the runtime owner when genuinely wrong; retain intentional public APIs when
+reporting an unsupported trace. Demo-only sizing, framing and arrangement still
+belong in public review/layout patterns. A style helper is not permission to
+author a second design in the scenario. For cascade risks and extraction issues,
+read [atomic-styles.md](atomic-styles.md).

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

@@ -46,11 +46,18 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
-For atomic base/variant styling, helper/wrapper class composition, or an
+For parent/child `covers`, public style-helper use in scenarios, or
+`scenario-render` / `showcase-class` findings, read
+[scenario contracts](references/scenarios.md). Traced parents can cover declared
+public children; verified public Linaria helpers do not grant custom scenario CSS.
+
+For atomic base/variant styling, helper/wrapper class composition, extracted
+custom-property arithmetic, or an
 `atomic-composition-review` / `atomic-composition-limit` advisory, read
 [atomic style composition](references/atomic-styles.md). The same guide is served
 as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
-matching-property fixes. Review warnings in the real `cx` composition and verify
+matching-property fixes, plus the build resolver for preserving opaque custom
+properties through extraction. Review warnings in the real `cx` composition and verify
 computed styles across affected sizes/states; retain intentional product behavior.
 
 Controllers are UI behavior owners: private helpers stay with their component or

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

@@ -81,6 +81,56 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Preserve custom-property arithmetic during extraction
+
+Custom properties can hold an unevaluated token stream that becomes arithmetic
+only after substitution into a later `calc()`. For example:
+
+```css
+--i: 2;
+--scale: var(--i) * 0.05 + 1;
+transform: scale(calc(-1 * var(--scale)));
+```
+
+The result is scale `0.9`: substitution does not add parentheses around the
+custom property. Some Linaria/Stylis extraction versions strip the whitespace
+around the bare `+`, leaving `0.05+1`. The browser then treats the transform as
+invalid. This can happen with CSS minification disabled. Source guards cannot
+prove what a later extractor emits.
+
+Use ADS's build-only resolver in **both** the application's Linaria configuration
+and its separately configured MCP preview builder:
+
+```js
+import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
+
+// In the project's Vite plugins:
+wyw({ tagResolver: linariaTagResolver });
+```
+
+The resolver keeps the project's installed atomic processor and preserves opaque
+custom-property values through its nesting/atomization pass. It does not add a
+browser runtime or alter token ownership. Existing projects must adopt it in
+each extraction pipeline; upgrading ADS alone does not rewrite custom builders.
+If an existing `tagResolver` handles other tags, delegate atomic imports to
+`linariaTagResolver(source, tag)` and retain the existing fallback. WyW config
+files also support this resolver when a build integration requires serializable
+inline options.
+
+For a source workaround, write a self-contained formula and consume it directly:
+
+```css
+--scale: calc(1 - var(--i) * 0.05);
+transform: scale(var(--scale));
+```
+
+This also produces `0.9`. Simply wrapping the old value in `calc()` while keeping
+the outer `-1 *` changes its grouping and result. Verify extracted CSS text and a
+computed style after any rewrite, including nested `var()` fallbacks/transforms.
+Do not globally insert spaces into already extracted CSS: that can change valid
+signed numbers, identifiers, strings or URLs.
+
 ## Follow helpers and forwarded classes
 
 Composition can cross a helper or a component boundary. For example, in component

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

@@ -0,0 +1,98 @@
+# Scenario rendering, token previews and public class helpers
+
+Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
+diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
+
+## Owner-local token previews load their own definitions
+
+Keep the registered token sheet imported by its runtime owner for product use.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
+## Public children can share their parent's scenario
+
+Declare the public parts actually demonstrated in `covers`, even when their
+parent renders them internally:
+
+```tsx
+// Runtime owner
+export function Part() { return <span>Content</span>; }
+export function Frame({ visible = true } = {}) {
+  return <section>{visible && <Part />}</section>;
+}
+
+// Colocated Scenario.tsx
+import { Frame } from "@ds";
+export const scenario = { title: "Frame", covers: ["Frame", "Part"] };
+export default function Scenario() { return <Frame />; }
+```
+
+ADS follows returned JSX through local components/helpers, aliases, registered
+framework factories, memo/ref wrappers and context providers. Fixture props,
+spreads and destructuring defaults select the child path. An explicit
+`visible={false}` does not cover `Part`. When a condition remains unknown, only
+parts returned on every possible path receive transitive credit. Imports, unused
+JSX, event-handler bodies and uncalled functions do not establish child rendering.
+Only the explicitly declared `covers` entries acquire coverage; dependencies are
+not silently added to metadata or the catalogue.
+
+Tracing is bounded and does not execute the project. Recursion, written/escaped inputs,
+opaque external wrappers and unsupported control flow can prevent proof. The
+diagnostic explains known limits. Use meaningful fixture states or another real
+scenario; do not make a valid public part private or duplicate it in a parent
+just to satisfy a guard. Static evidence does not establish successful mounting,
+visibility, interaction, every state or visual parity. Verify those in the built
+App and registered browser checks.
+
+## Scenarios may consume verified public style helpers
+
+A deliberately public helper can expose its owner's Linaria treatment:
+
+```tsx
+// Runtime owner
+const treatment = css`padding-inline: var(--space-4);`;
+export function controlClasses() {
+  return cx("control-hook", treatment);
+}
+
+// Scenario: consume the public API; define no styles here
+<PublicLink className={controlClasses()}>Documentation</PublicLink>
+```
+
+The sample token and APIs are illustrative; use the project's real exports and
+tokens. Import helpers through the public ADS entry. ADS traces helper calls,
+returns, local aliases, finite known selections and Linaria `cx` composition.
+Styling must originate in component/pattern Linaria through a public callable
+helper. A literal stable hook authored in that runtime owner may accompany the
+verified styles. Each nonempty return path needs actual Linaria declarations;
+empty templates and hook-only/string-only returns do not qualify.
+
+These are still rejected:
+
+```tsx
+<PublicLink className="custom-layout" />
+<PublicLink className={arbitraryPublicFunctionReturningAString()} />
+<PublicLink className={controlClasses({ className: "custom-layout" })} />
+```
+
+Scenario-supplied strings, generated styles in fixtures, private style imports,
+spoofed Linaria functions and untraceable results acquire no permission by being
+passed through a public function. Known className values in props/spreads receive
+the same provenance check. Opaque spreads remain outside complete source proof.
+An `exercises` entry records behavioral use; it never grants styling permission.
+
+Keep helper signatures compatible with the product API. Fix ownership/provenance
+in the runtime owner when genuinely wrong; retain intentional public APIs when
+reporting an unsupported trace. Demo-only sizing, framing and arrangement still
+belong in public review/layout patterns. A style helper is not permission to
+author a second design in the scenario. For cascade risks and extraction issues,
+read [atomic-styles.md](atomic-styles.md).

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

@@ -66,11 +66,18 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
-For atomic base/variant styling, helper/wrapper class composition, or an
+For parent/child `covers`, public style-helper use in scenarios, or
+`scenario-render` / `showcase-class` findings, read
+[scenario contracts](references/scenarios.md). Traced parents can cover declared
+public children; verified public Linaria helpers do not grant custom scenario CSS.
+
+For atomic base/variant styling, helper/wrapper class composition, extracted
+custom-property arithmetic, or an
 `atomic-composition-review` / `atomic-composition-limit` advisory, read
 [atomic style composition](references/atomic-styles.md). The same guide is served
 as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
-matching-property fixes. Review warnings in the real `cx` composition and verify
+matching-property fixes, plus the build resolver for preserving opaque custom
+properties through extraction. Review warnings in the real `cx` composition and verify
 computed styles across affected sizes/states; retain intentional product behavior.
 
 Controllers are UI behavior owners: private helpers stay with their component or

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

@@ -81,6 +81,56 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Preserve custom-property arithmetic during extraction
+
+Custom properties can hold an unevaluated token stream that becomes arithmetic
+only after substitution into a later `calc()`. For example:
+
+```css
+--i: 2;
+--scale: var(--i) * 0.05 + 1;
+transform: scale(calc(-1 * var(--scale)));
+```
+
+The result is scale `0.9`: substitution does not add parentheses around the
+custom property. Some Linaria/Stylis extraction versions strip the whitespace
+around the bare `+`, leaving `0.05+1`. The browser then treats the transform as
+invalid. This can happen with CSS minification disabled. Source guards cannot
+prove what a later extractor emits.
+
+Use ADS's build-only resolver in **both** the application's Linaria configuration
+and its separately configured MCP preview builder:
+
+```js
+import wyw from "@wyw-in-js/vite";
+import { linariaTagResolver } from "@reqvire-org/ads/linaria";
+
+// In the project's Vite plugins:
+wyw({ tagResolver: linariaTagResolver });
+```
+
+The resolver keeps the project's installed atomic processor and preserves opaque
+custom-property values through its nesting/atomization pass. It does not add a
+browser runtime or alter token ownership. Existing projects must adopt it in
+each extraction pipeline; upgrading ADS alone does not rewrite custom builders.
+If an existing `tagResolver` handles other tags, delegate atomic imports to
+`linariaTagResolver(source, tag)` and retain the existing fallback. WyW config
+files also support this resolver when a build integration requires serializable
+inline options.
+
+For a source workaround, write a self-contained formula and consume it directly:
+
+```css
+--scale: calc(1 - var(--i) * 0.05);
+transform: scale(var(--scale));
+```
+
+This also produces `0.9`. Simply wrapping the old value in `calc()` while keeping
+the outer `-1 *` changes its grouping and result. Verify extracted CSS text and a
+computed style after any rewrite, including nested `var()` fallbacks/transforms.
+Do not globally insert spaces into already extracted CSS: that can change valid
+signed numbers, identifiers, strings or URLs.
+
 ## Follow helpers and forwarded classes
 
 Composition can cross a helper or a component boundary. For example, in component

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

@@ -0,0 +1,98 @@
+# Scenario rendering, token previews and public class helpers
+
+Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
+diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
+
+## Owner-local token previews load their own definitions
+
+Keep the registered token sheet imported by its runtime owner for product use.
+A colocated `kind: "tokens"` scenario may render only the public review pattern
+with its fixture samples. Discovery adds the registered owner sheet to the
+generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
+into the token preview independently of the runtime component. Custom builders
+that replace this plugin must preserve these explicit stylesheet dependencies.
+Do not render the runtime owner merely to retain its CSS or add unrelated sheets.
+
+Open the exact token scenario in a fresh App and verify resolved values and sample
+effects in both themes. A successful ordinary component preview does not prove
+the independently bundled token preview loads the same definitions. Shared
+foundation styling still follows the project's mount/build integration.
+
+## Public children can share their parent's scenario
+
+Declare the public parts actually demonstrated in `covers`, even when their
+parent renders them internally:
+
+```tsx
+// Runtime owner
+export function Part() { return <span>Content</span>; }
+export function Frame({ visible = true } = {}) {
+  return <section>{visible && <Part />}</section>;
+}
+
+// Colocated Scenario.tsx
+import { Frame } from "@ds";
+export const scenario = { title: "Frame", covers: ["Frame", "Part"] };
+export default function Scenario() { return <Frame />; }
+```
+
+ADS follows returned JSX through local components/helpers, aliases, registered
+framework factories, memo/ref wrappers and context providers. Fixture props,
+spreads and destructuring defaults select the child path. An explicit
+`visible={false}` does not cover `Part`. When a condition remains unknown, only
+parts returned on every possible path receive transitive credit. Imports, unused
+JSX, event-handler bodies and uncalled functions do not establish child rendering.
+Only the explicitly declared `covers` entries acquire coverage; dependencies are
+not silently added to metadata or the catalogue.
+
+Tracing is bounded and does not execute the project. Recursion, written/escaped inputs,
+opaque external wrappers and unsupported control flow can prevent proof. The
+diagnostic explains known limits. Use meaningful fixture states or another real
+scenario; do not make a valid public part private or duplicate it in a parent
+just to satisfy a guard. Static evidence does not establish successful mounting,
+visibility, interaction, every state or visual parity. Verify those in the built
+App and registered browser checks.
+
+## Scenarios may consume verified public style helpers
+
+A deliberately public helper can expose its owner's Linaria treatment:
+
+```tsx
+// Runtime owner
+const treatment = css`padding-inline: var(--space-4);`;
+export function controlClasses() {
+  return cx("control-hook", treatment);
+}
+
+// Scenario: consume the public API; define no styles here
+<PublicLink className={controlClasses()}>Documentation</PublicLink>
+```
+
+The sample token and APIs are illustrative; use the project's real exports and
+tokens. Import helpers through the public ADS entry. ADS traces helper calls,
+returns, local aliases, finite known selections and Linaria `cx` composition.
+Styling must originate in component/pattern Linaria through a public callable
+helper. A literal stable hook authored in that runtime owner may accompany the
+verified styles. Each nonempty return path needs actual Linaria declarations;
+empty templates and hook-only/string-only returns do not qualify.
+
+These are still rejected:
+
+```tsx
+<PublicLink className="custom-layout" />
+<PublicLink className={arbitraryPublicFunctionReturningAString()} />
+<PublicLink className={controlClasses({ className: "custom-layout" })} />
+```
+
+Scenario-supplied strings, generated styles in fixtures, private style imports,
+spoofed Linaria functions and untraceable results acquire no permission by being
+passed through a public function. Known className values in props/spreads receive
+the same provenance check. Opaque spreads remain outside complete source proof.
+An `exercises` entry records behavioral use; it never grants styling permission.
+
+Keep helper signatures compatible with the product API. Fix ownership/provenance
+in the runtime owner when genuinely wrong; retain intentional public APIs when
+reporting an unsupported trace. Demo-only sizing, framing and arrangement still
+belong in public review/layout patterns. A style helper is not permission to
+author a second design in the scenario. For cascade risks and extraction issues,
+read [atomic-styles.md](atomic-styles.md).