akanjs 3.0.0-beta.9 → 3.0.1

package/vendor/@akanjs/native/plugins/auth-session/src/desktop.ts

@@ -0,0 +1,133 @@
+
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { claimLinks, defineDesktopPlugin, externalOpenAllowed } from "../../../packages/desktop/src/plugin.ts";
+import { checkStart, isAnswer } from "./args.ts";
+import type { AuthSessionApi } from "./index.ts";
+
+export const TIMEOUT_MS = 10 * 60 * 1000;
+
+export type Runner = (argv: string[]) => Promise<{ code: number; stderr: string }>;
+
+const spawnRunner: Runner = async (argv) => {
+  const proc = Bun.spawn(argv, { stdin: "ignore", stdout: "ignore", stderr: "pipe" });
+  const [stderr, code] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+  return { code, stderr };
+};
+
+/** CFBundleURLSchemes of an XML Info.plist (the CLI writes XML), or null if there is none to read. */
+export function registeredSchemes(plist: string | null): string[] | null {
+  if (plist === null) return null;
+  
+  const schemes: string[] = [];
+  for (const block of plist.matchAll(/<key>CFBundleURLSchemes<\/key>\s*<array>([\s\S]*?)<\/array>/g)) {
+    for (const s of block[1]!.matchAll(/<string>([^<]*)<\/string>/g)) schemes.push(s[1]!.toLowerCase());
+  }
+  return schemes;
+}
+
+function bundlePlist(): string | null {
+  try {
+    
+    return readFileSync(join(dirname(process.execPath), "..", "Info.plist"), "utf8");
+  } catch {
+    return null; 
+  }
+}
+
+interface Pending {
+  scheme: string;
+  /** The start URL's OAuth `state`: the callback must carry it (args.ts isAnswer). */
+  state: string | null;
+  resolve(result: { url: string }): void;
+  reject(error: AkanNativeError): void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/** Replaceable parts for tests: the command runner, the Info.plist text, the OS and the timeout. */
+export function createDesktopAuthSession(
+  options: { run?: Runner; plist?: () => string | null; timeoutMs?: number; platform?: NodeJS.Platform } = {},
+) {
+  const run = options.run ?? spawnRunner;
+  const plist = options.plist ?? bundlePlist;
+  const platform = options.platform ?? process.platform;
+  const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+  let pending: Pending | null = null;
+
+  const settle = (fn: (p: Pending) => void) => {
+    const p = pending;
+    if (!p) return;
+    pending = null;
+    clearTimeout(p.timer);
+    fn(p);
+  };
+
+  const answered = new Set<string>();
+  const claim = (url: string): boolean => {
+    if (answered.has(url)) return true;
+    if (!pending || !isAnswer(url, pending.scheme, pending.state)) return false;
+    settle((p) => p.resolve({ url }));
+    answered.add(url);
+    setTimeout(() => answered.delete(url), 10_000).unref?.();
+    return true;
+  };
+
+  return defineDesktopPlugin<AuthSessionApi>({
+    id: "auth-session",
+    setup(ctx) {
+      
+      claimLinks(claim);
+      ctx.onNativeEvent("opened", (event) => {
+        for (const url of (event.urls as string[] | undefined) ?? []) claim(url);
+      });
+    },
+    methods: {
+      async start(args, ctx) {
+        const { url, callbackScheme } = checkStart(args);
+        const mac = platform === "darwin";
+        if (!mac && platform !== "win32" && platform !== "linux")
+          throw new AkanNativeError("UNSUPPORTED", `auth-session is not implemented on ${platform}`);
+        const schemes = mac ? registeredSchemes(plist()) : [...ctx.deepLinkSchemes];
+        if (schemes && !schemes.includes(callbackScheme)) {
+          throw new AkanNativeError(
+            "INVALID_ARGS",
+            `the app does not handle ${callbackScheme}: links; add it to deepLinks.schemes in akan-native.config.ts`,
+          );
+        }
+        if (!externalOpenAllowed())
+          throw new AkanNativeError("NOT_ALLOWED", "at most one URL per second leaves the app; try again later");
+        settle((p) => p.reject(new AkanNativeError("CANCELLED", "replaced by a newer start()")));
+        const result = new Promise<{ url: string }>((resolve, reject) => {
+          const timer = setTimeout(
+            () => settle((p) => p.reject(new AkanNativeError("CANCELLED", "no sign-in callback arrived in time"))),
+            timeoutMs,
+          );
+          pending = { scheme: callbackScheme, state: url.searchParams.get("state"), resolve, reject, timer };
+        });
+        const mine = pending;
+        if (mac) {
+          const opened = await run(["/usr/bin/open", "-u", url.href]);
+          if (opened.code !== 0 && pending === mine) {
+            settle((p) =>
+              p.reject(new AkanNativeError("INTERNAL", `open failed (${opened.code}): ${opened.stderr.trim()}`)),
+            );
+          }
+        } else {
+          await ctx.shell("shell.open", { url: url.href }).catch((error: unknown) => {
+            if (pending === mine)
+              settle((p) =>
+                p.reject(
+                  new AkanNativeError("INTERNAL", `cannot open the browser: ${(error as Error)?.message ?? error}`),
+                ),
+              );
+          });
+        }
+        return result;
+      },
+    },
+  });
+}
+
+export default createDesktopAuthSession();

package/vendor/@akanjs/native/plugins/auth-session/src/index.ts

@@ -0,0 +1,39 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+
+export { checkStart, isCallback } from "./args.ts";
+
+/**
+ * OAuth / OpenID sign-in in the system browser (plugins.md §4.5, like Expo's
+ * WebBrowser.openAuthSessionAsync): shows the provider's page and returns the redirect to
+ * `callbackScheme` with the result (code, state, error) in its query or fragment. The app then
+ * exchanges the code itself (PKCE); this plugin does not parse or validate the result.
+ *
+ * The callback scheme must be one of the app's deep link schemes (akan-native.config.ts
+ * `deepLinks.schemes`): Android and macOS receive the redirect as a deep link, so the app's
+ * `urlOpen` listeners see it too there. iOS catches it inside the session.
+ *
+ * | host    | how                                              | cancel detection                         |
+ * |---------|--------------------------------------------------|------------------------------------------|
+ * | iOS     | ASWebAuthenticationSession                       | the user closed the sheet                |
+ * | Android | Custom Tab + deep link (plain browser if none)   | back in the app without the redirect     |
+ * | macOS   | default browser + deep link (TAO Event::Opened)  | none: a new start() or 10 minutes        |
+ * | web     | UNSUPPORTED                                      |                                          |
+ *
+ * The web has no custom-scheme callback to catch: web apps register an https redirect on their
+ * own origin and read the result on that route (full-page redirect, or a popup posting to its
+ * opener), which depends on the app's routing and is left to the app.
+ */
+export interface AuthSessionApi {
+  /**
+   * Resolves with the callback URL. Rejects CANCELLED when the user dismissed the page, came back
+   * without finishing (Android), or a newer start() replaced this one; INVALID_ARGS for a bad URL
+   * or scheme (Android also when the app does not handle the scheme). `ephemeral` (iOS) signs in
+   * without the browser's cookies and skips the "wants to use … to sign in" prompt.
+   * The callback that ends a start() is its result only: it does not also reach app.urlOpen, on any
+   * platform. A link of the scheme that arrives with no start() waiting (or with another state) is
+   * an ordinary deep link.
+   */
+  start(args: { url: string; callbackScheme: string; ephemeral?: boolean }): Promise<{ url: string }>;
+}
+
+export const authSession = definePlugin<AuthSessionApi>("auth-session", { methods: ["start"] });

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

@@ -0,0 +1,10 @@
+{
+  "id": "autostart",
+  "apiVersion": 1,
+  "methods": ["enable", "disable", "isEnabled", "openSettings"],
+  "events": [],
+  "web": null,
+  "desktop": "./src/desktop.ts",
+  "ios": null,
+  "android": null
+}

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

@@ -0,0 +1,189 @@
+
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+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 { AutostartApi, AutostartState, AutostartStatus } from "./index.ts";
+
+export interface ShellError {
+  reason: "alreadyRegistered" | "notRegistered" | "deniedByUser" | "invalidSignature" | "other";
+  code: number;
+  domain: string;
+  message: string;
+}
+
+export interface ShellAnswer {
+  status: AutostartStatus;
+  error?: ShellError | null;
+}
+
+const state = (status: AutostartStatus): AutostartState => ({ enabled: status === "enabled", status });
+
+/** Where the user switches login items on and off. */
+const SETTINGS_PAGE: Partial<Record<NodeJS.Platform, string>> = {
+  darwin: "System Settings › General › Login Items",
+  win32: "Settings › Apps › Startup",
+};
+
+/** The error an enable/disable answer stands for, or null when the app is where it was asked to be. */
+export function failure(
+  op: "enable" | "disable",
+  answer: ShellAnswer,
+  platform: NodeJS.Platform = process.platform,
+): AkanNativeError | null {
+  const { status, error } = answer;
+  const page = SETTINGS_PAGE[platform] ?? SETTINGS_PAGE.darwin!;
+  if (op === "enable" && status === "requiresApproval") {
+    return new AkanNativeError(
+      "PERMISSION_DENIED",
+      `the app is switched off in ${page}; openSettings() opens that page`,
+    );
+  }
+  if (op === "enable" ? status === "enabled" : status === "notRegistered" || status === "notFound") return null;
+  if (!error) return new AkanNativeError("INTERNAL", `${op} did not change the login item (status ${status})`);
+  const detail = `${error.message} (${error.domain} ${error.code})`;
+  switch (error.reason) {
+    case "deniedByUser":
+      return new AkanNativeError("PERMISSION_DENIED", `the user switched the app off in ${page}: ${detail}`);
+    case "invalidSignature":
+      return new AkanNativeError("INTERNAL", `macOS did not accept the app's code signature: ${detail}`);
+    default:
+      return new AkanNativeError("INTERNAL", `${op} failed: ${detail}`);
+  }
+}
+
+type Env = Record<string, string | undefined>;
+
+/** $XDG_CONFIG_HOME/autostart; the base directory must be absolute (XDG Base Directory spec). */
+export function autostartDir(env: Env = process.env, home = homedir()): string {
+  const config = env.XDG_CONFIG_HOME?.startsWith("/") ? env.XDG_CONFIG_HOME : join(home, ".config");
+  return join(config, "autostart");
+}
+
+/**
+ * The Exec= value that runs `path`: one quoted argument (Desktop Entry spec, "The Exec key").
+ * Inside quotes `"`, `` ` ``, `$` and `\` take a backslash; then the string escaping of values
+ * doubles every backslash, and a literal `%` is `%%` (field codes).
+ */
+export function desktopExec(path: string): string {
+  const quoted = `"${path.replace(/["`$\\]/g, (c) => `\\${c}`)}"`;
+  return quoted.replace(/\\/g, "\\\\").replace(/%/g, "%%");
+}
+
+/** Values of the Desktop Entry spec's string type: no line breaks. */
+const oneLine = (value: string) => value.replace(/[\r\n]+/g, " ");
+
+export function desktopEntry(name: string, exec: string): string {
+  return [
+    "[Desktop Entry]",
+    "Type=Application",
+    "Version=1.5",
+    `Name=${oneLine(name)}`,
+    `Exec=${desktopExec(exec)}`,
+    "Terminal=false",
+    "X-GNOME-Autostart-enabled=true",
+    "",
+  ].join("\n");
+}
+
+/**
+ * The state an entry stands for. Hidden=true (the spec's "deleted") or
+ * X-GNOME-Autostart-enabled=false (GNOME's startup settings) is an entry the user switched off.
+ */
+export function entryStatus(text: string | null): AutostartStatus {
+  if (text === null) return "notRegistered";
+  let group = "";
+  const keys = new Map<string, string>();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("[")) group = line;
+    else if (group === "[Desktop Entry]" && line.includes("=") && !line.startsWith("#")) {
+      const at = line.indexOf("=");
+      keys.set(line.slice(0, at).trim(), line.slice(at + 1).trim());
+    }
+  }
+  if (keys.get("Hidden") === "true" || keys.get("X-GNOME-Autostart-enabled") === "false") return "requiresApproval";
+  return "enabled";
+}
+
+/** `executable`: the file the entry starts; an AppImage's mount point changes at every start, $APPIMAGE does not. */
+export function linuxAutostart(
+  dir: () => string = () => autostartDir(),
+  executable: () => string = () => process.env.APPIMAGE || process.execPath,
+) {
+  const file = (ctx: DesktopContext) => join(dir(), `${ctx.app.id}.desktop`);
+  const read = (ctx: DesktopContext) => (existsSync(file(ctx)) ? readFileSync(file(ctx), "utf8") : null);
+  const answer = (status: AutostartStatus, error?: unknown): ShellAnswer => ({
+    status,
+    error: error
+      ? { reason: "other", code: 0, domain: "filesystem", message: (error as Error).message ?? String(error) }
+      : null,
+  });
+  return {
+    status: (ctx: DesktopContext): ShellAnswer => ({ status: entryStatus(read(ctx)) }),
+    
+    enable(ctx: DesktopContext): ShellAnswer {
+      try {
+        mkdirSync(dir(), { recursive: true });
+        writeFileSync(`${file(ctx)}.tmp`, desktopEntry(ctx.app.name, executable()));
+        renameSync(`${file(ctx)}.tmp`, file(ctx));
+      } catch (error) {
+        return answer(entryStatus(read(ctx)), error);
+      }
+      return answer(entryStatus(read(ctx)));
+    },
+    disable(ctx: DesktopContext): ShellAnswer {
+      try {
+        rmSync(file(ctx), { force: true });
+      } catch (error) {
+        return answer(entryStatus(read(ctx)), error);
+      }
+      return answer(entryStatus(read(ctx)));
+    },
+  };
+}
+
+type Backend = {
+  status(ctx: DesktopContext): Promise<ShellAnswer>;
+  change(op: "enable" | "disable", ctx: DesktopContext): Promise<ShellAnswer>;
+};
+
+/** The shell's autostart.* ops (macOS, Windows); `id` names the Windows Run value. */
+const shellBackend: Backend = {
+  status: async (ctx) => (await ctx.shell("autostart.status", { id: ctx.app.id })) as ShellAnswer,
+  change: async (op, ctx) => (await ctx.shell(`autostart.${op}`, { id: ctx.app.id })) as ShellAnswer,
+};
+
+/** `platform` and `linux` are replaceable so tests can check every OS's path on any OS. */
+export function createDesktopAutostart(platform: NodeJS.Platform = process.platform, linux = linuxAutostart()) {
+  const backend: Backend =
+    platform === "linux"
+      ? {
+          status: async (ctx) => linux.status(ctx),
+          change: async (op, ctx) => (op === "enable" ? linux.enable(ctx) : linux.disable(ctx)),
+        }
+      : shellBackend;
+  const change = async (op: "enable" | "disable", ctx: DesktopContext): Promise<AutostartState> => {
+    const answer = await backend.change(op, ctx);
+    const error = failure(op, answer, platform);
+    if (error) throw error;
+    return state(answer.status);
+  };
+  return defineDesktopPlugin<AutostartApi>({
+    id: "autostart",
+    methods: {
+      enable: (_args, ctx) => change("enable", ctx),
+      disable: (_args, ctx) => change("disable", ctx),
+      isEnabled: async (_args, ctx) => state((await backend.status(ctx)).status),
+      openSettings: async (_args, ctx) => {
+        if (platform === "linux")
+          throw new AkanNativeError("UNSUPPORTED", "Linux desktops have no common settings page for startup apps");
+        await ctx.shell("autostart.openSettings");
+      },
+    },
+  });
+}
+
+export default createDesktopAutostart();

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

@@ -0,0 +1,51 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+
+/**
+ * Launch the app when the user logs in (plugins.md §5).
+ *
+ * - macOS 13+: SMAppService.mainApp. The app itself becomes a login item under System Settings ›
+ *   General › Login Items › "Open at Login"; no permission prompt, but macOS shows a "Login Item
+ *   Added" notification. The user can switch it off there: then `status` is "requiresApproval"
+ *   and enable() rejects with PERMISSION_DENIED; openSettings() takes the user to that page.
+ * - `status` is macOS's own (SMAppService.Status):
+ *     "enabled": registered and will launch at login.
+ *     "notRegistered": not registered (typically after disable()).
+ *     "requiresApproval": registered, but switched off by the user in System Settings.
+ *     "notFound": macOS has no login item record for this app, e.g. it never called enable().
+ *       Seen on macOS 26 for an ad-hoc signed bundle that never registered; not an error.
+ *   `enabled` is `status === "enabled"`.
+ * - The registration belongs to the app bundle: enable() it from the copy users run, normally
+ *   the one in /Applications. A bundle whose signature macOS does not accept is refused
+ *   (INTERNAL, "invalid signature").
+ * - enable() when enabled and disable() when not are no-ops that resolve.
+ * - Windows: a value named after the app id under HKCU\Software\Microsoft\Windows\CurrentVersion\Run
+ *   that starts this .exe. The user can switch it off in Settings › Apps › Startup or Task Manager:
+ *   then `status` is "requiresApproval" and enable() rejects with PERMISSION_DENIED; openSettings()
+ *   opens that page. disable() removes the value and that switch. Never "notFound".
+ * - Linux: an XDG autostart entry, ~/.config/autostart/<app id>.desktop, that starts this
+ *   executable ($APPIMAGE for an AppImage). An entry the user switched off (Hidden=true,
+ *   X-GNOME-Autostart-enabled=false) reads "requiresApproval", and enable() switches it on again:
+ *   Linux has no approval system. openSettings() is UNSUPPORTED (no common settings page). Never "notFound".
+ * - Web, iOS and Android: UNSUPPORTED.
+ */
+export type AutostartStatus = "enabled" | "notRegistered" | "requiresApproval" | "notFound";
+
+export interface AutostartState {
+  enabled: boolean;
+  status: AutostartStatus;
+}
+
+export interface AutostartApi {
+  /** Registers the app to open at login. */
+  enable(): Promise<AutostartState>;
+  /** Stops opening at login. The running app keeps running. */
+  disable(): Promise<AutostartState>;
+  /** Reads the state without changing it. */
+  isEnabled(): Promise<AutostartState>;
+  /** Opens System Settings at Login Items, or Settings › Apps › Startup on Windows (to switch a "requiresApproval" item back on). */
+  openSettings(): Promise<void>;
+}
+
+export const autostart = definePlugin<AutostartApi>("autostart", {
+  methods: ["enable", "disable", "isEnabled", "openSettings"],
+});

package/vendor/@akanjs/native/plugins/badge/ios/BadgePlugin.swift

@@ -0,0 +1,92 @@
+import UserNotifications
+
+/// The app icon badge through UNUserNotificationCenter.setBadgeCount (iOS 16), plugins.md §4.6.
+/// - Not UIApplication.applicationIconBadgeNumber, which tao/src/platform_impl/ios/badge.rs:8-15 and
+///   capacitor-plugins/local-notifications/.../LocalNotificationsPlugin.swift:635 set: it is
+///   deprecated since iOS 17 and has no replacement getter, which is why there is no get().
+/// - Badges belong to the notification permission. tao sets the number without looking and the
+///   badge silently never appears; here set() checks the settings first and rejects
+///   PERMISSION_DENIED, the way plugins/local-notifications answers schedule() without permission.
+///   "granted" needs an authorization that shows badges: provisional authorization delivers quietly
+///   without badges, so it counts as "prompt" (requestPermission asks for the full one).
+/// - requestPermission asks for alerts, sounds and badges together, the set of
+///   plugins/local-notifications and capacitor-plugins/push-notifications/.../PushNotificationsHandler.swift:9.
+///   iOS prompts once per app, and the options of that first request are what the user grants, so a
+///   badge-only request would leave a later notifications prompt without alerts.
+/// - clear() resolves without the permission: no badge can be showing then.
+/// Arguments arrive decoded by the generated BadgePluginSpec (PL-10); the range is checked here.
+final class BadgePlugin: BadgePluginSpec {
+    static let id = "badge"
+    private static let maxCount = 2_147_483_647.0
+
+    init(context: AkanNativePluginContext) {}
+
+    func set(_ args: BadgeSetArgs, _ reply: AkanNativeReply<Void>) {
+        let value = args.count
+        guard value.rounded() == value, value >= 0, value <= Self.maxCount else {
+            return reply.reject(.invalidArgs, "count must be an integer from 0 to 2147483647")
+        }
+        let count = Int(value)
+        Task {
+            let center = UNUserNotificationCenter.current()
+            guard Self.state(await center.notificationSettings()) == .granted else {
+                return reply.reject(.permissionDenied, "badge permission is not granted (call requestPermission)")
+            }
+            do {
+                try await center.setBadgeCount(count)
+                reply.resolve()
+            } catch {
+                reply.reject(Self.code(error), "setting the badge failed: \(error.localizedDescription)")
+            }
+        }
+    }
+
+    func clear(_ reply: AkanNativeReply<Void>) {
+        Task {
+            let center = UNUserNotificationCenter.current()
+            guard Self.state(await center.notificationSettings()) == .granted else { return reply.resolve() }
+            do {
+                try await center.setBadgeCount(0)
+                reply.resolve()
+            } catch {
+                reply.reject(Self.code(error), "clearing the badge failed: \(error.localizedDescription)")
+            }
+        }
+    }
+
+    func checkPermission(_ reply: AkanNativeReply<BadgeCheckPermissionResult>) {
+        Task {
+            reply.resolve(BadgeCheckPermissionResult(badge: Self.state(await UNUserNotificationCenter.current().notificationSettings())))
+        }
+    }
+
+    func requestPermission(_ reply: AkanNativeReply<BadgeRequestPermissionResult>) {
+        Task {
+            let center = UNUserNotificationCenter.current()
+            let status = await center.notificationSettings().authorizationStatus
+            if status == .notDetermined || status == .provisional {
+                do {
+                    _ = try await center.requestAuthorization(options: [.alert, .sound, .badge])
+                } catch {
+                    return reply.reject(.internalError, "requestAuthorization failed: \(error.localizedDescription)")
+                }
+            }
+            reply.resolve(BadgeRequestPermissionResult(badge: Self.state(await center.notificationSettings())))
+        }
+    }
+
+    nonisolated private static func state(_ settings: UNNotificationSettings) -> BadgePermissionState {
+        switch settings.authorizationStatus {
+        case .notDetermined, .provisional:
+            return settings.badgeSetting == .enabled ? .granted : .prompt
+        case .denied:
+            return .denied
+        default: // authorized, ephemeral
+            return settings.badgeSetting == .enabled ? .granted : .denied // badges switched off in Settings
+        }
+    }
+
+    nonisolated private static func code(_ error: any Error) -> AkanNativeErrorCode {
+        (error as? UNError)?.code == .notificationsNotAllowed ? .permissionDenied : .internalError
+    }
+}

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

@@ -0,0 +1,15 @@
+{
+  "id": "badge",
+  "apiVersion": 1,
+  "methods": ["set", "clear", "checkPermission", "requestPermission"],
+  "events": [],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "./src/desktop.ts",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "BadgePlugin",
+    "frameworks": ["UserNotifications"]
+  },
+  "android": null
+}

package/vendor/@akanjs/native/plugins/badge/src/count.ts

@@ -0,0 +1,12 @@
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+
+/** The largest count: badges are 32-bit integers on iOS (UNUserNotificationCenter.setBadgeCount takes an NSInteger, tauri clamps to i32). */
+export const MAX_BADGE_COUNT = 2147483647;
+
+/** Checks set()'s count; the native implementation checks the same range. */
+export function checkCount(count: unknown): number {
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 0 || count > MAX_BADGE_COUNT) {
+    throw new AkanNativeError("INVALID_ARGS", `count must be an integer from 0 to ${MAX_BADGE_COUNT}`);
+  }
+  return count;
+}

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

@@ -0,0 +1,24 @@
+
+
+import { defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import { checkCount } from "./count.ts";
+import type { BadgeApi } from "./index.ts";
+
+export default defineDesktopPlugin<BadgeApi>({
+  id: "badge",
+  methods: {
+    async set(options, ctx) {
+      const count = checkCount(options?.count);
+      await ctx.shell("dock.setBadge", { label: count === 0 ? null : String(count) });
+    },
+    async clear(_args, ctx) {
+      await ctx.shell("dock.setBadge", { label: null });
+    },
+    async checkPermission() {
+      return { badge: "granted" as const };
+    },
+    async requestPermission() {
+      return { badge: "granted" as const };
+    },
+  },
+});

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

@@ -0,0 +1,40 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+import { web } from "./web.ts";
+
+export { checkCount, MAX_BADGE_COUNT } from "./count.ts";
+
+export type PermissionState = "granted" | "denied" | "prompt";
+
+/**
+ * The number on the app icon (plugins.md §4.6).
+ *
+ * - iOS: UNUserNotificationCenter.setBadgeCount. Badges are part of the notification permission:
+ *   set() rejects PERMISSION_DENIED until requestPermission() was granted, or when the user
+ *   switched badges off for the app. The prompt asks for alerts, sounds and badges together
+ *   (one prompt per app), the same set as @akanjs/native/plugins/local-notifications.
+ * - Web: the Badging API (navigator.setAppBadge), shown for installed web apps (Chromium PWAs;
+ *   Safari home screen / Dock web apps, which also need the notification permission). Browsers
+ *   without it reject UNSUPPORTED. The API has no permission of its own, so the permission
+ *   methods answer "granted" there.
+ * - Desktop, through the dock plugin's badge (no permission, "granted"): the Dock tile's label on
+ *   macOS; on Windows the taskbar buttons' overlay icon (counts over 99 as "99+"); on Linux the
+ *   launcher entry's count, shown by docks that support it once the app is installed with its
+ *   desktop file (@akanjs/native/plugins/dock).
+ * - Android has no badge API (launchers draw dots for notifications): every method rejects
+ *   UNSUPPORTED there.
+ */
+export interface BadgeApi {
+  /** Shows `count` (an integer from 0 to 2147483647) on the app icon; 0 removes the badge. */
+  set(options: { count: number }): Promise<void>;
+  /** Removes the badge. Resolves without the permission as well (no badge can be shown then). */
+  clear(): Promise<void>;
+  /** Never prompts. */
+  checkPermission(): Promise<{ badge: PermissionState }>;
+  /** Prompts when the state is "prompt"; otherwise answers like checkPermission. */
+  requestPermission(): Promise<{ badge: PermissionState }>;
+}
+
+export const badge = definePlugin<BadgeApi>("badge", {
+  methods: ["set", "clear", "checkPermission", "requestPermission"],
+  web,
+});

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

@@ -0,0 +1,37 @@
+import { AkanNativeError, defineWebPlugin } from "../../../packages/core/src/index.ts";
+import { checkCount } from "./count.ts";
+import type { BadgeApi } from "./index.ts";
+
+interface BadgingNavigator {
+  setAppBadge?: (count?: number) => Promise<void>;
+  clearAppBadge?: () => Promise<void>;
+}
+
+function badging(): Required<BadgingNavigator> {
+  const nav = (typeof navigator === "undefined" ? undefined : navigator) as BadgingNavigator | undefined;
+  if (typeof nav?.setAppBadge !== "function" || typeof nav.clearAppBadge !== "function") {
+    throw new AkanNativeError("UNSUPPORTED", "this browser has no Badging API (navigator.setAppBadge)");
+  }
+  return { setAppBadge: nav.setAppBadge.bind(nav), clearAppBadge: nav.clearAppBadge.bind(nav) };
+}
+
+export const web = defineWebPlugin<BadgeApi>({
+  methods: {
+    async set(options) {
+      const count = checkCount(options?.count);
+      const api = badging();
+      await (count === 0 ? api.clearAppBadge() : api.setAppBadge(count));
+    },
+    async clear() {
+      await badging().clearAppBadge();
+    },
+    async checkPermission() {
+      badging();
+      return { badge: "granted" };
+    },
+    async requestPermission() {
+      badging();
+      return { badge: "granted" };
+    },
+  },
+});