@usableapp/cardds 0.7.54 → 0.7.55

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 > 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.55 — 2026-10-06
+
+### Fixed
+- **Back on Home closes the open sheet and stays on the page.** With `LayerHistory` above `Home` and no `open` prop, the open sheet is one history entry. Back folds it. The address does not change, so the screen does not slide. Opening keeps the page's own query, and only `arrive` drops a query. If your `push` and `replace` still call `navigate({ pathname }, { state })`, they drop that query until you pass the page's own search through, as the README snippet does now.
+- **A character typed while the SheetSteps holder has the cursor lands in a Composer.** It already landed in a Field or a Pin. Nothing to change.
+- **Closing a SheetStack, the sheets in front return one at a time.** Nothing to change.
+- **A pull to refresh keeps going when the sheet starts reloading while the finger is still down.** Letting go clears the pull. Nothing to change.
+- **`Slider` with an empty `value` and a `defaultValue` draws one number,** on the knob and on the track. Nothing to change.
+
+### Changed
+- **The navigation that opens the home screen replaces the page behind it,** so a closed stack has nothing of the app to go back to. `Home` does not do this itself. The route that arrives there uses replace.
+- **A long title renders `is-long`, and a pull renders `is-refreshing`.** Do not stamp those classes onto the node after it has rendered.
+
 ## 0.7.54 — 2026-10-06
 
 ### Changed

package/README.md

@@ -387,8 +387,8 @@ between at 40% down the screen (see *Anatomy*, "Where the centre is"):
     sheet: read `?way=` once, no entry added, the query dropped). `useLayers().closeAll(then)` takes every layer off, then moves
     (signing out). NOTHING INSIDE A LAYER TAKES AN ENTRY — a step, typed text, a sheet's rest, a tab: back at any step takes the
     whole sheet down, and opened again it starts anew (a new `key` per opening). The project hands its router over once:
-    `<LayerHistory state push replace back>` around its screens — react-router: `state = useLocation().state`,
-    `push = (s) => navigate({ pathname }, { state: s })`, `replace = (s) => navigate({ pathname }, { replace: true, state: s })`,
+    `<LayerHistory state push replace back>` around its screens — react-router: `location = useLocation()`, `state = location.state`,
+    `push = (s, search) => navigate({ pathname: location.pathname, search: search === 'drop' ? '' : location.search }, { state: s })`, `replace = (s, search) => navigate({ pathname: location.pathname, search: search === 'drop' ? '' : location.search }, { replace: true, state: s })`,
     `back = (n) => navigate(-n)`. cardds never calls the History API itself. Story `LayerHistory · Back`.
     A FINISHED PROCESS IS NOT GONE BACK INTO: history cannot be deleted, so (a) inside a process every move on is a `replace`,
     never a push — when it ends, back skips all of it; (b) a page that can no longer be returned to guards itself: it checks on

package/dist/cards/Card.js

@@ -4,7 +4,7 @@ import { cx } from '../cx.js';
 import { warnOnce } from '../state.js';
 import { CardHead } from './CardHead.js';
 import { CardFoot } from './CardFoot.js';
-import { StackHeadCtx, stackPaint, useStackCard } from '../sheets/stackCard.js';
+import { StackHeadCtx, StackPullCtx, stackPaint, useStackCard } from '../sheets/stackCard.js';
 /**
  * Card — ONE boundary: head · content · foot. Cards are content the system offers (the words, the thing to read).
  * The head and the foot are SLOTS: `heading` · `caption` · `end` (the card writes its CardHead first) and `foot` · `footLink`
@@ -24,8 +24,8 @@ export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article',
     }
     const own = useRef(null);
     const swallow = useRef(false);
-    useStackCard(own, stack, swallow);
-    const painted = stackPaint(stack);
+    const pulling = useStackCard(own, stack, swallow);
+    const painted = stackPaint(stack, pulling);
     const setRef = (node) => {
         own.current = node;
         const passed = ref;
@@ -50,7 +50,7 @@ export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article',
         if (!stack.open && !stack.before && !stack.after)
             stack.onOpen();
     };
-    const inner = (body) => (_jsx(StackHeadCtx.Provider, { value: stack ? (stack.before || stack.after ? -1 : 0) : null, children: body }));
+    const inner = (body) => (_jsx(StackHeadCtx.Provider, { value: stack ? (stack.before || stack.after ? -1 : 0) : null, children: _jsx(StackPullCtx.Provider, { value: pulling, children: body }) }));
     const props = {
         ...rest,
         ref: setRef,

package/dist/cards/CardHead.d.ts

@@ -10,5 +10,7 @@ export interface CardHeadProps extends ComponentProps<'div'> {
     top?: boolean;
     /** the heading level to render the string heading with (h2 default; h1 for the one-feature page) */
     level?: 'h1' | 'h2' | 'display';
+    /** the sheet measured this title as wider than its line, so the heading runs sideways */
+    long?: boolean;
 }
-export declare function CardHead({ heading, caption, end, top, level, className, children, ...rest }: CardHeadProps): import("react").JSX.Element;
+export declare function CardHead({ heading, caption, end, top, level, long, className, children, ...rest }: CardHeadProps): import("react").JSX.Element;

package/dist/cards/CardHead.js

@@ -14,8 +14,8 @@ const onTitleKey = (e) => {
     e.preventDefault();
     e.currentTarget.click();
 };
-/** the stack's title is the keyboard's way in. The heading renders the tab stop; nothing sets it on the node afterwards */
-function markTitle(node, tab) {
+/** the stack's title is the keyboard's way in. The heading renders the tab stop and, when the sheet measured it long, `.is-long`. Nothing sets either on the node afterwards */
+function markTitle(node, tab, long) {
     if (!isValidElement(node))
         return node;
     const el = node;
@@ -24,13 +24,16 @@ function markTitle(node, tab) {
     if (level !== 'h1' && level !== 'h2' && level !== 'display' && !intrinsic)
         return node;
     return cloneElement(el, {
-        tabIndex: tab,
-        onKeyDown: (e) => { el.props.onKeyDown?.(e); if (!e.defaultPrevented)
-            onTitleKey(e); },
+        ...(long ? { className: cx(el.props.className, 'is-long') } : {}),
+        ...(tab != null ? {
+            tabIndex: tab,
+            onKeyDown: (e) => { el.props.onKeyDown?.(e); if (!e.defaultPrevented)
+                onTitleKey(e); },
+        } : {}),
     });
 }
-export function CardHead({ heading, caption, end, top, level = 'h2', className, children, ...rest }) {
+export function CardHead({ heading, caption, end, top, level = 'h2', long, className, children, ...rest }) {
     const tab = useContext(StackHeadCtx);
     const H = level === 'h1' ? 'h1' : 'h2';
-    return (_jsxs("div", { className: cx('card__head', top && 'card__head--top', className), ...rest, children: [heading != null && _jsx(H, { className: `t-${level}`, tabIndex: tab ?? undefined, onKeyDown: tab != null ? onTitleKey : undefined, children: heading }), caption != null && _jsx("span", { className: "t-caption t-muted", children: caption }), tab == null ? children : Children.map(children, (c) => markTitle(c, tab)), end] }));
+    return (_jsxs("div", { className: cx('card__head', top && 'card__head--top', className), ...rest, children: [heading != null && _jsx(H, { className: cx(`t-${level}`, long && 'is-long'), tabIndex: tab ?? undefined, onKeyDown: tab != null ? onTitleKey : undefined, children: heading }), caption != null && _jsx("span", { className: "t-caption t-muted", children: caption }), tab == null && !long ? children : Children.map(children, (c) => markTitle(c, tab, !!long)), end] }));
 }

package/dist/choice/Slider.js

@@ -7,8 +7,10 @@ const share = (value, min, max) => (max > min ? Math.min(1, Math.max(0, (value -
 export function Slider({ label, glyph, className, style, onInput, ...input }) {
     const cursor = useStepCursor();
     const min = Number(input.min) || 0, max = Number(input.max) || 100;
-    const [live, setLive] = useState(Number(input.defaultValue ?? input.value ?? min));
-    const value = input.value != null && input.value !== '' ? Number(input.value) : live;
-    return (_jsxs("label", { className: cx('slider', className), style: { ...style, '--slider-at': String(share(value, min, max)) }, children: [label != null && _jsx("span", { className: "slider__label", children: label }), glyph != null && _jsx("span", { className: "slider__glyph", "aria-hidden": "true", children: glyph }), _jsx("input", { className: "slider__range", type: "range", onInput: (e) => { if (input.value == null)
-                    setLive(Number(e.currentTarget.value)); onInput?.(e); }, ...input, ...cursor })] }));
+    const { value: given, defaultValue, ...rest } = input;
+    const held = given != null && given !== '';
+    const [live, setLive] = useState(Number((held ? given : defaultValue) ?? min));
+    const shown = held ? Number(given) : live;
+    return (_jsxs("label", { className: cx('slider', className), style: { ...style, '--slider-at': String(share(shown, min, max)) }, children: [label != null && _jsx("span", { className: "slider__label", children: label }), glyph != null && _jsx("span", { className: "slider__glyph", "aria-hidden": "true", children: glyph }), _jsx("input", { className: "slider__range", type: "range", onInput: (e) => { if (!held)
+                    setLive(Number(e.currentTarget.value)); onInput?.(e); }, ...rest, ...(held ? { value: given } : { defaultValue }), ...cursor })] }));
 }

package/dist/scaffold/LayerHistory.d.ts

@@ -1,15 +1,17 @@
 import { type ReactNode } from 'react';
 export type LayerValue = string | number;
+export type LayerSearch = 'keep' | 'drop';
 type EntryState = Record<string, unknown>;
 export interface LayerHistoryProps {
     /** the CURRENT history entry's state, as a value of this render — the hook re-reads it on every back / forward / push
      *  (react-router: `useLocation().state`) */
     state: unknown;
-    /** a NEW entry for the same page with this state: the path kept, the query dropped (react-router:
-     *  `navigate({ pathname }, { state })`) */
-    push: (state: EntryState) => void;
-    /** the SAME entry, its state replaced: the path kept, the query dropped (`navigate({ pathname }, { replace: true, state })`) */
-    replace: (state: EntryState) => void;
+    /** a NEW entry for the same page with this state. The path is kept. The query is kept unless the second argument is `'drop'` (react-router:
+     *  `navigate({ pathname, search: search === 'drop' ? '' : location.search }, { state })`) */
+    push: (state: EntryState, search?: LayerSearch) => void;
+    /** the SAME entry, its state replaced. The path is kept. The query is kept unless the second argument is `'drop'`
+     *  (`navigate({ pathname, search: search === 'drop' ? '' : location.search }, { replace: true, state })`) */
+    replace: (state: EntryState, search?: LayerSearch) => void;
     /** back by this many entries (`navigate(-entries)`) */
     back: (entries: number) => void;
     children?: ReactNode;
@@ -40,6 +42,8 @@ export interface LayerApi {
  * give what is inside a new `key` per opening.
  */
 export declare function useLayer(name: string): LayerApi;
+/** useOptionalLayer — the same layer as `useLayer`, or `null` when no `LayerHistory` is above. A missing provider does not warn. */
+export declare function useOptionalLayer(name: string): LayerApi | null;
 /**
  * useLayers — every layer over this screen: `up` (how many), and `closeAll(then)` — take them ALL off, then run `then`: before a
  * move that must leave nothing of this page's layers under it (signed out → replace with the sign-in page). The entries are

package/dist/scaffold/LayerHistory.js

@@ -33,6 +33,26 @@ const useHistory = () => {
         warnOnce('layer-history', 'cardds useLayer: no <LayerHistory> above — hand the router over once, around the screens; until then a layer never comes up.');
     return h ?? NONE;
 };
+const layerApi = (name, handle) => {
+    const { state, push, replace, back } = handle;
+    const { rest, layers } = read(state);
+    const layer = layers[name] ?? null;
+    const others = () => Object.fromEntries(Object.entries(layers).filter(([key]) => key !== name));
+    return {
+        value: layer?.value ?? null,
+        open: (to) => (layer ? replace({ ...rest, layers: { ...layers, [name]: { value: to, pushed: layer.pushed } } }, 'keep') : push({ ...rest, layers: { ...layers, [name]: { value: to, pushed: true } } }, 'keep')),
+        // already up on an entry the app pushed (the link opened where the layer was): it stays a pushed one, or the close would leave that entry behind
+        arrive: (as) => replace({ ...rest, layers: { ...layers, [name]: { value: as, pushed: layer?.pushed ?? false } } }, 'drop'),
+        close: () => {
+            if (!layer)
+                return;
+            if (layer.pushed)
+                back(1);
+            else
+                replace({ ...rest, layers: others() }, 'keep');
+        },
+    };
+};
 /**
  * useLayer — ONE layer of this screen, by its name: a whole bottom sheet, a modal. Back takes it off; the screen stays.
  * `const way = useLayer('way')` → `<CallSheet open={way.value} onOpenChange={(up, i) => (up ? way.open(i!) : way.close())}>`.
@@ -40,26 +60,13 @@ const useHistory = () => {
  * give what is inside a new `key` per opening.
  */
 export function useLayer(name) {
-    const { state, push, replace, back } = useHistory();
-    return useMemo(() => {
-        const { rest, layers } = read(state);
-        const layer = layers[name] ?? null;
-        const others = () => Object.fromEntries(Object.entries(layers).filter(([key]) => key !== name));
-        return {
-            value: layer?.value ?? null,
-            open: (to) => (layer ? replace({ ...rest, layers: { ...layers, [name]: { value: to, pushed: layer.pushed } } }) : push({ ...rest, layers: { ...layers, [name]: { value: to, pushed: true } } })),
-            // already up on an entry the app pushed (the link opened where the layer was): it stays a pushed one, or the close would leave that entry behind
-            arrive: (as) => replace({ ...rest, layers: { ...layers, [name]: { value: as, pushed: layer?.pushed ?? false } } }),
-            close: () => {
-                if (!layer)
-                    return;
-                if (layer.pushed)
-                    back(1);
-                else
-                    replace({ ...rest, layers: others() });
-            },
-        };
-    }, [state, push, replace, back, name]);
+    const handle = useHistory();
+    return useMemo(() => layerApi(name, handle), [handle, name]);
+}
+/** useOptionalLayer — the same layer as `useLayer`, or `null` when no `LayerHistory` is above. A missing provider does not warn. */
+export function useOptionalLayer(name) {
+    const handle = useContext(Ctx);
+    return useMemo(() => (handle ? layerApi(name, handle) : null), [handle, name]);
 }
 /**
  * useLayers — every layer over this screen: `up` (how many), and `closeAll(then)` — take them ALL off, then run `then`: before a

package/dist/sheets/Sheet.js

@@ -1,12 +1,22 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef } from 'react';
+import { Children, cloneElement, isValidElement, useCallback, useEffect, useRef, useState } from 'react';
 import { focusWhenActive, useControlled, watchSize } from '../state.js';
+import { CardHead } from '../cards/CardHead.js';
+import { SheetHead } from './SheetHead.js';
 import { cx } from '../cx.js';
 import { word } from '../words.js';
 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 };
+/** the sheet's own head renders `.is-long` from the measure. A heading further down is not that title. */
+function markLong(node, long) {
+    if (!long || !isValidElement(node))
+        return node;
+    if (node.type !== CardHead && node.type !== SheetHead)
+        return node;
+    return cloneElement(node, { long: true });
+}
 /**
  * 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).
@@ -102,7 +112,8 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
         });
     }, [reveal]);
     usePeekStrip(ref);
-    useTitleRun(ref);
+    const [titleLong, setTitleLong] = useState(false);
+    useTitleRun(ref, setTitleLong);
     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'));
@@ -120,5 +131,5 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
             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');
     };
-    return (_jsxs("article", { ref: ref, className: cx('card sheet', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', `sheet--${shown}`, className), inert: current === 'away' || held || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: cx('sheet__handle', mark === 'dots' && 'sheet__handle--dots'), type: "button", "aria-label": typeof handle === 'string' ? handle : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
+    return (_jsxs("article", { ref: ref, className: cx('card sheet', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', `sheet--${shown}`, className), inert: current === 'away' || held || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: cx('sheet__handle', mark === 'dots' && 'sheet__handle--dots'), type: "button", "aria-label": typeof handle === 'string' ? handle : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), Children.map(children, (node) => markLong(node, titleLong))] }));
 }

package/dist/sheets/SheetBody.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentProps } from 'react';
+import { type ComponentProps } from 'react';
 export interface SheetBodyProps extends ComponentProps<'div'> {
 }
 /** SheetBody — everything under a Sheet's head: the one thing that scrolls; its scroll padding keeps a focused control above the cut. Content never goes straight into the Sheet. */

package/dist/sheets/SheetBody.js

@@ -1,6 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from 'react';
 import { cx } from '../cx.js';
+import { StackPullCtx } from './stackCard.js';
 /** SheetBody — everything under a Sheet's head: the one thing that scrolls; its scroll padding keeps a focused control above the cut. Content never goes straight into the Sheet. */
 export function SheetBody({ className, ...rest }) {
-    return _jsx("div", { className: cx('sheet__body', className), ...rest });
+    const pulling = useContext(StackPullCtx);
+    return _jsx("div", { className: cx('sheet__body', pulling && 'is-refreshing', className), ...rest });
 }

package/dist/sheets/SheetHead.d.ts

@@ -8,6 +8,8 @@ export interface SheetHeadProps extends Omit<ComponentProps<'div'>, 'title'> {
     sub?: ReactNode;
     /** the round button on the right */
     trail?: ReactNode;
+    /** the sheet measured this title as wider than its line, so it runs sideways */
+    long?: boolean;
 }
 /** SheetHead — the stage sheet's three-column head: round button · centred title + sub · round button. A step sheet uses a CardHead instead. */
-export declare function SheetHead({ lead, title, sub, trail, className, ...rest }: SheetHeadProps): import("react").JSX.Element;
+export declare function SheetHead({ lead, title, sub, trail, long, className, ...rest }: SheetHeadProps): import("react").JSX.Element;

package/dist/sheets/SheetHead.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 /** SheetHead — the stage sheet's three-column head: round button · centred title + sub · round button. A step sheet uses a CardHead instead. */
-export function SheetHead({ lead, title, sub, trail, className, ...rest }) {
-    return (_jsxs("div", { className: cx('sheet__head', className), ...rest, children: [lead ?? _jsx("span", {}), _jsxs("div", { children: [_jsx("h2", { className: "sheet__title", children: title }), sub != null && _jsx("span", { className: "sheet__sub", children: sub })] }), trail ?? _jsx("span", {})] }));
+export function SheetHead({ lead, title, sub, trail, long, className, ...rest }) {
+    return (_jsxs("div", { className: cx('sheet__head', className), ...rest, children: [lead ?? _jsx("span", {}), _jsxs("div", { children: [_jsx("h2", { className: cx('sheet__title', long && 'is-long'), children: title }), sub != null && _jsx("span", { className: "sheet__sub", children: sub })] }), trail ?? _jsx("span", {})] }));
 }

package/dist/sheets/SheetStack.js

@@ -5,6 +5,7 @@ import { cx } from '../cx.js';
 import { Card } from '../cards/Card.js';
 import { StackSheet } from './StackSheet.js';
 const PHASE = 380; // ms before the before-pack un-tucks on close, so the after-pack is clear first
+const UNTUCK = 700; // the stagger stays for the return: the delay is read when is-before leaves, and a later render must not take it away mid-move
 const SHEET = new Set([Card, StackSheet]);
 /* one wrapper around a sheet is fine (a host's own box). The props land on the Card or StackSheet inside it, so the card renders them. */
 function stamp(child, place) {
@@ -40,6 +41,8 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
     const [current, request] = useControlled(open, defaultOpen, onOpenChange);
     const prev = useRef(current);
     const [closingFrom, setClosingFrom] = useState(null);
+    const back = useRef(null);
+    const [, tick] = useState(0);
     if (prev.current !== current) {
         const from = prev.current;
         prev.current = current;
@@ -54,6 +57,22 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
         const t = setTimeout(() => setClosingFrom(null), PHASE);
         return () => clearTimeout(t);
     }, [closingFrom]);
+    if (closingFrom != null)
+        back.current = { at: closingFrom, until: 0 };
+    else if (back.current && back.current.until === 0)
+        back.current = { at: back.current.at, until: performance.now() + UNTUCK };
+    const returning = closingFrom == null && back.current && performance.now() < back.current.until ? back.current.at : null;
+    useEffect(() => {
+        const held = back.current;
+        if (!held || held.until === 0)
+            return;
+        const t = setTimeout(() => {
+            if (back.current === held)
+                back.current = null;
+            tick((n) => n + 1);
+        }, Math.max(0, held.until - performance.now()));
+        return () => clearTimeout(t);
+    });
     const closing = current == null && closingFrom != null;
     const anchor = current ?? closingFrom;
     const items = Children.toArray(children);
@@ -68,7 +87,7 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
             refreshing: refreshing === i,
             before,
             after: !closing && current != null && i > current,
-            stagger: before && anchor != null ? anchor - 1 - i : 0,
+            stagger: before && anchor != null ? anchor - 1 - i : returning != null && i < returning ? returning - 1 - i : 0,
             onOpen: () => request(i),
             onClose: () => request(null),
             onRefresh: onRefresh ? () => onRefresh(i) : undefined,

package/dist/sheets/SheetSteps.js

@@ -11,9 +11,8 @@ import { usePile } from './sheetStepsPile.js';
 import { StepCursor } from './stepCursor.js';
 const MOVE_MS = 350; // = --motion-sheet: the accordion's beat
 const SWIPE_REM = 3; // an up/down move longer than this (and mostly up/down) is a swipe
-/* the open step's first field — the one that takes the cursor; NOW_INPUT: the one a typed character can be handed to */
+/* the open step's first field — the one that takes the cursor, and the one a typed character is handed to (an input or a textarea) */
 const NOW_FIELD = '.sheet-step--now .sheet-step__inner :is(input:not([type=checkbox], [type=radio], [type=hidden]), textarea)';
-const NOW_INPUT = '.sheet-step--now .sheet-step__inner input:not([type=checkbox], [type=radio], [type=hidden])';
 const coarse = () => typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches; // a phone: its keyboard follows a finger, not a script
 const StepCtx = createContext(null);
 /**
@@ -150,11 +149,12 @@ export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible
     const handOver = (e) => {
         const typed = e.currentTarget.value;
         e.currentTarget.value = '';
-        const field = ref.current?.querySelector(NOW_INPUT);
+        const field = ref.current?.querySelector(NOW_FIELD);
         if (!typed || !field)
             return;
         field.focus({ preventScroll: true });
-        Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set.call(field, field.value + typed);
+        const proto = field instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+        Object.getOwnPropertyDescriptor(proto, 'value').set.call(field, field.value + typed);
         field.dispatchEvent(new Event('input', { bubbles: true }));
     };
     return (_jsxs("div", { ref: ref, className: cx('sheet-steps', !reversible && 'sheet-steps--locked', className), style: style, onFocus: focusIn, onBlur: focusOut, onPointerDown: down, onPointerUp: up, onPointerCancel: (e) => { onPointerCancel?.(e); press.current = null; }, ...rest, children: [_jsx("input", { ref: holderRef, className: "sheet-steps__holder", "aria-hidden": true, tabIndex: -1, autoComplete: "off", onFocus: () => setParked(true), onBlur: () => setParked(false), onInput: handOver }), _jsx("ol", { className: "sheet-steps__track", children: steps.map((step, i) => (_jsx(StepCtx.Provider, { value: { numbered, i, at: current, furthest: reach, count, reversible, go, park, parked }, children: step }, step.key ?? i))) }), finish != null && ( // always in sight; it takes taps only once every step is done (or skipped)

package/dist/sheets/StackSheet.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { useControlled, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 import { Card } from '../cards/Card.js';
@@ -24,6 +24,7 @@ export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab,
     // a title longer than its room does not wrap: it runs sideways, like a song title in a short slot — the room it overflows by
     // is measured here (the tabs may grow with the text size) and handed to the CSS as --_over
     const titleRef = useRef(null);
+    const [long, setLong] = useState(false);
     useEffect(() => {
         const h = titleRef.current, run = h?.firstElementChild;
         if (!h || !run)
@@ -32,10 +33,10 @@ export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab,
             const over = Math.max(0, Math.ceil(run.scrollWidth - h.clientWidth));
             h.style.setProperty('--_over', `${over}px`);
             h.style.setProperty('--_run', `${(over / 30 + 3).toFixed(1)}s`);
-            h.classList.toggle('is-long', over > 0);
+            setLong(over > 0);
         };
         measure();
         return watchSize([h, run], measure);
     }, [title]);
-    return (_jsxs(Card, { stack: stack, tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [backAt === 'start' && _jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: "stack-sheet__title", children: _jsx("span", { className: "stack-sheet__run", children: title }) }), tabs?.length ? (_jsx("span", { className: "stack-sheet__tabs", role: "tablist", children: tabs.map((t) => (_jsxs(IconBtn, { sm: true, invert: t.id === tab, role: "tab", "aria-selected": t.id === tab, label: t.label, className: "stack-sheet__tab", onClick: () => pick(t.id), children: [_jsx(Icon, { name: t.icon }), t.count ? _jsx(Badge, { className: "stack-sheet__count", children: t.count > 99 ? '99+' : t.count }) : null] }, t.id))) })) : icon, backAt === 'end' && _jsx(StackBack, { end: true, label: backLabel })] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
+    return (_jsxs(Card, { stack: stack, tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [backAt === 'start' && _jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: cx('stack-sheet__title', long && 'is-long'), children: _jsx("span", { className: "stack-sheet__run", children: title }) }), tabs?.length ? (_jsx("span", { className: "stack-sheet__tabs", role: "tablist", children: tabs.map((t) => (_jsxs(IconBtn, { sm: true, invert: t.id === tab, role: "tab", "aria-selected": t.id === tab, label: t.label, className: "stack-sheet__tab", onClick: () => pick(t.id), children: [_jsx(Icon, { name: t.icon }), t.count ? _jsx(Badge, { className: "stack-sheet__count", children: t.count > 99 ? '99+' : t.count }) : null] }, t.id))) })) : icon, backAt === 'end' && _jsx(StackBack, { end: true, label: backLabel })] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
 }

package/dist/sheets/sheetMeasure.d.ts

@@ -5,6 +5,6 @@ type SheetRef = RefObject<HTMLElement | null>;
 export declare const slid: (el: HTMLElement) => number;
 export declare const stopsOf: (el: HTMLElement) => Record<Resting, number>;
 export declare function usePeekStrip(ref: SheetRef): void;
-export declare function useTitleRun(ref: SheetRef): void;
+export declare function useTitleRun(ref: SheetRef, onLong: (long: boolean) => void): void;
 export declare function useFootRoom(ref: SheetRef): void;
 export {};

package/dist/sheets/sheetMeasure.js

@@ -39,25 +39,30 @@ export function usePeekStrip(ref) {
     }, []);
 }
 /* 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. */
-export function useTitleRun(ref) {
+   words overflow the line and hands the widths to the CSS (--_over, --_run). The heading renders `.is-long` from what this
+   reports. Measured on the words themselves (a range), so the running indent never feeds back into the number. */
+export function useTitleRun(ref, onLong) {
     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;
+        let was = false;
         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 long = over > 0;
+            if (long !== was) {
+                was = long;
+                onLong(long);
+            }
         };
         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'); };
+        return () => { stop(); mo.disconnect(); 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

package/dist/sheets/stackCard.d.ts

@@ -9,7 +9,7 @@ export interface StackPlace {
     before: boolean;
     /** in front of the open sheet, leaving below */
     after: boolean;
-    /** nearest-first tuck, only while `before` */
+    /** nearest-first delay, while tucked and while those sheets return */
     stagger: number;
     onOpen: () => void;
     onClose: () => void;
@@ -17,7 +17,9 @@ export interface StackPlace {
 }
 /** the head's title is a tab stop while this sheet is the one Enter acts on: every title when none is open, only the open one otherwise */
 export declare const StackHeadCtx: import("react").Context<0 | -1 | null>;
-export declare function stackPaint(place: StackPlace | undefined): {
+/** a finger is pulling this card's content. The body renders `is-refreshing` from it */
+export declare const StackPullCtx: import("react").Context<boolean>;
+export declare function stackPaint(place: StackPlace | undefined, pulling?: boolean): {
     className?: string;
     style?: CSSProperties;
     busy?: true;
@@ -28,4 +30,4 @@ export declare function stackPaint(place: StackPlace | undefined): {
  */
 export declare function useStackCard(ref: RefObject<HTMLElement | null>, place: StackPlace | undefined, swallow: {
     current: boolean;
-}): void;
+}): boolean;

package/dist/sheets/stackCard.js

@@ -1,21 +1,23 @@
 /* one sheet of a tap stack — its own behaviour, not exported from the package.
    The app says which sheet is open and whether its data is in (`SheetStack`'s `open` and `refreshing`).
    This card renders what those two mean: the place classes, the grip, the pull. Nothing stamps them on afterwards. */
-import { createContext, useEffect, useLayoutEffect, useRef } from 'react';
+import { createContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { flushSync } from 'react-dom';
 import { focusWhenActive } from '../state.js';
 const SLOP_REM = 0.5;
 const COMMIT_REM = 4.5;
 /** the head's title is a tab stop while this sheet is the one Enter acts on: every title when none is open, only the open one otherwise */
 export const StackHeadCtx = createContext(null);
-export function stackPaint(place) {
+/** a finger is pulling this card's content. The body renders `is-refreshing` from it */
+export const StackPullCtx = createContext(false);
+export function stackPaint(place, pulling = false) {
     if (!place)
         return {};
     const loading = place.open && place.refreshing;
-    const className = ['stack-card', place.open && 'is-open', place.before && 'is-before', place.after && 'is-after', loading && 'is-loading'].filter(Boolean).join(' ');
+    const className = ['stack-card', place.open && 'is-open', place.before && 'is-before', place.after && 'is-after', loading && 'is-loading', pulling && 'is-refreshing'].filter(Boolean).join(' ');
     return {
         className,
-        style: place.before ? { '--stagger': String(place.stagger) } : undefined,
+        style: place.stagger > 0 ? { '--stagger': String(place.stagger) } : undefined,
         busy: loading || undefined,
     };
 }
@@ -49,6 +51,7 @@ export function useStackCard(ref, place, swallow) {
     const live = useRef(null);
     const headPull = useRef(null);
     const bodyPull = useRef(null);
+    const [pulling, setPulling] = useState(false);
     useLayoutEffect(() => {
         const el = ref.current;
         if (!el || !place)
@@ -191,6 +194,8 @@ export function useStackCard(ref, place, swallow) {
                         return;
                     }
                 }
+                if (!pull.moved)
+                    flushSync(() => setPulling(true));
                 pull.moved = true;
                 ev.preventDefault();
                 try {
@@ -198,12 +203,11 @@ export function useStackCard(ref, place, swallow) {
                         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 finish = () => {
-                scroller.classList.remove('is-refreshing');
                 scroller.style.removeProperty('--_refresh');
+                setPulling(false);
             };
             const onUp = (ev) => {
                 if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
@@ -258,12 +262,14 @@ export function useStackCard(ref, place, swallow) {
             stopDoc();
             headPull.current = null;
             bodyPull.current = null;
+            scroller.style.removeProperty('--_refresh');
+            setPulling(false);
             if (live.current?.prop === '--_pull')
                 release('--_pull');
             head?.removeEventListener('pointerdown', onHeadDown);
             scroller.removeEventListener('pointerdown', onBodyDown);
         };
-    }, [place?.open, place?.refreshing, !!place?.onRefresh, ref, swallow]);
+    }, [place?.open, !!place?.onRefresh, ref, swallow]);
     /* none open: a pull up on a peeked head follows the finger and, past the commit, opens this sheet */
     useEffect(() => {
         const card = ref.current;
@@ -386,4 +392,5 @@ export function useStackCard(ref, place, swallow) {
             head.removeEventListener('pointerdown', onDown);
         };
     }, [place?.open, place?.before, place?.after, ref, swallow]);
+    return pulling;
 }

package/dist/templates/Home.d.ts

@@ -49,7 +49,7 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
  * Home — TEMPLATE, a `Screen` with its parts filled — top: the AppBar · content: the `base` (title, welcome…) over a closed `SheetStack` · no bottom
  * (the stack is content, never the bottom: open, a sheet fills everything under the top).
  * Every section is a `StackSheet` of three parts: SHEET HEAD (title + icon tabs, a count over a tab; the back button once open) · SHEET BODY (scrolls) · SHEET FOOT (the CTA,
- * 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
+ * at the bottom). A tap on a head brings that sheet up to fill everything under the top. With a LayerHistory above and no `open` prop, that open sheet is one history entry named `home`. 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, onRefresh, refreshing, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;

package/dist/templates/Home.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { useControlled } from '../state.js';
+import { useOptionalLayer } from '../scaffold/LayerHistory.js';
 import { Screen } from '../scaffold/Screen.js';
 import { SheetStack } from '../sheets/SheetStack.js';
 import { StackSheet } from '../sheets/StackSheet.js';
@@ -12,20 +13,34 @@ const LEAVE = 800; // ms: a closing sheet keeps its body until it has slid home
  * Home — TEMPLATE, a `Screen` with its parts filled — top: the AppBar · content: the `base` (title, welcome…) over a closed `SheetStack` · no bottom
  * (the stack is content, never the bottom: open, a sheet fills everything under the top).
  * Every section is a `StackSheet` of three parts: SHEET HEAD (title + icon tabs, a count over a tab; the back button once open) · SHEET BODY (scrolls) · SHEET FOOT (the CTA,
- * 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
+ * at the bottom). A tap on a head brings that sheet up to fill everything under the top. With a LayerHistory above and no `open` prop, that open sheet is one history entry named `home`. 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, onRefresh, refreshing, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
-    const [open, change] = useControlled(openProp, defaultOpen, onOpenChange);
+    const layer = useOptionalLayer('home');
+    const [local, change] = useControlled(openProp, defaultOpen, onOpenChange);
+    // A passed `open` is the parent's. With no LayerHistory the index stays local, so a story without a router still opens sheets.
+    const shown = openProp !== undefined ? local : layer == null ? local : typeof layer.value === 'number' ? layer.value : null;
+    const request = (next) => {
+        if (openProp !== undefined || layer == null) {
+            change(next);
+            return;
+        }
+        onOpenChange?.(next);
+        if (next == null)
+            layer.close();
+        else
+            layer.open(next);
+    };
     const [leaving, setLeaving] = useState(null);
-    const [seen, setSeen] = useState(() => new Set(open != null ? [open] : []));
-    const [was, setWas] = useState(open);
-    if (was !== open) { // derived during render: which body must stay while its sheet slides home
-        if (was != null && open == null)
+    const [seen, setSeen] = useState(() => new Set(shown != null ? [shown] : []));
+    const [was, setWas] = useState(shown);
+    if (was !== shown) { // derived during render: which body must stay while its sheet slides home
+        if (was != null && shown == null)
             setLeaving(was);
-        if (open != null && !seen.has(open))
-            setSeen(new Set(seen).add(open));
-        setWas(open);
+        if (shown != null && !seen.has(shown))
+            setSeen(new Set(seen).add(shown));
+        setWas(shown);
     }
     useEffect(() => {
         if (leaving == null)
@@ -34,6 +49,6 @@ export function Home({ top, title, sheets, open: openProp, defaultOpen = null, o
         return () => clearTimeout(t);
     }, [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, onRefresh: onRefresh, refreshing: refreshing, 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] }));
+    const shows = (i) => i === shown || 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: shown, onOpenChange: request, onRefresh: onRefresh, refreshing: refreshing, 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.54",
+  "version": "0.7.55",
   "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.",