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

package/dist/safe-area/useSafeAreaMetrics.d.ts

@@ -0,0 +1,83 @@
+/** Insets in CSS pixels, by physical edge. */
+export type EdgeInsets = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** The full safe-area and viewport geometry Satin works from, including the diagnostic
+ * coordinate spaces installed-app fixtures compare. Apps want only `insets`. */
+export type SafeAreaMetrics = {
+    /** Insets to apply inside WebKit's layout viewport. */
+    insets: EdgeInsets;
+    /** Comparison insets in physicalCoordinateSpace; never use these as layout padding. */
+    physicalCoordinateSpace: 'calibrated-screen' | 'layout-viewport';
+    physicalInsets: EdgeInsets;
+    /** Stable pre-focus layout during keyboard avoidance; visualViewport stays observed. */
+    layoutViewport: {
+        width: number;
+        height: number;
+    };
+    visualViewport: {
+        width: number;
+        height: number;
+        offsetTop: number;
+        offsetLeft: number;
+        scale: number;
+    };
+    screen: {
+        width: number;
+        height: number;
+    };
+    safeFrame: {
+        width: number;
+        height: number;
+    };
+    physicalSafeFrame: {
+        width: number;
+        height: number;
+    };
+    coordinateSpacesReconcile: boolean;
+    standalone: boolean;
+};
+export declare function readSafeAreaMetrics(): SafeAreaMetrics;
+export declare function edgeInsetsEqual(left: EdgeInsets, right: EdgeInsets): boolean;
+export declare function safeAreaMetricsEqual(left: SafeAreaMetrics, right: SafeAreaMetrics): boolean;
+/** Refresh once at an interaction boundary, before an inactive reader opens. */
+export declare function refreshSafeAreaMetrics(): void;
+/** Internal selector store: one sensor sample, stable snapshots for unchanged selections. */
+export declare function useSafeAreaSelector<Selection>(select: (metrics: SafeAreaMetrics) => Selection, equal?: (left: Selection, right: Selection) => boolean, enabled?: boolean): Selection;
+/** Layout chrome does not change when the keyboard occludes the visual viewport. */
+export declare function useSafeAreaLayoutMetrics(): SafeAreaMetrics;
+/** Full diagnostic geometry, including visual viewport changes. */
+export declare function useSafeAreaMetrics(): SafeAreaMetrics;
+/** Internal presentation readers suspend observation while absent. */
+export declare function useObservedSafeAreaMetrics(enabled: boolean): SafeAreaMetrics;
+/** Screen dimensions alone cannot locate a floating window. Reconstruct only
+ * recorded full-screen coordinate pairs. Otherwise comparison is explicitly
+ * viewport-local, with no claim to know the OS-owned window decoration.
+ * Rotated screen dimensions are matched geometrically, never via orientation.
+ */
+export declare function reconcileWindowGeometry(insets: EdgeInsets, layout: {
+    width: number;
+    height: number;
+}, screen: {
+    width: number;
+    height: number;
+}, standalone: boolean): {
+    physicalCoordinateSpace: "calibrated-screen" | "layout-viewport";
+    physicalInsets: {
+        right: number;
+        bottom: number;
+        left: number;
+        top: number;
+    };
+    safeFrame: {
+        width: number;
+        height: number;
+    };
+    physicalSafeFrame: {
+        width: number;
+        height: number;
+    };
+};

package/dist/safe-area/useSafeAreaMetrics.js

@@ -0,0 +1,367 @@
+import { readDeviceIdiom } from '../layout/deviceIdiom.js';
+import { readKeyboardLayoutHeight } from '../keyboard/adapter.js';
+import { useCallback, useLayoutEffect, useRef, useSyncExternalStore } from 'react';
+// Native Foundation 00, iOS 27.0, plus the recorded fitted standalone viewports.
+// These pairs qualify physical-coordinate comparison, not inset restoration.
+const CALIBRATED_PHONE_WINDOWS = [
+    { screenWidth: 402, screenHeight: 874, width: 402, height: 812 },
+    { screenWidth: 440, screenHeight: 956, width: 440, height: 894 },
+];
+let sensor;
+let sensorOwners = 0;
+function createSensor() {
+    const element = document.createElement('div');
+    element.dataset.satinSafeAreaSensor = 'true';
+    element.setAttribute('aria-hidden', 'true');
+    element.style.cssText = [
+        'position:fixed',
+        'inset:0',
+        'visibility:hidden',
+        'pointer-events:none',
+        'padding-top:env(safe-area-inset-top, 0px)',
+        'padding-right:env(safe-area-inset-right, 0px)',
+        'padding-bottom:env(safe-area-inset-bottom, 0px)',
+        'padding-left:env(safe-area-inset-left, 0px)',
+    ].join(';');
+    // Diagnostic viewport rulers, read by the installed geometry fixture.
+    for (const unit of ['lvh', 'dvh', 'svh']) {
+        const ruler = document.createElement('div');
+        ruler.dataset.satinViewportRuler = unit;
+        ruler.style.cssText = `position:absolute;left:0;top:0;width:1px;height:100${unit};pointer-events:none`;
+        element.append(ruler);
+    }
+    document.body.append(element);
+    return element;
+}
+function acquireSensor() {
+    sensorOwners += 1;
+    if (!sensor?.isConnected)
+        sensor = createSensor();
+    return sensor;
+}
+function releaseSensor() {
+    sensorOwners = Math.max(0, sensorOwners - 1);
+    if (sensorOwners !== 0)
+        return;
+    sensor?.remove();
+    sensor = undefined;
+}
+function pixels(value) {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function readInsets(element) {
+    const computed = getComputedStyle(element);
+    return {
+        top: pixels(computed.paddingTop),
+        right: pixels(computed.paddingRight),
+        bottom: pixels(computed.paddingBottom),
+        left: pixels(computed.paddingLeft),
+    };
+}
+// Native home-indicator boundaries, in points. Phone: Foundation 00, iPhone 17 Pro Max,
+// iOS 27 portrait. Pad: a SwiftUI .safeAreaInset(edge: .bottom) composer on iPad Pro
+// 12.9-inch, iPadOS 27, which keeps 25 pt in portrait and in landscape.
+const PHONE_HOME_INDICATOR_INSET = 34;
+const PAD_HOME_INDICATOR_INSET = 25;
+// iPadOS 27 places this status band outside a fitted standalone viewport (both installed iPads).
+const PAD_FITTED_STATUS_BAND = 32;
+/**
+ * The home-indicator boundary a fitted standalone viewport leaves out of env(bottom).
+ *
+ * With viewport-fit auto/contain, the system takes the status band outside the viewport,
+ * but content still reaches the screen bottom and every env() inset reads zero. Without
+ * this boundary, bottom bars and composers sit in the home-indicator band: on iPad a
+ * composer sat 25 pt lower than the same SwiftUI layout, its trailing edge in the corner
+ * that carries the window-resize grabber. Device identity comes from the shared
+ * resolver, never from screen dimensions.
+ */
+function fittedHomeIndicatorInset(insets, layoutViewport, screen, standalone) {
+    const fit = document.documentElement.dataset.satinViewportFit;
+    const fitted = fit === 'auto' || fit === 'contain';
+    const reportsNoInsets = insets.top === 0 && insets.right === 0 && insets.bottom === 0 && insets.left === 0;
+    if (!standalone || !fitted || !reportsNoInsets)
+        return undefined;
+    const idiom = readDeviceIdiom();
+    if (idiom === 'phone')
+        return fittedPhoneHomeIndicator(layoutViewport, screen);
+    if (idiom === 'pad')
+        return fittedPadHomeIndicator(layoutViewport, screen);
+    return undefined;
+}
+// A missing 44..62 pt portrait band identifies the measured Face ID status region; a
+// home-button phone takes 20 pt, and a viewport excluding bottom 34 takes at least 78 pt.
+// Landscape remains observed-only: no installed landscape geometry qualifies restoration
+// of its native 21 pt boundary.
+function fittedPhoneHomeIndicator(layoutViewport, screen) {
+    const excludedStatusBand = screen.height - layoutViewport.height;
+    const restores = screen.height > screen.width &&
+        layoutViewport.width === screen.width &&
+        excludedStatusBand >= 44 &&
+        excludedStatusBand <= 62;
+    return restores ? PHONE_HOME_INDICATOR_INSET : undefined;
+}
+// The pad boundary is the same in both orientations. WebKit may keep reporting the
+// portrait screen size in landscape, so the window is compared with the screen side
+// that matches its own orientation. Split View, Slide Over and Stage Manager windows are
+// narrower than the screen and stay observed-only, as does any other status band.
+function fittedPadHomeIndicator(layoutViewport, screen) {
+    const longSide = Math.max(screen.width, screen.height);
+    const shortSide = Math.min(screen.width, screen.height);
+    const landscape = layoutViewport.width > layoutViewport.height;
+    const screenWidth = landscape ? longSide : shortSide;
+    const screenHeight = landscape ? shortSide : longSide;
+    const fullScreenWindow = layoutViewport.width === screenWidth;
+    const excludedStatusBand = screenHeight - layoutViewport.height;
+    const restores = fullScreenWindow && excludedStatusBand === PAD_FITTED_STATUS_BAND;
+    return restores ? PAD_HOME_INDICATOR_INSET : undefined;
+}
+function calculateSafeAreaMetrics(insets) {
+    const viewport = window.visualViewport;
+    const layoutViewport = {
+        width: window.innerWidth,
+        height: readKeyboardLayoutHeight(window.innerWidth, window.innerHeight),
+    };
+    const screen = {
+        width: window.screen.width,
+        height: window.screen.height,
+    };
+    const standalone = window.matchMedia('(display-mode: standalone)').matches ||
+        Boolean(window.navigator.standalone);
+    const homeIndicator = fittedHomeIndicatorInset(insets, layoutViewport, screen, standalone);
+    if (homeIndicator !== undefined)
+        insets = { ...insets, bottom: homeIndicator };
+    const comparison = reconcileWindowGeometry(insets, layoutViewport, screen, standalone);
+    const { physicalInsets, safeFrame, physicalSafeFrame, physicalCoordinateSpace } = comparison;
+    return {
+        insets,
+        physicalInsets,
+        physicalCoordinateSpace,
+        layoutViewport,
+        visualViewport: {
+            width: viewport?.width ?? window.innerWidth,
+            height: viewport?.height ?? window.innerHeight,
+            offsetTop: viewport?.offsetTop ?? 0,
+            offsetLeft: viewport?.offsetLeft ?? 0,
+            scale: viewport?.scale ?? 1,
+        },
+        screen,
+        safeFrame,
+        physicalSafeFrame,
+        coordinateSpacesReconcile: Math.abs(safeFrame.width - physicalSafeFrame.width) < 1 &&
+            Math.abs(safeFrame.height - physicalSafeFrame.height) < 1,
+        standalone,
+    };
+}
+function readSafeAreaMetricsFromSensor(element) {
+    return calculateSafeAreaMetrics(readInsets(element));
+}
+function readInitialSafeAreaMetrics() {
+    return calculateSafeAreaMetrics({ top: 0, right: 0, bottom: 0, left: 0 });
+}
+export function readSafeAreaMetrics() {
+    if (sensor?.isConnected)
+        return readSafeAreaMetricsFromSensor(sensor);
+    const temporarySensor = createSensor();
+    try {
+        return readSafeAreaMetricsFromSensor(temporarySensor);
+    }
+    finally {
+        temporarySensor.remove();
+    }
+}
+export function edgeInsetsEqual(left, right) {
+    return (left.top === right.top &&
+        left.right === right.right &&
+        left.bottom === right.bottom &&
+        left.left === right.left);
+}
+export function safeAreaMetricsEqual(left, right) {
+    return (edgeInsetsEqual(left.insets, right.insets) &&
+        edgeInsetsEqual(left.physicalInsets, right.physicalInsets) &&
+        left.layoutViewport.width === right.layoutViewport.width &&
+        left.layoutViewport.height === right.layoutViewport.height &&
+        left.visualViewport.width === right.visualViewport.width &&
+        left.visualViewport.height === right.visualViewport.height &&
+        left.visualViewport.offsetTop === right.visualViewport.offsetTop &&
+        left.visualViewport.offsetLeft === right.visualViewport.offsetLeft &&
+        left.visualViewport.scale === right.visualViewport.scale &&
+        left.screen.width === right.screen.width &&
+        left.screen.height === right.screen.height &&
+        left.safeFrame.width === right.safeFrame.width &&
+        left.safeFrame.height === right.safeFrame.height &&
+        left.physicalSafeFrame.width === right.physicalSafeFrame.width &&
+        left.physicalSafeFrame.height === right.physicalSafeFrame.height &&
+        left.coordinateSpacesReconcile === right.coordinateSpacesReconcile &&
+        left.physicalCoordinateSpace === right.physicalCoordinateSpace &&
+        left.standalone === right.standalone);
+}
+// All consumers observe the same ruler. In a long list, menus can mount thousands
+// of readers; they must not each install an observer, schedule a frame and force
+// a style read for the same viewport event.
+const metricsListeners = new Set();
+let observationOwners = 0;
+let sharedMetrics;
+let stopMetricsObservation;
+/** Refresh once at an interaction boundary, before an inactive reader opens. */
+export function refreshSafeAreaMetrics() {
+    const next = readSafeAreaMetrics();
+    if (sharedMetrics && safeAreaMetricsEqual(sharedMetrics, next))
+        return;
+    sharedMetrics = next;
+    for (const listener of metricsListeners)
+        listener();
+}
+function startMetricsObservation() {
+    const activeSensor = acquireSensor();
+    const visualViewport = window.visualViewport;
+    let frame = 0;
+    const commitMetrics = () => {
+        frame = 0;
+        const nextMetrics = readSafeAreaMetricsFromSensor(activeSensor);
+        if (sharedMetrics && safeAreaMetricsEqual(sharedMetrics, nextMetrics))
+            return;
+        sharedMetrics = nextMetrics;
+        for (const listener of metricsListeners)
+            listener();
+    };
+    const update = () => {
+        if (frame)
+            return;
+        frame = requestAnimationFrame(commitMetrics);
+    };
+    const observer = new ResizeObserver(update);
+    observer.observe(activeSensor);
+    for (const ruler of activeSensor.children)
+        observer.observe(ruler);
+    window.addEventListener('pageshow', update);
+    document.addEventListener('visibilitychange', update);
+    window.addEventListener('resize', update, { passive: true });
+    window.addEventListener('orientationchange', update, { passive: true });
+    visualViewport?.addEventListener('resize', update, { passive: true });
+    visualViewport?.addEventListener('scroll', update, { passive: true });
+    commitMetrics();
+    return () => {
+        cancelAnimationFrame(frame);
+        observer.disconnect();
+        window.removeEventListener('pageshow', update);
+        document.removeEventListener('visibilitychange', update);
+        window.removeEventListener('resize', update);
+        window.removeEventListener('orientationchange', update);
+        visualViewport?.removeEventListener('resize', update);
+        visualViewport?.removeEventListener('scroll', update);
+        releaseSensor();
+        sharedMetrics = undefined;
+    };
+}
+function retainMetricsObservation() {
+    observationOwners += 1;
+    if (!stopMetricsObservation)
+        stopMetricsObservation = startMetricsObservation();
+    return () => {
+        observationOwners -= 1;
+        if (observationOwners !== 0)
+            return;
+        stopMetricsObservation?.();
+        stopMetricsObservation = undefined;
+    };
+}
+function subscribeMetrics(listener) {
+    metricsListeners.add(listener);
+    return () => {
+        metricsListeners.delete(listener);
+    };
+}
+const subscribeWithoutMetrics = () => () => { };
+const identityMetrics = (metrics) => metrics;
+/** Internal selector store: one sensor sample, stable snapshots for unchanged selections. */
+export function useSafeAreaSelector(select, equal = Object.is, enabled = true) {
+    const cache = useRef(undefined);
+    const getSelection = useCallback(() => {
+        const metrics = (sharedMetrics ??= readInitialSafeAreaMetrics());
+        const previous = cache.current;
+        if (previous?.metrics === metrics && previous.select === select)
+            return previous.value;
+        const selected = select(metrics);
+        const value = previous && equal(previous.value, selected) ? previous.value : selected;
+        cache.current = { metrics, select, value };
+        return value;
+    }, [select, equal]);
+    // Start the one observer before layout effects consume geometry. External-store
+    // consistency checks then see the measured snapshot in this same commit.
+    useLayoutEffect(() => (enabled ? retainMetricsObservation() : undefined), [enabled]);
+    return useSyncExternalStore(enabled ? subscribeMetrics : subscribeWithoutMetrics, getSelection, getSelection);
+}
+function layoutMetricsEqual(left, right) {
+    return safeAreaMetricsEqual(left, { ...right, visualViewport: left.visualViewport });
+}
+/** Layout chrome does not change when the keyboard occludes the visual viewport. */
+export function useSafeAreaLayoutMetrics() {
+    return useSafeAreaSelector(identityMetrics, layoutMetricsEqual);
+}
+/** Full diagnostic geometry, including visual viewport changes. */
+export function useSafeAreaMetrics() {
+    return useObservedSafeAreaMetrics(true);
+}
+/** Internal presentation readers suspend observation while absent. */
+export function useObservedSafeAreaMetrics(enabled) {
+    return useSafeAreaSelector(identityMetrics, safeAreaMetricsEqual, enabled);
+}
+/** Screen dimensions alone cannot locate a floating window. Reconstruct only
+ * recorded full-screen coordinate pairs. Otherwise comparison is explicitly
+ * viewport-local, with no claim to know the OS-owned window decoration.
+ * Rotated screen dimensions are matched geometrically, never via orientation.
+ */
+export function reconcileWindowGeometry(insets, layout, screen, standalone) {
+    const calibratedPairs = [
+        ...CALIBRATED_PHONE_WINDOWS.map(window => [
+            window.screenWidth,
+            window.screenHeight,
+            window.width,
+            window.height,
+        ]),
+        [1032, 1376, 1032, 1344], // Phase reference fit full-screen iPad portrait
+        [1032, 1376, 1376, 1000], // Phase reference fit full-screen iPad landscape
+        [744, 1133, 744, 1101], // measured-reference installed iPad mini portrait
+        [744, 1133, 1133, 712], // measured-reference installed iPad mini landscape
+        [834, 1194, 834, 1162], // reference physical iPad fitted full-window portrait
+        [834, 1194, 1194, 802], // reference physical iPad fitted full-window landscape
+        [1024, 1366, 1024, 1334], // reference physical iPad fitted full-window portrait
+        [1024, 1366, 1366, 992], // reference physical iPad fitted full-window landscape
+    ];
+    const fullScreen = standalone &&
+        Math.min(layout.width, layout.height) === Math.min(screen.width, screen.height) &&
+        Math.max(layout.width, layout.height) === Math.max(screen.width, screen.height);
+    const calibrated = fullScreen ||
+        (standalone &&
+            calibratedPairs.some(([sw, sh, w, h]) => Math.min(screen.width, screen.height) === sw &&
+                Math.max(screen.width, screen.height) === sh &&
+                layout.width === w &&
+                layout.height === h));
+    const comparisonFrame = calibrated
+        ? {
+            width: layout.width,
+            height: layout.width === Math.min(screen.width, screen.height)
+                ? Math.max(screen.width, screen.height)
+                : Math.min(screen.width, screen.height),
+        }
+        : layout;
+    const physicalInsets = {
+        ...insets,
+        top: calibrated ? Math.max(insets.top, comparisonFrame.height - layout.height) : insets.top,
+    };
+    return {
+        physicalCoordinateSpace: calibrated
+            ? 'calibrated-screen'
+            : 'layout-viewport',
+        physicalInsets,
+        safeFrame: {
+            width: layout.width - insets.left - insets.right,
+            height: layout.height - insets.top - insets.bottom,
+        },
+        physicalSafeFrame: {
+            width: comparisonFrame.width - physicalInsets.left - physicalInsets.right,
+            height: comparisonFrame.height - physicalInsets.top - physicalInsets.bottom,
+        },
+    };
+}

package/dist/safe-area/windowChrome.d.ts

@@ -0,0 +1,7 @@
+import type { SafeAreaMetrics } from './useSafeAreaMetrics.js';
+/** iOS 27.0 (24A434): native back origin in the measured 375 pt mini and
+ * 473 pt Pro floating windows. See parity/calibrations/ipad-ios27.json.
+ * WebKit reports content insets, but does not reserve horizontal toolbar space
+ * for the OS window controls. Keep this clearance separate from safe-area padding.
+ */
+export declare function windowControlsBackInset(metrics: Pick<SafeAreaMetrics, 'standalone' | 'screen' | 'layoutViewport'>): number;

package/dist/safe-area/windowChrome.js

@@ -0,0 +1,14 @@
+import { readDeviceIdiom } from '../layout/deviceIdiom.js';
+/** iOS 27.0 (24A434): native back origin in the measured 375 pt mini and
+ * 473 pt Pro floating windows. See parity/calibrations/ipad-ios27.json.
+ * WebKit reports content insets, but does not reserve horizontal toolbar space
+ * for the OS window controls. Keep this clearance separate from safe-area padding.
+ */
+export function windowControlsBackInset(metrics) {
+    const shortScreen = Math.min(metrics.screen.width, metrics.screen.height);
+    return metrics.standalone &&
+        readDeviceIdiom() === 'pad' &&
+        metrics.layoutViewport.width < shortScreen
+        ? 78
+        : 0;
+}

package/dist/scroll/RefreshControl.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+import type { TaskAction } from '../tasks/useTask.js';
+/** An additive control inside the existing native WebKit scroll surface. */
+export declare function RefreshControl({ surface, content, action, }: {
+    surface: RefObject<HTMLDivElement | null>;
+    content: RefObject<HTMLDivElement | null>;
+    action: TaskAction;
+}): import("react").JSX.Element;

package/dist/scroll/RefreshControl.js

@@ -0,0 +1,135 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ActivityIndicatorSegments } from '../controls/ActivityIndicatorSegments.js';
+import { useContext, useEffect, useLayoutEffect, useRef } from 'react';
+import { ScreenContext } from '../navigation/navigationContext.js';
+import { TabActivityContext } from '../tabs/context.js';
+import { refreshHeight, refreshRelease, refreshReleaseOffset } from './refreshMotion.js';
+import { useRefreshAction } from './refreshable.js';
+import { animateElement, timelineStart } from '../motion/animate.js';
+// Native iPad sweep: 268 pt did not arm, 276 pt did.
+// Midpoint candidate; exact threshold and iPhone gesture parity remain pending.
+const pullThreshold = 272;
+/** An additive control inside the existing native WebKit scroll surface. */
+export function RefreshControl({ surface, content, action, }) {
+    const screen = useContext(ScreenContext);
+    const tabActive = useContext(TabActivityContext);
+    const active = tabActive && !screen?.lifecycle.isCovered;
+    const { running, run } = useRefreshAction(action, active);
+    const container = useRef(null);
+    const spinner = useRef(null);
+    const wasRunning = useRef(false);
+    const release = useRef(null);
+    useEffect(() => {
+        const element = surface.current;
+        const indicator = spinner.current;
+        if (!element || !indicator || !active || running)
+            return;
+        let touching = false;
+        let eligible = false;
+        let distance = 0;
+        const paint = () => {
+            distance = Math.max(0, -element.scrollTop);
+            indicator.style.opacity = String(Math.min(1, distance / refreshHeight));
+            indicator.style.transform = `scale(${Math.min(1, distance / refreshHeight)})`;
+        };
+        const reset = () => {
+            distance = 0;
+            indicator.style.opacity = '0';
+            indicator.style.transform = 'scale(0)';
+        };
+        const start = (event) => {
+            reset();
+            touching = event.touches.length === 1;
+            eligible = touching && element.scrollTop <= 0;
+        };
+        const scroll = () => {
+            if (touching && eligible)
+                paint();
+        };
+        const end = () => {
+            if (touching && eligible && distance >= pullThreshold)
+                run();
+            else
+                reset();
+            touching = false;
+            eligible = false;
+        };
+        const cancel = () => {
+            reset();
+            touching = false;
+            eligible = false;
+        };
+        element.addEventListener('touchstart', start, { passive: true });
+        element.addEventListener('scroll', scroll, { passive: true });
+        element.addEventListener('touchend', end, { passive: true });
+        element.addEventListener('touchcancel', cancel, { passive: true });
+        return () => {
+            element.removeEventListener('touchstart', start);
+            element.removeEventListener('scroll', scroll);
+            element.removeEventListener('touchend', end);
+            element.removeEventListener('touchcancel', cancel);
+        };
+    }, [surface, active, running, run]);
+    useLayoutEffect(() => {
+        const element = container.current;
+        const indicator = spinner.current;
+        const carrier = content.current;
+        if (!element || !indicator || !carrier)
+            return;
+        release.current?.cancel();
+        release.current = null;
+        if (running) {
+            element.style.height = `${refreshHeight}px`;
+            if (!wasRunning.current && surface.current)
+                surface.current.scrollTop += refreshHeight;
+            indicator.style.opacity = '1';
+            indicator.style.transform = 'scale(1)';
+        }
+        else if (wasRunning.current && active) {
+            // Commit layout once. Native scroll clamping/anchoring may consume some of the
+            // spacer change, so retain the actual visible displacement, not a guessed 60 pt.
+            const before = carrier.getBoundingClientRect().top;
+            element.style.height = '0px';
+            const displacement = before - carrier.getBoundingClientRect().top;
+            indicator.style.top = '15px';
+            const duration = refreshRelease.at(-1).time;
+            const finish = () => {
+                indicator.style.opacity = '0';
+                indicator.style.top = '-45px';
+            };
+            if (matchMedia('(prefers-reduced-motion: reduce)').matches || displacement === 0) {
+                finish();
+            }
+            else {
+                const start = performance.now();
+                const animation = animateElement(carrier, refreshRelease.map(sample => ({
+                    transform: `translateY(${refreshReleaseOffset(sample.height, displacement)}px)`,
+                    offset: sample.time / duration,
+                })), { duration, easing: 'linear', fill: 'both' });
+                animation.startTime = timelineStart(start);
+                release.current = animation;
+                void animation.finished.then(() => {
+                    if (release.current !== animation)
+                        return;
+                    finish();
+                    animation.cancel();
+                    release.current = null;
+                }, () => { });
+            }
+        }
+        else {
+            element.style.height = '0px';
+            indicator.style.opacity = '0';
+        }
+        wasRunning.current = running;
+    }, [running, active, surface, content]);
+    useLayoutEffect(() => () => release.current?.cancel(), []);
+    return (_jsx("div", { ref: container, style: { height: 0, position: 'relative', flexShrink: 0 }, children: _jsx("svg", { ref: spinner, role: running ? 'progressbar' : undefined, "aria-label": running ? 'Refreshing' : undefined, "aria-hidden": !running, width: "30", height: "30", viewBox: "0 0 20 20", style: {
+                position: 'absolute',
+                left: 'calc(50% - 15px)',
+                top: running ? 15 : -45,
+                opacity: 0,
+                color: 'var(--satin-list-secondary)',
+                pointerEvents: 'none',
+            }, children: _jsx(ActivityIndicatorSegments, { running: running }) }) }));
+}