pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native/android/src/main/java/com/pythonnative/runtime/bridge/PNRegistry.kt

@@ -0,0 +1,82 @@
+package com.pythonnative.runtime.bridge
+
+import android.util.Log
+import com.pythonnative.runtime.components.BuiltinComponents
+import com.pythonnative.runtime.components.ComponentManager
+import com.pythonnative.runtime.modules.BuiltinModules
+import com.pythonnative.runtime.modules.NativeModule
+import com.pythonnative.runtime.plugins.GeneratedPlugins
+
+/**
+ * A native extension: registers component managers and native modules.
+ *
+ * `pn build` generates a call to each plugin entry's `register` in
+ * `plugins/GeneratedPlugins.kt`.
+ */
+interface PNPlugin {
+    fun register(registry: PNRegistry)
+}
+
+/**
+ * Registry of component managers (by element type) and native modules
+ * (by module name). Built-ins are registered on first use, followed by
+ * the generated plugin registrations.
+ */
+object PNRegistry {
+    private val componentFactories = HashMap<String, () -> ComponentManager>()
+    private val managers = HashMap<String, ComponentManager>()
+    private val moduleFactories = HashMap<String, () -> NativeModule>()
+    private val modules = HashMap<String, NativeModule>()
+    private var builtinsRegistered = false
+
+    /** Register (or override) the manager factory for element type `name`. */
+    fun registerComponent(name: String, factory: () -> ComponentManager) {
+        componentFactories[name] = factory
+        managers.remove(name)
+    }
+
+    /**
+     * Register a native module. The factory is invoked once to read the
+     * module's `name`; the same instance then serves every call.
+     */
+    fun registerModule(factory: () -> NativeModule) {
+        val module = factory()
+        moduleFactories[module.name] = factory
+        modules[module.name] = module
+    }
+
+    /** The manager for element type `name`, or `null` when unknown. */
+    fun managerFor(name: String): ComponentManager? {
+        ensureBuiltins()
+        managers[name]?.let { return it }
+        val factory = componentFactories[name] ?: return null
+        val manager = factory()
+        managers[name] = manager
+        return manager
+    }
+
+    /** The module named `name`, or `null`. */
+    fun module(name: String): NativeModule? {
+        ensureBuiltins()
+        return modules[name]
+    }
+
+    /** Registered element type names. */
+    fun componentNames(): Set<String> {
+        ensureBuiltins()
+        return componentFactories.keys
+    }
+
+    /** Register built-in components and modules plus generated plugins (idempotent). */
+    fun ensureBuiltins() {
+        if (builtinsRegistered) return
+        builtinsRegistered = true
+        BuiltinComponents.register(this)
+        BuiltinModules.register(this)
+        try {
+            GeneratedPlugins.registerAll(this)
+        } catch (e: Exception) {
+            Log.e(PNLog.TAG, "plugin registration failed", e)
+        }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/bridge/PNTransaction.kt

@@ -0,0 +1,80 @@
+package com.pythonnative.runtime.bridge
+
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+/** One decoded mutation op. Geometry is in dp (points). */
+sealed class Op {
+    /** `["c", tag, "Type", {props}]` */
+    data class Create(val tag: Long, val typeName: String, val props: JSONObject) : Op()
+
+    /** `["u", tag, {changed}]` (a `null` value means the prop was removed) */
+    data class Update(val tag: Long, val changed: JSONObject) : Op()
+
+    /** `["i", parent, child, index]` (move-aware) */
+    data class Insert(val parent: Long, val child: Long, val index: Int) : Op()
+
+    /** `["d", tag]` */
+    data class Destroy(val tag: Long) : Op()
+
+    /** `["f", tag, x, y, w, h]` relative to the parent's content origin */
+    data class Frame(val tag: Long, val x: Double, val y: Double, val width: Double, val height: Double) : Op()
+}
+
+/**
+ * Decoder for the transaction wire format: a JSON array of ops, each an
+ * array whose first element is a one-letter opcode.
+ *
+ * Decoding is isolated per op: a malformed entry is reported through
+ * `onError` and skipped so the rest of the commit still applies.
+ */
+object PNTransaction {
+    /** Decode `json`; invalid ops are skipped after `onError(index, error)`. */
+    fun decode(json: String, onError: (Int, Throwable) -> Unit = { _, _ -> }): List<Op> {
+        val array = JSONArray(json)
+        val ops = ArrayList<Op>(array.length())
+        for (i in 0 until array.length()) {
+            try {
+                val raw = array.get(i) as? JSONArray
+                    ?: throw JSONException("op $i is not an array")
+                ops.add(decodeOp(raw))
+            } catch (e: Exception) {
+                onError(i, e)
+            }
+        }
+        return ops
+    }
+
+    /** Decode a single op array. */
+    fun decodeOp(raw: JSONArray): Op {
+        val code = raw.optString(0, "")
+        return when (code) {
+            "c" -> Op.Create(
+                tag(raw, 1),
+                raw.optString(2, ""),
+                raw.optJSONObject(3) ?: JSONObject(),
+            )
+            "u" -> Op.Update(tag(raw, 1), raw.optJSONObject(2) ?: JSONObject())
+            "i" -> Op.Insert(tag(raw, 1), tag(raw, 2), JsonUtil.toInt(raw.opt(3), 0))
+            "d" -> Op.Destroy(tag(raw, 1))
+            "f" -> Op.Frame(
+                tag(raw, 1),
+                JsonUtil.toDouble(raw.opt(2)),
+                JsonUtil.toDouble(raw.opt(3)),
+                JsonUtil.toDouble(raw.opt(4)),
+                JsonUtil.toDouble(raw.opt(5)),
+            )
+            else -> throw JSONException("unknown opcode '$code'")
+        }
+    }
+
+    private fun tag(raw: JSONArray, index: Int): Long {
+        val v = raw.opt(index) ?: throw JSONException("missing tag at $index")
+        return when (v) {
+            is Number -> v.toLong()
+            is String -> v.toLongOrNull() ?: throw JSONException("bad tag '$v'")
+            else -> throw JSONException("bad tag $v")
+        }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/bridge/TransactionApplier.kt

@@ -0,0 +1,117 @@
+package com.pythonnative.runtime.bridge
+
+import android.view.View
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.components.ComponentManager
+import com.pythonnative.runtime.components.PlaceholderManager
+import com.pythonnative.runtime.gestures.GestureCoordinator
+import org.json.JSONObject
+
+/**
+ * Applies decoded transactions to the view tree, in order, with per-op
+ * error isolation. Unknown element types create a placeholder view and
+ * log once.
+ */
+class TransactionApplier(private val registry: ViewRegistry) {
+    private val placeholder = PlaceholderManager()
+
+    /** Decode and apply `transactionJson`. */
+    fun apply(transactionJson: String) {
+        val ops = try {
+            PNTransaction.decode(transactionJson) { index, error ->
+                PNLog.rateLimited("decode", "transaction op $index could not be decoded", error)
+            }
+        } catch (e: Exception) {
+            PNLog.rateLimited("decode-top", "transaction is not a JSON array", e)
+            return
+        }
+        for (op in ops) {
+            try {
+                applyOp(op)
+            } catch (e: Exception) {
+                PNLog.rateLimited("op:" + op.javaClass.simpleName, "failed to apply $op", e)
+            }
+        }
+    }
+
+    /** Apply a single op. */
+    fun applyOp(op: Op) {
+        when (op) {
+            is Op.Create -> create(op)
+            is Op.Update -> update(op)
+            is Op.Insert -> insert(op)
+            is Op.Destroy -> destroy(op)
+            is Op.Frame -> frame(op)
+        }
+    }
+
+    private fun create(op: Op.Create) {
+        registry.get(op.tag)?.let {
+            PNLog.rateLimited("dup-create", "tag ${op.tag} already exists (${it.typeName}); replacing")
+            destroyRecord(it)
+        }
+        val manager = PNRegistry.managerFor(op.typeName) ?: run {
+            PNLog.once("unknown-type:" + op.typeName, "unknown element type '${op.typeName}'; using a placeholder view")
+            placeholder
+        }
+        val view = manager.createView(PNBridge.context(), op.tag, op.props)
+        val record = ViewRecord(op.tag, op.typeName, view, manager)
+        JsonUtil.merge(record.props, op.props)
+        registry.register(record)
+        try {
+            manager.applyProps(view, op.props, true)
+        } finally {
+            record.initialized = true
+        }
+        if (op.props.has("gestures")) {
+            GestureCoordinator.bind(record, op.props.opt("gestures"))
+        }
+    }
+
+    private fun update(op: Op.Update) {
+        val record = registry.get(op.tag) ?: throw IllegalStateException("update: unknown tag ${op.tag}")
+        JsonUtil.merge(record.props, op.changed)
+        record.manager.update(record.view, op.changed)
+        if (op.changed.has("gestures")) {
+            GestureCoordinator.bind(record, op.changed.opt("gestures"))
+        }
+    }
+
+    private fun insert(op: Op.Insert) {
+        val parent = registry.get(op.parent) ?: throw IllegalStateException("insert: unknown parent ${op.parent}")
+        val child = registry.get(op.child) ?: throw IllegalStateException("insert: unknown child ${op.child}")
+        parent.manager.insertChild(parent.view, child.view, op.index)
+    }
+
+    private fun destroy(op: Op.Destroy) {
+        val record = registry.get(op.tag) ?: return
+        destroyRecord(record)
+    }
+
+    private fun destroyRecord(record: ViewRecord) {
+        com.pythonnative.runtime.animation.AnimationGraph.forget(record.tag)
+        GestureCoordinator.unbind(record)
+        try {
+            val parentRecord = com.pythonnative.runtime.layout.NativeLayout.parent(record.tag)?.let { registry.get(it) }
+                ?: (record.view.parent as? View)?.let { registry.recordFor(it) }
+            if (parentRecord != null) {
+                parentRecord.manager.removeChild(parentRecord.view, record.view)
+            }
+            record.manager.destroy(record.view)
+        } finally {
+            registry.unregister(record.tag)
+        }
+    }
+
+    private fun frame(op: Op.Frame) {
+        val record = registry.get(op.tag) ?: throw IllegalStateException("frame: unknown tag ${op.tag}")
+        record.frame = doubleArrayOf(op.x, op.y, op.width, op.height)
+        record.manager.setFrame(record.view, op.x, op.y, op.width, op.height)
+    }
+
+    /** Whether `manager` is the fallback placeholder manager. */
+    fun isPlaceholder(manager: ComponentManager): Boolean = manager === placeholder
+
+    /** The props recorded for `tag`, mainly for diagnostics. */
+    fun propsOf(tag: Long): JSONObject? = registry.get(tag)?.props
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/bridge/ViewRegistry.kt

@@ -0,0 +1,74 @@
+package com.pythonnative.runtime.bridge
+
+import android.view.View
+import com.pythonnative.runtime.components.ComponentManager
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.IdentityHashMap
+
+/**
+ * Per-view bookkeeping: the reconciler tag, the element type, the
+ * manager that owns it, the merged props, and free-form manager state.
+ */
+class ViewRecord(
+    val tag: Long,
+    val typeName: String,
+    val view: View,
+    val manager: ComponentManager,
+) {
+    /** Every prop applied so far (removed props stay as JSON null). */
+    val props = JSONObject()
+
+    /** Manager-private state (suppress flags, wrapped widgets, etc.). */
+    val state = HashMap<String, Any?>()
+
+    /** Last frame applied by `setFrame`, in dp (`x, y, w, h`). */
+    var frame: DoubleArray? = null
+
+    /** Whether the initial props have been applied. */
+    var initialized = false
+
+    /** Whether the element wired a callback named `name` this render. */
+    fun hasEvent(name: String): Boolean {
+        val events = props.opt("_pn_events") as? JSONArray ?: return false
+        for (i in 0 until events.length()) {
+            if (events.optString(i) == name) return true
+        }
+        return false
+    }
+}
+
+/** Tag to [ViewRecord] map with a reverse index by view identity. */
+class ViewRegistry {
+    private val byTag = HashMap<Long, ViewRecord>()
+    private val byView = IdentityHashMap<View, ViewRecord>()
+
+    /** Number of live records. */
+    val size: Int get() = byTag.size
+
+    /** Register `record`; replaces any earlier record with the same tag. */
+    fun register(record: ViewRecord) {
+        byTag.remove(record.tag)?.let { byView.remove(it.view) }
+        byTag[record.tag] = record
+        byView[record.view] = record
+    }
+
+    /** Remove and return the record for `tag`. */
+    fun unregister(tag: Long): ViewRecord? {
+        val record = byTag.remove(tag) ?: return null
+        byView.remove(record.view)
+        return record
+    }
+
+    /** The record for `tag`, or `null`. */
+    fun get(tag: Long): ViewRecord? = byTag[tag]
+
+    /** The record whose view is `view`, or `null`. */
+    fun recordFor(view: View): ViewRecord? = byView[view]
+
+    /** The tag of `view`, or `null` when it is not a PythonNative view. */
+    fun tagOf(view: View): Long? = byView[view]?.tag
+
+    /** Snapshot of all records. */
+    fun all(): List<ViewRecord> = ArrayList(byTag.values)
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/components/BuiltinComponents.kt

@@ -0,0 +1,37 @@
+package com.pythonnative.runtime.components
+
+import com.pythonnative.runtime.bridge.PNRegistry
+
+/** Registers the built-in element types with the registry. */
+object BuiltinComponents {
+    fun register(registry: PNRegistry) {
+        registry.registerComponent("View") { ViewManager() }
+        registry.registerComponent("Screen") { ScreenManager() }
+        registry.registerComponent("ScreenStack") { ScreenStackManager() }
+        registry.registerComponent("Column") { ViewManager() }
+        registry.registerComponent("Row") { ViewManager() }
+        registry.registerComponent("Text") { TextManager() }
+        registry.registerComponent("Button") { ButtonManager() }
+        registry.registerComponent("TextInput") { TextInputManager() }
+        registry.registerComponent("Image") { ImageManager() }
+        registry.registerComponent("Switch") { SwitchManager() }
+        registry.registerComponent("Checkbox") { CheckboxManager() }
+        registry.registerComponent("ProgressBar") { ProgressBarManager() }
+        registry.registerComponent("ActivityIndicator") { ActivityIndicatorManager() }
+        registry.registerComponent("Slider") { SliderManager() }
+        registry.registerComponent("WebView") { WebViewManager() }
+        registry.registerComponent("Spacer") { SpacerManager() }
+        registry.registerComponent("ScrollView") { ScrollViewManager() }
+        registry.registerComponent("SafeAreaView") { SafeAreaViewManager() }
+        registry.registerComponent("KeyboardAvoidingView") { KeyboardAvoidingViewManager() }
+        registry.registerComponent("Modal") { ModalManager() }
+        registry.registerComponent("Portal") { PortalManager() }
+        registry.registerComponent("TabBar") { TabBarManager() }
+        registry.registerComponent("Pressable") { PressableManager() }
+        registry.registerComponent("StatusBar") { StatusBarManager() }
+        registry.registerComponent("Picker") { PickerManager() }
+        registry.registerComponent("SegmentedControl") { SegmentedControlManager() }
+        registry.registerComponent("DatePicker") { DatePickerManager() }
+        registry.registerComponent("VirtualList") { VirtualListManager() }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/components/ButtonManager.kt

@@ -0,0 +1,32 @@
+package com.pythonnative.runtime.components
+
+import android.content.Context
+import android.view.View
+import android.widget.Button
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.num
+import com.pythonnative.runtime.bridge.str
+import com.pythonnative.runtime.bridge.value
+import org.json.JSONObject
+
+/** `Button` element: a platform `Button` firing `on_press`. */
+class ButtonManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View {
+        val button = Button(context)
+        button.setOnClickListener { fire(it, "on_press") }
+        return button
+    }
+
+    override fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        val button = view as Button
+        if (props.has("title")) button.text = props.str("title") ?: ""
+        props.num("font_size")?.let { button.textSize = it.toFloat() }
+        PNColor.parse(props.value("color"))?.let { button.setTextColor(it) }
+        if (props.has("disabled")) button.isEnabled = !JsonUtil.truthy(props.value("disabled"))
+        if (props.has("all_caps")) button.isAllCaps = JsonUtil.truthy(props.value("all_caps"))
+        if (listOf("font_family", "font_weight", "italic", "bold").any { props.has(it) }) {
+            TextStyle.applyTypeface(button, propsOf(button))
+        }
+        ViewStyler.apply(button, props)
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/components/ComponentManager.kt

@@ -0,0 +1,213 @@
+package com.pythonnative.runtime.components
+
+import android.content.Context
+import android.util.Log
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.animation.PNAnimator
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.ViewRecord
+import com.pythonnative.runtime.bridge.present
+import org.json.JSONArray
+import org.json.JSONObject
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.roundToInt
+
+/**
+ * Base class for one element type's native implementation.
+ *
+ * Subclasses implement [createView] (construct the widget) and
+ * [applyProps] (apply visual props); the base class owns frame
+ * application, intrinsic measurement, child management, and the
+ * animation hooks. All geometry crossing this API is in dp.
+ */
+abstract class ComponentManager {
+    /** Construct the widget for `tag`; `props` may be consulted for creation-time choices. */
+    abstract fun createView(context: Context, tag: Long, props: JSONObject): View
+
+    /**
+     * Apply `props` to `view`. `initial` is `true` for the create op;
+     * on updates `props` holds only the changed keys (JSON null means
+     * removed). The merged props are always available via [propsOf].
+     */
+    open fun applyProps(view: View, props: JSONObject, initial: Boolean) {
+        ViewStyler.apply(view, props)
+    }
+
+    /** Apply changed props (the `u` op). */
+    fun update(view: View, changed: JSONObject) = applyProps(view, changed, false)
+
+    /** Ensure `child` sits at `index` under `parent` (move-aware, clamped). */
+    open fun insertChild(parent: View, child: View, index: Int) {
+        val group = parent as? ViewGroup ?: return
+        ViewChildren.insert(group, child, index)
+    }
+
+    /** Detach `child` from `parent` without destroying it. */
+    open fun removeChild(parent: View, child: View) {
+        (parent as? ViewGroup)?.removeView(child)
+    }
+
+    /** Release resources and detach from the parent. */
+    open fun destroy(view: View) {
+        try {
+            teardown(view)
+        } catch (e: Exception) {
+            Log.d(PNBridge.TAG, "teardown failed for ${view.javaClass.simpleName}", e)
+        }
+        (view.parent as? ViewGroup)?.removeView(view)
+    }
+
+    /** Subclass hook for extra cleanup before the view is released. */
+    protected open fun teardown(view: View) {}
+
+    /**
+     * Position `view` inside its parent's `FrameLayout` via margin layout
+     * params. Non-finite values are clamped; sizes are never negative.
+     */
+    open fun setFrame(view: View, x: Double, y: Double, width: Double, height: Double) {
+        val pxX = px(finite(x))
+        val pxY = px(finite(y))
+        val pxW = max(0, px(finite(width)))
+        val pxH = max(0, px(finite(height)))
+        val lp = view.layoutParams
+        val params: ViewGroup.LayoutParams = if (lp == null) {
+            FrameLayout.LayoutParams(pxW, pxH)
+        } else {
+            lp.width = pxW
+            lp.height = pxH
+            lp
+        }
+        if (params is ViewGroup.MarginLayoutParams) {
+            params.leftMargin = pxX
+            params.topMargin = pxY
+            params.rightMargin = 0
+            params.bottomMargin = 0
+        }
+        view.layoutParams = params
+        val record = recordOf(view)
+        if (record != null) {
+            record.frame = doubleArrayOf(x, y, width, height)
+            if (record.props.present("hit_slop") || record.state["hit_slop_active"] == true) {
+                ViewStyler.updateHitSlop(view)
+            }
+        }
+    }
+
+    /**
+     * Natural size of `view` under the constraints, in dp. Either
+     * constraint may be `1e6` or infinite meaning unconstrained.
+     */
+    open fun measure(view: View, maxWidth: Double, maxHeight: Double): FloatArray {
+        val density = PNBridge.density()
+        val wSpec = measureSpec(maxWidth, density)
+        val hSpec = measureSpec(maxHeight, density)
+        view.measure(wSpec, hSpec)
+        return floatArrayOf(view.measuredWidth / density, view.measuredHeight / density)
+    }
+
+    /** Run an imperative command; unknown names return `null`. */
+    open fun command(view: View, name: String, args: JSONObject): Any? = null
+
+    /** Apply one Python-driven animation frame immediately. */
+    open fun setAnimatedProperty(view: View, prop: String, value: Any?) {
+        PNAnimator.setProperty(view, prop, value)
+    }
+
+    /** Start a natively driven animation; `false` asks Python to tick it instead. */
+    open fun startAnimation(view: View, id: Long, prop: String, spec: JSONObject): Boolean =
+        PNAnimator.start(view, id, prop, spec)
+
+    /** Cancel a native animation and return the presentation value, if readable. */
+    open fun cancelAnimation(view: View, id: Long): Any? = PNAnimator.cancel(id)
+
+    // ------------------------------------------------------------------
+    // Helpers for subclasses
+    // ------------------------------------------------------------------
+
+    /** The registry record for `view`, or `null` for foreign views. */
+    protected fun recordOf(view: View): ViewRecord? = PNBridge.registry.recordFor(view)
+
+    /** Merged props for `view` (empty for foreign views). */
+    protected fun propsOf(view: View): JSONObject = recordOf(view)?.props ?: JSONObject()
+
+    /** Manager-private state map for `view`. */
+    protected fun stateOf(view: View): MutableMap<String, Any?> = recordOf(view)?.state ?: HashMap()
+
+    /** Dispatch event `name` with positional `args` for `view`'s tag. */
+    protected fun fire(view: View, name: String, vararg args: Any?): Boolean = PNEvents.fire(view, name, *args)
+
+    /** Dispatch event `name` and return Python's (JSON) reply. */
+    protected fun fireForResult(view: View, name: String, vararg args: Any?): String? =
+        PNEvents.fireForResult(view, name, *args)
+
+    /** Whether the element wired a callback named `name`. */
+    protected fun hasEvent(view: View, name: String): Boolean = recordOf(view)?.hasEvent(name) ?: false
+
+    /** dp to whole pixels. */
+    protected fun px(dp: Double): Int = (dp * PNBridge.density()).roundToInt()
+
+    /** dp to pixels as a float. */
+    protected fun pxF(dp: Double): Float = (dp * PNBridge.density()).toFloat()
+
+    /** pixels to dp. */
+    protected fun dp(px: Number): Double = px.toDouble() / PNBridge.density()
+
+    private fun finite(v: Double): Double = if (v.isNaN() || v.isInfinite()) 0.0 else v
+
+    private fun measureSpec(limit: Double, density: Float): Int {
+        if (limit.isNaN() || limit.isInfinite() || limit >= 1e6) {
+            return View.MeasureSpec.makeMeasureSpec(0, View.MeasureSpec.UNSPECIFIED)
+        }
+        val px = min((max(0.0, limit) * density).toInt(), (1 shl 29))
+        return View.MeasureSpec.makeMeasureSpec(px, View.MeasureSpec.AT_MOST)
+    }
+}
+
+/** Move-aware indexed insertion into any `ViewGroup`. */
+object ViewChildren {
+    fun insert(parent: ViewGroup, child: View, index: Int) {
+        val current = child.parent as? ViewGroup
+        if (current === parent) {
+            val currentIndex = parent.indexOfChild(child)
+            val target = max(0, min(index, parent.childCount - 1))
+            if (currentIndex == target) return
+            parent.removeView(child)
+            parent.addView(child, max(0, min(target, parent.childCount)))
+            return
+        }
+        current?.removeView(child)
+        if (child.layoutParams == null) {
+            child.layoutParams = FrameLayout.LayoutParams(0, 0)
+        }
+        parent.addView(child, max(0, min(index, parent.childCount)))
+    }
+}
+
+/** Event dispatch keyed by view identity. */
+object PNEvents {
+    /** Dispatch `name` for `view` with positional `args`; `false` when the view is unknown. */
+    fun fire(view: View, name: String, vararg args: Any?): Boolean {
+        val tag = PNBridge.registry.tagOf(view) ?: return false
+        fireTag(tag, name, JsonUtil.args(*args))
+        return true
+    }
+
+    /** Dispatch `name` for `view` and return Python's JSON reply. */
+    fun fireForResult(view: View, name: String, vararg args: Any?): String? {
+        val tag = PNBridge.registry.tagOf(view) ?: return null
+        return fireTag(tag, name, JsonUtil.args(*args))
+    }
+
+    /** Dispatch `name` for `tag` with an already built argument array. */
+    fun fireTag(tag: Long, name: String, args: JSONArray): String? =
+        PNBridge.callPython("event", tag, name, args.toString())
+}
+
+/** Fallback for unknown element types: an empty container that hosts children. */
+class PlaceholderManager : ComponentManager() {
+    override fun createView(context: Context, tag: Long, props: JSONObject): View = FrameLayout(context)
+}