@lingxia/types 0.15.0 → 0.16.0

package/src/index.ts

@@ -4,23 +4,26 @@
  * Type declarations for the LingXia JS API, driven by Rust implementation.
  */
 
-export * from './generated/logic';
-export * from './automation';
-export * from './error';
-export * from './generated/error';
-export * from './generated/i18n';
+export * from './generated/logic.js';
+export type { Automation } from './automation/index.js';
+export * from './error.js';
+export * from './generated/error.js';
+export * from './generated/i18n.js';
 
-import './generated/logic';
+import './generated/logic.js';
 
 import type {
   AppConfig,
   AppInstance,
+  AppLifecycleName,
   BinaryFileData,
   FsWriteOptions,
+  NoLifecycleTypos,
   PageConfig,
   PageInstance,
-} from './generated/logic';
-import type { Automation } from './automation';
+  PageLifecycleName,
+} from './generated/logic.js';
+import type { Automation } from './automation/index.js';
 
 export type Lx = globalThis.Lx;
 
@@ -52,10 +55,28 @@ declare global {
 
   const lx: Lx;
 
-  function App(config: AppConfig): AppInstance;
+  /**
+   * `TCustom` is inferred from the members you write beside the lifecycle
+   * hooks, so `this.myMethod()` resolves inside the config and a key that is
+   * only a case away from a hook is rejected.
+   */
+  function App<TCustom>(
+    config: AppConfig &
+      TCustom &
+      NoLifecycleTypos<TCustom, AppLifecycleName> &
+      ThisType<AppInstance & TCustom>
+  ): AppInstance & TCustom;
   function getApp<T extends AppInstance = AppInstance>(): T | null;
-  function Page<TData extends Record<string, unknown> = Record<string, unknown>>(
-    config: PageConfig<TData> & ThisType<PageInstance<TData> & PageConfig<TData>>
+  /**
+   * `TData` comes from `data`, `TCustom` from everything else you declare, so
+   * `this.data` is typed, `this.myMethod()` resolves, and `setData` checks
+   * top-level keys against `data`.
+   */
+  function Page<TData extends Record<string, unknown>, TCustom>(
+    config: PageConfig<TData> &
+      TCustom &
+      NoLifecycleTypos<TCustom, PageLifecycleName> &
+      ThisType<PageInstance<TData> & TCustom>
   ): void;
   function getCurrentPages<T extends PageInstance = PageInstance>(): T[];
 }

package/src/process.ts

@@ -1,8 +1,8 @@
 /**
- * OS process capability for trusted LingXia home lxapps.
+ * OS process capability for the Control app.
  *
  * Add `@lingxia/types/process` to the Logic tsconfig only when the host sets
- * `capabilities.process: true` and the home lxapp declares the `process`
+ * `capabilities.process: true` and the Control app declares the `process`
  * security privilege. These declarations have no runtime payload.
  */
 

package/src/testing/public-api.ts

@@ -23,8 +23,13 @@ import type {
 } from '../automation/index.js';
 import type {
   AppearanceApi,
+  AppCacheApi,
   AutostartApi,
   CompressVideoTask,
+  ControlApi,
+  ControlAppearanceApi,
+  ControlDisplayLanguageApi,
+  DisplayLanguageApi,
   DownloadTask,
   FileSystemApi,
   HostAppApi,
@@ -53,7 +58,6 @@ import type {
 
 export const LX_API_NAMES = [
   'app',
-  'appearance',
   'automation',
   'chooseDirectory',
   'chooseFile',
@@ -121,19 +125,38 @@ export const LX_API_NAMES = [
 ] as const;
 
 const HOST_APP_API = [
+  'appearance',
   'autostart',
+  'cache',
   'checkUpdate',
-  'envVersion',
+  'control',
+  'displayLanguage',
+  'env',
   'exit',
   'getBaseInfo',
-  'onDisplayLanguageChange',
   'screenshot',
   'setBadge',
-  'setDisplayLanguage',
 ] as const;
-const HOST_APP_RUNTIME_API = HOST_APP_API.filter((name) => name !== 'autostart');
+// `autostart`, `control`, and `cache` are injected only where they apply, so a
+// runtime walk of `lx.app` must not require them.
+const HOST_APP_RUNTIME_API = HOST_APP_API.filter(
+  (name) => name !== 'autostart' && name !== 'control' && name !== 'cache',
+);
 const AUTOSTART_API = ['isEnabled', 'setEnabled'] as const;
-const APPEARANCE_API = ['get', 'set'] as const;
+const APP_CACHE_API = ['clear', 'size'] as const;
+const DISPLAY_LANGUAGE_API = ['get', 'watch'] as const;
+const CONTROL_API = ['appearance', 'displayLanguage'] as const;
+const CONTROL_DISPLAY_LANGUAGE_API = [
+  'getPreference',
+  'setPreference',
+  'watchPreference',
+] as const;
+const APPEARANCE_API = ['get', 'watch'] as const;
+const CONTROL_APPEARANCE_API = [
+  'getPreference',
+  'setPreference',
+  'watchPreference',
+] as const;
 const NAVIGATION_BAR_API = ['update'] as const;
 const TAB_BAR_API = ['update'] as const;
 const TERMINAL_API = ['colorSchemes', 'fonts', 'settings', 'windows'] as const;
@@ -168,7 +191,7 @@ const LX_FILE_API = [
   'stat',
   'text',
 ] as const;
-const STORAGE_API = ['clear', 'delete', 'get', 'info', 'list', 'set'] as const;
+const STORAGE_API = ['clear', 'delete', 'get', 'has', 'info', 'list', 'set'] as const;
 const UPDATE_MANAGER_API = ['applyUpdate', 'onUpdateFailed', 'onUpdateReady'] as const;
 const VIDEO_CONTEXT_API = [
   'exitFullScreen',
@@ -193,6 +216,7 @@ const SHELL_DRIVER_API = ['pins', 'setPin'] as const;
 const TERMINAL_DRIVER_API = ['input', 'newTab', 'setMaximized', 'snapshot', 'split'] as const;
 const LXAPP_DRIVER_API = ['eval', 'info', 'nav', 'page', 'pages', 'surfaceLayout'] as const;
 const LXAPP_MANAGER_API = [
+  'applink',
   'close',
   'current',
   'list',
@@ -310,7 +334,6 @@ export const LX_RUNTIME_SURFACES = [
     optionalMembers: ['terminal'],
     properties: [
       'app',
-      'appearance',
       'env',
       'fs',
       'navigationBar',
@@ -326,7 +349,7 @@ export const LX_RUNTIME_SURFACES = [
     layer: 'logic',
     expression: 'lx.app',
     members: HOST_APP_RUNTIME_API,
-    properties: ['envVersion'],
+    properties: ['appearance', 'displayLanguage', 'env'],
   },
   {
     name: 'lx.app.autostart',
@@ -336,11 +359,46 @@ export const LX_RUNTIME_SURFACES = [
     optional: true,
   },
   {
-    name: 'lx.appearance',
+    name: 'lx.app.cache',
     layer: 'logic',
-    expression: 'lx.appearance',
+    expression: 'lx.app.cache',
+    members: APP_CACHE_API,
+    optional: true,
+  },
+  {
+    name: 'lx.app.displayLanguage',
+    layer: 'logic',
+    expression: 'lx.app.displayLanguage',
+    members: DISPLAY_LANGUAGE_API,
+  },
+  {
+    name: 'lx.app.control',
+    layer: 'logic',
+    expression: 'lx.app.control',
+    members: CONTROL_API,
+    properties: CONTROL_API,
+    optional: true,
+  },
+  {
+    name: 'lx.app.control.displayLanguage',
+    layer: 'logic',
+    expression: 'lx.app.control?.displayLanguage',
+    members: CONTROL_DISPLAY_LANGUAGE_API,
+    optional: true,
+  },
+  {
+    name: 'lx.app.appearance',
+    layer: 'logic',
+    expression: 'lx.app.appearance',
     members: APPEARANCE_API,
   },
+  {
+    name: 'lx.app.control.appearance',
+    layer: 'logic',
+    expression: 'lx.app.control?.appearance',
+    members: CONTROL_APPEARANCE_API,
+    optional: true,
+  },
   {
     name: 'lx.navigationBar',
     layer: 'logic',
@@ -359,6 +417,7 @@ export const LX_RUNTIME_SURFACES = [
     expression: 'lx.terminal',
     members: TERMINAL_API,
     properties: TERMINAL_API,
+    optionalMembers: ['windows'],
     optional: true,
   },
   {
@@ -424,6 +483,10 @@ export const LX_RUNTIME_SURFACES = [
     layer: 'automation',
     expression: 'lx.automation()',
     members: AUTOMATION_API,
+    // The desktop tier is deliberately absent on mobile hosts. Keep the
+    // portable shape contract honest while the desktop entry covers it on
+    // Windows and macOS.
+    optionalMembers: ['desktop'],
     properties: ['browser', 'desktop', 'device', 'lxapps', 'shell', 'terminal'],
   },
   { name: 'ShellDriver', layer: 'automation', expression: 'lx.automation().shell', members: SHELL_DRIVER_API },
@@ -465,16 +528,17 @@ export const LX_RUNTIME_SURFACES = [
     layer: 'automation',
     expression: 'lx.automation().desktop',
     members: DESKTOP_DRIVER_API,
+    optional: true,
     properties: ['app', 'ax', 'clipboard', 'key', 'pointer', 'process', 'wait', 'window'],
   },
-  { name: 'DesktopPointer', layer: 'automation', expression: 'lx.automation().desktop.pointer', members: DESKTOP_POINTER_API },
-  { name: 'DesktopKey', layer: 'automation', expression: 'lx.automation().desktop.key', members: DESKTOP_KEY_API },
-  { name: 'DesktopWindow', layer: 'automation', expression: 'lx.automation().desktop.window', members: DESKTOP_WINDOW_API },
-  { name: 'DesktopClipboard', layer: 'automation', expression: 'lx.automation().desktop.clipboard', members: DESKTOP_CLIPBOARD_API },
-  { name: 'DesktopAx', layer: 'automation', expression: 'lx.automation().desktop.ax', members: DESKTOP_AX_API },
-  { name: 'DesktopWait', layer: 'automation', expression: 'lx.automation().desktop.wait', members: DESKTOP_WAIT_API },
-  { name: 'DesktopApp', layer: 'automation', expression: 'lx.automation().desktop.app', members: DESKTOP_APP_API },
-  { name: 'DesktopProcess', layer: 'automation', expression: 'lx.automation().desktop.process', members: DESKTOP_PROCESS_API },
+  { name: 'DesktopPointer', layer: 'automation', expression: 'lx.automation().desktop.pointer', members: DESKTOP_POINTER_API, optional: true },
+  { name: 'DesktopKey', layer: 'automation', expression: 'lx.automation().desktop.key', members: DESKTOP_KEY_API, optional: true },
+  { name: 'DesktopWindow', layer: 'automation', expression: 'lx.automation().desktop.window', members: DESKTOP_WINDOW_API, optional: true },
+  { name: 'DesktopClipboard', layer: 'automation', expression: 'lx.automation().desktop.clipboard', members: DESKTOP_CLIPBOARD_API, optional: true },
+  { name: 'DesktopAx', layer: 'automation', expression: 'lx.automation().desktop.ax', members: DESKTOP_AX_API, optional: true },
+  { name: 'DesktopWait', layer: 'automation', expression: 'lx.automation().desktop.wait', members: DESKTOP_WAIT_API, optional: true },
+  { name: 'DesktopApp', layer: 'automation', expression: 'lx.automation().desktop.app', members: DESKTOP_APP_API, optional: true },
+  { name: 'DesktopProcess', layer: 'automation', expression: 'lx.automation().desktop.process', members: DESKTOP_PROCESS_API, optional: true },
 ] as const;
 
 /** Canonical identifiers used by behavioral automation coverage. */
@@ -647,7 +711,8 @@ export const LX_REQUIRED_RUNTIME_SHAPE_NAMES = [
       .map((member) => `shape:${surface.name}.${member}`);
   }),
   ...LX_RETURNED_OBJECT_SURFACES
-    .filter(({ fixture }) => fixture === 'runtime-safe')
+    .filter((surface) => surface.fixture === 'runtime-safe'
+      && !('optional' in surface && surface.optional))
     .flatMap(({ name, members }) => members.map((member) => `shape:${name}.${member}`)),
 ];
 
@@ -666,6 +731,11 @@ export type LxApiManifestGate = [
   AssertTrue<Exact<PublishedLx, typeof LX_API_NAMES>>,
   AssertTrue<Exact<HostAppApi, typeof HOST_APP_API>>,
   AssertTrue<Exact<AutostartApi, typeof AUTOSTART_API>>,
+  AssertTrue<Exact<AppCacheApi, typeof APP_CACHE_API>>,
+  AssertTrue<Exact<DisplayLanguageApi, typeof DISPLAY_LANGUAGE_API>>,
+  AssertTrue<Exact<ControlApi, typeof CONTROL_API>>,
+  AssertTrue<Exact<ControlDisplayLanguageApi, typeof CONTROL_DISPLAY_LANGUAGE_API>>,
+  AssertTrue<Exact<ControlAppearanceApi, typeof CONTROL_APPEARANCE_API>>,
   AssertTrue<Exact<AppearanceApi, typeof APPEARANCE_API>>,
   AssertTrue<Exact<NavigationBarApi, typeof NAVIGATION_BAR_API>>,
   AssertTrue<Exact<TabBarApi, typeof TAB_BAR_API>>,