@lingxia/types 0.11.1 → 0.12.0

package/src/automation/index.ts

@@ -9,6 +9,8 @@
  * product-side API.
  */
 
+import type { TerminalSettingsValue } from '../generated/logic.js';
+
 // ============================ factory ============================
 
 /** Stable automation root; it grants no capability until one is selected. */
@@ -21,6 +23,8 @@ export interface Automation {
   readonly lxapps: LxAppManager;
   /** The host app's browser tabs. */
   readonly browser: BrowserDriver;
+  /** Persisted host-shell shortcuts for deterministic test setup/assertion. */
+  readonly shell: ShellDriver;
   /** Simulated-device selection in a host runner. */
   readonly device: DeviceDriver;
   /**
@@ -29,6 +33,141 @@ export interface Automation {
    * Runner) on top of the `host` privilege. Windows/macOS only.
    */
   readonly desktop: DesktopDriver;
+  /** Native terminal workspace state and pane actions in trusted dev/test hosts. */
+  readonly terminal: TerminalDriver;
+}
+
+// ========================== terminal tier ==========================
+
+export type TerminalSplitDirection = 'left' | 'right' | 'up' | 'down';
+
+export interface TerminalSurfaceRef {
+  /** Stable id returned by `lx.shell.openDeclared('terminal', { key })`. */
+  surface: string;
+}
+
+export interface TerminalPaneSnapshot {
+  paneId: string;
+  active: boolean;
+  visible: boolean;
+  frame: { x: number; y: number; width: number; height: number };
+  grid: {
+    cols: number;
+    rows: number;
+    generation: number;
+    imageGeneration: number;
+    imageCount: number;
+    imagePlacementCount: number;
+    defaultForeground: number;
+    defaultBackground: number;
+    cursorRow: number;
+    cursorCol: number;
+    cursorVisible: boolean;
+    cursorStyle: 'block' | 'bar' | 'underline' | 'block-hollow';
+  };
+}
+
+export type TerminalPaneTree =
+  | { kind: 'leaf'; pane: TerminalPaneSnapshot }
+  | {
+    kind: 'split';
+    /** `horizontal` places children left/right; `vertical` stacks them. */
+    axis: 'horizontal' | 'vertical';
+    children: TerminalPaneTree[];
+  };
+
+export interface TerminalTabSnapshot {
+  id: string;
+  active: boolean;
+  activePaneId?: string;
+  paneCount: number;
+  tree?: TerminalPaneTree;
+}
+
+/** Semantic state published by the native terminal host after layout. */
+export interface TerminalWorkspaceSnapshot {
+  surfaceId: string;
+  presentation: 'main' | 'aside';
+  visible: boolean;
+  /** Expanded to the full content area rather than its docked size. */
+  maximized: boolean;
+  activeTabId?: string;
+  tabCount: number;
+  paneCount: number;
+  configGeneration: number;
+  visualGeneration: number;
+  config: TerminalSettingsValue;
+  chrome: {
+    surface: string;
+    header: string;
+    separator: string;
+    text: string;
+    textMuted: string;
+    cursor: string;
+    selectionBackground: string;
+    selectionForeground: string;
+  };
+  tabs: TerminalTabSnapshot[];
+}
+
+export interface TerminalSplitOptions extends TerminalSurfaceRef {
+  direction: TerminalSplitDirection;
+}
+
+/** Native terminal automation; available only to trusted dev/test hosts. */
+export interface TerminalDriver {
+  snapshot(options: TerminalSurfaceRef): Promise<TerminalWorkspaceSnapshot>;
+  /** Send text to the focused pane, as if typed into its PTY. */
+  input(options: TerminalInputOptions): Promise<TerminalWorkspaceSnapshot>;
+  split(options: TerminalSplitOptions): Promise<TerminalWorkspaceSnapshot>;
+  /** Open a tab and activate it. Resolves with the snapshot that follows. */
+  newTab(options: TerminalSurfaceRef): Promise<TerminalWorkspaceSnapshot>;
+  /** Expand to the full content area, or return to the docked size. */
+  setMaximized(options: TerminalMaximizeOptions): Promise<TerminalWorkspaceSnapshot>;
+}
+
+export interface TerminalInputOptions extends TerminalSurfaceRef {
+  text: string;
+}
+
+export interface TerminalMaximizeOptions extends TerminalSurfaceRef {
+  maximized: boolean;
+}
+
+// ============================ shell tier ============================
+
+/** One ordered shortcut in the host shell's persisted Pin collection. */
+export type AutomationShellPin =
+  | {
+    /** A host workspace shortcut; activation opens/focuses the app as main. */
+    kind: 'lxapp';
+    /** Installed lxapp id. This is not a page name or route. */
+    key: string;
+  }
+  | {
+    /** A website shortcut opened/focused as a main browser tab. */
+    kind: 'bookmark';
+    /** Persisted bookmark id. */
+    key: string;
+  };
+
+export type SetAutomationShellPinOptions = AutomationShellPin & {
+  pinned: boolean;
+};
+
+/**
+ * Host-shell state for test setup and end-to-end assertions. This does not
+ * customize an lxapp's production shell; use `lx.shell` for app behavior.
+ */
+export interface ShellDriver {
+  /** Ordered shortcuts exactly as projected into the host sidebar. */
+  pins(): Promise<AutomationShellPin[]>;
+  /**
+   * Idempotently persist or remove one shortcut. New Pins append to the
+   * existing order; adding beyond the host limit rejects without mutation.
+   * Returns the resulting complete order.
+   */
+  setPin(options: SetAutomationShellPinOptions): Promise<AutomationShellPin[]>;
 }
 
 // ============================ page tier ============================
@@ -89,7 +228,17 @@ export interface PageScrollToOptions extends PageTarget {
   css: string;
 }
 
-export type PageWaitState = 'exists' | 'visible' | 'gone';
+export type PageWaitState =
+  | 'attached'
+  | 'detached'
+  | 'visible'
+  | 'hidden'
+  | 'enabled'
+  | 'editable'
+  /** @deprecated Use `attached`. */
+  | 'exists'
+  /** @deprecated Use `detached`. */
+  | 'gone';
 
 export interface PageWaitForOptions extends PageTarget {
   css: string;
@@ -99,7 +248,12 @@ export interface PageWaitForOptions extends PageTarget {
   timeoutMs?: number;
 }
 
-/** An element's viewport rectangle (viewport-relative CSS pixels). */
+/**
+ * An element's viewport rectangle (viewport-relative CSS pixels).
+ *  Windows LingXia WebViews use a 1:1 CSS-to-child-window rasterization scale,
+ *  so combine this with that WebView's desktop bounds without multiplying by
+ *  `DesktopWindowInfo.scale`.
+ */
 export interface ElementRect {
   left: number;
   top: number;
@@ -257,6 +411,103 @@ export interface LxAppEvalOptions {
   timeoutMs?: number;
 }
 
+export type SurfaceLayoutSizeClass = 'compact' | 'medium' | 'expanded';
+export type SurfaceLayoutSwitcherForm = 'none' | 'sidebar' | 'rail';
+export type SurfaceLayoutSplitForm = 'none' | 'split' | 'collapsible' | 'fullScreen';
+export type SurfaceLayoutEdge = 'left' | 'right' | 'top' | 'bottom';
+
+export type SurfaceLayoutIcon =
+  | { source: 'builtIn'; name: string }
+  | { source: 'resource'; uri: string }
+  | { source: 'providerAsset'; provider: string; key: string };
+
+/** Resolved content identity carried by one host switcher item. */
+export type SurfaceSwitcherContent =
+  | { kind: 'lxapp'; appId: string }
+  | { kind: 'page'; appId: string }
+  | { kind: 'browser' }
+  | { kind: 'native'; capability: string };
+
+export interface SurfaceSwitcherItem {
+  surfaceId: string;
+  content: SurfaceSwitcherContent;
+  title?: string;
+  icon?: SurfaceLayoutIcon;
+  active: boolean;
+  root: boolean;
+  closable: boolean;
+  renameable: boolean;
+  titleOverridden: boolean;
+}
+
+/** Ordered semantic model behind the host's main-surface switcher. */
+export interface SurfaceSwitcherSnapshot {
+  /** Monotonically changes when the host surface model changes. */
+  revision: number;
+  rootSurfaceId?: string;
+  activeSurfaceId?: string;
+  items: SurfaceSwitcherItem[];
+}
+
+export interface SurfaceLayoutAside {
+  id: string;
+  edge?: SurfaceLayoutEdge;
+  preferredSize?: number;
+}
+
+export interface SurfaceLayoutAsideSlot {
+  kind: 'lxapp' | 'browser' | 'native';
+  edge?: SurfaceLayoutEdge;
+  /** Stable tab order within this content-kind region. */
+  children: string[];
+  activeChild?: string;
+  visible: boolean;
+  overlay: boolean;
+}
+
+export type SurfaceLayoutFloatAnchor =
+  | { to: 'screen' }
+  | { to: 'surface'; surfaceId: string };
+
+export interface SurfaceLayoutFloat {
+  id: string;
+  anchor: SurfaceLayoutFloatAnchor;
+  dismiss: 'tapOutside' | 'manual';
+  modal: boolean;
+  closeButton: boolean;
+}
+
+/** Id-only surface tree emitted by the shared layout core. */
+export type SurfaceLayoutTree =
+  | { kind: 'leaf'; surfaceId: string }
+  | {
+    kind: 'split';
+    axis: 'horizontal' | 'vertical';
+    children: SurfaceLayoutTree[];
+    weights: number[];
+  }
+  | { kind: 'tabs'; activeId: string; children: string[] }
+  | { kind: 'freeform'; surfaceId: string };
+
+/**
+ * Read-only automation snapshot of the exact render plan consumed by the host
+ * skin. Use this for end-to-end assertions; production lxapp behavior should
+ * depend on `SurfaceHandle`, not host layout internals.
+ */
+export interface SurfaceLayoutSnapshot {
+  sizeClass: SurfaceLayoutSizeClass;
+  bottomOwner: 'app';
+  switcherForm: SurfaceLayoutSwitcherForm;
+  splitForm: SurfaceLayoutSplitForm;
+  mains: string[];
+  activeMainId?: string;
+  mainSwitcher: SurfaceSwitcherSnapshot;
+  asides: SurfaceLayoutAside[];
+  asideSlots: SurfaceLayoutAsideSlot[];
+  floats: SurfaceLayoutFloat[];
+  tree?: SurfaceLayoutTree;
+}
+
 /** Capability for one selected running lxapp. */
 export interface LxAppDriver {
   readonly page: PageDriver;
@@ -265,6 +516,8 @@ export interface LxAppDriver {
   info(): Promise<LxAppRuntimeInfo>;
   /** Configured pages of the selected lxapp. */
   pages(): Promise<LxAppPageConfig[]>;
+  /** Authoritative host surface render plan, for end-to-end assertions. */
+  surfaceLayout(): Promise<SurfaceLayoutSnapshot>;
   /** Logic-runtime eval; self-eval from that Logic runtime is rejected. */
   eval(options: LxAppEvalOptions): Promise<unknown>;
 }
@@ -291,11 +544,46 @@ export interface LxAppRuntimeInfo {
   pages_count: number;
   page_entries: LxAppPageEntry[];
   page_stack: string[];
+  tab_bar: LxAppRuntimeTabBarInfo | null;
+  navigation_bar: LxAppRuntimeNavigationBarInfo | null;
   lxapp_dir: string;
   data_dir: string;
   cache_dir: string;
 }
 
+/** Runtime NavigationBar state exposed for deterministic host-level assertions. */
+export interface LxAppRuntimeNavigationBarInfo {
+  title: string;
+  home_button: 'auto' | 'hidden';
+  home_button_visible: boolean;
+  runtime_style: {
+    background_color: string | null;
+    foreground_color: string | null;
+    divider_color: string | null;
+  };
+}
+
+/** Runtime TabBar state exposed for deterministic host-level assertions. */
+export interface LxAppRuntimeTabBarInfo {
+  presentation: 'standard' | 'immersive';
+  visibility: 'auto' | 'visible' | 'hidden';
+  route_visible: boolean;
+  effective_visible: boolean;
+  selected_index: number;
+  runtime_style: {
+    foreground_color: string | null;
+    selected_foreground_color: string | null;
+  };
+  items: Array<{
+    index: number;
+    text: string | null;
+    icon_path: string | null;
+    selected_icon_path: string | null;
+    badge: string | null;
+    red_dot: boolean;
+  }>;
+}
+
 /** Selects a running lxapp by id; defaults to the current app. */
 export interface LxAppRef {
   /** LxApp id, or `"current"` (default). */
@@ -371,7 +659,7 @@ export interface DeviceSetOptions {
 }
 
 /**
- * Simulated-device control (`lxdev lxapp device`). Only functional in a host
+ * Simulated-device control (`lxdev runner`). Only functional in a host
  * runner that registered a device controller; otherwise every call rejects.
  */
 export interface DeviceDriver {
@@ -676,6 +964,10 @@ export interface DesktopWindowInfo {
   pid: number;
   bounds: DesktopRect;
   display_id: string;
+  /**
+   * Display DIP-to-physical scale. `bounds` are already backend-native; do not
+   * multiply them by this value.
+   */
   scale: number;
   dpi: number;
   visible: boolean;
@@ -861,11 +1153,15 @@ export interface DesktopKeyTypeOptions extends DesktopInputTarget {
 }
 
 export interface DesktopKeyPressOptions extends DesktopInputTarget {
+  /** Case-insensitive named key (`Enter`, `ArrowDown`, `Down`, etc.) or one
+   * printable character. */
   key: string;
   modifiers?: KeyModifier[];
 }
 
 export interface DesktopKeyNameOptions extends DesktopInputTarget {
+  /** Case-insensitive named key (`Enter`, `ArrowDown`, `Down`, etc.) or one
+   * printable character. */
   key: string;
 }
 

package/src/error.ts

@@ -1,3 +1,4 @@
+import type { SurfaceErrorCode } from './generated/logic.js';
 import { ERR_CODE_INFO_BY_CODE, type LxErrorCodeInfo } from "./generated/error";
 
 const ERR_CODE_INDEX = ERR_CODE_INFO_BY_CODE as Record<number, LxErrorCodeInfo>;
@@ -9,11 +10,27 @@ export interface LxApiError {
   readonly raw: unknown;
 }
 
+/** Check an already-normalized error without modifying the caught value. */
 export function isLxApiError(error: unknown): error is LxApiError {
-  return parseLxApiError(error) !== null;
+  const target = toRecord(error);
+  if (!target) return false;
+  const code = parseIntegerCode(target.code);
+  if (code === null) return false;
+  const info = infoForLxErrorCode(code);
+  return Boolean(
+    info &&
+      target.code === code &&
+      target.key === info.key &&
+      typeof target.message === "string" &&
+      Object.prototype.hasOwnProperty.call(target, "raw"),
+  );
 }
 
 function readMessage(error: unknown): string {
+  const root = toRecord(error);
+  const data = root && toRecord(root.data);
+  const detail = data?.detail;
+  if (typeof detail === "string" && detail.trim() !== "") return detail;
   if (typeof error === "string") return error;
   if (error instanceof Error && typeof error.message === "string") return error.message;
   if (typeof error === "object" && error !== null) {
@@ -50,6 +67,35 @@ export function extractLxErrorCode(error: unknown): number | null {
   return parseIntegerCode(data.bizCode) ?? parseIntegerCode(data.code);
 }
 
+/**
+ * The surface code carried by a `lx.surface.*` / `lx.shell.*` rejection.
+ *
+ * A rejection's `code` is the transport-level host code shared with every
+ * other `lx` API; the surface-specific member of `SurfaceErrorCode` rides on
+ * `data.code`. Reading it through this helper keeps callers off both the
+ * message text and the shape.
+ */
+export function surfaceErrorCode(error: unknown): SurfaceErrorCode | null {
+  const root = toRecord(error);
+  const data = root ? toRecord(root.data) : null;
+  const code = data?.code;
+  return typeof code === 'string' && SURFACE_ERROR_CODES.includes(code as SurfaceErrorCode)
+    ? (code as SurfaceErrorCode)
+    : null;
+}
+
+/** Every member of `SurfaceErrorCode`, for runtime narrowing. */
+export const SURFACE_ERROR_CODES = [
+  'unsupported_placement',
+  'denied',
+  'not_declared',
+  'invalid_arg',
+  'already_open_other_role',
+  'closed',
+  'capability_missing',
+  'failed',
+] as const satisfies readonly SurfaceErrorCode[];
+
 export function isKnownLxErrorCode(code: number): boolean {
   return Number.isInteger(code) && Object.prototype.hasOwnProperty.call(ERR_CODE_INDEX, code);
 }

package/src/generated/i18n.ts

@@ -27,6 +27,7 @@ export const I18N_KEYS = [
   "browser_page_menu",
   "browser_pin_to_sidebar",
   "browser_remove_bookmark",
+  "browser_tabs",
   "browser_unpin",
   "camera_access_denied",
   "camera_audio_init_failed",
@@ -57,6 +58,7 @@ export const I18N_KEYS = [
   "common_delete",
   "common_done",
   "common_exit",
+  "common_forward",
   "common_loading",
   "common_ok",
   "common_refresh",
@@ -132,6 +134,11 @@ export const I18N_KEYS = [
   "permission_wifi_reason",
   "shell_pin_limit_message",
   "shell_pin_limit_title",
+  "surface_close",
+  "surface_close_after",
+  "surface_close_others",
+  "surface_rename",
+  "surface_reset_title",
   "terminal_change_title",
   "terminal_close_pane",
   "terminal_copy",
@@ -139,6 +146,7 @@ export const I18N_KEYS = [
   "terminal_paste",
   "terminal_read_only",
   "terminal_reset",
+  "terminal_search",
   "terminal_split_down",
   "terminal_split_left",
   "terminal_split_right",