@lingxia/types 0.9.0 → 0.10.0

package/src/index.ts

@@ -32,6 +32,7 @@ import type {
   PageConfig,
   PageInstance,
   Surface,
+  SurfaceHandle,
 } from './app';
 
 import type {
@@ -65,8 +66,14 @@ import type {
 } from './file';
 
 import type {
+  AppDownloadOptions,
+  AppDownloadResult,
+  DownloadDestination,
   DownloadOptions,
+  DownloadResultForDestination,
   DownloadTask,
+  DownloadsDownloadOptions,
+  DownloadsDownloadResult,
   UploadOptions,
   UploadTask,
 } from './transfer';
@@ -83,7 +90,6 @@ import type {
 
 import type {
   SystemSettingInfo,
-  OpenURLOptions,
 } from './system';
 
 import type { NavigateToLxAppOptions } from './navigator';
@@ -96,7 +102,7 @@ import type {
   CompressImageOptions,
   CompressImageResult,
   CompressVideoOptions,
-  CompressVideoResult,
+  CompressVideoTask,
   GetVideoInfoOptions,
   VideoInfo,
   ExtractVideoThumbnailOptions,
@@ -134,24 +140,213 @@ import type {
   RemoveTabBarBadgeOptions,
   SetTabBarStyleOptions,
   SetTabBarItemOptions,
-  SurfaceOpenOptions,
+  SurfaceEdge,
+  SurfaceFloatPosition,
+  OverlaySurfaceSize,
+  SurfaceContext,
   CapsuleRect,
 } from './ui';
 
-export interface SurfaceApi {
+interface WindowSurfaceSize {
+  /** Initial window width in logical pixels. */
+  width?: number;
+  /** Initial window height in logical pixels. */
+  height?: number;
+}
+
+/**
+ * Spec for {@link Lx.openSurface}. 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`
+ *   (`aside` is a companion of the main; `float` is a popup; `window` is a bare
+ *   desktop window, which rejects on mobile). `edge` applies to `aside`,
+ *   `position` applies to `float`, and `size` is a Host-clamped hint. They are
+ *   fixed at open (re-open to change).
+ *
+ *   `aside` is **size-class adaptive**, not a fixed form: only on `medium` /
+ *   `expanded` (room to sit alongside) does it dock and split beside the main at
+ *   `edge` as a sidebar/split panel. On `compact` (phone, or a folded foldable)
+ *   there is no room to dock, so the same surface presents **full-screen** —
+ *   pushed over the main and dismissed by the host back affordance / edge swipe
+ *   (a drill-in), never a docked panel. So one declaration reads as a side panel
+ *   on large screens and a full-screen drill-in on small ones. For a destination
+ *   that should stay switchable on phones, declare it `role: main` instead.
+ *
+ *   `float` is a popup layered above the main at `position` (like a dialog); it
+ *   takes no layout space. The SDK gives it **no chrome of its own — there is no
+ *   built-in close button**: the lxapp owns the popup UI and dismisses it by
+ *   calling `surface.close()` (or `.hide()`). A float sized to the full container
+ *   (`size: { width: '100%', height: '100%' }`) presents immersively on mobile
+ *   (system bars hidden) and is likewise chrome-less — draw your own close
+ *   affordance. (iOS retains a silent left-edge swipe as a last-resort escape so a
+ *   full-screen float can never trap the user; don't rely on it as the primary
+ *   dismissal.)
+ * - `{ 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 }` — an `http(s)://` or `lingxia://` url, shown in the in-app chromed
+ *   browser (always with an address bar — never a chromeless embed). Without
+ *   `as` it opens as a main browser tab (host chrome, no handle). With
+ *   `as: 'aside'` it docks an `http(s)://` page beside the main as a single
+ *   browser aside (its own chrome + close, returns a closable handle); `edge`
+ *   defaults to `'right'` and `size` is a host-clamped preferred size. At most
+ *   one browser aside per window — a new one replaces the existing one.
+ */
+export type OpenPageSurfaceSpec =
+  | {
+      page: string;
+      as: 'aside';
+      edge?: SurfaceEdge;
+      size?: OverlaySurfaceSize;
+      query?: Record<string, unknown>;
+      position?: never;
+      surface?: never;
+      url?: never;
+    }
+  | {
+      page: string;
+      /**
+       * A chrome-less popup above the main: the lxapp draws its own UI and close
+       * affordance — there is no SDK-provided close button (see
+       * {@link OpenPageSurfaceSpec}).
+       */
+      as: 'float';
+      position?: SurfaceFloatPosition;
+      size?: OverlaySurfaceSize;
+      query?: Record<string, unknown>;
+      edge?: never;
+      surface?: never;
+      url?: never;
+    }
+  | {
+      page: string;
+      as: 'window';
+      size?: WindowSurfaceSize;
+      query?: Record<string, unknown>;
+      edge?: never;
+      position?: never;
+      surface?: never;
+      url?: never;
+    };
+
+export interface OpenDeclaredSurfaceSpec {
+  surface: string;
+  page?: never;
+  url?: never;
+  as?: never;
+  edge?: never;
+  position?: never;
+  size?: never;
+  query?: never;
+}
+
+export interface OpenUrlTabSpec {
+  url: string;
+  as?: never;
+  page?: never;
+  surface?: never;
+  edge?: never;
+  position?: never;
+  size?: never;
+  query?: never;
+}
+
+export interface OpenUrlAsideSpec {
+  url: string;
+  as: 'aside';
+  edge?: SurfaceEdge;
+  size?: OverlaySurfaceSize;
+  page?: never;
+  surface?: never;
+  position?: never;
+  query?: never;
+}
+
+export type OpenSurfaceSpec =
+  | OpenPageSurfaceSpec
+  | OpenDeclaredSurfaceSpec
+  | OpenUrlTabSpec
+  | OpenUrlAsideSpec;
+
+/**
+ * Runtime control of the menu-bar (macOS) / system-tray (Windows) status item.
+ * The tray is declared in `lingxia.yaml` (`tray:`); these update its dynamic
+ * content at runtime.
+ *
+ * **Desktop only.** Mobile platforms have no tray, so every method here is a
+ * no-op there (it never throws) — safe to call from portable code. For an
+ * app-icon badge that *is* cross-platform (including mobile), use
+ * {@link HostAppApi.setBadge}.
+ */
+export interface TrayMenuItem {
+  label: string;
+  /** Invoked when this item is clicked. */
+  onClick?: () => void;
+  enabled?: boolean;
+  checked?: boolean;
+}
+
+export interface TrayMenuSeparator {
+  separator: true;
+}
+
+export interface TrayApi {
+  /** Replace the status-item icon (a resource path). */
+  setIcon(icon: string): void;
+  /** Set the text shown beside the icon (macOS). Pass `null`/empty to clear. */
+  setTitle(text: string | null): void;
+  /** Set the badge — e.g. an unread count. Pass `null`/empty to clear. */
+  setBadge(value: string | number | null): void;
   /**
-   * Dynamically opens a page or URL in a runtime-managed surface.
+   * Replace the right-click dropdown menu. There is no default menu — provide
+   * your own items (e.g. `{ label: 'Quit', onClick: () => lx.app.exit() }`).
    *
-   * `overlay` is cross-platform. `window` is a desktop capability and rejects
-   * on mobile platforms.
+   * The menu is a snapshot: to change an item's `checked`/`enabled`/`label`
+   * state, call `setMenu` again with the full updated array. There is no
+   * per-item mutation API.
+   */
+  setMenu(items: Array<TrayMenuItem | TrayMenuSeparator>): void;
+  /**
+   * Handle a left-click on the tray icon yourself. While a handler is
+   * registered the click runs only the handler — the tray's configured surface
+   * `action` is suppressed, so the click is fully yours (e.g. toggle a state and
+   * `setIcon`). Returns an unsubscribe function.
    */
-  open(options: SurfaceOpenOptions): Promise<Surface>;
+  onClick(handler: () => void): () => void;
+  /** Show the tray status item. */
+  show(): void;
+  /** Hide the tray status item (without removing the app). */
+  hide(): void;
 }
 
 export interface Lx {
   env: LxEnv;
   app: HostAppApi;
-  surface: SurfaceApi;
+  tray: TrayApi;
+
+  /**
+   * Open a surface.
+   *
+   * - `{ url }` without `as` opens a host browser tab and resolves to `null`.
+   * - `{ surface }` resolves to a host-managed handle with show/hide/close.
+   * - page surfaces and `{ url, as: 'aside' }` resolve to a full Surface handle.
+   *
+   * `as: 'window'` is desktop-only and rejects on mobile. See
+   * {@link OpenSurfaceSpec}.
+   */
+  openSurface(spec: OpenUrlTabSpec): Promise<null>;
+  openSurface(spec: OpenDeclaredSurfaceSpec): Promise<SurfaceHandle>;
+  openSurface(spec: OpenPageSurfaceSpec | OpenUrlAsideSpec): Promise<Surface>;
+  openSurface(spec: OpenSurfaceSpec): Promise<Surface | SurfaceHandle | null>;
+  /** Hand a url off to the OS default browser (leaves the app). */
+  openExternal(url: string): void;
+  /**
+   * Subscribe to adaptive-context changes ({@link SurfaceContext}); the handler
+   * fires with the new context. Returns an unsubscribe function.
+   */
+  onSurfaceContext(handler: (context: SurfaceContext) => void): () => void;
 
   getDeviceInfo(): DeviceInfo;
   getScreenInfo(): ScreenInfo;
@@ -180,7 +375,11 @@ export interface Lx {
    * otherwise prefer `mode: 'auto'`.
    */
   openFile(options: OpenFileOptions): void;
-  downloadFile(options: DownloadOptions): DownloadTask;
+  downloadFile(options: DownloadsDownloadOptions): DownloadTask<DownloadsDownloadResult>;
+  downloadFile(options: AppDownloadOptions): DownloadTask<AppDownloadResult>;
+  downloadFile<TDestination extends DownloadDestination = 'app'>(
+    options: DownloadOptions<TDestination>,
+  ): DownloadTask<DownloadResultForDestination<TDestination>>;
   uploadFile(options: UploadOptions): UploadTask;
   getFileManager(): FileManager;
 
@@ -193,13 +392,12 @@ export interface Lx {
 
   getLxAppInfo(): LxAppInfo;
   getSystemSetting(): SystemSettingInfo;
-  openURL(options: OpenURLOptions): void;
 
   getUpdateManager(): UpdateManager;
 
   getImageInfo(options: GetImageInfoOptions): Promise<ImageInfo>;
   compressImage(options: CompressImageOptions): Promise<CompressImageResult>;
-  compressVideo(options: CompressVideoOptions): Promise<CompressVideoResult>;
+  compressVideo(options: CompressVideoOptions): CompressVideoTask;
   getVideoInfo(options: GetVideoInfoOptions): Promise<VideoInfo>;
   extractVideoThumbnail(options: ExtractVideoThumbnailOptions): Promise<ExtractVideoThumbnailResult>;
 
@@ -214,9 +412,12 @@ export interface Lx {
    * - a sequence object for multi-item preview with `sources`, `startIndex`, and `advance`
    *
    * Returns a {@link PreviewMediaHandle} synchronously. Await `handle.completed`
-   * for the final session result (`reason`, `lastIndex`). Subscribe to
-   * `handle.presented` to learn when the first pixel hits the screen — useful
-   * for coordinating a hide of any overlay surface that was previously visible.
+   * for the final session result (`reason`, `index`, `source` — the item the
+   * user was viewing when the preview closed). Subscribe to
+   * `handle.onChange(...)` / read `handle.current` to follow the viewed item
+   * live, and to `handle.presented` to learn when the first pixel hits the
+   * screen — useful for coordinating a hide of any overlay surface that was
+   * previously visible.
    *
    * `handle.completed` rejects with a cancellation error if `signal` is aborted;
    * abort also requests the active native preview session to close immediately.

package/src/media/index.ts

@@ -73,6 +73,41 @@ export interface CompressVideoResult {
   type: string;
 }
 
+export interface CompressVideoProgressEvent {
+  /** Transcode progress in percent, `0`-`100`. */
+  progress: number;
+}
+
+export interface CompressVideoIteratorResult {
+  done: boolean;
+  value?: CompressVideoProgressEvent;
+}
+
+/**
+ * Handle returned by `lx.compressVideo`.
+ *
+ * Awaiting the task resolves with the final {@link CompressVideoResult}.
+ * Iterating it with `for await` yields {@link CompressVideoProgressEvent}s
+ * while the transcode runs.
+ */
+export interface CompressVideoTask
+  extends PromiseLike<CompressVideoResult>,
+    AsyncIterable<CompressVideoProgressEvent> {
+  next(): Promise<CompressVideoIteratorResult>;
+  /** Stops iteration only. Does not cancel the compression. */
+  return(): Promise<CompressVideoIteratorResult>;
+  catch<TResult = never>(
+    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<CompressVideoResult | TResult>;
+  finally(onfinally?: (() => void) | null): Promise<CompressVideoResult>;
+  /**
+   * Cancels the transcode and deletes any partial output.
+   * The task promise rejects with an `AbortError` (`code: 'E_ABORT'`).
+   */
+  cancel(): void;
+  wait(): Promise<CompressVideoResult>;
+}
+
 export interface GetVideoInfoOptions {
   /**
    * Video file path or `lx://` URI.
@@ -279,35 +314,68 @@ export type PreviewMediaOptions =
 
 export type PreviewMediaCloseReason = 'manual' | 'completed' | 'interrupted' | 'error';
 
+/**
+ * The item the user is (or was) looking at, handed back as the caller
+ * described it — `path` is returned verbatim, so it can be matched against
+ * the caller's own data without re-indexing an array.
+ */
+export interface PreviewMediaShownSource {
+  /** The path exactly as passed in the request. */
+  path: string;
+  /** Resolved media kind (after extension inference when `type` was omitted). */
+  type: 'image' | 'video';
+}
+
+/** One change-stream event / the `current` snapshot. */
+export interface PreviewMediaChange {
+  index: number;
+  source: PreviewMediaShownSource;
+}
+
 export interface PreviewMediaResult {
   /**
    * Why the preview session finished.
    */
   reason: PreviewMediaCloseReason;
   /**
-   * Last active item index before close.
+   * Index of the item on screen when the session closed.
+   */
+  index: number;
+  /**
+   * The item on screen when the session closed — "what the user just
+   * viewed/played", without mapping `index` back yourself.
    */
-  lastIndex: number;
+  source: PreviewMediaShownSource;
 }
 
 /**
- * Handle returned synchronously from `lx.previewMedia(...)`. Exposes two
- * independent Promises so callers can coordinate transitions:
+ * Handle returned synchronously from `lx.previewMedia(...)` — synchronous so
+ * listeners can be attached before the first event fires:
  *
  * - `presented` resolves once the first pixel of the underlying media has
  *   been composited to screen. Use this to time the hide of an overlay
  *   surface above the preview so the swap is seamless. Never rejects;
  *   resolves with no value when the first frame is up. Safe to ignore.
- * - `completed` resolves when the preview session ends (manual / auto /
- *   interrupted / error). Replaces the previous `Promise<PreviewMediaResult>`
- *   that `previewMedia` used to return directly.
+ * - `current` is a live `{ index, source }` snapshot of the item on screen,
+ *   updated as the user swipes and as the session auto-advances.
+ * - `onChange(listener)` fires for every item change. Returns an
+ *   unsubscribe function.
+ * - `completed` resolves `{ reason, index, source }` when the preview
+ *   session ends (manual / auto / interrupted / error), or rejects on abort.
  *
  * If the call was aborted before any frame was presented, `presented` still
  * resolves (with no value) once the abort takes effect — it never rejects,
  * to keep fire-and-forget usage safe.
+ *
+ * @example
+ * const preview = lx.previewMedia({ sources, startIndex: 2 });
+ * preview.onChange(({ source }) => markAsViewed(source.path));
+ * const { reason, source } = await preview.completed;
  */
 export interface PreviewMediaHandle {
   readonly presented: Promise<void>;
+  readonly current: PreviewMediaChange;
+  onChange(listener: (change: PreviewMediaChange) => void): () => void;
   readonly completed: Promise<PreviewMediaResult>;
 }
 

package/src/system/index.ts

@@ -1,5 +1,5 @@
 /**
- * System settings and URL APIs.
+ * System settings.
  */
 
 export interface SystemSettingInfo {
@@ -7,8 +7,3 @@ export interface SystemSettingInfo {
   locationEnabled: boolean;
   wifiEnabled: boolean;
 }
-
-export interface OpenURLOptions {
-  url: string;
-  target?: 'self' | 'external';
-}

package/src/transfer/index.ts

@@ -2,7 +2,22 @@
  * Transfer task APIs.
  */
 
-export interface DownloadOptions {
+declare const appDownloadPathBrand: unique symbol;
+declare const systemDownloadsPathBrand: unique symbol;
+
+export type DownloadDestination = 'app' | 'downloads';
+
+/** Runtime-managed app download path, usually under `lx://userdata`. */
+export type AppDownloadFilePath = string & {
+  readonly [appDownloadPathBrand]: 'app-download-file-path';
+};
+
+/** Native system Downloads path. Do not pass this to `FileManager`. */
+export type SystemDownloadsPath = string & {
+  readonly [systemDownloadsPathBrand]: 'system-downloads-path';
+};
+
+export interface DownloadOptionsBase {
   /** HTTP(S) source URL. */
   url: string;
   /**
@@ -12,35 +27,66 @@ export interface DownloadOptions {
   headers?: Record<string, string>;
   /** Request timeout in milliseconds. */
   timeout?: number;
+  /** Optional abort signal. */
+  signal?: AbortSignal;
+}
+
+export interface AppDownloadOptions extends DownloadOptionsBase {
   /**
-   * Optional durable destination.
-   *
-   * - Omit `filePath` to receive a temporary file in `tempFilePath`
-   * - Relative paths resolve under user data
-   * - `lx://` paths must target `lx://userdata`
+   * Optional app-owned durable output path.
    *
+   * Omit `filePath` to receive a temporary result in `tempFilePath`. Relative
+   * paths resolve under user data. `lx://` paths must target `lx://userdata`;
    * `lx://usercache` is not accepted here.
    */
   filePath?: string;
-  /** Optional abort signal. */
-  signal?: AbortSignal;
+  /**
+   * App-owned output. Omit to use a temporary output unless `filePath` is set.
+   */
+  destination?: 'app';
+}
+
+export interface DownloadsDownloadOptions extends DownloadOptionsBase {
+  /**
+   * Optional filename hint for the system Downloads destination.
+   * This is not an app-owned FileManager path.
+   */
+  filePath?: string;
+  /** Save into the user's system Downloads directory. */
+  destination: 'downloads';
 }
 
-export interface DownloadProgressEvent {
+/**
+ * Download options.
+ *
+ * - `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`
+ *
+ * Default: `app`.
+ */
+export type DownloadOptions<TDestination extends DownloadDestination = DownloadDestination> =
+  TDestination extends 'downloads' ? DownloadsDownloadOptions : AppDownloadOptions;
+
+export type DownloadResultForDestination<TDestination extends DownloadDestination> =
+  TDestination extends 'downloads' ? DownloadsDownloadResult : AppDownloadResult;
+
+export interface DownloadProgressEvent<TResult extends DownloadResult = DownloadResult> {
   kind: 'progress' | 'paused' | 'resumed' | 'canceled' | 'completed';
   downloadedBytes?: number;
   totalBytes?: number;
   /** Present only when the total size is known. */
   progress?: number;
-  result?: DownloadResult;
+  result?: TResult;
 }
 
-export interface DownloadIteratorResult {
+export interface DownloadIteratorResult<TResult extends DownloadResult = DownloadResult> {
   done: boolean;
-  value?: DownloadProgressEvent;
+  value?: DownloadProgressEvent<TResult>;
 }
 
-export type DownloadResult =
+export type AppDownloadResult =
   | {
       /**
        * Temporary result.
@@ -57,26 +103,38 @@ export type DownloadResult =
     }
   | {
       /** Durable destination under `lx://userdata`. */
-      filePath: string;
+      filePath: AppDownloadFilePath;
       tempFilePath?: never;
       mimeType?: string;
       size: number;
     };
 
-export interface DownloadTask extends PromiseLike<DownloadResult>, AsyncIterable<DownloadProgressEvent> {
-  next(): Promise<DownloadIteratorResult>;
+export interface DownloadsDownloadResult {
+  /** Native system Downloads path. Do not pass this to `FileManager`. */
+  filePath: SystemDownloadsPath;
+  tempFilePath?: never;
+  mimeType?: string;
+  size: number;
+}
+
+export type DownloadResult = AppDownloadResult | DownloadsDownloadResult;
+
+export interface DownloadTask<TDownloadResult extends DownloadResult = DownloadResult>
+  extends PromiseLike<TDownloadResult>,
+    AsyncIterable<DownloadProgressEvent<TDownloadResult>> {
+  next(): Promise<DownloadIteratorResult<TDownloadResult>>;
   /** Stops iteration only. Does not cancel the underlying download task. */
-  return(): Promise<DownloadIteratorResult>;
-  catch<TResult = never>(
-    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
-  ): Promise<DownloadResult | TResult>;
-  finally(onfinally?: (() => void) | null): Promise<DownloadResult>;
+  return(): Promise<DownloadIteratorResult<TDownloadResult>>;
+  catch<TRejected = never>(
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): Promise<TDownloadResult | TRejected>;
+  finally(onfinally?: (() => void) | null): Promise<TDownloadResult>;
   pause(): Promise<void>;
   resume(): Promise<void>;
   cancel(): Promise<void>;
   /** Alias for cancel(), matching browser/mini-program abort naming. */
   abort(): Promise<void>;
-  wait(): Promise<DownloadResult>;
+  wait(): Promise<TDownloadResult>;
 }
 
 export interface UploadOptions {