@lingxia/types 0.18.0 → 0.19.0

package/src/generated/logic.ts

@@ -171,6 +171,14 @@ export interface PageInstance<TData extends object = Record<string, unknown>> {
   setDataPath(path: string, value: JsonValue | undefined): void;
   /** Drain pending state writes; an attached View acknowledges application, not paint. Rejects on unload. */
   flush(): Promise<void>;
+  /**
+   * Aborted as the page unloads, before `onUnload` runs, however the page
+   * leaves. Pass it to work the page starts — `fetch(url, { signal:
+   * this.signal })` — so that work stops with the page, rejecting with an
+   * `AbortError`, instead of resolving into a page that is gone. When the
+   * whole lxapp shuts down, its Logic ends with it and the signal does not fire.
+   */
+  readonly signal: AbortSignal;
 }
 
 /**
@@ -1138,8 +1146,11 @@ export type HostAppApi = globalThis.HostAppApi;
  * 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
+ * This is the immutable host build axis: package-id suffix, publish
+ * token, signed App Link entitlements, and self-update channel.
+ * In-app App Link hosts follow {@link HostAppApi.getServiceEnv} on
+ * the next launch. The mutable service environment is
+ * {@link HostAppApi.toggleServiceEnv}. It is **not** the
  * lxapp publish channel (`LxAppEnvVersion` / `LxAppReleaseType`:
  * `'release' | 'draft'`). Default channel is derived
  * from env (`dev` → `draft`, `prod` → `release`) and can be
@@ -2757,7 +2768,7 @@ export type WindowsTerminalInlineImageStatus = {
 export interface AppBaseInfo {
   /**
    * Platform family: `"iOS"` / `"macOS"` / `"Android"` / `"Windows"` /
-   * `"Harmony"`. Matches the View-side `usePlatform().os` value.
+   * `"Harmony"`. Matches the View-side `useLxHost().os` value.
    */
   os: HostOs;
   productName: string;
@@ -2784,6 +2795,23 @@ export interface FileStats {
   createTime?: number;
 }
 
+export interface HostServiceEnvState {
+  buildEnv: HostAppEnv;
+  /** Environment this process is running; unchanged until the app restarts. */
+  serviceEnv: HostAppEnv;
+  /** Environment that will be used after closing and reopening the app. */
+  nextLaunchEnv: HostAppEnv;
+  available: HostAppEnv[];
+  canToggle: boolean;
+}
+
+export interface HostServiceEnvSwitchResult {
+  state: HostServiceEnvState;
+  exitRequested: boolean;
+  /** If present, the environment was saved; close and reopen the app manually. */
+  exitError?: string;
+}
+
 export interface ImageInfo {
   width: number;
   height: number;
@@ -2963,6 +2991,15 @@ declare global {
      * restricted to the Control app, like the other host-level APIs on `lx.host`.
      */
     screenshot(options?: AppScreenshotOptions): Promise<AppScreenshotResult>;
+    /** Query the running and next-launch service environments. Control app only. */
+    getServiceEnv(): HostServiceEnvState;
+    /**
+     * Save the other service environment for next launch and request exit.
+     * A dev build cannot switch. Control app only. Save failures throw before exit.
+     * If exitRequested is false, ask the user to close and reopen the app manually.
+     * Retrying before restart keeps the same target environment.
+     */
+    toggleServiceEnv(): HostServiceEnvSwitchResult;
     /**
      * Query whether the host app has an update.
      * This host-level capability is restricted to the Control app. A successful

package/src/index.ts

@@ -6,6 +6,7 @@
 
 export * from './generated/logic.js';
 export type { Automation } from './automation/index.js';
+export type { MockAnswer, MockContext, MockHandler, MockRequest, Mocks } from './mocks.js';
 export * from './error.js';
 export * from './generated/error.js';
 export * from './generated/i18n.js';
@@ -46,11 +47,16 @@ declare global {
 
   interface Lx {
     /**
-     * In-process UI/runtime automation.
+     * In-process UI/runtime automation, as app Logic may use it.
      *
-     * Select the current app with `.lxapp()` or a specific running app with
-     * `.lxapp(appid)`. Host-only surfaces enforce the `host` privilege when
-     * selected; `lingxia dev` and the Runner grant it implicitly.
+     * Select the calling app with `.lxapp()` (requires the `automation`
+     * privilege) or another running app with `.lxapp(appid)`; the host tiers
+     * (`lxapps`, `browser`, `shell`, `device`, `desktop`, `terminal`) require
+     * `host`, checked when the property is read. A privilege holds only when
+     * it is allowed for the app and the native host sealed a session grant
+     * for it; `lingxia dev` and the Runner do not widen that. Test-run-only
+     * members (`network`, nav `waitUntil: 'ready'`) belong to
+     * `HostRunAutomation`, the root of an `lxdev test` program.
      */
     automation(): Automation;
   }

package/src/mocks.ts

@@ -0,0 +1,62 @@
+/**
+ * Types for an lxapp's `mocks/index.ts`: the complete set of mock
+ * handlers, one per call the app makes, answered in development when the
+ * mock selection says so (`mocks/config.json`, `lingxia dev --mock`,
+ * `lxdev mock`). Import them type-only; mocks never ship:
+ *
+ * ```ts
+ * import type { Mocks } from '@lingxia/types/mocks';
+ *
+ * let signedIn = true; // module state: fresh on save, reset, restart and each spec
+ *
+ * export default {
+ *   'GET **\/devices': () => (signedIn ? { json: DEVICES } : { status: 401 }),
+ *   'DELETE **\/sessions/current': () => { signedIn = false; return { status: 204 }; },
+ *   'GET **\/legal': { json: [] },
+ * } satisfies Mocks;
+ * ```
+ */
+import type { NetworkRouteAnswer } from './automation/index.js';
+
+/**
+ * What a handler answers: exactly a route answer — `{ status?, headers?,
+ * json | body, contentType?, delay? }`, `{ abort: 'failed' }`,
+ * `{ hang: true }`, `{ sse: [...] }`, or `{ continue: true, patchJson? }`
+ * (the real backend answers). One answer per call: `sequence`, `times`,
+ * `match` and `bodyBase64` are scenario fields.
+ */
+export type MockAnswer = NetworkRouteAnswer;
+
+/** The call a handler answers. */
+export type MockRequest = {
+  /** Fetch cancellation when supplied; null otherwise (including SSE). */
+  signal: AbortSignal | null;
+  /** Upper-case. */
+  method: string;
+  url: URL;
+  /** What the app sent. */
+  headers: Headers;
+  /** The body as text; rejects for a stream, `Blob` or `FormData` body. */
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+};
+
+/** What a handler can use besides the request. */
+export type MockContext = {
+  /** The original `fetch`, not intercepted: proxy without recursing. */
+  fetch: typeof fetch;
+};
+
+/**
+ * Answers one call. Throwing, returning `undefined` or an invalid answer
+ * fails the request (`TypeError: fetch failed`); it never falls through to
+ * the real backend.
+ */
+export type MockHandler = (req: MockRequest, ctx: MockContext) => MockAnswer | Promise<MockAnswer>;
+
+/**
+ * The default export of `mocks/index.ts`: keys are HTTP targets
+ * (`'GET **\/devices/*'`, `'* **\/x'`, `'POST /regex/'`), tried in order;
+ * values are answers or handlers.
+ */
+export type Mocks = Record<string, MockAnswer | MockHandler>;

package/src/page.ts

@@ -0,0 +1,26 @@
+/**
+ * `T` where every value survives the JSON transfer `setData` makes to the
+ * View; a function, Date, Map, Set, promise or class instance becomes
+ * `never`, so a contract holding one does not compile. `undefined` members
+ * are allowed: the transfer drops them, as an optional member reads.
+ */
+export type JsonData<T> =
+  0 extends 1 & T ? any
+    : unknown extends T ? unknown
+    : T extends string | number | boolean | null | undefined ? T
+    : T extends (...args: never[]) => unknown ? never
+    : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | PromiseLike<unknown> | symbol | bigint ? never
+    : T extends readonly unknown[] ? { [K in keyof T]: JsonData<T[K]> }
+    : T extends object ? { [K in keyof T]: JsonData<T[K]> }
+    : never;
+
+/**
+ * A shared, type-only page contract: the page's `data` and public actions,
+ * written once and used by Logic, View and tests. Importing it installs no
+ * Logic globals. `Data` must be JSON (see `JsonData`); otherwise the
+ * contract has no `data`, and every use of it names the problem.
+ */
+export type PageContract<Data = unknown, Actions = unknown> =
+  [Data] extends [JsonData<Data>]
+    ? { readonly data: Data; readonly actions: Actions }
+    : { readonly __pageDataMustBeJson: "PageContract data must be JSON: no functions, Dates, Maps, Sets or class instances" };

package/src/testing/public-api.ts

@@ -2,6 +2,8 @@ import type {
   Automation,
   BrowserCookies,
   BrowserDriver,
+  ClockDriver,
+  DialogDriver,
   DesktopApp,
   DesktopAx,
   DesktopClipboard,
@@ -14,8 +16,13 @@ import type {
   DeviceDriver,
   LxAppDriver,
   LxAppManager,
+  MockDriver,
   NavDriver,
+  NetworkDriver,
+  NetworkRoute,
+  Scenario,
   PageDriver,
+  ProfileDriver,
   PageKey,
   PagePointer,
   ShellDriver,
@@ -144,9 +151,11 @@ const HOST_APP_API = [
   'env',
   'exit',
   'getBaseInfo',
+  'getServiceEnv',
   'notification',
   'screenshot',
   'setBadge',
+  'toggleServiceEnv',
 ] as const;
 // `autostart`, `banner`, `control`, `cache`, and `notification` are injected
 // only where they apply, so a runtime walk of `lx.host` must not require them.
@@ -239,7 +248,24 @@ const AUTOMATION_API = [
 ] as const;
 const SHELL_DRIVER_API = ['pins', 'setPin', 'reorderPins'] 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_DRIVER_API = ['clock', 'dialogs', 'eval', 'info', 'mock', 'nav', 'network', 'page', 'pages', 'profile', 'surfaceLayout'] as const;
+const MOCK_DRIVER_API = ['reset', 'use'] as const;
+const CLOCK_DRIVER_API = ['install', 'runAll', 'setSystemTime', 'tick', 'uninstall'] as const;
+const DIALOG_DRIVER_API = [
+  'actionSheets',
+  'answerNextActionSheet',
+  'answerNextModal',
+  'modals',
+  'setAnswerMode',
+  'toasts',
+  'unanswered',
+  'unwatch',
+  'watch',
+] as const;
+const PROFILE_DRIVER_API = ['checkpoint', 'drop', 'restore'] as const;
+const NETWORK_DRIVER_API = ['captureResponses', 'requests', 'responses', 'route', 'unrouteAll'] as const;
+const NETWORK_ROUTE_API = ['id', 'pattern', 'requests', 'requestsAfter', 'unroute'] as const;
+const SCENARIO_API = ['calls', 'callsAfter', 'name', 'rules', 'unroute', 'variant'] as const;
 const LXAPP_MANAGER_API = [
   'applink',
   'close',
@@ -252,6 +278,7 @@ const LXAPP_MANAGER_API = [
   'windows',
 ] as const;
 const PAGE_DRIVER_API = [
+  'action',
   'click',
   'eval',
   'fill',
@@ -542,8 +569,9 @@ export const LX_RUNTIME_SURFACES = [
     layer: 'automation',
     expression: 'lx.automation().lxapp()',
     members: LXAPP_DRIVER_API,
-    properties: ['nav', 'page'],
+    properties: ['clock', 'dialogs', 'mock', 'nav', 'network', 'page', 'profile'],
   },
+  { name: 'MockDriver', layer: 'automation', expression: 'lx.automation().lxapp().mock', members: MOCK_DRIVER_API },
   {
     name: 'PageDriver',
     layer: 'automation',
@@ -554,6 +582,44 @@ export const LX_RUNTIME_SURFACES = [
   { name: 'PagePointer', layer: 'automation', expression: 'lx.automation().lxapp().page.pointer', members: PAGE_POINTER_API },
   { name: 'PageKey', layer: 'automation', expression: 'lx.automation().lxapp().page.key', members: PAGE_KEY_API },
   { name: 'NavDriver', layer: 'automation', expression: 'lx.automation().lxapp().nav', members: NAV_DRIVER_API },
+  {
+    name: 'NetworkDriver',
+    layer: 'automation',
+    expression: 'lx.automation().lxapp().network',
+    members: NETWORK_DRIVER_API,
+  },
+  {
+    name: 'ProfileDriver',
+    layer: 'automation',
+    expression: 'lx.automation().lxapp().profile',
+    members: PROFILE_DRIVER_API,
+  },
+  {
+    name: 'ClockDriver',
+    layer: 'automation',
+    expression: 'lx.automation().lxapp().clock',
+    members: CLOCK_DRIVER_API,
+  },
+  {
+    name: 'DialogDriver',
+    layer: 'automation',
+    expression: 'lx.automation().lxapp().dialogs',
+    members: DIALOG_DRIVER_API,
+  },
+  {
+    name: 'NetworkRoute',
+    layer: 'automation',
+    expression: 'lx.automation().lxapp().network.route()',
+    members: NETWORK_ROUTE_API,
+    properties: ['id', 'pattern'],
+  },
+  {
+    name: 'Scenario',
+    layer: 'automation',
+    expression: 'lx.automation().lxapp().mock.use()',
+    members: SCENARIO_API,
+    properties: ['name', 'rules', 'variant'],
+  },
   { name: 'LxAppManager', layer: 'automation', expression: 'lx.automation().lxapps', members: LXAPP_MANAGER_API },
   { name: 'DeviceDriver', layer: 'automation', expression: 'lx.automation().device', members: DEVICE_DRIVER_API },
   {
@@ -795,6 +861,13 @@ export type LxApiManifestGate = [
   AssertTrue<Exact<PagePointer, typeof PAGE_POINTER_API>>,
   AssertTrue<Exact<PageKey, typeof PAGE_KEY_API>>,
   AssertTrue<Exact<NavDriver, typeof NAV_DRIVER_API>>,
+  AssertTrue<Exact<NetworkDriver, typeof NETWORK_DRIVER_API>>,
+  AssertTrue<Exact<NetworkRoute, typeof NETWORK_ROUTE_API>>,
+  AssertTrue<Exact<Scenario, typeof SCENARIO_API>>,
+  AssertTrue<Exact<MockDriver, typeof MOCK_DRIVER_API>>,
+  AssertTrue<Exact<ProfileDriver, typeof PROFILE_DRIVER_API>>,
+  AssertTrue<Exact<ClockDriver, typeof CLOCK_DRIVER_API>>,
+  AssertTrue<Exact<DialogDriver, typeof DIALOG_DRIVER_API>>,
   AssertTrue<Exact<DeviceDriver, typeof DEVICE_DRIVER_API>>,
   AssertTrue<Exact<BrowserDriver, typeof BROWSER_DRIVER_API>>,
   AssertTrue<Exact<BrowserCookies, typeof BROWSER_COOKIES_API>>,

package/dist/automation-test-globals.d.ts

@@ -1,14 +0,0 @@
-/// <reference path="./logic-globals.d.ts" />
-
-import type { Automation } from './automation/index.js';
-
-/** Globals exposed by the `lxdev test` JavaScript runtime. */
-interface AutomationTestLx {
-  automation(): Automation;
-}
-
-declare global {
-  const lx: AutomationTestLx;
-}
-
-export {};