@tenphi/tasty 0.0.0-snapshot.95ec060 → 0.0.0-snapshot.aef860d

package/README.md

@@ -29,7 +29,7 @@ That guarantee unlocks a concise, CSS-like DSL where design tokens, custom units
 - **CSS properties as normal component props** — `styleProps` lets you expose selected styles as typed React props. Use `<Button placeSelf="end">` or `<Space flow="row" gap="2x">` without extra wrappers, utility classes, or `styles` overrides. The same props also accept state maps, so responsive values work with the same API. See [CSS properties as props](#css-properties-as-props).
 - **Design-system native** — Color tokens (`#primary`), spacing units (`2x`), typography presets (`h1`, `t2`), border radius (`1r`), and recipes are first-class primitives, not afterthoughts. See [Configuration](docs/configuration.md).
 - **Near-complete modern CSS coverage** — Media queries, container queries, `@supports`, `:has()`, `@starting-style`, `@property`, `@keyframes`, etc. Some features that don't fit Tasty's component model (such as `@layer` and `!important`) are intentionally omitted, but real-world use cases are covered almost completely.
-- **Runtime or zero-runtime — your call** — Use `tasty()` for dynamic React components with runtime injection, or `tastyStatic()` with the Babel plugin for zero-runtime CSS extraction. Same DSL, same tokens, same output. See [Zero Runtime](docs/tasty-static.md).
+- **Runtime, zero-runtime, or SSR — your call** — Use `tasty()` for dynamic React components with runtime injection, `tastyStatic()` with the Babel plugin for zero-runtime CSS extraction, or enable SSR with zero-cost client hydration for Next.js, Astro, or any React framework (experimental). Same DSL, same tokens, same output.
 - **Only generate what is used** — In runtime mode, Tasty injects CSS on demand for mounted components/variants, so your app avoids shipping style rules for UI states that are never rendered.
 - **Runtime performance that holds at scale** — The runtime path is tested against enterprise-scale applications and tuned with multi-level caching, chunk-level style reuse, style garbage collection, and a dedicated injector.
 - **Composable and extensible by design** — Extend any component's styles with proper merge semantics, and evolve built-in behavior through configuration and plugins.
@@ -192,6 +192,15 @@ Traditional CSS has two structural problems.
 
 First, the **cascade** resolves conflicts by specificity and source order: when multiple selectors match, the one with the highest specificity wins, or — if specificity is equal — the last one in source order wins. That makes styles inherently fragile. Reordering imports, adding a media query, or composing components from different libraries can silently break styling.
 
+A small example makes this tangible. Two rules for a button's background:
+
+```css
+.btn:hover     { background: dodgerblue; }
+.btn[disabled] { background: gray; }
+```
+
+Both selectors have specificity `(0, 1, 1)`. When the button is hovered **and** disabled, both match — and the last rule in source order wins. Swap the two lines and a hovered disabled button silently turns blue instead of gray. This class of bug is invisible in code review because the logic is correct; only the ordering is wrong.
+
 Second, **authoring selectors that capture real-world state logic is fundamentally hard.** A single state like "dark mode" may depend on a root attribute, an OS preference, or both — each branch needing its own selector, proper negation of competing branches, and correct `@media` nesting. The example below shows the CSS you'd write by hand for just *one* property with *one* state. Scale that across dozens of properties, then add breakpoints and container queries, and the selector logic quickly becomes unmanageable.
 
 Tasty solves both problems at once: **every state mapping compiles into mutually exclusive selectors.**
@@ -211,7 +220,33 @@ const Text = tasty({
 });
 ```
 
-If `@dark` expands to `@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))`, Tasty generates:
+If `@dark` expands to `@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))`, try writing the CSS by hand. A first attempt might look like this:
+
+```css
+/* First attempt — the @media branch is too broad */
+.t0 { color: var(--text-color); }
+:root[data-schema="dark"] .t0 { color: var(--text-on-dark-color); }
+@media (prefers-color-scheme: dark) {
+  .t0 { color: var(--text-on-dark-color); }
+}
+```
+
+The `@media` branch fires even when `data-schema="light"` is explicitly set. Fix that:
+
+```css
+/* Second attempt — @media is scoped, but the default is still too broad */
+.t0 { color: var(--text-color); }
+:root[data-schema="dark"] .t0 { color: var(--text-on-dark-color); }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-schema]) .t0 { color: var(--text-on-dark-color); }
+}
+```
+
+Better — but the bare `.t0` default still matches unconditionally. It matches in dark mode, it matches when `data-schema="dark"` is set, and it can beat the attribute selector by source order if another rule re-declares it later. There is no selector that says "apply this default only when none of the dark branches win."
+
+This is just *one* property with *one* state, and getting it right already takes multiple iterations. The correct selectors require negating every other branch — which is exactly what Tasty generates automatically:
+
+Tasty generates the correct version automatically:
 
 ```css
 /* Branch 1: Explicit dark schema */
@@ -243,6 +278,8 @@ Every rule is guarded by the negation of higher-priority rules. No two rules can
 
 By absorbing selector complexity, Tasty makes advanced CSS patterns practical again — nested container queries, multi-condition `@supports` gates, and combined root-state/media branches. You stay in pure CSS instead of relying on JavaScript workarounds, so the browser can optimize layout, painting, and transitions natively. Tasty doesn't limit CSS; it unlocks its full potential by removing the complexity that held teams back.
 
+[Try it in the Tasty Playground →](https://cube-ui-kit.vercel.app/?path=/story/getting-started-tasty-playground--playground)
+
 ## Capabilities
 
 ### Design Tokens and Custom Units
@@ -364,11 +401,11 @@ const ProfileCard = tasty({
 
 Use `/` to post-apply recipes after local styles when you need recipe states/styles to win the final merge order. Use `none` to skip base recipes: `recipe: 'none / disabled'`.
 
-### Keyframes and `@property`
+### Auto-Inferred `@property`
 
-CSS cannot animate or transition custom properties by default — the browser doesn't know their type. The [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) at-rule solves this by declaring a property's syntax (e.g. `<number>`, `<color>`), which unlocks smooth interpolation in transitions and keyframe animations.
+CSS custom properties do not animate smoothly by default because the browser does not know how to interpolate their values. The [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) at-rule fixes that by declaring a property's syntax, such as `<number>` or `<color>`.
 
-Tasty automatically infers the type from concrete values and registers `@property` for you — no manual declarations needed:
+In Tasty, you usually do not need to declare `@property` manually. When a custom property is assigned a concrete value, Tasty infers the syntax and registers the matching `@property` for you:
 
 ```tsx
 const Pulse = tasty({
@@ -385,9 +422,13 @@ const Pulse = tasty({
 });
 ```
 
-Here `$pulse-scale: 1` is detected as `<number>`, so `@property --pulse-scale` is injected automatically and the keyframe animation works. Supported types: `<number>`, `<length>`, `<percentage>`, `<angle>`, `<time>`, and `<color>`. This also works across `var()` chains — if `$a` references `var(--b)`, the type propagates once `--b` is resolved.
+Here, `$pulse-scale: 1` is inferred as `<number>`, so Tasty injects `@property --pulse-scale` automatically before using it in the animation. Numeric types (`<number>`, `<length>`, `<percentage>`, `<angle>`, `<time>`) are inferred from values; `<color>` is inferred from the `#name` token convention.
+
+If you prefer full manual control, disable auto-inference globally with `configure({ autoPropertyTypes: false })`.
 
-Use explicit `@properties` only when you need non-default settings (e.g. `inherits: false`):
+### Explicit `@properties`
+
+Declare `@properties` yourself only when you need to override the defaults, for example to set `inherits: false` or provide a custom `initialValue`:
 
 ```tsx
 '@properties': {
@@ -395,8 +436,6 @@ Use explicit `@properties` only when you need non-default settings (e.g. `inheri
 },
 ```
 
-Disable auto-inference globally with `configure({ autoPropertyTypes: false })`.
-
 ### React Hooks
 
 For cases where you don't need a full component:
@@ -406,8 +445,8 @@ import { useStyles, useGlobalStyles, useRawCSS } from '@tenphi/tasty';
 
 function App() {
   const { className } = useStyles({ padding: '2x', fill: '#surface' });
-  useGlobalStyles(':root', { '#primary': 'purple', '$gap': '8px' });
-  useRawCSS('body { margin: 0; }');
+  useGlobalStyles('body', { margin: '0' });
+  useRawCSS('@font-face { font-family: "Custom"; src: url(...); }');
 
   return <main className={className}>...</main>;
 }
@@ -474,6 +513,48 @@ If you choose the runtime approach, performance is usually a non-issue in practi
 - A dedicated style injector minimizes DOM/style-tag overhead.
 - This approach is validated in enterprise-scale apps where runtime styling overhead is not noticeable in normal UI flows.
 
+### Server-Side Rendering (Experimental)
+
+SSR with zero-cost client hydration. Existing `tasty()` components work unchanged — SSR is opt-in and requires no per-component modifications. Supports Next.js (App Router with streaming), Astro (middleware + islands), and any React-based framework via the core API. Requires React 19+.
+
+**Next.js setup:**
+
+```tsx
+// app/tasty-registry.tsx
+'use client';
+
+import { TastyRegistry } from '@tenphi/tasty/ssr/next';
+
+export default function TastyStyleRegistry({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <TastyRegistry>{children}</TastyRegistry>;
+}
+```
+
+```tsx
+// app/layout.tsx
+import TastyStyleRegistry from './tasty-registry';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html>
+      <body>
+        <TastyStyleRegistry>{children}</TastyStyleRegistry>
+      </body>
+    </html>
+  );
+}
+```
+
+See the [full SSR guide](docs/ssr.md) for Astro integration, streaming SSR, generic framework usage, and the complete API reference.
+
 ## Entry Points
 
 | Import | Description | Platform |
@@ -484,6 +565,9 @@ If you choose the runtime approach, performance is usually a non-issue in practi
 | `@tenphi/tasty/babel-plugin` | Babel plugin for zero-runtime CSS extraction | Node |
 | `@tenphi/tasty/zero` | Programmatic extraction API | Node |
 | `@tenphi/tasty/next` | Next.js integration wrapper | Node |
+| `@tenphi/tasty/ssr` | Core SSR API (collector, context, hydration) | Node |
+| `@tenphi/tasty/ssr/next` | Next.js App Router SSR integration | Node |
+| `@tenphi/tasty/ssr/astro` | Astro middleware + auto-hydration | Node / Browser |
 
 ## Ecosystem
 
@@ -526,19 +610,57 @@ Syntax highlighting for Tasty styles in TypeScript, TSX, JavaScript, and JSX. Hi
   <img src="assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example">
 </p>
 
-### [Cube UI Kit](https://github.com/cube-js/cube-ui-kit)
+## Built with Tasty
+
+### [tasty.style](https://tasty.style) ([source](https://github.com/tenphi/tasty.style))
+
+The official Tasty documentation and landing page — itself built entirely with Tasty. A showcase for zero-runtime styling via `tastyStatic`, SSR with Next.js, and OKHSL color theming with Glaze.
+
+### [Cube Cloud](https://cube.dev/)
+
+Enterprise universal semantic layer platform by Cube Dev, Inc. Cube Cloud unifies data modeling, caching, access control, and APIs (REST, GraphQL, SQL, AI) for analytics at scale. Tasty has powered its frontend for over 5 years in production.
+
+### [Cube Cloud for Excel and Google Sheets](https://cube.dev/)
+
+A single spreadsheet add-in deployed to both [Microsoft Excel](https://marketplace.microsoft.com/en-us/product/office/WA200008486) and [Google Sheets](https://workspace.google.com/u/0/marketplace/app/cube_cloud_for_sheets/641460343379). Connects spreadsheets to any cloud data platform (BigQuery, Databricks, Snowflake, Redshift, and more) via Cube Cloud's universal semantic layer.
+
+### [Cube UI Kit](https://github.com/cube-js/cube-ui-kit) ([storybook](https://cube-ui-kit.vercel.app/))
 
 Open-source React UI kit built on Tasty + React Aria. 100+ production components proving Tasty works at design-system scale. A reference implementation and a ready-to-use component library.
 
 ## Documentation
 
-- **[Usage Guide](docs/usage.md)** — Runtime styling: component creation, state mappings, sub-elements, variants, and hooks
+### Start here
+
+- **[Getting Started](docs/getting-started.md)** — Installation, first component, configuration, ESLint plugin setup, editor tooling, and rendering mode decision tree
+- **[Methodology](docs/methodology.md)** — The recommended patterns for structuring Tasty components: root + sub-elements, styleProps, tokens, styles vs style, wrapping and extension
+
+### Guides
+
+- **[Building a Design System](docs/design-system.md)** — Practical guide to building a DS layer: token vocabulary, state aliases, recipes, primitives, compound components, override contracts
+- **[Adoption Guide](docs/adoption.md)** — Where Tasty sits in the stack, who should adopt it, what you define yourself, and how to introduce it incrementally into an existing design system
+
+### Reference
+
+- **[Style DSL](docs/dsl.md)** — The Tasty style language: state maps, tokens, units, color syntax, extending semantics, recipes, keyframes, and @property
+- **[Runtime API](docs/runtime.md)** — React-specific API: `tasty()` factory, component props, variants, sub-elements, and hooks
 - **[Configuration](docs/configuration.md)** — Global configuration: tokens, recipes, custom units, style handlers, and TypeScript extensions
 - **[Style Properties](docs/styles.md)** — Complete reference for all enhanced style properties: syntax, values, modifiers, and recommendations
+
+### Rendering modes
+
 - **[Zero Runtime (tastyStatic)](docs/tasty-static.md)** — Build-time static styling: Babel plugin setup, Next.js integration, and static style patterns
+- **[Server-Side Rendering](docs/ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks: streaming support, cache hydration, and troubleshooting
+
+### Internals
+
 - **[Style Injector](docs/injector.md)** — Internal CSS injection engine: `inject()`, `injectGlobal()`, `injectRawCSS()`, `keyframes()`, deduplication, reference counting, cleanup, SSR support, and Shadow DOM
 - **[Debug Utilities](docs/debug.md)** — Runtime CSS inspection via `tastyDebug`: CSS extraction, element inspection, cache metrics, chunk breakdown, and performance monitoring
 
+### Context
+
+- **[Comparison](docs/comparison.md)** — How Tasty compares to Tailwind, Panda CSS, vanilla-extract, StyleX, Stitches, and Emotion: positioning, trade-offs, and when each tool fits best
+
 ## License
 
 [MIT](LICENSE)

package/dist/chunks/definitions.js

@@ -130,8 +130,7 @@ const DISPLAY_CHUNK_STYLES = [
 	"whiteSpace",
 	"flow",
 	"gap",
-	"scrollbar",
-	"styledScrollbar"
+	"scrollbar"
 ];
 /**
 * Layout chunk - flex/grid alignment and grid templates

package/dist/chunks/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","names":[],"sources":["../../src/chunks/definitions.ts"],"sourcesContent":["/**\n * Style chunk definitions for CSS chunking optimization.\n *\n * Styles are grouped into chunks based on:\n * 1. Handler dependencies - styles that share a handler MUST be in the same chunk\n * 2. Logical grouping - related styles grouped for better cache reuse\n *\n * See STYLE_CHUNKING_SPEC.md for detailed rationale.\n *\n * ============================================================================\n * ⚠️  CRITICAL ARCHITECTURAL CONSTRAINT: NO CROSS-CHUNK HANDLER DEPENDENCIES\n * ============================================================================\n *\n * Style handlers declare their dependencies via `__lookupStyles` array.\n * This creates a dependency graph where handlers read multiple style props.\n *\n * **ALL styles in a handler's `__lookupStyles` MUST be in the SAME chunk.**\n *\n * Why this matters:\n * 1. Each chunk computes a cache key from ONLY its own style values\n * 2. If a handler reads a style from another chunk, that value isn't in the cache key\n * 3. Changing the cross-chunk style won't invalidate this chunk's cache\n * 4. Result: stale CSS output or incorrect cache hits\n *\n * Example of a violation:\n * ```\n * // flowStyle.__lookupStyles = ['display', 'flow']\n * // If 'display' is in DISPLAY chunk and 'flow' is in LAYOUT chunk:\n * // - User sets { display: 'grid', flow: 'column' }\n * // - LAYOUT chunk caches CSS with flow=column, display=grid\n * // - User changes to { display: 'flex', flow: 'column' }\n * // - LAYOUT chunk cache key unchanged (only has 'flow')\n * // - Returns stale CSS computed with display=grid!\n * ```\n *\n * Before adding/moving styles, verify:\n * 1. Find all handlers that use this style (grep for the style name in __lookupStyles)\n * 2. Ensure ALL styles from each handler's __lookupStyles are in the same chunk\n * ============================================================================\n */\n\nimport { isSelector } from '../pipeline';\n\n// ============================================================================\n// Chunk Style Lists\n// ============================================================================\n\n/**\n * Appearance chunk - visual styling with independent handlers\n */\nexport const APPEARANCE_CHUNK_STYLES = [\n  'fill', // fillStyle (independent)\n  'color', // colorStyle (independent)\n  'opacity', // independent\n  'border', // borderStyle (independent)\n  'radius', // radiusStyle (independent)\n  'outline', // outlineStyle: outline ↔ outlineOffset\n  'outlineOffset', // outlineStyle: outline ↔ outlineOffset\n  'shadow', // shadowStyle (independent)\n  'fade', // fadeStyle (independent)\n] as const;\n\n/**\n * Font chunk - typography styles\n *\n * Handler dependencies (all styles in each handler MUST stay in this chunk):\n * ⚠️ presetStyle: preset, fontSize, lineHeight, letterSpacing, textTransform,\n *    fontWeight, fontStyle, font\n */\nexport const FONT_CHUNK_STYLES = [\n  // All from presetStyle handler - MUST stay together\n  'preset',\n  'font',\n  'fontWeight',\n  'fontStyle',\n  'fontSize',\n  'lineHeight',\n  'letterSpacing',\n  'textTransform',\n  // Independent text styles grouped for cohesion\n  'fontFamily', // independent alias (logical grouping with font styles)\n  'textAlign',\n  'textDecoration',\n  'wordBreak',\n  'wordWrap',\n  'boldFontWeight',\n] as const;\n\n/**\n * Dimension chunk - sizing and spacing\n *\n * Handler dependencies (all styles in each handler MUST stay in this chunk):\n * ⚠️ paddingStyle: padding, paddingTop/Right/Bottom/Left, paddingBlock/Inline\n * ⚠️ marginStyle: margin, marginTop/Right/Bottom/Left, marginBlock/Inline\n * ⚠️ widthStyle: width, minWidth, maxWidth\n * ⚠️ heightStyle: height, minHeight, maxHeight\n */\nexport const DIMENSION_CHUNK_STYLES = [\n  // All from paddingStyle handler - MUST stay together\n  'padding',\n  'paddingTop',\n  'paddingRight',\n  'paddingBottom',\n  'paddingLeft',\n  'paddingBlock',\n  'paddingInline',\n  // All from marginStyle handler - MUST stay together\n  'margin',\n  'marginTop',\n  'marginRight',\n  'marginBottom',\n  'marginLeft',\n  'marginBlock',\n  'marginInline',\n  // widthStyle handler - MUST stay together\n  'width',\n  'minWidth',\n  'maxWidth',\n  // heightStyle handler - MUST stay together\n  'height',\n  'minHeight',\n  'maxHeight',\n  'flexBasis',\n  'flexGrow',\n  'flexShrink',\n  'flex',\n] as const;\n\n/**\n * Display chunk - display mode, layout flow, text overflow, and scrollbar\n *\n * Handler dependencies (all styles in each handler MUST stay in this chunk):\n * ⚠️ displayStyle: display, hide, textOverflow, overflow, whiteSpace\n * ⚠️ flowStyle: display, flow\n * ⚠️ gapStyle: display, flow, gap\n * ⚠️ scrollbarStyle: scrollbar, overflow\n */\nexport const DISPLAY_CHUNK_STYLES = [\n  // displayStyle handler\n  'display',\n  'hide',\n  'textOverflow',\n  'overflow', // also used by scrollbarStyle\n  'whiteSpace',\n  // flowStyle handler (requires display)\n  'flow',\n  // gapStyle handler (requires display, flow)\n  'gap',\n  // scrollbarStyle handler (requires overflow)\n  'scrollbar',\n  'styledScrollbar', // styledScrollbarStyle (deprecated)\n] as const;\n\n/**\n * Layout chunk - flex/grid alignment and grid templates\n *\n * Note: flow and gap are in DISPLAY chunk due to handler dependencies\n * (flowStyle and gapStyle both require 'display' prop).\n */\nexport const LAYOUT_CHUNK_STYLES = [\n  // Alignment styles (all independent handlers)\n  'placeItems',\n  'placeContent',\n  'alignItems',\n  'alignContent',\n  'justifyItems',\n  'justifyContent',\n  'align', // alignStyle (independent)\n  'justify', // justifyStyle (independent)\n  'place', // placeStyle (independent)\n  'columnGap',\n  'rowGap',\n  // Grid template styles\n  'gridColumns',\n  'gridRows',\n  'gridTemplate',\n  'gridAreas',\n  'gridAutoFlow',\n  'gridAutoColumns',\n  'gridAutoRows',\n] as const;\n\n/**\n * Position chunk - element positioning\n *\n * Handler dependencies (all styles in each handler MUST stay in this chunk):\n * ⚠️ insetStyle: inset, insetBlock, insetInline, top, right, bottom, left\n */\nexport const POSITION_CHUNK_STYLES = [\n  'position',\n  // All from insetStyle handler - MUST stay together\n  'inset',\n  'insetBlock',\n  'insetInline',\n  'top',\n  'right',\n  'bottom',\n  'left',\n  'zIndex',\n  'gridArea',\n  'gridColumn',\n  'gridRow',\n  'order',\n  'placeSelf',\n  'alignSelf',\n  'justifySelf',\n  'transform',\n  'transition',\n  'animation',\n] as const;\n\n// ============================================================================\n// Chunk Names\n// ============================================================================\n\nexport const CHUNK_NAMES = {\n  /** Special chunk for styles that cannot be split (e.g., @starting-style) */\n  COMBINED: 'combined',\n  SUBCOMPONENTS: 'subcomponents',\n  APPEARANCE: 'appearance',\n  FONT: 'font',\n  DIMENSION: 'dimension',\n  DISPLAY: 'display',\n  LAYOUT: 'layout',\n  POSITION: 'position',\n  MISC: 'misc',\n} as const;\n\nexport type ChunkName = (typeof CHUNK_NAMES)[keyof typeof CHUNK_NAMES];\n\n// ============================================================================\n// Style-to-Chunk Lookup Map (O(1) categorization)\n// ============================================================================\n\n/**\n * Pre-computed map for O(1) style-to-chunk lookup.\n * Built once at module load time.\n */\nexport const STYLE_TO_CHUNK = new Map<string, ChunkName>();\n\n// Populate the lookup map\nfunction populateStyleToChunkMap() {\n  for (const style of APPEARANCE_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.APPEARANCE);\n  }\n  for (const style of FONT_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.FONT);\n  }\n  for (const style of DIMENSION_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.DIMENSION);\n  }\n  for (const style of DISPLAY_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.DISPLAY);\n  }\n  for (const style of LAYOUT_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.LAYOUT);\n  }\n  for (const style of POSITION_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.POSITION);\n  }\n}\n\n// Initialize at module load\npopulateStyleToChunkMap();\n\n// ============================================================================\n// Chunk Priority Order\n// ============================================================================\n\n/**\n * Chunk processing order. This ensures deterministic className allocation\n * regardless of style key order in the input.\n */\nconst CHUNK_ORDER: readonly string[] = [\n  CHUNK_NAMES.APPEARANCE,\n  CHUNK_NAMES.FONT,\n  CHUNK_NAMES.DIMENSION,\n  CHUNK_NAMES.DISPLAY,\n  CHUNK_NAMES.LAYOUT,\n  CHUNK_NAMES.POSITION,\n  CHUNK_NAMES.MISC,\n  CHUNK_NAMES.SUBCOMPONENTS,\n] as const;\n\n/**\n * Map from chunk name to its priority index for sorting.\n */\nconst _CHUNK_PRIORITY = new Map<string, number>(\n  CHUNK_ORDER.map((name, index) => [name, index]),\n);\n\n// ============================================================================\n// Chunk Info Interface\n// ============================================================================\n\nexport interface ChunkInfo {\n  /** Name of the chunk */\n  name: ChunkName | string;\n  /** Style keys belonging to this chunk */\n  styleKeys: string[];\n}\n\n// ============================================================================\n// Style Categorization\n// ============================================================================\n\n/**\n * Categorize style keys into chunks.\n *\n * Returns chunks in a deterministic order (by CHUNK_ORDER) regardless\n * of the order of keys in the input styles object.\n *\n * @param styles - The styles object to categorize\n * @returns Map of chunk name to array of style keys in that chunk (in priority order)\n */\nexport function categorizeStyleKeys(\n  styles: Record<string, unknown>,\n): Map<string, string[]> {\n  // First pass: collect keys into chunks (unordered)\n  const chunkData: Record<string, string[]> = {};\n  const keys = Object.keys(styles);\n\n  for (const key of keys) {\n    // Skip the $ helper key (used for selector combinators)\n    // Skip @keyframes and @properties (processed separately in useStyles)\n    // Skip recipe (resolved before pipeline by resolveRecipes)\n    if (\n      key === '$' ||\n      key === '@keyframes' ||\n      key === '@properties' ||\n      key === 'recipe'\n    ) {\n      continue;\n    }\n\n    if (isSelector(key)) {\n      // All selectors go into the subcomponents chunk\n      if (!chunkData[CHUNK_NAMES.SUBCOMPONENTS]) {\n        chunkData[CHUNK_NAMES.SUBCOMPONENTS] = [];\n      }\n      chunkData[CHUNK_NAMES.SUBCOMPONENTS].push(key);\n    } else {\n      // Look up the chunk for this style, default to misc\n      const chunkName = STYLE_TO_CHUNK.get(key) ?? CHUNK_NAMES.MISC;\n      if (!chunkData[chunkName]) {\n        chunkData[chunkName] = [];\n      }\n      chunkData[chunkName].push(key);\n    }\n  }\n\n  // Second pass: build ordered Map based on CHUNK_ORDER\n  const orderedChunks = new Map<string, string[]>();\n\n  // Add chunks in priority order\n  for (const chunkName of CHUNK_ORDER) {\n    if (chunkData[chunkName] && chunkData[chunkName].length > 0) {\n      // Sort keys within chunk for consistent cache key generation\n      orderedChunks.set(chunkName, chunkData[chunkName].sort());\n    }\n  }\n\n  // Handle any unknown chunks (shouldn't happen, but be defensive)\n  for (const chunkName of Object.keys(chunkData)) {\n    if (!orderedChunks.has(chunkName)) {\n      orderedChunks.set(chunkName, chunkData[chunkName].sort());\n    }\n  }\n\n  return orderedChunks;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,MAAa,0BAA0B;CACrC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,MAAa,oBAAoB;CAE/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;AAWD,MAAa,yBAAyB;CAEpC;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;AAWD,MAAa,uBAAuB;CAElC;CACA;CACA;CACA;CACA;CAEA;CAEA;CAEA;CACA;CACD;;;;;;;AAQD,MAAa,sBAAsB;CAEjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;AAQD,MAAa,wBAAwB;CACnC;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAMD,MAAa,cAAc;CAEzB,UAAU;CACV,eAAe;CACf,YAAY;CACZ,MAAM;CACN,WAAW;CACX,SAAS;CACT,QAAQ;CACR,UAAU;CACV,MAAM;CACP;;;;;AAYD,MAAa,iCAAiB,IAAI,KAAwB;AAG1D,SAAS,0BAA0B;AACjC,MAAK,MAAM,SAAS,wBAClB,gBAAe,IAAI,OAAO,YAAY,WAAW;AAEnD,MAAK,MAAM,SAAS,kBAClB,gBAAe,IAAI,OAAO,YAAY,KAAK;AAE7C,MAAK,MAAM,SAAS,uBAClB,gBAAe,IAAI,OAAO,YAAY,UAAU;AAElD,MAAK,MAAM,SAAS,qBAClB,gBAAe,IAAI,OAAO,YAAY,QAAQ;AAEhD,MAAK,MAAM,SAAS,oBAClB,gBAAe,IAAI,OAAO,YAAY,OAAO;AAE/C,MAAK,MAAM,SAAS,sBAClB,gBAAe,IAAI,OAAO,YAAY,SAAS;;AAKnD,yBAAyB;;;;;AAUzB,MAAM,cAAiC;CACrC,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACb;AAKuB,IAAI,IAC1B,YAAY,KAAK,MAAM,UAAU,CAAC,MAAM,MAAM,CAAC,CAChD;;;;;;;;;;AA0BD,SAAgB,oBACd,QACuB;CAEvB,MAAM,YAAsC,EAAE;CAC9C,MAAM,OAAO,OAAO,KAAK,OAAO;AAEhC,MAAK,MAAM,OAAO,MAAM;AAItB,MACE,QAAQ,OACR,QAAQ,gBACR,QAAQ,iBACR,QAAQ,SAER;AAGF,MAAI,WAAW,IAAI,EAAE;AAEnB,OAAI,CAAC,UAAU,YAAY,eACzB,WAAU,YAAY,iBAAiB,EAAE;AAE3C,aAAU,YAAY,eAAe,KAAK,IAAI;SACzC;GAEL,MAAM,YAAY,eAAe,IAAI,IAAI,IAAI,YAAY;AACzD,OAAI,CAAC,UAAU,WACb,WAAU,aAAa,EAAE;AAE3B,aAAU,WAAW,KAAK,IAAI;;;CAKlC,MAAM,gCAAgB,IAAI,KAAuB;AAGjD,MAAK,MAAM,aAAa,YACtB,KAAI,UAAU,cAAc,UAAU,WAAW,SAAS,EAExD,eAAc,IAAI,WAAW,UAAU,WAAW,MAAM,CAAC;AAK7D,MAAK,MAAM,aAAa,OAAO,KAAK,UAAU,CAC5C,KAAI,CAAC,cAAc,IAAI,UAAU,CAC/B,eAAc,IAAI,WAAW,UAAU,WAAW,MAAM,CAAC;AAI7D,QAAO"}
+{"version":3,"file":"definitions.js","names":[],"sources":["../../src/chunks/definitions.ts"],"sourcesContent":["/**\n * Style chunk definitions for CSS chunking optimization.\n *\n * Styles are grouped into chunks based on:\n * 1. Handler dependencies - styles that share a handler MUST be in the same chunk\n * 2. Logical grouping - related styles grouped for better cache reuse\n *\n * See STYLE_CHUNKING_SPEC.md for detailed rationale.\n *\n * ============================================================================\n * ⚠️  CRITICAL ARCHITECTURAL CONSTRAINT: NO CROSS-CHUNK HANDLER DEPENDENCIES\n * ============================================================================\n *\n * Style handlers declare their dependencies via `__lookupStyles` array.\n * This creates a dependency graph where handlers read multiple style props.\n *\n * **ALL styles in a handler's `__lookupStyles` MUST be in the SAME chunk.**\n *\n * Why this matters:\n * 1. Each chunk computes a cache key from ONLY its own style values\n * 2. If a handler reads a style from another chunk, that value isn't in the cache key\n * 3. Changing the cross-chunk style won't invalidate this chunk's cache\n * 4. Result: stale CSS output or incorrect cache hits\n *\n * Example of a violation:\n * ```\n * // flowStyle.__lookupStyles = ['display', 'flow']\n * // If 'display' is in DISPLAY chunk and 'flow' is in LAYOUT chunk:\n * // - User sets { display: 'grid', flow: 'column' }\n * // - LAYOUT chunk caches CSS with flow=column, display=grid\n * // - User changes to { display: 'flex', flow: 'column' }\n * // - LAYOUT chunk cache key unchanged (only has 'flow')\n * // - Returns stale CSS computed with display=grid!\n * ```\n *\n * Before adding/moving styles, verify:\n * 1. Find all handlers that use this style (grep for the style name in __lookupStyles)\n * 2. Ensure ALL styles from each handler's __lookupStyles are in the same chunk\n * ============================================================================\n */\n\nimport { isSelector } from '../pipeline';\n\n// ============================================================================\n// Chunk Style Lists\n// ============================================================================\n\n/**\n * Appearance chunk - visual styling with independent handlers\n */\nexport const APPEARANCE_CHUNK_STYLES = [\n  'fill', // fillStyle (independent)\n  'color', // colorStyle (independent)\n  'opacity', // independent\n  'border', // borderStyle (independent)\n  'radius', // radiusStyle (independent)\n  'outline', // outlineStyle: outline ↔ outlineOffset\n  'outlineOffset', // outlineStyle: outline ↔ outlineOffset\n  'shadow', // shadowStyle (independent)\n  'fade', // fadeStyle (independent)\n] as const;\n\n/**\n * Font chunk - typography styles\n *\n * Handler dependencies (all styles in each handler MUST stay in this chunk):\n * ⚠️ presetStyle: preset, fontSize, lineHeight, letterSpacing, textTransform,\n *    fontWeight, fontStyle, font\n */\nexport const FONT_CHUNK_STYLES = [\n  // All from presetStyle handler - MUST stay together\n  'preset',\n  'font',\n  'fontWeight',\n  'fontStyle',\n  'fontSize',\n  'lineHeight',\n  'letterSpacing',\n  'textTransform',\n  // Independent text styles grouped for cohesion\n  'fontFamily', // independent alias (logical grouping with font styles)\n  'textAlign',\n  'textDecoration',\n  'wordBreak',\n  'wordWrap',\n  'boldFontWeight',\n] as const;\n\n/**\n * Dimension chunk - sizing and spacing\n *\n * Handler dependencies (all styles in each handler MUST stay in this chunk):\n * ⚠️ paddingStyle: padding, paddingTop/Right/Bottom/Left, paddingBlock/Inline\n * ⚠️ marginStyle: margin, marginTop/Right/Bottom/Left, marginBlock/Inline\n * ⚠️ widthStyle: width, minWidth, maxWidth\n * ⚠️ heightStyle: height, minHeight, maxHeight\n */\nexport const DIMENSION_CHUNK_STYLES = [\n  // All from paddingStyle handler - MUST stay together\n  'padding',\n  'paddingTop',\n  'paddingRight',\n  'paddingBottom',\n  'paddingLeft',\n  'paddingBlock',\n  'paddingInline',\n  // All from marginStyle handler - MUST stay together\n  'margin',\n  'marginTop',\n  'marginRight',\n  'marginBottom',\n  'marginLeft',\n  'marginBlock',\n  'marginInline',\n  // widthStyle handler - MUST stay together\n  'width',\n  'minWidth',\n  'maxWidth',\n  // heightStyle handler - MUST stay together\n  'height',\n  'minHeight',\n  'maxHeight',\n  'flexBasis',\n  'flexGrow',\n  'flexShrink',\n  'flex',\n] as const;\n\n/**\n * Display chunk - display mode, layout flow, text overflow, and scrollbar\n *\n * Handler dependencies (all styles in each handler MUST stay in this chunk):\n * ⚠️ displayStyle: display, hide, textOverflow, overflow, whiteSpace\n * ⚠️ flowStyle: display, flow\n * ⚠️ gapStyle: display, flow, gap\n * ⚠️ scrollbarStyle: scrollbar, overflow\n */\nexport const DISPLAY_CHUNK_STYLES = [\n  // displayStyle handler\n  'display',\n  'hide',\n  'textOverflow',\n  'overflow', // also used by scrollbarStyle\n  'whiteSpace',\n  // flowStyle handler (requires display)\n  'flow',\n  // gapStyle handler (requires display, flow)\n  'gap',\n  // scrollbarStyle handler (requires overflow)\n  'scrollbar',\n] as const;\n\n/**\n * Layout chunk - flex/grid alignment and grid templates\n *\n * Note: flow and gap are in DISPLAY chunk due to handler dependencies\n * (flowStyle and gapStyle both require 'display' prop).\n */\nexport const LAYOUT_CHUNK_STYLES = [\n  // Alignment styles (all independent handlers)\n  'placeItems',\n  'placeContent',\n  'alignItems',\n  'alignContent',\n  'justifyItems',\n  'justifyContent',\n  'align', // alignStyle (independent)\n  'justify', // justifyStyle (independent)\n  'place', // placeStyle (independent)\n  'columnGap',\n  'rowGap',\n  // Grid template styles\n  'gridColumns',\n  'gridRows',\n  'gridTemplate',\n  'gridAreas',\n  'gridAutoFlow',\n  'gridAutoColumns',\n  'gridAutoRows',\n] as const;\n\n/**\n * Position chunk - element positioning\n *\n * Handler dependencies (all styles in each handler MUST stay in this chunk):\n * ⚠️ insetStyle: inset, insetBlock, insetInline, top, right, bottom, left\n */\nexport const POSITION_CHUNK_STYLES = [\n  'position',\n  // All from insetStyle handler - MUST stay together\n  'inset',\n  'insetBlock',\n  'insetInline',\n  'top',\n  'right',\n  'bottom',\n  'left',\n  'zIndex',\n  'gridArea',\n  'gridColumn',\n  'gridRow',\n  'order',\n  'placeSelf',\n  'alignSelf',\n  'justifySelf',\n  'transform',\n  'transition',\n  'animation',\n] as const;\n\n// ============================================================================\n// Chunk Names\n// ============================================================================\n\nexport const CHUNK_NAMES = {\n  /** Special chunk for styles that cannot be split (e.g., @starting-style) */\n  COMBINED: 'combined',\n  SUBCOMPONENTS: 'subcomponents',\n  APPEARANCE: 'appearance',\n  FONT: 'font',\n  DIMENSION: 'dimension',\n  DISPLAY: 'display',\n  LAYOUT: 'layout',\n  POSITION: 'position',\n  MISC: 'misc',\n} as const;\n\nexport type ChunkName = (typeof CHUNK_NAMES)[keyof typeof CHUNK_NAMES];\n\n// ============================================================================\n// Style-to-Chunk Lookup Map (O(1) categorization)\n// ============================================================================\n\n/**\n * Pre-computed map for O(1) style-to-chunk lookup.\n * Built once at module load time.\n */\nexport const STYLE_TO_CHUNK = new Map<string, ChunkName>();\n\n// Populate the lookup map\nfunction populateStyleToChunkMap() {\n  for (const style of APPEARANCE_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.APPEARANCE);\n  }\n  for (const style of FONT_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.FONT);\n  }\n  for (const style of DIMENSION_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.DIMENSION);\n  }\n  for (const style of DISPLAY_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.DISPLAY);\n  }\n  for (const style of LAYOUT_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.LAYOUT);\n  }\n  for (const style of POSITION_CHUNK_STYLES) {\n    STYLE_TO_CHUNK.set(style, CHUNK_NAMES.POSITION);\n  }\n}\n\n// Initialize at module load\npopulateStyleToChunkMap();\n\n// ============================================================================\n// Chunk Priority Order\n// ============================================================================\n\n/**\n * Chunk processing order. This ensures deterministic className allocation\n * regardless of style key order in the input.\n */\nconst CHUNK_ORDER: readonly string[] = [\n  CHUNK_NAMES.APPEARANCE,\n  CHUNK_NAMES.FONT,\n  CHUNK_NAMES.DIMENSION,\n  CHUNK_NAMES.DISPLAY,\n  CHUNK_NAMES.LAYOUT,\n  CHUNK_NAMES.POSITION,\n  CHUNK_NAMES.MISC,\n  CHUNK_NAMES.SUBCOMPONENTS,\n] as const;\n\n/**\n * Map from chunk name to its priority index for sorting.\n */\nconst _CHUNK_PRIORITY = new Map<string, number>(\n  CHUNK_ORDER.map((name, index) => [name, index]),\n);\n\n// ============================================================================\n// Chunk Info Interface\n// ============================================================================\n\nexport interface ChunkInfo {\n  /** Name of the chunk */\n  name: ChunkName | string;\n  /** Style keys belonging to this chunk */\n  styleKeys: string[];\n}\n\n// ============================================================================\n// Style Categorization\n// ============================================================================\n\n/**\n * Categorize style keys into chunks.\n *\n * Returns chunks in a deterministic order (by CHUNK_ORDER) regardless\n * of the order of keys in the input styles object.\n *\n * @param styles - The styles object to categorize\n * @returns Map of chunk name to array of style keys in that chunk (in priority order)\n */\nexport function categorizeStyleKeys(\n  styles: Record<string, unknown>,\n): Map<string, string[]> {\n  // First pass: collect keys into chunks (unordered)\n  const chunkData: Record<string, string[]> = {};\n  const keys = Object.keys(styles);\n\n  for (const key of keys) {\n    // Skip the $ helper key (used for selector combinators)\n    // Skip @keyframes and @properties (processed separately in useStyles)\n    // Skip recipe (resolved before pipeline by resolveRecipes)\n    if (\n      key === '$' ||\n      key === '@keyframes' ||\n      key === '@properties' ||\n      key === 'recipe'\n    ) {\n      continue;\n    }\n\n    if (isSelector(key)) {\n      // All selectors go into the subcomponents chunk\n      if (!chunkData[CHUNK_NAMES.SUBCOMPONENTS]) {\n        chunkData[CHUNK_NAMES.SUBCOMPONENTS] = [];\n      }\n      chunkData[CHUNK_NAMES.SUBCOMPONENTS].push(key);\n    } else {\n      // Look up the chunk for this style, default to misc\n      const chunkName = STYLE_TO_CHUNK.get(key) ?? CHUNK_NAMES.MISC;\n      if (!chunkData[chunkName]) {\n        chunkData[chunkName] = [];\n      }\n      chunkData[chunkName].push(key);\n    }\n  }\n\n  // Second pass: build ordered Map based on CHUNK_ORDER\n  const orderedChunks = new Map<string, string[]>();\n\n  // Add chunks in priority order\n  for (const chunkName of CHUNK_ORDER) {\n    if (chunkData[chunkName] && chunkData[chunkName].length > 0) {\n      // Sort keys within chunk for consistent cache key generation\n      orderedChunks.set(chunkName, chunkData[chunkName].sort());\n    }\n  }\n\n  // Handle any unknown chunks (shouldn't happen, but be defensive)\n  for (const chunkName of Object.keys(chunkData)) {\n    if (!orderedChunks.has(chunkName)) {\n      orderedChunks.set(chunkName, chunkData[chunkName].sort());\n    }\n  }\n\n  return orderedChunks;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,MAAa,0BAA0B;CACrC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,MAAa,oBAAoB;CAE/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;AAWD,MAAa,yBAAyB;CAEpC;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;AAWD,MAAa,uBAAuB;CAElC;CACA;CACA;CACA;CACA;CAEA;CAEA;CAEA;CACD;;;;;;;AAQD,MAAa,sBAAsB;CAEjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;AAQD,MAAa,wBAAwB;CACnC;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAMD,MAAa,cAAc;CAEzB,UAAU;CACV,eAAe;CACf,YAAY;CACZ,MAAM;CACN,WAAW;CACX,SAAS;CACT,QAAQ;CACR,UAAU;CACV,MAAM;CACP;;;;;AAYD,MAAa,iCAAiB,IAAI,KAAwB;AAG1D,SAAS,0BAA0B;AACjC,MAAK,MAAM,SAAS,wBAClB,gBAAe,IAAI,OAAO,YAAY,WAAW;AAEnD,MAAK,MAAM,SAAS,kBAClB,gBAAe,IAAI,OAAO,YAAY,KAAK;AAE7C,MAAK,MAAM,SAAS,uBAClB,gBAAe,IAAI,OAAO,YAAY,UAAU;AAElD,MAAK,MAAM,SAAS,qBAClB,gBAAe,IAAI,OAAO,YAAY,QAAQ;AAEhD,MAAK,MAAM,SAAS,oBAClB,gBAAe,IAAI,OAAO,YAAY,OAAO;AAE/C,MAAK,MAAM,SAAS,sBAClB,gBAAe,IAAI,OAAO,YAAY,SAAS;;AAKnD,yBAAyB;;;;;AAUzB,MAAM,cAAiC;CACrC,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,YAAY;CACb;AAKuB,IAAI,IAC1B,YAAY,KAAK,MAAM,UAAU,CAAC,MAAM,MAAM,CAAC,CAChD;;;;;;;;;;AA0BD,SAAgB,oBACd,QACuB;CAEvB,MAAM,YAAsC,EAAE;CAC9C,MAAM,OAAO,OAAO,KAAK,OAAO;AAEhC,MAAK,MAAM,OAAO,MAAM;AAItB,MACE,QAAQ,OACR,QAAQ,gBACR,QAAQ,iBACR,QAAQ,SAER;AAGF,MAAI,WAAW,IAAI,EAAE;AAEnB,OAAI,CAAC,UAAU,YAAY,eACzB,WAAU,YAAY,iBAAiB,EAAE;AAE3C,aAAU,YAAY,eAAe,KAAK,IAAI;SACzC;GAEL,MAAM,YAAY,eAAe,IAAI,IAAI,IAAI,YAAY;AACzD,OAAI,CAAC,UAAU,WACb,WAAU,aAAa,EAAE;AAE3B,aAAU,WAAW,KAAK,IAAI;;;CAKlC,MAAM,gCAAgB,IAAI,KAAuB;AAGjD,MAAK,MAAM,aAAa,YACtB,KAAI,UAAU,cAAc,UAAU,WAAW,SAAS,EAExD,eAAc,IAAI,WAAW,UAAU,WAAW,MAAM,CAAC;AAK7D,MAAK,MAAM,aAAa,OAAO,KAAK,UAAU,CAC5C,KAAI,CAAC,cAAc,IAAI,UAAU,CAC/B,eAAc,IAAI,WAAW,UAAU,WAAW,MAAM,CAAC;AAI7D,QAAO"}

package/dist/config.d.ts

@@ -1,7 +1,7 @@
 import { KeyframesSteps, PropertyDefinition } from "./injector/types.js";
 import { StyleDetails, UnitHandler } from "./parser/types.js";
 import { StyleHandlerDefinition } from "./utils/styles.js";
-import { RecipeStyles } from "./styles/types.js";
+import { ConfigTokens, RecipeStyles } from "./styles/types.js";
 import { StyleInjector } from "./injector/injector.js";
 import { TastyPlugin } from "./plugins/types.js";
 
@@ -152,20 +152,43 @@ interface TastyConfig {
    */
   handlers?: Record<string, StyleHandlerDefinition>;
   /**
-   * Predefined tokens that are replaced during style parsing.
-   * Token values are processed through the parser (like component tokens).
+   * Design tokens injected as CSS custom properties on `:root`.
+   * Values are parsed through the Tasty DSL. Supports state maps
+   * for responsive/theme-aware tokens.
+   *
+   * - `$name` keys become `--name` CSS custom properties
+   * - `#name` keys become `--name-color` and `--name-color-rgb` properties
+   *
+   * Tokens are injected once when the first style is rendered.
+   *
+   * @example
+   * ```ts
+   * configure({
+   *   tokens: {
+   *     '$gap': '4px',
+   *     '#primary': {
+   *       '': '#purple',
+   *       '@dark': '#light-purple',
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  tokens?: ConfigTokens;
+  /**
+   * Predefined tokens that are replaced during style parsing (parse-time substitution).
    * Use `$name` for custom properties and `#name` for color tokens.
+   * Values are substituted inline before CSS generation, unlike `tokens` which
+   * inject CSS custom properties on `:root`.
    *
    * For color tokens (#name), boolean `true` is converted to `transparent`.
    *
    * @example
    * ```ts
    * configure({
-   *   tokens: {
+   *   replaceTokens: {
    *     $spacing: '2x',
-   *     '$card-padding': '4x',
    *     '#accent': '#purple',
-   *     '#surface': '#white',
    *     '#overlay': true, // → transparent
    *   },
    * });
@@ -173,13 +196,13 @@ interface TastyConfig {
    * // Now use in styles - tokens are replaced at parse time:
    * const Card = tasty({
    *   styles: {
-   *     padding: '$card-padding',  // → calc(4 * var(--gap))
-   *     fill: '#surface',          // → var(--white-color)
+   *     padding: '$spacing',  // → calc(2 * var(--gap))
+   *     fill: '#accent',      // → var(--purple-color)
    *   },
    * });
    * ```
    */
-  tokens?: Record<`$${string}`, string | number | boolean> & Record<`#${string}`, string | number | boolean>;
+  replaceTokens?: Record<`$${string}`, string | number | boolean> & Record<`#${string}`, string | number | boolean>;
   /**
    * Predefined style recipes -- named style bundles that can be applied via `recipe` style property.
    * Recipe values are flat tasty styles (no sub-element keys). They may contain base styles,

package/dist/config.js

@@ -3,7 +3,7 @@ import { setGlobalPredefinedStates } from "./states/index.js";
 import { CUSTOM_UNITS, getGlobalFuncs, getGlobalParser, normalizeColorTokenValue, resetGlobalPredefinedTokens, setGlobalPredefinedTokens } from "./utils/styles.js";
 import { normalizeHandlerDefinition, registerHandler, resetHandlers } from "./styles/predefined.js";
 import { StyleInjector } from "./injector/injector.js";
-import { clearPipelineCache, isSelector } from "./pipeline/index.js";
+import { clearPipelineCache, isSelector, renderStyles } from "./pipeline/index.js";
 
 //#region src/config.ts
 /**
@@ -34,6 +34,7 @@ let currentConfig = null;
 let globalKeyframes = null;
 let globalProperties = null;
 let globalRecipes = null;
+let globalConfigTokens = null;
 /**
 * Internal properties required by tasty core features.
 * These are always injected when styles are first generated.
@@ -157,6 +158,10 @@ function markStylesGenerated() {
 		}]);
 	}
 	if (globalProperties && Object.keys(globalProperties).length > 0) for (const [token, definition] of Object.entries(globalProperties)) injector.property(token, definition);
+	if (globalConfigTokens && Object.keys(globalConfigTokens).length > 0) {
+		const tokenRules = renderStyles(globalConfigTokens, ":root");
+		if (tokenRules.length > 0) injector.injectGlobal(tokenRules);
+	}
 }
 /**
 * Check if styles have been generated (configuration is locked)
@@ -190,6 +195,20 @@ function setGlobalKeyframes(keyframes) {
 	globalKeyframes = keyframes;
 }
 /**
+* Check if any global properties are configured.
+* Fast path: returns false if no properties were ever set.
+*/
+function hasGlobalProperties() {
+	return globalProperties !== null && Object.keys(globalProperties).length > 0;
+}
+/**
+* Get global properties configuration.
+* Returns null if no properties configured (fast path for zero-overhead).
+*/
+function getGlobalProperties() {
+	return globalProperties;
+}
+/**
 * Set global properties (called from configure).
 * Internal use only.
 */
@@ -233,6 +252,27 @@ function setGlobalRecipes(recipes) {
 	globalRecipes = recipes;
 }
 /**
+* Get global token styles for :root injection.
+* Returns null if no tokens configured.
+*/
+function getGlobalConfigTokens() {
+	return globalConfigTokens;
+}
+/**
+* Set global token styles (called from configure).
+* Internal use only.
+*/
+function setGlobalConfigTokens(styles) {
+	if (stylesGenerated) {
+		warnOnce("tokens-after-styles", "[Tasty] Cannot update tokens after styles have been generated.\nThe new tokens will be ignored.");
+		return;
+	}
+	globalConfigTokens = globalConfigTokens ? {
+		...globalConfigTokens,
+		...styles
+	} : styles;
+}
+/**
 * Check if configuration is locked (styles have been generated)
 */
 function isConfigLocked() {
@@ -268,7 +308,8 @@ function configure(config = {}) {
 	let mergedUnits = {};
 	let mergedFuncs = {};
 	let mergedHandlers = {};
-	let mergedTokens = {};
+	let mergedReplaceTokens = {};
+	let mergedConfigTokens = {};
 	let mergedRecipes = {};
 	if (config.plugins) for (const plugin of config.plugins) {
 		if (plugin.states) mergedStates = {
@@ -287,8 +328,12 @@ function configure(config = {}) {
 			...mergedHandlers,
 			...plugin.handlers
 		};
-		if (plugin.tokens) mergedTokens = {
-			...mergedTokens,
+		if (plugin.replaceTokens) mergedReplaceTokens = {
+			...mergedReplaceTokens,
+			...plugin.replaceTokens
+		};
+		if (plugin.tokens) mergedConfigTokens = {
+			...mergedConfigTokens,
 			...plugin.tokens
 		};
 		if (plugin.recipes) mergedRecipes = {
@@ -312,14 +357,22 @@ function configure(config = {}) {
 		...mergedHandlers,
 		...config.handlers
 	};
-	if (config.tokens) mergedTokens = {
-		...mergedTokens,
+	if (config.replaceTokens) mergedReplaceTokens = {
+		...mergedReplaceTokens,
+		...config.replaceTokens
+	};
+	if (config.tokens) mergedConfigTokens = {
+		...mergedConfigTokens,
 		...config.tokens
 	};
 	if (config.recipes) mergedRecipes = {
 		...mergedRecipes,
 		...config.recipes
 	};
+	if (devMode) {
+		const tokenKeys = new Set(Object.keys(mergedConfigTokens));
+		for (const key of Object.keys(mergedReplaceTokens)) if (tokenKeys.has(key)) warnOnce(`token-conflict-${key}`, `[Tasty] Token "${key}" is defined in both \`tokens\` and \`replaceTokens\`. \`replaceTokens\` performs parse-time substitution, so the \`tokens\` CSS custom property will be injected but never used by Tasty styles. Remove it from one of the two.`);
+	}
 	if (Object.keys(mergedStates).length > 0) setGlobalPredefinedStates(mergedStates);
 	const parser = getGlobalParser();
 	if (config.parserCacheSize !== void 0) parser.updateOptions({ cacheSize: config.parserCacheSize });
@@ -342,9 +395,9 @@ function configure(config = {}) {
 	if (config.keyframes) setGlobalKeyframes(config.keyframes);
 	if (config.properties) setGlobalProperties(config.properties);
 	if (Object.keys(mergedHandlers).length > 0) for (const [name, definition] of Object.entries(mergedHandlers)) registerHandler(normalizeHandlerDefinition(name, definition));
-	if (Object.keys(mergedTokens).length > 0) {
+	if (Object.keys(mergedReplaceTokens).length > 0) {
 		const processedTokens = {};
-		for (const [key, value] of Object.entries(mergedTokens)) if (key.startsWith("#")) {
+		for (const [key, value] of Object.entries(mergedReplaceTokens)) if (key.startsWith("#")) {
 			const normalized = normalizeColorTokenValue(value);
 			if (normalized === null) continue;
 			processedTokens[key] = String(normalized);
@@ -352,8 +405,9 @@ function configure(config = {}) {
 		else processedTokens[key] = String(value);
 		setGlobalPredefinedTokens(processedTokens);
 	}
+	if (Object.keys(mergedConfigTokens).length > 0) setGlobalConfigTokens(mergedConfigTokens);
 	if (Object.keys(mergedRecipes).length > 0) setGlobalRecipes(mergedRecipes);
-	const { states: _states, parserCacheSize: _parserCacheSize, units: _units, funcs: _funcs, plugins: _plugins, keyframes: _keyframes, properties: _properties, handlers: _handlers, tokens: _tokens, recipes: _recipes, ...injectorConfig } = config;
+	const { states: _states, parserCacheSize: _parserCacheSize, units: _units, funcs: _funcs, plugins: _plugins, keyframes: _keyframes, properties: _properties, handlers: _handlers, tokens: _tokens, replaceTokens: _replaceTokens, recipes: _recipes, ...injectorConfig } = config;
 	const fullConfig = {
 		...createDefaultConfig(),
 		...currentConfig,
@@ -390,6 +444,7 @@ function resetConfig() {
 	globalKeyframes = null;
 	globalProperties = null;
 	globalRecipes = null;
+	globalConfigTokens = null;
 	resetGlobalPredefinedTokens();
 	resetHandlers();
 	clearPipelineCache();
@@ -399,5 +454,5 @@ function resetConfig() {
 }
 
 //#endregion
-export { configure, getConfig, getGlobalInjector, getGlobalKeyframes, getGlobalRecipes, hasGlobalKeyframes, hasGlobalRecipes, hasStylesGenerated, isConfigLocked, isTestEnvironment, markStylesGenerated, resetConfig };
+export { INTERNAL_PROPERTIES, INTERNAL_TOKENS, configure, getConfig, getGlobalConfigTokens, getGlobalInjector, getGlobalKeyframes, getGlobalProperties, getGlobalRecipes, hasGlobalKeyframes, hasGlobalProperties, hasGlobalRecipes, hasStylesGenerated, isConfigLocked, isTestEnvironment, markStylesGenerated, resetConfig };
 //# sourceMappingURL=config.js.map