@lingxia/html 0.18.0 → 0.20.0

package/dist/global.es2020.js

@@ -1,6 +1,6 @@
 var LingXiaPage = (function(exports) {
 	Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-	//#region dist/__page_runtime_runtime__.js
+	//#region ../lingxia-page-runtime/dist/shared/runtime.js
 	let snapshot = {};
 	let stateInfo = {
 		rev: -1,
@@ -8,7 +8,16 @@ var LingXiaPage = (function(exports) {
 	};
 	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 = /* @__PURE__ */ new Set();
 	function notifyListeners() {
@@ -18,8 +27,22 @@ var LingXiaPage = (function(exports) {
 			} catch {}
 		});
 	}
+	/**
+	* 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();
 	}
@@ -30,14 +53,31 @@ var LingXiaPage = (function(exports) {
 			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) return;
+		if (!bridge?.raw?.call) {
+			scheduleSnapshotRetry();
+			return;
+		}
 		snapshotRequestInFlight = true;
 		bridge.raw.call("state.getSnapshot", { scope: "page" }).then(() => {
 			initialSnapshotResolved = true;
 		}).catch(() => {
-			scheduleSubscribeRetry();
+			scheduleSnapshotRetry();
 		}).finally(() => {
 			snapshotRequestInFlight = false;
 		});
@@ -63,35 +103,58 @@ var LingXiaPage = (function(exports) {
 			listeners.delete(listener);
 		};
 	}
-	function subscribePageData(callback) {
-		if (typeof callback !== "function") return () => {};
+	/** Whether the page's first state has arrived. Flips once per document. */
+	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.
+	*/
+	function whenPageReady(options = {}) {
+		if (isPageReady()) return Promise.resolve();
+		const timeoutMs = options.timeoutMs === void 0 ? 1e4 : 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(/* @__PURE__ */ new Error(`Page Logic did not deliver the page state within ${timeoutMs} ms`));
+			}, timeoutMs);
+			listeners.add(check);
 		});
 	}
 	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.
+	*/
 	function getPageActions() {
-		const actions = {};
+		if (actions) return actions;
 		const bridge = window.__pageBridge;
-		if (!bridge?.__names) return actions;
+		if (!bridge?.__names) 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;
+			if (typeof fn === "function") built[name] = fn;
 		}
+		actions = built;
 		return actions;
 	}
-	function getPageStateInfo() {
-		return stateInfo;
-	}
 	function getOrCreatePageAction(bridge, name) {
 		const existing = bridge[name];
 		if (typeof existing === "function") return existing;
@@ -101,7 +164,8 @@ var LingXiaPage = (function(exports) {
 	}
 	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) {
@@ -116,13 +180,13 @@ var LingXiaPage = (function(exports) {
 				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);
 				});
 				return promise;
 			}
-			bridge.raw.notify(name, payload);
+			throw new Error(`Invalid bridge mode for page action '${name}'`);
 		}
 		Object.assign(action, {
 			__logicFunc: true,
@@ -131,31 +195,450 @@ var LingXiaPage = (function(exports) {
 		});
 		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) {
+		if (!isPageReady()) await whenPageReady({ timeoutMs: null });
+		try {
+			return await bridge.raw.call(name, payload, { timeoutMs: 0 });
+		} catch (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) {
-			if (typeof CustomEvent !== "undefined" && value instanceof CustomEvent) {
-				clean.push({
-					type: value.type,
-					detail: value.detail
+			if (isEventLike(value)) {
+				const event = value;
+				if (typeof event.type === "string" && "detail" in event) clean.push({
+					type: event.type,
+					detail: event.detail
 				});
 				continue;
 			}
-			const maybeEvent = value;
-			if (maybeEvent && typeof maybeEvent === "object" && typeof maybeEvent.type === "string" && "detail" in maybeEvent) {
-				clean.push({
-					type: maybeEvent.type,
-					detail: maybeEvent.detail
-				});
-				continue;
-			}
-			if (value instanceof Event) continue;
-			if (value && typeof value === "object" && "stopPropagation" in value && typeof value.stopPropagation === "function") continue;
 			clean.push(value);
 		}
 		if (clean.length > 1) throw new Error(`Page action '${name}' accepts at most one payload argument`);
 		return clean[0];
 	}
+	//#endregion
+	//#region ../lingxia-bridge/dist/es2020/error.js
+	const ERROR_STYLES = `
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Segoe UI', Roboto, sans-serif;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+  background: #f5f5f7;
+  color: #1d1d1f;
+  padding: 20px;
+  -webkit-font-smoothing: antialiased;
+}
+.lx-error {
+  text-align: center;
+  max-width: 400px;
+}
+.lx-error-code {
+  font-size: 120px;
+  font-weight: 700;
+  color: #d1d1d6;
+  line-height: 1;
+  letter-spacing: -4px;
+}
+.lx-error-title {
+  font-size: 21px;
+  font-weight: 600;
+  margin: 16px 0 8px;
+  color: #1d1d1f;
+}
+.lx-error-desc {
+  font-size: 15px;
+  color: #86868b;
+  line-height: 1.5;
+}
+.lx-error-path {
+  display: inline-block;
+  margin-top: 20px;
+  padding: 10px 16px;
+  background: rgba(0,0,0,0.04);
+  border-radius: 8px;
+  font-family: 'SF Mono', ui-monospace, Menlo, Monaco, monospace;
+  font-size: 13px;
+  color: #1d1d1f;
+  word-break: break-all;
+  max-width: 100%;
+}
+@media (prefers-color-scheme: dark) {
+  body { background: #000; color: #f5f5f7; }
+  .lx-error-code { color: #3a3a3c; }
+  .lx-error-title { color: #f5f5f7; }
+  .lx-error-desc { color: #86868b; }
+  .lx-error-path { background: rgba(255,255,255,0.08); color: #f5f5f7; }
+}
+`;
+	function escapeHtml(str) {
+		const div = document.createElement("div");
+		div.textContent = str;
+		return div.innerHTML;
+	}
+	/**
+	* A page whose Logic has not delivered its first state in time — it failed to
+	* load, threw before the page could start, or is very slow. Shown over the page
+	* instead of a blank screen, naming the page; returns a function that removes
+	* it, for when the state does arrive after all.
+	*/
+	function renderPageFault(pagePath, reason) {
+		const styleEl = document.createElement("style");
+		styleEl.textContent = `
+.lx-page-fault { position: fixed; inset: 0; z-index: 2147483647; overflow: auto;
+  background: #fff; color: #1d1d1f; }
+@media (prefers-color-scheme: dark) { .lx-page-fault { background: #000; color: #f5f5f7; } }
+${ERROR_STYLES.replace(/\bbody\b/g, ".lx-page-fault")}`;
+		document.head.appendChild(styleEl);
+		const overlay = document.createElement("div");
+		overlay.className = "lx-page-fault";
+		overlay.setAttribute("role", "alert");
+		const container = document.createElement("div");
+		container.className = "lx-error";
+		let html = "<div class=\"lx-error-code\">Page</div>";
+		html += `<h1 class="lx-error-title">${escapeHtml("This page couldn't start")}</h1>`;
+		html += `<p class="lx-error-desc">${escapeHtml("Its Logic has not delivered the page state. Check the Logic log for an error.")}</p>`;
+		if (pagePath) html += `<div class="lx-error-path">${escapeHtml(pagePath)}</div>`;
+		html += `<p class="lx-error-desc" style="margin-top:12px">${escapeHtml(reason)}</p>`;
+		container.innerHTML = html;
+		overlay.appendChild(container);
+		document.body.appendChild(overlay);
+		return () => {
+			overlay.remove();
+			styleEl.remove();
+		};
+	}
+	//#endregion
+	//#region ../lingxia-bridge/dist/es2020/runtime-env.js
+	const BRIDGE_CONFIG = typeof window !== "undefined" && window.__LX_BRIDGE_CFG || {};
+	/**
+	* One store per document, deliberately on `window`.
+	*
+	* This module is present twice in a page: once as the global bridge runtime
+	* the host injects, once bundled into the page's own JS. Module-local state
+	* would give each copy its own value — the host would push the change into
+	* whichever copy won the race to install the hook, and the other, which is the
+	* one the framework hooks read, would answer with the boot value forever.
+	*/
+	const fallbackStore$1 = {
+		value: BRIDGE_CONFIG.displayLanguage?.trim() || "en-US",
+		listeners: /* @__PURE__ */ new Set()
+	};
+	function store$1() {
+		if (typeof window === "undefined") return fallbackStore$1;
+		if (!window.__lxDisplayLanguage) window.__lxDisplayLanguage = {
+			value: BRIDGE_CONFIG.displayLanguage?.trim() || "en-US",
+			listeners: /* @__PURE__ */ new Set()
+		};
+		return window.__lxDisplayLanguage;
+	}
+	/** Primary subtags of languages written right to left, for engines without `Intl.Locale#getTextInfo`. */
+	const RTL_LANGUAGES = /* @__PURE__ */ new Set([
+		"ar",
+		"ckb",
+		"dv",
+		"fa",
+		"he",
+		"ps",
+		"sd",
+		"ug",
+		"ur",
+		"yi"
+	]);
+	/** The writing direction of a BCP-47 tag. */
+	function textDirection(tag) {
+		try {
+			const locale = new Intl.Locale(tag);
+			const info = typeof locale.getTextInfo === "function" ? locale.getTextInfo() : locale.textInfo;
+			if (info?.direction === "rtl" || info?.direction === "ltr") return info.direction;
+		} catch {}
+		return RTL_LANGUAGES.has(tag.split(/[-_]/)[0].toLowerCase()) ? "rtl" : "ltr";
+	}
+	/**
+	* `lang` and `dir` on `<html>` follow the display language, so a page never
+	* sets either: CSS logical properties and `:dir()` just work.
+	*/
+	function stampDocumentLanguage() {
+		if (typeof document !== "undefined" && document.documentElement) {
+			const language = store$1().value;
+			document.documentElement.lang = language;
+			document.documentElement.dir = textDirection(language);
+		}
+	}
+	stampDocumentLanguage();
+	/**
+	* Host entry point for a language the user changed while this document was
+	* open. Bootstrap alone would leave a live page in the language it started in,
+	* with the native chrome around it already switched.
+	*
+	* The host pushes each change once, and again — the current value — when a
+	* document's bridge reports ready, since a change made while it loaded found
+	* no hook to call. Those two can land in either order, so a push carries the
+	* host revision it took effect at and an older one never overwrites a newer
+	* one. A push without a revision applies as it always did.
+	*/
+	function applyDisplayLanguage(next, revision) {
+		const normalized = typeof next === "string" ? next.trim() : "";
+		const current = store$1();
+		if (typeof revision === "number" && Number.isFinite(revision)) {
+			if (revision <= (current.revision ?? 0)) return;
+			current.revision = revision;
+		}
+		if (!normalized || normalized === current.value) return;
+		current.value = normalized;
+		stampDocumentLanguage();
+		for (const listener of [...current.listeners]) listener(normalized);
+	}
+	if (typeof window !== "undefined" && !window.__lingxiaApplyDisplayLanguage) Object.defineProperty(window, "__lingxiaApplyDisplayLanguage", {
+		configurable: false,
+		enumerable: false,
+		value: applyDisplayLanguage
+	});
+	function getDisplayLanguage() {
+		return store$1().value;
+	}
+	/**
+	* 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.host.displayLanguage.watch` differs
+	* deliberately — it has no render loop to feed, so it delivers immediately.
+	*/
+	function subscribeDisplayLanguage(listener) {
+		const listeners = store$1().listeners;
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	}
+	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";
+	}
+	function isDesktop() {
+		return hostClass() === "desktop";
+	}
+	//#endregion
+	//#region ../lingxia-bridge/dist/es2020/surface-context.js
+	/** What a host that sends nothing — one older than this API — is taken to say. */
+	const 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() {
+		if (typeof window === "undefined") return fallbackStore;
+		if (!window.__lxSurfaceContext) {
+			const config = window.__LX_BRIDGE_CFG;
+			window.__lxSurfaceContext = {
+				value: parse(config?.surfaceContext) ?? UNREPORTED,
+				revision: typeof config?.surfaceContextRevision === "number" ? config.surfaceContextRevision : 0,
+				listeners: /* @__PURE__ */ new Set()
+			};
+		}
+		return window.__lxSurfaceContext;
+	}
+	const fallbackStore = {
+		value: UNREPORTED,
+		revision: 0,
+		listeners: /* @__PURE__ */ new Set()
+	};
+	function parse(next) {
+		if (typeof next !== "object" || next === null) return null;
+		const { sizeClass, width, height, aside } = next;
+		if (sizeClass !== "compact" && sizeClass !== "regular") return null;
+		if (typeof width !== "number" || typeof height !== "number") return null;
+		return {
+			sizeClass,
+			width,
+			height,
+			aside: aside === true
+		};
+	}
+	function same$1(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) {
+		const context = parse(next);
+		const current = store();
+		if (!context) return;
+		if (typeof revision === "number") {
+			if (revision <= current.revision) return;
+			current.revision = revision;
+		}
+		if (same$1(current.value, context)) return;
+		current.value = context;
+		for (const listener of [...current.listeners]) listener();
+	}
+	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.
+	*/
+	function getSurfaceContext() {
+		return store().value;
+	}
+	/**
+	* Follow the adaptive context. Change-only, like `subscribeDisplayLanguage`,
+	* so it composes with `useSyncExternalStore`. Returns an unsubscribe.
+	*/
+	function subscribeSurfaceContext(listener) {
+		const listeners = store().listeners;
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	}
+	//#endregion
+	//#region ../lingxia-bridge/dist/es2020/host.js
+	let current = null;
+	function read() {
+		const surface = getSurfaceContext();
+		return {
+			sizeClass: surface.sizeClass,
+			aside: surface.aside,
+			displayLanguage: getDisplayLanguage(),
+			formFactor: isDesktop() ? "desktop" : "mobile",
+			os: getPlatformOS(),
+			runner: BRIDGE_CONFIG.runner === true
+		};
+	}
+	function same(a, b) {
+		return a.sizeClass === b.sizeClass && a.aside === b.aside && a.displayLanguage === b.displayLanguage && a.formFactor === b.formFactor && a.os === b.os && a.runner === b.runner;
+	}
+	/**
+	* The host facts for this page. The same object is returned until a field
+	* changes, so it composes with `useSyncExternalStore` and with memoization.
+	*/
+	function getHost() {
+		const next = read();
+		if (current === null || !same(current, next)) current = next;
+		return current;
+	}
+	/**
+	* 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.
+	*/
+	function subscribeHost(listener) {
+		let last = getHost();
+		const check = () => {
+			const next = getHost();
+			if (next === last) return;
+			last = next;
+			listener();
+		};
+		const stopLanguage = subscribeDisplayLanguage(check);
+		const stopSurface = subscribeSurfaceContext(check);
+		return () => {
+			stopLanguage();
+			stopSurface();
+		};
+	}
+	//#endregion
+	//#region ../lingxia-page-runtime/dist/shared/startup.js
+	let pending;
+	/** Mount with complete initial data; a delayed startup stays recoverable. */
+	function waitForPageState() {
+		if (isPageReady()) return Promise.resolve();
+		return pending ?? (pending = wait().finally(() => {
+			pending = void 0;
+		}));
+	}
+	async function wait() {
+		const delay = 1e4;
+		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?.();
+		}
+	}
+	//#endregion
+	//#region ../lingxia-page-runtime/dist/page-chrome.js
 	const initialLayout = Object.freeze({
 		revision: 0,
 		topInset: 0,
@@ -171,21 +654,15 @@ var LingXiaPage = (function(exports) {
 		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. */
-	function getPageChromeLayout() {
-		if (typeof window === "undefined") return initialLayout;
-		return installPageChromeRuntime()?.layout ?? initialLayout;
-	}
-	/** Subscribe to realized page-chrome layout changes. */
-	function subscribePageChromeLayout(listener) {
-		if (typeof window === "undefined") return () => {};
-		installPageChromeRuntime();
-		const handleChange = (event) => {
-			listener(event.detail);
-		};
-		window.addEventListener("lxpagechromechange", handleChange);
-		return () => window.removeEventListener("lxpagechromechange", handleChange);
+		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. */
 	function installPageChromeRuntime() {
@@ -224,12 +701,34 @@ var LingXiaPage = (function(exports) {
 	}
 	installPageChromeRuntime();
 	//#endregion
-	exports.getActions = getPageActions;
-	exports.getPageChromeLayout = getPageChromeLayout;
-	exports.getSnapshot = getPageSnapshot;
-	exports.getStateInfo = getPageStateInfo;
-	exports.subscribe = subscribePageData;
-	exports.subscribePageChromeLayout = subscribePageChromeLayout;
-	exports.subscribeSnapshot = subscribePageSnapshot;
+	//#region dist/page.js
+	/**
+	* Resolves once the first state arrives. By default a delayed startup shows
+	* a fault panel and keeps waiting, just like React/Vue. An explicit timeout
+	* rejects instead; `null` waits without the panel. Await before `getPage()`.
+	*/
+	function pageReady(options) {
+		return options?.timeoutMs === void 0 ? waitForPageState() : whenPageReady(options);
+	}
+	/**
+	* This page's Logic state and actions — `this.data` and the page's methods.
+	* `data` is readonly: Logic owns it (in a dev session a write throws).
+	*/
+	function getPage() {
+		return {
+			data: getPageSnapshot(),
+			actions: getPageActions()
+		};
+	}
+	/** Follow the page's state. Change-only; read it with `getPage()`. Returns an unsubscribe. */
+	function subscribePage(listener) {
+		return subscribePageSnapshot(listener);
+	}
+	//#endregion
+	exports.getHost = getHost;
+	exports.getPage = getPage;
+	exports.pageReady = pageReady;
+	exports.subscribeHost = subscribeHost;
+	exports.subscribePage = subscribePage;
 	return exports;
 })({});