@lingxia/types 0.17.0 → 0.18.0

package/dist/generated/logic.d.ts

@@ -1,7 +1,18 @@
 declare const appDownloadPathBrand: unique symbol;
 declare const systemDownloadsPathBrand: unique symbol;
-export interface PageConfig<TData extends Record<string, unknown> = Record<string, unknown>> {
-    data?: TData;
+/** Managed paths and relative userdata paths; system Downloads references are excluded. */
+export type ManagedPath = string & {
+    readonly [systemDownloadsPathBrand]?: never;
+};
+/** JSON-shaped state; undefined removes a property in setData. */
+export type PageDataValue<T> = unknown extends T ? T : T extends string | number | boolean | null | undefined ? T : T extends (...args: never[]) => unknown ? never : T extends object ? {
+    [K in keyof T]: PageDataValue<T[K]>;
+} : never;
+export type NoReservedPageMembers<T> = {
+    [K in keyof T]: K extends 'data' ? T[K] : K extends keyof PageInstance | '_setData' | '_cancelPendingSetData' ? never : T[K];
+};
+export interface PageConfig<TData extends object = Record<string, unknown>> {
+    data?: TData & PageDataValue<TData>;
     onLoad?: (options?: PageLoadOptions) => void | Promise<void>;
     onShow?: () => void | Promise<void>;
     onReady?: () => void | Promise<void>;
@@ -31,25 +42,53 @@ export type NoLifecycleTypos<TCustom, TNames extends string> = {
 };
 /**
  * A `setData` key that addresses inside `data` — `'a.b'` or `'rows[0].name'`.
- * Values behind a path stay `unknown`: the runtime resolves the path, so the
- * type cannot.
+ * Kept for documentation; nested writes go through `setPath` (checked) or
+ * `setDataPath` (unchecked). `setData` no longer accepts these keys.
  */
 export type PageDataPath = `${string}.${string}` | `${string}[${number}]${string}`;
 /**
- * A field initialized to `null` or `[]` states nothing about what will fill it
- * later, so it stays open. Annotate it (`null as Profile | null`) to have the
- * fill checked.
+ * @deprecated Page `data` is no longer widened for `null` / `[]` initializers.
+ * Annotate the field (`null as Profile | null`) when a later fill should be
+ * checked.
  */
-export type LazyInitField<T> = [T] extends [null | undefined] ? unknown : [T] extends [never[]] ? unknown[] : T;
+export type LazyInitField<T> = T;
+type PageReadonlyDepth = [never, 0, 1, 2, 3, 4, 5, 6];
+type PagePrimitive = string | number | boolean | bigint | symbol | null | undefined;
 /**
- * Top-level keys are checked against `data`; only path-shaped keys stay open.
- * A misspelled or wrongly typed top-level key is a compile error.
+ * Deep readonly view of page `data`. Static only — the runtime object is not
+ * frozen.
+ */
+export type DeepReadonly<T, D extends number = 6> = [D] extends [never] ? T : T extends PagePrimitive ? T : T extends Function ? T : T extends readonly unknown[] ? {
+    readonly [K in keyof T]: DeepReadonly<T[K], PageReadonlyDepth[D]>;
+} : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K], PageReadonlyDepth[D]>;
+} : T;
+/**
+ * Tuple path into `data`, depth-capped so large page states stay completable.
+ */
+export type DataPath<T, D extends number = 5> = [D] extends [never] ? never : T extends readonly (infer U)[] ? [number] | [number, ...DataPath<U, PageReadonlyDepth[D]>] : T extends object ? {
+    [K in keyof T & (string | number)]: [K] | (DataPath<T[K], PageReadonlyDepth[D]> extends infer Rest ? Rest extends readonly PropertyKey[] ? [K, ...Rest] : never : never);
+}[keyof T & (string | number)] : never;
+export type DataPathValue<T, P extends readonly PropertyKey[]> = T extends null | undefined ? never : T extends unknown ? P extends readonly [
+    infer K,
+    ...infer Rest
+] ? Rest extends readonly PropertyKey[] ? Rest['length'] extends 0 ? K extends keyof T ? T[K] : K extends number ? T extends readonly (infer U)[] ? U : never : never : K extends keyof T ? DataPathValue<T[K], Rest> : K extends number ? T extends readonly (infer U)[] ? DataPathValue<U, Rest> : never : never : never : never : never;
+/**
+ * Top-level keys are checked against `data`. Nested writes use `setPath` or
+ * the unchecked `setDataPath`.
  */
 export type SetDataPatch<TData> = {
-    [K in keyof TData]?: LazyInitField<TData[K]>;
-} & Partial<Record<PageDataPath, unknown>>;
-export interface PageInstance<TData extends Record<string, unknown> = Record<string, unknown>> {
-    data: TData;
+    [K in keyof TData]?: TData[K];
+};
+type SetDataValue<TData, K> = K extends PageDataPath ? {
+    "LingXia type error": "use setPath or setDataPath for nested writes";
+} : K extends keyof TData ? TData[K] | DeepReadonly<TData[K]> : {
+    "LingXia type error": "unknown data key";
+};
+export interface PageInstance<TData extends object = Record<string, unknown>> {
+    readonly data: {
+        readonly [K in keyof TData]: DeepReadonly<TData[K]>;
+    };
     route: string;
     /**
      * Available when this page was opened as a surface via
@@ -60,7 +99,14 @@ export interface PageInstance<TData extends Record<string, unknown> = Record<str
      * Available when this page was opened by `lx.navigateTo(...)`.
      */
     opener?: PageMessagePort;
-    setData(data: SetDataPatch<TData>, callback?: () => void): void;
+    setData<TPatch extends Record<string, unknown>>(data: TPatch & {
+        [K in keyof TPatch]: SetDataValue<TData, K>;
+    }): void;
+    setPath<const P extends DataPath<TData>>(path: P, value: DataPathValue<TData, P>): void;
+    /** Nested write by a runtime-resolved string path. JSON shape is checked; the path/value relationship is not. */
+    setDataPath(path: string, value: JsonValue | undefined): void;
+    /** Drain pending state writes; an attached View acknowledges application, not paint. Rejects on unload. */
+    flush(): Promise<void>;
 }
 /**
  * Injected by the runtime into methods listed in `stream_handlers` page metadata.
@@ -76,6 +122,12 @@ export interface StreamHandle<T = unknown> {
     end(result?: unknown): void;
     /** End the stream with an error. */
     error(code: string, message?: string): void;
+    /**
+     * Called once if View cancels before `end`/`error`. Returns unsubscribe.
+     * The generator form still observes cancel in `finally`; use this for the
+     * callback-based handle.
+     */
+    onCancel(handler: () => void): () => void;
 }
 /**
  * Injected by the runtime as the second parameter when View opens a channel.
@@ -88,12 +140,12 @@ export interface ChannelHandle<TSend = unknown, TReceive = unknown> {
     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;
+    /** Register a listener for incoming events. Returns unsubscribe. */
+    on(event: 'data', handler: (payload: TReceive) => void): () => void;
     on(event: 'close', handler: (info: {
         code: string;
         reason: string;
-    }) => void): void;
+    }) => void): () => void;
 }
 /**
  * Download options.
@@ -107,30 +159,47 @@ export interface ChannelHandle<TSend = unknown, TReceive = unknown> {
  */
 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';
+export type DownloadProgressEvent<TResult extends DownloadResult = DownloadResult> = {
+    kind: 'progress' | 'paused' | 'resumed';
     downloadedBytes?: number;
     totalBytes?: number;
     /** Present only when the total size is known. */
     progress?: number;
-    result?: TResult;
+} | {
+    kind: 'canceled';
+    downloadedBytes?: number;
+    totalBytes?: number;
+    progress?: number;
+} | {
+    kind: 'completed';
+    downloadedBytes?: number;
+    totalBytes?: number;
+    progress?: number;
+    result: TResult;
+};
+export type DownloadIteratorResult<TResult extends DownloadResult = DownloadResult> = IteratorResult<DownloadProgressEvent<TResult>, void>;
+export type AppTempDownloadResult = Extract<AppDownloadResult, {
+    storage: 'temp';
+}>;
+export type AppPersistedDownloadResult = Extract<AppDownloadResult, {
+    storage: 'userdata';
+}>;
+export type ChooseFileSingleResult = {
+    status: 'ok';
+    paths: [string];
+} | CanceledResult;
+/** A running operation. Progress has one consumer; stopping observation does not cancel it. */
+export interface Task<TResult, TProgress> {
+    readonly result: Promise<TResult>;
+    readonly progress: AsyncIterable<TProgress>;
 }
-export interface DownloadIteratorResult<TResult extends DownloadResult = DownloadResult> {
-    done: boolean;
-    value?: DownloadProgressEvent<TResult>;
+export interface CancelableTask<TResult, TProgress> extends Task<TResult, TProgress> {
+    /** Requests cancellation. Await result to observe the terminal outcome. */
+    cancel(): Promise<void>;
 }
-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>;
+export interface DownloadTask<TResult extends DownloadResult = DownloadResult> extends CancelableTask<TResult, DownloadProgressEvent<TResult>> {
     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 {
     /**
@@ -151,28 +220,44 @@ declare global {
         readonly env: HostAppEnv;
         /**
          * 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.
+         * startup item; its presence and `lx.supports('app.autostart')` always
+         * agree, so `lx.host.autostart?.…` and the query are interchangeable.
          */
         autostart?: AutostartApi;
+        /**
+         * Local notifications. Absent where the host cannot post them; its presence
+         * and `lx.supports('app.notification')` always agree.
+         */
+        notification?: NotificationApi;
+        /**
+         * Product-drawn desktop banner (top-right). Absent off desktop and in
+         * guest lxapps; its presence and `lx.supports('app.banner')`
+         * always agree.
+         */
+        banner?: BannerApi;
         /** The language this lxapp renders in. Every lxapp follows it. */
         readonly displayLanguage: DisplayLanguageApi;
         /** The light/dark scheme this lxapp renders in. */
         readonly appearance: AppearanceApi;
         /**
          * Product-wide settings, and their single writer. Present only in the
-         * Control app the host sealed at build time; its presence and
-         * `lx.supports({ capability: 'control' })` always agree, so
-         * `lx.app.control?.…` and the query are interchangeable.
+         * Control app the host sealed at build time. Use
+         * `lx.host.control !== undefined` to inspect that identity.
          */
         readonly control?: ControlApi;
         /**
          * Product-wide cache reporting and clearing for a settings screen.
-         * Present only in the Control app; its presence and
-         * `lx.supports({ capability: 'control' })` always agree, so
-         * `lx.app.cache?.…` and the query are interchangeable.
+         * Present only in the Control app; presence agrees with
+         * `lx.host.control !== undefined`.
          */
         cache?: AppCacheApi;
+        /**
+         * Take over host updates for the rest of this process. Irreversible: the
+         * built-in auto-flow will not prompt or download again, including after
+         * the calling page unloads. Does not cancel an already-started update task.
+         * `update.apply()` claims as well. `checkUpdate()` does not.
+         */
+        claimCustomUpdate(): void;
     }
     /** Runtime environment constants backed by abstract `lx://` paths. */
     interface LxEnv {
@@ -181,15 +266,37 @@ declare global {
         /**
          * 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.
+         * presence and `lx.supports('terminal')` always agree.
          */
         readonly terminal?: TerminalApi;
         /** Download to the downloads directory. */
         downloadFile(options: DownloadsDownloadOptions): DownloadTask<DownloadsDownloadResult>;
+        /** Download to a durable app-owned path. */
+        downloadFile(options: AppDownloadOptions & {
+            filePath: string;
+        }): DownloadTask<AppPersistedDownloadResult>;
+        /** Download to a temporary app-owned path. */
+        downloadFile(options: AppDownloadOptions & {
+            filePath?: undefined;
+        }): DownloadTask<AppTempDownloadResult>;
         /** 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>>;
+        /** Single-file picker: a completed selection is exactly one path. */
+        chooseFile(options: ChooseFileOptions & {
+            multiple: false;
+        }): Promise<ChooseFileSingleResult>;
+        chooseFile(options: ChooseFileOptions & {
+            multiple: true;
+        }): Promise<ChooseFileResult>;
+        /**
+         * Opens a file picker.
+         * Resolves `{ status: 'canceled' }` only when the user dismisses the picker. A
+         * completed selection resolves `{ status: 'ok', paths }` with at least one
+         * path. Rejects when the picker fails or returns an invalid payload.
+         */
+        chooseFile(options?: ChooseFileOptions): Promise<ChooseFileResult>;
         /**
          * Open this lxapp's store with every key's shape pinned on the handle.
          * `get` / `set` / `delete` then share that schema instead of
@@ -207,7 +314,7 @@ declare global {
 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]];
+    [K in StorageKey<S>]: [key: K, value: S[K] | DeepReadonly<S[K]>];
 }[StorageKey<S>];
 /**
  * Schema-typed view of the same store `lx.getStorage()` returns.
@@ -220,7 +327,7 @@ type StorageEntry<S extends object> = {
  * 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>;
+    get<K extends StorageKey<S>>(key: K, decode?: (value: unknown) => S[K]): Promise<S[K] | undefined>;
     set(...entry: StorageEntry<S>): Promise<void>;
     has(key: StorageKey<S>): Promise<boolean>;
     delete(key: StorageKey<S>): Promise<void>;
@@ -229,21 +336,23 @@ export type TypedStorage<S extends object> = {
     info(): Promise<StorageInfo>;
 };
 /**
- * Result of `lx.showActionSheet`. Branch on `canceled` before reading
- * the selected item index.
+ * Result of `lx.showActionSheet`. Branch on `status` before reading
+ * the selected item id.
  */
 export type ActionSheetResult = {
-    canceled: false;
-    /** Index of the tapped item in `itemList`. */
-    index: number;
+    status: 'ok';
+    /** Stable id of the selected action. */
+    id: string;
 } | CanceledResult;
+/** An acknowledgement dialog has no cancel button. */
+export type AlertOptions = Omit<ShowModalOptions, 'showCancel' | 'cancelText' | 'cancelColor'>;
 /** Every surface handle, narrowable by `kind`. */
 export type AnySurface = PageSurface | DeclaredSurface | AppSurface | TabSurface | BuiltinSurface;
 /**
  * The product-wide cache a settings screen reports and clears.
  * App-scoped, not lxapp-scoped: the figure covers every lxapp the host
  * has run. Injected only into the Control app, same gate as
- * `lx.app.control` — guests do not have the member.
+ * `lx.host.control` — guests do not have the member.
  */
 export type AppCacheApi = {
     /** Estimated reclaimable managed bytes; excludes live session storage and WebView cache. */
@@ -278,7 +387,7 @@ export type AppDownloadOptions = DownloadOptionsBase & {
     /**
      * Optional app-owned durable output path.
      *
-     * Omit `filePath` to receive a temporary result in `tempFilePath`. Relative
+     * Omit `filePath` to receive a temporary result in `uri`. Relative
      * paths resolve under user data. `lx://` paths must target `lx://userdata`;
      * `lx://usercache` is not accepted here.
      */
@@ -289,24 +398,15 @@ export type AppDownloadOptions = DownloadOptionsBase & {
     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;
+    uri: AppDownloadFilePath;
+    storage: 'temp';
     mimeType?: string;
-    size: number;
+    sizeBytes: number;
 } | {
-    /** Durable destination under `lx://userdata`. */
-    filePath: AppDownloadFilePath;
-    tempFilePath?: never;
+    uri: AppDownloadFilePath;
+    storage: 'userdata';
     mimeType?: string;
-    size: number;
+    sizeBytes: number;
 };
 export type AppInstance = AppConfig & {
     globalData: Record<string, unknown>;
@@ -350,7 +450,7 @@ export type AppScreenshotOptions = {
 };
 export type AppScreenshotResult = {
     /** `lx://` URI of the captured PNG in the lxapp temp directory. */
-    tempFilePath: string;
+    uri: 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. */
@@ -361,7 +461,7 @@ export type AppSurface = SurfaceBase & SurfaceShowable & {
     readonly kind: 'app';
     readonly realized: 'main' | 'aside';
 };
-/** `lx.app.appearance` — the scheme this lxapp renders in. */
+/** `lx.host.appearance` — the scheme this lxapp renders in. */
 export type AppearanceApi = {
     /**
      * The scheme this lxapp is rendering in. An lxapp that pinned one in its
@@ -381,25 +481,6 @@ export type AppearanceApi = {
  * the system.
  */
 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 native-assigned Control app; other lxapps receive
- * a permission error.
- */
 export type AutostartApi = {
     /**
      * Whether the app is currently registered to launch at startup, read from
@@ -416,6 +497,40 @@ export type AutostartApi = {
      */
     setEnabled(on: boolean): Promise<void>;
 };
+/**
+ * Product-drawn desktop banner, top-right. Not an OS notification and
+ * not bound to App Link. Present only in the desktop Control app;
+ * presence and `lx.supports('app.banner')` always agree.
+ * No buttons: an informational card that auto-dismisses (5s unless
+ * `timeoutMs` is set). With buttons: a gate that waits for a choice,
+ * dismiss, timeout, or replace. User outcomes resolve; presentation
+ * failures reject.
+ */
+export type BannerApi = {
+    show(options: {
+        id?: string;
+        title: string;
+        body?: string;
+        actions?: Array<{
+            id: string;
+            label: string;
+            style?: 'default' | 'primary' | 'destructive';
+        }>;
+        timeoutMs?: number;
+        /** Omit/`system` follows the OS. `light`/`dark` force chrome. `#RGB`/`#RRGGBB`/`#RRGGBBAA` is a solid fill. */
+        background?: 'system' | 'light' | 'dark' | string;
+    }): Promise<{
+        status: 'ok';
+        id: string;
+        action: string;
+    } | {
+        status: 'canceled';
+        id: string;
+        reason: 'dismissed' | 'timeout' | 'replaced';
+    }>;
+    /** Unknown ids are fine. */
+    dismiss(id: string): Promise<void>;
+};
 export type BinaryFileData = ArrayBuffer | ArrayBufferView;
 /**
  * Built-in browser product page. Opening one requires
@@ -425,26 +540,25 @@ export type BuiltinShellPage = 'downloads';
 /**
  * A host builtin page such as 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`.
+ * there is no `show`, `hide`, `close`, or `onClose`.
  */
-export type BuiltinSurface = SurfaceBase & {
+export type BuiltinSurface = Omit<SurfaceBase, 'close' | 'onClose'> & {
     readonly kind: 'builtin';
 };
 /** The user dismissed the operation. Never an error. */
 export type CanceledResult = {
-    canceled: true;
+    status: 'canceled';
 };
 export type ChooseDirectoryOptions = {
     /** Initial directory the dialog opens in. Platform default if omitted. */
     defaultPath?: string;
 };
 /**
- * Result of `lx.chooseDirectory`. Branch on `canceled` before reading
+ * Result of `lx.chooseDirectory`. Branch on `status` before reading
  * the selected directory.
  */
 export type ChooseDirectoryResult = {
-    canceled: false;
+    status: 'ok';
     /** Native-consumable directory reference (path or URI). */
     path: string;
 } | CanceledResult;
@@ -462,11 +576,11 @@ export type ChooseFileOptions = {
     defaultPath?: string;
 };
 /**
- * Result of `lx.chooseFile`. Branch on `canceled` before reading the
+ * Result of `lx.chooseFile`. Branch on `status` before reading the
  * selected paths.
  */
 export type ChooseFileResult = {
-    canceled: false;
+    status: 'ok';
     /**
      * File paths returned by LingXia; always at least one. Values may be
      * app-local paths, `lx://...` paths, or platform system-picker references.
@@ -480,22 +594,79 @@ export type ChooseMediaOptions = {
     mediaType?: ('image' | 'video')[];
     sourceType?: ('album' | 'camera')[];
     camera?: 'back' | 'front';
-    maxDuration?: number;
+    maxDurationSeconds?: number;
 };
 /**
- * Result of `lx.chooseMedia`. Branch on `canceled` before reading the
+ * Result of `lx.chooseMedia`. Branch on `status` before reading the
  * selected entries.
  */
 export type ChooseMediaResult = {
-    canceled: false;
+    status: 'ok';
     /** Picked media; always at least one entry. */
     entries: [ChosenMediaEntry, ...ChosenMediaEntry[]];
 } | CanceledResult;
 export type ChosenMediaEntry = {
-    tempFilePath: string;
+    uri: string;
     fileType: 'image' | 'video';
     isOriginal: boolean;
 };
+export type ClipboardApi = globalThis.ClipboardApi;
+export type ClipboardItem = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    /**
+     * Temporary `lx://temp` PNG, session-scoped and auto-cleaned. Move or
+     * copy it with `lx.fs` if you need to keep it.
+     */
+    filePath: string;
+};
+export type ClipboardReadOptions = {
+    /** Omit to receive every representation the host can surface. */
+    type?: ClipboardType;
+};
+/**
+ * Result of `lx.clipboard.read`. Omit `type` to receive every
+ * representation this host can surface. A requested type that is
+ * absent is `{ status: 'empty' }`, not an error.
+ */
+export type ClipboardReadResult = {
+    status: 'empty';
+} | {
+    status: 'ok';
+    items: ClipboardItem[];
+} | CanceledResult;
+/**
+ * Result of `lx.clipboard.readText`. Branch on `status`.
+ * A copied empty string is `{ status: 'ok', text: '' }`;
+ * an image-only clipboard is `{ status: 'empty' }`.
+ */
+export type ClipboardTextResult = {
+    status: 'empty';
+} | {
+    status: 'ok';
+    text: string;
+} | CanceledResult;
+/** Representations the runtime can round-trip. Closed union. */
+export type ClipboardType = 'text' | 'image';
+/**
+ * One clipboard write. Every host accepts both: `image` takes a PNG or
+ * JPEG file and re-encodes it as the platform's native image format.
+ */
+export type ClipboardWriteItem = {
+    type: 'text';
+    /** Unicode text. Rejects `E_INVALID_ARG` when larger than 1 MiB. */
+    text: string;
+} | {
+    type: 'image';
+    /**
+     * Managed `lx://` path, or a picker result from `lx.chooseFile` /
+     * `lx.chooseMedia` — the same file rules as `lx.share`. Rejects
+     * `E_INVALID_ARG` when the file is not a decodable image.
+     */
+    filePath: string;
+};
 export type CompressImageOptions = {
     path: string;
     quality?: number;
@@ -503,25 +674,30 @@ export type CompressImageOptions = {
     compressedHeight?: number;
 };
 export type CompressImageResult = {
-    tempFilePath: string;
-};
-export type CompressVideoIteratorResult = {
-    done: boolean;
-    value?: CompressVideoProgressEvent;
+    uri: string;
 };
+export type CompressVideoIteratorResult = IteratorResult<CompressVideoProgressEvent, void>;
 export type CompressVideoOptions = {
+    signal?: AbortSignal;
     /**
      * 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.
-     *
+     * Optional output path for compressed file.
+     */
+    outputPath?: string;
+} & ({
+    /**
      * Compression quality preset.
-     * When provided, `bitrate`, `fps`, and `resolution` are ignored.
+     * Mutually exclusive with `bitrate`, `fps`, and `resolution`.
      */
-    quality?: VideoCompressQuality;
+    quality: VideoCompressQuality;
+    bitrate?: never;
+    fps?: never;
+    resolution?: never;
+} | {
+    quality?: never;
     /**
      * Preferred target video bitrate in kbps.
      * May be adjusted or ignored by platform codec/runtime limitations.
@@ -537,17 +713,13 @@ export type CompressVideoOptions = {
      * 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;
+    uri: string;
     width: number;
     height: number;
     durationMs: number;
@@ -560,23 +732,11 @@ export type CompressVideoResult = {
 };
 /**
  * Handle returned by `lx.compressVideo`.
- * Awaiting the task resolves with the final {@link CompressVideoResult}.
- * Iterating it with `for await` yields {@link CompressVideoProgressEvent}s
+ * Awaiting `task.result` resolves with the final {@link CompressVideoResult}.
+ * Iterating `task.progress` 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 CompressVideoTask = CancelableTask<CompressVideoResult, CompressVideoProgressEvent>;
 /**
  * Configured page name from `lxapp.json` / `lingxia.yaml`. JavaScript
  * navigation accepts only this name; full routes such as
@@ -587,16 +747,18 @@ export type CompressVideoTask = PromiseLike<CompressVideoResult> & AsyncIterable
  * a project that never ran a build still compiles.
  */
 export type ConfiguredPageName = keyof LxAppPages extends never ? string : keyof LxAppPages;
+/** A confirmation dialog always permits declining. */
+export type ConfirmOptions = Omit<ShowModalOptions, 'showCancel'>;
 export type ConnectWifiOptions = {
-    SSID: string;
+    ssid: string;
     password?: string;
 };
 /**
- * `lx.app.control` — product-wide settings, and their single writer.
+ * `lx.host.control` — product-wide settings, and their single writer.
  * Present only in the Control app. Bind it once rather than repeating
- * `lx.app.control!`:
+ * `lx.host.control!`:
  * ```js
- * const control = lx.app.control;
+ * const control = lx.host.control;
  * if (!control) return; // not the Control app
  * await control.appearance.setPreference('dark');
  * ```
@@ -605,7 +767,7 @@ export type ControlApi = {
     readonly displayLanguage: ControlDisplayLanguageApi;
     readonly appearance: ControlAppearanceApi;
 };
-/** `lx.app.control.appearance` — the product's own light/dark setting. */
+/** `lx.host.control.appearance` — the product's own light/dark setting. */
 export type ControlAppearanceApi = {
     /** What the user chose for the whole product. */
     getPreference(): AppearancePreference;
@@ -616,14 +778,14 @@ export type ControlAppearanceApi = {
     setPreference(preference: AppearancePreference): Promise<void>;
     /**
      * Follow the choice, not what it resolves to: a system flip under `'auto'`
-     * moves `lx.app.appearance.watch` and leaves this quiet. Starts with the
+     * moves `lx.host.appearance.watch` and leaves this quiet. Starts with the
      * current value; that first callback runs synchronously, before
      * `watchPreference` returns.
      */
     watchPreference(callback: (preference: AppearancePreference) => void): () => void;
 };
 /**
- * `lx.app.control.displayLanguage` — the preference behind that
+ * `lx.host.control.displayLanguage` — the preference behind that
  * language, for the one surface that edits it.
  */
 export type ControlDisplayLanguageApi = {
@@ -648,7 +810,7 @@ export type DeviceOrientation = "portrait" | "landscape";
 export type DeviceOrientationChangeEvent = {
     value: DeviceOrientation;
 };
-/** `lx.app.displayLanguage` — the language this lxapp renders in. */
+/** `lx.host.displayLanguage` — the language this lxapp renders in. */
 export type DisplayLanguageApi = {
     /**
      * The language in effect right now, as a canonical BCP-47 tag. Map it to
@@ -685,7 +847,7 @@ export type DownloadOptionsBase = {
      */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds. */
-    timeout?: number;
+    timeoutMs?: number;
     /** Optional abort signal. */
     signal?: AbortSignal;
 };
@@ -695,16 +857,16 @@ export type DownloadsDownloadOptions = DownloadOptionsBase & {
      * Optional filename hint for the system Downloads destination.
      * This is not an app-owned `lx.fs` path.
      */
-    filePath?: string;
+    suggestedName?: string;
+    filePath?: never;
     /** 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;
+    uri: SystemDownloadsPath;
+    storage: 'downloads';
     mimeType?: string;
-    size: number;
+    sizeBytes: number;
 };
 /**
  * Configured page name belonging to *another* lxapp. This app's own
@@ -745,7 +907,7 @@ export type ExtractVideoThumbnailResult = {
     /**
      * Generated thumbnail file path.
      */
-    tempFilePath: string;
+    uri: string;
     /**
      * Output image width in pixels.
      */
@@ -795,10 +957,10 @@ export type GetImageInfoOptions = {
 };
 /** Location APIs. */
 export type GetLocationOptions = {
-    type?: 'wgs84' | 'gcj02';
+    coordinateSystem?: 'wgs84' | 'gcj02';
     altitude?: boolean;
     isHighAccuracy?: boolean;
-    highAccuracyExpireTime?: number;
+    timeoutMs?: number;
 };
 export type GetVideoInfoOptions = {
     /**
@@ -832,7 +994,7 @@ export type HostAppUpdateEvent = {
     downloadedBytes?: number;
     progress?: number;
 } | {
-    state: 'downloaded' | 'installRequested';
+    state: 'downloaded' | 'installRequested' | 'storeOpened';
 } | {
     state: 'failed';
     stage: HostAppUpdateApplyStage;
@@ -842,38 +1004,36 @@ export type HostAppUpdateInfo = {
     version: string;
     size?: number;
     releaseNotes?: string[];
-    isForceUpdate: boolean;
     /**
-     * Download and apply this checked update.
+     * How this update is applied. `store` opens the platform marketplace;
+     * `direct` downloads and self-installs. `lx.supports('app.selfUpdate')`
+     * is true only for `direct`.
+     */
+    channel: 'direct' | 'store';
+    /**
+     * Apply this checked update.
      *
-     * `apply()` is single-use for this update object.
+     * `apply()` is single-use for this update object. It also claims custom
+     * host updates for the rest of this process, same as
+     * {@link HostAppApi.claimCustomUpdate}.
      *
-     * The returned task can be awaited directly when progress is not needed, or
-     * consumed with `for await...of` to render progress.
+     * Await `task.result` when progress is not needed, or iterate
+     * `task.progress` to render it.
      *
-     * 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.
+     * On `direct`, downloads and hands off install. On `store`, opens the
+     * platform store listing (no package is downloaded) and resolves
+     * `storeOpened`; whether the user then updates is not reported.
      */
     apply(): HostAppUpdateTask;
 };
-export type HostAppUpdateIteratorResult = {
-    done: boolean;
-    value?: HostAppUpdateEvent;
-};
+export type HostAppUpdateIteratorResult = IteratorResult<HostAppUpdateEvent, void>;
 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>;
+    /** `storeOpened` on a `store` channel: the listing opened, nothing was installed. */
+    state: 'installRequested' | 'storeOpened';
 };
+export type HostAppUpdateTask = Task<HostAppUpdateResult, HostAppUpdateEvent>;
 /**
- * Canonical platform-family label shared by `lx.app.getBaseInfo().os`
+ * Canonical platform-family label shared by `lx.host.getBaseInfo().os`
  * and `lx.getDeviceInfo().osName`. `"unknown"` is a non-product build.
  */
 export type HostOs = 'iOS' | 'macOS' | 'Android' | 'Windows' | 'Harmony' | 'unknown';
@@ -883,6 +1043,38 @@ export type InstalledTerminalFont = {
     ligatures: boolean;
     nerdIcons: boolean;
 };
+/**
+ * Launch-at-startup control for the host app.
+ * Absent (`undefined`) wherever the host cannot register a startup item.
+ * `lx.supports('app.autostart')` and the member's presence always
+ * agree, so either gate works:
+ * ```ts
+ * if (lx.supports('app.autostart')) {
+ * // render the "Launch at startup" toggle
+ * }
+ * ```
+ * Requires `capabilities.autostart: true` in `lingxia.yaml`; without it the
+ * member is absent on all platforms. Declaring the capability never enables
+ * autostart by itself — the SDK registers the app only when `setEnabled(true)`
+ * is called, so the decision stays with the user (typically a settings-page
+ * toggle, default off).
+ * Host-app-level capability: like `checkUpdate` and `screenshot`, the methods
+ * are available only to the native-assigned Control app; other lxapps receive
+ * a permission error.
+ * Local notifications as a Control-app resume affordance.
+ * Absent unless the host declared `capabilities.notifications` and the
+ * platform implements the local API. Presence and
+ * `lx.supports('app.notification')` always agree.
+ * Declaring the capability never prompts; permission runs on
+ * `requestPermission()` or the first `show()` that reaches the OS.
+ * Control app only. Guest lxapps receive a permission error.
+ * A JSON value: what a navigation route parameter may hold. Not a way
+ * to smuggle a payload — every route declares its own parameter
+ * schema, and the framework caps size, count, and nesting.
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 /**
  * Input event APIs.
  * Platform support: Android only
@@ -902,34 +1094,7 @@ export type KeyEventCallback = (event: KeyEvent) => void;
 export type LxAppEnvVersion = 'release' | 'draft';
 /** LxApp metadata APIs. */
 export type LxAppReleaseType = 'release' | 'draft';
-/** Boolean capability names accepted by `lx.supports`. */
-export type LxCapabilityFlag = 'control' | '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;
@@ -937,11 +1102,11 @@ export type MakePhoneCallOptions = {
 export type MediaObjectFit = 'cover' | 'contain' | 'fill' | 'fit';
 export type MediaRotation = 0 | 90 | 180 | 270;
 /**
- * Result of `lx.showModal`. `canceled: false` means the user confirmed;
+ * Result of `lx.showModal`. `status: 'ok'` means the user confirmed;
  * there is no third resolved outcome. Presentation failures reject.
  */
 export type ModalResult = {
-    canceled: false;
+    status: 'ok';
 } | CanceledResult;
 /**
  * One app-declared action shown in the host-provided More affordance.
@@ -997,6 +1162,36 @@ export type NavigationBarStylePatch = {
     foregroundColor?: string | null;
     dividerColor?: string | null;
 };
+/**
+ * Where a notification tap, a menu item, or the tray goes.
+ * `page` and `app` are the same contract as `lx.navigateTo` /
+ * `lx.navigateToApp`: a configured page name and a query, ordinary
+ * scene. `route` is a host-registered location that is not a page.
+ * `appLink` is an `https://` product URL that is also a real inbound
+ * App Link (`scene === 8003`). `activate` just brings the product
+ * forward.
+ * A branch carries its own fields and no others: a mixed target is a
+ * parameter error, not a best guess.
+ */
+export type NavigationTarget = {
+    kind: 'activate';
+} | {
+    kind: 'page';
+    page: ConfiguredPageName;
+    query?: PageQuery;
+} | {
+    kind: 'app';
+    appId: string;
+    page?: ExternalPageName;
+    query?: PageQuery;
+} | {
+    kind: 'route';
+    name: string;
+    params?: Record<string, JsonValue>;
+} | {
+    kind: 'appLink';
+    url: string;
+};
 export type NetworkChangeCallback = (info: NetworkInfo) => void;
 export type NetworkInfo = {
     isConnected: boolean;
@@ -1006,6 +1201,72 @@ export type NetworkInfo = {
 };
 /** Network status APIs. */
 export type NetworkType = 'none' | 'unknown' | 'wifi' | '2g' | '3g' | '4g' | '5g' | 'ethernet';
+export type NotificationApi = {
+    /**
+     * Read the current permission without prompting. `'default'` means the
+     * user has not been asked yet.
+     */
+    getPermission(): Promise<'granted' | 'denied' | 'default'>;
+    /**
+     * Ask for notification permission. Prompts where the OS has a prompt and
+     * the user has not answered; otherwise reports the current setting.
+     * Rejects when the prompt is left unanswered.
+     */
+    requestPermission(): Promise<'granted' | 'denied'>;
+    /**
+     * Post or replace a local notification. `id` is the replace key: anything
+     * pending or delivered under it is replaced, whatever `status` comes back,
+     * and its old tap target stops resolving. Omit `id` to get a generated
+     * one. Omit `schedule`, or pass a time that is not in the future, to post
+     * now.
+     *
+     * `target` is where the tap goes, and an omitted one means
+     * `{ kind: 'activate' }` — bring the product forward, nothing else.
+     * `{ kind: 'page' }` opens a page of this Control app the way
+     * `lx.navigateTo` does. `{ kind: 'app' }` opens another lxapp the way
+     * `lx.navigateToApp` does. `{ kind: 'route' }` names a location the host
+     * registered at startup that is not a page. `{ kind: 'appLink' }` takes
+     * an `https://` URL that is also a real inbound App Link
+     * (`scene === 8003`). An unknown page or route, a parameter the route
+     * did not declare, or a host that is not configured rejects here, before
+     * anything is posted.
+     *
+     * `status` says what happened: `'posted'` — the OS accepted it for
+     * display now, which is not a receipt that anyone saw or read it;
+     * `'scheduled'` — queued with the OS for `schedule`; `'suppressed'` — an
+     * immediate post while the product is already frontmost, where nothing is
+     * posted and no permission is needed. A scheduled notification is
+     * presented even if the product is frontmost when it fires.
+     *
+     * A tap resolves through the host, so a target that is gone by then — a
+     * route the build no longer registers, a cancelled or replaced
+     * notification, cleared app data — brings the product forward and says it
+     * is unavailable rather than opening something else.
+     */
+    show(options: {
+        id?: string;
+        title: string;
+        body?: string;
+        target?: NavigationTarget;
+        schedule?: {
+            at: number;
+        } | {
+            delayMs: number;
+        };
+        /** No sound. The banner still appears. */
+        silent?: boolean;
+    }): Promise<{
+        id: string;
+        status: 'posted' | 'scheduled' | 'suppressed';
+    }>;
+    /**
+     * Remove what is pending or delivered under `id`, and retire its tap
+     * target. Unknown ids are fine.
+     */
+    cancel(id: string): Promise<void>;
+    /** Remove every local notification this API posted or scheduled. */
+    cancelAll(): Promise<void>;
+};
 /** File system APIs. */
 export type OpenFileOptions = {
     /** Local file path or runtime-managed temp path. */
@@ -1058,7 +1319,7 @@ export type OpenPageShared = {
     size?: OverlaySurfaceSize;
     interaction?: SurfaceInteraction;
     query?: PageQuery;
-    /** Caller-owned identity, for `lx.surface.get(key)` later. */
+    /** Caller-owned identity, for `lx.surface.getByKey(key)` later. */
     key?: string;
 };
 export type OpenUrlOptions = {
@@ -1070,7 +1331,7 @@ export type OpenUrlOptions = {
     /** Preferred docking side when the realized placement is an aside. */
     edge?: SurfaceEdge;
     size?: OverlaySurfaceSize;
-    /** Stable identity for `lx.surface.get(key)`. */
+    /** Stable identity for `lx.surface.getByKey(key)`. */
     key?: string;
 };
 export type OverlaySurfaceSize = {
@@ -1109,6 +1370,11 @@ export type PageTargetOptions = {
     page: ConfiguredPageName;
     query?: PageQuery;
 };
+export type PickFileOptions = Omit<ChooseFileOptions, 'multiple'>;
+export type PickFileResult = {
+    status: 'ok';
+    uri: string;
+} | CanceledResult;
 export type PreviewMediaAdvance = 'manual' | 'next' | 'loop';
 /** One change-stream event / the `current` snapshot. */
 export type PreviewMediaChange = {
@@ -1117,28 +1383,17 @@ export type PreviewMediaChange = {
 };
 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;
+ * A media session. `presented` distinguishes a rendered first frame from
+ * an early close, cancellation, or failure. `completed` reports closure;
+ * native playback errors may report reason `error`, while request failures reject.
  */
 export type PreviewMediaHandle = {
-    readonly presented: Promise<void>;
+    readonly presented: Promise<{
+        status: 'presented';
+    } | {
+        status: 'notPresented';
+        reason: 'canceled' | 'failed' | 'closed';
+    }>;
     readonly current: PreviewMediaChange;
     onChange(listener: (change: PreviewMediaChange) => void): () => void;
     readonly completed: Promise<PreviewMediaResult>;
@@ -1270,14 +1525,40 @@ export type ScanCodeOptions = {
     scanType?: ('barCode' | 'qrCode' | 'datamatrix' | 'pdf417')[];
 };
 /**
- * Result of `lx.scanCode`. Branch on `canceled` before reading the scan
+ * Result of `lx.scanCode`. Branch on `status` before reading the scan
  * payload.
  */
 export type ScanCodeResult = {
-    canceled: false;
+    status: 'ok';
     scanResult: string;
     scanType: string;
 } | CanceledResult;
+/**
+ * Where `lx.host.setBadge` paints.
+ * `auto` (the default) marks every product-owned surface this platform
+ * has: the dock and the menu-bar item on macOS, the taskbar and the
+ * notification-area item on Windows, the home-screen icon on iOS and
+ * HarmonyOS. Name one only when that surface is the point.
+ * Asynchronous because it reports what actually happened: a platform that
+ * answers through its own callback has to be waited for to be believed.
+ * A surface with nothing to paint on is reported, not raised: a macOS
+ * status item exists from the moment a tray is declared but stays hidden
+ * until `lx.tray.show()`, and a badge on a hidden item is not a badge
+ * anyone can see. That resolves `false` whether you named the surface or
+ * took `auto`; only a malfunction rejects.
+ * Apple ties the badge to notification permission. On macOS the label
+ * always reaches the system, but the Dock declines to draw it for an app
+ * that is registered with Notification Center and not allowed — so a host
+ * that declares `capabilities.notifications` and never got a yes resolves
+ * `false` here. A host that never asks is unaffected.
+ * On iOS the home-screen badge is drawn by the notification system, so
+ * it needs notification permission and only accepts a number — that is
+ * the OS's rule, not an API coupling. Android has no cross-vendor
+ * launcher badge at all, so `setBadge` returns `false` there.
+ */
+export type SetBadgeOptions = {
+    surface?: 'auto' | 'appIcon' | 'tray';
+};
 /** Share images, PDFs, or other files. */
 export type ShareFilesOptions = ShareTitleOptions & {
     /**
@@ -1401,7 +1682,7 @@ export type ShellOpenAppOptions = {
      */
     channel?: LxAppEnvVersion;
     targetVersion?: string;
-    /** Stable identity for `lx.surface.get(key)`. */
+    /** Stable identity for `lx.surface.getByKey(key)`. */
     key?: string;
 };
 /**
@@ -1413,7 +1694,7 @@ export type ShellOpenAppOptions = {
  */
 export type ShellOpenDeclaredOptions = {
     /**
-     * Caller-owned identity, for `lx.surface.get(key)` later — the same key
+     * Caller-owned identity, for `lx.surface.getByKey(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
@@ -1508,7 +1789,10 @@ export type ShellSurfacePatch = {
     edge?: SurfaceEdge;
 };
 export type ShowActionSheetOptions = {
-    itemList: string[];
+    items: readonly {
+        id: string;
+        label: string;
+    }[];
     itemColor?: string;
 };
 export type ShowModalOptions = {
@@ -1525,7 +1809,7 @@ export type ShowToastOptions = {
     title: string;
     icon?: 'success' | 'error' | 'loading' | 'none';
     image?: string;
-    duration?: number;
+    durationMs?: number;
     mask?: boolean;
     position?: 'top' | 'center' | 'bottom';
 };
@@ -1542,7 +1826,7 @@ export type Storage = {
      * 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>;
+    get<T = unknown>(key: string, decode?: (value: unknown) => T): Promise<T | undefined>;
     set(key: string, value: unknown): Promise<void>;
     /**
      * Resolves whether an exact key exists, without reading its value. Prefer
@@ -1565,7 +1849,7 @@ export type StorageInfo = {
 export type StreamSourceOptions = {
     provider: string;
     isLive: boolean;
-    duration?: number;
+    durationSeconds?: number;
     params?: Record<string, unknown>;
 };
 /**
@@ -1584,19 +1868,16 @@ export type SurfaceApi = {
      */
     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.
+     * Find a live surface by the explicit key passed when opening it.
+     * Runtime-assigned ids are not lookup keys.
      */
-    get(keyOrId: string): AnySurface | undefined;
+    getByKey(key: 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;
+    watchContext(handler: (context: SurfaceContext) => void): () => void;
 };
 /** What every surface handle carries, whatever opened it. */
 export type SurfaceBase = {
@@ -1641,12 +1922,15 @@ export type SurfaceClosedEvent = {
     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`).
+ * The current surface viewport context, delivered to `lx.surface.watchContext()`
+ * so an lxapp can choose a compact or workspace View. Column count and
+ * spacing inside `regular` use CSS or the raw `width` / `height`.
  */
 export type SurfaceContext = {
-    /** compact (<600) / medium (600–840) / expanded (>840), with hysteresis. */
-    sizeClass: 'compact' | 'medium' | 'expanded';
+    /** Whether the host layout currently offers a docked aside. */
+    aside: boolean;
+    /** compact (<600) / regular (≥600). Shell medium/expanded are not distinct here. */
+    sizeClass: 'compact' | 'regular';
     /** Actual surface viewport width in logical pixels. */
     width: number;
     /** Actual surface viewport height in logical pixels. */
@@ -1777,31 +2061,29 @@ export type TabBarItemPatch = {
     badge?: string | null;
     redDot?: boolean;
 };
+/**
+ * Patch for `lx.tabBar.update()`. Items, badges, red dots, and
+ * visibility only — a `style` field is rejected. Colors stay in
+ * static `lxapp.json` `tabBar.style`. `backgroundColor` is
+ * mobile-only; the desktop sidebar follows the host
+ * `lingxia.yaml` theme.
+ */
 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 & {
+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. */
+    readonly scope: 'tab';
     activate(): Promise<void>;
-};
+}) | (Omit<SurfaceBase, 'close' | 'onClose'> & {
+    readonly kind: 'tab';
+    readonly realized: 'tab' | 'aside';
+    readonly scope: 'group';
+});
 export type TerminalApi = {
     /** Saved terminal settings, revision-checked on write. */
     readonly settings: TerminalSettingsApi;
@@ -1922,15 +2204,20 @@ export type TerminalThemeSettings = {
     light: string;
     dark: string;
 };
+export type ToastHandle = {
+    /** Dismiss this toast only; harmless after a newer toast replaces it. */
+    dismiss(): Promise<void>;
+};
 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`.
+ * no-op there (it never throws) — safe to call from portable code.
+ * The tray belongs to the product, not to the lxapp that happens to be
+ * running, so these are Control-app only: a guest lxapp calling one receives
+ * a permission error.
  */
 export type TrayMenuItem = {
     label: string;
@@ -1948,7 +2235,10 @@ export type UpdateFailedInfo = UpdateReadyInfo & {
 /**
  * Callback-based updates for this lxapp's bundle. Available to every
  * lxapp. To update the native host app, the Control app uses the
- * task-based `lx.app.checkUpdate()` API instead.
+ * task-based `lx.host.checkUpdate()` API instead.
+ * Listeners are a set: later subscriptions do not replace earlier ones.
+ * The last pending ready/failed event is replayed to each new
+ * subscriber until a newer event replaces it.
  */
 export type UpdateManager = {
     applyUpdate(): void;
@@ -1959,13 +2249,9 @@ export type UpdateManager = {
 };
 export type UpdateReadyInfo = {
     version?: string;
-    isForceUpdate?: boolean;
     channel?: "release" | "draft" | string;
 };
-export type UploadIteratorResult = {
-    done: boolean;
-    value?: UploadProgressEvent;
-};
+export type UploadIteratorResult = IteratorResult<UploadProgressEvent, void>;
 /**
  * Upload options. The file streams from disk, so the size ceiling is
  * the remote's, not memory.
@@ -1974,12 +2260,12 @@ export type UploadIteratorResult = {
  * - `multipart` (default) wraps the file in a `multipart/form-data`
  * envelope beside the `formData` text fields — what an ordinary form
  * endpoint parses. `name`, `fileName`, and `formData` describe that
- * envelope.
+ * envelope. `formData`, when present, must contain at least one field.
  * - `raw` sends the file bytes as the entire body. Presigned
  * object-storage URLs (S3, OSS, Azure Blob) need this: a multipart
  * envelope would be stored verbatim as the object's contents,
- * boundary lines and all. `name` and `formData` are then rejected
- * rather than silently dropped, and `fileName` is ignored.
+ * boundary lines and all. `name`, `formData`, and `fileName` are
+ * then rejected rather than silently dropped.
  * @example
  * ```ts
  * // A presigned URL is signed for one method and one Content-Type,
@@ -1991,8 +2277,8 @@ export type UploadIteratorResult = {
  * bodyMode: 'raw',
  * mimeType: 'video/mp4',
  * });
- * for await (const event of task) render(event.progress);
- * const { statusCode } = await task;
+ * for await (const event of task.progress) render(event.progress);
+ * const { statusCode } = await task.result;
  * ```
  */
 export type UploadOptions = {
@@ -2005,14 +2291,6 @@ export type UploadOptions = {
      * A presigned URL is signed for exactly one method, usually `PUT`.
      */
     method?: 'POST' | 'PUT' | 'PATCH';
-    /**
-     * How the file bytes are framed. Default: `multipart`.
-     * `raw` sends them as the whole body under a `Content-Length` taken from
-     * the file itself, which is what presigned endpoints require.
-     */
-    bodyMode?: 'multipart' | 'raw';
-    /** Name of the multipart part carrying the file. Default: `file`. Multipart only. */
-    name?: string;
     /**
      * Optional request headers.
      * Restricted headers such as `Referer` are ignored by the runtime.
@@ -2021,12 +2299,8 @@ export type UploadOptions = {
      * carries the part boundary.
      */
     headers?: Record<string, string>;
-    /** Text fields sent alongside the file in the envelope. Multipart only. */
-    formData?: Record<string, string>;
     /** Request timeout in milliseconds. */
-    timeout?: number;
-    /** Filename announced for the file part. Defaults to the file's own name. Multipart only. */
-    fileName?: string;
+    timeoutMs?: number;
     /**
      * File MIME type. Types the file part under `multipart`; becomes the
      * request `Content-Type` under `raw`, where it defaults to
@@ -2035,10 +2309,26 @@ export type UploadOptions = {
     mimeType?: string;
     /** Optional abort signal. */
     signal?: AbortSignal;
-};
+} & ({
+    /**
+     * How the file bytes are framed. Default: `multipart`.
+     */
+    bodyMode?: 'multipart';
+    /** Name of the multipart part carrying the file. Default: `file`. */
+    name?: string;
+    /** Text fields sent alongside the file. Must be non-empty when set. */
+    formData?: Record<string, string>;
+    /** Filename announced for the file part. Defaults to the file's own name. */
+    fileName?: string;
+} | {
+    /** Send the file bytes as the whole body. Multipart fields are rejected. */
+    bodyMode: 'raw';
+    name?: never;
+    formData?: never;
+    fileName?: never;
+});
 export type UploadProgressEvent = {
-    /** `completed` and `canceled` are terminal; iteration ends after either. */
-    kind: 'progress' | 'canceled' | 'completed';
+    kind: 'progress' | 'canceled';
     /** Bytes handed to the socket so far, envelope included under `multipart`. */
     uploadedBytes?: number;
     /**
@@ -2049,8 +2339,12 @@ export type UploadProgressEvent = {
     totalBytes?: number;
     /** `uploadedBytes / totalBytes`, absent while the total is unknown or zero. */
     progress?: number;
-    /** Present on `completed` only. */
-    result?: UploadResult;
+} | {
+    kind: 'completed';
+    uploadedBytes?: number;
+    totalBytes?: number;
+    progress?: number;
+    result: UploadResult;
 };
 export type UploadResult = {
     /** HTTP status code returned by the server. */
@@ -2058,21 +2352,13 @@ export type UploadResult = {
     /** 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 UploadTask = CancelableTask<UploadResult, UploadProgressEvent>;
 export type VideoCompressQuality = 'low' | 'medium' | 'high';
 export type VideoContext = {
     play(): void;
     pause(): void;
     stop(): void;
-    seek(position: number): void;
+    seek(positionSeconds: number): void;
     requestFullScreen(): void;
     exitFullScreen(): void;
     setStreamSource(options: StreamSourceOptions): void;
@@ -2184,7 +2470,7 @@ export type WindowsTerminalInlineImageStatus = {
 /**
  * Host app identity. Everything here is fixed for the life of the process;
  * the language the app renders in is not, and lives on
- * `lx.app.displayLanguage`.
+ * `lx.host.displayLanguage`.
  */
 export interface AppBaseInfo {
     /**
@@ -2194,7 +2480,7 @@ export interface AppBaseInfo {
     os: HostOs;
     productName: string;
     version: string;
-    SDKVersion: string;
+    sdkVersion: string;
 }
 /** Device info APIs. */
 export interface DeviceInfo {
@@ -2256,9 +2542,9 @@ export interface SystemSettingInfo {
 /** Wi-Fi APIs. */
 export interface WifiInfo {
     /** Service Set Identifier (network name) */
-    SSID: string;
+    ssid: string;
     /** Basic Service Set Identifier (MAC address) */
-    BSSID?: string;
+    bssid?: string;
     /** Whether the network is secure (requires password) */
     secure: boolean;
     /** Signal strength (0-100, higher is better) */
@@ -2266,15 +2552,13 @@ export interface WifiInfo {
     /** Center frequency in MHz (if available) */
     frequency?: number;
 }
-export declare class DirEntry {
-    private constructor();
+export interface DirEntry {
     readonly name: string;
     readonly isFile: boolean;
     readonly isDirectory: boolean;
     readonly isSymlink: boolean;
 }
-export declare class LxFile {
-    private constructor();
+export interface LxFile {
     /** The path supplied to `lx.fs.file`. */
     readonly path: string;
     /** Read the complete file as strict UTF-8 text. */
@@ -2297,6 +2581,56 @@ export declare class LxFile {
     /** Read metadata for this managed path. */
     stat(): Promise<FileStats>;
 }
+declare global {
+    interface ClipboardApi {
+        /**
+         * Replace the clipboard with Unicode text.
+         * Empty string is a valid payload (it is not `clear()`). The runtime does not
+         * present a toast — call `lx.showToast` if the product wants one. Rejects
+         * `E_INVALID_ARG` above 1 MiB.
+         */
+        writeText(text: string): Promise<void>;
+        /**
+         * Read Unicode text.
+         * Resolves `{ status: 'canceled' }` only when the user dismisses the OS paste
+         * prompt (iOS 16+, macOS 15.4+). No text representation (empty clipboard, or
+         * image-only) resolves `{ status: 'empty' }`. A copied empty
+         * string resolves `{ status: 'ok', text: '' }`.
+         * Rejects `E_PERMISSION_DENIED` when the host denies clipboard access
+         * outright: a macOS "never allow" setting, or HarmonyOS without
+         * `ohos.permission.READ_PASTEBOARD`. Android denies a read while the app has
+         * no window focus and reports it as an empty clipboard, so read in response
+         * to a user action.
+         */
+        readText(): Promise<ClipboardTextResult>;
+        /**
+         * Replace the clipboard with a typed item.
+         * Rejects `E_INVALID_ARG` for text above 1 MiB or an image file that does not
+         * decode.
+         */
+        write(item: ClipboardWriteItem): Promise<void>;
+        /**
+         * Read the clipboard.
+         * Omit `type` to receive every representation this host can surface.
+         * Pass `type` to request one; if that representation is absent, the
+         * completed result is `{ status: 'empty' }` rather than a mismatch error.
+         * Images arrive as a temporary PNG under `lx://temp`. Dismissal and
+         * permission behave as in `readText`.
+         */
+        read(options?: ClipboardReadOptions): Promise<ClipboardReadResult>;
+        /** Remove every representation. */
+        clear(): Promise<void>;
+        /**
+         * Which representations are present, without reading payloads. An empty
+         * array is an empty clipboard; representations this runtime cannot
+         * round-trip (HTML, files) are omitted.
+         * Never shows the OS paste prompt and needs no permission on any host, so it
+         * is the way to decide whether to offer "Paste". The answer is a hint —
+         * content may change before you read it.
+         */
+        types(): Promise<ClipboardType[]>;
+    }
+}
 declare global {
     interface FileSystemApi {
         /**
@@ -2304,44 +2638,53 @@ declare global {
          * Relative paths resolve under `lx.env.USER_DATA_PATH`. Creating a reference
          * does not require the path to exist.
          */
-        file(path: string): LxFile;
+        file(path: ManagedPath): LxFile;
         /** Test whether a managed path currently exists. */
-        exists(path: string): Promise<boolean>;
+        exists(path: ManagedPath): Promise<boolean>;
         /** Read metadata for a managed path. */
-        stat(path: string): Promise<FileStats>;
+        stat(path: ManagedPath): Promise<FileStats>;
         /** The direct children of a managed directory. */
-        readDir(path: string): Promise<DirEntry[]>;
+        readDir(path: ManagedPath): Promise<DirEntry[]>;
         /** Create a managed directory. */
-        mkdir(path: string, options?: FsMkdirOptions): Promise<void>;
+        mkdir(path: ManagedPath, options?: FsMkdirOptions): Promise<void>;
         /** Write UTF-8 text or bytes to a managed file. */
-        write(path: string, data: string, options?: FsWriteOptions): Promise<void>;
+        write(path: ManagedPath, data: string, options?: FsWriteOptions): Promise<void>;
         /** Copy a managed file. */
-        copy(source: string, destination: string, options?: FsCopyOptions): Promise<void>;
+        copy(source: ManagedPath, destination: ManagedPath, options?: FsCopyOptions): Promise<void>;
         /** Rename or move a managed file or directory. */
-        rename(source: string, destination: string, options?: FsRenameOptions): Promise<void>;
+        rename(source: ManagedPath, destination: ManagedPath, options?: FsRenameOptions): Promise<void>;
         /** Remove a managed file or directory. */
-        remove(path: string, options?: FsRemoveOptions): Promise<void>;
+        remove(path: ManagedPath, options?: FsRemoveOptions): Promise<void>;
     }
 }
 declare global {
     interface HostAppApi {
         /**
-         * `lx.app.screenshot(options?)` — capture the host app's window as a PNG.
+         * `lx.host.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 Control app, like the other host-level APIs on `lx.app`.
+         * restricted to the Control app, like the other host-level APIs on `lx.host`.
          */
         screenshot(options?: AppScreenshotOptions): Promise<AppScreenshotResult>;
         /**
-         * Check whether the host app has an update.
-         * This host-level capability is restricted to the Control app. 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.
+         * Query whether the host app has an update.
+         * This host-level capability is restricted to the Control app. A successful
+         * check does **not** take over the built-in auto-flow — that is
+         * `claimCustomUpdate()` or `update.apply()`. Permission denial or a failed
+         * check claims nothing. Incompatible updates are hidden as
+         * `hasUpdate: false`. Store-channel hosts still surface a newer feed version;
+         * `apply()` opens the store listing instead of downloading.
          */
         checkUpdate(): Promise<HostAppUpdateCheckResult>;
+        /**
+         * Claim the process-lifetime custom host-update flow.
+         * Irreversible: the built-in auto-flow will not prompt or download again,
+         * including after the calling page unloads. Does not cancel an already-started
+         * update task. Later failed checks do not undo a claim already made.
+         */
+        claimCustomUpdate(): void;
         readonly env: HostAppEnv;
         /**
          * Read the host app's identity: OS, product name, product version, and SDK
@@ -2357,29 +2700,31 @@ declare global {
          */
         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 — the product's own icon, not the calling lxapp's, so it is
-         * Control app only and other lxapps get a permission error. Null or an empty
-         * string clears it. Unsupported platforms treat the call as a no-op.
+         * Mark the product in system chrome, for example with an unread count.
+         * One call, because "where the count goes" is the platform's answer, not the
+         * caller's: `auto` paints every product-owned surface this platform has — the
+         * dock and the menu-bar item on macOS, the taskbar and the notification-area
+         * item on Windows, the home-screen icon on iOS and HarmonyOS. Name a
+         * `surface` only when one of them is the point.
+         * It is the product's chrome, not the calling lxapp's, so it is Control app
+         * only. Null or an empty string clears it.
+         * Returns whether anything was actually painted. A platform with no such
+         * chrome is a no-op that returns `false` rather than an error — portable code
+         * can call this unconditionally.
          */
-        setBadge(value: string | number | null): void;
+        setBadge(value: string | number | null, options?: SetBadgeOptions): Promise<boolean>;
     }
 }
 declare global {
     interface Lx {
-        readonly app: HostAppApi;
+        readonly host: 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.
+         * Frozen feature support, not permission or current layout. Unknown strings
+         * return false; non-strings throw TypeError. Required features also need an
+         * appropriate lxapp.json minRuntime.
          */
-        supports(query: LxCapabilityQuery): boolean;
+        supports(feature: LxFeature): boolean;
+        readonly clipboard: ClipboardApi;
         /** Vibrate briefly, where the device has a vibrator. */
         vibrateShort(): boolean;
         /** Vibrate for a longer pulse, where the device has a vibrator. */
@@ -2426,8 +2771,8 @@ declare global {
          * `method: 'PUT'` with `bodyMode: 'raw'` to send the file bytes as the whole
          * body instead, which is what presigned object-storage URLs expect.
          * Returns the task handle synchronously, before the transfer starts, so
-         * progress and cancellation can be wired up without racing it: the handle is
-         * awaitable for the final result, async-iterable for progress, and cancelable.
+         * progress and cancellation can be wired up without racing it: `result` settles
+         * once, `progress` streams to one consumer, and `cancel()` aborts.
          */
         uploadFile(options: UploadOptions): UploadTask;
         /**
@@ -2436,17 +2781,20 @@ declare global {
          * `mode: "auto"`.
          */
         openFile(options: OpenFileOptions): Promise<void>;
+        /** Pick one file. A successful selection returns one opaque URI. */
+        pickFile(options?: PickFileOptions): Promise<PickFileResult>;
+        /** Pick one or more files. Dismissal is a normal outcome. */
+        pickFiles(options?: PickFileOptions): Promise<ChooseFileResult>;
         /**
-         * 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
+         * Resolves `{ status: 'canceled' }` only when the user dismisses the picker. A
+         * completed selection resolves `{ status: 'ok', paths }` with at least one
          * path. Rejects when the picker fails or returns an invalid payload.
          */
-        chooseFile(options?: ChooseFileOptions): Promise<ChooseFileResult>;
+        chooseFile(options: never): Promise<never>;
         /**
          * Opens a directory picker.
-         * Resolves `{ canceled: true }` only when the user dismisses the picker. A
-         * completed selection resolves `{ canceled: false, path }`. Rejects when the
+         * Resolves `{ status: 'canceled' }` only when the user dismisses the picker. A
+         * completed selection resolves `{ status: 'ok', path }`. Rejects when the
          * picker fails or returns an invalid payload.
          */
         chooseDirectory(options?: ChooseDirectoryOptions): Promise<ChooseDirectoryResult>;
@@ -2465,8 +2813,8 @@ declare global {
         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
+         * Resolves `{ status: 'canceled' }` only when the user dismisses the picker. A
+         * completed selection resolves `{ status: 'ok', entries }` with at least one
          * entry. Rejects when capture or selection fails, or the host returns an invalid
          * payload.
          */
@@ -2474,10 +2822,8 @@ declare global {
         /**
          * 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).
+         * - `presented`: resolves `{ status: 'presented' }` only after the first
+         * frame; otherwise `{ status: 'notPresented', reason }`. 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
@@ -2495,8 +2841,8 @@ declare global {
         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
+         * Resolves `{ status: 'canceled' }` only when the user dismisses the scanner. A
+         * completed scan resolves `{ status: 'ok', scanResult, scanType }`. Rejects
          * when scanning fails or the host returns an invalid payload.
          */
         scanCode(options?: ScanCodeOptions): Promise<ScanCodeResult>;
@@ -2546,15 +2892,18 @@ declare global {
         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
+         * Resolves `{ status: 'ok', id }` when the user selects an item; `id` identifies the selected item. Resolves `{ status: 'canceled' }` only when the
          * user dismisses the sheet. Rejects when presentation fails or the host returns
          * an invalid selection.
          */
         showActionSheet(options: ShowActionSheetOptions): Promise<ActionSheetResult>;
+        /** Acknowledgement-only dialog. Resolves when the user dismisses it. */
+        alert(options: AlertOptions): Promise<void>;
+        /** Ask a yes/no question. Dismissal resolves false; presentation failure rejects. */
+        confirm(options: ConfirmOptions): Promise<boolean>;
         /**
          * Shows a confirmation modal.
-         * Resolves `{ canceled: false }` when the user confirms and `{ canceled: true }`
+         * Resolves `{ status: 'ok' }` when the user confirms and `{ status: 'canceled' }`
          * only when the user dismisses or cancels the modal. Rejects when presentation
          * fails or the host returns an invalid payload.
          */
@@ -2611,15 +2960,19 @@ declare global {
         reLaunch(options: ReLaunchOptions): Promise<void>;
         readonly shell: ShellApi;
         readonly tabBar: TabBarApi;
-        /** Show toast function */
-        showToast(options: ShowToastOptions): Promise<void>;
-        /** Hide toast function */
+        /**
+         * Presents a toast and resolves a handle once the host accepted it. The handle
+         * dismisses only this toast, never a newer one — including a newer one posted
+         * by another lxapp onto a host's shared overlay.
+         */
+        showToast(options: ShowToastOptions): Promise<ToastHandle>;
+        /** Hides whichever toast is showing. */
         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 Control-app-only
-         * `lx.app.checkUpdate()`, which updates the native host app.
+         * `lx.host.checkUpdate()`, which updates the native host app.
          */
         getUpdateManager(): UpdateManager;
     }
@@ -2708,34 +3061,35 @@ declare global {
          * `lingxia.yaml`, opened with the declaration's own presentation.
          */
         openDeclared(id: string): Promise<DeclaredSurface>;
+        /** Find a live surface by its explicit caller-owned key. Runtime ids are not keys. */
+        getByKey(key: string): AnySurface | undefined;
         /**
-         * `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
+         * `lx.surface.watchContext(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.
+         * presentation's viewport or host docking availability changes. Returns an unsubscribe fn.
          */
-        onContext(handler: (context: SurfaceContext) => void): () => void;
+        watchContext(handler: (context: SurfaceContext) => void): () => void;
     }
 }
 declare global {
     interface TabBarApi {
-        /** Patch this lxapp's tab bar; unset fields stay as they are. */
+        /**
+         * Patch this lxapp's tab bar; unset fields stay as they are.
+         * Items, badges, red dots, and visibility only. A `style` field is
+         * rejected — colors stay in static `lxapp.json` `tabBar.style`.
+         * `tabBar.style.backgroundColor` is mobile-only: it paints the bar on
+         * iOS / Android / Harmony. On macOS / Windows the sidebar follows the
+         * host `lingxia.yaml` theme (`windowBackgroundColor`) instead, so a
+         * `#FFFFFF` fill cannot paint a card on the sidebar. Other style keys
+         * (`foregroundColor`, `selectedForegroundColor`, `dividerColor`) may
+         * tint items while the desktop host is light; a dark host uses the
+         * shell theme for every key.
+         */
         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. */
@@ -2760,4 +3114,6 @@ declare global {
     }
 }
 export {};
+/** Feature contracts generated from the runtime registry. */
+export type LxFeature = 'app.appUse' | 'app.autostart' | 'app.banner' | 'app.browser' | 'app.browserUse' | 'app.computerUse' | 'app.mediaCapture' | 'app.notification' | 'app.proxy' | 'app.selfUpdate' | 'process' | 'surface.tab' | 'surface.window' | 'surface.window.fullChrome' | 'terminal';
 //# sourceMappingURL=logic.d.ts.map