akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/plugins/app-state/ios/AppStatePlugin.swift

@@ -0,0 +1,58 @@
+import UIKit
+
+/// Scene lifecycle → active / inactive / background, filtered to the scene showing our web view.
+/// Same mapping as react-native RCTAppState.mm: willEnterForeground still reports background
+/// (not visible yet) until didActivate.
+/// The result and event types come from the generated AppStatePluginSpec (PL-10).
+final class AppStatePlugin: AppStatePluginSpec {
+    static let id = "app-state"
+    private let context: AkanNativePluginContext
+    private var observers: [NSObjectProtocol] = []
+    private var last: AppStateValue?
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+    }
+
+    private static func state(_ s: UIScene.ActivationState?) -> AppStateValue {
+        switch s {
+        case .foregroundActive: .active
+        case .foregroundInactive: .inactive
+        default: .background
+        }
+    }
+
+    func getState(_ reply: AkanNativeReply<AppStateGetStateResult>) {
+        reply.resolve(AppStateGetStateResult(state: Self.state(context.windowScene?.activationState)))
+    }
+
+    func startListening(_ event: String) {
+        guard event == "change", observers.isEmpty else { return }
+        last = Self.state(context.windowScene?.activationState)
+        let transitions: [(Notification.Name, AppStateValue)] = [
+            (UIScene.didActivateNotification, .active),
+            (UIScene.willDeactivateNotification, .inactive),
+            (UIScene.didEnterBackgroundNotification, .background),
+            (UIScene.willEnterForegroundNotification, .background),
+        ]
+        for (name, state) in transitions {
+            observers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] note in
+                let scene = UncheckedBox(note.object as? UIScene)
+                MainActor.assumeIsolated { self?.changed(scene.value, state) }
+            })
+        }
+    }
+
+    func stopListening(_ event: String) {
+        guard event == "change" else { return }
+        observers.forEach(NotificationCenter.default.removeObserver)
+        observers.removeAll()
+    }
+
+    private func changed(_ scene: UIScene?, _ state: AppStateValue) {
+        if let mine = context.windowScene, let scene, scene !== mine { return }
+        guard state != last else { return }
+        last = state
+        AppStateEvents(context).change(AppStateChangeEvent(state: state))
+    }
+}

package/vendor/@akanjs/native/plugins/app-state/native-plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "app-state",
+  "apiVersion": 1,
+  "methods": ["getState"],
+  "events": ["change"],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "web",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "AppStatePlugin"
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.appstate.AppStatePlugin"
+  }
+}

package/vendor/@akanjs/native/plugins/app-state/src/index.ts

@@ -0,0 +1,42 @@
+import { createLiveValue, definePlugin } from "../../../packages/core/src/index.ts";
+import { useLiveValue } from "../../../packages/react/src/index.ts";
+import { web } from "./web.ts";
+
+/**
+ * - active: visible and receiving input
+ * - inactive: visible but not focused (another window, system overlay, app switcher)
+ * - background: not visible
+ */
+export type AppStateValue = "active" | "inactive" | "background";
+
+export interface AppStateApi {
+  getState(): Promise<{ state: AppStateValue }>;
+}
+
+export interface AppStateEvents {
+  change: { state: AppStateValue };
+}
+
+export const appState = definePlugin<AppStateApi, AppStateEvents>("app-state", {
+  methods: ["getState"],
+  events: ["change"],
+  web,
+});
+
+const current = createLiveValue<AppStateValue>("active", (set) => {
+  let live = true;
+  const stop = appState.listen("change", ({ state }) => set(state));
+  appState
+    .getState()
+    .then(({ state }) => live && set(state))
+    .catch(() => {});
+  return () => {
+    live = false;
+    stop();
+  };
+});
+
+/** The current app state. Re-renders on every change (SH-1). */
+export function useAppState(): AppStateValue {
+  return useLiveValue(current);
+}

package/vendor/@akanjs/native/plugins/app-state/src/web.ts

@@ -0,0 +1,33 @@
+import { defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { AppStateApi, AppStateEvents, AppStateValue } from "./index.ts";
+
+function read(): AppStateValue {
+  if (document.visibilityState === "hidden") return "background";
+  return document.hasFocus() ? "active" : "inactive";
+}
+
+export const web = defineWebPlugin<AppStateApi, AppStateEvents>({
+  methods: {
+    getState: async () => ({ state: read() }),
+  },
+  events: {
+    change(emit) {
+      let last = read();
+      const check = () => {
+        const next = read();
+        if (next === last) return;
+        last = next;
+        emit({ state: next });
+      };
+
+      document.addEventListener("visibilitychange", check);
+      window.addEventListener("focus", check);
+      window.addEventListener("blur", check);
+      return () => {
+        document.removeEventListener("visibilitychange", check);
+        window.removeEventListener("focus", check);
+        window.removeEventListener("blur", check);
+      };
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/appearance/android/AppearancePlugin.kt

@@ -0,0 +1,133 @@
+package com.akanjs.plugins.appearance
+
+import android.app.UiModeManager
+import android.content.Context
+import android.content.res.Configuration
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import com.akanjs.runtime.AkanNativeCompat
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * UiModeManager.setApplicationNightMode (API 31) instead of AppCompatDelegate.setDefaultNightMode,
+ * which react-native uses (AppearanceModule.kt:85-95), plugins.md §2 AndroidX table.
+ * - The system keeps the per-app night mode across launches and applies it to the app's
+ *   configuration before the activity starts; MODE_NIGHT_AUTO clears it (follow the system).
+ *   There is no getter, so the setting is mirrored in SharedPreferences and written again at
+ *   start, which also clears a stale system value after the app's data was cleared.
+ * - The shell handles uiMode changes without recreating the activity (configChanges); the
+ *   DayNight theme then flips the WebView's prefers-color-scheme with a matchMedia change event
+ *   (docs/research/android.md: verified for system switches, algorithmic darkening off).
+ * - mode: the fixed setting, or the configuration's night bit when following the system.
+ * - change: onConfigurationChanged, plus a check shortly after set(), since a setting that keeps
+ *   the drawn scheme (system dark, set dark) changes no configuration. Duplicates are filtered.
+ * - Below API 31 there is no per-app night mode: the setting goes to AkanNativeCompat.storeNightMode, the
+ *   shell applies it as an override configuration when the activity starts, and set() recreates the
+ *   activity when the drawn scheme changes, so the page reloads there.
+ * Arguments arrive decoded and checked by the generated AppearancePluginSpec (PL-10).
+ */
+class AppearancePlugin(private val context: AkanNativePluginContext) : AppearancePluginSpec {
+    private val prefs = context.activity.getSharedPreferences("akan-native.appearance", Context.MODE_PRIVATE)
+    private val uiModes: UiModeManager? = context.activity.getSystemService(UiModeManager::class.java)
+    private val main = Handler(Looper.getMainLooper())
+    private val check = Runnable { report() }
+    private val events = AppearanceEvents(context)
+    private var listening = false
+    private var last: AppearanceState? = null
+
+    init {
+        try {
+            if (Build.VERSION.SDK_INT >= 31) uiModes?.let { Api31.setNightMode(it, nightMode(setting())) }
+        } catch (e: RuntimeException) {
+            Log.w("AkanNative", "appearance: cannot apply the stored setting", e)
+        }
+    }
+
+    override fun get(reply: AkanNativeReply<AppearanceState>) = reply.resolve(state())
+
+    override fun set(args: AppearanceSetArgs, reply: AkanNativeVoidReply) {
+        if (Build.VERSION.SDK_INT < 31) return setLegacy(args.mode, reply)
+        val manager = uiModes ?: return reply.reject(AkanNativeErrorCode.UNSUPPORTED, "no UiModeManager on this device")
+        Api31.setNightMode(manager, nightMode(args.mode))
+        prefs.edit().putString(KEY, args.mode.json).apply()
+        reply.resolve()
+        main.removeCallbacks(check)
+        main.postDelayed(check, SETTLE_MS)
+    }
+
+    /** API 29 and 30: store the override and recreate the activity when the drawn scheme changes. */
+    private fun setLegacy(mode: AppearanceSetting, reply: AkanNativeVoidReply) {
+        val activity = context.activity
+        val night = when (mode) {
+            AppearanceSetting.DARK -> true
+            AppearanceSetting.LIGHT -> false
+            AppearanceSetting.SYSTEM -> null
+        }
+        val drawn = isNight(activity.resources.configuration)
+        // The application's configuration has no activity override: the system's own scheme.
+        val next = night ?: isNight(activity.applicationContext.resources.configuration)
+        AkanNativeCompat.storeNightMode(activity, night)
+        prefs.edit().putString(KEY, mode.json).apply()
+        reply.resolve()
+        if (next != drawn) main.post { activity.recreate() }
+    }
+
+    private fun isNight(config: Configuration) = (config.uiMode and Configuration.UI_MODE_NIGHT_MASK) == Configuration.UI_MODE_NIGHT_YES
+
+    private object Api31 {
+        fun setNightMode(manager: UiModeManager, mode: Int) = manager.setApplicationNightMode(mode)
+    }
+
+    override fun onConfigurationChanged(config: Configuration) = report()
+
+    override fun startListening(event: String) {
+        if (event != "change") return
+        listening = true
+        last = state()
+    }
+
+    override fun stopListening(event: String) {
+        if (event != "change") return
+        listening = false
+        last = null
+        main.removeCallbacks(check)
+    }
+
+    override fun destroy() = main.removeCallbacks(check)
+
+    private fun report() {
+        if (!listening) return
+        val next = state()
+        if (next == last) return
+        last = next
+        events.change(next)
+    }
+
+    private fun setting(): AppearanceSetting =
+        prefs.getString(KEY, null)?.let { stored -> AppearanceSetting.entries.firstOrNull { it.json == stored } } ?: AppearanceSetting.SYSTEM
+
+    private fun state(): AppearanceState = when (val setting = setting()) {
+        AppearanceSetting.LIGHT -> AppearanceState(mode = AppearanceColorScheme.LIGHT, setting = setting)
+        AppearanceSetting.DARK -> AppearanceState(mode = AppearanceColorScheme.DARK, setting = setting)
+        AppearanceSetting.SYSTEM -> {
+            val night = (context.activity.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) == Configuration.UI_MODE_NIGHT_YES
+            AppearanceState(mode = if (night) AppearanceColorScheme.DARK else AppearanceColorScheme.LIGHT, setting = setting)
+        }
+    }
+
+    private fun nightMode(setting: AppearanceSetting): Int = when (setting) {
+        AppearanceSetting.DARK -> UiModeManager.MODE_NIGHT_YES
+        AppearanceSetting.LIGHT -> UiModeManager.MODE_NIGHT_NO
+        AppearanceSetting.SYSTEM -> UiModeManager.MODE_NIGHT_AUTO
+    }
+
+    private companion object {
+        const val KEY = "setting"
+        const val SETTLE_MS = 500L
+    }
+}

package/vendor/@akanjs/native/plugins/appearance/ios/AppearancePlugin.swift

@@ -0,0 +1,109 @@
+import UIKit
+
+/// overrideUserInterfaceStyle on every window of every connected scene, as RN does
+/// (react-native/packages/react-native/React/CoreModules/RCTAppearance.mm:112-126): the window
+/// carries the style to the WKWebView (prefers-color-scheme), presented controllers, alerts and
+/// the status bar. The VC's own override would miss controllers presented by plugins.
+/// - The setting is stored in UserDefaults and applied when the plugin starts, which is inside the
+///   view controller's loadView: the window exists, nothing is drawn yet (no flash of the other scheme).
+/// - mode: the fixed setting, or the scene's style (the system's, unaffected by window overrides).
+/// - change: a trait registration on the web view sees both system switches and set(). iOS flips
+///   the style of a backgrounded app twice to snapshot both appearances, so changes are only
+///   reported while not in the background, and checked again on the way back to the foreground.
+/// Arguments arrive decoded and checked by the generated AppearancePluginSpec (PL-10).
+final class AppearancePlugin: AppearancePluginSpec {
+    static let id = "appearance"
+    private static let key = "akan-native.appearance"
+
+    private let context: AkanNativePluginContext
+    /// iOS 17+: the trait change registration. iOS 16: the observer of AkanNativeWebView.styleDidChange.
+    private var registration: Any?
+    private var foreground: (any NSObjectProtocol)?
+    private var last: AppearanceState?
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+        let setting = Self.setting
+        if setting != .system { Self.apply(setting) }
+    }
+
+    private static var setting: AppearanceSetting {
+        UserDefaults.standard.string(forKey: key).flatMap(AppearanceSetting.init(rawValue:)) ?? .system
+    }
+
+    func get(_ reply: AkanNativeReply<AppearanceState>) {
+        reply.resolve(state())
+    }
+
+    func set(_ args: AppearanceSetArgs, _ reply: AkanNativeReply<Void>) {
+        if args.mode == .system {
+            UserDefaults.standard.removeObject(forKey: Self.key)
+        } else {
+            UserDefaults.standard.set(args.mode.rawValue, forKey: Self.key)
+        }
+        Self.apply(args.mode)
+        reply.resolve()
+        // A setting change that keeps the drawn scheme (system is dark, set dark) moves no trait.
+        report()
+    }
+
+    func startListening(_ event: String) {
+        guard event == "change", registration == nil, let webView = context.webView else { return }
+        last = state()
+        if #available(iOS 17.0, *) {
+            registration = webView.registerForTraitChanges([UITraitUserInterfaceStyle.self]) { [weak self] (_: UIView, _: UITraitCollection) in
+                self?.report()
+            }
+        } else {
+            registration = NotificationCenter.default.addObserver(forName: AkanNativeWebView.styleDidChange, object: webView, queue: .main) { [weak self] _ in
+                MainActor.assumeIsolated { self?.report() }
+            }
+        }
+        foreground = NotificationCenter.default.addObserver(forName: UIApplication.willEnterForegroundNotification, object: nil, queue: .main) { [weak self] _ in
+            MainActor.assumeIsolated { self?.report() }
+        }
+    }
+
+    func stopListening(_ event: String) {
+        guard event == "change" else { return }
+        if #available(iOS 17.0, *), let registration = registration as? any UITraitChangeRegistration {
+            context.webView?.unregisterForTraitChanges(registration)
+        } else if let registration = registration as? any NSObjectProtocol {
+            NotificationCenter.default.removeObserver(registration)
+        }
+        if let foreground { NotificationCenter.default.removeObserver(foreground) }
+        registration = nil
+        foreground = nil
+        last = nil
+    }
+
+    private func report() {
+        guard registration != nil, UIApplication.shared.applicationState != .background else { return }
+        let next = state()
+        if let last, last.mode == next.mode, last.setting == next.setting { return }
+        last = next
+        AppearanceEvents(context).change(next)
+    }
+
+    private func state() -> AppearanceState {
+        let setting = Self.setting
+        switch setting {
+        case .light: return AppearanceState(mode: .light, setting: setting)
+        case .dark: return AppearanceState(mode: .dark, setting: setting)
+        case .system:
+            let style = context.windowScene?.traitCollection.userInterfaceStyle ?? UITraitCollection.current.userInterfaceStyle
+            return AppearanceState(mode: style == .dark ? .dark : .light, setting: setting)
+        }
+    }
+
+    private static func apply(_ setting: AppearanceSetting) {
+        let style: UIUserInterfaceStyle = switch setting {
+        case .dark: .dark
+        case .light: .light
+        case .system: .unspecified
+        }
+        for case let scene as UIWindowScene in UIApplication.shared.connectedScenes {
+            for window in scene.windows { window.overrideUserInterfaceStyle = style }
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/appearance/native-plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "appearance",
+  "apiVersion": 1,
+  "methods": ["get", "set"],
+  "events": ["change"],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "./src/desktop.ts",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "AppearancePlugin",
+    "privacyApis": { "UserDefaults": ["CA92.1"] }
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.appearance.AppearancePlugin"
+  }
+}

package/vendor/@akanjs/native/plugins/appearance/src/desktop.ts

@@ -0,0 +1,133 @@
+
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { type DesktopContext, defineDesktopPlugin, type NativeEvent } from "../../../packages/desktop/src/plugin.ts";
+import type { AppearanceApi, AppearanceEvents, AppearanceState } from "./index.ts";
+import { type AppearanceSetting, type ColorScheme, checkSetting } from "./setting.ts";
+
+export type Runner = (argv: string[]) => Promise<{ code: number; stdout: string }>;
+
+const spawnRunner: Runner = async (argv) => {
+  const proc = Bun.spawn(argv, { stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+  const [stdout, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  return { code, stdout };
+};
+
+const SHELL_TIMEOUT_MS = 2000;
+
+function isUnknownOp(error: unknown): boolean {
+  return /unknown op/.test(String((error as Error)?.message ?? error));
+}
+
+/** A shell op with a timeout, so a missing native side can never hang a call. */
+function shell(ctx: DesktopContext, op: string, args?: Record<string, unknown>): Promise<unknown> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new AkanNativeError("INTERNAL", `shell op ${op} did not answer`)),
+      SHELL_TIMEOUT_MS,
+    );
+  });
+  return Promise.race([ctx.shell(op, args), timeout]).finally(() => clearTimeout(timer));
+}
+
+/** `run` is replaceable so tests can check the commands and shell ops, `platform` to test the other OSes' fallback. */
+export function createDesktopAppearance(run: Runner = spawnRunner, platform: NodeJS.Platform = process.platform) {
+  let setting: AppearanceSetting = "system";
+  let loadedFrom = "";
+  let last: AppearanceState | null = null;
+  let send: ((state: AppearanceState) => void) | null = null;
+
+  const file = (ctx: DesktopContext) => join(ctx.appDataDir, "appearance.json");
+
+  const load = (ctx: DesktopContext) => {
+    const path = file(ctx);
+    if (loadedFrom === path) return;
+    loadedFrom = path;
+    try {
+      if (existsSync(path))
+        setting = checkSetting((JSON.parse(readFileSync(path, "utf8")) as { setting?: unknown }).setting);
+    } catch (error) {
+      console.error(`[akan-native] ${path} is unreadable, following the system appearance`, error);
+    }
+  };
+
+  const save = (ctx: DesktopContext) => {
+    const path = file(ctx);
+    writeFileSync(`${path}.tmp`, JSON.stringify({ setting }));
+    renameSync(`${path}.tmp`, path);
+  };
+
+  const systemMode = async (): Promise<ColorScheme> => {
+    if (platform !== "darwin") return "light"; 
+    const { code, stdout } = await run(["/usr/bin/defaults", "read", "-g", "AppleInterfaceStyle"]);
+    return code === 0 && stdout.trim() === "Dark" ? "dark" : "light"; 
+  };
+
+  const state = async (ctx: DesktopContext): Promise<AppearanceState> => {
+    load(ctx);
+    try {
+      const theme = ((await shell(ctx, "window.getState")) as { theme?: unknown } | null)?.theme;
+      if (theme === "light" || theme === "dark") return { mode: theme, setting };
+    } catch {
+    }
+    return { mode: setting === "system" ? await systemMode() : setting, setting };
+  };
+
+  const report = (next: AppearanceState) => {
+    if (!send || (last && last.mode === next.mode && last.setting === next.setting)) return;
+    last = next;
+    send(next);
+  };
+
+  return defineDesktopPlugin<AppearanceApi, AppearanceEvents>({
+    id: "appearance",
+    setup(ctx) {
+      ctx.onNativeEvent("init", () => {
+        load(ctx);
+        if (setting !== "system") shell(ctx, "window.setTheme", { theme: setting }).catch(() => {});
+      });
+      ctx.onNativeEvent("window", (event: NativeEvent) => {
+        if (event.event !== "themeChanged" || (event.theme !== "light" && event.theme !== "dark")) return;
+        report({ mode: event.theme, setting });
+      });
+    },
+    methods: {
+      get: (_args, ctx) => state(ctx),
+      async set(args, ctx) {
+        const next = checkSetting(args?.mode);
+        load(ctx);
+        try {
+          await shell(ctx, "window.setTheme", { theme: next === "system" ? null : next });
+        } catch (error) {
+          if (isUnknownOp(error))
+            throw new AkanNativeError(
+              "UNSUPPORTED",
+              "appearance.set needs the window.setTheme shell op, which this akan-native runtime lacks",
+            );
+          throw error;
+        }
+        setting = next;
+        save(ctx);
+        report(await state(ctx));
+      },
+    },
+    events: {
+      change(emit, ctx) {
+        send = emit;
+        last = null;
+        void state(ctx).then((s) => {
+          if (send === emit && !last) last = s; 
+        });
+        return () => {
+          send = null;
+          last = null;
+        };
+      },
+    },
+  });
+}
+
+export default createDesktopAppearance();

package/vendor/@akanjs/native/plugins/appearance/src/index.ts

@@ -0,0 +1,62 @@
+import { createLiveValue, definePlugin, shallowEqual } from "../../../packages/core/src/index.ts";
+import { useLiveValue } from "../../../packages/react/src/index.ts";
+import type { AppearanceSetting, ColorScheme } from "./setting.ts";
+import { readWebState, web } from "./web.ts";
+
+export { APPEARANCE_SETTINGS, type AppearanceSetting, type ColorScheme, checkSetting } from "./setting.ts";
+
+export interface AppearanceState {
+  /** The scheme the app is drawn in right now; the page's `prefers-color-scheme` matches it. */
+  mode: ColorScheme;
+  /** The app's setting. Always "system" on the web and until set() was called. */
+  setting: AppearanceSetting;
+}
+
+/**
+ * Light/dark appearance of the app (plugins.md §4.1). To only follow the OS, CSS
+ * `prefers-color-scheme` is enough; this plugin is for apps with their own theme switch.
+ */
+export interface AppearanceApi {
+  get(): Promise<AppearanceState>;
+  /**
+   * Forces light or dark for the whole app (WebView, system UI such as dialogs, keyboards and
+   * status bar icons), or goes back to the OS setting with "system". The setting is kept across
+   * launches and applied at start (on iOS and Android before the first paint), so call it when the
+   * user picks a theme, not at every start. The change event follows once the app redrew. Not
+   * available on the web (UNSUPPORTED): a page cannot change `prefers-color-scheme`.
+   */
+  set(args: { mode: AppearanceSetting }): Promise<void>;
+}
+
+export interface AppearanceEvents {
+  /** `mode` or `setting` changed: an OS switch while following the system, or set(). */
+  change: AppearanceState;
+}
+
+export const appearance = definePlugin<AppearanceApi, AppearanceEvents>("appearance", {
+  methods: ["get", "set"],
+  events: ["change"],
+  web,
+});
+
+const current = createLiveValue<AppearanceState>(
+  readWebState(),
+  (set) => {
+    let live = true;
+    const stop = appearance.listen("change", set);
+    appearance
+      .get()
+      .then((state) => live && set(state))
+      .catch(() => {});
+    return () => {
+      live = false;
+      stop();
+    };
+  },
+  shallowEqual,
+);
+
+/** The current appearance. Re-renders on every change. */
+export function useAppearance(): AppearanceState {
+  return useLiveValue(current);
+}

package/vendor/@akanjs/native/plugins/appearance/src/setting.ts

@@ -0,0 +1,18 @@
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+
+export type ColorScheme = "light" | "dark";
+/** What the app asked for: a fixed scheme, or "system" to follow the OS setting. */
+export type AppearanceSetting = ColorScheme | "system";
+
+export const APPEARANCE_SETTINGS: readonly AppearanceSetting[] = ["light", "dark", "system"];
+
+/** Checks set()'s argument; the native implementations check the same list. */
+export function checkSetting(mode: unknown): AppearanceSetting {
+  if (typeof mode !== "string" || !(APPEARANCE_SETTINGS as readonly string[]).includes(mode)) {
+    throw new AkanNativeError(
+      "INVALID_ARGS",
+      `mode must be one of ${APPEARANCE_SETTINGS.join(", ")} (got ${JSON.stringify(mode)})`,
+    );
+  }
+  return mode as AppearanceSetting;
+}

package/vendor/@akanjs/native/plugins/appearance/src/web.ts

@@ -0,0 +1,25 @@
+import { defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { AppearanceApi, AppearanceEvents, AppearanceState } from "./index.ts";
+
+function query(): MediaQueryList | null {
+  return typeof matchMedia === "function" ? matchMedia("(prefers-color-scheme: dark)") : null;
+}
+
+export function readWebState(): AppearanceState {
+  return { mode: query()?.matches ? "dark" : "light", setting: "system" };
+}
+
+export const web = defineWebPlugin<AppearanceApi, AppearanceEvents>({
+  methods: {
+    get: async () => readWebState(),
+  },
+  events: {
+    change(emit) {
+      const q = query();
+      if (!q) return () => {};
+      const onChange = () => emit(readWebState());
+      q.addEventListener("change", onChange);
+      return () => q.removeEventListener("change", onChange);
+    },
+  },
+});