@lingxia/bridge 0.15.0 → 0.16.0

package/dist/es2020/bridge.js

@@ -1,7 +1,8 @@
 import { BRIDGE_ERROR } from "./types";
 import { toBridgeError, toNativeError } from "./invocation";
 import { installNativeComponentCoverageMonitor } from "./nativecomponents/coverage-monitor";
-import { BRIDGE_CONFIG, getCommunicationMethod, getPlatformOS, isAndroid, isHarmony, isIOS, isMacOS, isWindows, isDesktop, isMobile, isApple, isDevSession, isRunner, } from "./runtime-env";
+import { consumeV3Bootstrap, } from "./protocol-v3";
+import { BRIDGE_CONFIG, getCommunicationMethod, getDisplayLanguage, getPlatformOS, subscribeDisplayLanguage, isAndroid, isHarmony, isIOS, isMacOS, isWindows, isDesktop, isMobile, isApple, isDevSession, isRunner, } from "./runtime-env";
 const NATIVE_HANDLER_NAME = "LingXia";
 const GLOBAL_RECEIVER_NAME = "__LingXiaRecvMessage";
 const DEFAULT_TIMEOUT_MS = 5000;
@@ -15,8 +16,28 @@ const OUTBOX_LIMIT = 256;
 const APPLE_DOWNSTREAM_URL = BRIDGE_CONFIG.appleDownstreamURL;
 const APPLE_RECONNECT_BASE_MS = 200;
 const APPLE_RECONNECT_MAX_MS = 2000;
+const BOUND_CONSOLE_MESSAGE_CHARS = 12 * 1024;
+// Native drops a larger frame before it reaches the bridge, so a request that
+// exceeds this would otherwise only surface as a timeout. Mirrors
+// MAX_WEB_MESSAGE_BYTES in the webview crate.
+const MAX_NATIVE_MESSAGE_BYTES = 64 * 1024;
+// Keep framework diagnostics and console forwarding on the original methods.
+// RequiredV3 installs a page-facing wrapper later; using it here would recurse
+// and could accidentally serialize the bound envelope into another log.
+const nativeConsole = {
+    log: console.log.bind(console),
+    warn: console.warn.bind(console),
+    error: console.error.bind(console),
+    info: (console.info || console.log).bind(console),
+    debug: (console.debug || console.log).bind(console),
+    group: (console.group || console.log).bind(console),
+    groupEnd: (console.groupEnd || (() => { })).bind(console),
+};
 const debugFlags = { data: false, proto: false, all: false };
 const earlyNativeMessages = [];
+// Fixed once, during init. The V3 secret remains captured only by the codec.
+let protocolMode = { kind: "v2" };
+let protocolInitialized = false;
 // Plain-object equivalent of `new Proxy(debugFlags, ...)`. Avoids referencing
 // the `Proxy` global so the module loads on older WebViews (Android 5.x stock
 // WebView is Chromium 37–39, which predates Chromium 49's Proxy support).
@@ -31,25 +52,50 @@ function createDebugObject(flags) {
             },
             set(value) {
                 flags[key] = !!value;
-                console.log(`[LX] ${key}: ${value}`);
+                nativeConsole.log(`[LX] ${key}: ${value}`);
             },
         });
     });
     return target;
 }
+function drainHostEarlyNativeMessages() {
+    if (typeof window === "undefined")
+        return;
+    const hostQueue = window.__LingXiaEarlyNativeMessages;
+    if (!Array.isArray(hostQueue) || hostQueue.length === 0)
+        return;
+    window.__LingXiaEarlyNativeMessages = [];
+    for (const message of hostQueue) {
+        if (typeof message === "string") {
+            earlyNativeMessages.push(message);
+        }
+    }
+}
 function installEarlyReceiver() {
     if (typeof window === "undefined")
         return;
-    if (typeof window[GLOBAL_RECEIVER_NAME] === "function")
+    drainHostEarlyNativeMessages();
+    const existing = window[GLOBAL_RECEIVER_NAME];
+    if (typeof existing === "function") {
+        if (earlyNativeMessages.length === 0)
+            return;
+        const queued = earlyNativeMessages.splice(0, earlyNativeMessages.length);
+        for (const message of queued) {
+            try {
+                existing(message);
+            }
+            catch (err) {
+                warn("Failed to replay queued native message:", err);
+            }
+        }
         return;
+    }
     window[GLOBAL_RECEIVER_NAME] = (message) => {
         earlyNativeMessages.push(message);
     };
 }
-function activateReceiver(receiver) {
-    if (typeof window === "undefined")
-        return;
-    window[GLOBAL_RECEIVER_NAME] = receiver;
+function flushEarlyNativeMessages(receiver) {
+    drainHostEarlyNativeMessages();
     if (earlyNativeMessages.length === 0)
         return;
     const queued = earlyNativeMessages.splice(0, earlyNativeMessages.length);
@@ -62,6 +108,17 @@ function activateReceiver(receiver) {
         }
     }
 }
+function activateReceiver(receiver) {
+    if (typeof window === "undefined")
+        return;
+    // Drain the inject-script queue on every inbound call so late
+    // `__LingXiaEarlyNativeMessages` items flush without rebinding.
+    window[GLOBAL_RECEIVER_NAME] = (message) => {
+        flushEarlyNativeMessages(receiver);
+        receiver(message);
+    };
+    flushEarlyNativeMessages(receiver);
+}
 function isDebugEnabled(flag) {
     return debugFlags.all || debugFlags[flag];
 }
@@ -77,13 +134,13 @@ function log(...args) {
         !debugFlags.data) {
         return;
     }
-    console.log(LOG_PREFIX, ...args);
+    nativeConsole.log(LOG_PREFIX, ...args);
 }
 function warn(...args) {
-    console.warn(LOG_PREFIX, ...args);
+    nativeConsole.warn(LOG_PREFIX, ...args);
 }
 function error(...args) {
-    console.error(LOG_PREFIX, ...args);
+    nativeConsole.error(LOG_PREFIX, ...args);
 }
 function safeStringify(obj, space) {
     const seen = new WeakSet();
@@ -132,7 +189,15 @@ let appleLastFrameSeq = 0;
 // than a couple of heartbeats means the connection is silently dead and we
 // reconnect proactively instead of waiting for a read error that may never come.
 const APPLE_DOWNSTREAM_STALE_MS = 35000;
+// A downstream that has never delivered a frame gets this long to connect.
+const APPLE_DOWNSTREAM_CONNECT_TIMEOUT_MS = 10000;
 let appleLastFrameAt = 0;
+let appleDownstreamAttemptAt = 0;
+// Names this page load to the host transport, so a reloaded document never
+// resumes the sequence of the one it replaced.
+const APPLE_DOWNSTREAM_DOCUMENT = `${Date.now().toString(36)}${Math.random()
+    .toString(36)
+    .slice(2, 10)}`;
 let appleWatchdogTimer = null;
 const portInitState = {
     listenerInstalled: false,
@@ -217,7 +282,9 @@ function rejectAllPendingForTransport(reason) {
 }
 function resetHandshakeState(reason, rejectPending) {
     clearHandshakeTimer();
-    handshakeSessionId = null;
+    if (protocolMode.kind !== "required-v3")
+        handshakeSessionId = null;
+    helloAcknowledged = false;
     handshakeDone = false;
     helloSent = false;
     handshakeRetryCount = 0;
@@ -284,7 +351,8 @@ async function runAppleDownstream() {
     appleDownstreamAbortController = controller;
     // Resume from the last frame we saw so the host replays the gap on reconnect.
     const separator = APPLE_DOWNSTREAM_URL.includes("?") ? "&" : "?";
-    const url = `${APPLE_DOWNSTREAM_URL}${separator}from=${appleLastFrameSeq}`;
+    const url = `${APPLE_DOWNSTREAM_URL}${separator}from=${appleLastFrameSeq}&doc=${APPLE_DOWNSTREAM_DOCUMENT}`;
+    appleDownstreamAttemptAt = Date.now();
     const response = await fetch(url, {
         method: "GET",
         cache: "no-store",
@@ -430,8 +498,18 @@ function startAppleWatchdog() {
     appleWatchdogTimer = setInterval(() => {
         // No `connected` guard: a reconnect that hung before delivering a frame
         // also goes stale, and forcing a reconnect aborts and retries it.
-        if (appleLastFrameAt === 0)
+        if (appleLastFrameAt === 0) {
+            // The first downstream has produced nothing yet. A fetch whose response
+            // never arrives raises no error, and a page that stays in-window (under
+            // a splash, say) never sees the visibility handler either.
+            if (appleDownstreamTask &&
+                appleDownstreamAttemptAt !== 0 &&
+                Date.now() - appleDownstreamAttemptAt > APPLE_DOWNSTREAM_CONNECT_TIMEOUT_MS) {
+                warn("Apple downstream did not connect, forcing reconnect");
+                forceDownstreamReconnect();
+            }
             return;
+        }
         if (Date.now() - appleLastFrameAt > APPLE_DOWNSTREAM_STALE_MS) {
             warn("Apple downstream stale (no heartbeat), forcing reconnect");
             forceDownstreamReconnect();
@@ -477,43 +555,114 @@ function getMessagePort() {
     }
     return portInitState.promise;
 }
+function encodeForNative(message) {
+    if (protocolMode.kind === "blocked")
+        return null;
+    if (protocolMode.kind === "v2")
+        return message;
+    if (!message || typeof message !== "object")
+        return null;
+    const { v: _v, kind, ...payload } = message;
+    if (typeof kind !== "string")
+        return null;
+    const encoded = protocolMode.codec.encode(kind, payload);
+    return encoded.ok ? encoded.value : null;
+}
 function postToNative(message) {
+    const encodedMessage = encodeForNative(message);
+    if (!encodedMessage)
+        return null;
     const kind = message.kind;
     if (kind === "req" || kind === "notify")
         log(`postToNative: ${kind} ${message.method}`);
     if (isDebugEnabled("proto"))
-        console.log("→", JSON.stringify(message, null, 2));
+        // Log the payload before RequiredV3 adds its document secret. The bound
+        // console wrapper posts what it prints, which would re-enter this function.
+        nativeConsole.log("→", JSON.stringify(message, null, 2));
     try {
+        const messageString = stringifyForNative(encodedMessage);
+        const bytes = utf8ByteLength(messageString);
+        if (bytes > MAX_NATIVE_MESSAGE_BYTES) {
+            return {
+                code: BRIDGE_ERROR.MESSAGE_TOO_LARGE,
+                message: `Bridge message of ${bytes} bytes exceeds the ${MAX_NATIVE_MESSAGE_BYTES}-byte native limit`,
+            };
+        }
         if (communicationMethod === "webkit") {
-            window.webkit?.messageHandlers[NATIVE_HANDLER_NAME]?.postMessage(message);
-            return;
+            window.webkit?.messageHandlers[NATIVE_HANDLER_NAME]?.postMessage(messageString);
+            return null;
         }
-        const messageString = stringifyForNative(message);
         if (communicationMethod === MESSAGE_PORT_TYPE && messagePort) {
             messagePort.postMessage(messageString);
-            return;
+            return null;
         }
         if ((communicationMethod === JS_INTERFACE_TYPE ||
             communicationMethod === WEB_MESSAGE_TYPE) &&
             window.LingXiaProxy?.postMessage) {
             window.LingXiaProxy.postMessage(messageString);
-            return;
+            return null;
         }
         warn("Transport not ready");
     }
     catch (e) {
-        error("Send error:", e);
+        if (protocolMode.kind === "required-v3")
+            error("Send error");
+        else
+            error("Send error:", e);
+    }
+    return null;
+}
+function formatBoundConsoleMessage(args) {
+    const message = args
+        .map((arg) => {
+        if (typeof arg === "string")
+            return arg;
+        try {
+            const encoded = stringifyForNative(arg);
+            return typeof encoded === "string" ? encoded : String(arg);
+        }
+        catch {
+            return "[Unserializable]";
+        }
+    })
+        .join(" ");
+    return message.length <= BOUND_CONSOLE_MESSAGE_CHARS
+        ? message
+        : `${message.slice(0, BOUND_CONSOLE_MESSAGE_CHARS)}…`;
+}
+/**
+ * BrowserControl console is an authenticated auxiliary V3 frame. Platform
+ * console hooks are disabled for BrowserRelaxed WebViews, so this is the only
+ * path that can reach the native log delegate for a control document.
+ */
+function installBoundV3Console() {
+    if (protocolMode.kind !== "required-v3")
+        return;
+    const methods = ["log", "error", "warn", "info", "debug"];
+    for (const level of methods) {
+        const original = nativeConsole[level];
+        console[level] = (...args) => {
+            original(...args);
+            // Native repeats Active session, WebMessageContext, generation and rate
+            // checks. Avoid sending pre-handshake output that can never be admitted.
+            if (!handshakeDone)
+                return;
+            postToNative({
+                kind: "console",
+                __lingxia_console__: true,
+                level,
+                message: formatBoundConsoleMessage(args),
+            });
+        };
     }
 }
 // Handshake state
 let handshakeSessionId = null;
+let helloAcknowledged = false;
 let handshakeDone = false;
 let helloSent = false;
 let handshakeRetryCount = 0;
 let handshakeTimer = null;
-// Host method schema — populated from handshake `Ready` message.
-// Maps "namespace.method" → "call" | "stream".
-const hostMethodKinds = {};
 // Request tracking
 let requestCounter = 0;
 function createListenerBuckets() {
@@ -894,6 +1043,26 @@ function removeOutboxByReqId(reqId) {
     }
     return false;
 }
+// UTF-8 byte length without allocating a copy of the string.
+function utf8ByteLength(value) {
+    if (typeof TextEncoder === "function")
+        return new TextEncoder().encode(value).length;
+    let bytes = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff) {
+            bytes += 4;
+            i += 1;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
 function send(msg, reqId) {
     const kind = msg.kind;
     const isHandshake = kind === "hello" || kind === "helloAck" || kind === "ready";
@@ -913,7 +1082,16 @@ function send(msg, reqId) {
     }
     if (reqId)
         armPendingOperationTimer(reqId);
-    postToNative(msg);
+    reportPostFailure(postToNative(msg), reqId);
+}
+// An oversized frame is dropped by native without a reply, so the caller would
+// otherwise learn about it only when its request timed out.
+function reportPostFailure(failure, reqId) {
+    if (!failure)
+        return;
+    error(failure.message);
+    if (reqId)
+        rejectPendingOperation(reqId, failure);
 }
 function flushOutbox() {
     if (!canSendAppMessages())
@@ -924,7 +1102,7 @@ function flushOutbox() {
             continue;
         if (item.reqId)
             armPendingOperationTimer(item.reqId);
-        postToNative(item.msg);
+        reportPostFailure(postToNative(item.msg), item.reqId);
     }
 }
 function clearHandshakeTimer() {
@@ -936,6 +1114,10 @@ function clearHandshakeTimer() {
 function startHandshake() {
     if (handshakeDone)
         return;
+    if (!protocolInitialized)
+        return;
+    if (protocolMode.kind === "blocked")
+        return;
     if (!isTransportReady())
         return;
     clearHandshakeTimer();
@@ -944,7 +1126,7 @@ function startHandshake() {
         kind: "hello",
         nonce: BRIDGE_CONFIG.nonce || "",
         role: "view",
-        protocolsSupported: [2],
+        protocolsSupported: protocolMode.kind === "required-v3" ? [3] : [2],
     };
     helloSent = true;
     postToNative(hello);
@@ -981,6 +1163,27 @@ function startHandshake() {
     }, HANDSHAKE_TIMEOUT_MS);
 }
 function parseIncoming(msg) {
+    if (protocolMode.kind === "blocked")
+        return null;
+    if (protocolMode.kind === "required-v3") {
+        const frame = typeof msg === "string" ? msg : stringifyForNative(msg);
+        const parsed = protocolMode.codec.parse(frame);
+        if (!parsed.ok)
+            return null;
+        return {
+            v: 3,
+            kind: parsed.value.kind,
+            ...parsed.value.payload,
+        };
+    }
+    if (typeof msg === "string") {
+        try {
+            msg = JSON.parse(msg);
+        }
+        catch {
+            return null;
+        }
+    }
     if (!msg || typeof msg !== "object")
         return null;
     const v = msg.v;
@@ -1106,17 +1309,26 @@ function applySnapshotFromResult(result) {
     pageData = obj.state;
     stateRev = obj.rev;
     if (isDebugEnabled("data")) {
-        console.group("[LX] snapshot(res)");
-        console.log("rev:", stateRev, "state:", deepCopy(pageData));
-        console.groupEnd();
+        nativeConsole.group("[LX] snapshot(res)");
+        nativeConsole.log("rev:", stateRev, "state:", deepCopy(pageData));
+        nativeConsole.groupEnd();
     }
     notifyStateSubscribers(true);
     return true;
 }
 function handleIncomingMessage(msg) {
+    let candidate = msg;
+    if (protocolMode.kind === "v2" && typeof candidate === "string") {
+        try {
+            candidate = JSON.parse(candidate);
+        }
+        catch {
+            candidate = null;
+        }
+    }
     // Handle native component events (from Android NativeBridge.sendEventToView)
-    if (msg && typeof msg === "object") {
-        const obj = msg;
+    if (protocolMode.kind === "v2" && candidate && typeof candidate === "object") {
+        const obj = candidate;
         if (obj.type === "event" && obj.name === "nativecomponent" && obj.payload) {
             const payload = obj.payload;
             const componentId = payload.id ||
@@ -1135,30 +1347,46 @@ function handleIncomingMessage(msg) {
             return;
         }
     }
-    const message = parseIncoming(msg);
+    const message = parseIncoming(candidate);
     if (!message) {
-        warn("Invalid V2 message:", msg);
+        warn("Invalid bridge message");
         return;
     }
     switch (message.kind) {
         case "helloAck":
-            handshakeSessionId = message.sessionId;
+            if (message.protocol !== (protocolMode.kind === "required-v3" ? 3 : 2) ||
+                message.nonce !== (BRIDGE_CONFIG.nonce || "")) {
+                warn("Invalid helloAck");
+                return;
+            }
+            if (protocolMode.kind === "required-v3") {
+                helloAcknowledged = true;
+                return;
+            }
+            if (handshakeSessionId && message.sessionId !== handshakeSessionId) {
+                warn("sessionId mismatch");
+                return;
+            }
+            if (!handshakeSessionId)
+                handshakeSessionId = message.sessionId;
+            helloAcknowledged = true;
             return;
         case "ready":
-            if (handshakeSessionId && message.sessionId !== handshakeSessionId) {
+            if (!helloAcknowledged)
+                return;
+            if (protocolMode.kind === "v2" &&
+                handshakeSessionId &&
+                message.sessionId !== handshakeSessionId) {
                 warn("sessionId mismatch");
                 return;
             }
             clearHandshakeTimer();
             handshakeDone = true;
             handshakeRetryCount = 0;
-            if (message.hostMethods) {
-                for (const [k, v] of Object.entries(message.hostMethods)) {
-                    hostMethodKinds[k] = v;
-                }
+            if (isDebugEnabled("proto")) {
+                log("Handshake complete, host routes:", Object.keys(message.hostMethods || {}).length +
+                    (message.hostChannels || []).length);
             }
-            if (isDebugEnabled("proto"))
-                log("Handshake complete, hostMethods:", Object.keys(hostMethodKinds).length);
             flushOutbox();
             return;
         case "res": {
@@ -1216,9 +1444,9 @@ function handleIncomingMessage(msg) {
             pageData = message.state || {};
             stateRev = message.rev;
             if (isDebugEnabled("data")) {
-                console.group("[LX] snapshot");
-                console.log("rev:", stateRev, "state:", deepCopy(pageData));
-                console.groupEnd();
+                nativeConsole.group("[LX] snapshot");
+                nativeConsole.log("rev:", stateRev, "state:", deepCopy(pageData));
+                nativeConsole.groupEnd();
             }
             notifyStateSubscribers(true);
             return;
@@ -1238,9 +1466,9 @@ function handleIncomingMessage(msg) {
                 return;
             }
             if (isDebugEnabled("data")) {
-                console.group("[LX] patch");
-                console.log("rev:", stateRev, "ops:", message.ops);
-                console.groupEnd();
+                nativeConsole.group("[LX] patch");
+                nativeConsole.log("rev:", stateRev, "ops:", message.ops);
+                nativeConsole.groupEnd();
             }
             notifyStateSubscribers(false);
             if (message.ack)
@@ -1349,7 +1577,8 @@ function hasNativeComponentHandler() {
     if (typeof window === "undefined")
         return false;
     return !!(window.webkit?.messageHandlers?.NativeComponent ||
-        window.NativeComponentBridge?.postMessage);
+        window.NativeComponentBridge?.postMessage ||
+        window.LingXiaProxy?.nativeComponentUpdate);
 }
 function postNativeComponentMessage(message) {
     try {
@@ -1361,6 +1590,18 @@ function postNativeComponentMessage(message) {
             window.NativeComponentBridge.postMessage(stringifyForNative(message));
             return;
         }
+        const update = window.LingXiaProxy?.nativeComponentUpdate;
+        if (typeof update === "function") {
+            const componentId = message.id || "island";
+            const payload = stringifyForNative({ ...message, componentId });
+            try {
+                update.call(window.LingXiaProxy, payload);
+            }
+            catch {
+                update.call(window.LingXiaProxy, componentId, payload);
+            }
+            return;
+        }
     }
     catch (e) {
         error("NativeComponent send error:", e);
@@ -1594,16 +1835,7 @@ export const LingXiaBridge = {
         }
         messagePort = port;
         port.onmessage = (event) => {
-            let data = event.data;
-            if (typeof data === "string") {
-                try {
-                    data = JSON.parse(data);
-                }
-                catch {
-                    return;
-                }
-            }
-            handleIncomingMessage(data);
+            handleIncomingMessage(event.data);
         };
         // Some WebView MessagePort implementations (notably Android WebMessagePort)
         // require an explicit start() to begin dispatching onmessage events.
@@ -1615,15 +1847,16 @@ export const LingXiaBridge = {
         startHandshake();
     },
     _receiveEvaluateMessage(messageString) {
-        try {
-            if (messageString)
-                handleIncomingMessage(JSON.parse(messageString));
-        }
-        catch (e) {
-            error("Parse error:", e);
-        }
+        if (messageString)
+            handleIncomingMessage(messageString);
     },
     debug: createDebugObject(debugFlags),
+    // The host language, for documents that cannot bundle `@lingxia/bridge` —
+    // browser internal pages and plain-HTML lxapps load this runtime as a script.
+    displayLanguage: {
+        get: getDisplayLanguage,
+        subscribe: subscribeDisplayLanguage,
+    },
     platform: {
         isHarmony,
         isIOS,
@@ -1770,6 +2003,15 @@ export function initBridge() {
     }
     window.__LX_BRIDGE_INIT_STATE = "initializing";
     try {
+        if (!protocolInitialized) {
+            const activation = consumeV3Bootstrap();
+            protocolMode =
+                activation.kind === "required"
+                    ? { kind: "required-v3", codec: activation.codec }
+                    : { kind: activation.kind === "absent" ? "v2" : "blocked" };
+            protocolInitialized = true;
+        }
+        installBoundV3Console();
         log(`Method: ${communicationMethod}`);
         activateReceiver(LingXiaBridge._receiveEvaluateMessage);
         if (useAppleDownstreamTransport()) {
@@ -1779,7 +2021,15 @@ export function initBridge() {
         }
         else if (communicationMethod === MESSAGE_PORT_TYPE) {
             installMessagePortInitListener();
-            getMessagePort().catch((e) => warn("Port init failed:", e));
+            const tryPort = (attempt) => {
+                getMessagePort().catch((e) => {
+                    warn("Port init failed:", e);
+                    if (attempt < 3) {
+                        window.setTimeout(() => tryPort(attempt + 1), 500 * attempt);
+                    }
+                });
+            };
+            tryPort(1);
         }
         else if (communicationMethod === "webkit" ||
             communicationMethod === JS_INTERFACE_TYPE ||