@lingxia/types 0.14.0 → 0.16.0

package/dist/generated/logic.d.ts

@@ -8,8 +8,46 @@ export interface PageConfig<TData extends Record<string, unknown> = Record<strin
     onHide?: () => void | Promise<void>;
     onUnload?: () => void | Promise<void>;
     onPullDownRefresh?: () => void | Promise<void>;
-    [key: string]: unknown;
 }
+/** Lifecycle hook names a `Page({...})` config may declare. */
+export type PageLifecycleName = Exclude<keyof PageConfig, 'data'>;
+/** Lifecycle hook names an `App({...})` config may declare. */
+export type AppLifecycleName = Exclude<keyof AppConfig, 'globalData'>;
+/**
+ * What a key that differs from a lifecycle hook only in case resolves to, so
+ * the compiler names the mistake instead of silently accepting a new method.
+ */
+export type MisspelledLifecycle<K extends string> = {
+    'LingXia type error': `'${K}' differs only in case from a lifecycle hook`;
+};
+/**
+ * Applied to the custom half of a `Page`/`App` config. `onload` and `onShow`
+ * are one keystroke apart from real hooks and the runtime would simply never
+ * call the misspelling, so the closest case-insensitive match is rejected.
+ * Genuinely different names stay ordinary methods.
+ */
+export type NoLifecycleTypos<TCustom, TNames extends string> = {
+    [K in keyof TCustom]: K extends TNames ? TCustom[K] : Lowercase<K & string> extends Lowercase<TNames> ? MisspelledLifecycle<K & string> : TCustom[K];
+};
+/**
+ * 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.
+ */
+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;
     route: string;
@@ -22,7 +60,7 @@ export interface PageInstance<TData extends Record<string, unknown> = Record<str
      * Available when this page was opened by `lx.navigateTo(...)`.
      */
     opener?: PageMessagePort;
-    setData(data: Partial<TData> | Record<string, unknown>, callback?: () => void): void;
+    setData(data: SetDataPatch<TData>, callback?: () => void): void;
 }
 /**
  * Injected by the runtime into methods listed in `stream_handlers` page metadata.
@@ -62,8 +100,8 @@ export interface ChannelHandle<TSend = unknown, TReceive = unknown> {
  *
  * - `app`: app-owned temporary output, or durable `lx://userdata` output when
  *   `filePath` is set
- * - `downloads`: user-visible system Downloads output, requiring
- *   `security.privileges: ["downloads"]` in `lxapp.json`
+ * - `downloads`: user-visible system Downloads output, requiring a host
+ *   privilege grant and a native Downloads grant
  *
  * Default: `app`.
  */
@@ -95,18 +133,46 @@ export interface DownloadTask<TDownloadResult extends DownloadResult = DownloadR
     wait(): Promise<TDownloadResult>;
 }
 declare global {
+    /**
+     * The lxapp's configured page names, one key per page.
+     *
+     * Empty here on purpose. `lingxia dev` / `lingxia build` generates the
+     * project's own names into this interface; until then `ConfiguredPageName`
+     * stays `string` and every navigation call compiles exactly as before.
+     */
+    interface LxAppPages {
+    }
     interface HostAppApi {
         /**
-         * The build environment from `app.json::envVersion`. It is fixed at boot
-         * and defaults to `release` for older artifacts.
+         * The host deployment environment from `app.json::env` (`dev` | `prod`).
+         * It is fixed at boot and defaults to `prod` for older artifacts.
+         * Not the lxapp publish channel (`release` | `preview` | `draft`).
          */
-        readonly envVersion: HostAppEnvVersion;
+        readonly env: HostAppEnv;
         /**
          * Launch-at-startup control. Absent where the host cannot register a
          * startup item; its presence and `lx.supports({ capability: 'autostart' })` always
          * agree, so `lx.app.autostart?.…` and the query are interchangeable.
          */
         autostart?: AutostartApi;
+        /** The language this lxapp renders in. Every lxapp follows it. */
+        readonly displayLanguage: DisplayLanguageApi;
+        /** The light/dark scheme this lxapp renders in. */
+        readonly appearance: AppearanceApi;
+        /**
+         * Product-wide settings, and their single writer. Present only in the
+         * Control app the host sealed at build time; its presence and
+         * `lx.supports({ capability: 'control' })` always agree, so
+         * `lx.app.control?.…` and the query are interchangeable.
+         */
+        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.
+         */
+        cache?: AppCacheApi;
     }
     /** Runtime environment constants backed by abstract `lx://` paths. */
     interface LxEnv {
@@ -156,6 +222,7 @@ type StorageEntry<S extends object> = {
 export type TypedStorage<S extends object> = {
     get<K extends StorageKey<S>>(key: K): Promise<S[K] | undefined>;
     set(...entry: StorageEntry<S>): Promise<void>;
+    has(key: StorageKey<S>): Promise<boolean>;
     delete(key: StorageKey<S>): Promise<void>;
     clear(): Promise<void>;
     list(prefix?: string): Promise<string[]>;
@@ -172,13 +239,36 @@ export type ActionSheetResult = {
 } | CanceledResult;
 /** Every surface handle, narrowable by `kind`. */
 export type AnySurface = PageSurface | DeclaredSurface | AppSurface | TabSurface | BuiltinSurface;
+/**
+ * The product-wide cache a settings screen reports and clears.
+ * App-scoped, not lxapp-scoped: the figure covers every lxapp the host
+ * has run. Injected only into the Control app, same gate as
+ * `lx.app.control` — guests do not have the member.
+ */
+export type AppCacheApi = {
+    /** Estimated reclaimable managed bytes; excludes live session storage and WebView cache. */
+    size(): Promise<number>;
+    /**
+     * Clear reclaimable host caches. Control app only. Live session usercache and
+     * temp are preserved, including the caller's. Does not restart any lxapp.
+     * Userdata, KV, Downloads, cookies, valid installs and host components survive.
+     * Per-category failures are reported; setup/worker failures reject the call.
+     */
+    clear(): Promise<{
+        /** Estimated file bytes successfully removed; excludes WebView cache. */
+        freedBytes: number;
+        /** Protected usercache/session paths skipped, not a count of apps. */
+        skippedActivePaths: number;
+        webview: 'cleared' | 'unsupported' | 'failed';
+        failures: string[];
+    }>;
+};
 export type AppConfig = {
     globalData?: Record<string, unknown>;
     onLaunch?: (options?: AppLaunchOptions) => void | Promise<void>;
     onShow?: (args?: AppLifecycleEventArgs) => void | Promise<void>;
     onHide?: (args?: AppLifecycleEventArgs) => void | Promise<void>;
     onUserCaptureScreen?: () => void | Promise<void>;
-    [key: string]: unknown;
 };
 /** Runtime-managed app download path, usually under `lx://userdata`. */
 export type AppDownloadFilePath = string & {
@@ -224,15 +314,32 @@ export type AppInstance = AppConfig & {
 export type AppLaunchOptions = {
     path?: string;
     query?: Record<string, string>;
-    scene?: number;
+    /** `8003` = AppLink (cold: onLaunch; warm: onShow). */
+    scene?: AppLaunchScene;
+    /**
+     * Inbound link exactly as the OS delivered it, fragment included. Present
+     * only with `scene: 8003`. Untrusted: route from an allowlist of paths.
+     */
+    url?: string;
     referrerInfo?: {
         appId?: string;
         extraData?: Record<string, unknown>;
     };
 };
+/**
+ * Launch scene. `8003` is AppLink (cold: `onLaunch`; warm: `onShow`).
+ * Other numeric scenes stay valid; completion offers `8003`.
+ */
+export type AppLaunchScene = 8003 | (number & {});
 export type AppLifecycleEventArgs = {
     source: 'host' | 'lxapp';
     reason: 'foreground' | 'background' | 'screenshot' | 'open' | 'close' | 'switch_back' | 'switch_away';
+    path?: string;
+    query?: Record<string, string>;
+    /** `8003` = AppLink. */
+    scene?: AppLaunchScene;
+    /** Inbound link, present only with `scene: 8003`. */
+    url?: string;
 };
 export type AppScreenshotOptions = {
     /**
@@ -254,7 +361,25 @@ export type AppSurface = SurfaceBase & SurfaceShowable & {
     readonly kind: 'app';
     readonly realized: 'main' | 'aside';
 };
-export type AppearanceApi = globalThis.AppearanceApi;
+/** `lx.app.appearance` — the scheme this lxapp renders in. */
+export type AppearanceApi = {
+    /**
+     * The scheme this lxapp is rendering in. An lxapp that pinned one in its
+     * `lxapp.json` reports that; every other lxapp reports the product's.
+     */
+    get(): ResolvedAppearance;
+    /**
+     * Follow it, starting with the current value. Returns an unsubscribe.
+     *
+     * The first callback runs synchronously, before `watch` returns, so the
+     * unsubscribe is not yet bound inside it.
+     */
+    watch(callback: (resolved: ResolvedAppearance) => void): () => void;
+};
+/**
+ * What the product's light/dark scheme is set to. `'auto'` follows
+ * the system.
+ */
 export type AppearancePreference = 'auto' | 'light' | 'dark';
 /**
  * Launch-at-startup control for the host app.
@@ -272,8 +397,8 @@ export type AppearancePreference = 'auto' | 'light' | 'dark';
  * is called, so the decision stays with the user (typically a settings-page
  * toggle, default off).
  * Host-app-level capability: like `checkUpdate` and `screenshot`, the methods
- * are available only to the home lxapp; other lxapps receive a permission
- * error.
+ * are available only to the native-assigned Control app; other lxapps receive
+ * a permission error.
  */
 export type AutostartApi = {
     /**
@@ -294,11 +419,11 @@ export type AutostartApi = {
 export type BinaryFileData = ArrayBuffer | ArrayBufferView;
 /**
  * Built-in browser product page. Opening one requires
- * `capabilities.browser` and is restricted to the home lxapp.
+ * `capabilities.browser` and is restricted to the native-assigned Control app.
  */
-export type BuiltinShellPage = 'settings' | 'downloads';
+export type BuiltinShellPage = 'downloads';
 /**
- * A host builtin page such as settings or downloads. The shell owns
+ * 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`.
@@ -452,10 +577,68 @@ export type CompressVideoTask = PromiseLike<CompressVideoResult> & AsyncIterable
     cancel(): void;
     wait(): Promise<CompressVideoResult>;
 };
+/**
+ * Configured page name from `lxapp.json` / `lingxia.yaml`. JavaScript
+ * navigation accepts only this name; full routes such as
+ * `/pages/home/index` are internal runtime details. Discover names
+ * with `lxdev lxapp pages`.
+ * Narrows to the project's own names once `lingxia dev` or
+ * `lingxia build` has generated them; plain `string` before that, so
+ * a project that never ran a build still compiles.
+ */
+export type ConfiguredPageName = keyof LxAppPages extends never ? string : keyof LxAppPages;
 export type ConnectWifiOptions = {
     SSID: string;
     password?: string;
 };
+/**
+ * `lx.app.control` — product-wide settings, and their single writer.
+ * Present only in the Control app. Bind it once rather than repeating
+ * `lx.app.control!`:
+ * ```js
+ * const control = lx.app.control;
+ * if (!control) return; // not the Control app
+ * await control.appearance.setPreference('dark');
+ * ```
+ */
+export type ControlApi = {
+    readonly displayLanguage: ControlDisplayLanguageApi;
+    readonly appearance: ControlAppearanceApi;
+};
+/** `lx.app.control.appearance` — the product's own light/dark setting. */
+export type ControlAppearanceApi = {
+    /** What the user chose for the whole product. */
+    getPreference(): AppearancePreference;
+    /**
+     * Pin the product to `'light'` or `'dark'`, or follow the system with
+     * `'auto'`. An lxapp that pinned a scheme in its manifest keeps it.
+     */
+    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
+     * current value; that first callback runs synchronously, before
+     * `watchPreference` returns.
+     */
+    watchPreference(callback: (preference: AppearancePreference) => void): () => void;
+};
+/**
+ * `lx.app.control.displayLanguage` — the preference behind that
+ * language, for the one surface that edits it.
+ */
+export type ControlDisplayLanguageApi = {
+    /** What the user chose: `'auto'`, or a canonical BCP-47 tag. */
+    getPreference(): DisplayLanguagePreference;
+    /** Persist the product's language. Rejects a tag that is not valid BCP-47. */
+    setPreference(preference: DisplayLanguagePreference): Promise<void>;
+    /**
+     * Follow the choice, not what it resolves to: a system locale change under
+     * `'auto'` moves the language without moving the preference. Starts with
+     * the current value and returns an unsubscribe; that first callback runs
+     * synchronously, before `watchPreference` returns.
+     */
+    watchPreference(callback: (preference: DisplayLanguagePreference) => void): () => void;
+};
 /** A surface declared by the host in `lingxia.yaml`. */
 export type DeclaredSurface = SurfaceBase & SurfaceShowable & {
     readonly kind: 'declared';
@@ -465,6 +648,33 @@ export type DeviceOrientation = "portrait" | "landscape";
 export type DeviceOrientationChangeEvent = {
     value: DeviceOrientation;
 };
+/** `lx.app.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
+     * the catalogs this lxapp actually ships and fall back where it has none;
+     * that narrowing is yours, and is not a language setting of its own.
+     */
+    get(): string;
+    /**
+     * Follow the language, starting with the current value. Returns an
+     * unsubscribe.
+     *
+     * Logic needs this 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.
+     *
+     * The first callback runs synchronously, before `watch` returns, so the
+     * unsubscribe is not yet bound inside it.
+     */
+    watch(callback: (language: string) => void): () => void;
+};
+/**
+ * What the product's language is set to: `'auto'` follows the system,
+ * or any canonical BCP-47 tag. `string & {}` keeps `'auto'` in
+ * autocomplete while still accepting a tag.
+ */
+export type DisplayLanguagePreference = 'auto' | (string & {});
 export type DownloadDestination = 'app' | 'downloads';
 export type DownloadOptionsBase = {
     /** HTTP(S) source URL. */
@@ -496,6 +706,12 @@ export type DownloadsDownloadResult = {
     mimeType?: string;
     size: number;
 };
+/**
+ * Configured page name belonging to *another* lxapp. This app's own
+ * page union cannot check it, so it stays a plain string and the
+ * target runtime rejects a name it does not have.
+ */
+export type ExternalPageName = string;
 export type ExtractVideoThumbnailOptions = {
     /**
      * Source video path or `lx://` URI.
@@ -592,15 +808,17 @@ export type GetVideoInfoOptions = {
 };
 export type HostAppApi = globalThis.HostAppApi;
 /**
- * Build-time environment version of the host app.
- * Surfaced via {@link HostAppApi.envVersion}. Mirrors the
- * `crates/lingxia-update::ReleaseType` enum and the `envVersion` field in the
- * generated `app.json`. Pre-envVersion app artifacts are treated as `'release'`.
- * Note: this is *separate* from `LxAppEnvVersion` in the navigator module,
- * which encodes lxapp release channels for cross-app navigation URLs —
- * same three names, different axis.
+ * Build-time deployment environment of the host app (`dev` | `prod`).
+ * Surfaced via {@link HostAppApi.env}. Taken from the `env` field in
+ * the generated `app.json`. Missing `env` is treated as `'prod'`.
+ * This is the host build axis: which server, package-id suffix, publish
+ * token, and self-update endpoint the host uses. It is **not** the
+ * lxapp publish channel (`LxAppEnvVersion` / `LxAppReleaseType`:
+ * `'release' | 'preview' | 'draft'`). Default channel is derived
+ * from env (`dev` → `draft`, `prod` → `release`) and can be
+ * overridden when opening an lxapp.
  */
-export type HostAppEnvVersion = 'developer' | 'preview' | 'release';
+export type HostAppEnv = 'dev' | 'prod';
 export type HostAppUpdateApplyStage = 'download' | 'install';
 export type HostAppUpdateCheckResult = {
     hasUpdate: false;
@@ -654,6 +872,11 @@ export type HostAppUpdateTask = PromiseLike<HostAppUpdateResult> & AsyncIterable
     finally(onfinally?: (() => void) | null): Promise<HostAppUpdateResult>;
     wait(): Promise<HostAppUpdateResult>;
 };
+/**
+ * Canonical platform-family label shared by `lx.app.getBaseInfo().os`
+ * and `lx.getDeviceInfo().osName`. `"unknown"` is a non-product build.
+ */
+export type HostOs = 'iOS' | 'macOS' | 'Android' | 'Windows' | 'Harmony' | 'unknown';
 export type InstalledTerminalFont = {
     family: string;
     monospace: boolean;
@@ -676,11 +899,11 @@ export type KeyEvent = {
     repeat?: boolean;
 };
 export type KeyEventCallback = (event: KeyEvent) => void;
-export type LxAppEnvVersion = 'release' | 'preview' | 'developer';
+export type LxAppEnvVersion = 'release' | 'preview' | 'draft';
 /** LxApp metadata APIs. */
-export type LxAppReleaseType = 'release' | 'preview' | 'developer';
+export type LxAppReleaseType = 'release' | 'preview' | 'draft';
 /** Boolean capability names accepted by `lx.supports`. */
-export type LxCapabilityFlag = 'terminal' | 'autostart' | 'notifications' | 'browser' | 'proxy' | 'selfUpdate' | 'process' | 'appUse' | 'computerUse' | 'browserUse' | 'mediaCapture';
+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`
@@ -753,9 +976,13 @@ export type NavigateToAppOptions = {
      * open the target app's initial page. Full routes such as
      * `/pages/home/index` are not supported.
      */
-    page?: string;
+    page?: ExternalPageName;
     query?: PageQuery;
-    envVersion?: LxAppEnvVersion;
+    /**
+     * Lxapp publish channel. Defaults from the host env
+     * (`dev` → `draft`, `prod` → `release`).
+     */
+    channel?: LxAppEnvVersion;
     targetVersion?: string;
 };
 export type NavigateToOptions = PageTargetOptions;
@@ -830,7 +1057,7 @@ export type OpenPageShared = {
      */
     size?: OverlaySurfaceSize;
     interaction?: SurfaceInteraction;
-    query?: Record<string, unknown>;
+    query?: PageQuery;
     /** Caller-owned identity, for `lx.surface.get(key)` later. */
     key?: string;
 };
@@ -879,7 +1106,7 @@ export type PageSurface = SurfaceBase & SurfaceShowable & SurfaceMessaging & {
  */
 export type PageTargetOptions = {
     /** Configured page name from `lingxia.yaml` / `lxapp.json`. */
-    page: string;
+    page: ConfiguredPageName;
     query?: PageQuery;
 };
 export type PreviewMediaAdvance = 'manual' | 'next' | 'loop';
@@ -1007,7 +1234,11 @@ export type PreviewMediaSingleOptions = PreviewMediaSource & {
 export type PreviewMediaSource = {
     /**
      * Media source path.
-     * Recommended: `lx://` path (for example `lx://usercache/...`) or a sandbox-local path
+     *
+     * Accepts an `https://` (or `http://`) URL for a remote image or video —
+     * the host loads it directly, so no prior `lx.downloadFile` is required,
+     * and its domain must be permitted by the app's network policy — an
+     * `lx://` path (for example `lx://usercache/...`), or a sandbox-local path
      * that can be resolved by runtime access rules.
     */
     path: string;
@@ -1130,8 +1361,8 @@ export type ShareTitleOptions = {
     title?: string;
 };
 /**
- * App-owned host-shell chrome. Mutations are available only to the home
- * lxapp's Logic context; other lxapps receive a permission error.
+ * App-owned host-shell chrome. Mutations are available only to the
+ * Control app's Logic context; other lxapps receive a permission error.
  */
 export type ShellApi = {
     /**
@@ -1142,7 +1373,7 @@ export type ShellApi = {
     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. */
+    /** Open a host builtin page such as downloads. */
     openBuiltin(page: BuiltinShellPage): Promise<BuiltinSurface>;
     /**
      * Open a declared surface with shell privileges — the same declaration
@@ -1162,16 +1393,19 @@ export type ShellOpenAppOptions = {
      * 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;
+    page?: ExternalPageName;
     query?: PageQuery;
-    /** Defaults to 'release'. */
-    envVersion?: LxAppEnvVersion;
+    /**
+     * Lxapp publish channel. Defaults from the host env
+     * (`dev` → `draft`, `prod` → `release`).
+     */
+    channel?: LxAppEnvVersion;
     targetVersion?: string;
     /** Stable identity for `lx.surface.get(key)`. */
     key?: string;
 };
 /**
- * The declared-surface options only the home lxapp may use.
+ * The declared-surface options only the native-assigned Control app 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
@@ -1214,8 +1448,13 @@ export type ShellSidebarAction = {
      * `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.
+     * remote icon before registration.
+     *
+     * SVG is a template glyph tinted by the host. Raster PNG/JPEG/WebP retains
+     * its colour and is center-cropped to the square icon slot, which is suitable
+     * for a brand logo; provide square artwork when the crop matters. A path in
+     * `lx://temp` is temporary, so download and register it again after the next
+     * Logic launch rather than persisting it.
      */
     icon: string;
     /**
@@ -1261,7 +1500,7 @@ export type ShellSidebarActionUpdate = {
     disabled?: boolean;
 };
 /**
- * Role and edge overrides the home lxapp may apply to a live declared
+ * Role and edge overrides the native-assigned Control app may apply to a live declared
  * surface. A stable root rejects non-main roles.
  */
 export type ShellSurfacePatch = {
@@ -1305,6 +1544,12 @@ export type Storage = {
      */
     get<T = unknown>(key: string): Promise<T | undefined>;
     set(key: string, value: unknown): Promise<void>;
+    /**
+     * Resolves whether an exact key exists, without reading its value. Prefer
+     * it over comparing `get` against `undefined`: presence is a key lookup,
+     * while `get` also reads and deserializes the stored value.
+     */
+    has(key: string): Promise<boolean>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
     /** Resolves every key, optionally filtered by prefix. */
@@ -1329,7 +1574,7 @@ export type StreamSourceOptions = {
  */
 export type SurfaceApi = {
     /** Open one of this lxapp's own pages as a float or a window. */
-    openPage(page: string, options?: OpenPageOptions): Promise<PageSurface>;
+    openPage(page: ConfiguredPageName, options?: OpenPageOptions): Promise<PageSurface>;
     /** Open external content in the in-app browser. */
     openUrl(url: string, options?: OpenUrlOptions): Promise<TabSurface>;
     /**
@@ -1435,7 +1680,7 @@ export type SurfaceError = Error & {
  * `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. */
+/** A privileged operation was called by an lxapp other than the native-assigned Control app. */
  | 'denied'
 /** No such declared surface, lxapp, or builtin page. */
  | 'not_declared'
@@ -1519,6 +1764,15 @@ export type TabBarApi = globalThis.TabBarApi;
 export type TabBarItemPatch = {
     index: number;
     text?: string | null;
+    /**
+     * Package-relative path, or an `lx://temp` / `lx://usercache` /
+     * `lx://userdata` path from a LingXia file API. Network URLs are rejected —
+     * download first (`lx.downloadFile`) and pass the returned path.
+     *
+     * SVG (and SF Symbols) are template-tinted with `foregroundColor` /
+     * `selectedForegroundColor`. Raster files (PNG/JPEG/WebP) keep their own
+     * colour so a brand mark is not flattened into a solid square.
+     */
     iconPath?: string | null;
     badge?: string | null;
     redDot?: boolean;
@@ -1641,8 +1895,7 @@ export type TerminalSettingsSnapshot = {
     /** Resolved configuration after all valid layers. */
     value: TerminalSettingsValue;
     effective: {
-        /** Host appearance before applying terminal.theme.mode. */
-        systemAppearance: 'light' | 'dark';
+        /** The scheme the product is in, and therefore the terminal too. */
         appearance: 'light' | 'dark';
         colorScheme: string | null;
         font: {
@@ -1661,9 +1914,11 @@ export type TerminalSettingsWarning = {
     code: 'invalidUserFile' | 'missingColorScheme';
     message: string;
 };
-export type TerminalThemeMode = 'system' | 'light' | 'dark';
+/**
+ * A light scheme and a dark one. Which is in use follows the
+ * product's light/dark setting; the terminal has no switch of its own.
+ */
 export type TerminalThemeSettings = {
-    mode: TerminalThemeMode;
     light: string;
     dark: string;
 };
@@ -1692,7 +1947,7 @@ export type UpdateFailedInfo = UpdateReadyInfo & {
 };
 /**
  * Callback-based updates for this lxapp's bundle. Available to every
- * lxapp. To update the native host app, the home lxapp uses the
+ * lxapp. To update the native host app, the Control app uses the
  * task-based `lx.app.checkUpdate()` API instead.
  */
 export type UpdateManager = {
@@ -1705,7 +1960,7 @@ export type UpdateManager = {
 export type UpdateReadyInfo = {
     version?: string;
     isForceUpdate?: boolean;
-    channel?: "release" | "preview" | "developer" | string;
+    channel?: "release" | "preview" | "draft" | string;
 };
 export type UploadIteratorResult = {
     done: boolean;
@@ -1926,38 +2181,27 @@ export type WindowsTerminalInlineImageStatus = {
         bytes: number;
     };
 };
-/** Host app base information. */
+/**
+ * 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`.
+ */
 export interface AppBaseInfo {
-    /**
-     * Raw system locale, unaffected by a saved in-app language override.
-     * For the language the UI should actually render in, use
-     * `display_language` instead.
-     */
-    locale: string;
-    /**
-     * Effective display language: a saved user override when set, else
-     * `locale`. This is what native chrome and `lx.*` i18n strings follow.
-     */
-    displayLanguage: string;
     /**
      * Platform family: `"iOS"` / `"macOS"` / `"Android"` / `"Windows"` /
      * `"Harmony"`. Matches the View-side `usePlatform().os` value.
      */
-    os: string;
+    os: HostOs;
     productName: string;
     version: string;
     SDKVersion: string;
 }
-export interface AppearanceState {
-    preference: AppearancePreference;
-    resolved: ResolvedAppearance;
-}
 /** Device info APIs. */
 export interface DeviceInfo {
     brand: string;
     model: string;
     marketName: string;
-    osName: string;
+    osName: HostOs;
     osVersion: string;
 }
 export interface FileStats {
@@ -1996,7 +2240,7 @@ export interface LxAppInfo {
     appId: string;
     appName: string;
     version: string;
-    releaseType: LxAppReleaseType;
+    channel: LxAppReleaseType;
 }
 export interface ScreenInfo {
     width: number;
@@ -2029,37 +2273,6 @@ export declare class DirEntry {
     readonly isDirectory: boolean;
     readonly isSymlink: boolean;
 }
-export declare class JSMessagePort {
-    constructor();
-    static postMessage(payload: any): void;
-    static onMessage(handler: (...args: any[]) => any): (...args: any[]) => any;
-}
-export declare class JSSurface {
-    constructor();
-    close(): Promise<void>;
-    postMessage(payload: any): void;
-    onMessage(handler: (...args: any[]) => any): (...args: any[]) => any;
-    static onClose(handler: (...args: any[]) => any): (...args: any[]) => any;
-}
-export declare class JSUpdateManager {
-    constructor();
-    /** Apply update by restarting the app */
-    applyUpdate(): void;
-    /** Subscribes to a ready update and returns the unsubscribe fn. */
-    onUpdateReady(cb: (...args: any[]) => any): (...args: any[]) => any;
-    /** Subscribes to a failed update and returns the unsubscribe fn. */
-    onUpdateFailed(cb: (...args: any[]) => any): (...args: any[]) => any;
-}
-export declare class JSVideoContext {
-    constructor();
-    play(): void;
-    pause(): void;
-    stop(): void;
-    seek(position: number): void;
-    requestFullScreen(): void;
-    exitFullScreen(): void;
-    setStreamSource(options: StreamSourceOptions): void;
-}
 export declare class LxFile {
     private constructor();
     /** The path supplied to `lx.fs.file`. */
@@ -2084,14 +2297,6 @@ export declare class LxFile {
     /** 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 {
         /**
@@ -2126,33 +2331,27 @@ declare global {
          * is what the user sees of the whole app — host-drawn navigation chrome,
          * native overlays, and every composited WebView, not just this lxapp's web
          * content. Because that view can include other lxapps' UI, the API is
-         * restricted to the home lxapp, like the other host-level APIs on `lx.app`.
+         * restricted to the Control app, like the other host-level APIs on `lx.app`.
          */
         screenshot(options?: AppScreenshotOptions): Promise<AppScreenshotResult>;
         /**
          * Check whether the host app has an update.
-         * This host-level capability is restricted to the home lxapp. Calling it opts
+         * 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.
          */
         checkUpdate(): Promise<HostAppUpdateCheckResult>;
-        readonly envVersion: HostAppEnvVersion;
+        readonly env: HostAppEnv;
         /**
-         * Read the host app's identity: locale, display language, OS, product name,
-         * product version, and SDK runtime version.
+         * Read the host app's identity: 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.
+         * Control app only: quitting the product is not an lxapp's decision. Other
+         * lxapps get a permission error.
          * If the user should confirm first, call `lx.showModal(...)` and invoke this
          * only after confirmation.
          */
@@ -2160,8 +2359,9 @@ declare global {
         /**
          * Set the app-icon badge, for example an unread count.
          * This targets the dock on macOS, taskbar on Windows, and home/launcher icon
-         * on mobile. Null or an empty string clears it. Unsupported platforms treat
-         * the call as a no-op.
+         * 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;
     }
@@ -2257,7 +2457,7 @@ declare global {
         onKeyUp(callback: KeyEventCallback): () => void;
         /** Get location function */
         getLocation(options?: GetLocationOptions): Promise<LocationInfo>;
-        /** Identify the running lxapp: its id, display name, version, and release type. */
+        /** Identify the running lxapp: its id, display name, version, and channel. */
         getLxAppInfo(): LxAppInfo;
         /** Read an image's dimensions, type, and orientation without decoding it into a view. */
         getImageInfo(options: GetImageInfoOptions): Promise<ImageInfo>;
@@ -2352,7 +2552,6 @@ declare global {
          * an invalid selection.
          */
         showActionSheet(options: ShowActionSheetOptions): Promise<ActionSheetResult>;
-        readonly appearance: AppearanceApi;
         /**
          * Shows a confirmation modal.
          * Resolves `{ canceled: false }` when the user confirms and `{ canceled: true }`
@@ -2371,6 +2570,8 @@ declare global {
          * lx.startPullDownRefresh()
          * Programmatically start the pull-to-refresh animation.
          * This will show the refresh indicator and trigger the onPullDownRefresh lifecycle method.
+         * Throws `E_INVALID_STATE` (`data.bizCode === 4004`) unless the current page
+         * config sets `enablePullDownRefresh: true`.
          */
         startPullDownRefresh(): void;
         /**
@@ -2417,7 +2618,7 @@ declare global {
         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
+         * available to every lxapp and is distinct from the Control-app-only
          * `lx.app.checkUpdate()`, which updates the native host app.
          */
         getUpdateManager(): UpdateManager;
@@ -2439,27 +2640,28 @@ declare global {
     interface ShellApi {
         /**
          * `lx.shell.openApp(appId, options)` — compose another lxapp into a shell
-         * slot. Home-lxapp only; the namespace is the privilege.
+         * slot. Control-app only; the namespace is the privilege.
          */
         openApp(appId: string, options: ShellOpenAppOptions): Promise<AppSurface>;
-        /** `lx.shell.openBuiltin(page)` — a host builtin page. Home-lxapp only. */
+        /** `lx.shell.openBuiltin(page)` — a host builtin page. Control-app only. */
         openBuiltin(page: BuiltinShellPage): Promise<BuiltinSurface>;
         /**
          * `lx.shell.openDeclared(id, options?)` — the declared surface, plus the
-         * keyed multi-instance form and placement overrides. Home-lxapp only.
+         * keyed multi-instance form and placement overrides. Control-app 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>;
+        readonly sidebarActions: ShellSidebarActionsApi;
     }
 }
 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
+         * Control app 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.
+         * paths or runtime-managed `lx://` paths accessible to the Control app.
          * 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
@@ -2469,21 +2671,21 @@ declare global {
         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
+         * Only the Control app 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
+         * Control app may call this API. Throws `E_NOT_FOUND` when `id` is not in the
          * current declaration.
          */
         remove(id: string): void;
         /**
-         * Atomically clears every runtime sidebar action and callback. Only the home
-         * lxapp may call this API. Equivalent to `replace([])` and safe when already
-         * empty; the home lxapp must still redeclare actions after the next Logic launch.
+         * Atomically clears every runtime sidebar action and callback. Only the
+         * Control app may call this API. Equivalent to `replace([])` and safe when already
+         * empty; the Control app must still redeclare actions after the next Logic launch.
          */
         clear(): void;
     }
@@ -2495,7 +2697,7 @@ declare global {
          * 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>;
+        openPage(page: ConfiguredPageName, options?: OpenPageOptions): Promise<PageSurface>;
         /**
          * `lx.surface.openUrl(url, options?)` — external content in the in-app
          * browser, as a tab or docked as an aside.