@satinhq/kit 0.1.0-beta.2 → 0.1.0-beta.4

package/NOTICE

@@ -1,6 +1,6 @@
 # Satin distribution notices
 
-Generated from packages/pwakit/src/acknowledgements/inventory.json.
+Generated from packages/kit/src/acknowledgements/inventory.json.
 
 Satin-authored framework packages use MIT; third-party terms are preserved.
 Retain the copyright and permission notices required by MIT in copies or
@@ -12,7 +12,7 @@ is a separately installed build dependency. Consumer Vite builds emit NOTICE.txt
 and licenses.json from their actual emitted module graph, including runtime peers.
 Development dependencies are not assumed to be bundled.
 
-## Satin 0.1.0-beta.2
+## Satin 0.1.0-beta.4
 
 License: MIT
 Source: https://opensource.org/license/mit

package/README.md

@@ -2,7 +2,7 @@
 
 Satin builds personal apps for the installed iOS Home Screen runtime. The framework owns navigation, glass, editing, restoration and release updates.
 
-Import app APIs from `@satinhq/kit`, build integration from `@satinhq/kit/vite`, and load `@satinhq/kit/styles.css` once. `@satinhq/kit/internal` is for framework development; app lint rejects it. `@satinhq/kit/testing` belongs in tests. `NavigationSplitView` and `SymbolImage` are public app APIs. Legacy `Sidebar`, `DetailList`, `useSplitSelection` and `SidebarSymbol` composition remains in `@satinhq/kit/unstable`; use its generated export inventory for the exact list.
+Import app APIs from `@satinhq/kit`, build integration from `@satinhq/kit/vite`, and let `satinApp()` include framework styles before app CSS. For utility classes, follow [Using Tailwind with Satin](dist/docs/tailwind.md). `@satinhq/kit/internal` is for framework development; app lint rejects it. `@satinhq/kit/testing` belongs in tests. `NavigationSplitView` and `SymbolImage` are public app APIs. Legacy `Sidebar`, `DetailList`, `useSplitSelection` and `SidebarSymbol` composition remains in `@satinhq/kit/unstable`; use its generated export inventory for the exact list.
 
 ## Declare routes, then primary navigation
 
@@ -26,7 +26,6 @@ import {
   useNavigation,
   type RouteParameters,
 } from '@satinhq/kit'
-import '@satinhq/kit/styles.css'
 
 const app = defineApp({ id: 'reading-list', name: 'Reading List', icons: { source: '/icon.png' } })
 const bookParams = { id: param.string(), page: param.int().optional() }
@@ -219,7 +218,7 @@ falls back to the base glyph when no fill exists. See the shipped [available sym
 
 ## Public API inventory
 
-See the packaged [Satin API reference](dist/docs/swiftui-reference.md) for behavior, limitations, unavailable concepts and the exact export coverage inventory. The index lists supported APIs and known gaps.
+See the packaged [Satin API reference](dist/docs/reference.md) for behavior, limits, unsupported capabilities and the exact export inventory. The index lists supported APIs and known gaps.
 
 For a Safari-tab development build, set `advanced: { updateProfile: 'preview' }` in `defineApp`. No environment switch is needed. It retains the iOS WebKit platform gate and uses the existing live-update service-worker policy, which may reload on update. Use the default `release` profile for installed production apps and cold-launch update activation. A query parameter cannot opt a release build into preview. The profile does not change status style, viewport geometry, glass or lifecycle ownership.
 

package/dist/acknowledgements/inventory.json

@@ -1,13 +1,13 @@
 [
     {
         "name": "Satin",
-        "version": "0.1.0-beta.2",
+        "version": "0.1.0-beta.4",
         "license": "MIT",
         "source": "https://opensource.org/license/mit",
         "text": "MIT License\n\nCopyright (c) 2026 Satin contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
         "sha256": "a9ca5be2844d1d12fbd9b77cd7446d1895c44b4c5253aed536c2c60ad8d10caa",
         "bundledPaths": [
-            "packages/pwakit/src"
+            "packages/kit/src"
         ],
         "role": "framework"
     },
@@ -19,8 +19,8 @@
         "text": "The MIT License (MIT)\n\nCopyright (c) 2016 Vladimir Kharlampidi\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\nthe Software, and to permit persons to whom the Software is furnished to do so,\nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\nFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\nCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\nCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n",
         "sha256": "61afeee2f1d59f21412901a0015ccbec0315ae4806e3f4fbd167201ebb17b2f8",
         "bundledPaths": [
-            "packages/pwakit/src/symbols/glyphs",
-            "packages/pwakit/src/glass/lens/icons.ts"
+            "packages/kit/src/symbols/glyphs",
+            "packages/kit/src/glass/lens/icons.ts"
         ],
         "role": "adapted or generated source"
     },
@@ -32,7 +32,7 @@
         "text": "MIT License\n\nCopyright (c) 2026 Pallav Agarwal\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
         "sha256": "949e33ed2f105f112b392ce9832799a1c6d2c1fe89784a87c919dfc6b115eacc",
         "bundledPaths": [
-            "packages/pwakit/src/glass/lens"
+            "packages/kit/src/glass/lens"
         ],
         "role": "adapted or generated source"
     }

package/dist/actions/RowActions.d.ts

@@ -16,13 +16,13 @@ export type RowActionsController = {
  * A row's swipe actions and context menu. Inside an editable `List` item, the item owns the row's
  * one gesture host (it adds swipe-to-delete), so the row hands its actions to the item instead of
  * hosting a second recognizer. Swipe actions are unavailable while the list is editing, as in
- * SwiftUI; the context menu stays.
+ * selection; the context menu stays.
  */
 export declare function RowActions(props: RowActionsEngineProps): import("react").JSX.Element;
 /**
  * The one gesture host of an editable `List` item. It hosts the row's own swipe actions and context
  * menu (handed over by the row, or declared on its `ListRow`) and adds the `onDelete` action as the
- * trailing swipe, unless the row declares trailing actions of its own: SwiftUI's `swipeActions`
+ * trailing swipe, unless the row declares its own trailing `swipeActions`
  * replace swipe-to-delete.
  */
 export declare function ListItemActions({ children, swipeActions, contextMenu, deleteAction, controller, }: RowActionsProps & {
@@ -31,8 +31,8 @@ export declare function ListItemActions({ children, swipeActions, contextMenu, d
     controller?: RowActionsController;
 }): import("react").JSX.Element;
 /**
- * `contextMenu`: long-pressing the content opens the glass menu of its actions, with an
- * optional custom `preview`. Rows in a `List` take a `contextMenu` prop instead.
+ * Opens a menu of actions when the user long-presses its content, with an optional custom
+ * `preview`. Rows in a `List` take a `contextMenu` prop instead.
  */
 export declare function ContextMenu({ children, actions, preview, }: {
     children: ReactNode;

package/dist/actions/RowActions.js

@@ -2,7 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { markRowSwipeRemoval } from '../list-form/rowMotion.js';
 import { cancelOnNativeScroll } from '../scroll/nativeScroll.js';
 import { SymbolImage } from '../symbols/Symbol.js';
-import { createRowScrub, rowSwipeShouldClose, rowSwipePosition, rowSwipeRaw, primaryParts, fullSwipeThreshold, swipeActionTracks, swipeContentTrack, swipeOpenWidth, swipeWidths, updateRowCorners, } from './rowScrub.js';
+import { createRowScrub, rowSwipeShouldClose, rowSwipeRaw, primaryParts, presentedTakeover, swipeActionTracks, swipeContentTrack, swipeOpenWidth, swipeWidths, updateRowCorners, } from './rowScrub.js';
+import { createFullSwipeContact } from './fullSwipeContact.js';
 import { CONTEXT_HOLD_MS, CONTEXT_STILL_MS } from './contextMotion.js';
 import { contextPreviewSource } from './preview.js';
 import { useMenuPresenter } from '../glass/menuPresenter.js';
@@ -29,6 +30,14 @@ function retireRowSource(source) {
     if (source)
         retireNativeScrubSource(source, source.clientWidth * 2);
 }
+/** Pill takeover each tray presents when a new contact catches the row. */
+function caughtTakeovers(element, initial) {
+    const caught = (side) => {
+        const primary = element.querySelector(`[data-satin-swipe-tray="${side}"] > :first-child`);
+        return primary ? presentedTakeover(primary, initial) : 0;
+    };
+    return { leading: caught('leading'), trailing: caught('trailing') };
+}
 function RowActionsEngine({ children, swipeActions, contextMenu, disabled = false, content = false, controller, }) {
     const host = useRef(null), body = useRef(null);
     const scrollSource = useRef(null);
@@ -315,8 +324,17 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
         let navigationOwns = false;
         // Native drags an open row from its action buttons too; their taps stay presses.
         let startedOnAction = false;
-        let rowWidth = 0;
+        let rowWidth = 0, rowLeft = 0;
+        // One contact maps raw travel to the presented row for the scroll source and
+        // for this touch fallback alike, including a destructive takeover's anchor.
+        let contact;
+        let cachedSide = 'trailing';
         let cachedActions = [];
+        let fallbackRaw = 0, fallbackFrame = 0;
+        const cancelFallbackFrame = () => {
+            cancelAnimationFrame(fallbackFrame);
+            fallbackFrame = 0;
+        };
         let contentFrame;
         let initial = 0, current = 0, owned = false, last;
         const clearTimer = () => {
@@ -326,6 +344,28 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
             timer = undefined;
             delete element.dataset.satinContextPending;
         };
+        /** Present the touch-fallback row and pills from one raw sample. A takeover's
+         * jump keeps moving without input, so it presents further frames itself. */
+        const paintFallback = (raw, now, evaluate) => {
+            if (!contact)
+                return current;
+            fallbackRaw = raw;
+            const position = contact.present(raw, now, evaluate);
+            const takeover = contact.takeover(cachedSide, raw, now);
+            for (const action of cachedActions)
+                Object.assign(action.element.style, action.frame(position, raw, initial ? 1 : 0, takeover));
+            if (body.current && contentFrame)
+                Object.assign(body.current.style, contentFrame(position, initial ? 1 : 0));
+            current = position;
+            live.current.offset = position;
+            if (evaluate && !fallbackFrame && contact.settling(now))
+                fallbackFrame = requestAnimationFrame(time => {
+                    fallbackFrame = 0;
+                    if (session && !scrub.current)
+                        paintFallback(fallbackRaw, time, true);
+                });
+            return position;
+        };
         const cancelPress = () => {
             if (pointerId !== undefined)
                 cancelPointerPressForOwnedGesture(pointerId);
@@ -344,6 +384,7 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
             }
             const previous = last;
             last = sample;
+            contact?.track(sample.x - rowLeft);
             session = reduceGestureArena(arena, session, sample).session;
             if (!session)
                 return;
@@ -397,6 +438,7 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
                         const primary = element.querySelector(`[data-satin-swipe-tray="${element.dataset.satinSwipeSide}"] > :first-child`);
                         const side = element.dataset.satinSwipeSide === 'leading' ? 'leading' : 'trailing';
                         const edge = swipeEdge(props.current.swipeActions, side);
+                        cachedSide = side;
                         cachedActions =
                             primary && !scrub.current
                                 ? swipeActionTracks(primary, edge.actions.length, rowWidth, edge.allowsFullSwipe)
@@ -414,16 +456,14 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
                     const raw = rowSwipeRaw(initial, rowWidth, props.current.swipeActions, swipeWidths(element)) +
                         sample.x -
                         session.start.x;
-                    current = scrub.current
-                        ? scrub.current.position()
-                        : rowSwipePosition(raw, rowWidth, props.current.swipeActions, swipeWidths(element));
-                    if (!scrub.current) {
-                        for (const action of cachedActions)
-                            Object.assign(action.element.style, action.frame(current, raw, initial ? 1 : 0));
-                        if (body.current && contentFrame)
-                            Object.assign(body.current.style, contentFrame(current, initial ? 1 : 0));
+                    // A lift-off sample is presented but never evaluated: release reads the
+                    // takeover that the last presented frame showed.
+                    if (scrub.current) {
+                        current = scrub.current.position();
+                        live.current.offset = current;
                     }
-                    live.current.offset = current;
+                    else
+                        paintFallback(raw, sample.time, sample.phase === 'move');
                 }
             }
             if (sample.phase === 'end' && initial !== 0 && !owned && !startedOnAction) {
@@ -432,10 +472,11 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
             }
             if (sample.phase === 'end' || sample.phase === 'cancel') {
                 clearTimer();
+                cancelFallbackFrame();
                 if (owned)
                     cancelPress();
                 if (swipe && sample.phase === 'end') {
-                    const released = scrub.current?.flush();
+                    const released = scrub.current?.flush(performance.now(), false);
                     const releaseRaw = released?.raw ??
                         rowSwipeRaw(initial, rowWidth, props.current.swipeActions, swipeWidths(element)) +
                             sample.x -
@@ -452,26 +493,37 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
                     element.dataset.satinSwipeSide = current >= 0 ? 'leading' : 'trailing';
                     const edge = swipeEdge(props.current.swipeActions, current >= 0 ? 'leading' : 'trailing');
                     const actions = edge.actions;
-                    const first = actions[0], width = rowWidth;
-                    // The same per-edge threshold that drives the takeover while held. Native
-                    // closes a leading three-action row dragged back from 295pt.
-                    const releaseSide = current >= 0 ? 'leading' : 'trailing';
-                    const threshold = fullSwipeThreshold(width, actions.length, releaseSide, swipeWidths(element)[releaseSide], element.dataset.satinSwipeLabelLayout === 'inline');
-                    if (edge.allowsFullSwipe && Math.abs(releaseRaw) >= threshold && first && !first.disabled)
+                    const first = actions[0];
+                    // The same rule that drives the takeover while held: a distance threshold,
+                    // or a destructive takeover still shown by the last frame. Native closes a
+                    // leading three-action row dragged back from 295pt.
+                    if (first && contact?.armed(releaseRaw))
                         perform(first, current, true);
                     else {
                         const from = current;
-                        current = !rowSwipeShouldClose(initial, current, sample.x - session.start.x)
+                        // Native closes a destructive takeover that was reversed out of its zone.
+                        // That close starts far across the row, so its pills stay and shrink
+                        // with it, as when an open row is dismissed, until it reaches rest.
+                        const anchoredClose = !!contact?.anchored();
+                        const closes = anchoredClose || rowSwipeShouldClose(initial, current, sample.x - session.start.x);
+                        current = !closes
                             ? Math.sign(current) *
                                 swipeOpenWidth(actions.length, swipeWidths(element)[current >= 0 ? 'leading' : 'trailing'])
                             : 0;
-                        element.dataset.satinSwipeActive = String(current !== 0);
+                        if (!anchoredClose)
+                            element.dataset.satinSwipeActive = String(current !== 0);
                         live.current.offset = current;
                         setOffset(current);
-                        if (body.current)
+                        const settling = body.current &&
                             settleSwipe(body.current, from, current, previous
                                 ? (sample.x - previous.x) / Math.max(0.001, (sample.time - previous.time) / 1000)
                                 : 0, element.querySelector(`[data-satin-swipe-tray="${from >= 0 ? 'leading' : 'trailing'}"] > :first-child`) ?? undefined, swipeOpenWidth(actions.length, swipeWidths(element)[current >= 0 ? 'leading' : 'trailing']), initial !== 0, rowWidth, edge.allowsFullSwipe);
+                        if (anchoredClose) {
+                            if (settling)
+                                void settling.finished.then(close, () => { });
+                            else
+                                close();
+                        }
                     }
                 }
                 else if (sample.phase === 'cancel' && !hold && !navigationOwns)
@@ -494,6 +546,8 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
                 return;
             const rect = element.getBoundingClientRect();
             rowWidth = rect.width;
+            rowLeft = rect.left;
+            cancelFallbackFrame();
             contentFrame = body.current ? swipeContentTrack(body.current) : undefined;
             navigationOwns = false;
             startedOnAction = !!target.closest('[data-satin-swipe-action]');
@@ -523,6 +577,17 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
             if (body.current && animations.length)
                 body.current.style.transform = `translate3d(${initial}px,0,0)`;
             scrub.current?.cancel();
+            // A new contact starts a new mapping: catching a settling row never inherits
+            // the previous contact's anchor, only its presented pose and pill takeover.
+            contact = createFullSwipeContact({
+                width: rowWidth,
+                configuration: props.current.swipeActions,
+                widths: swipeWidths(element),
+                inline: element.dataset.satinSwipeLabelLayout === 'inline',
+                caught: initial ? caughtTakeovers(element, initial) : undefined,
+                reducedMotion: window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false,
+                now: performance.now(),
+            });
             // A contact that touched down before the retired source re-armed cannot scroll
             // it; the touch path drives that contact while the clamp holds the source.
             const sourceLive = nativeTouch &&
@@ -533,7 +598,7 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
                 releaseNativeScrubClamp(scrollSource.current);
             scrub.current =
                 sourceLive && scrollSource.current && body.current
-                    ? createRowScrub(element, scrollSource.current, body.current, initial, rowWidth, props.current.swipeActions)
+                    ? createRowScrub(element, scrollSource.current, body.current, initial, rowWidth, props.current.swipeActions, contact)
                     : undefined;
             live.current.offset = initial;
             current = initial;
@@ -710,6 +775,7 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
             if (pointerId !== undefined && captureOwner?.hasPointerCapture?.(pointerId))
                 captureOwner.releasePointerCapture(pointerId);
             scrub.current?.cancel();
+            cancelFallbackFrame();
             delete element.dataset.satinRowCompositor;
             finishLift();
             clearTimer();
@@ -748,7 +814,7 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
             }
             if (event.key === 'Escape' && !open)
                 close();
-        }, children: [_jsx("div", { ref: scrollSource, "data-satin-row-scrub": "true", children: _jsx("div", { "data-satin-row-scrub-range": "true", children: _jsxs("div", { "data-satin-row-scrub-sticky": "true", children: [['leading', 'trailing'].map(side => (_jsx("div", { "data-satin-swipe-tray": side, inert: disabled || !offset || (offset > 0 ? side !== 'leading' : side !== 'trailing'), children: swipeEdge(swipeActions, side).actions.map(action => (_jsxs(Pressable, { disabled: disabled || action.disabled, "aria-label": action.accessibilityLabel ?? action.label, onPress: () => select(action), "data-satin-swipe-action": "true", "data-satin-swipe-icon": Boolean(action.icon || action.symbol), "data-satin-swipe-title": Boolean(action.label), style: {
+        }, children: [_jsx("div", { ref: scrollSource, "data-satin-row-scrub": "true", children: _jsx("div", { "data-satin-row-scrub-range": "true", children: _jsxs("div", { "data-satin-row-scrub-sticky": "true", children: [['leading', 'trailing'].map(side => (_jsx("div", { "data-satin-swipe-tray": side, inert: disabled || !offset || (offset > 0 ? side !== 'leading' : side !== 'trailing'), children: swipeEdge(swipeActions, side).actions.map(action => (_jsxs(Pressable, { disabled: disabled || action.disabled, "aria-label": action.accessibilityLabel ?? action.label, onPress: () => select(action), "data-satin-swipe-action": "true", "data-satin-swipe-role": action.role, "data-satin-swipe-icon": Boolean(action.icon || action.symbol), "data-satin-swipe-title": Boolean(action.label), style: {
                                         '--satin-swipe-tint': action.tint ??
                                             (action.role === 'destructive'
                                                 ? 'var(--satin-action-destructive)'
@@ -762,7 +828,7 @@ function RowActionsEngine({ children, swipeActions, contextMenu, disabled = fals
  * A row's swipe actions and context menu. Inside an editable `List` item, the item owns the row's
  * one gesture host (it adds swipe-to-delete), so the row hands its actions to the item instead of
  * hosting a second recognizer. Swipe actions are unavailable while the list is editing, as in
- * SwiftUI; the context menu stays.
+ * selection; the context menu stays.
  */
 export function RowActions(props) {
     const item = useContext(ListItemContext);
@@ -781,7 +847,7 @@ function DelegatedRowActions({ children, swipeActions, contextMenu, disabled, de
 /**
  * The one gesture host of an editable `List` item. It hosts the row's own swipe actions and context
  * menu (handed over by the row, or declared on its `ListRow`) and adds the `onDelete` action as the
- * trailing swipe, unless the row declares trailing actions of its own: SwiftUI's `swipeActions`
+ * trailing swipe, unless the row declares its own trailing `swipeActions`
  * replace swipe-to-delete.
  */
 export function ListItemActions({ children, swipeActions, contextMenu, deleteAction, controller, }) {
@@ -812,8 +878,8 @@ function withTrailingAction(swipeActions, action) {
     return configurations;
 }
 /**
- * `contextMenu`: long-pressing the content opens the glass menu of its actions, with an
- * optional custom `preview`. Rows in a `List` take a `contextMenu` prop instead.
+ * Opens a menu of actions when the user long-presses its content, with an optional custom
+ * `preview`. Rows in a `List` take a `contextMenu` prop instead.
  */
 export function ContextMenu({ children, actions, preview, }) {
     return (_jsx(RowActions, { contextMenu: { actions, preview }, content: true, children: children }));

package/dist/actions/fullSwipeContact.d.ts

@@ -0,0 +1,73 @@
+import { type SwipeWidths } from './rowScrub.js';
+import { type SwipeActions } from './types.js';
+/**
+ * Destructive full swipe, from the iOS 27 stock List reference (400pt rows, 80pt
+ * tall, UIKit pan translation plus per-frame model and presentation geometry;
+ * fullswipe r3 receipts, re-read in r4).
+ *
+ * - The trigger is where the finger is, not how far it went. Strokes starting at
+ *   x300, x350 and x400 all take over when the finger reaches screen x88 (row-local
+ *   68pt on a 20pt inset row), after 187, 236 and 287pt of travel; x90 never does.
+ *   It also needs recognized travel: 165pt that ends at x60 never takes over.
+ * - At takeover the row jumps once, to 29pt short of the far edge (-371 of 400),
+ *   then follows the finger 1:1 from that anchor for the rest of the contact,
+ *   including on the way back. Past 372.5pt it resists (5 contacts, RMS 0.02pt).
+ * - The jump settles as a critically damped 48/s spring after one 18ms frame
+ *   (4 takeovers, normalized RMS 0.020).
+ * - Leaving the zone disarms the release but keeps the anchor and the expanded pill.
+ *   All 5 reversals (to x140, 220, 280, 340 and 380) cancel and close to rest.
+ * - A release commits only if the last presented frame showed the takeover. A
+ *   2100pt/s flick whose in-zone sample lands after lift-off cancels; a
+ *   1300pt/s flick whose in-zone sample lands a frame earlier commits.
+ *
+ * Non-destructive first actions never re-anchor. They keep the distance threshold,
+ * read at release (leading Read: 205pt cancels, 210pt commits, row 1:1).
+ * No velocity projection appears in any of these trials, so none is modelled.
+ */
+export declare const destructiveFullSwipe: {
+    /** The finger must be within this distance of the row's far edge (bracket 68..70pt). */
+    readonly edgeZone: 69;
+    /** Recognized travel needed before the zone counts (bracket 165..187pt). */
+    readonly minimumTravel: 176;
+    /** The jump leaves this much of the row showing. */
+    readonly anchorInset: 29;
+    /** Past this inset from the far edge, the anchored row resists. */
+    readonly limitInset: 27.5;
+    readonly resistance: 0.46;
+    readonly resistanceLength: 31;
+    /** Critically damped approach of the jump, after one held frame. */
+    readonly jumpRate: 48;
+    readonly jumpDelay: 0.018;
+};
+type Side = 'leading' | 'trailing';
+/** Remaining fraction of the jump distance `seconds` after it began. */
+export declare function destructiveJumpRemaining(seconds: number): number;
+export type FullSwipeContactOptions = {
+    width: number;
+    configuration?: SwipeActions;
+    widths: SwipeWidths;
+    /** Single-line rows; selects the inline full-swipe threshold. */
+    inline: boolean;
+    /** Pill takeover already presented when this contact caught the row. */
+    caught?: Partial<Record<Side, number>>;
+    reducedMotion?: boolean;
+    now: number;
+};
+/**
+ * One finger's mapping from the row's raw offset to its presented position, plus
+ * whether releasing now performs the first action. Created per contact, so a new
+ * contact (including one that catches a settling row) starts without an anchor.
+ * The scroll-source path and the touch fallback both present through it.
+ */
+export declare function createFullSwipeContact(options: FullSwipeContactOptions): {
+    /** Record the finger's row-local x; the next presented frame evaluates it. */
+    track(x: number): void;
+    present: (raw: number, now: number, evaluate?: boolean) => number;
+    takeover: (side: Side, raw: number, now: number) => number;
+    armed: (raw: number) => boolean;
+    anchored: () => boolean;
+    /** The jump is still visibly moving, so a frame must be presented without input. */
+    settling: (now: number) => boolean;
+};
+export type FullSwipeContact = ReturnType<typeof createFullSwipeContact>;
+export {};

package/dist/actions/fullSwipeContact.js

@@ -0,0 +1,186 @@
+import { fullSwipeThreshold, rowSwipePosition } from './rowScrub.js';
+import { takeoverSample } from './swipeSpring.js';
+import { swipeEdge } from './types.js';
+/**
+ * Destructive full swipe, from the iOS 27 stock List reference (400pt rows, 80pt
+ * tall, UIKit pan translation plus per-frame model and presentation geometry;
+ * fullswipe r3 receipts, re-read in r4).
+ *
+ * - The trigger is where the finger is, not how far it went. Strokes starting at
+ *   x300, x350 and x400 all take over when the finger reaches screen x88 (row-local
+ *   68pt on a 20pt inset row), after 187, 236 and 287pt of travel; x90 never does.
+ *   It also needs recognized travel: 165pt that ends at x60 never takes over.
+ * - At takeover the row jumps once, to 29pt short of the far edge (-371 of 400),
+ *   then follows the finger 1:1 from that anchor for the rest of the contact,
+ *   including on the way back. Past 372.5pt it resists (5 contacts, RMS 0.02pt).
+ * - The jump settles as a critically damped 48/s spring after one 18ms frame
+ *   (4 takeovers, normalized RMS 0.020).
+ * - Leaving the zone disarms the release but keeps the anchor and the expanded pill.
+ *   All 5 reversals (to x140, 220, 280, 340 and 380) cancel and close to rest.
+ * - A release commits only if the last presented frame showed the takeover. A
+ *   2100pt/s flick whose in-zone sample lands after lift-off cancels; a
+ *   1300pt/s flick whose in-zone sample lands a frame earlier commits.
+ *
+ * Non-destructive first actions never re-anchor. They keep the distance threshold,
+ * read at release (leading Read: 205pt cancels, 210pt commits, row 1:1).
+ * No velocity projection appears in any of these trials, so none is modelled.
+ */
+export const destructiveFullSwipe = {
+    /** The finger must be within this distance of the row's far edge (bracket 68..70pt). */
+    edgeZone: 69,
+    /** Recognized travel needed before the zone counts (bracket 165..187pt). */
+    minimumTravel: 176,
+    /** The jump leaves this much of the row showing. */
+    anchorInset: 29,
+    /** Past this inset from the far edge, the anchored row resists. */
+    limitInset: 27.5,
+    resistance: 0.46,
+    resistanceLength: 31,
+    /** Critically damped approach of the jump, after one held frame. */
+    jumpRate: 48,
+    jumpDelay: 0.018,
+};
+const sides = { leading: 1, trailing: -1 };
+const sideOf = (sign) => (sign >= 0 ? 'leading' : 'trailing');
+/** Remaining fraction of the jump distance `seconds` after it began. */
+export function destructiveJumpRemaining(seconds) {
+    const elapsed = seconds - destructiveFullSwipe.jumpDelay;
+    if (elapsed <= 0)
+        return 1;
+    const rate = destructiveFullSwipe.jumpRate;
+    return (1 + rate * elapsed) * Math.exp(-rate * elapsed);
+}
+/** The anchored row tracks 1:1 up to the soft limit, then resists. */
+function anchoredResistance(distance, width) {
+    const { limitInset, resistance, resistanceLength } = destructiveFullSwipe;
+    const limit = width - limitInset;
+    const excess = distance - limit;
+    if (excess <= 0)
+        return distance;
+    return limit + (resistance * excess) / (1 + (resistance * excess) / resistanceLength);
+}
+const firstActionEnabled = (edge) => !!edge.actions[0] && !edge.actions[0].disabled;
+const isDestructive = (edge) => edge.allowsFullSwipe && firstActionEnabled(edge) && edge.actions[0].role === 'destructive';
+/**
+ * One finger's mapping from the row's raw offset to its presented position, plus
+ * whether releasing now performs the first action. Created per contact, so a new
+ * contact (including one that catches a settling row) starts without an anchor.
+ * The scroll-source path and the touch fallback both present through it.
+ */
+export function createFullSwipeContact(options) {
+    const { width, configuration, widths, inline, reducedMotion = false } = options;
+    const edges = {
+        leading: swipeEdge(configuration, 'leading'),
+        trailing: swipeEdge(configuration, 'trailing'),
+    };
+    const thresholds = {
+        leading: fullSwipeThreshold(width, edges.leading.actions.length, 'leading', widths.leading, inline),
+        trailing: fullSwipeThreshold(width, edges.trailing.actions.length, 'trailing', widths.trailing, inline),
+    };
+    /** Row-local x of the latest finger sample. */
+    let finger;
+    /** Set once, at the first takeover of this contact; never moved afterward. */
+    let anchor;
+    /** Zone state of the last evaluated frame; this is what a release reads. */
+    let engaged = false;
+    const takeovers = {
+        leading: springState(options.caught?.leading ?? 0, options.now),
+        trailing: springState(options.caught?.trailing ?? 0, options.now),
+    };
+    function inZone(raw) {
+        const side = sideOf(raw);
+        if (!raw || finger === undefined || !isDestructive(edges[side]))
+            return false;
+        const fromFarEdge = side === 'trailing' ? finger : width - finger;
+        return (fromFarEdge <= destructiveFullSwipe.edgeZone &&
+            Math.abs(raw) >= destructiveFullSwipe.minimumTravel);
+    }
+    function anchoredPosition(raw, side, offset) {
+        const sign = sides[side];
+        // The anchor keeps the row on its side even if the finger crosses back.
+        const distance = Math.max(0, (raw + offset) * sign);
+        return sign * anchoredResistance(distance, width);
+    }
+    /** Presented row position. `evaluate` is true for presented frames; a release
+     * sample is presented with `false`, so it cannot arm or anchor after lift-off. */
+    function present(raw, now, evaluate = true) {
+        if (evaluate) {
+            engaged = inZone(raw);
+            if (engaged && !anchor) {
+                const side = sideOf(raw);
+                const sign = sides[side];
+                const target = sign * (width - destructiveFullSwipe.anchorInset);
+                const before = rowSwipePosition(raw, width, configuration, widths);
+                anchor = { side, offset: target - raw, gap: before - target, time: now };
+            }
+        }
+        if (!anchor)
+            return rowSwipePosition(raw, width, configuration, widths);
+        // Once the jump is within a quarter point, finish it so the row stops writing.
+        if (!jumpVisible(now))
+            anchor.gap = 0;
+        const remaining = destructiveJumpRemaining((now - anchor.time) / 1000);
+        return anchoredPosition(raw, anchor.side, anchor.offset) + anchor.gap * remaining;
+    }
+    function jumpVisible(now) {
+        if (!anchor)
+            return false;
+        return Math.abs(anchor.gap) * destructiveJumpRemaining((now - anchor.time) / 1000) > 0.25;
+    }
+    /** Pill takeover for one tray. Destructive edges take over with the anchor and keep
+     * it through reversals; other edges follow the distance threshold. */
+    function takeover(side, raw, now) {
+        const edge = edges[side];
+        if (!edge.allowsFullSwipe)
+            return 0;
+        if (edge.actions.length === 1)
+            return 1;
+        const target = isDestructive(edge)
+            ? anchor?.side === side
+                ? 1
+                : 0
+            : raw * sides[side] >= thresholds[side]
+                ? 1
+                : 0;
+        const sample = takeovers[side].sample(target, now);
+        return reducedMotion ? target : Math.max(0, Math.min(1, sample));
+    }
+    /** Whether releasing with `raw` performs the first action of the presented side. */
+    function armed(raw) {
+        const side = anchor?.side ?? sideOf(raw);
+        const edge = edges[side];
+        if (!edge.allowsFullSwipe || !firstActionEnabled(edge))
+            return false;
+        if (isDestructive(edge))
+            return engaged && anchor?.side === side;
+        return raw * sides[side] >= thresholds[side];
+    }
+    return {
+        /** Record the finger's row-local x; the next presented frame evaluates it. */
+        track(x) {
+            finger = x;
+        },
+        present,
+        takeover,
+        armed,
+        anchored: () => anchor !== undefined,
+        /** The jump is still visibly moving, so a frame must be presented without input. */
+        settling: jumpVisible,
+    };
+}
+/** A takeover spring that retargets from its presented position and velocity. */
+function springState(initial, now) {
+    const state = { from: initial, target: initial, velocity: 0, started: now };
+    return {
+        sample(target, time) {
+            const sample = takeoverSample(state.from, state.target, state.velocity, (time - state.started) / 1000);
+            if (target !== state.target) {
+                state.from = sample.position;
+                state.velocity = sample.velocity;
+                state.target = target;
+                state.started = time;
+            }
+            return sample.position;
+        },
+    };
+}