@lingxia/types 0.14.0 → 0.16.0

package/src/generated/logic.ts

@@ -14,9 +14,61 @@ 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;
@@ -29,7 +81,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;
 }
 
 /**
@@ -69,8 +121,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`.
  */
@@ -113,16 +165,26 @@ export interface DownloadTask<TDownloadResult extends DownloadResult = DownloadR
 }
 
 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 {}
+
   // HostAppApi/LxEnv members are emitted from the Rust js_api metadata; these
   // merges only add what Rong cannot express — the cfg-gated autostart member
-  // and doc comments (js_api consts cannot carry docs). envVersion re-declares
+  // and doc comments (js_api consts cannot carry docs). env re-declares
   // the generated member doc-only; tsc rejects the merge if the types drift.
   interface HostAppApi {
     /**
-     * The build environment from `app.json::envVersion`. It is fixed at boot
-     * and defaults to `release` for older artifacts.
+     * 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
@@ -130,6 +192,28 @@ declare global {
      * 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. */
@@ -187,6 +271,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[]>;
@@ -206,13 +291,37 @@ export type ActionSheetResult = {
 /** 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`. */
@@ -263,16 +372,34 @@ 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 = {
@@ -298,8 +425,26 @@ export type AppSurface = SurfaceBase & SurfaceShowable & {
     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';
 
 /**
@@ -318,8 +463,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 = {
     /**
@@ -342,12 +487,12 @@ 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`.
@@ -517,11 +662,73 @@ export type CompressVideoTask = PromiseLike<CompressVideoResult> & AsyncIterable
     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';
@@ -534,6 +741,35 @@ 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 = {
@@ -570,6 +806,13 @@ export type DownloadsDownloadResult = {
     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.
@@ -679,15 +922,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';
 
@@ -749,6 +994,12 @@ export type HostAppUpdateTask = PromiseLike<HostAppUpdateResult> & AsyncIterable
     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;
@@ -774,13 +1025,13 @@ export type KeyEvent = {
 
 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
@@ -863,9 +1114,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;
 };
 
@@ -950,7 +1205,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;
 };
@@ -1008,7 +1263,7 @@ export type PageSurface = SurfaceBase & SurfaceShowable & SurfaceMessaging & {
  */
 export type PageTargetOptions = {
     /** Configured page name from `lingxia.yaml` / `lxapp.json`. */
-    page: string;
+    page: ConfiguredPageName;
     query?: PageQuery;
 };
 
@@ -1146,7 +1401,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;
@@ -1286,8 +1545,8 @@ export type ShareTitleOptions = {
 };
 
 /**
- * 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 = {
     /**
@@ -1298,7 +1557,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
@@ -1319,17 +1578,20 @@ 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
@@ -1373,8 +1635,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;
     /**
@@ -1423,7 +1690,7 @@ export type ShellSidebarActionUpdate = {
 };
 
 /**
- * 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 = {
@@ -1471,6 +1738,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. */
@@ -1498,7 +1771,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>;
     /**
@@ -1610,7 +1883,7 @@ export type SurfaceError = Error & {
  */
 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'
@@ -1707,6 +1980,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;
@@ -1844,8 +2126,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: {
@@ -1867,10 +2148,11 @@ export type TerminalSettingsWarning = {
     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;
 };
@@ -1904,7 +2186,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 = {
@@ -1918,7 +2200,7 @@ export type UpdateManager = {
 export type UpdateReadyInfo = {
     version?: string;
     isForceUpdate?: boolean;
-    channel?: "release" | "preview" | "developer" | string;
+    channel?: "release" | "preview" | "draft" | string;
 };
 
 export type UploadIteratorResult = {
@@ -2151,40 +2433,28 @@ export type WindowsTerminalInlineImageStatus = {
     };
 };
 
-/** 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;
 }
 
@@ -2227,7 +2497,7 @@ export interface LxAppInfo {
   appId: string;
   appName: string;
   version: string;
-  releaseType: LxAppReleaseType;
+  channel: LxAppReleaseType;
 }
 
 export interface ScreenInfo {
@@ -2265,41 +2535,6 @@ export declare class DirEntry {
   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`. */
@@ -2325,15 +2560,6 @@ export declare class LxFile {
   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 {
     /**
@@ -2369,33 +2595,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.
      */
@@ -2403,8 +2623,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;
   }
@@ -2501,7 +2722,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>;
@@ -2596,7 +2817,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 }`
@@ -2615,6 +2835,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;
     /**
@@ -2661,7 +2883,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;
@@ -2686,18 +2908,19 @@ 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;
   }
 }
 
@@ -2705,9 +2928,9 @@ 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
@@ -2717,21 +2940,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;
   }
@@ -2744,7 +2967,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.