@g9tm/lynxcontrols 0.0.0-stage → 1.4.0

package/dist/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,cAAc,EACd,cAAc,EACd,qBAAqB,GACtB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9F,OAAO,EACL,gBAAgB,EAChB,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,YAAY,EACZ,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,oBAAoB,EAAE,KAAK,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAC9F,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,OAAO,GACR,MAAM,YAAY,CAAC"}

package/dist/host/index.jsx

@@ -0,0 +1,8 @@
+export { createBackStack } from "./back.jsx";
+export { useG9Activation, useG9Back, useG9HideKeyboard, useG9Host, useG9HostInsets, useG9HostReady, useG9LayerItem, useG9PanSoftInputMode } from "./hooks.jsx";
+export { G9Host } from "./host.jsx";
+export { acquirePanSoftInputMode, g9KeyboardTargetProps, isKeyboardTarget } from "./keyboard.jsx";
+export { G9Layer, createLayerStore, g9LayerOrder, layerRank } from "./layers.jsx";
+export { G9PageLoadingOverlay } from "./page-loading-overlay.jsx";
+export { g9PageLoadingExitMs, g9PageLoadingWatchdogMarginMs } from "./readiness.jsx";
+export { g9Hosts } from "./registry.jsx";

package/dist/host/keyboard.d.ts

@@ -0,0 +1,24 @@
+import type { G9HostServices } from '@g9tm/lynxcontrols-foundation';
+/**
+ * Mark an element that takes keyboard focus (an `<input>`, `<textarea>`, or the field box around one) with these
+ * props. A tap on a marked element never dismisses the keyboard: focus moves between fields with the keyboard up
+ * (MAUI tap-outside rule, `Controls/G9Controls.md` §13).
+ */
+export declare const g9KeyboardTargetProps: Readonly<{
+    'data-g9keyboard': "target";
+}>;
+/**
+ * `true` when a tap target's dataset carries the {@link g9KeyboardTargetProps} mark. The key is one lower-case word
+ * so it reads the same whether the runtime keeps or camel-cases dataset keys.
+ */
+export declare function isKeyboardTarget(target: {
+    readonly dataset?: Readonly<Record<string, unknown>>;
+} | null | undefined): boolean;
+/**
+ * Switches the window to pan the focused input above the keyboard while a flow needs it (MAUI
+ * `G9KeyboardHelper.UseAndroidPanSoftInputMode`). Returns an idempotent restore function; the default `'resize'`
+ * comes back when the last user restores. Users are counted per host, so overlapping sheets do not undo each other.
+ * On a host without soft-input modes (iOS, desktop: no `setSoftInputMode`) nothing changes, as in MAUI.
+ */
+export declare function acquirePanSoftInputMode(host: G9HostServices): () => void;
+//# sourceMappingURL=keyboard.d.ts.map

package/dist/host/keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.d.ts","sourceRoot":"","sources":["../../src/host/keyboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;EAAiD,CAAC;AAEpF;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAClF,OAAO,CAET;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,IAAI,CAcxE"}

package/dist/host/keyboard.jsx

@@ -0,0 +1,28 @@
+const g9KeyboardTargetProps = Object.freeze({
+    'data-g9keyboard': 'target'
+});
+function isKeyboardTarget(target) {
+    var _target_dataset;
+    return (null == target ? void 0 : null == (_target_dataset = target.dataset) ? void 0 : _target_dataset.g9keyboard) === 'target';
+}
+const panUsers = new WeakMap();
+function acquirePanSoftInputMode(host) {
+    var _panUsers_get;
+    var _host_setSoftInputMode;
+    const setMode = null == (_host_setSoftInputMode = host.setSoftInputMode) ? void 0 : _host_setSoftInputMode.bind(host);
+    if (!setMode) return ()=>{};
+    const users = null != (_panUsers_get = panUsers.get(host)) ? _panUsers_get : 0;
+    panUsers.set(host, users + 1);
+    if (0 === users) setMode('pan');
+    let restored = false;
+    return ()=>{
+        if (restored) return;
+        restored = true;
+        const remaining = panUsers.get(host) - 1;
+        panUsers.set(host, remaining);
+        if (0 === remaining) setMode('resize');
+    };
+}
+export { acquirePanSoftInputMode, g9KeyboardTargetProps, isKeyboardTarget };
+
+//# sourceMappingURL=keyboard.jsx.map

package/dist/host/keyboard.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"host/keyboard.jsx","sources":["../../src/host/keyboard.ts"],"sourcesContent":["import type { G9HostServices } from '@g9tm/lynxcontrols-foundation';\n\n/**\n * Mark an element that takes keyboard focus (an `<input>`, `<textarea>`, or the field box around one) with these\n * props. A tap on a marked element never dismisses the keyboard: focus moves between fields with the keyboard up\n * (MAUI tap-outside rule, `Controls/G9Controls.md` §13).\n */\nexport const g9KeyboardTargetProps = Object.freeze({ 'data-g9keyboard': 'target' });\n\n/**\n * `true` when a tap target's dataset carries the {@link g9KeyboardTargetProps} mark. The key is one lower-case word\n * so it reads the same whether the runtime keeps or camel-cases dataset keys.\n */\nexport function isKeyboardTarget(\n  target: { readonly dataset?: Readonly<Record<string, unknown>> } | null | undefined,\n): boolean {\n  return target?.dataset?.g9keyboard === 'target';\n}\n\nconst panUsers = new WeakMap<G9HostServices, number>();\n\n/**\n * Switches the window to pan the focused input above the keyboard while a flow needs it (MAUI\n * `G9KeyboardHelper.UseAndroidPanSoftInputMode`). Returns an idempotent restore function; the default `'resize'`\n * comes back when the last user restores. Users are counted per host, so overlapping sheets do not undo each other.\n * On a host without soft-input modes (iOS, desktop: no `setSoftInputMode`) nothing changes, as in MAUI.\n */\nexport function acquirePanSoftInputMode(host: G9HostServices): () => void {\n  const setMode = host.setSoftInputMode?.bind(host);\n  if (!setMode) return () => {};\n  const users = panUsers.get(host) ?? 0;\n  panUsers.set(host, users + 1);\n  if (users === 0) setMode('pan');\n  let restored = false;\n  return () => {\n    if (restored) return;\n    restored = true;\n    const remaining = (panUsers.get(host) as number) - 1;\n    panUsers.set(host, remaining);\n    if (remaining === 0) setMode('resize');\n  };\n}\n"],"names":["g9KeyboardTargetProps","Object","isKeyboardTarget","target","_target_dataset","panUsers","WeakMap","acquirePanSoftInputMode","host","_panUsers_get","_host_setSoftInputMode","setMode","users","restored","remaining"],"mappings":"AAOO,MAAMA,wBAAwBC,OAAO,MAAM,CAAC;IAAE,mBAAmB;AAAS;AAM1E,SAASC,iBACdC,MAAmF;QAE5EC;IAAP,OAAOA,AAAAA,CAAAA,QAAAA,SAAAA,KAAAA,IAAAA,QAAAA,CAAAA,kBAAAA,OAAQ,OAAO,AAAD,IAAdA,KAAAA,IAAAA,gBAAiB,UAAU,AAAD,MAAM;AACzC;AAEA,MAAMC,WAAW,IAAIC;AAQd,SAASC,wBAAwBC,IAAoB;QAG5CC;QAFEC;IAAhB,MAAMC,UAAU,QAAAD,CAAAA,yBAAAA,KAAK,gBAAgB,AAAD,IAApBA,KAAAA,IAAAA,uBAAuB,IAAI,CAACF;IAC5C,IAAI,CAACG,SAAS,OAAO,KAAO;IAC5B,MAAMC,QAAQ,QAAAH,CAAAA,gBAAAA,SAAS,GAAG,CAACD,KAAI,IAAjBC,gBAAsB;IACpCJ,SAAS,GAAG,CAACG,MAAMI,QAAQ;IAC3B,IAAIA,AAAU,MAAVA,OAAaD,QAAQ;IACzB,IAAIE,WAAW;IACf,OAAO;QACL,IAAIA,UAAU;QACdA,WAAW;QACX,MAAMC,YAAaT,SAAS,GAAG,CAACG,QAAmB;QACnDH,SAAS,GAAG,CAACG,MAAMM;QACnB,IAAIA,AAAc,MAAdA,WAAiBH,QAAQ;IAC/B;AACF"}

package/dist/host/layers.d.ts

@@ -0,0 +1,69 @@
+import type { ReactNode } from '@lynx-js/react';
+/**
+ * The page layers a `G9Host` owns, bottom to top (plan/specs/01 §5, MAUI `G9PageTemplate.xaml` z-stack). Sibling order
+ * is the z-order; nothing relies on `z-index`.
+ *
+ * | Layer | MAUI template host | Holds |
+ * | --- | --- | --- |
+ * | `content` | `ContentHost` | the page itself (painted over `BackdropHost`) |
+ * | `edgePanel` | (page content) | side panels sliding over the content (WP06) |
+ * | `sheets` | `OverlayHost` | bottom sheets and their scrims (WP05) |
+ * | `popups` | `G9PopupHost` | popups (WP07) |
+ * | `feedback` | `ToastHost` | toasts, loaders, progress overlays: above sheets and popups |
+ * | `floating` | `DevHost` | always-available floating affordances (developer FAB, QA pill) |
+ *
+ * Only the page-loading cover sits above `floating`.
+ */
+export declare const G9Layer: {
+    readonly Content: "content";
+    readonly EdgePanel: "edgePanel";
+    readonly Sheets: "sheets";
+    readonly Popups: "popups";
+    readonly Feedback: "feedback";
+    readonly Floating: "floating";
+};
+export type G9Layer = (typeof G9Layer)[keyof typeof G9Layer];
+/** Every layer, bottom to top. */
+export declare const g9LayerOrder: readonly G9Layer[];
+/** The layers items can be registered into (`content` is the page's own children). */
+export type G9OverlayLayer = Exclude<G9Layer, 'content'>;
+/** Position of `layer` in the z-stack (0 = bottom). */
+export declare function layerRank(layer: G9Layer): number;
+/** One thing mounted into a layer. */
+export interface G9LayerItem {
+    /** Identity within the layer. Registering an existing key replaces its element and order in place. */
+    readonly key: string;
+    /** What to render. */
+    readonly element: ReactNode;
+    /** Ordering inside the layer: lower paints first (below). Ties keep registration order (later on top). Default 0. */
+    readonly order?: number;
+}
+/** A registered item as the layer renders it. */
+export interface G9LayerEntry {
+    readonly key: string;
+    readonly element: ReactNode;
+    readonly order: number;
+    /** Registration sequence; stable while the key stays registered. */
+    readonly sequence: number;
+}
+/** The items of every overlay layer of one host. */
+export interface G9LayerStore {
+    /** The layer's items, bottom first. The same array until the layer changes. */
+    getSnapshot(layer: G9OverlayLayer): ReadonlyArray<G9LayerEntry>;
+    /** Called after each change of `layer`. Returns an unsubscribe function. */
+    subscribe(layer: G9OverlayLayer, listener: () => void): () => void;
+    /**
+     * Mounts `item` into `layer` (or replaces the item with the same key). Returns a function that removes exactly this
+     * registration: it does nothing once the key was removed or registered again by someone else.
+     */
+    register(layer: G9OverlayLayer, item: G9LayerItem): () => void;
+    /** Removes the item with `key`; `false` when there was none. */
+    remove(layer: G9OverlayLayer, key: string): boolean;
+    /** Number of items in `layer`. */
+    count(layer: G9OverlayLayer): number;
+    /** Removes every item of every layer (host unmount). */
+    clear(): void;
+}
+/** Creates an empty {@link G9LayerStore}. */
+export declare function createLayerStore(): G9LayerStore;
+//# sourceMappingURL=layers.d.ts.map

package/dist/host/layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../src/host/layers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO;;;;;;;CAOV,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,kCAAkC;AAClC,eAAO,MAAM,YAAY,EAAE,SAAS,OAAO,EAOzC,CAAC;AAEH,sFAAsF;AACtF,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAEzD,uDAAuD;AACvD,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIhD;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,sGAAsG;IACtG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,qHAAqH;IACrH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IAChE,4EAA4E;IAC5E,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACnE;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,IAAI,CAAC;IAC/D,gEAAgE;IAChE,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACpD,kCAAkC;IAClC,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAC;IACrC,wDAAwD;IACxD,KAAK,IAAI,IAAI,CAAC;CACf;AAsBD,6CAA6C;AAC7C,wBAAgB,gBAAgB,IAAI,YAAY,CAsE/C"}

package/dist/host/layers.jsx

@@ -0,0 +1,111 @@
+import { G9Error } from "@g9tm/lynxcontrols-foundation";
+const G9Layer = {
+    Content: 'content',
+    EdgePanel: 'edgePanel',
+    Sheets: 'sheets',
+    Popups: 'popups',
+    Feedback: 'feedback',
+    Floating: 'floating'
+};
+const g9LayerOrder = Object.freeze([
+    'content',
+    'edgePanel',
+    'sheets',
+    'popups',
+    'feedback',
+    'floating'
+]);
+function layerRank(layer) {
+    const rank = g9LayerOrder.indexOf(layer);
+    if (rank < 0) throw new G9Error('host-layer', `"${String(layer)}" is not a G9 layer.`);
+    return rank;
+}
+const EMPTY = Object.freeze([]);
+function checkLayer(layer) {
+    if ('content' === layer) throw new G9Error('host-layer', 'The content layer holds the page itself; register items into an overlay layer.');
+    layerRank(layer);
+}
+function checkItem(item) {
+    var _item_order;
+    if ('string' != typeof (null == item ? void 0 : item.key) || '' === item.key) throw new G9Error('host-layer-item', 'A layer item needs a non-empty string key.');
+    const order = null != (_item_order = item.order) ? _item_order : 0;
+    if ('number' != typeof order || !Number.isFinite(order)) throw new G9Error('host-layer-item', `Layer item "${item.key}" has an invalid order (${String(order)}).`);
+    return order;
+}
+function createLayerStore() {
+    const layers = new Map();
+    const snapshots = new Map();
+    const listeners = new Map();
+    let sequence = 0;
+    function changed(layer) {
+        var _ref, _listeners_get;
+        var _layers_get;
+        const entries = Array.from(null != (_ref = null == (_layers_get = layers.get(layer)) ? void 0 : _layers_get.values()) ? _ref : []);
+        entries.sort((a, b)=>a.order - b.order || a.sequence - b.sequence);
+        snapshots.set(layer, entries.length ? Object.freeze(entries) : EMPTY);
+        for (const listener of Array.from(null != (_listeners_get = listeners.get(layer)) ? _listeners_get : []))listener();
+    }
+    const store = {
+        getSnapshot (layer) {
+            var _snapshots_get;
+            return null != (_snapshots_get = snapshots.get(layer)) ? _snapshots_get : EMPTY;
+        },
+        subscribe (layer, listener) {
+            checkLayer(layer);
+            let set = listeners.get(layer);
+            if (!set) {
+                set = new Set();
+                listeners.set(layer, set);
+            }
+            set.add(listener);
+            return ()=>{
+                set.delete(listener);
+            };
+        },
+        register (layer, item) {
+            checkLayer(layer);
+            const order = checkItem(item);
+            let entries = layers.get(layer);
+            if (!entries) {
+                entries = new Map();
+                layers.set(layer, entries);
+            }
+            const existing = entries.get(item.key);
+            sequence += 1;
+            const entry = Object.freeze({
+                key: item.key,
+                element: item.element,
+                order,
+                sequence: existing ? existing.sequence : sequence
+            });
+            entries.set(item.key, entry);
+            changed(layer);
+            return ()=>{
+                var _layers_get;
+                if ((null == (_layers_get = layers.get(layer)) ? void 0 : _layers_get.get(item.key)) === entry) store.remove(layer, item.key);
+            };
+        },
+        remove (layer, key) {
+            checkLayer(layer);
+            const entries = layers.get(layer);
+            if (!(null == entries ? void 0 : entries.delete(key))) return false;
+            changed(layer);
+            return true;
+        },
+        count (layer) {
+            var _ref;
+            var _layers_get;
+            return null != (_ref = null == (_layers_get = layers.get(layer)) ? void 0 : _layers_get.size) ? _ref : 0;
+        },
+        clear () {
+            for (const [layer, entries] of Array.from(layers))if (0 !== entries.size) {
+                entries.clear();
+                changed(layer);
+            }
+        }
+    };
+    return store;
+}
+export { G9Layer, createLayerStore, g9LayerOrder, layerRank };
+
+//# sourceMappingURL=layers.jsx.map

package/dist/host/layers.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"host/layers.jsx","sources":["../../src/host/layers.ts"],"sourcesContent":["import { G9Error } from '@g9tm/lynxcontrols-foundation';\nimport type { ReactNode } from '@lynx-js/react';\n\n/**\n * The page layers a `G9Host` owns, bottom to top (plan/specs/01 §5, MAUI `G9PageTemplate.xaml` z-stack). Sibling order\n * is the z-order; nothing relies on `z-index`.\n *\n * | Layer | MAUI template host | Holds |\n * | --- | --- | --- |\n * | `content` | `ContentHost` | the page itself (painted over `BackdropHost`) |\n * | `edgePanel` | (page content) | side panels sliding over the content (WP06) |\n * | `sheets` | `OverlayHost` | bottom sheets and their scrims (WP05) |\n * | `popups` | `G9PopupHost` | popups (WP07) |\n * | `feedback` | `ToastHost` | toasts, loaders, progress overlays: above sheets and popups |\n * | `floating` | `DevHost` | always-available floating affordances (developer FAB, QA pill) |\n *\n * Only the page-loading cover sits above `floating`.\n */\nexport const G9Layer = {\n  Content: 'content',\n  EdgePanel: 'edgePanel',\n  Sheets: 'sheets',\n  Popups: 'popups',\n  Feedback: 'feedback',\n  Floating: 'floating',\n} as const;\nexport type G9Layer = (typeof G9Layer)[keyof typeof G9Layer];\n\n/** Every layer, bottom to top. */\nexport const g9LayerOrder: readonly G9Layer[] = Object.freeze([\n  'content',\n  'edgePanel',\n  'sheets',\n  'popups',\n  'feedback',\n  'floating',\n]);\n\n/** The layers items can be registered into (`content` is the page's own children). */\nexport type G9OverlayLayer = Exclude<G9Layer, 'content'>;\n\n/** Position of `layer` in the z-stack (0 = bottom). */\nexport function layerRank(layer: G9Layer): number {\n  const rank = g9LayerOrder.indexOf(layer);\n  if (rank < 0) throw new G9Error('host-layer', `\"${String(layer)}\" is not a G9 layer.`);\n  return rank;\n}\n\n/** One thing mounted into a layer. */\nexport interface G9LayerItem {\n  /** Identity within the layer. Registering an existing key replaces its element and order in place. */\n  readonly key: string;\n  /** What to render. */\n  readonly element: ReactNode;\n  /** Ordering inside the layer: lower paints first (below). Ties keep registration order (later on top). Default 0. */\n  readonly order?: number;\n}\n\n/** A registered item as the layer renders it. */\nexport interface G9LayerEntry {\n  readonly key: string;\n  readonly element: ReactNode;\n  readonly order: number;\n  /** Registration sequence; stable while the key stays registered. */\n  readonly sequence: number;\n}\n\n/** The items of every overlay layer of one host. */\nexport interface G9LayerStore {\n  /** The layer's items, bottom first. The same array until the layer changes. */\n  getSnapshot(layer: G9OverlayLayer): ReadonlyArray<G9LayerEntry>;\n  /** Called after each change of `layer`. Returns an unsubscribe function. */\n  subscribe(layer: G9OverlayLayer, listener: () => void): () => void;\n  /**\n   * Mounts `item` into `layer` (or replaces the item with the same key). Returns a function that removes exactly this\n   * registration: it does nothing once the key was removed or registered again by someone else.\n   */\n  register(layer: G9OverlayLayer, item: G9LayerItem): () => void;\n  /** Removes the item with `key`; `false` when there was none. */\n  remove(layer: G9OverlayLayer, key: string): boolean;\n  /** Number of items in `layer`. */\n  count(layer: G9OverlayLayer): number;\n  /** Removes every item of every layer (host unmount). */\n  clear(): void;\n}\n\nconst EMPTY: ReadonlyArray<G9LayerEntry> = Object.freeze([]);\n\nfunction checkLayer(layer: G9OverlayLayer): void {\n  if (layer === ('content' as G9Layer)) {\n    throw new G9Error('host-layer', 'The content layer holds the page itself; register items into an overlay layer.');\n  }\n  layerRank(layer);\n}\n\nfunction checkItem(item: G9LayerItem): number {\n  if (typeof item?.key !== 'string' || item.key === '') {\n    throw new G9Error('host-layer-item', 'A layer item needs a non-empty string key.');\n  }\n  const order = item.order ?? 0;\n  if (typeof order !== 'number' || !Number.isFinite(order)) {\n    throw new G9Error('host-layer-item', `Layer item \"${item.key}\" has an invalid order (${String(order)}).`);\n  }\n  return order;\n}\n\n/** Creates an empty {@link G9LayerStore}. */\nexport function createLayerStore(): G9LayerStore {\n  const layers = new Map<G9OverlayLayer, Map<string, G9LayerEntry>>();\n  const snapshots = new Map<G9OverlayLayer, ReadonlyArray<G9LayerEntry>>();\n  const listeners = new Map<G9OverlayLayer, Set<() => void>>();\n  let sequence = 0;\n\n  function changed(layer: G9OverlayLayer): void {\n    const entries = Array.from(layers.get(layer)?.values() ?? []);\n    entries.sort((a, b) => a.order - b.order || a.sequence - b.sequence);\n    snapshots.set(layer, entries.length ? Object.freeze(entries) : EMPTY);\n    for (const listener of Array.from(listeners.get(layer) ?? [])) listener();\n  }\n\n  const store: G9LayerStore = {\n    getSnapshot(layer) {\n      return snapshots.get(layer) ?? EMPTY;\n    },\n    subscribe(layer, listener) {\n      checkLayer(layer);\n      let set = listeners.get(layer);\n      if (!set) {\n        set = new Set();\n        listeners.set(layer, set);\n      }\n      set.add(listener);\n      return () => {\n        set.delete(listener);\n      };\n    },\n    register(layer, item) {\n      checkLayer(layer);\n      const order = checkItem(item);\n      let entries = layers.get(layer);\n      if (!entries) {\n        entries = new Map();\n        layers.set(layer, entries);\n      }\n      const existing = entries.get(item.key);\n      sequence += 1;\n      const entry: G9LayerEntry = Object.freeze({\n        key: item.key,\n        element: item.element,\n        order,\n        sequence: existing ? existing.sequence : sequence,\n      });\n      entries.set(item.key, entry);\n      changed(layer);\n      return () => {\n        if (layers.get(layer)?.get(item.key) === entry) store.remove(layer, item.key);\n      };\n    },\n    remove(layer, key) {\n      checkLayer(layer);\n      const entries = layers.get(layer);\n      if (!entries?.delete(key)) return false;\n      changed(layer);\n      return true;\n    },\n    count(layer) {\n      return layers.get(layer)?.size ?? 0;\n    },\n    clear() {\n      for (const [layer, entries] of Array.from(layers)) {\n        if (entries.size === 0) continue;\n        entries.clear();\n        changed(layer);\n      }\n    },\n  };\n  return store;\n}\n"],"names":["G9Layer","g9LayerOrder","Object","layerRank","layer","rank","G9Error","String","EMPTY","checkLayer","checkItem","item","_item_order","order","Number","createLayerStore","layers","Map","snapshots","listeners","sequence","changed","_listeners_get","_layers_get","entries","Array","a","b","listener","store","_snapshots_get","set","Set","existing","entry","key"],"mappings":"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"}

package/dist/host/page-loading-overlay.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from '@lynx-js/react';
+/** Props of {@link G9PageLoadingOverlay}. */
+export interface G9PageLoadingOverlayProps {
+    /** Play the exit (scale to 0.9 and fade, 200 ms). */
+    readonly exiting?: boolean;
+    /** Cover colour. Default the theme's `Primary`. */
+    readonly backgroundColor?: string;
+    /** Spinner colour. Default the theme's `OnPrimary`. */
+    readonly spinnerColor?: string;
+}
+/**
+ * The full-screen cover that hides a page while it assembles itself (MAUI `G9PageLoadingOverlay`): input-opaque, a
+ * centred 48 px spinner, the top of the host's z-stack. `G9Host` mounts it and removes it after its exit; set the app
+ * default colours with `settings.pageLoading` (match the native splash colour for a seamless hand-off).
+ */
+export declare function G9PageLoadingOverlay(props: G9PageLoadingOverlayProps): ReactNode;
+//# sourceMappingURL=page-loading-overlay.d.ts.map

package/dist/host/page-loading-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-loading-overlay.d.ts","sourceRoot":"","sources":["../../src/host/page-loading-overlay.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,6CAA6C;AAC7C,MAAM,WAAW,yBAAyB;IACxC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,SAAS,CAahF"}

package/dist/host/page-loading-overlay.jsx

@@ -0,0 +1,16 @@
+const spinnerStyle = (color)=>({
+        borderLeftColor: color,
+        borderRightColor: color,
+        borderBottomColor: color
+    });
+function G9PageLoadingOverlay(props) {
+    var _props_backgroundColor, _props_spinnerColor;
+    return <view className={`g9-page-loading${props.exiting ? ' g9-page-loading--exiting' : ''}`} style={{
+        backgroundColor: null != (_props_backgroundColor = props.backgroundColor) ? _props_backgroundColor : 'var(--g9-primary)'
+    }} accessibility-element={true} accessibility-label="Loading" catchtap={()=>{}}>
+      <view className="g9-page-loading__spinner" style={spinnerStyle(null != (_props_spinnerColor = props.spinnerColor) ? _props_spinnerColor : 'var(--g9-on-primary)')}/>
+    </view>;
+}
+export { G9PageLoadingOverlay };
+
+//# sourceMappingURL=page-loading-overlay.jsx.map

package/dist/host/page-loading-overlay.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"host/page-loading-overlay.jsx","sources":["../../src/host/page-loading-overlay.tsx"],"sourcesContent":["import type { ReactNode } from '@lynx-js/react';\n\n/** Props of {@link G9PageLoadingOverlay}. */\nexport interface G9PageLoadingOverlayProps {\n  /** Play the exit (scale to 0.9 and fade, 200 ms). */\n  readonly exiting?: boolean;\n  /** Cover colour. Default the theme's `Primary`. */\n  readonly backgroundColor?: string;\n  /** Spinner colour. Default the theme's `OnPrimary`. */\n  readonly spinnerColor?: string;\n}\n\n// Three coloured sides and a transparent top make the rotating arc (inline styles win over the class).\nconst spinnerStyle = (color: string) => ({ borderLeftColor: color, borderRightColor: color, borderBottomColor: color });\n\n/**\n * The full-screen cover that hides a page while it assembles itself (MAUI `G9PageLoadingOverlay`): input-opaque, a\n * centred 48 px spinner, the top of the host's z-stack. `G9Host` mounts it and removes it after its exit; set the app\n * default colours with `settings.pageLoading` (match the native splash colour for a seamless hand-off).\n */\nexport function G9PageLoadingOverlay(props: G9PageLoadingOverlayProps): ReactNode {\n  return (\n    <view\n      className={`g9-page-loading${props.exiting ? ' g9-page-loading--exiting' : ''}`}\n      style={{ backgroundColor: props.backgroundColor ?? 'var(--g9-primary)' }}\n      accessibility-element={true}\n      accessibility-label=\"Loading\"\n      // Input-opaque on purpose: a tap must not reach a control that is not wired up yet (MAUI).\n      catchtap={() => {}}\n    >\n      <view className=\"g9-page-loading__spinner\" style={spinnerStyle(props.spinnerColor ?? 'var(--g9-on-primary)')} />\n    </view>\n  );\n}\n"],"names":["spinnerStyle","color","G9PageLoadingOverlay","props","_props_backgroundColor","_props_spinnerColor","view"],"mappings":"AAaA,MAAMA,eAAe,CAACC,QAAmB;QAAE,iBAAiBA;QAAO,kBAAkBA;QAAO,mBAAmBA;IAAM;AAO9G,SAASC,qBAAqBC,KAAgC;QAIrCC,wBAMqCC;IATnE,QACGC,KACC,WAAW,CAAC,eAAe,EAAEH,MAAM,OAAO,GAAG,8BAA8B,IAAI,EAC/E,OAAO;QAAE,iBAAiB,QAAAC,CAAAA,yBAAAA,MAAM,eAAe,AAAD,IAApBA,yBAAyB;IAAoB,GACvE,uBAAuB,MACvB,oBAAoB,UAEpB,UAAU,KAAO,GAClB;MACC,CAACE,KAAK,UAAU,2BAA2B,OAAON,aAAa,QAAAK,CAAAA,sBAAAA,MAAM,YAAY,AAAD,IAAjBA,sBAAsB,0BAA2B;IAClH,EAAEC;AAEN"}

package/dist/host/readiness.d.ts

@@ -0,0 +1,57 @@
+import { type G9AbortSignal } from '@g9tm/lynxcontrols-foundation';
+/** Duration of the cover's exit (MAUI: scale to 0.9 and fade out together, 200 ms, cubic-in). */
+export declare const g9PageLoadingExitMs = 200;
+/** Margin of the cover's watchdog behind the normal path (MAUI `RunPageLoadingWatchdogAsync`). */
+export declare const g9PageLoadingWatchdogMarginMs = 500;
+/** State of a host's page-loading cover and ready signal. */
+export interface G9HostReadinessSnapshot {
+    /** The page reported itself ready: automatically after `onAppearing`, or by `release()`. Latched. */
+    readonly ready: boolean;
+    /** `'covering'` while the cover hides the page, `'exiting'` during its 200 ms exit, `'hidden'` otherwise. */
+    readonly cover: 'covering' | 'exiting' | 'hidden';
+    /** The cover is gone for good (it is one-shot per host, as in MAUI). */
+    readonly dismissed: boolean;
+}
+/** A host's readiness, as pages and outside code use it (MAUI `G9PageBase` loading-overlay members). */
+export interface G9HostReadiness {
+    getSnapshot(): G9HostReadinessSnapshot;
+    subscribe(listener: (snapshot: G9HostReadinessSnapshot) => void): () => void;
+    /**
+     * Reports the page visually ready (MAUI `ReleasePageLoadingOverlay`): the cover leaves after the dismiss delay.
+     * Idempotent; calling it before the page appeared, or after the cover left, is harmless.
+     */
+    release(): void;
+    /** Settles once the cover has fully left, or at once when it never showed (MAUI `PageLoadingOverlayDismissed`). */
+    whenDismissed(): Promise<void>;
+}
+/** Inputs of {@link createHostReadiness}. */
+export interface G9HostReadinessOptions {
+    /** Whether the host shows the cover at all. */
+    readonly cover: boolean;
+    /** The page releases itself (MAUI `PageLoadingManualRelease`). */
+    readonly manualRelease: boolean;
+    readonly dismissDelayMs: number;
+    readonly safetyTimeoutMs: number;
+    /** The page's appearing work (MAUI `OnAppearingAfterParentAsync`); aborted when the page disappears. */
+    readonly runAppearing: (signal: G9AbortSignal) => Promise<void>;
+    /** Holds a busy activity while the cover is up (MAUI `G9Diagnostics.Activity("page:…")`); returns its release. */
+    readonly startActivity?: () => () => void;
+}
+/** The host-side driver of {@link G9HostReadiness}. */
+export interface G9HostReadinessController extends G9HostReadiness {
+    /** The page became visible (mount, or `active` turned on). */
+    appear(): void;
+    /** The page stopped being visible; an in-flight appearing run is aborted and the cover leaves. */
+    disappear(): void;
+    /** Unmount: stops every timer and settles `whenDismissed`. */
+    dispose(): void;
+}
+/**
+ * The MAUI page-loading lifecycle (`RunAppearingWithOverlayDismissAsync`, the watchdog and
+ * `DismissPageLoadingOverlayAsync`): on the first appearance run the appearing work, then (auto pages) report ready,
+ * wait for ready, wait the dismiss delay, and dismiss. Every wait is bounded by the safety timeout measured from the
+ * appearance, and a watchdog (safety + delay + 500 ms) dismisses even if the run never ends. Disappearing aborts the
+ * run and dismisses. Dismissal is one-shot; later appearances only run the appearing work.
+ */
+export declare function createHostReadiness(options: G9HostReadinessOptions): G9HostReadinessController;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/host/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/host/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAG1F,iGAAiG;AACjG,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,kGAAkG;AAClG,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACtC,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6GAA6G;IAC7G,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAClD,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,wGAAwG;AACxG,MAAM,WAAW,eAAe;IAC9B,WAAW,IAAI,uBAAuB,CAAC;IACvC,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC7E;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;IAChB,mHAAmH;IACnH,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,wGAAwG;IACxG,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,kHAAkH;IAClH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,MAAM,IAAI,CAAC;CAC3C;AAED,uDAAuD;AACvD,MAAM,WAAW,yBAA0B,SAAQ,eAAe;IAChE,8DAA8D;IAC9D,MAAM,IAAI,IAAI,CAAC;IACf,kGAAkG;IAClG,SAAS,IAAI,IAAI,CAAC;IAClB,8DAA8D;IAC9D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,sBAAsB,GAAG,yBAAyB,CAiI9F"}

package/dist/host/readiness.jsx

@@ -0,0 +1,138 @@
+import { createAbortController } from "@g9tm/lynxcontrols-foundation";
+import { createDisposer } from "../base/disposer.jsx";
+const g9PageLoadingExitMs = 200;
+const g9PageLoadingWatchdogMarginMs = 500;
+function createHostReadiness(options) {
+    const disposer = createDisposer();
+    const listeners = new Set();
+    let snapshot = Object.freeze({
+        ready: false,
+        cover: options.cover ? 'covering' : 'hidden',
+        dismissed: !options.cover
+    });
+    let resolveDismissed;
+    const dismissedPromise = new Promise((resolve)=>{
+        resolveDismissed = resolve;
+    });
+    if (!options.cover) resolveDismissed();
+    let readyWaiters = [];
+    let releaseActivity = options.cover && options.startActivity ? options.startActivity() : null;
+    let running = null;
+    function set(patch) {
+        snapshot = Object.freeze({
+            ...snapshot,
+            ...patch
+        });
+        if (disposer.disposed) return;
+        for (const listener of Array.from(listeners))listener(snapshot);
+    }
+    function stopActivity() {
+        const release = releaseActivity;
+        releaseActivity = null;
+        null == release || release();
+    }
+    function dismiss() {
+        if (snapshot.dismissed) return;
+        stopActivity();
+        set({
+            dismissed: true,
+            cover: 'exiting'
+        });
+        disposer.setTimeout(()=>{
+            set({
+                cover: 'hidden'
+            });
+            resolveDismissed();
+        }, g9PageLoadingExitMs);
+    }
+    function release() {
+        if (snapshot.ready) return;
+        set({
+            ready: true
+        });
+        const waiters = readyWaiters;
+        readyWaiters = [];
+        for (const waiter of waiters)waiter();
+    }
+    function race(signal, start) {
+        return new Promise((resolve)=>{
+            if (signal.aborted) return resolve(false);
+            const onAbort = ()=>resolve(false);
+            signal.addEventListener('abort', onAbort);
+            start(()=>{
+                signal.removeEventListener('abort', onAbort);
+                resolve(true);
+            });
+        });
+    }
+    async function run() {
+        const controller = createAbortController();
+        const signal = controller.signal;
+        running = {
+            abort: ()=>controller.abort()
+        };
+        const cancelSafety = disposer.setTimeout(()=>controller.abort(), options.safetyTimeoutMs);
+        try {
+            const appeared = await race(signal, (done)=>{
+                options.runAppearing(signal).then(done, done);
+            });
+            if (!appeared) return;
+            if (!options.manualRelease) release();
+            const ready = await race(signal, (done)=>{
+                if (snapshot.ready) done();
+                else readyWaiters.push(done);
+            });
+            if (!ready) return;
+            await race(signal, (done)=>{
+                disposer.setTimeout(done, options.dismissDelayMs);
+            });
+        } finally{
+            cancelSafety();
+            running = null;
+            if (!disposer.disposed) dismiss();
+        }
+    }
+    const controller = {
+        getSnapshot: ()=>snapshot,
+        subscribe (listener) {
+            listeners.add(listener);
+            return ()=>{
+                listeners.delete(listener);
+            };
+        },
+        release,
+        whenDismissed: ()=>dismissedPromise,
+        appear () {
+            if (disposer.disposed) return;
+            if (snapshot.dismissed) {
+                const appearance = createAbortController();
+                null == running || running.abort();
+                running = {
+                    abort: ()=>appearance.abort()
+                };
+                options.runAppearing(appearance.signal).then(()=>{
+                    if (!options.manualRelease) release();
+                }, ()=>{});
+                return;
+            }
+            if (running) return;
+            disposer.setTimeout(dismiss, options.safetyTimeoutMs + options.dismissDelayMs + g9PageLoadingWatchdogMarginMs);
+            run();
+        },
+        disappear () {
+            null == running || running.abort();
+        },
+        dispose () {
+            if (disposer.disposed) return;
+            null == running || running.abort();
+            stopActivity();
+            disposer.dispose();
+            readyWaiters = [];
+            resolveDismissed();
+        }
+    };
+    return controller;
+}
+export { createHostReadiness, g9PageLoadingExitMs, g9PageLoadingWatchdogMarginMs };
+
+//# sourceMappingURL=readiness.jsx.map

package/dist/host/readiness.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"host/readiness.jsx","sources":["../../src/host/readiness.ts"],"sourcesContent":["import { createAbortController, type G9AbortSignal } from '@g9tm/lynxcontrols-foundation';\nimport { createDisposer } from '../base/disposer';\n\n/** Duration of the cover's exit (MAUI: scale to 0.9 and fade out together, 200 ms, cubic-in). */\nexport const g9PageLoadingExitMs = 200;\n/** Margin of the cover's watchdog behind the normal path (MAUI `RunPageLoadingWatchdogAsync`). */\nexport const g9PageLoadingWatchdogMarginMs = 500;\n\n/** State of a host's page-loading cover and ready signal. */\nexport interface G9HostReadinessSnapshot {\n  /** The page reported itself ready: automatically after `onAppearing`, or by `release()`. Latched. */\n  readonly ready: boolean;\n  /** `'covering'` while the cover hides the page, `'exiting'` during its 200 ms exit, `'hidden'` otherwise. */\n  readonly cover: 'covering' | 'exiting' | 'hidden';\n  /** The cover is gone for good (it is one-shot per host, as in MAUI). */\n  readonly dismissed: boolean;\n}\n\n/** A host's readiness, as pages and outside code use it (MAUI `G9PageBase` loading-overlay members). */\nexport interface G9HostReadiness {\n  getSnapshot(): G9HostReadinessSnapshot;\n  subscribe(listener: (snapshot: G9HostReadinessSnapshot) => void): () => void;\n  /**\n   * Reports the page visually ready (MAUI `ReleasePageLoadingOverlay`): the cover leaves after the dismiss delay.\n   * Idempotent; calling it before the page appeared, or after the cover left, is harmless.\n   */\n  release(): void;\n  /** Settles once the cover has fully left, or at once when it never showed (MAUI `PageLoadingOverlayDismissed`). */\n  whenDismissed(): Promise<void>;\n}\n\n/** Inputs of {@link createHostReadiness}. */\nexport interface G9HostReadinessOptions {\n  /** Whether the host shows the cover at all. */\n  readonly cover: boolean;\n  /** The page releases itself (MAUI `PageLoadingManualRelease`). */\n  readonly manualRelease: boolean;\n  readonly dismissDelayMs: number;\n  readonly safetyTimeoutMs: number;\n  /** The page's appearing work (MAUI `OnAppearingAfterParentAsync`); aborted when the page disappears. */\n  readonly runAppearing: (signal: G9AbortSignal) => Promise<void>;\n  /** Holds a busy activity while the cover is up (MAUI `G9Diagnostics.Activity(\"page:…\")`); returns its release. */\n  readonly startActivity?: () => () => void;\n}\n\n/** The host-side driver of {@link G9HostReadiness}. */\nexport interface G9HostReadinessController extends G9HostReadiness {\n  /** The page became visible (mount, or `active` turned on). */\n  appear(): void;\n  /** The page stopped being visible; an in-flight appearing run is aborted and the cover leaves. */\n  disappear(): void;\n  /** Unmount: stops every timer and settles `whenDismissed`. */\n  dispose(): void;\n}\n\n/**\n * The MAUI page-loading lifecycle (`RunAppearingWithOverlayDismissAsync`, the watchdog and\n * `DismissPageLoadingOverlayAsync`): on the first appearance run the appearing work, then (auto pages) report ready,\n * wait for ready, wait the dismiss delay, and dismiss. Every wait is bounded by the safety timeout measured from the\n * appearance, and a watchdog (safety + delay + 500 ms) dismisses even if the run never ends. Disappearing aborts the\n * run and dismisses. Dismissal is one-shot; later appearances only run the appearing work.\n */\nexport function createHostReadiness(options: G9HostReadinessOptions): G9HostReadinessController {\n  const disposer = createDisposer();\n  const listeners = new Set<(snapshot: G9HostReadinessSnapshot) => void>();\n  let snapshot: G9HostReadinessSnapshot = Object.freeze({\n    ready: false,\n    cover: options.cover ? 'covering' : 'hidden',\n    dismissed: !options.cover,\n  });\n  let resolveDismissed!: () => void;\n  const dismissedPromise = new Promise<void>((resolve) => {\n    resolveDismissed = resolve;\n  });\n  if (!options.cover) resolveDismissed();\n  let readyWaiters: Array<() => void> = [];\n  let releaseActivity: (() => void) | null = options.cover && options.startActivity ? options.startActivity() : null;\n  let running: { abort(): void } | null = null;\n\n  function set(patch: Partial<G9HostReadinessSnapshot>): void {\n    snapshot = Object.freeze({ ...snapshot, ...patch });\n    if (disposer.disposed) return;\n    for (const listener of Array.from(listeners)) listener(snapshot);\n  }\n\n  function stopActivity(): void {\n    const release = releaseActivity;\n    releaseActivity = null;\n    release?.();\n  }\n\n  function dismiss(): void {\n    if (snapshot.dismissed) return;\n    // Released before the exit animation: the page is usable the moment dismissal starts (MAUI).\n    stopActivity();\n    set({ dismissed: true, cover: 'exiting' });\n    disposer.setTimeout(() => {\n      set({ cover: 'hidden' });\n      resolveDismissed();\n    }, g9PageLoadingExitMs);\n  }\n\n  function release(): void {\n    if (snapshot.ready) return;\n    set({ ready: true });\n    const waiters = readyWaiters;\n    readyWaiters = [];\n    for (const waiter of waiters) waiter();\n  }\n\n  /** Resolves `true` when `start` settles, `false` when the run is aborted first. */\n  function race(signal: G9AbortSignal, start: (done: () => void) => void): Promise<boolean> {\n    return new Promise<boolean>((resolve) => {\n      if (signal.aborted) return resolve(false);\n      const onAbort = () => resolve(false);\n      signal.addEventListener('abort', onAbort);\n      start(() => {\n        signal.removeEventListener('abort', onAbort);\n        resolve(true);\n      });\n    });\n  }\n\n  async function run(): Promise<void> {\n    const controller = createAbortController();\n    const signal = controller.signal;\n    running = { abort: () => controller.abort() };\n    const cancelSafety = disposer.setTimeout(() => controller.abort(), options.safetyTimeoutMs);\n    try {\n      const appeared = await race(signal, (done) => {\n        options.runAppearing(signal).then(done, done);\n      });\n      if (!appeared) return;\n      if (!options.manualRelease) release();\n      const ready = await race(signal, (done) => {\n        if (snapshot.ready) done();\n        else readyWaiters.push(done);\n      });\n      if (!ready) return;\n      await race(signal, (done) => {\n        disposer.setTimeout(done, options.dismissDelayMs);\n      });\n    } finally {\n      cancelSafety();\n      running = null;\n      if (!disposer.disposed) dismiss();\n    }\n  }\n\n  const controller: G9HostReadinessController = {\n    getSnapshot: () => snapshot,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    release,\n    whenDismissed: () => dismissedPromise,\n    appear() {\n      if (disposer.disposed) return;\n      if (snapshot.dismissed) {\n        const appearance = createAbortController();\n        running?.abort();\n        running = { abort: () => appearance.abort() };\n        options.runAppearing(appearance.signal).then(\n          () => {\n            if (!options.manualRelease) release();\n          },\n          () => {},\n        );\n        return;\n      }\n      if (running) return;\n      // The first appearance with the cover up (every later one finds it dismissed): start the watchdog once.\n      disposer.setTimeout(dismiss, options.safetyTimeoutMs + options.dismissDelayMs + g9PageLoadingWatchdogMarginMs);\n      void run();\n    },\n    disappear() {\n      running?.abort();\n    },\n    dispose() {\n      if (disposer.disposed) return;\n      running?.abort();\n      stopActivity();\n      disposer.dispose();\n      readyWaiters = [];\n      resolveDismissed();\n    },\n  };\n  return controller;\n}\n"],"names":["g9PageLoadingExitMs","g9PageLoadingWatchdogMarginMs","createHostReadiness","options","disposer","createDisposer","listeners","Set","snapshot","Object","resolveDismissed","dismissedPromise","Promise","resolve","readyWaiters","releaseActivity","running","set","patch","listener","Array","stopActivity","release","dismiss","waiters","waiter","race","signal","start","onAbort","run","controller","createAbortController","cancelSafety","appeared","done","ready","appearance"],"mappings":"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"}