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

package/dist/scroll/ScrollSurface.d.ts

@@ -0,0 +1,62 @@
+import { type ScrollEdgeEffectHidden, type ScrollEdgeEffectStyleSelection } from './edgePolicy.js';
+import type { TaskAction } from '../tasks/useTask.js';
+import { type ScrollAnchor, type ScrollPositionOptions } from './position.js';
+import { type ScrollDismissesKeyboardMode } from '../keyboard/adapter.js';
+import type { Searchable } from '../search/searchable.js';
+import { type HTMLAttributes } from 'react';
+import type { ScrollAxis, ScrollOffset, ScrollToTopOptions } from './types.js';
+/** The navigation title a List supplies for its own primary surface (ListForm.tsx). */
+export declare const ListNavigationContext: import("react").Context<{
+    title?: string;
+    display: 'large' | 'inline';
+    searchable?: Searchable;
+} | undefined>;
+/** Imperative scroll positioning for a named scroll view. */
+export interface ScrollSurfaceHandle {
+    readonly offset: ScrollOffset;
+    scrollTo(id: string, anchor?: ScrollAnchor): boolean;
+    scrollToTop(options?: ScrollToTopOptions): void;
+}
+/** A scroll view's content, scroll binding and keyboard dismissal policy. */
+export type ScrollSurfaceProps = Omit<HTMLAttributes<HTMLDivElement>, 'id'> & ScrollPositionOptions & Readonly<{
+    axis?: ScrollAxis;
+    chain?: boolean;
+    id: string;
+    scrollDismissesKeyboard?: ScrollDismissesKeyboardMode;
+    /** Awaited pull-to-refresh action. Vertical surfaces only. */
+    refreshable?: TaskAction;
+    /**
+     * Whether this is the screen's primary scroll view, which gets the large title, the bar's
+     * content inset and the scroll edge effect. By default the outermost vertical scroll view at the
+     * top of the screen's content is primary, as in SwiftUI.
+     */
+    primary?: boolean;
+    /** SwiftUI `scrollEdgeEffectHidden(_:for: .top)`: no scroll edge effect under the bar. */
+    scrollEdgeEffectHidden?: ScrollEdgeEffectHidden;
+    /** Soft/automatic select the existing top treatment. Hard is explicitly unsupported. */
+    scrollEdgeEffectStyle?: ScrollEdgeEffectStyleSelection;
+}>;
+/** SwiftUI `ScrollView`: a named scroll surface whose position is retained by the framework. */
+export declare const ScrollSurface: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "id"> & Readonly<{
+    defaultScrollAnchor?: 'top' | 'bottom';
+    maintainVisibleContentPosition?: boolean;
+    scrollPosition?: import("./position.js").ScrollPositionBinding;
+    onScrollGeometryChange?: (geometry: import("./position.js").VerticalScrollGeometry) => void;
+}> & Readonly<{
+    axis?: ScrollAxis;
+    chain?: boolean;
+    id: string;
+    scrollDismissesKeyboard?: ScrollDismissesKeyboardMode;
+    /** Awaited pull-to-refresh action. Vertical surfaces only. */
+    refreshable?: TaskAction;
+    /**
+     * Whether this is the screen's primary scroll view, which gets the large title, the bar's
+     * content inset and the scroll edge effect. By default the outermost vertical scroll view at the
+     * top of the screen's content is primary, as in SwiftUI.
+     */
+    primary?: boolean;
+    /** SwiftUI `scrollEdgeEffectHidden(_:for: .top)`: no scroll edge effect under the bar. */
+    scrollEdgeEffectHidden?: ScrollEdgeEffectHidden;
+    /** Soft/automatic select the existing top treatment. Hard is explicitly unsupported. */
+    scrollEdgeEffectStyle?: ScrollEdgeEffectStyleSelection;
+}> & import("react").RefAttributes<ScrollSurfaceHandle>>;

package/dist/scroll/ScrollSurface.js

@@ -0,0 +1,278 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ExpandedNavigationTitle } from '../navigation/NavigationTitleSlots.js';
+import { observeToolbarMinimization } from '../navigation/toolbarMinimization.js';
+import { topScrollEdgePolicy, } from './edgePolicy.js';
+import { RefreshControl } from './RefreshControl.js';
+import { BottomInsetContext } from '../safe-area/SafeAreaInset.js';
+import { ContentMarginsContext, IgnoresSafeAreaContext, NO_LENGTHS, SafeAreaPaddingContext, } from '../safe-area/context.js';
+import { useScreenContentNavigation } from '../public/chrome.js';
+import { observeListLayoutMargins, startsScreenContent } from './screenGeometry.js';
+import { ScrollTargetContext } from './ScrollTarget.js';
+import { createScrollPositionController, } from './position.js';
+import { scrollAfterGlassPrepared } from './scrollJump.js';
+import { installScrollKeyboardDismissal, } from '../keyboard/adapter.js';
+import { TabActivityContext, TabRegistrationContext } from '../tabs/context.js';
+import { SearchDrawer } from '../search/SearchDrawer.js';
+import { ContentAdmission } from '../image/ContentAdmission.js';
+import { SearchToolbarField } from '../search/SearchToolbarField.js';
+import { resolveSearchPlacement } from '../search/searchPlacement.js';
+import { Children, createContext, forwardRef, isValidElement, useCallback, useContext, useImperativeHandle, useLayoutEffect, useRef, useState, useSyncExternalStore, } from 'react';
+import { ScreenContext, SystemScrollRegistryContext, useScreenScrollRegistry, } from '../navigation/navigationContext.js';
+import { readScrollOffset } from './registry.js';
+import { installScrollPressOwnership } from './pressOwnership.js';
+/** Inside another scroll surface: never the screen's primary scroll view. */
+const NestedScrollContext = createContext(false);
+/** The navigation title a List supplies for its own primary surface (ListForm.tsx). */
+export const ListNavigationContext = createContext(undefined);
+/** A scroll view's content is inside its safe area: modifiers above it stop at its frame. */
+const NO_IGNORED = { container: new Set(), keyboard: false };
+const cssLength = (value) => typeof value === 'number' ? `${value}px` : (value ?? '0px');
+/** SwiftUI `ScrollView`: a named scroll surface whose position is retained by the framework. */
+export const ScrollSurface = forwardRef(function ScrollSurface({ axis = 'vertical', chain = false, children, primary, scrollEdgeEffectHidden, scrollEdgeEffectStyle, refreshable, scrollDismissesKeyboard = 'never', id, defaultScrollAnchor, maintainVisibleContentPosition, scrollPosition, onScrollGeometryChange, ...props }, forwardedRef) {
+    const refresh = refreshable;
+    if (axis !== 'vertical' &&
+        (refresh !== undefined ||
+            defaultScrollAnchor !== undefined ||
+            maintainVisibleContentPosition !== undefined ||
+            scrollPosition !== undefined ||
+            onScrollGeometryChange !== undefined))
+        throw new TypeError('Scroll positioning, refreshable and geometry observation require a vertical ScrollView.');
+    const bottom = useContext(BottomInsetContext);
+    const ignored = useContext(IgnoresSafeAreaContext).container;
+    const ignoresSafeArea = ignored.has('top') && ignored.has('bottom')
+        ? true
+        : ignored.has('top')
+            ? 'top'
+            : ignored.has('bottom')
+                ? 'bottom'
+                : undefined;
+    // SafeAreaPadding and ContentMargins above this scroll view (safe-area/modifiers.tsx).
+    const padding = useContext(SafeAreaPaddingContext);
+    const margins = useContext(ContentMarginsContext);
+    const extraBottom = padding.bottom + (margins.bottom ?? 0);
+    const extras = padding.top || padding.leading || padding.trailing || Object.keys(margins).length
+        ? {
+            ['--satin-extra-top']: `${padding.top + (margins.top ?? 0)}px`,
+            ['--satin-extra-leading']: `${padding.leading}px`,
+            ['--satin-extra-trailing']: `${padding.trailing}px`,
+            ...(margins.leading !== undefined && {
+                ['--satin-content-margin-leading']: `${margins.leading}px`,
+            }),
+            ...(margins.trailing !== undefined && {
+                ['--satin-content-margin-trailing']: `${margins.trailing}px`,
+            }),
+        }
+        : undefined;
+    const horizontalPadding = padding.leading + padding.trailing;
+    const tabActive = useContext(TabActivityContext);
+    const elementRef = useRef(null);
+    useLayoutEffect(() => {
+        if (elementRef.current)
+            return bottom.geometry?.attach(elementRef.current);
+    }, [bottom.geometry]);
+    const registry = useScreenScrollRegistry();
+    const screen = useContext(ScreenContext);
+    const systemRegistry = useContext(SystemScrollRegistryContext);
+    const ownsScreen = Boolean(screen || systemRegistry);
+    const nested = useContext(NestedScrollContext);
+    const listNavigation = useContext(ListNavigationContext);
+    const chrome = useScreenContentNavigation();
+    // `undefined` until the surface has measured whether it starts the screen's content.
+    const [candidate, setCandidate] = useState();
+    const preference = ownsScreen
+        ? (primary ?? (axis === 'vertical' && !nested && candidate ? 'automatic' : false))
+        : false;
+    const isPrimary = useSyncExternalStore(registry.subscribe, () => registry.getPrimary()?.id === id, () => ownsScreen && primary === true);
+    const isList = listNavigation !== undefined;
+    const authoredTitle = Children.toArray(children).some(child => isValidElement(child) && child.type === 'h1');
+    const screenTitle = chrome.titleDisplay !== 'none' && !authoredTitle ? chrome.title : undefined;
+    const title = isList ? listNavigation.title : screenTitle;
+    const display = isList
+        ? listNavigation.display
+        : chrome.titleDisplay === 'large'
+            ? 'large'
+            : 'inline';
+    const ignoresTop = ignoresSafeArea === true || ignoresSafeArea === 'top';
+    const ignoresBottom = ignoresSafeArea === true || ignoresSafeArea === 'bottom';
+    const barHidden = chrome.toolbarVisibility === 'hidden';
+    // Primary geometry belongs to the screen, even when title content is authored or absent.
+    const navigation = !isPrimary
+        ? undefined
+        : ignoresTop
+            ? 'ignored'
+            : barHidden
+                ? 'hidden'
+                : display;
+    const edgePolicy = topScrollEdgePolicy(scrollEdgeEffectHidden, scrollEdgeEffectStyle);
+    useLayoutEffect(() => {
+        const scroller = elementRef.current;
+        const behavior = chrome.toolbarMinimizationBehavior;
+        if (!scroller || !isPrimary || barHidden || !behavior || behavior === 'never')
+            return;
+        return observeToolbarMinimization(scroller, behavior, chrome.toolbarMinimizationRestoration, chrome.toolbarMinimizationSafeAreaAdjustment);
+    }, [
+        isPrimary,
+        barHidden,
+        chrome.toolbarMinimizationBehavior,
+        chrome.toolbarMinimizationRestoration,
+        chrome.toolbarMinimizationSafeAreaAdjustment,
+    ]);
+    const contentRef = useRef(null);
+    const targets = useRef(new Map());
+    const controller = useRef(null);
+    const positioning = forwardedRef != null ||
+        defaultScrollAnchor !== undefined ||
+        maintainVisibleContentPosition !== undefined ||
+        scrollPosition !== undefined ||
+        onScrollGeometryChange !== undefined;
+    const positionOptions = useRef({});
+    positionOptions.current = {
+        defaultScrollAnchor,
+        maintainVisibleContentPosition,
+        scrollPosition,
+        onScrollGeometryChange,
+    };
+    const registerTarget = useCallback((targetId, element) => {
+        if (element) {
+            if (targets.current.has(targetId) && targets.current.get(targetId) !== element) {
+                throw new Error(`Duplicate ScrollTarget id "${targetId}" in ScrollView "${id}".`);
+            }
+            targets.current.set(targetId, element);
+        }
+        else
+            targets.current.delete(targetId);
+        controller.current?.targetsChanged();
+    }, [id]);
+    // A titled List keeps its measured list hooks (styles.css); every other state is shared.
+    const listTitled = isList && (navigation === 'large' || navigation === 'inline');
+    const largeTitle = navigation === 'large' && title !== undefined && !authoredTitle ? (_jsx(ExpandedNavigationTitle, { entryKey: screen?.key ?? id, title: title, subtitle: chrome.subtitle, list: isList })) : null;
+    // The navigation bar drawer belongs to the bar's primary scroll view, after its large title.
+    const searchable = navigation === 'large' || navigation === 'inline'
+        ? (listNavigation?.searchable ?? chrome.searchable)
+        : undefined;
+    const tabbed = useContext(TabRegistrationContext) !== null;
+    const searchPlacement = searchable
+        ? resolveSearchPlacement(searchable.placement, {
+            compact: chrome.horizontalSizeClass === 'compact',
+            bottomBarItems: chrome.hasBottomBar === true,
+            searchToolbarItem: chrome.searchToolbarItem !== undefined,
+            scoped: searchable.scopes !== undefined,
+            tabbed,
+        })
+        : undefined;
+    const toolbarSearch = searchPlacement === 'toolbar' || searchPlacement === 'navigationBarToolbar';
+    const bottomSearch = searchPlacement === 'toolbar';
+    const searchHost = bottomSearch
+        ? (chrome.searchToolbarItem ?? chrome.bottomToolbar)
+        : chrome.trailingToolbar;
+    const content = (_jsxs(_Fragment, { children: [largeTitle, searchable && !toolbarSearch && (_jsx(SearchDrawer, { configuration: searchable, scroller: elementRef })), searchable && toolbarSearch && searchHost && (_jsx(SearchToolbarField, { configuration: searchable, scroller: elementRef, host: searchHost, navigation: searchPlacement === 'navigationBarToolbar' })), _jsx(ContentAdmission, { children: children })] }));
+    if (positioning && axis !== 'vertical') {
+        throw new Error('ScrollView positioning currently supports only the vertical axis.');
+    }
+    useLayoutEffect(() => elementRef.current
+        ? installScrollKeyboardDismissal(elementRef.current, scrollDismissesKeyboard)
+        : undefined, [scrollDismissesKeyboard]);
+    useImperativeHandle(forwardedRef, () => ({
+        get offset() {
+            const element = elementRef.current;
+            return element ? readScrollOffset(element) : Object.freeze({ x: 0, y: 0 });
+        },
+        scrollTo(targetId, anchor) {
+            if (axis !== 'vertical')
+                throw new TypeError('ScrollTarget positioning requires a vertical ScrollView.');
+            return controller.current?.scrollTo(targetId, anchor) ?? false;
+        },
+        scrollToTop(options = {}) {
+            const element = elementRef.current;
+            if (!element)
+                return;
+            registry.cancelRestoration(id);
+            const scroll = () => element.scrollTo({
+                behavior: options.animated ? 'smooth' : 'auto',
+                left: axis === 'horizontal' ? 0 : element.scrollLeft,
+                top: axis === 'vertical' ? 0 : element.scrollTop,
+            });
+            // Glass over a long list holds the list's top before the scroll starts (scroll/scrollJump.ts).
+            if (axis === 'vertical')
+                scrollAfterGlassPrepared(element, 0, scroll);
+            else
+                scroll();
+        },
+    }), [axis, id, registry]);
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        return element && tabActive ? installScrollPressOwnership(element, axis) : undefined;
+    }, [axis, tabActive]);
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (element && primary === undefined && axis === 'vertical' && !nested)
+            setCandidate(startsScreenContent(element));
+    }, [axis, nested, primary]);
+    // A List's layout margins follow its own width, as UIKit's do: a frame up to 402 pt wide insets
+    // its inset-grouped cards 16 pt, a wider one 20 pt (iOS 27 native reference, Forms framed 300-440 pt).
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (!element || !isList)
+            return;
+        return observeListLayoutMargins(element, horizontalPadding);
+    }, [isList, horizontalPadding]);
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (!element)
+            return;
+        const parentSurface = element.parentElement?.closest('[data-satin-scroll]');
+        const canChain = Boolean(chain && parentSurface);
+        element.dataset.satinScrollChain = canChain ? 'true' : 'false';
+        if (import.meta.env.DEV && chain && !parentSurface) {
+            console.error(`[Satin fidelity: invalid-scroll-chain] ScrollSurface "${id}" opted into ` +
+                'scroll chaining without a declared parent ScrollSurface. The dead document ' +
+                'can never be a chain target, so containment remains active.', element);
+        }
+        // Initial positioning precedes registration so an existing navigation
+        // snapshot wins. Later restoration explicitly refreshes the reading anchor.
+        if (positionOptions.current.defaultScrollAnchor === 'bottom') {
+            element.scrollTop = Math.max(0, element.scrollHeight - element.clientHeight);
+        }
+        return registry.register({
+            axis,
+            element,
+            id,
+            primary: preference,
+            onRestore: () => controller.current?.adoptRestoredOffset(),
+            initialOffset: () => ({
+                x: 0,
+                y: Math.max(0, element.scrollHeight - element.clientHeight) *
+                    { top: 0, center: 0.5, bottom: 1 }[positionOptions.current.defaultScrollAnchor ?? 'top'],
+            }),
+        });
+    }, [axis, chain, id, preference, registry]);
+    useLayoutEffect(() => {
+        if (axis !== 'vertical' || !positioning || !elementRef.current || !contentRef.current)
+            return;
+        const position = createScrollPositionController(elementRef.current, contentRef.current, targets.current, () => positionOptions.current, () => registry.cancelRestoration(id));
+        controller.current = position;
+        return () => {
+            position.dispose();
+            controller.current = null;
+        };
+    }, [axis, positioning, id, registry]);
+    useLayoutEffect(() => {
+        controller.current?.reconcile();
+    });
+    return (_jsxs("div", { ...props, style: {
+            ...extras,
+            ...(bottom.consumed && axis === 'vertical' && !(isPrimary && ignoresBottom)
+                ? {
+                    ...props.style,
+                    // The enclosing bottom insets' accessories (styles.css), in the same frame.
+                    paddingBottom: `calc(${cssLength(props.style?.paddingBottom)} + var(--satin-scroll-inset-bottom))`,
+                }
+                : props.style),
+        }, "data-satin-safe-area-extra": extras ? 'true' : undefined, ref: elementRef, "data-satin-bounce": "native", "data-satin-primary": isPrimary ? 'true' : 'false', "data-satin-list-navigation": listTitled ? navigation : undefined, "data-satin-scroll-navigation": listTitled ? undefined : navigation, "data-satin-ignores-safe-area": ignoresSafeArea === true ? 'all' : ignoresSafeArea, "data-satin-scroll-edge-hidden": edgePolicy.hidden || undefined, "data-satin-scroll-edge-style": edgePolicy.style, "data-satin-searchable": searchable && !toolbarSearch ? (searchable.scopes ? 'scoped' : 'plain') : undefined, "data-satin-search-placement": bottomSearch ? 'toolbar' : undefined, "data-satin-bottom-bar": isPrimary && !ignoresBottom
+            ? bottomSearch
+                ? 'search'
+                : chrome.hasBottomBar || undefined
+            : undefined, "data-satin-scroll": id, "data-satin-scroll-axis": axis, "data-satin-horizontal-drag": axis === 'horizontal' ? 'both' : undefined, "data-satin-scroll-chain": "false", children: [refresh && _jsx(RefreshControl, { surface: elementRef, content: contentRef, action: refresh }), _jsx(NestedScrollContext, { value: true, children: _jsx(ListNavigationContext, { value: undefined, children: _jsx(SafeAreaPaddingContext, { value: NO_LENGTHS, children: _jsxs(IgnoresSafeAreaContext, { value: NO_IGNORED, children: [positioning || refresh ? (_jsx(ScrollTargetContext.Provider, { value: registerTarget, children: _jsx("div", { ref: contentRef, "data-satin-scroll-content": "", "data-satin-refresh-content": refresh ? 'true' : undefined, "data-satin-scroll-positioned": positioning ? 'true' : undefined, style: !positioning
+                                            ? { display: isList ? 'flow-root' : undefined, minHeight: 0 }
+                                            : undefined, "data-satin-scroll-alignment": defaultScrollAnchor, children: content }) })) : (content), extraBottom > 0 && axis === 'vertical' && (_jsx("div", { "aria-hidden": "true", "data-satin-safe-area-tail": "", style: { height: extraBottom } }))] }) }) }) })] }));
+});

package/dist/scroll/ScrollTarget.d.ts

@@ -0,0 +1,6 @@
+import { type HTMLAttributes } from 'react';
+export declare const ScrollTargetContext: import("react").Context<((id: string, element: HTMLDivElement | null) => void) | null>;
+/** A stable identity in a vertical ScrollView's normal-flow target layout. */
+export declare function ScrollTarget({ id, ...props }: HTMLAttributes<HTMLDivElement> & {
+    id: string;
+}): import("react").JSX.Element;

package/dist/scroll/ScrollTarget.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext } from 'react';
+export const ScrollTargetContext = createContext(null);
+/** A stable identity in a vertical ScrollView's normal-flow target layout. */
+export function ScrollTarget({ id, ...props }) {
+    const register = useContext(ScrollTargetContext);
+    if (!register)
+        throw new Error('ScrollTarget requires a vertical ScrollView with positioning enabled.');
+    const ref = useCallback((element) => register(id, element), [id, register]);
+    return _jsx("div", { ...props, ref: ref, "data-satin-scroll-target": id });
+}

package/dist/scroll/edgePolicy.d.ts

@@ -0,0 +1,21 @@
+/** `Edge`: a logical edge of a scroll view. */
+export type ScrollEdge = 'top' | 'bottom' | 'leading' | 'trailing';
+/** One or more scroll edges, or all edges. */
+export type ScrollEdgeSelection = ScrollEdge | 'all' | readonly ScrollEdge[];
+/** `ScrollEdgeEffectStyle`: the requested edge material treatment. */
+export type ScrollEdgeEffectStyle = 'soft' | 'hard' | 'automatic';
+/** Whether to hide scroll edge material, optionally for specific edges. */
+export type ScrollEdgeEffectHidden = boolean | {
+    hidden: boolean;
+    edges: ScrollEdgeSelection;
+};
+/** The scroll edge treatment and the edges to which it applies. */
+export type ScrollEdgeEffectStyleSelection = ScrollEdgeEffectStyle | {
+    style: ScrollEdgeEffectStyle;
+    edges: ScrollEdgeSelection;
+};
+/** The navigation engine currently renders only the soft top edge. Other edges have no material. */
+export declare function topScrollEdgePolicy(hidden?: ScrollEdgeEffectHidden, selection?: ScrollEdgeEffectStyleSelection): {
+    hidden: boolean;
+    style: "automatic" | "soft";
+};

package/dist/scroll/edgePolicy.js

@@ -0,0 +1,17 @@
+function includesTop(edges) {
+    return edges === 'all' || edges === 'top' || (Array.isArray(edges) && edges.includes('top'));
+}
+/** The navigation engine currently renders only the soft top edge. Other edges have no material. */
+export function topScrollEdgePolicy(hidden = false, selection = 'automatic') {
+    const style = typeof selection === 'string'
+        ? selection
+        : includesTop(selection.edges)
+            ? selection.style
+            : 'automatic';
+    if (style === 'hard')
+        throw new Error('scrollEdgeEffectStyle hard is not supported by the navigation edge renderer.');
+    return {
+        hidden: typeof hidden === 'boolean' ? hidden : hidden.hidden && includesTop(hidden.edges),
+        style,
+    };
+}

package/dist/scroll/insertionMotion.d.ts

@@ -0,0 +1,15 @@
+export declare const SCROLL_INSERTION_MOTION = "satin-scroll-insertion-motion";
+export declare function insertionMotion(surface: HTMLElement): Readonly<{
+    epoch: number;
+    duration: number;
+    end: number;
+    offset: number;
+    stops: readonly (readonly [number, number])[];
+}> | undefined;
+/** Translate the already-anchored layout from its previous presented position. */
+export declare function createInsertionMotion(surface: HTMLElement, content: HTMLElement): {
+    reconcile: (pinned: boolean, hold?: boolean) => void;
+    offset: () => number;
+    cancel: () => void;
+    contentChanged: (records: MutationRecord[]) => void;
+};

package/dist/scroll/insertionMotion.js

@@ -0,0 +1,128 @@
+import { allowsComposerMotion, INSERTION_DURATION_MS, insertionProgress, } from '../motion/composerMotion.js';
+export const SCROLL_INSERTION_MOTION = 'satin-scroll-insertion-motion';
+const motions = new WeakMap();
+export function insertionMotion(surface) {
+    return motions.get(surface);
+}
+/** Translate the already-anchored layout from its previous presented position. */
+export function createInsertionMotion(surface, content) {
+    let animation;
+    let first = null;
+    let last = null;
+    let firstTop = 0;
+    let initialized = false;
+    let bottomInset = 0;
+    let restoreClip;
+    let holding = false;
+    let replacedContent = false;
+    const now = () => performance.timeOrigin + performance.now();
+    // DOM rects and their normalization must use the same presented frame. A later
+    // wall-clock sample can move an explicit bottom target a few points off bottom.
+    const offset = () => motions.has(surface)
+        ? parseFloat(getComputedStyle(content).translate?.split(' ')[1] ?? '0') || 0
+        : 0;
+    const announce = () => window.dispatchEvent(new Event(SCROLL_INSERTION_MOTION));
+    const cancel = () => {
+        animation?.cancel();
+        animation = undefined;
+        holding = false;
+        if (restoreClip !== undefined) {
+            surface.style.clipPath = restoreClip;
+            restoreClip = undefined;
+        }
+        if (motions.delete(surface))
+            announce();
+    };
+    const tail = () => {
+        let element = content.lastElementChild;
+        while (element?.lastElementChild)
+            element = element.lastElementChild;
+        return element;
+    };
+    const reconcile = (pinned, hold = false) => {
+        const releasing = holding && !hold;
+        const nextInset = parseFloat(getComputedStyle(surface).paddingBottom) || 0;
+        const resized = initialized && nextInset !== bottomInset;
+        bottomInset = nextInset;
+        const nextFirst = content.firstElementChild;
+        const nextLast = tail();
+        // Geometry must subtract the transform sampled by layout, not a later wall-clock
+        // spring sample. Mixing those clocks accumulates subpixel drift at each delivery.
+        const presented = offset();
+        const nextTop = (nextFirst?.getBoundingClientRect().top ?? 0) - presented;
+        // A subsequent append preserves the previous terminal element before the new
+        // one. Empty/placeholder replacement is handled separately as a first insert.
+        const appended = last &&
+            nextLast &&
+            last !== nextLast &&
+            content.contains(last) &&
+            !last.contains(nextLast) &&
+            Boolean(last.compareDocumentPosition(nextLast) & Node.DOCUMENT_POSITION_FOLLOWING);
+        const replacedTail = replacedContent ||
+            (initialized && last !== nextLast && Boolean(last) && !content.contains(last));
+        replacedContent = false;
+        const firstInsert = initialized && (!first || !content.contains(first)) && Boolean(nextFirst);
+        const distance = first === nextFirst
+            ? firstTop - nextTop
+            : firstInsert
+                ? (nextFirst?.getBoundingClientRect().height ?? 0)
+                : 0;
+        initialized = true;
+        first = nextFirst;
+        last = nextLast;
+        firstTop = nextTop;
+        if (!pinned ||
+            !(appended || firstInsert || resized || replacedTail || releasing) ||
+            (Math.abs(distance) < 0.5 && !releasing) ||
+            !allowsComposerMotion(content))
+            return;
+        const from = distance + presented;
+        cancel();
+        // SafeAreaInset intentionally lets ordinary scrolling continue beneath its
+        // accessory. Insert presentation must not paint a bubble through the editor.
+        restoreClip = surface.style.clipPath;
+        surface.style.clipPath = `inset(0 0 ${nextInset}px 0)`;
+        const epoch = now();
+        // A requested target may arrive asynchronously after the composer clears.
+        // Keep its old visual anchor until that request resolves or input cancels it;
+        // the worker receives the same stationary trajectory, with no frame loop.
+        holding = hold;
+        const duration = hold ? 1 : INSERTION_DURATION_MS;
+        const stops = hold
+            ? [
+                [0, from],
+                [1, from],
+            ]
+            : insertionProgress.map((progress, index) => [index / (insertionProgress.length - 1), from * (1 - progress)]);
+        const run = content.animate(stops.map(([progress, y]) => ({ translate: `0 ${y}px`, offset: progress })), {
+            duration,
+            // The document timeline can still be at the previous frame when startTime
+            // is assigned below. Retain the starting pose during that before phase,
+            // including another inset reconciliation in the same observer delivery.
+            fill: 'both',
+        });
+        run.startTime = epoch - performance.timeOrigin;
+        void run.finished?.catch(() => { });
+        animation = run;
+        motions.set(surface, {
+            epoch,
+            duration,
+            end: hold ? epoch : epoch + duration,
+            offset: 0,
+            stops,
+        });
+        run.onfinish = () => {
+            if (animation === run && !hold)
+                cancel();
+        };
+        announce();
+    };
+    const contentChanged = (records) => {
+        // A bubble can retain a decorative final child while replacing its typing
+        // indicator. The terminal leaf's identity alone misses that layout change.
+        replacedContent ||= records.some(record => last &&
+            [...record.removedNodes].some(node => node.nodeType === Node.ELEMENT_NODE) &&
+            record.target.contains(last));
+    };
+    return { reconcile, offset, cancel, contentChanged };
+}

package/dist/scroll/nativeScroll.d.ts

@@ -0,0 +1,14 @@
+/** One native dispatch per scroll owner, shared by active contacts and geometry observers. */
+export type NativeScrollSnapshot = Readonly<{
+    event: Event;
+    top: number;
+    left: number;
+    height: number;
+    contentHeight: number;
+    rect: (element: Element) => DOMRect;
+}>;
+type Listener = (snapshot: NativeScrollSnapshot) => void;
+/** Register only while an arena is active, rather than once for every rendered row. */
+export declare function cancelOnNativeScroll(element: HTMLElement, listener: Listener): () => void;
+export declare function observeNativeScroll(element: HTMLElement, listener: Listener): () => void;
+export {};

package/dist/scroll/nativeScroll.js

@@ -0,0 +1,71 @@
+const owners = new WeakMap();
+function ownerFor(element) {
+    let owner = owners.get(element);
+    if (owner)
+        return owner;
+    const gestures = new Set();
+    const observers = new Set();
+    const scroll = (event) => {
+        if (event.target !== element)
+            return;
+        const rectangles = new Map();
+        let geometry;
+        const read = () => (geometry ??= {
+            top: element.scrollTop,
+            left: element.scrollLeft,
+            height: element.clientHeight,
+            contentHeight: element.scrollHeight,
+        });
+        const snapshot = {
+            event,
+            get top() {
+                return read().top;
+            },
+            get left() {
+                return read().left;
+            },
+            get height() {
+                return read().height;
+            },
+            get contentHeight() {
+                return read().contentHeight;
+            },
+            rect(target) {
+                let rect = rectangles.get(target);
+                if (!rect) {
+                    rect = target.getBoundingClientRect();
+                    rectangles.set(target, rect);
+                }
+                return rect;
+            },
+        };
+        // Cancel active row/press arenas before glass or navigation observes their resulting state.
+        for (const listener of [...gestures])
+            listener(snapshot);
+        for (const listener of observers)
+            listener(snapshot);
+    };
+    element.addEventListener('scroll', scroll, { passive: true });
+    owner = { gestures, observers, dispose: () => element.removeEventListener('scroll', scroll) };
+    owners.set(element, owner);
+    return owner;
+}
+function subscribe(element, listener, gesture) {
+    const owner = ownerFor(element);
+    const listeners = gesture ? owner.gestures : owner.observers;
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (!owner.gestures.size && !owner.observers.size) {
+            owner.dispose();
+            owners.delete(element);
+        }
+    };
+}
+/** Register only while an arena is active, rather than once for every rendered row. */
+export function cancelOnNativeScroll(element, listener) {
+    return subscribe(element, listener, true);
+}
+export function observeNativeScroll(element, listener) {
+    return subscribe(element, listener, false);
+}