@usableapp/cardds 0.7.49 → 0.7.51

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 > 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
+- **With the keyboard up, the screen's top stays in sight** (Lh 2026-10-04, timebank on an iPhone): when its keyboard opens, an iPhone slides the whole page up to show the field — a sheet's title went over the clock, a `Track` under the camera. cardds now measures that slide (`--vv-top`) and adds it to the screen's top reserve (`--safe-top`), so the top of a fill screen, an `AppBar`, a `Track`, a `Snackbar` stay where they were. Nothing to change in a screen. If your own CSS reads `env(safe-area-inset-top)` directly for something at the top of a cardds screen, read `--safe-top` instead.
+- **`SheetSteps`: the phone's keyboard no longer drops when a step changes** (Lh 2026-10-04, timebank as a home-screen app on an iPhone): the pad went down at every step change and the member had to tap a cell to get it back. On a touch screen the cursor now waits in the steps' hidden holder from the moment the step's button is pressed, and no script moves it after that; the open step's first field shows the cursor (a `Pin`'s caret, a `Field`'s full border) and takes the first key typed. A desktop is unchanged. Nothing to change in a screen — but `document.activeElement` is the holder (`.sheet-steps__holder`) until the first key, not the field: do not test for the field's focus right after a step change on a phone. Arriving on a NEW screen (a route change) still shows no keyboard until a tap — an iPhone allows none.
+- **`Field`: the words keep 12px from the lead icon** — 0.7.49 took the browser's padding off inputs, and the words stood against the icon. The gap is the Field's own now (`--field-gap`, 12px; it was 8px plus the browser's padding: 2px on a desktop, about 13px on an iPhone). If your theme sets `--field-gap`, it still wins.
+
 ## 0.7.49 — 2026-10-03
 
 ### 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/cardds.js

@@ -11,12 +11,17 @@
    bar and the sheet's control disappear behind the keyboard unless they
    read this; Android with interactive-widget=resizes-content (set it in the
    viewport meta) shrinks the layout viewport, and this stays 0. A pinch zoom
-   also shrinks the visual viewport, and is not a keyboard — ignored. */
+   also shrinks the visual viewport, and is not a keyboard — ignored.
+   --vv-top: how far the phone has PANNED the page up to show a focused field (iOS does it when the keyboard opens, even on
+   a page that cannot scroll): everything on the screen slides up by that much, its top under the status bar and the camera
+   (timebank on an iPhone, Lh 2026-10-04 — a sheet's title over the clock, a Track under the island). The screen's top
+   reserve (--safe-top, tokens.css) adds it, so the top stays where the eye is; --kb already counts it out at the foot. */
 if (window.visualViewport) {
   const vv = window.visualViewport;
   const publish = () => {
     const covered = vv.scale > 1.01 ? 0 : Math.max(0, Math.round(window.innerHeight - vv.height - vv.offsetTop));
     document.documentElement.style.setProperty('--kb', covered + 'px');
+    document.documentElement.style.setProperty('--vv-top', (vv.scale > 1.01 ? 0 : Math.max(0, Math.round(vv.offsetTop))) + 'px');
   };
   vv.addEventListener('resize', publish);
   vv.addEventListener('scroll', publish);

package/css/choice.css

@@ -218,19 +218,20 @@
 .pin--secret .pin__cell.is-fresh:not(:placeholder-shown) { animation: pin-flash var(--pin-flash-time, 0.5s) steps(1); }
 @keyframes pin-flash { 0% { -webkit-text-fill-color: currentColor; background-size: 0 0; } }
 .pin--secret .pin__cell::selection { background: transparent; } /* its digit is selected when the cell takes the cursor: nothing to show of it */
-.pin__cell:focus { outline: none; border-color: var(--pin-cell-active-border, currentColor); }
+.pin__cell:focus { outline: none; }
+.pin__cell:is(:focus, [data-cursor]) { border-color: var(--pin-cell-active-border, currentColor); } /* [data-cursor]: SheetSteps holds the phone's keyboard for this cell — it shows the cursor it is about to get */
 /* asleep (Pin sets it): the cursor was put here by a script on a phone and no keyboard is up — nothing can be typed until a tap, so
    the cell does not say "ready": the resting border, no caret */
 .pin--asleep .pin__cell:focus { border-color: var(--pin-cell-border, var(--outline)); }
 .pin--asleep .pin__cell:focus:placeholder-shown { background-image: none; animation: none; }
-.pin__cell:focus:placeholder-shown {
+.pin__cell:is(:focus, [data-cursor]):placeholder-shown {
   background-image: linear-gradient(currentColor, currentColor);
   background-size: var(--pin-caret-w, 2px) var(--pin-caret-h, 1em);
   background-position: center;
   background-repeat: no-repeat;
 }
 @media (prefers-reduced-motion: no-preference) {
-  .pin__cell:focus:placeholder-shown { animation: pin-caret 1.1s steps(1) infinite; }
+  .pin__cell:is(:focus, [data-cursor]):placeholder-shown { animation: pin-caret 1.1s steps(1) infinite; }
   @keyframes pin-caret { 50% { background-size: 0 0; } }
 }
 

package/css/forms.css

@@ -7,7 +7,8 @@
 .field {
   display: flex;
   align-items: center;
-  gap: var(--field-gap, var(--sp-2));
+  gap: var(--field-gap, var(--sp-3)); /* 12 between the lead icon and the words: the field's OWN room (Lh 2026-10-04) — it was sp-2 plus whatever padding the
+    browser gave the input (2px on a desktop, 0.5em on an iPhone); with that padding taken off (base.css) the words stood against the icon */
   border: var(--border-w) solid var(--field-border, var(--action-border));
   border-radius: var(--field-radius, var(--r-control));
   background: var(--field-bg, var(--action-bg));
@@ -30,7 +31,7 @@
 }
 .field input::placeholder { color: inherit; opacity: 0.55; font-size: calc(1em * var(--_ph-fit, 1)); } /* --_ph-fit: Field's measure — a placeholder longer than the box shrinks to show whole (Lh 2026-09-25) */
 /* the field the cursor is in: its own border goes full ink, in every palette (the coloured ones fade it to 25% at rest) */
-.field:has(:focus) { border-color: var(--field-active-border, currentColor); }
+.field:has(:focus, [data-cursor]) { border-color: var(--field-active-border, currentColor); } /* [data-cursor]: SheetSteps holds the phone's keyboard for this field */
 
 /* field with its action inside: date pick, send, go — the button sits flush right */
 .field--action { padding-right: var(--sp-1); min-height: var(--field-action-min-h, var(--tap-lg)); }

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/css/tokens.css

@@ -256,7 +256,7 @@
   --signal-error-soft: color-mix(in srgb, var(--signal-error) 14%, var(--surface));
   --signal-info-soft: color-mix(in srgb, var(--signal-info) 14%, var(--surface));
 }
-:root { --safe-top: env(safe-area-inset-top, 0px); --safe-bottom: env(safe-area-inset-bottom, 0px); }
+:root { --safe-top: calc(env(safe-area-inset-top, 0px) + var(--vv-top, 0px)); /* + the phone's pan while a keyboard is up (cardds.js) */ --safe-bottom: env(safe-area-inset-bottom, 0px); }
 * { --_safe-b-open: max(0px, var(--safe-bottom) - var(--kb, 0px)); }
 
 @property --sheet-peek { syntax: "<length>"; inherits: true; initial-value: 0px; }

package/dist/cardds.css

@@ -297,7 +297,7 @@
   --signal-error-soft: color-mix(in srgb, var(--signal-error) 14%, var(--surface));
   --signal-info-soft: color-mix(in srgb, var(--signal-info) 14%, var(--surface));
 }
-:root { --safe-top: env(safe-area-inset-top, 0px); --safe-bottom: env(safe-area-inset-bottom, 0px); }
+:root { --safe-top: calc(env(safe-area-inset-top, 0px) + var(--vv-top, 0px)); /* + the phone's pan while a keyboard is up (cardds.js) */ --safe-bottom: env(safe-area-inset-bottom, 0px); }
 * { --_safe-b-open: max(0px, var(--safe-bottom) - var(--kb, 0px)); }
 
 @property --sheet-peek { syntax: "<length>"; inherits: true; initial-value: 0px; }
@@ -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) */
@@ -1974,7 +1990,8 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .field {
   display: flex;
   align-items: center;
-  gap: var(--field-gap, var(--sp-2));
+  gap: var(--field-gap, var(--sp-3)); /* 12 between the lead icon and the words: the field's OWN room (Lh 2026-10-04) — it was sp-2 plus whatever padding the
+    browser gave the input (2px on a desktop, 0.5em on an iPhone); with that padding taken off (base.css) the words stood against the icon */
   border: var(--border-w) solid var(--field-border, var(--action-border));
   border-radius: var(--field-radius, var(--r-control));
   background: var(--field-bg, var(--action-bg));
@@ -1997,7 +2014,7 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 }
 .field input::placeholder { color: inherit; opacity: 0.55; font-size: calc(1em * var(--_ph-fit, 1)); } /* --_ph-fit: Field's measure — a placeholder longer than the box shrinks to show whole (Lh 2026-09-25) */
 /* the field the cursor is in: its own border goes full ink, in every palette (the coloured ones fade it to 25% at rest) */
-.field:has(:focus) { border-color: var(--field-active-border, currentColor); }
+.field:has(:focus, [data-cursor]) { border-color: var(--field-active-border, currentColor); } /* [data-cursor]: SheetSteps holds the phone's keyboard for this field */
 
 /* field with its action inside: date pick, send, go — the button sits flush right */
 .field--action { padding-right: var(--sp-1); min-height: var(--field-action-min-h, var(--tap-lg)); }
@@ -3094,19 +3111,20 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .pin--secret .pin__cell.is-fresh:not(:placeholder-shown) { animation: pin-flash var(--pin-flash-time, 0.5s) steps(1); }
 @keyframes pin-flash { 0% { -webkit-text-fill-color: currentColor; background-size: 0 0; } }
 .pin--secret .pin__cell::selection { background: transparent; } /* its digit is selected when the cell takes the cursor: nothing to show of it */
-.pin__cell:focus { outline: none; border-color: var(--pin-cell-active-border, currentColor); }
+.pin__cell:focus { outline: none; }
+.pin__cell:is(:focus, [data-cursor]) { border-color: var(--pin-cell-active-border, currentColor); } /* [data-cursor]: SheetSteps holds the phone's keyboard for this cell — it shows the cursor it is about to get */
 /* asleep (Pin sets it): the cursor was put here by a script on a phone and no keyboard is up — nothing can be typed until a tap, so
    the cell does not say "ready": the resting border, no caret */
 .pin--asleep .pin__cell:focus { border-color: var(--pin-cell-border, var(--outline)); }
 .pin--asleep .pin__cell:focus:placeholder-shown { background-image: none; animation: none; }
-.pin__cell:focus:placeholder-shown {
+.pin__cell:is(:focus, [data-cursor]):placeholder-shown {
   background-image: linear-gradient(currentColor, currentColor);
   background-size: var(--pin-caret-w, 2px) var(--pin-caret-h, 1em);
   background-position: center;
   background-repeat: no-repeat;
 }
 @media (prefers-reduced-motion: no-preference) {
-  .pin__cell:focus:placeholder-shown { animation: pin-caret 1.1s steps(1) infinite; }
+  .pin__cell:is(:focus, [data-cursor]):placeholder-shown { animation: pin-caret 1.1s steps(1) infinite; }
   @keyframes pin-caret { 50% { background-size: 0 0; } }
 }
 

package/dist/sheets/Sheet.d.ts

@@ -1,10 +1,9 @@
 import type { ComponentProps } from 'react';
+import { type Resting } from './sheetMeasure.js';
 /** how far the sheet slid. `away` = not on the screen (slid out, inert) — a state the app sets, never one a drag or a tap lands on */
 export type SheetState = 'peek' | 'half' | '3q' | 'full' | 'away';
 /** what asked for the change: the handle's `tap`, a `drag` released, `focus` in a peeked sheet, the `keyboard` (or anything else) moving the cut */
 export type SheetChangeReason = 'tap' | 'drag' | 'focus' | 'keyboard';
-declare const ORDER: readonly ["peek", "half", "3q", "full"];
-type Resting = (typeof ORDER)[number];
 export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'> {
     /** CONTROLLED: where the sheet is. The app owns it — pair it with `onStateChange`, or the sheet cannot move (like `value` without `onChange`).
      *  `peek` (handle + title row) · `half` · `3q` · `full` (its top edge at the top bar) · `away` (not on the screen). A class, never a height. */
@@ -45,4 +44,3 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
  * first's `onSettled`) — the app adds no timer.
  */
 export declare function Sheet({ state, defaultState, onStateChange, onSettled, states, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
-export {};

package/dist/sheets/Sheet.js

@@ -1,20 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { focusWhenActive, reducedMotion, useControlled, useLatest, warnOnce, watchSize } from '../state.js';
+import { useCallback, useEffect, useRef } from 'react';
+import { focusWhenActive, useControlled, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 import { word } from '../words.js';
-const ORDER = ['peek', 'half', '3q', 'full']; // low → high; `away` is below them all and outside them
+import { ORDER, slid, stopsOf, useFootRoom, usePeekStrip, useTitleRun } from './sheetMeasure.js';
+import { useSheetSlide } from './sheetSlide.js';
+import { useSheetDrag } from './sheetDrag.js';
 const RANK = { away: 0, peek: 1, half: 2, '3q': 3, full: 4 };
-const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
-/* A SHEET THAT GOES AWAY IS NOT DONE WHEN IT LANDS (Lh 2026-10-03): it holds its box for a beat more (--motion-sheet-rest) — the base
-   is seen — and only then is it settled. `out` = the sheets still on their way out, per box; a sheet asked up in that box waits for it to empty. */
-const out = new WeakMap();
-const waiting = new WeakMap();
-const leave = (box, key) => { if (!out.has(box))
-    out.set(box, new Set()); out.get(box).add(key); };
-const gone = (box, key) => { const set = out.get(box); if (set?.delete(key) && !set.size)
-    [...(waiting.get(box) ?? [])].forEach((go) => go()); };
-const ms = (t) => Math.max(0, ...t.split(',').map((v) => parseFloat(v) * (v.trim().endsWith('ms') ? 1 : 1000) || 0)); // a computed `0.35s, 0s` list → its longest, in ms
 /**
  * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on. Always the full height of its
  * box — a Step or a SheetStage — a state is only how far it slid (translate; the material never changes size).
@@ -42,90 +34,12 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
     const handleRef = useRef(null);
     const home = useRef(current !== 'peek' && current !== 'away' ? current : 'half'); // where a tap from peek returns to
     const was = useRef('away'); // mounted up = it came onto the screen: it rises from away like any arrival
-    const skipClick = useRef(false);
-    const [entered, setEntered] = useState(false); // false for the first frame: the class says `away`, so a sheet mounted up has somewhere to slide from
-    const me = useRef({}).current; // this sheet, in its box's list of sheets on their way out
-    const [held, setHeld] = useState(false); // true while it waits for the sheet going away before it to be settled
-    const [prev, setPrev] = useState('away'); // asked up from `away` (or mounted up): it holds first, and rises once its box is free
-    if (prev !== current) {
-        setPrev(current);
-        setHeld(prev === 'away' && current !== 'away');
-    }
-    const shown = entered && !held ? current : 'away';
-    const live = held ? 'away' : current; // where it is as far as its own habits go: a held sheet has not come up yet
-    const latest = useLatest({ current, onSettled });
-    const last = useRef('away'); // where it was last SHOWN (the settle effect keeps it)
-    const drag = useRef(null);
     const allowed = useCallback(() => {
         const list = (typeof states === 'string' ? states.split(/\s+/) : [...(states ?? [])]).filter((s) => ORDER.includes(s));
         return list.length ? ORDER.filter((s) => list.includes(s)) : [...ORDER];
     }, [states]);
-    useLayoutEffect(() => {
-        void ref.current?.offsetHeight; // the browser styles the `away` frame first, or there is no transition to run
-        setEntered(true);
-    }, []);
-    /* it starts on its way out: said in the commit itself, before any sheet of the box decides to rise */
-    useLayoutEffect(() => {
-        const box = ref.current?.parentElement;
-        if (box && current === 'away' && last.current !== 'away' && !reducedMotion())
-            leave(box, me);
-    }, [current, me]);
-    /* held: it rises when no sheet of its box is on its way out — at once if none is */
-    useEffect(() => {
-        const box = ref.current?.parentElement;
-        if (!held)
-            return;
-        if (!box || !out.get(box)?.size) {
-            setHeld(false);
-            return;
-        }
-        const go = () => setHeld(false);
-        if (!waiting.has(box))
-            waiting.set(box, new Set());
-        waiting.get(box).add(go);
-        return () => { waiting.get(box)?.delete(go); };
-    }, [held]);
-    /* it has finished moving: the transition ended (or at once where there is none) — say so once per move; a move cut short by another says nothing */
-    useEffect(() => {
-        const el = ref.current, box = el?.parentElement;
-        if (!el || last.current === shown)
-            return;
-        last.current = shown;
-        const cs = getComputedStyle(el);
-        let done = false, rest = 0;
-        const settled = () => { if (box)
-            gone(box, me); latest.current.onSettled?.(latest.current.current); };
-        const end = () => {
-            if (done)
-                return;
-            done = true;
-            clearTimeout(t);
-            el.removeEventListener('transitionend', onEnd);
-            if (shown !== 'away' || reducedMotion())
-                return settled();
-            rest = window.setTimeout(settled, ms(cs.getPropertyValue('--motion-sheet-rest') || '0s')); // landed: the base is seen for the rest, THEN it is settled
-        };
-        const onEnd = (e) => { if (e.target === el && e.propertyName === 'translate')
-            end(); };
-        el.addEventListener('transitionend', onEnd);
-        const t = setTimeout(end, ms(cs.transitionDuration) + ms(cs.transitionDelay) + 100); // no transition (motion off) or none came: settled anyway
-        return () => { done = true; clearTimeout(t); clearTimeout(rest); el.removeEventListener('transitionend', onEnd); if (box && shown === 'away')
-            gone(box, me); }; // cut short on its way out (raised again, unmounted): the box is free
-    }, [shown, latest, me]);
-    /* taken out of the tree while it is still up — the box stays, the sheet goes: nothing to slide, so it vanishes. Said once in dev.
-       (A whole screen leaving takes the box too; StrictMode's trial unmount is over by the time the timer looks.) */
-    const alive = useRef(false);
-    useEffect(() => {
-        alive.current = true;
-        const box = ref.current?.parentElement;
-        return () => {
-            alive.current = false;
-            setTimeout(() => {
-                if (!alive.current && box?.isConnected && latest.current.current !== 'away')
-                    warnOnce('sheet-unmount', 'cardds Sheet: unmounted while on the screen, so it vanished instead of sliding out. Set state="away" and unmount it in onSettled (state === "away").');
-            });
-        };
-    }, [latest]);
+    /* it arrives and leaves by sliding, with a rest after it went away — sheetSlide.ts */
+    const { shown, live, held } = useSheetSlide(ref, current, onSettled);
     /* THE SHEET COMES UP → ITS FIELD HAS THE CURSOR, always (Lh 2026-09-29): whenever it rises — onto the screen (mounted up, or from `away`),
        or from peek to any open state, by a button, the handle, a drag or the app — once it has finished sliding (Lh 2026-09-24: the keyboard
        must not come up while it still moves) the cursor goes to the field marked `data-autofocus` (a SheetSteps marks its open step's first
@@ -143,20 +57,6 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
         return () => { if (!cancel())
             was.current = from; }; // cut short (StrictMode's trial run, or a new state mid-slide): the rise still counts from where it began
     }, [live]);
-    /* geometry, read once per gesture — never stored: how far it has slid, and where each state rests, in px from its top at full */
-    const slid = (el) => {
-        const box = (el.offsetParent ?? el.parentElement);
-        return el.getBoundingClientRect().top - (box.getBoundingClientRect().top + box.clientTop + el.offsetTop);
-    };
-    const stopsOf = (el) => {
-        const cs = getComputedStyle(el), height = el.getBoundingClientRect().height;
-        return {
-            full: 0,
-            half: height * (parseFloat(cs.getPropertyValue('--sheet-half')) || 0),
-            '3q': height * (parseFloat(cs.getPropertyValue('--sheet-3q')) || 0),
-            peek: height - (parseFloat(cs.getPropertyValue('--sheet-peek')) || 0), // registered in tokens.css: reads back resolved
-        };
-    };
     /* bring a control into the part of the body that shows — between the pinned head and the foot's strip on the cut. The sheet asks
        for the lowest of its states, from the current one (or `atLeast`) upward, that has room; if none has, its highest. */
     const reveal = useCallback((target, reason, atLeast) => {
@@ -201,65 +101,11 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
                 reveal(at, 'keyboard');
         });
     }, [reveal]);
-    /* the peek strip holds the handle and the WHOLE title row. CSS gives the box the strip for a one-line head (--sheet-peek in
-       sheet.css); when the head is taller than that floor — a title wrapped on a narrow phone at a large text size — the sheet
-       measures its head and publishes the real strip on its box, so nothing of the title is under the cut (2026-09-22, with the
-       22-base type scale). Removed when the head fits the floor again, so the CSS number is the one in force. */
-    useEffect(() => {
-        const el = ref.current, box = el?.parentElement, head = el?.querySelector(':scope > .card__head, :scope > .sheet__head');
-        if (!el || !box || !head)
-            return;
-        const publish = () => {
-            box.style.removeProperty('--sheet-peek'); // read the CSS strip, not our own
-            const cs = getComputedStyle(el);
-            const strip = parseFloat(cs.getPropertyValue('--sheet-peek')) || 0, floor = parseFloat(cs.getPropertyValue('--sheet-head-h')) || 0;
-            const over = head.getBoundingClientRect().height - floor;
-            if (over > 0.5)
-                box.style.setProperty('--sheet-peek', `${strip + over}px`);
-        };
-        const stop = watchSize([head], publish);
-        return () => { stop(); box.style.removeProperty('--sheet-peek'); };
-    }, []);
-    /* the TITLE is one line; too long for it, it runs sideways like a song title (Lh 2026-10-03): the sheet measures how far its
-       words overflow the line and hands it to the CSS (--_over, --_run, .is-long — sheet.css). Measured on the words themselves
-       (a range), so the running indent never feeds back into the number. */
-    useEffect(() => {
-        const el = ref.current, title = el?.querySelector(':scope > .card__head > :is(h1, h2, h3):first-child, :scope > .sheet__head .sheet__title');
-        if (!el || !title)
-            return;
-        const measure = () => {
-            const words = document.createRange();
-            words.selectNodeContents(title);
-            const over = Math.max(0, Math.ceil(words.getBoundingClientRect().width - title.clientWidth));
-            title.style.setProperty('--_over', `${over}px`);
-            title.style.setProperty('--_run', `${(over / 30 + 3).toFixed(1)}s`);
-            title.classList.toggle('is-long', over > 0);
-        };
-        const stop = watchSize([title], measure);
-        const mo = new MutationObserver(measure);
-        mo.observe(title, { childList: true, characterData: true, subtree: true }); // the app changed the words
-        return () => { stop(); mo.disconnect(); title.classList.remove('is-long'); title.style.removeProperty('--_over'); title.style.removeProperty('--_run'); };
-    });
-    /* the FOOT's room follows what the foot really holds (timebank, Lh 2026-10-01): a button grows with the member's text size, a
-       line may stand over it (an error) — the CSS strip was a fixed sum (--btn-h), so the body's words ran under the button. The
-       sheet measures its foot's rows and publishes --sheet-foot-h; the strip, its ground and the body's stop all read it. */
-    useEffect(() => {
-        const el = ref.current, foot = el?.querySelector(':scope > .card__foot');
-        if (!el || !foot) {
-            el?.style.removeProperty('--sheet-foot-h');
-            return;
-        }
-        const publish = () => {
-            const rows = [...foot.children].map((c) => c.getBoundingClientRect()).filter((r) => r.height > 0);
-            if (!rows.length)
-                return el.style.removeProperty('--sheet-foot-h');
-            el.style.setProperty('--sheet-foot-h', `${Math.max(...rows.map((r) => r.bottom)) - Math.min(...rows.map((r) => r.top))}px`);
-        };
-        const stop = watchSize([...foot.children], publish);
-        const mo = new MutationObserver(publish);
-        mo.observe(foot, { childList: true });
-        return () => { stop(); mo.disconnect(); };
-    }); // every render: the foot's rows are the app's, they come and go
+    usePeekStrip(ref);
+    useTitleRun(ref);
+    useFootRoom(ref);
+    /* the handle held and moved: the sheet follows, and asks for the nearest state on release — sheetDrag.ts */
+    const { down, move, up, afterDrag } = useSheetDrag(ref, allowed, (to) => request(to, 'drag'));
     const focus = (e) => {
         onFocus?.(e);
         if (current !== 'peek' || e.target.closest('.sheet__handle'))
@@ -270,48 +116,9 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
         reveal(e.target, 'focus', home.current);
     };
     const tap = () => {
-        if (skipClick.current) {
-            skipClick.current = false;
-            return;
-        } // the click that follows a drag is not a tap
+        if (afterDrag())
+            return; // the click that follows a drag is not a tap
         request(current === 'peek' ? (allowed().includes(home.current) ? home.current : allowed().find((s) => s !== 'peek') ?? 'half') : 'peek', 'tap');
     };
-    const down = (e) => {
-        const el = ref.current;
-        if (!el || !e.isPrimary || e.button !== 0)
-            return;
-        const list = allowed(), stops = stopsOf(el), y = slid(el); // where it is now — mid-slide too, so a grab never jumps
-        drag.current = { startY: e.clientY, y0: y, y, stops, allowed: list, moved: false,
-            min: Math.min(...list.map((s) => stops[s])), max: Math.max(...list.map((s) => stops[s])),
-            tap: TAP_REM * parseFloat(getComputedStyle(document.documentElement).fontSize) };
-        e.currentTarget.setPointerCapture(e.pointerId);
-    };
-    const move = (e) => {
-        const d = drag.current, el = ref.current;
-        if (!d || !el || !e.isPrimary)
-            return;
-        const dy = e.clientY - d.startY;
-        if (!d.moved) {
-            if (Math.abs(dy) < d.tap)
-                return;
-            d.moved = true;
-            el.classList.add('is-dragging');
-        }
-        d.y = Math.min(Math.max(d.y0 + dy, d.min), d.max); // never above full, never below its lowest state
-        el.style.setProperty('--_drag', `${d.y - d.y0}px`); // the one thing written while held — the CSS adds it to the state's translate
-    };
-    const up = () => {
-        const d = drag.current, el = ref.current;
-        drag.current = null;
-        if (!d || !el)
-            return;
-        el.classList.remove('is-dragging');
-        if (!d.moved)
-            return; // a tap: the click that follows toggles
-        el.style.removeProperty('--_drag'); // same state, or the app says no: it eases back on its own
-        request(d.allowed.reduce((a, b) => (Math.abs(d.stops[b] - d.y) < Math.abs(d.stops[a] - d.y) ? b : a)), 'drag');
-        skipClick.current = true;
-        requestAnimationFrame(() => { skipClick.current = false; });
-    };
     return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${shown}`, className), inert: current === 'away' || held || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
 }

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;