@lingxia/types 0.10.0 → 0.12.0

package/src/generated/logic.ts

@@ -0,0 +1,2753 @@
+// Generated by rong-typegen from the lingxia module's Rust source.
+// Do not edit by hand — run `npm run gen:logic` in packages/lingxia-types to regenerate.
+
+// Keep generic TypeScript-only aliases, correlated overloads, and types owned
+// by external Rong modules in this generated prelude.
+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.surface.openPage(...)`.
+   */
+  surface?: PageSurface;
+  /**
+   * 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>;
+}
+
+declare global {
+  // HostAppApi/LxEnv members are emitted from the Rust js_api metadata; these
+  // merges only add what Rong cannot express — the cfg-gated autostart member
+  // and doc comments (js_api consts cannot carry docs). envVersion re-declares
+  // the generated member doc-only; tsc rejects the merge if the types drift.
+  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. Absent where the host cannot register a
+     * startup item; its presence and `lx.supports({ capability: 'autostart' })` always
+     * agree, so `lx.app.autostart?.…` and the query are interchangeable.
+     */
+    autostart?: AutostartApi;
+  }
+
+  /** Runtime environment constants backed by abstract `lx://` paths. */
+  interface LxEnv {}
+
+  interface Lx {
+    /**
+     * Terminal product settings. Present only in the host-bundled Terminal
+     * Settings lxapp when the host declares `capabilities.terminal`; its
+     * presence and `lx.supports({ capability: 'terminal' })` always agree.
+     */
+    readonly terminal?: TerminalApi;
+
+    /** 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>>;
+
+    /**
+     * Open this lxapp's store with every key's shape pinned on the handle.
+     * `get` / `set` / `delete` then share that schema instead of
+     * repeating `get<T>()` at each call site.
+     */
+    getStorage<S extends StorageSchema>(): TypedStorage<S>;
+  }
+}
+
+/**
+ * A map of storage keys to stored value shapes.
+ *
+ * `object` deliberately accepts both type aliases and interfaces. Requiring a
+ * string index signature would reject ordinary interface-based schemas.
+ */
+export type StorageSchema = object;
+
+type StorageKey<S extends object> = Extract<keyof S, string>;
+type StorageEntry<S extends object> = {
+  [K in StorageKey<S>]: [key: K, value: S[K]];
+}[StorageKey<S>];
+
+/**
+ * Schema-typed view of the same store `lx.getStorage()` returns.
+ * Runtime is identical; only the key/value types are pinned.
+ *
+ * The schema constrains what this handle writes and reads, not what the store
+ * contains: a previous app version, or another code path holding the untyped
+ * handle, can have written keys outside it. That is why `list` still resolves
+ * plain strings — narrowing it to the schema's keys would be the same
+ * unchecked assertion this type exists to remove from `get<T>()`.
+ */
+export type TypedStorage<S extends object> = {
+  get<K extends StorageKey<S>>(key: K): Promise<S[K] | undefined>;
+  set(...entry: StorageEntry<S>): Promise<void>;
+  delete(key: StorageKey<S>): Promise<void>;
+  clear(): Promise<void>;
+  list(prefix?: string): Promise<string[]>;
+  info(): Promise<StorageInfo>;
+};
+
+/**
+ * Result of `lx.showActionSheet`. Branch on `canceled` before reading
+ * the selected item index.
+ */
+export type ActionSheetResult = {
+    canceled: false;
+    /** Index of the tapped item in `itemList`. */
+    index: number;
+} | CanceledResult;
+
+/** Every surface handle, narrowable by `kind`. */
+export type AnySurface = PageSurface | DeclaredSurface | AppSurface | TabSurface | BuiltinSurface;
+
+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;
+};
+
+/** Another lxapp composed into a shell slot. */
+export type AppSurface = SurfaceBase & SurfaceShowable & {
+    readonly kind: 'app';
+    readonly realized: 'main' | 'aside';
+};
+
+export type AppearanceApi = globalThis.AppearanceApi;
+
+export type AppearancePreference = 'auto' | 'light' | 'dark';
+
+/**
+ * Launch-at-startup control for the host app.
+ * Absent (`undefined`) wherever the host cannot register a startup item.
+ * `lx.supports({ capability: 'autostart' })` and the member's presence always
+ * agree, so either gate works:
+ * ```ts
+ * if (lx.supports({ capability: '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;
+
+/**
+ * Built-in browser product page. Opening one requires
+ * `capabilities.browser` and is restricted to the home lxapp.
+ */
+export type BuiltinShellPage = 'settings' | 'downloads';
+
+/**
+ * A host builtin page such as settings or downloads. The shell owns
+ * its lifetime and its visibility, so this handle reports identity:
+ * there is no `show` / `hide`, and the inherited `close()` rejects
+ * with `unsupported_placement`.
+ */
+export type BuiltinSurface = SurfaceBase & {
+    readonly kind: 'builtin';
+};
+
+/** The user dismissed the operation. Never an error. */
+export type CanceledResult = {
+    canceled: true;
+};
+
+export type ChooseDirectoryOptions = {
+    /** Initial directory the dialog opens in. Platform default if omitted. */
+    defaultPath?: string;
+};
+
+/**
+ * Result of `lx.chooseDirectory`. Branch on `canceled` before reading
+ * the selected directory.
+ */
+export type ChooseDirectoryResult = {
+    canceled: false;
+    /** Native-consumable directory reference (path or URI). */
+    path: string;
+} | CanceledResult;
+
+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;
+};
+
+/**
+ * Result of `lx.chooseFile`. Branch on `canceled` before reading the
+ * selected paths.
+ */
+export type ChooseFileResult = {
+    canceled: false;
+    /**
+     * File paths returned by LingXia; always at least one. 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, ...string[]];
+} | CanceledResult;
+
+export type ChooseMediaOptions = {
+    count?: number;
+    mediaType?: ('image' | 'video')[];
+    sourceType?: ('album' | 'camera')[];
+    camera?: 'back' | 'front';
+    maxDuration?: number;
+};
+
+/**
+ * Result of `lx.chooseMedia`. Branch on `canceled` before reading the
+ * selected entries.
+ */
+export type ChooseMediaResult = {
+    canceled: false;
+    /** Picked media; always at least one entry. */
+    entries: [ChosenMediaEntry, ...ChosenMediaEntry[]];
+} | CanceledResult;
+
+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;
+};
+
+/** A surface declared by the host in `lingxia.yaml`. */
+export type DeclaredSurface = SurfaceBase & SurfaceShowable & {
+    readonly kind: 'declared';
+};
+
+/** 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 `lx.fs` 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 `lx.fs`. */
+    filePath: SystemDownloadsPath;
+    tempFilePath?: never;
+    mimeType?: string;
+    size: number;
+};
+
+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[];
+};
+
+export type FileSystemApi = globalThis.FileSystemApi;
+
+export type FsCopyOptions = {
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+
+export type FsMkdirOptions = {
+    recursive?: boolean;
+};
+
+export type FsRemoveOptions = {
+    recursive?: boolean;
+};
+
+export type FsRenameOptions = {
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+
+export type FsWriteOptions = {
+    /**
+     * How string input is interpreted. Strings are UTF-8 by default; `base64`
+     * decodes the input into raw bytes before writing.
+     */
+    encoding?: 'utf8' | 'base64';
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+
+/** 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.
+     *
+     * Requires `lx.supports({ capability: 'selfUpdate' })`. Where the host cannot
+     * install its own update it rejects with an unsupported-operation error;
+     * use `version` and `releaseNotes` to guide users to the 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>;
+};
+
+export type InstalledTerminalFont = {
+    family: string;
+    monospace: boolean;
+    ligatures: boolean;
+    nerdIcons: boolean;
+};
+
+/**
+ * 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';
+
+/** Boolean capability names accepted by `lx.supports`. */
+export type LxCapabilityFlag = 'terminal' | 'autostart' | 'notifications' | 'browser' | 'proxy' | 'selfUpdate' | 'process' | 'appUse' | 'computerUse' | 'browserUse' | 'mediaCapture';
+
+/**
+ * One capability question per call. The catalog is closed, so
+ * completion enumerates it and a typo is a type error. `capability`
+ * is the discriminant; only the `surface` branch accepts a `value`.
+ * Two surface answers describe an *affordance*, not whether the call
+ * succeeds: `tab` is "the host has an in-app browser" — without it a
+ * url still opens, in the OS browser instead — and `aside` is "a
+ * docked region exists right now", while a compact layout still opens
+ * the url through the in-app browser's own chrome. Ask them to decide
+ * what to render, not whether to call.
+ * `chrome` qualifies a window and only a window: it asks whether this
+ * host can produce that decoration, not merely a window.
+ */
+export type LxCapabilityQuery = {
+    capability: 'surface';
+    value: 'window';
+    chrome?: WindowChrome;
+} | {
+    capability: 'surface';
+    value: Exclude<LxSurfaceCapability, 'window'>;
+} | {
+    capability: LxCapabilityFlag;
+};
+
+export type LxEnv = globalThis.LxEnv;
+
+/** Surface placements accepted by `lx.supports`. */
+export type LxSurfaceCapability = 'main' | 'aside' | 'float' | 'window' | 'tab';
+
+/** Device action APIs. */
+export type MakePhoneCallOptions = {
+    phoneNumber: string;
+};
+
+export type MediaObjectFit = 'cover' | 'contain' | 'fill' | 'fit';
+
+export type MediaRotation = 0 | 90 | 180 | 270;
+
+/**
+ * Result of `lx.showModal`. `canceled: false` means the user confirmed;
+ * there is no third resolved outcome. Presentation failures reject.
+ */
+export type ModalResult = {
+    canceled: false;
+} | CanceledResult;
+
+/**
+ * One app-declared action shown in the host-provided More affordance.
+ * Mobile hosts render these in the capsule sheet; desktop hosts render
+ * them in the lxapp context menu. The native menu is fully dismissed
+ * before `onClick` runs.
+ */
+export type MoreAction = {
+    /** Bundled resource path or an app-accessible local `lx://` path. */
+    icon: string;
+    /** Visible action label. */
+    label: string;
+    onClick: () => void | Promise<void>;
+};
+
+/**
+ * Options for `lx.navigateBack()`. Omit the object or `delta` to pop
+ * one page.
+ */
+export type NavigateBackOptions = {
+    /** Number of pages to pop. Defaults to 1. */
+    delta?: number;
+};
+
+/**
+ * Navigate to another lxapp inside the current App Surface. JavaScript
+ * callers address pages by their configured name; page routes are an
+ * internal runtime detail and are not accepted as input.
+ */
+export type NavigateToAppOptions = {
+    appId: string;
+    /**
+     * Configured page name from the target lxapp's `lxapp.json`. Omit it to
+     * open the target app's initial page. Full routes such as
+     * `/pages/home/index` are not supported.
+     */
+    page?: string;
+    query?: PageQuery;
+    envVersion?: LxAppEnvVersion;
+    targetVersion?: string;
+};
+
+export type NavigateToOptions = PageTargetOptions;
+
+export type NavigationBarApi = globalThis.NavigationBarApi;
+
+export type NavigationBarPatch = {
+    title?: string | null;
+    homeButton?: VisibilityPreference;
+    style?: NavigationBarStylePatch | null;
+};
+
+export type NavigationBarStylePatch = {
+    backgroundColor?: string | null;
+    foregroundColor?: string | null;
+    dividerColor?: string | null;
+};
+
+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';
+
+/** 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;
+};
+
+/**
+ * `as` picks the shape. A float anchors and carries no decoration; a
+ * window is decorated and does not anchor. The runtime rejects the
+ * wrong pairing either way, so the type says it first — except with an
+ * ordered preference, where the realized placement is not known up
+ * front and both stay open.
+ */
+export type OpenPageOptions = (OpenPageShared & {
+    /** The default. Rejects when the host cannot float. */
+    as?: 'float';
+    /** Where the float anchors. */
+    position?: SurfaceFloatPosition;
+    chrome?: never;
+}) | (OpenPageShared & {
+    /** A separate desktop window. Rejects when the host cannot make one. */
+    as: 'window';
+    /** Window decoration. */
+    chrome?: WindowChrome;
+    position?: never;
+}) | (OpenPageShared & {
+    /**
+     * An ordered preference: the first placement the host can realize wins,
+     * and `realized` reports which.
+     */
+    as: readonly ('float' | 'window')[];
+    chrome?: WindowChrome;
+    position?: SurfaceFloatPosition;
+});
+
+export type OpenPageShared = {
+    /**
+     * A float accepts a percentage; a window is in logical pixels and ignores
+     * one. Both live here rather than in two option types, because `as` may be
+     * an ordered preference and the realized placement is not known up front.
+     */
+    size?: OverlaySurfaceSize;
+    interaction?: SurfaceInteraction;
+    query?: Record<string, unknown>;
+    /** Caller-owned identity, for `lx.surface.get(key)` later. */
+    key?: string;
+};
+
+export type OpenUrlOptions = {
+    /**
+     * `tab` opens a browser tab; `aside` docks the browser beside the main.
+     * Defaults to `'tab'`.
+     */
+    as?: 'tab' | 'aside' | readonly ('tab' | 'aside')[];
+    /** Preferred docking side when the realized placement is an aside. */
+    edge?: SurfaceEdge;
+    size?: OverlaySurfaceSize;
+    /** Stable identity for `lx.surface.get(key)`. */
+    key?: string;
+};
+
+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;
+
+/** One of this lxapp's own pages, opened as a float or a window. */
+export type PageSurface = SurfaceBase & SurfaceShowable & SurfaceMessaging & {
+    readonly kind: 'page';
+    readonly realized: 'float' | 'window';
+};
+
+/**
+ * Target page for `navigateTo`, `redirectTo`, `switchTab`, and `reLaunch`.
+ * JavaScript navigation accepts only the configured page name; full routes
+ * are internal runtime details. Discover names with `lxdev lxapp pages`.
+ */
+export type PageTargetOptions = {
+    /** Configured page name from `lingxia.yaml` / `lxapp.json`. */
+    page: string;
+    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 RedirectToOptions = PageTargetOptions;
+
+export type ResolvedAppearance = 'light' | 'dark';
+
+export type SaveMediaOptions = {
+    filePath: string;
+};
+
+export type ScanCodeOptions = {
+    onlyFromCamera?: boolean;
+    scanType?: ('barCode' | 'qrCode' | 'datamatrix' | 'pdf417')[];
+};
+
+/**
+ * Result of `lx.scanCode`. Branch on `canceled` before reading the scan
+ * payload.
+ */
+export type ScanCodeResult = {
+    canceled: false;
+    scanResult: string;
+    scanType: string;
+} | CanceledResult;
+
+/** 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 = {
+    /**
+     * What the share sheet reported. Not part of the `canceled` family: some
+     * platforms only observe that the system UI opened and closed, so the
+     * unknown case is stated rather than hidden in a missing boolean that
+     * every call site would read as "not shared".
+     */
+    outcome: 'completed' | 'dismissed' | 'unknown';
+};
+
+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;
+};
+
+/**
+ * App-owned host-shell chrome. Mutations are available only to the home
+ * lxapp's Logic context; other lxapps receive a permission error.
+ */
+export type ShellApi = {
+    /**
+     * Declares runtime actions in the desktop shell's sidebar header or footer.
+     * The shell controls layout and only dispatches activation; callbacks own
+     * navigation and all other behavior.
+     */
+    sidebarActions: ShellSidebarActionsApi;
+    /** Compose another lxapp into a shell slot. */
+    openApp(appId: string, options: ShellOpenAppOptions): Promise<AppSurface>;
+    /** Open a host builtin page such as settings or downloads. */
+    openBuiltin(page: BuiltinShellPage): Promise<BuiltinSurface>;
+    /**
+     * Open a declared surface with shell privileges — the same declaration
+     * `lx.surface.openDeclared` opens, plus the keyed multi-instance form and
+     * placement overrides.
+     */
+    openDeclared(id: string, options?: ShellOpenDeclaredOptions): Promise<DeclaredSurface>;
+    /** Re-place a live declared surface: change its role or its edge. */
+    reconfigure(id: string, patch: ShellSurfacePatch): Promise<void>;
+};
+
+export type ShellOpenAppOptions = {
+    /** `main` occupies the primary content area; `aside` a companion region. */
+    as: 'main' | 'aside';
+    /** Preferred docking side. Only meaningful with `as: 'aside'`. */
+    edge?: SurfaceEdge;
+    /**
+     * Configured page name from the target lxapp's `lxapp.json`. Omit it to
+     * open that app's initial page. Full page routes are not supported.
+     */
+    page?: string;
+    query?: PageQuery;
+    /** Defaults to 'release'. */
+    envVersion?: LxAppEnvVersion;
+    targetVersion?: string;
+    /** Stable identity for `lx.surface.get(key)`. */
+    key?: string;
+};
+
+/**
+ * The declared-surface options only the home lxapp may use.
+ * Creating an extra instance and overriding a placement both mutate
+ * shared shell composition, so they live here and not on
+ * `lx.surface.openDeclared` — which consumes a declaration exactly as
+ * the host authored it, and therefore takes no options at all.
+ */
+export type ShellOpenDeclaredOptions = {
+    /**
+     * Caller-owned identity, for `lx.surface.get(key)` later — the same key
+     * every opener takes. It carries one extra power here: a declaration can
+     * be opened more than once, and the key is which instance you mean, so a
+     * new key creates one. 1 to 128 UTF-8 bytes. Declarations without
+     * instantiable native providers reject it with `capability_missing`.
+     */
+    key?: string;
+    /**
+     * Open with a role other than the declaration's. Must be realizable by the
+     * declared provider; a stable root rejects anything but `main`. Prefer this
+     * over opening and then calling `reconfigure`, which would present the
+     * wrong role first.
+     */
+    as?: 'main' | 'aside' | 'float';
+    /** Preferred docking side when the effective role is `aside`. */
+    edge?: SurfaceEdge;
+};
+
+/**
+ * One app-declared shell sidebar action. It is a stateless command, not a
+ * selectable navigation item: the shell invokes `onActivate` once and
+ * does not infer a target or active state.
+ */
+export type ShellSidebarAction = {
+    /** Stable, non-empty id; unique across both header and footer actions. */
+    id: string;
+    /**
+     * Initial host-owned region. Use `replace` to move an action. The header
+     * takes at most two; everything else belongs in the footer.
+     */
+    placement: ShellSidebarActionPlacement;
+    /**
+     * Local lxapp-accessible icon. Use a bundled relative path such as
+     * `public/settings.svg`, or an `lx://temp`, `lx://usercache`, or
+     * `lx://userdata` path returned by LingXia file APIs. Native absolute paths,
+     * parent traversal, `file:` URLs, and network URLs are rejected; download a
+     * remote icon before registration. For portable rendering, prefer a square,
+     * transparent, monochrome SVG or PNG designed for a 16-point visual.
+     */
+    icon: string;
+    /**
+     * Visible footer title and the tooltip/accessibility text for every
+     * placement. Long footer labels are kept on one line and tail-truncated.
+     */
+    label: string;
+    /** Visible but non-activatable when true. Defaults to false. */
+    disabled?: boolean;
+    /**
+     * Called once for each enabled mouse, keyboard, accessibility, shortcut, or
+     * automation activation. Explicitly open or navigate to the desired content.
+     */
+    onActivate: () => void;
+};
+
+/**
+ * Where the host renders a sidebar action on desktop.
+ * - `header`: icon-only, at most two actions; `label` supplies tooltip
+ * and accessibility text. Hidden in the compact/collapsed shell.
+ * - `footer`: icon and label in the expanded sidebar, icon-only in the
+ * compact rail. The host wraps cells and scrolls after five visible
+ * rows.
+ * Apps cannot configure cell size, row, weight, color, or selected state.
+ * Where an action lives in the sidebar.
+ * `header` is the caption row beside the window controls: at most two
+ * actions, for the ones a person reaches for constantly. Declaring a
+ * third rejects the whole `replace` call rather than hiding one.
+ * `footer` is unbounded and scrolls, and every entry stays visible at
+ * any window size. Anything that must be findable belongs here.
+ */
+export type ShellSidebarActionPlacement = 'header' | 'footer';
+
+/**
+ * Mutable presentation fields for an existing sidebar action. The patch
+ * must contain at least one field. Use `replace` to change `placement` or
+ * `onActivate`.
+ */
+export type ShellSidebarActionUpdate = {
+    /** Replacement local icon, with the same path rules as registration. */
+    icon?: string;
+    /** Replacement non-empty visible/accessibility label. */
+    label?: string;
+    /** Whether the action remains visible but rejects activation. */
+    disabled?: boolean;
+};
+
+/**
+ * Role and edge overrides the home lxapp may apply to a live declared
+ * surface. A stable root rejects non-main roles.
+ */
+export type ShellSurfacePatch = {
+    as?: 'main' | 'aside' | 'float';
+    edge?: SurfaceEdge;
+};
+
+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';
+};
+
+/**
+ * Asynchronous persistent key-value storage backed by the lxapp
+ * database. Use `lx.fs` for path-based data.
+ * `get<T>()` is an unchecked assertion at the call site. Pin every
+ * key's shape once with `lx.getStorage<Schema>()` — that returns a
+ * `TypedStorage<Schema>` instead of this untyped handle.
+ */
+export type Storage = {
+    /**
+     * Reads a stored value. `T` is an unchecked assertion about the stored
+     * shape, exactly like a `JSON.parse` boundary; a missing key resolves
+     * `undefined`, which a stored `null` never does.
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /** Resolves every key, optionally filtered by prefix. */
+    list(prefix?: string): Promise<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>;
+};
+
+/**
+ * Content-keyed surface composition, callable by any lxapp. Privileged
+ * composition lives on `lx.shell`, so the namespace is the privilege.
+ */
+export type SurfaceApi = {
+    /** Open one of this lxapp's own pages as a float or a window. */
+    openPage(page: string, options?: OpenPageOptions): Promise<PageSurface>;
+    /** Open external content in the in-app browser. */
+    openUrl(url: string, options?: OpenUrlOptions): Promise<TabSurface>;
+    /**
+     * Open a surface the host declared in `lingxia.yaml`, with the placement
+     * the declaration chose. Instance keys and placement overrides are shell
+     * composition; they live on `lx.shell.openDeclared`.
+     */
+    openDeclared(id: string): Promise<DeclaredSurface>;
+    /**
+     * The live handle for a surface this lxapp opened **with a `key`**, found
+     * by that key or by its `id`. Removes the need to cache handles in order
+     * to reuse or close them. A surface opened without a `key` is not
+     * addressable — nothing else refers to a runtime-assigned id, so nothing
+     * registers it. A key you chose wins over an id it happens to spell.
+     */
+    get(keyOrId: string): AnySurface | undefined;
+    /**
+     * Observe this presentation's viewport. Invoked immediately with the
+     * current context, then again whenever it changes. Returns an unsubscribe
+     * function.
+     */
+    onContext(handler: (context: SurfaceContext) => void): () => void;
+};
+
+/** What every surface handle carries, whatever opened it. */
+export type SurfaceBase = {
+    readonly kind: SurfaceKind;
+    readonly id: string;
+    /** The caller-supplied identity, when this surface was opened with one. */
+    readonly key?: string;
+    /**
+     * The placement the host produced, which an ordered preference may narrow.
+     * Live rather than a snapshot: `lx.shell.reconfigure` updates it on the
+     * handle you already hold.
+     */
+    readonly realized: SurfacePlacement;
+    /** True until `close()` fires; afterwards the page instance is torn down. */
+    readonly alive: boolean;
+    /**
+     * Last-known visibility, kept in sync with the native side. Safe to bind
+     * into declarative UI; for event-driven updates use `onShow` / `onHide`.
+     */
+    readonly visible: boolean;
+    /**
+     * Destroy the surface. The stable root main cannot be closed. Repeated
+     * calls after a successful close are idempotent.
+     */
+    close(): Promise<void>;
+    onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
+};
+
+/**
+ * Surfaces (docked asides, floats, windows, browser tabs, declared surfaces)
+ * and the desktop tray — the types behind `lx.surface`, `lx.shell`,
+ * 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;
+    reason: SurfaceCloseReason;
+};
+
+/**
+ * The current surface viewport context, delivered to `lx.surface.onContext()`
+ * 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;
+};
+
+/**
+ * Preferred docking side for an aside when the Host has room for a docked
+ * layout. `aside` selects the companion region; `edge` selects a side within
+ * it. Compact Hosts may reproject the same aside as a full-screen overlay.
+ */
+export type SurfaceEdge = 'left' | 'right' | 'top' | 'bottom';
+
+/**
+ * A surface rejection. The runtime carries the surface code on
+ * `data.code` — `code` itself is the transport-level host code, shared
+ * with every other `lx` rejection — so read it with
+ * `surfaceErrorCode(error)` and never parse the message.
+ * ```ts
+ * import { surfaceErrorCode } from 'lingxia-types/error';
+ * catch (error) {
+ * if (surfaceErrorCode(error) === 'unsupported_placement') { … }
+ * }
+ * ```
+ */
+export type SurfaceError = Error & {
+    readonly data?: { readonly code?: SurfaceErrorCode };
+};
+
+/**
+ * Why a surface operation was refused. Carried as `code` on every
+ * `SurfaceError`, so no caller has to match on message text.
+ */
+export type SurfaceErrorCode = /** The placement cannot be realized by this host build. */
+'unsupported_placement'
+/** A privileged operation was called by an lxapp other than the home lxapp. */
+ | 'denied'
+/** No such declared surface, lxapp, or builtin page. */
+ | 'not_declared'
+/** The arguments are malformed or combine options that cannot apply together. */
+ | 'invalid_arg'
+/** The target is already open in a role this call cannot change. */
+ | 'already_open_other_role'
+/** The surface has been closed; the handle is detached. */
+ | 'closed'
+/** The host lacks a capability the request needs, such as an instantiable
+ * native provider for a keyed surface. */
+ | 'capability_missing'
+/** The operation reached the host and failed there. */
+ | 'failed';
+
+/** Where a float popup anchors (default `center`). */
+export type SurfaceFloatPosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
+
+/** 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;
+};
+
+/**
+ * Where the content came from. The discriminant on every surface
+ * handle, so `AnySurface` narrows without a runtime `typeof` check.
+ */
+export type SurfaceKind = 'page' | 'declared' | 'app' | 'tab' | 'builtin';
+
+/** Two-way messaging, available when both sides are lxapp pages. */
+export type SurfaceMessaging = {
+    /**
+     * Send to the other side. For the opener this targets the opened page;
+     * for the opened page it targets the opener.
+     */
+    postMessage(message: unknown): void;
+    onMessage(handler: (message: unknown) => void): () => void;
+};
+
+/**
+ * What the host actually produced. Reported by `realized`, which is
+ * how a caller reads the outcome of an ordered placement preference.
+ */
+export type SurfacePlacement = 'main' | 'aside' | 'float' | 'window' | 'tab';
+
+export type SurfacePresentation = 'main' | 'dock' | 'overlay' | 'popover' | 'sheet' | 'window';
+
+export type SurfaceRole = 'main' | 'aside' | 'float';
+
+/** Surfaces the host can hide and restore without losing page state. */
+export type SurfaceShowable = {
+    /**
+     * Restore a hidden surface. The page instance survived, so scroll
+     * position, form input, and JS state come back with it. Idempotent.
+     */
+    show(): Promise<void>;
+    /**
+     * Hide without destroying. Main surfaces cannot be hidden and reject.
+     * Idempotent.
+     */
+    hide(): Promise<void>;
+    /** Fires on a real transition to visible, whichever side drove it. */
+    onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+    /** Fires on a real transition to hidden, whichever side drove it. */
+    onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+};
+
+/**
+ * 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). `shell` identifies a host-driven main switch.
+ */
+export type SurfaceVisibilityEvent = {
+    id: string;
+    source: 'opener' | 'page' | 'shell';
+};
+
+export type SwitchTabOptions = PageTargetOptions;
+
+/** Native system Downloads path. Do not pass this to `lx.fs`. */
+export type SystemDownloadsPath = string & {
+    readonly [systemDownloadsPathBrand]: 'system-downloads-path';
+};
+
+export type TabBarApi = globalThis.TabBarApi;
+
+export type TabBarItemPatch = {
+    index: number;
+    text?: string | null;
+    iconPath?: string | null;
+    selectedIconPath?: string | null;
+    badge?: string | null;
+    redDot?: boolean;
+};
+
+export type TabBarPatch = {
+    visibility?: TabBarVisibilityPreference;
+    style?: TabBarStylePatch | null;
+    items?: readonly TabBarItemPatch[];
+};
+
+export type TabBarStylePatch = {
+    foregroundColor?: string | null;
+    selectedForegroundColor?: string | null;
+};
+
+export type TabBarVisibilityPreference = 'auto' | 'visible' | 'hidden';
+
+/** External content in the in-app browser. */
+export type TabSurface = SurfaceBase & {
+    readonly kind: 'tab';
+    readonly realized: 'tab' | 'aside';
+    /**
+     * `tab` when this handle owns exactly the tab it opened, and `close()` /
+     * `activate()` act on it. `group` when the browser chrome owns the tab
+     * strip: the content is open, but control belongs to that chrome, so both
+     * methods reject with `unsupported_placement`. Branch on this rather than
+     * on the old platform-dependent `null`.
+     */
+    readonly scope: 'tab' | 'group';
+    /** Bring this tab to the front of its browser. `scope: 'group'` rejects. */
+    activate(): Promise<void>;
+};
+
+export type TerminalApi = {
+    /** Saved terminal settings, revision-checked on write. */
+    readonly settings: TerminalSettingsApi;
+    /** Installed color schemes, plus import and live preview. */
+    readonly colorSchemes: TerminalColorSchemesApi;
+    /** Terminal fonts installed on this machine. */
+    readonly fonts: TerminalFontsApi;
+    /** Windows-only optional inline-image compatibility runtime. */
+    readonly windows?: WindowsTerminalApi;
+};
+
+export type TerminalColorScheme = {
+    name?: string;
+    background: string;
+    foreground: string;
+    cursorColor?: string;
+    selectionBackground?: string;
+    selectionForeground?: string;
+    black: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    purple: string;
+    cyan: string;
+    white: string;
+    brightBlack: string;
+    brightRed: string;
+    brightGreen: string;
+    brightYellow: string;
+    brightBlue: string;
+    brightPurple: string;
+    brightCyan: string;
+    brightWhite: string;
+};
+
+export type TerminalColorSchemeDetails = {
+    name: string;
+    source: 'builtIn' | 'imported';
+    scheme: TerminalColorScheme;
+};
+
+export type TerminalColorSchemesApi = {
+    list(): Promise<TerminalColorSchemeDetails[]>;
+    import(options: {
+        text: string;
+        name?: string;
+        /** Existing names are rejected unless overwrite is explicit. */
+        overwrite?: boolean;
+    }): Promise<TerminalColorSchemeDetails>;
+    createPreview(): TerminalPreviewController;
+};
+
+export type TerminalFontSettings = {
+    /** Ordered candidates; the first installed monospaced family wins. */
+    family: string[];
+    size: number;
+    lineHeight: number;
+    ligatures: boolean;
+};
+
+export type TerminalFontsApi = {
+    list(): Promise<InstalledTerminalFont[]>;
+};
+
+export type TerminalPreviewController = {
+    /** Preview a stored name or an unpersisted scheme. Last request wins. */
+    show(scheme: string | TerminalColorScheme): Promise<void>;
+    /** Restore saved settings only when this controller owns the preview. */
+    clear(): Promise<void>;
+    /** Idempotently clear and retire this controller. */
+    close(): Promise<void>;
+};
+
+export type TerminalSettingsApi = {
+    get(): Promise<TerminalSettingsSnapshot>;
+    update(
+        patch: TerminalSettingsPatch,
+        options: { ifRevision: number },
+    ): Promise<TerminalSettingsSnapshot>;
+    reset(options: {
+        ifRevision: number;
+        scope?: 'font' | 'theme';
+    }): Promise<TerminalSettingsSnapshot>;
+    /** Fires after saved settings, effective appearance, or fonts change. */
+    onChange(listener: (snapshot: TerminalSettingsSnapshot) => void): () => void;
+};
+
+export type TerminalSettingsPatch = {
+    font?: Partial<TerminalFontSettings>;
+    theme?: Partial<TerminalThemeSettings>;
+};
+
+export type TerminalSettingsSnapshot = {
+    /** Monotonic process revision used by update/reset compare-and-swap. */
+    revision: number;
+    /** Framework defaults. */
+    defaults: TerminalSettingsValue;
+    /** User-authored fields only. */
+    overrides: TerminalSettingsPatch;
+    /** Resolved configuration after all valid layers. */
+    value: TerminalSettingsValue;
+    effective: {
+        /** Host appearance before applying terminal.theme.mode. */
+        systemAppearance: 'light' | 'dark';
+        appearance: 'light' | 'dark';
+        colorScheme: string | null;
+        font: {
+            family: string;
+            missing: string[];
+            fellBack: boolean;
+        };
+    };
+    warnings: TerminalSettingsWarning[];
+};
+
+export type TerminalSettingsValue = {
+    font: TerminalFontSettings;
+    theme: TerminalThemeSettings;
+};
+
+export type TerminalSettingsWarning = {
+    code: 'invalidUserFile' | 'missingColorScheme';
+    message: string;
+};
+
+export type TerminalThemeMode = 'system' | 'light' | 'dark';
+
+export type TerminalThemeSettings = {
+    mode: TerminalThemeMode;
+    light: string;
+    dark: string;
+};
+
+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;
+};
+
+/**
+ * Callback-based updates for this lxapp's bundle. Available to every
+ * lxapp. To update the native host app, the home lxapp uses the
+ * task-based `lx.app.checkUpdate()` API instead.
+ */
+export type UpdateManager = {
+    applyUpdate(): void;
+    /** Subscribes to a ready update and returns the unsubscribe fn. */
+    onUpdateReady(callback: (info: UpdateReadyInfo) => void): () => void;
+    /** Subscribes to a failed update and returns the unsubscribe fn. */
+    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 VisibilityPreference = 'auto' | 'hidden';
+
+export type WifiConnectedCallback = (info: WifiConnectedInfo) => void;
+
+export type WifiConnectedInfo = WifiInfo & {
+    connected: boolean;
+    state: string;
+};
+
+/**
+ * Window decoration. `system` is the standard title bar. `full`
+ * extends the page to the window edge while keeping the system
+ * minimize, maximize, resize, and drag affordances — the runtime owns
+ * a native drag strip across the top and publishes its height as
+ * `topInset` on the page-chrome snapshot, so a page that does nothing
+ * to opt in still cannot trap the user.
+ */
+export type WindowChrome = 'system' | 'full';
+
+export type WindowSurfaceSize = {
+    /** Initial window width in logical pixels. */
+    width?: number;
+    /** Initial window height in logical pixels. */
+    height?: number;
+};
+
+export type WindowsTerminalApi = {
+    status(): Promise<WindowsTerminalInlineImageStatus>;
+    /** Verify and install the fixed Microsoft ConPTY package from lxapp temp storage. */
+    install(options: { path: string }): Promise<WindowsTerminalInlineImageStatus>;
+    /** Select the installed runtime for new terminal sessions. */
+    setEnabled(options: { enabled: boolean }): Promise<WindowsTerminalInlineImageStatus>;
+};
+
+export type WindowsTerminalInlineImageStatus = {
+    enabled: boolean;
+    installed: boolean;
+    package: {
+        version: string;
+        url: string;
+        sha256: string;
+        bytes: number;
+    };
+};
+
+/** 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;
+}
+
+export interface AppearanceState {
+  preference: AppearancePreference;
+  resolved: ResolvedAppearance;
+}
+
+/** 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;
+}
+
+export interface ScreenInfo {
+  width: number;
+  height: number;
+  scale: number;
+}
+
+/** 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 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;
+  /** Subscribes to a ready update and returns the unsubscribe fn. */
+  onUpdateReady(cb: (...args: any[]) => any): (...args: any[]) => any;
+  /** Subscribes to a failed update and returns the unsubscribe fn. */
+  onUpdateFailed(cb: (...args: any[]) => any): (...args: any[]) => any;
+}
+
+export declare class JSVideoContext {
+  constructor();
+  play(): void;
+  pause(): void;
+  stop(): void;
+  seek(position: number): void;
+  requestFullScreen(): void;
+  exitFullScreen(): void;
+  setStreamSource(options: StreamSourceOptions): void;
+}
+
+export declare class LxFile {
+  private constructor();
+  /** The path supplied to `lx.fs.file`. */
+  readonly path: string;
+  /** Read the complete file as strict UTF-8 text. */
+  text(): Promise<string>;
+  /**
+   * Read and parse the complete file as JSON. Stays `unknown`: a class
+   * method cannot carry a type parameter through the binding, so unlike
+   * `lx.getStorage().get<T>()` the assertion is spelled `as` at the call
+   * site rather than passed in.
+   */
+  json(): Promise<unknown>;
+  /** Read the complete file as a Base64 string. */
+  base64(): Promise<string>;
+  /** Read the complete file as bytes. */
+  bytes(): Promise<Uint8Array>;
+  /** Read the complete file as an ArrayBuffer. */
+  arrayBuffer(): Promise<ArrayBuffer>;
+  /** Test whether this managed path currently exists. */
+  exists(): Promise<boolean>;
+  /** Read metadata for this managed path. */
+  stat(): Promise<FileStats>;
+}
+
+declare global {
+  interface AppearanceApi {
+    /** Read the appearance preference and the light/dark value it resolves to. */
+    get(): AppearanceState;
+    /** Set the appearance preference to `auto`, `light`, or `dark`. */
+    set(preference: AppearancePreference): Promise<void>;
+  }
+}
+
+declare global {
+  interface FileSystemApi {
+    /**
+     * Create a lazy reference to a LingXia-managed path.
+     * Relative paths resolve under `lx.env.USER_DATA_PATH`. Creating a reference
+     * does not require the path to exist.
+     */
+    file(path: string): LxFile;
+    /** Test whether a managed path currently exists. */
+    exists(path: string): Promise<boolean>;
+    /** Read metadata for a managed path. */
+    stat(path: string): Promise<FileStats>;
+    /** The direct children of a managed directory. */
+    readDir(path: string): Promise<DirEntry[]>;
+    /** Create a managed directory. */
+    mkdir(path: string, options?: FsMkdirOptions): Promise<void>;
+    /** Write UTF-8 text or bytes to a managed file. */
+    write(path: string, data: string, options?: FsWriteOptions): Promise<void>;
+    /** Copy a managed file. */
+    copy(source: string, destination: string, options?: FsCopyOptions): Promise<void>;
+    /** Rename or move a managed file or directory. */
+    rename(source: string, destination: string, options?: FsRenameOptions): Promise<void>;
+    /** Remove a managed file or directory. */
+    remove(path: string, options?: FsRemoveOptions): Promise<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;
+    /**
+     * Read the host app's identity: locale, display language, OS, product name,
+     * product version, and SDK runtime version.
+     */
+    getBaseInfo(): AppBaseInfo;
+    /**
+     * Follow the host's effective display language.
+     * `getBaseInfo().displayLanguage` answers what it is now; this answers when it
+     * changes. Logic needs both because the strings it hands to native chrome —
+     * navigation bar titles, tab bar labels, modal and action-sheet text — are the
+     * app's own, and nothing re-renders them on its behalf.
+     */
+    onDisplayLanguageChange(callback: (language: string) => void): () => void;
+    /**
+     * 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;
+    /**
+     * Whether this host exposes a capability to this Logic context, right now.
+     * Synchronous, because it is meant to be called from render paths. The answer
+     * is live and may be stale by the time you act on it — it is an affordance for
+     * deciding what to render, not a replacement for handling a rejection.
+     * `{ capability: 'surface', value: 'aside' }` in particular changes when a
+     * desktop window crosses the compact breakpoint; pair it with
+     * `lx.surface.onContext` instead of polling. The answer is per runtime context:
+     * a context that does not expose an API reports false for it.
+     */
+    supports(query: LxCapabilityQuery): boolean;
+    /** Vibrate briefly, where the device has a vibrator. */
+    vibrateShort(): boolean;
+    /** Vibrate for a longer pulse, where the device has a vibrator. */
+    vibrateLong(): boolean;
+    /** Hand a number to the system dialer; the user still places the call. */
+    makePhoneCall(options: MakePhoneCallOptions): boolean;
+    /** Read the device and OS facts this host reports. */
+    getDeviceInfo(): DeviceInfo;
+    /** Read the screen geometry and pixel ratio this host reports. */
+    getScreenInfo(): ScreenInfo;
+    /** Read connectivity right now: whether it is connected, its type, and addresses. */
+    getNetworkInfo(): Promise<NetworkInfo>;
+    /** Subscribes to network changes and returns the unsubscribe fn. */
+    onNetworkChange(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>;
+    /** Subscribes to WiFi connection events and returns the unsubscribe fn. */
+    onWifiConnected(callback: WifiConnectedCallback): () => void;
+    /**
+     * Lock this lxapp to `portrait` or `landscape`.
+     * Any other value rejects. Where the host does not report the change back,
+     * the runtime emits the orientation event itself so JS state stays in sync.
+     */
+    setDeviceOrientation(orientation: DeviceOrientation): boolean;
+    /** Subscribes to orientation changes and returns the unsubscribe fn. */
+    onDeviceOrientationChange(callback: (event: DeviceOrientationChangeEvent) => void): () => void;
+    readonly env: LxEnv;
+    downloadFile(options: never): never;
+    /**
+     * Upload a managed file to an ordinary HTTP multipart endpoint.
+     * Returns a task handle synchronously so progress and abort can be wired up
+     * before the transfer starts.
+     */
+    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>;
+    /**
+     * Opens a file picker.
+     * Resolves `{ canceled: true }` only when the user dismisses the picker. A
+     * completed selection resolves `{ canceled: false, paths }` with at least one
+     * path. Rejects when the picker fails or returns an invalid payload.
+     */
+    chooseFile(options?: ChooseFileOptions): Promise<ChooseFileResult>;
+    /**
+     * Opens a directory picker.
+     * Resolves `{ canceled: true }` only when the user dismisses the picker. A
+     * completed selection resolves `{ canceled: false, path }`. Rejects when the
+     * picker fails or returns an invalid payload.
+     */
+    chooseDirectory(options?: ChooseDirectoryOptions): Promise<ChooseDirectoryResult>;
+    readonly fs: FileSystemApi;
+    /** Subscribes to key-down events and returns the unsubscribe fn. */
+    onKeyDown(callback: KeyEventCallback): () => void;
+    /** Subscribes to key-up events and returns the unsubscribe fn. */
+    onKeyUp(callback: KeyEventCallback): () => void;
+    /** Get location function */
+    getLocation(options?: GetLocationOptions): Promise<LocationInfo>;
+    /** Identify the running lxapp: its id, display name, version, and release type. */
+    getLxAppInfo(): LxAppInfo;
+    /** Read an image's dimensions, type, and orientation without decoding it into a view. */
+    getImageInfo(options: GetImageInfoOptions): Promise<ImageInfo>;
+    /** Re-encode an image at a lower quality or size, writing a new managed file. */
+    compressImage(options: CompressImageOptions): Promise<CompressImageResult>;
+    /**
+     * Opens the media picker or camera.
+     * Resolves `{ canceled: true }` only when the user dismisses the picker. A
+     * completed selection resolves `{ canceled: false, entries }` with at least one
+     * entry. Rejects when capture or selection fails, or the host returns an invalid
+     * payload.
+     */
+    chooseMedia(options?: ChooseMediaOptions): Promise<ChooseMediaResult>;
+    /**
+     * 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;
+    /** Save an image into the system photo library. */
+    saveImageToPhotosAlbum(options: SaveMediaOptions): Promise<void>;
+    /** Save a video into the system photo library. */
+    saveVideoToPhotosAlbum(options: SaveMediaOptions): Promise<void>;
+    /**
+     * Opens the scanner.
+     * Resolves `{ canceled: true }` only when the user dismisses the scanner. A
+     * completed scan resolves `{ canceled: false, scanResult, scanType }`. Rejects
+     * when scanning fails or the host returns an invalid payload.
+     */
+    scanCode(options?: ScanCodeOptions): Promise<ScanCodeResult>;
+    /** Take a control handle for the `<lx-video>` component with this id. */
+    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>;
+    /** Write one frame of a video out as an image file. */
+    extractVideoThumbnail(options: ExtractVideoThumbnailOptions): Promise<ExtractVideoThumbnailResult>;
+    /**
+     * Transcode a video to a smaller file.
+     * Returns a task handle synchronously, so progress and cancellation can be
+     * wired up before transcoding starts.
+     */
+    compressVideo(options: CompressVideoOptions): CompressVideoTask;
+    /**
+     * Open another lxapp, optionally at one of its pages.
+     * Navigating to the lxapp already running is a no-op. Rejects with
+     * `E_SURFACE_CONFLICT` when the target is currently docked as an aside —
+     * close that aside before opening it as a main.
+     */
+    navigateToApp(options: NavigateToAppOptions): Promise<void>;
+    /** Leave this lxapp and reveal the one that opened it. */
+    navigateBackApp(): Promise<void>;
+    /**
+     * Hand content to the system share sheet.
+     * Share text, files, or a page link — files cannot be combined with a page
+     * target or with text; share those separately.
+     */
+    share(options: ShareOptions): Promise<ShareResult>;
+    /**
+     * Open this lxapp's asynchronous persistent key-value store. `get` asserts the
+     * value shape at the call site and resolves `undefined` for a missing key. Use
+     * `lx.fs` instead for path-based data.
+     */
+    getStorage(): Storage;
+    /** `lx.openExternal(url)` — hand the url off to the OS default browser. */
+    openExternal(url: string): void;
+    readonly surface: SurfaceApi;
+    /** Read system switches the lxapp may branch on, such as location and WiFi. */
+    getSystemSetting(): SystemSettingInfo;
+    /**
+     * Shows a list of actions.
+     * Resolves `{ canceled: false, index }` when the user selects an item; `index`
+     * points into `options.itemList`. Resolves `{ canceled: true }` only when the
+     * user dismisses the sheet. Rejects when presentation fails or the host returns
+     * an invalid selection.
+     */
+    showActionSheet(options: ShowActionSheetOptions): Promise<ActionSheetResult>;
+    readonly appearance: AppearanceApi;
+    /**
+     * Shows a confirmation modal.
+     * Resolves `{ canceled: false }` when the user confirms and `{ canceled: true }`
+     * only when the user dismisses or cancels the modal. Rejects when presentation
+     * fails or the host returns an invalid payload.
+     */
+    showModal(options: ShowModalOptions): Promise<ModalResult>;
+    /**
+     * Replace the current lxapp's complete app-declared More action list (seven
+     * entries maximum). Pass an empty array to clear it. Native hosts append these
+     * entries after their own lifecycle actions.
+     */
+    setMoreActions(items: MoreAction[]): void;
+    readonly navigationBar: NavigationBarApi;
+    /**
+     * 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;
+    /**
+     * Push a configured page onto the stack.
+     * A route can appear on the stack only once. The promise rejects with
+     * `data.reason === "duplicate_route"` when the target is already present,
+     * or `data.reason === "stack_full"` when the ten-page limit is reached.
+     */
+    navigateTo(options: NavigateToOptions): Promise<PageMessagePort>;
+    /**
+     * Pop one or more pages and reveal the destination page.
+     * `options` and `options.delta` are optional; both default to one page. The
+     * promise resolves once the destination WebView is ready, so callers can
+     * safely continue with work that targets the revealed page.
+     */
+    navigateBack(options?: NavigateBackOptions): Promise<void>;
+    /**
+     * Replace the current stack entry with a configured page.
+     * Redirecting to the current route keeps its page instance and runs `onLoad`
+     * again with the new query. Redirecting to a route lower in the stack rejects
+     * with `data.reason === "duplicate_route"`.
+     */
+    redirectTo(options: RedirectToOptions): Promise<void>;
+    /**
+     * Switch to a configured tab page.
+     * The tab page being left is hidden and retained. Non-tab pages pushed above
+     * a tab leave the stack and receive `onUnload`.
+     */
+    switchTab(options: SwitchTabOptions): Promise<void>;
+    /** Clear the page stack and launch a configured page as the new root. */
+    reLaunch(options: ReLaunchOptions): Promise<void>;
+    readonly shell: ShellApi;
+    readonly tabBar: TabBarApi;
+    /** Show toast function */
+    showToast(options: ShowToastOptions): Promise<void>;
+    /** Hide toast function */
+    hideToast(): Promise<void>;
+    readonly tray: TrayApi;
+    /**
+     * Return the callback-based update manager for this lxapp's bundle. This is
+     * available to every lxapp and is distinct from the home-only
+     * `lx.app.checkUpdate()`, which updates the native host app.
+     */
+    getUpdateManager(): UpdateManager;
+  }
+}
+
+declare global {
+  interface LxEnv {
+    readonly USER_DATA_PATH: 'lx://userdata';
+    readonly USER_CACHE_PATH: 'lx://usercache';
+  }
+}
+
+declare global {
+  interface NavigationBarApi {
+    /** Patch the navigation bar of the active page; unset fields stay as they are. */
+    update(patch: NavigationBarPatch): Promise<void>;
+  }
+}
+
+declare global {
+  interface ShellApi {
+    /**
+     * `lx.shell.openApp(appId, options)` — compose another lxapp into a shell
+     * slot. Home-lxapp only; the namespace is the privilege.
+     */
+    openApp(appId: string, options: ShellOpenAppOptions): Promise<AppSurface>;
+    /** `lx.shell.openBuiltin(page)` — a host builtin page. Home-lxapp only. */
+    openBuiltin(page: BuiltinShellPage): Promise<BuiltinSurface>;
+    /**
+     * `lx.shell.openDeclared(id, options?)` — the declared surface, plus the
+     * keyed multi-instance form and placement overrides. Home-lxapp only.
+     */
+    openDeclared(id: string, options?: ShellOpenDeclaredOptions): Promise<DeclaredSurface>;
+    /** `lx.shell.reconfigure(id, patch)` — re-place a live declared surface. */
+    reconfigure(id: string, patch: ShellSurfacePatch): Promise<void>;
+  }
+}
+
+declare global {
+  interface ShellSidebarActionsApi {
+    /**
+     * Atomically replaces the complete desktop sidebar action declaration. Only the
+     * home lxapp may call this API. Ids must be non-empty and unique across both
+     * placements; header accepts at most two entries. Icons must be bundled relative
+     * paths or runtime-managed `lx://` paths accessible to the home lxapp.
+     * Every entry is bound to its generation-scoped callback. The shell invokes that
+     * callback but never infers navigation or selected state. Validation or host
+     * projection failure leaves the previous generation active. `replace([])` clears
+     * the chrome explicitly. Declarations are process-local, so call `replace` again
+     * on every Logic launch.
+     */
+    replace(items: ShellSidebarAction[]): void;
+    /**
+     * Atomically updates the icon, label, and/or disabled state of one stable id.
+     * Only the home lxapp may call this API. The patch must be non-empty; unknown
+     * fields are rejected. The callback and placement stay unchanged. Throws
+     * `E_NOT_FOUND` when `id` is not in the current declaration.
+     */
+    update(id: string, patch: ShellSidebarActionUpdate): void;
+    /**
+     * Atomically removes one stable id and its generation-scoped callback. Only the
+     * home lxapp may call this API. Throws `E_NOT_FOUND` when `id` is not in the
+     * current declaration.
+     */
+    remove(id: string): void;
+    /**
+     * Atomically clears every runtime sidebar action and callback. Only the home
+     * lxapp may call this API. Equivalent to `replace([])` and safe when already
+     * empty; the home lxapp must still redeclare actions after the next Logic launch.
+     */
+    clear(): void;
+  }
+}
+
+declare global {
+  interface SurfaceApi {
+    /**
+     * `lx.surface.openPage(page, options?)` — one of this lxapp's own pages as a
+     * float or a window. A page can never be an aside: asides carry external
+     * content only, which is why that member does not exist on this signature.
+     */
+    openPage(page: string, options?: OpenPageOptions): Promise<PageSurface>;
+    /**
+     * `lx.surface.openUrl(url, options?)` — external content in the in-app
+     * browser, as a tab or docked as an aside.
+     */
+    openUrl(url: string, options?: OpenUrlOptions): Promise<TabSurface>;
+    /**
+     * `lx.surface.openDeclared(id, options?)` — a surface the host declared in
+     * `lingxia.yaml`, opened with the declaration's own presentation.
+     */
+    openDeclared(id: string): Promise<DeclaredSurface>;
+    /**
+     * `lx.surface.get(keyOrId)` — the live handle for a surface this lxapp opened
+     * **with a `key`**, so no caller has to cache one in order to reuse or close
+     * it. An unkeyed surface is not addressable: nothing registers it, because
+     * holding one for the session costs its closures and its message port and
+     * nobody can look up a uuid they never chose.
+     * A `key` you chose wins over a runtime-assigned `id`, so a key that happens
+     * to spell another surface's id still finds yours.
+     */
+    get(keyOrId: string): AnySurface | undefined;
+    /**
+     * `lx.surface.onContext(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.
+     */
+    onContext(handler: (context: SurfaceContext) => void): () => void;
+  }
+}
+
+declare global {
+  interface TabBarApi {
+    /** Patch this lxapp's tab bar; unset fields stay as they are. */
+    update(patch: TabBarPatch): Promise<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 {};