@iyexin/mio-api 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Mio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Third-party components (Flutter/Dart, webview_flutter, webview_flutter_windows,
+window_manager, file_selector, url_launcher, path_provider, @electron/asar,
+resedit, apksigner/zipalign, and the Dart/npm dependencies listed in
+packages/*/THIRD_PARTY_NOTICES.md) keep their own licenses. The prebuilt
+Android/Windows templates in packages/cli/templates embed the Flutter engine;
+review those licenses before redistributing an app built with Mio.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @iyexin/mio-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Web 侧 Mio API 与 bootstrap bridge。
+
+```bash
+npm install @iyexin/mio-api
+```
+
+```ts
+import { Mio, app, fs, clipboard, nativeApi, processApi } from "@iyexin/mio-api";
+
+await Mio.ready;
+console.log(await app.info());
+await fs.writeText("notes/hello.txt", "hello");
+await clipboard.writeText("Hello from the shell");
+
+// Native library with a small scalar ABI (Android + Windows).
+const lib = await nativeApi.load("demo");
+const sum = await nativeApi.call(lib.handle, "mio_add", "i32(i32,i32)", [2, 3]);
+
+// Windows only: start a sidecar and pipe stdio.
+const child = await processApi.spawn({ path: "sidecar/helper.exe" });
+await processApi.write(child.id, "ping\n");
+await processApi.closeStdin(child.id);
+```
+
+- `bootstrap.js` 是零依赖的 classic script，由运行时注入，也可被打包器 import；
+- `index.ts` 是类型封装，所有调用返回 Promise；
+- `window.Mio` 与 `Mio` 共用同一个 bridge；
+- 错误带符号码 `code`（`FS_FORBIDDEN` 等）与数字 `rpcCode`。
+
+完整 API 见仓库 `docs/api.md`。

package/bootstrap.js

@@ -0,0 +1,364 @@
+/*
+ * Mio bootstrap bridge.
+ *
+ * This file is intentionally dependency-free and runs as a classic script.
+ * The runtime injects window.__MIO_BOOT__ before it; dev mode reads the same
+ * values from the page query string. It is the only implementation of the
+ * WebSocket/JSON-RPC transport.
+ */
+(function () {
+  "use strict";
+
+  if (window.Mio && window.Mio.__mio) return;
+
+  function readBoot() {
+    if (window.__MIO_BOOT__) return window.__MIO_BOOT__;
+    try {
+      var params = new URLSearchParams(window.location.search);
+      var port = params.get("__mio_port");
+      var token = params.get("__mio_token");
+      if (!port || !token) return null;
+      return {
+        port: Number(port),
+        token: token,
+        platform: params.get("__mio_platform") || "web",
+        apiVersion: "1.0.0",
+        app: {
+          id: params.get("__mio_app_id") || "dev.mio.app",
+          name: params.get("__mio_app_name") || "Mio App",
+          version: params.get("__mio_app_version") || "0.0.0"
+        }
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  var boot = readBoot();
+  if (!boot || !boot.port || !boot.token) {
+    console.error("[Mio] bootstrap data is missing; the bridge was not started");
+    return;
+  }
+
+  function MioError(code, message, data) {
+    var error = new Error(message);
+    error.name = "MioError";
+    error.code = code;
+    error.data = data;
+    return error;
+  }
+
+  var nextId = 1;
+  var pending = new Map();
+  var listeners = new Map();
+  var outgoing = [];
+  var socket = null;
+  var reconnectTimer = null;
+  var reconnectDelay = 250;
+  var closedByApp = false;
+  var opened = false;
+  var state = "connecting";
+  var heartbeat = null;
+  var HEARTBEAT_INTERVAL = 5000;
+  var HEARTBEAT_TIMEOUT = 4000;
+
+  function setState(next) {
+    if (state === next) return;
+    state = next;
+    dispatch("bridge.state", { state: next });
+  }
+
+  var resolveReady;
+  var rejectReady;
+  var ready = new Promise(function (resolve, reject) {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+  var readyTimer = setTimeout(function () {
+    if (!opened) {
+      rejectReady(MioError("MIO_TIMEOUT", "Mio bridge did not connect in time"));
+    }
+  }, 15000);
+
+  function endpoint() {
+    return (
+      "ws://127.0.0.1:" +
+      boot.port +
+      "/__mio__/rpc?token=" +
+      encodeURIComponent(boot.token)
+    );
+  }
+
+  function connect() {
+    if (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)) {
+      return;
+    }
+    socket = new WebSocket(endpoint());
+
+    socket.onopen = function () {
+      opened = true;
+      reconnectDelay = 250;
+      clearTimeout(readyTimer);
+      setState("open");
+      startHeartbeat();
+      resolveReady({
+        apiVersion: boot.apiVersion || "1.0.0",
+        platform: boot.platform || "web",
+        app: boot.app || {}
+      });
+      window.dispatchEvent(new CustomEvent("mio:ready", { detail: boot.app || {} }));
+      var queue = outgoing;
+      outgoing = [];
+      for (var i = 0; i < queue.length; i++) {
+        socket.send(queue[i]);
+      }
+    };
+
+    socket.onmessage = function (event) {
+      var message;
+      try {
+        message = JSON.parse(event.data);
+      } catch (error) {
+        console.error("[Mio] invalid bridge message", error);
+        return;
+      }
+      if (message.method === "event" && message.params) {
+        dispatch(message.params.name, message.params.data);
+        return;
+      }
+      if (message.id === undefined || message.id === null) return;
+      var request = pending.get(message.id);
+      if (!request) return;
+      pending.delete(message.id);
+      clearTimeout(request.timer);
+      if (message.error) {
+        // `mioCode` is the stable symbolic code (FS_FORBIDDEN, ...); the JSON-RPC
+        // `code` is an integer and stays available as `rpcCode`.
+        var symbol = message.error.mioCode != null ? message.error.mioCode : message.error.code;
+        var failure = MioError(
+          symbol,
+          message.error.message || "Mio call failed",
+          message.error.data
+        );
+        if (typeof message.error.code === "number") {
+          failure.rpcCode = message.error.code;
+        }
+        request.reject(failure);
+      } else {
+        request.resolve(message.result);
+      }
+    };
+
+    socket.onerror = function () {
+      // onclose will schedule reconnect
+    };
+
+    socket.onclose = function () {
+      socket = null;
+      stopHeartbeat();
+      if (closedByApp) return;
+      setState("closed");
+      for (var entry of pending.values()) {
+        clearTimeout(entry.timer);
+        entry.reject(MioError("MIO_DISCONNECTED", "Mio bridge disconnected"));
+      }
+      pending.clear();
+      if (reconnectTimer) return;
+      reconnectTimer = setTimeout(function () {
+        reconnectTimer = null;
+        reconnectDelay = Math.min(reconnectDelay * 2, 10000);
+        setState("connecting");
+        connect();
+      }, reconnectDelay);
+    };
+  }
+
+  /*
+   * A half-open socket looks alive forever: the OS only notices after minutes.
+   * A ping every few seconds turns "the shell froze or died" into a fast
+   * disconnect instead of a 30 second timeout on the next real call.
+   */
+  function startHeartbeat() {
+    stopHeartbeat();
+    heartbeat = setInterval(function () {
+      if (!socket || socket.readyState !== WebSocket.OPEN) return;
+      request("ping", {}, HEARTBEAT_TIMEOUT).catch(function () {
+        if (!socket) return;
+        try {
+          socket.close();
+        } catch (error) {
+          // onclose handles the reconnect.
+        }
+      });
+    }, HEARTBEAT_INTERVAL);
+  }
+
+  function stopHeartbeat() {
+    if (!heartbeat) return;
+    clearInterval(heartbeat);
+    heartbeat = null;
+  }
+
+  function request(method, params, timeoutMs) {
+    return new Promise(function (resolve, reject) {
+      if (typeof method !== "string" || method.length === 0) {
+        reject(MioError("MIO_BAD_REQUEST", "method must be a non-empty string"));
+        return;
+      }
+      var id = nextId++;
+      var payload = JSON.stringify({
+        jsonrpc: "2.0",
+        id: id,
+        method: method,
+        params: params || {}
+      });
+      var timer = setTimeout(function () {
+        if (!pending.has(id)) return;
+        pending.delete(id);
+        reject(MioError("MIO_TIMEOUT", "Mio call timed out: " + method));
+      }, timeoutMs || 30000);
+      pending.set(id, { resolve: resolve, reject: reject, timer: timer });
+
+      if (socket && socket.readyState === WebSocket.OPEN) {
+        socket.send(payload);
+      } else {
+        outgoing.push(payload);
+        connect();
+      }
+    });
+  }
+
+  function invoke(method, params) {
+    return request(method, params, 30000);
+  }
+
+  function blobUrl(path) {
+    return (
+      "http://127.0.0.1:" +
+      boot.port +
+      "/__mio__/blob?token=" +
+      encodeURIComponent(boot.token) +
+      "&path=" +
+      encodeURIComponent(path)
+    );
+  }
+
+  function errorFromResponse(response, detail) {
+    return MioError("FS_ERROR", detail || "HTTP " + response.status, {
+      status: response.status
+    });
+  }
+
+  async function readBlob(path) {
+    var response;
+    try {
+      response = await fetch(blobUrl(path));
+    } catch (error) {
+      throw MioError("MIO_DISCONNECTED", "Blob request failed: " + path);
+    }
+    if (!response.ok) {
+      var body = "";
+      try {
+        body = await response.text();
+      } catch (error) {
+        body = "";
+      }
+      throw errorFromResponse(response, body || undefined);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  async function writeBlob(path, data) {
+    var isBytes =
+      data instanceof ArrayBuffer ||
+      (typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(data));
+    if (!isBytes) {
+      throw MioError(
+        "MIO_BAD_REQUEST",
+        "writeBlob expects an ArrayBuffer or typed array"
+      );
+    }
+    var response;
+    try {
+      response = await fetch(blobUrl(path), {
+        method: "POST",
+        headers: { "Content-Type": "application/octet-stream" },
+        body: data
+      });
+    } catch (error) {
+      throw MioError("MIO_DISCONNECTED", "Blob request failed: " + path);
+    }
+    if (!response.ok) {
+      var body = "";
+      try {
+        body = await response.text();
+      } catch (error) {
+        body = "";
+      }
+      throw errorFromResponse(response, body || undefined);
+    }
+  }
+
+  function on(name, handler) {
+    if (typeof handler !== "function") {
+      throw new TypeError("Mio.on requires a handler function");
+    }
+    var bucket = listeners.get(name);
+    if (!bucket) {
+      bucket = new Set();
+      listeners.set(name, bucket);
+    }
+    bucket.add(handler);
+    return function () {
+      bucket.delete(handler);
+      if (bucket.size === 0) listeners.delete(name);
+    };
+  }
+
+  function off(name, handler) {
+    var bucket = listeners.get(name);
+    if (!bucket) return;
+    bucket.delete(handler);
+    if (bucket.size === 0) listeners.delete(name);
+  }
+
+  function once(name, handler) {
+    var unsubscribe = on(name, function (data) {
+      unsubscribe();
+      handler(data);
+    });
+    return unsubscribe;
+  }
+
+  function dispatch(name, data) {
+    var bucket = listeners.get(name);
+    if (!bucket) return;
+    for (var handler of Array.from(bucket)) {
+      try {
+        handler(data);
+      } catch (error) {
+        console.error("[Mio] event handler failed", name, error);
+      }
+    }
+  }
+
+  window.Mio = {
+    __mio: true,
+    apiVersion: boot.apiVersion || "1.0.0",
+    platform: boot.platform || "web",
+    app: boot.app || {},
+    ready: ready,
+    get state() {
+      return state;
+    },
+    invoke: invoke,
+    on: on,
+    off: off,
+    once: once,
+    blobUrl: blobUrl,
+    readBlob: readBlob,
+    writeBlob: writeBlob
+  };
+
+  connect();
+})();

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+import "../bootstrap.js";
+import type { BridgeState, MioBridge } from "./types.js";
+export type { BridgeState, MioBridge, MioBootstrap, } from "./types.js";
+export interface AppFeatures {
+    /** `nativeApi` is usable: supported platform and a packaged build. */
+    native: boolean;
+    /** `processApi` is usable (Windows only). */
+    process: boolean;
+    /** Window controls are available. */
+    window: boolean;
+}
+export interface AppInfo {
+    id: string;
+    name: string;
+    version: string;
+    title: string;
+    platform: string;
+    apiVersion: string;
+    templateVersion: string;
+    /** True when the page is served by a dev server instead of the app archive. */
+    dev: boolean;
+    /** ISO timestamp of when the shell started. */
+    startedAt: string;
+    /** Milliseconds since the shell started. */
+    uptimeMs: number;
+    features: AppFeatures;
+}
+export interface PlatformInfo {
+    os: string;
+    osVersion: string;
+    locale: string;
+    processors: number;
+    platform: string;
+    /** ABI this shell runs as: `arm64`, `x64`, `arm`, `x86`. */
+    abi: string;
+}
+export interface AppPaths {
+    /** Root of everything the app owns. */
+    data: string;
+    /** The only writable sandbox; paths passed to `fs.*` are relative to it. */
+    app: string;
+    /** Where native libraries are extracted. */
+    native: string;
+    /** Directory of the installed executable. */
+    install: string;
+    /** System temp directory. */
+    temp: string;
+}
+export interface AppLogResult {
+    /** Path of the log file, relative to the `fs` sandbox. */
+    path: string;
+}
+export interface FileEntry {
+    name: string;
+    path: string;
+    type: string;
+    size: number;
+    modified: string;
+}
+export interface FileStat {
+    type: string;
+    size: number;
+    modified: string;
+}
+export interface WindowState {
+    supported: boolean;
+    width?: number;
+    height?: number;
+    isMaximized?: boolean;
+    isFullScreen?: boolean;
+}
+export interface ProcessSpawnOptions {
+    /**
+     * Executable path. Relative paths are resolved against the install directory
+     * (next to the app executable) and then the app data directory; absolute
+     * paths must resolve inside one of those two roots.
+     */
+    path: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export interface ProcessInfo {
+    id: string;
+    pid: number;
+    executable: string;
+    cwd?: string;
+}
+export interface ProcessChunk {
+    id: string;
+    pid: number;
+    bytes: Uint8Array;
+}
+export interface ProcessExitEvent {
+    id: string;
+    pid: number;
+    code: number;
+    signal: string | null;
+    executable?: string;
+}
+export interface NativeHandle {
+    handle: string;
+    name: string;
+    /** ABI the library was checked against, e.g. `arm64` or `x64`. */
+    abi: string;
+    /** Path inside the app archive, e.g. `native/arm64/demo.so`. */
+    path: string;
+    /** Absolute path of the extracted copy the loader opened. */
+    file: string;
+    /** Whether the library exports the optional `mio_start` entry point. */
+    entry: boolean;
+    started: boolean;
+}
+export interface NativeStartResult {
+    handle: string;
+    /** Value returned by `mio_start`; null when the entry is still running. */
+    code: number | null;
+    running: boolean;
+}
+export interface NativeStopResult {
+    handle: string;
+    /** True when `mio_stop` existed and returned. */
+    stopped: boolean;
+    /** `not started`, `no mio_stop`, or the error the export raised. */
+    reason?: string;
+    /** The export did not return within the shutdown budget. */
+    timedOut?: boolean;
+}
+export interface NativeEvent {
+    handle: string;
+    /** Caller-chosen id passed to the sink by native code. */
+    event: number;
+    a: number;
+    b: number;
+    c: number;
+}
+export type NativeValue = number | string;
+export declare function getMio(): Promise<MioBridge>;
+/**
+ * Native libraries with a small, fixed scalar ABI.
+ *
+ * A library is packed under `native/<abi>/<name>.so|dll` in the app content,
+ * extracted to the app data directory on first load, and opened with `dlopen` /
+ * `LoadLibrary`. Two ways to use it:
+ *
+ * - `call` invokes exported functions with the supported scalar signatures
+ *   (`i32`, `i64`, `f64`, `str` arguments; `void`, `i32`, `i64`, `f64` returns);
+ * - `start` calls the optional `mio_start(sink, config)` entry, after which the
+ *   library can push scalar events to the page through the sink.
+ *
+ * Anything beyond scalars — buffers, structs, callbacks with pointers — is out
+ * of scope by design: use files, the blob endpoint, or a sidecar process.
+ */
+export declare const nativeApi: {
+    /** Loads `native/<abi>/<name>.<ext>` from the app content. */
+    load: (name: string) => Promise<NativeHandle>;
+    /** Calls `mio_start(sink, config)`; returns its result or reports it running. */
+    start: (handle: string, config?: string) => Promise<NativeStartResult>;
+    /**
+     * Calls the optional `mio_stop()` export and marks the library as stopped.
+     * The library stays loaded; `start` can be called again afterwards.
+     */
+    stop: (handle: string) => Promise<NativeStopResult>;
+    /**
+     * Calls an exported function. `signature` must be one of the supported
+     * shapes, e.g. `i32(i32,i32)`, `f64(str)`, `void()`.
+     */
+    call: (handle: string, symbol: string, signature: string, args?: NativeValue[]) => Promise<number | null>;
+    /**
+     * Pushes a scalar event into the library through its optional `mio_event`
+     * export — the reverse direction of `onEvent`:
+     *
+     * ```c
+     * void mio_event(int32_t event, int64_t a, int64_t b, double c);
+     * ```
+     */
+    emit: (handle: string, event: number, a?: number, b?: number, c?: number) => Promise<void>;
+    list: () => Promise<NativeHandle[]>;
+    /** Scalar events pushed by native code through the `mio_start` sink. */
+    onEvent: (handler: (event: NativeEvent) => void) => Promise<() => void>;
+};
+/**
+ * Sidecar processes. Windows only; every other platform rejects with
+ * `UNSUPPORTED`.
+ *
+ * Mio does not provide native plugins. This namespace only starts a process and
+ * moves its stdio; the wire protocol between the app and the sidecar is the
+ * app's own business. Named `processApi` rather than `process` so importing it
+ * never shadows the global `process`.
+ */
+export declare const processApi: {
+    spawn: (options: ProcessSpawnOptions) => Promise<ProcessInfo>;
+    /** Sends bytes to the child's stdin. Strings are encoded as UTF-8. */
+    write: (id: string, data: Uint8Array | ArrayBuffer | string) => Promise<void>;
+    closeStdin: (id: string) => Promise<void>;
+    /** SIGTERM, escalating to SIGKILL after five seconds. */
+    kill: (id: string, signal?: "term" | "kill") => Promise<{
+        id: string;
+        pid: number;
+        killed: boolean;
+    }>;
+    list: () => Promise<ProcessInfo[]>;
+    /** stdout chunks; concatenate `bytes` — chunk boundaries are arbitrary. */
+    onStdout: (handler: (chunk: ProcessChunk) => void) => Promise<() => void>;
+    onStderr: (handler: (chunk: ProcessChunk) => void) => Promise<() => void>;
+    onExit: (handler: (event: ProcessExitEvent) => void) => Promise<() => void>;
+};
+export declare const Mio: {
+    readonly ready: Promise<{
+        apiVersion: string;
+        platform: string;
+        app: Record<string, unknown>;
+    }>;
+    /** `connecting` | `open` | `closed`; changes arrive as `bridge.state`. */
+    connectionState(): Promise<BridgeState>;
+    invoke<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    on(name: string, handler: (data: unknown) => void): Promise<() => void>;
+    off(name: string, handler: (data: unknown) => void): Promise<void>;
+    once(name: string, handler: (data: unknown) => void): Promise<() => void>;
+    process: {
+        spawn: (options: ProcessSpawnOptions) => Promise<ProcessInfo>;
+        /** Sends bytes to the child's stdin. Strings are encoded as UTF-8. */
+        write: (id: string, data: Uint8Array | ArrayBuffer | string) => Promise<void>;
+        closeStdin: (id: string) => Promise<void>;
+        /** SIGTERM, escalating to SIGKILL after five seconds. */
+        kill: (id: string, signal?: "term" | "kill") => Promise<{
+            id: string;
+            pid: number;
+            killed: boolean;
+        }>;
+        list: () => Promise<ProcessInfo[]>;
+        /** stdout chunks; concatenate `bytes` — chunk boundaries are arbitrary. */
+        onStdout: (handler: (chunk: ProcessChunk) => void) => Promise<() => void>;
+        onStderr: (handler: (chunk: ProcessChunk) => void) => Promise<() => void>;
+        onExit: (handler: (event: ProcessExitEvent) => void) => Promise<() => void>;
+    };
+    native: {
+        /** Loads `native/<abi>/<name>.<ext>` from the app content. */
+        load: (name: string) => Promise<NativeHandle>;
+        /** Calls `mio_start(sink, config)`; returns its result or reports it running. */
+        start: (handle: string, config?: string) => Promise<NativeStartResult>;
+        /**
+         * Calls the optional `mio_stop()` export and marks the library as stopped.
+         * The library stays loaded; `start` can be called again afterwards.
+         */
+        stop: (handle: string) => Promise<NativeStopResult>;
+        /**
+         * Calls an exported function. `signature` must be one of the supported
+         * shapes, e.g. `i32(i32,i32)`, `f64(str)`, `void()`.
+         */
+        call: (handle: string, symbol: string, signature: string, args?: NativeValue[]) => Promise<number | null>;
+        /**
+         * Pushes a scalar event into the library through its optional `mio_event`
+         * export — the reverse direction of `onEvent`:
+         *
+         * ```c
+         * void mio_event(int32_t event, int64_t a, int64_t b, double c);
+         * ```
+         */
+        emit: (handle: string, event: number, a?: number, b?: number, c?: number) => Promise<void>;
+        list: () => Promise<NativeHandle[]>;
+        /** Scalar events pushed by native code through the `mio_start` sink. */
+        onEvent: (handler: (event: NativeEvent) => void) => Promise<() => void>;
+    };
+};
+export declare const app: {
+    info: () => Promise<AppInfo>;
+    /** Absolute directories the app owns; `app` is the writable sandbox. */
+    paths: () => Promise<AppPaths>;
+    /**
+     * Appends a timestamped `level message` line to `logs/mio.log` (rotated at
+     * ~1 MB). Android has no console, so the file is the useful sink.
+     */
+    log: (level: "debug" | "info" | "warn" | "error", message: string) => Promise<AppLogResult>;
+    quit: () => Promise<void>;
+};
+export declare const platform: {
+    info: () => Promise<PlatformInfo>;
+};
+export declare const fs: {
+    readText: (path: string) => Promise<string>;
+    writeText: (path: string, text: string) => Promise<void>;
+    appendText: (path: string, text: string) => Promise<void>;
+    readBytes: (path: string) => Promise<Uint8Array>;
+    writeBytes: (path: string, data: Uint8Array | ArrayBuffer) => Promise<void>;
+    list: (path?: string) => Promise<FileEntry[]>;
+    stat: (path: string) => Promise<FileStat | null>;
+    mkdir: (path: string) => Promise<void>;
+    remove: (path: string, recursive?: boolean) => Promise<boolean>;
+    rename: (from: string, to: string) => Promise<void>;
+    exists: (path: string) => Promise<boolean>;
+    /** URL usable with fetch() for streaming reads (Range supported). */
+    blobUrl: (path: string) => Promise<string>;
+};
+export declare const dialog: {
+    openFile: (extensions?: string[]) => Promise<string | null>;
+    openDirectory: () => Promise<string | null>;
+    saveFile: (suggestedName?: string) => Promise<string | null>;
+};
+export declare const clipboard: {
+    readText: () => Promise<string | null>;
+    writeText: (text: string) => Promise<void>;
+};
+export declare const shell: {
+    openExternal: (url: string) => Promise<void>;
+    /**
+     * Opens a file from the app sandbox with the system default application.
+     * Windows only: Android would need a content provider Mio does not ship.
+     */
+    openPath: (path: string) => Promise<void>;
+    /** Shows a sandbox file or folder in Explorer, selected when possible. */
+    reveal: (path: string) => Promise<void>;
+};
+export declare const windowApi: {
+    state: () => Promise<WindowState>;
+    setTitle: (title: string) => Promise<void>;
+    minimize: () => Promise<void>;
+    maximize: () => Promise<void>;
+    restore: () => Promise<void>;
+    close: () => Promise<void>;
+    center: () => Promise<void>;
+    moveTo: (x: number, y: number) => Promise<void>;
+    setSize: (width: number, height: number) => Promise<void>;
+    setFullScreen: (fullScreen: boolean) => Promise<void>;
+    setAlwaysOnTop: (alwaysOnTop: boolean) => Promise<void>;
+};
+export default Mio;

package/dist/index.js

@@ -0,0 +1,252 @@
+// Side-effect import: installs window.Mio before app code runs. In production
+// the runtime also injects this file before the app bundle; the bootstrap
+// guards against double installation.
+import "../bootstrap.js";
+function toBase64(data) {
+    let bytes;
+    if (typeof data === "string") {
+        bytes = new TextEncoder().encode(data);
+    }
+    else if (data instanceof ArrayBuffer) {
+        bytes = new Uint8Array(data);
+    }
+    else {
+        bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+    }
+    return btoa(binary);
+}
+function fromBase64(data) {
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+function waitForBridge(timeoutMs = 10_000) {
+    if (typeof window === "undefined") {
+        return Promise.reject(new Error("Mio API is only available in a browser"));
+    }
+    if (window.Mio)
+        return Promise.resolve(window.Mio);
+    return new Promise((resolve, reject) => {
+        const started = Date.now();
+        const timer = window.setInterval(() => {
+            if (window.Mio) {
+                window.clearInterval(timer);
+                resolve(window.Mio);
+                return;
+            }
+            if (Date.now() - started > timeoutMs) {
+                window.clearInterval(timer);
+                reject(new Error("Mio bridge did not become ready"));
+            }
+        }, 50);
+    });
+}
+async function injectBootstrapFromQuery() {
+    if (typeof document === "undefined")
+        return false;
+    const params = new URLSearchParams(window.location.search);
+    const port = params.get("__mio_port");
+    if (!port)
+        return false;
+    if (document.querySelector("script[data-mio-bootstrap]"))
+        return true;
+    await new Promise((resolve, reject) => {
+        const script = document.createElement("script");
+        script.src = `http://127.0.0.1:${port}/__mio__/bootstrap.js`;
+        script.async = true;
+        script.dataset.mioBootstrap = "true";
+        script.onload = () => resolve();
+        script.onerror = () => reject(new Error("Failed to load the Mio bootstrap"));
+        document.head.appendChild(script);
+    });
+    return true;
+}
+export async function getMio() {
+    if (typeof window === "undefined") {
+        throw new Error("Mio API is only available in a browser");
+    }
+    if (window.Mio)
+        return window.Mio;
+    // Dev mode: the shell adds __mio_port/__mio_token to the Vite URL. The
+    // bootstrap file may also be bundled by the app, in which case this is a
+    // no-op. Either way window.Mio is installed exactly once.
+    if (!window.Mio) {
+        try {
+            await injectBootstrapFromQuery();
+        }
+        catch {
+            // Fall through to waitForBridge for a useful timeout.
+        }
+    }
+    return await waitForBridge();
+}
+async function invoke(method, params) {
+    const bridge = await getMio();
+    return await bridge.invoke(method, params);
+}
+async function subscribeProcessStream(name, handler) {
+    return await Mio.on(name, (data) => {
+        const event = data;
+        handler({ id: event.id, pid: event.pid, bytes: fromBase64(event.data) });
+    });
+}
+/**
+ * Native libraries with a small, fixed scalar ABI.
+ *
+ * A library is packed under `native/<abi>/<name>.so|dll` in the app content,
+ * extracted to the app data directory on first load, and opened with `dlopen` /
+ * `LoadLibrary`. Two ways to use it:
+ *
+ * - `call` invokes exported functions with the supported scalar signatures
+ *   (`i32`, `i64`, `f64`, `str` arguments; `void`, `i32`, `i64`, `f64` returns);
+ * - `start` calls the optional `mio_start(sink, config)` entry, after which the
+ *   library can push scalar events to the page through the sink.
+ *
+ * Anything beyond scalars — buffers, structs, callbacks with pointers — is out
+ * of scope by design: use files, the blob endpoint, or a sidecar process.
+ */
+export const nativeApi = {
+    /** Loads `native/<abi>/<name>.<ext>` from the app content. */
+    load: (name) => invoke("native.load", { name }),
+    /** Calls `mio_start(sink, config)`; returns its result or reports it running. */
+    start: (handle, config) => invoke("native.start", { handle, config }),
+    /**
+     * Calls the optional `mio_stop()` export and marks the library as stopped.
+     * The library stays loaded; `start` can be called again afterwards.
+     */
+    stop: (handle) => invoke("native.stop", { handle }),
+    /**
+     * Calls an exported function. `signature` must be one of the supported
+     * shapes, e.g. `i32(i32,i32)`, `f64(str)`, `void()`.
+     */
+    call: (handle, symbol, signature, args = []) => invoke("native.call", { handle, symbol, signature, args }),
+    /**
+     * Pushes a scalar event into the library through its optional `mio_event`
+     * export — the reverse direction of `onEvent`:
+     *
+     * ```c
+     * void mio_event(int32_t event, int64_t a, int64_t b, double c);
+     * ```
+     */
+    emit: (handle, event, a = 0, b = 0, c = 0) => invoke("native.emit", { handle, event, a, b, c }),
+    list: () => invoke("native.list"),
+    /** Scalar events pushed by native code through the `mio_start` sink. */
+    onEvent: (handler) => Mio.on("native.event", (data) => handler(data)),
+};
+/**
+ * Sidecar processes. Windows only; every other platform rejects with
+ * `UNSUPPORTED`.
+ *
+ * Mio does not provide native plugins. This namespace only starts a process and
+ * moves its stdio; the wire protocol between the app and the sidecar is the
+ * app's own business. Named `processApi` rather than `process` so importing it
+ * never shadows the global `process`.
+ */
+export const processApi = {
+    spawn: (options) => invoke("process.spawn", { ...options }),
+    /** Sends bytes to the child's stdin. Strings are encoded as UTF-8. */
+    write: (id, data) => invoke("process.write", { id, data: toBase64(data) }),
+    closeStdin: (id) => invoke("process.closeStdin", { id }),
+    /** SIGTERM, escalating to SIGKILL after five seconds. */
+    kill: (id, signal = "term") => invoke("process.kill", { id, signal }),
+    list: () => invoke("process.list"),
+    /** stdout chunks; concatenate `bytes` — chunk boundaries are arbitrary. */
+    onStdout: (handler) => subscribeProcessStream("process.stdout", handler),
+    onStderr: (handler) => subscribeProcessStream("process.stderr", handler),
+    onExit: (handler) => Mio.on("process.exit", (data) => handler(data)),
+};
+export const Mio = {
+    get ready() {
+        return getMio().then((bridge) => bridge.ready);
+    },
+    /** `connecting` | `open` | `closed`; changes arrive as `bridge.state`. */
+    async connectionState() {
+        return (await getMio()).state;
+    },
+    async invoke(method, params) {
+        return await invoke(method, params);
+    },
+    async on(name, handler) {
+        return (await getMio()).on(name, handler);
+    },
+    async off(name, handler) {
+        (await getMio()).off(name, handler);
+    },
+    async once(name, handler) {
+        return (await getMio()).once(name, handler);
+    },
+    process: processApi,
+    native: nativeApi,
+};
+export const app = {
+    info: () => invoke("app.info"),
+    /** Absolute directories the app owns; `app` is the writable sandbox. */
+    paths: () => invoke("app.paths"),
+    /**
+     * Appends a timestamped `level message` line to `logs/mio.log` (rotated at
+     * ~1 MB). Android has no console, so the file is the useful sink.
+     */
+    log: (level, message) => invoke("app.log", { level, message }),
+    quit: () => invoke("app.quit"),
+};
+export const platform = {
+    info: () => invoke("platform.info"),
+};
+export const fs = {
+    readText: (path) => invoke("fs.readText", { path }),
+    writeText: (path, text) => invoke("fs.writeText", { path, text }),
+    appendText: (path, text) => invoke("fs.appendText", { path, text }),
+    // Binary reads and writes go through the HTTP blob endpoint: they stream and
+    // avoid the base64 round trip that the JSON methods need.
+    readBytes: async (path) => (await getMio()).readBlob(path),
+    writeBytes: async (path, data) => await (await getMio()).writeBlob(path, data),
+    list: (path = ".") => invoke("fs.list", { path }),
+    stat: (path) => invoke("fs.stat", { path }),
+    mkdir: (path) => invoke("fs.mkdir", { path }),
+    remove: (path, recursive = false) => invoke("fs.remove", { path, recursive }),
+    rename: (from, to) => invoke("fs.rename", { from, to }),
+    exists: (path) => invoke("fs.exists", { path }),
+    /** URL usable with fetch() for streaming reads (Range supported). */
+    blobUrl: async (path) => (await getMio()).blobUrl(path),
+};
+export const dialog = {
+    openFile: (extensions) => invoke("dialog.openFile", { extensions }),
+    openDirectory: () => invoke("dialog.openDirectory"),
+    saveFile: (suggestedName) => invoke("dialog.saveFile", { suggestedName }),
+};
+export const clipboard = {
+    readText: () => invoke("clipboard.readText"),
+    writeText: (text) => invoke("clipboard.writeText", { text }),
+};
+export const shell = {
+    openExternal: (url) => invoke("shell.openExternal", { url }),
+    /**
+     * Opens a file from the app sandbox with the system default application.
+     * Windows only: Android would need a content provider Mio does not ship.
+     */
+    openPath: (path) => invoke("shell.openPath", { path }),
+    /** Shows a sandbox file or folder in Explorer, selected when possible. */
+    reveal: (path) => invoke("shell.reveal", { path }),
+};
+export const windowApi = {
+    state: () => invoke("window.state"),
+    setTitle: (title) => invoke("window.setTitle", { title }),
+    minimize: () => invoke("window.minimize"),
+    maximize: () => invoke("window.maximize"),
+    restore: () => invoke("window.restore"),
+    close: () => invoke("window.close"),
+    center: () => invoke("window.center"),
+    moveTo: (x, y) => invoke("window.moveTo", { x, y }),
+    setSize: (width, height) => invoke("window.setSize", { width, height }),
+    setFullScreen: (fullScreen) => invoke("window.setFullScreen", { fullScreen }),
+    setAlwaysOnTop: (alwaysOnTop) => invoke("window.setAlwaysOnTop", { alwaysOnTop }),
+};
+export default Mio;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+export interface MioBootstrap {
+    port: number;
+    token: string;
+    apiVersion: string;
+    platform: string;
+    app: {
+        id: string;
+        name: string;
+        version: string;
+    };
+}
+export type BridgeState = "connecting" | "open" | "closed";
+export interface MioBridge {
+    readonly __mio: true;
+    readonly apiVersion: string;
+    readonly platform: string;
+    readonly app: {
+        id?: string;
+        name?: string;
+        version?: string;
+    };
+    readonly ready: Promise<{
+        apiVersion: string;
+        platform: string;
+        app: Record<string, unknown>;
+    }>;
+    /** Transport state; changes are reported as the `bridge.state` event. */
+    readonly state: BridgeState;
+    invoke<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    on(name: string, handler: (data: unknown) => void): () => void;
+    off(name: string, handler: (data: unknown) => void): void;
+    once(name: string, handler: (data: unknown) => void): () => void;
+    /** Absolute URL of the blob endpoint for a file, usable with fetch(). */
+    blobUrl(path: string): string;
+    /** Read a file over HTTP (streaming, no base64 overhead). */
+    readBlob(path: string): Promise<Uint8Array>;
+    /** Write a file over HTTP. */
+    writeBlob(path: string, data: ArrayBuffer | ArrayBufferView): Promise<void>;
+}
+declare global {
+    interface Window {
+        Mio?: MioBridge;
+        __MIO_BOOT__?: MioBootstrap;
+    }
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@iyexin/mio-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "Typed Mio bridge API for web applications",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./bootstrap": "./bootstrap.js",
+    "./bootstrap.js": "./bootstrap.js"
+  },
+  "files": [
+    "dist",
+    "bootstrap.js"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iYeXin/Mio.git",
+    "directory": "packages/api"
+  },
+  "homepage": "https://github.com/iYeXin/Mio#readme",
+  "bugs": {
+    "url": "https://github.com/iYeXin/Mio/issues"
+  },
+  "keywords": [
+    "mio",
+    "flutter",
+    "webview",
+    "web-app",
+    "android",
+    "windows"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test"
+  }
 }