@lingxia/types 0.17.0 → 0.18.0

package/src/generated/logic.ts

@@ -5,9 +5,21 @@
 // by external Rong modules in this generated prelude.
 declare const appDownloadPathBrand: unique symbol;
 declare const systemDownloadsPathBrand: unique symbol;
+/** Managed paths and relative userdata paths; system Downloads references are excluded. */
+export type ManagedPath = string & { readonly [systemDownloadsPathBrand]?: never };
 
-export interface PageConfig<TData extends Record<string, unknown> = Record<string, unknown>> {
-  data?: TData;
+/** 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>;
@@ -46,31 +58,98 @@ 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.
- */
-export type LazyInitField<T> = [T] extends [null | undefined]
-  ? unknown
-  : [T] extends [never[]]
-    ? unknown[]
-    : T;
-
-/**
- * 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.
- */
-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;
+ * @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;
+
+type PageReadonlyDepth = [never, 0, 1, 2, 3, 4, 5, 6];
+
+type PagePrimitive = string | number | boolean | bigint | symbol | null | undefined;
+
+/**
+ * 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]?: 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
@@ -81,7 +160,17 @@ 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>;
 }
 
 /**
@@ -98,6 +187,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;
 }
 
 /**
@@ -111,9 +206,9 @@ 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;
-  on(event: 'close', handler: (info: { code: string; reason: string }) => 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;
 }
 
 /**
@@ -132,36 +227,54 @@ export type DownloadOptions<TDestination extends DownloadDestination = DownloadD
 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 type DownloadProgressEvent<TResult extends DownloadResult = DownloadResult> =
+  | {
+      kind: 'progress' | 'paused' | 'resumed';
+      downloadedBytes?: number;
+      totalBytes?: number;
+      /** Present only when the total size is known. */
+      progress?: number;
+    }
+  | {
+      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 {
@@ -188,11 +301,24 @@ declare global {
 
     /**
      * 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;
 
@@ -201,19 +327,25 @@ declare global {
 
     /**
      * 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. */
@@ -223,18 +355,36 @@ 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.
@@ -255,7 +405,7 @@ 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>];
 
 /**
@@ -269,7 +419,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>;
@@ -279,15 +429,18 @@ export type TypedStorage<S extends object> = {
 };
 
 /**
- * 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;
 
@@ -295,7 +448,7 @@ export type AnySurface = PageSurface | DeclaredSurface | AppSurface | TabSurface
  * 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. */
@@ -333,7 +486,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.
      */
@@ -345,24 +498,15 @@ export type AppDownloadOptions = DownloadOptionsBase & {
 };
 
 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 & {
@@ -412,7 +556,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. */
@@ -425,7 +569,7 @@ export type AppSurface = SurfaceBase & SurfaceShowable & {
     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
@@ -447,25 +591,6 @@ export type 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 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
@@ -483,6 +608,36 @@ 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;
 
 /**
@@ -494,16 +649,15 @@ 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 = {
@@ -512,11 +666,11 @@ export type ChooseDirectoryOptions = {
 };
 
 /**
- * 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;
@@ -536,11 +690,11 @@ export type ChooseFileOptions = {
 };
 
 /**
- * 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.
@@ -555,25 +709,89 @@ 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;
@@ -582,27 +800,34 @@ export type CompressImageOptions = {
 };
 
 export type CompressImageResult = {
-    tempFilePath: string;
+    uri: string;
 };
 
-export type CompressVideoIteratorResult = {
-    done: boolean;
-    value?: CompressVideoProgressEvent;
-};
+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.
@@ -618,11 +843,8 @@ 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`. */
@@ -630,7 +852,7 @@ export type CompressVideoProgressEvent = {
 };
 
 export type CompressVideoResult = {
-    tempFilePath: string;
+    uri: string;
     width: number;
     height: number;
     durationMs: number;
@@ -644,23 +866,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
@@ -673,17 +883,20 @@ export type CompressVideoTask = PromiseLike<CompressVideoResult> & AsyncIterable
  */
 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');
  * ```
@@ -693,7 +906,7 @@ export type ControlApi = {
     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;
@@ -704,7 +917,7 @@ 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.
      */
@@ -712,7 +925,7 @@ export type ControlAppearanceApi = {
 };
 
 /**
- * `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 = {
@@ -741,7 +954,7 @@ 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
@@ -781,7 +994,7 @@ export type DownloadOptionsBase = {
      */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds. */
-    timeout?: number;
+    timeoutMs?: number;
     /** Optional abort signal. */
     signal?: AbortSignal;
 };
@@ -793,17 +1006,17 @@ 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;
 };
 
 /**
@@ -847,7 +1060,7 @@ export type ExtractVideoThumbnailResult = {
     /**
      * Generated thumbnail file path.
      */
-    tempFilePath: string;
+    uri: string;
     /**
      * Output image width in pixels.
      */
@@ -906,10 +1119,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 = {
@@ -949,7 +1162,7 @@ export type HostAppUpdateEvent = {
     downloadedBytes?: number;
     progress?: number;
 } | {
-    state: 'downloaded' | 'installRequested';
+    state: 'downloaded' | 'installRequested' | 'storeOpened';
 } | {
     state: 'failed';
     stage: HostAppUpdateApplyStage;
@@ -960,42 +1173,40 @@ 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';
+    /** `storeOpened` on a `store` channel: the listing opened, nothing was installed. */
+    state: 'installRequested' | 'storeOpened';
 };
 
-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 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';
@@ -1007,6 +1218,43 @@ export type InstalledTerminalFont = {
     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
@@ -1030,38 +1278,8 @@ 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;
@@ -1072,11 +1290,11 @@ 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;
 
 /**
@@ -1140,6 +1358,24 @@ export type NavigationBarStylePatch = {
     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 = {
@@ -1152,6 +1388,66 @@ 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. */
@@ -1206,7 +1502,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;
 };
 
@@ -1219,7 +1515,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;
 };
 
@@ -1267,6 +1563,10 @@ export type PageTargetOptions = {
     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. */
@@ -1278,28 +1578,12 @@ 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>;
@@ -1443,15 +1727,42 @@ export type ScanCodeOptions = {
 };
 
 /**
- * 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 & {
     /**
@@ -1586,7 +1897,7 @@ export type ShellOpenAppOptions = {
      */
     channel?: LxAppEnvVersion;
     targetVersion?: string;
-    /** Stable identity for `lx.surface.get(key)`. */
+    /** Stable identity for `lx.surface.getByKey(key)`. */
     key?: string;
 };
 
@@ -1599,7 +1910,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
@@ -1699,7 +2010,7 @@ export type ShellSurfacePatch = {
 };
 
 export type ShowActionSheetOptions = {
-    itemList: string[];
+    items: readonly { id: string; label: string }[];
     itemColor?: string;
 };
 
@@ -1718,7 +2029,7 @@ export type ShowToastOptions = {
     title: string;
     icon?: 'success' | 'error' | 'loading' | 'none';
     image?: string;
-    duration?: number;
+    durationMs?: number;
     mask?: boolean;
     position?: 'top' | 'center' | 'bottom';
 };
@@ -1736,7 +2047,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
@@ -1761,7 +2072,7 @@ export type StorageInfo = {
 export type StreamSourceOptions = {
     provider: string;
     isLive: boolean;
-    duration?: number;
+    durationSeconds?: number;
     params?: Record<string, unknown>;
 };
 
@@ -1781,19 +2092,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. */
@@ -1842,12 +2150,15 @@ export type SurfaceClosedEvent = {
 };
 
 /**
- * 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. */
@@ -1994,34 +2305,31 @@ export type TabBarItemPatch = {
     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. */
@@ -2157,6 +2465,11 @@ export type TerminalThemeSettings = {
     dark: string;
 };
 
+export type ToastHandle = {
+    /** Dismiss this toast only; harmless after a newer toast replaces it. */
+    dismiss(): Promise<void>;
+};
+
 export type TrayApi = globalThis.TrayApi;
 
 /**
@@ -2164,9 +2477,10 @@ export type TrayApi = globalThis.TrayApi;
  * 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;
@@ -2187,7 +2501,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;
@@ -2199,14 +2516,10 @@ 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
@@ -2216,12 +2529,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,
@@ -2233,8 +2546,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 = {
@@ -2247,14 +2560,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.
@@ -2263,12 +2568,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
@@ -2277,11 +2578,30 @@ 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;
     /**
@@ -2292,8 +2612,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 = {
@@ -2303,15 +2627,7 @@ export type UploadResult = {
     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';
 
@@ -2319,7 +2635,7 @@ 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;
@@ -2436,7 +2752,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 {
   /**
@@ -2446,7 +2762,7 @@ export interface AppBaseInfo {
   os: HostOs;
   productName: string;
   version: string;
-  SDKVersion: string;
+  sdkVersion: string;
 }
 
 /** Device info APIs. */
@@ -2516,9 +2832,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) */
@@ -2527,16 +2843,14 @@ export interface WifiInfo {
   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. */
@@ -2560,6 +2874,57 @@ export declare class LxFile {
   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 {
     /**
@@ -2567,45 +2932,54 @@ 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
@@ -2621,30 +2995,32 @@ 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.
-     */
-    setBadge(value: string | number | null): void;
+     * 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, options?: SetBadgeOptions): Promise<boolean>;
   }
 }
 
 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;
+    readonly host: HostAppApi;
+    /**
+     * 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(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. */
@@ -2691,8 +3067,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;
     /**
@@ -2701,17 +3077,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>;
@@ -2730,8 +3109,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.
      */
@@ -2739,10 +3118,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
@@ -2760,8 +3137,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>;
@@ -2811,15 +3188,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.
      */
@@ -2876,15 +3256,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;
   }
@@ -2978,36 +3362,37 @@ 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. */
@@ -3033,3 +3418,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';