@lingxia/types 0.10.0 → 0.11.1

package/dist/generated/logic.d.ts

@@ -0,0 +1,1909 @@
+declare const appDownloadPathBrand: unique symbol;
+declare const systemDownloadsPathBrand: unique symbol;
+export interface PageConfig<TData extends Record<string, unknown> = Record<string, unknown>> {
+    data?: TData;
+    onLoad?: (options?: PageLoadOptions) => void | Promise<void>;
+    onShow?: () => void | Promise<void>;
+    onReady?: () => void | Promise<void>;
+    onHide?: () => void | Promise<void>;
+    onUnload?: () => void | Promise<void>;
+    onPullDownRefresh?: () => void | Promise<void>;
+    [key: string]: unknown;
+}
+export interface PageInstance<TData extends Record<string, unknown> = Record<string, unknown>> {
+    data: TData;
+    route: string;
+    /**
+     * Available when this page was opened as a surface via `lx.openSurface(...)`.
+     */
+    surface?: Surface;
+    /**
+     * Available when this page was opened by `lx.navigateTo(...)`.
+     */
+    opener?: PageMessagePort;
+    setData(data: Partial<TData> | Record<string, unknown>, callback?: () => void): void;
+}
+/**
+ * Injected by the runtime into methods listed in `stream_handlers` page metadata.
+ *
+ * Use this when your async source uses callbacks rather than an async iterator.
+ * For the generator form (`async *method()`), no handle is needed — the runtime
+ * pumps the generator automatically.
+ */
+export interface StreamHandle<T = unknown> {
+    /** Send a chunk to View. */
+    send(payload: T): void;
+    /** End the stream with an optional final value. */
+    end(result?: unknown): void;
+    /** End the stream with an error. */
+    error(code: string, message?: string): void;
+}
+/**
+ * Injected by the runtime as the second parameter when View opens a channel.
+ *
+ * Use `ch.send()` to push data to View, `ch.on()` to receive data/close
+ * events from View, and `ch.close()` to shut down the channel.
+ */
+export interface ChannelHandle<TSend = unknown, TReceive = unknown> {
+    /** Push a message to View. */
+    send(payload: TSend): void;
+    /** Close the channel from Logic side. */
+    close(code?: string, reason?: string): void;
+    /** Register a listener for incoming events. */
+    on(event: 'data', handler: (payload: TReceive) => void): void;
+    on(event: 'close', handler: (info: {
+        code: string;
+        reason: string;
+    }) => void): void;
+}
+/**
+ * Download options.
+ *
+ * - `app`: app-owned temporary output, or durable `lx://userdata` output when
+ *   `filePath` is set
+ * - `downloads`: user-visible system Downloads output, requiring
+ *   `security.privileges: ["downloads"]` in `lxapp.json`
+ *
+ * Default: `app`.
+ */
+export type DownloadOptions<TDestination extends DownloadDestination = DownloadDestination> = TDestination extends 'downloads' ? DownloadsDownloadOptions : AppDownloadOptions;
+export type DownloadResultForDestination<TDestination extends DownloadDestination> = TDestination extends 'downloads' ? DownloadsDownloadResult : AppDownloadResult;
+export interface DownloadProgressEvent<TResult extends DownloadResult = DownloadResult> {
+    kind: 'progress' | 'paused' | 'resumed' | 'canceled' | 'completed';
+    downloadedBytes?: number;
+    totalBytes?: number;
+    /** Present only when the total size is known. */
+    progress?: number;
+    result?: TResult;
+}
+export interface DownloadIteratorResult<TResult extends DownloadResult = DownloadResult> {
+    done: boolean;
+    value?: DownloadProgressEvent<TResult>;
+}
+export interface DownloadTask<TDownloadResult extends DownloadResult = DownloadResult> extends PromiseLike<TDownloadResult>, AsyncIterable<DownloadProgressEvent<TDownloadResult>> {
+    next(): Promise<DownloadIteratorResult<TDownloadResult>>;
+    /** Stops iteration only. Does not cancel the underlying download task. */
+    return(): Promise<DownloadIteratorResult<TDownloadResult>>;
+    catch<TRejected = never>(onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null): Promise<TDownloadResult | TRejected>;
+    finally(onfinally?: (() => void) | null): Promise<TDownloadResult>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    cancel(): Promise<void>;
+    /** Alias for cancel(), matching browser/mini-program abort naming. */
+    abort(): Promise<void>;
+    wait(): Promise<TDownloadResult>;
+}
+export interface FileManager {
+    readFile(options: ReadTextFileOptions): Promise<ReadTextFileResult>;
+    readFile(options: ReadBinaryFileOptions): Promise<ReadBinaryFileResult>;
+    readFile(options: ReadFileOptions): Promise<ReadFileResult>;
+}
+declare global {
+    interface HostAppApi {
+        /**
+         * The build environment from `app.json::envVersion`. It is fixed at boot
+         * and defaults to `release` for older artifacts.
+         */
+        readonly envVersion: HostAppEnvVersion;
+        /**
+         * Launch-at-startup control. Present only on macOS / Windows with the
+         * capability declared; gate access with `lx.app.autostart?.…`.
+         */
+        autostart?: AutostartApi;
+    }
+    /** Runtime environment constants backed by abstract `lx://` paths. */
+    interface LxEnv {
+    }
+    interface Lx {
+        /**
+         * Open a surface. Browser tabs resolve to `null`, declared surfaces to a
+         * host-managed handle, and page surfaces to a full `Surface`. URL asides
+         * return a `Surface` when docked and `null` in compact browser chrome.
+         * `as: "window"` is desktop-only.
+         */
+        openSurface(spec: OpenUrlTabSpec): Promise<null>;
+        openSurface(spec: OpenDeclaredSurfaceSpec | OpenLxappSurfaceSpec | OpenNativeSurfaceSpec): Promise<SurfaceHandle>;
+        openSurface(spec: OpenPageSurfaceSpec): Promise<Surface>;
+        openSurface(spec: OpenUrlAsideSpec): Promise<Surface | null>;
+        openSurface(spec: OpenSurfaceSpec): Promise<Surface | SurfaceHandle | null>;
+        /** Download to the downloads directory. */
+        downloadFile(options: DownloadsDownloadOptions): DownloadTask<DownloadsDownloadResult>;
+        /** Download to the lxapp-managed app directory. */
+        downloadFile(options: AppDownloadOptions): DownloadTask<AppDownloadResult>;
+        /** Download with a destination-correlated result type. */
+        downloadFile<TDestination extends DownloadDestination = "app">(options: DownloadOptions<TDestination>): DownloadTask<DownloadResultForDestination<TDestination>>;
+    }
+}
+export type ActionSheetResult = {
+    tapIndex: number;
+};
+export type AppConfig = {
+    globalData?: Record<string, unknown>;
+    onLaunch?: (options?: AppLaunchOptions) => void | Promise<void>;
+    onShow?: (args?: AppLifecycleEventArgs) => void | Promise<void>;
+    onHide?: (args?: AppLifecycleEventArgs) => void | Promise<void>;
+    onUserCaptureScreen?: () => void | Promise<void>;
+    [key: string]: unknown;
+};
+/** Runtime-managed app download path, usually under `lx://userdata`. */
+export type AppDownloadFilePath = string & {
+    readonly [appDownloadPathBrand]: 'app-download-file-path';
+};
+export type AppDownloadOptions = DownloadOptionsBase & {
+    /**
+     * Optional app-owned durable output path.
+     *
+     * Omit `filePath` to receive a temporary result in `tempFilePath`. Relative
+     * paths resolve under user data. `lx://` paths must target `lx://userdata`;
+     * `lx://usercache` is not accepted here.
+     */
+    filePath?: string;
+    /**
+     * App-owned output. Omit to use a temporary output unless `filePath` is set.
+     */
+    destination?: 'app';
+};
+export type AppDownloadResult = {
+    /**
+     * Temporary result.
+     *
+     * Not durable; move or copy it to `lx://userdata` if you need to keep it.
+     *
+     * When `filePath` is omitted, the runtime must be able to infer a file
+     * type from the URL or the server's `Content-Type` header.
+     */
+    tempFilePath: string;
+    filePath?: never;
+    mimeType?: string;
+    size: number;
+} | {
+    /** Durable destination under `lx://userdata`. */
+    filePath: AppDownloadFilePath;
+    tempFilePath?: never;
+    mimeType?: string;
+    size: number;
+};
+export type AppInstance = AppConfig & {
+    globalData: Record<string, unknown>;
+};
+export type AppLaunchOptions = {
+    path?: string;
+    query?: Record<string, string>;
+    scene?: number;
+    referrerInfo?: {
+        appId?: string;
+        extraData?: Record<string, unknown>;
+    };
+};
+export type AppLifecycleEventArgs = {
+    source: 'host' | 'lxapp';
+    reason: 'foreground' | 'background' | 'screenshot' | 'open' | 'close' | 'switch_back' | 'switch_away';
+};
+export type AppScreenshotOptions = {
+    /**
+     * Platform-specific window id to capture (desktop only). Omit to let the
+     * platform pick: the key/main window on desktop, the sole window on mobile.
+     */
+    windowId?: string;
+};
+export type AppScreenshotResult = {
+    /** `lx://` URI of the captured PNG in the lxapp temp directory. */
+    tempFilePath: string;
+    /** Image width in pixels, when the runtime could read it from the PNG. */
+    width?: number;
+    /** Image height in pixels, when the runtime could read it from the PNG. */
+    height?: number;
+};
+/**
+ * Launch-at-startup control for the host app.
+ * **macOS 13+ / Windows only.** Everywhere else — other platforms, or a
+ * macOS shell older than 13 — `lx.app.autostart` is absent (`undefined`);
+ * presence is the support check, so portable code gates on the member itself:
+ * ```ts
+ * if (lx.app.autostart) {
+ * // render the "Launch at startup" toggle
+ * }
+ * ```
+ * Requires `capabilities.autostart: true` in `lingxia.yaml`; without it the
+ * member is absent on all platforms. Declaring the capability never enables
+ * autostart by itself — the SDK registers the app only when `setEnabled(true)`
+ * is called, so the decision stays with the user (typically a settings-page
+ * toggle, default off).
+ * Host-app-level capability: like `checkUpdate` and `screenshot`, the methods
+ * are available only to the home lxapp; other lxapps receive a permission
+ * error.
+ */
+export type AutostartApi = {
+    /**
+     * Whether the app is currently registered to launch at startup, read from
+     * the OS (macOS login items / Windows `Run` registry key) — never a cached
+     * preference. The user can flip this outside the app (System Settings on
+     * macOS, Task Manager's Startup page on Windows), so re-read it whenever the
+     * settings UI is shown.
+     */
+    isEnabled(): Promise<boolean>;
+    /**
+     * Register or unregister the app as a startup item for the current user.
+     * Idempotent. On macOS the system may notify the user that a login item was
+     * added — only call this from an explicit user action.
+     */
+    setEnabled(on: boolean): Promise<void>;
+};
+export type BinaryFileData = ArrayBuffer | ArrayBufferView;
+export type CapsuleRect = {
+    width?: number;
+    height?: number;
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+export type ChooseDirectoryOptions = {
+    /** Initial directory the dialog opens in. Platform default if omitted. */
+    defaultPath?: string;
+};
+export type ChooseDirectoryResult = {
+    /** True if the user dismissed the dialog without selecting. */
+    canceled: boolean;
+    /** Native-consumable directory reference (path or URI). Undefined when canceled. */
+    path?: string;
+};
+export type ChooseFileOptions = {
+    /** Allow selecting multiple files. Default: false */
+    multiple?: boolean;
+    /** Optional file filters. Empty or omitted means all file types. */
+    filters?: FileDialogFilter[];
+    /**
+     * Initial directory the dialog opens in.
+     *
+     * When this resolves to an app-local directory, LingXia may use its internal
+     * file picker. When omitted, the platform system file picker is used.
+     */
+    defaultPath?: string;
+};
+export type ChooseFileResult = {
+    /** True if the user dismissed the dialog without selecting. */
+    canceled: boolean;
+    /**
+     * File paths returned by LingXia. Values may be app-local paths, `lx://...`
+     * paths, or platform system-picker references. Treat them as opaque strings
+     * and pass them back to LingXia APIs such as `lx.share`.
+     */
+    paths: string[];
+};
+export type ChooseMediaOptions = {
+    count?: number;
+    mediaType?: ('image' | 'video')[];
+    sourceType?: ('album' | 'camera')[];
+    camera?: 'back' | 'front';
+    maxDuration?: number;
+};
+export type ChosenMediaEntry = {
+    tempFilePath: string;
+    fileType: 'image' | 'video';
+    isOriginal: boolean;
+};
+export type CompressImageOptions = {
+    path: string;
+    quality?: number;
+    compressedWidth?: number;
+    compressedHeight?: number;
+};
+export type CompressImageResult = {
+    tempFilePath: string;
+};
+export type CompressVideoIteratorResult = {
+    done: boolean;
+    value?: CompressVideoProgressEvent;
+};
+export type CompressVideoOptions = {
+    /**
+     * Source video path or `lx://` URI.
+     */
+    path: string;
+    /**
+     * Cross-platform note: video compression parameters are best-effort and may map to
+     * native presets instead of exact encoder settings.
+     *
+     * Compression quality preset.
+     * When provided, `bitrate`, `fps`, and `resolution` are ignored.
+     */
+    quality?: VideoCompressQuality;
+    /**
+     * Preferred target video bitrate in kbps.
+     * May be adjusted or ignored by platform codec/runtime limitations.
+     */
+    bitrate?: number;
+    /**
+     * Preferred target frame rate in fps.
+     * Some platforms may ignore this option.
+     */
+    fps?: number;
+    /**
+     * Target resolution scale ratio relative to source size, in range `(0, 1]`.
+     * May be approximated or ignored by platform transcoder capabilities.
+     */
+    resolution?: number;
+    /**
+     * Optional output path for compressed file.
+     */
+    outputPath?: string;
+};
+export type CompressVideoProgressEvent = {
+    /** Transcode progress in percent, `0`-`100`. */
+    progress: number;
+};
+export type CompressVideoResult = {
+    tempFilePath: string;
+    width: number;
+    height: number;
+    durationMs: number;
+    /**
+     * Output file size in bytes.
+     * Could be close to source size when platform falls back to source content.
+     */
+    size: number;
+    type: string;
+};
+/**
+ * Handle returned by `lx.compressVideo`.
+ * Awaiting the task resolves with the final {@link CompressVideoResult}.
+ * Iterating it with `for await` yields {@link CompressVideoProgressEvent}s
+ * while the transcode runs.
+ */
+export type CompressVideoTask = PromiseLike<CompressVideoResult> & AsyncIterable<CompressVideoProgressEvent> & {
+    next(): Promise<CompressVideoIteratorResult>;
+    /** Stops iteration only. Does not cancel the compression. */
+    return(): Promise<CompressVideoIteratorResult>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<CompressVideoResult | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<CompressVideoResult>;
+    /**
+     * Cancels the transcode and deletes any partial output.
+     * The task promise rejects with an `AbortError` (`code: 'E_ABORT'`).
+     */
+    cancel(): void;
+    wait(): Promise<CompressVideoResult>;
+};
+export type ConnectWifiOptions = {
+    SSID: string;
+    password?: string;
+};
+export type CopyFileOptions = {
+    srcPath: string;
+    destPath: string;
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+/** Display and orientation APIs. */
+export type DeviceOrientation = "portrait" | "landscape";
+export type DeviceOrientationChangeEvent = {
+    value: DeviceOrientation;
+};
+export type DownloadDestination = 'app' | 'downloads';
+export type DownloadOptionsBase = {
+    /** HTTP(S) source URL. */
+    url: string;
+    /**
+     * Optional request headers.
+     * Restricted headers such as `Referer` are ignored by the runtime.
+     */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds. */
+    timeout?: number;
+    /** Optional abort signal. */
+    signal?: AbortSignal;
+};
+export type DownloadResult = AppDownloadResult | DownloadsDownloadResult;
+export type DownloadsDownloadOptions = DownloadOptionsBase & {
+    /**
+     * Optional filename hint for the system Downloads destination.
+     * This is not an app-owned FileManager path.
+     */
+    filePath?: string;
+    /** Save into the user's system Downloads directory. */
+    destination: 'downloads';
+};
+export type DownloadsDownloadResult = {
+    /** Native system Downloads path. Do not pass this to `FileManager`. */
+    filePath: SystemDownloadsPath;
+    tempFilePath?: never;
+    mimeType?: string;
+    size: number;
+};
+export type ExistsOptions = {
+    path: string;
+};
+export type ExtractVideoThumbnailOptions = {
+    /**
+     * Source video path or `lx://` URI.
+     */
+    path: string;
+    /**
+     * Optional output image path. If omitted, runtime chooses a temporary path.
+     */
+    outputPath?: string;
+    /**
+     * Max output width in pixels.
+     * Optional; when set with/without `maxHeight`, output keeps aspect ratio (no cropping).
+     */
+    maxWidth?: number;
+    /**
+     * Max output height in pixels.
+     * Optional; when set with/without `maxWidth`, output keeps aspect ratio (no cropping).
+     */
+    maxHeight?: number;
+    /**
+     * Target frame time in milliseconds from video start.
+     * `0` means first frame.
+     */
+    timeMs?: number;
+    /**
+     * JPEG quality in range `0-100`.
+     */
+    quality?: number;
+};
+export type ExtractVideoThumbnailResult = {
+    /**
+     * Generated thumbnail file path.
+     */
+    tempFilePath: string;
+    /**
+     * Output image width in pixels.
+     */
+    width: number;
+    /**
+     * Output image height in pixels.
+     */
+    height: number;
+    /**
+     * Output MIME type, usually `image/jpeg`.
+     */
+    type: string;
+};
+export type FileDialogFilter = {
+    /** Optional label shown in the native dialog. */
+    name?: string;
+    /** Allowed extensions without dots, e.g. ['pdf', 'txt']. */
+    extensions: string[];
+};
+/** Media picker, preview, scan, and file processing APIs. */
+export type GetImageInfoOptions = {
+    path: string;
+};
+/** Location APIs. */
+export type GetLocationOptions = {
+    type?: 'wgs84' | 'gcj02';
+    altitude?: boolean;
+    isHighAccuracy?: boolean;
+    highAccuracyExpireTime?: number;
+};
+export type GetVideoInfoOptions = {
+    /**
+     * Video file path or `lx://` URI.
+     */
+    path: string;
+};
+export type HostAppApi = globalThis.HostAppApi;
+/**
+ * Build-time environment version of the host app.
+ * Surfaced via {@link HostAppApi.envVersion}. Mirrors the
+ * `crates/lingxia-update::ReleaseType` enum and the `envVersion` field in the
+ * generated `app.json`. Pre-envVersion app artifacts are treated as `'release'`.
+ * Note: this is *separate* from `LxAppEnvVersion` in the navigator module,
+ * which encodes lxapp release channels (`'develop' | 'preview' | 'release'`)
+ * for cross-app navigation URLs and uses the truncated `develop` form.
+ */
+export type HostAppEnvVersion = 'developer' | 'preview' | 'release';
+export type HostAppUpdateApplyStage = 'download' | 'install';
+export type HostAppUpdateCheckResult = {
+    hasUpdate: false;
+    update?: never;
+} | {
+    hasUpdate: true;
+    update: HostAppUpdateInfo;
+};
+export type HostAppUpdateEvent = {
+    state: 'downloading';
+    downloadedBytes?: number;
+    progress?: number;
+} | {
+    state: 'downloaded' | 'installRequested';
+} | {
+    state: 'failed';
+    stage: HostAppUpdateApplyStage;
+    error: string;
+};
+export type HostAppUpdateInfo = {
+    version: string;
+    size?: number;
+    releaseNotes?: string[];
+    isForceUpdate: boolean;
+    /**
+     * Download and apply this checked update.
+     *
+     * `apply()` is single-use for this update object.
+     *
+     * The returned task can be awaited directly when progress is not needed, or
+     * consumed with `for await...of` to render progress.
+     *
+     * Direct package handoff is currently supported on Android and macOS. Other
+     * platforms reject with an unsupported-operation error; use `version` and
+     * `releaseNotes` to guide users to the appropriate app marketplace.
+     */
+    apply(): HostAppUpdateTask;
+};
+export type HostAppUpdateIteratorResult = {
+    done: boolean;
+    value?: HostAppUpdateEvent;
+};
+export type HostAppUpdateResult = {
+    state: 'installRequested';
+};
+export type HostAppUpdateTask = PromiseLike<HostAppUpdateResult> & AsyncIterable<HostAppUpdateEvent> & {
+    next(): Promise<HostAppUpdateIteratorResult>;
+    /** Stops iteration only. It does not cancel an app update already handed to the platform. */
+    return(): Promise<HostAppUpdateIteratorResult>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<HostAppUpdateResult | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<HostAppUpdateResult>;
+    wait(): Promise<HostAppUpdateResult>;
+};
+/**
+ * Input event APIs.
+ * Platform support: Android only
+ */
+export type KeyEvent = {
+    /** Key value following W3C naming (e.g. "Enter", "ArrowLeft", "a") */
+    key: string;
+    /** Physical key code (e.g. "ENTER", "DPAD_LEFT") */
+    code: string;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    metaKey?: boolean;
+    repeat?: boolean;
+};
+export type KeyEventCallback = (event: KeyEvent) => void;
+export type LxAppEnvVersion = 'release' | 'preview' | 'develop';
+/** LxApp metadata APIs. */
+export type LxAppReleaseType = 'release' | 'preview' | 'developer';
+export type LxEnv = globalThis.LxEnv;
+/** Device action APIs. */
+export type MakePhoneCallOptions = {
+    phoneNumber: string;
+};
+export type MediaObjectFit = 'cover' | 'contain' | 'fill' | 'fit';
+export type MediaRotation = 0 | 90 | 180 | 270;
+export type MkdirOptions = {
+    path: string;
+    recursive?: boolean;
+};
+export type ModalResult = {
+    confirm: boolean;
+    cancel: boolean;
+};
+export type NavigateBackOptions = {
+    delta: number;
+};
+export type NavigateToLxAppOptions = {
+    appId: string;
+    page?: string;
+    path?: string;
+    query?: PageQuery;
+    envVersion?: LxAppEnvVersion;
+    targetVersion?: string;
+};
+export type NavigateToOptions = PageTargetOptions;
+export type NetworkChangeCallback = (info: NetworkInfo) => void;
+export type NetworkInfo = {
+    isConnected: boolean;
+    networkType: NetworkType;
+    ipv4: string[];
+    ipv6: string[];
+};
+/** Network status APIs. */
+export type NetworkType = 'none' | 'unknown' | 'wifi' | '2g' | '3g' | '4g' | '5g' | 'ethernet';
+/**
+ * Show a surface declared by id in the host's `lingxia.yaml`.
+ * Available to any lxapp granted access to that declaration.
+ */
+export type OpenDeclaredSurfaceSpec = {
+    surface: string;
+    /** Docking edge override for this open. */
+    edge?: SurfaceEdge;
+    page?: never;
+    url?: never;
+    lxapp?: never;
+    native?: never;
+    as?: never;
+    position?: never;
+    size?: never;
+    query?: never;
+};
+/** File system APIs. */
+export type OpenFileOptions = {
+    /** Local file path or runtime-managed temp path. */
+    filePath: string;
+    /** Optional coarse file type hint such as `pdf`, `docx`, or `xlsx`. */
+    fileType?: string;
+    /**
+     * `auto`: prefer native review, then fall back to external open.
+     * `review`: require native review UI and reject when unsupported.
+     * `external`: hand off directly to the system / external app.
+     */
+    mode?: 'auto' | 'review' | 'external';
+    /** Hint for whether the native review UI should expose its action menu when supported. */
+    showMenu?: boolean;
+};
+/**
+ * Open another lxapp by appId (home lxapp only). A declared surface
+ * toggles its shell presentation; an undeclared lxapp opens as a main
+ * tab, or docks as an aside panel with `as: 'aside'`.
+ */
+export type OpenLxappSurfaceSpec = {
+    lxapp: string;
+    /** Defaults to the lingxia.yaml role, else 'main'. */
+    as?: 'main' | 'aside' | 'float';
+    /**
+     * Docking edge override for this open. Without it the surface keeps its
+     * current placement (initially the `lingxia.yaml` edge); with it the panel
+     * opens there — or moves there if already visible.
+     */
+    edge?: SurfaceEdge;
+    page?: never;
+    url?: never;
+    native?: never;
+    position?: never;
+    size?: never;
+    query?: never;
+};
+/**
+ * Open a host-registered native capability (home lxapp only), e.g.
+ * the built-in terminal declared in `lingxia.yaml` surfaces.
+ */
+export type OpenNativeSurfaceSpec = {
+    native: string;
+    /** Docking edge override for this open. */
+    edge?: SurfaceEdge;
+    page?: never;
+    url?: never;
+    lxapp?: never;
+    as?: never;
+    position?: never;
+    size?: never;
+    query?: never;
+};
+/**
+ * Spec for {@link OpenSurfaceSpec}. A discriminated union keyed by source so a
+ * page name and a declared surface id never collide (each is its own string
+ * space, separately type-checkable).
+ * - `{ page }` — one of this lxapp's own pages, by name, arranged as `as`
+ * (`float` is a popup; `window` is a bare desktop window, which rejects on
+ * mobile). `position` applies to `float`, and `size` is a Host-clamped hint.
+ * They are fixed at open (re-open to change). Your own pages **cannot** be
+ * docked as an `aside` — an aside is external content only (see `{ url }`).
+ * For a side panel of your own, use a declared `surface`, an in-page split
+ * layout, or `role: main` for a switchable destination.
+ * `float` is a popup layered above the main at `position` (like a dialog); it
+ * takes no layout space. `interaction` controls the native close button,
+ * outside-click dismissal, and modality. Defaults are no button,
+ * `tapOutside`, and non-modal.
+ * - `{ surface }` — a surface declared in `lingxia.yaml` `surfaces:`, by id
+ * (e.g. `'terminal'`, `'ai-assistant'`). Form, position, and startup data come
+ * from the declaration.
+ * - `{ url }` — external content in the in-app browser. Without `as` it opens as
+ * a main browser tab (the **self** browser: full chrome **with an editable
+ * address bar**, no handle). With `as: 'aside'` it opens in the **browser
+ * aside** — a docked (large screen) / full-screen (phone) **multi-tab** browser
+ * for external content only (`https://` or `file://`).
+ * The aside is **API-only** and never permits address editing or a manual
+ * "new tab" action. Desktop may show the current address read-only; compact
+ * phone/Runner chrome omits the address row entirely.
+ * Tabs are **deduped by URL** — reopening a URL focuses the existing tab and
+ * preserves its current navigation. On `medium` / `expanded`, the returned
+ * handle is **tab-scoped**: `close()` closes that tab. Compact browser chrome
+ * owns the group and returns `null`. Closing the last tab closes the aside;
+ * dismissing it only hides the group. The tab UI shows page **titles** (never
+ * the URL), plus per-tab close, back/forward, refresh, and dismissal.
+ * Presentation is the only large/small difference: on `medium` / `expanded`
+ * the aside **docks** and splits beside the main at `edge` (default `'right'`)
+ * with a horizontal title tab strip; on `compact` (phone / runner) it presents
+ * **full-screen** with a single-row **bottom** browser toolbar (tabs reached
+ * via an aside-only switcher). System/edge Back and the toolbar dismiss action
+ * exit the whole aside even when page history exists; the explicit browser
+ * Back button navigates history. `size` is a host-clamped preferred size
+ * (large screen only).
+ */
+export type OpenPageSurfaceSpec = {
+    page: string;
+    /** A popup above the main. */
+    as: 'float';
+    position?: SurfaceFloatPosition;
+    size?: OverlaySurfaceSize;
+    interaction?: SurfaceInteraction;
+    query?: Record<string, unknown>;
+    edge?: never;
+    surface?: never;
+    url?: never;
+} | {
+    page: string;
+    as: 'window';
+    size?: WindowSurfaceSize;
+    /** Windows use manual dismissal; `tapOutside` is invalid. */
+    interaction?: SurfaceInteraction;
+    query?: Record<string, unknown>;
+    edge?: never;
+    position?: never;
+    surface?: never;
+    url?: never;
+};
+export type OpenSurfaceSpec = OpenPageSurfaceSpec | OpenDeclaredSurfaceSpec | OpenLxappSurfaceSpec | OpenNativeSurfaceSpec | OpenUrlTabSpec | OpenUrlAsideSpec;
+/**
+ * Open `url` in the multi-tab browser aside. `url` must be `https://` or
+ * `file://` (external content only). Repeated calls add/focus tabs (deduped by
+ * URL) in the single aside per window. Medium/expanded returns a tab-scoped
+ * handle; compact returns `null` because browser chrome owns the group. See
+ * {@link OpenSurfaceSpec} for the full aside contract.
+ */
+export type OpenUrlAsideSpec = {
+    url: string;
+    as: 'aside';
+    edge?: SurfaceEdge;
+    size?: OverlaySurfaceSize;
+    page?: never;
+    surface?: never;
+    position?: never;
+    query?: never;
+};
+export type OpenUrlTabSpec = {
+    url: string;
+    as?: never;
+    page?: never;
+    surface?: never;
+    edge?: never;
+    position?: never;
+    size?: never;
+    query?: never;
+};
+export type OverlaySurfaceSize = {
+    /** Width hint. */
+    width?: OverlaySurfaceSizeValue;
+    /** Height hint. */
+    height?: OverlaySurfaceSizeValue;
+};
+/**
+ * Size hint for an overlay surface (aside / float).
+ * - number: absolute px, must be > 0
+ * - `${number}%`: percentage of the container, 0 < N ≤ 100
+ */
+export type OverlaySurfaceSizeValue = number | `${number}%`;
+export type PageLoadOptions = {
+    [key: string]: string | undefined;
+};
+export type PageMessagePort = {
+    postMessage(message: unknown): void;
+    onMessage(handler: (message: unknown) => void): () => void;
+};
+export type PageQuery = Record<string, PageQueryValue>;
+export type PageQueryValue = string | number | boolean | null | undefined;
+/**
+ * Target page for `navigateTo`, `redirectTo`, `switchTab`, and `reLaunch`.
+ * Pass exactly one of `page` or `path`; there is no `url` field. Page
+ * names and routes are discoverable with `lxdev lxapp pages`.
+ */
+export type PageTargetOptions = {
+    /** Configured page name from `lingxia.yaml` / `lxapp.json`. */
+    page: string;
+    path?: never;
+    query?: PageQuery;
+} | {
+    /** Full page route, for example `/pages/home/index`. */
+    path: string;
+    page?: never;
+    query?: PageQuery;
+};
+export type PreviewMediaAdvance = 'manual' | 'next' | 'loop';
+/** One change-stream event / the `current` snapshot. */
+export type PreviewMediaChange = {
+    index: number;
+    source: PreviewMediaShownSource;
+};
+export type PreviewMediaCloseReason = 'manual' | 'completed' | 'interrupted' | 'error';
+/**
+ * Handle returned synchronously from `lx.previewMedia(...)` — synchronous so
+ * listeners can be attached before the first event fires:
+ * - `presented` resolves once the first pixel of the underlying media has
+ * been composited to screen. Use this to time the hide of an overlay
+ * surface above the preview so the swap is seamless. Never rejects;
+ * resolves with no value when the first frame is up. Safe to ignore.
+ * - `current` is a live `{ index, source }` snapshot of the item on screen,
+ * updated as the user swipes and as the session auto-advances.
+ * - `onChange(listener)` fires for every item change. Returns an
+ * unsubscribe function.
+ * - `completed` resolves `{ reason, index, source }` when the preview
+ * session ends (manual / auto / interrupted / error), or rejects on abort.
+ * If the call was aborted before any frame was presented, `presented` still
+ * resolves (with no value) once the abort takes effect — it never rejects,
+ * to keep fire-and-forget usage safe.
+ * @example
+ * const preview = lx.previewMedia({ sources, startIndex: 2 });
+ * preview.onChange(({ source }) => markAsViewed(source.path));
+ * const { reason, source } = await preview.completed;
+ */
+export type PreviewMediaHandle = {
+    readonly presented: Promise<void>;
+    readonly current: PreviewMediaChange;
+    onChange(listener: (change: PreviewMediaChange) => void): () => void;
+    readonly completed: Promise<PreviewMediaResult>;
+};
+export type PreviewMediaOptions = string | PreviewMediaSingleOptions | PreviewMediaSequenceOptions;
+export type PreviewMediaResult = {
+    /**
+     * Why the preview session finished.
+     */
+    reason: PreviewMediaCloseReason;
+    /**
+     * Index of the item on screen when the session closed.
+     */
+    index: number;
+    /**
+     * The item on screen when the session closed — "what the user just
+     * viewed/played", without mapping `index` back yourself.
+     */
+    source: PreviewMediaShownSource;
+};
+export type PreviewMediaSequenceOptions = {
+    /**
+     * Preview list. Supports images, videos, or a mixed queue.
+     */
+    sources: PreviewMediaSource[];
+    /**
+     * Initial item index in `sources`.
+     * Must be an integer.
+     * Out-of-range values are clamped by runtime.
+     * Default: `0`.
+     */
+    startIndex?: number;
+    /**
+     * Auto behavior for the preview session.
+     *
+     * - `manual`: never auto-advance
+     * - `next`: advance to the next item; if already on the last item, close the session
+     * - `loop`: advance to the next item; if already on the last item, wrap to the first item
+     *
+     * Default: `manual`
+     */
+    advance?: PreviewMediaAdvance;
+    /**
+     * Optional cancellation signal for the preview request.
+     *
+     * Aborting rejects the returned promise with a cancellation error and requests the active
+     * native preview session to close immediately.
+     */
+    signal?: AbortSignal;
+    /**
+     * Whether to show the top `current/total` indicator.
+     *
+     * Default: `true` when previewing multiple items, otherwise `false`.
+     */
+    showIndexIndicator?: boolean;
+};
+/**
+ * The item the user is (or was) looking at, handed back as the caller
+ * described it — `path` is returned verbatim, so it can be matched against
+ * the caller's own data without re-indexing an array.
+ */
+export type PreviewMediaShownSource = {
+    /** The path exactly as passed in the request. */
+    path: string;
+    /** Resolved media kind (after extension inference when `type` was omitted). */
+    type: 'image' | 'video';
+};
+export type PreviewMediaSingleOptions = PreviewMediaSource & {
+    /**
+     * Auto behavior for the preview session.
+     *
+     * - `manual`: never auto-advance
+     * - `next`: advance to the next item; if already on the last item, close the session
+     * - `loop`: advance to the next item; if already on the last item, wrap to the first item
+     *
+     * Default: `manual`
+     */
+    advance?: PreviewMediaAdvance;
+    /**
+     * Optional cancellation signal for the preview request.
+     *
+     * Aborting rejects the returned promise with a cancellation error and requests the active
+     * native preview session to close immediately.
+     */
+    signal?: AbortSignal;
+    /**
+     * Whether to show the top `current/total` indicator.
+     *
+     * Default: `true` when previewing multiple items, otherwise `false`.
+     */
+    showIndexIndicator?: boolean;
+};
+export type PreviewMediaSource = {
+    /**
+     * Media source path.
+     * Recommended: `lx://` path (for example `lx://usercache/...`) or a sandbox-local path
+     * that can be resolved by runtime access rules.
+    */
+    path: string;
+    type?: 'image' | 'video';
+    /**
+     * Optional clockwise rotation in degrees (`0 | 90 | 180 | 270`).
+     * Default: when omitted, runtime resolves orientation from media metadata.
+     */
+    rotate?: MediaRotation;
+    /**
+     * Optional display fit mode for video preview.
+     * Default: `contain`.
+     */
+    objectFit?: MediaObjectFit;
+    /**
+     * Display duration in milliseconds.
+     * Effective when preview `advance` is not `manual`.
+     */
+    durationMs?: number;
+};
+export type ReLaunchOptions = PageTargetOptions;
+export type ReadBinaryFileOptions = {
+    filePath: string;
+    encoding?: undefined;
+};
+export type ReadBinaryFileResult = {
+    data: ArrayBuffer;
+};
+export type ReadDirOptions = {
+    path: string;
+};
+export type ReadFileOptions = ReadTextFileOptions | ReadBinaryFileOptions;
+export type ReadFileResult = ReadTextFileResult | ReadBinaryFileResult;
+export type ReadTextFileOptions = {
+    filePath: string;
+    encoding: 'utf8' | 'base64';
+};
+export type ReadTextFileResult = {
+    data: string;
+};
+export type RedirectToOptions = PageTargetOptions;
+export type RemoveOptions = {
+    path: string;
+    recursive?: boolean;
+};
+export type RenameOptions = {
+    oldPath: string;
+    newPath: string;
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+export type SaveMediaOptions = {
+    filePath: string;
+};
+export type ScanCodeOptions = {
+    onlyFromCamera?: boolean;
+    scanType?: ('barCode' | 'qrCode' | 'datamatrix' | 'pdf417')[];
+};
+export type ScanCodeResult = {
+    scanResult: string;
+    scanType: string;
+};
+/** Share images, PDFs, or other files. */
+export type ShareFilesOptions = ShareTitleOptions & {
+    /**
+     * File paths returned by LingXia APIs to share. Images, PDFs, and other
+     * documents are all represented as file paths.
+     *
+     * Use `lx.chooseFile` for system files and `lx.chooseMedia` for picked media;
+     * pass the returned path here without parsing it.
+     * Some platforms or receivers may limit multi-file shares. Share files one
+     * at a time when targeting those receivers.
+     *
+     * `files` and `page` are mutually exclusive.
+     * `text` is intentionally not supported for file shares because system
+     * receivers handle text+attachment inconsistently.
+     */
+    files: string[];
+    page?: never;
+    text?: never;
+};
+export type ShareOptions = ShareTextOptions | SharePageOptions | ShareFilesOptions;
+export type SharePage = /**
+ * Share the current page.
+ */ true
+/**
+ * Share the current page with query.
+ */
+ | {
+    /**
+     * Query appended to the current page. Query belongs to the page target and is
+     * encoded into the AppLink URL.
+     */
+    query?: ShareQuery;
+};
+/** Share the current page as an AppLink. */
+export type SharePageOptions = ShareTextBaseOptions & {
+    /**
+     * Share the current page. The runtime uses the current appId and page path
+     * implicitly and shares it through the host AppLink configuration.
+     *
+     * Rejects when the host app has no `appLinks.hosts` configuration because
+     * receivers would not be able to open the shared page.
+     *
+     * `title` and `text` are presentation hints. Platforms and receivers may
+     * ignore them; on iOS the URL is shared by itself so receivers can render it
+     * as a webpage card when they support that.
+     *
+     * `page` and `files` are mutually exclusive.
+     */
+    page: SharePage;
+    files?: never;
+};
+/** Share APIs. */
+export type ShareQuery = Record<string, string | number | boolean>;
+export type ShareResult = {
+    /**
+     * Best-effort completion flag. Some platforms can only confirm that the
+     * system share UI was opened or closed.
+     */
+    completed?: boolean;
+};
+export type ShareTextBaseOptions = ShareTitleOptions & {
+    /**
+     * Share text body.
+     */
+    text?: string;
+};
+/**
+ * Share title/text only. Receiver support is platform/app dependent; some
+ * share extensions may reject text-only shares.
+ */
+export type ShareTextOptions = ShareTextBaseOptions & {
+    page?: never;
+    files?: never;
+};
+export type ShareTitleOptions = {
+    /**
+     * Share title.
+     */
+    title?: string;
+};
+/**
+ * One app-declared shell activator. Its `id` remains stable across
+ * updates and activation. The shell only routes activation to the
+ * callback; the app owns every resulting action.
+ */
+export type ShellActivator = {
+    id: string;
+    icon: string;
+    label: string;
+    disabled?: boolean;
+    onActivate: () => void;
+};
+/** Mutable presentation fields for an existing activator. */
+export type ShellActivatorUpdate = {
+    icon?: string;
+    label?: string;
+    disabled?: boolean;
+};
+/** Shell chrome writer API (home lxapp only). */
+export type ShellApi = {
+    activators: ShellActivatorsApi;
+};
+export type ShowActionSheetOptions = {
+    itemList: string[];
+    itemColor?: string;
+};
+export type ShowModalOptions = {
+    title?: string;
+    content?: string;
+    showCancel?: boolean;
+    cancelText?: string;
+    cancelColor?: string;
+    confirmText?: string;
+    confirmColor?: string;
+};
+/** UI feedback, navigation, and surface control APIs. */
+export type ShowToastOptions = {
+    title: string;
+    icon?: 'success' | 'error' | 'loading' | 'none';
+    image?: string;
+    duration?: number;
+    mask?: boolean;
+    position?: 'top' | 'center' | 'bottom';
+};
+export type StatOptions = {
+    path: string;
+};
+/** Persistent key-value storage backed by the lxapp database. */
+export type Storage = {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    list(prefix?: string): Promise<IterableIterator<string>>;
+    info(): Promise<StorageInfo>;
+};
+/** Current persistent-storage usage and configured limits. */
+export type StorageInfo = {
+    currentSize: number;
+    limitSize: number;
+    keyCount: number;
+};
+export type StreamSourceOptions = {
+    provider: string;
+    isLive: boolean;
+    duration?: number;
+    params?: Record<string, unknown>;
+};
+export type Surface = SurfaceHandle & {
+    readonly kind: 'overlay' | 'window';
+    /**
+     * Last-known visibility, kept in sync with the native side via show/hide
+     * events. False once the surface has been closed. Safe to bind into
+     * declarative UI; for event-driven updates subscribe via `onShow`/`onHide`.
+     */
+    readonly visible: boolean;
+    /**
+     * True until `close()` fires. After close the surface is detached and the
+     * page instance is being torn down; further `show()` / `hide()` calls will
+     * reject.
+     */
+    readonly alive: boolean;
+    /**
+     * Sends a message to the other side of a page surface.
+     *
+     * For the opener this targets the opened page. For the opened page this
+     * targets the opener. URL surfaces have no page-side receiver.
+    */
+    postMessage(message: unknown): void;
+    onMessage(handler: (message: unknown) => void): () => void;
+    onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
+    /**
+     * Fires when the surface transitions to visible, regardless of whether
+     * `show()` was called on this side or on the peer. Returns an unsubscribe
+     * function. Only fires on real state changes — calling `show()` on an
+     * already-visible surface is a no-op for listeners.
+     */
+    onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+    /**
+     * Fires when the surface transitions to hidden, regardless of which side
+     * triggered it. Returns an unsubscribe function. Only fires on real state
+     * changes.
+     */
+    onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+    close(): Promise<void>;
+    /**
+     * Toggle the surface to visible without tearing it down. The page instance
+     * and its state survive a hide / show round-trip — only close() actually
+     * destroys the surface and fires the onClose listener. Idempotent: calling
+     * on an already-visible surface resolves without firing `onShow`.
+     */
+    show(): Promise<void>;
+    /**
+     * Hide the surface without destroying it. The page instance stays mounted,
+     * so a subsequent show() restores the same scroll position, form input,
+     * and JS state. Hidden surfaces still receive postMessage but are not
+     * visible to the user. Idempotent.
+     */
+    hide(): Promise<void>;
+};
+/**
+ * Surfaces (docked asides, floats, windows, browser tabs, declared surfaces)
+ * and the desktop tray — the types behind `lx.openSurface`, `lx.onSurfaceContext`,
+ * and `lx.tray`.
+ */
+export type SurfaceCloseReason = 'user' | 'programmatic' | 'owner_closed' | 'app_closed' | 'failed'
+/**
+ * The SDK reclaimed a long-hidden overlay surface for resource reasons.
+ * Treat as a normal close: the page instance is gone; further postMessage /
+ * show / hide calls will fail. The opener may immediately reopen if needed.
+ */
+ | 'reclaimed' | 'unknown';
+export type SurfaceClosedEvent = {
+    id: string;
+    kind: 'overlay' | 'window';
+    reason: SurfaceCloseReason;
+};
+/**
+ * The current surface viewport context, delivered to `lx.onSurfaceContext()`
+ * so an lxapp can self-adapt (e.g. switch column count by `sizeClass`).
+ */
+export type SurfaceContext = {
+    /** compact (<600) / medium (600–840) / expanded (>840), with hysteresis. */
+    sizeClass: 'compact' | 'medium' | 'expanded';
+    /** Actual surface viewport width in logical pixels. */
+    width: number;
+    /** Actual surface viewport height in logical pixels. */
+    height: number;
+};
+/** Edge an aside docks to; the Host decides the realized form by screen size. */
+export type SurfaceEdge = 'left' | 'right' | 'top' | 'bottom';
+/** Where a float popup anchors (default `center`). */
+export type SurfaceFloatPosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
+export type SurfaceHandle = {
+    readonly id: string;
+    /** Standalone windows have no role in the primary shell graph. */
+    readonly role?: SurfaceRole;
+    readonly presentation: SurfacePresentation;
+    readonly visible: boolean;
+    readonly alive: boolean;
+    /**
+     * Show a host-managed surface. Dynamic page/url surfaces return a Promise;
+     * host-declared surfaces may complete synchronously.
+     */
+    show(): void | Promise<void>;
+    /**
+     * Hide without destroying user-visible state when the platform supports it.
+     */
+    hide(): void | Promise<void>;
+    /**
+     * Destroy the live surface. Repeated close calls are idempotent.
+     */
+    close(): void | Promise<void>;
+    onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+    onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+    onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
+};
+/** Native interaction supplied by the host around page content. */
+export type SurfaceInteraction = {
+    /** Show the standard circular close button. Default `false`. */
+    closeButton?: boolean;
+    /** Default `tapOutside` for floats and `manual` for windows. */
+    dismiss?: 'tapOutside' | 'manual';
+    /** Block interaction with content below. Default `false`. */
+    modal?: boolean;
+};
+export type SurfacePresentation = 'main' | 'dock' | 'overlay' | 'popover' | 'sheet' | 'window';
+export type SurfaceRole = 'main' | 'aside' | 'float';
+/**
+ * Detail payload for `onShow` / `onHide` events. `source` identifies which
+ * Surface object initiated the visibility change so observers can
+ * distinguish self-driven transitions from peer-driven ones (e.g. an opener
+ * UI that wants to update its own button state only when the page side
+ * toggled visibility).
+ */
+export type SurfaceVisibilityEvent = {
+    id: string;
+    kind: 'overlay' | 'window';
+    source: 'opener' | 'page';
+};
+export type SwitchTabOptions = PageTargetOptions;
+/** Native system Downloads path. Do not pass this to `FileManager`. */
+export type SystemDownloadsPath = string & {
+    readonly [systemDownloadsPathBrand]: 'system-downloads-path';
+};
+export type TabBarRedDotOptions = {
+    index: number;
+};
+export type TrayApi = globalThis.TrayApi;
+/**
+ * Runtime control of the menu-bar (macOS) / system-tray (Windows) status item.
+ * The tray is declared in `lingxia.yaml` (`tray:`); these update its dynamic
+ * content at runtime.
+ * **Desktop only.** Mobile platforms have no tray, so every method here is a
+ * no-op there (it never throws) — safe to call from portable code. For an
+ * app-icon badge that *is* cross-platform (including mobile), use
+ * `lx.app.setBadge`.
+ */
+export type TrayMenuItem = {
+    label: string;
+    /** Invoked when this item is clicked. */
+    onClick?: () => void;
+    enabled?: boolean;
+    checked?: boolean;
+};
+export type TrayMenuSeparator = {
+    separator: true;
+};
+export type UpdateFailedInfo = UpdateReadyInfo & {
+    error?: string;
+};
+/** Runtime update APIs. */
+export type UpdateManager = {
+    applyUpdate(): void;
+    onUpdateReady(callback: (info: UpdateReadyInfo) => void): void;
+    onUpdateFailed(callback: (info: UpdateFailedInfo) => void): void;
+};
+export type UpdateReadyInfo = {
+    version?: string;
+    isForceUpdate?: boolean;
+    channel?: "release" | "preview" | "developer" | string;
+};
+export type UploadIteratorResult = {
+    done: boolean;
+    value?: UploadProgressEvent;
+};
+export type UploadOptions = {
+    /** HTTP(S) destination URL. */
+    url: string;
+    /** Local file path or runtime-managed URI to upload. */
+    filePath: string;
+    /** Multipart field name. Default: `file`. */
+    name?: string;
+    /**
+     * Optional request headers.
+     * Restricted headers such as `Referer` are ignored by the runtime.
+     */
+    headers?: Record<string, string>;
+    /** Optional extra `multipart/form-data` text fields. */
+    formData?: Record<string, string>;
+    /** Request timeout in milliseconds. */
+    timeout?: number;
+    /** Override multipart filename. */
+    fileName?: string;
+    /** Override file MIME type. */
+    mimeType?: string;
+    /** Optional abort signal. */
+    signal?: AbortSignal;
+};
+export type UploadProgressEvent = {
+    kind: 'progress' | 'canceled' | 'completed';
+    uploadedBytes?: number;
+    totalBytes?: number;
+    progress?: number;
+    result?: UploadResult;
+};
+export type UploadResult = {
+    /** HTTP status code returned by the server. */
+    statusCode: number;
+    /** Response body decoded as UTF-8 text. */
+    data: string;
+};
+export type UploadTask = PromiseLike<UploadResult> & AsyncIterable<UploadProgressEvent> & {
+    next(): Promise<UploadIteratorResult>;
+    /** Stops iteration only. Does not cancel the underlying upload task. */
+    return(): Promise<UploadIteratorResult>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<UploadResult | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<UploadResult>;
+    cancel(): Promise<void>;
+    wait(): Promise<UploadResult>;
+};
+export type VideoCompressQuality = 'low' | 'medium' | 'high';
+export type VideoContext = {
+    play(): void;
+    pause(): void;
+    stop(): void;
+    seek(position: number): void;
+    requestFullScreen(): void;
+    exitFullScreen(): void;
+    setStreamSource(options: StreamSourceOptions): void;
+};
+/**
+ * Local video metadata for client-side upload preflight and presentation.
+ * Track-level codec and audio fields are best-effort. The receiving service
+ * must still validate the uploaded bytes; this result does not indicate
+ * whether the file already exists in cloud storage.
+ */
+export type VideoInfo = {
+    /**
+     * Encoded display width in pixels.
+     */
+    width: number;
+    /**
+     * Encoded display height in pixels.
+     */
+    height: number;
+    /**
+     * Video duration in milliseconds.
+     */
+    durationMs: number;
+    /**
+     * Exact local file size in bytes.
+     */
+    size: number;
+    /**
+     * Clockwise rotation in degrees (usually `0 | 90 | 180 | 270`).
+     */
+    rotation?: number;
+    /**
+     * Average bitrate in bits per second (bps).
+     */
+    bitrate?: number;
+    /**
+     * Frame rate in frames per second (fps).
+     */
+    fps?: number;
+    /**
+     * Best-effort container MIME type, e.g. `video/mp4`.
+     * It may be inferred from the file extension when the platform does not expose it.
+     */
+    type?: string;
+    /**
+     * Normalized video-track codec MIME type. Known values include `video/avc`,
+     * `video/hevc`, `video/x-vnd.on2.vp8`, `video/x-vnd.on2.vp9`, `video/av01`,
+     * `video/mp4v-es`, `video/mpeg2`, and `video/mjpeg`. Other valid `video/*`
+     * values may be returned for codecs added by the platform. Omitted when the
+     * platform cannot determine it.
+     */
+    videoCodec?: string;
+    /**
+     * Whether an audio track was detected. Omitted when the platform cannot determine it.
+     */
+    hasAudio?: boolean;
+    /**
+     * Best-effort audio-track codec MIME type, e.g. `audio/mp4a-latm` or `audio/opus`.
+     * Omitted when there is no audio track or the platform cannot determine it.
+     */
+    audioCodec?: string;
+    /**
+     * Resolved path used by runtime (typically `lx://...`).
+     */
+    path: string;
+};
+export type WifiConnectedCallback = (info: WifiConnectedInfo) => void;
+export type WifiConnectedInfo = WifiInfo & {
+    connected: boolean;
+    state: string;
+};
+export type WindowSurfaceSize = {
+    /** Initial window width in logical pixels. */
+    width?: number;
+    /** Initial window height in logical pixels. */
+    height?: number;
+};
+export type WriteBinaryFileOptions = {
+    filePath: string;
+    data: BinaryFileData;
+    encoding?: never;
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+export type WriteFileOptions = WriteTextFileOptions | WriteBinaryFileOptions;
+export type WriteTextFileOptions = {
+    filePath: string;
+    data: string;
+    encoding?: 'utf8' | 'base64';
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+/** Host app base information. */
+export interface AppBaseInfo {
+    /**
+     * Raw system locale, unaffected by a saved in-app language override.
+     * For the language the UI should actually render in, use
+     * `display_language` instead.
+     */
+    locale: string;
+    /**
+     * Effective display language: a saved user override when set, else
+     * `locale`. This is what native chrome and `lx.*` i18n strings follow.
+     */
+    displayLanguage: string;
+    /**
+     * Platform family: `"iOS"` / `"macOS"` / `"Android"` / `"Windows"` /
+     * `"Harmony"`. Matches the View-side `usePlatform().os` value.
+     */
+    os: string;
+    productName: string;
+    version: string;
+    SDKVersion: string;
+}
+/** Device info APIs. */
+export interface DeviceInfo {
+    brand: string;
+    model: string;
+    marketName: string;
+    osName: string;
+    osVersion: string;
+}
+export interface FileStats {
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymlink: boolean;
+    size: number;
+    lastModifiedTime?: number;
+    lastAccessedTime?: number;
+    createTime?: number;
+}
+export interface ImageInfo {
+    width: number;
+    height: number;
+    type: string;
+    path: string;
+}
+/** Location information */
+export interface LocationInfo {
+    /** Latitude, range -90~90, negative for south */
+    latitude: number;
+    /** Longitude, range -180~180, negative for west */
+    longitude: number;
+    /** Speed in m/s */
+    speed?: number;
+    /** Position accuracy in meters (smaller = more accurate) */
+    accuracy?: number;
+    /** Altitude in meters */
+    altitude?: number;
+    /** Vertical accuracy in meters */
+    verticalAccuracy?: number;
+    /** Horizontal accuracy in meters */
+    horizontalAccuracy?: number;
+}
+export interface LxAppInfo {
+    appId: string;
+    appName: string;
+    version: string;
+    releaseType: LxAppReleaseType;
+}
+/** Options for removing TabBar badge */
+export interface RemoveTabBarBadgeOptions {
+    index: number;
+}
+export interface ScreenInfo {
+    width: number;
+    height: number;
+    scale: number;
+}
+/** Options for setNavigationBarColor */
+export interface SetNavigationBarColorOptions {
+    frontColor: string;
+    backgroundColor: string;
+}
+/** Options for setNavigationBarTitle */
+export interface SetNavigationBarTitleOptions {
+    title: string;
+}
+/** Options for setting TabBar badge */
+export interface SetTabBarBadgeOptions {
+    index: number;
+    text: string;
+}
+/** Options for setting TabBar item */
+export interface SetTabBarItemOptions {
+    index: number;
+    text?: string;
+    iconPath?: string;
+    selectedIconPath?: string;
+}
+/** Options for setting TabBar style */
+export interface SetTabBarStyleOptions {
+    color?: string;
+    selectedColor?: string;
+    backgroundColor?: string;
+    borderStyle?: string;
+}
+/** System setting status */
+export interface SystemSettingInfo {
+    bluetoothEnabled: boolean;
+    locationEnabled: boolean;
+    wifiEnabled: boolean;
+}
+/** Wi-Fi APIs. */
+export interface WifiInfo {
+    /** Service Set Identifier (network name) */
+    SSID: string;
+    /** Basic Service Set Identifier (MAC address) */
+    BSSID?: string;
+    /** Whether the network is secure (requires password) */
+    secure: boolean;
+    /** Signal strength (0-100, higher is better) */
+    signalStrength: number;
+    /** Center frequency in MHz (if available) */
+    frequency?: number;
+}
+export declare class DirEntry {
+    private constructor();
+    readonly name: string;
+    readonly isFile: boolean;
+    readonly isDirectory: boolean;
+    readonly isSymlink: boolean;
+}
+export declare class FileManager {
+    private constructor();
+    exists(options: ExistsOptions): Promise<boolean>;
+    stat(options: StatOptions): Promise<FileStats>;
+    readDir(options: ReadDirOptions): Promise<AsyncIterableIterator<DirEntry>>;
+    mkdir(options: MkdirOptions): Promise<void>;
+    readFile(options: never): Promise<never>;
+    writeFile(options: WriteFileOptions): Promise<void>;
+    copyFile(options: CopyFileOptions): Promise<void>;
+    rename(options: RenameOptions): Promise<void>;
+    remove(options: RemoveOptions): Promise<void>;
+}
+export declare class JSMessagePort {
+    constructor();
+    static postMessage(payload: any): void;
+    static onMessage(handler: (...args: any[]) => any): (...args: any[]) => any;
+}
+export declare class JSSurface {
+    constructor();
+    close(): Promise<void>;
+    postMessage(payload: any): void;
+    onMessage(handler: (...args: any[]) => any): (...args: any[]) => any;
+    static onClose(handler: (...args: any[]) => any): (...args: any[]) => any;
+}
+export declare class JSUpdateManager {
+    constructor();
+    /** Apply update by restarting the app */
+    applyUpdate(): void;
+    onUpdateReady(cb: (...args: any[]) => any): void;
+    onUpdateFailed(cb: (...args: any[]) => any): void;
+}
+export declare class JSVideoContext {
+    constructor();
+    play(): void;
+    pause(): void;
+    stop(): void;
+    seek(position: number): void;
+    requestFullScreen(): void;
+    exitFullScreen(): void;
+    setStreamSource(options: StreamSourceOptions): void;
+}
+declare global {
+    interface HostAppApi {
+        /**
+         * `lx.app.screenshot(options?)` — capture the host app's window as a PNG.
+         * App-level semantics, one level above any page/WebView capture: the image
+         * is what the user sees of the whole app — host-drawn navigation chrome,
+         * native overlays, and every composited WebView, not just this lxapp's web
+         * content. Because that view can include other lxapps' UI, the API is
+         * restricted to the home lxapp, like the other host-level APIs on `lx.app`.
+         */
+        screenshot(options?: AppScreenshotOptions): Promise<AppScreenshotResult>;
+        /**
+         * Check whether the host app has an update.
+         * This host-level capability is restricted to the home lxapp. Calling it opts
+         * the process into custom update handling. Incompatible updates are hidden as
+         * `hasUpdate: false`; platforms that cannot apply a package may still return
+         * metadata and reject when `update.apply()` is invoked.
+         */
+        checkUpdate(): Promise<HostAppUpdateCheckResult>;
+        readonly envVersion: HostAppEnvVersion;
+        getBaseInfo(): AppBaseInfo;
+        /**
+         * Exit the host app immediately without a confirmation dialog.
+         * If the user should confirm first, call `lx.showModal(...)` and invoke this
+         * only after confirmation.
+         */
+        exit(): void;
+        /**
+         * Set the app-icon badge, for example an unread count.
+         * This targets the dock on macOS, taskbar on Windows, and home/launcher icon
+         * on mobile. Null or an empty string clears it. Unsupported platforms treat
+         * the call as a no-op.
+         */
+        setBadge(value: string | number | null): void;
+    }
+}
+declare global {
+    interface Lx {
+        readonly app: HostAppApi;
+        vibrateShort(): boolean;
+        vibrateLong(): boolean;
+        makePhoneCall(options: MakePhoneCallOptions): boolean;
+        getDeviceInfo(): DeviceInfo;
+        getScreenInfo(): ScreenInfo;
+        getNetworkInfo(): Promise<NetworkInfo>;
+        onNetworkChange(callback: NetworkChangeCallback): void;
+        offNetworkChange(callback?: NetworkChangeCallback): void;
+        /** Initialize WiFi module */
+        startWifi(): Promise<void>;
+        /** Stop WiFi module */
+        stopWifi(): Promise<void>;
+        /**
+         * Connect to WiFi (async - waits for request submission, not actual connection)
+         * This function returns when the connection request is successfully submitted to the system.
+         * The actual connection status will be reported via onWifiConnected event.
+         */
+        connectWifi(options: ConnectWifiOptions): Promise<void>;
+        /** Get WiFi list (scan results) */
+        getWifiList(): Promise<WifiInfo[]>;
+        /** Get connected WiFi info */
+        getConnectedWifi(): Promise<WifiInfo>;
+        onWifiConnected(callback: WifiConnectedCallback): void;
+        offWifiConnected(callback?: WifiConnectedCallback): void;
+        setDeviceOrientation(orientation: DeviceOrientation): boolean;
+        onDeviceOrientationChange(callback: (event: DeviceOrientationChangeEvent) => void): void;
+        offDeviceOrientationChange(callback?: (event: DeviceOrientationChangeEvent) => void): void;
+        readonly env: LxEnv;
+        downloadFile(options: never): never;
+        uploadFile(options: UploadOptions): UploadTask;
+        /**
+         * Open a local file with the requested strategy.
+         * Use `mode: "review"` when the UX requires in-app preview; otherwise prefer
+         * `mode: "auto"`.
+         */
+        openFile(options: OpenFileOptions): Promise<void>;
+        chooseFile(options?: ChooseFileOptions): Promise<ChooseFileResult>;
+        chooseDirectory(options?: ChooseDirectoryOptions): Promise<ChooseDirectoryResult>;
+        getFileManager(): FileManager;
+        onKeyDown(callback: KeyEventCallback): void;
+        offKeyDown(callback?: KeyEventCallback): void;
+        onKeyUp(callback: KeyEventCallback): void;
+        offKeyUp(callback?: KeyEventCallback): void;
+        /** Get location function */
+        getLocation(options?: GetLocationOptions): Promise<LocationInfo>;
+        getLxAppInfo(): LxAppInfo;
+        getImageInfo(options: GetImageInfoOptions): Promise<ImageInfo>;
+        compressImage(options: CompressImageOptions): Promise<CompressImageResult>;
+        chooseMedia(options?: ChooseMediaOptions): Promise<ChosenMediaEntry[]>;
+        /**
+         * Synchronously returns a JS handle so listeners can be attached before the
+         * first event fires:
+         * - `presented`: Promise, resolves with no value when the first pixel of the
+         * underlying media is composited to screen. Also resolves unconditionally
+         * once `completed` settles, so consumers can safely ignore it (it never
+         * rejects).
+         * - `current`: `{ index, source }` snapshot of the item on screen, updated
+         * live as the user swipes / the session auto-advances.
+         * - `onChange(listener)`: fires `{ index, source }` for every item change
+         * (the initial item is seeded into `current`, and re-fired by native so
+         * late platforms still converge); returns an unsubscribe function.
+         * - `completed`: Promise resolving `{ reason, index, source }` when the
+         * session ends, or rejecting on abort / error. `source` is the item that
+         * was on screen when the preview closed — handed back verbatim so the
+         * caller never re-indexes their own array.
+         */
+        previewMedia(options: PreviewMediaOptions): PreviewMediaHandle;
+        saveImageToPhotosAlbum(options: SaveMediaOptions): Promise<void>;
+        saveVideoToPhotosAlbum(options: SaveMediaOptions): Promise<void>;
+        scanCode(options?: ScanCodeOptions): Promise<ScanCodeResult>;
+        createVideoContext(componentId: string): VideoContext;
+        /**
+         * Reads local video metadata for upload preflight and presentation.
+         * Size, dimensions, duration, and path form the portable core. Container type,
+         * rotation, and track-level codec/audio fields are best-effort and may be
+         * omitted when the platform cannot determine them. The receiving service must
+         * still validate the uploaded bytes.
+         */
+        getVideoInfo(options: GetVideoInfoOptions): Promise<VideoInfo>;
+        extractVideoThumbnail(options: ExtractVideoThumbnailOptions): Promise<ExtractVideoThumbnailResult>;
+        compressVideo(options: CompressVideoOptions): CompressVideoTask;
+        navigateToLxApp(options: NavigateToLxAppOptions): Promise<void>;
+        navigateBackLxApp(): Promise<void>;
+        share(options: ShareOptions): Promise<ShareResult>;
+        getStorage(): Storage;
+        /**
+         * `lx.openSurface(spec)` — unified surface entry point. The spec is a
+         * discriminated union keyed by exactly one of `page`, `surface`, or `url`:
+         * - `{ page, as, position?, size?, query? }` opens one of this lxapp's own
+         * pages as a `float` (overlay popup) or a `window` (bare standalone desktop
+         * window). Pages cannot be docked as an `aside` — an aside shows external
+         * content only.
+         * - `{ surface, edge?, query? }` shows a host-declared surface by its `ui` id.
+         * - `{ url }` opens an authorized HTTPS/file URL in the in-app chromed browser.
+         */
+        openSurface(spec: never): Promise<never>;
+        /** `lx.openExternal(url)` — hand the url off to the OS default browser. */
+        openExternal(url: string): void;
+        /**
+         * `lx.onSurfaceContext(handler)` — register a JS callback (scoped to this
+         * lxapp's JS context), invoke it immediately, then again whenever that
+         * presentation's actual viewport changes. Returns an unsubscribe fn.
+         */
+        onSurfaceContext(handler: (context: SurfaceContext) => void): () => void;
+        getSystemSetting(): SystemSettingInfo;
+        /** Show action sheet function for JavaScript */
+        showActionSheet(options: ShowActionSheetOptions): Promise<ActionSheetResult>;
+        /**
+         * Get capsule button bounding client rect (async)
+         * Returns Promise<{width, height, top, right, bottom, left}>
+         */
+        getCapsuleRect(): Promise<CapsuleRect>;
+        /** Show modal function (async) */
+        showModal(options: ShowModalOptions): Promise<ModalResult>;
+        /** Set navigation bar title */
+        setNavigationBarTitle(options: SetNavigationBarTitleOptions): boolean;
+        /** Set navigation bar color */
+        setNavigationBarColor(options: SetNavigationBarColorOptions): boolean;
+        /** Hide home button */
+        hideHomeButton(): boolean;
+        /**
+         * lx.startPullDownRefresh()
+         * Programmatically start the pull-to-refresh animation.
+         * This will show the refresh indicator and trigger the onPullDownRefresh lifecycle method.
+         */
+        startPullDownRefresh(): void;
+        /**
+         * lx.stopPullDownRefresh()
+         * Stop the pull-to-refresh animation.
+         * This should be called after the refresh operation is complete.
+         */
+        stopPullDownRefresh(): void;
+        /** Navigate to a new page (forward navigation) */
+        navigateTo(options: NavigateToOptions): Promise<PageMessagePort>;
+        /** Navigate back to previous page */
+        navigateBack(options: NavigateBackOptions): void;
+        /** Redirect to a new page (replace current page) */
+        redirectTo(options: RedirectToOptions): Promise<void>;
+        /** Switch to a tab page */
+        switchTab(options: SwitchTabOptions): Promise<void>;
+        /** Relaunch to a new page (clear page stack) */
+        reLaunch(options: ReLaunchOptions): Promise<void>;
+        readonly shell: ShellApi;
+        /** Show TabBar red dot */
+        showTabBarRedDot(options: TabBarRedDotOptions): boolean;
+        /** Hide TabBar red dot */
+        hideTabBarRedDot(options: TabBarRedDotOptions): boolean;
+        /** Set TabBar badge */
+        setTabBarBadge(options: SetTabBarBadgeOptions): boolean;
+        /** Remove TabBar badge */
+        removeTabBarBadge(options: RemoveTabBarBadgeOptions): boolean;
+        /** Show TabBar */
+        showTabBar(): Promise<boolean>;
+        /** Hide TabBar */
+        hideTabBar(): Promise<boolean>;
+        /** Set TabBar style */
+        setTabBarStyle(options: SetTabBarStyleOptions): boolean;
+        /** Set TabBar item */
+        setTabBarItem(options: SetTabBarItemOptions): boolean;
+        /** Show toast function */
+        showToast(options: ShowToastOptions): Promise<void>;
+        /** Hide toast function */
+        hideToast(): Promise<void>;
+        readonly tray: TrayApi;
+        getUpdateManager(): UpdateManager;
+    }
+}
+declare global {
+    interface LxEnv {
+        readonly USER_DATA_PATH: 'lx://userdata';
+        readonly USER_CACHE_PATH: 'lx://usercache';
+    }
+}
+declare global {
+    interface ShellActivatorsApi {
+        /**
+         * Atomically replaces the complete desktop activator declaration. Home lxapp
+         * only. Relative icons resolve from the home app bundle. Every entry is bound
+         * to its generation-scoped callback; `replace([])` explicitly clears chrome.
+         */
+        replace(items: ShellActivator[]): void;
+        /** Updates presentation fields for one stable id. Home lxapp only. */
+        update(id: string, patch: ShellActivatorUpdate): void;
+        /** Removes one stable id from the declaration. Home lxapp only. */
+        remove(id: string): void;
+        /** Clears the current runtime declaration. Home lxapp only. */
+        clear(): void;
+    }
+}
+declare global {
+    interface TrayApi {
+        /** lx.tray.setBadge(value) — the menu-bar / system-tray badge. Null/empty clears it. */
+        setBadge(value: string | number | null): void;
+        /** lx.tray.setIcon(icon) — replace the tray icon (a resource path). */
+        setIcon(icon: string): void;
+        /** lx.tray.setTitle(text) — text shown beside the icon (macOS). Empty clears it. */
+        setTitle(text: string | null): void;
+        /**
+         * lx.tray.setMenu(items) — replace the tray dropdown menu. Each item is
+         * `{ label, onClick?, enabled?, checked? }` or `{ separator: true }`. The native
+         * menu is built from labels; clicks are routed back to each item's `onClick` by
+         * index over the app event bus.
+         */
+        setMenu(items: Array<TrayMenuItem | TrayMenuSeparator>): void;
+        /**
+         * lx.tray.onClick(handler) — left-click on the tray icon. While at least one
+         * handler is registered, the left-click runs only the handler(s); the tray's
+         * configured surface action is suppressed. Returns an unsubscribe function.
+         */
+        onClick(handler: () => void): () => void;
+        /** lx.tray.show() — show the tray status item. */
+        show(): void;
+        /** lx.tray.hide() — hide the tray status item. */
+        hide(): void;
+    }
+}
+export {};
+//# sourceMappingURL=logic.d.ts.map