@usableapp/cardds 0.7.50 → 0.7.52

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 > 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.52 — 2026-10-05
+
+### Changed
+- **A `StackSheet` tab's disc shows only while its sheet is open** (Lh 2026-10-04). On the home, every peeked sheet's tabs are the icon alone — none is filled. The chosen tab fills as the sheet rises (the one that was pressed, or the page the sheet opens on) and the fill leaves as the sheet folds. Which page is current is unchanged; only the paint waits. Nothing to change in a screen.
+
+## 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/finish.css

@@ -65,6 +65,11 @@
     0 1px 2px color-mix(in srgb, var(--_shade) 20%, transparent),
     0 0.5rem 1rem -0.25rem color-mix(in srgb, var(--accent) 45%, transparent);
 }
+/* a peeked stack tab is the icon alone: no sheen and no shadow until its sheet is open (the fill fades with the sheet) */
+[data-finish="lit"] .sheet-stack--tap > .card:not(.is-open) > .card__head .stack-sheet__tab {
+  background-image: none;
+  box-shadow: none;
+}
 [data-finish="lit"] :is(.btn:not(.btn--quiet), .icon-btn:not(.icon-btn-group > *, .stack-sheet__tab:not(.icon-btn--invert))):active:not(:disabled) {
   background-image: none;
   box-shadow: var(--finish-control-down);

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) */
@@ -269,7 +285,7 @@
 .sheet-stack > .card > .sheet__body { --_cover: 0rem; } /* nothing slid under here: the stack's sheet is always whole */
 
 /* ---- StackSheet's tabs (Lh 2026-09-23): the head's end is a row of small icon buttons, the sheet's pages — the chosen one
-   filled (.icon-btn--invert); a count is a small circle over the icon's top right corner ---- */
+   filled (.icon-btn--invert) only while the sheet is open; a count is a small circle over the icon's top right corner ---- */
 .stack-sheet__tabs { display: flex; gap: var(--stack-sheet-tabs-gap, var(--sp-2)); flex: none; } /* room between the tabs: with none, the chosen tab's disc touched its neighbour's (Lh 2026-09-24) */
 /* the head is ONE line, always (Lh 2026-09-24): the tabs keep their size, the TITLE gives — it never wraps, it runs sideways
    (StackSheet measures --_over, the width it overflows by, and sets .is-long), one way: it waits, runs to the end, waits, and starts again from the first letter — like a song title */
@@ -288,8 +304,19 @@
 @media (prefers-reduced-motion: reduce) {
   .stack-sheet__title.is-long .stack-sheet__run { animation: none; display: inline; } /* inline: an ellipsis cannot cut an inline-block */
   .stack-sheet__title.is-long { text-overflow: ellipsis; }
+  .stack-sheet__tab { transition: none; } /* the disc is simply there while open, and gone while closed */
+}
+.stack-sheet__tab {
+  position: relative;
+  /* the disc fades with the sheet: in as it rises, out as it folds, and across when another tab is pressed.
+     scale stays on the press (actions.css) so the give under a finger stays quick */
+  transition:
+    scale var(--motion-press) ease-out,
+    background-color var(--motion-sheet) ease,
+    color var(--motion-sheet) ease,
+    border-color var(--motion-sheet) ease,
+    box-shadow var(--motion-sheet) ease;
 }
-.stack-sheet__tab { position: relative; }
 .stack-sheet__tab > .stack-sheet__count { /* outranks .badge (numbers.css loads after this file) */
   position: absolute;
   top: calc(-1 * var(--stack-sheet-count-out, var(--sp-2))); /* how far it stands OUT of the tab's corner, up and to the right: at sp-1 it
@@ -307,6 +334,12 @@
 /* a tab not chosen is the icon alone — no ring, no ground (Lh 2026-09-23: "the circle around is not pretty"); the chosen one turns
    to the opposite colour (.icon-btn--invert). */
 .stack-sheet__tab:not(.icon-btn--invert) { border-color: transparent; background: transparent; box-shadow: none; color: inherit; } /* the sheet's own ink, on any paper */
+/* a CLOSED sheet shows no chosen disc either (Lh 2026-10-04): arriving on the home, every tab of every sheet is the icon
+   alone. The fill fades in with the rise — the tab that was pressed, or the one the sheet opens on — and fades out as the
+   sheet folds. The class stays (which page it is); only the paint waits for .is-open. */
+.sheet-stack--tap > .card:not(.is-open) > .card__head .stack-sheet__tab.icon-btn--invert {
+  border-color: transparent; background-color: transparent; box-shadow: none; color: inherit;
+}
 /* the last tab's ICON lines up with the inset, not its button's edge: an unchosen tab shows the glyph only, so the button's own
    margin around it reaches into the card's padding — and an open head (back · title · three tabs) keeps one line (Lh 2026-09-23) */
 .card__head > .stack-sheet__tabs { margin-right: calc(-1 * var(--sp-2)); }

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) */
@@ -1270,7 +1286,7 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .sheet-stack > .card > .sheet__body { --_cover: 0rem; } /* nothing slid under here: the stack's sheet is always whole */
 
 /* ---- StackSheet's tabs (Lh 2026-09-23): the head's end is a row of small icon buttons, the sheet's pages — the chosen one
-   filled (.icon-btn--invert); a count is a small circle over the icon's top right corner ---- */
+   filled (.icon-btn--invert) only while the sheet is open; a count is a small circle over the icon's top right corner ---- */
 .stack-sheet__tabs { display: flex; gap: var(--stack-sheet-tabs-gap, var(--sp-2)); flex: none; } /* room between the tabs: with none, the chosen tab's disc touched its neighbour's (Lh 2026-09-24) */
 /* the head is ONE line, always (Lh 2026-09-24): the tabs keep their size, the TITLE gives — it never wraps, it runs sideways
    (StackSheet measures --_over, the width it overflows by, and sets .is-long), one way: it waits, runs to the end, waits, and starts again from the first letter — like a song title */
@@ -1289,8 +1305,19 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 @media (prefers-reduced-motion: reduce) {
   .stack-sheet__title.is-long .stack-sheet__run { animation: none; display: inline; } /* inline: an ellipsis cannot cut an inline-block */
   .stack-sheet__title.is-long { text-overflow: ellipsis; }
+  .stack-sheet__tab { transition: none; } /* the disc is simply there while open, and gone while closed */
+}
+.stack-sheet__tab {
+  position: relative;
+  /* the disc fades with the sheet: in as it rises, out as it folds, and across when another tab is pressed.
+     scale stays on the press (actions.css) so the give under a finger stays quick */
+  transition:
+    scale var(--motion-press) ease-out,
+    background-color var(--motion-sheet) ease,
+    color var(--motion-sheet) ease,
+    border-color var(--motion-sheet) ease,
+    box-shadow var(--motion-sheet) ease;
 }
-.stack-sheet__tab { position: relative; }
 .stack-sheet__tab > .stack-sheet__count { /* outranks .badge (numbers.css loads after this file) */
   position: absolute;
   top: calc(-1 * var(--stack-sheet-count-out, var(--sp-2))); /* how far it stands OUT of the tab's corner, up and to the right: at sp-1 it
@@ -1308,6 +1335,12 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 /* a tab not chosen is the icon alone — no ring, no ground (Lh 2026-09-23: "the circle around is not pretty"); the chosen one turns
    to the opposite colour (.icon-btn--invert). */
 .stack-sheet__tab:not(.icon-btn--invert) { border-color: transparent; background: transparent; box-shadow: none; color: inherit; } /* the sheet's own ink, on any paper */
+/* a CLOSED sheet shows no chosen disc either (Lh 2026-10-04): arriving on the home, every tab of every sheet is the icon
+   alone. The fill fades in with the rise — the tab that was pressed, or the one the sheet opens on — and fades out as the
+   sheet folds. The class stays (which page it is); only the paint waits for .is-open. */
+.sheet-stack--tap > .card:not(.is-open) > .card__head .stack-sheet__tab.icon-btn--invert {
+  border-color: transparent; background-color: transparent; box-shadow: none; color: inherit;
+}
 /* the last tab's ICON lines up with the inset, not its button's edge: an unchosen tab shows the glyph only, so the button's own
    margin around it reaches into the card's padding — and an open head (back · title · three tabs) keeps one line (Lh 2026-09-23) */
 .card__head > .stack-sheet__tabs { margin-right: calc(-1 * var(--sp-2)); }
@@ -4120,6 +4153,11 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
     0 1px 2px color-mix(in srgb, var(--_shade) 20%, transparent),
     0 0.5rem 1rem -0.25rem color-mix(in srgb, var(--accent) 45%, transparent);
 }
+/* a peeked stack tab is the icon alone: no sheen and no shadow until its sheet is open (the fill fades with the sheet) */
+[data-finish="lit"] .sheet-stack--tap > .card:not(.is-open) > .card__head .stack-sheet__tab {
+  background-image: none;
+  box-shadow: none;
+}
 [data-finish="lit"] :is(.btn:not(.btn--quiet), .icon-btn:not(.icon-btn-group > *, .stack-sheet__tab:not(.icon-btn--invert))):active:not(:disabled) {
   background-image: none;
   box-shadow: var(--finish-control-down);

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/sheets/StackSheet.d.ts

@@ -32,8 +32,9 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
 }
 /**
  * StackSheet — ONE sheet of a `SheetStack`, in the one sheet shape: SHEET HEAD (back · title · tabs or an icon) pinned at the top ·
- * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons, the chosen one filled;
- * a count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
+ * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons. The chosen one is filled
+ * only while this sheet is open — a closed home shows every icon plain; the disc fades in with the rise and out with the fold.
+ * A count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
 export declare function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel, backAt, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;

package/dist/sheets/StackSheet.js

@@ -14,8 +14,9 @@ import { Badge } from '../numbers/Badge.js';
 import { word } from '../words.js';
 /**
  * StackSheet — ONE sheet of a `SheetStack`, in the one sheet shape: SHEET HEAD (back · title · tabs or an icon) pinned at the top ·
- * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons, the chosen one filled;
- * a count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
+ * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons. The chosen one is filled
+ * only while this sheet is open — a closed home shows every icon plain; the disc fades in with the rise and out with the fold.
+ * A count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
 export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = word('back'), backAt = 'none', className, children, ...rest }) {

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.52",
   "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.",