@tenphi/tasty 0.0.0-snapshot.d2dcdeb → 0.0.0-snapshot.d4ccea8

package/dist/index-BcsaHo8x.d.ts

@@ -0,0 +1,1568 @@
+import { Properties } from "csstype";
+
+//#region src/properties/property-type-resolver.d.ts
+/**
+ * PropertyTypeResolver
+ *
+ * Automatically infers CSS @property types from custom property values.
+ * Supports deferred resolution for var() reference chains of arbitrary depth.
+ */
+declare class PropertyTypeResolver {
+  /** propName → the prop it depends on */
+  private pendingDeps;
+  /** propName → list of props waiting on it */
+  private reverseDeps;
+  /**
+   * Scan CSS declarations and auto-register @property for custom properties
+   * whose types can be inferred from their values.
+   */
+  scanDeclarations(declarations: string, isPropertyDefined: (name: string) => boolean, registerProperty: (name: string, syntax: string, initialValue: string) => void): void;
+  private addDependency;
+  private resolve;
+  private isComplexValue;
+}
+//#endregion
+//#region src/injector/batch.d.ts
+/**
+ * Deferred CSSOM writes ("batched injection").
+ *
+ * Every `insertRule()` on a live stylesheet invalidates style for the sheet's
+ * scope, so Blink recalculates style the next time anything reads layout or
+ * computed style. When components inject during React's render phase and other
+ * components read layout in the same pass, the two interleave:
+ *
+ *   inject -> read (forced recalc) -> inject -> read (forced recalc) -> ...
+ *
+ * Batching moves every sheet write out from between those reads. Writes are
+ * queued in FIFO order and drained in one go, so the tree is invalidated once
+ * per flush instead of once per component.
+ *
+ * ## Ordering
+ *
+ * A single queue holds *all* writes — component rules, global rules, keyframes,
+ * `@property`, `@font-face`, `@counter-style`, `@function` and raw CSS. Draining
+ * it in insertion order keeps the sheet byte-identical to unbatched output,
+ * which matters because equal-specificity rules resolve by document order.
+ *
+ * ## Batch windows — why queuing is safe
+ *
+ * Deferring a write past React's layout phase would let a `useLayoutEffect`
+ * measure an element whose rules are not in the sheet yet, reading the unstyled
+ * box. `<TastyBatchProvider>` closes that hole by opening a *window* during its
+ * render and closing it — flushing — in its `useInsertionEffect`, which React
+ * runs in the mutation phase, before any layout effect:
+ *
+ *   provider renders          -> window OPEN
+ *     children render         -> injections queued
+ *   provider insertionEffect  -> FLUSH, window CLOSED
+ *   layout effects run        -> rules are in the sheet
+ *
+ * So in the default (`batchInjection: true`) mode a write is only ever queued
+ * inside a commit whose flush is already guaranteed by that same commit. Every
+ * injection outside a window — a deep update the provider did not re-render
+ * for, a `useLayoutEffect` that injects, an event handler, an async callback —
+ * is written straight through, exactly as with batching off.
+ *
+ * `batchInjection: 'always'` opts out of the gate and queues unconditionally.
+ * That wins on more commits, at the cost of the measurement hazard above.
+ *
+ * ## Flush points (earliest wins)
+ *
+ * 1. `<TastyBatchProvider>`'s `useInsertionEffect` — closes the window.
+ * 2. A microtask — a backstop for a render that was aborted or suspended and
+ *    therefore never reached its insertion effect. An aborted render mounts
+ *    nothing, so nothing can measure what it queued. Microtasks also always
+ *    drain before paint, so styles are never visually missing.
+ * 3. `flushStyles()` — explicit, and called internally by every injector read
+ *    API (`getCSSText`, `cleanup`, `gc`, `destroy`, ...).
+ */
+interface QueuedWrite {
+  /** Perform the deferred sheet write. */
+  run: () => void;
+  /** Set when the owner disposed before the write happened. */
+  cancelled: boolean;
+  /** Set once the write has been applied (or skipped as cancelled). */
+  done: boolean;
+}
+/** Whether any write is still waiting to hit a stylesheet. */
+declare function hasPendingStyleWrites(): boolean;
+/**
+ * Drain every pending sheet write, in insertion order.
+ *
+ * Safe to call when the queue is empty (the common case, so the guard comes
+ * first) and safe to call re-entrantly: a nested `flushStyles()` is a no-op,
+ * and work a draining write triggers is written in place by
+ * `enqueueStyleWrite` rather than queued behind the rest of the batch.
+ */
+declare function flushStyles(): void;
+/**
+ * Drop every pending write without applying it. Test helper — production code
+ * should call `flushStyles()` instead.
+ */
+declare function resetStyleBatch(): void;
+//#endregion
+//#region src/injector/types.d.ts
+declare global {
+  interface Window {
+    __TASTY__?: string[];
+  }
+}
+interface InjectResult {
+  className: string;
+  dispose: () => void;
+}
+interface GlobalInjectResult {
+  dispose: () => void;
+}
+type DisposeFunction = () => void;
+interface StyleInjectorConfig {
+  nonce?: string;
+  maxRulesPerSheet?: number;
+  forceTextInjection?: boolean;
+  /** Enable development mode features: performance metrics and debug information storage */
+  devMode?: boolean;
+  /**
+   * Global predefined states for advanced state mapping.
+   * These are state aliases that can be used in any component.
+   * Example: { '@mobile': '@media(w < 920px)', '@dark': '@root(theme=dark)' }
+   */
+  states?: Record<string, string>;
+  /**
+   * Automatically infer and register CSS @property declarations
+   * from custom property values. When false, only explicit @property are used.
+   * @default true
+   */
+  autoPropertyTypes?: boolean;
+  /** Garbage collection configuration for unused styles */
+  gc?: GCConfig;
+  /**
+   * Prefix prepended to every generated identifier.
+   * Mirrors the `namePrefix` field on the public `TastyConfig` so that
+   * standalone injector consumers can configure it directly.
+   * @default 't'
+   */
+  namePrefix?: string;
+  /**
+   * Defer stylesheet writes and apply them in one batch instead of one
+   * `insertRule()` per component. Mirrors `batchInjection` on the public
+   * `TastyConfig`.
+   * @default false
+   */
+  batchInjection?: boolean | 'always';
+}
+/**
+ * Per-className usage tracking for GC.
+ */
+interface StyleUsage {
+  lastTouchedAt: number;
+}
+/**
+ * Configuration for the style garbage collector.
+ *
+ * GC is triggered by touch count rather than timers: every `touchInterval`
+ * touches, an idle callback is scheduled to evict unused styles above
+ * `capacity`, oldest first.
+ */
+interface GCConfig {
+  /**
+   * Sweep automatically as rendering goes, instead of only when `gc()` or
+   * `cleanup()` is called (default `false`).
+   *
+   * **Unsafe, by name and in fact.** A sweep decides what is finished by
+   * scanning the DOM, and rendering is not commit-aware: a concurrent render
+   * can yield between the `inject()` that creates a class and the commit that
+   * attaches it. A sweep landing in that window sees no element carrying the
+   * class and deletes rules the pending render is about to use, so the element
+   * commits unstyled until something re-renders it. A pending render is
+   * indistinguishable from one that already committed and unmounted — React
+   * reports neither commit nor discard for a class name handed out during
+   * render — so no heuristic closes this; only a real commit signal would.
+   *
+   * Prefer `gc()` or `cleanup()` at a moment of your choosing: a route change,
+   * an idle callback of your own, test teardown.
+   */
+  unsafeAutoCollect?: boolean;
+  /**
+   * With `unsafeAutoCollect`, schedule the sweep with a timeout where
+   * `requestIdleCallback` is missing (default `false`).
+   *
+   * Collection is a background chore, so it otherwise only ever runs in idle
+   * time: where the engine cannot offer idle time, nothing is collected
+   * automatically at all. Opt in to give those engines automatic collection
+   * anyway, at the cost of a sweep that competes with whatever else the page is
+   * doing.
+   */
+  timeoutFallback?: boolean;
+  /**
+   * Number of touch events between automatic GC cycles.
+   * Only used with `unsafeAutoCollect`.
+   * @default 1000
+   */
+  touchInterval?: number;
+  /**
+   * Maximum number of unused styles to retain.
+   * GC evicts the oldest unused styles when this limit is exceeded.
+   * Pinned styles and DOM-live styles
+   * do not count against this limit.
+   * @default 1000
+   */
+  capacity?: number;
+}
+/**
+ * Per-call options for inject().
+ */
+interface InjectOptions {
+  root?: Document | ShadowRoot;
+  /** Reuse the class already injected for this key instead of writing again. */
+  cacheKey?: string;
+  /**
+   * Pin the injected class (default `true`). A pinned class is never evicted by
+   * `gc()`, and the returned `dispose()` releases the pin. Pass `false` when the
+   * caller keeps no handle and the DOM is the only record that the class is in
+   * use — the render path does this, because a hook-free render has no unmount
+   * signal to dispose on.
+   */
+  pin?: boolean;
+}
+/**
+ * Per-call options for gc().
+ */
+interface GCOptions {
+  root?: Document | ShadowRoot;
+  /** Bypass capacity threshold and remove ALL unused styles. */
+  force?: boolean;
+}
+interface RuleInfo {
+  className: string;
+  ruleIndex: number;
+  sheetIndex: number;
+  /** Dev-only: full CSS texts inserted for this class; omitted in production */
+  cssText?: string[];
+  /** Inclusive end index of the contiguous block of inserted rules for this className */
+  endRuleIndex?: number;
+  /** NEW: exact indices of all inserted rules for this className */
+  indices?: number[];
+}
+type InjectionMode = 'style-element' | 'adopted';
+interface SheetInfo {
+  /** HTMLStyleElement used in style-element mode; null in adopted mode. */
+  sheet: HTMLStyleElement | null;
+  /** Constructable CSSStyleSheet used in adopted mode (ShadowRoot targets) */
+  constructableSheet?: CSSStyleSheet;
+  ruleCount: number;
+  holes: number[];
+  /**
+   * True when this sheet is written through `textContent` instead of CSSOM.
+   * Decided once at sheet creation so a sheet is never half CSSOM / half text.
+   */
+  textMode?: boolean;
+  /**
+   * Inserted rule texts in rule-index order. Maintained only in text mode —
+   * it is what makes deletion possible there, since `textContent` cannot be
+   * edited rule-by-rule and has to be rebuilt.
+   */
+  textRules?: string[];
+}
+interface CleanupStats {
+  timestamp: number;
+  classesDeleted: number;
+  cssSize: number;
+  rulesDeleted: number;
+}
+interface CacheMetrics {
+  hits: number;
+  misses: number;
+  bulkCleanups: number;
+  totalInsertions: number;
+  totalUnused: number;
+  stylesCleanedUp: number;
+  cleanupHistory: CleanupStats[];
+  startTime: number;
+  unusedHits?: number;
+}
+interface RootRegistry {
+  sheets: SheetInfo[];
+  /** className -> outstanding `inject()` references; 0 means nobody holds a handle */
+  pinCounts: Map<string, number>;
+  rules: Map<string, RuleInfo>;
+  /** Cache key to className mapping to avoid dual storage of RuleInfo objects */
+  cacheKeyToClassName: Map<string, string>;
+  /** Deduplication set of fully materialized CSS rules inserted into sheets */
+  ruleTextSet: Set<string>;
+  /** Performance metrics (optional) */
+  metrics?: CacheMetrics;
+  /** Keyframes cache by content hash -> entry */
+  keyframesCache: Map<string, KeyframesCacheEntry>;
+  /** Keyframes name to content hash mapping for collision detection */
+  keyframesNameToContent: Map<string, string>;
+  /** Counter for generating keyframes names like k0, k1, k2... */
+  keyframesCounter: number;
+  /** Map of injected @property names to their normalized declarations for tracking */
+  injectedProperties: Map<string, string>;
+  /** Content hashes of injected @font-face rules for deduplication */
+  injectedFontFaces: Set<string>;
+  /**
+   * Injected @counter-style rules. Maps the name to whether it was injected
+   * "strong" (`true`, the default — overrides) or "weak" (`false`, global
+   * `configure()` definitions that never clobber an existing rule).
+   */
+  injectedCounterStyles: Map<string, boolean>;
+  /**
+   * Injected @function rules. Maps the CSS function name to whether it was
+   * injected "strong" (`true`, the default — overrides) or "weak" (`false`,
+   * global `configure()` definitions that never clobber an existing rule).
+   */
+  injectedFunctions: Map<string, boolean>;
+  /** Global rules tracking for index adjustment */
+  globalRules: Map<string, RuleInfo>;
+  /** Resolver for auto-inferring @property types from declaration values */
+  propertyTypeResolver: PropertyTypeResolver;
+  /** Per-className usage tracking for GC */
+  usageMap: Map<string, StyleUsage>;
+  /** Touch counter for scheduling GC (per-root) */
+  touchCount: number;
+  /**
+   * Millisecond that `touchedTick` refers to. `touch()` only ever stamps
+   * `lastTouchedAt` with the current millisecond, so a repeat touch of the same
+   * class name inside one millisecond is a no-op worth skipping.
+   */
+  touchTick: number;
+  /** Class-name strings already touched during `touchTick`. */
+  touchedTick: Set<string>;
+  /** How many entries from `window.__TASTY__` have been synced into this registry */
+  serverClassSyncIndex: number;
+  /** Whether `<style data-tasty-rsc>` tags have been scanned for class names */
+  rscStylesScanned: boolean;
+  /** Whether this root uses adoptedStyleSheets or <style> elements */
+  injectionMode: InjectionMode;
+  /**
+   * Lazy feature-test for `@property` support, cached per registry.
+   * - `undefined`: not yet probed.
+   * - `true`: engine supports `@property`; rejections indicate user-authored
+   *   invalid rules and should warn.
+   * - `false`: engine doesn't support `@property` (e.g., jsdom); rejections
+   *   are expected and warnings are suppressed.
+   */
+  atPropertySupported?: boolean;
+}
+type StyleRule = StyleResult;
+interface KeyframesInfo {
+  name: string;
+  sheetIndex: number;
+  ruleIndex: number;
+  /** Dev-only: full CSS text of the @keyframes rule; omitted in production */
+  cssText?: string;
+}
+type KeyframeStep = string | Record<string, string | number>;
+type KeyframesSteps = Record<string, KeyframeStep>;
+interface KeyframesResult {
+  toString(): string;
+  dispose: () => void;
+}
+interface KeyframesCacheEntry {
+  name: string;
+  refCount: number;
+  info: KeyframesInfo;
+  /**
+   * Queued sheet write, when `batchInjection` deferred the insertion. Present
+   * only between `keyframes()` and the flush; disposing in that window cancels
+   * the write instead of deleting a rule that was never inserted.
+   */
+  pending?: QueuedWrite;
+}
+/**
+ * Definition for a CSS @property at-rule.
+ * Used to define custom property syntax, inheritance, and initial value.
+ */
+interface PropertyDefinition {
+  /** CSS syntax string (e.g., '<color>', '<angle>', '<number>') */
+  syntax?: string;
+  /** Whether the property inherits (default: true) */
+  inherits?: boolean;
+  /** Initial value for the property */
+  initialValue?: string | number;
+}
+/**
+ * Options for registering a CSS `@property`.
+ * Extends {@link PropertyDefinition} with an optional injection root.
+ */
+interface PropertyOptions extends PropertyDefinition {
+  /** Shadow root or document to inject into */
+  root?: Document | ShadowRoot;
+}
+/**
+ * A single parameter for a CSS @function at-rule.
+ *
+ * - `true` — a bare parameter with no type or default.
+ * - `string` — a CSS type shorthand (e.g. `'<length>'`, `'<color>'`).
+ * - object — full form with optional `syntax` (type) and `default` value.
+ */
+type FunctionParameter = true | string | {
+  syntax?: string;
+  default?: string | number;
+};
+/**
+ * Definition for a CSS @function at-rule (custom function).
+ *
+ * The descriptor body reads like a mini styles object: any `$name` key declares
+ * a local variable (`--name`) whose value is parsed through the Tasty DSL.
+ * `result` is the only required field.
+ *
+ * @example
+ * ```ts
+ * // @function --negative(--value) { result: calc(-1 * var(--value)); }
+ * { args: ['$value'], result: '(-1 * $value)' }
+ * ```
+ */
+interface FunctionDefinition {
+  /**
+   * Ordered parameters. Array form lists bare parameter names (`['$value']`);
+   * object form maps each parameter name to its type/default.
+   */
+  args?: string[] | Record<string, FunctionParameter>;
+  /** Optional return type, e.g. `'<color>'`. */
+  returns?: string;
+  /** The `result:` descriptor value (parsed through the Tasty DSL). Required. */
+  result: string;
+  /** Local variables: any `$name` key declares `--name` in the body. */
+  [localVar: `$${string}`]: string | number | undefined;
+}
+/**
+ * Descriptors for a CSS @font-face at-rule.
+ */
+interface FontFaceDescriptors {
+  /** Required. URL(s) to the font file(s). */
+  src: string;
+  /** Font weight or range. Default: 'normal'. */
+  fontWeight?: string | number;
+  /** Font style. Default: 'normal'. */
+  fontStyle?: 'normal' | 'italic' | 'oblique' | (string & {});
+  /** Font stretch. Default: 'normal'. */
+  fontStretch?: string;
+  /** Loading behavior. Default: 'auto'. */
+  fontDisplay?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+  /** Unicode range to cover. */
+  unicodeRange?: string;
+  /** Ascent metric override. */
+  ascentOverride?: string;
+  /** Descent metric override. */
+  descentOverride?: string;
+  /** Line gap metric override. */
+  lineGapOverride?: string;
+  /** Size adjustment factor. */
+  sizeAdjust?: string;
+  /** OpenType feature settings. */
+  fontFeatureSettings?: string;
+  /** Font variation axis settings. */
+  fontVariationSettings?: string;
+}
+/** Single descriptor or array of descriptors for multiple weights/styles. */
+type FontFaceInput = FontFaceDescriptors | FontFaceDescriptors[];
+/**
+ * Descriptors for a CSS @counter-style at-rule.
+ */
+interface CounterStyleDescriptors {
+  /** Required. Numbering algorithm. */
+  system: 'cyclic' | 'numeric' | 'alphabetic' | 'symbolic' | 'additive' | 'fixed' | (string & {});
+  /** Symbols for non-additive systems. */
+  symbols?: string;
+  /** Symbol-value pairs for additive system. */
+  additiveSymbols?: string;
+  /** String prepended to the marker. Default: "". */
+  prefix?: string;
+  /** String appended to the marker. Default: ". ". */
+  suffix?: string;
+  /** Negative-value wrapping (e.g., '"(" ")"'). */
+  negative?: string;
+  /** Counter range (e.g., 'infinite infinite'). */
+  range?: string;
+  /** Minimum marker width and pad symbol (e.g., '3 "0"'). */
+  pad?: string;
+  /** Fallback counter style name. */
+  fallback?: string;
+  /** Speech synthesis hint. */
+  speakAs?: string;
+}
+interface RawCSSResult {
+  dispose: () => void;
+}
+//#endregion
+//#region src/utils/css-types.d.ts
+interface CSSProperties extends Properties<string | number> {}
+//#endregion
+//#region src/parser/types.d.ts
+/**
+ * A part within a group, representing a slash-separated segment.
+ * For example, in `'2px solid #red / 4px'`, there are two parts:
+ * - Part 0: `2px solid #red`
+ * - Part 1: `4px`
+ */
+interface StyleDetailsPart {
+  mods: string[];
+  values: string[];
+  colors: string[];
+  all: string[];
+  output: string;
+}
+/**
+ * A group of style details, representing a comma-separated segment.
+ * Contains aggregated values from all parts for backward compatibility,
+ * plus the structured `parts` array for handlers that need slash separation.
+ */
+interface StyleDetails {
+  input: string;
+  output: string;
+  /** Aggregated mods from all parts (backward compatible) */
+  mods: string[];
+  /** Aggregated values from all parts (backward compatible) */
+  values: string[];
+  /** Aggregated colors from all parts (backward compatible) */
+  colors: string[];
+  /** Aggregated all tokens from all parts (backward compatible) */
+  all: string[];
+  /** Slash-separated parts within this group */
+  parts: StyleDetailsPart[];
+}
+interface ProcessedStyle {
+  output: string;
+  groups: StyleDetails[];
+}
+type UnitHandler = (scalar: number) => string;
+interface ParserOptions {
+  functions?: Record<string, (parsed: StyleDetails[]) => string>;
+  units?: Record<string, string | UnitHandler>;
+  cacheSize?: number;
+}
+//#endregion
+//#region src/parser/parser.d.ts
+declare class StyleParser {
+  private opts;
+  private cache;
+  constructor(opts?: ParserOptions);
+  process(src: string): ProcessedStyle;
+  setFunctions(functions: Required<ParserOptions>['functions']): void;
+  setUnits(units: Required<ParserOptions>['units']): void;
+  updateOptions(patch: Partial<ParserOptions>): void;
+  /**
+   * Clear the parser cache.
+   * Call this when external state that affects parsing results has changed
+   * (e.g., predefined tokens).
+   */
+  clearCache(): void;
+  /**
+   * Get the current units configuration.
+   */
+  getUnits(): ParserOptions['units'];
+}
+//#endregion
+//#region src/utils/color-math.d.ts
+/**
+ * Consolidated color conversion math.
+ *
+ * Single source of truth for all color space conversions used across the
+ * library: sRGB gamma, HSL, OKLab, OKLCH, OKHSL, hex parsing, named
+ * colors, and CSS string converters.
+ *
+ * This module has zero internal imports — it is a leaf dependency.
+ *
+ * Reference: https://bottosson.github.io/posts/oklab/
+ */
+type Vec3 = [number, number, number];
+/**
+ * sRGB gamma to linear. Only the sRGB-to-OKLab direction needs it, so this is
+ * test-only for the same reason as {@link srgbToOkhsl} — the forward path goes
+ * through {@link srgbLinearToGamma} instead.
+ */
+/**
+ * HSL to RGB.
+ * Algorithm from CSS Color 4 spec.
+ *
+ * @param h - Hue in degrees (0-360)
+ * @param s - Saturation (0-1)
+ * @param l - Lightness (0-1)
+ * @returns RGB values in 0-255 range (may have fractional values)
+ */
+declare function hslToRgbValues(h: number, s: number, l: number): Vec3;
+declare function getNamedColorHex(): Map<string, string>;
+/**
+ * Convert hex color string to `rgb()` CSS string.
+ * Supports 3, 4, 6, and 8 character hex values (with or without `#`).
+ */
+declare function hexToRgb(hex: string): string | null;
+/**
+ * Extract RGB values from an `rgb()`/`rgba()` string.
+ * Supports comma-separated, space-separated, fractional, percentage,
+ * and slash alpha notation.
+ *
+ * @returns Array of RGB values (0-255 range), converting percentages as needed.
+ */
+declare function getRgbValuesFromRgbaString(str: string): number[];
+/**
+ * Convert any recognized color string to an `rgb()` CSS string.
+ * Handles hex, `okhsl()`, `okhst()`, `hsl()`/`hsla()`, named CSS colors,
+ * and `rgb()`/`rgba()` pass-through.
+ */
+declare function strToRgb(color: string, _ignoreAlpha?: boolean): string | null | undefined;
+//#endregion
+//#region src/utils/styles.d.ts
+type StyleValue<T = string> = T | boolean | number | null | undefined;
+/**
+ * Normalize a color token value.
+ * - Boolean `true` is converted to `'transparent'`
+ * - Boolean `false` returns `null` (signals the token should be skipped)
+ * - Other values are returned as-is
+ *
+ * @param value - The raw token value
+ * @returns Normalized value or null if the token should be skipped
+ */
+declare function normalizeColorTokenValue<T>(value: T | boolean): T | 'transparent' | null;
+type StyleValueStateMap<T = string> = Record<string, StyleValue<T> | '@inherit'>;
+/**
+ * Combined type for style values that can be either a direct value or a state map.
+ * Use this for component props that accept style values.
+ */
+type StylePropValue<T = string> = StyleValue<T> | StyleValueStateMap<T>;
+/**
+ * One dependency value as a style handler receives it: already resolved for a
+ * single state, but still the **raw authored DSL string** (`'2x'`, `'#purple.5'`).
+ * Handlers parse it themselves via {@link parseStyle} / {@link parseColor}.
+ */
+type ResolvedStyleValue = StyleValue<string>;
+/**
+ * The dependency map a handler receives — one resolved value per style name in
+ * its `__lookupStyles`.
+ */
+type StyleHandlerProps<TDeps extends string = string> = Partial<Record<TDeps, ResolvedStyleValue>>;
+/**
+ * One set of CSS declarations returned by a style handler.
+ *
+ * Keys are **kebab-case** CSS property names (`'background-color'`, not
+ * `backgroundColor`) or `--custom-property` names. Values are stringified, so
+ * numbers are accepted. `$` is reserved as a selector suffix.
+ */
+type CSSMap = {
+  /** Selector suffix (or suffixes) these declarations apply to, e.g. `'& > *'`. */$?: string | string[];
+} & Record<string, string | number | (string | number)[] | undefined>;
+type StyleHandlerResult = CSSMap | CSSMap[] | null | void;
+type RawStyleHandler<TProps extends object = StyleHandlerProps> = (props: TProps) => StyleHandlerResult;
+type StyleHandler<TProps extends object = StyleHandlerProps> = RawStyleHandler<TProps> & {
+  __lookupStyles: string[];
+};
+/**
+ * The handler type used by the registry (`STYLE_HANDLER_MAP`), with parameter
+ * variance erased.
+ *
+ * Handlers declare narrow, hand-written dependency types — `({ fill }: { fill?:
+ * string }) => …` — which under `strictFunctionTypes` are not assignable to a
+ * wider parameter type. The registry stores handlers of many different dependency
+ * shapes together, so it needs the erased form. Prefer {@link StyleHandler} (or
+ * {@link defineHandler}) when writing a handler; this type is for code that
+ * inspects the registry.
+ */
+type AnyStyleHandler = ((props: any) => StyleHandlerResult) & {
+  __lookupStyles: string[];
+};
+/**
+ * Handler definition forms for configure() and plugins.
+ * - Function only: lookup styles inferred from key name
+ * - Single property tuple: ['styleName', handler]
+ * - Multi-property tuple: [['style1', 'style2'], handler]
+ *
+ * Use {@link defineHandler} to have the dependency names inferred into the
+ * handler's parameter type instead of annotating it by hand.
+ */
+type StyleHandlerDefinition<TDeps extends string = string> = RawStyleHandler<StyleHandlerProps<TDeps>> | [TDeps, RawStyleHandler<StyleHandlerProps<TDeps>>] | [readonly TDeps[], RawStyleHandler<StyleHandlerProps<TDeps>>];
+interface ParsedColor {
+  color?: string;
+  name?: string;
+  opacity?: number;
+}
+type StyleMap = Record<string, StyleValue | StyleValueStateMap>;
+declare const CUSTOM_UNITS: {
+  r: string;
+  cr: string;
+  bw: string;
+  ow: string;
+  x: string;
+  sf: (num: number) => string;
+};
+declare const DIRECTIONS: string[];
+/**
+ * Get the global StyleParser instance.
+ * Used by configure() to apply parser configuration.
+ */
+declare function getGlobalParser(): StyleParser;
+/**
+ * Get the current global predefined tokens.
+ * Returns null if no tokens are configured.
+ */
+declare function getGlobalPredefinedTokens(): Record<string, string> | null;
+/**
+ *
+ * @param {String} value
+ * @param {Number} mode
+ * @returns {Object<String,String|Array>}
+ */
+declare function parseStyle(value: StyleValue): ProcessedStyle;
+/**
+ * Parse color. Find it value, name and opacity.
+ * Optimized to avoid heavy parseStyle calls for simple color patterns.
+ */
+declare function parseColor(val: string, ignoreError?: boolean): ParsedColor;
+declare function filterMods(mods: string[], allowedMods: string[]): string[];
+declare function stringifyStyles(styles: unknown): string;
+//#endregion
+//#region src/styles/types.d.ts
+/**
+ * Extensible interface for named color tokens.
+ * Augment this interface to register project-specific color names
+ * for autocomplete in `fill`, `color`, `svgFill`, and other color style props.
+ *
+ * @example
+ * ```typescript
+ * declare module '@tenphi/tasty' {
+ *   interface TastyNamedColors {
+ *     primary: true;
+ *     danger: true;
+ *   }
+ * }
+ * ```
+ */
+interface TastyNamedColors {}
+type NamedColorKey = Extract<keyof TastyNamedColors, string>;
+type NamedColor = [NamedColorKey] extends [never] ? string : NamedColorKey;
+/**
+ * Extensible interface for typography preset names.
+ * Augment this interface to register project-specific preset names for autocomplete.
+ *
+ * @example
+ * ```typescript
+ * declare module '@tenphi/tasty' {
+ *   interface TastyPresetNames {
+ *     h1: true;
+ *     t3: true;
+ *   }
+ * }
+ * ```
+ */
+interface TastyPresetNames {}
+type PresetNameKey = Extract<keyof TastyPresetNames, string>;
+type PresetName = [PresetNameKey] extends [never] ? string : PresetNameKey;
+type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+type OpaquePercentage = '' | `.${Digit}` | `.${Digit}${Digit}` | '.100';
+type ColorValue = `#${NamedColor}${OpaquePercentage}` | `rgb(${string})` | `hsl(${string})` | `okhsl(${string})` | `oklch(${string})` | (string & {});
+type NoType = false | null | undefined;
+interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' | 'font' | 'outline' | 'type' | 'gap' | 'padding' | 'margin' | 'width' | 'height' | 'border' | 'transition' | 'placeContent' | 'placeItems' | 'scrollMargin' | 'scrollMarginTop' | 'scrollMarginRight' | 'scrollMarginBottom' | 'scrollMarginLeft' | 'scrollMarginBlock' | 'scrollMarginInline'> {
+  /**
+   * @deprecated Use `flow` style instead.
+   */
+  flexDirection: CSSProperties['flexDirection'];
+  /**
+   * @deprecated Use `placeContent`, `placeItems`, `gridColumns`, `gridRows`, and `gridTemplate` styles instead.
+   */
+  grid: CSSProperties['grid'];
+  /**
+   * @deprecated Use `flexShrink`, `flexGrow`, and `flexBasis` styles instead.
+   */
+  flex: CSSProperties['flex'];
+  /**
+   * Set the background color of the element. Shortcut for `background-color` with enhanced support for Tasty color tokens and syntaxes.
+   *
+   * Supports double-color syntax: the second color is applied as a foreground overlay via a CSS custom property.
+   *
+   * Examples:
+   * - `fill="#purple.10"` // purple background with 10% opacity
+   * - `fill="#danger"` // danger theme color
+   * - `fill="rgb(255 128 0)"` // custom RGB color
+   * - `fill="rgb(255 128 0 / 0.5)"` // RGB with opacity
+   * - `fill="hsl(200 100% 50%)"` // HSL color
+   * - `fill="okhsl(200 100% 50%)"` // perceptually uniform OKHSL color
+   * - `fill="oklch(0.7 0.15 200)"` // OKLCH color
+   * - `fill="#primary #secondary"` // double color (second as foreground overlay)
+   * - `fill={true}` // default fill color
+   */
+  fill?: ColorValue | boolean;
+  /**
+   * @deprecated Use `fill` instead.
+   */
+  backgroundColor?: CSSProperties['backgroundColor'];
+  /**
+   * Set the background image of the element. Shortcut for `background-image` with enhanced support for Tasty tokens.
+   *
+   * Examples:
+   * - `image="url(/path/to/image.png)"` // image from URL
+   * - `image="linear-gradient(to right, #purple, #danger)"` // gradient
+   */
+  image?: CSSProperties['backgroundImage'];
+  /**
+   * @deprecated Use `image` instead.
+   */
+  backgroundImage?: CSSProperties['backgroundImage'];
+  /**
+   * @deprecated Use separate background styles (`fill`, `image`, `backgroundSize`, etc.) instead.
+   * When set, overrides all other background-related styles.
+   */
+  background?: CSSProperties['background'];
+  /**
+   * Set the fill color of SVG elements. Outputs the native CSS `fill` property with enhanced support for Tasty color tokens and syntaxes.
+   *
+   * Examples:
+   * - `svgFill="#purple.10"` // purple fill with 10% opacity
+   * - `svgFill="#danger"` // danger theme color
+   * - `svgFill="rgb(255 128 0)"` // custom RGB color
+   * - `svgFill="hsl(200 100% 50%)"` // HSL color
+   * - `svgFill="okhsl(200 100% 50%)"` // OKHSL color
+   * - `svgFill="oklch(0.7 0.15 200)"` // OKLCH color
+   * - `svgFill="currentColor"` // inherit from parent color
+   */
+  svgFill?: ColorValue;
+  /**
+   * Set the text (current) color of the element. Shortcut for `color` with enhanced support for Tasty color tokens and syntaxes.
+   *
+   * Examples:
+   * - `color="#purple"` // purple text color
+   * - `color="#danger.6"` // danger color with 60% opacity
+   * - `color="rgb(255 128 0)"` // custom RGB color
+   * - `color="hsl(200 100% 50%)"` // HSL color
+   * - `color="okhsl(200 100% 50%)"` // OKHSL color
+   * - `color="oklch(0.7 0.15 200)"` // OKLCH color
+   * - `color="red"` // CSS color name
+   * - `color={true}` // currentColor
+   */
+  color?: ColorValue | boolean;
+  /**
+   * The fade style applies gradient-based fading masks to the edges of an element. Replaces complex CSS mask gradients with a simple, declarative API.
+   *
+   * Syntax: `[width] [direction...] [#from-color] [#to-color]`
+   *
+   * Multiple groups can be separated by commas to specify different widths and
+   * colors per direction. A group that names edges takes a single width, applied
+   * to every edge it names; a group that names none covers all four edges and
+   * keeps plain CSS shorthand order.
+   *
+   * Color tokens (optional):
+   * - First color: transparent start of gradient (default: `rgb(0 0 0 / 0)`)
+   * - Second color: opaque end of gradient (default: `rgb(0 0 0 / 1)`)
+   *
+   * Examples:
+   * - `fade="top"` // fade only top edge with default width
+   * - `fade="2x left right"` // fade left and right edges with 2x width
+   * - `fade={true}` // all edges at the design-system default width
+   * - `fade="1x top"` // fade only top edge with 1x width
+   * - `fade="3x 1x"` // all edges: top/bottom 3x, left/right 1x
+   * - `fade="3x top, 1x bottom"` // top: 3x width, bottom: 1x width
+   * - `fade="2x #transparent #dark"` // custom colors for gradient mask
+   * - `fade="1x top #clear #solid"` // top edge with custom mask colors
+   * - `fade="top #red #blue, bottom #green #yellow"` // different colors per direction
+   * - `fade="2x top #a #b, 1x bottom #c #d"` // different widths and colors per direction
+   */
+  fade?: 'top' | 'right' | 'bottom' | 'left' | string | boolean;
+  /**
+   * Scrollbar styling using standard CSS properties (`scrollbar-width`, `scrollbar-color`, `scrollbar-gutter`).
+   *
+   * Syntax: `[width] [modifiers...] [thumb-color] [track-color]`
+   *
+   * Width values: `thin` (default), `auto`, `none`
+   * Modifiers: `stable`, `both-edges`, `always`
+   *
+   * Examples:
+   * - `scrollbar={true}` // thin scrollbar, default colors
+   * - `scrollbar="thin #purple.40 #dark.04"`
+   * - `scrollbar="auto #red #blue"`
+   * - `scrollbar="none"`
+   * - `scrollbar="always #primary.50 #white.02"`
+   * - `scrollbar="thin stable #red #blue"`
+   */
+  scrollbar?: string | boolean;
+  /**
+   * Set font weight for bold texts.
+   */
+  boldFontWeight?: number;
+  /**
+   * The gap style is a powerful, cross-layout shorthand for spacing between child elements. Works with flex, grid, and block layouts.
+   *
+   * For flex/grid: sets native `gap` property
+   * For block layouts: emulated using margin on children
+   *
+   * Examples:
+   * - `gap="2x"` // gap: 2x (or margin-bottom: 2x for block)
+   * - `gap="1x 2x"` // row gap: 1x, column gap: 2x
+   * - `gap={true}` // default gap (1x)
+   */
+  gap?: CSSProperties['gap'] | string | boolean;
+  /**
+   * Shorthand for element padding. Supports custom units, directional modifiers, and design-system-driven defaults.
+   *
+   * A group that names directions takes a single value, applied to every
+   * direction it names — use comma groups for per-side values.
+   *
+   * Examples:
+   * - `padding="2x 1x"` // top/bottom: 2x, left/right: 1x
+   * - `padding="2x top"` // only top padding: 2x
+   * - `padding="1x left right"` // left and right padding: 1x
+   * - `padding="2x top, 4x right"` // top: 2x, right: 4x, bottom/left: 0
+   * - `padding={true}` // default padding on all sides
+   */
+  padding?: CSSProperties['padding'] | string | boolean;
+  /**
+   * Shorthand for element margin. Supports custom units, directional modifiers, and design-system-driven defaults.
+   *
+   * A group that names directions takes a single value, applied to every
+   * direction it names — use comma groups for per-side values.
+   *
+   * Examples:
+   * - `margin="2x 1x"` // top/bottom: 2x, left/right: 1x
+   * - `margin="2x top"` // only top margin: 2x
+   * - `margin="1x left right"` // left and right margin: 1x
+   * - `margin="2x top, 4x right"` // top: 2x, right: 4x, bottom/left: 0
+   * - `margin={true}` // default margin on all sides
+   */
+  margin?: CSSProperties['margin'] | string | boolean;
+  /**
+   * Concise shorthand for setting element width, including min-width and max-width. Supports custom units and advanced sizing keywords.
+   *
+   * Syntax: `[value]` | `[min max]` | `[min value max]` | `[modifier value]`
+   *
+   * Modifiers: `min`, `max`
+   * Keywords: `stretch`, `max-content`, `min-content`, `fit-content`
+   *
+   * Examples:
+   * - `width="10x"` // width: 10x
+   * - `width="1x 10x"` // min-width: 1x; max-width: 10x
+   * - `width="min 2x"` // min-width: 2x
+   * - `width="stretch"` // width: stretch (fill-available)
+   * - `width={true}` // width: auto
+   */
+  width?: CSSProperties['width'] | string | boolean;
+  /**
+   * Concise shorthand for setting element height, including min-height and max-height. Supports custom units and advanced sizing keywords.
+   *
+   * Syntax: `[value]` | `[min max]` | `[min value max]` | `[modifier value]`
+   *
+   * Modifiers: `min`, `max`
+   * Keywords: `stretch`, `max-content`, `min-content`, `fit-content`
+   *
+   * Examples:
+   * - `height="100px"` // height: 100px
+   * - `height="1x 5x 10x"` // min-height: 1x; height: 5x; max-height: 10x
+   * - `height="min 2x"` // min-height: 2x
+   * - `height={true}` // height: auto
+   */
+  height?: CSSProperties['height'] | string | boolean;
+  /**
+   * Shorthand for border width, style, and color. Supports directional modifiers and design-system defaults.
+   *
+   * Syntax: `[width] [style] [color] [directions]` | `[directions]` | `true`
+   *
+   * Multiple groups can be separated by commas. Later groups override earlier groups for conflicting directions.
+   *
+   * Examples:
+   * - `border={true}` // default border on all sides (1bw solid)
+   * - `border="2bw dashed #purple"` // 2bw dashed purple border
+   * - `border="2bw top"` // only top border: 2bw solid
+   * - `border="dotted #danger left right"` // left/right: 1bw dotted danger
+   * - `border="1bw #red, 2bw #blue top"` // all sides red 1bw, top overridden to blue 2bw
+   * - `border="1bw, dashed top bottom, #purple left right"` // base 1bw, dashed on top/bottom, purple on left/right
+   * - `border="1bw $my-style"` // custom property in the style slot
+   *
+   * A `$name` reference fills the first free slot — width, then style, then
+   * color. Colors are authored as `#name`; to point the color slot at a raw
+   * custom property directly, name it `$name-color`.
+   */
+  border?: CSSProperties['border'] | string | boolean;
+  /**
+   * Powerful shorthand for CSS transitions using semantic names and design tokens. Supports grouped transitions for common UI effects.
+   *
+   * Semantic names: `fade`, `fill`, `border`, `radius`, `shadow`, `preset`, `gap`, `theme`
+   * Multiple transitions: separated by commas
+   *
+   * Examples:
+   * - `transition="fill 0.2s, radius 0.3s"` // transitions background-color and border-radius
+   * - `transition="fade 0.15s ease-in"` // transitions mask with easing
+   * - `transition="theme 0.3s"` // transitions all theme-related properties
+   * - `transition="preset 0.2s"` // transitions typography properties
+   */
+  transition?: CSSProperties['transition'] | string;
+  /**
+   * Whether the element is hidden using `display: none`. Boolean shortcut for conditional element visibility.
+   *
+   * Examples:
+   * - `hide={true}` // display: none
+   * - `hide={false}` // element remains visible
+   */
+  hide?: boolean;
+  /**
+   * The shadow style adds shadow effects around an element's frame. Supports multiple effects separated by commas with X/Y offsets, blur, spread radius, and color.
+   *
+   * Examples:
+   * - `shadow="1x .5x .5x #dark.50"` // custom shadow with Tasty units and colors
+   * - `shadow="0 1x 2x #dark.20"` // standard shadow syntax
+   * - `shadow={true}` // default shadow from design system
+   */
+  shadow?: string | boolean;
+  /**
+   * The radius style rounds the corners of an element's outer border edge. Supports custom units, advanced shapes, and directional modifiers.
+   *
+   * Syntax: `[value] [modifiers]` | `[shape]` | `true`
+   *
+   * Shapes: `round` (fully rounded), `ellipse` (50%), `leaf`, `backleaf` (asymmetric), `inherit` (inherit from parent)
+   * Edge modifiers: `top`, `right`, `bottom`, `left` — the corner pair along that edge
+   * Corner modifiers: `top-left`, `top-right`, `bottom-right`, `bottom-left` — a single corner
+   *
+   * Examples:
+   * - `radius="2r"` // border-radius: calc(var(--radius) * 2)
+   * - `radius={true}` // default radius (1r)
+   * - `radius="round"` // fully rounded (9999rem)
+   * - `radius="leaf"` // asymmetric leaf shape
+   * - `radius="1r top"` // round both top corners
+   * - `radius="top-right"` // round only the top-right corner (1r)
+   * - `radius="4px top-left"` // round only the top-left corner
+   * - `radius="inherit"` // inherit border-radius from parent
+   * - `radius="inherit right"` // inherit only right corners (uses longhand properties)
+   */
+  radius?: 'round' | 'ellipse' | 'leaf' | 'backleaf' | 'inherit' | string | true;
+  /**
+   * The flow style is a unified shorthand for controlling layout direction and wrapping in both flex and grid containers. Replaces `flexDirection` and `gridAutoFlow`.
+   *
+   * For flex: sets `flex-flow` (direction + wrapping)
+   * For grid: sets `grid-auto-flow` (direction + density)
+   * For block: determines gap direction (row/column)
+   *
+   * Syntax: `[direction] [wrap|dense]`
+   *
+   * Examples:
+   * - `flow="row wrap"` // flex-flow: row wrap
+   * - `flow="column dense"` // grid-auto-flow: column dense
+   * - `flow="row"` // primary axis direction
+   */
+  flow?: CSSProperties['flexFlow'] | CSSProperties['gridAutoFlow'] | string;
+  /**
+   * The gridAreas style specifies named grid areas, establishing cells in the grid and assigning them names.
+   *
+   * Examples:
+   * - `gridAreas='"header header" "sidebar content" "footer footer"'`
+   */
+  gridAreas?: CSSProperties['gridTemplateAreas'];
+  /**
+   * The gridColumns style defines line names and track sizing functions of grid columns.
+   *
+   * Examples:
+   * - `gridColumns="1fr 2fr 1fr"` // three columns with flex ratios
+   * - `gridColumns={3}` // three equal columns (shorthand)
+   * - `gridColumns="repeat(auto-fit, minmax(200px, 1fr))"` // responsive columns
+   */
+  gridColumns?: CSSProperties['gridTemplateColumns'] | number;
+  /**
+   * The gridRows style defines line names and track sizing functions of grid rows.
+   *
+   * Examples:
+   * - `gridRows="auto 1fr auto"` // header, content, footer layout
+   * - `gridRows={4}` // four equal rows (shorthand)
+   * - `gridRows="repeat(3, 100px)"` // three 100px rows
+   */
+  gridRows?: CSSProperties['gridTemplateRows'] | number;
+  /**
+   * The gridTemplate style is a shorthand property for defining grid columns, rows, and areas simultaneously.
+   *
+   * Examples:
+   * - `gridTemplate='"header header" auto "content sidebar" 1fr / 2fr 1fr'`
+   */
+  gridTemplate?: CSSProperties['gridTemplate'];
+  /**
+   * The font style specifies a prioritized list of font family names with design-system-driven defaults and fallbacks.
+   *
+   * Examples:
+   * - `font="monospace"` // monospace font stack
+   * - `font="Helvetica, Arial, sans-serif"` // custom font list
+   * - `font={true}` // default design system font
+   */
+  font?: CSSProperties['fontFamily'] | boolean;
+  /**
+   * The outline style sets the outline for the element.
+   *
+   * Syntax: `[width] [style] [color] / [offset]` | `true`
+   *
+   * Examples:
+   * - `outline="2ow dashed #purple"` // 2ow dashed purple outline
+   * - `outline="2ow #danger / 1x"` // 2ow solid danger outline, 1x offset
+   * - `outline={true}` // default outline (1ow solid)
+   * - `outline="2ow $my-style"` // custom property in the style slot
+   *
+   * A `$name` reference fills the first free slot — width, then style, then
+   * color. Colors are authored as `#name`; to point the color slot at a raw
+   * custom property directly, name it `$name-color`.
+   */
+  outline?: string | boolean;
+  /**
+   * The outline offset style sets the offset of the outline.
+   *
+   * Examples:
+   * - `outlineOffset="4px"` // 4px offset
+   * - `outlineOffset="1x"` // 1x (8px) offset
+   */
+  outlineOffset?: string | number;
+  /**
+   * The preset style sets base text settings according to named presets. Affects `font-size`, `line-height`, `letter-spacing`, `font-weight`, and `text-transform`.
+   *
+   * Syntax: `name`, `name / modifier...`, or `modifier...` (shorthand, name defaults to `inherit`).
+   * Multiple modifiers are space-separated and combine freely (e.g. `strong italic tight`).
+   * Preset names are project-specific. Augment `TastyPresetNames` to register them for autocomplete.
+   *
+   * Examples:
+   * - `preset="h1"` // heading 1 typography
+   * - `preset="h2 / strong"` // bold heading 2
+   * - `preset="h2 / strong italic"` // bold + italic heading 2
+   * - `preset="t2 / strong tight"` // bold text 2 with tight line-height
+   * - `preset="bold"` // inherit with bold (shorthand)
+   * - `preset="bold italic"` // inherit with bold + italic (shorthand)
+   * - `preset="t3"` // text size 3
+   */
+  preset?: PresetName | (string & {});
+  /**
+   * Shorthand for `align-items` and `align-content`. Sets both properties for unified vertical alignment in flex/grid layouts.
+   *
+   * Examples:
+   * - `align="center"` // align-items: center; align-content: center
+   * - `align="flex-start"` // align both to start
+   * - `align="space-between"` // distribute space between items
+   */
+  align?: CSSProperties['alignItems'] | CSSProperties['alignContent'];
+  /**
+   * Shorthand for `justify-items` and `justify-content`. Sets both properties for unified horizontal alignment in flex/grid layouts.
+   *
+   * Examples:
+   * - `justify="center"` // justify-items: center; justify-content: center
+   * - `justify="space-between"` // distribute space between items
+   * - `justify="flex-end"` // align both to end
+   */
+  justify?: CSSProperties['justifyItems'] | CSSProperties['justifyContent'];
+  /**
+   * Shorthand for all placement properties. Sets all 4 longhands: align-items, justify-items, align-content, justify-content.
+   *
+   * Examples:
+   * - `place="center"` // all 4 longhands: center
+   * - `place="start end"` // align-*: start; justify-*: end
+   * - `place="stretch"` // all 4 longhands: stretch
+   */
+  place?: CSSProperties['placeItems'] | CSSProperties['placeContent'] | string;
+  /**
+   * Sets `place-content` property for aligning and distributing content in grid/flex containers.
+   *
+   * Examples:
+   * - `placeContent="center"` // center content in both axes
+   * - `placeContent="space-between"` // distribute content with space between
+   */
+  placeContent?: CSSProperties['placeContent'];
+  /**
+   * Sets `place-items` property for aligning items in grid/flex containers.
+   *
+   * Examples:
+   * - `placeItems="center"` // center items in both axes
+   * - `placeItems="start end"` // start on block axis, end on inline axis
+   */
+  placeItems?: CSSProperties['placeItems'];
+  /**
+   * Shorthand for scroll-margin on all sides. Supports custom units and directional modifiers.
+   *
+   * Examples:
+   * - `scrollMargin="2x"` // scroll-margin on all sides: 2x
+   * - `scrollMargin="2x top"` // only top scroll-margin: 2x
+   * - `scrollMargin="2x top, 4x bottom"` // top: 2x, bottom: 4x
+   * - `scrollMargin={true}` // default scroll-margin on all sides
+   */
+  scrollMargin?: CSSProperties['scrollMargin'] | string | boolean;
+  scrollMarginTop?: string | number | boolean;
+  scrollMarginRight?: string | number | boolean;
+  scrollMarginBottom?: string | number | boolean;
+  scrollMarginLeft?: string | number | boolean;
+  scrollMarginBlock?: string | number | boolean;
+  scrollMarginInline?: string | number | boolean;
+  /**
+   * Shorthand for `top`, `right`, `bottom`, and `left` offsets. Supports custom units, directional modifiers, and positioning.
+   *
+   * Examples:
+   * - `inset="0"` // all sides: 0
+   * - `inset="2x top"` // only top offset: 2x
+   * - `inset="1x left right"` // left and right offsets: 1x
+   * - `inset="2x top, 4x right"` // top: 2x, right: 4x, bottom/left: auto
+   * - `inset="bottom dock"` // bottom-anchored, full width: auto 0 0 0
+   * - `inset={true}` // all sides: 0
+   *
+   * A group that names directions takes a single value, applied to every
+   * direction it names — use comma groups for per-side values.
+   *
+   * The `dock` modifier pins the named edge and spans its full length, applying
+   * the value to the two perpendicular sides as well. `dock` is the one case
+   * where a directional group takes two values: the second applies to those
+   * spanned sides, so `inset="2x 4x bottom dock"` pins the bottom at `2x` and
+   * insets the sides by `4x`. Without `dock` a second value is ignored.
+   */
+  inset?: 'top' | 'right' | 'bottom' | 'left' | 'dock' | string | CSSProperties['inset'];
+  /**
+   * Local keyframes definitions for this component.
+   * Keys are animation names, values are keyframes step definitions.
+   * Local keyframes override global keyframes with the same name.
+   *
+   * Examples:
+   * - `'@keyframes': { fadeIn: { from: { opacity: 0 }, to: { opacity: 1 } } }`
+   * - `'@keyframes': { pulse: { '0%, 100%': { transform: 'scale(1)' }, '50%': { transform: 'scale(1.05)' } } }`
+   */
+  '@keyframes'?: Record<string, KeyframesSteps>;
+  /**
+   * CSS @property definitions for custom properties using tasty token syntax.
+   * Properties are registered once and are permanent (never removed).
+   *
+   * Token formats:
+   * - `$name` for regular properties → `--name` (requires syntax to be specified)
+   * - `#name` for color properties → `--name-color` (auto-sets syntax: '<color>', defaults initialValue: 'transparent')
+   *
+   * Examples:
+   * - `'@property': { '$rotation': { syntax: '<angle>', inherits: false, initialValue: '45deg' } }`
+   * - `'@property': { '#theme': { initialValue: 'purple' } }` // syntax: '<color>' is auto-set
+   */
+  '@property'?: Record<string, PropertyDefinition>;
+  /**
+   * Local @font-face definitions for this component.
+   * Keys are font-family names, values are descriptors or arrays of descriptors
+   * (for multiple weights/styles of the same family).
+   *
+   * Examples:
+   * - `'@font-face': { Icons: { src: 'url("/fonts/icons.woff2") format("woff2")', fontDisplay: 'block' } }`
+   * - `'@font-face': { 'Brand Sans': [{ src: '...', fontWeight: 400 }, { src: '...', fontWeight: 700 }] }`
+   */
+  '@font-face'?: Record<string, FontFaceInput>;
+  /**
+   * Local @counter-style definitions for this component.
+   * Keys are counter-style names, values are descriptor objects.
+   *
+   * Examples:
+   * - `'@counter-style': { thumbs: { system: 'cyclic', symbols: '"👍"', suffix: '" "' } }`
+   */
+  '@counter-style'?: Record<string, CounterStyleDescriptors>;
+  /**
+   * Local @function definitions (CSS custom functions) for this component.
+   * Keys are function names using `$$name` (the literal callable `--name`),
+   * matching the call site `$$name(...)`. Values are function definitions.
+   *
+   * Local variables are declared directly as `$name` keys on the descriptor;
+   * `result`, local-var values, and parameter defaults are parsed through the
+   * Tasty DSL (units, color tokens, auto-calc, fallbacks).
+   *
+   * Examples:
+   * - `'@function': { '$$negative': { args: ['$value'], result: '(-1 * $value)' } }`
+   * - `'@function': { '$$shadow': { args: { '$color': { syntax: '<color>', default: 'inherit' } }, returns: '<color>', '$offset': '2px', result: '$offset $offset ($color, black)' } }`
+   */
+  '@function'?: Record<string, FunctionDefinition>;
+  /**
+   * Apply one or more predefined style recipes by name.
+   * Recipes are defined globally via `configure({ recipes: { ... } })`.
+   * Multiple recipes are space-separated. Use `/` to separate base recipes
+   * (applied before component styles) from post recipes (applied after, via mergeStyles).
+   * Use `none` to explicitly skip base recipes.
+   *
+   * Examples:
+   * - `recipe: 'card'` // Apply the 'card' recipe
+   * - `recipe: 'card elevated'` // Apply 'card' then 'elevated', then component styles
+   * - `recipe: 'reset input / input-autofill'` // Base recipes, then post recipe
+   * - `recipe: 'none / disabled'` // No base recipes, only post recipe
+   * - `recipe: ''` // Clear recipes from base styles when extending
+   */
+  recipe?: string;
+}
+type SuffixForSelector = '&' | '.' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+type Selector = `${SuffixForSelector}${string}`;
+type NotSelector = Exclude<string, Selector | keyof StylesInterface>;
+/** Special style keys that should not be wrapped in StyleValue/StyleValueStateMap */
+type SpecialStyleKeys = '@keyframes' | '@property' | '@font-face' | '@counter-style' | '@function' | 'recipe';
+type StylesWithoutSelectors = { [key in keyof StylesInterface as key extends SpecialStyleKeys ? never : key]?: StyleValue<StylesInterface[key]> | StyleValueStateMap<StylesInterface[key]> };
+/**
+ * Index signature for recipe-specific arbitrary keys.
+ * Supports local predefined states (`@name`), vendor-prefixed CSS properties (`-webkit-*`),
+ * CSS custom properties (`$name`), and color tokens (`#name`).
+ * Unlike StylesIndexSignature, does NOT allow sub-element selectors (recipes are flat).
+ */
+type RecipeIndexSignature = Record<string, StyleValue<string | number | boolean | undefined> | StyleValueStateMap<string | number | boolean | undefined>>;
+/**
+ * Style type for recipe definitions.
+ * Like StylesWithoutSelectors but also allows `@keyframes`, `@property`,
+ * local predefined states, and vendor-prefixed CSS properties.
+ * Excludes `recipe` to prevent recursive references.
+ */
+type RecipeStyles = StylesWithoutSelectors & RecipeIndexSignature & {
+  '@keyframes'?: StylesInterface['@keyframes'];
+  '@property'?: StylesInterface['@property'];
+  '@font-face'?: StylesInterface['@font-face'];
+  '@counter-style'?: StylesInterface['@counter-style'];
+  '@function'?: StylesInterface['@function'];
+};
+/** Special properties that are not regular style values */
+interface SpecialStyleProperties {
+  '@keyframes'?: StylesInterface['@keyframes'];
+  '@property'?: StylesInterface['@property'];
+  '@font-face'?: StylesInterface['@font-face'];
+  '@counter-style'?: StylesInterface['@counter-style'];
+  '@function'?: StylesInterface['@function'];
+  recipe?: StylesInterface['recipe'];
+}
+/** Index signature for arbitrary style keys (sub-elements, CSS variables, etc.) */
+interface StylesIndexSignature {
+  [key: string]: StyleValue<string | number | boolean | undefined> | StyleValueStateMap<string | number | boolean | undefined> | Styles | false | StylesInterface['@keyframes'] | StylesInterface['@property'] | StylesInterface['@font-face'] | StylesInterface['@counter-style'] | StylesInterface['@function'];
+  /**
+   * Selector combinator: `undefined` (descendant, default), `'>'` (child), `'+'` (adjacent), `'~'` (sibling).
+   * Can chain with capitalized names: `'> Body > Row >'`. Spaces required around combinators.
+   */
+  $?: string;
+}
+type Styles = StylesWithoutSelectors & SpecialStyleProperties & StylesIndexSignature;
+/**
+ * Value type for design tokens passed to `configure({ tokens })`.
+ * Can be a direct value or a state map for responsive/theme-aware tokens.
+ */
+type ConfigTokenValue = string | number | boolean | Record<string, string | number | boolean | undefined | null | '@inherit'>;
+/**
+ * Design tokens injected as CSS custom properties on `:root`.
+ * Keys must start with `$` (value tokens) or `#` (color tokens).
+ *
+ * - `$name` keys become `--name` CSS custom properties
+ * - `#name` keys become `--name-color` properties
+ */
+type ConfigTokens = Record<`$${string}` | `#${string}`, ConfigTokenValue>;
+//#endregion
+//#region src/pipeline/conditions.d.ts
+/**
+ * ConditionNode Types and Helpers
+ *
+ * Core data structures for representing style conditions as an abstract syntax tree.
+ * Used throughout the pipeline for parsing, simplification, and CSS generation.
+ */
+/**
+ * Base interface for all state conditions (leaf nodes)
+ */
+interface BaseStateCondition {
+  kind: 'state';
+  negated: boolean;
+  raw: string;
+  uniqueId: string;
+}
+/**
+ * Modifier condition: [data-attr] or [data-attr="value"]
+ */
+interface ModifierCondition extends BaseStateCondition {
+  type: 'modifier';
+  attribute: string;
+  value?: string;
+  operator?: '=' | '^=' | '$=' | '*=';
+}
+/**
+ * Pseudo-class condition: :hover, :focus-visible
+ */
+interface PseudoCondition extends BaseStateCondition {
+  type: 'pseudo';
+  pseudo: string;
+}
+/**
+ * Numeric bound for dimension queries
+ */
+interface NumericBound {
+  value: string;
+  valueNumeric: number | null;
+  inclusive: boolean;
+}
+/**
+ * Media query condition
+ */
+interface MediaCondition extends BaseStateCondition {
+  type: 'media';
+  subtype: 'dimension' | 'feature' | 'type';
+  dimension?: 'width' | 'height' | 'inline-size' | 'block-size';
+  lowerBound?: NumericBound;
+  upperBound?: NumericBound;
+  feature?: string;
+  featureValue?: string;
+  mediaType?: 'print' | 'screen' | 'all' | 'speech';
+}
+/**
+ * Container query condition
+ */
+interface ContainerCondition extends BaseStateCondition {
+  type: 'container';
+  subtype: 'dimension' | 'style' | 'raw';
+  containerName?: string;
+  dimension?: 'width' | 'height' | 'inline-size' | 'block-size';
+  lowerBound?: NumericBound;
+  upperBound?: NumericBound;
+  property?: string;
+  propertyValue?: string;
+  rawCondition?: string;
+}
+/**
+ * Root state condition: @root(theme=dark)
+ */
+interface RootCondition extends BaseStateCondition {
+  type: 'root';
+  innerCondition: ConditionNode;
+}
+/**
+ * Parent state condition: @parent(hovered), @parent(theme=dark, >)
+ */
+interface ParentCondition extends BaseStateCondition {
+  type: 'parent';
+  innerCondition: ConditionNode;
+  direct: boolean;
+}
+/**
+ * Own state condition: @own(hovered)
+ */
+interface OwnCondition extends BaseStateCondition {
+  type: 'own';
+  innerCondition: ConditionNode;
+}
+/**
+ * Starting style condition: @starting
+ */
+interface StartingCondition extends BaseStateCondition {
+  type: 'starting';
+}
+/**
+ * Supports query condition: @supports(display: grid), @supports($, :has(*))
+ */
+interface SupportsCondition extends BaseStateCondition {
+  type: 'supports';
+  subtype: 'feature' | 'selector';
+  condition: string;
+}
+/**
+ * Union of all state condition types
+ */
+type StateCondition = ModifierCondition | PseudoCondition | MediaCondition | ContainerCondition | RootCondition | ParentCondition | OwnCondition | StartingCondition | SupportsCondition;
+/**
+ * Compound node: combines conditions with AND/OR
+ */
+interface CompoundCondition {
+  kind: 'compound';
+  operator: 'AND' | 'OR';
+  children: ConditionNode[];
+}
+/**
+ * True condition (matches everything)
+ */
+interface TrueCondition {
+  kind: 'true';
+}
+/**
+ * False condition (matches nothing - skip this rule)
+ */
+interface FalseCondition {
+  kind: 'false';
+}
+/**
+ * Union of all condition node types
+ */
+type ConditionNode = StateCondition | CompoundCondition | TrueCondition | FalseCondition;
+//#endregion
+//#region src/states/index.d.ts
+/**
+ * Parsed advanced state information
+ */
+interface ParsedAdvancedState {
+  type: 'media' | 'container' | 'root' | 'parent' | 'own' | 'starting' | 'predefined' | 'modifier';
+  condition: string;
+  containerName?: string;
+  raw: string;
+  mediaType?: string;
+}
+/**
+ * Context for state parsing operations
+ */
+interface StateParserContext {
+  localPredefinedStates: Record<string, string>;
+  globalPredefinedStates: Record<string, string>;
+  isSubElement?: boolean;
+}
+/**
+ * At-rule context for CSS generation
+ */
+interface AtRuleContext {
+  media?: string[];
+  container?: {
+    name?: string;
+    condition: string;
+  }[];
+  startingStyle?: boolean;
+  rootStates?: string[];
+  negatedRootStates?: string[];
+}
+/**
+ * Configure global predefined states
+ */
+declare function setGlobalPredefinedStates(states: Record<string, string>): void;
+/**
+ * Get global predefined states
+ */
+declare function getGlobalPredefinedStates(): Record<string, string>;
+/**
+ * Create a state parser context from styles
+ */
+declare function createStateParserContext(styles?: Styles, isSubElement?: boolean): StateParserContext;
+//#endregion
+//#region src/pipeline/parseStateKey.d.ts
+interface ParseStateKeyOptions {
+  context?: StateParserContext;
+  isSubElement?: boolean;
+}
+/**
+ * Parse a state key string into a ConditionNode
+ */
+declare function parseStateKey(stateKey: string, options?: ParseStateKeyOptions): ConditionNode;
+//#endregion
+//#region src/pipeline/index.d.ts
+/**
+ * Matches the old StyleResult interface for backward compatibility
+ */
+interface StyleResult {
+  selector: string;
+  declarations: string;
+  atRules?: string[];
+  needsClassName?: boolean;
+  rootPrefix?: string;
+  /** When true, declarations are wrapped in @starting-style { ... } inside the selector rule */
+  startingStyle?: boolean;
+}
+/**
+ * Matches the old RenderResult interface for backward compatibility
+ */
+interface RenderResult {
+  rules: StyleResult[];
+  className?: string;
+}
+/**
+ * Check if a key is a CSS selector
+ */
+declare function isSelector(key: string): boolean;
+/**
+ * Options for renderStyles when using direct selector mode.
+ */
+interface RenderStylesOptions {
+  /**
+   * Whether to double the class selector for increased specificity.
+   * When true, `.myClass` becomes `.myClass.myClass` for higher specificity.
+   *
+   * @default false - User-provided selectors are not doubled.
+   *
+   * Note: This only applies when a classNameOrSelector is provided.
+   * When renderStyles returns RenderResult with needsClassName=true,
+   * the injector handles doubling automatically.
+   */
+  doubleSelector?: boolean;
+}
+/**
+ * Render styles to CSS rules.
+ *
+ * When called without classNameOrSelector, returns RenderResult with needsClassName=true.
+ * When called with a selector/className string, returns StyleResult[] for direct injection.
+ */
+declare function renderStyles(styles?: Styles, classNameOrSelector?: undefined, options?: undefined, pipelineCacheKey?: string): RenderResult;
+declare function renderStyles(styles: Styles | undefined, classNameOrSelector: string, options?: RenderStylesOptions): StyleResult[];
+//#endregion
+export { StyleParser as $, ParsedColor as A, StyleRule as At, StyleValueStateMap as B, SuffixForSelector as C, PropertyDefinition as Ct, CSSMap as D, RuleInfo as Dt, AnyStyleHandler as E, RootRegistry as Et, StyleHandlerProps as F, resetStyleBatch as Ft, parseColor as G, getGlobalParser as H, StyleHandlerResult as I, getNamedColorHex as J, parseStyle as K, StyleMap as L, ResolvedStyleValue as M, QueuedWrite as Mt, StyleHandler as N, flushStyles as Nt, CUSTOM_UNITS as O, SheetInfo as Ot, StyleHandlerDefinition as P, hasPendingStyleWrites as Pt, strToRgb as Q, StylePropValue as R, StylesWithoutSelectors as S, KeyframesSteps as St, TastyPresetNames as T, RawCSSResult as Tt, getGlobalPredefinedTokens as U, filterMods as V, normalizeColorTokenValue as W, hexToRgb as X, getRgbValuesFromRgbaString as Y, hslToRgbValues as Z, NotSelector as _, InjectResult as _t, ParseStateKeyOptions as a, CSSProperties as at, Styles as b, KeyframesInfo as bt, ParsedAdvancedState as c, DisposeFunction as ct, getGlobalPredefinedStates as d, FunctionDefinition as dt, ParserOptions as et, setGlobalPredefinedStates as f, FunctionParameter as ft, NoType as g, InjectOptions as gt, ConfigTokens as h, GlobalInjectResult as ht, renderStyles as i, UnitHandler as it, RawStyleHandler as j, StyleUsage as jt, DIRECTIONS as k, StyleInjectorConfig as kt, StateParserContext as l, FontFaceDescriptors as lt, ConfigTokenValue as m, GCOptions as mt, StyleResult as n, StyleDetails as nt, parseStateKey as o, CacheMetrics as ot, ConditionNode as p, GCConfig as pt, stringifyStyles as q, isSelector as r, StyleDetailsPart as rt, AtRuleContext as s, CounterStyleDescriptors as st, RenderResult as t, ProcessedStyle as tt, createStateParserContext as u, FontFaceInput as ut, RecipeStyles as v, InjectionMode as vt, TastyNamedColors as w, PropertyOptions as wt, StylesInterface as x, KeyframesResult as xt, Selector as y, KeyframesCacheEntry as yt, StyleValue as z };
+//# sourceMappingURL=index-BcsaHo8x.d.ts.map