@lingxia/types 0.11.1 → 0.13.0

package/src/generated/logic.ts

@@ -21,9 +21,10 @@ export interface PageInstance<TData extends Record<string, unknown> = Record<str
   data: TData;
   route: string;
   /**
-   * Available when this page was opened as a surface via `lx.openSurface(...)`.
+   * Available when this page was opened as a surface via
+   * `lx.surface.openPage(...)`.
    */
-  surface?: Surface;
+  surface?: PageSurface;
   /**
    * Available when this page was opened by `lx.navigateTo(...)`.
    */
@@ -111,12 +112,6 @@ export interface DownloadTask<TDownloadResult extends DownloadResult = DownloadR
   wait(): Promise<TDownloadResult>;
 }
 
-export interface FileManager {
-  readFile(options: ReadTextFileOptions): Promise<ReadTextFileResult>;
-  readFile(options: ReadBinaryFileOptions): Promise<ReadBinaryFileResult>;
-  readFile(options: ReadFileOptions): Promise<ReadFileResult>;
-}
-
 declare global {
   // HostAppApi/LxEnv members are emitted from the Rust js_api metadata; these
   // merges only add what Rong cannot express — the cfg-gated autostart member
@@ -130,8 +125,9 @@ declare global {
     readonly envVersion: HostAppEnvVersion;
 
     /**
-     * Launch-at-startup control. Present only on macOS / Windows with the
-     * capability declared; gate access with `lx.app.autostart?.…`.
+     * Launch-at-startup control. Absent where the host cannot register a
+     * startup item; its presence and `lx.supports({ capability: 'autostart' })` always
+     * agree, so `lx.app.autostart?.…` and the query are interchangeable.
      */
     autostart?: AutostartApi;
   }
@@ -141,16 +137,11 @@ declare global {
 
   interface Lx {
     /**
-     * Open a surface. Browser tabs resolve to `null`, declared surfaces to a
-     * host-managed handle, and page surfaces to a full `Surface`. URL asides
-     * return a `Surface` when docked and `null` in compact browser chrome.
-     * `as: "window"` is desktop-only.
+     * 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.
      */
-    openSurface(spec: OpenUrlTabSpec): Promise<null>;
-    openSurface(spec: OpenDeclaredSurfaceSpec | OpenLxappSurfaceSpec | OpenNativeSurfaceSpec): Promise<SurfaceHandle>;
-    openSurface(spec: OpenPageSurfaceSpec): Promise<Surface>;
-    openSurface(spec: OpenUrlAsideSpec): Promise<Surface | null>;
-    openSurface(spec: OpenSurfaceSpec): Promise<Surface | SurfaceHandle | null>;
+    readonly terminal?: TerminalApi;
 
     /** Download to the downloads directory. */
     downloadFile(options: DownloadsDownloadOptions): DownloadTask<DownloadsDownloadResult>;
@@ -160,13 +151,61 @@ declare global {
     downloadFile<TDestination extends DownloadDestination = "app">(
       options: DownloadOptions<TDestination>,
     ): DownloadTask<DownloadResultForDestination<TDestination>>;
+
+    /**
+     * Open this lxapp's store with every key's shape pinned on the handle.
+     * `get` / `set` / `delete` then share that schema instead of
+     * repeating `get<T>()` at each call site.
+     */
+    getStorage<S extends StorageSchema>(): TypedStorage<S>;
   }
 }
 
-export type ActionSheetResult = {
-    tapIndex: number;
+/**
+ * A map of storage keys to stored value shapes.
+ *
+ * `object` deliberately accepts both type aliases and interfaces. Requiring a
+ * string index signature would reject ordinary interface-based schemas.
+ */
+export type StorageSchema = object;
+
+type StorageKey<S extends object> = Extract<keyof S, string>;
+type StorageEntry<S extends object> = {
+  [K in StorageKey<S>]: [key: K, value: S[K]];
+}[StorageKey<S>];
+
+/**
+ * Schema-typed view of the same store `lx.getStorage()` returns.
+ * Runtime is identical; only the key/value types are pinned.
+ *
+ * The schema constrains what this handle writes and reads, not what the store
+ * contains: a previous app version, or another code path holding the untyped
+ * handle, can have written keys outside it. That is why `list` still resolves
+ * plain strings — narrowing it to the schema's keys would be the same
+ * unchecked assertion this type exists to remove from `get<T>()`.
+ */
+export type TypedStorage<S extends object> = {
+  get<K extends StorageKey<S>>(key: K): Promise<S[K] | undefined>;
+  set(...entry: StorageEntry<S>): Promise<void>;
+  delete(key: StorageKey<S>): Promise<void>;
+  clear(): Promise<void>;
+  list(prefix?: string): Promise<string[]>;
+  info(): Promise<StorageInfo>;
 };
 
+/**
+ * Result of `lx.showActionSheet`. Branch on `canceled` before reading
+ * the selected item index.
+ */
+export type ActionSheetResult = {
+    canceled: false;
+    /** Index of the tapped item in `itemList`. */
+    index: number;
+} | CanceledResult;
+
+/** Every surface handle, narrowable by `kind`. */
+export type AnySurface = PageSurface | DeclaredSurface | AppSurface | TabSurface | BuiltinSurface;
+
 export type AppConfig = {
     globalData?: Record<string, unknown>;
     onLaunch?: (options?: AppLaunchOptions) => void | Promise<void>;
@@ -253,13 +292,23 @@ export type AppScreenshotResult = {
     height?: number;
 };
 
+/** Another lxapp composed into a shell slot. */
+export type AppSurface = SurfaceBase & SurfaceShowable & {
+    readonly kind: 'app';
+    readonly realized: 'main' | 'aside';
+};
+
+export type AppearanceApi = globalThis.AppearanceApi;
+
+export type AppearancePreference = 'auto' | 'light' | 'dark';
+
 /**
  * Launch-at-startup control for the host app.
- * **macOS 13+ / Windows only.** Everywhere else — other platforms, or a
- * macOS shell older than 13 — `lx.app.autostart` is absent (`undefined`);
- * presence is the support check, so portable code gates on the member itself:
+ * 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.app.autostart) {
+ * if (lx.supports({ capability: 'autostart' })) {
  * // render the "Launch at startup" toggle
  * }
  * ```
@@ -291,13 +340,25 @@ export type AutostartApi = {
 
 export type BinaryFileData = ArrayBuffer | ArrayBufferView;
 
-export type CapsuleRect = {
-    width?: number;
-    height?: number;
-    top?: number;
-    right?: number;
-    bottom?: number;
-    left?: number;
+/**
+ * Built-in browser product page. Opening one requires
+ * `capabilities.browser` and is restricted to the home lxapp.
+ */
+export type BuiltinShellPage = 'settings' | 'downloads';
+
+/**
+ * A host builtin page such as settings or downloads. The shell owns
+ * its lifetime and its visibility, so this handle reports identity:
+ * there is no `show` / `hide`, and the inherited `close()` rejects
+ * with `unsupported_placement`.
+ */
+export type BuiltinSurface = SurfaceBase & {
+    readonly kind: 'builtin';
+};
+
+/** The user dismissed the operation. Never an error. */
+export type CanceledResult = {
+    canceled: true;
 };
 
 export type ChooseDirectoryOptions = {
@@ -305,12 +366,15 @@ export type ChooseDirectoryOptions = {
     defaultPath?: string;
 };
 
+/**
+ * Result of `lx.chooseDirectory`. Branch on `canceled` before reading
+ * the selected directory.
+ */
 export type ChooseDirectoryResult = {
-    /** True if the user dismissed the dialog without selecting. */
-    canceled: boolean;
-    /** Native-consumable directory reference (path or URI). Undefined when canceled. */
-    path?: string;
-};
+    canceled: false;
+    /** Native-consumable directory reference (path or URI). */
+    path: string;
+} | CanceledResult;
 
 export type ChooseFileOptions = {
     /** Allow selecting multiple files. Default: false */
@@ -326,16 +390,20 @@ export type ChooseFileOptions = {
     defaultPath?: string;
 };
 
+/**
+ * Result of `lx.chooseFile`. Branch on `canceled` before reading the
+ * selected paths.
+ */
 export type ChooseFileResult = {
-    /** True if the user dismissed the dialog without selecting. */
-    canceled: boolean;
+    canceled: false;
     /**
-     * File paths returned by LingXia. Values may be app-local paths, `lx://...`
-     * paths, or platform system-picker references. Treat them as opaque strings
-     * and pass them back to LingXia APIs such as `lx.share`.
+     * File paths returned by LingXia; always at least one. Values may be
+     * app-local paths, `lx://...` paths, or platform system-picker references.
+     * Treat them as opaque strings and pass them back to LingXia APIs such as
+     * `lx.share`.
      */
-    paths: string[];
-};
+    paths: [string, ...string[]];
+} | CanceledResult;
 
 export type ChooseMediaOptions = {
     count?: number;
@@ -345,6 +413,16 @@ export type ChooseMediaOptions = {
     maxDuration?: number;
 };
 
+/**
+ * Result of `lx.chooseMedia`. Branch on `canceled` before reading the
+ * selected entries.
+ */
+export type ChooseMediaResult = {
+    canceled: false;
+    /** Picked media; always at least one entry. */
+    entries: [ChosenMediaEntry, ...ChosenMediaEntry[]];
+} | CanceledResult;
+
 export type ChosenMediaEntry = {
     tempFilePath: string;
     fileType: 'image' | 'video';
@@ -444,11 +522,9 @@ export type ConnectWifiOptions = {
     password?: string;
 };
 
-export type CopyFileOptions = {
-    srcPath: string;
-    destPath: string;
-    /** Defaults to false. */
-    overwrite?: boolean;
+/** A surface declared by the host in `lingxia.yaml`. */
+export type DeclaredSurface = SurfaceBase & SurfaceShowable & {
+    readonly kind: 'declared';
 };
 
 /** Display and orientation APIs. */
@@ -479,7 +555,7 @@ export type DownloadResult = AppDownloadResult | DownloadsDownloadResult;
 export type DownloadsDownloadOptions = DownloadOptionsBase & {
     /**
      * Optional filename hint for the system Downloads destination.
-     * This is not an app-owned FileManager path.
+     * This is not an app-owned `lx.fs` path.
      */
     filePath?: string;
     /** Save into the user's system Downloads directory. */
@@ -487,17 +563,13 @@ export type DownloadsDownloadOptions = DownloadOptionsBase & {
 };
 
 export type DownloadsDownloadResult = {
-    /** Native system Downloads path. Do not pass this to `FileManager`. */
+    /** Native system Downloads path. Do not pass this to `lx.fs`. */
     filePath: SystemDownloadsPath;
     tempFilePath?: never;
     mimeType?: string;
     size: number;
 };
 
-export type ExistsOptions = {
-    path: string;
-};
-
 export type ExtractVideoThumbnailOptions = {
     /**
      * Source video path or `lx://` URI.
@@ -554,6 +626,36 @@ export type FileDialogFilter = {
     extensions: string[];
 };
 
+export type FileSystemApi = globalThis.FileSystemApi;
+
+export type FsCopyOptions = {
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+
+export type FsMkdirOptions = {
+    recursive?: boolean;
+};
+
+export type FsRemoveOptions = {
+    recursive?: boolean;
+};
+
+export type FsRenameOptions = {
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+
+export type FsWriteOptions = {
+    /**
+     * How string input is interpreted. Strings are UTF-8 by default; `base64`
+     * decodes the input into raw bytes before writing.
+     */
+    encoding?: 'utf8' | 'base64';
+    /** Defaults to false. */
+    overwrite?: boolean;
+};
+
 /** Media picker, preview, scan, and file processing APIs. */
 export type GetImageInfoOptions = {
     path: string;
@@ -582,8 +684,8 @@ export type HostAppApi = globalThis.HostAppApi;
  * `crates/lingxia-update::ReleaseType` enum and the `envVersion` field in the
  * generated `app.json`. Pre-envVersion app artifacts are treated as `'release'`.
  * Note: this is *separate* from `LxAppEnvVersion` in the navigator module,
- * which encodes lxapp release channels (`'develop' | 'preview' | 'release'`)
- * for cross-app navigation URLs and uses the truncated `develop` form.
+ * which encodes lxapp release channels for cross-app navigation URLs —
+ * same three names, different axis.
  */
 export type HostAppEnvVersion = 'developer' | 'preview' | 'release';
 
@@ -622,9 +724,9 @@ export type HostAppUpdateInfo = {
      * The returned task can be awaited directly when progress is not needed, or
      * consumed with `for await...of` to render progress.
      *
-     * Direct package handoff is currently supported on Android and macOS. Other
-     * platforms reject with an unsupported-operation error; use `version` and
-     * `releaseNotes` to guide users to the appropriate app marketplace.
+     * Requires `lx.supports({ capability: 'selfUpdate' })`. Where the host cannot
+     * install its own update it rejects with an unsupported-operation error;
+     * use `version` and `releaseNotes` to guide users to the app marketplace.
      */
     apply(): HostAppUpdateTask;
 };
@@ -647,6 +749,13 @@ export type HostAppUpdateTask = PromiseLike<HostAppUpdateResult> & AsyncIterable
     wait(): Promise<HostAppUpdateResult>;
 };
 
+export type InstalledTerminalFont = {
+    family: string;
+    monospace: boolean;
+    ligatures: boolean;
+    nerdIcons: boolean;
+};
+
 /**
  * Input event APIs.
  * Platform support: Android only
@@ -665,13 +774,43 @@ export type KeyEvent = {
 
 export type KeyEventCallback = (event: KeyEvent) => void;
 
-export type LxAppEnvVersion = 'release' | 'preview' | 'develop';
+export type LxAppEnvVersion = 'release' | 'preview' | 'developer';
 
 /** LxApp metadata APIs. */
 export type LxAppReleaseType = 'release' | 'preview' | 'developer';
 
+/** Boolean capability names accepted by `lx.supports`. */
+export type LxCapabilityFlag = 'terminal' | 'autostart' | 'notifications' | 'browser' | 'proxy' | 'selfUpdate' | 'process' | 'appUse' | 'computerUse' | 'browserUse' | 'mediaCapture';
+
+/**
+ * One capability question per call. The catalog is closed, so
+ * completion enumerates it and a typo is a type error. `capability`
+ * is the discriminant; only the `surface` branch accepts a `value`.
+ * Two surface answers describe an *affordance*, not whether the call
+ * succeeds: `tab` is "the host has an in-app browser" — without it a
+ * url still opens, in the OS browser instead — and `aside` is "a
+ * docked region exists right now", while a compact layout still opens
+ * the url through the in-app browser's own chrome. Ask them to decide
+ * what to render, not whether to call.
+ * `chrome` qualifies a window and only a window: it asks whether this
+ * host can produce that decoration, not merely a window.
+ */
+export type LxCapabilityQuery = {
+    capability: 'surface';
+    value: 'window';
+    chrome?: WindowChrome;
+} | {
+    capability: 'surface';
+    value: Exclude<LxSurfaceCapability, 'window'>;
+} | {
+    capability: LxCapabilityFlag;
+};
+
 export type LxEnv = globalThis.LxEnv;
 
+/** Surface placements accepted by `lx.supports`. */
+export type LxSurfaceCapability = 'main' | 'aside' | 'float' | 'window' | 'tab';
+
 /** Device action APIs. */
 export type MakePhoneCallOptions = {
     phoneNumber: string;
@@ -681,24 +820,50 @@ export type MediaObjectFit = 'cover' | 'contain' | 'fill' | 'fit';
 
 export type MediaRotation = 0 | 90 | 180 | 270;
 
-export type MkdirOptions = {
-    path: string;
-    recursive?: boolean;
-};
-
+/**
+ * Result of `lx.showModal`. `canceled: false` means the user confirmed;
+ * there is no third resolved outcome. Presentation failures reject.
+ */
 export type ModalResult = {
-    confirm: boolean;
-    cancel: boolean;
+    canceled: false;
+} | CanceledResult;
+
+/**
+ * One app-declared action shown in the host-provided More affordance.
+ * Mobile hosts render these in the capsule sheet; desktop hosts render
+ * them in the lxapp context menu. The native menu is fully dismissed
+ * before `onClick` runs.
+ */
+export type MoreAction = {
+    /** Bundled resource path or an app-accessible local `lx://` path. */
+    icon: string;
+    /** Visible action label. */
+    label: string;
+    onClick: () => void | Promise<void>;
 };
 
+/**
+ * Options for `lx.navigateBack()`. Omit the object or `delta` to pop
+ * one page.
+ */
 export type NavigateBackOptions = {
-    delta: number;
+    /** Number of pages to pop. Defaults to 1. */
+    delta?: number;
 };
 
-export type NavigateToLxAppOptions = {
+/**
+ * Navigate to another lxapp inside the current App Surface. JavaScript
+ * callers address pages by their configured name; page routes are an
+ * internal runtime detail and are not accepted as input.
+ */
+export type NavigateToAppOptions = {
     appId: string;
+    /**
+     * Configured page name from the target lxapp's `lxapp.json`. Omit it to
+     * open the target app's initial page. Full routes such as
+     * `/pages/home/index` are not supported.
+     */
     page?: string;
-    path?: string;
     query?: PageQuery;
     envVersion?: LxAppEnvVersion;
     targetVersion?: string;
@@ -706,6 +871,20 @@ export type NavigateToLxAppOptions = {
 
 export type NavigateToOptions = PageTargetOptions;
 
+export type NavigationBarApi = globalThis.NavigationBarApi;
+
+export type NavigationBarPatch = {
+    title?: string | null;
+    homeButton?: VisibilityPreference;
+    style?: NavigationBarStylePatch | null;
+};
+
+export type NavigationBarStylePatch = {
+    backgroundColor?: string | null;
+    foregroundColor?: string | null;
+    dividerColor?: string | null;
+};
+
 export type NetworkChangeCallback = (info: NetworkInfo) => void;
 
 export type NetworkInfo = {
@@ -718,24 +897,6 @@ export type NetworkInfo = {
 /** Network status APIs. */
 export type NetworkType = 'none' | 'unknown' | 'wifi' | '2g' | '3g' | '4g' | '5g' | 'ethernet';
 
-/**
- * Show a surface declared by id in the host's `lingxia.yaml`.
- * Available to any lxapp granted access to that declaration.
- */
-export type OpenDeclaredSurfaceSpec = {
-    surface: string;
-    /** Docking edge override for this open. */
-    edge?: SurfaceEdge;
-    page?: never;
-    url?: never;
-    lxapp?: never;
-    native?: never;
-    as?: never;
-    position?: never;
-    size?: never;
-    query?: never;
-};
-
 /** File system APIs. */
 export type OpenFileOptions = {
     /** Local file path or runtime-managed temp path. */
@@ -753,139 +914,58 @@ export type OpenFileOptions = {
 };
 
 /**
- * Open another lxapp by appId (home lxapp only). A declared surface
- * toggles its shell presentation; an undeclared lxapp opens as a main
- * tab, or docks as an aside panel with `as: 'aside'`.
+ * `as` picks the shape. A float anchors and carries no decoration; a
+ * window is decorated and does not anchor. The runtime rejects the
+ * wrong pairing either way, so the type says it first — except with an
+ * ordered preference, where the realized placement is not known up
+ * front and both stay open.
  */
-export type OpenLxappSurfaceSpec = {
-    lxapp: string;
-    /** Defaults to the lingxia.yaml role, else 'main'. */
-    as?: 'main' | 'aside' | 'float';
+export type OpenPageOptions = (OpenPageShared & {
+    /** The default. Rejects when the host cannot float. */
+    as?: 'float';
+    /** Where the float anchors. */
+    position?: SurfaceFloatPosition;
+    chrome?: never;
+}) | (OpenPageShared & {
+    /** A separate desktop window. Rejects when the host cannot make one. */
+    as: 'window';
+    /** Window decoration. */
+    chrome?: WindowChrome;
+    position?: never;
+}) | (OpenPageShared & {
     /**
-     * Docking edge override for this open. Without it the surface keeps its
-     * current placement (initially the `lingxia.yaml` edge); with it the panel
-     * opens there — or moves there if already visible.
+     * An ordered preference: the first placement the host can realize wins,
+     * and `realized` reports which.
      */
-    edge?: SurfaceEdge;
-    page?: never;
-    url?: never;
-    native?: never;
-    position?: never;
-    size?: never;
-    query?: never;
-};
-
-/**
- * Open a host-registered native capability (home lxapp only), e.g.
- * the built-in terminal declared in `lingxia.yaml` surfaces.
- */
-export type OpenNativeSurfaceSpec = {
-    native: string;
-    /** Docking edge override for this open. */
-    edge?: SurfaceEdge;
-    page?: never;
-    url?: never;
-    lxapp?: never;
-    as?: never;
-    position?: never;
-    size?: never;
-    query?: never;
-};
-
-/**
- * Spec for {@link OpenSurfaceSpec}. A discriminated union keyed by source so a
- * page name and a declared surface id never collide (each is its own string
- * space, separately type-checkable).
- * - `{ page }` — one of this lxapp's own pages, by name, arranged as `as`
- * (`float` is a popup; `window` is a bare desktop window, which rejects on
- * mobile). `position` applies to `float`, and `size` is a Host-clamped hint.
- * They are fixed at open (re-open to change). Your own pages **cannot** be
- * docked as an `aside` — an aside is external content only (see `{ url }`).
- * For a side panel of your own, use a declared `surface`, an in-page split
- * layout, or `role: main` for a switchable destination.
- * `float` is a popup layered above the main at `position` (like a dialog); it
- * takes no layout space. `interaction` controls the native close button,
- * outside-click dismissal, and modality. Defaults are no button,
- * `tapOutside`, and non-modal.
- * - `{ surface }` — a surface declared in `lingxia.yaml` `surfaces:`, by id
- * (e.g. `'terminal'`, `'ai-assistant'`). Form, position, and startup data come
- * from the declaration.
- * - `{ url }` — external content in the in-app browser. Without `as` it opens as
- * a main browser tab (the **self** browser: full chrome **with an editable
- * address bar**, no handle). With `as: 'aside'` it opens in the **browser
- * aside** — a docked (large screen) / full-screen (phone) **multi-tab** browser
- * for external content only (`https://` or `file://`).
- * The aside is **API-only** and never permits address editing or a manual
- * "new tab" action. Desktop may show the current address read-only; compact
- * phone/Runner chrome omits the address row entirely.
- * Tabs are **deduped by URL** — reopening a URL focuses the existing tab and
- * preserves its current navigation. On `medium` / `expanded`, the returned
- * handle is **tab-scoped**: `close()` closes that tab. Compact browser chrome
- * owns the group and returns `null`. Closing the last tab closes the aside;
- * dismissing it only hides the group. The tab UI shows page **titles** (never
- * the URL), plus per-tab close, back/forward, refresh, and dismissal.
- * Presentation is the only large/small difference: on `medium` / `expanded`
- * the aside **docks** and splits beside the main at `edge` (default `'right'`)
- * with a horizontal title tab strip; on `compact` (phone / runner) it presents
- * **full-screen** with a single-row **bottom** browser toolbar (tabs reached
- * via an aside-only switcher). System/edge Back and the toolbar dismiss action
- * exit the whole aside even when page history exists; the explicit browser
- * Back button navigates history. `size` is a host-clamped preferred size
- * (large screen only).
- */
-export type OpenPageSurfaceSpec = {
-    page: string;
-    /** A popup above the main. */
-    as: 'float';
+    as: readonly ('float' | 'window')[];
+    chrome?: WindowChrome;
     position?: SurfaceFloatPosition;
+});
+
+export type OpenPageShared = {
+    /**
+     * A float accepts a percentage; a window is in logical pixels and ignores
+     * one. Both live here rather than in two option types, because `as` may be
+     * an ordered preference and the realized placement is not known up front.
+     */
     size?: OverlaySurfaceSize;
     interaction?: SurfaceInteraction;
     query?: Record<string, unknown>;
-    edge?: never;
-    surface?: never;
-    url?: never;
-} | {
-    page: string;
-    as: 'window';
-    size?: WindowSurfaceSize;
-    /** Windows use manual dismissal; `tapOutside` is invalid. */
-    interaction?: SurfaceInteraction;
-    query?: Record<string, unknown>;
-    edge?: never;
-    position?: never;
-    surface?: never;
-    url?: never;
+    /** Caller-owned identity, for `lx.surface.get(key)` later. */
+    key?: string;
 };
 
-export type OpenSurfaceSpec = OpenPageSurfaceSpec | OpenDeclaredSurfaceSpec | OpenLxappSurfaceSpec | OpenNativeSurfaceSpec | OpenUrlTabSpec | OpenUrlAsideSpec;
-
-/**
- * Open `url` in the multi-tab browser aside. `url` must be `https://` or
- * `file://` (external content only). Repeated calls add/focus tabs (deduped by
- * URL) in the single aside per window. Medium/expanded returns a tab-scoped
- * handle; compact returns `null` because browser chrome owns the group. See
- * {@link OpenSurfaceSpec} for the full aside contract.
- */
-export type OpenUrlAsideSpec = {
-    url: string;
-    as: 'aside';
+export type OpenUrlOptions = {
+    /**
+     * `tab` opens a browser tab; `aside` docks the browser beside the main.
+     * Defaults to `'tab'`.
+     */
+    as?: 'tab' | 'aside' | readonly ('tab' | 'aside')[];
+    /** Preferred docking side when the realized placement is an aside. */
     edge?: SurfaceEdge;
     size?: OverlaySurfaceSize;
-    page?: never;
-    surface?: never;
-    position?: never;
-    query?: never;
-};
-
-export type OpenUrlTabSpec = {
-    url: string;
-    as?: never;
-    page?: never;
-    surface?: never;
-    edge?: never;
-    position?: never;
-    size?: never;
-    query?: never;
+    /** Stable identity for `lx.surface.get(key)`. */
+    key?: string;
 };
 
 export type OverlaySurfaceSize = {
@@ -915,20 +995,20 @@ export type PageQuery = Record<string, PageQueryValue>;
 
 export type PageQueryValue = string | number | boolean | null | undefined;
 
+/** One of this lxapp's own pages, opened as a float or a window. */
+export type PageSurface = SurfaceBase & SurfaceShowable & SurfaceMessaging & {
+    readonly kind: 'page';
+    readonly realized: 'float' | 'window';
+};
+
 /**
  * Target page for `navigateTo`, `redirectTo`, `switchTab`, and `reLaunch`.
- * Pass exactly one of `page` or `path`; there is no `url` field. Page
- * names and routes are discoverable with `lxdev lxapp pages`.
+ * JavaScript navigation accepts only the configured page name; full routes
+ * are internal runtime details. Discover names with `lxdev lxapp pages`.
  */
 export type PageTargetOptions = {
     /** Configured page name from `lingxia.yaml` / `lxapp.json`. */
     page: string;
-    path?: never;
-    query?: PageQuery;
-} | {
-    /** Full page route, for example `/pages/home/index`. */
-    path: string;
-    page?: never;
     query?: PageQuery;
 };
 
@@ -1090,45 +1170,9 @@ export type PreviewMediaSource = {
 
 export type ReLaunchOptions = PageTargetOptions;
 
-export type ReadBinaryFileOptions = {
-    filePath: string;
-    encoding?: undefined;
-};
-
-export type ReadBinaryFileResult = {
-    data: ArrayBuffer;
-};
-
-export type ReadDirOptions = {
-    path: string;
-};
-
-export type ReadFileOptions = ReadTextFileOptions | ReadBinaryFileOptions;
-
-export type ReadFileResult = ReadTextFileResult | ReadBinaryFileResult;
-
-export type ReadTextFileOptions = {
-    filePath: string;
-    encoding: 'utf8' | 'base64';
-};
-
-export type ReadTextFileResult = {
-    data: string;
-};
-
 export type RedirectToOptions = PageTargetOptions;
 
-export type RemoveOptions = {
-    path: string;
-    recursive?: boolean;
-};
-
-export type RenameOptions = {
-    oldPath: string;
-    newPath: string;
-    /** Defaults to false. */
-    overwrite?: boolean;
-};
+export type ResolvedAppearance = 'light' | 'dark';
 
 export type SaveMediaOptions = {
     filePath: string;
@@ -1139,10 +1183,15 @@ export type ScanCodeOptions = {
     scanType?: ('barCode' | 'qrCode' | 'datamatrix' | 'pdf417')[];
 };
 
+/**
+ * Result of `lx.scanCode`. Branch on `canceled` before reading the scan
+ * payload.
+ */
 export type ScanCodeResult = {
+    canceled: false;
     scanResult: string;
     scanType: string;
-};
+} | CanceledResult;
 
 /** Share images, PDFs, or other files. */
 export type ShareFilesOptions = ShareTitleOptions & {
@@ -1205,10 +1254,12 @@ export type ShareQuery = Record<string, string | number | boolean>;
 
 export type ShareResult = {
     /**
-     * Best-effort completion flag. Some platforms can only confirm that the
-     * system share UI was opened or closed.
+     * What the share sheet reported. Not part of the `canceled` family: some
+     * platforms only observe that the system UI opened and closed, so the
+     * unknown case is stated rather than hidden in a missing boolean that
+     * every call site would read as "not shared".
      */
-    completed?: boolean;
+    outcome: 'completed' | 'dismissed' | 'unknown';
 };
 
 export type ShareTextBaseOptions = ShareTitleOptions & {
@@ -1235,28 +1286,149 @@ export type ShareTitleOptions = {
 };
 
 /**
- * One app-declared shell activator. Its `id` remains stable across
- * updates and activation. The shell only routes activation to the
- * callback; the app owns every resulting action.
+ * App-owned host-shell chrome. Mutations are available only to the home
+ * lxapp's Logic context; other lxapps receive a permission error.
+ */
+export type ShellApi = {
+    /**
+     * Declares runtime actions in the desktop shell's sidebar header or footer.
+     * The shell controls layout and only dispatches activation; callbacks own
+     * navigation and all other behavior.
+     */
+    sidebarActions: ShellSidebarActionsApi;
+    /** Compose another lxapp into a shell slot. */
+    openApp(appId: string, options: ShellOpenAppOptions): Promise<AppSurface>;
+    /** Open a host builtin page such as settings or downloads. */
+    openBuiltin(page: BuiltinShellPage): Promise<BuiltinSurface>;
+    /**
+     * Open a declared surface with shell privileges — the same declaration
+     * `lx.surface.openDeclared` opens, plus the keyed multi-instance form and
+     * placement overrides.
+     */
+    openDeclared(id: string, options?: ShellOpenDeclaredOptions): Promise<DeclaredSurface>;
+    /** Re-place a live declared surface: change its role or its edge. */
+    reconfigure(id: string, patch: ShellSurfacePatch): Promise<void>;
+};
+
+export type ShellOpenAppOptions = {
+    /** `main` occupies the primary content area; `aside` a companion region. */
+    as: 'main' | 'aside';
+    /** Preferred docking side. Only meaningful with `as: 'aside'`. */
+    edge?: SurfaceEdge;
+    /**
+     * Configured page name from the target lxapp's `lxapp.json`. Omit it to
+     * open that app's initial page. Full page routes are not supported.
+     */
+    page?: string;
+    query?: PageQuery;
+    /** Defaults to 'release'. */
+    envVersion?: LxAppEnvVersion;
+    targetVersion?: string;
+    /** Stable identity for `lx.surface.get(key)`. */
+    key?: string;
+};
+
+/**
+ * The declared-surface options only the home lxapp may use.
+ * Creating an extra instance and overriding a placement both mutate
+ * shared shell composition, so they live here and not on
+ * `lx.surface.openDeclared` — which consumes a declaration exactly as
+ * the host authored it, and therefore takes no options at all.
  */
-export type ShellActivator = {
+export type ShellOpenDeclaredOptions = {
+    /**
+     * Caller-owned identity, for `lx.surface.get(key)` later — the same key
+     * every opener takes. It carries one extra power here: a declaration can
+     * be opened more than once, and the key is which instance you mean, so a
+     * new key creates one. 1 to 128 UTF-8 bytes. Declarations without
+     * instantiable native providers reject it with `capability_missing`.
+     */
+    key?: string;
+    /**
+     * Open with a role other than the declaration's. Must be realizable by the
+     * declared provider; a stable root rejects anything but `main`. Prefer this
+     * over opening and then calling `reconfigure`, which would present the
+     * wrong role first.
+     */
+    as?: 'main' | 'aside' | 'float';
+    /** Preferred docking side when the effective role is `aside`. */
+    edge?: SurfaceEdge;
+};
+
+/**
+ * One app-declared shell sidebar action. It is a stateless command, not a
+ * selectable navigation item: the shell invokes `onActivate` once and
+ * does not infer a target or active state.
+ */
+export type ShellSidebarAction = {
+    /** Stable, non-empty id; unique across both header and footer actions. */
     id: string;
+    /**
+     * Initial host-owned region. Use `replace` to move an action. The header
+     * takes at most two; everything else belongs in the footer.
+     */
+    placement: ShellSidebarActionPlacement;
+    /**
+     * Local lxapp-accessible icon. Use a bundled relative path such as
+     * `public/settings.svg`, or an `lx://temp`, `lx://usercache`, or
+     * `lx://userdata` path returned by LingXia file APIs. Native absolute paths,
+     * parent traversal, `file:` URLs, and network URLs are rejected; download a
+     * remote icon before registration. For portable rendering, prefer a square,
+     * transparent, monochrome SVG or PNG designed for a 16-point visual.
+     */
     icon: string;
+    /**
+     * Visible footer title and the tooltip/accessibility text for every
+     * placement. Long footer labels are kept on one line and tail-truncated.
+     */
     label: string;
+    /** Visible but non-activatable when true. Defaults to false. */
     disabled?: boolean;
+    /**
+     * Called once for each enabled mouse, keyboard, accessibility, shortcut, or
+     * automation activation. Explicitly open or navigate to the desired content.
+     */
     onActivate: () => void;
 };
 
-/** Mutable presentation fields for an existing activator. */
-export type ShellActivatorUpdate = {
+/**
+ * Where the host renders a sidebar action on desktop.
+ * - `header`: icon-only, at most two actions; `label` supplies tooltip
+ * and accessibility text. Hidden in the compact/collapsed shell.
+ * - `footer`: icon and label in the expanded sidebar, icon-only in the
+ * compact rail. The host wraps cells and scrolls after five visible
+ * rows.
+ * Apps cannot configure cell size, row, weight, color, or selected state.
+ * Where an action lives in the sidebar.
+ * `header` is the caption row beside the window controls: at most two
+ * actions, for the ones a person reaches for constantly. Declaring a
+ * third rejects the whole `replace` call rather than hiding one.
+ * `footer` is unbounded and scrolls, and every entry stays visible at
+ * any window size. Anything that must be findable belongs here.
+ */
+export type ShellSidebarActionPlacement = 'header' | 'footer';
+
+/**
+ * Mutable presentation fields for an existing sidebar action. The patch
+ * must contain at least one field. Use `replace` to change `placement` or
+ * `onActivate`.
+ */
+export type ShellSidebarActionUpdate = {
+    /** Replacement local icon, with the same path rules as registration. */
     icon?: string;
+    /** Replacement non-empty visible/accessibility label. */
     label?: string;
+    /** Whether the action remains visible but rejects activation. */
     disabled?: boolean;
 };
 
-/** Shell chrome writer API (home lxapp only). */
-export type ShellApi = {
-    activators: ShellActivatorsApi;
+/**
+ * Role and edge overrides the home lxapp may apply to a live declared
+ * surface. A stable root rejects non-main roles.
+ */
+export type ShellSurfacePatch = {
+    as?: 'main' | 'aside' | 'float';
+    edge?: SurfaceEdge;
 };
 
 export type ShowActionSheetOptions = {
@@ -1284,17 +1456,25 @@ export type ShowToastOptions = {
     position?: 'top' | 'center' | 'bottom';
 };
 
-export type StatOptions = {
-    path: string;
-};
-
-/** Persistent key-value storage backed by the lxapp database. */
+/**
+ * Asynchronous persistent key-value storage backed by the lxapp
+ * database. Use `lx.fs` for path-based data.
+ * `get<T>()` is an unchecked assertion at the call site. Pin every
+ * key's shape once with `lx.getStorage<Schema>()` — that returns a
+ * `TypedStorage<Schema>` instead of this untyped handle.
+ */
 export type Storage = {
-    get(key: string): Promise<unknown>;
+    /**
+     * Reads a stored value. `T` is an unchecked assertion about the stored
+     * shape, exactly like a `JSON.parse` boundary; a missing key resolves
+     * `undefined`, which a stored `null` never does.
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
     set(key: string, value: unknown): Promise<void>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
-    list(prefix?: string): Promise<IterableIterator<string>>;
+    /** Resolves every key, optionally filtered by prefix. */
+    list(prefix?: string): Promise<string[]>;
     info(): Promise<StorageInfo>;
 };
 
@@ -1312,62 +1492,67 @@ export type StreamSourceOptions = {
     params?: Record<string, unknown>;
 };
 
-export type Surface = SurfaceHandle & {
-    readonly kind: 'overlay' | 'window';
+/**
+ * Content-keyed surface composition, callable by any lxapp. Privileged
+ * composition lives on `lx.shell`, so the namespace is the privilege.
+ */
+export type SurfaceApi = {
+    /** Open one of this lxapp's own pages as a float or a window. */
+    openPage(page: string, options?: OpenPageOptions): Promise<PageSurface>;
+    /** Open external content in the in-app browser. */
+    openUrl(url: string, options?: OpenUrlOptions): Promise<TabSurface>;
     /**
-     * Last-known visibility, kept in sync with the native side via show/hide
-     * events. False once the surface has been closed. Safe to bind into
-     * declarative UI; for event-driven updates subscribe via `onShow`/`onHide`.
+     * Open a surface the host declared in `lingxia.yaml`, with the placement
+     * the declaration chose. Instance keys and placement overrides are shell
+     * composition; they live on `lx.shell.openDeclared`.
      */
-    readonly visible: boolean;
+    openDeclared(id: string): Promise<DeclaredSurface>;
     /**
-     * True until `close()` fires. After close the surface is detached and the
-     * page instance is being torn down; further `show()` / `hide()` calls will
-     * reject.
+     * 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.
      */
-    readonly alive: boolean;
-    /**
-     * Sends a message to the other side of a page surface.
-     *
-     * For the opener this targets the opened page. For the opened page this
-     * targets the opener. URL surfaces have no page-side receiver.
-    */
-    postMessage(message: unknown): void;
-    onMessage(handler: (message: unknown) => void): () => void;
-    onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
+    get(keyOrId: string): AnySurface | undefined;
     /**
-     * Fires when the surface transitions to visible, regardless of whether
-     * `show()` was called on this side or on the peer. Returns an unsubscribe
-     * function. Only fires on real state changes — calling `show()` on an
-     * already-visible surface is a no-op for listeners.
+     * Observe this presentation's viewport. Invoked immediately with the
+     * current context, then again whenever it changes. Returns an unsubscribe
+     * function.
      */
-    onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+    onContext(handler: (context: SurfaceContext) => void): () => void;
+};
+
+/** What every surface handle carries, whatever opened it. */
+export type SurfaceBase = {
+    readonly kind: SurfaceKind;
+    readonly id: string;
+    /** The caller-supplied identity, when this surface was opened with one. */
+    readonly key?: string;
     /**
-     * Fires when the surface transitions to hidden, regardless of which side
-     * triggered it. Returns an unsubscribe function. Only fires on real state
-     * changes.
+     * The placement the host produced, which an ordered preference may narrow.
+     * Live rather than a snapshot: `lx.shell.reconfigure` updates it on the
+     * handle you already hold.
      */
-    onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
-    close(): Promise<void>;
+    readonly realized: SurfacePlacement;
+    /** True until `close()` fires; afterwards the page instance is torn down. */
+    readonly alive: boolean;
     /**
-     * Toggle the surface to visible without tearing it down. The page instance
-     * and its state survive a hide / show round-trip — only close() actually
-     * destroys the surface and fires the onClose listener. Idempotent: calling
-     * on an already-visible surface resolves without firing `onShow`.
+     * Last-known visibility, kept in sync with the native side. Safe to bind
+     * into declarative UI; for event-driven updates use `onShow` / `onHide`.
      */
-    show(): Promise<void>;
+    readonly visible: boolean;
     /**
-     * Hide the surface without destroying it. The page instance stays mounted,
-     * so a subsequent show() restores the same scroll position, form input,
-     * and JS state. Hidden surfaces still receive postMessage but are not
-     * visible to the user. Idempotent.
+     * Destroy the surface. The stable root main cannot be closed. Repeated
+     * calls after a successful close are idempotent.
      */
-    hide(): Promise<void>;
+    close(): Promise<void>;
+    onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
 };
 
 /**
  * Surfaces (docked asides, floats, windows, browser tabs, declared surfaces)
- * and the desktop tray — the types behind `lx.openSurface`, `lx.onSurfaceContext`,
+ * and the desktop tray — the types behind `lx.surface`, `lx.shell`,
  * and `lx.tray`.
  */
 export type SurfaceCloseReason = 'user' | 'programmatic' | 'owner_closed' | 'app_closed' | 'failed'
@@ -1380,12 +1565,11 @@ export type SurfaceCloseReason = 'user' | 'programmatic' | 'owner_closed' | 'app
 
 export type SurfaceClosedEvent = {
     id: string;
-    kind: 'overlay' | 'window';
     reason: SurfaceCloseReason;
 };
 
 /**
- * The current surface viewport context, delivered to `lx.onSurfaceContext()`
+ * The current surface viewport context, delivered to `lx.surface.onContext()`
  * so an lxapp can self-adapt (e.g. switch column count by `sizeClass`).
  */
 export type SurfaceContext = {
@@ -1397,37 +1581,54 @@ export type SurfaceContext = {
     height: number;
 };
 
-/** Edge an aside docks to; the Host decides the realized form by screen size. */
+/**
+ * Preferred docking side for an aside when the Host has room for a docked
+ * layout. `aside` selects the companion region; `edge` selects a side within
+ * it. Compact Hosts may reproject the same aside as a full-screen overlay.
+ */
 export type SurfaceEdge = 'left' | 'right' | 'top' | 'bottom';
 
+/**
+ * A surface rejection. The runtime carries the surface code on
+ * `data.code` — `code` itself is the transport-level host code, shared
+ * with every other `lx` rejection — so read it with
+ * `surfaceErrorCode(error)` and never parse the message.
+ * ```ts
+ * import { surfaceErrorCode } from 'lingxia-types/error';
+ * catch (error) {
+ * if (surfaceErrorCode(error) === 'unsupported_placement') { … }
+ * }
+ * ```
+ */
+export type SurfaceError = Error & {
+    readonly data?: { readonly code?: SurfaceErrorCode };
+};
+
+/**
+ * Why a surface operation was refused. Carried as `code` on every
+ * `SurfaceError`, so no caller has to match on message text.
+ */
+export type SurfaceErrorCode = /** The placement cannot be realized by this host build. */
+'unsupported_placement'
+/** A privileged operation was called by an lxapp other than the home lxapp. */
+ | 'denied'
+/** No such declared surface, lxapp, or builtin page. */
+ | 'not_declared'
+/** The arguments are malformed or combine options that cannot apply together. */
+ | 'invalid_arg'
+/** The target is already open in a role this call cannot change. */
+ | 'already_open_other_role'
+/** The surface has been closed; the handle is detached. */
+ | 'closed'
+/** The host lacks a capability the request needs, such as an instantiable
+ * native provider for a keyed surface. */
+ | 'capability_missing'
+/** The operation reached the host and failed there. */
+ | 'failed';
+
 /** Where a float popup anchors (default `center`). */
 export type SurfaceFloatPosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
 
-export type SurfaceHandle = {
-    readonly id: string;
-    /** Standalone windows have no role in the primary shell graph. */
-    readonly role?: SurfaceRole;
-    readonly presentation: SurfacePresentation;
-    readonly visible: boolean;
-    readonly alive: boolean;
-    /**
-     * Show a host-managed surface. Dynamic page/url surfaces return a Promise;
-     * host-declared surfaces may complete synchronously.
-     */
-    show(): void | Promise<void>;
-    /**
-     * Hide without destroying user-visible state when the platform supports it.
-     */
-    hide(): void | Promise<void>;
-    /**
-     * Destroy the live surface. Repeated close calls are idempotent.
-     */
-    close(): void | Promise<void>;
-    onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
-    onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
-    onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
-};
-
 /** Native interaction supplied by the host around page content. */
 export type SurfaceInteraction = {
     /** Show the standard circular close button. Default `false`. */
@@ -1438,32 +1639,241 @@ export type SurfaceInteraction = {
     modal?: boolean;
 };
 
+/**
+ * Where the content came from. The discriminant on every surface
+ * handle, so `AnySurface` narrows without a runtime `typeof` check.
+ */
+export type SurfaceKind = 'page' | 'declared' | 'app' | 'tab' | 'builtin';
+
+/** Two-way messaging, available when both sides are lxapp pages. */
+export type SurfaceMessaging = {
+    /**
+     * Send to the other side. For the opener this targets the opened page;
+     * for the opened page it targets the opener.
+     */
+    postMessage(message: unknown): void;
+    onMessage(handler: (message: unknown) => void): () => void;
+};
+
+/**
+ * What the host actually produced. Reported by `realized`, which is
+ * how a caller reads the outcome of an ordered placement preference.
+ */
+export type SurfacePlacement = 'main' | 'aside' | 'float' | 'window' | 'tab';
+
 export type SurfacePresentation = 'main' | 'dock' | 'overlay' | 'popover' | 'sheet' | 'window';
 
 export type SurfaceRole = 'main' | 'aside' | 'float';
 
+/** Surfaces the host can hide and restore without losing page state. */
+export type SurfaceShowable = {
+    /**
+     * Restore a hidden surface. The page instance survived, so scroll
+     * position, form input, and JS state come back with it. Idempotent.
+     */
+    show(): Promise<void>;
+    /**
+     * Hide without destroying. Main surfaces cannot be hidden and reject.
+     * Idempotent.
+     */
+    hide(): Promise<void>;
+    /** Fires on a real transition to visible, whichever side drove it. */
+    onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+    /** Fires on a real transition to hidden, whichever side drove it. */
+    onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
+};
+
 /**
  * Detail payload for `onShow` / `onHide` events. `source` identifies which
  * Surface object initiated the visibility change so observers can
  * distinguish self-driven transitions from peer-driven ones (e.g. an opener
  * UI that wants to update its own button state only when the page side
- * toggled visibility).
+ * toggled visibility). `shell` identifies a host-driven main switch.
  */
 export type SurfaceVisibilityEvent = {
     id: string;
-    kind: 'overlay' | 'window';
-    source: 'opener' | 'page';
+    source: 'opener' | 'page' | 'shell';
 };
 
 export type SwitchTabOptions = PageTargetOptions;
 
-/** Native system Downloads path. Do not pass this to `FileManager`. */
+/** Native system Downloads path. Do not pass this to `lx.fs`. */
 export type SystemDownloadsPath = string & {
     readonly [systemDownloadsPathBrand]: 'system-downloads-path';
 };
 
-export type TabBarRedDotOptions = {
+export type TabBarApi = globalThis.TabBarApi;
+
+export type TabBarItemPatch = {
     index: number;
+    text?: string | null;
+    iconPath?: string | null;
+    selectedIconPath?: string | null;
+    badge?: string | null;
+    redDot?: boolean;
+};
+
+export type TabBarPatch = {
+    visibility?: TabBarVisibilityPreference;
+    style?: TabBarStylePatch | null;
+    items?: readonly TabBarItemPatch[];
+};
+
+export type TabBarStylePatch = {
+    foregroundColor?: string | null;
+    selectedForegroundColor?: string | null;
+};
+
+export type TabBarVisibilityPreference = 'auto' | 'visible' | 'hidden';
+
+/** External content in the in-app browser. */
+export type TabSurface = SurfaceBase & {
+    readonly kind: 'tab';
+    readonly realized: 'tab' | 'aside';
+    /**
+     * `tab` when this handle owns exactly the tab it opened, and `close()` /
+     * `activate()` act on it. `group` when the browser chrome owns the tab
+     * strip: the content is open, but control belongs to that chrome, so both
+     * methods reject with `unsupported_placement`. Branch on this rather than
+     * on the old platform-dependent `null`.
+     */
+    readonly scope: 'tab' | 'group';
+    /** Bring this tab to the front of its browser. `scope: 'group'` rejects. */
+    activate(): Promise<void>;
+};
+
+export type TerminalApi = {
+    /** Saved terminal settings, revision-checked on write. */
+    readonly settings: TerminalSettingsApi;
+    /** Installed color schemes, plus import and live preview. */
+    readonly colorSchemes: TerminalColorSchemesApi;
+    /** Terminal fonts installed on this machine. */
+    readonly fonts: TerminalFontsApi;
+    /** Windows-only optional inline-image compatibility runtime. */
+    readonly windows?: WindowsTerminalApi;
+};
+
+export type TerminalColorScheme = {
+    name?: string;
+    background: string;
+    foreground: string;
+    cursorColor?: string;
+    selectionBackground?: string;
+    selectionForeground?: string;
+    black: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    purple: string;
+    cyan: string;
+    white: string;
+    brightBlack: string;
+    brightRed: string;
+    brightGreen: string;
+    brightYellow: string;
+    brightBlue: string;
+    brightPurple: string;
+    brightCyan: string;
+    brightWhite: string;
+};
+
+export type TerminalColorSchemeDetails = {
+    name: string;
+    source: 'builtIn' | 'imported';
+    scheme: TerminalColorScheme;
+};
+
+export type TerminalColorSchemesApi = {
+    list(): Promise<TerminalColorSchemeDetails[]>;
+    import(options: {
+        text: string;
+        name?: string;
+        /** Existing names are rejected unless overwrite is explicit. */
+        overwrite?: boolean;
+    }): Promise<TerminalColorSchemeDetails>;
+    createPreview(): TerminalPreviewController;
+};
+
+export type TerminalFontSettings = {
+    /** Ordered candidates; the first installed monospaced family wins. */
+    family: string[];
+    size: number;
+    lineHeight: number;
+    ligatures: boolean;
+};
+
+export type TerminalFontsApi = {
+    list(): Promise<InstalledTerminalFont[]>;
+};
+
+export type TerminalPreviewController = {
+    /** Preview a stored name or an unpersisted scheme. Last request wins. */
+    show(scheme: string | TerminalColorScheme): Promise<void>;
+    /** Restore saved settings only when this controller owns the preview. */
+    clear(): Promise<void>;
+    /** Idempotently clear and retire this controller. */
+    close(): Promise<void>;
+};
+
+export type TerminalSettingsApi = {
+    get(): Promise<TerminalSettingsSnapshot>;
+    update(
+        patch: TerminalSettingsPatch,
+        options: { ifRevision: number },
+    ): Promise<TerminalSettingsSnapshot>;
+    reset(options: {
+        ifRevision: number;
+        scope?: 'font' | 'theme';
+    }): Promise<TerminalSettingsSnapshot>;
+    /** Fires after saved settings, effective appearance, or fonts change. */
+    onChange(listener: (snapshot: TerminalSettingsSnapshot) => void): () => void;
+};
+
+export type TerminalSettingsPatch = {
+    font?: Partial<TerminalFontSettings>;
+    theme?: Partial<TerminalThemeSettings>;
+};
+
+export type TerminalSettingsSnapshot = {
+    /** Monotonic process revision used by update/reset compare-and-swap. */
+    revision: number;
+    /** Framework defaults. */
+    defaults: TerminalSettingsValue;
+    /** User-authored fields only. */
+    overrides: TerminalSettingsPatch;
+    /** Resolved configuration after all valid layers. */
+    value: TerminalSettingsValue;
+    effective: {
+        /** Host appearance before applying terminal.theme.mode. */
+        systemAppearance: 'light' | 'dark';
+        appearance: 'light' | 'dark';
+        colorScheme: string | null;
+        font: {
+            family: string;
+            missing: string[];
+            fellBack: boolean;
+        };
+    };
+    warnings: TerminalSettingsWarning[];
+};
+
+export type TerminalSettingsValue = {
+    font: TerminalFontSettings;
+    theme: TerminalThemeSettings;
+};
+
+export type TerminalSettingsWarning = {
+    code: 'invalidUserFile' | 'missingColorScheme';
+    message: string;
+};
+
+export type TerminalThemeMode = 'system' | 'light' | 'dark';
+
+export type TerminalThemeSettings = {
+    mode: TerminalThemeMode;
+    light: string;
+    dark: string;
 };
 
 export type TrayApi = globalThis.TrayApi;
@@ -1493,11 +1903,17 @@ export type UpdateFailedInfo = UpdateReadyInfo & {
     error?: string;
 };
 
-/** Runtime update APIs. */
+/**
+ * Callback-based updates for this lxapp's bundle. Available to every
+ * lxapp. To update the native host app, the home lxapp uses the
+ * task-based `lx.app.checkUpdate()` API instead.
+ */
 export type UpdateManager = {
     applyUpdate(): void;
-    onUpdateReady(callback: (info: UpdateReadyInfo) => void): void;
-    onUpdateFailed(callback: (info: UpdateFailedInfo) => void): void;
+    /** Subscribes to a ready update and returns the unsubscribe fn. */
+    onUpdateReady(callback: (info: UpdateReadyInfo) => void): () => void;
+    /** Subscribes to a failed update and returns the unsubscribe fn. */
+    onUpdateFailed(callback: (info: UpdateFailedInfo) => void): () => void;
 };
 
 export type UpdateReadyInfo = {
@@ -1511,35 +1927,91 @@ export type UploadIteratorResult = {
     value?: UploadProgressEvent;
 };
 
+/**
+ * Upload options. The file streams from disk, so the size ceiling is
+ * the remote's, not memory.
+ * `bodyMode` picks the body shape, and with it which of the other
+ * fields apply:
+ * - `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.
+ * - `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.
+ * @example
+ * ```ts
+ * // A presigned URL is signed for one method and one Content-Type,
+ * // so both have to match whatever the signer used.
+ * const task = lx.uploadFile({
+ * url: presignedUrl,
+ * filePath: 'lx://media/clip.mp4',
+ * method: 'PUT',
+ * bodyMode: 'raw',
+ * mimeType: 'video/mp4',
+ * });
+ * for await (const event of task) render(event.progress);
+ * const { statusCode } = await task;
+ * ```
+ */
 export type UploadOptions = {
     /** HTTP(S) destination URL. */
     url: string;
     /** Local file path or runtime-managed URI to upload. */
     filePath: string;
-    /** Multipart field name. Default: `file`. */
+    /**
+     * HTTP method. Default: `POST`.
+     * 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.
+     * `Content-Type` is yours to set only under `bodyMode: 'raw'`, where it
+     * wins over `mimeType`; a multipart body owns the header, because it
+     * carries the part boundary.
      */
     headers?: Record<string, string>;
-    /** Optional extra `multipart/form-data` text fields. */
+    /** Text fields sent alongside the file in the envelope. Multipart only. */
     formData?: Record<string, string>;
     /** Request timeout in milliseconds. */
     timeout?: number;
-    /** Override multipart filename. */
+    /** Filename announced for the file part. Defaults to the file's own name. Multipart only. */
     fileName?: string;
-    /** Override file MIME type. */
+    /**
+     * File MIME type. Types the file part under `multipart`; becomes the
+     * request `Content-Type` under `raw`, where it defaults to
+     * `application/octet-stream`.
+     */
     mimeType?: string;
     /** Optional abort signal. */
     signal?: AbortSignal;
 };
 
 export type UploadProgressEvent = {
+    /** `completed` and `canceled` are terminal; iteration ends after either. */
     kind: 'progress' | 'canceled' | 'completed';
+    /** Bytes handed to the socket so far, envelope included under `multipart`. */
     uploadedBytes?: number;
+    /**
+     * Bytes the whole request body will carry. Equals the file size under
+     * `bodyMode: 'raw'`; under `multipart` it also covers the envelope, so it
+     * runs slightly above the file size.
+     */
     totalBytes?: number;
+    /** `uploadedBytes / totalBytes`, absent while the total is unknown or zero. */
     progress?: number;
+    /** Present on `completed` only. */
     result?: UploadResult;
 };
 
@@ -1635,6 +2107,8 @@ export type VideoInfo = {
     path: string;
 };
 
+export type VisibilityPreference = 'auto' | 'hidden';
+
 export type WifiConnectedCallback = (info: WifiConnectedInfo) => void;
 
 export type WifiConnectedInfo = WifiInfo & {
@@ -1642,6 +2116,16 @@ export type WifiConnectedInfo = WifiInfo & {
     state: string;
 };
 
+/**
+ * Window decoration. `system` is the standard title bar. `full`
+ * extends the page to the window edge while keeping the system
+ * minimize, maximize, resize, and drag affordances — the runtime owns
+ * a native drag strip across the top and publishes its height as
+ * `topInset` on the page-chrome snapshot, so a page that does nothing
+ * to opt in still cannot trap the user.
+ */
+export type WindowChrome = 'system' | 'full';
+
 export type WindowSurfaceSize = {
     /** Initial window width in logical pixels. */
     width?: number;
@@ -1649,22 +2133,23 @@ export type WindowSurfaceSize = {
     height?: number;
 };
 
-export type WriteBinaryFileOptions = {
-    filePath: string;
-    data: BinaryFileData;
-    encoding?: never;
-    /** Defaults to false. */
-    overwrite?: boolean;
+export type WindowsTerminalApi = {
+    status(): Promise<WindowsTerminalInlineImageStatus>;
+    /** Verify and install the fixed Microsoft ConPTY package from lxapp temp storage. */
+    install(options: { path: string }): Promise<WindowsTerminalInlineImageStatus>;
+    /** Select the installed runtime for new terminal sessions. */
+    setEnabled(options: { enabled: boolean }): Promise<WindowsTerminalInlineImageStatus>;
 };
 
-export type WriteFileOptions = WriteTextFileOptions | WriteBinaryFileOptions;
-
-export type WriteTextFileOptions = {
-    filePath: string;
-    data: string;
-    encoding?: 'utf8' | 'base64';
-    /** Defaults to false. */
-    overwrite?: boolean;
+export type WindowsTerminalInlineImageStatus = {
+    enabled: boolean;
+    installed: boolean;
+    package: {
+        version: string;
+        url: string;
+        sha256: string;
+        bytes: number;
+    };
 };
 
 /** Host app base information. */
@@ -1690,6 +2175,11 @@ export interface AppBaseInfo {
   SDKVersion: string;
 }
 
+export interface AppearanceState {
+  preference: AppearancePreference;
+  resolved: ResolvedAppearance;
+}
+
 /** Device info APIs. */
 export interface DeviceInfo {
   brand: string;
@@ -1741,50 +2231,12 @@ export interface LxAppInfo {
   releaseType: LxAppReleaseType;
 }
 
-/** Options for removing TabBar badge */
-export interface RemoveTabBarBadgeOptions {
-  index: number;
-}
-
 export interface ScreenInfo {
   width: number;
   height: number;
   scale: number;
 }
 
-/** Options for setNavigationBarColor */
-export interface SetNavigationBarColorOptions {
-  frontColor: string;
-  backgroundColor: string;
-}
-
-/** Options for setNavigationBarTitle */
-export interface SetNavigationBarTitleOptions {
-  title: string;
-}
-
-/** Options for setting TabBar badge */
-export interface SetTabBarBadgeOptions {
-  index: number;
-  text: string;
-}
-
-/** Options for setting TabBar item */
-export interface SetTabBarItemOptions {
-  index: number;
-  text?: string;
-  iconPath?: string;
-  selectedIconPath?: string;
-}
-
-/** Options for setting TabBar style */
-export interface SetTabBarStyleOptions {
-  color?: string;
-  selectedColor?: string;
-  backgroundColor?: string;
-  borderStyle?: string;
-}
-
 /** System setting status */
 export interface SystemSettingInfo {
   bluetoothEnabled: boolean;
@@ -1814,19 +2266,6 @@ export declare class DirEntry {
   readonly isSymlink: boolean;
 }
 
-export declare class FileManager {
-  private constructor();
-  exists(options: ExistsOptions): Promise<boolean>;
-  stat(options: StatOptions): Promise<FileStats>;
-  readDir(options: ReadDirOptions): Promise<AsyncIterableIterator<DirEntry>>;
-  mkdir(options: MkdirOptions): Promise<void>;
-  readFile(options: never): Promise<never>;
-  writeFile(options: WriteFileOptions): Promise<void>;
-  copyFile(options: CopyFileOptions): Promise<void>;
-  rename(options: RenameOptions): Promise<void>;
-  remove(options: RemoveOptions): Promise<void>;
-}
-
 export declare class JSMessagePort {
   constructor();
   static postMessage(payload: any): void;
@@ -1845,8 +2284,10 @@ export declare class JSUpdateManager {
   constructor();
   /** Apply update by restarting the app */
   applyUpdate(): void;
-  onUpdateReady(cb: (...args: any[]) => any): void;
-  onUpdateFailed(cb: (...args: any[]) => any): void;
+  /** Subscribes to a ready update and returns the unsubscribe fn. */
+  onUpdateReady(cb: (...args: any[]) => any): (...args: any[]) => any;
+  /** Subscribes to a failed update and returns the unsubscribe fn. */
+  onUpdateFailed(cb: (...args: any[]) => any): (...args: any[]) => any;
 }
 
 export declare class JSVideoContext {
@@ -1860,6 +2301,67 @@ export declare class JSVideoContext {
   setStreamSource(options: StreamSourceOptions): void;
 }
 
+export declare class LxFile {
+  private constructor();
+  /** The path supplied to `lx.fs.file`. */
+  readonly path: string;
+  /** Read the complete file as strict UTF-8 text. */
+  text(): Promise<string>;
+  /**
+   * Read and parse the complete file as JSON. Stays `unknown`: a class
+   * method cannot carry a type parameter through the binding, so unlike
+   * `lx.getStorage().get<T>()` the assertion is spelled `as` at the call
+   * site rather than passed in.
+   */
+  json(): Promise<unknown>;
+  /** Read the complete file as a Base64 string. */
+  base64(): Promise<string>;
+  /** Read the complete file as bytes. */
+  bytes(): Promise<Uint8Array>;
+  /** Read the complete file as an ArrayBuffer. */
+  arrayBuffer(): Promise<ArrayBuffer>;
+  /** Test whether this managed path currently exists. */
+  exists(): Promise<boolean>;
+  /** Read metadata for this managed path. */
+  stat(): Promise<FileStats>;
+}
+
+declare global {
+  interface AppearanceApi {
+    /** Read the appearance preference and the light/dark value it resolves to. */
+    get(): AppearanceState;
+    /** Set the appearance preference to `auto`, `light`, or `dark`. */
+    set(preference: AppearancePreference): Promise<void>;
+  }
+}
+
+declare global {
+  interface FileSystemApi {
+    /**
+     * Create a lazy reference to a LingXia-managed path.
+     * Relative paths resolve under `lx.env.USER_DATA_PATH`. Creating a reference
+     * does not require the path to exist.
+     */
+    file(path: string): LxFile;
+    /** Test whether a managed path currently exists. */
+    exists(path: string): Promise<boolean>;
+    /** Read metadata for a managed path. */
+    stat(path: string): Promise<FileStats>;
+    /** The direct children of a managed directory. */
+    readDir(path: string): Promise<DirEntry[]>;
+    /** Create a managed directory. */
+    mkdir(path: string, options?: FsMkdirOptions): Promise<void>;
+    /** Write UTF-8 text or bytes to a managed file. */
+    write(path: string, data: string, options?: FsWriteOptions): Promise<void>;
+    /** Copy a managed file. */
+    copy(source: string, destination: string, options?: FsCopyOptions): Promise<void>;
+    /** Rename or move a managed file or directory. */
+    rename(source: string, destination: string, options?: FsRenameOptions): Promise<void>;
+    /** Remove a managed file or directory. */
+    remove(path: string, options?: FsRemoveOptions): Promise<void>;
+  }
+}
+
 declare global {
   interface HostAppApi {
     /**
@@ -1880,7 +2382,19 @@ declare global {
      */
     checkUpdate(): Promise<HostAppUpdateCheckResult>;
     readonly envVersion: HostAppEnvVersion;
+    /**
+     * Read the host app's identity: locale, display language, OS, product name,
+     * product version, and SDK runtime version.
+     */
     getBaseInfo(): AppBaseInfo;
+    /**
+     * Follow the host's effective display language.
+     * `getBaseInfo().displayLanguage` answers what it is now; this answers when it
+     * changes. Logic needs both because the strings it hands to native chrome —
+     * navigation bar titles, tab bar labels, modal and action-sheet text — are the
+     * app's own, and nothing re-renders them on its behalf.
+     */
+    onDisplayLanguageChange(callback: (language: string) => void): () => void;
     /**
      * Exit the host app immediately without a confirmation dialog.
      * If the user should confirm first, call `lx.showModal(...)` and invoke this
@@ -1900,14 +2414,31 @@ declare global {
 declare global {
   interface Lx {
     readonly app: HostAppApi;
+    /**
+     * Whether this host exposes a capability to this Logic context, right now.
+     * Synchronous, because it is meant to be called from render paths. The answer
+     * is live and may be stale by the time you act on it — it is an affordance for
+     * deciding what to render, not a replacement for handling a rejection.
+     * `{ capability: 'surface', value: 'aside' }` in particular changes when a
+     * desktop window crosses the compact breakpoint; pair it with
+     * `lx.surface.onContext` instead of polling. The answer is per runtime context:
+     * a context that does not expose an API reports false for it.
+     */
+    supports(query: LxCapabilityQuery): boolean;
+    /** Vibrate briefly, where the device has a vibrator. */
     vibrateShort(): boolean;
+    /** Vibrate for a longer pulse, where the device has a vibrator. */
     vibrateLong(): boolean;
+    /** Hand a number to the system dialer; the user still places the call. */
     makePhoneCall(options: MakePhoneCallOptions): boolean;
+    /** Read the device and OS facts this host reports. */
     getDeviceInfo(): DeviceInfo;
+    /** Read the screen geometry and pixel ratio this host reports. */
     getScreenInfo(): ScreenInfo;
+    /** Read connectivity right now: whether it is connected, its type, and addresses. */
     getNetworkInfo(): Promise<NetworkInfo>;
-    onNetworkChange(callback: NetworkChangeCallback): void;
-    offNetworkChange(callback?: NetworkChangeCallback): void;
+    /** Subscribes to network changes and returns the unsubscribe fn. */
+    onNetworkChange(callback: NetworkChangeCallback): () => void;
     /** Initialize WiFi module */
     startWifi(): Promise<void>;
     /** Stop WiFi module */
@@ -1922,13 +2453,27 @@ declare global {
     getWifiList(): Promise<WifiInfo[]>;
     /** Get connected WiFi info */
     getConnectedWifi(): Promise<WifiInfo>;
-    onWifiConnected(callback: WifiConnectedCallback): void;
-    offWifiConnected(callback?: WifiConnectedCallback): void;
+    /** Subscribes to WiFi connection events and returns the unsubscribe fn. */
+    onWifiConnected(callback: WifiConnectedCallback): () => void;
+    /**
+     * Lock this lxapp to `portrait` or `landscape`.
+     * Any other value rejects. Where the host does not report the change back,
+     * the runtime emits the orientation event itself so JS state stays in sync.
+     */
     setDeviceOrientation(orientation: DeviceOrientation): boolean;
-    onDeviceOrientationChange(callback: (event: DeviceOrientationChangeEvent) => void): void;
-    offDeviceOrientationChange(callback?: (event: DeviceOrientationChangeEvent) => void): void;
+    /** Subscribes to orientation changes and returns the unsubscribe fn. */
+    onDeviceOrientationChange(callback: (event: DeviceOrientationChangeEvent) => void): () => void;
     readonly env: LxEnv;
     downloadFile(options: never): never;
+    /**
+     * Upload a file over HTTP, streamed from disk.
+     * Defaults to a `POST` with a `multipart/form-data` body. Set
+     * `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.
+     */
     uploadFile(options: UploadOptions): UploadTask;
     /**
      * Open a local file with the requested strategy.
@@ -1936,19 +2481,41 @@ declare global {
      * `mode: "auto"`.
      */
     openFile(options: OpenFileOptions): Promise<void>;
+    /**
+     * Opens a file picker.
+     * Resolves `{ canceled: true }` only when the user dismisses the picker. A
+     * completed selection resolves `{ canceled: false, paths }` with at least one
+     * path. Rejects when the picker fails or returns an invalid payload.
+     */
     chooseFile(options?: ChooseFileOptions): Promise<ChooseFileResult>;
+    /**
+     * Opens a directory picker.
+     * Resolves `{ canceled: true }` only when the user dismisses the picker. A
+     * completed selection resolves `{ canceled: false, path }`. Rejects when the
+     * picker fails or returns an invalid payload.
+     */
     chooseDirectory(options?: ChooseDirectoryOptions): Promise<ChooseDirectoryResult>;
-    getFileManager(): FileManager;
-    onKeyDown(callback: KeyEventCallback): void;
-    offKeyDown(callback?: KeyEventCallback): void;
-    onKeyUp(callback: KeyEventCallback): void;
-    offKeyUp(callback?: KeyEventCallback): void;
+    readonly fs: FileSystemApi;
+    /** Subscribes to key-down events and returns the unsubscribe fn. */
+    onKeyDown(callback: KeyEventCallback): () => void;
+    /** Subscribes to key-up events and returns the unsubscribe fn. */
+    onKeyUp(callback: KeyEventCallback): () => void;
     /** Get location function */
     getLocation(options?: GetLocationOptions): Promise<LocationInfo>;
+    /** Identify the running lxapp: its id, display name, version, and release type. */
     getLxAppInfo(): LxAppInfo;
+    /** Read an image's dimensions, type, and orientation without decoding it into a view. */
     getImageInfo(options: GetImageInfoOptions): Promise<ImageInfo>;
+    /** Re-encode an image at a lower quality or size, writing a new managed file. */
     compressImage(options: CompressImageOptions): Promise<CompressImageResult>;
-    chooseMedia(options?: ChooseMediaOptions): Promise<ChosenMediaEntry[]>;
+    /**
+     * Opens the media picker or camera.
+     * Resolves `{ canceled: true }` only when the user dismisses the picker. A
+     * completed selection resolves `{ canceled: false, entries }` with at least one
+     * entry. Rejects when capture or selection fails, or the host returns an invalid
+     * payload.
+     */
+    chooseMedia(options?: ChooseMediaOptions): Promise<ChooseMediaResult>;
     /**
      * Synchronously returns a JS handle so listeners can be attached before the
      * first event fires:
@@ -1967,9 +2534,18 @@ declare global {
      * caller never re-indexes their own array.
      */
     previewMedia(options: PreviewMediaOptions): PreviewMediaHandle;
+    /** Save an image into the system photo library. */
     saveImageToPhotosAlbum(options: SaveMediaOptions): Promise<void>;
+    /** Save a video into the system photo library. */
     saveVideoToPhotosAlbum(options: SaveMediaOptions): Promise<void>;
+    /**
+     * Opens the scanner.
+     * Resolves `{ canceled: true }` only when the user dismisses the scanner. A
+     * completed scan resolves `{ canceled: false, scanResult, scanType }`. Rejects
+     * when scanning fails or the host returns an invalid payload.
+     */
     scanCode(options?: ScanCodeOptions): Promise<ScanCodeResult>;
+    /** Take a control handle for the `<lx-video>` component with this id. */
     createVideoContext(componentId: string): VideoContext;
     /**
      * Reads local video metadata for upload preflight and presentation.
@@ -1979,47 +2555,63 @@ declare global {
      * still validate the uploaded bytes.
      */
     getVideoInfo(options: GetVideoInfoOptions): Promise<VideoInfo>;
+    /** Write one frame of a video out as an image file. */
     extractVideoThumbnail(options: ExtractVideoThumbnailOptions): Promise<ExtractVideoThumbnailResult>;
+    /**
+     * Transcode a video to a smaller file.
+     * Returns a task handle synchronously, so progress and cancellation can be
+     * wired up before transcoding starts.
+     */
     compressVideo(options: CompressVideoOptions): CompressVideoTask;
-    navigateToLxApp(options: NavigateToLxAppOptions): Promise<void>;
-    navigateBackLxApp(): Promise<void>;
+    /**
+     * Open another lxapp, optionally at one of its pages.
+     * Navigating to the lxapp already running is a no-op. Rejects with
+     * `E_SURFACE_CONFLICT` when the target is currently docked as an aside —
+     * close that aside before opening it as a main.
+     */
+    navigateToApp(options: NavigateToAppOptions): Promise<void>;
+    /** Leave this lxapp and reveal the one that opened it. */
+    navigateBackApp(): Promise<void>;
+    /**
+     * Hand content to the system share sheet.
+     * Share text, files, or a page link — files cannot be combined with a page
+     * target or with text; share those separately.
+     */
     share(options: ShareOptions): Promise<ShareResult>;
-    getStorage(): Storage;
     /**
-     * `lx.openSurface(spec)` — unified surface entry point. The spec is a
-     * discriminated union keyed by exactly one of `page`, `surface`, or `url`:
-     * - `{ page, as, position?, size?, query? }` opens one of this lxapp's own
-     * pages as a `float` (overlay popup) or a `window` (bare standalone desktop
-     * window). Pages cannot be docked as an `aside` — an aside shows external
-     * content only.
-     * - `{ surface, edge?, query? }` shows a host-declared surface by its `ui` id.
-     * - `{ url }` opens an authorized HTTPS/file URL in the in-app chromed browser.
+     * Open this lxapp's asynchronous persistent key-value store. `get` asserts the
+     * value shape at the call site and resolves `undefined` for a missing key. Use
+     * `lx.fs` instead for path-based data.
      */
-    openSurface(spec: never): Promise<never>;
+    getStorage(): Storage;
     /** `lx.openExternal(url)` — hand the url off to the OS default browser. */
     openExternal(url: string): void;
+    readonly surface: SurfaceApi;
+    /** Read system switches the lxapp may branch on, such as location and WiFi. */
+    getSystemSetting(): SystemSettingInfo;
     /**
-     * `lx.onSurfaceContext(handler)` — register a JS callback (scoped to this
-     * lxapp's JS context), invoke it immediately, then again whenever that
-     * presentation's actual viewport changes. Returns an unsubscribe fn.
+     * Shows a list of actions.
+     * Resolves `{ canceled: false, index }` when the user selects an item; `index`
+     * points into `options.itemList`. Resolves `{ canceled: true }` only when the
+     * user dismisses the sheet. Rejects when presentation fails or the host returns
+     * an invalid selection.
      */
-    onSurfaceContext(handler: (context: SurfaceContext) => void): () => void;
-    getSystemSetting(): SystemSettingInfo;
-    /** Show action sheet function for JavaScript */
     showActionSheet(options: ShowActionSheetOptions): Promise<ActionSheetResult>;
+    readonly appearance: AppearanceApi;
     /**
-     * Get capsule button bounding client rect (async)
-     * Returns Promise<{width, height, top, right, bottom, left}>
+     * Shows a confirmation modal.
+     * Resolves `{ canceled: false }` when the user confirms and `{ canceled: true }`
+     * only when the user dismisses or cancels the modal. Rejects when presentation
+     * fails or the host returns an invalid payload.
      */
-    getCapsuleRect(): Promise<CapsuleRect>;
-    /** Show modal function (async) */
     showModal(options: ShowModalOptions): Promise<ModalResult>;
-    /** Set navigation bar title */
-    setNavigationBarTitle(options: SetNavigationBarTitleOptions): boolean;
-    /** Set navigation bar color */
-    setNavigationBarColor(options: SetNavigationBarColorOptions): boolean;
-    /** Hide home button */
-    hideHomeButton(): boolean;
+    /**
+     * Replace the current lxapp's complete app-declared More action list (seven
+     * entries maximum). Pass an empty array to clear it. Native hosts append these
+     * entries after their own lifecycle actions.
+     */
+    setMoreActions(items: MoreAction[]): void;
+    readonly navigationBar: NavigationBarApi;
     /**
      * lx.startPullDownRefresh()
      * Programmatically start the pull-to-refresh animation.
@@ -2032,38 +2624,47 @@ declare global {
      * This should be called after the refresh operation is complete.
      */
     stopPullDownRefresh(): void;
-    /** Navigate to a new page (forward navigation) */
+    /**
+     * Push a configured page onto the stack.
+     * A route can appear on the stack only once. The promise rejects with
+     * `data.reason === "duplicate_route"` when the target is already present,
+     * or `data.reason === "stack_full"` when the ten-page limit is reached.
+     */
     navigateTo(options: NavigateToOptions): Promise<PageMessagePort>;
-    /** Navigate back to previous page */
-    navigateBack(options: NavigateBackOptions): void;
-    /** Redirect to a new page (replace current page) */
+    /**
+     * Pop one or more pages and reveal the destination page.
+     * `options` and `options.delta` are optional; both default to one page. The
+     * promise resolves once the destination WebView is ready, so callers can
+     * safely continue with work that targets the revealed page.
+     */
+    navigateBack(options?: NavigateBackOptions): Promise<void>;
+    /**
+     * Replace the current stack entry with a configured page.
+     * Redirecting to the current route keeps its page instance and runs `onLoad`
+     * again with the new query. Redirecting to a route lower in the stack rejects
+     * with `data.reason === "duplicate_route"`.
+     */
     redirectTo(options: RedirectToOptions): Promise<void>;
-    /** Switch to a tab page */
+    /**
+     * Switch to a configured tab page.
+     * The tab page being left is hidden and retained. Non-tab pages pushed above
+     * a tab leave the stack and receive `onUnload`.
+     */
     switchTab(options: SwitchTabOptions): Promise<void>;
-    /** Relaunch to a new page (clear page stack) */
+    /** Clear the page stack and launch a configured page as the new root. */
     reLaunch(options: ReLaunchOptions): Promise<void>;
     readonly shell: ShellApi;
-    /** Show TabBar red dot */
-    showTabBarRedDot(options: TabBarRedDotOptions): boolean;
-    /** Hide TabBar red dot */
-    hideTabBarRedDot(options: TabBarRedDotOptions): boolean;
-    /** Set TabBar badge */
-    setTabBarBadge(options: SetTabBarBadgeOptions): boolean;
-    /** Remove TabBar badge */
-    removeTabBarBadge(options: RemoveTabBarBadgeOptions): boolean;
-    /** Show TabBar */
-    showTabBar(): Promise<boolean>;
-    /** Hide TabBar */
-    hideTabBar(): Promise<boolean>;
-    /** Set TabBar style */
-    setTabBarStyle(options: SetTabBarStyleOptions): boolean;
-    /** Set TabBar item */
-    setTabBarItem(options: SetTabBarItemOptions): boolean;
+    readonly tabBar: TabBarApi;
     /** Show toast function */
     showToast(options: ShowToastOptions): Promise<void>;
     /** Hide toast function */
     hideToast(): Promise<void>;
     readonly tray: TrayApi;
+    /**
+     * Return the callback-based update manager for this lxapp's bundle. This is
+     * available to every lxapp and is distinct from the home-only
+     * `lx.app.checkUpdate()`, which updates the native host app.
+     */
     getUpdateManager(): UpdateManager;
   }
 }
@@ -2076,22 +2677,111 @@ declare global {
 }
 
 declare global {
-  interface ShellActivatorsApi {
+  interface NavigationBarApi {
+    /** Patch the navigation bar of the active page; unset fields stay as they are. */
+    update(patch: NavigationBarPatch): Promise<void>;
+  }
+}
+
+declare global {
+  interface ShellApi {
+    /**
+     * `lx.shell.openApp(appId, options)` — compose another lxapp into a shell
+     * slot. Home-lxapp only; the namespace is the privilege.
+     */
+    openApp(appId: string, options: ShellOpenAppOptions): Promise<AppSurface>;
+    /** `lx.shell.openBuiltin(page)` — a host builtin page. Home-lxapp only. */
+    openBuiltin(page: BuiltinShellPage): Promise<BuiltinSurface>;
     /**
-     * Atomically replaces the complete desktop activator declaration. Home lxapp
-     * only. Relative icons resolve from the home app bundle. Every entry is bound
-     * to its generation-scoped callback; `replace([])` explicitly clears chrome.
+     * `lx.shell.openDeclared(id, options?)` — the declared surface, plus the
+     * keyed multi-instance form and placement overrides. Home-lxapp only.
+     */
+    openDeclared(id: string, options?: ShellOpenDeclaredOptions): Promise<DeclaredSurface>;
+    /** `lx.shell.reconfigure(id, patch)` — re-place a live declared surface. */
+    reconfigure(id: string, patch: ShellSurfacePatch): Promise<void>;
+  }
+}
+
+declare global {
+  interface ShellSidebarActionsApi {
+    /**
+     * Atomically replaces the complete desktop sidebar action declaration. Only the
+     * home lxapp may call this API. Ids must be non-empty and unique across both
+     * placements; header accepts at most two entries. Icons must be bundled relative
+     * paths or runtime-managed `lx://` paths accessible to the home lxapp.
+     * Every entry is bound to its generation-scoped callback. The shell invokes that
+     * callback but never infers navigation or selected state. Validation or host
+     * projection failure leaves the previous generation active. `replace([])` clears
+     * the chrome explicitly. Declarations are process-local, so call `replace` again
+     * on every Logic launch.
+     */
+    replace(items: ShellSidebarAction[]): void;
+    /**
+     * Atomically updates the icon, label, and/or disabled state of one stable id.
+     * Only the home lxapp may call this API. The patch must be non-empty; unknown
+     * fields are rejected. The callback and placement stay unchanged. Throws
+     * `E_NOT_FOUND` when `id` is not in the current declaration.
+     */
+    update(id: string, patch: ShellSidebarActionUpdate): void;
+    /**
+     * Atomically removes one stable id and its generation-scoped callback. Only the
+     * home lxapp may call this API. Throws `E_NOT_FOUND` when `id` is not in the
+     * current declaration.
      */
-    replace(items: ShellActivator[]): void;
-    /** Updates presentation fields for one stable id. Home lxapp only. */
-    update(id: string, patch: ShellActivatorUpdate): void;
-    /** Removes one stable id from the declaration. Home lxapp only. */
     remove(id: string): void;
-    /** Clears the current runtime declaration. Home lxapp only. */
+    /**
+     * Atomically clears every runtime sidebar action and callback. Only the home
+     * lxapp may call this API. Equivalent to `replace([])` and safe when already
+     * empty; the home lxapp must still redeclare actions after the next Logic launch.
+     */
     clear(): void;
   }
 }
 
+declare global {
+  interface SurfaceApi {
+    /**
+     * `lx.surface.openPage(page, options?)` — one of this lxapp's own pages as a
+     * float or a window. A page can never be an aside: asides carry external
+     * content only, which is why that member does not exist on this signature.
+     */
+    openPage(page: string, options?: OpenPageOptions): Promise<PageSurface>;
+    /**
+     * `lx.surface.openUrl(url, options?)` — external content in the in-app
+     * browser, as a tab or docked as an aside.
+     */
+    openUrl(url: string, options?: OpenUrlOptions): Promise<TabSurface>;
+    /**
+     * `lx.surface.openDeclared(id, options?)` — a surface the host declared in
+     * `lingxia.yaml`, opened with the declaration's own presentation.
+     */
+    openDeclared(id: string): Promise<DeclaredSurface>;
+    /**
+     * `lx.surface.get(keyOrId)` — the live handle for a surface this lxapp opened
+     * **with a `key`**, so no caller has to cache one in order to reuse or close
+     * it. An unkeyed surface is not addressable: nothing registers it, because
+     * holding one for the session costs its closures and its message port and
+     * nobody can look up a uuid they never chose.
+     * A `key` you chose wins over a runtime-assigned `id`, so a key that happens
+     * to spell another surface's id still finds yours.
+     */
+    get(keyOrId: string): AnySurface | undefined;
+    /**
+     * `lx.surface.onContext(handler)` — register a JS callback (scoped to this
+     * lxapp's JS context), invoke it immediately, then again whenever that
+     * presentation's actual viewport changes. Returns an unsubscribe fn.
+     */
+    onContext(handler: (context: SurfaceContext) => void): () => void;
+  }
+}
+
+declare global {
+  interface TabBarApi {
+    /** Patch this lxapp's tab bar; unset fields stay as they are. */
+    update(patch: TabBarPatch): Promise<void>;
+  }
+}
+
 declare global {
   interface TrayApi {
     /** lx.tray.setBadge(value) — the menu-bar / system-tray badge. Null/empty clears it. */