@sigx/lynx-navigation 0.4.4 → 0.4.5

package/dist/hooks/use-hardware-back.js

@@ -1,28 +1,109 @@
-import { onMounted } from '@sigx/lynx';
+import { onMounted, onUnmounted } from '@sigx/lynx';
 import { BackHandler } from '@sigx/lynx-linking';
 import { useNav } from './use-nav.js';
 /**
- * Wire the Android hardware back button to the active navigator.
+ * Navigator trees with an active hardware-back registration, keyed by
+ * their root nav. Used to keep wiring idempotent per tree: `<NavigationRoot>`
+ * auto-wires by default, and an app that *also* calls `useHardwareBack()`
+ * (or migrates from manual wiring) must not end up with two listeners that
+ * both pop on a single back press. The first registration for a root wins;
+ * later ones are no-ops until it unsubscribes.
+ */
+const wiredRoots = new WeakSet();
+/** Walk up the `parent` chain to the top-most navigator. */
+function rootOf(nav) {
+    let cur = nav;
+    while (cur.parent)
+        cur = cur.parent;
+    return cur;
+}
+/**
+ * Subscribe the Android hardware back button/gesture to a navigator tree.
  *
  * Listens for `hardwareBackPress` events from `@sigx/lynx-linking`'s
  * `BackHandler` (which the native side dispatches from
- * `MainActivity.onBackPressed`). On press the handler walks to the
- * deepest currently-focused navigator (per-tab `<Stack>`s register with
- * their parent), then walks back up the `parent` chain looking for the
- * first nav that `canGoBack`:
+ * `MainActivity.onBackPressed`). On press the handler walks from the tree's
+ * root to the deepest currently-focused navigator (per-tab `<Stack>`s
+ * register with their parent), then walks back up the `parent` chain looking
+ * for the first nav that `canGoBack`:
  *
  *   - If any nav in the chain can go back → `nav.pop()` on that nav.
  *   - Otherwise → `BackHandler.exitApp()` (Android: `moveTaskToBack(true)`,
  *     keeps the bundle warm; iOS: rejects, since iOS doesn't permit
  *     programmatic termination).
  *
- * The traversal means you only need to call this once at the root — a
- * back press from inside a tab pops that tab's nested stack first, only
- * exiting the app once every level is at its base entry.
+ * **Idempotent per tree.** Only the first registration for a given root
+ * actually subscribes; later calls return a no-op disposer. So `<NavigationRoot>`
+ * auto-wiring this and an app calling `useHardwareBack()` coexist without
+ * double-popping.
+ *
+ * Returns a disposer that unsubscribes (and frees the root for re-wiring).
+ * No-op on iOS (event never fires) and in non-native environments (no
+ * `GlobalEventEmitter`, e.g. web/SSR/tests) — `addEventListener` returns a
+ * no-op subscription there.
+ *
+ * @internal Apps should rely on `<NavigationRoot>`'s default or call
+ * `useHardwareBack()`; this raw form exists so the root can wire from setup.
+ */
+export function wireHardwareBack(nav) {
+    const root = rootOf(nav);
+    // A registration for this tree already exists — don't add a second
+    // listener that would pop twice on one press.
+    if (wiredRoots.has(root))
+        return () => { };
+    wiredRoots.add(root);
+    const sub = BackHandler.addEventListener(() => {
+        // Walk down to the deepest focused nav. Per-tab `<Stack>`s register
+        // themselves via `parent._children.add(nav)`; only one child per
+        // level is `isLocallyFocused` at a time, so the traversal is
+        // unambiguous. Falls back to the root if no nested stacks are wired.
+        let active = root;
+        // Loop instead of recursion so a deeply-nested tree doesn't blow the
+        // stack on a synchronous back press.
+        outer: while (active._children.size > 0) {
+            for (const child of active._children) {
+                if (child.isLocallyFocused) {
+                    active = child;
+                    continue outer;
+                }
+            }
+            // No focused child at this level — stop drilling.
+            break;
+        }
+        // Walk back up the chain looking for the first nav that has something
+        // to pop. This is what makes "back press in trips tab with empty
+        // inner stack" fall through to root (which might have a modal on top)
+        // before exiting.
+        let cur = active;
+        while (cur) {
+            if (cur.canGoBack) {
+                cur.pop();
+                return true;
+            }
+            cur = cur.parent;
+        }
+        // At the root with nothing to pop — leave the app. Promise is
+        // fire-and-forget; we don't await because we want the back press to
+        // feel instant (Android starts the move-to-back transition
+        // immediately).
+        void BackHandler.exitApp();
+        return true;
+    });
+    return () => {
+        wiredRoots.delete(root);
+        sub.remove();
+    };
+}
+/**
+ * Wire the Android hardware back button to the active navigator.
+ *
+ * `<NavigationRoot>` already does this by default (see its `hardwareBack`
+ * prop). Use this hook only when you've opted out (`hardwareBack={false}`)
+ * and want to wire it yourself — it's safe to call regardless thanks to the
+ * idempotency in {@link wireHardwareBack}.
  *
- * Call this once in any component under `<NavigationRoot>` (typically a
- * thin wrapper sibling to `<Stack />`). iOS doesn't fire the event so the
- * hook is a no-op there.
+ * Call it once in any component under `<NavigationRoot>`. iOS doesn't fire
+ * the event so the hook is a no-op there.
  *
  * @example
  * ```tsx
@@ -31,7 +112,7 @@ import { useNav } from './use-nav.js';
  *     return () => null;
  * });
  *
- * <NavigationRoot routes={routes}>
+ * <NavigationRoot routes={routes} hardwareBack={false}>
  *     <BackHandlerWiring />
  *     <Stack />
  * </NavigationRoot>
@@ -39,46 +120,10 @@ import { useNav } from './use-nav.js';
  */
 export function useHardwareBack() {
     const nav = useNav();
-    onMounted(() => {
-        const sub = BackHandler.addEventListener(() => {
-            // Walk down to the deepest focused nav. Per-tab `<Stack>`s
-            // register themselves via `parent._children.add(nav)`; only one
-            // child per level is `isLocallyFocused` at a time, so the
-            // traversal is unambiguous. Falls back to the starting nav if
-            // no nested stacks are wired up.
-            let active = nav;
-            // Loop instead of recursion so a deeply-nested tree doesn't blow
-            // the stack on a synchronous back press.
-            outer: while (active._children.size > 0) {
-                for (const child of active._children) {
-                    if (child.isLocallyFocused) {
-                        active = child;
-                        continue outer;
-                    }
-                }
-                // No focused child at this level — stop drilling.
-                break;
-            }
-            // Walk back up the chain looking for the first nav that has
-            // something to pop. This is what makes "back press in trips
-            // tab with empty inner stack" fall through to root (which might
-            // have a modal on top) before exiting.
-            let cur = active;
-            while (cur) {
-                if (cur.canGoBack) {
-                    cur.pop();
-                    return true;
-                }
-                cur = cur.parent;
-            }
-            // At the root with nothing to pop — leave the app. Promise is
-            // fire-and-forget; we don't await because we want the back
-            // press to feel instant (Android starts the move-to-back
-            // transition immediately).
-            void BackHandler.exitApp();
-            return true;
-        });
-        return () => sub.remove();
-    });
+    // `onMounted`'s return value isn't a cleanup hook in sigx — register the
+    // disposer with `onUnmounted` explicitly so the listener is released.
+    let dispose = () => { };
+    onMounted(() => { dispose = wireHardwareBack(nav); });
+    onUnmounted(() => { dispose(); });
 }
 //# sourceMappingURL=use-hardware-back.js.map

package/dist/hooks/use-hardware-back.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-hardware-back.js","sourceRoot":"","sources":["../../src/hooks/use-hardware-back.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAY,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,GAAG,GAAG,WAAW,CAAC,gBAAgB,CAAC,GAAG,EAAE;YAC1C,2DAA2D;YAC3D,gEAAgE;YAChE,0DAA0D;YAC1D,8DAA8D;YAC9D,iCAAiC;YACjC,IAAI,MAAM,GAAQ,GAAG,CAAC;YACtB,iEAAiE;YACjE,yCAAyC;YACzC,KAAK,EAAE,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBACtC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;oBACnC,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;wBACzB,MAAM,GAAG,KAAK,CAAC;wBACf,SAAS,KAAK,CAAC;oBACnB,CAAC;gBACL,CAAC;gBACD,kDAAkD;gBAClD,MAAM;YACV,CAAC;YACD,4DAA4D;YAC5D,4DAA4D;YAC5D,gEAAgE;YAChE,uCAAuC;YACvC,IAAI,GAAG,GAAe,MAAM,CAAC;YAC7B,OAAO,GAAG,EAAE,CAAC;gBACT,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;oBAChB,GAAG,CAAC,GAAG,EAAE,CAAC;oBACV,OAAO,IAAI,CAAC;gBAChB,CAAC;gBACD,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;YACrB,CAAC;YACD,8DAA8D;YAC9D,2DAA2D;YAC3D,yDAAyD;YACzD,2BAA2B;YAC3B,KAAK,WAAW,CAAC,OAAO,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;IAC9B,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"use-hardware-back.js","sourceRoot":"","sources":["../../src/hooks/use-hardware-back.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAY,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,IAAI,OAAO,EAAO,CAAC;AAEtC,4DAA4D;AAC5D,SAAS,MAAM,CAAC,GAAQ;IACpB,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,OAAO,GAAG,CAAC,MAAM;QAAE,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;IACpC,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAQ;IACrC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,mEAAmE;IACnE,8CAA8C;IAC9C,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAC1C,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAErB,MAAM,GAAG,GAAG,WAAW,CAAC,gBAAgB,CAAC,GAAG,EAAE;QAC1C,oEAAoE;QACpE,iEAAiE;QACjE,6DAA6D;QAC7D,qEAAqE;QACrE,IAAI,MAAM,GAAQ,IAAI,CAAC;QACvB,qEAAqE;QACrE,qCAAqC;QACrC,KAAK,EAAE,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACtC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACnC,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;oBACzB,MAAM,GAAG,KAAK,CAAC;oBACf,SAAS,KAAK,CAAC;gBACnB,CAAC;YACL,CAAC;YACD,kDAAkD;YAClD,MAAM;QACV,CAAC;QACD,sEAAsE;QACtE,iEAAiE;QACjE,sEAAsE;QACtE,kBAAkB;QAClB,IAAI,GAAG,GAAe,MAAM,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC;YACT,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;gBAChB,GAAG,CAAC,GAAG,EAAE,CAAC;gBACV,OAAO,IAAI,CAAC;YAChB,CAAC;YACD,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;QACrB,CAAC;QACD,8DAA8D;QAC9D,oEAAoE;QACpE,2DAA2D;QAC3D,gBAAgB;QAChB,KAAK,WAAW,CAAC,OAAO,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,EAAE;QACR,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxB,GAAG,CAAC,MAAM,EAAE,CAAC;IACjB,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,yEAAyE;IACzE,sEAAsE;IACtE,IAAI,OAAO,GAAe,GAAG,EAAE,GAAE,CAAC,CAAC;IACnC,SAAS,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/dist/internal/layer-plan.d.ts

@@ -13,35 +13,51 @@
  *
  * Rules:
  *
- *  - **Idle (no transition).** Render the topmost non-overlay entry
- *    as the base, plus every overlay entry above it. Overlays
- *    (`modal` / `fullScreen` / `transparent-modal`) keep their
- *    underneath mounted; cards replace their underneath in the base
- *    layer.
+ *  - **Visible region.** Each branch first computes its *visible*
+ *    region — the layers the user can actually see:
+ *      - **Idle (no transition).** The topmost non-overlay entry as
+ *        the base, plus every overlay entry above it.
+ *      - **Card transition.** The underneath entry (parallax) + the
+ *        top entry (slide), both animated.
+ *      - **Overlay transition.** The static base..underneath run plus
+ *        the animated overlay top.
  *
- *  - **Card transition.** Two layers: the underneath entry (animated
- *    with the parallax-card-underneath spec) and the top entry
- *    (animated with the slide-in-from-right spec). After the
- *    transition completes, the idle rule kicks in — the underneath
- *    unmounts because the new top becomes the sole base.
+ *  - **Retention (card-stack screen retention).** Every entry *below*
+ *    the visible region's base is kept mounted as a `hidden: true`
+ *    static layer (`display: none`), instead of unmounting. So a card
+ *    push leaves the covered card mounted, and a pop reveals the
+ *    already-mounted underneath — no rebuild, no lost scroll/UI state
+ *    (matching native stacks). Overlays already preserved their
+ *    underneath; this extends the same retain-below-base behaviour to
+ *    cards, and to entries deeper than the immediate underneath during
+ *    a deep-stack transition.
  *
- *  - **Overlay transition.** The full idle layer stack up through the
- *    underneath entry stays static (no transform). The animated top
- *    is the only layer with a transform. After the transition, the
- *    overlay either joins the static idle stack (push) or unmounts
- *    (pop).
+ *  - **Bounds.** `maxRetained` (the `<Stack maxRetainedScreens>` prop)
+ *    caps how many covered cards stay mounted; `MAX_LAYERS` is the hard
+ *    renderer-slot cap. Both trim the *deepest* (front) layers, so the
+ *    visible region at the end of the list is never truncated.
  *
- * The Layer.key for the Stack render is
- * `layer-${entry.key}-${animVariant(layer.animation)}`. The variant
- * suffix forces a remount when an entry transitions from animated to
- * static (or vice versa) — `useAnimatedStyle` can't re-bind mid-life,
- * so we get a fresh `useAnimatedStyle` call per animation state.
- * Modal underneath layers never animate, so they stay statically
- * keyed across the modal lifecycle and their state (per-tab Stack,
- * scroll, in-flight inputs) survives.
+ * The Layer.key for the Stack render is `layer-${entry.key}` — stable
+ * across animation phases. `<Layer>` rebinds its transform reactively
+ * (via the reactive form of `useAnimatedStyle`) as `animation` flips
+ * between a spec and `null`, so the layer never remounts just to change
+ * its animation state and screen subtrees survive the transition. The
+ * reactive binding dedupes its own register/unregister by signature
+ * internally (see `useAnimatedStyle`), so no per-layer variant key is
+ * computed here.
  */
 import type { SharedValue } from '@sigx/lynx';
 import type { Presentation, StackEntry, TransitionState } from '../types.js';
+/**
+ * Hard cap on how many layers `<Stack>` renders at once. The Stack body
+ * emits exactly this many position-stable slots (unrolled), so
+ * `computeLayers` must never return more — excess deepest (hidden,
+ * retained) layers are trimmed off the front. The slots are mechanical
+ * (just verbose), so this can be raised if an app legitimately stacks
+ * more; 24 is high enough that normal card apps never hit the trim
+ * boundary, while still bounding retained-screen memory.
+ */
+export declare const MAX_LAYERS = 24;
 export type LayerAnimation = {
     axis: 'translateX' | 'translateY';
     inputRange: readonly [number, number];
@@ -53,17 +69,27 @@ export interface Layer {
     readonly entry: StackEntry;
     /** When non-null, the layer's host view binds a `useAnimatedStyle` mapper. */
     readonly animation: LayerAnimation | null;
+    /**
+     * Retained-but-covered layer: mounted (so its screen subtree, signals,
+     * and scroll offset survive), rendered with `display: none` so it costs
+     * no paint/layout while a higher opaque card covers it. Always paired
+     * with `animation: null` — a hidden layer never animates. Falsy/omitted
+     * = visible.
+     */
+    readonly hidden?: boolean;
 }
 export declare function isOverlayPresentation(p: Presentation): boolean;
-/**
- * Suffix used in a layer's render key. Stable for the layer's
- * lifetime (same entry, same animation kind) and changes when the
- * animation transitions on/off so the Layer remounts and rebinds.
- */
-export declare function animationVariant(animation: LayerAnimation | null): string;
 /**
  * Compute the visible-layer list for one render of `<Stack>`. Pure —
  * unit-testable independently of the renderer.
+ *
+ * Each branch produces `{ visBaseIdx, visible }`: `visible` is the
+ * animated/painted region, and `visBaseIdx` is the stack index of that
+ * region's lowest layer. Everything in `stack` below `visBaseIdx` is
+ * then retained as hidden static layers (see the module docstring).
+ *
+ * `maxRetained` caps the retained (hidden) layers; `undefined` means
+ * "retain all, bounded only by `MAX_LAYERS`".
  */
-export declare function computeLayers(stack: readonly StackEntry[], transition: TransitionState | null, progress: SharedValue<number> | null): Layer[];
+export declare function computeLayers(stack: readonly StackEntry[], transition: TransitionState | null, progress: SharedValue<number> | null, maxRetained?: number): Layer[];
 //# sourceMappingURL=layer-plan.d.ts.map

package/dist/internal/layer-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layer-plan.d.ts","sourceRoot":"","sources":["../../src/internal/layer-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EACR,YAAY,EACZ,UAAU,EAEV,eAAe,EAClB,MAAM,aAAa,CAAC;AAIrB,MAAM,MAAM,cAAc,GAAG;IACzB,IAAI,EAAE,YAAY,GAAG,YAAY,CAAC;IAClC,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,WAAW,KAAK;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,CAMzE;AAwCD;;;GAGG;AACH,wBAAgB,aAAa,CACzB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,eAAe,GAAG,IAAI,EAClC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,GACrC,KAAK,EAAE,CAwDT"}
+{"version":3,"file":"layer-plan.d.ts","sourceRoot":"","sources":["../../src/internal/layer-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EACR,YAAY,EACZ,UAAU,EAEV,eAAe,EAClB,MAAM,aAAa,CAAC;AAIrB;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,KAAK,CAAC;AAE7B,MAAM,MAAM,cAAc,GAAG;IACzB,IAAI,EAAE,YAAY,GAAG,YAAY,CAAC;IAClC,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,WAAW,KAAK;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAE9D;AAiDD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CACzB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,eAAe,GAAG,IAAI,EAClC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,EACpC,WAAW,CAAC,EAAE,MAAM,GACrB,KAAK,EAAE,CA+ET"}

package/dist/internal/layer-plan.js

@@ -1,20 +1,17 @@
 import { SCREEN_HEIGHT, SCREEN_WIDTH } from './screen-width.js';
 const PARALLAX_FACTOR = 0.3;
-export function isOverlayPresentation(p) {
-    return p === 'modal' || p === 'fullScreen' || p === 'transparent-modal';
-}
 /**
- * Suffix used in a layer's render key. Stable for the layer's
- * lifetime (same entry, same animation kind) and changes when the
- * animation transitions on/off so the Layer remounts and rebinds.
+ * Hard cap on how many layers `<Stack>` renders at once. The Stack body
+ * emits exactly this many position-stable slots (unrolled), so
+ * `computeLayers` must never return more — excess deepest (hidden,
+ * retained) layers are trimmed off the front. The slots are mechanical
+ * (just verbose), so this can be raised if an app legitimately stacks
+ * more; 24 is high enough that normal card apps never hit the trim
+ * boundary, while still bounding retained-screen memory.
  */
-export function animationVariant(animation) {
-    if (!animation)
-        return 'static';
-    // Output range alone identifies the transition shape — different
-    // animations (card-top vs card-underneath vs overlay-top, push vs
-    // pop) all land on different range tuples.
-    return `${animation.axis}:${animation.outputRange[0]}->${animation.outputRange[1]}`;
+export const MAX_LAYERS = 24;
+export function isOverlayPresentation(p) {
+    return p === 'modal' || p === 'fullScreen' || p === 'transparent-modal';
 }
 /**
  * Card-presentation transition transforms. `role='top'` is the entry
@@ -45,58 +42,97 @@ function overlayTopAnimation(kind, progress) {
     }
     return { axis: 'translateY', inputRange: [0, 1], outputRange: [0, SCREEN_HEIGHT], progress };
 }
+/** Walk back from `from` past overlay entries to the topmost non-overlay. */
+function nonOverlayBaseIdx(stack, from) {
+    let baseIdx = from;
+    while (baseIdx > 0 && isOverlayPresentation(stack[baseIdx].presentation)) {
+        baseIdx -= 1;
+    }
+    return baseIdx;
+}
 /**
  * Compute the visible-layer list for one render of `<Stack>`. Pure —
  * unit-testable independently of the renderer.
+ *
+ * Each branch produces `{ visBaseIdx, visible }`: `visible` is the
+ * animated/painted region, and `visBaseIdx` is the stack index of that
+ * region's lowest layer. Everything in `stack` below `visBaseIdx` is
+ * then retained as hidden static layers (see the module docstring).
+ *
+ * `maxRetained` caps the retained (hidden) layers; `undefined` means
+ * "retain all, bounded only by `MAX_LAYERS`".
  */
-export function computeLayers(stack, transition, progress) {
+export function computeLayers(stack, transition, progress, maxRetained) {
+    let visBaseIdx;
+    let visible;
     if (!transition) {
         // Idle: topmost non-overlay base + any overlays above it.
-        let baseIdx = stack.length - 1;
-        while (baseIdx > 0 && isOverlayPresentation(stack[baseIdx].presentation)) {
-            baseIdx -= 1;
-        }
-        return stack.slice(baseIdx).map((entry) => ({ entry, animation: null }));
+        visBaseIdx = nonOverlayBaseIdx(stack, stack.length - 1);
+        visible = stack
+            .slice(visBaseIdx)
+            .map((entry) => ({ entry, animation: null, hidden: false }));
     }
-    // A transition is in flight. `progress` may still be null when
-    // animations are disabled — produce static layers in that case
-    // (the animation never plays; the transition timer just ticks).
-    const isOverlay = isOverlayPresentation(transition.topEntry.presentation);
-    if (!isOverlay) {
-        // Card transition: just the two participating entries, both
-        // animated (parallax underneath + slide top).
-        return [
+    else if (!isOverlayPresentation(transition.topEntry.presentation)) {
+        // Card transition: the two participating entries, both animated
+        // (parallax underneath + slide top). `progress` may be null when
+        // animations are disabled — produce static layers in that case.
+        const underneathIdx = stack.findIndex((e) => e.key === transition.underneathEntry.key);
+        // Underneath is the visible base. If it isn't on the stack (e.g.
+        // mid-pop where the mutation already ran), retain nothing rather
+        // than slicing with a negative index.
+        visBaseIdx = underneathIdx >= 0 ? underneathIdx : 0;
+        visible = [
             {
                 entry: transition.underneathEntry,
                 animation: progress ? cardAnimation('underneath', transition.kind, progress) : null,
+                hidden: false,
             },
             {
                 entry: transition.topEntry,
                 animation: progress ? cardAnimation('top', transition.kind, progress) : null,
+                hidden: false,
             },
         ];
     }
-    // Overlay transition: render the full idle layer stack up through
-    // the underneath entry (all static — they don't animate) plus the
-    // animated top.
-    const underneathIdx = stack.findIndex((e) => e.key === transition.underneathEntry.key);
-    // If the underneath isn't in the stack (e.g. mid-pop where the
-    // stack mutation already removed an entry), fall back to the
-    // current top of the stack.
-    const lastStaticIdx = underneathIdx >= 0 ? underneathIdx : stack.length - 1;
-    let baseIdx = lastStaticIdx;
-    while (baseIdx > 0 && isOverlayPresentation(stack[baseIdx].presentation)) {
-        baseIdx -= 1;
+    else {
+        // Overlay transition: the full layer stack up through the
+        // underneath entry stays static (no transform) plus the animated
+        // top.
+        const underneathIdx = stack.findIndex((e) => e.key === transition.underneathEntry.key);
+        // If the underneath isn't in the stack (e.g. mid-pop where the
+        // stack mutation already removed an entry), fall back to the
+        // current top of the stack.
+        const lastStaticIdx = underneathIdx >= 0 ? underneathIdx : stack.length - 1;
+        visBaseIdx = nonOverlayBaseIdx(stack, lastStaticIdx);
+        const staticLayers = stack
+            .slice(visBaseIdx, lastStaticIdx + 1)
+            .map((entry) => ({ entry, animation: null, hidden: false }));
+        visible = [
+            ...staticLayers,
+            {
+                entry: transition.topEntry,
+                animation: progress ? overlayTopAnimation(transition.kind, progress) : null,
+                hidden: false,
+            },
+        ];
+    }
+    // Retention: every entry below the visible base stays mounted as a
+    // hidden static layer. Ordered deepest-first so each surviving entry
+    // keeps a stable slot index across pushes/pops (the Stack renderer's
+    // fixed slots remount keyed children whose slot index shifts).
+    const retained = stack
+        .slice(0, visBaseIdx)
+        .map((entry) => ({ entry, animation: null, hidden: true }));
+    let result = [...retained, ...visible];
+    // Apply the user's retention window, then the hard renderer cap.
+    // Both trim the deepest (front) layers, so the visible region at the
+    // tail is never truncated.
+    if (maxRetained != null && retained.length > maxRetained) {
+        result = result.slice(retained.length - maxRetained);
+    }
+    if (result.length > MAX_LAYERS) {
+        result = result.slice(result.length - MAX_LAYERS);
     }
-    const staticLayers = stack
-        .slice(baseIdx, lastStaticIdx + 1)
-        .map((entry) => ({ entry, animation: null }));
-    return [
-        ...staticLayers,
-        {
-            entry: transition.topEntry,
-            animation: progress ? overlayTopAnimation(transition.kind, progress) : null,
-        },
-    ];
+    return result;
 }
 //# sourceMappingURL=layer-plan.js.map

package/dist/internal/layer-plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"layer-plan.js","sourceRoot":"","sources":["../../src/internal/layer-plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"layer-plan.js","sourceRoot":"","sources":["../../src/internal/layer-plan.ts"],"names":[],"mappings":"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"}

package/dist/navigator/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/navigator/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAKH,KAAK,WAAW,EACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAIR,QAAQ,EACR,UAAU,EAEb,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE;QACf,gBAAgB,IAAI,IAAI,CAAC;QACzB,iBAAiB,IAAI,IAAI,CAAC;QAC1B,iBAAiB,IAAI,IAAI,CAAC;KAC7B,CAAC;IACF;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,EAAE;QACf,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QACzC,wEAAwE;QACxE,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QAC3C,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;KACrD,CAAC;IACF;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3D;AAuED,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACpB;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,sBAAsB,GAAG,cAAc,CA0TjF"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/navigator/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAMH,KAAK,WAAW,EACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAIR,QAAQ,EACR,UAAU,EAEb,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE;QACf,gBAAgB,IAAI,IAAI,CAAC;QACzB,iBAAiB,IAAI,IAAI,CAAC;QAC1B,iBAAiB,IAAI,IAAI,CAAC;KAC7B,CAAC;IACF;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,EAAE;QACf,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QACzC,wEAAwE;QACxE,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QAC3C,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;KACrD,CAAC;IACF;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3D;AAuED,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACpB;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,sBAAsB,GAAG,cAAc,CA8UjF"}

package/dist/navigator/core.js

@@ -1,4 +1,4 @@
-import { runOnMainThread, signal, untrack, } from '@sigx/lynx';
+import { batch, runOnMainThread, signal, untrack, } from '@sigx/lynx';
 import { isLazyComponent } from '@sigx/lynx';
 import { withTiming } from '@sigx/lynx-motion';
 /**
@@ -155,19 +155,28 @@ export function createNavigatorState(opts) {
         const newEntry = makeEntry(name, params, search, options, routes);
         const cur = getStack();
         const prevTop = cur[cur.length - 1];
-        // Append eagerly — UX-wise the user just initiated a forward nav, so
-        // the new entry should be queryable immediately (`nav.current` =
-        // newEntry). The slide animation overlays the visual transition.
-        setStack([...cur, newEntry]);
         const animated = options?.animated !== false && !!progress;
+        // Commit the stack append and the transition in a single batch so the
+        // Stack renders once with both screens already present. Without the
+        // batch, `@sigx/reactivity` flushes the stack write eagerly, producing
+        // an intermediate render where only the new top is on the stack and
+        // no transition is in flight — `computeLayers` would drop the
+        // underneath and the Stack would remount it on the next render.
+        // Append eagerly so the new entry is queryable immediately
+        // (`nav.current` = newEntry); the slide animation overlays the visual.
+        batch(() => {
+            setStack([...cur, newEntry]);
+            if (animated) {
+                setTransition({
+                    kind: 'push',
+                    topEntry: newEntry,
+                    underneathEntry: prevTop,
+                    progress,
+                });
+            }
+        });
         if (!animated)
             return;
-        setTransition({
-            kind: 'push',
-            topEntry: newEntry,
-            underneathEntry: prevTop,
-            progress,
-        });
         animateProgress(1, TRANSITION_DURATION_SEC).then(() => setTransition(null), () => setTransition(null));
     });
     const replace = ((name, ...args) => {
@@ -208,14 +217,21 @@ export function createNavigatorState(opts) {
             progress,
         });
         animateProgress(1, TRANSITION_DURATION_SEC).then(() => {
-            setStack(cur.slice(0, cur.length - 1));
-            setTransition(null);
+            // Batch so the commit (drop the popped entry) and clearing the
+            // transition land in one render — no intermediate frame where
+            // the stack has mutated but the transition is still in flight.
+            batch(() => {
+                setStack(cur.slice(0, cur.length - 1));
+                setTransition(null);
+            });
         }, () => {
             // On animation failure, snap to the destination state anyway —
             // leaving the popped entry rendered would be more confusing
             // than skipping the animation.
-            setStack(cur.slice(0, cur.length - 1));
-            setTransition(null);
+            batch(() => {
+                setStack(cur.slice(0, cur.length - 1));
+                setTransition(null);
+            });
         });
     }
     function popTo(name) {
@@ -243,8 +259,10 @@ export function createNavigatorState(opts) {
         if (state.stack.length === 0) {
             throw new Error('[lynx-navigation] reset() called with empty stack.');
         }
-        setStack([...state.stack]);
-        setTransition(null);
+        batch(() => {
+            setStack([...state.stack]);
+            setTransition(null);
+        });
     }
     function dismiss() {
         if (isTransitioning())
@@ -282,10 +300,12 @@ export function createNavigatorState(opts) {
     }
     function commitBackGesture() {
         const cur = getStack();
-        if (cur.length >= 2) {
-            setStack(cur.slice(0, cur.length - 1));
-        }
-        setTransition(null);
+        batch(() => {
+            if (cur.length >= 2) {
+                setStack(cur.slice(0, cur.length - 1));
+            }
+            setTransition(null);
+        });
     }
     function cancelBackGesture() {
         setTransition(null);