akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/types/vendor/@akanjs/native/packages/core/src/protocol.d.ts

@@ -0,0 +1,109 @@
+import { ERROR_CODES as CONTRACT_ERROR_CODES, INIT_PREFIX, INIT_SUFFIX } from "./contract.ts";
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * What the hosts of this akan-native version speak beyond v1 (boot.json `bridge.features`, part of the UP-3
+ * fingerprint, so a web bundle never runs on a shell that lacks one):
+ * - doc: every request names its document (one page load); the host ends the previous document
+ *   when a new one calls or the main frame commits a navigation, and refuses calls of ended ones
+ * - seq: the host numbers a document's responses and events (from 1) where it sends them; the page
+ *   delivers them in that order
+ * - once: a document's request id runs at most once
+ * - cancel: `$bridge.cancel { id, reason }` ends a running call of the same document at once
+ *   (CANCELLED, or TIMEOUT for reason "timeout") and tells its plugin; `$bridge.release { url }`
+ *   drops a FileRef. Errors may carry `data` and `retryable`.
+ */
+export declare const BRIDGE_FEATURES: readonly ["doc", "seq", "once", "cancel"];
+/** Reserved method names for event subscription. */
+export declare const LISTEN = "$listen";
+export declare const UNLISTEN = "$unlisten";
+/**
+ * Reserved plugin id for the bridge's follow-up operations (v1.1 `cancel`). They act on something a
+ * call of the same page handed out, so holding it is the permission (no ACL entry):
+ * - cancel { id, reason }: the call `id` of this document ends now (reason "abort" → CANCELLED,
+ *   "timeout" → TIMEOUT); answers `{ cancelled }`, false when the call already finished
+ * - release { url }: the FileRef at `url` is no longer served; answers `{ released }`
+ */
+export declare const BRIDGE_PLUGIN = "$bridge";
+export declare const CANCEL = "cancel";
+export declare const RELEASE = "release";
+export type CancelReason = "abort" | "timeout";
+/**
+ * A plugin's method and event names (manifest, definePlugin): a letter, then letters, digits and "_".
+ * Names starting with "$" belong to the bridge ($listen, $unlisten, $bridge, $host, $console).
+ */
+export declare const MEMBER_NAME: RegExp;
+/** Method names the plugin object uses itself, or that JavaScript and React look for on any object. */
+export declare const RESERVED_MEMBERS: readonly string[];
+export declare const CANCEL_REASONS: readonly CancelReason[];
+/** The app's capabilities do not grant a call: NOT_ALLOWED (PL-11). PERMISSION_DENIED is the OS or the user saying no. */
+export type ErrorCode = (typeof CONTRACT_ERROR_CODES)[number];
+export declare const ERROR_CODES: readonly ErrorCode[];
+/** JS → host */
+export interface BridgeRequest {
+    v: 1;
+    id: number;
+    plugin: string;
+    method: string;
+    args?: unknown;
+    /** The calling document (v1.1 `doc`). The page runtime always sends it. */
+    doc?: string;
+}
+export interface BridgeErrorBody {
+    code: ErrorCode;
+    message: string;
+    /** Details a caller can act on, e.g. `{ reason: "packageManaged" }` (v1.1 `cancel`). */
+    data?: unknown;
+    /** The same call may work later (a plugin still starting, the network, a busy database). */
+    retryable?: boolean;
+}
+/** Where a host message goes and its place in the document's order (v1.1 `doc`, `seq`). */
+export interface Delivery {
+    doc?: string;
+    seq?: number;
+}
+/** host → JS, answers one request */
+export type BridgeResponse = ({
+    v: 1;
+    id: number;
+    ok: true;
+    result?: unknown;
+} & Delivery) | ({
+    v: 1;
+    id: number;
+    ok: false;
+    error: BridgeErrorBody;
+} & Delivery);
+/** host → JS, push */
+export interface BridgeEvent extends Delivery {
+    v: 1;
+    plugin: string;
+    event: string;
+    data?: unknown;
+}
+/** Arguments of the reserved $listen / $unlisten methods. */
+export interface ListenArgs {
+    event: string;
+}
+/** Large results (photos, files) are returned as a URL served by the host (PL-7). */
+export interface FileRef {
+    url: string;
+    mime: string;
+    size: number;
+}
+/** A document id: the page runtime makes 32 hex digits; hosts accept 8 to 64 of [A-Za-z0-9_-] (contract.json). */
+export declare const DOC_ID: RegExp;
+/** Validates an incoming request (SEC-3). Returns an error message or null. */
+export declare function validateRequest(value: unknown): string | null;
+export declare function isResponse(value: unknown): value is BridgeResponse;
+export declare function isEvent(value: unknown): value is BridgeEvent;
+export declare function okResponse(id: number, result?: unknown): BridgeResponse;
+export declare function errorResponse(id: number, code: ErrorCode, message: string, extra?: {
+    data?: unknown;
+    retryable?: boolean;
+}): BridgeResponse;
+export { INIT_PREFIX, INIT_SUFFIX };
+export declare function renderInitScript(bootJson: string, envJson: string): string;
+/** Reserved plugin id for forwarding page console output to the host log in dev builds (WV-3). */
+export declare const CONSOLE_PLUGIN = "$console";
+/** Reserved plugin id for shell built-ins the page runtime calls itself, e.g. `print` (plugins.md D8). */
+export declare const HOST_PLUGIN = "$host";

package/types/vendor/@akanjs/native/packages/core/src/runtime.d.ts

@@ -0,0 +1,66 @@
+import { type AkanNativeBoot } from "./boot.ts";
+import { type BridgeEvent, type BridgeRequest, type BridgeResponse, type CancelReason } from "./protocol.ts";
+/** One way to reach the host. Events always come back through `__AKAN_NATIVE__.receive`. */
+export interface Transport {
+    send(request: BridgeRequest): Promise<BridgeResponse>;
+    /** Internal diagnostics for the self-test (e.g. how many bridge ports the page adopted). */
+    info?(): Record<string, unknown>;
+}
+type Listener = (data: unknown) => void;
+interface Pending {
+    resolve(response: BridgeResponse): void;
+}
+export interface Runtime {
+    boot: AkanNativeBoot;
+    transport: Transport | null;
+    nextId: number;
+    /** Calls waiting for their response, which always comes through receive(). */
+    pending: Map<number, Pending>;
+    /** "plugin\0event" → listeners, shared by native and web event sources. */
+    listeners: Map<string, Set<Listener>>;
+    /** This document's id (bridge v1.1 `doc`), sent with every request. */
+    doc: string;
+    /** The runtime's timers (the gap timer, the next-task deferrals); tests replace them with a virtual clock. */
+    timers: Timers;
+    /** In-order delivery of host messages (v1.1 `seq`): see receive(). */
+    order: {
+        /** The next number to deliver, and later ones that came early. */
+        next: number;
+        held: Map<number, BridgeResponse | BridgeEvent>;
+        timer: unknown;
+        /** A response was delivered in this task: events wait for the next one. */
+        answered: boolean;
+        /** Messages in order that wait for the next task. */
+        later: (BridgeResponse | BridgeEvent)[];
+    };
+}
+export interface Timers {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+export declare function eventKey(plugin: string, event: string): string;
+export declare function runtime(): Runtime;
+/**
+ * macOS: WKWebView ignores window.print(), so the page asks the shell to print its window
+ * (plugins.md D8; Tauri replaces window.print the same way, tauri/crates/tauri/src/webview/scripts/print.js).
+ * Runs when @akanjs/native/core loads; init.js has already set the platform by then. Returns whether it replaced print.
+ */
+export declare function installPrint(): boolean;
+/**
+ * Dev builds: errors the page had before this module ran, collected by the snippet the build puts
+ * after init.js (__AKAN_NATIVE__.early). They go to the host log once, marked "[before runtime]"; the
+ * snippet stops collecting and does not report them itself.
+ */
+export declare function flushEarlyErrors(): void;
+/** Drops all runtime state. Only for tests. */
+export declare function resetRuntime(): void;
+export declare function dispatchEvent(rt: Runtime, plugin: string, event: string, data: unknown): void;
+/** How long later messages wait for a missing number before they are delivered anyway. */
+export declare const SEQ_GAP_MS = 500;
+/**
+ * The page gave up on a call that has no answer yet (its AbortSignal fired, v1.1 `cancel`): it stops
+ * waiting now, and the host is told so that the plugin can stop and the call's resources go. The
+ * host's late answer finds no pending call and is dropped.
+ */
+export declare function cancelCall(rt: Runtime, id: number, reason: CancelReason): void;
+export {};

package/types/vendor/@akanjs/native/packages/core/src/state.d.ts

@@ -0,0 +1,28 @@
+import type { AppInfo, Platform } from "./boot.ts";
+/**
+ * The PUBLIC_ keys the app's config and .env files define. `akan-native build` writes akan-native-env.d.ts next
+ * to akan-native.config.ts, which adds them to this interface (ENV-7).
+ */
+export interface AkanNativeEnv {
+}
+/**
+ * Known keys from AkanNativeEnv; other keys (set only at run time through AKAN_NATIVE_PUBLIC_*) stay a plain
+ * index signature, so with noUncheckedIndexedAccess they read as string | undefined.
+ */
+export type Env = Readonly<AkanNativeEnv> & Readonly<Record<string, string>>;
+export declare let platform: Platform;
+export declare let env: Env;
+export declare let runtimeVersion: string;
+export declare let app: AppInfo | null;
+export declare let isDev: boolean;
+/** True inside an akan-native app shell (macOS, iOS, Android ...), false on the web. */
+export declare let isNative: boolean;
+/** Desktop: this page's window (1 = the window the app opened, SH-6). null elsewhere. */
+export declare let windowId: number | null;
+/**
+ * Native hosts: a fingerprint of what this app binary provides natively (bridge protocol, akan-native
+ * runtime minor, plugins, capabilities, permissions). A web bundle runs only in a binary with the
+ * same value (UP-3). null on the web.
+ */
+export declare let nativeApi: string | null;
+export declare function refreshBoot(): void;

package/types/vendor/@akanjs/native/packages/core/src/testing.d.ts

@@ -0,0 +1,41 @@
+import { type CallScope, type ResolvedAcl } from "./acl.ts";
+import type { Platform } from "./boot.ts";
+import { type BridgeRequest } from "./protocol.ts";
+/**
+ * `scope`: what the app's capabilities allow this call (PL-11), as a real host passes it. `signal`
+ * fires when the page cancels the call ($bridge.cancel), like a desktop plugin's ctx.signal.
+ */
+export type MockMethod = (args: any, host: MockHost, scope?: CallScope, signal?: AbortSignal) => unknown;
+export interface MockPlugin {
+    methods?: Record<string, MockMethod>;
+    events?: string[];
+    /** The other methods and events use the web implementation (a native subset with `web: true`). */
+    web?: true;
+}
+export interface MockHostOptions {
+    platform?: Platform;
+    env?: Record<string, string>;
+    dev?: boolean;
+    /** "web" makes the page use the plugin's web implementation, as a desktop host may declare. */
+    plugins?: Record<string, MockPlugin | "web">;
+    /** Capabilities (PL-11): the mock host enforces them like a real host, and the page sees them in boot. */
+    acl?: ResolvedAcl;
+    /** The page's window id (desktop multi-window). Default 1. */
+    windowId?: number;
+}
+export interface MockHost {
+    readonly requests: BridgeRequest[];
+    /** $bridge.cancel requests the page sent: the call id and the reason. */
+    readonly cancels: {
+        id: number;
+        reason: string;
+        cancelled: boolean;
+    }[];
+    /** $bridge.release requests: the FileRef URLs (answered released: true). */
+    readonly releases: string[];
+    /** Pushes an event the way a native host would. Delivered only while subscribed. */
+    emit(plugin: string, event: string, data?: unknown): boolean;
+    subscriptions(plugin: string, event: string): number;
+    uninstall(): void;
+}
+export declare function installMockHost(options?: MockHostOptions): MockHost;

package/types/vendor/@akanjs/native/packages/core/src/version.d.ts

@@ -0,0 +1,2 @@
+/** The runtime version (UP-3): builtin plugins share it, and OTA updates compare its line. */
+export declare const VERSION = "0.1.0";

package/types/vendor/@akanjs/native/packages/core/src/veto.d.ts

@@ -0,0 +1,17 @@
+export interface VetoEvent {
+    /** Keeps the window open / the app running. Call it before the handler returns (await first if needed). */
+    preventDefault(): void;
+    readonly defaultPrevented: boolean;
+}
+export type VetoHandler<E> = (event: E & VetoEvent) => void | Promise<void>;
+/**
+ * Builds an `onX(handler)` registration for a cancelable event.
+ * `listen` subscribes to the plugin event; `answer` is the plugin method the host waits for.
+ * Registering is a no-op where the event is not supported (it simply never fires).
+ */
+export declare function vetoable<E extends object>(listen: (listener: (data: E & {
+    id: number;
+}) => void) => () => void, answer: (args: {
+    id: number;
+    allow?: boolean;
+}) => Promise<unknown>): (handler: VetoHandler<E>) => () => void;

package/types/vendor/@akanjs/native/packages/core/src.d.ts

@@ -0,0 +1 @@
+export * from "./src/index.d.ts";

package/types/vendor/@akanjs/native/packages/desktop/src/deeplinks.d.ts

@@ -0,0 +1,24 @@
+type Env = Record<string, string | undefined>;
+type Runner = (argv: string[]) => Promise<{
+    code: number;
+    stdout: string;
+}>;
+/** The links in a launch's arguments (without the executable): one argument, of an app scheme. */
+export declare function linkArguments(args: readonly string[], schemes: readonly string[]): string[];
+/** Exec= of a desktop entry: the path quoted, with the characters the spec reserves escaped. */
+export declare function desktopExec(exe: string): string;
+export declare function desktopEntry(name: string, exe: string, schemes: readonly string[]): string;
+/** mimeapps.list with `x-scheme-handler/<scheme>=<desktop file>` set in [Default Applications]. */
+export declare function withDefaults(list: string, desktopFile: string, schemes: readonly string[]): string;
+/** Makes this executable the current user's handler of the app's schemes (Windows, Linux). */
+export declare function registerDeepLinks(app: {
+    id: string;
+    name: string;
+}, schemes: readonly string[], options?: {
+    exe?: string;
+    platform?: NodeJS.Platform;
+    env?: Env;
+    home?: string;
+    run?: Runner;
+}): Promise<void>;
+export {};

package/types/vendor/@akanjs/native/packages/desktop/src/delta.d.ts

@@ -0,0 +1,2 @@
+export declare function createDelta(oldData: Uint8Array, newData: Uint8Array): Uint8Array<ArrayBuffer>;
+export declare function applyDelta(oldData: Uint8Array, delta: Uint8Array): Uint8Array<ArrayBuffer>;

package/types/vendor/@akanjs/native/packages/desktop/src/dispatcher.d.ts

@@ -0,0 +1,95 @@
+import type { AppInfo, FileRef, ResolvedAcl } from "../../core/src/index.ts";
+import { type BridgeEvent, type BridgeRequest, type BridgeResponse } from "../../core/src/protocol.ts";
+import type { Lifecycle } from "./lifecycle.ts";
+import type { DesktopPlugin, Launch, NativeEvent } from "./plugin.ts";
+/** How long the window waits for one plugin's setup. */
+export declare const SETUP_TIMEOUT_MS = 3000;
+/**
+ * How long a page's call to a plugin whose setup is still running (it outlasted SETUP_TIMEOUT_MS)
+ * waits for it before it is answered INTERNAL with `retryable`.
+ */
+export declare const SETUP_WAIT_MS = 5000;
+export interface HostServices {
+    app: AppInfo;
+    appDataDir: string;
+    /** Sends an event (numbered for its document) to a window's page. */
+    emit(window: number, message: BridgeEvent): void;
+    /**
+     * Reserved plugin ids the host answers itself ($console, $host): the result, or a throw. `signal`
+     * fires when the page cancels the call or goes away.
+     */
+    builtins?: Record<string, (req: BridgeRequest, window: number, signal: AbortSignal) => unknown>;
+    /** Windows by last focus, most recent first (SH-6). For EmitTarget "focused". */
+    focusOrder?(): number[];
+    registerFile(path: string, mime: string): FileRef;
+    /** Stops serving a FileRef ($bridge.release). False when the URL is not one of this session's. */
+    releaseFile?(url: string): boolean;
+    shell?(op: string, args?: Record<string, unknown>): Promise<unknown>;
+    onNativeEvent?(type: string, listener: (event: NativeEvent) => void): () => void;
+    deepLinkSchemes?: readonly string[];
+    /** security.shell.externalSchemes from shell.json (L0). */
+    externalSchemes?: readonly string[];
+    openLinks?(args: readonly string[]): void;
+    quit?(code: number): void;
+    /** Quit and close sequence (lifecycle.ts). Without it, quit() ends the app at once and nothing can veto. */
+    lifecycle?: Lifecycle;
+}
+export interface Dispatcher {
+    /** Every plugin's setup finished (or ran out of time): what the window should look like, or exit. */
+    launched: Promise<Launch>;
+    /** Handles one request body (JSON text) from a window's page and returns the response. Never throws. */
+    handle(body: string, window?: number): Promise<BridgeResponse>;
+    /**
+     * A window's page (re)loaded or the window is gone: its document ends, its subscriptions are
+     * gone, and event sources nobody listens to any more stop. Without a window: every page.
+     */
+    reset(window?: number): void;
+    /** Sends an event to a window's current document whether or not it listens (host built-ins). */
+    emitTo(window: number, plugin: string, event: string, data?: unknown): void;
+    /** Table sizes for the document churn check (K13, dev $host.info). */
+    stats(): DispatcherStats;
+}
+export interface DispatcherStats {
+    documents: number;
+    /** Ended document ids remembered, all windows. */
+    ended: number;
+    /** $listen counts, all windows and events. */
+    subscriptions: number;
+    /** Event sources running. */
+    sources: number;
+    /** Calls not answered yet. */
+    running: number;
+    /** Resources owned by live documents (ctx.document.own). */
+    resources: number;
+    /** ctx.onDocumentEnd listeners. */
+    documentListeners: number;
+}
+/**
+ * A document's request ids (bridge v1.1 `once`): each is accepted once. The page numbers its
+ * requests upward, but they arrive over HTTP and can overtake each other, so the recent ids are
+ * kept in a set and older ones are covered by a floor.
+ */
+export declare class CallIds {
+    private floor;
+    private readonly seen;
+    /** Whether the id was received (or is older than what is remembered). */
+    has(id: number): boolean;
+    accept(id: number): boolean;
+}
+/**
+ * How long a coalescing event (manifest `coalesce`, architecture review stage 4) waits for a newer one
+ * before it is sent: about 10 per second at most.
+ */
+export declare const COALESCE_MS = 100;
+export interface DispatcherOptions {
+    setupTimeoutMs?: number;
+    setupWaitMs?: number;
+    /** The app's resolved capabilities from boot.json (PL-11). Absent: everything is allowed. */
+    acl?: ResolvedAcl | null;
+    /**
+     * boot.json `plugins` (L2 declaration gate): a method or event a plugin does not declare for this
+     * platform is NOT_FOUND before the ACL and the plugin, whatever its module implements. Absent: no gate (tests).
+     */
+    declarations?: Record<string, unknown>;
+}
+export declare function createDispatcher(plugins: DesktopPlugin[], services: HostServices, options?: DispatcherOptions): Dispatcher;

package/types/vendor/@akanjs/native/packages/desktop/src/ffi.d.ts

@@ -0,0 +1,144 @@
+export interface DesktopPaths {
+    /** The native library: libakan_native_desktop.dylib, akan_native_desktop.dll or libakan_native_desktop.so */
+    lib: string;
+    /** boot.json, env.runtime.json, shell.json, app/ (platforms/desktop.ts in the CLI) */
+    resources: string;
+    appDir: string;
+}
+/**
+ * Paths relative to the executable, as the CLI lays them out (packages/cli/src/platforms/*.ts):
+ *   macOS    <App>.app/Contents/MacOS/<exe>, Frameworks/libakan_native_desktop.dylib, Resources/
+ *   Windows  <App>\<exe>.exe, akan_native_desktop.dll, resources\
+ *   Linux    <app>/<exe>, lib/libakan_native_desktop.so, resources/
+ * process.execPath is absolute even when the app is started with `open` (cwd = /) or through a
+ * symlink. Nothing in the environment overrides them: the app would load whatever library a
+ * variable (or a .env file next to it, before the build turned autoloading off) names.
+ */
+export declare function resolvePaths(platform?: NodeJS.Platform, execPath?: string): DesktopPaths;
+/** The C ABI major version this code speaks (lib.rs ABI >> 16). */
+export declare const ABI_MAJOR = 0;
+export declare const SYMBOLS: {
+    readonly akan_native_abi: {
+        readonly args: readonly [];
+        readonly returns: "u32";
+    };
+    readonly akan_native_init: {
+        readonly args: readonly ["u8"];
+        readonly returns: "i32";
+    };
+    readonly akan_native_last_error: {
+        readonly args: readonly ["ptr", "u64"];
+        readonly returns: "u64";
+    };
+    readonly akan_native_run: {
+        readonly args: readonly ["ptr"];
+        readonly returns: "i32";
+    };
+    readonly akan_native_set_wake: {
+        readonly args: readonly ["ptr"];
+        readonly returns: "void";
+    };
+    readonly akan_native_poll: {
+        readonly args: readonly ["ptr", "u32"];
+        readonly returns: "u32";
+    };
+    readonly akan_native_respond: {
+        readonly args: readonly ["u64", "u16", "ptr", "ptr", "u32"];
+        readonly returns: "void";
+    };
+    readonly akan_native_emit: {
+        readonly args: readonly ["u32", "ptr"];
+        readonly returns: "void";
+    };
+    readonly akan_native_register_file: {
+        readonly args: readonly ["ptr", "ptr", "ptr"];
+        readonly returns: "void";
+    };
+    readonly akan_native_unregister_file: {
+        readonly args: readonly ["ptr"];
+        readonly returns: "u8";
+    };
+    readonly akan_native_quit: {
+        readonly args: readonly ["i32"];
+        readonly returns: "void";
+    };
+    readonly akan_native_quit_cancel: {
+        readonly args: readonly [];
+        readonly returns: "void";
+    };
+    readonly akan_native_external_open_allowed: {
+        readonly args: readonly [];
+        readonly returns: "u8";
+    };
+    readonly akan_native_shell: {
+        readonly args: readonly ["u64", "ptr"];
+        readonly returns: "void";
+    };
+};
+export declare function openNative(libPath: string): import("bun:ffi").Library<{
+    readonly akan_native_abi: {
+        readonly args: readonly [];
+        readonly returns: "u32";
+    };
+    readonly akan_native_init: {
+        readonly args: readonly ["u8"];
+        readonly returns: "i32";
+    };
+    readonly akan_native_last_error: {
+        readonly args: readonly ["ptr", "u64"];
+        readonly returns: "u64";
+    };
+    readonly akan_native_run: {
+        readonly args: readonly ["ptr"];
+        readonly returns: "i32";
+    };
+    readonly akan_native_set_wake: {
+        readonly args: readonly ["ptr"];
+        readonly returns: "void";
+    };
+    readonly akan_native_poll: {
+        readonly args: readonly ["ptr", "u32"];
+        readonly returns: "u32";
+    };
+    readonly akan_native_respond: {
+        readonly args: readonly ["u64", "u16", "ptr", "ptr", "u32"];
+        readonly returns: "void";
+    };
+    readonly akan_native_emit: {
+        readonly args: readonly ["u32", "ptr"];
+        readonly returns: "void";
+    };
+    readonly akan_native_register_file: {
+        readonly args: readonly ["ptr", "ptr", "ptr"];
+        readonly returns: "void";
+    };
+    readonly akan_native_unregister_file: {
+        readonly args: readonly ["ptr"];
+        readonly returns: "u8";
+    };
+    readonly akan_native_quit: {
+        readonly args: readonly ["i32"];
+        readonly returns: "void";
+    };
+    readonly akan_native_quit_cancel: {
+        readonly args: readonly [];
+        readonly returns: "void";
+    };
+    readonly akan_native_external_open_allowed: {
+        readonly args: readonly [];
+        readonly returns: "u8";
+    };
+    readonly akan_native_shell: {
+        readonly args: readonly ["u64", "ptr"];
+        readonly returns: "void";
+    };
+}>;
+/** The native library's last error (akan_native_last_error), or "". */
+export declare function lastError(lib: NativeLib): string;
+export type NativeLib = ReturnType<typeof openNative>;
+/** NUL-terminated UTF-8. Native code copies it during the call, so it may be collected afterwards. */
+export declare const cstr: (text: string) => Uint8Array<ArrayBuffer>;
+/** Message kinds in akan_native_poll frames: [u8 kind][u64 reqId LE][u32 webviewId LE][body]. */
+export declare const FRAME_IPC = 1;
+export declare const FRAME_EVENT = 2;
+export declare const FRAME_HEADER = 13;

package/types/vendor/@akanjs/native/packages/desktop/src/host.d.ts

@@ -0,0 +1,11 @@
+import { AkanNativeError } from "../../core/src/index.ts";
+import { type DesktopPlugin } from "./plugin.ts";
+/** A drain handles at most this many frames, or runs this long, before it yields (see drain). */
+export declare const DRAIN_FRAMES = 256;
+export declare const DRAIN_MS = 4;
+/**
+ * A failed shell op. Ops may name the error code first ("UNSUPPORTED: no tray on this desktop");
+ * other messages are about the arguments.
+ */
+export declare function shellError(message: string): AkanNativeError;
+export declare function startHost(plugins: DesktopPlugin[]): void;

package/types/vendor/@akanjs/native/packages/desktop/src/lifecycle.d.ts

@@ -0,0 +1,40 @@
+export type QuitReason = "user" | "session" | "lastWindowClosed";
+/** Return false (or resolve to false) to keep the app running / the window open. */
+export type Veto<E> = (event: E) => boolean | void | Promise<boolean | void>;
+export interface LifecycleOptions {
+    quitOnLastWindowClosed: boolean;
+    /** Ends the process (akan_native_quit). */
+    exit(code: number): void;
+    /** The app stays after a logout asked it to quit (akan_native_quit_cancel). */
+    cancelSessionEnd(): void;
+    /** Hides the last window instead of quitting (quitOnLastWindowClosed: false). */
+    hideWindow(window: number): Promise<unknown>;
+    /** Destroys a window that is not the last one. */
+    destroyWindow?(window: number): Promise<unknown>;
+    /** The windows that exist, hidden ones included. Default: only the one being closed. */
+    windows?(): Promise<number[]>;
+    /** How long quit() waits for the onQuit hooks, all together. Default QUIT_HOOK_TIMEOUT. */
+    quitHookTimeout?: number;
+}
+export interface Lifecycle {
+    onQuit(fn: () => void | Promise<void>): () => void;
+    onBeforeQuit(fn: Veto<{
+        reason: QuitReason;
+    }>): () => void;
+    onCloseRequested(fn: Veto<{
+        window: number;
+    }>): () => void;
+    /** A window's close button or Cmd+W: asks the close vetoes, then closeWindow(window). */
+    closeRequested(window?: number): Promise<void>;
+    /**
+     * Closes a window without asking: destroys it while another window exists, else a quit
+     * request, or hide (quitOnLastWindowClosed: false).
+     */
+    closeWindow(window?: number): Promise<void>;
+    /** Asks the quit vetoes, then quits. Resolves true when the app quits. */
+    requestQuit(reason: QuitReason): Promise<boolean>;
+    /** Quits without asking: onQuit hooks, then exit. */
+    quit(code?: number): Promise<void>;
+}
+export declare const QUIT_HOOK_TIMEOUT = 2000;
+export declare function createLifecycle(options: LifecycleOptions): Lifecycle;

package/types/vendor/@akanjs/native/packages/desktop/src/main.d.ts

@@ -0,0 +1,4 @@
+import type { LaunchWindow } from "./plugin.ts";
+/** The launch phase's window bounds that akan_native_run understands (x and y only together). */
+export declare function launchBounds(window: LaunchWindow): LaunchWindow;
+export declare function startMain(workerUrl: string): Promise<never>;

package/types/vendor/@akanjs/native/packages/desktop/src/page-veto.d.ts

@@ -0,0 +1,17 @@
+import type { DesktopContext, EmitTarget } from "./plugin.ts";
+export declare const PAGE_ACK_TIMEOUT = 2000;
+export interface PageVeto<D> {
+    readonly listening: boolean;
+    /**
+     * The plugin's event source: `events: { closeRequested: (emit, ctx) => veto.source(emit, ctx) }`.
+     * With `ctx`, a page that reloads or whose window is destroyed while asked drops the request.
+     */
+    source(emit: (data: D & {
+        id: number;
+    }, target?: EmitTarget) => number[] | unknown, ctx?: DesktopContext): () => void;
+    /** Resolves false if a page called preventDefault(). */
+    ask(data: D, target?: EmitTarget): Promise<boolean>;
+    /** The plugin method the pages answer with: { id, allow? }, from `window` (ctx.window). */
+    answer(args: unknown, window?: number): void;
+}
+export declare function createPageVeto<D extends object = {}>(ackTimeout?: number): PageVeto<D>;

package/types/vendor/@akanjs/native/packages/desktop/src/paths.d.ts

@@ -0,0 +1,25 @@
+type Env = Record<string, string | undefined>;
+/**
+ * Settings and state the app keeps (preferences, window state, files):
+ *   macOS    ~/Library/Application Support/<id>
+ *   Windows  %APPDATA%\<id>          (Roaming: follows the user between PCs)
+ *   Linux    $XDG_DATA_HOME/<id>     (~/.local/share/<id>)
+ */
+export declare function appDataDir(id: string, platform?: NodeJS.Platform, env?: Env, home?: string): string;
+/**
+ * The webview's own storage and caches (Windows, Linux; WKWebView chooses its own on macOS):
+ *   Windows  %LOCALAPPDATA%\<id>\WebView2   (large and machine-specific: not Roaming)
+ *   Linux    $XDG_DATA_HOME/<id>/webview
+ * WebView2's default would be next to the .exe, which is not writable once installed.
+ */
+export declare function webviewDataDir(id: string, platform?: NodeJS.Platform, env?: Env, home?: string): string | undefined;
+/**
+ * Folders whose files no FileRef may serve (L4): the shell's and the plugins' own storage
+ * (preferences, secure storage, databases, update bundles, window state, the webview's data). Only
+ * the filesystem plugin's `data` base (<app data>/files) is servable inside the app data folder.
+ */
+export declare function reservedDirs(id: string, platform?: NodeJS.Platform, env?: Env, home?: string): {
+    root: string;
+    except: string[];
+}[];
+export {};