# AGENTS.md - Guide for AI Coding Assistants This document provides context and guidelines for AI coding assistants working with the Valdi codebase. ## Overview Valdi is a cross-platform UI framework that compiles declarative TypeScript components to native views on iOS, Android, and macOS. Write your UI once, and it runs natively on multiple platforms without web views or JavaScript bridges. Valdi has been used in production at Snap for 8 years and is now available as open source under the MIT license. ### How Valdi Works The Valdi compiler takes TypeScript source files (using TSX/JSX syntax) and compiles them into `.valdimodule` files. These compiled modules are read by the Valdi runtime on each platform to render native views. **This is not TypeScript rendered in a WebView** - Valdi generates true native UI components. ## 🚨 AI Anti-Hallucination: This is NOT React! **CRITICAL**: Valdi uses TSX/JSX syntax but **is fundamentally different from React**. The most common AI error is suggesting React patterns that do not exist in Valdi. ### ❌ FORBIDDEN React Patterns (Do NOT use these) These React APIs **DO NOT EXIST** in Valdi and will cause compilation errors: ```typescript // ❌ WRONG - useState does not exist in Valdi const [count, setCount] = useState(0); // ❌ WRONG - useEffect does not exist in Valdi useEffect(() => { ... }, []); // ❌ WRONG - useContext does not exist in Valdi const value = useContext(MyContext); // ❌ WRONG - useMemo, useCallback, useRef do not exist const memoized = useMemo(() => ..., []); const callback = useCallback(() => ..., []); const ref = useRef(null); // ❌ WRONG - React.Component does not exist class MyComponent extends React.Component { ... } // ❌ WRONG - Functional components do not exist function MyComponent(props) { return ; } const MyComponent = () => ; ``` ### ⚠️ COMMON AI MISTAKES (Even advanced models make these errors!) **These patterns DO NOT EXIST in Valdi** but are commonly suggested by AI models: ```typescript // ❌ WRONG - markNeedsRender() does NOT exist class MyComponent extends Component { count = 0; handleClick() { this.count++; this.markNeedsRender(); // ERROR: This method doesn't exist! } } // ❌ WRONG - scheduleRender() exists but is DEPRECATED class MyComponent extends Component { count = 0; handleClick() { this.count++; this.scheduleRender(); // DEPRECATED: Use StatefulComponent with setState() instead } } // ❌ WRONG - onMount/onUpdate/onUnmount do NOT exist (React-like names) class MyComponent extends Component { onMount() { } // Should be: onCreate() onUpdate() { } // Should be: onViewModelUpdate(previousViewModel) onUnmount() { } // Should be: onDestroy() } // ❌ WRONG - this.props does NOT exist class MyComponent extends Component { onRender() { ; // Should be: this.viewModel.title } } // ❌ WRONG - this.context.get() does NOT exist class MyComponent extends Component { onRender() { const service = this.context.get(MyService); // This API doesn't exist! } } // ❌ WRONG - Returning JSX from onRender() class MyComponent extends Component { onRender() { return ; // onRender() returns void, not JSX! } } ``` **Why these errors happen**: AI models are heavily trained on React code, and Valdi's TSX syntax triggers incorrect React pattern suggestions. Always verify against actual Valdi APIs. ### ✅ CORRECT Valdi Patterns (Use these instead) Valdi uses a **class-based component model** with explicit lifecycle methods: ```typescript // ✅ CORRECT - Stateful Valdi component pattern import { StatefulComponent } from 'valdi_core/src/Component'; class MyComponent extends StatefulComponent { // State management via StatefulComponent state = { count: 0 }; // Lifecycle: Called when component is first created onCreate() { console.log('Component created'); } // Lifecycle: Called when viewModel changes onViewModelUpdate(previousViewModel: ViewModel) { console.log('ViewModel changed'); } // Lifecycle: Called before component is removed onDestroy() { console.log('Component destroying'); } // Required: Render method returns void (not JSX!) onRender() { // Note: onRender returns VOID, not JSX // JSX is written as a statement, not returned