@sigx/lynx-navigation 0.2.0 → 0.4.1

package/README.md

@@ -148,17 +148,46 @@ Inside a tab body, `useNav()` resolves to the **innermost** navigator:
   nav **and** every ancestor is focused (parent's current entry matches +
   enclosing tab is active).
 
+**Modal preservation.** When a `modal` / `fullScreen` /
+`transparent-modal` push goes onto the root navigator (via escalation
+from a per-tab stack), `<Stack>` keeps the underneath entry mounted
+behind the overlay. Per-tab stack state, scroll positions, and in-flight
+inputs all survive the modal lifecycle. Card pushes still replace the
+underneath in the base layer — the user's mental model is "back
+recreates the previous screen from history".
+
 **Limitations (current slice)**:
 
-- Pushing a modal re-mounts the underlying root entry (the Tabs UI),
-  resetting inner-tab stack state. To preserve inner state across modals,
-  hoist app state out of screens.
 - One global route registry — there's no per-tab whitelist yet. Deep-link
   routing always pushes against the innermost nav of the caller site
   (modal routes still escalate). A future slice may add `<Stack routes={…}>`.
 - `useNavSerializer` snapshots one nav only — nested-tab stack state isn't
   persisted across reload yet.
 
+### Per-stack header chrome
+
+`<Stack>` accepts a default slot — its children render *inside* the
+stack's nav scope, above the active screen. That's how to give a
+nested per-tab stack its own header, since the root-level `<Header />`
+only tracks the root navigator:
+
+```tsx
+<Tabs.Screen name="trips" label="Trips">
+    <Stack initialRoute="tripsHome">
+        <Header />   {/* useNav() here resolves to the per-tab nav */}
+    </Stack>
+</Tabs.Screen>
+```
+
+Without this, a `<Header />` placed as a sibling of `<Stack>` would
+resolve `useNav()` to the *enclosing* nav and never react to pushes
+inside the nested stack — the back button + title wouldn't update on
+`nav.push('tripDetail', ...)`.
+
+For a daisy-themed bar (height, padding, centred title, separator),
+use `<NavHeader />` from `@sigx/lynx-daisyui` — same slot position,
+same `useScreenChrome()` data source.
+
 ### `<Screen>`
 
 Per-route slot container. Lets a screen declare its header / tab-bar item
@@ -185,13 +214,61 @@ const Profile = component(() => () => (
 All sub-slots are optional. Anything not declared falls back to the
 navigator's default chrome.
 
+**Placement — `<Screen>` is a child component, return it from
+render.** `<Screen>` and its slot-filler siblings (`<Screen.Header>`,
+`<Screen.HeaderRight>`, etc.) each call `useScreenRegistry()` from
+their *own* setup, which means they have to actually mount inside
+your screen's `<EntryScope>` to find the registry — and that only
+happens when JSX returned from your render function is reconciled
+into the tree. Constructing `<Screen ... />` JSX inside setup without
+returning it doesn't mount anything:
+
+```tsx
+// ✗ Won't take effect — the JSX is created but never rendered.
+const Profile = component(() => {
+    <Screen title="Profile" />;
+    return () => <view>profile body</view>;
+});
+
+// ✓ Returned from render — gets mounted, registers its options.
+const Profile = component(() => {
+    return () => (
+        <Screen title="Profile">
+            <view>profile body</view>
+        </Screen>
+    );
+});
+```
+
+When `<Screen>` *does* mount outside of any `<EntryScope>` — typically
+because the consumer placed it at the app root instead of inside a
+route component — it throws:
+
+> `[lynx-navigation] No screen registry in scope. `<Screen>` (and
+> `<Screen.Header>`, etc.) must be used inside a route component
+> rendered by `<Stack>`.`
+
+If you need to write options *imperatively* at setup time (e.g. to
+react to a hook result before the first render), reach for
+`useScreenOptions(...)` — it calls `useScreenRegistry()` directly
+from your own setup, where the EntryScope's registry is already
+visible.
+
 ### `<Header>`
 
-Default navigator header. Reads the focused entry's `<Screen.Header>`
-slot if set, otherwise renders `headerLeft | title | headerRight` with a
-back button as the default `headerLeft` when `nav.canGoBack` is true.
-Pulls `title` / `headerShown` / `gestureEnabled` from the focused
-screen's `useScreenOptions(...)` registration.
+**Headless** default navigator header — bare `<view>`/`<text>` nodes,
+no flex direction, no padding, no theme. Reads the focused entry's
+`<Screen.Header>` slot if set, otherwise renders
+`headerLeft | title | headerRight` with a back button as the default
+`headerLeft` when `nav.canGoBack` is true. Pulls `title` /
+`headerShown` / `gestureEnabled` from the focused screen's
+`useScreenOptions(...)` registration (or declarative `<Screen title=…>`).
+
+For a daisy-themed bar with sensible defaults (surface colour,
+separator, fixed ~48dp height, centred title), use `<NavHeader />`
+from `@sigx/lynx-daisyui` — same data source via `useScreenChrome()`.
+Custom designs can build their own component on top of
+`useScreenChrome()` without touching internals.
 
 ```tsx
 <NavigationRoot routes={routes} initialRoute="home">
@@ -312,6 +389,49 @@ const Profile = component(() => {
 });
 ```
 
+Equivalent declarative form via `<Screen>`:
+
+```tsx
+<Screen title={() => `User ${id}`} />
+```
+
+`<Screen>` only patches keys you actually pass — omitting `title`
+won't clear a title set elsewhere on the same entry. Safe to use a
+bare `<Screen>` purely to host `<Screen.HeaderRight>` slots without
+worrying about wiping a sibling `useScreenOptions(...)` write.
+
+### `useScreenChrome()`
+
+Reactive read of the focused screen's options + slot fills, plus
+navigation helpers a header would need (`canGoBack`, `pop`). The
+public foundation for building custom header components without
+touching internal modules — `<NavHeader />` in `@sigx/lynx-daisyui` is
+built on this.
+
+```tsx
+import { useScreenChrome } from '@sigx/lynx-navigation';
+
+const MyHeader = component(() => {
+    const chrome = useScreenChrome();
+    return () => {
+        if (!chrome.headerShown) return null;
+        return (
+            <view class="my-header">
+                {chrome.canGoBack
+                    ? <view bindtap={chrome.pop}><text>‹ Back</text></view>
+                    : null}
+                <text>{chrome.title}</text>
+                {chrome.headerRight?.()}
+            </view>
+        );
+    };
+});
+```
+
+Every property is a getter — reading it inside a render or `computed`
+subscribes to the underlying signal, so the consumer re-renders when
+title / slots change.
+
 ### `useLinkingNav(options?)`
 
 Bridges `@sigx/lynx-linking` URL events into the navigator. Call once

package/dist/components/EntryScope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntryScope.d.ts","sourceRoot":"","sources":["../../src/components/EntryScope.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAyC,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAGhF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,KAAK,eAAe,GACd,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,GACtC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAE7B;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU;;EAUrB,CAAC"}
+{"version":3,"file":"EntryScope.d.ts","sourceRoot":"","sources":["../../src/components/EntryScope.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAyC,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAQhF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,KAAK,eAAe,GACd,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,GACtC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAE7B;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU;;EAgBrB,CAAC"}

package/dist/components/EntryScope.js

@@ -1,5 +1,5 @@
 import { component, defineProvide, onUnmounted } from '@sigx/lynx';
-import { useCurrentEntry, useNavInternals, useScreenRegistry } from '../hooks/use-nav-internal.js';
+import { useCurrentEntry, useCurrentEntryOptional, useNavInternals, useScreenRegistry, } from '../hooks/use-nav-internal.js';
 import { createScreenRegistry } from '../internal/screen-registry.js';
 /**
  * Provider wrapper for a single screen mount.
@@ -24,9 +24,15 @@ export const EntryScope = component(({ props, slots }) => {
     const registry = createScreenRegistry(props.entry);
     internals.screens.register(registry);
     onUnmounted(() => {
-        internals.screens.unregister(props.entry.key);
+        // Pass the registry instance — `unregister` is identity-checked,
+        // so this is a no-op when a newer EntryScope has already taken
+        // over the same entry key (e.g. at the transition→idle handoff
+        // where the reconciler mounts the new EntryScope before
+        // unmounting the old).
+        internals.screens.unregister(registry);
     });
     defineProvide(useCurrentEntry, () => props.entry);
+    defineProvide(useCurrentEntryOptional, () => props.entry);
     defineProvide(useScreenRegistry, () => registry);
     return () => slots.default?.();
 });

package/dist/components/EntryScope.js.map

@@ -1 +1 @@
-{"version":3,"file":"EntryScope.js","sourceRoot":"","sources":["../../src/components/EntryScope.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAe,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAOtE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;IACtE,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACnD,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,WAAW,CAAC,GAAG,EAAE;QACb,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IACH,aAAa,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClD,aAAa,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC;IACjD,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;AACnC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"EntryScope.js","sourceRoot":"","sources":["../../src/components/EntryScope.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAe,MAAM,YAAY,CAAC;AAChF,OAAO,EACH,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,iBAAiB,GACpB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAOtE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;IACtE,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACnD,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,WAAW,CAAC,GAAG,EAAE;QACb,iEAAiE;QACjE,+DAA+D;QAC/D,+DAA+D;QAC/D,wDAAwD;QACxD,uBAAuB;QACvB,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IACH,aAAa,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClD,aAAa,CAAC,uBAAuB,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1D,aAAa,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC;IACjD,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;AACnC,CAAC,CAAC,CAAC"}

package/dist/components/Layer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `<Layer>` — one row in `<Stack>`'s layered render. Absolutely-
+ * positioned host view that fills the Stack's relative wrapper, with
+ * an optional MT-bound `translateX` / `translateY` animation driven
+ * by a `SharedValue<number>` from the navigator's transition state.
+ *
+ * `<Stack>` emits one `<Layer>` per entry returned by
+ * `computeLayers(...)`. Layer.key in the parent is
+ * `layer-${entry.key}-${animationVariant(animation)}` so that:
+ *
+ *  - The same entry under the same animation state is preserved across
+ *    renders (modal underneath stays mounted through the modal
+ *    lifecycle; per-tab Stack state survives).
+ *  - An entry transitioning between animated and static (e.g. a card
+ *    top after its push transition completes) remounts so the
+ *    `useAnimatedStyle` binding can be rebound — the underlying
+ *    `useAnimatedStyle` is set-once at setup and can't switch its
+ *    mapper at runtime.
+ *
+ * Layouts:
+ *  - Host view is `position: absolute; top/right/bottom/left: 0;
+ *    display: flex; flexDirection: column` so descendants that
+ *    flex-fill (SafeAreaView, daisyui screens) get a sized parent.
+ *  - No background. Screens own their own surface colour (typically
+ *    via a daisy `bg-base-*` class on the screen body).
+ */
+import { type ComponentFactory, type Define } from '@sigx/lynx';
+import type { LayerAnimation } from '../internal/layer-plan.js';
+import type { RouteMap, StackEntry } from '../types.js';
+export type LayerProps = Define.Prop<'entry', StackEntry, true> & Define.Prop<'routes', RouteMap, true>
+/** When set, the host view animates per the transform spec. */
+ & Define.Prop<'animation', LayerAnimation | null, false>;
+export declare const Layer: ComponentFactory<LayerProps, void, {}>;
+//# sourceMappingURL=Layer.d.ts.map

package/dist/components/Layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Layer.d.ts","sourceRoot":"","sources":["../../src/components/Layer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAIH,KAAK,gBAAgB,EACrB,KAAK,MAAM,EAEd,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGxD,MAAM,MAAM,UAAU,GAChB,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,GACtC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC;AACvC,+DAA+D;GAC7D,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC;AAE7D,eAAO,MAAM,KAAK,wCAkDhB,CAAC"}

package/dist/components/Layer.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+/**
+ * `<Layer>` — one row in `<Stack>`'s layered render. Absolutely-
+ * positioned host view that fills the Stack's relative wrapper, with
+ * an optional MT-bound `translateX` / `translateY` animation driven
+ * by a `SharedValue<number>` from the navigator's transition state.
+ *
+ * `<Stack>` emits one `<Layer>` per entry returned by
+ * `computeLayers(...)`. Layer.key in the parent is
+ * `layer-${entry.key}-${animationVariant(animation)}` so that:
+ *
+ *  - The same entry under the same animation state is preserved across
+ *    renders (modal underneath stays mounted through the modal
+ *    lifecycle; per-tab Stack state survives).
+ *  - An entry transitioning between animated and static (e.g. a card
+ *    top after its push transition completes) remounts so the
+ *    `useAnimatedStyle` binding can be rebound — the underlying
+ *    `useAnimatedStyle` is set-once at setup and can't switch its
+ *    mapper at runtime.
+ *
+ * Layouts:
+ *  - Host view is `position: absolute; top/right/bottom/left: 0;
+ *    display: flex; flexDirection: column` so descendants that
+ *    flex-fill (SafeAreaView, daisyui screens) get a sized parent.
+ *  - No background. Screens own their own surface colour (typically
+ *    via a daisy `bg-base-*` class on the screen body).
+ */
+import { component, useMainThreadRef, useAnimatedStyle, } from '@sigx/lynx';
+import { Suspense, isLazyComponent } from '@sigx/lynx';
+import { EntryScope } from './EntryScope.js';
+export const Layer = component(({ props }) => {
+    const ref = useMainThreadRef(null);
+    // `useAnimatedStyle` binds once at setup. Calling it conditionally
+    // is safe because setup runs once per mount and props.animation
+    // never changes for a given Layer instance — animation changes
+    // re-key the Layer at the parent, forcing a fresh mount.
+    if (props.animation) {
+        const a = props.animation;
+        useAnimatedStyle(ref, a.progress, a.axis, {
+            inputRange: [a.inputRange[0], a.inputRange[1]],
+            outputRange: [a.outputRange[0], a.outputRange[1]],
+        });
+    }
+    return () => {
+        const route = props.routes[props.entry.route];
+        if (!route)
+            return null;
+        const Comp = route.component;
+        if (typeof Comp !== 'function')
+            return null;
+        const entryParams = props.entry.params;
+        const body = isLazyComponent(Comp) && route.fallback
+            ? (_jsx(Suspense, { fallback: route.fallback, children: _jsx(Comp, { ...entryParams }) }))
+            : _jsx(Comp, { ...entryParams });
+        return (_jsx("view", { "main-thread:ref": ref, style: {
+                position: 'absolute',
+                top: '0',
+                left: '0',
+                right: '0',
+                bottom: '0',
+                display: 'flex',
+                flexDirection: 'column',
+            }, children: _jsx(EntryScope, { entry: props.entry, children: body }, props.entry.key) }));
+    };
+});
+//# sourceMappingURL=Layer.js.map

package/dist/components/Layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Layer.js","sourceRoot":"","sources":["../../src/components/Layer.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACH,SAAS,EACT,gBAAgB,EAChB,gBAAgB,GAInB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGvD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQ7C,MAAM,CAAC,MAAM,KAAK,GAAG,SAAS,CAAa,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;IACrD,MAAM,GAAG,GAAG,gBAAgB,CAA4B,IAAI,CAAC,CAAC;IAC9D,mEAAmE;IACnE,gEAAgE;IAChE,+DAA+D;IAC/D,yDAAyD;IACzD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAClB,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;QAC1B,gBAAgB,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE;YACtC,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC9C,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;SACpD,CAAC,CAAC;IACP,CAAC;IAED,OAAO,GAAG,EAAE;QACR,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,SAIlB,CAAC;QACF,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,OAAO,IAAI,CAAC;QAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,MAAiC,CAAC;QAClE,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ;YAChD,CAAC,CAAC,CACE,KAAC,QAAQ,IAAC,QAAQ,EAAE,KAAK,CAAC,QAAiB,YACvC,KAAC,IAAI,OAAK,WAAW,GAAI,GAClB,CACd;YACD,CAAC,CAAC,KAAC,IAAI,OAAK,WAAW,GAAI,CAAC;QAChC,OAAO,CACH,kCACqB,GAAG,EACpB,KAAK,EAAE;gBACH,QAAQ,EAAE,UAAU;gBACpB,GAAG,EAAE,GAAG;gBACR,IAAI,EAAE,GAAG;gBACT,KAAK,EAAE,GAAG;gBACV,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE,MAAM;gBACf,aAAa,EAAE,QAAQ;aAC1B,YAED,KAAC,UAAU,IAAuB,KAAK,EAAE,KAAK,CAAC,KAAK,YAC/C,IAAI,IADQ,KAAK,CAAC,KAAK,CAAC,GAAG,CAEnB,GACV,CACV,CAAC;IACN,CAAC,CAAC;AACN,CAAC,CAAC,CAAC"}

package/dist/components/Screen.d.ts

@@ -50,9 +50,9 @@ type TabBarItemProps = Define.Slot<'default'>;
  * call site shown in the file header.
  */
 export declare const Screen: ((props: {
-    title?: string | (() => string) | undefined;
-    headerShown?: boolean | undefined;
     gestureEnabled?: boolean | undefined;
+    headerShown?: boolean | undefined;
+    title?: string | (() => string) | undefined;
 } & {} & {
     slots?: Partial<{
         default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
@@ -62,18 +62,18 @@ export declare const Screen: ((props: {
     children?: any;
 }) => import("@sigx/runtime-core").JSXElement) & {
     __setup: import("@sigx/runtime-core").SetupFn<{
-        title?: string | (() => string) | undefined;
-        headerShown?: boolean | undefined;
         gestureEnabled?: boolean | undefined;
+        headerShown?: boolean | undefined;
+        title?: string | (() => string) | undefined;
     }, ScreenProps, void, {
         default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
     }>;
     __name?: string;
     __islandId?: string;
     __props: {
-        title?: string | (() => string) | undefined;
-        headerShown?: boolean | undefined;
         gestureEnabled?: boolean | undefined;
+        headerShown?: boolean | undefined;
+        title?: string | (() => string) | undefined;
     };
     __events: ScreenProps;
     __ref: void;

package/dist/components/Screen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Screen.d.ts","sourceRoot":"","sources":["../../src/components/Screen.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAA0B,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAIjE,KAAK,WAAW,GACV,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC,GAC7C,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GACnC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GACtC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAgB7B,KAAK,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAoB9C;;;;;;;;;GASG;AACH,KAAK,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAmB9C;;;;GAIG;AACH,eAAO,MAAM,MAAM;4BAzEwB,MAAM;;;;;;;;;;;;gCAAN,MAAM;;;;;;;;;gCAAN,MAAM;;;;;;;;;;;;;;;;;;;;;;CA8E/C,CAAC"}
+{"version":3,"file":"Screen.d.ts","sourceRoot":"","sources":["../../src/components/Screen.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAA0B,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAKjE,KAAK,WAAW,GACV,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC,GAC7C,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GACnC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GACtC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAiB7B,KAAK,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAoB9C;;;;;;;;;GASG;AACH,KAAK,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAmB9C;;;;GAIG;AACH,eAAO,MAAM,MAAM;;;4BA1EwB,MAAM;;;;;;;;;;;;gCAAN,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+E/C,CAAC"}

package/dist/components/Screen.js

@@ -35,15 +35,19 @@ import { useScreenRegistry } from '../hooks/use-nav-internal.js';
 import { mergeOptions, setSlot } from '../internal/screen-registry.js';
 const ScreenRoot = component(({ props, slots }) => {
     const registry = useScreenRegistry();
-    // Apply options whenever the component sets up. Options are reactive
-    // through the registry's `options` signal — chrome consumers re-render
-    // on the next merge. We don't bother diffing here: the patch is small
-    // and writes only happen during setup + explicit prop changes upstream.
-    mergeOptions(registry, {
-        title: props.title,
-        headerShown: props.headerShown,
-        gestureEnabled: props.gestureEnabled,
-    });
+    // Apply options whenever the component sets up. Only set keys that
+    // were actually passed — `mergeOptions` treats `undefined` as "clear
+    // this key", so building the patch from raw `props.X` would wipe
+    // every option a previous `useScreenOptions(...)` (or another `<Screen>`)
+    // had set on this same entry.
+    const patch = {};
+    if (props.title !== undefined)
+        patch.title = props.title;
+    if (props.headerShown !== undefined)
+        patch.headerShown = props.headerShown;
+    if (props.gestureEnabled !== undefined)
+        patch.gestureEnabled = props.gestureEnabled;
+    mergeOptions(registry, patch);
     return () => slots.default?.();
 });
 /**

package/dist/components/Screen.js.map

@@ -1 +1 @@
-{"version":3,"file":"Screen.js","sourceRoot":"","sources":["../../src/components/Screen.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAe,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAQvE,MAAM,UAAU,GAAG,SAAS,CAAc,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;IAC3D,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;IACrC,qEAAqE;IACrE,uEAAuE;IACvE,sEAAsE;IACtE,wEAAwE;IACxE,YAAY,CAAC,QAAQ,EAAE;QACnB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,cAAc,EAAE,KAAK,CAAC,cAAc;KACvC,CAAC,CAAC;IACH,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;AACnC,CAAC,CAAC,CAAC;AAIH;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAA6C;IACjE,OAAO,SAAS,CAAkB,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;QAC5C,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;QACrC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACjD,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;QACtD,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC;IACtB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;AACxC,MAAM,UAAU,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;AAChD,MAAM,WAAW,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;AAclD,MAAM,UAAU,GAAG,SAAS,CAAkB,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;IACxD,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;IACrC,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAC,GAAG,EAAE,EAAE;QACpC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC9B,iEAAiE;QACjE,iEAAiE;QACjE,IAAI,OAAO,GAAG,KAAK,UAAU;YAAE,OAAQ,GAAkC,CAAC,GAAG,CAAC,CAAC;QAC/E,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACrB,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,OAAQ,KAAoC,CAAC,GAAG,CAAC,CAAC;QACvF,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC,CAAC,CAAC;IACH,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;IAC9D,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC;AACtB,CAAC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE;IAC5C,MAAM;IACN,UAAU;IACV,WAAW;IACX,UAAU;CACb,CAAC,CAAC"}
+{"version":3,"file":"Screen.js","sourceRoot":"","sources":["../../src/components/Screen.tsx"],"names":[],"mappings":"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"}

package/dist/components/Stack.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentFactory, type Define } from '@sigx/lynx';
+import { type Define } from '@sigx/lynx';
 type StackProps = 
 /**
  * Mint a nested navigator with this route at its base. When set, the
@@ -17,7 +17,19 @@ Define.Prop<'initialRoute', string>
 /** Initial params for the nested-stack base entry. */
  & Define.Prop<'initialParams', Record<string, unknown>>
 /** Initial search for the nested-stack base entry. */
- & Define.Prop<'initialSearch', Record<string, unknown>>;
+ & Define.Prop<'initialSearch', Record<string, unknown>>
+/**
+ * Optional chrome rendered *above* the active screen, **inside this
+ * Stack's nav scope**. The intended use is `<Header />`, which needs
+ * to resolve `useNav()` to the per-stack nav (not the enclosing one)
+ * so it can react to pushes inside this stack — e.g. show a back
+ * button when a card is pushed onto a per-tab stack.
+ *
+ * Without this, a `<Header />` placed as a sibling of `<Stack>`
+ * would see the enclosing nav and never update when pushes happen
+ * inside the nested stack.
+ */
+ & Define.Slot<'default'>;
 /**
  * Stack navigator — renders the topmost stack entry's component at rest, or
  * the top + underneath entries during a transition.
@@ -46,21 +58,34 @@ Define.Prop<'initialRoute', string>
  * walks to root and overlays the whole UI. `replace` stays strictly local
  * (asymmetric with `push`) so a modal `replace` never wipes the root stack.
  *
- * **Render strategy** (same in both modes):
- *  - **Idle**: just the top entry, full-bleed, no transform. The screen
- *    component mounts directly so it can use its own layout (no extra
- *    absolute positioning that would break percentage heights).
- *  - **Transitioning**: two `<ScreenContainer>` instances stacked
- *    absolutely, each with an MT-driven `translateX` that reads from the
- *    navigator's progress `SharedValue`. The host's BG thread doesn't tick
- *    per frame — `useAnimatedStyle` runs the interpolation entirely on MT.
+ * **Render strategy.** Stack always emits the same JSX shape — a
+ * relative wrapper containing one `<Layer>` per entry returned by
+ * `computeLayers(stack, transition, progress)`. Each Layer is an
+ * absolutely-positioned host view with optional MT-bound translate
+ * animation. The pure layer-plan function decides:
+ *
+ *  - **Idle.** Topmost non-overlay base + any overlays above it. All
+ *    static (no transform). Overlays (`modal` / `fullScreen` /
+ *    `transparent-modal`) keep their underneath mounted; cards
+ *    replace their underneath in the base layer.
+ *  - **Card transition.** Both top and underneath animate (slide-in
+ *    + parallax). After settle, idle rules apply — the underneath
+ *    unmounts because the new top is the sole base.
+ *  - **Overlay transition.** The full idle layer stack up through
+ *    the underneath stays static; only the animated top has a
+ *    transform. After settle, the overlay either joins the static
+ *    idle stack (push) or unmounts (pop).
  *
- * `key={top.key}` keeps the idle render's component instance stable across
- * unrelated re-renders. During transitions, composite keys
- * (`${entry.key}-${role}-${kind}`) ensure a fresh mount per role/kind pair
- * so the `useAnimatedStyle` binding is set with the right input/output
- * ranges.
+ * Layer keys are `layer-${entry.key}-${animationVariant}`. The variant
+ * suffix forces a remount when an entry transitions from animated to
+ * static (or vice versa) — `useAnimatedStyle` binds once at setup and
+ * can't switch its mapper at runtime. Modal underneath layers never
+ * animate, so their key is stable across the modal lifecycle and the
+ * subtree's state (per-tab Stack navigators, scroll positions,
+ * in-flight inputs) survives.
  */
-export declare const Stack: ComponentFactory<StackProps, void, {}>;
+export declare const Stack: import("@sigx/runtime-core").ComponentFactory<StackProps, void, {
+    default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+}>;
 export {};
 //# sourceMappingURL=Stack.d.ts.map

package/dist/components/Stack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Stack.d.ts","sourceRoot":"","sources":["../../src/components/Stack.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOH,KAAK,gBAAgB,EACrB,KAAK,MAAM,EAEd,MAAM,YAAY,CAAC;AAgBpB,KAAK,UAAU;AACX;;;;;;;;;;;;GAYG;AACD,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC;AACrC,sDAAsD;GACpD,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACvD,sDAAsD;GACpD,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAI5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,KAAK,wCA+NhB,CAAC"}
+{"version":3,"file":"Stack.d.ts","sourceRoot":"","sources":["../../src/components/Stack.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOH,KAAK,MAAM,EACd,MAAM,YAAY,CAAC;AAepB,KAAK,UAAU;AACX;;;;;;;;;;;;GAYG;AACD,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC;AACrC,sDAAsD;GACpD,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACvD,sDAAsD;GACpD,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACvD;;;;;;;;;;GAUG;GACD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAI7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,KAAK;;EAuPhB,CAAC"}