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

package/vendor/@akanjs/native/plugins/opener/android/OpenerPlugin.kt

@@ -0,0 +1,81 @@
+package com.akanjs.plugins.opener
+
+import android.content.ActivityNotFoundException
+import android.content.Intent
+import android.net.Uri
+import android.provider.Settings
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativeExternal
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * ACTION_VIEW for http, https, mailto and tel (src/url.ts and the iOS plugin check the same list).
+ * - normalizeScheme() first: intent filters match the scheme case-sensitively, and a new task for
+ *   the other app (react-native IntentModule.kt:124, :255-279).
+ * - CATEGORY_BROWSABLE as for links the page follows (shell SH-4): only activities that accept
+ *   links from a browser can be started this way.
+ * - No handler throws ActivityNotFoundException: NOT_FOUND. startActivity needs no package
+ *   visibility, so this works without <queries>.
+ * - openSettings: ACTION_APPLICATION_DETAILS_SETTINGS for this package (IntentModule.kt:169-189).
+ * - canOpenUrl is not in native-plugin.json: since Android 11 resolveActivity() sees other apps only if
+ *   the manifest lists them in <queries> (capacitor-plugins/app-launcher/README.md), which plugin
+ *   manifests cannot add yet. canOpen() below is what it will run once they can (the generated
+ *   OpenerPluginSpec then declares it too).
+ * Arguments arrive decoded by the generated OpenerPluginSpec (PL-10); the URL checks stay here.
+ */
+class OpenerPlugin(private val context: AkanNativePluginContext) : OpenerPluginSpec {
+    override fun openUrl(args: OpenerOpenUrlArgs, reply: AkanNativeVoidReply) {
+        val uri = uri(args.url, reply) ?: return
+        // PL-11 scopes { url }: matched on the URL normalized like the JS URL class does.
+        if (reply.call.inScope(mapOf("url" to normalized(uri)), urlFields = setOf("url"), what = uri.toString())) start(reply, view(uri))
+    }
+
+    override fun openSettings(reply: AkanNativeVoidReply) = start(
+        reply,
+        Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", context.activity.packageName, null))
+            .addCategory(Intent.CATEGORY_DEFAULT)
+            .addFlags(Intent.FLAG_ACTIVITY_NO_HISTORY or Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS),
+    )
+
+    @Suppress("unused") // canOpenUrl, once the manifest can declare <queries> (see above)
+    private fun canOpen(uri: Uri): Boolean = view(uri).resolveActivity(context.activity.packageManager) != null
+
+    private fun view(uri: Uri) = Intent(Intent.ACTION_VIEW, uri).addCategory(Intent.CATEGORY_BROWSABLE)
+
+    private fun start(reply: AkanNativeVoidReply, intent: Intent) {
+        if (!AkanNativeExternal.allowed()) return reply.reject(AkanNativeErrorCode.NOT_ALLOWED, "at most one URL per second leaves the app; try again later")
+        try {
+            context.activity.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
+            reply.resolve()
+        } catch (e: ActivityNotFoundException) {
+            reply.reject(AkanNativeErrorCode.NOT_FOUND, "no app can open ${intent.data}")
+        } catch (e: SecurityException) {
+            reply.reject(AkanNativeErrorCode.PERMISSION_DENIED, e.message ?: "not allowed to open ${intent.data}")
+        }
+    }
+
+    /** Lowercase scheme and host, "/" as the path of a bare http(s) host: the same text `new URL(u).href` gives. */
+    private fun normalized(uri: Uri): String {
+        var b = uri.buildUpon().scheme(uri.scheme?.lowercase())
+        uri.encodedAuthority?.let { b = b.encodedAuthority(it.lowercase()) }
+        if (uri.scheme?.startsWith("http") == true && uri.encodedPath.isNullOrEmpty()) b = b.encodedPath("/")
+        return b.build().toString()
+    }
+
+    /** The checked URI with a normalized scheme, or null after rejecting the call. */
+    private fun uri(text: String, reply: AkanNativeReply<*>): Uri? {
+        val uri = if (text.isEmpty()) null else Uri.parse(text).normalizeScheme()
+        val scheme = uri?.scheme
+        val problem = when {
+            uri == null || scheme == null || !uri.isAbsolute -> "url must be an absolute URL"
+            scheme !in AkanNativeExternal.schemes -> "only ${AkanNativeExternal.schemes.joinToString(", ")} URLs can be opened (got $scheme:)"
+            scheme.startsWith("http") && uri.host.isNullOrEmpty() -> "$text has no host"
+            else -> return uri
+        }
+        reply.reject(AkanNativeErrorCode.INVALID_ARGS, problem)
+        return null
+    }
+
+}

package/vendor/@akanjs/native/plugins/opener/ios/OpenerPlugin.swift

@@ -0,0 +1,83 @@
+import UIKit
+
+/// UIApplication.open for http, https, mailto and tel (the default set of
+/// tauri-plugins-workspace/plugins/opener/permissions/allow-default-urls.toml; src/url.ts checks the same).
+/// - Opens only while the scene is foregroundActive, like the shell's external links (SH-4,
+///   capacitor/ios/Capacitor/Capacitor/WebViewDelegationHandler.swift:67-125).
+/// - The completion reports whether an app took the URL: false (tel: on a simulator or iPad) is NOT_FOUND.
+/// - canOpenURL answers false for schemes missing from LSApplicationQueriesSchemes
+///   (capacitor-plugins/app-launcher/src/definitions.ts). That list is for other apps' custom
+///   schemes, which this plugin refuses anyway; http(s)/mailto/tel are expected to work without an
+///   entry (not yet confirmed on the simulator: see the self-test).
+/// Arguments arrive decoded by the generated OpenerPluginSpec (PL-10); the URL checks stay here.
+final class OpenerPlugin: OpenerPluginSpec {
+    static let id = "opener"
+    /// The shell's external list: http, https, mailto, tel and security.shell.externalSchemes (L0).
+    private static var schemes: [String] { AkanNativeExternal.schemes }
+    private let context: AkanNativePluginContext
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+    }
+
+    func openUrl(_ args: OpenerOpenUrlArgs, _ reply: AkanNativeReply<Void>) {
+        guard let url = url(args.url, reply) else { return }
+        // PL-11 scopes { url }: matched on the URL normalized like the JS URL class does.
+        guard reply.call.inScope(["url": Self.normalized(url)], urlFields: ["url"], what: url.absoluteString) else { return }
+        open(url, reply)
+    }
+
+    func canOpenUrl(_ args: OpenerCanOpenUrlArgs, _ reply: AkanNativeReply<OpenerCanOpenUrlResult>) {
+        guard let url = url(args.url, reply) else { return }
+        reply.resolve(OpenerCanOpenUrlResult(value: UIApplication.shared.canOpenURL(url)))
+    }
+
+    func openSettings(_ reply: AkanNativeReply<Void>) {
+        open(URL(string: UIApplication.openSettingsURLString)!, reply)
+    }
+
+    private func open(_ url: URL, _ reply: AkanNativeReply<Void>) {
+        guard context.windowScene?.activationState == .foregroundActive else {
+            return reply.reject(.permissionDenied, "URLs can be opened only while the app is in the foreground")
+        }
+        guard AkanNativeExternal.allowed() else { return reply.reject(.notAllowed, "at most one URL per second leaves the app; try again later") }
+        UIApplication.shared.open(url, options: [:]) { opened in
+            if opened {
+                reply.resolve()
+            } else {
+                reply.reject(.notFound, "no app can open \(url.absoluteString)")
+            }
+        }
+    }
+
+    /// Lowercase scheme and host, "/" as the path of a bare http(s) host: the same text `new URL(u).href` gives.
+    static func normalized(_ url: URL) -> String {
+        guard var parts = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return url.absoluteString }
+        parts.scheme = parts.scheme?.lowercased()
+        parts.host = parts.host?.lowercased()
+        if parts.scheme?.hasPrefix("http") == true, parts.path.isEmpty { parts.path = "/" }
+        return parts.string ?? url.absoluteString
+    }
+
+    /// The checked URL with a lowercase scheme, or nil after rejecting the call.
+    private func url<T>(_ text: String, _ reply: AkanNativeReply<T>) -> URL? {
+        guard !text.isEmpty, var parts = URLComponents(string: text), let scheme = parts.scheme?.lowercased() else {
+            reply.reject(.invalidArgs, "url must be an absolute URL")
+            return nil
+        }
+        guard Self.schemes.contains(scheme) else {
+            reply.reject(.invalidArgs, "only \(Self.schemes.joined(separator: ", ")) URLs can be opened (got \(scheme):)")
+            return nil
+        }
+        if scheme.hasPrefix("http"), parts.host?.isEmpty ?? true {
+            reply.reject(.invalidArgs, "\(text) has no host")
+            return nil
+        }
+        parts.scheme = scheme
+        guard let url = parts.url else {
+            reply.reject(.invalidArgs, "url must be an absolute URL")
+            return nil
+        }
+        return url
+    }
+}

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

@@ -0,0 +1,25 @@
+{
+  "id": "opener",
+  "apiVersion": 1,
+  "methods": ["openUrl", "canOpenUrl", "openSettings"],
+  "events": [],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "./src/desktop.ts",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "OpenerPlugin"
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.opener.OpenerPlugin",
+    "methods": ["openUrl", "openSettings"]
+  },
+  "scope": {
+    "description": "Which URLs openUrl may open (canOpenUrl and openSettings are not scoped).",
+    "fields": {
+      "url": "URL pattern: scheme, host, port and path compared separately (* in the host spans dots, in the path crosses /; no port = the default port in allow and any port in deny, :* = any port, no path = any path; query ignored), on the normalized URL"
+    },
+    "urlFields": ["url"]
+  }
+}

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

@@ -0,0 +1,88 @@
+
+
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { type DesktopContext, defineDesktopPlugin, externalOpenAllowed } from "../../../packages/desktop/src/plugin.ts";
+import type { OpenerApi } from "./index.ts";
+import { checkUrl, checkUrlScope } from "./url.ts";
+
+export interface Command {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export type Runner = (argv: string[]) => Promise<Command>;
+
+const spawnRunner: Runner = async (argv) => {
+  const proc = Bun.spawn(argv, { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, stdout, stderr };
+};
+
+const LOOKUP = `function run(argv) {
+  ObjC.import("AppKit");
+  var url = $.NSURL.URLWithString(argv[0]);
+  if (url.isNil()) return "";
+  var app = $.NSWorkspace.sharedWorkspace.URLForApplicationToOpenURL(url);
+  return app.isNil() ? "" : app.path.js;
+}`;
+
+const SETTINGS = "x-apple.systempreferences:com.apple.preference.security";
+/** Settings › Privacy & security (ms-settings URIs: learn.microsoft.com/windows/apps/develop/launch/launch-settings-app). */
+const WINDOWS_SETTINGS = "ms-settings:privacy";
+
+async function open(run: Runner, url: string): Promise<void> {
+  const { code, stderr } = await run(["/usr/bin/open", "-u", url]);
+  if (code === 0) return;
+  if (/-10814|No application knows/.test(stderr)) throw new AkanNativeError("NOT_FOUND", `no app can open ${url}`);
+  throw new AkanNativeError("INTERNAL", `open failed (${code}): ${stderr.trim()}`);
+}
+
+/**
+ * `run` is replaceable so tests can check the commands without opening anything, `platform` so
+ * they can check the Windows and Linux paths (shell ops) on any OS.
+ */
+export function createDesktopOpener(run: Runner = spawnRunner, platform: NodeJS.Platform = process.platform) {
+  const mac = platform === "darwin";
+  const shellOpen = async (ctx: DesktopContext, url: string) => {
+    await ctx.shell("shell.open", { url });
+  };
+  return defineDesktopPlugin<OpenerApi>({
+    id: "opener",
+    methods: {
+      async openUrl(args, ctx) {
+        const url = checkUrl(args?.url, ctx.externalSchemes);
+        checkUrlScope(ctx.scope, url);
+        if (!externalOpenAllowed())
+          throw new AkanNativeError("NOT_ALLOWED", "at most one URL per second leaves the app; try again later");
+        if (mac) await open(run, url.href);
+        else await shellOpen(ctx, url.href);
+      },
+      async canOpenUrl(args, ctx) {
+        const url = checkUrl(args?.url, ctx.externalSchemes);
+        if (!mac)
+          return {
+            value: ((await ctx.shell("shell.handler", { url: url.href })) as { app: string | null }).app !== null,
+          };
+        const { code, stdout, stderr } = await run(["/usr/bin/osascript", "-l", "JavaScript", "-e", LOOKUP, url.href]);
+        if (code !== 0)
+          throw new AkanNativeError("INTERNAL", `LaunchServices lookup failed (${code}): ${stderr.trim()}`);
+        return { value: stdout.trim().length > 0 };
+      },
+      async openSettings(_args, ctx) {
+        if (!externalOpenAllowed())
+          throw new AkanNativeError("NOT_ALLOWED", "at most one URL per second leaves the app; try again later");
+        if (mac) await open(run, SETTINGS);
+        else if (platform === "win32") await shellOpen(ctx, WINDOWS_SETTINGS);
+        else
+          throw new AkanNativeError("UNSUPPORTED", "Linux desktops have no common settings page for app permissions");
+      },
+    },
+  });
+}
+
+export default createDesktopOpener();

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

@@ -0,0 +1,35 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+import { web } from "./web.ts";
+
+export { OPENER_SCHEMES } from "./url.ts";
+
+/**
+ * Opens URLs in other apps (browser, mail, phone) and the app's system settings. This is the
+ * explicit API; links the page follows leave the WebView on their own (shell SH-4).
+ * Only http, https, mailto and tel URLs are accepted; others reject INVALID_ARGS.
+ */
+export interface OpenerApi {
+  /**
+   * Opens the URL with the app the system picks. Rejects NOT_FOUND when no app handles it (e.g. tel:
+   * on a simulator), PERMISSION_DENIED on iOS while the app is not in the foreground and on the web
+   * when the browser blocked the new window (call it from a click).
+   */
+  openUrl(args: { url: string }): Promise<void>;
+  /**
+   * Whether an installed app handles the URL. iOS, macOS, Windows and Linux ask the system (tel: is
+   * false on iPad and the simulator, and wherever no phone app is registered); the web cannot tell
+   * and answers true. Not available on Android, where apps are
+   * invisible to the query unless the manifest lists them in <queries>.
+   */
+  canOpenUrl(args: { url: string }): Promise<{ value: boolean }>;
+  /**
+   * Opens this app's page in Settings (iOS, Android), Privacy & Security in System Settings (macOS)
+   * or Settings › Privacy & security (Windows). UNSUPPORTED on Linux, whose desktops have no common page.
+   */
+  openSettings(): Promise<void>;
+}
+
+export const opener = definePlugin<OpenerApi>("opener", {
+  methods: ["openUrl", "canOpenUrl", "openSettings"],
+  web,
+});

package/vendor/@akanjs/native/plugins/opener/src/url.ts

@@ -0,0 +1,39 @@
+import { EXTERNAL_SCHEMES } from "../../../packages/core/src/contract.ts";
+import { AkanNativeError, type CallScope, scopePermits } from "../../../packages/core/src/index.ts";
+
+/**
+ * Schemes the opener hands to the system by default: the shell's external list (contract.json;
+ * tauri-plugins-workspace/plugins/opener allows the same, permissions/allow-default-urls.toml). An
+ * app adds others with security.shell.externalSchemes. Anything else (file:, javascript:, other
+ * apps' schemes) is INVALID_ARGS on every platform; the native implementations check the same list.
+ */
+export const OPENER_SCHEMES = EXTERNAL_SCHEMES;
+
+/** Parses and checks a URL for openUrl/canOpenUrl. Scheme case is normalized by URL (as Android normalizeScheme). */
+export function checkUrl(url: unknown, schemes: readonly string[] = OPENER_SCHEMES): URL {
+  if (typeof url !== "string" || url.length === 0)
+    throw new AkanNativeError("INVALID_ARGS", "url must be a non-empty string");
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new AkanNativeError("INVALID_ARGS", `${url} is not an absolute URL`);
+  }
+  const scheme = parsed.protocol.slice(0, -1);
+  if (!schemes.includes(scheme)) {
+    throw new AkanNativeError("INVALID_ARGS", `only ${schemes.join(", ")} URLs can be opened (got ${scheme}:)`);
+  }
+  if ((scheme === "http" || scheme === "https") && !parsed.hostname)
+    throw new AkanNativeError("INVALID_ARGS", `${url} has no host`);
+  return parsed;
+}
+
+/**
+ * PL-11: the app's capabilities may limit openUrl to scopes { url } (URL patterns, urlMatch in
+ * @akanjs/native/core), matched against the normalized URL, e.g. { url: "https://*.example.com/*" }.
+ * Throws NOT_ALLOWED outside the call's scope.
+ */
+export function checkUrlScope(scope: CallScope | undefined, url: URL): void {
+  if (!scopePermits(scope, { url: url.href }, [], ["url"]))
+    throw new AkanNativeError("NOT_ALLOWED", `${url.href} is outside the app's capabilities`);
+}

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

@@ -0,0 +1,33 @@
+import { AkanNativeError, defineWebPlugin, type WebCallContext } from "../../../packages/core/src/index.ts";
+import type { OpenerApi } from "./index.ts";
+import { checkUrl, checkUrlScope } from "./url.ts";
+
+export const web = defineWebPlugin<OpenerApi>({
+  methods: {
+    openUrl(args, ctx?: WebCallContext) {
+      const url = checkUrl(args?.url);
+      checkUrlScope(ctx?.scope, url);
+      if (url.protocol === "http:" || url.protocol === "https:") {
+        
+        const opened = window.open(url.href, "_blank");
+        if (!opened)
+          throw new AkanNativeError(
+            "PERMISSION_DENIED",
+            "the browser blocked the new window (call openUrl from a click)",
+          );
+        try {
+          opened.opener = null; 
+        } catch {
+        }
+      } else {
+        window.location.href = url.href;
+      }
+      return Promise.resolve();
+    },
+    
+    canOpenUrl: async (args) => {
+      checkUrl(args?.url);
+      return { value: true };
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/preferences/android/PreferencesPlugin.kt

@@ -0,0 +1,44 @@
+package com.akanjs.plugins.preferences
+
+import android.content.Context
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * SharedPreferences in its own file, written with apply() (as capacitor-plugins/preferences does).
+ * Arguments arrive decoded and checked by the generated PreferencesPluginSpec (PL-10).
+ */
+class PreferencesPlugin(context: AkanNativePluginContext) : PreferencesPluginSpec {
+    private val prefs = context.activity.getSharedPreferences("akan-native.preferences", Context.MODE_PRIVATE)
+
+    override fun get(args: PreferencesGetArgs, reply: AkanNativeReply<PreferencesGetResult>) {
+        if (valid(args.key, reply)) reply.resolve(PreferencesGetResult(value = prefs.getString(args.key, null)))
+    }
+
+    override fun set(args: PreferencesSetArgs, reply: AkanNativeVoidReply) {
+        if (!valid(args.key, reply)) return
+        prefs.edit().putString(args.key, args.value).apply()
+        reply.resolve()
+    }
+
+    override fun remove(args: PreferencesRemoveArgs, reply: AkanNativeVoidReply) {
+        if (!valid(args.key, reply)) return
+        prefs.edit().remove(args.key).apply()
+        reply.resolve()
+    }
+
+    override fun keys(reply: AkanNativeReply<PreferencesKeysResult>) = reply.resolve(PreferencesKeysResult(keys = prefs.all.keys.sorted()))
+
+    override fun clear(reply: AkanNativeVoidReply) {
+        prefs.edit().clear().apply()
+        reply.resolve()
+    }
+
+    private fun valid(key: String, reply: AkanNativeReply<*>): Boolean {
+        if (key.isNotEmpty()) return true
+        reply.reject(AkanNativeErrorCode.INVALID_ARGS, "key must be a non-empty string")
+        return false
+    }
+}

package/vendor/@akanjs/native/plugins/preferences/ios/PreferencesPlugin.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+/// UserDefaults in a dedicated suite (Library/Preferences/akan-native.preferences.plist).
+/// capacitor-plugins/preferences uses UserDefaults.standard with a key prefix because .standard
+/// also holds system keys; a separate suite keeps keys() and clear() exact. The suite name must
+/// not be the bundle id (that is the .standard domain).
+/// Arguments arrive decoded and checked by the generated PreferencesPluginSpec (PL-10).
+final class PreferencesPlugin: PreferencesPluginSpec {
+    static let id = "preferences"
+    private static let suite = "akan-native.preferences"
+    private let defaults = UserDefaults(suiteName: PreferencesPlugin.suite)!
+
+    init(context: AkanNativePluginContext) {}
+
+    func get(_ args: PreferencesGetArgs, _ reply: AkanNativeReply<PreferencesGetResult>) {
+        guard Self.valid(args.key, reply) else { return }
+        reply.resolve(PreferencesGetResult(value: defaults.string(forKey: args.key)))
+    }
+
+    func set(_ args: PreferencesSetArgs, _ reply: AkanNativeReply<Void>) {
+        guard Self.valid(args.key, reply) else { return }
+        defaults.set(args.value, forKey: args.key)
+        reply.resolve()
+    }
+
+    func remove(_ args: PreferencesRemoveArgs, _ reply: AkanNativeReply<Void>) {
+        guard Self.valid(args.key, reply) else { return }
+        defaults.removeObject(forKey: args.key)
+        reply.resolve()
+    }
+
+    func keys(_ reply: AkanNativeReply<PreferencesKeysResult>) {
+        let keys = defaults.persistentDomain(forName: Self.suite).map { Array($0.keys) } ?? []
+        reply.resolve(PreferencesKeysResult(keys: keys.sorted()))
+    }
+
+    func clear(_ reply: AkanNativeReply<Void>) {
+        defaults.removePersistentDomain(forName: Self.suite)
+        reply.resolve()
+    }
+
+    private static func valid<T>(_ key: String, _ reply: AkanNativeReply<T>) -> Bool {
+        if !key.isEmpty { return true }
+        reply.reject(.invalidArgs, "key must be a non-empty string")
+        return false
+    }
+}

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

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

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

@@ -0,0 +1,59 @@
+
+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 } from "../../../packages/desktop/src/plugin.ts";
+import type { PreferencesApi } from "./index.ts";
+
+let store: Map<string, string> | null = null;
+let path = "";
+
+function load(ctx: DesktopContext): Map<string, string> {
+  const file = join(ctx.appDataDir, "preferences.json");
+  if (store && path === file) return store;
+  path = file;
+  store = new Map();
+  if (existsSync(path)) {
+    try {
+      const data = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+      for (const [key, value] of Object.entries(data)) if (typeof value === "string") store.set(key, value);
+    } catch (error) {
+      console.error(`[akan-native] ${path} is unreadable, starting empty`, error);
+    }
+  }
+  return store;
+}
+
+function save(): void {
+  
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(Object.fromEntries(store!), null, 2));
+  renameSync(tmp, path);
+}
+
+function checkKey(key: unknown): string {
+  if (typeof key !== "string" || key.length === 0)
+    throw new AkanNativeError("INVALID_ARGS", "key must be a non-empty string");
+  return key;
+}
+
+export default defineDesktopPlugin<PreferencesApi>({
+  id: "preferences",
+  methods: {
+    get: (args, ctx) => ({ value: load(ctx).get(checkKey(args?.key)) ?? null }),
+    set(args, ctx) {
+      const key = checkKey(args?.key);
+      if (typeof args.value !== "string") throw new AkanNativeError("INVALID_ARGS", "value must be a string");
+      load(ctx).set(key, args.value);
+      save();
+    },
+    remove(args, ctx) {
+      if (load(ctx).delete(checkKey(args?.key))) save();
+    },
+    keys: (_args, ctx) => ({ keys: [...load(ctx).keys()] }),
+    clear(_args, ctx) {
+      load(ctx).clear();
+      save();
+    },
+  },
+});

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

@@ -0,0 +1,75 @@
+
+
+import * as React from "react";
+import { createLiveValue, definePlugin, type LiveValue } from "../../../packages/core/src/index.ts";
+import { useLiveValue } from "../../../packages/react/src/index.ts";
+import { web } from "./web.ts";
+
+/** String key-value storage that survives app restarts. Store JSON yourself for structured data. */
+export interface PreferencesApi {
+  get(args: { key: string }): Promise<{ value: string | null }>;
+  set(args: { key: string; value: string }): Promise<void>;
+  remove(args: { key: string }): Promise<void>;
+  keys(): Promise<{ keys: string[] }>;
+  clear(): Promise<void>;
+}
+
+export const preferences = definePlugin<PreferencesApi>("preferences", {
+  methods: ["get", "set", "remove", "keys", "clear"],
+  web,
+});
+
+interface Entry {
+  value: string | null;
+  ready: boolean;
+}
+
+const entries = new Map<string, LiveValue<Entry>>();
+
+function entry(key: string): LiveValue<Entry> {
+  let live = entries.get(key);
+  if (!live) {
+    const created = createLiveValue<Entry>({ value: null, ready: false }, (set) => {
+      if (!created.get().ready) {
+        preferences
+          .get({ key })
+          .then(({ value }) => {
+            
+            if (!created.get().ready) set({ value, ready: true });
+          })
+          .catch((error) => {
+            console.warn(`[akan-native] preferences.get(${key}) failed`, error);
+            set({ value: null, ready: true });
+          });
+      }
+    });
+    live = created;
+    entries.set(key, created);
+  }
+  return live;
+}
+
+export type PreferenceSetter = (value: string | null) => Promise<void>;
+
+/**
+ * Reads and writes one key. `ready` is false until the stored value has loaded.
+ * Setting null removes the key.
+ */
+export function usePreference(key: string): [value: string | null, set: PreferenceSetter, ready: boolean] {
+  const live = entry(key);
+  const { value, ready } = useLiveValue(live);
+  const set = React.useCallback<PreferenceSetter>(
+    async (next) => {
+      const previous = live.get();
+      live.set({ value: next, ready: true });
+      try {
+        await (next === null ? preferences.remove({ key }) : preferences.set({ key, value: next }));
+      } catch (error) {
+        live.set(previous);
+        throw error;
+      }
+    },
+    [key, live],
+  );
+  return [value, set, ready];
+}