@lingxia/bridge 0.18.0 → 0.19.0

package/dist/es5/surface-context.js

@@ -0,0 +1,135 @@
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+/** What a host that sends nothing — one older than this API — is taken to say. */
+var UNREPORTED = { sizeClass: 'compact', width: 0, height: 0, aside: false };
+/**
+ * One store per document, on `window`, for the same reason as the display
+ * language: the bridge module is present twice in a page, and the host must
+ * reach the copy the framework hooks read.
+ */
+function store() {
+    var _a;
+    if (typeof window === 'undefined')
+        return fallbackStore;
+    if (!window.__lxSurfaceContext) {
+        // Seeded by the host in this document's bridge config, before any script.
+        var config = window.__LX_BRIDGE_CFG;
+        window.__lxSurfaceContext = {
+            value: (_a = parse(config === null || config === void 0 ? void 0 : config.surfaceContext)) !== null && _a !== void 0 ? _a : UNREPORTED,
+            revision: typeof (config === null || config === void 0 ? void 0 : config.surfaceContextRevision) === 'number' ? config.surfaceContextRevision : 0,
+            listeners: new Set(),
+        };
+    }
+    return window.__lxSurfaceContext;
+}
+var fallbackStore = { value: UNREPORTED, revision: 0, listeners: new Set() };
+function parse(next) {
+    if (typeof next !== 'object' || next === null)
+        return null;
+    var _a = next, sizeClass = _a.sizeClass, width = _a.width, height = _a.height, aside = _a.aside;
+    if (sizeClass !== 'compact' && sizeClass !== 'regular')
+        return null;
+    if (typeof width !== 'number' || typeof height !== 'number')
+        return null;
+    return { sizeClass: sizeClass, width: width, height: height, aside: aside === true };
+}
+function same(a, b) {
+    return a.sizeClass === b.sizeClass
+        && a.width === b.width
+        && a.height === b.height
+        && a.aside === b.aside;
+}
+/**
+ * Host entry point: once the page's bridge is up, and on every change. Pushes
+ * can run out of order across host threads, so each carries a revision and an
+ * older one than the store holds is dropped.
+ */
+function applySurfaceContext(next, revision) {
+    var e_1, _a;
+    var context = parse(next);
+    var current = store();
+    if (!context)
+        return;
+    if (typeof revision === 'number') {
+        if (revision <= current.revision)
+            return;
+        current.revision = revision;
+    }
+    if (same(current.value, context))
+        return;
+    // A new object per change, so `useSyncExternalStore` sees it changed.
+    current.value = context;
+    try {
+        for (var _b = __values(__spreadArray([], __read(current.listeners), false)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var listener = _c.value;
+            listener();
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+}
+if (typeof window !== 'undefined' && !window.__lingxiaApplySurfaceContext) {
+    Object.defineProperty(window, '__lingxiaApplySurfaceContext', {
+        configurable: false,
+        enumerable: false,
+        value: applySurfaceContext,
+    });
+}
+/**
+ * The lxapp's adaptive context. The host seeds it into every page before any
+ * script runs and pushes each change, so there is always a value; a host older
+ * than this API reports `compact` with a 0×0 viewport.
+ */
+export function getSurfaceContext() {
+    return store().value;
+}
+/**
+ * Follow the adaptive context. Change-only, like `subscribeDisplayLanguage`,
+ * so it composes with `useSyncExternalStore`. Returns an unsubscribe.
+ */
+export function subscribeSurfaceContext(listener) {
+    var listeners = store().listeners;
+    listeners.add(listener);
+    return function () {
+        listeners.delete(listener);
+    };
+}

package/dist/host.d.ts

@@ -0,0 +1,33 @@
+import { type PlatformOS } from './runtime-env';
+/**
+ * What the host decided for this page: the facts a View picks its layout and
+ * copy from. Every field changes rarely or never, so reading them costs a
+ * re-render only when one of them actually changes — never while a window is
+ * dragged. Measured geometry belongs to CSS (`--lx-page-chrome-*`, container
+ * queries), not here.
+ */
+export interface LxHost {
+    /** `compact` (< 600 logical px) or `regular`, with hysteresis; the same value Logic's `lx.surface.watchContext()` reports. */
+    readonly sizeClass: 'compact' | 'regular';
+    /** Whether the host layout currently offers a docked aside. */
+    readonly aside: boolean;
+    /** The BCP-47 tag in effect, as Logic's `lx.host.displayLanguage.get()`. */
+    readonly displayLanguage: string;
+    /** Which kind of machine this is; fixed for the document. A narrowed desktop window is still `desktop`. */
+    readonly formFactor: 'mobile' | 'desktop';
+    /** The operating system, for the rare OS-specific feature; not a layout fact. */
+    readonly os: PlatformOS;
+    /** Whether the page runs in the LingXia Runner (the `lingxia dev` simulator). */
+    readonly runner: boolean;
+}
+/**
+ * The host facts for this page. The same object is returned until a field
+ * changes, so it composes with `useSyncExternalStore` and with memoization.
+ */
+export declare function getHost(): LxHost;
+/**
+ * Follow the host facts. Change-only: the listener runs when a field of
+ * `getHost()` changes — not on subscribe, and not when only the viewport's
+ * size moves within its size class. Returns an unsubscribe.
+ */
+export declare function subscribeHost(listener: () => void): () => void;

package/dist/index.d.ts

@@ -8,6 +8,6 @@
 export type { BridgeConfig, CallOptions, ChannelCloseEvent, ChannelOptions, ChannelOpenOptions, BridgeErrorCode, ChannelEventName, DataSubscriber, ErrorInfo, LingXiaBridgeInterface, LxChannel, LxBridgeError, LxMethod, LxMethodParams, LxMethodResult, LxMethodStreamData, LxStream, NativeComponentMessage, NativeChannel, NativeError, NativeStream, NotifyOptions, InvokeOptions, StateInfo, StreamCallOptions, StreamOptions, StreamEventName, } from './types';
 export { LingXiaBridge, channel, initBridge, invoke, notify, stream, } from './bridge';
 export { isNativeError } from './invocation';
-export { getDisplayLanguage, subscribeDisplayLanguage } from './runtime-env';
-export { renderErrorUI, hasError, getErrorInfo } from './error';
+export { getHost, subscribeHost, type LxHost } from './host';
+export { renderErrorUI, renderPageFault, hasError, getErrorInfo } from './error';
 export { boot, bootWhenReady } from './boot';

package/dist/invocation.d.ts

@@ -1,6 +1,17 @@
 import type { LxBridgeError, LxChannel, LxStream } from "./types";
 export type ParamsSource<T> = T | (() => T);
-export type MethodParams<TMethod> = TMethod extends () => any ? undefined : TMethod extends (params: infer P) => any ? P : never;
+/** The one payload a method takes: `undefined` for none, `P | undefined` when optional. */
+export type MethodParams<TMethod> = TMethod extends (...args: infer A) => any ? A extends [] ? undefined : A extends [infer P] ? P : A extends [(infer P)?] ? P | undefined : never : never;
+/** Whether calling `TMethod` needs its payload. */
+export type RequiresParams<TMethod> = TMethod extends (...args: infer A) => any ? [] extends A ? false : true : never;
+/** `params`, required exactly when the method requires its payload. */
+export type ParamsOption<TMethod, TSource> = RequiresParams<TMethod> extends true ? {
+    params: TSource;
+} : {
+    params?: TSource;
+};
+/** A hook's options argument: required when `params` is. */
+export type OptionsArg<TMethod, TOptions> = RequiresParams<TMethod> extends true ? [options: TOptions] : [options?: TOptions];
 export type StreamData<TMethod> = TMethod extends (...args: any[]) => LxStream<infer TData, any> ? TData : never;
 export type StreamResult<TMethod> = TMethod extends (...args: any[]) => LxStream<any, infer TResult> ? TResult : never;
 export type ChannelIn<TMethod> = TMethod extends (...args: any[]) => Promise<LxChannel<infer TIn, any>> ? TIn : never;

package/dist/runtime-env.d.ts

@@ -2,6 +2,8 @@ import type { BridgeConfig } from './types';
 export type CommunicationMethod = 'messageport' | 'jsinterface' | 'webmessage' | 'webkit' | 'unknown';
 export type PlatformOS = NonNullable<BridgeConfig['os']> | 'unknown';
 export declare const BRIDGE_CONFIG: BridgeConfig;
+/** The writing direction of a BCP-47 tag. */
+export declare function textDirection(tag: string): 'ltr' | 'rtl';
 export declare function getDisplayLanguage(): string;
 /**
  * Subscribe to host display-language changes. Returns an unsubscribe.

package/dist/surface-context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The lxapp's adaptive context, from the host: the same value Logic's
+ * `lx.surface.watchContext()` delivers, so a View picks its layout without
+ * Logic forwarding it through `setData`. It describes the lxapp's main
+ * presentation; a page shown in an aside, float or window sees the same value.
+ */
+export interface SurfaceContext {
+    /** `compact` (< 600 logical px) or `regular`, with hysteresis. */
+    sizeClass: 'compact' | 'regular';
+    /** The presentation's viewport width in logical pixels; 0 until measured. */
+    width: number;
+    /** The presentation's viewport height in logical pixels; 0 until measured. */
+    height: number;
+    /** Whether the host layout currently offers a docked aside. */
+    aside: boolean;
+}
+/**
+ * The lxapp's adaptive context. The host seeds it into every page before any
+ * script runs and pushes each change, so there is always a value; a host older
+ * than this API reports `compact` with a 0×0 viewport.
+ */
+export declare function getSurfaceContext(): SurfaceContext;
+/**
+ * Follow the adaptive context. Change-only, like `subscribeDisplayLanguage`,
+ * so it composes with `useSyncExternalStore`. Returns an unsubscribe.
+ */
+export declare function subscribeSurfaceContext(listener: () => void): () => void;

package/dist/types.d.ts

@@ -8,6 +8,10 @@ export interface BridgeConfig {
     hostClass?: 'mobile' | 'desktop';
     /** Effective host display language; distinct from the raw system locale. */
     displayLanguage?: string;
+    /** The lxapp's adaptive context when this document was built; see `surface-context.ts`. */
+    surfaceContext?: unknown;
+    /** The host revision of `surfaceContext`, so a later push can supersede it. */
+    surfaceContextRevision?: number;
     nonce?: string;
     appleDownstreamURL?: string;
     dev?: boolean;
@@ -137,10 +141,19 @@ declare global {
     interface Window {
         __LX_BRIDGE_CFG?: BridgeConfig;
         /** Host push for a display language changed while the page is open. */
-        __lingxiaApplyDisplayLanguage?: (language: string) => void;
+        __lingxiaApplyDisplayLanguage?: (language: string, revision?: number) => void;
         /** Shared by every copy of the bridge module in this document. */
         __lxDisplayLanguage?: {
             value: string;
+            revision?: number;
+            listeners: Set<() => void>;
+        };
+        /** Host push for the page's adaptive context; see `surface-context.ts`. */
+        __lingxiaApplySurfaceContext?: (context: unknown, revision?: unknown) => void;
+        /** Shared by every copy of the bridge module in this document. */
+        __lxSurfaceContext?: {
+            value: import('./surface-context').SurfaceContext;
+            revision: number;
             listeners: Set<() => void>;
         };
         __LX_BRIDGE_INIT_STATE?: 'initializing' | 'initialized';
@@ -192,10 +205,10 @@ export interface LingXiaBridgeInterface {
         proto: boolean;
         all: boolean;
     };
-    displayLanguage: {
-        get(): string;
+    host: {
+        get(): import('./host').LxHost;
         /** Change-only; read the current value with `get()`. */
-        subscribe(listener: (language: string) => void): () => void;
+        subscribe(listener: () => void): () => void;
     };
     platform: {
         isHarmony(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingxia/bridge",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "private": false,
   "description": "LingXia Web Runtime - Bridge, boot, and error handling for WebView",
   "repository": {
@@ -40,7 +40,7 @@
     "build:modules:es5": "tsc -p tsconfig.modules.legacy.json",
     "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
     "build:v3-test": "tsc -p tsconfig.v3-test.json",
-    "test": "npm run build:es2020 && npm run build:es5 && npm run build:v3-test && node ./test-support/test-protocol-v3.mjs && node ./test-support/test-bridge-required-v3.mjs && node ./test-support/test-control-bootstrap.mjs",
+    "test": "npm run build:es2020 && npm run build:es5 && npm run build:v3-test && node ./test-support/test-protocol-v3.mjs && node ./test-support/test-bridge-required-v3.mjs && node ./test-support/test-control-bootstrap.mjs && npm run build:modules:es2020 && node ./test-support/test-surface-context.mjs && rolldown test-support/host-entry.ts --file dist/test/host.mjs --format esm && node ./test-support/test-host.mjs",
     "dev": "rolldown -c -w",
     "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
     "prepublishOnly": "npm run build"