Write a native module

kuito module create Battery

modules/battery/
  battery.ts
  ios/BatteryModule.swift
  android/BatteryModule.kt

import { defineModule, fn, live } from 'kuito';

export type Reading = { level: number; charging: boolean };

export default defineModule('Battery', {
  /** Low Power Mode on iOS, Battery Saver on Android. */
  lowPower: live<boolean>(),
  /** The charge from 0 to 1, or -1 when unknown. */
  read: fn.main<() => Promise<Reading>>(),
  ios: { class: 'BatteryModule' },
  android: { class: 'com.example.myapp.modules.battery.BatteryModule' },
});

import UIKit

final class BatteryModule: BatterySpec {
    private var observer: NSObjectProtocol?

    init(context: KuitoModuleContext) {}

    // ProcessInfo is thread-safe, so the read runs on the JS thread.
    func lowPower() -> Bool {
        ProcessInfo.processInfo.isLowPowerModeEnabled
    }

    @MainActor func read() -> Reading {
        let device = UIDevice.current

        device.isBatteryMonitoringEnabled = true

        return Reading(level: Double(device.batteryLevel), charging: device.batteryState == .charging)
    }

    @MainActor func startLowPower(_ signal: KuitoSignal<Bool>) {
        observer = NotificationCenter.default.addObserver(
            forName: .NSProcessInfoPowerStateDidChange, object: nil, queue: .main
        ) { _ in signal.set(ProcessInfo.processInfo.isLowPowerModeEnabled) }
    }

    @MainActor func stopLowPower() {
        observer.map(NotificationCenter.default.removeObserver)
        observer = nil
    }
}

package com.example.myapp.modules.battery

import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.content.IntentFilter
import android.os.BatteryManager
import android.os.PowerManager
import dev.kuito.link.BatterySpec
import dev.kuito.link.Reading
import dev.kuito.runtime.link.KuitoSignal
import dev.kuito.runtime.modules.KuitoModuleContext

class BatteryModule(context: KuitoModuleContext) : BatterySpec {
    private val app = context.applicationContext
    private val power = app.getSystemService(PowerManager::class.java)
    private var receiver: BroadcastReceiver? = null

    override fun lowPower() = power.isPowerSaveMode

    override fun read(): Reading {
        val battery = app.getSystemService(BatteryManager::class.java)

        return Reading(
            level = battery.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY) / 100.0,
            charging = battery.isCharging,
        )
    }

    override fun startLowPower(signal: KuitoSignal<Boolean>) {
        receiver = object : BroadcastReceiver() {
            override fun onReceive(c: Context, intent: Intent) = signal.set(power.isPowerSaveMode)
        }.also { app.registerReceiver(it, IntentFilter(PowerManager.ACTION_POWER_SAVE_MODE_CHANGED)) }
    }

    override fun stopLowPower() {
        receiver?.let(app::unregisterReceiver)
        receiver = null
    }
}

Include `ios/` or `android/` sources for every platform section you declare. Android `res/` resources join the app's resource namespace; prefix names to avoid collisions. Two modules cannot supply conflicting Info.plist values. Permission reasons declared by the app replace module defaults.

A module with `launch: true` implements a static Swift `@MainActor launch()` or a Kotlin companion `launch(application: Application)`. The shell calls it during app launch, before the runtime starts. Use it only for APIs requiring early registration, and keep it short.

## Handle errors and binary data

<!-- error codes: generated from src/protocol/modules.ts -->

| Code                     | Meaning                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------ |
| `ERR_FUNCTION_NOT_FOUND` | The shell's link table doesn't hold the function: rebuild it.                        |
| `ERR_VIEW_NOT_FOUND`     | A view function's view is not mounted.                                               |
| `ERR_ARGUMENT`           | An argument didn't decode into the declared type.                                    |
| `ERR_ENCODE`             | A result or event payload isn't plain data of the declared type.                     |
| `ERR_NATIVE`             | The function threw something other than `KuitoModuleError`.                          |
| `ERR_THREAD`             | A synchronous call reached an asynchronous function.                                 |
| `ERR_NO_ACTIVITY`        | The module needs the activity, and a background task runs without one. Android only. |

<!-- end of generated error codes -->

Synchronous failures throw; asynchronous failures reject. Errors include the module, member and code. Listener exceptions are reported without preventing other listeners from running.

`ArrayBuffer` crosses as bytes. Native-returned writable buffers can be shared; JavaScript-owned buffers are copied into native-owned memory. Do not mutate a buffer while native code is still using it, and do not return read-only mapped memory as a writable buffer.

## Test and distribute

Test JavaScript behavior with native fakes through [kuito/tests](testing.md). Build and run both platform implementations to verify permissions, threading, event cleanup and view behavior. Headless tests do not execute Swift or Kotlin.

The documented spec factories and generated native protocols form module API version 1. Host function names and link IDs are implementation details. To share the module between apps, follow [package a module](module-packaging.md).