Composition and Lifecycle

/**
 * Marks a function as composable, allowing it to call other composable functions
 * and participate in recomposition
 */
@Target(AnnotationTarget.FUNCTION, AnnotationTarget.TYPE)
@Retention(AnnotationRetention.BINARY)
annotation class Composable

@Composable
fun MyButton(
    text: String,
    onClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    Button(onClick = onClick, modifier = modifier) {
        Text(text)
    }
}

@Composable
fun UserProfile(user: User) {
    Column {
        Text("Name: ${user.name}")
        Text("Email: ${user.email}")
        MyButton("Edit Profile", onClick = { /* edit logic */ })
    }
}

/**
 * Remembers a value across recompositions with no keys
 * @param calculation Function to compute the initial value
 * @return The remembered value
 */
inline fun <T> remember(crossinline calculation: () -> T): T

/**
 * Remembers a value with one key dependency
 * @param key1 Key that determines when to recalculate
 * @param calculation Function to compute the value
 * @return The remembered value, recalculated when key changes
 */
inline fun <T> remember(
    key1: Any?,
    crossinline calculation: () -> T
): T

/**
 * Remembers a value with two key dependencies
 * @param key1 First key dependency
 * @param key2 Second key dependency
 * @param calculation Function to compute the value
 * @return The remembered value, recalculated when any key changes
 */
inline fun <T> remember(
    key1: Any?,
    key2: Any?,
    crossinline calculation: () -> T
): T

/**
 * Remembers a value with three key dependencies
 * @param key1 First key dependency
 * @param key2 Second key dependency
 * @param key3 Third key dependency
 * @param calculation Function to compute the value
 * @return The remembered value, recalculated when any key changes
 */
inline fun <T> remember(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    crossinline calculation: () -> T
): T

/**
 * Remembers a value with multiple key dependencies
 * @param keys Variable number of key dependencies
 * @param calculation Function to compute the value
 * @return The remembered value, recalculated when any key changes
 */
inline fun <T> remember(
    vararg keys: Any?,
    crossinline calculation: () -> T
): T

@Composable
fun ExpensiveComputationExample(data: List<Int>) {
    // Remember expensive computation result
    val processedData = remember(data) {
        data.map { it * it }.sorted() // Only recalculates when data changes
    }
    
    // Remember object creation
    val textStyle = remember {
        TextStyle(fontSize = 16.sp, fontWeight = FontWeight.Bold)
    }
    
    // Remember with multiple keys
    val filteredItems = remember(data, filter, sortOrder) {
        data.filter(filter).sortedWith(sortOrder)
    }
    
    LazyColumn {
        items(processedData) { item ->
            Text("$item", style = textStyle)
        }
    }
}

/**
 * Returns the current recompose scope, which can be used to invalidate the current composition
 * @return Current RecomposeScope or null if not in composition
 */
val currentRecomposeScope: RecomposeScope?

/**
 * Interface for controlling recomposition of a specific scope
 */
interface RecomposeScope {
    /**
     * Invalidates this scope, causing it to be recomposed on the next recomposition
     */
    fun invalidate()
}

/**
 * Invalidates the current recompose scope, causing recomposition
 */
fun invalidate(): Unit

@Composable
fun ManualRecompositionExample() {
    val scope = currentRecomposeScope
    
    Button(onClick = {
        // Manually trigger recomposition
        scope?.invalidate()
    }) {
        Text("Force Recompose")
    }
}

/**
 * Context for composition operations, providing access to composition-wide state
 */
abstract class CompositionContext {
    /** Unique identifier for this composition context */
    abstract val id: Int
    
    /** Parent composition context, if any */
    abstract val parent: CompositionContext?
}

/**
 * Represents a composition tree and its lifecycle
 */
interface Composition {
    /** Applies changes to the composition */
    fun applyChanges()
    
    /** Disposes the composition and releases resources */
    fun dispose()
    
    /** Whether this composition has pending changes */
    val hasInvalidations: Boolean
}

/**
 * A Composition that provides additional control over composition execution
 */
interface ControlledComposition : Composition {
    /** Composes the composition with the given content */
    fun compose(content: @Composable () -> Unit)
    
    /** Forces recomposition of invalidated content */
    fun recompose(): Boolean
    
    /** Number of pending invalidations */
    val invalidationCount: Int
}

/**
 * Creates a new Composition
 * @param applier The applier that will receive composition changes  
 * @param parent Parent CompositionContext for hierarchical compositions
 * @return New Composition instance
 */
fun Composition(
    applier: Applier<*>,
    parent: CompositionContext? = null
): ControlledComposition

/**
 * Creates a new Composition with additional configuration
 * @param applier The applier that will receive composition changes
 * @param parent Parent CompositionContext for hierarchical compositions
 * @param onDispose Callback invoked when composition is disposed
 * @return New Composition instance
 */
fun Composition(
    applier: Applier<*>,
    parent: CompositionContext? = null,
    onDispose: (() -> Unit)? = null
): ControlledComposition

/**
 * Applies composition changes to a tree of nodes
 * @param Node The type of nodes in the tree
 */
interface Applier<Node> {
    /** The current node being modified */
    val current: Node
    
    /** Insert nodes at the specified index in the current node */
    fun insertTopDown(index: Int, instance: Node)
    
    /** Insert nodes from bottom up */
    fun insertBottomUp(index: Int, instance: Node)
    
    /** Remove nodes starting at index */
    fun remove(index: Int, count: Int)
    
    /** Move nodes from one position to another */
    fun move(from: Int, to: Int, count: Int)
    
    /** Clear all child nodes */
    fun clear()
    
    /** Move down to a child node */
    fun down(node: Node)
    
    /** Move up to the parent node */
    fun up()
}

/**
 * Information about recomposition for debugging and optimization
 */
interface RecompositionInfo {
    /** Number of times this scope has recomposed */
    val recomposeCount: Int
    
    /** Number of times this scope has been skipped */
    val skipCount: Int
}

/**
 * Gets recomposition information for the current scope
 * @return RecompositionInfo for debugging
 */
@Composable
fun currentRecompositionInfo(): RecompositionInfo

/**
 * Provides debugging information about the current composition
 */
object CompositionTracing {
    /** Whether composition tracing is enabled */
    var isEnabled: Boolean
    
    /** Begin tracing a composition section */
    fun beginSection(name: String)
    
    /** End the current composition section */
    fun endSection()
}

/**
 * Creates a UIViewController that hosts Compose content
 * @param content The composable content to display
 * @return UIViewController containing the Compose UI
 */
fun ComposeUIViewController(content: @Composable () -> Unit): UIViewController

/**
 * Platform-specific composition context for iOS
 */
class IOSCompositionContext : CompositionContext {
    /** The UIView hosting the composition */
    val hostView: UIView
    
    /** Main thread dispatcher for iOS */
    val mainDispatcher: CoroutineDispatcher
}