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

package/types/vendor/@akanjs/native/plugins/clipboard/src/index.d.ts

@@ -0,0 +1,40 @@
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+/**
+ * Plain text on the system clipboard.
+ *
+ * readText resolves `{ text: "" }` when the clipboard holds no text. It may reject:
+ * - PERMISSION_DENIED
+ *   - iOS 16+: the user answered "Don't Allow" to the paste prompt, shown when another app copied the text
+ *   - Android 10+: the app does not have window focus
+ *   - web: the browser refused (Chrome asks for clipboard-read permission, Safari and Firefox show a
+ *     "Paste" button that must be clicked, both need a user gesture)
+ * - UNSUPPORTED on the web without `navigator.clipboard.readText` (insecure http:// origin, older browsers)
+ *
+ * writeText needs a user gesture on the web (and a focused document in Chrome); without
+ * `navigator.clipboard` it falls back to `execCommand("copy")`, which also needs the gesture.
+ */
+export interface ClipboardApi {
+    writeText(args: {
+        text: string;
+    }): Promise<void>;
+    readText(): Promise<{
+        text: string;
+    }>;
+}
+export declare const clipboard: import("../../../packages/core/src/plugin.ts").Plugin<ClipboardApi, {}>;
+export interface UseClipboard {
+    supported: boolean;
+    /** True for `resetAfter` ms after a successful copy, for "Copied" feedback next to the button. */
+    copied: boolean;
+    /** Last copy failure. */
+    error: AkanNativeError | null;
+    /** Copies text; resolves false (and sets `error`) instead of throwing. */
+    copy(text: string): Promise<boolean>;
+}
+/**
+ * Copy-button helper. Android 13+ already shows a system confirmation after copying, so show
+ * `copied` in place (e.g. the button label) rather than as an extra toast.
+ */
+export declare function useClipboard(options?: {
+    resetAfter?: number;
+}): UseClipboard;

package/types/vendor/@akanjs/native/plugins/clipboard/src/web.d.ts

@@ -0,0 +1,2 @@
+import type { ClipboardApi } from "./index.ts";
+export declare const web: import("../../../packages/core/src/plugin.ts").WebPlugin<ClipboardApi, {}>;

package/types/vendor/@akanjs/native/plugins/clipboard/src.d.ts

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

package/types/vendor/@akanjs/native/plugins/device/src/desktop.d.ts

@@ -0,0 +1,33 @@
+import type { BatteryInfo, DeviceApi } from "./index.ts";
+/** A <string> value from an XML property list (SystemVersion.plist and Safari's Info.plist are XML). */
+export declare function plistString(xml: string, key: string): string | null;
+/**
+ * `pmset -g batt`, e.g.
+ *   Now drawing from 'AC Power'
+ *    -InternalBattery-0 (id=22806627)	100%; charged; 0:00 remaining present: true
+ * Desktop Macs print only the first line (a UPS may add its own line, which is not the Mac's battery).
+ */
+export declare function parsePmset(out: string): BatteryInfo;
+/** The first entry of `defaults read -g AppleLanguages`: ( "en-KR", en, ... ). */
+export declare function parseAppleLanguages(out: string): string | null;
+/** One entry of /sys/class/power_supply: the attribute files it has (sysfs-class-power ABI). */
+export type PowerSupply = Partial<Record<"type" | "scope" | "status" | "capacity" | "online" | "energy_now" | "energy_full" | "charge_now" | "charge_full", string>>;
+/**
+ * The system's batteries (type Battery; scope Device is a mouse or headset) as one reading: the
+ * summed energy (or charge) where every battery reports it, else the mean capacity. Connected to
+ * power: a mains or USB supply online, else the batteries' status ("Not charging" is a full or
+ * held battery on AC, as macOS's "AC attached").
+ */
+export declare function parsePowerSupplies(supplies: PowerSupply[]): BatteryInfo;
+/**
+ * The user's language from the POSIX locale variables, in gettext's order for messages:
+ * LANGUAGE (a list), LC_ALL, LC_MESSAGES, LANG. "ko_KR.UTF-8" → "ko-KR", "sr_RS@latin" →
+ * "sr-Latn-RS"; C and POSIX are no language.
+ */
+export declare function posixLanguage(env: Record<string, string | undefined>): string | null;
+/** Vendor and product names of hypervisors in DMI/SMBIOS (QEMU, KVM, VMware, VirtualBox, Hyper-V, Parallels, Xen, Apple's Virtualization framework). */
+export declare function isVirtualMachine(manufacturer: string, model: string): boolean;
+/** `platform` and `root` (prefix of /sys, /proc) are replaceable so tests can read a fake Linux on any OS. */
+export declare function createDesktopDevice(platform?: NodeJS.Platform, root?: string, env?: Record<string, string | undefined>): import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<DeviceApi, {}>;
+declare const _default: import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<DeviceApi, {}>;
+export default _default;

package/types/vendor/@akanjs/native/plugins/device/src/index.d.ts

@@ -0,0 +1,55 @@
+import { type Platform } from "../../../packages/core/src/index.ts";
+export interface DeviceInfo {
+    /** The akan-native platform: "web" in a browser, otherwise the app host. */
+    platform: Platform;
+    /** Hardware model identifier, e.g. "iPhone17,1", "Pixel 9", "Mac16,7". Best effort on the web. */
+    model: string;
+    /** e.g. "Apple", "Google", "samsung". "unknown" where the host cannot tell (most browsers). */
+    manufacturer: string;
+    /** "iOS", "iPadOS", "Android", "macOS", "Windows", "Linux", "ChromeOS" or "unknown". */
+    osName: string;
+    /** e.g. "26.0", "16". Browsers freeze the version in the user agent, so it may be stale on the web. */
+    osVersion: string;
+    /**
+     * True in the iOS simulator, the Android emulator and virtual machines (macOS: the hypervisor
+     * flag; Windows and Linux: the firmware's vendor and product names, and the CPU's hypervisor flag
+     * on Linux). Always false on the web.
+     */
+    isVirtual: boolean;
+    /**
+     * Version of the engine rendering the page: WebKit ships with iOS, the WebView package on Android,
+     * Safari on macOS, the WebView2 runtime on Windows, WebKitGTK on Linux, the browser on the web.
+     */
+    webViewVersion: string | null;
+}
+export interface BatteryInfo {
+    /** Charge from 0 to 1, or null without a battery (iOS simulator, desktop Macs) or a reading. iOS reports 5% steps. */
+    level: number | null;
+    /** True while connected to power (charging or full), null without a battery. */
+    charging: boolean | null;
+}
+export interface DeviceApi {
+    getInfo(): Promise<DeviceInfo>;
+    /**
+     * A stable identifier for this app on this device. Not a hardware id:
+     * iOS identifierForVendor (reset when all of the vendor's apps are removed), Android ANDROID_ID
+     * (differs per signing key and user), desktop and web a random UUID stored with the app data.
+     */
+    getId(): Promise<{
+        identifier: string;
+    }>;
+    /**
+     * The user's preferred language as a BCP 47 tag ("ko-KR", "zh-Hans-CN") and its language subtag ("ko").
+     * Prefer this over navigator.language inside apps: WKWebView answers from the app bundle's
+     * localizations, not the user's language list (an app without any reports "en-US"; verified on macOS).
+     */
+    getLanguage(): Promise<{
+        tag: string;
+        code: string;
+    }>;
+    /** Rejects UNSUPPORTED where the host cannot read the battery (Safari, Firefox). */
+    getBattery(): Promise<BatteryInfo>;
+}
+export declare const device: import("../../../packages/core/src/plugin.ts").Plugin<DeviceApi, {}>;
+/** Device information, or null until it has loaded. */
+export declare function useDeviceInfo(): DeviceInfo | null;

package/types/vendor/@akanjs/native/plugins/device/src/web.d.ts

@@ -0,0 +1,22 @@
+import type { DeviceApi } from "./index.ts";
+export interface UserAgentFields {
+    osName: string;
+    osVersion: string;
+    model: string;
+    manufacturer: string;
+    browserVersion: string | null;
+}
+/** OS and browser from a user agent string. `touchPoints` tells iPads in desktop mode from Macs. */
+export declare function parseUserAgent(ua: string, touchPoints?: number): UserAgentFields;
+interface HighEntropyValues {
+    model?: string;
+    platformVersion?: string;
+    fullVersionList?: {
+        brand: string;
+        version: string;
+    }[];
+}
+/** Applies Client Hints on top of the user agent fields. */
+export declare function applyClientHints(fields: UserAgentFields, hints: HighEntropyValues): UserAgentFields;
+export declare const web: import("../../../packages/core/src/plugin.ts").WebPlugin<DeviceApi, {}>;
+export {};

package/types/vendor/@akanjs/native/plugins/device/src.d.ts

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

package/types/vendor/@akanjs/native/plugins/dialog/src/desktop.d.ts

@@ -0,0 +1,3 @@
+import type { DialogApi } from "./index.ts";
+declare const _default: import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<DialogApi, {}>;
+export default _default;

package/types/vendor/@akanjs/native/plugins/dialog/src/index.d.ts

@@ -0,0 +1,60 @@
+export interface AlertOptions {
+    title?: string;
+    /** Required; may be "" when there is a title. */
+    message: string;
+    /** Default: "OK" (the OS's localized OK on iOS and Android). */
+    buttonTitle?: string;
+}
+export interface ConfirmOptions {
+    title?: string;
+    message: string;
+    okButtonTitle?: string;
+    cancelButtonTitle?: string;
+}
+export interface ConfirmResult {
+    /** true only for the OK button. */
+    value: boolean;
+}
+export interface PromptOptions extends ConfirmOptions {
+    inputPlaceholder?: string;
+    /** Text the field starts with. */
+    inputText?: string;
+}
+export interface PromptResult {
+    /** The text as typed (not trimmed). "" when cancelled. */
+    value: string;
+    cancelled: boolean;
+}
+export type ActionSheetOptionStyle = "default" | "destructive" | "cancel";
+export interface ActionSheetOption {
+    title: string;
+    /**
+     * "destructive" is shown in red. At most one option may be "cancel": it is shown apart
+     * (iOS hides it on iPhone and iPad and cancels on a tap outside instead) and choosing it
+     * answers `{ index: -1, cancelled: true }` like any other dismissal.
+     */
+    style?: ActionSheetOptionStyle;
+}
+export interface ActionSheetOptions {
+    title?: string;
+    message?: string;
+    /** At least one. */
+    options: ActionSheetOption[];
+}
+export interface ActionSheetResult {
+    /** Index into `options` of the chosen option, or -1 when cancelled. */
+    index: number;
+    cancelled: boolean;
+}
+export interface DialogApi {
+    alert(options: AlertOptions): Promise<void>;
+    confirm(options: ConfirmOptions): Promise<ConfirmResult>;
+    prompt(options: PromptOptions): Promise<PromptResult>;
+    actionSheet(options: ActionSheetOptions): Promise<ActionSheetResult>;
+}
+export declare const dialog: import("../../../packages/core/src/plugin.ts").Plugin<DialogApi, {}>;
+export interface UseDialog extends DialogApi {
+    supported: boolean;
+}
+/** The dialog functions for components. They hold no state, so they are stable across renders. */
+export declare function useDialog(): UseDialog;

package/types/vendor/@akanjs/native/plugins/dialog/src/options.d.ts

@@ -0,0 +1,29 @@
+import type { ActionSheetOption, ActionSheetOptionStyle, ActionSheetOptions, AlertOptions, ConfirmOptions, PromptOptions } from "./index.ts";
+export declare const OPTION_STYLES: readonly ActionSheetOptionStyle[];
+/** Web defaults. The native hosts use the OS's localized OK / Cancel instead. */
+export declare const DEFAULT_OK = "OK";
+export declare const DEFAULT_CANCEL = "Cancel";
+export interface NormalizedAlert {
+    title: string;
+    message: string;
+    buttonTitle: string;
+}
+export interface NormalizedConfirm {
+    title: string;
+    message: string;
+    okButtonTitle: string;
+    cancelButtonTitle: string;
+}
+export interface NormalizedPrompt extends NormalizedConfirm {
+    inputPlaceholder: string;
+    inputText: string;
+}
+export interface NormalizedActionSheet {
+    title: string;
+    message: string;
+    options: Required<ActionSheetOption>[];
+}
+export declare function normalizeAlert(args: AlertOptions | undefined): NormalizedAlert;
+export declare function normalizeConfirm(args: ConfirmOptions | undefined, method?: string): NormalizedConfirm;
+export declare function normalizePrompt(args: PromptOptions | undefined): NormalizedPrompt;
+export declare function normalizeActionSheet(args: ActionSheetOptions | undefined): NormalizedActionSheet;

package/types/vendor/@akanjs/native/plugins/dialog/src/web.d.ts

@@ -0,0 +1,2 @@
+import type { DialogApi } from "./index.ts";
+export declare const web: import("../../../packages/core/src/plugin.ts").WebPlugin<DialogApi, {}>;

package/types/vendor/@akanjs/native/plugins/dialog/src.d.ts

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

package/types/vendor/@akanjs/native/plugins/dock/src/desktop.d.ts

@@ -0,0 +1,3 @@
+import type { DockApi } from "./index.ts";
+declare const _default: import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<DockApi, {}>;
+export default _default;

package/types/vendor/@akanjs/native/plugins/dock/src/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The app's Dock icon on macOS, its taskbar buttons on Windows and its launcher entry on Linux
+ * (plugins.md §5): a badge, a progress bar, and whether the app has a Dock icon at all.
+ *
+ * - Everything is app-wide and outlives the page: after a reload, read it back with getState().
+ * - setBadge: any short text ("3", "!", "new"); null or "" removes it. Numbers read best.
+ * - setProgress: 0..1, drawn as a bar over the icon in whole percents; null hides it. `state`
+ *   colors it: normal (blue), paused (yellow), error (red). There is no indeterminate bar on macOS.
+ * - setVisible(false): no Dock icon, not in Cmd+Tab, no menu bar (keyboard shortcuts of the app
+ *   menu still work); windows stay open. For apps that live in the menu bar (tray plugin).
+ *   `policy` also reports "prohibited", the state `akan-native test` starts the app in.
+ * - Windows: every window's taskbar button. setBadge draws the label on a red disc as the overlay
+ *   icon (counts over 99 as "99+", other labels longer than 2 characters as a plain disc),
+ *   setProgress is the button's progress bar in the same three colors, setVisible(false) takes
+ *   the buttons away (policy "accessory"; the windows stay in Alt+Tab).
+ * - Linux: the launcher entry of the desktop file "<app id>.desktop" (the Unity LauncherEntry
+ *   API, which Ubuntu's dock, Dash to Dock and KDE Plasma show): setBadge takes whole numbers
+ *   only (other labels reject UNSUPPORTED), setProgress draws paused and error like normal, and
+ *   setVisible(false) sets the windows' skip-taskbar hint. Nothing shows until the app is
+ *   installed with a desktop file of that name; the state is kept meanwhile.
+ * - Web, iOS and Android: UNSUPPORTED.
+ */
+export type DockProgressState = "normal" | "paused" | "error";
+export interface DockState {
+    /** The app has a Dock icon (activation policy "regular"). */
+    visible: boolean;
+    policy: "regular" | "accessory" | "prohibited";
+    badge: string | null;
+    /** 0..1 as last set, or null when no bar is shown. */
+    progress: number | null;
+    progressState: DockProgressState | null;
+}
+export interface DockApi {
+    setBadge(args: {
+        label: string | null;
+    }): Promise<DockState>;
+    setProgress(args: {
+        progress: number | null;
+        state?: DockProgressState;
+    }): Promise<DockState>;
+    setVisible(args: {
+        visible: boolean;
+    }): Promise<DockState>;
+    getState(): Promise<DockState>;
+}
+export declare const dock: import("../../../packages/core/src/plugin.ts").Plugin<DockApi, {}>;

package/types/vendor/@akanjs/native/plugins/dock/src.d.ts

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

package/types/vendor/@akanjs/native/plugins/file-picker/src/common.d.ts

@@ -0,0 +1,33 @@
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+export declare const invalid: (message: string) => AkanNativeError;
+export declare function checkObject(args: unknown, optional: boolean): Record<string, unknown>;
+/**
+ * File types as given to pickFiles: MIME types ("image/png", "image/*") or file name extensions
+ * ("pdf" or ".pdf"). Normalized to lower case, extensions without the dot. "*\/*" or no types
+ * means any file.
+ */
+export declare function checkTypes(types: unknown): string[];
+export declare function checkFlag(value: unknown, key: string): boolean;
+/** A file name for saveFile: one path segment, no control characters. */
+export declare function checkName(name: unknown): string;
+export declare const DEFAULT_LIMIT = 1000;
+export declare const MAX_LIMIT = 10000;
+export declare function checkLimit(value: unknown): number;
+export declare function checkMime(value: unknown): string | undefined;
+export declare function checkBase64(data: string): void;
+export type SaveSource = {
+    kind: "data";
+    data: string;
+    encoding: "utf8" | "base64";
+} | {
+    kind: "url";
+    url: string;
+};
+/** Content for saveFile: `data` (text, or base64 with encoding) or `url`. Exactly one. */
+export declare function checkSaveSource(args: Record<string, unknown>): SaveSource;
+export declare function base64ToBytes(data: string): Uint8Array;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** A FileRef served by the host: "/__akan_native/file/<id>", optionally on the app origin. */
+export declare function isFileRef(url: string): boolean;
+/** Hidden entries (".DS_Store", ".git/…") are left out of pickDirectory everywhere. */
+export declare const isHidden: (relativePath: string) => boolean;

package/types/vendor/@akanjs/native/plugins/file-picker/src/desktop.d.ts

@@ -0,0 +1,9 @@
+import type { FilePickerApi } from "./index.ts";
+/** Regular files under `dir`, depth first by name, without hidden files and folders (".*"). */
+export declare function listFiles(dir: string, limit: number): {
+    files: string[];
+    truncated: boolean;
+};
+export declare function createDesktopFilePicker(): import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<FilePickerApi, {}>;
+declare const _default: import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<FilePickerApi, {}>;
+export default _default;

package/types/vendor/@akanjs/native/plugins/file-picker/src/index.d.ts

@@ -0,0 +1,84 @@
+import { AkanNativeError, type FileRef, type Plugin } from "../../../packages/core/src/index.ts";
+/** A file the user picked: a copy served by the host (web: a blob: URL of the browser's File). */
+export interface PickedFile extends FileRef {
+    /** The file's name as the user saw it, e.g. "Invoice.pdf". Never a path. */
+    name: string;
+}
+export interface DirectoryFile extends PickedFile {
+    /** Relative to the picked folder, "/"-separated, e.g. "2026/March/receipt.pdf". */
+    path: string;
+}
+export interface PickFilesOptions {
+    /**
+     * Allowed types: MIME types ("application/pdf", "image/*") or extensions ("pdf", ".csv").
+     * Omitted, empty or "*\/*": any file. A type the platform cannot map turns the filter off rather
+     * than hide files the user may be looking for.
+     */
+    types?: string[];
+    /** Let the user pick more than one file. Default false. */
+    multiple?: boolean;
+}
+export interface SaveFileOptions {
+    /** Suggested file name; the user can change it (the result says what was chosen, where known). */
+    name: string;
+    /** Text, or base64 with encoding: "base64". */
+    data?: string;
+    /** Default "utf8". */
+    encoding?: "utf8" | "base64";
+    /** Instead of data: a FileRef of this session (camera, filesystem.readFile, pickFiles) or a blob:/data:/same-origin URL. */
+    url?: string;
+    /** MIME type of the content (Android files the document under it). Default: from the name's extension. */
+    mime?: string;
+}
+export interface SaveFileResult {
+    /** False when the user closed the dialog. On the web without showSaveFilePicker this is true once the download started. */
+    saved: boolean;
+    /** The name the file was saved under, when the platform tells (it may differ from the suggestion). */
+    name?: string;
+}
+export interface PickDirectoryOptions {
+    /** Most files to return (1–10000, default 1000); `truncated` tells whether there were more. */
+    limit?: number;
+}
+export interface PickDirectoryResult {
+    /** The folder's name; null when the user closed the dialog. */
+    name: string | null;
+    /** Every file inside, recursively, as copies; hidden files and folders (".*") are left out. */
+    files: DirectoryFile[];
+    truncated: boolean;
+}
+/**
+ * System file dialogs.
+ * - pickFiles: UIDocumentPickerViewController (iOS, as copies), ACTION_OPEN_DOCUMENT (Android, copied
+ *   into the app cache), an NSOpenPanel sheet on the calling window (macOS), <input type=file> (web).
+ * - saveFile: the export picker (iOS), ACTION_CREATE_DOCUMENT (Android), an NSSavePanel sheet
+ *   (macOS), showSaveFilePicker or a download (web).
+ * - pickDirectory: a read-only snapshot of a folder the user picks: its files, copied like pickFiles.
+ * Results are copies registered as FileRefs; no absolute path reaches the page. Closing a dialog
+ * resolves (`files: []`, `saved: false`, `name: null`); a second dialog while one is open rejects
+ * CANCELLED. On the web call these from a click handler, before any await (user activation).
+ */
+export interface FilePickerApi {
+    pickFiles(options?: PickFilesOptions): Promise<{
+        files: PickedFile[];
+    }>;
+    saveFile(options: SaveFileOptions): Promise<SaveFileResult>;
+    pickDirectory(options?: PickDirectoryOptions): Promise<PickDirectoryResult>;
+}
+export type FilePicker = Plugin<FilePickerApi>;
+export declare const filePicker: FilePicker;
+export interface UseFilePicker {
+    supported: {
+        pickFiles: boolean;
+        saveFile: boolean;
+        pickDirectory: boolean;
+    };
+    pending: boolean;
+    /** Last failure. Closing a dialog is not a failure. */
+    error: AkanNativeError | null;
+    /** These resolve null on failure (see `error`). */
+    pickFiles(options?: PickFilesOptions): Promise<PickedFile[] | null>;
+    saveFile(options: SaveFileOptions): Promise<SaveFileResult | null>;
+    pickDirectory(options?: PickDirectoryOptions): Promise<PickDirectoryResult | null>;
+}
+export declare function useFilePicker(): UseFilePicker;

package/types/vendor/@akanjs/native/plugins/file-picker/src/web.d.ts

@@ -0,0 +1,6 @@
+import type { FilePickerApi, PickDirectoryResult } from "./index.ts";
+/** The accept attribute: MIME types as they are, extensions with a dot. */
+export declare function acceptAttribute(types: string[]): string;
+/** What pickDirectory makes of the files an <input webkitdirectory> returns. */
+export declare function directoryResult(files: File[], limit: number): PickDirectoryResult;
+export declare const web: import("../../../packages/core/src/plugin.ts").WebPlugin<FilePickerApi, {}>;

package/types/vendor/@akanjs/native/plugins/file-picker/src.d.ts

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

package/types/vendor/@akanjs/native/plugins/filesystem/src/common.d.ts

@@ -0,0 +1,49 @@
+import { AkanNativeError, type CallScope } from "../../../packages/core/src/index.ts";
+import type { BaseDirectory, Encoding, EntryType } from "./index.ts";
+export declare const BASES: readonly BaseDirectory[];
+export declare const invalid: (message: string) => AkanNativeError;
+export declare function checkObject(args: unknown, what?: string): Record<string, unknown>;
+export declare function checkBase(base: unknown, key?: string): BaseDirectory;
+/**
+ * A path relative to a base directory, as segments. Only "/" separates segments; "" and "."
+ * segments are dropped. Rejected: absolute paths, "..", backslashes and NUL, so a path can never
+ * leave its base by its spelling (tauri/crates/tauri/src/path/mod.rs:47 SafePathBuf rejects any
+ * ParentDir component the same way). Symbolic links are checked separately, after resolving.
+ * `allowRoot`: whether "" (the base itself) is acceptable, e.g. for readDir.
+ */
+export declare function checkPath(path: unknown, allowRoot: boolean, key?: string): string[];
+/**
+ * PL-11: the app's capabilities may limit filesystem calls to scopes { base?, path? } (globs; the
+ * path is relative to the base with "/" separators; an allowed wildcard never matches a dot file).
+ * `fold`: the base is on a case-insensitive volume. Throws NOT_ALLOWED outside the call's scope.
+ */
+export declare function checkScope(scope: CallScope | undefined, base: BaseDirectory, segments: string[], fold?: boolean): void;
+export declare function checkEncoding(encoding: unknown, allowNone: boolean): Encoding | undefined;
+export declare function checkFlag(value: unknown, key: string): boolean;
+/**
+ * A FileRef served by the host: "/__akan_native/file/<id>", absolute on the app origin, or null. The origin
+ * is the shell's (`__AKAN_NATIVE__.origin`); without one (the desktop plugin host, tests) either shell origin.
+ */
+export declare function fileRefId(url: string, origin?: string | undefined): string | null;
+export declare function checkBase64(data: string): void;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(data: string): Uint8Array;
+export declare const decodeUtf8: (bytes: Uint8Array) => string;
+export declare const encodeUtf8: (text: string) => Uint8Array<ArrayBuffer>;
+/** Content to write: text or base64 `data`, or a `url` to copy from. Exactly one. */
+export type WriteSource = {
+    kind: "data";
+    data: string;
+    encoding: Encoding;
+} | {
+    kind: "url";
+    url: string;
+};
+export declare function checkWriteSource(args: Record<string, unknown>): WriteSource;
+export { mimeFor } from "../../../packages/core/src/index.ts";
+export declare function sortEntries<T extends {
+    name: string;
+}>(entries: T[]): T[];
+/** Runs tasks one after another in call order, so un-awaited calls (e.g. append chunks) land in order. */
+export declare function serialQueue(): <T>(task: () => Promise<T> | T) => Promise<T>;
+export type { EntryType };

package/types/vendor/@akanjs/native/plugins/filesystem/src/desktop.d.ts

@@ -0,0 +1,8 @@
+import { type DesktopContext } from "../../../packages/desktop/src/plugin.ts";
+import type { BaseDirectory, FilesystemApi } from "./index.ts";
+type Dirs = Record<BaseDirectory, string>;
+/** The base folders for an app. Windows and Linux are unverified until those milestones. */
+export declare function baseDirs(ctx: Pick<DesktopContext, "app" | "appDataDir">, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string, tmp?: string): Dirs;
+export declare function createDesktopFilesystem(dirsFor?: (ctx: DesktopContext) => Dirs): import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<FilesystemApi, {}>;
+declare const _default: import("../../../packages/desktop/src/plugin.ts").DesktopPlugin<FilesystemApi, {}>;
+export default _default;

package/types/vendor/@akanjs/native/plugins/filesystem/src/index.d.ts

@@ -0,0 +1,123 @@
+import { type FileRef, type Plugin } from "../../../packages/core/src/index.ts";
+/**
+ * Where a path lives. Paths are always relative to one of these; absolute paths and ".." are
+ * rejected with INVALID_ARGS, and symbolic links that lead outside the base with PERMISSION_DENIED.
+ *
+ * | base      | macOS                                   | iOS                                | Android                                        | web (OPFS) |
+ * |-----------|-----------------------------------------|------------------------------------|------------------------------------------------|------------|
+ * | data      | ~/Library/Application Support/<id>/files | Library/Application Support/files | files/ (Context.filesDir)                      | /data      |
+ * | cache     | ~/Library/Caches/<id>/files             | Library/Caches/files               | cache/files                                    | /cache     |
+ * | documents | ~/Documents                             | Documents                          | Android/data/<id>/files/Documents (external)   | /documents |
+ * | temp      | $TMPDIR/<id>/files                      | tmp/files                          | cache/temp                                     | /temp      |
+ *
+ * - data: kept until the app is removed, included in device backups.
+ * - cache, temp: the OS may delete them when storage runs low (iOS, Android) or at any time the app
+ *   is not running (iOS tmp). Not backed up.
+ * - documents: user-visible documents. On macOS the first access asks the user for the Documents
+ *   folder (TCC). On iOS the Files app shows it only if the app's Info.plist sets
+ *   UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace. On Android it is the app's own
+ *   external folder: no permission, removed with the app.
+ * - web: the origin private file system (navigator.storage.getDirectory()), one folder per base.
+ */
+export type BaseDirectory = "data" | "cache" | "documents" | "temp";
+export type Encoding = "utf8" | "base64";
+export type EntryType = "file" | "directory" | "symlink" | "other";
+export interface PathOptions {
+    /** Relative to `base`, "/"-separated, e.g. "notes/today.txt". */
+    path: string;
+    base: BaseDirectory;
+}
+export interface ReadFileOptions extends PathOptions {
+    /**
+     * "utf8" returns the text, "base64" the bytes as base64. Without an encoding the file is not
+     * sent over the bridge at all: the result is a FileRef whose `url` serves the file (fetch it,
+     * or use it as an <img>/<video> src), which is the way to read large or binary files.
+     */
+    encoding?: Encoding;
+}
+export type WriteFileOptions = PathOptions & {
+    /** Add to the end of the file instead of replacing it. Replacing writes are atomic (temp file + rename). */
+    append?: boolean;
+    /** Create missing parent folders. Without it a missing parent rejects NOT_FOUND. */
+    recursive?: boolean;
+} & ({
+    /** Text, or base64 with encoding: "base64". For large binary content write base64 chunks with append. */
+    data: string;
+    /** Default "utf8". */
+    encoding?: Encoding;
+    url?: never;
+} | {
+    /**
+     * Copy the content of this URL: a FileRef of this session (camera.takePhoto, file-picker,
+     * readFile), or a blob:, data: or same-origin URL, which the page fetches first.
+     */
+    url: string;
+    data?: never;
+    encoding?: never;
+});
+export interface FileInfo {
+    /** Symbolic links are followed by stat and reported as "symlink" by readDir. */
+    type: EntryType;
+    /** Bytes; 0 for folders. */
+    size: number;
+    /** Last modification, ms since the epoch (like Date.now()). 0 where unknown (OPFS folders). */
+    mtime: number;
+}
+export interface DirEntry extends FileInfo {
+    name: string;
+}
+export interface MoveOptions {
+    from: string;
+    to: string;
+    /** Base of `from`, and of `to` unless `toBase` is given. */
+    base: BaseDirectory;
+    toBase?: BaseDirectory;
+}
+export interface FilesystemApi {
+    readFile(options: PathOptions & {
+        encoding: Encoding;
+    }): Promise<{
+        data: string;
+    }>;
+    readFile(options: PathOptions & {
+        encoding?: undefined;
+    }): Promise<FileRef>;
+    readFile(options: ReadFileOptions): Promise<{
+        data: string;
+    } | FileRef>;
+    /** Creates or replaces the file (or appends to it). Parent folders must exist unless `recursive`. */
+    writeFile(options: WriteFileOptions): Promise<void>;
+    /** Entries of a folder ("" is the base itself), sorted by name. */
+    readDir(options: PathOptions): Promise<{
+        entries: DirEntry[];
+    }>;
+    stat(options: PathOptions): Promise<FileInfo>;
+    exists(options: PathOptions): Promise<{
+        value: boolean;
+    }>;
+    /** Without `recursive` the parent must exist and the folder must not (INVALID_ARGS). */
+    mkdir(options: PathOptions & {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Removes a file, a symbolic link (not its target) or a folder; non-empty folders need `recursive`. */
+    remove(options: PathOptions & {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Moves a file or folder, also across bases (copy + remove where the bases are on different
+     * volumes). An existing file at `to` is replaced; an existing folder rejects INVALID_ARGS.
+     */
+    rename(options: MoveOptions): Promise<void>;
+    /** Copies a file, or a folder with everything in it. Same rules for `to` as rename. */
+    copy(options: MoveOptions): Promise<void>;
+    /** Absolute locations of the bases, for display and logs only; other methods take relative paths. */
+    paths(): Promise<Record<BaseDirectory, string>>;
+}
+/**
+ * The iOS bridge parses requests with JSONSerialization, which drops a U+FEFF (byte order mark) at
+ * the start of any string value (verified). Such text goes as base64 there, so the bytes on disk are
+ * the ones written everywhere.
+ */
+export declare function protectLeadingBom(options: WriteFileOptions): WriteFileOptions;
+export type Filesystem = Plugin<FilesystemApi>;
+export declare const filesystem: Filesystem;