@animus-ui/system 0.1.1-beta.2 → 0.1.2

package/dist/bootstrap/createAppearanceBootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAppearanceBootstrap.d.ts","sourceRoot":"","sources":["../../src/bootstrap/createAppearanceBootstrap.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE;QACR,2DAA2D;QAC3D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,CAAC;CACH;AAED,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B;IAC1C,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,wBAAwB,EAC/B,OAAO,GAAE,0BAA+B,GACvC,2BAA2B,CAsE7B"}

package/dist/bootstrap/index.d.ts

@@ -0,0 +1,2 @@
+export { type AppearanceBootstrapArtifact, type AppearanceBootstrapOptions, type AppearanceBootstrapTheme, createAppearanceBootstrap, } from './createAppearanceBootstrap.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/bootstrap/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bootstrap/index.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC"}

package/dist/bootstrap/index.js

@@ -0,0 +1,98 @@
+import { createHash } from "node:crypto";
+//#region src/bootstrap/createAppearanceBootstrap.ts
+/**
+* Appearance bootstrap generator — build-tooling surface ONLY.
+*
+* This module is reachable exclusively from the `@animus-ui/system/bootstrap`
+* subpath. It is never imported by the component/runtime entries, so no part of
+* it (including the storage keys below) can reach an extracted application
+* bundle.
+*/
+/** The single versioned appearance record key. */
+const DEFAULT_STORAGE_KEY = "animus:appearance";
+/**
+* Pre-record key read once, only when the record is absent. Never written —
+* migration is read-only by contract.
+*/
+const LEGACY_STORAGE_KEY = "color-mode";
+/** The mode axis attribute. Its ABSENCE means "follow the OS" (D4). */
+const MODE_ATTRIBUTE = "data-color-mode";
+/**
+* Reserved mode name. `system` is modeled as attribute absence and can never be
+* a declared mode, so it must never enter the generated allowlist.
+*/
+const RESERVED_MODE_NAME = "system";
+/** The only appearance-record version this generation of the snippet reads. */
+const RECORD_VERSION = 1;
+/**
+* Renders a string as a JS literal that is also safe inside an inline
+* `<script>` and inside a consumer's own string context:
+* - `<` is escaped, so an embedded value can never open a closing tag or an
+*   HTML comment;
+* - U+2028/U+2029 are escaped, so `code` survives being nested in string
+*   contexts that still treat them as line terminators.
+*
+* Character-wise on purpose: this file stays pure ASCII, so no invisible
+* separator can hide in it.
+*/
+function inlineLiteral(value) {
+	let out = "";
+	for (const char of JSON.stringify(value)) {
+		if (char === "<") {
+			out += "\\u003c";
+			continue;
+		}
+		const code = char.codePointAt(0);
+		if (code === 8232 || code === 8233) {
+			out += `\\u${code.toString(16)}`;
+			continue;
+		}
+		out += char;
+	}
+	return out;
+}
+/**
+* Builds the inline appearance-restoration script for a built theme.
+*
+* The generated snippet, before first paint:
+* 1. reads the appearance record from `storageKey`, falling back to the legacy
+*    `color-mode` key ONLY when the record is absent (missing key, or an empty
+*    string, which is not a record);
+* 2. accepts the record only at version `1` — a future or absent version is
+*    treated as NO record, because an older snippet cannot interpret a newer
+*    record and absence is the neutral fail-safe;
+* 3. sets `data-color-mode` when the resulting name is a declared mode;
+* 4. removes the attribute for `system`, no record, an unreadable store, or an
+*    unknown mode — absence is how "follow the OS" is represented, so later OS
+*    changes apply with no script running.
+*
+* The failure semantics are deliberately asymmetric:
+* - storage that THROWS on read (private browsing, blocked storage) means "no
+*   knowledge", so the attribute is REMOVED and the media-query fallback takes
+*   over; freezing a server-rendered mode would defeat that fallback;
+* - a record that is PRESENT but unparseable means "storage is telling us
+*   something we cannot read", so the snippet exits leaving the server-rendered
+*   markup exactly as it was.
+*
+* It never writes storage, never calls `matchMedia`, and ignores the record's
+* `theme` axis. Identical inputs always yield byte-identical output.
+*
+* @throws if the theme declares no color modes (a bootstrap without a mode
+*   allowlist could not validate anything), declares the reserved name
+*   `system`, or declares a blank mode name.
+*/
+function createAppearanceBootstrap(theme, options = {}) {
+	const { storageKey = DEFAULT_STORAGE_KEY } = options;
+	if (typeof storageKey !== "string" || storageKey === "") throw new Error("createAppearanceBootstrap: storageKey must be a non-empty string.");
+	const modeNames = Object.keys(theme?.manifest?.modes ?? {}).sort();
+	if (modeNames.length === 0) throw new Error("createAppearanceBootstrap: the theme declares no color modes — call addColorModes() before generating a bootstrap.");
+	if (modeNames.includes(RESERVED_MODE_NAME)) throw new Error(`createAppearanceBootstrap: '${RESERVED_MODE_NAME}' is a reserved mode name — the OS preference is represented by the absence of the ${MODE_ATTRIBUTE} attribute, never by a declared mode.`);
+	if (modeNames.some((name) => name.trim() === "")) throw new Error("createAppearanceBootstrap: a declared mode name is empty or whitespace-only — such a name matches no mode block and would suppress the system fallback.");
+	const code = `(function(){try{var m=${`[${modeNames.map(inlineLiteral).join(",")}]`};var r=document.documentElement;var v=null;try{v=localStorage.getItem(${inlineLiteral(storageKey)});}catch(e){v=null;}var n=null;if(typeof v==="string"&&v!==""){var p;try{p=JSON.parse(v);}catch(e){return;}n=p&&typeof p==="object"&&p.v===${RECORD_VERSION}?p.mode:null;}else{try{n=localStorage.getItem(${inlineLiteral(LEGACY_STORAGE_KEY)});}catch(e){n=null;}}if(typeof n==="string"&&m.indexOf(n)!==-1){r.setAttribute(${inlineLiteral(MODE_ATTRIBUTE)},n);}else{r.removeAttribute(${inlineLiteral(MODE_ATTRIBUTE)});}}catch(e){}})();`;
+	return {
+		code,
+		cspHash: `sha256-${createHash("sha256").update(code, "utf8").digest("base64")}`
+	};
+}
+//#endregion
+export { createAppearanceBootstrap };

package/dist/composeWithContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composeWithContext.d.ts","sourceRoot":"","sources":["../src/composeWithContext.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,yBAAyB,EAI/B,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACjD,KAAK,CAAC,MAAM,SAAS,YAAY,CAAC,KAAK,CAAC,EAExC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,cAAc,CAAC,KAAK,CAAC,CA8CvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC,EACrD,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7C,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC,CAqChD"}
+{"version":3,"file":"composeWithContext.d.ts","sourceRoot":"","sources":["../src/composeWithContext.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,yBAAyB,EAI/B,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACjD,KAAK,CAAC,MAAM,SAAS,YAAY,CAAC,KAAK,CAAC,EAExC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,cAAc,CAAC,KAAK,CAAC,CAmEvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC,EACrD,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7C,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC,CA+DhD"}

package/dist/composeWithContext.js

@@ -18,18 +18,28 @@ function composeWithContext(slots, options) {
 	const result = {};
 	for (const [name, SourceComponent] of Object.entries(slots)) {
 		let Wrapper;
-		if (name === "Root") Wrapper = forwardRef((props, ref) => {
-			const shared = {};
-			for (const key of sharedKeySet) if (key in props) shared[key] = props[key];
-			return createElement(SourceComponent, {
-				...props,
-				ref
-			}, createElement(FamilyCtx.Provider, { value: shared }, props.children));
-		});
-		else Wrapper = forwardRef((props, ref) => {
+		if (name === "Root") {
+			const rootDefaults = SourceComponent.variantDefaults;
+			Wrapper = forwardRef((props, ref) => {
+				const shared = {};
+				for (const key of sharedKeySet) {
+					const value = props[key] ?? rootDefaults?.[key];
+					if (value != null) shared[key] = value;
+				}
+				return createElement(SourceComponent, {
+					...props,
+					ref
+				}, createElement(FamilyCtx.Provider, { value: shared }, props.children));
+			});
+		} else Wrapper = forwardRef((props, ref) => {
+			const inherited = useContext(FamilyCtx);
+			const merged = {
+				...inherited,
+				...props
+			};
+			for (const key of sharedKeySet) if (props[key] == null && key in inherited) merged[key] = inherited[key];
 			return createElement(SourceComponent, {
-				...useContext(FamilyCtx),
-				...props,
+				...merged,
 				ref
 			});
 		});
@@ -55,24 +65,35 @@ function createComposedFamilyWithContext(slots, config) {
 	const result = {};
 	for (const [slotName, SourceComponent] of Object.entries(slots)) {
 		let Wrapper;
-		if (slotName === "Root") Wrapper = forwardRef((props, ref) => {
-			const shared = {};
-			for (const key of keySet) if (key in props) shared[key] = props[key];
-			return createElement(SourceComponent, {
-				...props,
-				ref
-			}, createElement(Ctx.Provider, { value: shared }, props.children));
-		});
-		else Wrapper = forwardRef((props, ref) => {
+		if (slotName === "Root") {
+			const rootDefaults = SourceComponent.variantDefaults;
+			Wrapper = forwardRef((props, ref) => {
+				const shared = {};
+				for (const key of keySet) {
+					const value = props[key] ?? rootDefaults?.[key];
+					if (value != null) shared[key] = value;
+				}
+				return createElement(SourceComponent, {
+					...props,
+					ref
+				}, createElement(Ctx.Provider, { value: shared }, props.children));
+			});
+		} else Wrapper = forwardRef((props, ref) => {
+			const inherited = useContext(Ctx);
+			const merged = {
+				...inherited,
+				...props
+			};
+			for (const key of keySet) if (props[key] == null && key in inherited) merged[key] = inherited[key];
 			return createElement(SourceComponent, {
-				...useContext(Ctx),
-				...props,
+				...merged,
 				ref
 			});
 		});
 		Wrapper.displayName = `${name}.${slotName}`;
 		result[slotName] = Wrapper;
 	}
+	if (!("Root" in result)) throw new Error("createComposedFamilyWithContext(): No \"Root\" slot found. The root slot key must be exactly \"Root\" (PascalCase).");
 	return result;
 }
 //#endregion

package/dist/conditions.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Condition alias registry — maps `_`-prefixed alias keys to at-rule condition
+ * strings (`@media` / `@container` / `@supports`). Parallel in shape to the
+ * selector alias registry (`selectors.ts`): alias → `{ value, order, kind }`.
+ *
+ * `order` determines cascade precedence within a layer (aliased conditions emit
+ * in registry order, per design D4). `kind` is inferred from the at-rule prefix
+ * of `value` (design D3) and drives which at-rule the extractor wraps the block
+ * in. Serialized into the manifest as the NEW `conditionAliases` field, leaving
+ * `selectorAliases` byte-for-byte unchanged.
+ *
+ * This module hosts BOTH the runtime registry and the authoring TYPE surface
+ * (inc 04): the augmentable `Conditions`/`Selectors` publication, the
+ * `ConditionsOf`/`SelectorsOf` extractors, the branded rejection types
+ * (`UnknownConditionAlias`/`UnknownAtRule`), and the shallow `RawAtRuleKey`
+ * shapes consumed by `ThemedCSSProps`' kind-dispatched arms. `addConditions()`
+ * constrains values to `@media`/`@container`/`@supports`-prefixed strings at
+ * the type level; `inferConditionKind` remains the runtime fail-loud check.
+ */
+/** The three condition kinds, inferred from the at-rule prefix of the value. */
+export type ConditionKind = 'media' | 'container' | 'supports';
+/**
+ * Augmentable registry of registered condition alias keys. Empty by default;
+ * a consumer publishes its registrations with:
+ *
+ * ```ts
+ * declare module '@animus-ui/system' {
+ *   interface Conditions extends Record<ConditionsOf<typeof ds>, true> {}
+ * }
+ * ```
+ *
+ * When this interface is empty (no publication), `ThemedCSSProps` keeps
+ * `_`-prefixed block keys permissive — the same graceful degradation the
+ * augmentable `Theme` uses (empty theme ⇒ raw CSS values). Once populated, the
+ * validating arms engage: unknown `_` keys resolve to `UnknownConditionAlias`.
+ *
+ * JOINT NAMESPACE (inc-04 F8/F9): condition and selector aliases share the one
+ * `_` block-key namespace, so publishing EITHER `Conditions` OR `Selectors`
+ * flips BOTH namespaces from permissive to validating (see `KnownUnderscoreKey`
+ * in `types/config.ts`, whose gate reads `keyof Conditions | keyof Selectors`).
+ *
+ * Built-in condition aliases (`BUILT_IN_CONDITIONS`, design D8) are NOT members
+ * of this interface — they live in the static `BuiltInConditionAlias` union
+ * (`types/config.ts`), mirroring `BuiltInSelectorAlias`. Defaulting members here
+ * would make publication permanently non-empty and destroy the degradation
+ * contract above (a non-augmenting consumer with custom aliases would flip from
+ * permissive to branded-rejection the day built-ins shipped).
+ */
+export interface Conditions {
+}
+declare const CONDS_BRAND: unique symbol;
+declare const SELS_BRAND: unique symbol;
+/**
+ * Phantom brand carried on `build()`'s system output, threading the accumulated
+ * registered condition (`C`) and custom selector (`S`) alias-key unions to the
+ * consumer's augmentation site. Type-only — never present at runtime.
+ */
+export interface RegistryBrand<C extends string = never, S extends string = never> {
+    readonly [CONDS_BRAND]?: C;
+    readonly [SELS_BRAND]?: S;
+}
+/** Extract the registered condition alias keys from a built system. */
+export type ConditionsOf<Sys> = Sys extends RegistryBrand<infer C, string> ? C : never;
+/** Extract the registered custom selector alias keys from a built system. */
+export type SelectorsOf<Sys> = Sys extends RegistryBrand<string, infer S> ? S : never;
+/**
+ * Branded rejection for a `_`-prefixed block key that is neither a registered
+ * condition alias, a registered selector alias, a built-in selector alias,
+ * nor a built-in condition alias.
+ * The type name carries the offending key; the `hint` states the remedy. Never
+ * a bare `never` arm — `never` produces a misleading "not assignable to
+ * 'undefined'" (design D9, measured).
+ */
+export interface UnknownConditionAlias<K extends string> {
+    readonly __unknownConditionAlias: K;
+    readonly hint: `"${K}" is not a registered condition or selector alias. Register it with .addConditions() / .addSelectors(), or use a raw "&…" selector or "@media|@container|@supports (…)" key.`;
+}
+/**
+ * Branded rejection for an `@`-prefixed block key that does not match an
+ * accepted at-rule shape (`@media …` / `@container …` / `@supports …`). The
+ * type name carries the offending key; the `hint` states the remedy.
+ */
+export interface UnknownAtRule<K extends string> {
+    readonly __unknownAtRule: K;
+    readonly hint: `"${K}" is not a valid at-rule block key. At-rule keys must begin with "@media ", "@container ", or "@supports " followed by a parenthesized/feature tail.`;
+}
+/**
+ * SHALLOW at-rule key shapes (design D9): prefix + tail only. Deep query-grammar
+ * template literals are the repo's one known TS2589 zone (string-embedded
+ * unions) and stay out — Rust validates queries for real; the type layer stops
+ * at the prefix. The trailing space after each at-rule name is load-bearing: it
+ * rejects prefix typos (`@containr …`, `@medi …`) without a closed grammar.
+ */
+export type RawAtRuleKey = `@media ${string}` | `@container ${string}` | `@supports ${string}`;
+export interface ConditionAlias {
+    /** Full at-rule condition string, e.g. `@media (prefers-reduced-motion: reduce)`. */
+    value: string;
+    /** Sort index for cascade ordering within a layer. */
+    order: number;
+    /** Condition kind, inferred from the at-rule prefix of `value`. */
+    kind: ConditionKind;
+}
+export type ConditionAliasMap = Record<string, ConditionAlias>;
+/**
+ * Built-in condition aliases (design D8, increment 06).
+ *
+ * The Panda-compatible media-feature set: motion, print, orientation, contrast,
+ * and OS color-scheme preferences. Every alias is a pure `@media` feature query
+ * (`kind: 'media'`). Color-mode aliases (`_dark` / `_light`) are DELIBERATELY
+ * excluded — they are selector-kind (`[data-color-mode]`) surface owned by the
+ * `system-color-scheme` change, not media features.
+ *
+ * ORDER BAND (inc-03 full-pass): built-ins occupy a reserved band BELOW the user
+ * band — one slot of 10 per alias in table row order, 300–380. The user band
+ * starts at 500 (`mergeConditions` floors allocation at 490 → first user alias
+ * is 500), so built-ins and user registrations never interleave on collision.
+ * This mirrors the selector registry's real layout (built-ins 10–440, users
+ * 500+).
+ *
+ * The static type-level mirror is `BuiltInConditionAlias` in `types/config.ts`
+ * (added to `KnownUnderscoreKey`'s VALIDATING branch, exactly like
+ * `BuiltInSelectorAlias`). Built-ins are NOT members of the augmentable
+ * `Conditions` interface: interface members would make publication permanently
+ * non-empty, killing inc-04's graceful-degradation contract. The
+ * `types.test-d.tsx` drift positives keep the two in sync.
+ */
+export declare const BUILT_IN_CONDITIONS: ConditionAliasMap;
+/**
+ * Infer the condition kind from an at-rule value's prefix (design D3).
+ * Throws (fail-loud, build time) when the value does not begin with a
+ * supported at-rule name. The compile-time complement is `addConditions()`'s
+ * value constraint (`@media`/`@container`/`@supports`-prefixed template
+ * literals); this runtime throw remains the backstop for untyped callers.
+ */
+export declare function inferConditionKind(value: string): ConditionKind;
+/**
+ * Merge user-provided condition aliases with a base map.
+ *
+ * - User aliases override built-ins of the same name, preserving the existing
+ *   order (mirrors `mergeSelectors`).
+ * - New aliases allocate orders CONTINUING from the highest existing order
+ *   (floored at 490, so the first user alias lands at 500) rather than
+ *   restarting at 500 each call — chained `.addConditions()` calls must not
+ *   collide on order 500.
+ * - Fails loud when a condition alias name is already reserved by the SELECTOR
+ *   alias registry (`reservedSelectorNames`): the two registries share the `_`
+ *   namespace at the call site and their names MUST be disjoint, else a block
+ *   key would be ambiguous. The error names the offending alias and both
+ *   registries.
+ */
+export declare function mergeConditions(base: ConditionAliasMap, custom: Record<string, string>, reservedSelectorNames?: ReadonlySet<string>): ConditionAliasMap;
+/** Get the sorted alias keys for deterministic cascade ordering. */
+export declare function getSortedConditionKeys(map: ConditionAliasMap): string[];
+/**
+ * Serialize the condition map for the extraction pipeline.
+ * Emits `alias → { value, order, kind }` in registry (cascade) order so the
+ * JSON is deterministic. Distinct in SHAPE from the selector map (which
+ * flattens to `alias → selector`) — the object entry is forward-compatible
+ * with a future multi-valued `values: string[]` property (design D3).
+ */
+export declare function serializeConditionMap(map: ConditionAliasMap): Record<string, ConditionAlias>;
+export {};
+//# sourceMappingURL=conditions.d.ts.map

package/dist/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC;AAY/D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,UAAU;CAAG;AAE9B,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAC;AACzC,OAAO,CAAC,MAAM,UAAU,EAAE,OAAO,MAAM,CAAC;AAExC;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAC5B,CAAC,SAAS,MAAM,GAAG,KAAK,EACxB,CAAC,SAAS,MAAM,GAAG,KAAK;IAExB,QAAQ,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3B,QAAQ,CAAC,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,MAAM,YAAY,CAAC,GAAG,IAC1B,GAAG,SAAS,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,MAAM,WAAW,CAAC,GAAG,IACzB,GAAG,SAAS,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,MAAM;IACrD,QAAQ,CAAC,uBAAuB,EAAE,CAAC,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,8KAA8K,CAAC;CACpM;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM;IAC7C,QAAQ,CAAC,eAAe,EAAE,CAAC,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,sJAAsJ,CAAC;CAC5K;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB,UAAU,MAAM,EAAE,GAClB,cAAc,MAAM,EAAE,GACtB,aAAa,MAAM,EAAE,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBA0CjC,CAAC;AAUF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAS/D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,qBAAqB,GAAE,WAAW,CAAC,MAAM,CAAqB,GAC7D,iBAAiB,CA0BnB;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,iBAAiB,GACrB,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAMhC"}

package/dist/{createComposedFamily-DSE2ZuRE.js → createComposedFamily-DJ2aqfqN.js}

@@ -57,13 +57,14 @@ function warnDroppedValue(baseClassName, propName, serializedValue) {
 	}
 }
 /**
-* Resolve className parts from props, using extracted configuration.
-* This is the shared logic between createComponent and createClassResolver.
+* Apply variant classes in declaration order, recording a static witness per
+* resolved variant. When a value comes from a defaultVariant fallback (prop not
+* passed), emit --{prop}-default instead of --{prop}-{value} so the compose
+* override rule cannot match, allowing inheritance from the parent to win.
 */
-function resolveClasses(baseClassName, props, config, systemPropMap, dynamicPropConfig) {
-	const classes = [baseClassName];
-	let dynStyle;
-	if (config.variants) for (const [prop, vc] of Object.entries(config.variants)) {
+function applyVariantClasses(classes, baseClassName, props, config) {
+	if (!config.variants) return;
+	for (const [prop, vc] of Object.entries(config.variants)) {
 		const value = props[prop] ?? vc.default;
 		if (value != null) {
 			const isDefault = !(prop in props) && vc.default != null;
@@ -71,7 +72,14 @@ function resolveClasses(baseClassName, props, config, systemPropMap, dynamicProp
 			recordWitness(baseClassName, prop, value, "static");
 		}
 	}
-	if (config.compounds) for (const compound of config.compounds) {
+}
+/**
+* Apply compound classes: push each compound's className when every condition
+* matches (against the prop value or its variant default). No witness records.
+*/
+function applyCompoundClasses(classes, props, config) {
+	if (!config.compounds) return;
+	for (const compound of config.compounds) {
 		let match = true;
 		for (const [prop, expected] of Object.entries(compound.conditions)) {
 			const current = props[prop] ?? config.variants?.[prop]?.default;
@@ -82,14 +90,54 @@ function resolveClasses(baseClassName, props, config, systemPropMap, dynamicProp
 		}
 		if (match) classes.push(compound.className);
 	}
-	const activeStates = [];
-	if (config.states) {
-		for (const state of config.states) if (props[state]) {
-			classes.push(`${baseClassName}--${state}`);
-			activeStates.push(state);
-			recordWitness(baseClassName, state, "true", "static");
+}
+/**
+* Apply state classes and track active states for data-attribute passthrough,
+* recording a static witness per active state.
+*/
+function applyStateClasses(classes, baseClassName, props, config, activeStates) {
+	if (!config.states) return;
+	for (const state of config.states) if (props[state]) {
+		classes.push(`${baseClassName}--${state}`);
+		activeStates.push(state);
+		recordWitness(baseClassName, state, "true", "static");
+	}
+}
+/**
+* Expand a resolved dynamic prop into slot classes and CSS-variable style
+* entries. Responsive objects expand per breakpoint: the `_` base breakpoint
+* uses the bare slotClass and varName; named breakpoints suffix both
+* (`${slotClass}-${bp}` and `${varName}-${bp}`). Scalar values push the bare
+* slotClass and set varName directly. Mutates `classes` (push order preserved)
+* and `dynStyle` in place; the caller records the dynamic witness beforehand.
+*/
+function applyDynamicProp(classes, dynStyle, propValue, dc) {
+	if (typeof propValue === "object" && propValue !== null && !Array.isArray(propValue)) for (const [bp, bpVal] of Object.entries(propValue)) {
+		if (bpVal == null) continue;
+		if (bp === "_") {
+			classes.push(dc.slotClass);
+			dynStyle[dc.varName] = resolveValue(bpVal, dc);
+		} else {
+			classes.push(`${dc.slotClass}-${bp}`);
+			dynStyle[`${dc.varName}-${bp}`] = resolveValue(bpVal, dc);
 		}
 	}
+	else {
+		classes.push(dc.slotClass);
+		dynStyle[dc.varName] = resolveValue(propValue, dc);
+	}
+}
+/**
+* Resolve className parts from props, using extracted configuration.
+* This is the shared logic between createComponent and createClassResolver.
+*/
+function resolveClasses(baseClassName, props, config, systemPropMap, dynamicPropConfig) {
+	const classes = [baseClassName];
+	let dynStyle;
+	applyVariantClasses(classes, baseClassName, props, config);
+	applyCompoundClasses(classes, props, config);
+	const activeStates = [];
+	applyStateClasses(classes, baseClassName, props, config, activeStates);
 	const systemPropNames = config.systemPropNames || [];
 	if (systemPropNames.length > 0) {
 		const { customPropMap, customDynamicConfig } = config;
@@ -107,24 +155,7 @@ function resolveClasses(baseClassName, props, config, systemPropMap, dynamicProp
 				if (dc) {
 					recordWitness(baseClassName, propName, key, "dynamic");
 					if (!dynStyle) dynStyle = {};
-					if (typeof propValue === "object" && propValue !== null && !Array.isArray(propValue)) for (const [bp, bpVal] of Object.entries(propValue)) {
-						if (bpVal == null) continue;
-						if (bp === "_") {
-							classes.push(dc.slotClass);
-							const finalVal = resolveValue(bpVal, dc);
-							dynStyle[dc.varName] = finalVal;
-						} else {
-							classes.push(`${dc.slotClass}-${bp}`);
-							const varName = `${dc.varName}-${bp}`;
-							const finalVal = resolveValue(bpVal, dc);
-							dynStyle[varName] = finalVal;
-						}
-					}
-					else {
-						classes.push(dc.slotClass);
-						const finalVal = resolveValue(propValue, dc);
-						dynStyle[dc.varName] = finalVal;
-					}
+					applyDynamicProp(classes, dynStyle, propValue, dc);
 				} else {
 					warnDroppedValue(baseClassName, propName, key);
 					recordWitness(baseClassName, propName, key, "drop");
@@ -152,6 +183,74 @@ function composeRefs(...refs) {
 	};
 }
 /**
+* Forward props to the underlying element, filtering out Animus-managed props.
+*
+* data-* and aria-* attributes always pass through to the DOM, even when used
+* as variant/state keys. This enables headless UI interop: the attribute is
+* consumed for styling AND forwarded to the element so external frameworks
+* (Radix, Ark-UI) see it.
+*
+* filterProps covers all Animus props, so unknown props pass through: for DOM
+* elements React handles any unknown-attribute warnings in dev mode, and for
+* component elements all non-filtered props are forwarded to the component.
+*/
+function forwardProps(props, filterProps, domProps) {
+	for (const [key, value] of Object.entries(props)) {
+		if (key === "className") continue;
+		if (!(key.startsWith("data-") || key.startsWith("aria-")) && filterProps.has(key)) continue;
+		domProps[key] = value;
+	}
+}
+/**
+* asChild render path: don't render our own element — merge the resolved
+* className/ref/style onto the single child element, plus the parent's own
+* forwardable props (event handlers, role, aria-*, data-*, id, tabIndex).
+*
+* Conflict rule is child-wins: the parent's props are spread UNDER the child's
+* own, so a handler or attribute declared on the child replaces the parent's
+* rather than chaining with it.
+*/
+function renderAsChild(className, filterProps, props, ref, classes, dynamicStyle) {
+	const child = Children.only(props.children);
+	if (!isValidElement(child)) throw new Error(`${className}: asChild requires a single React element as children`);
+	const childRef = child.ref;
+	const mergedClassName = [classes.join(" "), child.props.className].filter(Boolean).join(" ");
+	const mergedStyle = dynamicStyle || props.style || child.props.style ? {
+		...props.style,
+		...child.props.style,
+		...dynamicStyle
+	} : void 0;
+	const parentProps = {};
+	forwardProps(props, filterProps, parentProps);
+	delete parentProps.children;
+	delete parentProps.style;
+	delete parentProps.ref;
+	return cloneElement(child, {
+		...parentProps,
+		...child.props,
+		ref: composeRefs(ref, childRef),
+		className: mergedClassName,
+		...mergedStyle ? { style: mergedStyle } : {}
+	});
+}
+/**
+* Normal render path: render our own element (or the `as` override), forwarding
+* filtered props and applying any dynamic CSS-variable style.
+*/
+function renderElement(element, filterProps, props, ref, classes, dynamicStyle) {
+	const target = props.as || element;
+	const domProps = {
+		ref,
+		className: classes.join(" ")
+	};
+	forwardProps(props, filterProps, domProps);
+	if (dynamicStyle) domProps.style = props.style ? {
+		...props.style,
+		...dynamicStyle
+	} : dynamicStyle;
+	return createElement(target, domProps);
+}
+/**
 * Create a lightweight component that applies extracted CSS class names.
 * Replaces Emotion's styled() for extracted components.
 *
@@ -180,44 +279,19 @@ function createComponent(element, className, config, systemPropMap, dynamicPropC
 	const Component = forwardRef((props, ref) => {
 		const { classes, dynamicStyle } = resolveClasses(className, props, config, systemPropMap, dynamicPropConfig);
 		if (props.className) classes.push(props.className);
-		if (props.asChild) {
-			const child = Children.only(props.children);
-			if (!isValidElement(child)) throw new Error(`${className}: asChild requires a single React element as children`);
-			const childRef = child.ref;
-			const mergedClassName = [classes.join(" "), child.props.className].filter(Boolean).join(" ");
-			const mergedStyle = dynamicStyle || props.style || child.props.style ? {
-				...props.style,
-				...child.props.style,
-				...dynamicStyle
-			} : void 0;
-			return cloneElement(child, {
-				ref: composeRefs(ref, childRef),
-				className: mergedClassName,
-				...mergedStyle ? { style: mergedStyle } : {}
-			});
-		}
-		const renderElement = props.as || element;
-		const isComponentElement = typeof renderElement !== "string";
-		const domProps = {
-			ref,
-			className: classes.join(" ")
-		};
-		for (const [key, value] of Object.entries(props)) {
-			if (key === "className") continue;
-			if (!(key.startsWith("data-") || key.startsWith("aria-")) && filterProps.has(key)) continue;
-			if (!isComponentElement) {}
-			domProps[key] = value;
-		}
-		if (dynamicStyle) domProps.style = props.style ? {
-			...props.style,
-			...dynamicStyle
-		} : dynamicStyle;
-		return createElement(renderElement, domProps);
+		return props.asChild ? renderAsChild(className, filterProps, props, ref, classes, dynamicStyle) : renderElement(element, filterProps, props, ref, classes, dynamicStyle);
 	});
 	Component.displayName = className;
-	return Object.assign(Component, { extend: () => {
-		throw new Error(`Cannot extend extracted component "${className}" at runtime. Extensions must be authored in source code using the builder API (e.g. import the original component and call .extend() there) so the extraction pipeline can resolve them at build time.`);
-	} });
+	const variantDefaults = {};
+	if (config.variants) {
+		for (const [prop, vc] of Object.entries(config.variants)) if (vc.default != null) variantDefaults[prop] = vc.default;
+	}
+	return Object.assign(Component, {
+		variantDefaults: Object.freeze(variantDefaults),
+		extend: () => {
+			throw new Error(`Cannot extend extracted component "${className}" at runtime. Extensions must be authored in source code using the builder API (e.g. import the original component and call .extend() there) so the extraction pipeline can resolve them at build time.`);
+		}
+	});
 }
 //#endregion
 //#region src/runtime/createClassResolver.ts

package/dist/index.d.ts

@@ -8,7 +8,8 @@ export { createComposedFamily } from './runtime/createComposedFamily';
 export type { CreateKeyframesFactory, GlobalStyleBlock, GlobalStyleMap, GlobalStylesFactory, SerializedConfig, SystemInstance, } from './SystemBuilder';
 export { createSystem, SystemBuilder } from './SystemBuilder';
 export { createScale, numericOrStringScale, numericScale, stringScale, } from './scales/createScale';
-export { BUILT_IN_SELECTORS, type SelectorAlias, type SelectorAliasMap, } from './selectors';
+export { BUILT_IN_CONDITIONS, type ConditionAlias, type ConditionAliasMap, type ConditionKind, type Conditions, type ConditionsOf, type RawAtRuleKey, type RegistryBrand, type SelectorsOf, type UnknownAtRule, type UnknownConditionAlias, } from './conditions.js';
+export { BUILT_IN_SELECTORS, type SelectorAlias, type SelectorAliasMap, type Selectors, } from './selectors';
 export type { Assign, AssignValueIfUnmergable, ColorModeConfig, FindPath, KeyAsVariable, LiteralPaths, Mergable, Merge, MergeTheme, Path, PathToLiteral, PathValue, PrivateThemeKeys, SanitizeKey, } from './theme';
 export { createTheme, ThemeBuilder } from './theme';
 export { borderShorthand } from './transforms/border';
@@ -16,9 +17,9 @@ export { createTransform, type NamedTransform, type TransformFn, } from './trans
 export { gridItem, gridItemRatio } from './transforms/grid';
 export { percentageOrAbsolute, size } from './transforms/size';
 export type { AnimusComponent, AnimusWrappedComponent, AnyBrandedComponent, ComposedFamily, SharedConfig, VariantPropsOf, } from './types/component';
-export type { AbstractParser, BuiltInSelectorAlias, CompoundEntry, CSSPropMap, CSSProps, CustomPropConfig, Parser, ParserProps, Prop, PropertyValues, Scale, ScaleValue, SelectorAliasProps, SystemProps, ThemedCSSPropMap, ThemedCSSProps, ThemedScale, ThemedScaleValue, VariantConfig, } from './types/config';
+export type { AbstractParser, BuiltInConditionAlias, BuiltInSelectorAlias, CompoundEntry, CSSPropMap, CSSProps, CustomPropConfig, Parser, ParserProps, Prop, PropertyValues, Scale, ScaleValue, SelectorAliasProps, SystemProps, ThemedCSSPropMap, ThemedCSSProps, ThemedScale, ThemedScaleValue, VariantConfig, } from './types/config';
 export type { AbstractProps, MediaQueryMap, ResponsiveProp, ThemeProps, } from './types/props';
 export type { ArrayScale, MapScale } from './types/scales';
 export type { CSSObject } from './types/shared';
-export type { AbstractTheme, BaseTheme, ColorTokenRef, CSSColorValue, EmittedScales, EmittedTokenPaths, ScaleTokenRef, SerializedTheme, Theme, ThemeManifest, TokenScales, } from './types/theme';
+export type { AbstractTheme, BaseTheme, BrowserColorSchemeConfig, ColorModeOptions, ColorTokenRef, ContextualVarRegistration, CSSColorValue, EmittedScales, EmittedTokenPaths, ScaleTokenRef, SerializedTheme, SystemPreferenceConfig, Theme, ThemeManifest, TokenScales, } from './types/theme';
 //# sourceMappingURL=index.d.ts.map