@usableapp/cardds 0.7.6 → 0.7.8

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 > 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.8 — 2026-09-25
+
+### Changed
+- `Pin error` (the app's answer, a refused OTP): before — the red digits stayed until the next one was typed. After — the Pin
+  shakes red, then EMPTIES itself (`onChange('', false)`), the cursor in the first cell, on the same step — as a `match` miss.
+  Give a new `error` value per refusal (a counter) so a second one shakes again.
+
+### Added
+- `WaitLink` — a Link that waits: `until` (ms time) → counts down ("ขอรหัสใหม่ได้ใน 0:27", `waiting={(t) => …}`), takes no
+  tap until then. The app owns the rule (30 s, +30 s per ask) and sets the next `until` in its onClick. `Link disabled`
+  (muted, knob `--link-disabled-ink`). Stories `WaitLink · Resend`, `SheetSteps · Errors` (ask for a new code).
+- `SheetSteps reached` — controlled progress: how many steps are done. Before: the steps remembered the furthest step reached,
+  so after the app sent `at` back (the server refused the code at the end) the later steps still showed ✓ and their summary.
+  After: `reached={1}` with `at={1}` → the steps after it are "next" again. Once set the app owns it — keep
+  `reached = max(reached, at)` beside `at`. Without it: as before. Story `SheetSteps · Reached` (timebank card 142).
+
+## 0.7.7 — 2026-09-25
+
+### Changed (breaking for a confirm PIN)
+- `Pin match` that does not match: before — red for 3 s, then the steps went back one on their own (`onAtChange(at - 1,
+  'mismatch')`). After — the step STAYS: the Pin shakes with red edges, the step shows `formatError`, then the Pin empties
+  itself (`onChange('', false)`) ready for a new try; the words go with the next digit. Going back is the member's choice:
+  put a `Link` under the Pin that sets `at` back (and clears both codes) — story `SheetSteps · Errors` ("ตั้ง PIN ใหม่").
+  The reason `'mismatch'` is gone from `SheetStepsReason` — drop its branch from `onAtChange`. Knobs `--pin-shake-x`, `--pin-shake-time`.
+- `SheetStep`: a tap on a `Link` in the step keeps the cursor in its field, like its buttons — before, the field lost the
+  focus, the pile scrolled back and the link's click was lost (a "change number" link under an OTP too).
+
+### Added
+- `Field mask` — `"###-###-####"`: `#` = a digit, anything else is written in for the member as they type (081-234-5678).
+  Only digits stay; a mark comes only once a digit follows it. `onChange` reads the shaped value.
+- `Field`: a placeholder longer than the box shrinks to show whole (measured in the input's font; the typed value keeps its size).
+
 ## 0.7.6 — 2026-09-24
 
 ### Changed

package/README.md

@@ -57,6 +57,14 @@ story live in a 375×812 phone cell, grouped by `src/<group>/`, searchable; swit
 it comes up over the phone cell and publishes `--kb` there — to SEE what a keyboard leaves of the screen; it
 types nothing), text size, and a slider per size base. Nothing is hand-listed: add a preview file or a story and it shows.
 
+**On a real phone** — the mock keyboard shows the room a keyboard takes; the REAL one (its kind by `inputMode`: `numeric` /
+`tel` = digits, `email`, `text`; its language is the member's own setting) only shows on a device. The gallery's server is
+open on the Wi-Fi (`server.host: true`): `npm run dev` prints a `Network:` address — open it on a phone on the same
+Wi-Fi. A project using cardds does the same in its own `vite.config` (`server: { host: true }`, or `vite --host`).
+The iOS Simulator's Safari shows the iOS keyboard too (⌘K if it hides); desktop device modes show none. Installing as a
+PWA needs https — a tunnel (`cloudflared tunnel --url http://localhost:<port>`), then Add to Home Screen. `host: true`
+lets anyone on the same network open the dev server: use it on a network you trust.
+
 `tests/fixtures/*.html` are the pages the geometry tests measure — not a demo. Nothing here is verified by eye.
 
 ### In another project

package/css/forms.css

@@ -28,7 +28,7 @@
   outline: none; /* the browser's ring drew a second box inside the field (Lh 2026-09-22) — the field itself tells focus */
   caret-color: currentColor;
 }
-.field input::placeholder { color: inherit; opacity: 0.55; }
+.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); }
 
@@ -72,6 +72,11 @@
    <p class="form-note form-note--busy" role="status"><svg …/>Sending the code…</p> (the ring turns) */
 .field.field--error, [data-palette] .field.field--error { border-color: var(--field-error-border, var(--signal-error)); }
 .pin.pin--error .pin__cell, .pin.pin--error .pin__cell:focus { border-color: var(--pin-error-border, var(--signal-error)); color: var(--pin-error-ink, var(--signal-error)); } /* ALL the cells, edge and digit — the one the cursor waits in too (Lh 2026-09-24); the wrong digits stay in red until the member types again */
+/* a code that does not match (Pin match): the row shakes once, sideways, then the Pin empties itself for a new try (Lh 2026-09-25) */
+@media (prefers-reduced-motion: no-preference) {
+  .pin--shake { animation: pin-shake var(--pin-shake-time, 0.4s) ease-in-out; }
+}
+@keyframes pin-shake { 0%, 100% { translate: 0; } 20%, 60% { translate: calc(-1 * var(--pin-shake-x, var(--sp-2))); } 40%, 80% { translate: var(--pin-shake-x, var(--sp-2)); } }
 .form-note { display: flex; align-items: center; justify-content: center; gap: var(--sp-2); margin: 0; font: var(--form-note-font, var(--type-caption)); color: var(--form-note-ink, var(--card-muted)); text-align: center; }
 .form-note > .icon { flex: none; }
 .form-note--error { color: var(--form-note-error-ink, var(--signal-error)); }

package/css/lists.css

@@ -206,4 +206,6 @@
 .link--sm { position: relative; font-size: var(--link-sm-font-size, var(--fs-2xs)); min-height: var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)); }
 .link--sm::after { content: ""; position: absolute; inset: calc((var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)) - var(--tap-sm)) / 2) 0; }
 .link--muted { color: var(--link-muted-ink, var(--card-muted)); }
+.link:disabled { color: var(--link-disabled-ink, var(--card-muted)); cursor: default; } /* inactive = muted (a WaitLink counting down) */
+.link--wait { font-variant-numeric: tabular-nums; } /* the countdown's digits keep their width: the words do not jiggle each second */
 .card--3 .link--muted { color: var(--card-3-muted); }

package/css/sheet.css

@@ -381,7 +381,7 @@
    falls — no height is written. Nothing fades: done and next read at full ink. */
 .sheet__body:has(> .sheet-steps) { display: flex; flex-direction: column; }
 .sheet-steps { flex-shrink: 0; min-height: calc(100% + var(--kb, 0rem)); /* the keyboard's height more: the pile of next steps stays under the keyboard, it never rises with it */ display: flex; flex-direction: column; touch-action: pan-y; }
-.sheet-steps__holder { position: absolute; top: 0; left: 0; width: 1px; height: 1px; padding: 0; border: 0; opacity: 0; pointer-events: none; font-size: 1rem; } /* holds the cursor (and the phone's keyboard) while a step folds; 1rem (16px at the browser's size) so iOS does not zoom to it */
+.sheet-steps__holder { position: absolute; top: 0; left: 0; width: 1rem; height: 1rem; padding: 0; border: 0; opacity: 0; pointer-events: none; font-size: 1rem; } /* holds the cursor (and the phone's keyboard) while a step folds; font 1rem = the browser's own size, so iOS does not zoom to it */
 .sheet-steps { position: relative; }
 .sheet-steps__track { list-style: none; margin: 0; padding: 0; flex: 1; display: flex; flex-direction: column; }
 
@@ -403,7 +403,7 @@
 .sheet-step__body { min-height: 0; overflow: clip; overflow-clip-margin: var(--sp-1); }
 .sheet-step__inner { display: grid; gap: var(--card-gap); padding-bottom: var(--card-gap); }
 .sheet-step__inner > * { min-width: 0; }
-.sheet-step__skip { justify-self: center; }
+.sheet-step__inner > .link { justify-self: center; } /* a link of its own row in a step (skip, "change number", "set PIN again"): centred under the step, as the skip (Lh 2026-09-25) */
 .sheet-step:not(.sheet-step--now) > .sheet-step__body { visibility: hidden; transition: visibility 0s linear var(--motion-sheet); }
 .sheet-step__go { position: absolute; inset: 0; margin: 0; padding: 0; border: 0; background: none; cursor: pointer; -webkit-tap-highlight-color: transparent; }
 /* the last step's finish, when the app gives one: under the steps */

package/dist/actions/Link.d.ts

@@ -9,9 +9,13 @@ export interface LinkProps extends ComponentProps<'a'> {
     sm?: boolean;
     /** without an href it renders as a button */
     href?: string;
+    /** a button link that takes no taps now (reads inactive: muted) — `WaitLink` while it counts down */
+    disabled?: boolean;
 }
 /** Link — an inline text action big enough to tap (40px): "See all ↗" in a card head, "Skip" between pager buttons. */
 export declare function Link({ muted, sm, icon, href, className, children, ...rest }: LinkProps): import("react").DetailedReactHTMLElement<{
+    /** a button link that takes no taps now (reads inactive: muted) — `WaitLink` while it counts down */
+    disabled?: boolean;
     ref?: import("react").Ref<HTMLAnchorElement> | undefined;
     key?: import("react").Key | null | undefined;
     download?: any;

package/dist/actions/WaitLink.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+import { type LinkProps } from './Link.js';
+export interface WaitLinkProps extends Omit<LinkProps, 'href'> {
+    /** CONTROLLED: when it may be pressed again (a time in ms, `Date.now()` based). Before that it counts down and takes no taps;
+     *  null / past = ready. The APP owns the rule — 30 s, +30 s each time — and sets a new `until` in its onClick. */
+    until?: number | null;
+    /** the words while it waits, given the time left as "0:27" (default: the children, then the time) */
+    waiting?: (left: string) => ReactNode;
+}
+/**
+ * WaitLink — a Link that waits: "ขอรหัสใหม่ได้ใน 0:27", counting down each second, then "ขอรหัสใหม่" to press (a new OTP, a retry).
+ * A link, not a button: it is the step's second way, under its control; in a SheetStep it stands centred on its own row.
+ */
+export declare function WaitLink({ until, waiting, children, className, disabled, ...rest }: WaitLinkProps): import("react").JSX.Element;

package/dist/actions/WaitLink.js

@@ -0,0 +1,22 @@
+import { Fragment as _Fragment, jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { cx } from '../cx.js';
+import { Link } from './Link.js';
+/**
+ * WaitLink — a Link that waits: "ขอรหัสใหม่ได้ใน 0:27", counting down each second, then "ขอรหัสใหม่" to press (a new OTP, a retry).
+ * A link, not a button: it is the step's second way, under its control; in a SheetStep it stands centred on its own row.
+ */
+export function WaitLink({ until, waiting, children, className, disabled, ...rest }) {
+    const [now, setNow] = useState(() => Date.now());
+    const left = until != null ? Math.ceil((until - now) / 1000) : 0;
+    useEffect(() => {
+        if (until == null || until <= Date.now())
+            return;
+        setNow(Date.now());
+        const t = setInterval(() => { setNow(Date.now()); if (Date.now() >= until)
+            clearInterval(t); }, 250);
+        return () => clearInterval(t);
+    }, [until]);
+    const time = `${Math.floor(Math.max(left, 0) / 60)}:${String(Math.max(left, 0) % 60).padStart(2, '0')}`;
+    return (_jsx(Link, { className: cx('link--wait', className), disabled: left > 0 || disabled, ...rest, children: left > 0 ? (waiting ? waiting(time) : _jsxs(_Fragment, { children: [children, " ", time] })) : children }));
+}

package/dist/cardds.css

@@ -1558,7 +1558,7 @@ button { font: inherit; cursor: pointer; }
    falls — no height is written. Nothing fades: done and next read at full ink. */
 .sheet__body:has(> .sheet-steps) { display: flex; flex-direction: column; }
 .sheet-steps { flex-shrink: 0; min-height: calc(100% + var(--kb, 0rem)); /* the keyboard's height more: the pile of next steps stays under the keyboard, it never rises with it */ display: flex; flex-direction: column; touch-action: pan-y; }
-.sheet-steps__holder { position: absolute; top: 0; left: 0; width: 1px; height: 1px; padding: 0; border: 0; opacity: 0; pointer-events: none; font-size: 1rem; } /* holds the cursor (and the phone's keyboard) while a step folds; 1rem (16px at the browser's size) so iOS does not zoom to it */
+.sheet-steps__holder { position: absolute; top: 0; left: 0; width: 1rem; height: 1rem; padding: 0; border: 0; opacity: 0; pointer-events: none; font-size: 1rem; } /* holds the cursor (and the phone's keyboard) while a step folds; font 1rem = the browser's own size, so iOS does not zoom to it */
 .sheet-steps { position: relative; }
 .sheet-steps__track { list-style: none; margin: 0; padding: 0; flex: 1; display: flex; flex-direction: column; }
 
@@ -1580,7 +1580,7 @@ button { font: inherit; cursor: pointer; }
 .sheet-step__body { min-height: 0; overflow: clip; overflow-clip-margin: var(--sp-1); }
 .sheet-step__inner { display: grid; gap: var(--card-gap); padding-bottom: var(--card-gap); }
 .sheet-step__inner > * { min-width: 0; }
-.sheet-step__skip { justify-self: center; }
+.sheet-step__inner > .link { justify-self: center; } /* a link of its own row in a step (skip, "change number", "set PIN again"): centred under the step, as the skip (Lh 2026-09-25) */
 .sheet-step:not(.sheet-step--now) > .sheet-step__body { visibility: hidden; transition: visibility 0s linear var(--motion-sheet); }
 .sheet-step__go { position: absolute; inset: 0; margin: 0; padding: 0; border: 0; background: none; cursor: pointer; -webkit-tap-highlight-color: transparent; }
 /* the last step's finish, when the app gives one: under the steps */
@@ -1785,7 +1785,7 @@ button { font: inherit; cursor: pointer; }
   outline: none; /* the browser's ring drew a second box inside the field (Lh 2026-09-22) — the field itself tells focus */
   caret-color: currentColor;
 }
-.field input::placeholder { color: inherit; opacity: 0.55; }
+.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); }
 
@@ -1829,6 +1829,11 @@ button { font: inherit; cursor: pointer; }
    <p class="form-note form-note--busy" role="status"><svg …/>Sending the code…</p> (the ring turns) */
 .field.field--error, [data-palette] .field.field--error { border-color: var(--field-error-border, var(--signal-error)); }
 .pin.pin--error .pin__cell, .pin.pin--error .pin__cell:focus { border-color: var(--pin-error-border, var(--signal-error)); color: var(--pin-error-ink, var(--signal-error)); } /* ALL the cells, edge and digit — the one the cursor waits in too (Lh 2026-09-24); the wrong digits stay in red until the member types again */
+/* a code that does not match (Pin match): the row shakes once, sideways, then the Pin empties itself for a new try (Lh 2026-09-25) */
+@media (prefers-reduced-motion: no-preference) {
+  .pin--shake { animation: pin-shake var(--pin-shake-time, 0.4s) ease-in-out; }
+}
+@keyframes pin-shake { 0%, 100% { translate: 0; } 20%, 60% { translate: calc(-1 * var(--pin-shake-x, var(--sp-2))); } 40%, 80% { translate: var(--pin-shake-x, var(--sp-2)); } }
 .form-note { display: flex; align-items: center; justify-content: center; gap: var(--sp-2); margin: 0; font: var(--form-note-font, var(--type-caption)); color: var(--form-note-ink, var(--card-muted)); text-align: center; }
 .form-note > .icon { flex: none; }
 .form-note--error { color: var(--form-note-error-ink, var(--signal-error)); }
@@ -3118,6 +3123,8 @@ button { font: inherit; cursor: pointer; }
 .link--sm { position: relative; font-size: var(--link-sm-font-size, var(--fs-2xs)); min-height: var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)); }
 .link--sm::after { content: ""; position: absolute; inset: calc((var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)) - var(--tap-sm)) / 2) 0; }
 .link--muted { color: var(--link-muted-ink, var(--card-muted)); }
+.link:disabled { color: var(--link-disabled-ink, var(--card-muted)); cursor: default; } /* inactive = muted (a WaitLink counting down) */
+.link--wait { font-variant-numeric: tabular-nums; } /* the countdown's digits keep their width: the words do not jiggle each second */
 .card--3 .link--muted { color: var(--card-3-muted); }
 
 /* ---- css/media.css — cover card, quote, tile grid, fold, mosaic, wave ---- */

package/dist/forms/Field.d.ts

@@ -20,11 +20,17 @@ export interface FieldProps extends Omit<ComponentProps<'input'>, 'className' |
     /** the words when the format check fails — shown under the step's button (the app's words: cardds has none). `required`
      *  (the attribute) makes an empty field fail when the button is pressed. */
     formatError?: ReactNode;
+    /** the shape the digits are written in, AS THE MEMBER TYPES: `#` = one digit, anything else is put in for them ("###-###-####"
+     *  → 081-234-5678). Only digits are kept; a mark comes only once a digit follows it, so Backspace never sticks on a dash. The
+     *  app's `onChange` reads the shaped value (the digits alone: `value.replace(/\D/g, '')`). Lh 2026-09-25 */
+    mask?: string;
     className?: string;
     style?: React.CSSProperties;
 }
+/** the digits of `v`, written into `mask`; a mark is written only when a digit comes after it */
+export declare function applyMask(v: string, mask: string): string;
 /**
  * Field — the flat outlined input: the LABEL IS THE PLACEHOLDER. 48px tall (56px with an action inside).
  * Fields belong in a Sheet (what the member acts on), 1–3 per step, never in a reading card.
  */
-export declare function Field({ icon, action, label, error, format, digits, formatError, className, style, onBlur, onInput, ...input }: FieldProps): import("react").JSX.Element;
+export declare function Field({ icon, action, label, error, format, digits, formatError, mask, className, style, onBlur, onInput, onChange, ...input }: FieldProps): import("react").JSX.Element;

package/dist/forms/Field.js

@@ -1,13 +1,27 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { formatOk, useCheck } from './check.js';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
+/** the digits of `v`, written into `mask`; a mark is written only when a digit comes after it */
+export function applyMask(v, mask) {
+    const d = v.replace(/\D/g, '');
+    let out = '', k = 0;
+    for (const m of mask) {
+        if (k >= d.length)
+            break;
+        if (m === '#')
+            out += d[k++];
+        else
+            out += m;
+    }
+    return out;
+}
 /**
  * Field — the flat outlined input: the LABEL IS THE PLACEHOLDER. 48px tall (56px with an action inside).
  * Fields belong in a Sheet (what the member acts on), 1–3 per step, never in a reading card.
  */
-export function Field({ icon, action, label, error, format, digits, formatError, className, style, onBlur, onInput, ...input }) {
+export function Field({ icon, action, label, error, format, digits, formatError, mask, className, style, onBlur, onInput, onChange, ...input }) {
     const ref = useRef(null);
     const [bad, setBad] = useState(false); // the format check failed, and has not been fixed since
     const wrong = (error != null && error !== false && error !== '') || bad;
@@ -21,6 +35,35 @@ export function Field({ icon, action, label, error, format, digits, formatError,
     };
     const { say } = useCheck((strict) => { const w = verdict(strict); if (w != null)
         setBad(true); return w; }, () => { ref.current?.focus(); ref.current?.select(); });
+    /* a placeholder longer than the box SHRINKS to show whole (Lh 2026-09-25): its width is measured in the input's own font,
+       and `--_ph-fit` (the share that fits, ≤ 1) scales the placeholder's size — again whenever the box or the font changes */
+    useLayoutEffect(() => {
+        const el = ref.current, text = input.placeholder;
+        if (!el)
+            return;
+        if (!text) {
+            el.style.removeProperty('--_ph-fit');
+            return;
+        }
+        const ctx = document.createElement('canvas').getContext('2d');
+        const fit = () => {
+            if (!ctx)
+                return;
+            const cs = getComputedStyle(el);
+            ctx.font = cs.font;
+            const room = el.clientWidth - parseFloat(cs.paddingLeft) - parseFloat(cs.paddingRight), need = ctx.measureText(text).width;
+            const share = need > room && room > 0 ? Math.floor((room / need) * 1000) / 1000 : 1;
+            if (share < 1)
+                el.style.setProperty('--_ph-fit', String(share));
+            else
+                el.style.removeProperty('--_ph-fit');
+        };
+        fit();
+        const ro = new ResizeObserver(fit);
+        ro.observe(el);
+        document.fonts?.ready.then(fit);
+        return () => ro.disconnect();
+    }, [input.placeholder]);
     useEffect(() => {
         if (wrong) {
             ref.current?.focus();
@@ -29,7 +72,21 @@ export function Field({ icon, action, label, error, format, digits, formatError,
         // eslint-disable-next-line react-hooks/exhaustive-deps -- when the app's error comes or changes
     }, [error]);
     return (_jsxs("label", { className: cx('field', action != null && 'field--action', wrong && 'field--error', className), style: style, children: [icon && _jsx(Icon, { name: icon, size: "sm" }), _jsx("input", { ref: ref, "aria-label": label, "aria-invalid": wrong || undefined, ...input, onBlur: (e) => { onBlur?.(e); if (!checked)
-                    return; const w = verdict(false); setBad(w != null); say(w); }, onInput: (e) => { onInput?.(e); if (bad && verdict(false) == null) {
+                    return; const w = verdict(false); setBad(w != null); say(w); }, onChange: (e) => {
+                    if (mask) {
+                        const el = e.currentTarget, before = el.value.slice(0, el.selectionStart ?? el.value.length).replace(/\D/g, '').length;
+                        const shaped = applyMask(el.value, mask);
+                        if (shaped !== el.value) {
+                            el.value = shaped;
+                            let at = 0;
+                            for (let n = 0; at < shaped.length && n < before; at++)
+                                if (/\d/.test(shaped[at]))
+                                    n++; // the caret stays after the same digit
+                            el.setSelectionRange(at, at);
+                        }
+                    }
+                    onChange?.(e);
+                }, onInput: (e) => { onInput?.(e); if (bad && verdict(false) == null) {
                     setBad(false);
                     say(null);
                 } } }), action] }));

package/dist/forms/Pin.d.ts

@@ -10,12 +10,15 @@ export interface PinProps extends Omit<ComponentProps<'div'>, 'onChange' | 'defa
     label?: string;
     /** the code so far, after every change; `complete` once every cell holds a digit */
     onChange?: (code: string, complete: boolean) => void;
-    /** the code is wrong: the digits stay in sight in `--signal-error` (words, no fill) with red edges, the cursor goes back to the
-     *  first cell, and the next digit typed starts a new code. The words are the step's (`SheetStep error`). */
+    /** the code is wrong (the app's answer — an OTP the server refused): the Pin SHAKES with red edges and its digits in sight,
+     *  then empties itself (`onChange('', false)`) and the cursor waits in the first cell for a new try — the same as a `match`
+     *  miss (Lh 2026-09-25; the red digits used to stay until the next one was typed). Give a NEW value for each refusal (a
+     *  counter) so a second one shakes again. The words are the step's (`SheetStep error`): the app keeps them until it clears `error`. */
     error?: unknown;
     /** a FORMAT check on the client: the code it must equal (the first PIN, when this one confirms it). Once every cell is filled
-     *  and it differs, the Pin turns red with its digits in sight, the step shows `formatError` under it for three seconds and then
-     *  steps BACK one step (`onAtChange(at - 1, 'mismatch')` — the app clears both codes there). */
+     *  and it differs, the Pin SHAKES with red edges and its digits in sight, the step shows `formatError` under it, then the Pin
+     *  empties itself (`onChange('', false)`), ready for a new try — it stays on its step. Going back to set the first code again
+     *  is the member's choice: the app puts a `Link` under it (Lh 2026-09-25; it used to step back on its own after 3 s). */
     match?: string;
     /** the words when a check fails: the code does not match, or the step's button was pressed with cells still empty */
     formatError?: ReactNode;
@@ -28,4 +31,4 @@ export interface PinProps extends Omit<ComponentProps<'div'>, 'onChange' | 'defa
  * arrows walk the cells, a pasted code fills them from the one it landed in; only digits stay. The first cell takes the SMS
  * one-time-code autofill. The code is a VALUE, controlled like an input: `value` + `onChange`, or `defaultValue`.
  */
-export declare function Pin({ length, value, defaultValue, label, onChange, autoFocus, error, match, formatError, className, ...rest }: PinProps): import("react").JSX.Element;
+export declare function Pin({ length, value, defaultValue, label, onChange, autoFocus, error, match, formatError, className, onAnimationEnd, ...rest }: PinProps): import("react").JSX.Element;

package/dist/forms/Pin.js

@@ -2,28 +2,49 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
 import { useCheck } from './check.js';
+const RESET_MS = 900; // a code that does not match: red + shake this long, then the cells empty for a new try
 /**
  * Pin — big code entry, one digit per pill; a filled cell turns accent. Lives in a Sheet.
  * Its own behaviour, inside it: typing a digit moves to the next cell, Backspace in an empty cell moves back and clears, the
  * arrows walk the cells, a pasted code fills them from the one it landed in; only digits stay. The first cell takes the SMS
  * one-time-code autofill. The code is a VALUE, controlled like an input: `value` + `onChange`, or `defaultValue`.
  */
-export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onChange, autoFocus, error, match, formatError, className, ...rest }) {
+export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onChange, autoFocus, error, match, formatError, className, onAnimationEnd, ...rest }) {
     const ref = useRef(null);
     const [inner, setInner] = useState(defaultValue);
     const code = (value ?? inner).replace(/\D/g, '').slice(0, length);
     const cell = (i) => ref.current?.querySelectorAll('.pin__cell')[i];
+    /* a miss — a match that failed, or the app's error: shake, red, then the cells empty for a new try on the same step */
+    const latest = useRef({ value, onChange, error });
+    latest.current = { value, onChange, error };
+    const miss = () => {
+        restart.current = true;
+        setShake(true);
+        clearTimeout(reset.current);
+        reset.current = setTimeout(() => {
+            setBad(false);
+            setCleared(latest.current.error);
+            restart.current = false;
+            if (latest.current.value === undefined)
+                setInner('');
+            latest.current.onChange?.('', false);
+            cell(0)?.focus();
+        }, RESET_MS);
+    };
     const set = (next) => {
         next = next.slice(0, length);
-        if (bad) {
+        if (bad || said.current) {
             setBad(false);
             say(null);
+            said.current = false;
         }
+        clearTimeout(reset.current);
+        setCleared(error); // typed before the cells emptied: the new try has begun, the red goes
         if (match != null && next.length === length && next !== match) {
             setBad(true);
             say(words);
-            back();
-            restart.current = true;
+            said.current = true;
+            miss();
         }
         if (value === undefined)
             setInner(next);
@@ -36,8 +57,12 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
         // eslint-disable-next-line react-hooks/exhaustive-deps -- on mount only
     }, [autoFocus]);
     const [bad, setBad] = useState(false); // a format check failed, and nothing was typed since
+    const [shake, setShake] = useState(false); // plays once per miss; off again at its animationend
+    const said = useRef(false); // the mismatch words are still shown (the cells were emptied, the words wait for the next digit)
+    const reset = useRef(undefined);
+    useEffect(() => () => clearTimeout(reset.current), []);
     const words = formatError ?? '';
-    const { say, back } = useCheck((strict) => {
+    const { say } = useCheck((strict) => {
         if (strict && code.length < length) {
             setBad(true);
             return words;
@@ -48,15 +73,21 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
         }
         return null;
     }, () => cell(Math.min(code.length, length - 1))?.focus());
-    const wrong = (error != null && error !== false && error !== '') || bad;
+    const errOn = error != null && error !== false && error !== '';
+    const [cleared, setCleared] = useState(undefined); // the app's error whose miss has played out (its cells emptied)
+    const wrong = (errOn && error !== cleared) || bad;
     const restart = useRef(false);
     useEffect(() => {
-        if (!wrong)
+        if (!errOn) {
+            setCleared(undefined);
+            return;
+        }
+        if (error === cleared)
             return;
-        restart.current = true; // the wrong code stays in sight (red); the next digit typed starts a new one from the first cell
         cell(0)?.focus();
+        miss(); // each new error, once
         // eslint-disable-next-line react-hooks/exhaustive-deps -- each new error, once
-    }, [wrong, error]);
+    }, [error]);
     /* the app emptied the code (a new try: it went back after a mismatch): the red goes with it */
     useEffect(() => {
         if (code || !bad)
@@ -68,14 +99,18 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
     }, [code]);
     const input = (i) => (e) => {
         const digits = e.target.value.replace(/\D/g, '');
-        if (restart.current) {
+        if (restart.current) { // a new try after a wrong code: what arrives starts a new code from the first cell
             restart.current = false;
-            if (digits) {
-                set(digits.slice(-1));
-                cell(1)?.focus();
-            }
+            if (!digits)
+                return;
+            const old = code[i] ?? '';
+            // the cell still held its red digit (not selected, so it stays visible): what came in is the value minus that digit — one
+            // typed digit, or a whole pasted / SMS-autofilled code (then it fills every cell, never just the last digit: timebank 142)
+            const fresh = digits.length >= length ? digits.slice(-length) : old && digits.length > 1 && digits.startsWith(old) ? digits.slice(old.length) : old && digits.length > 1 && digits.endsWith(old) ? digits.slice(0, -old.length) : digits;
+            set(fresh);
+            cell(Math.min(fresh.length, length - 1))?.focus();
             return;
-        } // a new try
+        }
         const at = Math.min(i, code.length); // a code has no gaps: a digit typed further along lands in the first empty cell
         if (!digits) {
             set(code.slice(0, at) + code.slice(at + 1));
@@ -84,6 +119,18 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
         set(code.slice(0, at) + digits + code.slice(at + digits.length)); // a paste (or a typed run) spills over the cells that follow
         cell(Math.min(at + digits.length, length - 1))?.focus();
     };
+    /* a paste after a wrong code: the clipboard's digits ARE the new code — read them straight, whatever the cell held */
+    const paste = (e) => {
+        if (!restart.current)
+            return; // otherwise the change handler spills it over the cells as always
+        const digits = e.clipboardData.getData('text').replace(/\D/g, '').slice(0, length);
+        if (!digits)
+            return;
+        e.preventDefault();
+        restart.current = false;
+        set(digits);
+        cell(Math.min(digits.length, length - 1))?.focus();
+    };
     const key = (i) => (e) => {
         if (e.key === 'Backspace' && !e.currentTarget.value && i > 0) {
             e.preventDefault();
@@ -99,9 +146,10 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
             cell(i + 1)?.focus();
         }
     };
-    return (_jsx("div", { ref: ref, className: cx('pin', wrong && 'pin--error', className), ...rest, children: Array.from({ length }, (_, i) => (
+    return (_jsx("div", { ref: ref, className: cx('pin', wrong && 'pin--error', shake && 'pin--shake', className), ...rest, onAnimationEnd: (e) => { if (e.animationName === 'pin-shake')
+            setShake(false); onAnimationEnd?.(e); }, children: Array.from({ length }, (_, i) => (
         // no maxLength: the browser would cut a pasted code before this ever saw it. A cell holds one digit — typing into a full one
         // replaces it, so its digit is selected whenever the cell takes the focus
-        _jsx("input", { className: "pin__cell", inputMode: "numeric", pattern: "[0-9]*", placeholder: " ", value: code[i] ?? '', "aria-label": `${label} ${i + 1}`, "aria-invalid": wrong || undefined, autoComplete: i === 0 ? 'one-time-code' : 'off', onChange: input(i), onKeyDown: key(i), onFocus: (e) => { if (!restart.current)
+        _jsx("input", { className: "pin__cell", inputMode: "numeric", pattern: "[0-9]*", placeholder: " ", value: code[i] ?? '', "aria-label": `${label} ${i + 1}`, "aria-invalid": wrong || undefined, autoComplete: i === 0 ? 'one-time-code' : 'off', onChange: input(i), onPaste: paste, onKeyDown: key(i), onFocus: (e) => { if (!restart.current)
                 e.currentTarget.select(); } }, i))) }));
 }

package/dist/forms/check.d.ts

@@ -9,15 +9,11 @@ export type CheckGroup = {
     add: (c: Check) => () => void;
     /** a control's own verdict changed (it was left, or it was fixed): its words, or null */
     say: (c: Check, words: ReactNode | null) => void;
-    /** a check that can only be failed by going back (the second PIN does not match the first): the group shows the words for a
-     *  moment, then steps back */
-    back: () => void;
 };
 export declare const CheckContext: import("react").Context<CheckGroup | null>;
 /** join the group around (if any) with this control's check; the latest check function is always the one asked */
 export declare function useCheck(check: Check['check'], focus: Check['focus']): {
     say: (words: ReactNode | null) => void | undefined;
-    back: () => void | undefined;
 };
 /** a Field's format: `email`, `tel` (digits, spaces, - + ( ) only) and/or an exact count of `digits` */
 export declare function formatOk(value: string, format?: 'email' | 'tel', digits?: number): boolean;

package/dist/forms/check.js

@@ -8,7 +8,7 @@ export function useCheck(check, focus) {
     latest.current.focus = focus;
     const self = useRef({ check: (s) => latest.current.check(s), focus: () => latest.current.focus() }).current;
     useEffect(() => group?.add(self), [group, self]);
-    return { say: (words) => group?.say(self, words), back: () => group?.back() };
+    return { say: (words) => group?.say(self, words) };
 }
 const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 /** a Field's format: `email`, `tel` (digits, spaces, - + ( ) only) and/or an exact count of `digits` */

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export * from './actions/Segment.js';
 export * from './actions/Fab.js';
 export * from './actions/BtnRow.js';
 export * from './actions/Link.js';
+export * from './actions/WaitLink.js';
 export * from './forms/Field.js';
 export * from './forms/FileBtn.js';
 export * from './forms/AddRow.js';

package/dist/index.js

@@ -42,6 +42,7 @@ export * from './actions/Segment.js';
 export * from './actions/Fab.js';
 export * from './actions/BtnRow.js';
 export * from './actions/Link.js';
+export * from './actions/WaitLink.js';
 export * from './forms/Field.js';
 export * from './forms/FileBtn.js';
 export * from './forms/AddRow.js';

package/dist/sheets/SheetSteps.d.ts

@@ -1,7 +1,6 @@
 import type { ComponentProps, ReactNode } from 'react';
-/** what asked for the move: a `tap` on another step, a `swipe` across the steps, the step's `skip` link, a `mismatch` (a Pin's
- *  `match` failed: back one step — clear the codes there) */
-export type SheetStepsReason = 'tap' | 'swipe' | 'skip' | 'mismatch';
+/** what asked for the move: a `tap` on another step, a `swipe` across the steps, the step's `skip` link */
+export type SheetStepsReason = 'tap' | 'swipe' | 'skip';
 export interface SheetStepsProps extends ComponentProps<'div'> {
     /** optional: a `Btn` that finishes, under the steps — always in sight, `disabled` until EVERY step is done (its work, or
      *  skipped: `at` has reached `count`). None = the task ends when `at` reaches `count` — the last step's own action, or its skip. */
@@ -10,6 +9,12 @@ export interface SheetStepsProps extends ComponentProps<'div'> {
      *  work is really finished (the code checked by the server, the two PINs match), `setAt(at + 1)`; after the last step the app sends. `at = count` = every step done —
      *  the app then closes its Sheet (`state="away"`, a beat after the fold) and says so on the page: the steps never close it themselves. */
     at?: number;
+    /** CONTROLLED progress: how many steps are DONE (0-based: the steps before this one show ✓). Without it the steps remember the
+     *  furthest step reached — a step once passed stays done when `at` goes back. Set it when that progress is GONE: the server
+     *  refused the code at the end, the app sends `at` back to the code step and clears the PINs → `reached={1}`, and the steps
+     *  after it are "next" again, no ✓, no summary. Once set, the APP owns it: raise it as the member goes on (keep
+     *  `reached = max(reached, at)` beside `at`), or a tap back in a `reversible` walk forgets what is after. Read as at least `at`. Lh 2026-09-25 */
+    reached?: number;
     /** UNCONTROLLED: the step it starts on (default 0) */
     defaultAt?: number;
     /** the steps ASK to move — a tap on another step, a swipe, a skip. Controlled: set `at` to it (or don't). */
@@ -25,7 +30,7 @@ export interface SheetStepsProps extends ComponentProps<'div'> {
  * steps on the last one. Goes in a `SheetBody`.
  * The sheet may be dragged down to peek and back — the body keeps where it was scrolled.
  */
-export declare function SheetSteps({ at, defaultAt, onAtChange, reversible, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }: SheetStepsProps): import("react").JSX.Element;
+export declare function SheetSteps({ at, reached, defaultAt, onAtChange, reversible, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }: SheetStepsProps): import("react").JSX.Element;
 export interface SheetStepProps extends Omit<ComponentProps<'li'>, 'title'> {
     /** the step's name — always shown: over the open step, on the folded line of a done one */
     title: ReactNode;

package/dist/sheets/SheetSteps.js

@@ -5,7 +5,6 @@ import { Icon } from '../type/Icon.js';
 import { Link } from '../actions/Link.js';
 import { FormNote } from '../forms/FormNote.js';
 import { CheckContext } from '../forms/check.js';
-const BACK_MS = 3000; // a PIN that does not match: its red digits and words stay this long, then the step goes back
 const MOVE_MS = 350; // = --motion-sheet: the accordion's beat
 const GLIDE_MS = 220; // the pile's slide out of the keyboard's way and back: quick, but the eye follows it
 const SWIPE_REM = 3; // an up/down move longer than this (and mostly up/down) is a swipe
@@ -17,7 +16,7 @@ const StepCtx = createContext(null);
  * steps on the last one. Goes in a `SheetBody`.
  * The sheet may be dragged down to peek and back — the body keeps where it was scrolled.
  */
-export function SheetSteps({ at, defaultAt = 0, onAtChange, reversible = false, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }) {
+export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible = false, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }) {
     const [inner, setInner] = useState(defaultAt);
     const current = at ?? inner;
     const steps = Children.toArray(children).filter(isValidElement);
@@ -26,7 +25,9 @@ export function SheetSteps({ at, defaultAt = 0, onAtChange, reversible = false,
     const [furthest, setFurthest] = useState(current);
     if (current > furthest)
         setFurthest(current);
-    const reach = Math.max(furthest, current);
+    if (reached != null && furthest !== Math.max(reached, current))
+        setFurthest(Math.max(reached, current)); // the app's word wins, and is remembered from there
+    const reach = reached != null ? Math.max(reached, current) : Math.max(furthest, current);
     const ref = useRef(null);
     const first = useRef(true);
     const holderRef = useRef(null);
@@ -197,9 +198,7 @@ export function SheetStep({ title, summary, skippable, skipLabel = 'Skip', error
     const off = phase !== 'now';
     /* the step is the FORM GROUP of the format checks inside it (Field format/digits/required, Pin match): the words of the first
        control that fails show under the button; a press on a button of the step checks them all first and holds the press back
-       when one fails (the app's onClick never hears it); a Pin that does not match shows its words for three seconds, then steps back */
-    const goRef = useRef(go);
-    goRef.current = go;
+       when one fails (the app's onClick never hears it); a Pin that does not match shakes, shows its words and empties itself — the step stays */
     const [note, setNote] = useState(null);
     const checks = useRef(new Map());
     const first = () => { for (const w of checks.current.values())
@@ -208,18 +207,17 @@ export function SheetStep({ title, summary, skippable, skipLabel = 'Skip', error
     const group = useMemo(() => ({
         add: (c) => { checks.current.set(c, null); return () => { checks.current.delete(c); setNote(first()); }; },
         say: (c, w) => { checks.current.set(c, w); setNote(first()); },
-        back: () => setTimeout(() => goRef.current(i - 1, 'mismatch'), BACK_MS),
-    }), [i]);
+    }), []);
     useEffect(() => { if (off) {
         for (const c of checks.current.keys())
             checks.current.set(c, null);
         setNote(null);
     } }, [off]);
-    /* a press on the step's button keeps the cursor where it is: the button still clicks, but the field keeps the focus, so a
+    /* a press on the step's button or link keeps the cursor where it is: the button still clicks, but the field keeps the focus, so a
        phone's keyboard does not drop and come back (the pile jumped up and down with it — Lh 2026-09-24) */
     const keepCursor = (e) => {
         const at = document.activeElement;
-        if (e.target.closest('.btn') && at instanceof HTMLElement && at.matches('input, textarea') && e.currentTarget.contains(at))
+        if (e.target.closest('.btn, .link') && at instanceof HTMLElement && at.matches('input, textarea') && e.currentTarget.contains(at))
             e.preventDefault();
     };
     const press = (e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "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.",