@lingxia/page-runtime 0.18.0 → 0.19.0

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { ensurePageBridgeSubscription, getPageActions, getPageSnapshot, getPageStateInfo, subscribePageData, subscribePageSnapshot, type ActionMap, type Snapshot, } from "./shared/runtime.js";
-export { getPageChromeLayout, installPageChromeRuntime, subscribePageChromeLayout, type LxPageChrome, type PageChromeLayoutListener, type PageChromeLayoutSnapshot, type PageChromeRect, } from "./page-chrome.js";
+export { ensurePageBridgeSubscription, getPageActions, getPageSnapshot, isPageReady, subscribePageSnapshot, whenPageReady, type ActionMap, type PageActions, type DeepReadonly, type Snapshot, } from "./shared/runtime.js";
+export { waitForPageState } from "./shared/startup.js";
+export { installPageChromeRuntime, type LxPageChrome, type PageChromeLayoutSnapshot, type PageChromeRect, } from "./page-chrome.js";

package/dist/index.js

@@ -1,2 +1,3 @@
-export { ensurePageBridgeSubscription, getPageActions, getPageSnapshot, getPageStateInfo, subscribePageData, subscribePageSnapshot, } from "./shared/runtime.js";
-export { getPageChromeLayout, installPageChromeRuntime, subscribePageChromeLayout, } from "./page-chrome.js";
+export { ensurePageBridgeSubscription, getPageActions, getPageSnapshot, isPageReady, subscribePageSnapshot, whenPageReady, } from "./shared/runtime.js";
+export { waitForPageState } from "./shared/startup.js";
+export { installPageChromeRuntime, } from "./page-chrome.js";

package/dist/page-chrome.d.ts

@@ -22,7 +22,6 @@ export interface PageChromeLayoutSnapshot {
 export interface LxPageChrome {
     readonly layout: PageChromeLayoutSnapshot;
 }
-export type PageChromeLayoutListener = (layout: PageChromeLayoutSnapshot) => void;
 declare global {
     interface Window {
         readonly lxPageChrome: LxPageChrome;
@@ -32,10 +31,6 @@ declare global {
     }
 }
 export declare function shouldApplyPageChromeRevision(currentRevision: number, nextRevision: number): boolean;
-/** Read the latest realized page-chrome layout synchronously. */
-export declare function getPageChromeLayout(): PageChromeLayoutSnapshot;
-/** Subscribe to realized page-chrome layout changes. */
-export declare function subscribePageChromeLayout(listener: PageChromeLayoutListener): () => void;
 /** Ensure browser previews have the same synchronous contract as native pages. */
 export declare function installPageChromeRuntime(): LxPageChrome | undefined;
 declare global {

package/dist/page-chrome.js

@@ -13,23 +13,13 @@ function projectPageChromeLayout(layout) {
     root?.style.setProperty("--lx-page-chrome-top-inset", `${layout.topInset}px`);
     root?.style.setProperty("--lx-page-chrome-bottom-inset", `${layout.bottomInset}px`);
     root?.style.setProperty("--lx-page-chrome-capsule-inline-end-inset", `${layout.capsuleInlineEndInset}px`);
-}
-/** Read the latest realized page-chrome layout synchronously. */
-export function getPageChromeLayout() {
-    if (typeof window === "undefined")
-        return initialLayout;
-    return installPageChromeRuntime()?.layout ?? initialLayout;
-}
-/** Subscribe to realized page-chrome layout changes. */
-export function subscribePageChromeLayout(listener) {
-    if (typeof window === "undefined")
-        return () => { };
-    installPageChromeRuntime();
-    const handleChange = (event) => {
-        listener(event.detail);
-    };
-    window.addEventListener("lxpagechromechange", handleChange);
-    return () => window.removeEventListener("lxpagechromechange", handleChange);
+    // The capsule's box, so a header can clear it in CSS alone
+    // (`padding-top: calc(var(--lx-page-chrome-capsule-bottom) + 12px)`).
+    // All zero when the page has no capsule.
+    const capsule = layout.capsuleRect;
+    for (const edge of ["top", "right", "bottom", "left", "width", "height"]) {
+        root?.style.setProperty(`--lx-page-chrome-capsule-${edge}`, `${capsule ? capsule[edge] : 0}px`);
+    }
 }
 /** Ensure browser previews have the same synchronous contract as native pages. */
 export function installPageChromeRuntime() {

package/dist/shared/runtime.d.ts

@@ -1,10 +1,48 @@
-import { type DataSubscriber, type StateInfo } from "@lingxia/bridge";
+import { type LxStream } from "@lingxia/bridge";
 export type ActionMap = Record<string, (...args: never[]) => unknown>;
+/**
+ * The View's side of a page action: at most one JSON payload; unary actions
+ * acknowledge completion, generators arrive as a stream handle.
+ */
+export type PageActions<A extends ActionMap> = {
+    readonly [K in keyof A]: A[K] extends (...args: infer P) => infer R ? number extends P["length"] ? (payload?: unknown) => ViewActionResult<R> : P extends [] | [unknown] | [unknown?] ? (...args: P) => ViewActionResult<R> : (error: "a page action takes at most one JSON payload") => never : never;
+};
+type ViewActionResult<R> = R extends LxStream<any, any> ? R : R extends AsyncGenerator<infer T, infer TReturn, any> ? LxStream<T, TReturn> : Promise<Awaited<R>>;
 export type Snapshot = Record<string, unknown>;
+/**
+ * What a View reads of its page's data: Logic owns it, so every level is
+ * readonly. Keep editable state (a form draft) in the View and send it with
+ * an action.
+ */
+export type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
 export type Listener = () => void;
 export declare function ensurePageBridgeSubscription(): void;
 export declare function subscribePageSnapshot(listener: Listener): () => void;
-export declare function subscribePageData(callback: DataSubscriber): () => void;
+/** Whether the page's first state has arrived. Flips once per document. */
+export declare function isPageReady(): boolean;
+/**
+ * Resolves once the page's first state has arrived — the host pushes it at
+ * bridge-ready, before `onLoad`, carrying `Page({ data })`'s defaults — so a
+ * page can mount with its data whole. With `timeoutMs`, rejects if Logic has
+ * not delivered it by then (it failed to load, or threw first); `null` waits
+ * without limit.
+ */
+export declare function whenPageReady(options?: {
+    timeoutMs?: number | null;
+}): Promise<void>;
 export declare function getPageSnapshot<TData = Snapshot>(): TData;
-export declare function getPageActions<TActions extends ActionMap>(): TActions;
-export declare function getPageStateInfo(): StateInfo;
+/**
+ * The page's actions: one object for the whole page, so it is a stable
+ * dependency. Built on first use — the page's action names arrive with its
+ * bridge metadata, after the page module has evaluated.
+ */
+export declare function getPageActions<TActions extends ActionMap>(): PageActions<TActions>;
+declare global {
+    interface Window {
+        /** Automation-only; see `invokePageActionForAutomation`. */
+        __lxInvokePageAction?: (name: string, payload?: unknown) => Promise<unknown>;
+    }
+}
+export {};

package/dist/shared/runtime.js

@@ -2,7 +2,16 @@ let snapshot = {};
 let stateInfo = { rev: -1, initial: true };
 let subscribed = false;
 let subscribeRetryTimer = null;
+let snapshotRetryTimer = null;
+let snapshotRetries = 0;
+/**
+ * The host pushes a page's first state at bridge-ready, so the request is only
+ * a fallback: a few tries, backing off, then stop. A page with no Logic never
+ * answers, and must not be asked for the life of the page.
+ */
+const MAX_SNAPSHOT_RETRIES = 3;
 let initialSnapshotResolved = false;
+let actions = null;
 let snapshotRequestInFlight = false;
 const listeners = new Set();
 function notifyListeners() {
@@ -15,8 +24,26 @@ function notifyListeners() {
         }
     });
 }
+/**
+ * In a dev session the page data is frozen, so a View that writes to it fails
+ * at the write instead of drifting from Logic until the next update. Each
+ * push is a fresh copy, so nothing else holds these objects.
+ */
+function isDevSession() {
+    return typeof window !== "undefined" && window.__LX_BRIDGE_CFG?.dev === true;
+}
+function deepFreeze(value) {
+    if (!value || typeof value !== "object" || Object.isFrozen(value))
+        return;
+    Object.freeze(value);
+    for (const key of Object.keys(value)) {
+        deepFreeze(value[key]);
+    }
+}
 function updateSnapshot(next, info) {
     snapshot = next && typeof next === "object" ? next : {};
+    if (isDevSession())
+        deepFreeze(snapshot);
     stateInfo = info;
     notifyListeners();
 }
@@ -28,11 +55,29 @@ function scheduleSubscribeRetry() {
         ensurePageBridgeSubscription();
     }, 10);
 }
+/**
+ * Retry the snapshot request itself. The subscription is already in place, so
+ * retrying it (as this used to) returned at once and never asked again; the
+ * page then relied on the host's own push at bridge-ready.
+ */
+function scheduleSnapshotRetry() {
+    if (snapshotRetryTimer !== null || snapshotRetries >= MAX_SNAPSHOT_RETRIES)
+        return;
+    snapshotRetries += 1;
+    snapshotRetryTimer = setTimeout(() => {
+        snapshotRetryTimer = null;
+        requestInitialSnapshot(window.LingXiaBridge);
+    }, 250 * 2 ** (snapshotRetries - 1));
+}
 function requestInitialSnapshot(bridge) {
+    if (stateInfo.rev >= 0)
+        initialSnapshotResolved = true;
     if (initialSnapshotResolved || snapshotRequestInFlight)
         return;
-    if (!bridge?.raw?.call)
+    if (!bridge?.raw?.call) {
+        scheduleSnapshotRetry();
         return;
+    }
     snapshotRequestInFlight = true;
     bridge
         .raw.call("state.getSnapshot", { scope: "page" })
@@ -40,7 +85,7 @@ function requestInitialSnapshot(bridge) {
         initialSnapshotResolved = true;
     })
         .catch(() => {
-        scheduleSubscribeRetry();
+        scheduleSnapshotRetry();
     })
         .finally(() => {
         snapshotRequestInFlight = false;
@@ -68,40 +113,69 @@ export function subscribePageSnapshot(listener) {
         listeners.delete(listener);
     };
 }
-export function subscribePageData(callback) {
-    if (typeof callback !== "function")
-        return () => { };
+/** Whether the page's first state has arrived. Flips once per document. */
+export function isPageReady() {
     ensurePageBridgeSubscription();
-    if (stateInfo.rev >= 0) {
-        callback(snapshot, { rev: stateInfo.rev, initial: true });
-    }
-    return subscribePageSnapshot(() => {
-        callback(snapshot, stateInfo);
+    return stateInfo.rev >= 0;
+}
+/**
+ * Resolves once the page's first state has arrived — the host pushes it at
+ * bridge-ready, before `onLoad`, carrying `Page({ data })`'s defaults — so a
+ * page can mount with its data whole. With `timeoutMs`, rejects if Logic has
+ * not delivered it by then (it failed to load, or threw first); `null` waits
+ * without limit.
+ */
+export function whenPageReady(options = {}) {
+    if (isPageReady())
+        return Promise.resolve();
+    const timeoutMs = options.timeoutMs === undefined ? 10000 : options.timeoutMs;
+    return new Promise((resolve, reject) => {
+        let timer = null;
+        const check = () => {
+            if (stateInfo.rev < 0)
+                return;
+            if (timer !== null)
+                clearTimeout(timer);
+            listeners.delete(check);
+            resolve();
+        };
+        if (timeoutMs !== null) {
+            timer = setTimeout(() => {
+                listeners.delete(check);
+                reject(new Error(`Page Logic did not deliver the page state within ${timeoutMs} ms`));
+            }, timeoutMs);
+        }
+        listeners.add(check);
     });
 }
 export function getPageSnapshot() {
     ensurePageBridgeSubscription();
     return snapshot;
 }
+/**
+ * The page's actions: one object for the whole page, so it is a stable
+ * dependency. Built on first use — the page's action names arrive with its
+ * bridge metadata, after the page module has evaluated.
+ */
 export function getPageActions() {
-    const actions = {};
+    if (actions)
+        return actions;
     const bridge = window.__pageBridge;
     if (!bridge?.__names) {
-        return actions;
+        throw new Error("Page actions are not ready. Read useLxPage() during component setup/render, or getPage() after pageReady(); pass actions into shared helpers.");
     }
+    const built = {};
     for (const name of bridge.__names) {
         if (typeof name !== "string")
             continue;
         const fn = getOrCreatePageAction(bridge, name);
         if (typeof fn === "function") {
-            actions[name] = fn;
+            built[name] = fn;
         }
     }
+    actions = built;
     return actions;
 }
-export function getPageStateInfo() {
-    return stateInfo;
-}
 function getOrCreatePageAction(bridge, name) {
     const existing = bridge[name];
     if (typeof existing === "function") {
@@ -114,7 +188,9 @@ function getOrCreatePageAction(bridge, name) {
 }
 function resolvePageActionMode(bridge, name) {
     const mode = bridge.__modes?.[name];
-    return mode === "call" || mode === "stream" ? mode : "notify";
+    if (mode === "call" || mode === "stream")
+        return mode;
+    throw new Error(`Invalid bridge mode for page action '${name}'; regenerate the page with the current CLI`);
 }
 function definePageBridgeAction(name, mode) {
     function action(...args) {
@@ -133,7 +209,7 @@ function definePageBridgeAction(name, mode) {
             return handle;
         }
         if (mode === "call") {
-            const promise = bridge.raw.call(name, payload);
+            const promise = callUnaryPageAction(bridge, name, payload);
             if (promise && typeof promise.catch === "function") {
                 promise.catch((err) => {
                     console.warn(`[PageFunc] ${name} failed:`, err instanceof Error ? err.message : err);
@@ -141,8 +217,7 @@ function definePageBridgeAction(name, mode) {
             }
             return promise;
         }
-        bridge.raw.notify(name, payload);
-        return undefined;
+        throw new Error(`Invalid bridge mode for page action '${name}'`);
     }
     Object.assign(action, {
         __logicFunc: true,
@@ -151,40 +226,87 @@ function definePageBridgeAction(name, mode) {
     });
     return action;
 }
+/**
+ * The one wire path of a unary action. It has no bridge deadline: an action
+ * may wait for a person or poll for minutes, and settles when Logic settles
+ * or the document goes away.
+ */
+async function callUnaryPageAction(bridge, name, payload, dropWhenGone = true) {
+    // Native components fire events before the page's first state arrives,
+    // and the host refuses calls until then: hold the call instead.
+    if (!isPageReady())
+        await whenPageReady({ timeoutMs: null });
+    try {
+        return await bridge.raw.call(name, payload, { timeoutMs: 0 });
+    }
+    catch (error) {
+        // Once the page has had its state, a not-ready answer means the host
+        // ended this document's session: the page has left, and a native
+        // component's late event has no one to report to. Drop it quietly.
+        // Automation has a caller waiting, so it gets the error.
+        if (dropWhenGone && error?.code === "BRIDGE_NOT_READY") {
+            return new Promise(() => { });
+        }
+        throw error;
+    }
+}
+/**
+ * A DOM or framework event, in this realm or another. A JSON payload never
+ * carries methods, so event methods tell the two apart.
+ */
+function isEventLike(value) {
+    if (typeof Event !== "undefined" && value instanceof Event)
+        return true;
+    if (!value || typeof value !== "object")
+        return false;
+    const event = value;
+    return typeof event.preventDefault === "function" && typeof event.stopPropagation === "function";
+}
+const PAGE_ACTIONS_NOT_READY = "PAGE_ACTIONS_NOT_READY";
+function pageActionError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+/**
+ * Automation entry (`PageDriver.action`): invoke one unary action of this
+ * page with a JSON payload, as the View would. The payload is passed as is —
+ * no DOM-event repackaging.
+ */
+function invokePageActionForAutomation(name, payload) {
+    if (typeof name !== "string" || name === "") {
+        return Promise.reject(pageActionError("BRIDGE_MALFORMED_MESSAGE", "Page action name must be a non-empty string"));
+    }
+    const metadata = window.__pageBridge;
+    const bridge = window.LingXiaBridge;
+    if (!Array.isArray(metadata?.__names) || !bridge?.raw) {
+        return Promise.reject(pageActionError(PAGE_ACTIONS_NOT_READY, "Page actions are not ready yet"));
+    }
+    if (!metadata.__names.includes(name)) {
+        const known = metadata.__names.length ? metadata.__names.join(", ") : "none";
+        return Promise.reject(pageActionError("BRIDGE_METHOD_NOT_FOUND", `'${name}' is not an action of this page (actions: ${known})`));
+    }
+    if (metadata.__modes?.[name] !== "call") {
+        return Promise.reject(pageActionError("PAGE_ACTION_NOT_UNARY", `Page action '${name}' is a stream action; only unary actions can be invoked`));
+    }
+    return callUnaryPageAction(bridge, name, payload, false);
+}
+if (typeof window !== "undefined") {
+    Object.defineProperty(window, "__lxInvokePageAction", {
+        value: invokePageActionForAutomation,
+        configurable: true,
+    });
+}
 function filterPayload(name, args) {
     const clean = [];
     for (const value of args) {
-        // CustomEvent carries serializable data on `.detail`, but the DOM Event
-        // wrapper itself is not portable across the bridge. Repackage as a plain
-        // `{detail, type}` so page actions bound directly to DOM listeners (e.g.
-        // `onVideoEnded={action}`) keep the familiar `event.detail` shape without
-        // forwarding the live Event instance. Without this rewrite the bare Event
-        // was stripped wholesale, producing `event = undefined` on the receiving
-        // side — surfaced in the showcase as "video ended undefined".
-        if (typeof CustomEvent !== "undefined" && value instanceof CustomEvent) {
-            clean.push({ type: value.type, detail: value.detail });
-            continue;
-        }
-        // Some framework wrappers / WebView realms do not preserve
-        // `instanceof CustomEvent`, but still expose the portable event payload
-        // shape. Keep it before the generic Event stripping path so page actions
-        // receive `event.detail` consistently.
-        const maybeEvent = value;
-        if (maybeEvent && typeof maybeEvent === "object" && typeof maybeEvent.type === "string" && "detail" in maybeEvent) {
-            clean.push({
-                type: maybeEvent.type,
-                detail: maybeEvent.detail,
-            });
-            continue;
-        }
-        // Generic Event / event-like objects with non-serializable methods stay
-        // stripped — there's no portable payload to extract.
-        if (value instanceof Event)
-            continue;
-        if (value &&
-            typeof value === "object" &&
-            "stopPropagation" in value &&
-            typeof value.stopPropagation === "function") {
+        // A DOM event bound straight to an action (`onVideoEnded={action}`)
+        // crosses as its portable `{ type, detail }`; one without `detail`
+        // carries nothing portable. A business payload passes as is, whatever
+        // its field names.
+        if (isEventLike(value)) {
+            const event = value;
+            if (typeof event.type === "string" && "detail" in event) {
+                clean.push({ type: event.type, detail: event.detail });
+            }
             continue;
         }
         clean.push(value);

package/dist/shared/startup.d.ts

@@ -0,0 +1,2 @@
+/** Mount with complete initial data; a delayed startup stays recoverable. */
+export declare function waitForPageState(): Promise<void>;

package/dist/shared/startup.js

@@ -0,0 +1,25 @@
+import { renderPageFault } from "@lingxia/bridge";
+import { isPageReady, whenPageReady } from "./runtime.js";
+let pending;
+/** Mount with complete initial data; a delayed startup stays recoverable. */
+export function waitForPageState() {
+    if (isPageReady())
+        return Promise.resolve();
+    return pending ?? (pending = wait().finally(() => { pending = undefined; }));
+}
+async function wait() {
+    const delay = 10000;
+    const panel = {};
+    const timer = setTimeout(() => {
+        const reason = `Page Logic has not delivered the page state after ${delay} ms`;
+        console.error(`[LingXia] ${location.pathname}: ${reason}`);
+        panel.dismiss = renderPageFault(location.pathname, reason);
+    }, delay);
+    try {
+        await whenPageReady({ timeoutMs: null });
+    }
+    finally {
+        clearTimeout(timer);
+        panel.dismiss?.();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingxia/page-runtime",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "private": false,
   "description": "Shared page runtime core for LingXia lxapp frameworks",
   "type": "module",
@@ -17,10 +17,11 @@
     "build": "npm run clean && npm --prefix ../lingxia-bridge run build:types && tsc -p tsconfig.json",
     "clean": "rm -rf dist",
     "test:runtime": "npm run build && node tests/page-chrome-revision.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "rolldown src/shared/runtime.ts --file dist/test/runtime.mjs --format esm && node ./test-support/test-runtime.mjs"
   },
   "dependencies": {
-    "@lingxia/bridge": "~0.18.0"
+    "@lingxia/bridge": "~0.19.0"
   },
   "devDependencies": {
     "@lingxia/bridge": "file:../lingxia-bridge",