@satinhq/kit 0.0.0-stage → 0.1.0-beta.1

package/dist/navigation/motionTokens.d.ts

@@ -0,0 +1,43 @@
+/** Measured from the iOS 26.5 Settings app on iPhone 17 Pro. */
+export declare const NAVIGATION_DURATION_MS = 352;
+export declare const NAVIGATION_EASING: readonly [0.21, 0.71, 0.3, 1];
+export declare const NAVIGATION_EASING_CSS: string;
+export declare const NAVIGATION_PARALLAX_FRACTION = 0.3;
+export declare const NAVIGATION_DIM_OPACITY = 0.1;
+export declare const NAVIGATION_EDGE_SHADOW_WIDTH_PX = 20;
+export declare const NAVIGATION_EDGE_SHADOW_OPACITY = 0.018;
+/** Legacy non-touch fallback. Installed touch uses releaseDecision statistics. */
+export declare const NAVIGATION_POSITION_THRESHOLD = 0.425;
+export declare const NAVIGATION_VELOCITY_THRESHOLD_PX_PER_SECOND = 317;
+export declare const NAVIGATION_HORIZONTAL_INTENT_PX = 30;
+/** Chosen inside UIKit's observed 10-12 point direction-lock window. */
+export declare const NAVIGATION_DIRECTION_LOCK_PX = 10;
+export declare const navigationMotionTokens: Readonly<{
+    dimOpacity: 0.1;
+    directionLockPx: 10;
+    durationMs: 352;
+    easing: readonly [0.21, 0.71, 0.3, 1];
+    edgeShadowOpacity: 0.018;
+    edgeShadowWidthPx: 20;
+    horizontalIntentPx: 30;
+    parallaxFraction: 0.3;
+    positionThreshold: 0.425;
+    releaseSampleRateHz: 240;
+    releaseSpring: Readonly<{
+        damping: 35.60471674068432;
+        mass: 1;
+        stiffness: 438.6490844928604;
+    }>;
+    velocityThresholdPxPerSecond: 317;
+    releaseCompletion: "first edge arrival";
+    flickVelocityBoost: 1;
+    nativeControllerFlickVelocityBoost: 4.25;
+    initialFlickHistoryThresholdWidthsPerSecond: 1.5;
+    touchReleaseProjectionSeconds: 0.35;
+    touchReleaseThresholdPoints: 187.5;
+    trackingResponseSeconds: 0.08;
+    trackingDampingRatio: 0.85;
+}>;
+export declare function clampProgress(progress: number): number;
+export declare function sampleNavigationCurve(timeProgress: number): number;
+export declare function shouldCompleteInteractivePop(progress: number, velocityPointsPerSecond: number): boolean;

package/dist/navigation/motionTokens.js

@@ -0,0 +1,75 @@
+// The navigation push/pop timing model: measured durations, curve and thresholds, plus the
+// sampling helpers that read them. Values come from the native references named beside them.
+import { NAVIGATION_EDGE_FLICK_BOOST, NAVIGATION_EDGE_FLICK_NORMALIZED_VELOCITY, NAVIGATION_PROJECTION_SECONDS, NAVIGATION_PROJECTED_COMPLETION_POINTS, } from './releaseDecision.js';
+import { NAVIGATION_TRACKING_DAMPING_RATIO, NAVIGATION_TRACKING_RESPONSE_SECONDS, } from './tracking.js';
+import { NAVIGATION_RELEASE_SAMPLE_RATE_HZ, NAVIGATION_RELEASE_SPRING_DAMPING, NAVIGATION_RELEASE_SPRING_MASS, NAVIGATION_RELEASE_SPRING_STIFFNESS, } from './releaseTrajectory.js';
+/** Measured from the iOS 26.5 Settings app on iPhone 17 Pro. */
+export const NAVIGATION_DURATION_MS = 352;
+export const NAVIGATION_EASING = Object.freeze([0.21, 0.71, 0.3, 1]);
+export const NAVIGATION_EASING_CSS = `cubic-bezier(${NAVIGATION_EASING.join(', ')})`;
+export const NAVIGATION_PARALLAX_FRACTION = 0.3;
+export const NAVIGATION_DIM_OPACITY = 0.1;
+export const NAVIGATION_EDGE_SHADOW_WIDTH_PX = 20;
+export const NAVIGATION_EDGE_SHADOW_OPACITY = 0.018;
+/** Legacy non-touch fallback. Installed touch uses releaseDecision statistics. */
+export const NAVIGATION_POSITION_THRESHOLD = 0.425;
+export const NAVIGATION_VELOCITY_THRESHOLD_PX_PER_SECOND = 317;
+export const NAVIGATION_HORIZONTAL_INTENT_PX = 30;
+/** Chosen inside UIKit's observed 10-12 point direction-lock window. */
+export const NAVIGATION_DIRECTION_LOCK_PX = 10;
+export const navigationMotionTokens = Object.freeze({
+    dimOpacity: NAVIGATION_DIM_OPACITY,
+    directionLockPx: NAVIGATION_DIRECTION_LOCK_PX,
+    durationMs: NAVIGATION_DURATION_MS,
+    easing: NAVIGATION_EASING,
+    edgeShadowOpacity: NAVIGATION_EDGE_SHADOW_OPACITY,
+    edgeShadowWidthPx: NAVIGATION_EDGE_SHADOW_WIDTH_PX,
+    horizontalIntentPx: NAVIGATION_HORIZONTAL_INTENT_PX,
+    parallaxFraction: NAVIGATION_PARALLAX_FRACTION,
+    positionThreshold: NAVIGATION_POSITION_THRESHOLD,
+    releaseSampleRateHz: NAVIGATION_RELEASE_SAMPLE_RATE_HZ,
+    releaseSpring: Object.freeze({
+        damping: NAVIGATION_RELEASE_SPRING_DAMPING,
+        mass: NAVIGATION_RELEASE_SPRING_MASS,
+        stiffness: NAVIGATION_RELEASE_SPRING_STIFFNESS,
+    }),
+    velocityThresholdPxPerSecond: NAVIGATION_VELOCITY_THRESHOLD_PX_PER_SECOND,
+    releaseCompletion: 'first edge arrival',
+    flickVelocityBoost: 1,
+    nativeControllerFlickVelocityBoost: NAVIGATION_EDGE_FLICK_BOOST,
+    initialFlickHistoryThresholdWidthsPerSecond: NAVIGATION_EDGE_FLICK_NORMALIZED_VELOCITY,
+    touchReleaseProjectionSeconds: NAVIGATION_PROJECTION_SECONDS,
+    touchReleaseThresholdPoints: NAVIGATION_PROJECTED_COMPLETION_POINTS,
+    // Native reference values. Interactive input uses the fixed scroll mapping;
+    // applying the tracking spring in JavaScript regresses compositor continuity.
+    trackingResponseSeconds: NAVIGATION_TRACKING_RESPONSE_SECONDS,
+    trackingDampingRatio: NAVIGATION_TRACKING_DAMPING_RATIO,
+});
+export function clampProgress(progress) {
+    return Math.min(1, Math.max(0, progress));
+}
+function cubicCoordinate(amount, firstControl, secondControl) {
+    const inverse = 1 - amount;
+    return (3 * inverse * inverse * amount * firstControl +
+        3 * inverse * amount * amount * secondControl +
+        amount * amount * amount);
+}
+export function sampleNavigationCurve(timeProgress) {
+    const [x1, y1, x2, y2] = NAVIGATION_EASING;
+    const targetX = clampProgress(timeProgress);
+    let lower = 0;
+    let upper = 1;
+    for (let iteration = 0; iteration < 28; iteration += 1) {
+        const candidate = (lower + upper) / 2;
+        const x = cubicCoordinate(candidate, x1, x2);
+        if (x < targetX)
+            lower = candidate;
+        else
+            upper = candidate;
+    }
+    return cubicCoordinate((lower + upper) / 2, y1, y2);
+}
+export function shouldCompleteInteractivePop(progress, velocityPointsPerSecond) {
+    return (progress >= NAVIGATION_POSITION_THRESHOLD ||
+        velocityPointsPerSecond >= NAVIGATION_VELOCITY_THRESHOLD_PX_PER_SECOND);
+}

package/dist/navigation/nativeScrubExperiment.d.ts

@@ -0,0 +1,5 @@
+/** Installed-only architecture experiment. No application navigation is
+ * replaced. The nested vertical surface uses the production ScrollSurface
+ * policy, including scroll-chain containment.
+ */
+export declare function createNativeScrubExperiment(record: (value: unknown) => void): HTMLDivElement;

package/dist/navigation/nativeScrubExperiment.js

@@ -0,0 +1,153 @@
+import { resolveInteractivePopDirectionLock } from './interactivePop.js';
+/** Installed-only architecture experiment. No application navigation is
+ * replaced. The nested vertical surface uses the production ScrollSurface
+ * policy, including scroll-chain containment.
+ */
+export function createNativeScrubExperiment(record) {
+    const root = document.createElement('section');
+    root.hidden = true;
+    root.setAttribute('data-satin-motion-probe', 'true');
+    Object.assign(root.style, {
+        position: 'fixed',
+        top: '180px',
+        left: '60px',
+        width: '280px',
+        background: '#17212e',
+        color: 'white',
+        zIndex: '20000',
+        padding: '8px',
+    });
+    const label = document.createElement('p');
+    label.textContent =
+        'Nested native scrub experiment: drag right across the striped surface. Then try 40° and 50° diagonals. Reports retain native scroll and touch coordinates.';
+    const select = document.createElement('select');
+    for (const value of ['nested-contained', 'nested-chain', 'horizontal-only', 'claim-at-10']) {
+        const option = document.createElement('option');
+        option.value = option.textContent = value;
+        select.append(option);
+    }
+    const x = document.createElement('div'), track = document.createElement('div'), y = document.createElement('div'), content = document.createElement('div');
+    Object.assign(x.style, {
+        position: 'relative',
+        width: '280px',
+        height: '160px',
+        overflowX: 'scroll',
+        overflowY: 'hidden',
+        touchAction: 'pan-y pan-right pinch-zoom',
+        overscrollBehaviorX: 'contain',
+        background: '#345',
+    });
+    Object.assign(track.style, { width: '840px', height: '160px', position: 'relative' });
+    Object.assign(y.style, {
+        position: 'absolute',
+        left: '280px',
+        width: '280px',
+        height: '160px',
+        overflowY: 'auto',
+        overflowX: 'hidden',
+        touchAction: 'pan-y pan-right pinch-zoom',
+        overscrollBehavior: 'contain',
+    });
+    Object.assign(content.style, {
+        width: '280px',
+        height: '600px',
+        background: 'repeating-linear-gradient(0deg,#345 0px,#345 39px,#fff 40px,#345 41px)',
+    });
+    content.textContent = 'Native vertical content';
+    y.setAttribute('data-satin-scroll', 'native-scrub-experiment');
+    const button = document.createElement('button');
+    button.textContent = 'Press target';
+    content.append(button);
+    y.append(content);
+    track.append(y);
+    x.append(track);
+    const dot = document.createElement('div');
+    Object.assign(dot.style, { width: '8px', height: '8px', background: '#ffbd42', marginTop: '4px' });
+    let animation;
+    const reset = () => {
+        y.style.overflow = select.value === 'horizontal-only' ? 'visible' : '';
+        if (select.value !== 'horizontal-only') {
+            y.style.overflowY = 'auto';
+            y.style.overflowX = 'hidden';
+        }
+        content.style.height = select.value === 'horizontal-only' ? '160px' : '600px';
+        y.style.overscrollBehavior = select.value === 'nested-chain' ? 'auto' : 'contain';
+        x.scrollLeft = 280;
+        y.scrollTop = 200;
+        animation?.cancel();
+        const Timeline = window.ScrollTimeline;
+        if (Timeline)
+            animation = dot.animate([{ transform: 'translateX(280px)' }, { transform: 'translateX(-280px)' }], { timeline: new Timeline({ source: x, axis: 'x' }), fill: 'both' });
+    };
+    const events = [];
+    let startX = 0, startY = 0, claimed = false;
+    const sample = (type, touch) => {
+        const dx = touch ? touch.clientX - startX : undefined, dy = touch ? touch.clientY - startY : undefined;
+        events.push({
+            type,
+            at: performance.now(),
+            x: x.scrollLeft,
+            y: y.scrollTop,
+            dx,
+            dy,
+            lock: dx === undefined ? undefined : resolveInteractivePopDirectionLock(dx, dy),
+            claimed,
+        });
+        if (events.length > 600)
+            events.shift();
+    };
+    x.addEventListener('touchstart', event => {
+        events.length = 0;
+        claimed = false;
+        startX = event.touches[0].clientX;
+        startY = event.touches[0].clientY;
+        sample('touchstart', event.touches[0]);
+    }, { passive: true });
+    x.addEventListener('touchmove', event => {
+        const t = event.touches[0];
+        if (select.value === 'claim-at-10' &&
+            resolveInteractivePopDirectionLock(t.clientX - startX, t.clientY - startY) ===
+                'claim-horizontal')
+            claimed = true;
+        if (claimed && event.cancelable)
+            event.preventDefault();
+        sample('touchmove', t);
+    }, { passive: false });
+    for (const type of ['touchend', 'touchcancel'])
+        x.addEventListener(type, event => {
+            sample(type, event.changedTouches[0]);
+            setTimeout(() => {
+                record({
+                    kind: 'nested-native-scrub',
+                    mode: select.value,
+                    timeline: Boolean(animation),
+                    events: [...events],
+                });
+                reset();
+            }, 700);
+        }, { passive: true });
+    for (const type of ['pointercancel', 'pointerup', 'click'])
+        button.addEventListener(type, () => sample(type));
+    x.addEventListener('scroll', () => sample('scroll-x'), { passive: true });
+    y.addEventListener('scroll', () => sample('scroll-y'), { passive: true });
+    select.onchange = reset;
+    const resetButton = document.createElement('button');
+    resetButton.textContent = 'Reset native scrub';
+    resetButton.onclick = reset;
+    root.append(label, select, resetButton, x, dot);
+    const close = document.createElement('button');
+    close.textContent = 'Close native scrub';
+    close.onclick = () => {
+        root.hidden = true;
+    };
+    root.append(close);
+    const launcher = document.createElement('button');
+    launcher.textContent = 'Open nested scrub experiment';
+    launcher.onclick = () => {
+        root.hidden = false;
+        reset();
+    };
+    const controls = document.createElement('div');
+    controls.append(launcher, root);
+    return controls;
+}

package/dist/navigation/nativeScrubSource.d.ts

@@ -0,0 +1,15 @@
+/** A retired source clamps its offset while its native deceleration is stopped. */
+export declare const NATIVE_SCRUB_RETIRED_ATTRIBUTE = "data-satin-scrub-retired";
+/** One display frame at 60 Hz: a re-arm is committed with the next update. */
+export declare const NATIVE_SCRUB_REARM_COMMIT_MS = 17;
+/** Retires the shared source and schedules its re-arm. Returns the retirement
+ * token; only that retirement may be re-armed with it. */
+export declare function retireNativeScrubSource(source: HTMLElement, origin: number): number;
+/** Re-arms the source if `retirement` (or, when omitted, any retirement) is
+ * still current and its native reset has committed. A superseded retirement
+ * never re-arms a newer one. */
+export declare function rearmNativeScrubSource(source: HTMLElement, retirement?: number): boolean;
+/** A new eligible contact returns offset ownership before its native pan starts. Re-arming alone does not. */
+export declare function releaseNativeScrubClamp(source: HTMLElement): void;
+/** Whether a contact that touched down at `time` can be scrolling `source`. */
+export declare function nativeScrubSourceLiveAt(source: HTMLElement | null | undefined, time: number): boolean;

package/dist/navigation/nativeScrubSource.js

@@ -0,0 +1,88 @@
+// The private horizontal scroller that carries an installed back swipe: retiring it after a
+// release and re-arming it for the next contact.
+import { recordMotionPreparation } from '../motionProbe.js';
+/** A retired source clamps its offset while its native deceleration is stopped. */
+export const NATIVE_SCRUB_RETIRED_ATTRIBUTE = 'data-satin-scrub-retired';
+const nativeScrubSources = new WeakMap();
+let nativeScrubRetirements = 0;
+/** One display frame at 60 Hz: a re-arm is committed with the next update. */
+export const NATIVE_SCRUB_REARM_COMMIT_MS = 17;
+/** Retires the shared source and schedules its re-arm. Returns the retirement
+ * token; only that retirement may be re-armed with it. */
+export function retireNativeScrubSource(source, origin) {
+    const state = nativeScrubSources.get(source);
+    if (state)
+        source.removeEventListener?.('scroll', state.clamp);
+    const retiredWidth = source.clientWidth;
+    const clamp = () => {
+        const target = retiredWidth > 0 && source.clientWidth > 0
+            ? (origin / retiredWidth) * source.clientWidth
+            : origin;
+        if (source.scrollLeft !== target)
+            source.scrollLeft = target;
+    };
+    const next = {
+        frame: 0,
+        rearmedAt: state?.rearmedAt ?? -Infinity,
+        retirement: ++nativeScrubRetirements,
+        clamp,
+        clampActive: true,
+        overflowX: state?.frame ? state.overflowX : source.style.overflowX,
+    };
+    if (state?.frame && typeof window !== 'undefined')
+        window.cancelAnimationFrame(state.frame);
+    nativeScrubSources.set(source, next);
+    source.setAttribute?.(NATIVE_SCRUB_RETIRED_ATTRIBUTE, 'true');
+    source.addEventListener?.('scroll', clamp, { passive: true });
+    // Recentre immediately for painted stability. This alone does not end UIKit deceleration.
+    source.scrollLeft = origin;
+    if (typeof window !== 'undefined') {
+        next.frame = window.requestAnimationFrame(() => {
+            // Run after lift, when UIKit has begun decelerating. Keep overflow disabled
+            // through a rendering update so the native scrolling tree drops momentum.
+            // Restore the same source: replacing it would lose active touch ownership.
+            source.style.overflowX = 'hidden';
+            void source.offsetWidth;
+            next.frame = window.requestAnimationFrame(() => {
+                next.frame = 0;
+                source.style.overflowX = next.overflowX;
+                rearmNativeScrubSource(source, next.retirement);
+            });
+        });
+    }
+    return next.retirement;
+}
+/** Re-arms the source if `retirement` (or, when omitted, any retirement) is
+ * still current and its native reset has committed. A superseded retirement
+ * never re-arms a newer one. */
+export function rearmNativeScrubSource(source, retirement) {
+    const state = nativeScrubSources.get(source);
+    if (!state?.retirement || (retirement !== undefined && retirement !== state.retirement))
+        return false;
+    // An endpoint release may complete before the native reset commits. Completion
+    // must not cancel that reset and leave the next content tap stopping momentum.
+    if (state.frame)
+        return false;
+    state.retirement = 0;
+    // Re-arm contact eligibility, but keep offset ownership until another native scrub starts.
+    // Momentum can arrive after the re-arm frame; letting it move this sticky ancestor shifts content.
+    state.rearmedAt = performance.now();
+    source.removeAttribute?.(NATIVE_SCRUB_RETIRED_ATTRIBUTE);
+    recordMotionPreparation(() => ({ kind: 'navigation-source-rearmed', at: state.rearmedAt }));
+    return true;
+}
+/** A new eligible contact returns offset ownership before its native pan starts. Re-arming alone does not. */
+export function releaseNativeScrubClamp(source) {
+    const state = nativeScrubSources.get(source);
+    if (!state?.clampActive)
+        return;
+    source.removeEventListener?.('scroll', state.clamp);
+    state.clampActive = false;
+}
+/** Whether a contact that touched down at `time` can be scrolling `source`. */
+export function nativeScrubSourceLiveAt(source, time) {
+    if (!source || source.getAttribute?.(NATIVE_SCRUB_RETIRED_ATTRIBUTE))
+        return false;
+    const state = nativeScrubSources.get(source);
+    return !state || (!state.retirement && time >= state.rearmedAt + NATIVE_SCRUB_REARM_COMMIT_MS);
+}

package/dist/navigation/navigationChromeModel.d.ts

@@ -0,0 +1,8 @@
+import type { AnyScreenDefinition, NavigationBarDefinition, TitleDisplayMode, ScreenEntry } from './types.js';
+export declare function resolveNavigationTitle(navigation: NavigationBarDefinition<any> | undefined, params: unknown): string | undefined;
+export declare function backButtonVisible(definition: AnyScreenDefinition | undefined, entryIndex: number): boolean;
+export declare function backTargetIndex(entries: readonly ScreenEntry[]): number;
+/** An empty title reserves no large-title row. Bar demand is resolved separately. */
+export declare function resolveNavigationDisplay(title: string | undefined, display: TitleDisplayMode | undefined, compact?: boolean): TitleDisplayMode;
+/** Native iOS 27 omits an untitled root bar unless controls need its row. */
+export declare function resolveNavigationVisibility(title: string | undefined, visibility: 'automatic' | 'visible' | 'hidden' | undefined, display: TitleDisplayMode | undefined, hasToolbar?: boolean, hasBackButton?: boolean): "hidden" | "visible";

package/dist/navigation/navigationChromeModel.js

@@ -0,0 +1,30 @@
+export function resolveNavigationTitle(navigation, params) {
+    if (!navigation)
+        return undefined;
+    return typeof navigation.title === 'function' ? navigation.title(params) : navigation.title;
+}
+export function backButtonVisible(definition, entryIndex) {
+    return (entryIndex > 0 &&
+        definition?.navigation !== undefined &&
+        definition.navigation.backButton !== 'hidden');
+}
+export function backTargetIndex(entries) {
+    const firstExiting = entries.findIndex(entry => entry.transition.phase === 'exiting');
+    return (firstExiting === -1 ? entries.length - 1 : firstExiting) - 1;
+}
+/** An empty title reserves no large-title row. Bar demand is resolved separately. */
+export function resolveNavigationDisplay(title, display, compact = false) {
+    if (display === 'none')
+        return 'none';
+    if (!title || (compact && display === 'large'))
+        return 'inline';
+    return display ?? 'inline';
+}
+/** Native iOS 27 omits an untitled root bar unless controls need its row. */
+export function resolveNavigationVisibility(title, visibility, display, hasToolbar = false, hasBackButton = false) {
+    if (visibility && visibility !== 'automatic')
+        return visibility;
+    return (display !== 'none' && Boolean(title)) || hasToolbar || hasBackButton
+        ? 'visible'
+        : 'hidden';
+}

package/dist/navigation/navigationContext.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from 'react';
+import type { ScreenRegistry } from './registry.js';
+import type { NavigatorActions, NavigatorStore, RegistryScreenEntry } from './store.js';
+import type { NavigatorState, ScreenLifecycle, ScreenLifecycleCallbacks } from './types.js';
+import { type ScrollSurfaceRegistry } from '../scroll/registry.js';
+type ScreenContextValue = Readonly<{
+    key: string;
+    lifecycle: ScreenLifecycle;
+    params: unknown;
+    scrollRegistry: ScrollSurfaceRegistry;
+}>;
+export declare const NavigationPaneContext: Context<"detail" | "sidebar" | "stack">;
+export declare const NavigatorContext: Context<NavigatorStore | undefined>;
+export declare const ScreenContext: Context<ScreenContextValue | undefined>;
+export declare const SystemScrollRegistryContext: Context<ScrollSurfaceRegistry | undefined>;
+export declare function useNavigator<Registry extends ScreenRegistry = ScreenRegistry>(): NavigatorActions<Registry>;
+export declare function useNavigatorState<Registry extends ScreenRegistry = ScreenRegistry>(): NavigatorState<RegistryScreenEntry<Registry>>;
+export declare function useParams<Params = unknown>(): Params;
+export declare function useScreenScrollRegistry(): ScrollSurfaceRegistry;
+/** `onAppear` and `onDisappear`: callbacks for a retained navigation entry's visible lifecycle. */
+export declare function useScreenLifecycle(callbacks?: ScreenLifecycleCallbacks): ScreenLifecycle;
+export {};

package/dist/navigation/navigationContext.js

@@ -0,0 +1,65 @@
+import { createContext, useContext, useEffect, useRef, useSyncExternalStore } from 'react';
+import { createScrollSurfaceRegistry } from '../scroll/registry.js';
+export const NavigationPaneContext = createContext('stack');
+const EMPTY_LIFECYCLE_CALLBACKS = Object.freeze({});
+export const NavigatorContext = createContext(undefined);
+export const ScreenContext = createContext(undefined);
+// Framework-owned system presentations can scroll without joining an app screen's
+// registry or its restoration snapshot. Bare app content owns a local registry.
+export const SystemScrollRegistryContext = createContext(undefined);
+export function useNavigator() {
+    const navigator = useContext(NavigatorContext);
+    if (!navigator) {
+        throw new Error('useNavigator must be called inside NavigatorHost.');
+    }
+    return navigator;
+}
+export function useNavigatorState() {
+    const navigator = useContext(NavigatorContext);
+    if (!navigator) {
+        throw new Error('useNavigatorState must be called inside NavigatorHost.');
+    }
+    return useSyncExternalStore(navigator.subscribe, navigator.getState, navigator.getState);
+}
+export function useParams() {
+    const screen = useContext(ScreenContext);
+    if (!screen) {
+        throw new Error('useParams must be called inside a NavigatorHost screen.');
+    }
+    return screen.params;
+}
+export function useScreenScrollRegistry() {
+    const systemRegistry = useContext(SystemScrollRegistryContext);
+    const screen = useContext(ScreenContext);
+    const standalone = useRef(null);
+    if (systemRegistry)
+        return systemRegistry;
+    if (screen)
+        return screen.scrollRegistry;
+    // Onboarding and bare presentation content own their scroll state for this mount.
+    // They never join a navigation entry's restoration snapshot.
+    if (!standalone.current) {
+        standalone.current = createScrollSurfaceRegistry();
+        standalone.current.setUncovered(true);
+    }
+    return standalone.current;
+}
+/** `onAppear` and `onDisappear`: callbacks for a retained navigation entry's visible lifecycle. */
+export function useScreenLifecycle(callbacks = EMPTY_LIFECYCLE_CALLBACKS) {
+    const screen = useContext(ScreenContext);
+    if (!screen) {
+        throw new Error('useScreenLifecycle must be called inside a NavigatorHost screen.');
+    }
+    const callbacksRef = useRef(callbacks);
+    const isAppeared = !screen.lifecycle.isCovered;
+    useEffect(() => {
+        callbacksRef.current = callbacks;
+    }, [callbacks]);
+    useEffect(() => {
+        if (!isAppeared)
+            return;
+        callbacksRef.current.appear?.();
+        return () => callbacksRef.current.disappear?.();
+    }, [isAppeared]);
+    return screen.lifecycle;
+}

package/dist/navigation/navigationEdge.d.ts

@@ -0,0 +1,4 @@
+/** Observe the material belonging to one page, independent of stack coverage.
+ * `statusEdgeOnly`: the page has no bar row of its own (a hidden bar, or a root under floating
+ * iPad tabs), so the edge effect covers only the status bar. */
+export declare function observeNavigationEdge(edge: HTMLElement, scroller: HTMLElement | null, statusEdgeOnly: boolean): () => void;

package/dist/navigation/navigationEdge.js

@@ -0,0 +1,101 @@
+import { observeNativeScroll } from '../scroll/nativeScroll.js';
+import { firstContentTop, pinnedSectionHeader, scrollEdgeStrength, searchHeaderEdge, } from './scrollEdge.js';
+/** Observe the material belonging to one page, independent of stack coverage.
+ * `statusEdgeOnly`: the page has no bar row of its own (a hidden bar, or a root under floating
+ * iPad tabs), so the edge effect covers only the status bar. */
+export function observeNavigationEdge(edge, scroller, statusEdgeOnly) {
+    // Content drawn up against the status band (a hidden bar, or a primary that ignores the top
+    // safe area) has no top content inset, and native's edge effect then covers only the status
+    // bar, never the bar row (iOS 27 native reference hero-toolbar at offsets 0/150/600). The band already
+    // covers that strip here, so the edge material stays off and the band keeps its short seam
+    // fade at rest and while scrolled (styles.css).
+    const ignoresTop = ['top', 'all'].includes(scroller?.dataset.satinIgnoresSafeArea ?? '');
+    const underEdge = Boolean(scroller) && (ignoresTop || statusEdgeOnly);
+    let edgeHidden = scroller?.dataset.satinScrollEdgeHidden === 'true';
+    const applySeam = () => edge.parentElement?.toggleAttribute('data-satin-edge-seam', underEdge && !edgeHidden);
+    applySeam();
+    let applied = -1;
+    let pinnedHeader;
+    let pinnedReach = -1;
+    let searchMarker;
+    let searchStart = -1;
+    const releaseSearch = () => {
+        searchMarker?.removeAttribute('data-satin-search-edge-covered');
+        searchMarker = undefined;
+        searchStart = -1;
+        edge.removeAttribute('data-satin-scroll-edge-search');
+        edge.style.removeProperty('--satin-scroll-edge-search-start');
+    };
+    const releasePinnedHeader = () => {
+        pinnedHeader?.removeAttribute('data-satin-section-header-pinned');
+        pinnedHeader = undefined;
+    };
+    const update = (snapshot) => {
+        const rect = (element) => snapshot?.rect(element) ?? element.getBoundingClientRect();
+        const live = Boolean(scroller) && !edgeHidden && !underEdge;
+        const search = live && scroller ? searchHeaderEdge(scroller, snapshot?.top, rect) : undefined;
+        if (searchMarker !== search?.marker) {
+            releaseSearch();
+            searchMarker = search?.marker;
+            searchMarker?.setAttribute('data-satin-search-edge-covered', '');
+        }
+        if (search && edge.parentElement) {
+            const start = search.top - rect(edge.parentElement).top;
+            if (start !== searchStart) {
+                searchStart = start;
+                edge.style.setProperty('--satin-scroll-edge-search-start', `${start}px`);
+                edge.setAttribute('data-satin-scroll-edge-search', '');
+            }
+        }
+        // A hidden pane has no edge geometry to update.
+        if (edge.getClientRects().length === 0)
+            return;
+        // A pinned plain-list header carries the edge material through itself (styles.css).
+        const pinned = live && scroller ? pinnedSectionHeader(scroller, rect) : undefined;
+        if (pinned?.header !== pinnedHeader) {
+            releasePinnedHeader();
+            pinnedHeader = pinned?.header;
+            pinnedHeader?.setAttribute('data-satin-section-header-pinned', 'true');
+            pinnedReach = -1;
+        }
+        if (pinned && pinned.reach !== pinnedReach) {
+            pinnedReach = pinned.reach;
+            pinned.header.style.setProperty('--satin-pinned-header-reach', `${pinned.reach}px`);
+        }
+        const strength = !live || !scroller || pinned
+            ? 0
+            : (search?.strength ??
+                scrollEdgeStrength(rect(edge).bottom, firstContentTop(scroller, snapshot?.top, rect)));
+        if (strength === applied)
+            return;
+        applied = strength;
+        edge.style.opacity = strength > 0 && strength < 1 ? String(strength) : '';
+        edge.setAttribute('data-satin-scroll-edge-visible', strength > 0 ? 'true' : 'false');
+    };
+    update();
+    if (!scroller)
+        return releasePinnedHeader;
+    const releaseScroll = observeNativeScroll(scroller, update);
+    // Policy changes are rare; keep their reads and seam writes off the scroll path.
+    const policy = new MutationObserver(() => {
+        const hidden = scroller.dataset.satinScrollEdgeHidden === 'true';
+        edgeHidden = hidden;
+        applySeam();
+        update();
+    });
+    policy.observe(scroller, {
+        attributes: true,
+        attributeFilter: ['data-satin-scroll-edge-hidden', 'data-satin-search-presented'],
+    });
+    const resize = new ResizeObserver(() => update());
+    resize.observe(scroller);
+    if (scroller.firstElementChild)
+        resize.observe(scroller.firstElementChild);
+    return () => {
+        releaseScroll();
+        resize.disconnect();
+        policy.disconnect();
+        releasePinnedHeader();
+        releaseSearch();
+    };
+}

package/dist/navigation/pointerPop.d.ts

@@ -0,0 +1,32 @@
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react';
+import type { AxisLayoutClass } from '../layout/layoutClass.js';
+import { type InteractivePopGesture } from './interactivePop.js';
+import { type EarlyTouchArbitration, type InteractivePopDiagnostic, type InteractiveTransitionController, type NavigatorHostGeometry, type ScrubDiagnosticState } from './interactivePopTypes.js';
+import type { ScreenRegistry } from './registry.js';
+import type { InteractiveScrubFrameLoop } from './scrubFrameLoop.js';
+import { type NavigatorStore } from './store.js';
+/** What the navigator host's pointer handlers read; recreated with the host on every render. */
+export type PointerPopContext = {
+    navigator: NavigatorStore<ScreenRegistry>;
+    tabActive: boolean;
+    nativeNavigation: boolean;
+    split: boolean;
+    horizontal: AxisLayoutClass;
+    appliedHorizontal: AxisLayoutClass;
+    onInteractivePopDiagnostic: ((diagnostic: InteractivePopDiagnostic) => void) | undefined;
+    startScrubFrameLoop: (controller: InteractiveTransitionController, diagnosticState: ScrubDiagnosticState) => InteractiveScrubFrameLoop;
+    hostGeometryRef: RefObject<NavigatorHostGeometry | undefined>;
+    earlyTouchArbitrationRef: RefObject<EarlyTouchArbitration | undefined>;
+    scrubFrameLoopRef: RefObject<InteractiveScrubFrameLoop | undefined>;
+    scrubDiagnosticStateRef: RefObject<ScrubDiagnosticState | undefined>;
+    gestureRef: RefObject<InteractivePopGesture | undefined>;
+    interactiveControllerRef: RefObject<InteractiveTransitionController | undefined>;
+};
+/** The host's pointer handlers for the back gesture. */
+export declare function createPointerPopHandlers(context: PointerPopContext): {
+    onLostPointerCapture: (event: ReactPointerEvent<HTMLDivElement>) => void;
+    onPointerCancel: (event: ReactPointerEvent<HTMLDivElement>) => void;
+    onPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void;
+    onPointerMove: (event: ReactPointerEvent<HTMLDivElement>) => void;
+    onPointerUp: (event: ReactPointerEvent<HTMLDivElement>) => void;
+};