iOS Runtime Rules

Applies to: Objective-C/C++ files in /valdi/src/valdi/ios/ and related iOS runtime code

Overview

The Valdi iOS runtime bridges TypeScript/Valdi components to native UIKit views. It's implemented in Objective-C, Objective-C++, and Swift.

Code Style

• 4-space indentation for Objective-C
• Follow Apple's Objective-C conventions
• Use modern Objective-C features (properties, blocks, etc.)

Key Concepts

View Rendering

• Valdi components map to UIViews
• View recycling for performance
• UIKit integration

Platform Bridge

• Objective-C++ bridge to C++ runtime
• Memory management (ARC)
• iOS-specific APIs

Common Patterns

Bazel iOS Targets

objc_library(
    name = "valdi_ios",
    srcs = glob(["**/*.m", "**/*.mm"]),
    hdrs = glob(["**/*.h"]),
)

View Implementation

• Custom UIView subclasses
• CALayer for advanced rendering
• Metal for GPU acceleration

Testing

# Run iOS runtime tests (Objective-C)
bazel test //valdi:valdi_ios_objc_test

# Run iOS runtime tests (Swift)
bazel test //valdi:valdi_ios_swift_test

# Run all iOS tests
bazel test //valdi:valdi_ios_objc_test //valdi:valdi_ios_swift_test

Test files are in /valdi/test/ios/ and /valdi/test/ios_swift/

Building

# Build iOS runtime library
bazel build //valdi:valdi_ios

# Test with hello world app
cd apps/helloworld
valdi install ios

Platform-Specific Notes

1. iOS Version - Be mindful of minimum iOS version
2. ARC - Automatic Reference Counting (memory management)
3. Auto Layout - Valdi uses flexbox, not Auto Layout
4. Metal - GPU rendering for advanced graphics

Important

• Performance - UIView creation and layout are critical
• Memory - Understand retain cycles and weak references
• Threading - Main thread for UI, background for heavy work
• Lifecycle - UIViewController lifecycle

More Information

• Runtime source: /valdi/src/valdi/ios/
• Runtime tests: /valdi/test/ios/ and /valdi/test/ios_swift/
• Core iOS code: /valdi_core/src/valdi_core/ios/
• Build config: /valdi/BUILD.bazel
• Framework docs: /AGENTS.md