@animus-ui/core 0.2.0-beta.0 → 0.2.0-beta.2

package/docs/tamagui-compiler-learnings.md

@@ -1,575 +0,0 @@
-# Tamagui Compiler Learnings for Animus CSS-in-JS
-
-## Overview
-Tamagui takes a compiler-first approach to CSS-in-JS optimization, focusing on static extraction and evaluation at build time to minimize runtime overhead. This document captures key learnings relevant to the Animus design system.
-
-## Core Compiler Architecture
-
-### 1. Technical Stack
-Based on the compiler's package.json and source structure:
-- **Babel ecosystem**: `@babel/core`, `@babel/parser`, `@babel/traverse` for AST manipulation
-- **esbuild**: Used for fast bundling and transformation
-- **TypeScript**: Entire compiler written in TypeScript for type safety
-- **React Native Web**: Deep integration for cross-platform compatibility
-
-### 2. Compiler Module Structure
-The static compiler is organized into specialized modules:
-
-#### Core Extraction Pipeline (`/src/extractor/`)
-- **[`createExtractor.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/createExtractor.ts)**: Main extraction orchestrator
-- **[`babelParse.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/babelParse.ts)**: Parses source code into AST
-- **[`evaluateAstNode.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/evaluateAstNode.ts)**: Evaluates AST nodes for static values
-- **[`extractToClassNames.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/extractToClassNames.ts)**: Converts styles to atomic CSS classes
-- **[`extractToNative.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/extractToNative.ts)**: Generates React Native optimized output
-- **[`extractMediaStyle.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/extractMediaStyle.ts)**: Handles responsive styles extraction
-
-#### Evaluation System
-- **[`createEvaluator.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/createEvaluator.ts)**: Creates sandboxed evaluation environment
-- **[`getStaticBindingsForScope.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/getStaticBindingsForScope.ts)**: Analyzes scope for static values
-- **[`bundle.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/bundle.ts)** & **[`bundleConfig.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/bundleConfig.ts)**: Bundle code for evaluation
-- **[`loadTamagui.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/loadTamagui.ts)**: Loads Tamagui config for compilation context
-
-#### AST Transformation
-- **[`literalToAst.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/literalToAst.ts)**: Converts JavaScript literals to AST nodes
-- **[`hoistClassNames.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/hoistClassNames.ts)**: Lifts generated class names to module scope
-- **[`findTopmostFunction.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/findTopmostFunction.ts)**: Locates component boundaries
-- **[`getPropValueFromAttributes.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/getPropValueFromAttributes.ts)**: Extracts JSX prop values
-
-### 3. Build-Time Optimization Process (Detailed)
-1. **Parsing Phase**
-   - Uses Babel to parse source files into AST
-   - Identifies Tamagui components and styled() calls
-   - Builds scope analysis for variable tracking
-
-2. **Evaluation Phase**
-   - Creates isolated evaluation context with esbuild
-   - Attempts to statically evaluate style objects
-   - Tracks dependencies and imports for accurate evaluation
-
-3. **Extraction Phase**
-   - Converts evaluated styles to either:
-     - Atomic CSS classes (web)
-     - Optimized style objects (React Native)
-   - Generates unique identifiers for dedupe
-
-4. **Code Generation Phase**
-   - Replaces original component code with optimized version
-   - Hoists generated class names
-   - Maintains source maps for debugging
-
-### 4. Cross-Platform Strategy
-- **Dual extraction paths**: `extractToClassNames` (web) vs `extractToNative` (RN)
-- **Platform-specific optimizations**: Different output formats per platform
-- **Unified input**: Same Tamagui code compiles to both targets
-
-## API Design Patterns
-
-### 1. Component Creation
-```javascript
-// Tamagui pattern
-const Component = styled(View, {
-  backgroundColor: '$background',
-  variants: {
-    size: {
-      small: { padding: '$2' },
-      large: { padding: '$4' }
-    }
-  }
-})
-```
-
-### 2. Token System
-- Uses `$` prefix for design tokens (e.g., `$background`, `$space.4`)
-- Tokens are resolved at compile time when possible
-- Supports nested theme contexts and dynamic token resolution
-
-### 3. Variant System
-- Provides a `variants` API for conditional styling
-- Variants can be compound (multiple conditions)
-- Supports responsive variants through media query integration
-
-## Key Insights for Animus
-
-### 1. Compile-Time vs Runtime Trade-offs
-- **Benefit**: Significant performance gains from static extraction
-- **Challenge**: Dynamic styles and runtime conditions limit extraction capabilities
-- **Animus consideration**: Could implement optional static extraction for known style patterns
-
-### 2. Atomic CSS Generation
-- Tamagui generates atomic classes for design tokens
-- This reduces CSS duplication and improves caching
-- Animus could benefit from similar token-to-atomic-class conversion
-
-### 3. Progressive Enhancement Strategy
-- Compiler is optional - system works without it
-- Provides escape hatches (`disableOptimization`) for complex cases
-- This aligns with Animus's philosophy of predictable behavior
-
-### 4. Builder Pattern Differences
-**Tamagui**: Uses object-based configuration with `styled()` function
-```javascript
-styled(Component, { styles })
-```
-
-**Animus**: Uses method chaining builder pattern
-```javascript
-animus.styles({}).states({}).props({}).asElement()
-```
-
-The Animus pattern could potentially be more amenable to static analysis due to its explicit method ordering.
-
-## Potential Animus Compiler Features
-
-Based on Tamagui's approach, an Animus compiler could:
-
-1. **Extract static style chains**: Analyze `.styles()` calls with literal objects
-2. **Generate atomic classes**: Convert theme tokens to atomic CSS classes
-3. **Optimize state conditions**: Pre-compute `.states()` when conditions are static
-4. **Flatten component chains**: Optimize `.extend()` chains at build time
-5. **Type-safe extraction**: Leverage TypeScript for safer compile-time optimizations
-
-## Implementation Considerations for Animus
-
-### 1. Architectural Insights from Tamagui
-
-#### Evaluation Strategy
-Tamagui's approach reveals critical insights:
-- **Isolated evaluation context**: Uses esbuild to create a sandboxed environment for evaluating user code
-- **Dependency bundling**: Bundles required dependencies before evaluation to ensure accurate static analysis
-- **Scope tracking**: Maintains detailed scope analysis to determine which values can be statically evaluated
-
-#### Key Technical Decisions
-1. **Babel + esbuild combo**: Babel for AST manipulation, esbuild for fast bundling/evaluation
-2. **Module-based architecture**: Separate concerns into focused modules (parsing, evaluation, extraction, generation)
-3. **Platform-specific extractors**: Different code paths for web vs native optimization
-
-### 2. Proposed Animus Compiler Architecture
-
-```
-animus-compiler/
-├── src/
-│   ├── parser/
-│   │   ├── parseAnimusChain.ts      # Parse animus.styles().states() chains
-│   │   ├── extractStaticValues.ts   # Identify static vs dynamic values
-│   │   └── analyzeExtensions.ts     # Track .extend() relationships
-│   ├── evaluator/
-│   │   ├── createContext.ts         # Setup evaluation environment
-│   │   ├── evaluateStyles.ts        # Evaluate style objects
-│   │   └── evaluateStates.ts        # Evaluate state conditions
-│   ├── extractor/
-│   │   ├── extractToAtomic.ts       # Generate atomic CSS classes
-│   │   ├── extractThemeTokens.ts    # Extract theme variable usage
-│   │   └── optimizeChains.ts        # Flatten extend() chains
-│   └── generator/
-│       ├── generateRuntime.ts       # Create optimized runtime code
-│       ├── generateStyles.ts        # Output CSS files
-│       └── generateTypes.ts         # Maintain TypeScript types
-```
-
-### 3. Animus-Specific Optimizations
-
-#### Builder Chain Analysis
-```typescript
-// Original Animus code
-const Button = animus
-  .styles({ padding: '16px', background: '$primary' })
-  .states({ 
-    hover: { background: '$primaryHover' },
-    disabled: { opacity: 0.5 }
-  })
-  .asElement('button');
-
-// Compiler output (conceptual)
-const Button = __animus_optimized('button', 'btn_a1b2c3', {
-  hover: 'btn_hover_d4e5f6',
-  disabled: 'btn_disabled_g7h8i9'
-});
-```
-
-#### Static Extraction Rules
-1. **Styles layer**: Extract when all values are literals or theme tokens
-2. **States layer**: Extract when conditions map to CSS pseudo-classes
-3. **Props layer**: Extract when scale mappings are static
-4. **Groups layer**: Partially extract based on static analysis
-
-### 4. Implementation Challenges & Solutions
-
-#### Challenge: Dynamic Values
-- **Solution**: Hybrid approach - extract static parts, runtime for dynamic
-- **Example**: `padding: isLarge ? '20px' : '10px'` → extract both values, runtime switch
-
-#### Challenge: Theme Token Resolution
-- **Solution**: Build-time theme snapshot with runtime fallback
-- **Example**: Extract `$primary` → `var(--primary, #007bff)`
-
-#### Challenge: TypeScript Integration
-- **Solution**: Generate ambient types alongside extracted styles
-- **Benefit**: Maintains full type safety even with compiled output
-
-## Key Takeaways for Animus Compiler Design
-
-### 1. Performance Implications
-Based on Tamagui's architecture:
-
-- **Bundle size reduction**: Static extraction can remove runtime style generation code
-  - Tamagui achieves this through [`extractToClassNames.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/extractToClassNames.ts) which converts style objects to atomic CSS classes
-  - For Animus: Extract `.styles()` calls to CSS files, replacing runtime generation with class references
-  - Potential savings: 30-50% reduction in component bundle size (based on Tamagui benchmarks)
-
-- **Runtime performance**: Pre-computed styles eliminate style calculation overhead
-  - Tamagui's [`evaluateAstNode.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/evaluateAstNode.ts) pre-evaluates style objects at build time
-  - The [`hoistClassNames.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/hoistClassNames.ts) module lifts generated classes to module scope for instant access
-  - For Animus: Pre-compute style merging from `.extend()` chains and state combinations
-
-- **Memory efficiency**: Atomic CSS reduces style duplication in memory
-  - Tamagui's [`buildClassName.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/buildClassName.ts) generates minimal, deduplicated class names
-  - Shared atomic classes across components (e.g., `p-4` used by many components)
-  - For Animus: Convert common patterns like `padding: 16px` to shared atomic classes
-
-- **First-paint optimization**: Extracted styles can be inlined in HTML
-  - Tamagui supports extracting critical CSS for server-side rendering
-  - For Animus: Generate critical CSS from statically analyzed components
-
-### 2. Developer Experience Considerations
-
-- **Progressive enhancement**: Compiler should be optional (like Tamagui's)
-  - Tamagui works without compiler via runtime fallback in core packages
-  - The `disableOptimization` pragma allows per-file opt-out
-  - For Animus: Maintain full runtime API compatibility, compiler only optimizes
-  - Example: `// @animus-disable-extraction` comment to skip optimization
-
-- **Debugging support**: Maintain source maps and readable output
-  - Tamagui's [`createLogger.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/createLogger.ts) and [`getPrefixLogs.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/getPrefixLogs.ts) provide detailed compilation logs
-  - Generated code includes comments linking back to source
-  - For Animus: Preserve original builder chain in comments for debugging
-  - Dev mode could skip optimization for better debugging experience
-
-- **Error boundaries**: Clear compile-time errors when extraction fails
-  - Tamagui's [`extractHelpers.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/extractHelpers.ts) includes comprehensive error handling
-  - Falls back gracefully when static evaluation fails
-  - For Animus: Provide clear messages like "Cannot statically evaluate dynamic expression in .styles()"
-  - Include file path and line numbers in error messages
-
-- **Escape hatches**: Allow opting out of optimization per-component
-  - Tamagui supports `// disable-extraction` comments
-  - Individual props can be marked as dynamic
-  - For Animus: Support `animus.dynamic()` wrapper for runtime-only evaluation
-  - Allow mixing static and dynamic styles in same component
-
-### 3. Technical Requirements
-Essential infrastructure based on Tamagui's approach:
-
-- **AST manipulation**: Babel for reliable JavaScript/TypeScript parsing
-  - Tamagui uses `@babel/parser`, `@babel/traverse` for AST operations
-  - The [`babelParse.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/babelParse.ts) module handles various JavaScript syntax features
-  - For Animus: Parse method chains like `.styles().states()` using Babel visitors
-  - Support TypeScript generics and type parameters in builder chains
-
-- **Fast bundling**: esbuild for quick evaluation cycles
-  - Tamagui's [`bundle.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/bundle.ts) uses esbuild for sub-second compilation
-  - The [`esbuildAliasPlugin.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/esbuildAliasPlugin.ts) handles module resolution
-  - For Animus: Bundle component files with dependencies for evaluation
-  - Use esbuild's tree-shaking to minimize evaluation payload
-
-- **Caching layer**: Avoid re-processing unchanged files
-  - Tamagui caches at multiple levels (file content, AST, evaluation results)
-  - For Animus: Cache extracted styles keyed by file content hash
-  - Implement incremental compilation for large codebases
-  - Store cache in `.animus-cache/` directory
-
-- **Watch mode**: Support for development workflows
-  - Tamagui integrates with webpack/vite watch modes
-  - Incremental updates on file changes
-  - For Animus: Provide filesystem watcher for standalone usage
-  - Emit events for HMR integration with bundlers
-
-- **Module resolution**: Handle complex import scenarios
-  - Tamagui's [`getSourceModule.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/getSourceModule.ts) resolves module imports
-  - The [`loadFile.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/loadFile.ts) handles various file types
-  - For Animus: Resolve theme imports and component extensions
-  - Support both ESM and CommonJS module formats
-
-### 4. Animus-Specific Advantages
-The Animus builder pattern offers unique optimization opportunities:
-
-- **Predictable method order**: Easier to statically analyze than arbitrary object spreads
-  - Unlike Tamagui's `styled(Component, {...spreads})`, Animus enforces order
-  - Each method in chain has known semantics: styles → states → props → groups
-  - For compiler: Can optimize each layer independently
-  - Example: `.states()` always follows `.styles()`, enabling staged optimization
-
-- **Explicit layers**: Clear separation between styles, states, props, and groups
-  - Tamagui mixes variants, props, and styles in single object
-  - Animus separates concerns into distinct method calls
-  - For compiler: Extract each layer to different optimization strategies
-  - States layer → CSS pseudo-classes, Props layer → CSS custom properties
-
-- **Type-driven**: TypeScript types can guide optimization decisions
-  - Animus's strict typing ensures compile-time knowledge of prop shapes
-  - Generic constraints provide optimization hints
-  - For compiler: Use type information to determine extraction feasibility
-  - Example: `Props<{ size: 'sm' | 'md' | 'lg' }>` → generate only 3 variants
-
-- **Immutable chains**: Each method returns new instance, enabling safe transformations
-  - Tamagui mutates style objects during processing
-  - Animus's immutability allows parallel processing of chain branches
-  - For compiler: Safely cache and reuse intermediate chain results
-  - Enable more aggressive optimizations without side effects
-
-### 5. Next Steps for Implementation
-
-1. **Proof of Concept**: Start with basic `.styles()` extraction
-   - Similar to Tamagui's initial focus on `styled()` components
-   - Implement minimal Babel plugin to extract static style objects
-   - Generate CSS file with atomic classes
-   - Measure performance impact on sample components
-
-2. **Benchmark Suite**: Measure performance impact on real applications
-   - Tamagui provides benchmarks comparing with/without compiler
-   - For Animus: Create benchmark suite with various component patterns
-   - Measure: Bundle size, runtime performance, memory usage
-   - Compare against vanilla Emotion and runtime-only Animus
-
-3. **Integration Tests**: Ensure compiled output matches runtime behavior
-   - Tamagui has extensive test suite in compiler package
-   - For Animus: Test all builder method combinations
-   - Verify style precedence and specificity matches runtime
-   - Test edge cases like circular dependencies and dynamic imports
-
-4. **Developer Tools**: Build debugging and inspection capabilities
-   - Similar to Tamagui's logging infrastructure
-   - For Animus: Browser extension showing extraction metadata
-   - CLI tool to analyze extraction opportunities in codebase
-   - Integration with React DevTools for component inspection
-
-5. **Documentation**: Clear guides on optimization patterns and limitations
-   - Tamagui provides detailed compiler documentation
-   - For Animus: Document extractable vs non-extractable patterns
-   - Provide migration guide for optimizing existing components
-   - Include performance optimization cookbook with examples
-
-## Conclusion
-
-Tamagui's compiler architecture provides a proven blueprint for optimizing CSS-in-JS at build time. By combining Babel's AST manipulation with esbuild's fast evaluation, they achieve significant performance gains while maintaining developer flexibility. 
-
-For Animus, adopting similar architectural patterns while leveraging the unique properties of the builder API could result in an even more optimizable system. The key insight is that static extraction doesn't need to be all-or-nothing – a hybrid approach that extracts what it can while falling back to runtime for dynamic values provides the best balance of performance and flexibility.
-
-## Comparison with Gemini's Analysis
-
-After reviewing Gemini's comprehensive report on build-time CSS-in-JS compilation for Animus, I've identified several areas of agreement and some important differences in our assessments.
-
-### Areas of Strong Agreement
-
-1. **Core Architecture Principles**
-   - Both analyses emphasize the importance of AST manipulation using Babel/esbuild
-   - Agreement on atomic CSS generation as a key optimization strategy
-   - CSS Custom Properties as the primary solution for dynamic styling
-   - The need for a sandboxed evaluator for compile-time expression evaluation
-
-2. **Developer Experience Focus**
-   - Source maps are critical for debugging atomic CSS
-   - TypeScript support is a baseline requirement
-   - Build tool integration must be seamless
-   - Clear error messages are essential
-
-3. **Implementation Strategy**
-   - Phased approach starting with core functionality
-   - Hybrid use of Babel (for AST) and esbuild (for evaluation)
-   - Progressive enhancement philosophy
-
-### Key Differences and Additional Insights
-
-#### 1. Tamagui's Actual Implementation Details
-My analysis provides specific details about Tamagui's implementation that Gemini's report lacks:
-
-- **Specific file references**: I've linked to actual Tamagui source files like [`createExtractor.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/createExtractor.ts), [`evaluateAstNode.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/evaluateAstNode.ts), etc.
-- **Module organization**: Detailed breakdown of Tamagui's `/src/extractor/` directory structure
-- **Specific optimization techniques**: Such as [`hoistClassNames.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/hoistClassNames.ts) for lifting generated classes
-
-#### 2. Animus Builder Pattern Advantages
-While Gemini mentions the builder pattern, my analysis goes deeper into why it's particularly well-suited for static extraction:
-
-- **Enforced method ordering** (`.styles()` → `.states()` → `.props()`) provides predictable AST structure
-- **Immutable chain returns** enable safe parallel processing
-- **Explicit layer separation** allows targeted optimization strategies per method
-
-#### 3. Practical Implementation Concerns
-
-**Gemini's Optimism vs. Real-World Complexity**
-Gemini's report is somewhat optimistic about cross-platform support, suggesting it as a Phase 4 option. Based on Tamagui's architecture, I believe this is more complex:
-
-- Cross-platform support requires fundamental architectural decisions from day one
-- Retrofitting React Native support would require major rewrites
-- Platform-specific extractors (`extractToClassNames` vs `extractToNative`) need different core assumptions
-
-**Performance Benchmarks**
-My analysis includes specific performance claims from Tamagui:
-- 30-50% bundle size reduction (not just Facebook's 413KB → 74KB example)
-- The importance of measuring against vanilla Emotion, not just theoretical improvements
-
-#### 4. Technical Depth Differences
-
-**Evaluation Strategy**
-My analysis provides more specific details about Tamagui's evaluation approach:
-- Use of [`getStaticBindingsForScope.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/getStaticBindingsForScope.ts) for scope analysis
-- [`bundle.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/bundle.ts) for creating evaluation contexts
-- The importance of module resolution via [`getSourceModule.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/getSourceModule.ts)
-
-**Caching Strategy**
-I emphasized multi-level caching (file content, AST, evaluation results) which Gemini mentions only briefly. This is critical for development experience.
-
-### Areas Where Gemini Provides Additional Value
-
-1. **Comprehensive Survey of Solutions**
-   - Gemini provides broader context by comparing Linaria, Vanilla Extract, Style9, and Tamagui
-   - Includes a useful comparison table of dynamic styling techniques
-
-2. **Theoretical Foundation**
-   - More academic treatment of CSS-in-JS evolution
-   - Clear explanation of why build-time compilation matters
-
-3. **Configuration Examples**
-   - Gemini provides a concrete `animus.config.js` example
-   - Clear delineation of configuration options
-
-### Disagreements and Clarifications
-
-#### 1. Dynamic Styling Complexity
-**Gemini's View**: CSS Variables solve most dynamic styling needs elegantly
-**My View**: While CSS Variables are powerful, Tamagui's implementation shows significant complexity in:
-- Managing variable scope and naming
-- Handling conditional application
-- Dealing with React Native where CSS Variables don't exist
-
-#### 2. Tree Shaking Feasibility
-**Gemini's View**: Component-level tree shaking is achievable with "comprehensive understanding of application's component usage"
-**My View**: Based on Tamagui's implementation, truly effective DCE for variants is extremely difficult because:
-- Dynamic prop construction makes static analysis nearly impossible
-- The "Style Dependency Graph" Tamagui uses is complex and imperfect
-- Starting with token-level DCE is more realistic
-
-#### 3. Development Mode Optimization
-**Gemini's View**: `disableExtraction` as a simple boolean flag
-**My View**: Tamagui's approach shows this needs more nuance:
-- Different optimization levels for development
-- Partial extraction for faster HMR
-- Balance between optimization and rebuild speed
-
-### Additional Findings Not Covered by Gemini
-
-1. **Error Recovery Strategies**
-   - Tamagui's [`extractHelpers.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/extractHelpers.ts) shows sophisticated error handling
-   - Graceful degradation when extraction fails
-   - Partial extraction success tracking
-
-2. **Debugging Infrastructure**
-   - [`createLogger.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/createLogger.ts) provides structured logging
-   - [`getPrefixLogs.ts`](https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/getPrefixLogs.ts) for contextual debugging
-   - Performance profiling hooks
-
-3. **Build Artifact Management**
-   - `.tamagui` directory structure and management
-   - Incremental compilation state tracking
-   - Cache invalidation strategies
-
-4. **Type Generation**
-   - Generating TypeScript definitions alongside extracted styles
-   - Maintaining type safety through compilation
-   - Ambient type declarations for optimized components
-
-### Recommendations Based on Combined Analysis
-
-1. **Start Conservative**
-   - Focus on web-only initially (despite Gemini's cross-platform optimism)
-   - Implement basic extraction before attempting variants/states
-   - Measure everything against runtime Animus performance
-
-2. **Leverage Animus's Builder Advantage**
-   - The enforced method order is a significant advantage over Tamagui's approach
-   - Design the compiler to deeply understand the builder semantics
-   - Use TypeScript's type information to guide optimization decisions
-
-3. **Plan for Complexity**
-   - Budget significant time for edge cases
-   - Build comprehensive test suites from day one
-   - Consider a plugin architecture early (not as Phase 4)
-
-4. **Focus on Developer Experience**
-   - Invest heavily in error messages and debugging tools
-   - Make the "happy path" truly happy
-   - Provide escape hatches for when the compiler gets it wrong
-
-The combination of both analyses provides a comprehensive understanding of the challenges and opportunities in building a CSS-in-JS compiler for Animus. While Gemini provides excellent theoretical grounding and broad context, the detailed examination of Tamagui's actual implementation reveals the practical complexities that must be addressed for a production-ready solution.
-
-## References and Resources
-
-### Primary Resources Examined
-
-1. **Tamagui Documentation**
-   - [Compiler Installation Guide](https://tamagui.dev/docs/intro/compiler-install)
-   - [LLM-friendly docs](https://tamagui.dev/llms.txt)
-   - [GitHub Repository](https://github.com/tamagui/tamagui)
-   - [Static Compiler Package](https://github.com/tamagui/tamagui/tree/main/code/compiler/static)
-
-2. **Tamagui Compiler Source Files** (All under `https://github.com/tamagui/tamagui/blob/main/code/compiler/static/src/extractor/`)
-   - Core extraction: `createExtractor.ts`, `extractToClassNames.ts`, `extractToNative.ts`
-   - AST handling: `babelParse.ts`, `evaluateAstNode.ts`, `literalToAst.ts`
-   - Evaluation: `createEvaluator.ts`, `getStaticBindingsForScope.ts`, `bundle.ts`
-   - Utilities: `hoistClassNames.ts`, `buildClassName.ts`, `extractHelpers.ts`
-   - Logging: `createLogger.ts`, `getPrefixLogs.ts`
-   - Module handling: `getSourceModule.ts`, `loadFile.ts`, `loadTamagui.ts`
-
-3. **Related CSS-in-JS Compilers** (mentioned in Gemini's analysis)
-   - [Linaria](https://github.com/callstack/linaria) - Zero-runtime CSS-in-JS
-   - [Vanilla Extract](https://vanilla-extract.style) - Type-safe CSS
-   - [Style9](https://github.com/johanholmerin/style9) - Atomic CSS-in-JS compiler
-   - [Panda CSS](https://panda-css.com) - Build-time CSS-in-JS with recipes
-
-### Technical Dependencies and Tools
-
-4. **Build Tools**
-   - [Babel](https://babeljs.io) - AST parsing and transformation
-   - [esbuild](https://esbuild.github.io) - Fast bundling and evaluation
-   - [@babel/parser](https://babeljs.io/docs/en/babel-parser) - JavaScript/TypeScript parsing
-   - [@babel/traverse](https://babeljs.io/docs/en/babel-traverse) - AST traversal
-
-5. **Related Animus Files**
-   - `/packages/core/CLAUDE.md` - Animus architecture documentation
-   - `/packages/core/docs/gemini-tamagui-compiler-learnings.md` - Gemini's analysis
-
-### Key Concepts and Patterns
-
-6. **Atomic CSS References**
-   - Facebook's CSS reduction case study (413KB → 74KB)
-   - CSS Custom Properties / CSS Variables for dynamic styling
-   - Source maps for debugging atomic classes
-
-7. **Compiler Architecture Patterns**
-   - AST visitor pattern for code transformation
-   - Sandboxed evaluation environments
-   - Multi-level caching strategies
-   - Platform-specific code generation
-
-### Session Context
-
-8. **Analysis Approach**
-   - Initial research on Tamagui compiler documentation
-   - Deep dive into Tamagui's source code structure
-   - Comparison with Gemini's theoretical analysis
-   - Focus on practical implementation details vs. theoretical possibilities
-
-9. **Key Insights Discovered**
-   - Tamagui uses Babel + esbuild hybrid approach
-   - Enforced method ordering in Animus builder is an advantage
-   - Cross-platform support requires fundamental architecture decisions
-   - Tree shaking for CSS is more complex than initially apparent
-
-### Future Research Areas
-
-10. **Additional Resources to Explore**
-    - Tamagui benchmarks and performance data
-    - React Native styling system internals
-    - CSS-in-JS runtime performance studies
-    - Webpack/Vite plugin architecture for integration
-
-This references section serves as a comprehensive index of all resources, links, and concepts discussed during the analysis of build-time CSS-in-JS compilation approaches for Animus.