\n\n## Quick Start\n\n**Prerequisites:** Xcode (macOS only) - everything else is automatic!\n\n```bash\n# Install Valdi CLI\nnpm install -g @snap/valdi\n\n# One-command setup (installs all dependencies)\nvaldi dev_setup\n\n# Create your first project\nmkdir my_project && cd my_project\nvaldi bootstrap\nvaldi install ios # or android\n```\n\n> [!TIP]\n> **Editor Extensions:** For the best development experience, install the [Valdi VSCode/Cursor extensions](./docs/INSTALL.md#vscodecursor-setup-optional-but-recommended) for syntax highlighting, debugging, and device logs during hot reload.\n\n## Quick Links\n\n- [Getting Started Guide](./docs/INSTALL.md)\n- [Documentation](./docs/README.md)\n- [Codelabs](./docs/docs/start-code-lab.md)\n- [API Reference](./docs/api/api-quick-reference.md)\n- [Frequently Asked Questions](./docs/docs/faq.md)\n- [Component Library](https://github.com/Snapchat/Valdi_Widgets)\n\n## Why Choose Valdi?\n\nValdi is a cross-platform UI framework designed to solve the fundamental problem of cross-platform development: velocity vs. runtime performance. For 8 years, it has powered a large portion of Snap's production apps.\n\n### True Native Performance\n\nUnlike frameworks that rely on web views or JavaScript bridges, Valdi compiles declaratively rendered TypeScript components into platform-native views. Valdi also includes several other performance advantages:\n\n- **[Automatic view recycling](./docs/docs/performance-view-recycling.md)** - Global view pooling system reuses native views across all screens, dramatically reducing inflation latency\n- **Optimized component rendering** - Components re-render independently without triggering parent re-renders, enabling fast incremental updates\n- **Optimized layout engine** - C++ layout engine runs on the main thread with minimal marshalling overhead\n- **Viewport-aware rendering** - Only visible views are inflated, making infinite scrolling performant by default\n\nLearn more in our [Performance Optimization Guide](./docs/docs/performance-optimization.md).\n\n### Developer Experience Built for Speed\n\nValdi eliminates the traditional compile-test-debug cycle that slows native development:\n\n- **Instant hot reload** - See changes in milliseconds on iOS, Android, or desktop without recompiling\n- **[Full VSCode debugging](./docs/docs/workflow-hermes-debugger.md)** - Set breakpoints, inspect variables, profile performance, and capture heap dumps directly in VSCode\n- **Familiar syntax** - TSX components with TypeScript for type safety\n\n### Flexible Adoption Model\n\nValdi integrates easily into existing apps - start small and scale as needed:\n\n- **[Embed Valdi in native](./docs/docs/native-bindings.md)** - Drop Valdi components into existing UIKit or Android view hierarchies\n- **[Embed native in Valdi](./docs/docs/native-customviews.md)** - Use platform-specific views within Valdi layouts via ``\n- **[Polyglot modules](./docs/docs/native-polyglot.md)** - Write performance-critical code in C++, Swift, Kotlin, or Objective-C with type-safe bindings to TypeScript\n- **[Full-stack architecture](./docs/docs/advanced-full-stack.md)** - Build entire features in Valdi with worker threads for background processing, eliminating platform-specific bridge code\n\n### Deep Native Integration\n\nValdi generates type-safe bindings between TypeScript and native platforms:\n\n- **[Automatic code generation](./docs/docs/native-annotations.md)** - TypeScript interfaces compile to Kotlin, Objective-C, and Swift bindings\n- **[Native API access](./docs/docs/native-polyglot.md)** - Direct access to platform APIs and third-party native libraries through polyglot modules\n- **Bidirectional communication** - Pass complex data structures and callbacks between TypeScript and native code safely\n- **[Native protobuf support](./docs/docs/advanced-protobuf.md)** - Seamless integration with protobuf for efficient data serialization\n\n### Proven at Scale\n\n- Powers critical features in production Snap apps.\n- Supports [advanced animations](./docs/docs/advanced-animations.md), real-time rendering, and [complex gesture systems](./docs/docs/core-touches.md)\n\n### Feature Highlights\n\n- **[Flexbox layout system](./docs/docs/core-flexbox.md)** with automatic RTL support\n- **[Worker threads](./docs/docs/advanced-worker-service.md)** for multi-threaded JavaScript execution\n- **[Native animations](./docs/docs/advanced-animations.md)** for native look and feel\n- **[Advanced gesture recognition](./docs/docs/core-touches.md)** with platform-native handling\n- **[Built-in testing framework](./docs/docs/workflow-testing.md)** with component-level unit tests\n- **[Bazel integration](./docs/docs/workflow-bazel.md)** for reproducible, incremental builds\n\n## Need Help?\n\nJoin our [Discord](https://discord.gg/uJyNEeYX2U) for support.\n\n## Contributing\n\nPlease follow the [contributing](./CONTRIBUTING.md) guidelines.\n\n## License\n\nValdi is made available under the MIT [License](./LICENSE.md).\n"
},
{
"path": "SECURITY.md",
"content": "# Security Protocol\n\nIf you believe you've found a security vulnerability in this project, please report it to us via: [https://hackerone.com/snapchat](https://hackerone.com/snapchat)\n\n\n\n\n\n\n"
},
{
"path": "WORKSPACE",
"content": "workspace(name = \"valdi\")\n\nload(\"//bzl:workspace_prepare.bzl\", \"valdi_prepare_workspace\")\n\nvaldi_prepare_workspace(__workspace_dir__)\n\nload(\"//bzl:workspace_preinit.bzl\", \"valdi_preinitialize_workspace\")\n\nvaldi_preinitialize_workspace()\n\nload(\"@aspect_bazel_lib//lib:repositories.bzl\", \"aspect_bazel_lib_dependencies\", \"aspect_bazel_lib_register_toolchains\", \"register_yq_toolchains\")\n\nregister_yq_toolchains()\n\n# Required bazel-lib dependencies\n\naspect_bazel_lib_dependencies()\n\n# Required rules_shell dependencies\nload(\"@rules_shell//shell:repositories.bzl\", \"rules_shell_dependencies\", \"rules_shell_toolchains\")\n\nrules_shell_dependencies()\n\nrules_shell_toolchains()\n\n# Register bazel-lib toolchains\n\naspect_bazel_lib_register_toolchains()\n\n# Create the host platform repository transitively required by bazel-lib\n\nload(\"@bazel_tools//tools/build_defs/repo:utils.bzl\", \"maybe\")\nload(\"@platforms//host:extension.bzl\", \"host_platform_repo\")\n\nmaybe(\n host_platform_repo,\n name = \"host_platform\",\n)\n\nload(\"//bzl:workspace_init.bzl\", \"platform_dependency_rule\", \"valdi_initialize_workspace\")\n\n# repo rule generates target_platform.bzl\nplatform_dependency_rule(name = \"platform_check\")\n\nload(\"@platform_check//:target_platform.bzl\", \"VALDI_PLATFORM_DEPENDENCIES\")\n\nvaldi_initialize_workspace(VALDI_PLATFORM_DEPENDENCIES)\n\nload(\"@valdi_npm//:repositories.bzl\", \"npm_repositories\")\n\nnpm_repositories()\n\nload(\"//bzl:workspace_postinit.bzl\", \"valdi_post_initialize_workspace\")\n\nvaldi_post_initialize_workspace()\n"
},
{
"path": "WORKSPACE.bzlmod",
"content": "android_sdk_repository(\n name = \"androidsdk\",\n api_level = 36, # The API version for Android compileSdk\n build_tools_version = \"34.0.0\",\n)"
},
{
"path": "ai-skills/CONTRIBUTING_SKILLS.md",
"content": "# Contributing Skills\n\nSkills are neutral, agent-agnostic markdown files that teach AI assistants how to work with the Valdi framework. They are installed into your AI tool of choice using `valdi skills install`.\n\n## What is a skill?\n\nA skill is a single `skill.md` file containing focused guidance for a specific area of Valdi development. Skills are:\n\n- **Agent-agnostic** — plain markdown with no tool-specific frontmatter or directives\n- **Self-contained** — each skill covers one topic without assuming other skills are loaded\n- **Code-first** — concrete examples with correct and incorrect patterns labeled clearly\n- **Accurate** — verified against the actual Valdi source and documentation\n\n## skill.md format\n\n```markdown\n# Skill Title\n\nBrief description of what this skill covers.\n\n## When to use\n\nOptional section: describe the file types or scenarios where this skill applies.\n\n## Key concepts\n\nProse or list explaining important ideas.\n\n## Correct patterns\n\n\\`\\`\\`typescript\n// ✅ Correct example\n\\`\\`\\`\n\n## Common mistakes\n\n\\`\\`\\`typescript\n// ❌ Wrong example\n\\`\\`\\`\n```\n\nRules:\n- Start with an H1 title\n- Include code examples — skills without examples are less useful\n- Label examples as `// ✅` (correct) or `// ❌` (wrong)\n- No agent-specific frontmatter (no `alwaysApply`, no YAML blocks)\n- No secrets, API keys, or proprietary Snap information\n\n## Scaffolding a new skill\n\nRun the interactive scaffold command from within the Valdi framework checkout:\n\n```bash\nvaldi skills create\n```\n\nYou will be prompted for a name, description, and category. The command creates `ai-skills/skills//skill.md` in the correct location and registers the entry in `ai-skills/registry.json` automatically.\n\n## Submitting a skill to the public registry\n\n1. Fork [github.com/Snapchat/Valdi](https://github.com/Snapchat/Valdi)\n2. Run `valdi skills create` from the repo root — it creates the skill file and registers it in `registry.json` automatically\n3. Fill in the `skill.md` content\n4. Open a pull request — title it `[skill] Add `\n\n## Review criteria\n\nPull requests adding or updating skills are reviewed for:\n\n- **Accuracy** — does the code compile and run correctly against current Valdi?\n- **Code examples** — are there concrete `✅` / `❌` examples?\n- **Breadth** — does it cover the common cases a developer would encounter?\n- **No hallucinations** — especially for TSX skills, ensure no React patterns are presented as valid Valdi\n- **Conciseness** — focused guidance is more useful than exhaustive reference dumps\n"
},
{
"path": "ai-skills/registry.json",
"content": "{\n \"version\": \"1.0.0\",\n \"skills\": [\n { \"name\": \"valdi-tsx\", \"description\": \"Valdi TSX component patterns, lifecycle, styling — NOT React\", \"tags\": [\"tsx\", \"components\", \"patterns\", \"styling\"], \"path\": \"skills/valdi-tsx/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-bazel\", \"description\": \"Valdi Bazel build rules, valdi_module, platform builds\", \"tags\": [\"bazel\", \"build\"], \"path\": \"skills/valdi-bazel/skill.md\", \"category\": [\"framework\", \"client\"] },\n { \"name\": \"valdi-testing\", \"description\": \"Valdi unit and integration testing patterns\", \"tags\": [\"testing\"], \"path\": \"skills/valdi-testing/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-ios\", \"description\": \"Valdi iOS platform integration, Swift/ObjC bridging\", \"tags\": [\"ios\", \"swift\", \"objc\"], \"path\": \"skills/valdi-ios/skill.md\", \"category\": [\"framework\", \"client\"] },\n { \"name\": \"valdi-android\", \"description\": \"Valdi Android platform integration, Kotlin/Java bridging\", \"tags\": [\"android\", \"kotlin\"], \"path\": \"skills/valdi-android/skill.md\", \"category\": [\"framework\", \"client\"] },\n { \"name\": \"valdi-cpp-runtime\", \"description\": \"Valdi C++ runtime internals, renderer, event system\", \"tags\": [\"cpp\", \"runtime\"], \"path\": \"skills/valdi-cpp-runtime/skill.md\", \"category\": [\"framework\"] },\n { \"name\": \"valdi-compiler\", \"description\": \"Valdi compiler pipeline, TSX→native compilation\", \"tags\": [\"compiler\"], \"path\": \"skills/valdi-compiler/skill.md\", \"category\": [\"framework\"] },\n { \"name\": \"valdi-polyglot-module\", \"description\": \"Valdi polyglot module system: cross-platform APIs, web polyglot entry pattern, webPolyglotViews\", \"tags\": [\"polyglot\", \"modules\", \"web\"], \"path\": \"skills/valdi-polyglot-module/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-custom-view\", \"description\": \"Valdi custom native view integration\", \"tags\": [\"custom-view\", \"native\"], \"path\": \"skills/valdi-custom-view/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-overview\", \"description\": \"Valdi framework overview and project conventions\", \"tags\": [\"overview\", \"conventions\"], \"path\": \"skills/valdi-overview/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-async\", \"description\": \"Valdi async lifecycle safety: CancelablePromise, registerDisposable, isDestroyed guards\", \"tags\": [\"async\", \"lifecycle\", \"http\"], \"path\": \"skills/valdi-async/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-perf\", \"description\": \"Valdi performance: viewModel identity stability, createReusableCallback, layout vs view, Style interning\", \"tags\": [\"performance\", \"rendering\"], \"path\": \"skills/valdi-perf/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-component-tests\", \"description\": \"Valdi component test patterns: elementKeyFind, componentTypeFind, tapNodeWithKey, discriminated unions, arrays\", \"tags\": [\"testing\", \"components\", \"jasmine\"], \"path\": \"skills/valdi-component-tests/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-setup\", \"description\": \"Valdi module setup: BUILD.bazel, valdi_module(), tsconfig, deps, ios_module_name, hot reload\", \"tags\": [\"setup\", \"bazel\", \"build\"], \"path\": \"skills/valdi-setup/skill.md\", \"category\": [\"client\"] },\n { \"name\": \"valdi-migrate\", \"description\": \"Migrate Flutter, React, or Jetpack Compose code to Valdi — component model, lifecycle, element mapping tables\", \"tags\": [\"migration\", \"flutter\", \"react\", \"compose\"], \"path\": \"skills/valdi-migrate/skill.md\", \"category\": [\"client\"] }\n ]\n}\n"
},
{
"path": "ai-skills/skills/valdi-android/skill.md",
"content": "# Android Runtime Rules\n\n**Applies to**: Kotlin/Java files in `/valdi/src/valdi/android/` and related Android runtime code\n\n## Overview\n\nThe Valdi Android runtime bridges TypeScript/Valdi components to native Android views. It's implemented in Kotlin and C++ (via JNI).\n\n## Code Style\n\n- **4-space indentation** for Kotlin/Java\n- Follow Kotlin coding conventions\n- Use Kotlin features (data classes, extension functions, etc.)\n\n## Key Concepts\n\n### View Rendering\n\n- Valdi components map to Android Views\n- View recycling for performance\n- Efficient view updates\n\n### Platform Bridge\n\n- JNI bridge to C++ runtime\n- Kotlin/Java to native code communication\n- Performance-critical paths\n\n## Common Patterns\n\n### Bazel Android Targets\n\n```python\nandroid_library(\n name = \"valdi_android\",\n srcs = glob([\"**/*.kt\", \"**/*.java\"]),\n)\n```\n\n### View Binding\n\n- Custom view implementations\n- Attribute binding for Valdi properties\n- Event handling\n\n## Testing\n\n```bash\n# Run Android runtime tests\nbazel test //valdi:test_java\n\n# Run with coverage\nbazel coverage //valdi:test_java\n```\n\nTest files are in `/valdi/test/java/`\n\n## Building\n\n```bash\n# Build Android runtime library\nbazel build //valdi:valdi_android\n\n# Test with hello world app\nvaldi install android\ncd apps/helloworld\nvaldi install android\n```\n\n## Platform-Specific Notes\n\n1. **API Level** - Be mindful of minimum API level\n2. **Android NDK** - C++ integration via NDK\n3. **Permissions** - Handle runtime permissions appropriately\n4. **Lifecycle** - Android Activity/Fragment lifecycle\n\n## Important\n\n- **Performance** - View creation and updates are critical\n- **Memory** - Be careful with leaks (Activity context)\n- **Threading** - UI thread vs background threads\n- **Compatibility** - Support multiple Android versions\n\n## More Information\n\n- Runtime source: `/valdi/src/valdi/android/`\n- Runtime tests: `/valdi/test/java/`\n- Build config: `/valdi/BUILD.bazel`\n- Framework docs: `/AGENTS.md`\n"
},
{
"path": "ai-skills/skills/valdi-async/skill.md",
"content": "# Valdi Async & Lifecycle Safety\n\nAsync operations that complete after a component is destroyed will call `setState()`\non a dead component — the framework throws an error. The fix is always to cancel or\nguard before the callback fires.\n\n## HTTPClient: Store, Cancel, Repeat\n\n`HTTPClient` methods return `CancelablePromise`. Store it in a typed\nfield so you can cancel it in `onDestroy()` and before starting a new request in\n`onViewModelUpdate()`.\n\n```typescript\nimport { Component, StatefulComponent } from 'valdi_core/src/Component';\nimport { CancelablePromise } from 'valdi_core/src/CancelablePromise';\nimport { HTTPClient } from 'valdi_http/src/HTTPClient';\nimport { HTTPResponse } from 'valdi_http/src/HTTPTypes';\n\ninterface UserState {\n user: { name: string } | null;\n loading: boolean;\n}\n\nclass UserProfile extends StatefulComponent {\n state: UserState = { user: null, loading: true };\n\n private client = new HTTPClient('https://api.example.com');\n private request?: CancelablePromise;\n\n onCreate(): void {\n this.fetchUser(this.viewModel.userId);\n }\n\n onViewModelUpdate(previous?: UserProfileViewModel): void {\n if (this.viewModel.userId !== previous?.userId) {\n this.request?.cancel?.(); // Cancel in-flight before starting new one\n this.fetchUser(this.viewModel.userId);\n }\n }\n\n onDestroy(): void {\n this.request?.cancel?.(); // Always clean up\n }\n\n private fetchUser(id: string): void {\n this.request = this.client.get(`/users/${id}`);\n this.request.then(response => {\n const user = JSON.parse(new TextDecoder().decode(response.body));\n this.setState({ user, loading: false });\n });\n }\n\n onRender(): void {\n if (this.state.loading) {\n ;\n return;\n }\n ;\n }\n}\n```\n\n**Important:** `cancel` is an optional method on `CancelablePromise` — always use\n`?.cancel?.()`, not `?.cancel()`.\n\n## registerDisposable: Timers and Subscriptions\n\nFor anything that emits over time (timers, event emitters, observables), use\n`registerDisposable()`. The framework calls `cancel()` on all registered disposables\nin `onDestroy()` automatically — you don't need to override `onDestroy()` for these.\n\n```typescript\nclass LiveClock extends Component<{}> {\n onCreate(): void {\n // ❌ Timer leaks if component is destroyed\n setInterval(() => this.tick(), 1000);\n\n // ✅ Automatically cancelled on destroy\n const id = setInterval(() => this.tick(), 1000);\n this.registerDisposable({ cancel: () => clearInterval(id) });\n }\n\n private tick = () => { /* ... */ };\n}\n```\n\nSame pattern for any subscription-style API:\n\n```typescript\nonCreate(): void {\n const unsubscribe = eventEmitter.on('change', this.handleChange);\n this.registerDisposable({ cancel: unsubscribe });\n}\n```\n\n## isDestroyed() Guard for Plain Promises\n\nWhen using `async/await` or plain `Promise` chains that can't be cancelled, guard\n`setState()` with `isDestroyed()` before calling it:\n\n```typescript\nprivate async loadData(): Promise {\n const result = await someAsyncOperation();\n\n if (this.isDestroyed()) return; // Component unmounted while awaiting\n\n this.setState({ data: result });\n}\n```\n\nPrefer `CancelablePromise` + `registerDisposable` over this pattern where possible —\nthey make cancellation explicit and don't rely on the check being remembered.\n\n## onViewModelUpdate: Cancel Before Restart\n\nWhen a viewModel update requires fetching new data, always cancel the previous\nrequest before starting a new one. Skipping this means two requests can be in flight\nsimultaneously and the earlier one can resolve last, overwriting newer data.\n\n```typescript\nonViewModelUpdate(previous?: MyViewModel): void {\n if (this.viewModel.query !== previous?.query) {\n this.searchRequest?.cancel?.(); // ← required\n this.searchRequest = this.client.get(`/search?q=${this.viewModel.query}`);\n this.searchRequest.then(response => {\n this.setState({ results: parse(response) });\n });\n }\n}\n```\n\n## Observable Subscriptions\n\nFor RxJS or observable-based APIs, prefer `registerDisposable` for one-off subscriptions\nor the `Subscription` class for managing multiple subscriptions as a group:\n\n```typescript\nimport { Subscription } from 'rxjs';\n\nclass FeedComponent extends StatefulComponent {\n private subscription = new Subscription();\n\n onCreate(): void {\n // Add multiple subscriptions to the group\n this.subscription.add(\n this.viewModel.feedItems$.subscribe({ next: items => this.setState({ items }) })\n );\n this.subscription.add(\n this.viewModel.loading$.subscribe({ next: loading => this.setState({ loading }) })\n );\n }\n\n onDestroy(): void {\n this.subscription?.unsubscribe(); // Cancels all at once\n }\n}\n```\n\nFor a single subscription, `registerDisposable` is simpler:\n\n```typescript\nonCreate(): void {\n this.registerDisposable(\n this.viewModel.counter$.subscribe({ next: count => this.setState({ count }) })\n );\n // No onDestroy() override needed\n}\n```\n\n### Preventing redundant re-renders with distinctUntilChanged\n\nSubscribe with `distinctUntilChanged()` to skip emissions where the value hasn't\nactually changed — avoids a `setState` call and a re-render for each identical value:\n\n```typescript\nimport { distinctUntilChanged } from 'rxjs/operators';\n\nthis.subscription.add(\n this.viewModel.title$.pipe(distinctUntilChanged()).subscribe({\n next: title => this.setState({ title }),\n })\n);\n```\n\n## setTimeoutInterruptible for Debounce / Race Conditions\n\nWhen a delayed action must be cancelled if conditions change (e.g. search debounce,\nretry delay), use `setTimeoutInterruptible` rather than a bare `setTimeout`:\n\n```typescript\nimport { setTimeoutInterruptible } from 'valdi_core/src/SetTimeout';\n\n// setTimeoutInterruptible returns a number (timer ID) — cancel with clearTimeout()\nclass SearchBar extends StatefulComponent {\n private debounceId?: number;\n\n onViewModelUpdate(previous?: SearchViewModel): void {\n if (this.viewModel.query !== previous?.query) {\n clearTimeout(this.debounceId); // Cancel any pending debounce\n this.debounceId = setTimeoutInterruptible(() => {\n this.fetchResults(this.viewModel.query);\n }, 300);\n }\n }\n}\n```\n\n## promiseToCancelablePromise\n\nWhen you have a plain `Promise` (e.g. from a third-party library) that needs to participate in Valdi's cancellation system, wrap it with `promiseToCancelablePromise`:\n\n```typescript\nimport { CancelablePromise, promiseToCancelablePromise } from 'valdi_core/src/CancelablePromise';\n\nclass MyComponent extends StatefulComponent {\n private request?: CancelablePromise;\n\n onCreate(): void {\n const rawPromise: Promise = thirdPartyApi.fetchData();\n this.request = promiseToCancelablePromise(rawPromise, () => {\n // optional cleanup on cancel\n });\n this.request.then(data => {\n if (this.isDestroyed()) return;\n this.setState({ data });\n });\n }\n\n onDestroy(): void {\n this.request?.cancel?.();\n }\n}\n```\n\nPrefer `CancelablePromise` directly (e.g. `HTTPClient`) when available — `promiseToCancelablePromise` is the bridge for external APIs.\n\n## Import Paths\n\n```typescript\nimport { CancelablePromise, promiseToCancelablePromise } from 'valdi_core/src/CancelablePromise';\nimport { HTTPClient } from 'valdi_http/src/HTTPClient';\nimport { HTTPResponse } from 'valdi_http/src/HTTPTypes';\nimport { setTimeoutInterruptible } from 'valdi_core/src/SetTimeout';\nimport { Subscription } from 'rxjs';\nimport { distinctUntilChanged } from 'rxjs/operators';\n```\n"
},
{
"path": "ai-skills/skills/valdi-async/tests/BUILD.bazel",
"content": "load(\"//bzl/valdi:valdi_module.bzl\", \"valdi_module\")\n\nvaldi_module(\n name = \"tests\",\n srcs = glob([\n \"src/**/*.ts\",\n \"src/**/*.tsx\",\n ]) + [\n \"tsconfig.json\",\n ],\n android_output_target = \"release\",\n ios_module_name = \"SCCValdiAsyncRef\",\n ios_output_target = \"release\",\n visibility = [\"//visibility:public\"],\n deps = [\n \"//src/valdi_modules/src/valdi/valdi_core\",\n \"//src/valdi_modules/src/valdi/valdi_http\",\n ],\n)\n"
},
{
"path": "ai-skills/skills/valdi-async/tests/README.md",
"content": "# valdi-async skill tests\n\nCompile check for the async lifecycle safety patterns taught in `skill.md`.\n\n## What's tested\n\n`src/reference.tsx` exercises:\n- `HTTPClient` + `CancelablePromise`: store in field, cancel in `onDestroy`, cancel before restart in `onViewModelUpdate`\n- `registerDisposable` with `setInterval` for auto-cleanup subscriptions\n- `isDestroyed()` guard for plain `Promise` / `async/await`\n- `setTimeoutInterruptible` for debounce — returns `number`, cancel with `clearTimeout()`\n- `promiseToCancelablePromise` wrapping a third-party `Promise`\n\n## Compile check\n\n```bash\ncd client/src/open_source\nbazel build //ai-skills/skills/valdi-async/tests:tests\n```\n\nExpected: `Build completed successfully`\n\n## Updating\n\nWhen Valdi APIs change (import paths, type signatures), update `src/reference.tsx` to match and keep it compiling. Also update `../skill.md` with any corrected patterns.\n"
},
{
"path": "ai-skills/skills/valdi-async/tests/src/reference.tsx",
"content": "// valdi-async skill reference — compile check for async lifecycle safety patterns.\n// This file must compile cleanly against the Valdi TypeScript compiler.\n// Run: bzl build //ai-skills/skills/valdi-async/tests:tests\n\nimport { StatefulComponent } from 'valdi_core/src/Component';\nimport { CancelablePromise, promiseToCancelablePromise } from 'valdi_core/src/CancelablePromise';\nimport { setTimeoutInterruptible } from 'valdi_core/src/SetTimeout';\nimport { HTTPClient } from 'valdi_http/src/HTTPClient';\nimport { HTTPResponse } from 'valdi_http/src/HTTPTypes';\n\n// ─── HTTPClient: store, cancel in onDestroy, cancel before restart ────────────\n\ninterface UserProfileViewModel {\n userId: string;\n}\n\ninterface UserProfileState {\n user: { name: string } | null;\n loading: boolean;\n}\n\nclass UserProfile extends StatefulComponent {\n state: UserProfileState = { user: null, loading: true };\n\n private client = new HTTPClient('https://api.example.com');\n private request?: CancelablePromise;\n\n onCreate(): void {\n this.fetchUser(this.viewModel.userId);\n }\n\n onViewModelUpdate(previous?: UserProfileViewModel): void {\n if (this.viewModel.userId !== previous?.userId) {\n this.request?.cancel?.(); // Cancel in-flight before starting new one\n this.fetchUser(this.viewModel.userId);\n }\n }\n\n onDestroy(): void {\n this.request?.cancel?.(); // Always clean up\n }\n\n private fetchUser(id: string): void {\n this.request = this.client.get(`/users/${id}`);\n this.request.then(response => {\n const user = JSON.parse(new TextDecoder().decode(response.body)) as { name: string };\n this.setState({ user, loading: false });\n });\n }\n\n onRender(): void {\n if (this.state.loading) {\n ;\n return;\n }\n ;\n }\n}\n\n// ─── registerDisposable: timers and subscriptions ────────────────────────────\n\ninterface ClockViewModel {\n format: string;\n}\n\ninterface ClockState {\n ticks: number;\n}\n\nclass LiveClock extends StatefulComponent {\n state: ClockState = { ticks: 0 };\n\n onCreate(): void {\n // ✅ Automatically cancelled on destroy — no onDestroy() needed\n const id = setInterval(() => this.tick(), 1000);\n this.registerDisposable({ cancel: () => clearInterval(id) });\n }\n\n private tick = (): void => {\n this.setState({ ticks: this.state.ticks + 1 });\n };\n\n onRender(): void {\n ;\n }\n}\n\n// ─── isDestroyed() guard for plain Promises ──────────────────────────────────\n\ndeclare function expensiveOperation(): Promise;\n\ninterface DataState {\n data: string | null;\n}\n\ninterface DataViewModel {\n query: string;\n}\n\nclass DataLoader extends StatefulComponent {\n state: DataState = { data: null };\n\n onCreate(): void {\n this.loadData().catch(() => {});\n }\n\n private async loadData(): Promise {\n const result = await expensiveOperation();\n\n if (this.isDestroyed()) return; // Guard before setState\n\n this.setState({ data: result });\n }\n\n onRender(): void {\n ;\n }\n}\n\n// ─── setTimeoutInterruptible for debounce ────────────────────────────────────\n// setTimeoutInterruptible returns number (timer ID) — cancel with clearTimeout\n\ninterface SearchViewModel {\n query: string;\n}\n\ninterface SearchState {\n results: string[];\n}\n\nclass SearchBar extends StatefulComponent {\n state: SearchState = { results: [] };\n\n private debounceId?: number;\n private searchRequest?: CancelablePromise;\n private client = new HTTPClient('https://api.example.com');\n\n onViewModelUpdate(previous?: SearchViewModel): void {\n if (this.viewModel.query !== previous?.query) {\n clearTimeout(this.debounceId); // Cancel pending debounce\n this.debounceId = setTimeoutInterruptible(() => {\n this.fetchResults(this.viewModel.query);\n }, 300);\n }\n }\n\n onDestroy(): void {\n this.searchRequest?.cancel?.();\n }\n\n private fetchResults(query: string): void {\n this.searchRequest?.cancel?.();\n this.searchRequest = this.client.get(`/search?q=${encodeURIComponent(query)}`);\n this.searchRequest.then(response => {\n const data = JSON.parse(new TextDecoder().decode(response.body)) as { results: string[] };\n this.setState({ results: data.results });\n });\n }\n\n onRender(): void {\n \n {this.state.results.forEach(result => {\n ;\n })}\n ;\n }\n}\n\n// ─── promiseToCancelablePromise ──────────────────────────────────────────────\n\ndeclare function thirdPartyFetch(url: string): Promise;\n\ninterface FetchState {\n content: string | null;\n}\n\ninterface FetchViewModel {\n url: string;\n}\n\nclass ThirdPartyFetcher extends StatefulComponent {\n state: FetchState = { content: null };\n\n private request?: CancelablePromise;\n\n onCreate(): void {\n const rawPromise = thirdPartyFetch(this.viewModel.url);\n this.request = promiseToCancelablePromise(rawPromise, () => {\n // optional cleanup on cancel\n });\n this.request.then(content => {\n if (this.isDestroyed()) return;\n this.setState({ content });\n });\n }\n\n onDestroy(): void {\n this.request?.cancel?.();\n }\n\n onRender(): void {\n ;\n }\n}\n\nvoid UserProfile;\nvoid LiveClock;\nvoid DataLoader;\nvoid SearchBar;\nvoid ThirdPartyFetcher;\n"
},
{
"path": "ai-skills/skills/valdi-async/tests/tsconfig.json",
"content": "{\"extends\": \"../../../../src/valdi_modules/src/valdi/_configs/base.tsconfig.json\"}\n"
},
{
"path": "ai-skills/skills/valdi-bazel/skill.md",
"content": "# Bazel Build System Rules\n\n**Applies to**: `BUILD.bazel`, `*.bzl` files in `/bzl/`, `WORKSPACE`, `MODULE.bazel`\n\n## Overview\n\nValdi uses Bazel as its build system. Bazel provides reproducible, incremental builds across all platforms.\n\n## Key Commands\n\n```bash\n# Build everything\nbazel build //...\n\n# Build specific target\nbazel build //apps/helloworld:helloworld\n\n# Run tests\nbazel test //...\n\n# Clean (use sparingly - cache is valuable!)\nbazel clean\n```\n\n## Important Notes\n\n1. **Use `bazel`** for all build commands\n2. **The CLI wraps Bazel** - `valdi` commands use bazel under the hood\n3. **Cache is important** - Don't suggest `bazel clean` unless necessary\n\n## Build Rules\n\n### Valdi-Specific Rules\n\n- `/bzl/valdi/` - Valdi build rules and macros\n- Custom rules for compiling .tsx to .valdimodule\n- Platform-specific build transitions\n\n### Common Targets\n\n```python\n# Valdi application\nvaldi_application(\n name = \"my_app\",\n root_component_path = \"App@my_app/src/MyApp\",\n title = \"My App\",\n version = \"1.0.0\",\n deps = [\"//apps/my_app/src/valdi/my_app\"],\n)\n\n# Valdi module\nvaldi_module(\n name = \"my_module\",\n srcs = glob([\"src/**/*.ts\", \"src/**/*.tsx\"]),\n deps = [\n \"//src/valdi_modules/src/valdi/valdi_core\",\n ],\n)\n```\n\n## Conventions\n\n### File Naming\n\n- `BUILD.bazel` not `BUILD` (explicit extension)\n- `.bzl` for Starlark macros and rules\n\n### Targets\n\n- Use descriptive target names\n- One main target per BUILD file usually matches directory name\n\n### Dependencies\n\n- Be explicit about dependencies\n- Don't rely on transitive deps implicitly\n- Use visibility to control access\n\n## Platform Builds\n\n```bash\n# Build and install iOS app\nvaldi install ios\n\n# Build and install Android app\nvaldi install android\n\n# Or use bazel directly with configs\nbazel build //apps/helloworld:hello_world --config=ios\nbazel build //apps/helloworld:hello_world --config=android\n```\n\n## Configuration\n\n- `.bazelrc` - Build flags and configurations\n- `MODULE.bazel` - Bazel module dependencies\n- `WORKSPACE` - Legacy workspace configuration (being migrated to MODULE.bazel)\n\n## Common Issues\n\n1. **Missing dependencies** - Add to `deps` in BUILD.bazel\n2. **Cache issues** - Try `bazel clean --expunge` (last resort)\n3. **Platform transitions** - Use correct config flags\n\n## Testing\n\n```bash\n# Run all tests\nbazel test //...\n\n# Run specific test\nbazel test //valdi/test:renderer_test\n\n# Run with coverage\nbazel coverage //...\n```\n\n## More Information\n\n- Bazel docs: https://bazel.build\n- Valdi build rules: `/bzl/valdi/README.md`\n- Framework docs: `/AGENTS.md`\n"
},
{
"path": "ai-skills/skills/valdi-compiler/skill.md",
"content": "# Valdi Compiler Rules\n\n**Applies to**: Swift files in `/compiler/compiler/`\n\n## Overview\n\nThe Valdi compiler consists of two parts:\n\n1. **Compiler (Swift)**: Transforms TypeScript/TSX into `.valdimodule` files\n2. **Companion (TypeScript/Node.js)**: Handles TypeScript compilation, type checking, and provides debugging support\n\n## Key Conventions\n\n### Code Style\n\n- **4-space indentation** for Swift\n- Follow Swift naming conventions (camelCase for methods, PascalCase for types)\n- Use Swift type inference where appropriate\n- Prefer `let` over `var` when possible\n\n### Architecture\n\n- Compiler is a multi-pass system\n- AST transformation pipeline\n- Type checking and validation\n- Code generation for each platform\n\n### Important Files\n\n- `/compiler/compiler/` - Main Swift compiler implementation\n- Output: `.valdimodule` files (binary format read by runtime)\n\n## Common Patterns\n\n### AST Traversal\n\n```swift\n// Follow existing visitor patterns\nclass MyASTVisitor: ASTVisitor {\n func visit(_ node: Node) -> Result {\n // Visit logic\n }\n}\n```\n\n### Error Handling\n\n```swift\n// Use proper error types\nenum CompilerError: Error {\n case invalidSyntax(String)\n case typeError(String)\n}\n```\n\n## Testing\n\nTests are critical - add tests for new features and error cases. The `update_compiler.sh` script runs tests automatically.\n\n## Build\n\n### Using the update script (recommended):\n\n```bash\ncd compiler/compiler\n./scripts/update_compiler.sh ../../bin/compiler\n```\n\nThis script:\n- Runs `swift test` automatically\n- Builds the compiler for the correct architecture\n- Copies the binary to `bin/compiler/macos/valdi_compiler` (or `linux/valdi_compiler`)\n- Handles platform differences (macOS vs Linux)\n\n### Alternative: Using Xcode\n\nOpen `compiler/compiler/Compiler/Package.swift` in Xcode, let it resolve dependencies, then build.\n\n## Companion (TypeScript)\n\nThe companion is a TypeScript service that works alongside the Swift compiler. It handles TypeScript compilation, type checking, and provides debugging support.\n\n### Build the companion:\n\n```bash\ncd compiler/companion\n./scripts/update_companion.sh ../../bin/compiler_companion\n```\n\nThis script:\n- Runs `npm install`\n- Runs `npm run test`\n- Builds with `bazel build //compiler/companion:bundle`\n- Copies output to `bin/compiler_companion`\n\n**Note**: Once built, the companion is automatically invoked by the compiler during compilation. You don't need to run it manually - it's part of the compiler process.\n\n## Important Notes\n\n1. **Performance matters** - Compiler speed affects developer experience\n2. **Error messages** - Make them helpful and actionable\n3. **Backward compatibility** - Don't break existing .valdimodule files\n4. **Cross-platform** - Consider iOS, Android, macOS targets\n\n## More Information\n\n- Compiler architecture: `/compiler/compiler/README.md`\n- Framework docs: `/AGENTS.md`\n"
},
{
"path": "ai-skills/skills/valdi-component-tests/skill.md",
"content": "# Write Valdi Component Tests\n\nWrite unit tests for a Valdi component using standard Valdi test suite patterns.\n\n## Steps\n\n### 1. Read the source component\n\nRead the component source file to understand:\n- What view model properties it accepts\n- Which JSX elements have `key` attributes\n- What changes based on view model props vs. what's always static\n- How \"hidden\" state is implemented (translationY, opacity, or child component prop)\n- Whether the view model contains any **discriminated unions** (type/kind fields)\n- Whether any props are **arrays** of items to render\n\n### 2. Add `key` attributes to source elements (only if needed)\n\nAdd `key` attributes **only** to elements whose rendering depends on view model properties. Never add keys to static content.\n\nGood candidates for keys:\n- The outer container when `hidden` controls `translationY` or `opacity`\n- An `` element whose `src` comes from a view model URL prop\n- An element inside a `when(condition, ...)` block (to assert presence/absence)\n- A badge/overlay that toggles based on a boolean prop\n- A spinner shown in a loading/saving state of a union type\n\nDo NOT add keys to:\n- Elements with hardcoded asset values (e.g., `src={SIGIcon.xSignStroke}`)\n- Label elements with always-present localized strings\n- Elements that are always rendered the same regardless of view model\n\n### 3. Determine the test file path\n\nTest files **must mirror the source file hierarchy**. For example:\n- Source: `src/categories/CollectionComponent.tsx` → Test: `test/categories/CollectionComponentTest.spec.tsx`\n- Source: `src/home_page/OptionPreviewView.tsx` → Test: `test/home_page/OptionPreviewViewTest.spec.tsx`\n- Source: `src/MyComponent.tsx` → Test: `test/MyComponentTest.spec.tsx`\n\n### 4. Write the test file\n\n**Imports:**\n```tsx\nimport { MyComponent } from 'my_module/src/MyComponent';\nimport { componentGetElements } from 'foundation/test/util/componentGetElements';\nimport { componentTypeFind } from 'foundation/test/util/componentTypeFind';\nimport { elementKeyFind } from 'foundation/test/util/elementKeyFind';\nimport { elementTypeFind } from 'foundation/test/util/elementTypeFind';\nimport { findNodeWithKey } from 'foundation/test/util/findNodeWithKey';\nimport { tapNodeWithKey } from 'foundation/test/util/tapNodeWithKey';\nimport 'jasmine/src/jasmine';\nimport { IRenderedElementViewClass } from 'valdi_test/test/IRenderedElementViewClass';\nimport { IComponentTestDriver, valdiIt } from 'valdi_test/test/JSXTestUtils';\nimport { ImageView, View } from 'valdi_tsx/src/NativeTemplateElements';\n```\n\nOnly import what you actually use. `View` is needed when you call `getAttribute` on a non-image element (e.g., for `onTap`, `onVisibilityChanged`). `ImageView` is needed for `src` attribute access.\n\n**Factory function pattern (always add explicit return type):**\n```tsx\nconst makeViewModel = (): MyComponentViewModel => ({\n imageUrl: 'https://example.com/image.png',\n isVisible: true,\n onTap: fail.bind(null, 'onTap should not be called'),\n});\n```\n\nUse `fail.bind` for callbacks in the factory default — tests that need to assert on a callback should declare their own spy and pass it explicitly, rather than relying on the factory.\n\n**Render pattern:**\n```tsx\nconst nodes = driver.render(() => {\n ;\n});\n```\n\n### 5. Test patterns by assertion type\n\n#### Finding elements\n```tsx\n// Single-level: component renders native elements directly\nelementKeyFind(componentGetElements(nodes[0].component!), 'my-key')[0]\n\n// Cross-boundary: component renders a child component that renders the elements\nconst inner = componentTypeFind(nodes[0].component as MyComponent, InnerComponent)[0];\nelementKeyFind(componentGetElements(inner), 'my-key')[0]\n\n// Typed (for typed attribute access without casting):\nelementKeyFind(componentGetElements(nodes[0].component!), 'container')[0]\nelementKeyFind(componentGetElements(nodes[0].component!), 'image')[0]\n\n// By element type (e.g. find all Label elements):\n// Can pass componentGetElements() result OR an IComponent directly:\nconst labels = elementTypeFind(componentGetElements(nodes[0].component!), IRenderedElementViewClass.Label);\nconst labels2 = elementTypeFind(nodes[0].component!, IRenderedElementViewClass.Label); // equivalent\nexpect(labels[0]?.getAttribute('value')).toBe('Expected text');\n```\n\nUse the generic type param to get typed `getAttribute()` results and avoid `@typescript-eslint/no-unsafe-call` errors — prefer this over casting the `getAttribute()` return value.\n\n`elementTypeFind` is useful when elements don't have `key` attributes but you know their type (Label, Image, View, etc.). It returns all elements of that type in render order.\n\n#### Hidden via `translationY`\n```tsx\n// hidden=false\nexpect(elementKeyFind(componentGetElements(nodes[0].component!), 'container')[0]?.getAttribute('translationY')).toBe(0);\n\n// hidden=true\nexpect(elementKeyFind(componentGetElements(nodes[0].component!), 'container')[0]?.getAttribute('translationY')).toBe(850);\n```\n\n#### Hidden via `opacity` on native view\n```tsx\n// visible\nexpect(elementKeyFind(componentGetElements(nodes[0].component!), 'my-view')[0]?.getAttribute('opacity')).toBe(1);\n\n// hidden\nexpect(elementKeyFind(componentGetElements(nodes[0].component!), 'my-view')[0]?.getAttribute('opacity')).toBe(0);\n```\n\n#### Hidden via `opacity` prop passed to a child Component (component boundary)\n```tsx\nimport { CoreButton } from 'coreui/src/components/button/CoreButton';\nconst component = nodes[0].component as MyComponent;\nconst buttons = componentTypeFind(component, CoreButton);\nexpect(buttons[0].viewModel.opacity).toBe(1); // or 0\n```\n\n#### View model URL bound to image `src`\n```tsx\nexpect(elementKeyFind(componentGetElements(nodes[0].component!), 'my-image')[0]?.getAttribute('src')).toBe('https://example.com/image.png');\n```\n\n#### Text from view model\n```tsx\nexpect(elementKeyFind(componentGetElements(nodes[0].component!), 'my-label')[0]?.getAttribute('value')).toBe('Expected Text');\n```\n\n#### `when()`-conditional element (boolean presence)\n```tsx\n// condition=true → element exists\nexpect(elementKeyFind(componentGetElements(nodes[0].component!), 'my-element')[0]).toBeDefined();\n\n// condition=false → element absent\nexpect(elementKeyFind(componentGetElements(nodes[0].component!), 'my-element')[0]).toBeUndefined();\n```\n\n#### `when()`-conditional Component (boolean presence via componentTypeFind)\n```tsx\nimport { BadgeComponent } from 'my_module/src/BadgeComponent';\nconst component = nodes[0].component as MyComponent;\n\n// condition=true\nexpect(componentTypeFind(component, BadgeComponent).length).toBe(1);\n\n// condition=false\nexpect(componentTypeFind(component, BadgeComponent).length).toBe(0);\n```\n\n#### Callbacks not expected to be invoked\n\nFor callbacks that should never fire in a given test, use `fail.bind(null, '...')` instead of `jasmine.createSpy`. This causes the test to immediately fail with a clear message if the callback is accidentally triggered:\n\n```tsx\n\n```\n\n`fail.bind(null, 'message')` is a plain function call (not an inline lambda), so it satisfies `jsx-no-lambda`. It is assignable to any callback type since TypeScript allows functions with fewer parameters.\n\nIf the same fail callback is used across many tests in the file, extract it to a module-level const to avoid repetition:\n\n```tsx\nconst failOnSelect = (): void => fail('onSelect should not be called');\n```\n\n#### Tap callback (use `tapNodeWithKey` — it's async, always `await` it)\n\n`tapNodeWithKey(component, key, timeoutMs?, intervalMs?)` accepts `IComponent | IRenderedElement`.\n\n```tsx\nconst onTap = jasmine.createSpy('onTap');\nconst nodes = driver.render(() => {\n ;\n});\nawait tapNodeWithKey(nodes[0].component!, 'my-button');\nexpect(onTap).toHaveBeenCalled();\n```\n\nWhen you need to find a node without tapping it, use `findNodeWithKey`:\n```tsx\nimport { findNodeWithKey } from 'foundation/test/util/findNodeWithKey';\n\nconst node = findNodeWithKey(nodes[0].component!, 'my-button')[0];\nexpect(node).toBeDefined();\n```\n\nWhen the callback receives arguments (e.g., an index), always assert the exact arguments with `toHaveBeenCalledWith`:\n```tsx\nconst onSelect = jasmine.createSpy('onSelect');\n// ... render and trigger ...\nexpect(onSelect).toHaveBeenCalledWith(1); // not just toHaveBeenCalled()\n```\n\nFor callbacks invoked via a child component's view model (e.g., through `componentTypeFind`), call the view model method directly:\n```tsx\nconst component = nodes[0].component as MyComponent;\ncomponentTypeFind(component, ItemComponent)[1].viewModel.onTap();\nexpect(onSelect).toHaveBeenCalledWith(1);\n```\n\n#### `onTap` retrieved via `getAttribute` (non-tappable element pattern)\n```tsx\n// Use elementKeyFind so getAttribute('onTap') is typed — no cast needed\nconst el = elementKeyFind(componentGetElements(nodes[0].component!), 'my-element')[0];\nel?.getAttribute('onTap')?.();\nexpect(onTap).toHaveBeenCalled();\n```\n\n#### `onVisibilityChanged` callback\n\n`View.onVisibilityChanged` signature is `(isVisible: boolean, eventTime: EventTime)` where `EventTime = number`. Always pass both args when invoking:\n\n```tsx\nconst el = elementKeyFind(componentGetElements(nodes[0].component!), 'container')[0];\nel?.getAttribute('onVisibilityChanged')?.(true, 0);\n```\n\n**Asserting the callback:** depends on how the component wires the handler:\n\n- If the component **wraps** the viewModel callback (e.g., `onVisibilityChanged={(v) => vm.onVisibilityChanged(v)}`), `toHaveBeenCalledWith(true)` works:\n ```tsx\n expect(onVisibilityChanged).toHaveBeenCalledWith(true);\n ```\n\n- If the component **directly assigns** the viewModel callback (e.g., `onVisibilityChanged={this.viewModel.onVisibilityChanged}`), the spy receives both args. If the spy is typed as `(isVisible: boolean) => void`, `toHaveBeenCalledWith(true, ...)` is a TypeScript error. Check the first arg via `calls`:\n ```tsx\n const spy = viewModel.onVisibilityChanged as jasmine.Spy;\n expect(spy).toHaveBeenCalled();\n expect(spy.calls.mostRecent().args[0]).toBe(true);\n ```\n If the spy is an untyped `jasmine.createSpy()`, you can use `toHaveBeenCalledWith(true, 0)` directly.\n\n### 6. Discriminated union state testing\n\nWhen a view model contains a discriminated union (e.g., `type: 'LOADING' | 'CONTENT' | 'ERROR'`), **test every branch**. For each state:\n1. Assert which elements/components ARE rendered\n2. Assert which elements/components from OTHER states are NOT rendered\n\n```tsx\n// LOADING state: spinner present, action button absent\nvaldiIt('Verify spinner is shown in loading state', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(elementKeyFind(componentGetElements(nodes[0].component!), 'loading-spinner')[0]).toBeDefined();\n expect(elementKeyFind(componentGetElements(nodes[0].component!), 'action-button')[0]).toBeUndefined();\n});\n\n// CONTENT state: action button present, no spinner\nvaldiIt('Verify action button is shown in content state', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(elementKeyFind(componentGetElements(nodes[0].component!), 'action-button')[0]).toBeDefined();\n expect(elementKeyFind(componentGetElements(nodes[0].component!), 'loading-spinner')[0]).toBeUndefined();\n});\n```\n\n### 7. Array view model testing\n\nWhen a component renders a list from an array prop, test three cases:\n1. **Empty array** — assert 0 items render\n2. **Single item** — assert 1 item renders\n3. **Multiple items** — assert item count matches array length\n\nUse `componentTypeFind(component, ItemComponent)` or `elementKeyFind` with indexed keys (e.g., `tile-0`, `tile-1`) to count rendered items.\n\n```tsx\nvaldiIt('Verify no items render when array is empty', async driver => {\n const emptyOptions: OptionViewModel[] = [];\n const nodes = driver.render(() => {\n ;\n });\n const component = nodes[0].component as MyComponent;\n expect(componentTypeFind(component, ItemComponent).length).toBe(0);\n});\n\nvaldiIt('Verify item count matches array length', async driver => {\n const threeItems: OptionViewModel[] = [makeItem('a'), makeItem('b'), makeItem('c')];\n const nodes = driver.render(() => {\n ;\n });\n const component = nodes[0].component as MyComponent;\n expect(componentTypeFind(component, ItemComponent).length).toBe(3);\n});\n```\n\nNote: Extract array literals to local `const` variables before using in JSX (required by `@snapchat/valdi/jsx-no-lambda`).\n\n### 8. Component boundary traversal\n\nWhen a component's `onRender()` only renders child components (not native elements), `componentGetElements(component)` returns `[]`. You must get the child component first:\n\n```tsx\nimport { componentGetElements } from 'foundation/test/util/componentGetElements';\nimport { componentTypeFind } from 'foundation/test/util/componentTypeFind';\nimport { elementKeyFind } from 'foundation/test/util/elementKeyFind';\n\nconst component = nodes[0].component as OuterComponent;\nconst inner = componentTypeFind(component, InnerComponent)[0];\nconst container = elementKeyFind(componentGetElements(inner), 'container')[0];\nexpect(container?.getAttribute('translationY')).toBe(0);\n```\n\n### 9. Extract render and find helpers for readability\n\nFor larger test files, extract repeated render + find logic into helper functions. This keeps individual tests focused:\n\n```tsx\n// Extract rendering\nconst renderComponent = (driver: IComponentTestDriver, overrides?: Partial) => {\n const vm = { ...makeViewModel(), ...overrides };\n return driver.render(() => { ; })[0].component as MyComponent;\n};\n\n// Extract finding\nconst getImage = (component: MyComponent) =>\n elementKeyFind(componentGetElements(component), 'image')[0];\n\n// Tests become clean:\nvaldiIt('Verify imageUrl is bound', async driver => {\n expect(getImage(renderComponent(driver))?.getAttribute('src')).toBe('https://example.com/image.png');\n});\n```\n\n### 10. Lint rules to follow\n\n- **`explicit-function-return-type`**: Always add explicit return types to factory functions: `const makeViewModel = (): MyViewModel => ({...})`\n- **`jsx-no-lambda`**: Never assign inline array literals directly in JSX props. Extract to a local `const` first:\n ```tsx\n // WRONG\n ;\n\n // CORRECT\n const items: ItemViewModel[] = [makeItem('a')];\n ;\n ```\n- **`no-unsafe-call`**: Use the generic type parameter on `elementKeyFind` to get typed `getAttribute()` results rather than casting: `elementKeyFind(...)` gives typed access to `onTap`, `onVisibilityChanged`, etc.\n- **`import/order`**: Keep imports sorted alphabetically by path.\n\n### 11. Key principle\n\n**Only assert on things that change based on view model props.** Every test should have a clear \"when X is Y, then Z\" story. If the UI looks the same regardless of the prop, skip it.\n\nFor union types, a test that only verifies \"the component renders without error\" in a given state is not sufficient — assert the meaningful structural difference that state introduces.\n\n## Example test file structure\n\n```tsx\nimport { MyComponent } from 'my_module/src/MyComponent';\nimport { MyComponentViewModel } from 'my_module/src/MyComponentViewModel';\nimport { ChildComponent } from 'my_module/src/ChildComponent';\nimport { componentGetElements } from 'foundation/test/util/componentGetElements';\nimport { componentTypeFind } from 'foundation/test/util/componentTypeFind';\nimport { elementKeyFind } from 'foundation/test/util/elementKeyFind';\nimport { tapNodeWithKey } from 'foundation/test/util/tapNodeWithKey';\nimport 'jasmine/src/jasmine';\nimport { IComponentTestDriver, valdiIt } from 'valdi_test/test/JSXTestUtils';\nimport { ImageView, View } from 'valdi_tsx/src/NativeTemplateElements';\n// elementTypeFind + IRenderedElementViewClass for finding elements by type (no key needed):\n// import { elementTypeFind } from 'foundation/test/util/elementTypeFind';\n// import { IRenderedElementViewClass } from 'valdi_test/test/IRenderedElementViewClass';\n\nconst makeViewModel = (): MyComponentViewModel => ({\n imageUrl: 'https://example.com/image.png',\n isVisible: true,\n onTap: fail.bind(null, 'onTap should not be called'),\n});\n\ndescribe('MyComponentTest', () => {\n valdiIt('Verify visible when isVisible is true', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(elementKeyFind(componentGetElements(nodes[0].component!), 'container')[0]?.getAttribute('opacity')).toBe(1);\n });\n\n valdiIt('Verify hidden when isVisible is false', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(elementKeyFind(componentGetElements(nodes[0].component!), 'container')[0]?.getAttribute('opacity')).toBe(0);\n });\n\n valdiIt('Verify imageUrl is bound to image src', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(elementKeyFind(componentGetElements(nodes[0].component!), 'image')[0]?.getAttribute('src')).toBe('https://example.com/image.png');\n });\n\n valdiIt('Verify onTap is called when tapped', async driver => {\n const onTap = jasmine.createSpy('onTap');\n const nodes = driver.render(() => {\n ;\n });\n await tapNodeWithKey(nodes[0].component!, 'button');\n expect(onTap).toHaveBeenCalled();\n });\n\n valdiIt('Verify ChildComponent is present when condition is true', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n const component = nodes[0].component as MyComponent;\n expect(componentTypeFind(component, ChildComponent).length).toBe(1);\n });\n\n valdiIt('Verify ChildComponent is absent when condition is false', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n const component = nodes[0].component as MyComponent;\n expect(componentTypeFind(component, ChildComponent).length).toBe(0);\n });\n});\n```\n"
},
{
"path": "ai-skills/skills/valdi-component-tests/tests/BUILD.bazel",
"content": "load(\"//bzl/valdi:valdi_module.bzl\", \"valdi_module\")\n\nvaldi_module(\n name = \"tests\",\n srcs = glob([\n \"src/**/*.ts\",\n \"src/**/*.tsx\",\n \"test/**/*.ts\",\n \"test/**/*.tsx\",\n ]) + [\n \"tsconfig.json\",\n ],\n android_output_target = \"debug\",\n ios_module_name = \"SCCValdiCompTestRef\",\n ios_output_target = \"debug\",\n visibility = [\"//visibility:public\"],\n deps = [\n \"//src/valdi_modules/src/valdi/foundation\",\n \"//src/valdi_modules/src/valdi/jasmine\",\n \"//src/valdi_modules/src/valdi/valdi_core\",\n \"//src/valdi_modules/src/valdi/valdi_test\",\n \"//src/valdi_modules/src/valdi/valdi_tsx\",\n ],\n)\n"
},
{
"path": "ai-skills/skills/valdi-component-tests/tests/README.md",
"content": "# valdi-component-tests skill tests\n\nReference spec file demonstrating all test utility patterns from `skill.md`.\n\n## Files\n\n| File | Description |\n|------|-------------|\n| `src/ProfileCard.tsx` | Component under test — has an image, labels, conditional child, tap handler |\n| `test/ProfileCardTest.spec.tsx` | Spec file exercising all test utilities |\n\n## What's demonstrated\n\n`test/ProfileCardTest.spec.tsx` exercises:\n- `elementKeyFind` — typed `getAttribute('src')` on image element\n- `elementKeyFind` — untyped string attribute access\n- `elementKeyFind` — typed `getAttribute('onTap')` for direct invocation\n- `elementTypeFind` — find elements by type (`IRenderedElementViewClass.Label`)\n- `componentTypeFind` — conditional child component presence/absence\n- `tapNodeWithKey` — async tap triggering a spy callback\n- `fail.bind(null, '...')` — factory function default for callbacks that must not fire\n- `valdiIt` — test runner with driver\n\n## Run tests\n\n```bash\ncd client/src/open_source\nbazel test //ai-skills/skills/valdi-component-tests/tests:tests\n```\n\nExpected: all jasmine specs pass.\n\n## Updating\n\nWhen test utility APIs change, update `test/ProfileCardTest.spec.tsx` to match and keep it passing. Also update `../skill.md` with any corrected patterns.\n"
},
{
"path": "ai-skills/skills/valdi-component-tests/tests/src/ProfileCard.tsx",
"content": "// Simple component used by the component-tests skill reference spec.\n// Exercises: elementKeyFind, elementTypeFind, componentTypeFind, tapNodeWithKey.\n\nimport { Component } from 'valdi_core/src/Component';\n\n// ─── FollowBadge: child component (used for componentTypeFind) ────────────────\n\nexport interface FollowBadgeViewModel {\n label: string;\n}\n\nexport class FollowBadge extends Component {\n onRender(): void {\n ;\n }\n}\n\n// ─── ProfileCard ──────────────────────────────────────────────────────────────\n\nexport interface ProfileCardViewModel {\n avatarUrl: string;\n name: string;\n isFollowing: boolean;\n onFollowTap: () => void;\n}\n\nexport class ProfileCard extends Component {\n onRender(): void {\n \n ;\n ;\n {this.viewModel.isFollowing && }\n \n ;\n ;\n ;\n }\n}\n"
},
{
"path": "ai-skills/skills/valdi-component-tests/tests/test/ProfileCardTest.spec.tsx",
"content": "// valdi-component-tests skill reference — demonstrates all test utility patterns.\n// Run: bzl test //ai-skills/skills/valdi-component-tests/tests:tests\n\nimport { componentGetElements } from 'foundation/test/util/componentGetElements';\nimport { componentTypeFind } from 'foundation/test/util/componentTypeFind';\nimport { elementKeyFind } from 'foundation/test/util/elementKeyFind';\nimport { elementTypeFind } from 'foundation/test/util/elementTypeFind';\nimport { tapNodeWithKey } from 'foundation/test/util/tapNodeWithKey';\nimport 'jasmine/src/jasmine';\nimport { IRenderedElementViewClass } from 'valdi_test/test/IRenderedElementViewClass';\nimport { valdiIt } from 'valdi_test/test/JSXTestUtils';\nimport { ImageView, View } from 'valdi_tsx/src/NativeTemplateElements';\nimport { FollowBadge, ProfileCard, ProfileCardViewModel } from '../src/ProfileCard';\n\n// ─── Factory function with explicit return type ───────────────────────────────\n\nconst makeViewModel = (): ProfileCardViewModel => ({\n avatarUrl: 'https://example.com/avatar.png',\n name: 'Alice',\n isFollowing: false,\n onFollowTap: fail.bind(null, 'onFollowTap should not be called'),\n});\n\n// ─── Tests ───────────────────────────────────────────────────────────────────\n\ndescribe('ProfileCardTest', () => {\n\n // elementKeyFind: typed access to src attribute\n valdiIt('Verify avatar src is bound from viewModel', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(\n elementKeyFind(componentGetElements(nodes[0].component!), 'avatar')[0]\n ?.getAttribute('src'),\n ).toBe('https://example.com/avatar.png');\n });\n\n // elementKeyFind: untyped access to string attribute\n valdiIt('Verify name label is bound from viewModel', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(\n elementKeyFind(componentGetElements(nodes[0].component!), 'name-label')[0]\n ?.getAttribute('value'),\n ).toBe('Alice');\n });\n\n // elementTypeFind: find all Label elements without key attributes\n valdiIt('Verify label count when not following', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n const labels = elementTypeFind(\n componentGetElements(nodes[0].component!),\n IRenderedElementViewClass.Label,\n );\n // name-label + follow button label = 2 (FollowBadge not rendered)\n expect(labels.length).toBe(2);\n });\n\n // componentTypeFind: conditional child component absent\n valdiIt('Verify FollowBadge is absent when isFollowing is false', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(\n componentTypeFind(nodes[0].component as ProfileCard, FollowBadge).length,\n ).toBe(0);\n });\n\n // componentTypeFind: conditional child component present\n valdiIt('Verify FollowBadge is present when isFollowing is true', async driver => {\n const nodes = driver.render(() => {\n ;\n });\n expect(\n componentTypeFind(nodes[0].component as ProfileCard, FollowBadge).length,\n ).toBe(1);\n });\n\n // tapNodeWithKey: async tap triggers callback\n valdiIt('Verify onFollowTap fires when follow button is tapped', async driver => {\n const onFollowTap = jasmine.createSpy('onFollowTap');\n const nodes = driver.render(() => {\n ;\n });\n await tapNodeWithKey(nodes[0].component!, 'follow-button');\n expect(onFollowTap).toHaveBeenCalled();\n });\n\n // elementKeyFind: typed access to onTap via getAttribute\n valdiIt('Verify onTap is set on follow button', async driver => {\n const onFollowTap = jasmine.createSpy('onFollowTap');\n const nodes = driver.render(() => {\n ;\n });\n const button = elementKeyFind(\n componentGetElements(nodes[0].component!),\n 'follow-button',\n )[0];\n button?.getAttribute('onTap')?.();\n expect(onFollowTap).toHaveBeenCalled();\n });\n\n});\n"
},
{
"path": "ai-skills/skills/valdi-component-tests/tests/tsconfig.json",
"content": "{\"extends\": \"../../../../src/valdi_modules/src/valdi/_configs/base.tsconfig.json\"}\n"
},
{
"path": "ai-skills/skills/valdi-cpp-runtime/skill.md",
"content": "# C++ Runtime Rules\n\n**Applies to**: C++ files in `/valdi/`, `/valdi_core/`, `/snap_drawing/`\n\n## Overview\n\nValdi's runtime and layout engine are implemented in C++ for cross-platform performance. This code runs on iOS, Android, macOS, but not web.\n\n**Note**: `/libs/` contains shared utility libraries (crypto, logging, image processing) used across the codebase, but not the core runtime itself.\n\n## Code Style\n\n- **4-space indentation**\n- Follow existing C++ style in the codebase\n- Use smart pointers appropriately\n- Prefer const correctness\n\n## Key Concepts\n\n### Layout Engine\n\n- Uses **Yoga** (Facebook's Flexbox implementation) for layout\n- Cross-platform layout calculations\n- Performance-critical code\n- RTL (right-to-left) support built-in\n- Yoga source: `/third-party/yoga/`\n\n### Memory Management\n\n- Be careful with memory ownership\n- Use RAII patterns\n- Consider platform-specific memory constraints (mobile)\n\n### Platform Abstractions\n\n- Code must work on iOS, Android, macOS\n- Use platform-agnostic APIs where possible\n- Platform-specific code goes in appropriate subdirectories\n\n## Common Patterns\n\n### Djinni Generated Code\n\n- Some C++ code is generated from `.djinni` interface files\n- **Don't modify generated code** - change the .djinni file instead\n- Generated files typically in `generated-src/` directories\n\n### Performance\n\n- This is performance-critical code\n- Profile before optimizing\n- Consider cache locality\n- Be mindful of allocations in hot paths\n\n## Testing\n\n```bash\n# Run all C++ runtime tests\nbazel test //valdi:test\n\n# Run specific test suites\nbazel test //valdi:test_runtime # Runtime tests\nbazel test //valdi:test_integration # Integration tests\nbazel test //valdi:test_snap_drawing # Snap drawing tests\n```\n\n## Platform-Specific Notes\n\n### iOS\n- Objective-C++ bridge in `/valdi/src/valdi/ios/`\n- Metal for GPU rendering\n- UIKit view integration\n\n### Android\n- JNI bridge in `/valdi/src/valdi/android/`\n- NDK integration\n- Native view rendering\n\n### macOS\n- Platform-specific code in `/valdi/src/valdi/macos/`\n- Desktop runtime support\n\n### Build\n\n```bash\n# Build runtime for specific platform\nbazel build //valdi:valdi_ios\nbazel build //valdi:valdi_android\nbazel build //valdi:valdi_macos\n```\n\n## Important\n\n1. **Cross-platform first** - Code must work on all platforms\n2. **Performance critical** - UI rendering and layout\n3. **Memory efficiency** - Mobile devices have constraints\n4. **Thread safety** - Consider concurrency\n\n## More Information\n\n- Runtime overview: `/valdi/README.md`\n- Core bindings: `/valdi_core/README.md`\n- Framework docs: `/AGENTS.md`\n"
},
{
"path": "ai-skills/skills/valdi-custom-view/skill.md",
"content": "# Custom View Rules\n\n**Applies to**: `**/*.tsx` files using `` elements.\n\n## `` Element\n\n`` renders a platform-native view inside a Valdi component. Each platform resolves the view by class name.\n\n```typescript\n\n```\n\n## Class Attributes\n\n| Attribute | Platform | Resolution |\n|-----------|----------|------------|\n| `androidClass` | Android | Reflection via `ReflectionViewFactory`; needs `@RegisterAttributesBinder` |\n| `iosClass` | iOS | ObjC class name; must be linked via `ios_deps` |\n| `macosClass` | macOS | `NSClassFromString()`; must be linked via `macos_deps` |\n| `webClass` | Web | Looked up in `WebViewClassRegistry`; registered via `webPolyglotViews` export |\n\n## Platform Discovery\n\n- **Android**: The view class needs a single-arg `(Context)` constructor. An `@RegisterAttributesBinder`-annotated binder is discovered from assets at runtime.\n- **iOS**: The ObjC class must be an `NSView`/`UIView` subclass linked into the binary.\n- **macOS**: Same as iOS but with `NSView` subclass.\n- **Web**: The `webClass` name is matched against the `WebViewClassRegistry`. Register by exporting `webPolyglotViews` from a web polyglot entry file (see `web-polyglot.md` rule).\n\n## viewFactory Pattern\n\nInstead of resolving by class name, you can pass a `ViewFactory` object directly. This is useful when the factory is provided by a parent component or constructed dynamically:\n\n```typescript\nimport { ViewFactory } from 'valdi_tsx/src/ViewFactory';\n\ninterface MyViewModel {\n viewFactory?: ViewFactory;\n}\n\nclass MyComponent extends Component {\n onRender(): void {\n if (this.viewModel.viewFactory) {\n ;\n }\n }\n}\n```\n\n`viewFactory` and `*Class` attributes are mutually exclusive — use one or the other. `viewFactory` takes precedence when both are provided.\n\n## Common Mistakes\n\n- Using `` without checking the platform — wrap in `Device.isAndroid()` / `Device.isIOS()` etc. if not all platforms are supported\n- Forgetting to link native implementations — the class name string alone isn't enough; the native code must be compiled and linked via platform `_deps` in BUILD.bazel\n- Wrong package name in `androidClass` — must match the Kotlin/Java package exactly\n"
},
{
"path": "ai-skills/skills/valdi-ios/skill.md",
"content": "# iOS Runtime Rules\n\n**Applies to**: Objective-C/C++ files in `/valdi/src/valdi/ios/` and related iOS runtime code\n\n## Overview\n\nThe Valdi iOS runtime bridges TypeScript/Valdi components to native UIKit views. It's implemented in Objective-C, Objective-C++, and Swift.\n\n## Code Style\n\n- **4-space indentation** for Objective-C\n- Follow Apple's Objective-C conventions\n- Use modern Objective-C features (properties, blocks, etc.)\n\n## Key Concepts\n\n### View Rendering\n\n- Valdi components map to UIViews\n- View recycling for performance\n- UIKit integration\n\n### Platform Bridge\n\n- Objective-C++ bridge to C++ runtime\n- Memory management (ARC)\n- iOS-specific APIs\n\n## Common Patterns\n\n### Bazel iOS Targets\n\n```python\nobjc_library(\n name = \"valdi_ios\",\n srcs = glob([\"**/*.m\", \"**/*.mm\"]),\n hdrs = glob([\"**/*.h\"]),\n)\n```\n\n### View Implementation\n\n- Custom UIView subclasses\n- CALayer for advanced rendering\n- Metal for GPU acceleration\n\n## Testing\n\n```bash\n# Run iOS runtime tests (Objective-C)\nbazel test //valdi:valdi_ios_objc_test\n\n# Run iOS runtime tests (Swift)\nbazel test //valdi:valdi_ios_swift_test\n\n# Run all iOS tests\nbazel test //valdi:valdi_ios_objc_test //valdi:valdi_ios_swift_test\n```\n\nTest files are in `/valdi/test/ios/` and `/valdi/test/ios_swift/`\n\n## Building\n\n```bash\n# Build iOS runtime library\nbazel build //valdi:valdi_ios\n\n# Test with hello world app\ncd apps/helloworld\nvaldi install ios\n```\n\n## Platform-Specific Notes\n\n1. **iOS Version** - Be mindful of minimum iOS version\n2. **ARC** - Automatic Reference Counting (memory management)\n3. **Auto Layout** - Valdi uses flexbox, not Auto Layout\n4. **Metal** - GPU rendering for advanced graphics\n\n## Important\n\n- **Performance** - UIView creation and layout are critical\n- **Memory** - Understand retain cycles and weak references\n- **Threading** - Main thread for UI, background for heavy work\n- **Lifecycle** - UIViewController lifecycle\n\n## More Information\n\n- Runtime source: `/valdi/src/valdi/ios/`\n- Runtime tests: `/valdi/test/ios/` and `/valdi/test/ios_swift/`\n- Core iOS code: `/valdi_core/src/valdi_core/ios/`\n- Build config: `/valdi/BUILD.bazel`\n- Framework docs: `/AGENTS.md`\n"
},
{
"path": "ai-skills/skills/valdi-migrate/skill.md",
"content": "# Valdi Migration Assistant\n\nGuidance for migrating code from Flutter, React, or Jetpack Compose to Valdi.\n\n## When to use\n\nUse this skill when converting Flutter widgets, React components, or Compose `@Composable` functions to Valdi components, or when translating framework-specific patterns (hooks, widgets, Navigator, setState, remember, LaunchedEffect, Modifier, Provider, styled-components, FlatList, LazyColumn, etc.) to Valdi equivalents.\n\n## Critical: Never suggest these patterns\n\n```typescript\n// ❌ React hooks — DO NOT EXIST in Valdi\nuseState / useEffect / useContext / useMemo / useCallback / useRef\n\n// ❌ Compose APIs — DO NOT EXIST in Valdi\n@Composable annotation\nremember { mutableStateOf() } / remember { }\nderivedStateOf / collectAsState / LaunchedEffect / DisposableEffect\nModifier chain (Modifier.padding().background().clickable())\nCompositionLocalProvider / LocalXxx.current\n\n// ❌ Functional components — DO NOT EXIST\nconst MyComp = () => ;\nfunction MyComp(props) { return ; }\n\n// ❌ Wrong naming\nthis.props // → this.viewModel\nonMount/onUnmount // → onCreate/onDestroy\nmarkNeedsRender() // → this.setState({})\nscheduleRender() // → deprecated, use setState\n\n// ❌ Returning JSX — onRender() returns void\nonRender() { return ; } // no return statement\n\n// ❌ Inline lambdas in JSX props — causes re-renders\n this.doThing()} /> // use class arrow fn\n\n// ❌ map() in render — does not work (JSX is side-effect, not return value)\n{items.map(i => )} // use forEach\n\n// ❌ JSX as a prop value\n} /> // use render prop () => void\n\n// ❌ new Style() inside onRender() — style interning requires module-level init\nonRender() { const s = new Style({...}); ... } // wrong\n```\n\n## Correct patterns\n\n```typescript\nimport { Component, StatefulComponent } from 'valdi_core/src/Component';\n\n// ✅ Stateless component\nclass MyComp extends Component {\n onRender() {\n \n ;\n ;\n }\n}\n\n// ✅ Stateful component\nclass Counter extends StatefulComponent {\n state = { count: 0 };\n\n // Class arrow function — never inline lambda in JSX\n private handleTap = () => {\n this.setState({ count: this.state.count + 1 });\n };\n\n onRender() {\n \n ;\n ;\n }\n}\n\n// ✅ Lists — forEach, not map()\nonRender() {\n \n {this.viewModel.items.forEach(item => {\n ;\n })}\n ;\n}\n\n// ✅ Style — created at module level, not inside onRender()\nconst cardStyle = new Style({ backgroundColor: '#fff', borderRadius: 8 });\n```\n\n## Lifecycle mapping\n\n| Flutter | Jetpack Compose | React | Valdi |\n|---------|-----------------|-------|-------|\n| `initState()` | `LaunchedEffect(Unit) { }` | `componentDidMount` / `useEffect(fn, [])` | `onCreate()` |\n| `dispose()` | `DisposableEffect { onDispose { } }` | `componentWillUnmount` / `useEffect(() => fn, [])` | `onDestroy()` |\n| `didUpdateWidget(old)` | `LaunchedEffect(key) { }` | `componentDidUpdate(prev)` / `useEffect(fn, [dep])` | `onViewModelUpdate(previous?)` |\n| `build(context)` | `@Composable fun` recomposition | `render(): JSX.Element` | `onRender(): void` |\n| `setState(() {...})` | `mutableStateOf` + state write | `this.setState({...})` | `this.setState({...})` |\n\n## Component and element mapping\n\n| Flutter | Jetpack Compose | React | Valdi |\n|---------|-----------------|-------|-------|\n| `StatelessWidget` | `@Composable fun` (stateless) | Function component | `class X extends Component` |\n| `StatefulWidget` + `State` | `@Composable fun` + `remember { mutableStateOf() }` | Class component + state | `class X extends StatefulComponent` |\n| `Container` / `SizedBox` (visual) | `Box` / `Surface` | `
![\"Hello](\"./docs/docs/assets/start-about/IMG_1445.jpg\")
\n