akanjs 3.0.0-beta.9 → 3.0.0

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

@@ -0,0 +1,140 @@
+
+
+import { Database, type Statement } from "bun:sqlite";
+import { mkdirSync } 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 { checkDb, checkName, checkParams, checkSql, columnValue, sqliteCode } from "./common.ts";
+import type { SqliteSpec, StatementArgs } from "./index.ts";
+
+function mapError(error: unknown): AkanNativeError {
+  if (error instanceof AkanNativeError) return error;
+  const errno = (error as { errno?: unknown })?.errno;
+  const message = String((error as Error)?.message ?? error);
+  return new AkanNativeError(typeof errno === "number" ? sqliteCode(errno) : "INTERNAL", message);
+}
+
+/** `dir` is replaceable so tests can use a temporary folder. */
+export function createDesktopSqlite(dir: (ctx: DesktopContext) => string = (ctx) => join(ctx.appDataDir, "databases")) {
+  /** Page (window and document) → name → connection. */
+  const pages = new Map<string, Map<string, Database>>();
+  const pageOf = (ctx: DesktopContext) => `${ctx.window ?? 1}:${ctx.document?.id ?? ""}`;
+
+  const database = (db: unknown, ctx: DesktopContext): Database => {
+    const handle = pages.get(pageOf(ctx))?.get(checkDb(db));
+    if (!handle)
+      throw new AkanNativeError(
+        "NOT_FOUND",
+        `database ${String(db)} is not open in this page (call open first; a page load opens its own)`,
+      );
+    return handle;
+  };
+
+  /** Rolls back what is left open and closes the connection. */
+  const shut = (db: Database) => {
+    try {
+      if (db.inTransaction) db.run("ROLLBACK");
+    } catch (error) {
+      console.error("[akan-native] sqlite: rolling back an open transaction failed", error);
+    }
+    db.close();
+  };
+
+  const closePage = (page: string) => {
+    const open = pages.get(page);
+    pages.delete(page);
+    for (const db of open?.values() ?? []) shut(db);
+  };
+
+  /** Prepares one statement with its values bound-checked, runs `use`, then finalizes it. */
+  const withStatement = <T>(
+    args: StatementArgs,
+    ctx: DesktopContext,
+    use: (statement: Statement, values: ReturnType<typeof checkParams>) => T,
+  ): T => {
+    const db = database(args?.db, ctx);
+    const sql = checkSql(args.sql);
+    const values = checkParams(args.params);
+    let statement: Statement;
+    try {
+      statement = db.prepare(sql);
+    } catch (error) {
+      throw mapError(error);
+    }
+    try {
+      if (statement.paramsCount !== values.length) {
+        throw new AkanNativeError("INVALID_ARGS", `sql expects ${statement.paramsCount} values, got ${values.length}`);
+      }
+      return use(statement, values);
+    } catch (error) {
+      throw mapError(error);
+    } finally {
+      statement.finalize();
+    }
+  };
+
+  const closeAll = () => {
+    for (const page of [...pages.keys()]) closePage(page);
+  };
+
+  return defineDesktopPlugin<SqliteSpec>({
+    id: "sqlite",
+    setup(ctx) {
+      ctx.onQuit(closeAll);
+    },
+    methods: {
+      open(args, ctx) {
+        const name = checkName(args?.name);
+        const page = pageOf(ctx);
+        let open = pages.get(page);
+        if (open?.has(name)) return { db: name };
+        const folder = dir(ctx);
+        try {
+          mkdirSync(folder, { recursive: true });
+          const db = new Database(join(folder, name), { create: true, readwrite: true });
+          db.run("PRAGMA busy_timeout = 5000");
+          db.run("PRAGMA journal_mode = WAL");
+          db.run("PRAGMA foreign_keys = ON");
+          if (!open) {
+            open = new Map();
+            pages.set(page, open);
+            ctx.document?.own(() => closePage(page));
+          }
+          open.set(name, db);
+        } catch (error) {
+          const e = mapError(error);
+          throw new AkanNativeError(
+            e.code === "INVALID_ARGS" ? "INTERNAL" : e.code,
+            `cannot open ${name}: ${e.message}`,
+          );
+        }
+        return { db: name };
+      },
+      execute: (args, ctx) =>
+        withStatement(args, ctx, (statement, values) => {
+          const { changes, lastInsertRowid } = statement.run(...values);
+          return { changes, lastInsertId: Number(lastInsertRowid) };
+        }),
+      query: (args, ctx) =>
+        withStatement(args, ctx, (statement, values) => {
+          const columns = statement.columnNames;
+          const rows = (statement.values(...values) as unknown[][]).map((row) => {
+            const out: Record<string, unknown> = {};
+            for (const [i, name] of columns.entries()) out[name] = columnValue(row[i]);
+            return out;
+          });
+          return { columns, rows };
+        }),
+      close(args, ctx) {
+        const name = checkDb(args?.db);
+        const open = pages.get(pageOf(ctx));
+        const db = open?.get(name);
+        open?.delete(name);
+        if (db) shut(db);
+      },
+    },
+  });
+}
+
+export default createDesktopSqlite();

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

@@ -0,0 +1,114 @@
+import { definePlugin, type Plugin } from "../../../packages/core/src/index.ts";
+
+/**
+ * A value bound to a `?` parameter or read from a column. The same rules hold on macOS, iOS and
+ * Android:
+ * - number: an integer within ±(2^53 − 1) binds as INTEGER, any other number as REAL (bun:sqlite's
+ *   rule). Columns come back as numbers; INTEGER values beyond 2^53 lose precision, as in JSON.
+ *   REAL infinities come back as null (JSON has no Infinity).
+ * - boolean: binds as 1 or 0 (SQLite has no boolean type) and reads back as a number.
+ * - BLOB: `{ base64 }` both ways (standard alphabet, padding optional when binding). An empty
+ *   `{ base64: "" }` is a zero-length BLOB, not NULL.
+ * - string: TEXT, UTF-8 in the file. NUL characters are kept.
+ */
+export type SqlValue = string | number | boolean | null | SqlBlob;
+
+export interface SqlBlob {
+  base64: string;
+}
+
+/** A result row: column name → value. Later columns with the same name replace earlier ones (alias them). */
+export type SqlRow = Record<string, SqlValue>;
+
+export interface SqlStatement {
+  /** A handle from open(). */
+  db: string;
+  /**
+   * One SQL statement; a trailing ";" and comments are fine. More than one statement rejects
+   * INVALID_ARGS instead of running only the first (what SQLite's prepare, Android and bun:sqlite
+   * would otherwise do silently): send them one call at a time.
+   */
+  sql: string;
+  /** Positional values for `?`, `?NNN`, `:name` parameters (by index). The count must match the statement's. */
+  params?: SqlValue[];
+}
+
+export interface ExecuteResult {
+  /**
+   * Rows inserted, updated or deleted by this statement, including rows changed by triggers and
+   * foreign key actions (the difference of sqlite3_total_changes()); 0 for other statements.
+   */
+  changes: number;
+  /** sqlite3_last_insert_rowid() of the connection after the statement: the rowid of the most recent successful INSERT, 0 if none. */
+  lastInsertId: number;
+}
+
+export interface QueryResult<T extends SqlRow = SqlRow> {
+  /** Result column names in order (also for an empty result; rows are objects, whose key order is not guaranteed on iOS). */
+  columns: string[];
+  rows: T[];
+}
+
+/**
+ * SQLite databases in the app's data folder, with the SQLite that ships with the OS: libsqlite3 on
+ * iOS, android.database.sqlite on Android, bun:sqlite on desktop. Not available on the web.
+ *
+ * - Files: `<name>` in Library/Application Support/databases (iOS), the app's databases folder
+ *   (Android, Context.getDatabasePath), `<app data>/databases` (desktop). Kept until the app is
+ *   removed.
+ * - A handle belongs to the page that opened it (architecture review, 2026-09-26): each page load
+ *   (and each desktop window) has its own connection, and when the page reloads, navigates or its
+ *   window closes, an open transaction is rolled back and the connection closed. Call open() after
+ *   every page load; open() of a name this page already opened returns it again.
+ * - Every database opens with `PRAGMA foreign_keys = ON` and a 5 s busy timeout. The journal is
+ *   WAL on the desktop and iOS, where several windows' connections may share a file; Android keeps
+ *   journal_mode DELETE (its WAL uses a pool of connections, and a statement's connection state
+ *   would depend on the connection it lands on; Android's windows never overlap in one process).
+ * - Calls run one at a time off the main thread, in call order, for all databases together.
+ *   Transactions: `execute({ sql: "BEGIN" })` … `"COMMIT"` / `"ROLLBACK"`. On Android BEGIN, COMMIT
+ *   and ROLLBACK must start the statement text (Android runs them itself), and SAVEPOINT works
+ *   only inside BEGIN … COMMIT.
+ * - Errors: INVALID_ARGS for bad arguments and for SQL errors (syntax, missing table, constraint
+ *   violations, with SQLite's message), NOT_FOUND for a db that is not open, INTERNAL for I/O and
+ *   other failures.
+ */
+export interface SqliteApi {
+  /**
+   * Opens (creating if needed) the database file `name`: letters, digits, ".", "_" and "-", up to
+   * 128 characters, starting with a letter or digit, not ending in -journal, -wal or -shm. The
+   * handle is the name.
+   */
+  open(args: { name: string }): Promise<{ db: string }>;
+  /** Runs a statement and discards any rows it returns. */
+  execute(args: SqlStatement): Promise<ExecuteResult>;
+  /** Runs a statement and returns its rows (any statement: SELECT, `INSERT … RETURNING`, PRAGMA). */
+  query<T extends SqlRow = SqlRow>(args: SqlStatement): Promise<QueryResult<T>>;
+  /** Closes the database. Closing a database that is not open does nothing. */
+  close(args: { db: string }): Promise<void>;
+}
+
+/** The arguments of execute and query as the host receives them. */
+export interface StatementArgs {
+  db: string;
+  sql: string;
+  /** SqlValue items; the hosts check them (the generator cannot express a union of primitives). */
+  params?: unknown[];
+}
+
+/**
+ * The bridge shape of SqliteApi, the spec the Swift and Kotlin bindings are generated from (PL-10):
+ * params and row values are `unknown` because a union of primitives has no generated form.
+ */
+export interface SqliteSpec {
+  open(args: { name: string }): Promise<{ db: string }>;
+  execute(args: StatementArgs): Promise<ExecuteResult>;
+  query(args: StatementArgs): Promise<{ columns: string[]; rows: Record<string, unknown>[] }>;
+  close(args: { db: string }): Promise<void>;
+}
+
+const handle = definePlugin<SqliteSpec>("sqlite", {
+  methods: ["open", "execute", "query", "close"],
+});
+
+/** The hosts return only SqlValue items, so the typed facade is the same object. */
+export const sqlite = handle as unknown as Plugin<SqliteApi>;

package/vendor/@akanjs/native/plugins/toast/android/ToastPlugin.kt

@@ -0,0 +1,27 @@
+package com.akanjs.plugins.toast
+
+import android.widget.Toast
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * The system text Toast, like capacitor-plugins/toast/android/.../Toast.java:21-30.
+ * - position is not applied: for apps targeting API 30+ Toast.setGravity does nothing on text
+ *   toasts (and logs a warning), so Capacitor's setGravity calls (:24-28) have no effect on the
+ *   Android versions akan-native supports (minSdk 35). Text toasts always sit at the bottom.
+ * - The system queues the app's toasts and shows them one after another; the page's in-page
+ *   toast (src/queue.ts) copies that order for the other platforms.
+ * - The application context: a toast outlives the call and must not hold the activity.
+ * - Toasts need no notification permission (POST_NOTIFICATIONS) and TalkBack reads them.
+ * Entry points run on the main thread, where Toast needs its Looper.
+ * Arguments arrive decoded and checked by the generated ToastPluginSpec (PL-10).
+ */
+class ToastPlugin(private val context: AkanNativePluginContext) : ToastPluginSpec {
+    override fun show(args: ToastShowOptions, reply: AkanNativeVoidReply) {
+        if (args.text.isBlank()) return reply.reject(AkanNativeErrorCode.INVALID_ARGS, "text must not be empty")
+        val length = if (args.duration == ToastDuration.LONG) Toast.LENGTH_LONG else Toast.LENGTH_SHORT
+        Toast.makeText(context.activity.applicationContext, args.text, length).show()
+        reply.resolve()
+    }
+}

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

@@ -0,0 +1,14 @@
+{
+  "id": "toast",
+  "apiVersion": 1,
+  "methods": ["show"],
+  "events": [],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "web",
+  "ios": "web",
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.toast.ToastPlugin"
+  }
+}

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

@@ -0,0 +1,41 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+import { web } from "./web.ts";
+
+export { checkShow, createToastQueue, MAX_QUEUED, TOAST_DURATION_MS, type ToastItem } from "./queue.ts";
+
+/** "short" shows the toast for 2 s, "long" for 3.5 s (Android's Toast.LENGTH_SHORT / LENGTH_LONG). */
+export type ToastDuration = "short" | "long";
+
+/** Where the toast appears. Android shows text toasts at the bottom whatever is asked (see show). */
+export type ToastPosition = "top" | "center" | "bottom";
+
+export interface ToastShowOptions {
+  /** The message, not empty. Android 12+ cuts text toasts to two lines. */
+  text: string;
+  /** Default "short". */
+  duration?: ToastDuration;
+  /** Default "bottom". Ignored on Android. */
+  position?: ToastPosition;
+}
+
+/**
+ * A short message that goes away by itself (plugins.md §4.2), with the options of
+ * capacitor-plugins/toast/src/definitions.ts. It does not take touches or focus.
+ *
+ * Android shows the system Toast. Web, macOS and iOS show the same in-page toast, which stays
+ * above the app's own layers (the top layer, also above open dialogs) and is read by screen
+ * readers through a live region. On every platform toasts queue up and show one after another,
+ * as Android's do; at most 5 wait at a time, more are dropped (Android drops them as well).
+ */
+export interface ToastApi {
+  /**
+   * Resolves once the toast is queued or shown, not when it goes away. Rejects INVALID_ARGS for
+   * empty text or an unknown duration or position.
+   */
+  show(options: ToastShowOptions): Promise<void>;
+}
+
+export const toast = definePlugin<ToastApi>("toast", {
+  methods: ["show"],
+  web,
+});

package/vendor/@akanjs/native/plugins/toast/src/queue.ts

@@ -0,0 +1,77 @@
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import type { ToastDuration, ToastPosition } from "./index.ts";
+
+/** Android's toast lengths (NotificationManagerService SHORT_DELAY / LONG_DELAY), also capacitor-plugins/toast/src/web.ts:8-10. */
+export const TOAST_DURATION_MS: Readonly<Record<ToastDuration, number>> = { short: 2000, long: 3500 };
+
+/** Toasts of one app that may be waiting or showing at once; Android drops more (MAX_PACKAGE_TOASTS). */
+export const MAX_QUEUED = 5;
+
+const DURATIONS: readonly ToastDuration[] = ["short", "long"];
+const POSITIONS: readonly ToastPosition[] = ["top", "center", "bottom"];
+
+export interface ToastItem {
+  text: string;
+  duration: ToastDuration;
+  position: ToastPosition;
+  /** How long the toast stays fully visible. */
+  ms: number;
+}
+
+function choice<T extends string>(value: unknown, allowed: readonly T[], fallback: T, name: string): T {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === "string" && (allowed as readonly string[]).includes(value)) return value as T;
+  throw new AkanNativeError("INVALID_ARGS", `${name} must be one of ${allowed.join(", ")}`);
+}
+
+/** Checks show()'s options the way the Android plugin does (generated checks plus the empty text). */
+export function checkShow(options: unknown): ToastItem {
+  if (typeof options !== "object" || options === null) throw new AkanNativeError("INVALID_ARGS", "text is required");
+  const { text, duration, position } = 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");
+  const d = choice(duration, DURATIONS, "short", "duration");
+  return { text, duration: d, position: choice(position, POSITIONS, "bottom", "position"), ms: TOAST_DURATION_MS[d] };
+}
+
+/**
+ * One toast at a time, in order, like Android's toast queue. `display` resolves once its toast is
+ * gone. `push` returns false when MAX_QUEUED toasts are already waiting or showing (the toast is dropped).
+ */
+export function createToastQueue(display: (item: ToastItem) => Promise<void>, max = MAX_QUEUED) {
+  const waiting: ToastItem[] = [];
+  let busy = false;
+
+  const next = () => {
+    if (busy) return;
+    const item = waiting.shift();
+    if (!item) return;
+    busy = true;
+    let shown: Promise<void>;
+    try {
+      shown = display(item);
+    } catch (error) {
+      shown = Promise.reject(error);
+    }
+    shown
+      .catch((error) => console.warn("[akan-native] toast: showing a toast failed", error))
+      .finally(() => {
+        busy = false;
+        next();
+      });
+  };
+
+  return {
+    push(item: ToastItem): boolean {
+      if (waiting.length + (busy ? 1 : 0) >= max) return false;
+      waiting.push(item);
+      next();
+      return true;
+    },
+    /** Waiting plus showing. */
+    get size(): number {
+      return waiting.length + (busy ? 1 : 0);
+    },
+  };
+}

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

@@ -0,0 +1,130 @@
+import { AkanNativeError, defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { ToastApi } from "./index.ts";
+import { checkShow, createToastQueue, MAX_QUEUED, type ToastItem } from "./queue.ts";
+
+const P = "akan-native-toast";
+const FADE_MS = 180;
+
+const CSS = `
+.${P}{all:initial;display:block;box-sizing:border-box;position:fixed;inset:auto;left:50%;z-index:2147483647;margin:0;
+padding:10px 18px;border:0;border-radius:18px;width:max-content;max-width:min(560px,calc(100vw - 32px));height:auto;overflow:hidden;
+background:rgba(38,38,40,.94);color:#fff;font:15px/1.35 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+text-align:center;white-space:pre-wrap;overflow-wrap:anywhere;box-shadow:0 6px 24px rgba(0,0,0,.24);
+pointer-events:none;user-select:none;-webkit-user-select:none;
+opacity:0;transform:translateX(-50%);translate:0 12px;transition:opacity ${FADE_MS}ms ease-out,translate ${FADE_MS}ms ease-out}
+.${P}-bottom{bottom:calc(56px + env(safe-area-inset-bottom,0px))}
+.${P}-top{top:calc(48px + env(safe-area-inset-top,0px));translate:0 -12px}
+.${P}-center{top:50%;transform:translate(-50%,-50%);translate:0 0;scale:.96;transition:opacity ${FADE_MS}ms ease-out,scale ${FADE_MS}ms ease-out}
+.${P}.${P}-on{opacity:1;translate:0 0;scale:1}
+@media (prefers-color-scheme:dark){.${P}{background:rgba(232,232,237,.96);color:#1c1c1e;box-shadow:0 6px 24px rgba(0,0,0,.5)}}
+@media (prefers-reduced-motion:reduce){.${P}{translate:0 0;scale:1;transition:opacity ${FADE_MS}ms linear}}
+.${P}-live{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}
+`;
+
+let sheet: CSSStyleSheet | null = null;
+
+function injectStyle(): void {
+  if (sheet || document.getElementById(`${P}-style`)) return;
+  if (typeof CSSStyleSheet === "function" && "adoptedStyleSheets" in document) {
+    try {
+      sheet = new CSSStyleSheet();
+      sheet.replaceSync(CSS);
+      document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+      return;
+    } catch {
+      sheet = null;
+    }
+  }
+  const style = document.createElement("style");
+  style.id = `${P}-style`;
+  style.textContent = CSS;
+  (document.head ?? document.documentElement).append(style);
+}
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+let live: HTMLElement | null = null;
+
+/** A modal <dialog> makes the rest of the page inert, live regions included. */
+function topModal(): Element | null {
+  try {
+    const open = document.querySelectorAll("dialog:modal");
+    return open.length > 0 ? open[open.length - 1]! : null;
+  } catch {
+    return null; 
+  }
+}
+
+/** The persistent live region; `fresh` when it was just (re)inserted and needs a moment to be registered. */
+function liveRegion(): { region: HTMLElement; fresh: boolean } {
+  const host = topModal() ?? document.body ?? document.documentElement;
+  if (live && live.parentNode === host) return { region: live, fresh: false };
+  if (!live) {
+    live = document.createElement("div");
+    live.className = `${P}-live`;
+    live.setAttribute("role", "status");
+    live.setAttribute("aria-live", "polite");
+    live.setAttribute("aria-atomic", "true");
+  }
+  host.append(live);
+  return { region: live, fresh: true };
+}
+
+/** Moves a bottom toast above the soft keyboard when it covers the layout viewport's bottom. */
+function liftAboveKeyboard(box: HTMLElement): void {
+  const vv = typeof visualViewport === "undefined" ? null : visualViewport;
+  if (!vv || vv.scale > 1.01) return; 
+  const covered = innerHeight - vv.offsetTop - vv.height;
+  if (covered > 80) box.style.bottom = `${Math.round(covered + 16)}px`;
+}
+
+function display(item: ToastItem): Promise<void> {
+  injectStyle();
+  const parent = document.body ?? document.documentElement;
+  const box = document.createElement("div");
+  box.className = `${P} ${P}-${item.position}`;
+  box.setAttribute("aria-hidden", "true");
+  box.textContent = item.text;
+  if (item.position === "bottom") liftAboveKeyboard(box);
+  parent.append(box);
+  const popover = typeof box.showPopover === "function";
+  if (popover) {
+    try {
+      box.popover = "manual";
+      box.showPopover();
+    } catch {
+    }
+  }
+  void box.offsetWidth; 
+  box.classList.add(`${P}-on`);
+
+  const { region, fresh } = liveRegion();
+  region.textContent = ""; 
+  const announced = wait(fresh ? 150 : 50).then(() => {
+    region.textContent = item.text;
+  });
+
+  return Promise.all([announced, wait(item.ms + FADE_MS)])
+    .then(() => {
+      box.classList.remove(`${P}-on`);
+      return wait(FADE_MS);
+    })
+    .finally(() => {
+      if (popover && box.matches(":popover-open")) box.hidePopover();
+      box.remove();
+      if (region.textContent === item.text) region.textContent = "";
+    });
+}
+
+const queue = createToastQueue(display);
+
+export const web = defineWebPlugin<ToastApi>({
+  methods: {
+    async show(options) {
+      const item = checkShow(options);
+      if (typeof document === "undefined") throw new AkanNativeError("UNSUPPORTED", "toasts need a document");
+      if (!queue.push(item))
+        console.warn(`[akan-native] toast: ${MAX_QUEUED} toasts are already queued, dropped "${item.text}"`);
+    },
+  },
+});

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

@@ -0,0 +1,10 @@
+{
+  "id": "tray",
+  "apiVersion": 1,
+  "methods": ["create", "update", "setIcon", "setTitle", "setTooltip", "setMenu", "remove", "list", "trigger"],
+  "events": ["click", "menuClick"],
+  "web": null,
+  "desktop": "./src/desktop.ts",
+  "ios": null,
+  "android": null
+}

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

@@ -0,0 +1,73 @@
+
+
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { type DesktopContext, defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import type { TrayApi, TrayEvents, TrayInfo, TrayOptions } from "./index.ts";
+
+let nextId = 1;
+
+function id(value: unknown): string {
+  if (typeof value !== "string" || value === "")
+    throw new AkanNativeError("INVALID_ARGS", "id must be a non-empty string");
+  return value;
+}
+
+const nullableString = (v: unknown) => v === undefined || v === null || typeof v === "string";
+const boolean = (v: unknown) => v === undefined || typeof v === "boolean";
+
+/** The fields given, checked; the shell changes only these. */
+function fields(args: Partial<TrayOptions>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!nullableString(args.icon)) throw new AkanNativeError("INVALID_ARGS", "icon must be a path or null");
+  if (args.title !== undefined && typeof args.title !== "string")
+    throw new AkanNativeError("INVALID_ARGS", "title must be a string");
+  if (!nullableString(args.tooltip)) throw new AkanNativeError("INVALID_ARGS", "tooltip must be a string or null");
+  if (args.menu !== undefined && args.menu !== null && !Array.isArray(args.menu))
+    throw new AkanNativeError("INVALID_ARGS", "menu must be an array of menu items or null");
+  if (!boolean(args.iconAsTemplate) || !boolean(args.menuOnLeftClick))
+    throw new AkanNativeError("INVALID_ARGS", "iconAsTemplate and menuOnLeftClick must be booleans");
+  for (const key of ["icon", "iconAsTemplate", "title", "tooltip", "menu", "menuOnLeftClick"] as const) {
+    if (args[key] !== undefined) out[key] = args[key];
+  }
+  return out;
+}
+
+const update = (ctx: DesktopContext, trayId: string, args: Partial<TrayOptions>) =>
+  ctx.shell("tray.update", { ...fields(args), id: trayId }) as Promise<TrayInfo>;
+
+export default defineDesktopPlugin<TrayApi, TrayEvents>({
+  id: "tray",
+  methods: {
+    create: (args, ctx) => {
+      const trayId = args?.id === undefined ? `tray-${nextId++}` : id(args.id);
+      return ctx.shell("tray.create", { ...fields(args ?? {}), id: trayId }) as Promise<TrayInfo>;
+    },
+    update: (args, ctx) => update(ctx, id(args?.id), args),
+    setIcon: (args, ctx) => update(ctx, id(args?.id), { icon: args.icon ?? null, iconAsTemplate: args.iconAsTemplate }),
+    setTitle: (args, ctx) => update(ctx, id(args?.id), { title: args.title }),
+    setTooltip: (args, ctx) => update(ctx, id(args?.id), { tooltip: args.tooltip ?? null }),
+    setMenu: (args, ctx) =>
+      update(ctx, id(args?.id), { menu: args.menu ?? null, menuOnLeftClick: args.menuOnLeftClick }),
+    remove: async (args, ctx) => {
+      await ctx.shell("tray.remove", { id: id(args?.id) });
+    },
+    list: (_args, ctx) => ctx.shell("tray.list") as Promise<TrayInfo[]>,
+    trigger: async (args, ctx) => {
+      if (args?.button !== undefined && args.button !== "left" && args.button !== "right")
+        throw new AkanNativeError("INVALID_ARGS", "button must be left or right");
+      await ctx.shell("tray.trigger", { id: id(args?.id), button: args.button });
+    },
+  },
+  events: {
+    
+    click: (emit, ctx) =>
+      ctx.onNativeEvent("tray", (e) => {
+        if (e.event === "click")
+          emit({ id: e.tray as string, button: e.button === "right" ? "right" : "left" }, "focused");
+      }),
+    menuClick: (emit, ctx) =>
+      ctx.onNativeEvent("tray", (e) => {
+        if (e.event === "menuClick") emit({ id: e.tray as string, item: e.item as string }, "focused");
+      }),
+  },
+});