{"owner":"Snapchat","repo":"Valdi","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".cursorrules"],"skills":{"AGENTS.md":"# AGENTS.md - Guide for AI Coding Assistants\n\nThis document provides context and guidelines for AI coding assistants working with the Valdi codebase.\n\n## Overview\n\nValdi 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.\n\nValdi has been used in production at Snap for 8 years and is now available as open source under the MIT license.\n\n### How Valdi Works\n\nThe 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.\n\n## 🚨 AI Anti-Hallucination: This is NOT React!\n\n**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.\n\n### ❌ FORBIDDEN React Patterns (Do NOT use these)\n\nThese React APIs **DO NOT EXIST** in Valdi and will cause compilation errors:\n\n```typescript\n// ❌ WRONG - useState does not exist in Valdi\nconst [count, setCount] = useState(0);\n\n// ❌ WRONG - useEffect does not exist in Valdi \nuseEffect(() => { ... }, []);\n\n// ❌ WRONG - useContext does not exist in Valdi\nconst value = useContext(MyContext);\n\n// ❌ WRONG - useMemo, useCallback, useRef do not exist\nconst memoized = useMemo(() => ..., []);\nconst callback = useCallback(() => ..., []);\nconst ref = useRef(null);\n\n// ❌ WRONG - React.Component does not exist\nclass MyComponent extends React.Component { ... }\n\n// ❌ WRONG - Functional components do not exist\nfunction MyComponent(props) { return ; }\nconst MyComponent = () => ;\n```\n\n### ⚠️ COMMON AI MISTAKES (Even advanced models make these errors!)\n\n**These patterns DO NOT EXIST in Valdi** but are commonly suggested by AI models:\n\n```typescript\n// ❌ WRONG - markNeedsRender() does NOT exist\nclass MyComponent extends Component {\n count = 0;\n handleClick() {\n this.count++;\n this.markNeedsRender(); // ERROR: This method doesn't exist!\n }\n}\n\n// ❌ WRONG - scheduleRender() exists but is DEPRECATED\nclass MyComponent extends Component {\n count = 0;\n handleClick() {\n this.count++;\n this.scheduleRender(); // DEPRECATED: Use StatefulComponent with setState() instead\n }\n}\n\n// ❌ WRONG - onMount/onUpdate/onUnmount do NOT exist (React-like names)\nclass MyComponent extends Component {\n onMount() { } // Should be: onCreate()\n onUpdate() { } // Should be: onViewModelUpdate(previousViewModel)\n onUnmount() { } // Should be: onDestroy()\n}\n\n// ❌ WRONG - this.props does NOT exist\nclass MyComponent extends Component {\n onRender() {\n ; // Should be: this.viewModel.title\n }\n}\n\n// ❌ WRONG - this.context.get() does NOT exist\nclass MyComponent extends Component {\n onRender() {\n const service = this.context.get(MyService); // This API doesn't exist!\n }\n}\n\n// ❌ WRONG - Returning JSX from onRender()\nclass MyComponent extends Component {\n onRender() {\n return ; // onRender() returns void, not JSX!\n }\n}\n```\n\n**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.\n\n### ✅ CORRECT Valdi Patterns (Use these instead)\n\nValdi uses a **class-based component model** with explicit lifecycle methods:\n\n```typescript\n// ✅ CORRECT - Stateful Valdi component pattern\nimport { StatefulComponent } from 'valdi_core/src/Component';\n\nclass MyComponent extends StatefulComponent {\n // State management via StatefulComponent\n state = { count: 0 };\n \n // Lifecycle: Called when component is first created\n onCreate() {\n console.log('Component created');\n }\n \n // Lifecycle: Called when viewModel changes\n onViewModelUpdate(previousViewModel: ViewModel) {\n console.log('ViewModel changed');\n }\n \n // Lifecycle: Called before component is removed\n onDestroy() {\n console.log('Component destroying');\n }\n \n // Required: Render method returns void (not JSX!)\n onRender() {\n // Note: onRender returns VOID, not JSX\n // JSX is written as a statement, not returned\n \n \n ;\n }\n}\n\n// For components without state, use Component\nimport { Component } from 'valdi_core/src/Component';\n\nclass SimpleComponent extends Component {\n onRender() {\n ;\n }\n}\n```\n\n### Key Valdi Concepts\n\n1. **State Management**: Use `StatefulComponent` with `setState()`, not `useState`\n2. **Props Access**: Use `this.viewModel`, not `this.props`\n3. **Re-rendering**: `setState()` automatically triggers re-render\n4. **Lifecycle Methods**: `onCreate()`, `onViewModelUpdate()`, `onDestroy()`\n5. **Dependency Injection**: Use `createProviderComponent()` + `withProviders()` HOC pattern\n6. **Return Type**: `onRender()` returns `void`, not JSX (JSX is written as a statement)\n7. **Component Definition**: Always use `class` extending `Component` or `StatefulComponent`, never functions\n\n### State Management with StatefulComponent\n\n```typescript\n// ✅ CORRECT - Use StatefulComponent with setState()\nclass Counter extends StatefulComponent {\n state = { count: 0 };\n \n handleClick = () => {\n this.setState({ count: this.state.count + 1 }); // Automatically triggers re-render\n };\n \n onRender() {\n ;\n }\n}\n\n// ❌ WRONG - Using markNeedsRender() doesn't exist\nhandleClick() {\n this.count++;\n this.markNeedsRender(); // ERROR: markNeedsRender is not a function!\n}\n```\n\n### Provider Pattern (Not useContext)\n\n```typescript\n// ✅ CORRECT - Valdi provider pattern\nimport { createProviderComponentWithKeyName } from 'valdi_core/src/provider/createProvider';\nimport { withProviders } from 'valdi_core/src/provider/withProviders';\nimport { ProvidersValuesViewModel } from 'valdi_core/src/provider/withProviders';\nimport { Component } from 'valdi_core/src/Component';\n\n// Step 1: Define service\nclass MyService {\n getData() { return 'data'; }\n}\n\n// Step 2: Create provider component\nconst MyServiceProvider = createProviderComponentWithKeyName('MyServiceProvider');\n\n// Step 3: Provide value in parent\nclass ParentComponent extends Component {\n private service = new MyService();\n \n onRender() {\n \n \n ;\n }\n}\n\n// Step 4: Consume in child - extend viewModel from ProvidersValuesViewModel\ninterface ChildViewModel extends ProvidersValuesViewModel<[MyService]> {\n // other props if needed\n}\n\nclass ChildComponent extends Component {\n onRender() {\n // Access provider via viewModel.providersValues\n const [myService] = this.viewModel.providersValues;\n const data = myService.getData();\n \n ;\n }\n}\n\n// Step 5: Wrap component with provider HOC\nconst ChildComponentWithProvider = withProviders(MyServiceProvider)(ChildComponent);\n```\n\n## Key Technologies\n\n- **Valdi**: TypeScript-based declarative UI framework that compiles to native code\n- **TSX/JSX**: React-like syntax for declarative UI (but this is **NOT React** - Valdi compiles to native)\n- **Bazel**: Primary build system for reproducible builds\n- **TypeScript/JavaScript**: Application and UI layer\n- **C++**: Cross-platform runtime and layout engine\n- **Swift**: Compiler implementation\n- **Kotlin/Java**: Android runtime\n- **Objective-C/C++**: iOS runtime\n- **Flexbox**: Layout system with automatic RTL support\n\n## Directory Structure\n\n### `/apps/`\nExample applications demonstrating Valdi features:\n- `helloworld/` - Basic getting started example\n- `valdi_gpt/` - More complex demo application\n- `benchmark/` - Performance testing app\n- `*_example/` - Various feature demonstrations (navigation, managed context, etc.)\n\n### `/compiler/`\nThe Valdi compiler and companion tools:\n- `compiler/` - Swift-based main compiler that transforms TypeScript to native code\n- `companion/` - TypeScript-based companion tools for the build process\n\n### `/valdi/`, `/valdi_core/`, `/valdi_protobuf/`\nCore Valdi runtime implementations:\n- Platform-specific implementations (iOS, Android, macOS)\n- Cross-platform C++ core with layout engine\n- Protobuf integration for efficient serialization\n- Generated code from Djinni interfaces for cross-language bindings\n\n### `/src/valdi_modules/`\nCore Valdi TypeScript modules and standard library:\n- `valdi_core/` - Core component and runtime APIs (Component, Provider, etc.)\n- `valdi_protobuf/` - Protobuf serialization support\n- `valdi_http/` - HTTP client module (promise-based network requests)\n- `valdi_navigation/` - Navigation utilities\n- `valdi_rxjs/` - RxJS integration for reactive programming\n- `persistence/` - Key-value storage with encryption and TTL support\n- `drawing/` - Managed context for graphics and drawing operations\n- `file_system/` - Low-level file I/O operations\n- `valdi_web/`, `web_renderer/` - Web runtime implementations\n- `foundation/`, `coreutils/` - Common utilities (arrays, Base64, LRU cache, UUID, etc.)\n- `worker/` - Worker service support for background JavaScript execution\n- Other standard library modules\n\n### `/npm_modules/`\nNode.js packages:\n- `cli/` - Command-line interface for Valdi development (`valdi` command)\n- `eslint-plugin-valdi/` - ESLint rules for Valdi code\n\n### `/bzl/`\nBazel build rules and macros for the Valdi build system\n\n### `/docs/`\nComprehensive documentation:\n- Codelabs for learning\n- API documentation\n- Setup and installation guides\n\n### `/third-party/`\nExternal dependencies and their Bazel build configurations\n\n## Important Conventions\n\n### Build System\n\n1. **Bazel is the primary build system** - Use `bazel build`, `bazel test`, etc.\n - Note: `bzl` is an alias for `bazel` - both commands work interchangeably\n - The CLI looks for `bazel`, `bzl`, or `bazelisk` executables\n2. **MODULE.bazel and WORKSPACE** - Bazel module system is in use\n3. **Cross-platform builds** - Code must work on iOS, Android, Linux, and macOS\n4. **Platform transitions** - Build rules handle platform-specific compilation automatically\n\n### Code Style\n\n1. **C++**: Follow the project's C++ style conventions\n2. **TypeScript**: Use ESLint with Valdi-specific rules\n3. **Swift**: Follow Swift conventions for compiler code\n4. **Kotlin**: Follow Kotlin conventions for Android runtime\n5. **Indentation**: Always match existing file conventions\n\n### Testing\n\n1. Test files are typically in `test/` subdirectories\n2. Run tests with `bazel test //path/to:target`\n3. All changes should include appropriate tests\n4. Use the built-in Valdi testing framework for component tests\n\n### Generated Code\n\n1. **Djinni interfaces** - Some code is generated from `.djinni` files for cross-language bindings\n2. **Don't modify generated code** - Change the source `.djinni` file instead\n3. Generated files are typically in `generated-src/` directories\n\n## Common Tasks\n\n### Building the Compiler\n\n```bash\n# Build the compiler\nbazel build //compiler/compiler:valdi-compiler\n\n# After building, move the binary to bin/ directory for use by the toolchain\n# The exact path depends on your platform (macos/linux and architecture)\n# Example for macOS ARM64:\ncp bazel-bin/compiler/compiler/valdi-compiler bin/compiler/macos/arm64/\n```\n\nNote: Pre-built compiler binaries are checked in to `/bin/compiler/` for convenience, but you can build and use your own version during development.\n\n### Running Tests\n\n```bash\n# Run all tests\nbazel test //...\n\n# Run specific test\nbazel test //valdi/test:some_test\n```\n\n### Installing and Using the CLI\n\n```bash\ncd npm_modules/cli\n\n# Install the valdi command-line tool globally\nnpm run cli:install\n\n# After installation, use the CLI\nvaldi --help\n```\n\n### Creating New Examples\n\nUse existing apps in `/apps/` as templates. Each app needs:\n- `BUILD.bazel` file defining build targets\n- `package.json` for npm dependencies\n- Entry point file (typically `.tsx` for TypeScript JSX)\n- Source files in `src/` directory\n\n## Important Files to Review\n\n- `/README.md` - Main project documentation\n- `/docs/INSTALL.md` - Installation and setup instructions\n- `/docs/DEV_SETUP.md` - Developer environment setup\n- `/CONTRIBUTING.md` - Contribution guidelines\n- `/CODE_OF_CONDUCT.md` - Community standards\n- `/LICENSE` - MIT License information\n\n## Toolchain Locations\n\nPre-built binaries are stored in `/bin/`:\n- Compiler binaries for Linux/macOS\n- SQLite compiler for data persistence\n- Other build tools\n\n## Platform-Specific Notes\n\n### iOS\n- Uses Objective-C++ bridge layer for TypeScript-native communication\n- Metal for GPU-accelerated rendering\n- See `/valdi/src/ios/` for platform implementations\n\n### Android\n- Kotlin/Java implementations\n- Uses Android NDK for C++ integration\n- See `/valdi/src/android/` for platform implementations\n\n### Web\n- TypeScript runtime for web targets\n- **Custom views**: Use `webClass` attribute on ``. Factories are registered via `webPolyglotViews` exports and looked up in `WebViewClassRegistry`. Factories receive a container DOM element and can return a `changeAttribute(name, value)` handler.\n- **`web_deps` must be a `ts_project`** — never use `filegroup` for web code. Always use typed TypeScript with `ts_project` from `@aspect_rules_ts`.\n- See `/src/valdi_modules/src/valdi/web_renderer/` for web implementation\n\n### Desktop (macOS)\n- Native macOS implementation using AppKit (`NSView`, `NSWindow`)\n- **Platform type**: `PlatformTypeMacOS` (3) — distinct from iOS (2)\n- **Class name resolution**: macOS falls through to iOS class names for both built-in elements and custom views. This means `iosClass` works on macOS without specifying `macosClass`.\n- **SnapDrawing**: Shares iOS layer classes (registered under iOS names like `SCValdiView`, `SCValdiLabel`)\n- See `/valdi/src/valdi/macos/` for desktop implementations\n\n## Development Workflow\n\n1. **Setup environment** - Follow `/docs/DEV_SETUP.md`\n2. **Make changes** in appropriate directory\n3. **Build locally** with Bazel\n4. **Run tests** to verify changes\n5. **Run linters** with appropriate tools\n6. **Test on multiple platforms** - Changes may affect iOS, Android, and web\n7. **Update documentation** if adding features\n\n## Common Patterns\n\n### Component Development\n\nValdi components follow a class-based pattern with lifecycle methods:\n\n```typescript\nimport { Component } from 'valdi_core/src/Component';\n\nclass MyComponent extends Component {\n // Required: Render the component's UI\n onRender() {\n \n \n ;\n }\n \n // Optional lifecycle methods:\n // onCreate() - Called when component is first created\n // onDestroy() - Called before component is removed\n // onViewModelUpdate(previousViewModel) - Called when viewModel updates\n}\n```\n\n**Key Valdi Concepts:**\n- Components use TSX/JSX syntax (similar to React but compiles to native)\n- State management via component properties\n- Event handlers for user interactions\n- Flexbox layout system for positioning\n\n### Native Polyglot Modules\n\nFor performance-critical code or platform-specific views, write native implementations with TypeScript bindings:\n- Define interfaces in TypeScript\n- Specify polyglot modules in build files (BUILD.bazel)\n- Implement in C++, Swift, Kotlin, or Objective-C\n- Compiler generates type-safe bindings\n\n### Custom Views (``)\n\nCustom views inject native platform views into Valdi components. Use platform-specific class attributes:\n\n```tsx\n\n```\n\n**Platform resolution rules:**\n- **macOS falls through to iOS**: If `macosClass` is not specified, `iosClass` is used. This applies both in TypeScript (`JSXBootstrap.ts`) and C++ (`ViewNode.cpp`).\n- **Built-in elements** (view, label, image, scroll, etc.) always resolve to iOS class names on macOS (e.g., `SCValdiView`, `SCValdiLabel`).\n- **Web** uses `webClass` to look up a factory in `WebViewClassRegistry`. Factories can return a `changeAttribute(name, value)` handler to receive attribute updates.\n- See `/docs/docs/native-customviews.md` for full examples on all platforms.\n\n**Bazel dependencies for custom views:**\n\n```python\nload(\"@aspect_rules_ts//ts:defs.bzl\", \"ts_project\")\n\n# Web views MUST be a ts_project, never a filegroup.\n# - transpiler = \"tsc\" is required (aspect_rules_ts does not default it)\n# - Provide a dedicated web/tsconfig.json (standalone, not extending the module tsconfig)\n# - If web code imports .d.ts from the module's src/, include \"src/**/*.d.ts\" in srcs\n# - Exclude \"web/**/*.d.ts\" from srcs to avoid TS5055 collisions with composite: true\nts_project(\n name = \"my_web_views\",\n srcs = glob([\n \"web/**/*.ts\",\n \"src/**/*.d.ts\", # only if web code imports module type declarations\n ], exclude = [\n \"web/**/*.d.ts\", # avoid TS5055 output collision with composite\n ]),\n allow_js = True,\n composite = True,\n transpiler = \"tsc\",\n tsconfig = \"web/tsconfig.json\",\n)\n\nvaldi_module(\n name = \"my_module\",\n srcs = [...],\n ios_deps = [\":my_ios_views\"], # objc_library\n macos_deps = [\":my_macos_views\"], # objc_library (or omit to share ios_deps)\n android_deps = [\":my_android_views\"], # valdi_android_library\n web_deps = [\":my_web_views\"], # ts_project (never filegroup)\n)\n```\n\n**Web `tsconfig.json`** — the `web/tsconfig.json` should be standalone (not extending the module-level tsconfig) since `ts_project` compiles independently:\n\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2016\",\n \"module\": \"commonjs\",\n \"strict\": true,\n \"composite\": true,\n \"allowJs\": true,\n \"lib\": [\"dom\", \"ES2019\"]\n }\n}\n```\n\n### Worker Services\n\nFor background processing:\n- Create worker services that run in separate JavaScript contexts\n- Communicate via message passing\n- See `/docs/docs/advanced-worker-service.md`\n\n### Component Context & Native Integration\n\nPass data and services between native code and Valdi:\n- **Component Context**: Pass native data to Valdi components when instantiating them\n- **Native Annotations**: Use TypeScript comments to export components to native platforms\n- **Example**: `@Component` and `@ExportModel` annotations define how components are exposed\n- See `/docs/docs/native-annotations.md` and `/docs/docs/native-context.md`\n\n### Provider Pattern\n\nDependency injection for Valdi components:\n- Use `Provider` to pass services and data down the component tree\n- Similar to React Context but Valdi-specific\n- Enables loose coupling and testability\n- See `/docs/docs/advanced-provider.md`\n\n### Localization\n\nString management for multi-language support:\n- String resources defined in JSON files\n- Automatic locale switching based on device settings\n- See `/docs/docs/advanced-localization.md`\n\n## Common Pitfalls\n\n1. **Don't skip cross-platform testing** - Changes affect multiple platforms\n2. **Don't modify generated code** - Change the source instead\n3. **Don't ignore Bazel cache** - Use `bazel clean` sparingly\n4. **Don't hardcode platform assumptions** - Use appropriate abstractions\n5. **Performance matters** - Valdi is a UI framework where rendering performance is critical\n\n## Architecture Overview\n\n### Compilation Pipeline\n\n1. **TypeScript source** → Valdi compiler (Swift)\n2. **Compiler output** → Platform-specific code generation\n3. **Native builds** → iOS/Android/macOS apps\n4. **Runtime** → C++ layout engine + platform-specific renderers\n\n### Hot Reload System\n\n- Valdi includes instant hot reload during development\n- Changes to TypeScript components are reflected in milliseconds\n- No need to recompile native code for UI changes\n- Use `valdi hotreload` command\n\n### Performance Features\n\n- **View recycling** - Global view pooling reuses native views\n- **Viewport-aware rendering** - Only visible views are inflated\n- **Independent component rendering** - Components update without parent re-renders\n- **Optimized layout** - C++ layout engine with minimal marshalling\n\n## Key Points for AI Assistants\n\n1. **Cross-platform compatibility is critical** - Test implications across iOS, Android, and web\n2. **Bazel is non-negotiable** - Don't suggest alternative build systems\n3. **Generated code exists** - Some files are auto-generated from Djinni interfaces\n4. **Performance is paramount** - This is a production UI framework used at scale\n5. **Follow existing patterns** - This is a mature codebase with established conventions\n6. **TypeScript is compiled** - Unlike React Native, this doesn't run JavaScript at runtime\n7. **Native integration is deep** - Direct access to platform APIs via polyglot modules\n\n## Quick Reference Commands\n\n### For App Development\n\n```bash\n# Install Valdi CLI (first time)\ncd npm_modules/cli && npm run cli:install\n\n# Setup development environment\nvaldi dev_setup\n\n# Bootstrap a new project\nmkdir my_project && cd my_project\nvaldi bootstrap\n\n# Install dependencies and build\nvaldi install ios # or android\n\n# Start hot reload\nvaldi hotreload\n```\n\n### For Platform Development (Contributing to Valdi)\n\n```bash\n# Setup development environment (first time)\nscripts/dev_setup.sh\n\n# Build everything\nbazel build //...\n\n# Run all tests\nbazel test //...\n\n# Build and run example app\ncd apps/helloworld\nvaldi install ios # or android\n```\n\n## Testing Framework\n\nValdi includes a built-in testing framework:\n- Component-level unit tests\n- Mock services and dependencies\n- See `/docs/docs/workflow-testing.md`\n\n```typescript\nimport { TestRunner } from 'valdi_core/src/TestRunner';\n\nTestRunner.test('component renders correctly', () => {\n const component = new MyComponent();\n // Test assertions\n});\n```\n\n## Debugging\n\n- **VSCode integration** - Full debugging support with breakpoints\n- **Hermes debugger** - For JavaScript debugging\n- **Native debugging** - Xcode/Android Studio for platform-specific issues\n- See `/docs/docs/workflow-hermes-debugger.md`\n\n## Related Documentation\n\nFor more details on specific topics, see the `/docs/` directory:\n- Architecture overview\n- API reference\n- Codelabs for hands-on learning\n- Advanced features (animations, gestures, protobuf)\n- Native bindings and custom views\n\n## AI Skills (Context for AI Agents)\n\nThe Valdi CLI ships context files (\"skills\") that give AI agents accurate knowledge about Valdi APIs, patterns, and conventions. Install them once to reduce hallucinations:\n\n```bash\nnpm install -g @snap/valdi\nvaldi skills install # installs all skills for detected AI agents\n# or install by category:\nvaldi skills install --category=client # module development skills\nvaldi skills install --category=framework # framework internals skills\n```\n\nSkills are bundled inside the npm package — no network access required after install.\n\n## Contributing\n\nThis is an open-source project. When contributing:\n1. Follow the style guides\n2. Include tests for new features\n3. Update documentation\n4. Ensure cross-platform compatibility\n5. See `CONTRIBUTING.md` for full guidelines\n\n## Community & Support\n\n- **Documentation**: Comprehensive docs in `/docs/` directory\n- **Examples**: Working examples in `/apps/` directory\n- **Issues**: Report bugs and request features via GitHub issues\n- **Discussions**: Ask questions and share ideas in GitHub Discussions\n\n---\n\n*This document is intended for AI coding assistants to quickly understand the structure and conventions of the Valdi codebase. For human developers, please refer to the main README.md and comprehensive documentation in `/docs/`.*\n",".cursorrules":"# Valdi Open Source - Cursor Rules\n\n## ⚠️ Open Source Project\n\nThis is an open source project. Never commit secrets, API keys, or proprietary information.\n\n## 🚨 CRITICAL: This is NOT React!\n\nValdi uses TSX/JSX syntax but is **fundamentally different from React**. \n\n**Common AI mistakes:**\n- ❌ Suggesting `useState`, `useEffect`, `useContext` (don't exist!)\n- ❌ Functional components (don't exist!)\n- ❌ `this.props` (should be `this.viewModel`)\n- ❌ `markNeedsRender()`, `onMount()`, `onUpdate()` (wrong names/don't exist!)\n\n**Correct Valdi:**\n- ✅ `class MyComponent extends StatefulComponent`\n- ✅ `state = {}` + `this.setState()`\n- ✅ `this.viewModel` for props\n- ✅ `onCreate()`, `onViewModelUpdate()`, `onDestroy()` lifecycle\n\n## 📁 Context-Specific Rules\n\nCursor automatically loads additional rules based on where you're working:\n\n| Working In | See |\n|-----------|-----|\n| TypeScript/TSX components | `.cursor/rules/typescript-tsx.md` |\n| Swift compiler | `.cursor/rules/compiler.md` |\n| C++ runtime | `.cursor/rules/cpp-runtime.md` |\n| Android (Kotlin) | `.cursor/rules/android.md` |\n| iOS (Objective-C) | `.cursor/rules/ios.md` |\n| Bazel files | `.cursor/rules/bazel.md` |\n| Tests | `.cursor/rules/testing.md` |\n\n**→ Check `.cursor/rules/README.md` for the full list**\n\n## Quick Commands\n\n```bash\nbazel build //... # Build everything\nbazel test //... # Run all tests\nvaldi install ios # Build & install iOS app\nvaldi hotreload # Start hot reload\n```\n\n## More Information\n\n- **Comprehensive guide**: `/AGENTS.md` (621 lines)\n- **AI tooling**: `/docs/docs/ai-tooling.md`\n- **Support**: `/SUPPORT.md`\n- **Discussions**: https://github.com/Snapchat/Valdi/discussions\n- **Issues**: https://github.com/Snapchat/Valdi/issues\n"},"files":{"AGENTS.md":"# AGENTS.md - Guide for AI Coding Assistants\n\nThis document provides context and guidelines for AI coding assistants working with the Valdi codebase.\n\n## Overview\n\nValdi 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.\n\nValdi has been used in production at Snap for 8 years and is now available as open source under the MIT license.\n\n### How Valdi Works\n\nThe 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.\n\n## 🚨 AI Anti-Hallucination: This is NOT React!\n\n**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.\n\n### ❌ FORBIDDEN React Patterns (Do NOT use these)\n\nThese React APIs **DO NOT EXIST** in Valdi and will cause compilation errors:\n\n```typescript\n// ❌ WRONG - useState does not exist in Valdi\nconst [count, setCount] = useState(0);\n\n// ❌ WRONG - useEffect does not exist in Valdi \nuseEffect(() => { ... }, []);\n\n// ❌ WRONG - useContext does not exist in Valdi\nconst value = useContext(MyContext);\n\n// ❌ WRONG - useMemo, useCallback, useRef do not exist\nconst memoized = useMemo(() => ..., []);\nconst callback = useCallback(() => ..., []);\nconst ref = useRef(null);\n\n// ❌ WRONG - React.Component does not exist\nclass MyComponent extends React.Component { ... }\n\n// ❌ WRONG - Functional components do not exist\nfunction MyComponent(props) { return ; }\nconst MyComponent = () => ;\n```\n\n### ⚠️ COMMON AI MISTAKES (Even advanced models make these errors!)\n\n**These patterns DO NOT EXIST in Valdi** but are commonly suggested by AI models:\n\n```typescript\n// ❌ WRONG - markNeedsRender() does NOT exist\nclass MyComponent extends Component {\n count = 0;\n handleClick() {\n this.count++;\n this.markNeedsRender(); // ERROR: This method doesn't exist!\n }\n}\n\n// ❌ WRONG - scheduleRender() exists but is DEPRECATED\nclass MyComponent extends Component {\n count = 0;\n handleClick() {\n this.count++;\n this.scheduleRender(); // DEPRECATED: Use StatefulComponent with setState() instead\n }\n}\n\n// ❌ WRONG - onMount/onUpdate/onUnmount do NOT exist (React-like names)\nclass MyComponent extends Component {\n onMount() { } // Should be: onCreate()\n onUpdate() { } // Should be: onViewModelUpdate(previousViewModel)\n onUnmount() { } // Should be: onDestroy()\n}\n\n// ❌ WRONG - this.props does NOT exist\nclass MyComponent extends Component {\n onRender() {\n ; // Should be: this.viewModel.title\n }\n}\n\n// ❌ WRONG - this.context.get() does NOT exist\nclass MyComponent extends Component {\n onRender() {\n const service = this.context.get(MyService); // This API doesn't exist!\n }\n}\n\n// ❌ WRONG - Returning JSX from onRender()\nclass MyComponent extends Component {\n onRender() {\n return ; // onRender() returns void, not JSX!\n }\n}\n```\n\n**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.\n\n### ✅ CORRECT Valdi Patterns (Use these instead)\n\nValdi uses a **class-based component model** with explicit lifecycle methods:\n\n```typescript\n// ✅ CORRECT - Stateful Valdi component pattern\nimport { StatefulComponent } from 'valdi_core/src/Component';\n\nclass MyComponent extends StatefulComponent {\n // State management via StatefulComponent\n state = { count: 0 };\n \n // Lifecycle: Called when component is first created\n onCreate() {\n console.log('Component created');\n }\n \n // Lifecycle: Called when viewModel changes\n onViewModelUpdate(previousViewModel: ViewModel) {\n console.log('ViewModel changed');\n }\n \n // Lifecycle: Called before component is removed\n onDestroy() {\n console.log('Component destroying');\n }\n \n // Required: Render method returns void (not JSX!)\n onRender() {\n // Note: onRender returns VOID, not JSX\n // JSX is written as a statement, not returned\n \n \n ;\n }\n}\n\n// For components without state, use Component\nimport { Component } from 'valdi_core/src/Component';\n\nclass SimpleComponent extends Component {\n onRender() {\n ;\n }\n}\n```\n\n### Key Valdi Concepts\n\n1. **State Management**: Use `StatefulComponent` with `setState()`, not `useState`\n2. **Props Access**: Use `this.viewModel`, not `this.props`\n3. **Re-rendering**: `setState()` automatically triggers re-render\n4. **Lifecycle Methods**: `onCreate()`, `onViewModelUpdate()`, `onDestroy()`\n5. **Dependency Injection**: Use `createProviderComponent()` + `withProviders()` HOC pattern\n6. **Return Type**: `onRender()` returns `void`, not JSX (JSX is written as a statement)\n7. **Component Definition**: Always use `class` extending `Component` or `StatefulComponent`, never functions\n\n### State Management with StatefulComponent\n\n```typescript\n// ✅ CORRECT - Use StatefulComponent with setState()\nclass Counter extends StatefulComponent {\n state = { count: 0 };\n \n handleClick = () => {\n this.setState({ count: this.state.count + 1 }); // Automatically triggers re-render\n };\n \n onRender() {\n ;\n }\n}\n\n// ❌ WRONG - Using markNeedsRender() doesn't exist\nhandleClick() {\n this.count++;\n this.markNeedsRender(); // ERROR: markNeedsRender is not a function!\n}\n```\n\n### Provider Pattern (Not useContext)\n\n```typescript\n// ✅ CORRECT - Valdi provider pattern\nimport { createProviderComponentWithKeyName } from 'valdi_core/src/provider/createProvider';\nimport { withProviders } from 'valdi_core/src/provider/withProviders';\nimport { ProvidersValuesViewModel } from 'valdi_core/src/provider/withProviders';\nimport { Component } from 'valdi_core/src/Component';\n\n// Step 1: Define service\nclass MyService {\n getData() { return 'data'; }\n}\n\n// Step 2: Create provider component\nconst MyServiceProvider = createProviderComponentWithKeyName('MyServiceProvider');\n\n// Step 3: Provide value in parent\nclass ParentComponent extends Component {\n private service = new MyService();\n \n onRender() {\n \n \n ;\n }\n}\n\n// Step 4: Consume in child - extend viewModel from ProvidersValuesViewModel\ninterface ChildViewModel extends ProvidersValuesViewModel<[MyService]> {\n // other props if needed\n}\n\nclass ChildComponent extends Component {\n onRender() {\n // Access provider via viewModel.providersValues\n const [myService] = this.viewModel.providersValues;\n const data = myService.getData();\n \n ;\n }\n}\n\n// Step 5: Wrap component with provider HOC\nconst ChildComponentWithProvider = withProviders(MyServiceProvider)(ChildComponent);\n```\n\n## Key Technologies\n\n- **Valdi**: TypeScript-based declarative UI framework that compiles to native code\n- **TSX/JSX**: React-like syntax for declarative UI (but this is **NOT React** - Valdi compiles to native)\n- **Bazel**: Primary build system for reproducible builds\n- **TypeScript/JavaScript**: Application and UI layer\n- **C++**: Cross-platform runtime and layout engine\n- **Swift**: Compiler implementation\n- **Kotlin/Java**: Android runtime\n- **Objective-C/C++**: iOS runtime\n- **Flexbox**: Layout system with automatic RTL support\n\n## Directory Structure\n\n### `/apps/`\nExample applications demonstrating Valdi features:\n- `helloworld/` - Basic getting started example\n- `valdi_gpt/` - More complex demo application\n- `benchmark/` - Performance testing app\n- `*_example/` - Various feature demonstrations (navigation, managed context, etc.)\n\n### `/compiler/`\nThe Valdi compiler and companion tools:\n- `compiler/` - Swift-based main compiler that transforms TypeScript to native code\n- `companion/` - TypeScript-based companion tools for the build process\n\n### `/valdi/`, `/valdi_core/`, `/valdi_protobuf/`\nCore Valdi runtime implementations:\n- Platform-specific implementations (iOS, Android, macOS)\n- Cross-platform C++ core with layout engine\n- Protobuf integration for efficient serialization\n- Generated code from Djinni interfaces for cross-language bindings\n\n### `/src/valdi_modules/`\nCore Valdi TypeScript modules and standard library:\n- `valdi_core/` - Core component and runtime APIs (Component, Provider, etc.)\n- `valdi_protobuf/` - Protobuf serialization support\n- `valdi_http/` - HTTP client module (promise-based network requests)\n- `valdi_navigation/` - Navigation utilities\n- `valdi_rxjs/` - RxJS integration for reactive programming\n- `persistence/` - Key-value storage with encryption and TTL support\n- `drawing/` - Managed context for graphics and drawing operations\n- `file_system/` - Low-level file I/O operations\n- `valdi_web/`, `web_renderer/` - Web runtime implementations\n- `foundation/`, `coreutils/` - Common utilities (arrays, Base64, LRU cache, UUID, etc.)\n- `worker/` - Worker service support for background JavaScript execution\n- Other standard library modules\n\n### `/npm_modules/`\nNode.js packages:\n- `cli/` - Command-line interface for Valdi development (`valdi` command)\n- `eslint-plugin-valdi/` - ESLint rules for Valdi code\n\n### `/bzl/`\nBazel build rules and macros for the Valdi build system\n\n### `/docs/`\nComprehensive documentation:\n- Codelabs for learning\n- API documentation\n- Setup and installation guides\n\n### `/third-party/`\nExternal dependencies and their Bazel build configurations\n\n## Important Conventions\n\n### Build System\n\n1. **Bazel is the primary build system** - Use `bazel build`, `bazel test`, etc.\n - Note: `bzl` is an alias for `bazel` - both commands work interchangeably\n - The CLI looks for `bazel`, `bzl`, or `bazelisk` executables\n2. **MODULE.bazel and WORKSPACE** - Bazel module system is in use\n3. **Cross-platform builds** - Code must work on iOS, Android, Linux, and macOS\n4. **Platform transitions** - Build rules handle platform-specific compilation automatically\n\n### Code Style\n\n1. **C++**: Follow the project's C++ style conventions\n2. **TypeScript**: Use ESLint with Valdi-specific rules\n3. **Swift**: Follow Swift conventions for compiler code\n4. **Kotlin**: Follow Kotlin conventions for Android runtime\n5. **Indentation**: Always match existing file conventions\n\n### Testing\n\n1. Test files are typically in `test/` subdirectories\n2. Run tests with `bazel test //path/to:target`\n3. All changes should include appropriate tests\n4. Use the built-in Valdi testing framework for component tests\n\n### Generated Code\n\n1. **Djinni interfaces** - Some code is generated from `.djinni` files for cross-language bindings\n2. **Don't modify generated code** - Change the source `.djinni` file instead\n3. Generated files are typically in `generated-src/` directories\n\n## Common Tasks\n\n### Building the Compiler\n\n```bash\n# Build the compiler\nbazel build //compiler/compiler:valdi-compiler\n\n# After building, move the binary to bin/ directory for use by the toolchain\n# The exact path depends on your platform (macos/linux and architecture)\n# Example for macOS ARM64:\ncp bazel-bin/compiler/compiler/valdi-compiler bin/compiler/macos/arm64/\n```\n\nNote: Pre-built compiler binaries are checked in to `/bin/compiler/` for convenience, but you can build and use your own version during development.\n\n### Running Tests\n\n```bash\n# Run all tests\nbazel test //...\n\n# Run specific test\nbazel test //valdi/test:some_test\n```\n\n### Installing and Using the CLI\n\n```bash\ncd npm_modules/cli\n\n# Install the valdi command-line tool globally\nnpm run cli:install\n\n# After installation, use the CLI\nvaldi --help\n```\n\n### Creating New Examples\n\nUse existing apps in `/apps/` as templates. Each app needs:\n- `BUILD.bazel` file defining build targets\n- `package.json` for npm dependencies\n- Entry point file (typically `.tsx` for TypeScript JSX)\n- Source files in `src/` directory\n\n## Important Files to Review\n\n- `/README.md` - Main project documentation\n- `/docs/INSTALL.md` - Installation and setup instructions\n- `/docs/DEV_SETUP.md` - Developer environment setup\n- `/CONTRIBUTING.md` - Contribution guidelines\n- `/CODE_OF_CONDUCT.md` - Community standards\n- `/LICENSE` - MIT License information\n\n## Toolchain Locations\n\nPre-built binaries are stored in `/bin/`:\n- Compiler binaries for Linux/macOS\n- SQLite compiler for data persistence\n- Other build tools\n\n## Platform-Specific Notes\n\n### iOS\n- Uses Objective-C++ bridge layer for TypeScript-native communication\n- Metal for GPU-accelerated rendering\n- See `/valdi/src/ios/` for platform implementations\n\n### Android\n- Kotlin/Java implementations\n- Uses Android NDK for C++ integration\n- See `/valdi/src/android/` for platform implementations\n\n### Web\n- TypeScript runtime for web targets\n- **Custom views**: Use `webClass` attribute on ``. Factories are registered via `webPolyglotViews` exports and looked up in `WebViewClassRegistry`. Factories receive a container DOM element and can return a `changeAttribute(name, value)` handler.\n- **`web_deps` must be a `ts_project`** — never use `filegroup` for web code. Always use typed TypeScript with `ts_project` from `@aspect_rules_ts`.\n- See `/src/valdi_modules/src/valdi/web_renderer/` for web implementation\n\n### Desktop (macOS)\n- Native macOS implementation using AppKit (`NSView`, `NSWindow`)\n- **Platform type**: `PlatformTypeMacOS` (3) — distinct from iOS (2)\n- **Class name resolution**: macOS falls through to iOS class names for both built-in elements and custom views. This means `iosClass` works on macOS without specifying `macosClass`.\n- **SnapDrawing**: Shares iOS layer classes (registered under iOS names like `SCValdiView`, `SCValdiLabel`)\n- See `/valdi/src/valdi/macos/` for desktop implementations\n\n## Development Workflow\n\n1. **Setup environment** - Follow `/docs/DEV_SETUP.md`\n2. **Make changes** in appropriate directory\n3. **Build locally** with Bazel\n4. **Run tests** to verify changes\n5. **Run linters** with appropriate tools\n6. **Test on multiple platforms** - Changes may affect iOS, Android, and web\n7. **Update documentation** if adding features\n\n## Common Patterns\n\n### Component Development\n\nValdi components follow a class-based pattern with lifecycle methods:\n\n```typescript\nimport { Component } from 'valdi_core/src/Component';\n\nclass MyComponent extends Component {\n // Required: Render the component's UI\n onRender() {\n \n \n ;\n }\n \n // Optional lifecycle methods:\n // onCreate() - Called when component is first created\n // onDestroy() - Called before component is removed\n // onViewModelUpdate(previousViewModel) - Called when viewModel updates\n}\n```\n\n**Key Valdi Concepts:**\n- Components use TSX/JSX syntax (similar to React but compiles to native)\n- State management via component properties\n- Event handlers for user interactions\n- Flexbox layout system for positioning\n\n### Native Polyglot Modules\n\nFor performance-critical code or platform-specific views, write native implementations with TypeScript bindings:\n- Define interfaces in TypeScript\n- Specify polyglot modules in build files (BUILD.bazel)\n- Implement in C++, Swift, Kotlin, or Objective-C\n- Compiler generates type-safe bindings\n\n### Custom Views (``)\n\nCustom views inject native platform views into Valdi components. Use platform-specific class attributes:\n\n```tsx\n\n```\n\n**Platform resolution rules:**\n- **macOS falls through to iOS**: If `macosClass` is not specified, `iosClass` is used. This applies both in TypeScript (`JSXBootstrap.ts`) and C++ (`ViewNode.cpp`).\n- **Built-in elements** (view, label, image, scroll, etc.) always resolve to iOS class names on macOS (e.g., `SCValdiView`, `SCValdiLabel`).\n- **Web** uses `webClass` to look up a factory in `WebViewClassRegistry`. Factories can return a `changeAttribute(name, value)` handler to receive attribute updates.\n- See `/docs/docs/native-customviews.md` for full examples on all platforms.\n\n**Bazel dependencies for custom views:**\n\n```python\nload(\"@aspect_rules_ts//ts:defs.bzl\", \"ts_project\")\n\n# Web views MUST be a ts_project, never a filegroup.\n# - transpiler = \"tsc\" is required (aspect_rules_ts does not default it)\n# - Provide a dedicated web/tsconfig.json (standalone, not extending the module tsconfig)\n# - If web code imports .d.ts from the module's src/, include \"src/**/*.d.ts\" in srcs\n# - Exclude \"web/**/*.d.ts\" from srcs to avoid TS5055 collisions with composite: true\nts_project(\n name = \"my_web_views\",\n srcs = glob([\n \"web/**/*.ts\",\n \"src/**/*.d.ts\", # only if web code imports module type declarations\n ], exclude = [\n \"web/**/*.d.ts\", # avoid TS5055 output collision with composite\n ]),\n allow_js = True,\n composite = True,\n transpiler = \"tsc\",\n tsconfig = \"web/tsconfig.json\",\n)\n\nvaldi_module(\n name = \"my_module\",\n srcs = [...],\n ios_deps = [\":my_ios_views\"], # objc_library\n macos_deps = [\":my_macos_views\"], # objc_library (or omit to share ios_deps)\n android_deps = [\":my_android_views\"], # valdi_android_library\n web_deps = [\":my_web_views\"], # ts_project (never filegroup)\n)\n```\n\n**Web `tsconfig.json`** — the `web/tsconfig.json` should be standalone (not extending the module-level tsconfig) since `ts_project` compiles independently:\n\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2016\",\n \"module\": \"commonjs\",\n \"strict\": true,\n \"composite\": true,\n \"allowJs\": true,\n \"lib\": [\"dom\", \"ES2019\"]\n }\n}\n```\n\n### Worker Services\n\nFor background processing:\n- Create worker services that run in separate JavaScript contexts\n- Communicate via message passing\n- See `/docs/docs/advanced-worker-service.md`\n\n### Component Context & Native Integration\n\nPass data and services between native code and Valdi:\n- **Component Context**: Pass native data to Valdi components when instantiating them\n- **Native Annotations**: Use TypeScript comments to export components to native platforms\n- **Example**: `@Component` and `@ExportModel` annotations define how components are exposed\n- See `/docs/docs/native-annotations.md` and `/docs/docs/native-context.md`\n\n### Provider Pattern\n\nDependency injection for Valdi components:\n- Use `Provider` to pass services and data down the component tree\n- Similar to React Context but Valdi-specific\n- Enables loose coupling and testability\n- See `/docs/docs/advanced-provider.md`\n\n### Localization\n\nString management for multi-language support:\n- String resources defined in JSON files\n- Automatic locale switching based on device settings\n- See `/docs/docs/advanced-localization.md`\n\n## Common Pitfalls\n\n1. **Don't skip cross-platform testing** - Changes affect multiple platforms\n2. **Don't modify generated code** - Change the source instead\n3. **Don't ignore Bazel cache** - Use `bazel clean` sparingly\n4. **Don't hardcode platform assumptions** - Use appropriate abstractions\n5. **Performance matters** - Valdi is a UI framework where rendering performance is critical\n\n## Architecture Overview\n\n### Compilation Pipeline\n\n1. **TypeScript source** → Valdi compiler (Swift)\n2. **Compiler output** → Platform-specific code generation\n3. **Native builds** → iOS/Android/macOS apps\n4. **Runtime** → C++ layout engine + platform-specific renderers\n\n### Hot Reload System\n\n- Valdi includes instant hot reload during development\n- Changes to TypeScript components are reflected in milliseconds\n- No need to recompile native code for UI changes\n- Use `valdi hotreload` command\n\n### Performance Features\n\n- **View recycling** - Global view pooling reuses native views\n- **Viewport-aware rendering** - Only visible views are inflated\n- **Independent component rendering** - Components update without parent re-renders\n- **Optimized layout** - C++ layout engine with minimal marshalling\n\n## Key Points for AI Assistants\n\n1. **Cross-platform compatibility is critical** - Test implications across iOS, Android, and web\n2. **Bazel is non-negotiable** - Don't suggest alternative build systems\n3. **Generated code exists** - Some files are auto-generated from Djinni interfaces\n4. **Performance is paramount** - This is a production UI framework used at scale\n5. **Follow existing patterns** - This is a mature codebase with established conventions\n6. **TypeScript is compiled** - Unlike React Native, this doesn't run JavaScript at runtime\n7. **Native integration is deep** - Direct access to platform APIs via polyglot modules\n\n## Quick Reference Commands\n\n### For App Development\n\n```bash\n# Install Valdi CLI (first time)\ncd npm_modules/cli && npm run cli:install\n\n# Setup development environment\nvaldi dev_setup\n\n# Bootstrap a new project\nmkdir my_project && cd my_project\nvaldi bootstrap\n\n# Install dependencies and build\nvaldi install ios # or android\n\n# Start hot reload\nvaldi hotreload\n```\n\n### For Platform Development (Contributing to Valdi)\n\n```bash\n# Setup development environment (first time)\nscripts/dev_setup.sh\n\n# Build everything\nbazel build //...\n\n# Run all tests\nbazel test //...\n\n# Build and run example app\ncd apps/helloworld\nvaldi install ios # or android\n```\n\n## Testing Framework\n\nValdi includes a built-in testing framework:\n- Component-level unit tests\n- Mock services and dependencies\n- See `/docs/docs/workflow-testing.md`\n\n```typescript\nimport { TestRunner } from 'valdi_core/src/TestRunner';\n\nTestRunner.test('component renders correctly', () => {\n const component = new MyComponent();\n // Test assertions\n});\n```\n\n## Debugging\n\n- **VSCode integration** - Full debugging support with breakpoints\n- **Hermes debugger** - For JavaScript debugging\n- **Native debugging** - Xcode/Android Studio for platform-specific issues\n- See `/docs/docs/workflow-hermes-debugger.md`\n\n## Related Documentation\n\nFor more details on specific topics, see the `/docs/` directory:\n- Architecture overview\n- API reference\n- Codelabs for hands-on learning\n- Advanced features (animations, gestures, protobuf)\n- Native bindings and custom views\n\n## AI Skills (Context for AI Agents)\n\nThe Valdi CLI ships context files (\"skills\") that give AI agents accurate knowledge about Valdi APIs, patterns, and conventions. Install them once to reduce hallucinations:\n\n```bash\nnpm install -g @snap/valdi\nvaldi skills install # installs all skills for detected AI agents\n# or install by category:\nvaldi skills install --category=client # module development skills\nvaldi skills install --category=framework # framework internals skills\n```\n\nSkills are bundled inside the npm package — no network access required after install.\n\n## Contributing\n\nThis is an open-source project. When contributing:\n1. Follow the style guides\n2. Include tests for new features\n3. Update documentation\n4. Ensure cross-platform compatibility\n5. See `CONTRIBUTING.md` for full guidelines\n\n## Community & Support\n\n- **Documentation**: Comprehensive docs in `/docs/` directory\n- **Examples**: Working examples in `/apps/` directory\n- **Issues**: Report bugs and request features via GitHub issues\n- **Discussions**: Ask questions and share ideas in GitHub Discussions\n\n---\n\n*This document is intended for AI coding assistants to quickly understand the structure and conventions of the Valdi codebase. For human developers, please refer to the main README.md and comprehensive documentation in `/docs/`.*\n",".cursorrules":"# Valdi Open Source - Cursor Rules\n\n## ⚠️ Open Source Project\n\nThis is an open source project. Never commit secrets, API keys, or proprietary information.\n\n## 🚨 CRITICAL: This is NOT React!\n\nValdi uses TSX/JSX syntax but is **fundamentally different from React**. \n\n**Common AI mistakes:**\n- ❌ Suggesting `useState`, `useEffect`, `useContext` (don't exist!)\n- ❌ Functional components (don't exist!)\n- ❌ `this.props` (should be `this.viewModel`)\n- ❌ `markNeedsRender()`, `onMount()`, `onUpdate()` (wrong names/don't exist!)\n\n**Correct Valdi:**\n- ✅ `class MyComponent extends StatefulComponent`\n- ✅ `state = {}` + `this.setState()`\n- ✅ `this.viewModel` for props\n- ✅ `onCreate()`, `onViewModelUpdate()`, `onDestroy()` lifecycle\n\n## 📁 Context-Specific Rules\n\nCursor automatically loads additional rules based on where you're working:\n\n| Working In | See |\n|-----------|-----|\n| TypeScript/TSX components | `.cursor/rules/typescript-tsx.md` |\n| Swift compiler | `.cursor/rules/compiler.md` |\n| C++ runtime | `.cursor/rules/cpp-runtime.md` |\n| Android (Kotlin) | `.cursor/rules/android.md` |\n| iOS (Objective-C) | `.cursor/rules/ios.md` |\n| Bazel files | `.cursor/rules/bazel.md` |\n| Tests | `.cursor/rules/testing.md` |\n\n**→ Check `.cursor/rules/README.md` for the full list**\n\n## Quick Commands\n\n```bash\nbazel build //... # Build everything\nbazel test //... # Run all tests\nvaldi install ios # Build & install iOS app\nvaldi hotreload # Start hot reload\n```\n\n## More Information\n\n- **Comprehensive guide**: `/AGENTS.md` (621 lines)\n- **AI tooling**: `/docs/docs/ai-tooling.md`\n- **Support**: `/SUPPORT.md`\n- **Discussions**: https://github.com/Snapchat/Valdi/discussions\n- **Issues**: https://github.com/Snapchat/Valdi/issues\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md - Guide for AI Coding Assistants\n\nThis document provides context and guidelines for AI coding assistants working with the Valdi codebase.\n\n## Overview\n\nValdi 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.\n\nValdi has been used in production at Snap for 8 years and is now available as open source under the MIT license.\n\n### How Valdi Works\n\nThe 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.\n\n## 🚨 AI Anti-Hallucination: This is NOT React!\n\n**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.\n\n### ❌ FORBIDDEN React Patterns (Do NOT use these)\n\nThese React APIs **DO NOT EXIST** in Valdi and will cause compilation errors:\n\n```typescript\n// ❌ WRONG - useState does not exist in Valdi\nconst [count, setCount] = useState(0);\n\n// ❌ WRONG - useEffect does not exist in Valdi \nuseEffect(() => { ... }, []);\n\n// ❌ WRONG - useContext does not exist in Valdi\nconst value = useContext(MyContext);\n\n// ❌ WRONG - useMemo, useCallback, useRef do not exist\nconst memoized = useMemo(() => ..., []);\nconst callback = useCallback(() => ..., []);\nconst ref = useRef(null);\n\n// ❌ WRONG - React.Component does not exist\nclass MyComponent extends React.Component { ... }\n\n// ❌ WRONG - Functional components do not exist\nfunction MyComponent(props) { return ; }\nconst MyComponent = () => ;\n```\n\n### ⚠️ COMMON AI MISTAKES (Even advanced models make these errors!)\n\n**These patterns DO NOT EXIST in Valdi** but are commonly suggested by AI models:\n\n```typescript\n// ❌ WRONG - markNeedsRender() does NOT exist\nclass MyComponent extends Component {\n count = 0;\n handleClick() {\n this.count++;\n this.markNeedsRender(); // ERROR: This method doesn't exist!\n }\n}\n\n// ❌ WRONG - scheduleRender() exists but is DEPRECATED\nclass MyComponent extends Component {\n count = 0;\n handleClick() {\n this.count++;\n this.scheduleRender(); // DEPRECATED: Use StatefulComponent with setState() instead\n }\n}\n\n// ❌ WRONG - onMount/onUpdate/onUnmount do NOT exist (React-like names)\nclass MyComponent extends Component {\n onMount() { } // Should be: onCreate()\n onUpdate() { } // Should be: onViewModelUpdate(previousViewModel)\n onUnmount() { } // Should be: onDestroy()\n}\n\n// ❌ WRONG - this.props does NOT exist\nclass MyComponent extends Component {\n onRender() {\n ; // Should be: this.viewModel.title\n }\n}\n\n// ❌ WRONG - this.context.get() does NOT exist\nclass MyComponent extends Component {\n onRender() {\n const service = this.context.get(MyService); // This API doesn't exist!\n }\n}\n\n// ❌ WRONG - Returning JSX from onRender()\nclass MyComponent extends Component {\n onRender() {\n return ; // onRender() returns void, not JSX!\n }\n}\n```\n\n**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.\n\n### ✅ CORRECT Valdi Patterns (Use these instead)\n\nValdi uses a **class-based component model** with explicit lifecycle methods:\n\n```typescript\n// ✅ CORRECT - Stateful Valdi component pattern\nimport { StatefulComponent } from 'valdi_core/src/Component';\n\nclass MyComponent extends StatefulComponent {\n // State management via StatefulComponent\n state = { count: 0 };\n \n // Lifecycle: Called when component is first created\n onCreate() {\n console.log('Component created');\n }\n \n // Lifecycle: Called when viewModel changes\n onViewModelUpdate(previousViewModel: ViewModel) {\n console.log('ViewModel changed');\n }\n \n // Lifecycle: Called before component is removed\n onDestroy() {\n console.log('Component destroying');\n }\n \n // Required: Render method returns void (not JSX!)\n onRender() {\n // Note: onRender returns VOID, not JSX\n // JSX is written as a statement, not returned\n \n \n ;\n }\n}\n\n// For components without state, use Component\nimport { Component } from 'valdi_core/src/Component';\n\nclass SimpleComponent extends Component {\n onRender() {\n ;\n }\n}\n```\n\n### Key Valdi Concepts\n\n1. **State Management**: Use `StatefulComponent` with `setState()`, not `useState`\n2. **Props Access**: Use `this.viewModel`, not `this.props`\n3. **Re-rendering**: `setState()` automatically triggers re-render\n4. **Lifecycle Methods**: `onCreate()`, `onViewModelUpdate()`, `onDestroy()`\n5. **Dependency Injection**: Use `createProviderComponent()` + `withProviders()` HOC pattern\n6. **Return Type**: `onRender()` returns `void`, not JSX (JSX is written as a statement)\n7. **Component Definition**: Always use `class` extending `Component` or `StatefulComponent`, never functions\n\n### State Management with StatefulComponent\n\n```typescript\n// ✅ CORRECT - Use StatefulComponent with setState()\nclass Counter extends StatefulComponent {\n state = { count: 0 };\n \n handleClick = () => {\n this.setState({ count: this.state.count + 1 }); // Automatically triggers re-render\n };\n \n onRender() {\n ;\n }\n}\n\n// ❌ WRONG - Using markNeedsRender() doesn't exist\nhandleClick() {\n this.count++;\n this.markNeedsRender(); // ERROR: markNeedsRender is not a function!\n}\n```\n\n### Provider Pattern (Not useContext)\n\n```typescript\n// ✅ CORRECT - Valdi provider pattern\nimport { createProviderComponentWithKeyName } from 'valdi_core/src/provider/createProvider';\nimport { withProviders } from 'valdi_core/src/provider/withProviders';\nimport { ProvidersValuesViewModel } from 'valdi_core/src/provider/withProviders';\nimport { Component } from 'valdi_core/src/Component';\n\n// Step 1: Define service\nclass MyService {\n getData() { return 'data'; }\n}\n\n// Step 2: Create provider component\nconst MyServiceProvider = createProviderComponentWithKeyName('MyServiceProvider');\n\n// Step 3: Provide value in parent\nclass ParentComponent extends Component {\n private service = new MyService();\n \n onRender() {\n \n \n ;\n }\n}\n\n// Step 4: Consume in child - extend viewModel from ProvidersValuesViewModel\ninterface ChildViewModel extends ProvidersValuesViewModel<[MyService]> {\n // other props if needed\n}\n\nclass ChildComponent extends Component {\n onRender() {\n // Access provider via viewModel.providersValues\n const [myService] = this.viewModel.providersValues;\n const data = myService.getData();\n \n ;\n }\n}\n\n// Step 5: Wrap component with provider HOC\nconst ChildComponentWithProvider = withProviders(MyServiceProvider)(ChildComponent);\n```\n\n## Key Technologies\n\n- **Valdi**: TypeScript-based declarative UI framework that compiles to native code\n- **TSX/JSX**: React-like syntax for declarative UI (but this is **NOT React** - Valdi compiles to native)\n- **Bazel**: Primary build system for reproducible builds\n- **TypeScript/JavaScript**: Application and UI layer\n- **C++**: Cross-platform runtime and layout engine\n- **Swift**: Compiler implementation\n- **Kotlin/Java**: Android runtime\n- **Objective-C/C++**: iOS runtime\n- **Flexbox**: Layout system with automatic RTL support\n\n## Directory Structure\n\n### `/apps/`\nExample applications demonstrating Valdi features:\n- `helloworld/` - Basic getting started example\n- `valdi_gpt/` - More complex demo application\n- `benchmark/` - Performance testing app\n- `*_example/` - Various feature demonstrations (navigation, managed context, etc.)\n\n### `/compiler/`\nThe Valdi compiler and companion tools:\n- `compiler/` - Swift-based main compiler that transforms TypeScript to native code\n- `companion/` - TypeScript-based companion tools for the build process\n\n### `/valdi/`, `/valdi_core/`, `/valdi_protobuf/`\nCore Valdi runtime implementations:\n- Platform-specific implementations (iOS, Android, macOS)\n- Cross-platform C++ core with layout engine\n- Protobuf integration for efficient serialization\n- Generated code from Djinni interfaces for cross-language bindings\n\n### `/src/valdi_modules/`\nCore Valdi TypeScript modules and standard library:\n- `valdi_core/` - Core component and runtime APIs (Component, Provider, etc.)\n- `valdi_protobuf/` - Protobuf serialization support\n- `valdi_http/` - HTTP client module (promise-based network requests)\n- `valdi_navigation/` - Navigation utilities\n- `valdi_rxjs/` - RxJS integration for reactive programming\n- `persistence/` - Key-value storage with encryption and TTL support\n- `drawing/` - Managed context for graphics and drawing operations\n- `file_system/` - Low-level file I/O operations\n- `valdi_web/`, `web_renderer/` - Web runtime implementations\n- `foundation/`, `coreutils/` - Common utilities (arrays, Base64, LRU cache, UUID, etc.)\n- `worker/` - Worker service support for background JavaScript execution\n- Other standard library modules\n\n### `/npm_modules/`\nNode.js packages:\n- `cli/` - Command-line interface for Valdi development (`valdi` command)\n- `eslint-plugin-valdi/` - ESLint rules for Valdi code\n\n### `/bzl/`\nBazel build rules and macros for the Valdi build system\n\n### `/docs/`\nComprehensive documentation:\n- Codelabs for learning\n- API documentation\n- Setup and installation guides\n\n### `/third-party/`\nExternal dependencies and their Bazel build configurations\n\n## Important Conventions\n\n### Build System\n\n1. **Bazel is the primary build system** - Use `bazel build`, `bazel test`, etc.\n - Note: `bzl` is an alias for `bazel` - both commands work interchangeably\n - The CLI looks for `bazel`, `bzl`, or `bazelisk` executables\n2. **MODULE.bazel and WORKSPACE** - Bazel module system is in use\n3. **Cross-platform builds** - Code must work on iOS, Android, Linux, and macOS\n4. **Platform transitions** - Build rules handle platform-specific compilation automatically\n\n### Code Style\n\n1. **C++**: Follow the project's C++ style conventions\n2. **TypeScript**: Use ESLint with Valdi-specific rules\n3. **Swift**: Follow Swift conventions for compiler code\n4. **Kotlin**: Follow Kotlin conventions for Android runtime\n5. **Indentation**: Always match existing file conventions\n\n### Testing\n\n1. Test files are typically in `test/` subdirectories\n2. Run tests with `bazel test //path/to:target`\n3. All changes should include appropriate tests\n4. Use the built-in Valdi testing framework for component tests\n\n### Generated Code\n\n1. **Djinni interfaces** - Some code is generated from `.djinni` files for cross-language bindings\n2. **Don't modify generated code** - Change the source `.djinni` file instead\n3. Generated files are typically in `generated-src/` directories\n\n## Common Tasks\n\n### Building the Compiler\n\n```bash\n# Build the compiler\nbazel build //compiler/compiler:valdi-compiler\n\n# After building, move the binary to bin/ directory for use by the toolchain\n# The exact path depends on your platform (macos/linux and architecture)\n# Example for macOS ARM64:\ncp bazel-bin/compiler/compiler/valdi-compiler bin/compiler/macos/arm64/\n```\n\nNote: Pre-built compiler binaries are checked in to `/bin/compiler/` for convenience, but you can build and use your own version during development.\n\n### Running Tests\n\n```bash\n# Run all tests\nbazel test //...\n\n# Run specific test\nbazel test //valdi/test:some_test\n```\n\n### Installing and Using the CLI\n\n```bash\ncd npm_modules/cli\n\n# Install the valdi command-line tool globally\nnpm run cli:install\n\n# After installation, use the CLI\nvaldi --help\n```\n\n### Creating New Examples\n\nUse existing apps in `/apps/` as templates. Each app needs:\n- `BUILD.bazel` file defining build targets\n- `package.json` for npm dependencies\n- Entry point file (typically `.tsx` for TypeScript JSX)\n- Source files in `src/` directory\n\n## Important Files to Review\n\n- `/README.md` - Main project documentation\n- `/docs/INSTALL.md` - Installation and setup instructions\n- `/docs/DEV_SETUP.md` - Developer environment setup\n- `/CONTRIBUTING.md` - Contribution guidelines\n- `/CODE_OF_CONDUCT.md` - Community standards\n- `/LICENSE` - MIT License information\n\n## Toolchain Locations\n\nPre-built binaries are stored in `/bin/`:\n- Compiler binaries for Linux/macOS\n- SQLite compiler for data persistence\n- Other build tools\n\n## Platform-Specific Notes\n\n### iOS\n- Uses Objective-C++ bridge layer for TypeScript-native communication\n- Metal for GPU-accelerated rendering\n- See `/valdi/src/ios/` for platform implementations\n\n### Android\n- Kotlin/Java implementations\n- Uses Android NDK for C++ integration\n- See `/valdi/src/android/` for platform implementations\n\n### Web\n- TypeScript runtime for web targets\n- **Custom views**: Use `webClass` attribute on ``. Factories are registered via `webPolyglotViews` exports and looked up in `WebViewClassRegistry`. Factories receive a container DOM element and can return a `changeAttribute(name, value)` handler.\n- **`web_deps` must be a `ts_project`** — never use `filegroup` for web code. Always use typed TypeScript with `ts_project` from `@aspect_rules_ts`.\n- See `/src/valdi_modules/src/valdi/web_renderer/` for web implementation\n\n### Desktop (macOS)\n- Native macOS implementation using AppKit (`NSView`, `NSWindow`)\n- **Platform type**: `PlatformTypeMacOS` (3) — distinct from iOS (2)\n- **Class name resolution**: macOS falls through to iOS class names for both built-in elements and custom views. This means `iosClass` works on macOS without specifying `macosClass`.\n- **SnapDrawing**: Shares iOS layer classes (registered under iOS names like `SCValdiView`, `SCValdiLabel`)\n- See `/valdi/src/valdi/macos/` for desktop implementations\n\n## Development Workflow\n\n1. **Setup environment** - Follow `/docs/DEV_SETUP.md`\n2. **Make changes** in appropriate directory\n3. **Build locally** with Bazel\n4. **Run tests** to verify changes\n5. **Run linters** with appropriate tools\n6. **Test on multiple platforms** - Changes may affect iOS, Android, and web\n7. **Update documentation** if adding features\n\n## Common Patterns\n\n### Component Development\n\nValdi components follow a class-based pattern with lifecycle methods:\n\n```typescript\nimport { Component } from 'valdi_core/src/Component';\n\nclass MyComponent extends Component {\n // Required: Render the component's UI\n onRender() {\n \n \n ;\n }\n \n // Optional lifecycle methods:\n // onCreate() - Called when component is first created\n // onDestroy() - Called before component is removed\n // onViewModelUpdate(previousViewModel) - Called when viewModel updates\n}\n```\n\n**Key Valdi Concepts:**\n- Components use TSX/JSX syntax (similar to React but compiles to native)\n- State management via component properties\n- Event handlers for user interactions\n- Flexbox layout system for positioning\n\n### Native Polyglot Modules\n\nFor performance-critical code or platform-specific views, write native implementations with TypeScript bindings:\n- Define interfaces in TypeScript\n- Specify polyglot modules in build files (BUILD.bazel)\n- Implement in C++, Swift, Kotlin, or Objective-C\n- Compiler generates type-safe bindings\n\n### Custom Views (``)\n\nCustom views inject native platform views into Valdi components. Use platform-specific class attributes:\n\n```tsx\n\n```\n\n**Platform resolution rules:**\n- **macOS falls through to iOS**: If `macosClass` is not specified, `iosClass` is used. This applies both in TypeScript (`JSXBootstrap.ts`) and C++ (`ViewNode.cpp`).\n- **Built-in elements** (view, label, image, scroll, etc.) always resolve to iOS class names on macOS (e.g., `SCValdiView`, `SCValdiLabel`).\n- **Web** uses `webClass` to look up a factory in `WebViewClassRegistry`. Factories can return a `changeAttribute(name, value)` handler to receive attribute updates.\n- See `/docs/docs/native-customviews.md` for full examples on all platforms.\n\n**Bazel dependencies for custom views:**\n\n```python\nload(\"@aspect_rules_ts//ts:defs.bzl\", \"ts_project\")\n\n# Web views MUST be a ts_project, never a filegroup.\n# - transpiler = \"tsc\" is required (aspect_rules_ts does not default it)\n# - Provide a dedicated web/tsconfig.json (standalone, not extending the module tsconfig)\n# - If web code imports .d.ts from the module's src/, include \"src/**/*.d.ts\" in srcs\n# - Exclude \"web/**/*.d.ts\" from srcs to avoid TS5055 collisions with composite: true\nts_project(\n name = \"my_web_views\",\n srcs = glob([\n \"web/**/*.ts\",\n \"src/**/*.d.ts\", # only if web code imports module type declarations\n ], exclude = [\n \"web/**/*.d.ts\", # avoid TS5055 output collision with composite\n ]),\n allow_js = True,\n composite = True,\n transpiler = \"tsc\",\n tsconfig = \"web/tsconfig.json\",\n)\n\nvaldi_module(\n name = \"my_module\",\n srcs = [...],\n ios_deps = [\":my_ios_views\"], # objc_library\n macos_deps = [\":my_macos_views\"], # objc_library (or omit to share ios_deps)\n android_deps = [\":my_android_views\"], # valdi_android_library\n web_deps = [\":my_web_views\"], # ts_project (never filegroup)\n)\n```\n\n**Web `tsconfig.json`** — the `web/tsconfig.json` should be standalone (not extending the module-level tsconfig) since `ts_project` compiles independently:\n\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2016\",\n \"module\": \"commonjs\",\n \"strict\": true,\n \"composite\": true,\n \"allowJs\": true,\n \"lib\": [\"dom\", \"ES2019\"]\n }\n}\n```\n\n### Worker Services\n\nFor background processing:\n- Create worker services that run in separate JavaScript contexts\n- Communicate via message passing\n- See `/docs/docs/advanced-worker-service.md`\n\n### Component Context & Native Integration\n\nPass data and services between native code and Valdi:\n- **Component Context**: Pass native data to Valdi components when instantiating them\n- **Native Annotations**: Use TypeScript comments to export components to native platforms\n- **Example**: `@Component` and `@ExportModel` annotations define how components are exposed\n- See `/docs/docs/native-annotations.md` and `/docs/docs/native-context.md`\n\n### Provider Pattern\n\nDependency injection for Valdi components:\n- Use `Provider` to pass services and data down the component tree\n- Similar to React Context but Valdi-specific\n- Enables loose coupling and testability\n- See `/docs/docs/advanced-provider.md`\n\n### Localization\n\nString management for multi-language support:\n- String resources defined in JSON files\n- Automatic locale switching based on device settings\n- See `/docs/docs/advanced-localization.md`\n\n## Common Pitfalls\n\n1. **Don't skip cross-platform testing** - Changes affect multiple platforms\n2. **Don't modify generated code** - Change the source instead\n3. **Don't ignore Bazel cache** - Use `bazel clean` sparingly\n4. **Don't hardcode platform assumptions** - Use appropriate abstractions\n5. **Performance matters** - Valdi is a UI framework where rendering performance is critical\n\n## Architecture Overview\n\n### Compilation Pipeline\n\n1. **TypeScript source** → Valdi compiler (Swift)\n2. **Compiler output** → Platform-specific code generation\n3. **Native builds** → iOS/Android/macOS apps\n4. **Runtime** → C++ layout engine + platform-specific renderers\n\n### Hot Reload System\n\n- Valdi includes instant hot reload during development\n- Changes to TypeScript components are reflected in milliseconds\n- No need to recompile native code for UI changes\n- Use `valdi hotreload` command\n\n### Performance Features\n\n- **View recycling** - Global view pooling reuses native views\n- **Viewport-aware rendering** - Only visible views are inflated\n- **Independent component rendering** - Components update without parent re-renders\n- **Optimized layout** - C++ layout engine with minimal marshalling\n\n## Key Points for AI Assistants\n\n1. **Cross-platform compatibility is critical** - Test implications across iOS, Android, and web\n2. **Bazel is non-negotiable** - Don't suggest alternative build systems\n3. **Generated code exists** - Some files are auto-generated from Djinni interfaces\n4. **Performance is paramount** - This is a production UI framework used at scale\n5. **Follow existing patterns** - This is a mature codebase with established conventions\n6. **TypeScript is compiled** - Unlike React Native, this doesn't run JavaScript at runtime\n7. **Native integration is deep** - Direct access to platform APIs via polyglot modules\n\n## Quick Reference Commands\n\n### For App Development\n\n```bash\n# Install Valdi CLI (first time)\ncd npm_modules/cli && npm run cli:install\n\n# Setup development environment\nvaldi dev_setup\n\n# Bootstrap a new project\nmkdir my_project && cd my_project\nvaldi bootstrap\n\n# Install dependencies and build\nvaldi install ios # or android\n\n# Start hot reload\nvaldi hotreload\n```\n\n### For Platform Development (Contributing to Valdi)\n\n```bash\n# Setup development environment (first time)\nscripts/dev_setup.sh\n\n# Build everything\nbazel build //...\n\n# Run all tests\nbazel test //...\n\n# Build and run example app\ncd apps/helloworld\nvaldi install ios # or android\n```\n\n## Testing Framework\n\nValdi includes a built-in testing framework:\n- Component-level unit tests\n- Mock services and dependencies\n- See `/docs/docs/workflow-testing.md`\n\n```typescript\nimport { TestRunner } from 'valdi_core/src/TestRunner';\n\nTestRunner.test('component renders correctly', () => {\n const component = new MyComponent();\n // Test assertions\n});\n```\n\n## Debugging\n\n- **VSCode integration** - Full debugging support with breakpoints\n- **Hermes debugger** - For JavaScript debugging\n- **Native debugging** - Xcode/Android Studio for platform-specific issues\n- See `/docs/docs/workflow-hermes-debugger.md`\n\n## Related Documentation\n\nFor more details on specific topics, see the `/docs/` directory:\n- Architecture overview\n- API reference\n- Codelabs for hands-on learning\n- Advanced features (animations, gestures, protobuf)\n- Native bindings and custom views\n\n## AI Skills (Context for AI Agents)\n\nThe Valdi CLI ships context files (\"skills\") that give AI agents accurate knowledge about Valdi APIs, patterns, and conventions. Install them once to reduce hallucinations:\n\n```bash\nnpm install -g @snap/valdi\nvaldi skills install # installs all skills for detected AI agents\n# or install by category:\nvaldi skills install --category=client # module development skills\nvaldi skills install --category=framework # framework internals skills\n```\n\nSkills are bundled inside the npm package — no network access required after install.\n\n## Contributing\n\nThis is an open-source project. When contributing:\n1. Follow the style guides\n2. Include tests for new features\n3. Update documentation\n4. Ensure cross-platform compatibility\n5. See `CONTRIBUTING.md` for full guidelines\n\n## Community & Support\n\n- **Documentation**: Comprehensive docs in `/docs/` directory\n- **Examples**: Working examples in `/apps/` directory\n- **Issues**: Report bugs and request features via GitHub issues\n- **Discussions**: Ask questions and share ideas in GitHub Discussions\n\n---\n\n*This document is intended for AI coding assistants to quickly understand the structure and conventions of the Valdi codebase. For human developers, please refer to the main README.md and comprehensive documentation in `/docs/`.*\n","category":"root","tokens":6020},{"name":".cursorrules","path":".cursorrules","title":".cursorrules","content":"# Valdi Open Source - Cursor Rules\n\n## ⚠️ Open Source Project\n\nThis is an open source project. Never commit secrets, API keys, or proprietary information.\n\n## 🚨 CRITICAL: This is NOT React!\n\nValdi uses TSX/JSX syntax but is **fundamentally different from React**. \n\n**Common AI mistakes:**\n- ❌ Suggesting `useState`, `useEffect`, `useContext` (don't exist!)\n- ❌ Functional components (don't exist!)\n- ❌ `this.props` (should be `this.viewModel`)\n- ❌ `markNeedsRender()`, `onMount()`, `onUpdate()` (wrong names/don't exist!)\n\n**Correct Valdi:**\n- ✅ `class MyComponent extends StatefulComponent`\n- ✅ `state = {}` + `this.setState()`\n- ✅ `this.viewModel` for props\n- ✅ `onCreate()`, `onViewModelUpdate()`, `onDestroy()` lifecycle\n\n## 📁 Context-Specific Rules\n\nCursor automatically loads additional rules based on where you're working:\n\n| Working In | See |\n|-----------|-----|\n| TypeScript/TSX components | `.cursor/rules/typescript-tsx.md` |\n| Swift compiler | `.cursor/rules/compiler.md` |\n| C++ runtime | `.cursor/rules/cpp-runtime.md` |\n| Android (Kotlin) | `.cursor/rules/android.md` |\n| iOS (Objective-C) | `.cursor/rules/ios.md` |\n| Bazel files | `.cursor/rules/bazel.md` |\n| Tests | `.cursor/rules/testing.md` |\n\n**→ Check `.cursor/rules/README.md` for the full list**\n\n## Quick Commands\n\n```bash\nbazel build //... # Build everything\nbazel test //... # Run all tests\nvaldi install ios # Build & install iOS app\nvaldi hotreload # Start hot reload\n```\n\n## More Information\n\n- **Comprehensive guide**: `/AGENTS.md` (621 lines)\n- **AI tooling**: `/docs/docs/ai-tooling.md`\n- **Support**: `/SUPPORT.md`\n- **Discussions**: https://github.com/Snapchat/Valdi/discussions\n- **Issues**: https://github.com/Snapchat/Valdi/issues\n","category":"root","tokens":441}]}