Autosave Ratchet

1"use client";
2 
3import {
4  useCallback,
5  useEffect,
6  useId,
7  useMemo,
8  useRef,
9  useState,
10  type KeyboardEvent as ReactKeyboardEvent,
11  type PointerEvent as ReactPointerEvent,
12} from "react";
13 
14// ---------------------------------------------------------------------------
15// PawlTick — autosave status rendered as a mechanical ratchet, not a spinner
16// or a text swap. A 10-tooth gear (9 teeth in --muted, one index tooth in
17// --foreground so a one-tooth-width rotation is actually visible against the
18// gear's own 10-fold symmetry) sits under a fixed pawl triangle. Every
19// SUCCESSFUL save advances the gear exactly one tooth-width and folds into a
20// silent running tally; the position is cosmetic (it wraps every 10 saves),
21// the count and timestamp are the real record and live in the tooltip text.
22//
23// Motion is three distinct, non-looping events, all direct-DOM CSS-transform
24// writes on two SVG refs (no React state on the hot path):
25//   - save-start ("saving"): a small anticipation backswing, winding the
26//     wheel back against the pawl before the outcome is known.
27//   - ack ("saved"): a 200ms ease-out-expo spring settle forward past the
28//     wind-up to the next tooth. Count++, timestamp stamped, wind-up cleared.
29//   - failure ("error"): the pawl slips — the wheel kicks back half a tooth
30//     from its last good seat (not from wherever the wind-up left it, so
31//     repeated failures hold the same broken pose rather than unraveling
32//     further) and the pawl itself lifts off and thickens to 2px
33//     --foreground. That pose holds — no loop — until the next successful
34//     save resolves it.
35//
36// Accessibility: a dedicated sr-only span (not the whole wrapper) is the
37// status live region — role=status/aria-live=polite/aria-atomic=true on
38// just that span, so re-reading it atomically never picks up the button's
39// label or an open tooltip's duplicated text, and hovering the tooltip
40// (marked aria-live=off) can never itself trigger a spurious announcement.
41// "Saving"/"Saved" chatter is throttled to at most one shared announcement
42// per 30s so a bursty autosave doesn't spam a screen reader; "Save failed"
43// always announces and resets that throttle window so the next resolution
44// is guaranteed to announce too. The gear is aria-hidden; the only focusable
45// element is the button that doubles as the tooltip trigger (hover or focus
46// reveals a Geist Mono panel that duplicates every fact as text — status,
47// … truncated