feat: add navigate-for-result API for type-safe result handling

.gitignore

@@ -15,3 +15,4 @@ build
 .cxx
 local.properties
 .kotlin
+**/bin/

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.serena/memories/architecture_patterns.md

@@ -0,0 +1,73 @@
+# Nibel Architecture & Design Patterns
+
+## Core Architecture Patterns
+
+### Navigation Controller Pattern
+
+- **NavigationController**: Central navigation component injected into Composables
+- **Entry Classes**: Generated navigation entry points (e.g., `MyScreenEntry`)
+- **Type-safe**: Compile-time checking for navigation arguments and types
+
+### Annotation-Driven Code Generation
+
+- **@UiEntry**: Internal screen entries (single module)
+- **@UiExternalEntry**: External entries (multi-module)
+- **@LegacyEntry/@LegacyExternalEntry**: Fragment integration
+- **KSP Processor**: Generates entry classes and navigation boilerplate
+
+### Multi-Module Navigation Pattern
+
+```
+ featureA          featureB
+  module            module
+    │                  │
+    └──► navigation ◄──┘
+           module
+```
+
+- **Destinations**: Type-safe navigation intents in shared navigation module
+- **DestinationWithNoArgs**: Simple object destinations
+- **DestinationWithArgs<T>**: Parameterized destinations
+
+### Result-Based Navigation Pattern
+
+- **Activity Result API**: Integration for type-safe result handling
+- **ResultEntry<T>**: Generated interfaces for result-returning screens
+- **Callbacks**: Strongly typed result callbacks with null handling for cancellation
+
+## State Management Pattern (Sample App)
+
+```kotlin
+@HiltViewModel
+class MyViewModel @Inject constructor() : ViewModel() {
+    private val _state = MutableStateFlow(MyState())
+    val state: StateFlow<MyState> = _state.asStateFlow()
+
+    private val _sideEffects = Channel<MySideEffect>()
+    val sideEffects: Flow<MySideEffect> = _sideEffects.receiveAsFlow()
+}
+```
+
+## Implementation Types Strategy
+
+- **ImplementationType.Composable**: Preferred for performance (avoids fragment overhead)
+- **ImplementationType.Fragment**: Required when navigating FROM existing fragments
+- **Gradual Migration**: Start with fragments, migrate to Composable over time
+
+## Code Generation Patterns
+
+- **Entry Factories**: Generated companion objects with `newInstance()` methods
+- **Type Safety**: Compile-time verification of argument types between annotations and function parameters
+- **Destination Resolution**: Cached multi-module destination lookup after first access
+
+## Testing Patterns
+
+- **Compilation Tests**: Verify generated code has correct interfaces and methods
+- **Integration Tests**: Test actual navigation flows end-to-end
+- **Type Validation**: Ensure argument type matching between annotations and function parameters
+
+## Performance Considerations
+
+- Use `ImplementationType.Composable` when possible
+- Generated entry classes optimized for minimal runtime cost
+- Multi-module destination resolution cached after first lookup

.serena/memories/code_style_conventions.md

@@ -0,0 +1,55 @@
+# Nibel Code Style & Conventions
+
+## Kotlin Style Guidelines
+
+- **Official Kotlin code style** configured in `gradle.properties` (`kotlin.code.style=official`)
+- **4-space indentation** for all code
+- **PascalCase** for classes and Composable functions
+- **camelCase** for functions and variables
+- **UPPER_SNAKE_CASE** for constants
+- **Comprehensive KDoc** required for all public APIs
+
+## Android-Specific Conventions
+
+- **Composable functions**: PascalCase (e.g., `FirstScreen`, `PhotoPickerScreen`)
+- **State management**: Use `collectAsStateWithLifecycle()` for observing state
+- **Hilt integration**: `@HiltViewModel` and `hiltViewModel()` for dependency injection
+
+## Package Structure
+
+- `nibel.runtime` - Core runtime components
+- `com.turo.nibel.sample.featureX` - Sample feature modules
+- Feature-based module organization
+- Clear separation of concerns (screens, ViewModels, navigation)
+
+## Annotation Patterns
+
+```kotlin
+// Internal entry (single module)
+@UiEntry(type = ImplementationType.Fragment)
+@Composable
+fun MyScreen() { ... }
+
+// External entry (multi-module)
+@UiExternalEntry(
+    type = ImplementationType.Composable,
+    destination = MyScreenDestination::class
+)
+@Composable
+fun MyScreen(args: MyScreenArgs) { ... }
+```
+
+## Naming Conventions
+
+- **Entry classes**: `{ComposableName}Entry` (auto-generated)
+- **Destination classes**: `{Screen}Destination`
+- **Args classes**: `{Screen}Args`
+- **Result classes**: `{Screen}Result`
+- **ViewModels**: `{Screen}ViewModel` (in sample app)
+
+## File Organization
+
+- Keep related functionality together in feature modules
+- Prefer editing existing files over creating new ones
+- Use symbolic tools for precise code modifications
+- Follow existing patterns when adding new code

.serena/memories/project_overview.md

@@ -0,0 +1,30 @@
+# Nibel Project Overview
+
+## Purpose
+
+Nibel is a type-safe navigation library for seamless integration of Jetpack Compose in fragment-based Android apps. It enables gradual migration from Fragment-based Android apps to Jetpack Compose while maintaining compatibility with existing codebases.
+
+## Key Features
+
+- **Type-safe navigation** with compile-time checking between fragments and Compose screens
+- **Multi-directional navigation**: fragment→compose, compose→compose, compose→fragment
+- **Single-module and multi-module** navigation support
+- **Result-based navigation** with Activity Result API pattern
+- **Annotation processing** for code generation via KSP (Kotlin Symbol Processing)
+- **Seamless integration** with existing fragment-based codebases
+
+## Navigation Scenarios Supported
+
+- fragment → compose (existing fragments to new Compose screens)
+- compose → compose (between Compose screens)
+- compose → fragment (Compose screens back to legacy fragments)
+
+## Main Components
+
+- **nibel-runtime**: Core runtime library with NavigationController
+- **nibel-compiler**: KSP processor for generating entry classes
+- **nibel-annotations**: Annotations (@UiEntry, @UiExternalEntry, etc.)
+- **nibel-stub**: Stub classes for compilation
+- **sample**: Multi-module sample application demonstrating usage patterns
+- **tests**: Integration and compilation tests
+- **build-tools**: Gradle convention plugins for consistent builds

.serena/memories/project_structure.md

@@ -0,0 +1,92 @@
+# Nibel Project Structure
+
+## Root Directory Structure
+
+```
+nibel/
+├── nibel-annotations/     # Annotations for code generation
+├── nibel-compiler/        # KSP processor for generating entry classes
+├── nibel-runtime/         # Core runtime library with NavigationController
+├── nibel-stub/           # Stub classes for compilation
+├── tests/                # Integration and compilation tests
+├── sample/               # Multi-module sample application
+├── build-tools/          # Gradle convention plugins
+├── config/               # Configuration files
+├── docs/                 # Documentation
+└── .github/              # GitHub workflows and templates
+```
+
+## Core Modules
+
+### nibel-annotations/
+
+- Contains `@UiEntry`, `@UiExternalEntry`, `@LegacyEntry` annotations
+- Defines annotation parameters and validation rules
+- Minimal dependencies, used at compile-time only
+
+### nibel-compiler/
+
+- KSP (Kotlin Symbol Processing) implementation
+- Generates entry classes, destination factories, result handlers
+- Validates annotation usage and argument type matching
+- Produces type-safe navigation boilerplate code
+
+### nibel-runtime/
+
+- Core `NavigationController` implementation
+- Entry interfaces (`ComposableEntry`, `FragmentEntry`, `ResultEntry`)
+- Destination resolution and factory management
+- Result-based navigation infrastructure
+
+### nibel-stub/
+
+- Stub implementations for generated classes during compilation
+- Ensures clean compilation before code generation completes
+
+## Sample Application Structure
+
+```
+sample/
+├── app/             # Main application module
+├── navigation/      # Shared navigation destinations
+├── feature-A/       # Independent feature module
+├── feature-B/       # Independent feature module
+├── feature-C/       # Independent feature module
+└── common/         # Shared utilities and components
+```
+
+### Multi-Module Dependencies
+
+- Features depend on `navigation/` for shared destinations
+- Features do NOT depend on each other directly
+- `app/` module depends on all features for final assembly
+
+## Testing Structure
+
+```
+tests/src/test/kotlin/nibel/tests/
+├── codegen/                    # Code generation tests
+│   ├── InternalEntryCompileTest.kt
+│   ├── ExternalEntryCompileTest.kt
+│   ├── ResultEntryCompileTest.kt
+│   └── TestArgs.kt
+└── ExternalDestinationSearchTest.kt
+```
+
+## Build Tools Structure
+
+```
+build-tools/conventions/
+├── src/main/kotlin/
+│   ├── NibelAndroidCommonPlugin.kt
+│   ├── NibelKotlinJvmLibraryPlugin.kt
+│   └── SampleAndroidApplicationPlugin.kt
+└── build.gradle.kts
+```
+
+## Configuration Files
+
+- `.pre-commit-config.yaml`: Pre-commit hooks configuration
+- `gradle.properties`: Gradle and Kotlin configuration
+- `settings.gradle.kts`: Project module configuration
+- `CLAUDE.md`: Development guidelines and instructions

.serena/memories/suggested_commands.md

@@ -0,0 +1,92 @@
+# Nibel Essential Commands
+
+## Development Workflow Commands
+
+```bash
+# After making changes - run all verification (MOST IMPORTANT)
+./gradlew check
+
+# Full build verification (used in CI)
+./gradlew build
+
+# Clean build to avoid stale artifacts
+./gradlew clean build
+```
+
+## Testing Commands
+
+```bash
+# Run all unit tests
+./gradlew test
+
+# Run specific test variants
+./gradlew testDebugUnitTest
+./gradlew testReleaseUnitTest
+
+# Run instrumentation tests (requires device)
+./gradlew connectedAndroidTest
+```
+
+## Linting & Formatting Commands
+
+```bash
+# Fix lint issues automatically (IMPORTANT)
+./gradlew lintFix
+
+# Run Kotlin static analysis
+./gradlew detekt
+
+# Run all Android lint checks
+./gradlew lint
+```
+
+## Module-Specific Commands
+
+```bash
+# Build specific modules
+./gradlew :nibel-runtime:build
+./gradlew :nibel-compiler:build
+./gradlew :sample:app:build
+
+# Test changes locally (for library development)
+./gradlew publishToMavenLocal --no-configuration-cache
+```
+
+## Pre-commit & Git Commands
+
+```bash
+# Run pre-commit hooks manually
+pre-commit run --all-files
+
+# Standard git commands (macOS/Darwin system)
+git status
+git add .
+git commit -m "feat: description"
+git push
+```
+
+## Documentation Commands
+
+```bash
+# Generate documentation
+./gradlew dokkaHtml
+./gradlew dokkaGfm
+```
+
+## System Utilities (macOS/Darwin)
+
+```bash
+# File operations
+ls -la          # List files with details
+find . -name "*.kt"  # Find Kotlin files
+grep -r "pattern" .  # Search in files
+cd directory    # Change directory
+
+# Development utilities
+./gradlew tasks  # List all available Gradle tasks
+./gradlew help   # Gradle help
+```
+
+## Critical Workflow
+
+**ALWAYS run `./gradlew check` before considering any task complete!**