@lingxia/bridge 0.14.0 → 0.16.0

package/dist/es5/protocol-v3.js

@@ -0,0 +1,215 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+/** Document-side framing for host-attested RequiredV3 documents. */
+export var V3_PROTOCOL = 3;
+export var DEFAULT_MAX_V3_FRAME_BYTES = 64 * 1024;
+var documentToNativeKinds = new Set([
+    "hello",
+    "req",
+    "res",
+    "notify",
+    "cancel",
+    "ch.open",
+    "ch.data",
+    "ch.close",
+    "state.ack",
+    "console",
+]);
+var nativeToDocumentKinds = new Set([
+    "helloAck",
+    "ready",
+    "req",
+    "res",
+    "event",
+    "state.snapshot",
+    "state.patch",
+    "ch.ack",
+    "ch.data",
+    "ch.close",
+]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasDuplicateTopLevelSecurityKey(frame) {
+    var _a;
+    var securityKeys = new Set(["v", "kind", "sessionId", "secret"]);
+    var seen = new Set();
+    var depth = 0;
+    for (var index = 0; index < frame.length; index++) {
+        var char = frame[index];
+        if (char === "{" || char === "[") {
+            depth++;
+            continue;
+        }
+        if (char === "}" || char === "]") {
+            depth--;
+            continue;
+        }
+        if (char !== '"')
+            continue;
+        var start = index;
+        index++;
+        while (index < frame.length) {
+            if (frame[index] === "\\") {
+                index += 2;
+                continue;
+            }
+            if (frame[index] === '"')
+                break;
+            index++;
+        }
+        if (index >= frame.length)
+            return false;
+        if (depth !== 1)
+            continue;
+        var next = index + 1;
+        while (/\s/.test((_a = frame[next]) !== null && _a !== void 0 ? _a : ""))
+            next++;
+        if (frame[next] !== ":")
+            continue;
+        var key = void 0;
+        try {
+            key = JSON.parse(frame.slice(start, index + 1));
+        }
+        catch (_b) {
+            return false;
+        }
+        if (typeof key === "string" && securityKeys.has(key)) {
+            if (seen.has(key))
+                return true;
+            seen.add(key);
+        }
+    }
+    return false;
+}
+/**
+ * Captures the document secret in a closure. Neither the returned codec nor
+ * parsed native messages expose it.
+ */
+export function createV3DocumentCodec(binding) {
+    if (!isRecord(binding) ||
+        typeof binding.sessionId !== "string" ||
+        binding.sessionId.length === 0 ||
+        typeof binding.secret !== "string" ||
+        binding.secret.length === 0) {
+        return { ok: false, error: "INVALID_DOCUMENT_BINDING" };
+    }
+    var sessionId = binding.sessionId, secret = binding.secret;
+    return {
+        ok: true,
+        value: {
+            encode: function (kind, payload) {
+                if (!documentToNativeKinds.has(kind) || !isRecord(payload)) {
+                    return { ok: false, error: "INVALID_DOCUMENT_PAYLOAD" };
+                }
+                if (["v", "kind", "sessionId", "secret"].some(function (field) { return field in payload; })) {
+                    return { ok: false, error: "SECURITY_FIELD_IN_PAYLOAD" };
+                }
+                return {
+                    ok: true,
+                    value: __assign(__assign({}, payload), { v: V3_PROTOCOL, kind: kind, sessionId: sessionId, secret: secret }),
+                };
+            },
+            parse: function (frame, maxFrameBytes) {
+                if (maxFrameBytes === void 0) { maxFrameBytes = DEFAULT_MAX_V3_FRAME_BYTES; }
+                // Envelope checks deliberately precede typed payload handling.
+                if (new TextEncoder().encode(frame).byteLength > maxFrameBytes) {
+                    return { ok: false, error: "FRAME_TOO_LARGE" };
+                }
+                if (hasDuplicateTopLevelSecurityKey(frame)) {
+                    return { ok: false, error: "MALFORMED_ENVELOPE" };
+                }
+                var candidate;
+                try {
+                    candidate = JSON.parse(frame);
+                }
+                catch (_a) {
+                    return { ok: false, error: "MALFORMED_ENVELOPE" };
+                }
+                if (!isRecord(candidate))
+                    return { ok: false, error: "MALFORMED_ENVELOPE" };
+                if (candidate.v !== V3_PROTOCOL) {
+                    return { ok: false, error: "UNSUPPORTED_VERSION" };
+                }
+                if (typeof candidate.kind !== "string" ||
+                    !nativeToDocumentKinds.has(candidate.kind)) {
+                    return { ok: false, error: "UNSUPPORTED_NATIVE_KIND" };
+                }
+                if (typeof candidate.sessionId !== "string" || candidate.sessionId.length === 0) {
+                    return { ok: false, error: "MALFORMED_ENVELOPE" };
+                }
+                if (candidate.sessionId !== sessionId)
+                    return { ok: false, error: "SESSION_MISMATCH" };
+                if (Object.prototype.hasOwnProperty.call(candidate, "secret")) {
+                    return { ok: false, error: "UNEXPECTED_SECRET" };
+                }
+                var _v = candidate.v, _kind = candidate.kind, _sessionId = candidate.sessionId, payload = __rest(candidate, ["v", "kind", "sessionId"]);
+                return {
+                    ok: true,
+                    value: { kind: candidate.kind, payload: payload },
+                };
+            },
+        },
+    };
+}
+/**
+ * Atomically takes the host-installed one-shot handoff. The secret remains in
+ * the returned codec closure and is never copied into bridge globals/config.
+ */
+export function consumeV3Bootstrap() {
+    if (typeof window === "undefined")
+        return { kind: "absent" };
+    var take = window.__LingXiaTakeControlBootstrap;
+    if (typeof take !== "function")
+        return { kind: "absent" };
+    try {
+        var bootstrap = take();
+        if (!bootstrap ||
+            bootstrap.requiredProtocol !== V3_PROTOCOL ||
+            typeof bootstrap.publicSessionId !== "string" ||
+            bootstrap.publicSessionId.length === 0 ||
+            typeof bootstrap.secret !== "string" ||
+            bootstrap.secret.length === 0) {
+            return { kind: "blocked" };
+        }
+        var codec = createV3DocumentCodec({
+            sessionId: bootstrap.publicSessionId,
+            secret: bootstrap.secret,
+        });
+        return codec.ok
+            ? { kind: "required", codec: codec.value }
+            : { kind: "blocked" };
+    }
+    catch (_a) {
+        return { kind: "blocked" };
+    }
+    finally {
+        // A malformed replacement must not leave a callable handoff for later.
+        try {
+            delete window.__LingXiaTakeControlBootstrap;
+        }
+        catch (_b) {
+            // A hostile non-configurable property has no attested secret to retain.
+        }
+    }
+}

package/dist/es5/runtime-env.js

@@ -83,7 +83,7 @@ function applyDisplayLanguage(next) {
     try {
         for (var _b = __values(__spreadArray([], __read(current.listeners), false)), _c = _b.next(); !_c.done; _c = _b.next()) {
             var listener = _c.value;
-            listener();
+            listener(normalized);
         }
     }
     catch (e_1_1) { e_1 = { error: e_1_1 }; }
@@ -104,7 +104,14 @@ if (typeof window !== 'undefined' && !window.__lingxiaApplyDisplayLanguage) {
 export function getDisplayLanguage() {
     return store().value;
 }
-/** Subscribe to host display-language changes. Returns an unsubscribe. */
+/**
+ * Subscribe to host display-language changes. Returns an unsubscribe.
+ *
+ * Change-only, so that this composes with `useSyncExternalStore`: the listener
+ * runs when the language changes, never on subscribe. Read the current value
+ * with `getDisplayLanguage()`. Logic's `lx.app.displayLanguage.watch` differs
+ * deliberately — it has no render loop to feed, so it delivers immediately.
+ */
 export function subscribeDisplayLanguage(listener) {
     var listeners = store().listeners;
     listeners.add(listener);
@@ -115,6 +122,23 @@ export function subscribeDisplayLanguage(listener) {
 export function getPlatformOS() {
     return BRIDGE_CONFIG.os || 'unknown';
 }
+/**
+ * Which kind of machine this is, mobile or desktop. Read through `isMobile()`
+ * and `isDesktop()`; the class itself is host vocabulary, not lxapp API.
+ *
+ * Fixed for the life of the document. A shipped host is one machine; the
+ * Runner re-serves the page when its simulated device changes class, so this
+ * never has to change under a page that is already rendering.
+ *
+ * Hosts from before this config key shipped send nothing, so fall back to the
+ * OS: every one of them is the machine it names.
+ */
+function hostClass() {
+    if (BRIDGE_CONFIG.hostClass === 'mobile' || BRIDGE_CONFIG.hostClass === 'desktop') {
+        return BRIDGE_CONFIG.hostClass;
+    }
+    return BRIDGE_CONFIG.os === 'macOS' || BRIDGE_CONFIG.os === 'Windows' ? 'desktop' : 'mobile';
+}
 export function isHarmony() {
     return BRIDGE_CONFIG.os === 'Harmony';
 }
@@ -130,8 +154,13 @@ export function isMacOS() {
 export function isWindows() {
     return BRIDGE_CONFIG.os === 'Windows';
 }
+// Form factor, not OS: the Runner shows a real macOS/Windows build inside a
+// phone frame, and a page that keyed off the OS would keep its desktop layout.
 export function isDesktop() {
-    return isMacOS() || isWindows();
+    return hostClass() === 'desktop';
+}
+export function isMobile() {
+    return hostClass() === 'mobile';
 }
 // 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.

package/dist/es5/types.js

@@ -13,4 +13,5 @@ export var BRIDGE_ERROR = {
     OUTBOX_FULL: 'BRIDGE_OUTBOX_FULL',
     STREAM_OVERFLOW: 'BRIDGE_STREAM_OVERFLOW',
     STREAM_CLOSED: 'BRIDGE_STREAM_CLOSED',
+    MESSAGE_TOO_LARGE: 'BRIDGE_MESSAGE_TOO_LARGE',
 };

package/dist/protocol-v3.d.ts

@@ -0,0 +1,43 @@
+/** Document-side framing for host-attested RequiredV3 documents. */
+export declare const V3_PROTOCOL: 3;
+export declare const DEFAULT_MAX_V3_FRAME_BYTES: number;
+export type V3DocumentToNativeKind = "hello" | "req" | "res" | "notify" | "cancel" | "ch.open" | "ch.data" | "ch.close" | "state.ack" | "console";
+export type V3NativeToDocumentKind = "helloAck" | "ready" | "req" | "res" | "event" | "state.snapshot" | "state.patch" | "ch.ack" | "ch.data" | "ch.close";
+export type V3CodecError = "FRAME_TOO_LARGE" | "MALFORMED_ENVELOPE" | "UNSUPPORTED_VERSION" | "UNSUPPORTED_NATIVE_KIND" | "INVALID_DOCUMENT_BINDING" | "INVALID_DOCUMENT_PAYLOAD" | "SECURITY_FIELD_IN_PAYLOAD" | "SESSION_MISMATCH" | "UNEXPECTED_SECRET";
+export type V3CodecResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: V3CodecError;
+};
+export type V3DocumentBinding = {
+    readonly sessionId: string;
+    readonly secret: string;
+};
+export type V3NativeEnvelope = {
+    readonly kind: V3NativeToDocumentKind;
+    readonly payload: Readonly<Record<string, unknown>>;
+};
+export type V3DocumentCodec = {
+    encode(kind: V3DocumentToNativeKind, payload: Record<string, unknown>): V3CodecResult<Record<string, unknown>>;
+    parse(frame: string, maxFrameBytes?: number): V3CodecResult<V3NativeEnvelope>;
+};
+export type V3BootstrapActivation = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "required";
+    readonly codec: V3DocumentCodec;
+} | {
+    readonly kind: "blocked";
+};
+/**
+ * Captures the document secret in a closure. Neither the returned codec nor
+ * parsed native messages expose it.
+ */
+export declare function createV3DocumentCodec(binding: V3DocumentBinding): V3CodecResult<V3DocumentCodec>;
+/**
+ * Atomically takes the host-installed one-shot handoff. The secret remains in
+ * the returned codec closure and is never copied into bridge globals/config.
+ */
+export declare function consumeV3Bootstrap(): V3BootstrapActivation;

package/dist/runtime-env.d.ts

@@ -3,8 +3,15 @@ export type CommunicationMethod = 'messageport' | 'jsinterface' | 'webmessage' |
 export type PlatformOS = NonNullable<BridgeConfig['os']> | 'unknown';
 export declare const BRIDGE_CONFIG: BridgeConfig;
 export declare function getDisplayLanguage(): string;
-/** Subscribe to host display-language changes. Returns an unsubscribe. */
-export declare function subscribeDisplayLanguage(listener: () => void): () => void;
+/**
+ * Subscribe to host display-language changes. Returns an unsubscribe.
+ *
+ * Change-only, so that this composes with `useSyncExternalStore`: the listener
+ * runs when the language changes, never on subscribe. Read the current value
+ * with `getDisplayLanguage()`. Logic's `lx.app.displayLanguage.watch` differs
+ * deliberately — it has no render loop to feed, so it delivers immediately.
+ */
+export declare function subscribeDisplayLanguage(listener: (language: string) => void): () => void;
 export declare function getPlatformOS(): PlatformOS;
 export declare function isHarmony(): boolean;
 export declare function isIOS(): boolean;
@@ -12,6 +19,7 @@ export declare function isAndroid(): boolean;
 export declare function isMacOS(): boolean;
 export declare function isWindows(): boolean;
 export declare function isDesktop(): boolean;
+export declare function isMobile(): boolean;
 export declare function isApple(): boolean;
 export declare function isDevSession(): boolean;
 export declare function isRunner(): boolean;

package/dist/types.d.ts

@@ -1,5 +1,11 @@
 export interface BridgeConfig {
     os?: 'Harmony' | 'iOS' | 'Android' | 'macOS' | 'Windows';
+    /**
+     * Transport for the host's form factor, read through `isMobile()` /
+     * `isDesktop()` rather than directly. Distinct from `os`, which names the
+     * actual system: the Runner simulating a phone is still macOS or Windows.
+     */
+    hostClass?: 'mobile' | 'desktop';
     /** Effective host display language; distinct from the raw system locale. */
     displayLanguage?: string;
     nonce?: string;
@@ -15,6 +21,18 @@ export interface ErrorInfo {
     reason?: string;
     code?: number;
 }
+/**
+ * Private, one-shot handoff installed only in host-attested internal HTML.
+ *
+ * This is intentionally not part of the public bridge API and V2 never reads
+ * it. A future V3 bootstrap consumes the handoff before protocol activation.
+ */
+interface ControlBootstrap {
+    readonly requiredProtocol: 3;
+    readonly publicSessionId: string;
+    readonly secret: string;
+}
+type TakeControlBootstrap = () => ControlBootstrap | undefined;
 export declare const BRIDGE_ERROR: {
     readonly NOT_READY: "BRIDGE_NOT_READY";
     readonly TIMEOUT: "BRIDGE_TIMEOUT";
@@ -29,6 +47,7 @@ export declare const BRIDGE_ERROR: {
     readonly OUTBOX_FULL: "BRIDGE_OUTBOX_FULL";
     readonly STREAM_OVERFLOW: "BRIDGE_STREAM_OVERFLOW";
     readonly STREAM_CLOSED: "BRIDGE_STREAM_CLOSED";
+    readonly MESSAGE_TOO_LARGE: "BRIDGE_MESSAGE_TOO_LARGE";
 };
 export type BridgeErrorCode = (typeof BRIDGE_ERROR)[keyof typeof BRIDGE_ERROR];
 export interface LxBridgeError {
@@ -126,16 +145,24 @@ declare global {
         };
         __LX_BRIDGE_INIT_STATE?: 'initializing' | 'initialized';
         __LX_RUNTIME_CONFIG?: RuntimeConfig;
+        /**
+         * Host-attested, one-shot V3 bootstrap handoff. It is absent for legacy
+         * scheme loads, assets, and all untrusted documents.
+         */
+        __LingXiaTakeControlBootstrap?: TakeControlBootstrap;
         __pageBridge?: {
             __names: string[];
             [key: string]: unknown;
         };
         __LingXiaRecvMessage?: (message: string) => void;
+        /** WebView2 inject script queues inbound payloads here until the bridge binds `__LingXiaRecvMessage`. */
+        __LingXiaEarlyNativeMessages?: string[];
         LingXiaBridge?: LingXiaBridgeInterface;
         LingXiaProxy?: {
             supportsMessagePort: () => boolean;
             getPort: (name: string) => string;
             postMessage: (message: string) => void;
+            nativeComponentUpdate?: ((payload: string) => void) | ((componentId: string, payload: string) => void);
         };
         NativeComponentBridge?: {
             postMessage: (message: string) => void;
@@ -165,6 +192,11 @@ export interface LingXiaBridgeInterface {
         proto: boolean;
         all: boolean;
     };
+    displayLanguage: {
+        get(): string;
+        /** Change-only; read the current value with `get()`. */
+        subscribe(listener: (language: string) => void): () => void;
+    };
     platform: {
         isHarmony(): boolean;
         isIOS(): boolean;
@@ -172,6 +204,7 @@ export interface LingXiaBridgeInterface {
         isMacOS(): boolean;
         isWindows(): boolean;
         isDesktop(): boolean;
+        isMobile(): boolean;
         isApple(): boolean;
         isRunner(): boolean;
         getOS(): string;
@@ -204,3 +237,4 @@ export interface StreamOptions extends StreamCallOptions {
 }
 export interface ChannelOptions extends ChannelOpenOptions {
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingxia/bridge",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "private": false,
   "description": "LingXia Web Runtime - Bridge, boot, and error handling for WebView",
   "repository": {
@@ -39,6 +39,8 @@
     "build:modules:es2020": "tsc -p tsconfig.modules.json",
     "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",
     "dev": "rolldown -c -w",
     "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
     "prepublishOnly": "npm run build"