@lingxia/bridge 0.10.0 → 0.11.1

package/dist/es2020/bridge.js

@@ -1,7 +1,7 @@
 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, } from "./runtime-env";
+import { BRIDGE_CONFIG, getCommunicationMethod, getPlatformOS, isAndroid, isHarmony, isIOS, isMacOS, isWindows, isDesktop, isApple, isDevSession, isRunner, } from "./runtime-env";
 const NATIVE_HANDLER_NAME = "LingXia";
 const GLOBAL_RECEIVER_NAME = "__LingXiaRecvMessage";
 const DEFAULT_TIMEOUT_MS = 5000;
@@ -65,7 +65,18 @@ function activateReceiver(receiver) {
 function isDebugEnabled(flag) {
     return debugFlags.all || debugFlags[flag];
 }
+// `log` is the bridge's own protocol/lifecycle trace. Native log capture
+// forwards whatever the page emits to `console`, so the bridge itself decides
+// whether to surface this framework chatter: only in a `lingxia dev` session
+// (or when a debug flag is set). Shipped apps stay quiet, leaving the captured
+// stream to the page's own output plus bridge warnings/errors.
 function log(...args) {
+    if (!isDevSession() &&
+        !debugFlags.all &&
+        !debugFlags.proto &&
+        !debugFlags.data) {
+        return;
+    }
     console.log(LOG_PREFIX, ...args);
 }
 function warn(...args) {
@@ -112,6 +123,17 @@ let appleDownstreamTask = null;
 let appleDownstreamAbortController = null;
 let appleReconnectTimer = null;
 let appleReconnectDelayMs = APPLE_RECONNECT_BASE_MS;
+let appleDownstreamDisposed = false;
+// Highest transport frame seq processed. Sent as `?from=` on reconnect so the
+// host replays the gap; survives reconnects so a WebKit-replaced stream resumes
+// without losing frames or tearing down the bridge session.
+let appleLastFrameSeq = 0;
+// Liveness tracking: the host heartbeats an idle connection, so a gap longer
+// 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;
+let appleLastFrameAt = 0;
+let appleWatchdogTimer = null;
 const portInitState = {
     listenerInstalled: false,
     promise: null,
@@ -155,6 +177,23 @@ function clearAppleReconnectTimer() {
         appleReconnectTimer = null;
     }
 }
+function disposeAppleDownstream(reason) {
+    if (!useAppleDownstreamTransport() || appleDownstreamDisposed)
+        return;
+    appleDownstreamDisposed = true;
+    clearAppleReconnectTimer();
+    if (appleWatchdogTimer !== null) {
+        clearInterval(appleWatchdogTimer);
+        appleWatchdogTimer = null;
+    }
+    if (typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", handleAppleVisibilityChange);
+    }
+    appleForcedReconnectPending = false;
+    appleDownstreamAbortController?.abort();
+    appleDownstreamConnected = false;
+    resetHandshakeState(reason, true);
+}
 function closeActiveChannelsFromTransport(reason) {
     for (const [id, channel] of Array.from(activeChannels.entries())) {
         activeChannels.delete(id);
@@ -196,7 +235,7 @@ function processAppleDownstreamBuffer(buffer) {
         if (!line)
             continue;
         try {
-            handleIncomingMessage(JSON.parse(line));
+            handleAppleDownstreamFrame(JSON.parse(line));
         }
         catch (e) {
             warn("Apple downstream parse error:", e, line);
@@ -204,13 +243,49 @@ function processAppleDownstreamBuffer(buffer) {
     }
     return remaining;
 }
+// Unwrap the transport envelope: {"lxff":seq,"m":<message>} carries a business
+// message with its frame seq; {"lxreset":true} means the host cannot replay our
+// resume point and we must re-handshake.
+function handleAppleDownstreamFrame(frame) {
+    if (!frame || typeof frame !== "object")
+        return;
+    // Any frame — data, heartbeat, or reset — proves the connection is alive.
+    appleLastFrameAt = Date.now();
+    const record = frame;
+    if (record.lxshutdown === true) {
+        disposeAppleDownstream("Apple downstream closed");
+        return;
+    }
+    if (record.lxhb !== undefined)
+        return; // heartbeat: liveness only, nothing to dispatch
+    if (record.lxreset === true) {
+        appleLastFrameSeq = 0;
+        resetHandshakeState("Apple downstream reset", true);
+        startHandshake();
+        return;
+    }
+    if (typeof record.lxff === "number") {
+        // Replayed frames after a reconnect can repeat the last-seen seq; ignore
+        // anything we have already processed so the session is not double-fed.
+        if (record.lxff <= appleLastFrameSeq)
+            return;
+        appleLastFrameSeq = record.lxff;
+        handleIncomingMessage(record.m);
+        return;
+    }
+    // Legacy/un-enveloped line (e.g. a bare keepalive); pass through.
+    handleIncomingMessage(frame);
+}
 async function runAppleDownstream() {
     if (!APPLE_DOWNSTREAM_URL) {
         throw new Error("Apple downstream URL is not configured");
     }
     const controller = new AbortController();
     appleDownstreamAbortController = controller;
-    const response = await fetch(APPLE_DOWNSTREAM_URL, {
+    // 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 response = await fetch(url, {
         method: "GET",
         cache: "no-store",
         headers: { Accept: "application/x-ndjson" },
@@ -219,11 +294,16 @@ async function runAppleDownstream() {
     if (!response.ok) {
         throw new Error(`Apple downstream HTTP ${response.status}`);
     }
+    if (response.headers.get("X-LingXia-Bridge-Shutdown") === "1") {
+        disposeAppleDownstream("Apple downstream closed");
+        return;
+    }
     if (!response.body) {
         throw new Error("Apple downstream response body unavailable");
     }
     appleDownstreamConnected = true;
     appleReconnectDelayMs = APPLE_RECONNECT_BASE_MS;
+    appleLastFrameAt = Date.now();
     if (isDebugEnabled("proto"))
         log("Apple downstream connected");
     startHandshake();
@@ -242,7 +322,7 @@ async function runAppleDownstream() {
         const tail = buffered.trim();
         if (tail) {
             try {
-                handleIncomingMessage(JSON.parse(tail));
+                handleAppleDownstreamFrame(JSON.parse(tail));
             }
             catch (e) {
                 warn("Apple downstream trailing parse error:", e, tail);
@@ -261,13 +341,17 @@ async function runAppleDownstream() {
         catch { }
     }
 }
-function scheduleAppleDownstreamReconnect(reason) {
-    if (!useAppleDownstreamTransport())
+function scheduleAppleDownstreamReconnect(reason, immediate = false) {
+    if (!useAppleDownstreamTransport() || appleDownstreamDisposed)
         return;
     clearAppleReconnectTimer();
-    const delay = appleReconnectDelayMs;
-    appleReconnectDelayMs = Math.min(appleReconnectDelayMs * 2, APPLE_RECONNECT_MAX_MS);
-    const message = `Apple downstream disconnected, retrying in ${delay}ms: ${reason}`;
+    const delay = immediate ? 0 : appleReconnectDelayMs;
+    if (!immediate) {
+        appleReconnectDelayMs = Math.min(appleReconnectDelayMs * 2, APPLE_RECONNECT_MAX_MS);
+    }
+    const message = immediate
+        ? `Apple downstream completed, reconnecting immediately: ${reason}`
+        : `Apple downstream disconnected, retrying in ${delay}ms: ${reason}`;
     if (delay <= APPLE_RECONNECT_BASE_MS) {
         log(message);
     }
@@ -280,12 +364,16 @@ function scheduleAppleDownstreamReconnect(reason) {
     }, delay);
 }
 function ensureAppleDownstream() {
-    if (!useAppleDownstreamTransport())
+    if (!useAppleDownstreamTransport() || appleDownstreamDisposed)
         return;
     if (appleDownstreamTask)
         return;
     clearAppleReconnectTimer();
+    let completedCleanly = false;
     appleDownstreamTask = runAppleDownstream()
+        .then(() => {
+        completedCleanly = true;
+    })
         .catch((e) => {
         if (appleDownstreamAbortController?.signal.aborted)
             return;
@@ -295,13 +383,72 @@ function ensureAppleDownstream() {
         const aborted = appleDownstreamAbortController?.signal.aborted ?? false;
         appleDownstreamTask = null;
         appleDownstreamAbortController = null;
-        const wasConnected = appleDownstreamConnected;
         appleDownstreamConnected = false;
-        resetHandshakeState("Apple downstream closed", wasConnected);
-        if (!aborted)
-            scheduleAppleDownstreamReconnect("stream closed");
+        // A dropped transport is not a dead session: reconnect resumes from the
+        // last seq and the host replays the gap, so the handshake and in-flight
+        // streams stay intact. Only a host-sent reset (handled on the frame path)
+        // or a real abort tears things down.
+        if (!aborted && !appleDownstreamDisposed) {
+            // Native intentionally completes bootstrap/replay responses to flush
+            // WebKit. Reconnect without the failure backoff so a live stream can
+            // catch up and settle onto a long-lived downstream.
+            scheduleAppleDownstreamReconnect("stream closed", completedCleanly);
+        }
     });
 }
+// Drop the current downstream and reconnect, exactly as WebKit does when it
+// replaces the streaming fetch. The reconnect carries the real `from=<lastSeq>`,
+// so nothing is lost. Driven by the staleness watchdog and the foreground
+// handler, and exposed as a dev hook for repro harnesses. A no-op off Apple.
+let appleForcedReconnectPending = false;
+function forceDownstreamReconnect() {
+    if (!useAppleDownstreamTransport() || appleDownstreamDisposed)
+        return;
+    // Coalesce a burst of triggers (rapid foreground toggles, repeated calls)
+    // into a single reconnect so they cannot stack concurrent fetches.
+    if (appleForcedReconnectPending)
+        return;
+    appleForcedReconnectPending = true;
+    const task = appleDownstreamTask;
+    appleDownstreamAbortController?.abort();
+    const reconnect = () => {
+        appleForcedReconnectPending = false;
+        ensureAppleDownstream();
+    };
+    if (task)
+        task.finally(reconnect);
+    else
+        reconnect();
+}
+// A silently dead connection (half-open socket) never surfaces a read error, so
+// poll for heartbeat staleness and reconnect when the host has gone quiet.
+function startAppleWatchdog() {
+    if (!useAppleDownstreamTransport() ||
+        appleDownstreamDisposed ||
+        appleWatchdogTimer !== null)
+        return;
+    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)
+            return;
+        if (Date.now() - appleLastFrameAt > APPLE_DOWNSTREAM_STALE_MS) {
+            warn("Apple downstream stale (no heartbeat), forcing reconnect");
+            forceDownstreamReconnect();
+        }
+    }, 5000);
+}
+// WebKit suspends/throttles a backgrounded webview and may tear the stream
+// down; reconnect the moment it returns so the UI is never left stale.
+function handleAppleVisibilityChange() {
+    if (document.visibilityState === "visible")
+        forceDownstreamReconnect();
+}
+function installAppleForegroundReconnect() {
+    if (!useAppleDownstreamTransport() || typeof document === "undefined")
+        return;
+    document.addEventListener("visibilitychange", handleAppleVisibilityChange);
+}
 function getMessagePort() {
     if (messagePort)
         return Promise.resolve(messagePort);
@@ -380,6 +527,9 @@ function createListenerBuckets() {
 function createStreamHandle(id, cancelFn) {
     const listeners = createListenerBuckets();
     let done = false;
+    // Only buffer for the async iterator; long-lived streams consumed via
+    // .on("data") would otherwise accumulate payloads forever.
+    let iteratorRequested = false;
     let resolveResult = () => { };
     let rejectResult = () => { };
     const pendingData = [];
@@ -401,6 +551,7 @@ function createStreamHandle(id, cancelFn) {
             return this;
         },
         [Symbol.asyncIterator]() {
+            iteratorRequested = true;
             return {
                 next() {
                     if (pendingData.length > 0) {
@@ -429,7 +580,7 @@ function createStreamHandle(id, cancelFn) {
             if (pendingReads.length > 0) {
                 pendingReads.shift().resolve({ done: false, value: payload });
             }
-            else {
+            else if (iteratorRequested) {
                 pendingData.push(payload);
             }
             for (const listener of listeners.data) {
@@ -483,6 +634,9 @@ function createChannel(id, sendFn, closeFn) {
     let open = false;
     let outboundSeq = 0;
     let closed = false;
+    // Only buffer for the async iterator or pre-first-listener replay;
+    // otherwise a listener-driven channel would accumulate payloads forever.
+    let iteratorRequested = false;
     const pendingData = [];
     const pendingReads = [];
     const channel = {
@@ -523,6 +677,7 @@ function createChannel(id, sendFn, closeFn) {
             return this;
         },
         [Symbol.asyncIterator]() {
+            iteratorRequested = true;
             return {
                 next() {
                     if (pendingData.length > 0) {
@@ -554,7 +709,7 @@ function createChannel(id, sendFn, closeFn) {
             if (pendingReads.length > 0) {
                 pendingReads.shift().resolve({ done: false, value: payload });
             }
-            else {
+            else if (iteratorRequested || listeners.data.size === 0) {
                 pendingData.push(payload);
             }
             for (const listener of listeners.data) {
@@ -642,7 +797,15 @@ function isTransportReady() {
         communicationMethod === WEB_MESSAGE_TYPE);
 }
 function canSendAppMessages() {
-    return isTransportReady() && handshakeDone;
+    if (!handshakeDone)
+        return false;
+    // Apple upstream posts through WKScriptMessageHandler independently of the
+    // downstream fetch. During a replay reconnect, native retains responses by
+    // sequence, so treating that short gap as an unsendable session can strand
+    // requests in the outbox with no second `ready` event to flush them.
+    if (useAppleDownstreamTransport())
+        return true;
+    return isTransportReady();
 }
 function rejectPendingRequest(reqId, err) {
     const info = pendingReq.get(reqId);
@@ -1031,7 +1194,15 @@ function handleIncomingMessage(msg) {
             if (pendingReq.has(message.id)) {
                 const req = pendingReq.get(message.id);
                 if (req?.mode === "stream" && req.stream) {
-                    armRequestTimer(message.id);
+                    // The first frame proves the handler is live. Long-lived streams
+                    // (bookmarks.watch, proxy.watch) are idle between pushes, so the
+                    // request timeout must not treat silence as death — disarm it for
+                    // good instead of re-arming per frame.
+                    if (req.timerId !== null) {
+                        clearTimeout(req.timerId);
+                        req.timerId = null;
+                    }
+                    req.timeoutMs = 0;
                     req.stream._emitData(message.payload);
                 }
                 else {
@@ -1109,8 +1280,10 @@ function handleIncomingMessage(msg) {
         case "ch.close": {
             const pendingChannel = pendingChannels.get(message.id);
             if (pendingChannel) {
-                pendingChannels.delete(message.id);
-                pendingChannel.channel._emitClose(message.code, message.reason);
+                rejectPendingChannel(message.id, {
+                    code: message.code ?? BRIDGE_ERROR.STREAM_CLOSED,
+                    message: message.reason ?? "Channel closed before opening",
+                });
                 return;
             }
             const channel = activeChannels.get(message.id);
@@ -1458,6 +1631,8 @@ export const LingXiaBridge = {
         isMacOS,
         isWindows,
         isDesktop,
+        isApple,
+        isRunner,
         getOS: getPlatformOS,
     },
     dom: {
@@ -1598,6 +1773,8 @@ export function initBridge() {
         activateReceiver(LingXiaBridge._receiveEvaluateMessage);
         if (useAppleDownstreamTransport()) {
             ensureAppleDownstream();
+            startAppleWatchdog();
+            installAppleForegroundReconnect();
         }
         else if (communicationMethod === MESSAGE_PORT_TYPE) {
             installMessagePortInitListener();
@@ -1612,6 +1789,9 @@ export function initBridge() {
             warn("Unknown method");
         }
         window.LingXiaBridge = LingXiaBridge;
+        // Dev hook so repro/test pages can simulate a WebKit stream replacement.
+        window.__lxForceDownstreamReconnect =
+            forceDownstreamReconnect;
         installNativeComponentCoverageMonitor({
             os: getPlatformOS(),
             send: sendNativeComponentMessage,

package/dist/es2020/index.js

@@ -7,6 +7,7 @@
  */
 export { LingXiaBridge, channel, initBridge, invoke, notify, stream, } from './bridge';
 export { isNativeError } from './invocation';
+export { getDisplayLanguage } from './runtime-env';
 export { renderErrorUI, hasError, getErrorInfo } from './error';
 export { boot, bootWhenReady } from './boot';
 import { bootWhenReady } from './boot';

package/dist/es2020/runtime-env.js

@@ -1,4 +1,11 @@
 export const BRIDGE_CONFIG = (typeof window !== 'undefined' && window.__LX_BRIDGE_CFG) || {};
+const displayLanguage = BRIDGE_CONFIG.displayLanguage?.trim() || 'en-US';
+if (typeof document !== 'undefined' && document.documentElement) {
+    document.documentElement.lang = displayLanguage;
+}
+export function getDisplayLanguage() {
+    return displayLanguage;
+}
 export function getPlatformOS() {
     return BRIDGE_CONFIG.os || 'unknown';
 }
@@ -20,6 +27,24 @@ export function isWindows() {
 export function isDesktop() {
     return isMacOS() || isWindows();
 }
+// iOS and macOS share the WKWebView transport, so features scoped to it (e.g.
+// the streaming downstream) key off this rather than the two OS checks.
+export function isApple() {
+    return isIOS() || isMacOS();
+}
+// True when attached to a `lingxia dev` session (the host sets `dev` in
+// `__LX_BRIDGE_CFG`). Used to surface the bridge's own protocol/lifecycle trace
+// only during development.
+export function isDevSession() {
+    return BRIDGE_CONFIG.dev === true;
+}
+// True when running inside the LingXia Runner (the `lingxia dev` device
+// simulator), which the host marks in `__LX_BRIDGE_CFG`. Unlike a real host
+// app in dev mode, the Runner lacks host-declared surfaces such as the
+// terminal — apps read this to hide those affordances.
+export function isRunner() {
+    return BRIDGE_CONFIG.runner === true;
+}
 export function getCommunicationMethod() {
     if (BRIDGE_CONFIG.os === 'iOS' || BRIDGE_CONFIG.os === 'macOS')
         return 'webkit';

package/dist/es2020/ui/action-sheet.js

@@ -1,9 +1,9 @@
-import { getPlatformOS } from '../runtime-env';
+import { isDesktop } from '../runtime-env';
 const ANIMATION_MS = 300;
 const STYLE_ID = 'lx-action-sheet-style';
 let activeSheet = null;
 function isDesktopMode() {
-    return getPlatformOS() === 'macOS';
+    return isDesktop();
 }
 function ensureActionSheetStyle() {
     if (document.getElementById(STYLE_ID))