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

package/docs/critical-findings.md

@@ -1,87 +0,0 @@
-# Critical Findings: Animus Framework Analysis
-
-Based on comprehensive analysis across competitive positioning, agent compatibility, and philosophical foundations, these are the critical findings about Animus:
-
-## 1. The Core Innovation: Progressive Type Narrowing
-
-**Finding**: Animus is the only CSS framework that uses class inheritance to enforce method calling order, creating a unique "progressive type narrowing" pattern.
-
-**Significance**: This transforms the infinite CSS possibility space into a finite state machine with clear transitions, making it uniquely suited for AI agent code generation.
-
-## 2. Constraints Are Actually Advantages
-
-**Finding**: What initially appeared as rigid constraints (enforced method ordering) are actually significant advantages for both static analysis and AI agent predictability.
-
-**Evidence**: 
-- Deterministic AST generation enables superior compile-time optimization
-- More amenable to static extraction than Panda CSS's flexible object API
-- Could potentially match or exceed Vanilla Extract's zero-runtime performance
-
-## 3. The `extend()` Escape Hatch Changes Everything
-
-**Finding**: The `extend()` method completely eliminates the perceived inflexibility by allowing all methods to be called in any order when needed.
-
-**Impact**: This provides "guided flexibility" - structure for 95% of cases, complete freedom for 5% edge cases.
-
-## 4. Perfect Human-AI Alignment
-
-**Finding**: Animus creates unprecedented alignment between human developer needs and AI agent capabilities.
-
-**How**:
-- Humans benefit from reduced cognitive load and self-documenting patterns
-- AI agents benefit from unambiguous intent expression and predictable patterns
-- Both benefit from having one canonical way to express styling intent
-
-## 5. Intent-Driven API Design
-
-**Finding**: Each Animus method isn't just "adding styles" - it's declaring semantic intent:
-- `.styles()` = "This is what it always looks like"
-- `.variant()` = "This is how it varies by design choice"
-- `.states()` = "This is how it responds to interaction"
-- `.props()` = "This is what can be dynamically controlled"
-
-**Significance**: This creates a shared language for intent between humans and machines.
-
-## 6. No Capability Sacrifice
-
-**Finding**: Despite the constraints, Animus retains full CSS capability:
-- Any valid CSS can be written in `.styles()`
-- All Emotion features (css prop, className, runtime styles) remain available
-- The constraints exist only at the API design level, not the capability level
-
-## 7. Superior Agent Compatibility Potential
-
-**Finding**: With proper investment, Animus could become the #2 framework for AI agents (score: 8.84/10), surpassed only by Vanilla Extract.
-
-**Key Advantages**:
-- Type Safety: 10/10 potential
-- API Predictability: 10/10 potential
-- Code Generation: 10/10 potential
-
-## 8. The Philosophy Is the Product
-
-**Finding**: Animus represents a new paradigm - "Constrain expression to enable communication, not capability to limit possibility."
-
-**Implication**: This philosophy could guide future API design in the AI age, where tools need to create structured languages for intent that both humans and machines can speak fluently.
-
-## 9. Current Limitations Are Solvable
-
-**Finding**: The main current limitations are:
-- Documentation (4/10) - Easily improved with investment
-- Community (1/10) - Natural growth over time
-- Runtime overhead - Solvable with static extraction
-
-**Note**: The core architecture has no fundamental limitations.
-
-## 10. This Is Actually Revolutionary (For AI Agents)
-
-**Personal Assessment**: After deep analysis and self-reflection, Animus IS revolutionary for AI agents because:
-- It's the only framework where the API itself enforces best practices
-- Invalid patterns are structurally impossible, not just discouraged
-- It transforms styling from an open-ended problem to a constraint satisfaction problem
-
-**The Ultimate Realization**: I would genuinely prefer working with Animus over more "flexible" alternatives. The pattern isn't just intellectually satisfying - it's practically optimal for how AI agents approach code generation.
-
-## Conclusion
-
-Animus demonstrates that the future of human-AI collaboration isn't about dumbing down APIs or limiting capabilities. It's about creating structured ways to express intent that make the right thing the obvious thing, while keeping everything else possible. This is a genuinely new approach that could reshape how we think about API design in the age of AI.

package/docs/gemini-tamagui-compiler-learnings.md

@@ -1,393 +0,0 @@
-# A Proposal for a Build-Time CSS-in-JS Compiler for the Animus Component Builder API
-
-## I. Introduction
-
-### The Evolution of CSS-in-JS
-
-The evolution of styling in modern web development has seen a significant shift towards CSS-in-JS solutions, driven by:
-- Better developer experience
-- Component-level encapsulation
-- Ability to leverage JavaScript's dynamism
-
-However, traditional runtime CSS-in-JS libraries introduce performance overhead due to style parsing and injection during component rendering. This has spurred the development of build-time, or "zero-runtime," CSS-in-JS compilers that extract styles into static CSS files during the build process.
-
-### Animus and Build-Time Compilation
-
-Animus, a library for "creating scalable and expressive component languages with CSS-in-JS", stands to gain substantially from a build-time compiler. This would:
-- Align with Animus's goal of expressiveness (JavaScript-based style definitions)
-- Ensure scalability and performance (optimized, static CSS output)
-- Draw inspiration from established solutions:
-  - [Tamagui](https://tamagui.dev)
-  - [Linaria](https://github.com/callstack/linaria)
-  - [Vanilla Extract](https://vanilla-extract.style)
-  - [Style9](https://github.com/johanholmerin/style9)
-
-### Core Objectives
-
-The proposed Animus compiler aims to:
-1. Parse styles defined via the Animus component builder API at build time
-2. Generate atomic CSS for optimal bundle size and reusability
-3. Handle dynamic styling and theming through CSS custom properties
-4. Deliver high-performance styling with superior developer experience
-5. Provide robust integration with modern build tools
-
-## II. Core Architectural Principles
-
-### A. Static Extraction of Styles
-
-#### The Foundation
-Build-time CSS-in-JS compilers shift style processing from the browser (runtime) to the developer's machine (build time).
-
-**Key Benefits:**
-- Browser downloads and parses CSS in parallel with JavaScript
-- Eliminates JavaScript execution cost for style computation
-- Enables advanced optimizations not possible at runtime
-
-**Implementation Examples:**
-- **Tamagui**: Pre-processes styles at build time, transforming verbose UI code into optimized atomic CSS
-- **Linaria**: Extracts CSS at build time, leaving no runtime component for style processing
-
-**Animus Requirements:**
-- Parse output of the component builder API (e.g., `.styles()`, `.variant()`, `.states()`)
-- Evaluate JavaScript expressions at build time (constants, theme variables)
-- Balance between expressive power and static analyzability
-
-### B. Abstract Syntax Tree (AST) Manipulation
-
-#### Core Technology
-AST manipulation is central to static extraction and code transformation.
-
-**Primary Tools:**
-1. **Babel**
-   - Comprehensive transformation API
-   - Visitor pattern for AST traversal
-   - Used by Linaria for transformations
-
-2. **esbuild**
-   - Exceptional speed
-   - Used by Tamagui for bundling and evaluation
-   - Good for auxiliary tasks
-
-**Animus Implementation Strategy:**
-
-A custom Babel plugin would:
-1. Identify Animus component builder API calls
-2. Extract style objects or template literals
-3. Evaluate embedded JavaScript expressions
-4. Generate unique class names
-5. Replace original definitions with class references
-6. Collect extracted styles for CSS generation
-
-### C. Generation of Atomic CSS
-
-#### The Atomic CSS Methodology
-Each CSS class performs a single, immutable styling task:
-```css
-.color-blue { color: blue; }
-.padding-10 { padding: 10px; }
-```
-
-**Benefits for Animus:**
-- **Reduced Bundle Size**: CSS size plateaus as components reuse atomic classes
-- **Improved Cacheability**: Highly reusable classes
-- **Predictable Styling**: Single-purpose classes reduce style conflicts
-
-**Real-World Results:**
-- Facebook's redesign: 413 KB → 74 KB gzipped CSS
-- Style9 and Tamagui both use atomic CSS generation
-
-**Implementation Process:**
-1. Break down style rules into property-value pairs
-2. Create deterministic class names for each pair
-3. Assign multiple atomic classes to components
-
-### D. Handling Dynamic Styles and Theming
-
-#### CSS Custom Properties Solution
-The most effective approach for zero-runtime dynamic styling uses CSS Variables.
-
-**Example Transformation:**
-```javascript
-// Input (Linaria-style)
-const Title = styled.h1`
-  color: ${props => (props.primary ? 'tomato' : 'black')};
-`;
-
-// Output CSS
-.title_xyz {
-  color: var(--title-color-xyz);
-}
-
-// Runtime: style="--title-color-xyz: tomato;"
-```
-
-#### Techniques for Dynamic Styling
-
-| Technique | Description | Example Libraries | Animus Implementation | Pros | Cons |
-|-----------|-------------|-------------------|----------------------|------|------|
-| **CSS Custom Properties via Props** | Styles use CSS variables; props update variables via inline styles | Linaria, Vanilla Extract, Style9 | Generate CSS with `var()`, set values inline | Highly flexible, minimal runtime | Requires CSS variable support |
-| **Pre-defined Variants** | Finite style variations; compiler generates CSS for each | Panda CSS, Vanilla Extract, Tamagui | `.variant()` generates classes like `.Button--size-small` | Zero runtime for definitions, type-safe | Less flexible for continuous values |
-| **Build-Time Theme Resolution** | Theme tokens resolved to values at compile time | Tamagui, Style9 | Replace `theme.colors.primary` with `#FF0000` | No runtime cost | Fixed at build time |
-| **Runtime Theme via CSS Variables** | Themes as CSS variable sets; switch by updating root variables | Vanilla Extract | Use `var(--animus-primary-color)` everywhere | Dynamic theme switching | More setup required |
-
-## III. Compiler Toolchain and Implementation
-
-### A. Leveraging Babel or esbuild
-
-#### Tool Selection
-
-**Babel**
-- Rich plugin ecosystem
-- Visitor pattern ideal for AST manipulation
-- Best for primary transformation phase
-
-**esbuild**
-- Exceptional speed
-- Good for bundling and evaluation tasks
-- Used by Tamagui for certain operations
-
-**Hybrid Approach for Animus:**
-- Babel for main AST traversal and style extraction
-- esbuild for evaluating theme files and utilities
-
-### B. The Evaluator Component
-
-#### Purpose
-Evaluate JavaScript expressions within styles at compile time.
-
-#### Capabilities
-
-1. **Constant Folding**
-   - `2 * 8` → `16`
-   - Simple arithmetic evaluation
-
-2. **Variable Resolution**
-   - Look up imported constants
-   - Access theme values from whitelisted modules
-
-3. **Function Calls**
-   - Pure utility functions only
-   - e.g., `darken(colors.primary, 0.1)`
-
-4. **Sandboxing**
-   - Isolated evaluation environment
-   - Prevent arbitrary code execution
-
-#### Limitations
-- Cannot handle runtime state (props, browser APIs)
-- Dynamic aspects must use CSS variables
-
-### C. Configuration and Integration
-
-#### Key Configuration Options
-
-```javascript
-// animus.config.js
-{
-  components: ['src/components/**/*'],      // Where to find components
-  themePath: './src/theme.ts',             // Theme configuration
-  importsWhitelist: ['constants.js'],      // Safe to evaluate
-  outputDir: '.animus',                    // Build artifacts
-  atomicCss: true,                         // Enable atomic CSS
-  disableExtraction: false                 // Dev mode flag
-}
-```
-
-#### Bundler Integration
-- Webpack: Custom loader
-- Vite: Transform plugin
-- Rspack: Compatible with webpack loaders
-
-## IV. Advanced Optimizations
-
-### A. Tree Shaking and Dead Code Elimination
-
-#### Style-Level Tree Shaking
-- Analyze component usage across application
-- Remove unused variants and states
-- Track style dependency graphs
-
-**Implementation Complexity:**
-- Requires whole-application analysis
-- Must track dynamic prop usage
-- Start with simpler token-level DCE
-
-#### JavaScript Integration
-- Generate tree-shakeable JavaScript
-- Mark CSS imports with proper `sideEffects`
-- Use ES module syntax throughout
-
-### B. Minimizing Runtime Overhead
-
-#### CSS Variables Approach
-```javascript
-// Minimal runtime for dynamic styles
-element.style.setProperty('--my-color', newColor);
-```
-
-#### Conditional Classes
-- Compile-time string concatenation
-- No runtime style object creation
-- Simple className application logic
-
-### C. Cross-Platform Optimization (Tamagui-Inspired)
-
-#### Platform-Specific Output
-- **Web**: Generate CSS files
-- **React Native**: JavaScript style objects
-
-#### Compiler Requirements
-- Understand platform differences
-- Transform property names and values
-- Handle layout system variations
-
-### D. Additional Optimizations
-
-1. **CSS Property Sorting**: Improve compression
-2. **Shorthand Handling**: Expand for atomicity
-3. **Media Query Optimization**: Collapse and reorder
-
-## V. Developer Experience Considerations
-
-### A. API Design
-
-#### Animus Builder Pattern Advantages
-```javascript
-// Structured, analyzable API
-const Button = animus
-  .styles({ padding: '10px' })
-  .variant({ 
-    prop: 'size',
-    variants: { small: {}, large: {} }
-  })
-  .states({ hover: {} })
-  .asElement('button');
-```
-
-**Benefits:**
-- Clear method semantics
-- Easier static analysis
-- Structured input for compiler
-
-### B. Debugging Support
-
-#### Essential Features
-1. **High-Quality Source Maps**
-   - Link atomic classes to source
-   - Enable browser DevTools inspection
-
-2. **Clear Error Messages**
-   - Pinpoint exact source location
-   - Actionable error descriptions
-
-### C. Build Tool Integration
-
-#### Requirements
-- Fast recompilation
-- Reliable HMR support
-- TypeScript integration
-- Editor autocompletion
-
-## VI. Animus API Integration
-
-### A. Compiler as API Backend
-
-The compiler processes structured builder definitions:
-
-```javascript
-// Example Animus API usage
-Animus.defineComponent('MyStyledButton')
-  .baseStyles({
-    padding: '10px 15px',
-    borderRadius: '4px',
-  })
-  .variants({
-    intent: {
-      primary: { backgroundColor: theme.colors.primary },
-      secondary: { backgroundColor: theme.colors.secondary },
-    },
-    size: {
-      small: { fontSize: '12px' },
-      large: { fontSize: '16px' },
-    }
-  })
-  .dynamicStyles(props => ({
-    opacity: props.disabled ? 0.5 : 1,
-  }))
-  .build();
-```
-
-**Compiler Processing:**
-- `.baseStyles()` and `.variants()` → Static extraction
-- `.dynamicStyles()` → CSS variable generation
-
-### B. Preserving Expressiveness
-
-The compiler must:
-- Correctly interpret all API semantics
-- Handle complex variant definitions
-- Support responsive styles
-- Resolve theme tokens appropriately
-
-### C. Developer Workflow
-
-1. Define components using Animus API
-2. Build process invokes compiler automatically
-3. Compiler extracts and optimizes styles
-4. Bundler processes results
-5. No manual intervention required
-
-## VII. Implementation Roadmap
-
-### Phase 1: Core Functionality
-- Parse basic Animus API calls
-- Implement atomic CSS generation
-- Basic theme token resolution
-- Simple Babel plugin
-
-### Phase 2: Dynamic Styling
-- CSS Custom Properties support
-- Runtime theme switching
-- Expression evaluation
-- Enhanced source maps
-
-### Phase 3: Advanced Features
-- Dead code elimination
-- Media query optimization
-- TypeScript enhancements
-- HMR improvements
-
-### Phase 4: Extended Capabilities (Optional)
-- Cross-platform support
-- Plugin architecture
-- Community extensions
-
-## VIII. Key Challenges and Considerations
-
-### Technical Challenges
-1. **Static Analysis Complexity**: Reliable JavaScript evaluation
-2. **Compiler Performance**: Fast build times for large projects
-3. **Edge Case Handling**: Comprehensive CSS/JS coverage
-4. **Ecosystem Evolution**: Keeping pace with frontend changes
-
-### Long-Term Considerations
-- Ongoing maintenance requirements
-- Community building and documentation
-- Integration with design tools
-- Visual regression testing support
-
-## IX. Conclusion
-
-A dedicated build-time CSS-in-JS compiler represents a strategic imperative for Animus. By combining:
-- Static extraction and AST manipulation
-- Atomic CSS generation
-- Intelligent dynamic styling via CSS Variables
-- Deep integration with the builder API
-
-The Animus compiler can deliver on the promise of "scalable and expressive component languages" without runtime performance penalties. A phased implementation approach, strong focus on developer experience, and commitment to ongoing maintenance will position Animus as a leading solution for next-generation component development.
-
----
-
-## References
-
-[1-29] *[References omitted for brevity but preserved in structure]*