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

package/vendor/@akanjs/native/plugins/accessibility/ios/AccessibilityPlugin.swift

@@ -0,0 +1,92 @@
+import UIKit
+
+/// VoiceOver, Reduce Motion and Dynamic Type from UIAccessibility and UIApplication, the values
+/// react-native/packages/react-native/React/CoreModules/RCTAccessibilityManager.mm reads (:99-106).
+/// - fontScale: the body text size for the content size category / 17 pt (the size at the default
+///   "Large"), as capacitor-plugins/text-zoom/ios/Sources/TextZoomPlugin/TextZoom.swift:5-8 computes
+///   it. RN keeps a fixed table (RCTAccessibilityManager.mm:261-279) that matches for the standard
+///   sizes but not for the accessibility sizes (AX1: RN 1.786, the body font 28 / 17 = 1.647); the
+///   font follows Apple's own ramp, which is also what CSS `font: -apple-system-body` gets.
+/// - change: the three notifications RN observes (:54-97), only while the page listens, reported
+///   when a field really changed (RN filters the same way, :170-181).
+/// - announce: UIAccessibility.post(.announcement), RN :323-363 with its queue / priority attributes:
+///   "polite" queues behind current speech, "assertive" interrupts with high priority (iOS 17).
+///   Posted 0.1 s later, as capacitor-plugins/screen-reader/.../ScreenReaderPlugin.swift:39-43 does:
+///   VoiceOver cuts an announcement off when it starts reading the element that was just tapped.
+/// Arguments arrive decoded by the generated AccessibilityPluginSpec (PL-10); empty text is checked here.
+final class AccessibilityPlugin: AccessibilityPluginSpec {
+    static let id = "accessibility"
+    private static let baseBodySize: Double = 17
+
+    private let context: AkanNativePluginContext
+    private var observers: [any NSObjectProtocol] = []
+    private var last: AccessibilityState?
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+    }
+
+    func getState(_ reply: AkanNativeReply<AccessibilityState>) {
+        reply.resolve(Self.state())
+    }
+
+    func announce(_ args: AccessibilityAnnounceArgs, _ reply: AkanNativeReply<Void>) {
+        let text = args.text
+        guard !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            return reply.reject(.invalidArgs, "text must not be empty")
+        }
+        let priority = args.priority ?? .polite
+        Task {
+            try? await Task.sleep(for: .milliseconds(100))
+            var attributes: [NSAttributedString.Key: Any] = [.accessibilitySpeechQueueAnnouncement: priority == .polite]
+            // iOS 16 has no announcement priority: an assertive announcement only skips the queue.
+            if priority == .assertive, #available(iOS 17.0, *) { attributes[.accessibilitySpeechAnnouncementPriority] = UIAccessibilityPriority.high }
+            UIAccessibility.post(notification: .announcement, argument: NSAttributedString(string: text, attributes: attributes))
+            reply.resolve()
+        }
+    }
+
+    func startListening(_ event: String) {
+        guard event == "change", observers.isEmpty else { return }
+        last = Self.state()
+        let names: [Notification.Name] = [
+            UIAccessibility.voiceOverStatusDidChangeNotification,
+            UIAccessibility.reduceMotionStatusDidChangeNotification,
+            UIContentSizeCategory.didChangeNotification,
+        ]
+        observers = names.map { name in
+            NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in
+                MainActor.assumeIsolated { self?.report() }
+            }
+        }
+    }
+
+    func stopListening(_ event: String) {
+        guard event == "change" else { return }
+        for observer in observers { NotificationCenter.default.removeObserver(observer) }
+        observers = []
+        last = nil
+    }
+
+    private func report() {
+        guard !observers.isEmpty else { return }
+        let next = Self.state()
+        if next == last { return }
+        last = next
+        AccessibilityEvents(context).change(next)
+    }
+
+    private static func state() -> AccessibilityState {
+        AccessibilityState(
+            screenReader: UIAccessibility.isVoiceOverRunning,
+            reduceMotion: UIAccessibility.isReduceMotionEnabled,
+            fontScale: fontScale(UIApplication.shared.preferredContentSizeCategory)
+        )
+    }
+
+    private static func fontScale(_ category: UIContentSizeCategory) -> Double {
+        let traits = UITraitCollection(preferredContentSizeCategory: category)
+        let body = Double(UIFont.preferredFont(forTextStyle: .body, compatibleWith: traits).pointSize)
+        return (body / baseBodySize * 1000).rounded() / 1000
+    }
+}

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

@@ -0,0 +1,21 @@
+{
+  "id": "accessibility",
+  "apiVersion": 1,
+  "methods": ["getState", "announce"],
+  "events": ["change"],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "web",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "AccessibilityPlugin",
+    "frameworks": ["UIKit"]
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.accessibility.AccessibilityPlugin",
+    "methods": ["getState"],
+    "events": ["change"],
+    "web": true
+  }
+}

package/vendor/@akanjs/native/plugins/accessibility/src/announce.ts

@@ -0,0 +1,71 @@
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import type { AnnouncePriority } from "./index.ts";
+
+const PRIORITIES: readonly AnnouncePriority[] = ["polite", "assertive"];
+const HIDDEN =
+  "position:fixed;left:0;top:0;width:1px;height:1px;margin:-1px;padding:0;border:0;overflow:hidden;clip-path:inset(50%);white-space:nowrap";
+const REGISTER_MS = 100;
+const KEEP_MS = 7000;
+
+/** Checks announce()'s options; the iOS plugin checks the same. */
+export function checkAnnounce(options: unknown): { text: string; priority: AnnouncePriority } {
+  if (typeof options !== "object" || options === null) throw new AkanNativeError("INVALID_ARGS", "text is required");
+  const { text, priority } = options as Record<string, unknown>;
+  if (text === undefined || text === null) throw new AkanNativeError("INVALID_ARGS", "text is required");
+  if (typeof text !== "string") throw new AkanNativeError("INVALID_ARGS", "text must be a string");
+  if (text.trim() === "") throw new AkanNativeError("INVALID_ARGS", "text must not be empty");
+  if (priority !== undefined && priority !== null && !(PRIORITIES as readonly unknown[]).includes(priority)) {
+    throw new AkanNativeError("INVALID_ARGS", `priority must be one of ${PRIORITIES.join(", ")}`);
+  }
+  return { text, priority: (priority as AnnouncePriority | null | undefined) ?? "polite" };
+}
+
+const regions = new Map<AnnouncePriority, HTMLElement>();
+
+function topModal(): Element | null {
+  try {
+    const open = document.querySelectorAll("dialog:modal");
+    return open.length > 0 ? open[open.length - 1]! : null;
+  } catch {
+    return null; 
+  }
+}
+
+function region(priority: AnnouncePriority): { el: HTMLElement; fresh: boolean } {
+  const host = topModal() ?? document.body ?? document.documentElement;
+  let el = regions.get(priority);
+  if (el && el.parentNode === host) return { el, fresh: false };
+  if (!el) {
+    el = document.createElement("div");
+    el.setAttribute("aria-live", priority);
+    el.setAttribute("aria-relevant", "additions");
+    el.setAttribute("data-akan-native-announcer", priority);
+    el.style.cssText = HIDDEN;
+    regions.set(priority, el);
+  }
+  host.append(el);
+  return { el, fresh: true };
+}
+
+/** Adds `text` to the live region of `priority`; resolves once it is in the page. */
+export function announceInPage(text: string, priority: AnnouncePriority): Promise<void> {
+  if (typeof document === "undefined")
+    return Promise.reject(new AkanNativeError("UNSUPPORTED", "announcements need a document"));
+  const { el, fresh } = region(priority);
+  const message = document.createElement("div");
+  message.textContent = text;
+  const add = () => {
+    el.append(message);
+    setTimeout(() => message.remove(), KEEP_MS);
+  };
+  if (!fresh) {
+    add();
+    return Promise.resolve();
+  }
+  return new Promise((resolve) =>
+    setTimeout(() => {
+      add();
+      resolve();
+    }, REGISTER_MS),
+  );
+}

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

@@ -0,0 +1,77 @@
+import { createLiveValue, definePlugin, shallowEqual } from "../../../packages/core/src/index.ts";
+import { useLiveValue } from "../../../packages/react/src/index.ts";
+import { readWebState, web } from "./web.ts";
+
+export { checkAnnounce } from "./announce.ts";
+
+export interface AccessibilityState {
+  /**
+   * A screen reader is on: VoiceOver on iOS, a touch-exploration service such as TalkBack on
+   * Android. null where the host cannot tell: browsers and macOS (a page cannot see VoiceOver).
+   */
+  screenReader: boolean | null;
+  /**
+   * The user asked for less motion: Reduce Motion on iOS, "Remove animations" (animation scales
+   * at 0) on Android, `prefers-reduced-motion` on the web and macOS.
+   */
+  reduceMotion: boolean;
+  /**
+   * The user's text size as a factor of the default size (1): iOS Dynamic Type (the body text
+   * size / 17 pt), Android Configuration.fontScale, the browser's default font size / 16 px on the
+   * web and macOS (1 unless the user changed it; iOS browsers always report 1).
+   */
+  fontScale: number;
+}
+
+/** "polite" waits until the screen reader finished speaking, "assertive" interrupts it. */
+export type AnnouncePriority = "polite" | "assertive";
+
+/** Screen reader state and announcements (plugins.md §4.1). */
+export interface AccessibilityApi {
+  getState(): Promise<AccessibilityState>;
+  /**
+   * Makes the running screen reader speak `text` (e.g. "3 results", "Saved"), for changes that
+   * have no focusable element of their own. Resolves once handed over, also when no screen
+   * reader runs (then nothing is spoken). Default priority "polite".
+   * iOS: UIAccessibility announcement. Web, macOS and Android: a live region in the page
+   * (Android's own announcement API is deprecated in API 36); inside a modal <dialog> the region
+   * moves into the dialog, since the rest of the page is inert then.
+   */
+  announce(options: { text: string; priority?: AnnouncePriority }): Promise<void>;
+}
+
+export interface AccessibilityEvents {
+  /** One of the state's fields changed. */
+  change: AccessibilityState;
+}
+
+export const accessibility = definePlugin<AccessibilityApi, AccessibilityEvents>("accessibility", {
+  methods: ["getState", "announce"],
+  events: ["change"],
+  web,
+});
+
+const current = createLiveValue<AccessibilityState>(
+  readWebState(),
+  (set) => {
+    let live = true;
+    const stop = accessibility.listen("change", set);
+    accessibility
+      .getState()
+      .then((state) => live && set(state))
+      .catch(() => {});
+    return () => {
+      live = false;
+      stop();
+    };
+  },
+  shallowEqual,
+);
+
+/**
+ * The current accessibility state. Re-renders on every change. Until the host answered, it is
+ * the page's own reading (screenReader null, reduceMotion from `prefers-reduced-motion`).
+ */
+export function useAccessibility(): AccessibilityState {
+  return useLiveValue(current);
+}

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

@@ -0,0 +1,52 @@
+import { defineWebPlugin, shallowEqual } from "../../../packages/core/src/index.ts";
+import { announceInPage, checkAnnounce } from "./announce.ts";
+import type { AccessibilityApi, AccessibilityEvents, AccessibilityState } from "./index.ts";
+
+function motionQuery(): MediaQueryList | null {
+  return typeof matchMedia === "function" ? matchMedia("(prefers-reduced-motion: reduce)") : null;
+}
+
+export function readFontScale(): number {
+  if (typeof document === "undefined" || typeof getComputedStyle !== "function") return 1;
+  const probe = document.createElement("div");
+  probe.style.cssText = "position:absolute;visibility:hidden;width:0;height:0;overflow:hidden;font-size:medium";
+  (document.body ?? document.documentElement).append(probe);
+  const px = Number.parseFloat(getComputedStyle(probe).fontSize);
+  probe.remove();
+  return Number.isFinite(px) && px > 0 ? Math.round((px / 16) * 1000) / 1000 : 1;
+}
+
+export function readWebState(): AccessibilityState {
+  return { screenReader: null, reduceMotion: motionQuery()?.matches ?? false, fontScale: readFontScale() };
+}
+
+export const web = defineWebPlugin<AccessibilityApi, AccessibilityEvents>({
+  methods: {
+    getState: async () => readWebState(),
+    announce(options) {
+      const { text, priority } = checkAnnounce(options);
+      return announceInPage(text, priority);
+    },
+  },
+  events: {
+    change(emit) {
+      let last = readWebState();
+      const check = () => {
+        const next = readWebState();
+        if (shallowEqual(next, last)) return;
+        last = next;
+        emit(next);
+      };
+      const onVisible = () => {
+        if (document.visibilityState === "visible") check();
+      };
+      const q = motionQuery();
+      q?.addEventListener("change", check);
+      if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisible);
+      return () => {
+        q?.removeEventListener("change", check);
+        if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisible);
+      };
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/app/android/AppPlugin.kt

@@ -0,0 +1,72 @@
+package com.akanjs.plugins.app
+
+import com.akanjs.runtime.AkanNativeActivity
+import com.akanjs.runtime.AkanNativeLinks
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * App info, deep links (ACTION_VIEW intents, plugins.md S4) and the back button (S3).
+ * - Links come from the shell's AkanNativeLinks (App scope): the launch URL is the process's and never
+ *   changes; every link, the launch URL included, is delivered once as urlOpen, kept until the page
+ *   listens (C2). react-native IntentModule / capacitor-plugins/app only take ACTION_VIEW intents too.
+ * - backButton: while the page listens, the shell hands back gestures to us instead of going back
+ *   in the WebView history (capacitor-plugins/app AppPlugin.java does the same with AndroidX).
+ * The result and event types come from the generated AppPluginSpec (PL-10).
+ */
+class AppPlugin(private val context: AkanNativePluginContext) : AppPluginSpec {
+    private val events = AppEvents(context)
+    private var linksListening = false
+
+    override fun getInfo(reply: AkanNativeReply<AppInfoResult>) {
+        val activity = context.activity
+        val info = activity.packageManager.getPackageInfo(activity.packageName, 0)
+        reply.resolve(
+            AppInfoResult(
+                id = activity.packageName,
+                name = activity.applicationInfo.loadLabel(activity.packageManager).toString(),
+                version = info.versionName ?: "",
+                build = info.longVersionCode.toDouble(),
+            ),
+        )
+    }
+
+    override fun getLaunchUrl(reply: AkanNativeReply<AppGetLaunchUrlResult>) = reply.resolve(AppGetLaunchUrlResult(url = AkanNativeLinks.launchUrl))
+
+    override fun exit(reply: AkanNativeVoidReply) {
+        reply.resolve()
+        context.activity.finishAndRemoveTask()
+    }
+
+    override fun minimize(reply: AkanNativeVoidReply) {
+        context.activity.moveTaskToBack(true)
+        reply.resolve()
+    }
+
+    override fun startListening(event: String) {
+        when (event) {
+            "urlOpen" -> {
+                linksListening = true
+                AkanNativeLinks.listen(this, context.activity) { url ->
+                    if (linksListening) events.urlOpen(AppUrlOpenEvent(url = url))
+                    linksListening
+                }
+            }
+            "backButton" -> context.setBackInterceptor {
+                val canGoBack = (context.activity as? AkanNativeActivity)?.canGoBack() ?: false
+                events.backButton(AppBackButtonEvent(canGoBack = canGoBack))
+            }
+        }
+    }
+
+    override fun stopListening(event: String) {
+        when (event) {
+            "urlOpen" -> {
+                linksListening = false
+                AkanNativeLinks.unlisten(this)
+            }
+            "backButton" -> context.setBackInterceptor(null)
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/app/ios/AppPlugin.swift

@@ -0,0 +1,52 @@
+import UIKit
+
+/// App info from the bundle and deep links from the scene (AkanNativeLinks, plugins.md S4).
+/// iOS apps must not quit or minimize themselves: exit/minimize are UNSUPPORTED
+/// (capacitor-plugins/app does the same).
+/// The result and event types come from the generated AppPluginSpec (PL-10).
+final class AppPlugin: AppPluginSpec {
+    static let id = "app"
+    private let context: AkanNativePluginContext
+    private var subscription: UUID?
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+    }
+
+    func getInfo(_ reply: AkanNativeReply<AppInfoResult>) {
+        let info = Bundle.main.infoDictionary ?? [:]
+        reply.resolve(AppInfoResult(
+            id: Bundle.main.bundleIdentifier ?? "",
+            name: info["CFBundleDisplayName"] as? String ?? info["CFBundleName"] as? String ?? "",
+            version: info["CFBundleShortVersionString"] as? String ?? "",
+            build: Double(Int(info["CFBundleVersion"] as? String ?? "") ?? 1)
+        ))
+    }
+
+    func getLaunchUrl(_ reply: AkanNativeReply<AppGetLaunchUrlResult>) {
+        reply.resolve(AppGetLaunchUrlResult(url: AkanNativeLinks.shared.launchURL?.absoluteString))
+    }
+
+    func exit(_ reply: AkanNativeReply<Void>) {
+        reply.reject(.unsupported, "iOS apps cannot exit themselves")
+    }
+
+    func minimize(_ reply: AkanNativeReply<Void>) {
+        reply.reject(.unsupported, "iOS apps cannot minimize themselves")
+    }
+
+    func startListening(_ event: String) {
+        guard event == "urlOpen", subscription == nil else { return }
+        subscription = AkanNativeLinks.shared.listen(owner: context.owner) { [weak self] url in
+            guard let self else { return false }
+            AppEvents(self.context).urlOpen(AppUrlOpenEvent(url: url.absoluteString))
+            return true
+        }
+    }
+
+    func stopListening(_ event: String) {
+        guard event == "urlOpen", let subscription else { return }
+        AkanNativeLinks.shared.unlisten(subscription)
+        self.subscription = nil
+    }
+}

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

@@ -0,0 +1,21 @@
+{
+  "id": "app",
+  "apiVersion": 1,
+  "methods": ["getInfo", "getLaunchUrl", "exit", "minimize", "answerBeforeQuit"],
+  "events": ["urlOpen", "backButton", "beforeQuit"],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "./src/desktop.ts",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "AppPlugin",
+    "methods": ["getInfo", "getLaunchUrl", "exit", "minimize"],
+    "events": ["urlOpen", "backButton"]
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.app.AppPlugin",
+    "methods": ["getInfo", "getLaunchUrl", "exit", "minimize"],
+    "events": ["urlOpen", "backButton"]
+  }
+}

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

@@ -0,0 +1,64 @@
+
+
+import { RetainedEvents } from "../../../packages/core/src/kernel.ts";
+import {
+  createPageVeto,
+  type DesktopContext,
+  defineDesktopPlugin,
+  linkClaimed,
+  type QuitReason,
+} from "../../../packages/desktop/src/plugin.ts";
+import type { AppApi, AppEvents } from "./index.ts";
+
+const quitVeto = createPageVeto<{ reason: QuitReason }>();
+
+let launchUrl: string | null = null;
+let launched = false;
+/** Every link, the launch link too, retained until a page listens (the shared C2 rule, kernel RetainedEvents). */
+const links = new RetainedEvents<string>();
+
+export default defineDesktopPlugin<AppApi, AppEvents>({
+  id: "app",
+  setup(ctx: DesktopContext) {
+    ctx.onBeforeQuit(({ reason }) => quitVeto.ask({ reason }));
+    ctx.onNativeEvent("opened", (event) => {
+      for (const url of (event.urls as string[] | undefined) ?? []) {
+        
+        if (linkClaimed(url)) continue;
+
+        if (!launched) {
+          launched = true;
+          launchUrl = url;
+        }
+        links.emit(url, true);
+      }
+    });
+  },
+  methods: {
+    getInfo: (_args, ctx) => ({
+      id: ctx.app.id,
+      name: ctx.app.name,
+      version: ctx.app.version,
+      build: ctx.app.build ?? 1,
+    }),
+    getLaunchUrl: () => ({ url: launchUrl }),
+    exit: (_args, ctx) => {
+      setTimeout(() => ctx.quit(0), 50); 
+    },
+    answerBeforeQuit: (args, ctx) => quitVeto.answer(args, ctx.window),
+    minimize: async (_args, ctx) => {
+      await ctx.shell("window.minimize");
+    },
+  },
+  events: {
+    urlOpen(send) {
+      launched = true;
+
+      links.listen("pages", (url) => (send({ url }, "focused")?.length ?? 1) > 0);
+      return () => links.unlisten("pages");
+    },
+    beforeQuit: (send, ctx) => quitVeto.source(send, ctx),
+    
+    backButton: () => () => {},
+  },
+});

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

@@ -0,0 +1,77 @@
+
+
+import * as React from "react";
+import { definePlugin, type VetoHandler, vetoable } from "../../../packages/core/src/index.ts";
+import { usePluginEvent } from "../../../packages/react/src/index.ts";
+import { web } from "./web.ts";
+
+/**
+ * Why the app is about to quit: "user" (Cmd+Q, Dock menu, AppleScript), "session" (logout,
+ * restart, shutdown; preventing it cancels the logout), "lastWindowClosed" (the window was closed).
+ */
+export type QuitReason = "user" | "session" | "lastWindowClosed";
+
+export interface AppInfoResult {
+  id: string;
+  name: string;
+  version: string;
+  build: number;
+}
+
+export interface AppApi {
+  getInfo(): Promise<AppInfoResult>;
+  /** The URL that started the app (deep link), or null. */
+  getLaunchUrl(): Promise<{ url: string | null }>;
+  /** Ends the app without asking onBeforeQuit handlers. Android and desktop only (iOS apps must not quit themselves). */
+  exit(): Promise<void>;
+  /** Sends the app to the background (Android) or minimizes its window (desktop). */
+  minimize(): Promise<void>;
+  /** Internal: the page's answer to a beforeQuit event. Use onBeforeQuit(). */
+  answerBeforeQuit(args: { id: number; allow?: boolean }): Promise<void>;
+}
+
+export interface AppEvents {
+  /** A deep link arrived while running. URLs that arrive before anyone listens are delivered to the first listener. */
+  urlOpen: { url: string };
+  /** Android back gesture/button. While anything listens, back no longer walks the WebView history by itself. */
+  backButton: { canGoBack: boolean };
+  /** Internal: the app is about to quit (desktop). Use onBeforeQuit(). */
+  beforeQuit: { id: number; reason: QuitReason };
+}
+
+export const app = definePlugin<AppApi, AppEvents>("app", {
+  methods: ["getInfo", "getLaunchUrl", "exit", "minimize", "answerBeforeQuit"],
+  events: ["urlOpen", "backButton", "beforeQuit"],
+  web,
+});
+
+/** Calls `handler` for every deep link while mounted. */
+export function useUrlOpen(handler: (url: string) => void): void {
+  usePluginEvent(app, "urlOpen", ({ url }) => handler(url));
+}
+
+/**
+ * Takes over the Android back button while mounted. The handler decides: e.g. close a dialog,
+ * `history.back()` when `canGoBack`, or `app.exit()` at the root.
+ */
+export function useBackButton(handler: (event: { canGoBack: boolean }) => void): void {
+  usePluginEvent(app, "backButton", handler);
+}
+
+/**
+ * Runs `handler` before the app quits (desktop: Cmd+Q, Dock menu, logout, closing the window).
+ * Call `event.preventDefault()` to keep running, e.g. after asking to save; `event.reason` tells
+ * why. app.exit() does not ask. Elsewhere it never fires (`app.eventImplementation("beforeQuit")`
+ * tells). Returns an unregister function.
+ */
+export const onBeforeQuit: (handler: VetoHandler<{ reason: QuitReason }>) => () => void = vetoable(
+  (listener) => app.listen("beforeQuit", listener),
+  (args) => app.answerBeforeQuit(args),
+);
+
+/** onBeforeQuit while mounted; always calls the latest handler. */
+export function useBeforeQuit(handler: VetoHandler<{ reason: QuitReason }>): void {
+  const latest = React.useRef(handler);
+  latest.current = handler;
+  React.useEffect(() => onBeforeQuit((event) => latest.current(event)), []);
+}

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

@@ -0,0 +1,12 @@
+import { AkanNativeError, app as appInfo, defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { AppApi, AppEvents } from "./index.ts";
+
+export const web = defineWebPlugin<AppApi, AppEvents>({
+  methods: {
+    async getInfo() {
+      if (!appInfo) throw new AkanNativeError("UNSUPPORTED", "no app info (the page was not built by akan-native)");
+      return { id: appInfo.id, name: appInfo.name, version: appInfo.version, build: appInfo.build ?? 1 };
+    },
+    getLaunchUrl: async () => ({ url: null }),
+  },
+});

package/vendor/@akanjs/native/plugins/app-state/android/AppStatePlugin.kt

@@ -0,0 +1,54 @@
+package com.akanjs.plugins.appstate
+
+import android.app.Activity
+import android.app.Application
+import android.os.Bundle
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+
+/**
+ * Activity lifecycle → active / inactive / background.
+ * react-native AppStateModule maps pause straight to background; here a paused but
+ * still visible activity (split screen, system dialog) is "inactive" and only onStop is "background".
+ * The result and event types come from the generated AppStatePluginSpec (PL-10).
+ */
+class AppStatePlugin(private val context: AkanNativePluginContext) : AppStatePluginSpec {
+    private var state = AppStateValue.ACTIVE // the shell creates plugins while the activity is being resumed
+    private var listening = false
+    private val events = AppStateEvents(context)
+
+    private val callbacks = object : Application.ActivityLifecycleCallbacks {
+        override fun onActivityResumed(activity: Activity) = update(AppStateValue.ACTIVE)
+        override fun onActivityPaused(activity: Activity) = update(AppStateValue.INACTIVE)
+        override fun onActivityStarted(activity: Activity) = update(AppStateValue.INACTIVE)
+        override fun onActivityStopped(activity: Activity) = update(AppStateValue.BACKGROUND)
+        override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
+        override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}
+        override fun onActivityDestroyed(activity: Activity) {}
+    }
+
+    init {
+        // Activity-scoped registration (API 29+): only our activity's transitions arrive.
+        context.activity.registerActivityLifecycleCallbacks(callbacks)
+    }
+
+    private fun update(next: AppStateValue) {
+        if (next == state) return
+        state = next
+        if (listening) events.change(AppStateChangeEvent(state = next))
+    }
+
+    override fun getState(reply: AkanNativeReply<AppStateGetStateResult>) = reply.resolve(AppStateGetStateResult(state = state))
+
+    override fun startListening(event: String) {
+        if (event == "change") listening = true
+    }
+
+    override fun stopListening(event: String) {
+        if (event == "change") listening = false
+    }
+
+    override fun destroy() {
+        context.activity.unregisterActivityLifecycleCallbacks(callbacks)
+    }
+}