@usableapp/cardds 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 > 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.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
+- The bottom layer of a `Screen fill` (the `ActionBar` — a Walkthrough's dots, controls, CTA row and link) now lies on
+  the screen's surface. Before: it had no ground, so long words scrolling under it mid-scroll showed through and could
+  not be read. Knob `--action-bar-bg` (default `var(--surface)`; `transparent` = the old see-through).
+- `SheetSteps`: the cursor holder field's size is `1rem` (was 16px); no raw px left in sheet.css.
+
 ## 0.7.5 — 2026-09-24
 
 ### Errors in a form (new)

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

@@ -380,8 +380,8 @@
    bottom of the body, each its title line. Every step has a thin rule on top. A step opens and folds as a 1fr ↔ 0fr grid row, so the pile rises and
    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, 0px)); /* 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: 16px; } /* holds the cursor (and the phone's keyboard) while a step folds; 16px so iOS never zooms to it */
+.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: 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/css/step.css

@@ -120,7 +120,11 @@
   position: absolute; inset-inline: 0; top: auto; bottom: var(--kb, 0rem);
   max-width: none;
   margin: 0;
-  padding-top: 0; /* no ground of its own, never a solid strip */
+  padding-top: 0;
+  /* its GROUND (Lh 2026-09-24, timebank card 141 — was "no ground of its own"): words that run under the layer mid-scroll
+     showed through the dots, the controls and the buttons. The layer lies on the screen's own surface now; a project sets
+     another (or `transparent`, the old see-through) with the knob */
+  background: var(--action-bar-bg, var(--surface));
 }
 /* the walk's dots are the BOTTOM layer's too (Lh 2026-09-23): a row of the bar, over its buttons, centred */
 .action-bar > .pager__at, .action-bar__tier > .pager__at { align-self: center; }

package/dist/cardds.css

@@ -1557,8 +1557,8 @@ button { font: inherit; cursor: pointer; }
    bottom of the body, each its title line. Every step has a thin rule on top. A step opens and folds as a 1fr ↔ 0fr grid row, so the pile rises and
    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, 0px)); /* 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: 16px; } /* holds the cursor (and the phone's keyboard) while a step folds; 16px so iOS never zooms to it */
+.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: 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 */
@@ -1712,7 +1712,11 @@ button { font: inherit; cursor: pointer; }
   position: absolute; inset-inline: 0; top: auto; bottom: var(--kb, 0rem);
   max-width: none;
   margin: 0;
-  padding-top: 0; /* no ground of its own, never a solid strip */
+  padding-top: 0;
+  /* its GROUND (Lh 2026-09-24, timebank card 141 — was "no ground of its own"): words that run under the layer mid-scroll
+     showed through the dots, the controls and the buttons. The layer lies on the screen's own surface now; a project sets
+     another (or `transparent`, the old see-through) with the knob */
+  background: var(--action-bar-bg, var(--surface));
 }
 /* the walk's dots are the BOTTOM layer's too (Lh 2026-09-23): a row of the bar, over its buttons, centred */
 .action-bar > .pager__at, .action-bar__tier > .pager__at { align-self: center; }
@@ -1781,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); }
 
@@ -1825,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)); }

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

@@ -14,8 +14,9 @@ export interface PinProps extends Omit<ComponentProps<'div'>, 'onChange' | 'defa
      *  first cell, and the next digit typed starts a new code. The words are the step's (`SheetStep 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 +29,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,40 @@ 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];
     const set = (next) => {
         next = next.slice(0, length);
-        if (bad) {
+        if (bad || said.current) {
             setBad(false);
             say(null);
+            said.current = false;
         }
+        clearTimeout(reset.current);
         if (match != null && next.length === length && next !== match) {
             setBad(true);
             say(words);
-            back();
+            said.current = true;
             restart.current = true;
+            setShake(true);
+            reset.current = setTimeout(() => {
+                setBad(false);
+                restart.current = false;
+                if (value === undefined)
+                    setInner('');
+                onChange?.('', false);
+                cell(0)?.focus();
+            }, RESET_MS);
         }
         if (value === undefined)
             setInner(next);
@@ -36,8 +48,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;
@@ -68,14 +84,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 +104,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 +131,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/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. */

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
@@ -197,9 +196,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 +205,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.5",
+  "version": "0.7.7",
   "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.",