@usableapp/cardds 0.7.50 → 0.7.51

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 > For: a project that consumes `@usableapp/cardds` and its AI — what changed between versions, written as before → after, so a screen can be brought up to date without reading the source. Newest first. A consumer never edits cardds; if something here leaves you without a way to do what you did before, report the gap.
 
+## 0.7.51 — 2026-10-04
+
+### Added
+- **`SheetStack`: a peeked head opens on a pull up, and an open head folds on a pull down** (Lh 2026-10-04). A tap still does both. The finger starts on the title, the back button, or the head itself. A tab, or any other button in the head, stays a click. The card follows the finger, and past the commit it opens or folds through `onOpenChange`, the same ask as a tap. A short pull springs back. Nothing to change in a screen for the open and the fold.
+- **`Home` and `SheetStack` take `onRefresh`**: a pull down in the open sheet's content, already scrolled to the top, asks `onRefresh(index)`. The sheet stays open. The words drop with the finger, then spring back. The stack does not fetch — reload that section yourself. Omit `onRefresh` and that pull only scrolls. If the content is scrolled down, the finger scrolls. `<Home onRefresh={(index) => …}>` forwards it.
+
+### Changed
+- **A pull down on a closed stack's empty base no longer reaches the browser's reload.** The base does not scroll and does not chain the gesture. Nothing to change in a screen.
+
 ## 0.7.50 — 2026-10-04
 
 ### Fixed

package/README.md

@@ -178,12 +178,15 @@ the card is the material, the sheet is what it is in the stack.
   front one too, peeks at the stack's bottom; the headroom above is the base's.
   An optional `<div class="sheet-stack__base">` — written AFTER the sheets, so
   it takes no sheet slot — is what the base shows there, behind every sheet.
-  A tap opens any sheet over it; back drops it home.
+  A tap, or a pull up, opens any sheet over it. The open title or its back
+  button, tapped or pulled down, drops it home. A pull down in the open
+  content, already at the top, asks `onRefresh` — omit it and that pull only
+  scrolls. A tab in the head stays a click.
 - **Five sheets max.** Slots are declared per `:nth-child` in `stack.css`; a
   sixth would render at slot 0, on top of the first.
 - **Every head needs its own `.sheet-stack__back`** if the stack is `--tap`. It stays
   hidden until that sheet is open, then slides into a reserved header slot.
-- **No ids, no wiring.** `SheetStack` holds which sheet is open (`open` + `onOpenChange`, or `defaultOpen`).
+- **No ids, no wiring.** `SheetStack` holds which sheet is open (`open` + `onOpenChange`, or `defaultOpen`). A pull down in the open content asks `onRefresh(index)`. The stack does not fetch.
 - **`.card-stack` is gone.** That was this component's first name and the wrong
   one — the members are sheets and the stack is the menu, not a list of cards.
   Never bring it back, not even as an alias.

package/css/stack.css

@@ -167,12 +167,22 @@
 }
 .sheet-stack--tap > .card.is-open {
   /* up by its own resting offset — pure movement, nothing resizes */
-  translate: 0 calc(-1 * var(--slot, 0) * var(--stack-step));
+  translate: 0 calc(-1 * var(--slot, 0) * var(--stack-step) + var(--_pull, 0px));
   cursor: default;
   overflow-y: auto;
   overflow-x: clip;
   overscroll-behavior: contain;
 }
+.sheet-stack--tap > .card.is-open.is-dragging { transition: none; }
+.sheet-stack--tap > .card > .card__head { touch-action: none; }
+/* a pull in the content, already at the top: the words move down, the card stays. --_refresh is the finger, private. */
+.sheet-stack > .card > .sheet__body { padding-top: var(--_refresh, 0px); transition: padding-top var(--motion-sheet) ease; }
+.sheet-stack--tap > .card.is-open:not(:has(> .sheet__body)) {
+  padding-top: calc(var(--card-pad) + var(--_refresh, 0px));
+  transition: translate var(--motion-sheet) ease, padding-top var(--motion-sheet) ease;
+}
+.sheet-stack > .card > .sheet__body.is-refreshing,
+.sheet-stack--tap > .card.is-open.is-refreshing:not(:has(> .sheet__body)) { transition: none; }
 /* the front sheet — the one open on arrival — never travels up (it is not
    tappable), so its resting offset would leave its last n steps below the
    screen forever, unreachable by any scroll (timebank home, 2026-09-13). It
@@ -205,9 +215,13 @@
    lands flush at the top. is-before tucks one step below its resting place.
    ============================================================ */
 .sheet-stack--closed { --_headroom: calc(100% - var(--_n) * var(--stack-step)); }
-.sheet-stack--closed > .card { translate: 0 var(--_headroom); }
+.sheet-stack--closed > .card { translate: 0 calc(var(--_headroom) - var(--_lift, 0px)); }
+.sheet-stack--closed > .card.is-dragging { transition: none; }
+.sheet-stack--tap:not(.sheet-stack--closed) > .card.is-dragging:not(.is-open) {
+  translate: 0 calc(-1 * var(--_lift, 0px));
+  transition: none;
+}
 .sheet-stack--closed > .card.is-before { translate: 0 calc(var(--_headroom) + var(--stack-step)); }
-.sheet-stack--closed > .card.is-open { translate: 0 calc(-1 * var(--slot, 0) * var(--stack-step)); }
 .sheet-stack--closed > .card.is-after { translate: 0 100vh; }
 
 /* .sheet-stack__base — the base's content, in the headroom of a closed stack:
@@ -224,7 +238,9 @@
   display: grid;
   align-content: end;
   gap: var(--card-gap, var(--sp-5));
-  overflow: clip;
+  overflow: hidden;
+  overscroll-behavior: none;
+  touch-action: none;
 }
 /* a base that is ONE Page is a page's words (a title, a welcome, the news): it reads from the TOP, like any page —
    loose things (a picture, a line) still sit against the peeks (Lh 2026-09-23, the home) */

package/dist/cardds.css

@@ -1168,12 +1168,22 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 }
 .sheet-stack--tap > .card.is-open {
   /* up by its own resting offset — pure movement, nothing resizes */
-  translate: 0 calc(-1 * var(--slot, 0) * var(--stack-step));
+  translate: 0 calc(-1 * var(--slot, 0) * var(--stack-step) + var(--_pull, 0px));
   cursor: default;
   overflow-y: auto;
   overflow-x: clip;
   overscroll-behavior: contain;
 }
+.sheet-stack--tap > .card.is-open.is-dragging { transition: none; }
+.sheet-stack--tap > .card > .card__head { touch-action: none; }
+/* a pull in the content, already at the top: the words move down, the card stays. --_refresh is the finger, private. */
+.sheet-stack > .card > .sheet__body { padding-top: var(--_refresh, 0px); transition: padding-top var(--motion-sheet) ease; }
+.sheet-stack--tap > .card.is-open:not(:has(> .sheet__body)) {
+  padding-top: calc(var(--card-pad) + var(--_refresh, 0px));
+  transition: translate var(--motion-sheet) ease, padding-top var(--motion-sheet) ease;
+}
+.sheet-stack > .card > .sheet__body.is-refreshing,
+.sheet-stack--tap > .card.is-open.is-refreshing:not(:has(> .sheet__body)) { transition: none; }
 /* the front sheet — the one open on arrival — never travels up (it is not
    tappable), so its resting offset would leave its last n steps below the
    screen forever, unreachable by any scroll (timebank home, 2026-09-13). It
@@ -1206,9 +1216,13 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
    lands flush at the top. is-before tucks one step below its resting place.
    ============================================================ */
 .sheet-stack--closed { --_headroom: calc(100% - var(--_n) * var(--stack-step)); }
-.sheet-stack--closed > .card { translate: 0 var(--_headroom); }
+.sheet-stack--closed > .card { translate: 0 calc(var(--_headroom) - var(--_lift, 0px)); }
+.sheet-stack--closed > .card.is-dragging { transition: none; }
+.sheet-stack--tap:not(.sheet-stack--closed) > .card.is-dragging:not(.is-open) {
+  translate: 0 calc(-1 * var(--_lift, 0px));
+  transition: none;
+}
 .sheet-stack--closed > .card.is-before { translate: 0 calc(var(--_headroom) + var(--stack-step)); }
-.sheet-stack--closed > .card.is-open { translate: 0 calc(-1 * var(--slot, 0) * var(--stack-step)); }
 .sheet-stack--closed > .card.is-after { translate: 0 100vh; }
 
 /* .sheet-stack__base — the base's content, in the headroom of a closed stack:
@@ -1225,7 +1239,9 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   display: grid;
   align-content: end;
   gap: var(--card-gap, var(--sp-5));
-  overflow: clip;
+  overflow: hidden;
+  overscroll-behavior: none;
+  touch-action: none;
 }
 /* a base that is ONE Page is a page's words (a title, a welcome, the news): it reads from the TOP, like any page —
    loose things (a picture, a line) still sit against the peeks (Lh 2026-09-23, the home) */

package/dist/sheets/SheetStack.d.ts

@@ -9,6 +9,8 @@ export interface SheetStackProps extends ComponentProps<'div'> {
     defaultOpen?: number | null;
     /** the stack ASKS: a peeked head was tapped (its index), or the open sheet's `StackBack` (`null`) */
     onOpenChange?: (open: number | null) => void;
+    /** the open sheet's scroller was already at the top and the finger pulled down past the commit. The stack asks with that index. It does not fetch. Omit it and a pull in the body only scrolls */
+    onRefresh?: (index: number) => void;
     /** wider peeks so more of each title shows (display stacks) */
     fanned?: boolean;
     /** nothing open on arrival (tap mode): every sheet, the front one too, peeks at the stack's bottom; the room above is the base's (`base`). A tap opens any sheet over it */
@@ -26,8 +28,9 @@ export interface SheetStackProps extends ComponentProps<'div'> {
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
  *
  * A COMPONENT, not a wiring: WHICH sheet is open is the app's (`open` + `onOpenChange`, or `defaultOpen`) — so a button anywhere, a route or
- * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, the open
- * sheet's StackBack or its title (folds it). How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, or a pull up on
+ * that head (the title, the back button, or the head itself — not a tab), opens it. The open sheet's StackBack or its title, tapped or pulled
+ * down, folds it. A pull down in the content, already at the top, asks `onRefresh` and does not fold. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
  * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }: SheetStackProps): import("react").JSX.Element;
+export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, onRefresh, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }: SheetStackProps): import("react").JSX.Element;

package/dist/sheets/SheetStack.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef } from 'react';
-import { focusWhenActive, useControlled } from '../state.js';
+import { flushSync } from 'react-dom';
+import { focusWhenActive, useControlled, useLatest } from '../state.js';
 import { cx } from '../cx.js';
 const PHASE = 380; // ms before the before-pack un-tucks on close, so the after-pack is clear first
 /* the stack's sheets, in slot order: its direct children — or, where a host wraps each child in one box of its own, the first .card in
@@ -9,6 +10,28 @@ const sheetsOf = (stack) => [...stack.children]
     .filter((c) => !c.classList.contains('sheet-stack__base'))
     .map((c) => (c.classList.contains('card') ? c : c.querySelector(':scope > .card')))
     .filter((c) => c instanceof HTMLElement);
+const SLOP_REM = 0.5;
+const COMMIT_REM = 4.5;
+const pxFromRem = (rem) => parseFloat(getComputedStyle(document.documentElement).fontSize) * rem;
+const restPullPx = (card, stack) => {
+    if (!stack.classList.contains('sheet-stack--closed'))
+        return card.offsetTop;
+    const sheets = sheetsOf(stack);
+    const step = sheets[1]?.offsetTop ?? 0;
+    return Math.max(0, stack.clientHeight - sheets.length * step) + card.offsetTop;
+};
+const readFrame = (card) => { card.getBoundingClientRect(); };
+const along = (dir, startY, y) => (dir === 'down' ? Math.max(0, y - startY) : Math.max(0, startY - y));
+const releaseProp = (card, prop) => {
+    card.classList.remove('is-dragging');
+    readFrame(card);
+    card.style.removeProperty(prop);
+};
+const pullsHead = (target, head) => {
+    if (!(target instanceof Element))
+        return false;
+    return target === head || !!target.closest('.sheet-stack__back') || !!target.closest('.card__head > :is(h1, h2, h3)');
+};
 /**
  * SheetStack — the MENU: sheets stacked like paper at the middle of the home screen, every one a main section.
  * Children are Cards, direct children only, at most five: first = the back of the stack, last = the front (open) sheet.
@@ -19,21 +42,31 @@ const sheetsOf = (stack) => [...stack.children]
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
  *
  * A COMPONENT, not a wiring: WHICH sheet is open is the app's (`open` + `onOpenChange`, or `defaultOpen`) — so a button anywhere, a route or
- * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, the open
- * sheet's StackBack or its title (folds it). How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, or a pull up on
+ * that head (the title, the back button, or the head itself — not a tab), opens it. The open sheet's StackBack or its title, tapped or pulled
+ * down, folds it. A pull down in the content, already at the top, asks `onRefresh` and does not fold. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
  * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }) {
+export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, onRefresh, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }) {
     const [current, request] = useControlled(open, defaultOpen, onOpenChange);
     const ref = useRef(null);
     const was = useRef(null);
     const untuck = useRef(null);
+    const headPull = useRef(null);
+    const bodyPull = useRef(null);
+    const swallow = useRef(false);
+    const refreshRef = useLatest(onRefresh);
     /* paint the state onto the sheets — after every render, so a re-rendered Card never loses its place */
     useLayoutEffect(() => {
         const stack = ref.current;
         if (!stack || mode !== 'tap')
             return;
         const sheets = sheetsOf(stack);
+        for (const c of sheets)
+            if (!c.classList.contains('is-dragging')) {
+                c.style.removeProperty('--_pull');
+                c.style.removeProperty('--_lift');
+            }
         // the keyboard's way in: a head's title takes the focus where a tap on it would do something — every title while none is
         // open (Enter opens that sheet), only the open one's while one is (Enter folds it)
         sheets.forEach((c, i) => {
@@ -74,8 +107,299 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
         const cancel = focusWhenActive(sheetsOf(ref.current)[current], { scope: ':scope > .sheet__body' });
         return () => { cancel(); };
     }, [current, mode]);
+    useEffect(() => {
+        const stack = ref.current;
+        if (!stack || mode !== 'tap' || current == null)
+            return;
+        const card = sheetsOf(stack)[current];
+        if (!card)
+            return;
+        const head = card.querySelector(':scope > .card__head');
+        const scroller = card.querySelector(':scope > .sheet__body') ?? card;
+        const index = current;
+        let stopDoc = () => { };
+        const listen = (move, up, cancel) => {
+            stopDoc();
+            document.addEventListener('pointermove', move, { passive: false });
+            document.addEventListener('pointerup', up);
+            document.addEventListener('pointercancel', cancel);
+            stopDoc = () => {
+                document.removeEventListener('pointermove', move);
+                document.removeEventListener('pointerup', up);
+                document.removeEventListener('pointercancel', cancel);
+                stopDoc = () => { };
+            };
+        };
+        const primary = (e) => e.isPrimary && e.button === 0;
+        const armSwallow = () => {
+            swallow.current = true;
+            requestAnimationFrame(() => { swallow.current = false; });
+        };
+        const onHeadDown = (e) => {
+            e.stopPropagation();
+            if (!head || !primary(e) || headPull.current || bodyPull.current)
+                return;
+            if (!pullsHead(e.target, head))
+                return;
+            const slop = pxFromRem(SLOP_REM);
+            const commit = pxFromRem(COMMIT_REM);
+            const pull = {
+                pointerId: e.pointerId, card, index, dir: 'down', startY: e.clientY, last: 0,
+                cap: Math.max(restPullPx(card, stack), commit), commit, slop, moved: false,
+            };
+            headPull.current = pull;
+            const onMove = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                const dy = along('down', pull.startY, ev.clientY);
+                pull.last = dy;
+                if (dy < pull.slop)
+                    return;
+                pull.moved = true;
+                ev.preventDefault();
+                try {
+                    if (head && !head.hasPointerCapture(ev.pointerId))
+                        head.setPointerCapture(ev.pointerId);
+                }
+                catch { /* the pointer is already gone */ }
+                card.classList.add('is-dragging');
+                card.style.setProperty('--_pull', `${Math.min(dy, pull.cap)}px`);
+            };
+            const onUp = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                const dy = Math.max(pull.last, along('down', pull.startY, ev.clientY));
+                const moved = pull.moved || dy >= pull.slop;
+                headPull.current = null;
+                stopDoc();
+                if (moved && dy >= pull.commit) {
+                    card.classList.remove('is-dragging');
+                    readFrame(card);
+                    flushSync(() => request(null));
+                    if (card.isConnected && card.classList.contains('is-open') && card.style.getPropertyValue('--_pull'))
+                        releaseProp(card, '--_pull');
+                }
+                else
+                    releaseProp(card, '--_pull');
+                if (moved)
+                    armSwallow();
+            };
+            const onCancel = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                headPull.current = null;
+                stopDoc();
+                releaseProp(card, '--_pull');
+            };
+            listen(onMove, onUp, onCancel);
+        };
+        const onBodyDown = (e) => {
+            if (!primary(e) || headPull.current || bodyPull.current || !refreshRef.current)
+                return;
+            if (scroller.scrollTop > 0)
+                return;
+            if (e.target instanceof Element && e.target.closest('.card__head'))
+                return;
+            const slop = pxFromRem(SLOP_REM);
+            const commit = pxFromRem(COMMIT_REM);
+            const pull = {
+                pointerId: e.pointerId, scroller, index, startX: e.clientX, startY: e.clientY,
+                lastDy: 0, commit, slop, moved: false, drop: false,
+            };
+            bodyPull.current = pull;
+            const onMove = (ev) => {
+                if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
+                    return;
+                if (scroller.scrollTop > 0) {
+                    pull.drop = true;
+                    return;
+                }
+                if (pull.drop)
+                    return;
+                const dx = ev.clientX - pull.startX;
+                const dy = ev.clientY - pull.startY;
+                pull.lastDy = Math.max(0, dy);
+                if (!pull.moved && !pull.drop) {
+                    if (Math.max(Math.abs(dx), Math.abs(dy)) < pull.slop)
+                        return;
+                    if (Math.abs(dx) > dy || dy <= 0) {
+                        pull.drop = true;
+                        return;
+                    }
+                }
+                pull.moved = true;
+                ev.preventDefault();
+                try {
+                    if (!scroller.hasPointerCapture(ev.pointerId))
+                        scroller.setPointerCapture(ev.pointerId);
+                }
+                catch { /* the pointer is already gone */ }
+                scroller.classList.add('is-refreshing');
+                scroller.style.setProperty('--_refresh', `${Math.min(dy, pull.commit)}px`);
+            };
+            const onUp = (ev) => {
+                if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
+                    return;
+                const dy = Math.max(pull.lastDy, Math.max(0, ev.clientY - pull.startY));
+                const ask = pull.moved && !pull.drop && scroller.scrollTop <= 0 && dy >= pull.commit;
+                bodyPull.current = null;
+                stopDoc();
+                scroller.classList.remove('is-refreshing');
+                readFrame(scroller);
+                scroller.style.removeProperty('--_refresh');
+                if (ask)
+                    refreshRef.current?.(pull.index);
+                if (pull.moved)
+                    armSwallow();
+            };
+            const onCancel = (ev) => {
+                if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
+                    return;
+                bodyPull.current = null;
+                stopDoc();
+                scroller.classList.remove('is-refreshing');
+                scroller.style.removeProperty('--_refresh');
+            };
+            listen(onMove, onUp, onCancel);
+        };
+        head?.addEventListener('pointerdown', onHeadDown);
+        scroller.addEventListener('pointerdown', onBodyDown);
+        return () => {
+            stopDoc();
+            const held = headPull.current;
+            headPull.current = null;
+            bodyPull.current = null;
+            if (held?.card.classList.contains('is-dragging'))
+                releaseProp(held.card, '--_pull');
+            head?.removeEventListener('pointerdown', onHeadDown);
+            scroller.removeEventListener('pointerdown', onBodyDown);
+        };
+    }, [current, mode, request]);
+    /* none open: a pull UP on a peeked head (not a tab) follows the finger and, past the commit, opens that sheet */
+    useEffect(() => {
+        const stack = ref.current;
+        if (!stack || mode !== 'tap' || current != null)
+            return;
+        const sheets = sheetsOf(stack);
+        let stopDoc = () => { };
+        const listen = (move, up, cancel) => {
+            stopDoc();
+            document.addEventListener('pointermove', move, { passive: false });
+            document.addEventListener('pointerup', up);
+            document.addEventListener('pointercancel', cancel);
+            stopDoc = () => {
+                document.removeEventListener('pointermove', move);
+                document.removeEventListener('pointerup', up);
+                document.removeEventListener('pointercancel', cancel);
+                stopDoc = () => { };
+            };
+        };
+        const armSwallow = () => {
+            swallow.current = true;
+            requestAnimationFrame(() => { swallow.current = false; });
+        };
+        const cleanups = [];
+        sheets.forEach((card, index) => {
+            const head = card.querySelector(':scope > .card__head');
+            if (!head)
+                return;
+            const onDown = (e) => {
+                if (!e.isPrimary || e.button !== 0 || headPull.current)
+                    return;
+                if (!pullsHead(e.target, head)) {
+                    if (!(e.target instanceof Element) || !e.target.closest('button, a'))
+                        return;
+                    const startY = e.clientY;
+                    const id = e.pointerId;
+                    const slop = pxFromRem(SLOP_REM);
+                    const move = (ev) => {
+                        if (ev.pointerId !== id)
+                            return;
+                        if (Math.abs(ev.clientY - startY) >= slop)
+                            swallow.current = true;
+                    };
+                    const up = (ev) => {
+                        if (ev.pointerId !== id)
+                            return;
+                        document.removeEventListener('pointermove', move);
+                        document.removeEventListener('pointerup', up);
+                        if (swallow.current)
+                            requestAnimationFrame(() => { swallow.current = false; });
+                    };
+                    document.addEventListener('pointermove', move);
+                    document.addEventListener('pointerup', up);
+                    return;
+                }
+                e.stopPropagation();
+                const slop = pxFromRem(SLOP_REM);
+                const commit = pxFromRem(COMMIT_REM);
+                const travel = card.getBoundingClientRect().top - stack.getBoundingClientRect().top;
+                const pull = {
+                    pointerId: e.pointerId, card, index, dir: 'up', startY: e.clientY, last: 0,
+                    cap: Math.max(travel, commit), commit, slop, moved: false,
+                };
+                headPull.current = pull;
+                const onMove = (ev) => {
+                    if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                        return;
+                    const upPx = along('up', pull.startY, ev.clientY);
+                    pull.last = upPx;
+                    if (upPx < pull.slop)
+                        return;
+                    pull.moved = true;
+                    ev.preventDefault();
+                    try {
+                        if (!head.hasPointerCapture(ev.pointerId))
+                            head.setPointerCapture(ev.pointerId);
+                    }
+                    catch { /* the pointer is already gone */ }
+                    card.classList.add('is-dragging');
+                    card.style.setProperty('--_lift', `${Math.min(upPx, pull.cap)}px`);
+                };
+                const onUp = (ev) => {
+                    if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                        return;
+                    const upPx = Math.max(pull.last, along('up', pull.startY, ev.clientY));
+                    const moved = pull.moved || upPx >= pull.slop;
+                    headPull.current = null;
+                    stopDoc();
+                    if (moved && upPx >= pull.commit) {
+                        card.classList.remove('is-dragging');
+                        readFrame(card);
+                        flushSync(() => request(pull.index));
+                        if (card.isConnected && !card.classList.contains('is-open'))
+                            releaseProp(card, '--_lift');
+                    }
+                    else
+                        releaseProp(card, '--_lift');
+                    if (moved)
+                        armSwallow();
+                };
+                const onCancel = (ev) => {
+                    if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                        return;
+                    headPull.current = null;
+                    stopDoc();
+                    releaseProp(card, '--_lift');
+                };
+                listen(onMove, onUp, onCancel);
+            };
+            head.addEventListener('pointerdown', onDown);
+            cleanups.push(() => head.removeEventListener('pointerdown', onDown));
+        });
+        return () => {
+            stopDoc();
+            const held = headPull.current;
+            headPull.current = null;
+            if (held?.dir === 'up' && held.card.classList.contains('is-dragging'))
+                releaseProp(held.card, '--_lift');
+            cleanups.forEach((fn) => fn());
+        };
+    }, [current, mode, request]);
     const click = (e) => {
         onClick?.(e);
+        if (swallow.current)
+            return;
         const stack = ref.current;
         if (!stack || mode !== 'tap')
             return;

package/dist/templates/Home.d.ts

@@ -29,6 +29,8 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
     open?: number | null;
     defaultOpen?: number | null;
     onOpenChange?: (open: number | null) => void;
+    /** the open sheet's scroller was already at the top and the finger pulled down past the commit. The stack asks with that index. It does not fetch. Omit it and a pull in the body only scrolls */
+    onRefresh?: (index: number) => void;
     /** CONTENT above the sheet heads — one `Page`: a welcome, the news, a picture. It reads
      *  from the top; a sheet coming up covers it */
     base?: ReactNode;
@@ -48,4 +50,4 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
  * at the bottom). A tap on a head brings that sheet up to fill everything under the top. Only the open sheet's body is rendered — three
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
-export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;
+export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, onRefresh, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;

package/dist/templates/Home.js

@@ -15,7 +15,7 @@ const LEAVE = 800; // ms: a closing sheet keeps its body until it has slid home
  * at the bottom). A tap on a head brings that sheet up to fill everything under the top. Only the open sheet's body is rendered — three
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
-export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
+export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, onRefresh, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
     const [open, change] = useControlled(openProp, defaultOpen, onOpenChange);
     const [leaving, setLeaving] = useState(null);
     const [seen, setSeen] = useState(() => new Set(open != null ? [open] : []));
@@ -35,5 +35,5 @@ export function Home({ top, title, sheets, open: openProp, defaultOpen = null, o
     }, [leaving]);
     const [tabs, setTabs] = useState(() => Object.fromEntries(sheets.map((x, i) => [i, x.defaultTab ?? x.tabs?.[0]?.id])));
     const shows = (i) => i === open || i === leaving || (keep && seen.has(i));
-    return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: open, onOpenChange: change, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, backAt: backAt, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));
+    return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: open, onOpenChange: change, onRefresh: onRefresh, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, backAt: backAt, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.50",
+  "version": "0.7.51",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",