fix(timer): sync schedule updates and document use cases

Author: crup

README.md

@@ -20,11 +20,11 @@ Timers get messy when a product needs pause and resume, countdowns tied to serve
 `@crup/react-timer-hook` keeps the default import small and lets you add only the pieces your screen needs:
 
 - ⏱️ `useTimer()` from the root package for one lifecycle: stopwatch, countdown, clock, or custom flow.
-- 🔋 Add-ons are opt-in: schedules, timer groups, duration helpers, and diagnostics live in subpath imports.
+- 🔋 Add schedules, timer groups, duration helpers, and diagnostics only when a screen needs them.
 - 🧭 `useTimerGroup()` from `/group` for many keyed lifecycles with one shared scheduler.
 - 📡 `useScheduledTimer()` from `/schedules` for polling and timing context.
 - 🧩 `durationParts()` from `/duration` for common display math.
-- 🧪 Tested for React Strict Mode, rerenders, async callbacks, cleanup, and multi-timer screens.
+- 🧪 Covered for rerenders, React Strict Mode, async callbacks, cleanup, and multi-timer screens.
 - 🤖 AI-ready docs are available through hosted `llms.txt`, `llms-full.txt`, and an optional MCP docs helper.
 
 ## Install
@@ -51,6 +51,22 @@ Each recipe has a live playground and a focused code sample:
 - Intermediate: [once-only onEnd](https://crup.github.io/react-timer-hook/recipes/intermediate/once-only-on-end/), [polling schedule](https://crup.github.io/react-timer-hook/recipes/intermediate/polling-schedule/), [poll and cancel](https://crup.github.io/react-timer-hook/recipes/intermediate/poll-and-cancel/), [backend event stop](https://crup.github.io/react-timer-hook/recipes/intermediate/backend-event-stop/), [diagnostics](https://crup.github.io/react-timer-hook/recipes/intermediate/debug-logs/)
 - Advanced: [many display countdowns](https://crup.github.io/react-timer-hook/recipes/advanced/many-display-countdowns/), [timer group](https://crup.github.io/react-timer-hook/recipes/advanced/timer-group/), [group controls](https://crup.github.io/react-timer-hook/recipes/advanced/group-controls/), [per-item polling](https://crup.github.io/react-timer-hook/recipes/advanced/per-item-polling/), [dynamic items](https://crup.github.io/react-timer-hook/recipes/advanced/dynamic-items/)
 
+## Use cases
+
+| Product case | Use | Import | Recipe |
+| --- | --- | --- | --- |
+| Stopwatch, call timer, workout timer | Core | `@crup/react-timer-hook` | [Stopwatch](https://crup.github.io/react-timer-hook/recipes/basic/stopwatch/) |
+| Wall clock or "last updated" display | Core | `@crup/react-timer-hook` | [Wall clock](https://crup.github.io/react-timer-hook/recipes/basic/wall-clock/) |
+| Auction, reservation, or job deadline | Core | `@crup/react-timer-hook` | [Absolute countdown](https://crup.github.io/react-timer-hook/recipes/basic/absolute-countdown/) |
+| Focus timer or checkout hold that pauses | Core + duration | `@crup/react-timer-hook` + `/duration` | [Pausable countdown](https://crup.github.io/react-timer-hook/recipes/basic/pausable-countdown/) |
+| Backend status polling | Schedules | `@crup/react-timer-hook/schedules` | [Polling schedule](https://crup.github.io/react-timer-hook/recipes/intermediate/polling-schedule/) |
+| Polling that can close early | Schedules | `@crup/react-timer-hook/schedules` | [Poll and cancel](https://crup.github.io/react-timer-hook/recipes/intermediate/poll-and-cancel/) |
+| Auction list with independent row controls | Timer group | `@crup/react-timer-hook/group` | [Timer group](https://crup.github.io/react-timer-hook/recipes/advanced/timer-group/) |
+| Upload/job dashboard with per-row polling | Timer group + schedules | `@crup/react-timer-hook/group` | [Per-item polling](https://crup.github.io/react-timer-hook/recipes/advanced/per-item-polling/) |
+| Toast expiry or runtime item timers | Timer group | `@crup/react-timer-hook/group` | [Dynamic items](https://crup.github.io/react-timer-hook/recipes/advanced/dynamic-items/) |
+
+See the full use-case guide: https://crup.github.io/react-timer-hook/use-cases/
+
 ## Quick examples
 
 ### Stopwatch
@@ -152,6 +168,7 @@ const timers = useTimerGroup({
 | `updateIntervalMs` | `number` | No | Render/update cadence in milliseconds. Defaults to `1000`. This does not define elapsed time; elapsed time is calculated from timestamps. Use a smaller value like `100` or `20` when the UI needs finer updates. |
 | `endWhen` | `(snapshot) => boolean` | No | Ends the lifecycle when it returns `true`. Use this for countdowns, timeouts, and custom stop conditions. |
 | `onEnd` | `(snapshot, controls) => void \| Promise<void>` | No | Called once per generation when `endWhen` ends the lifecycle. `restart()` creates a new generation. |
+| `onError` | `(error, snapshot, controls) => void` | No | Handles sync throws and async rejections from `onEnd`. |
 
 ### `useScheduledTimer()` settings
 
@@ -163,6 +180,7 @@ Import from `@crup/react-timer-hook/schedules` when you need polling or schedule
 | `updateIntervalMs` | `number` | No | Render/update cadence in milliseconds. Defaults to `1000`. Scheduled callbacks can run on their own cadence. |
 | `endWhen` | `(snapshot) => boolean` | No | Ends the lifecycle when it returns `true`. |
 | `onEnd` | `(snapshot, controls) => void \| Promise<void>` | No | Called once per generation when `endWhen` ends the lifecycle. |
+| `onError` | `(error, snapshot, controls) => void` | No | Handles sync throws and async rejections from `onEnd`. |
 | `schedules` | `TimerSchedule[]` | No | Scheduled side effects that run while the timer is active. Async overlap defaults to `skip`. |
 | `diagnostics` | `TimerDiagnostics` | No | Optional lifecycle and schedule events. No logs are emitted unless you pass a logger. |
 
@@ -194,6 +212,7 @@ Import from `@crup/react-timer-hook/group` when many keyed items need independen
 | `autoStart` | `boolean` | No | Starts the item automatically when it is added or synced. Defaults to `false`. |
 | `endWhen` | `(snapshot) => boolean` | No | Ends that item when it returns `true`. |
 | `onEnd` | `(snapshot, controls) => void \| Promise<void>` | No | Called once per item generation when that item ends naturally. |
+| `onError` | `(error, snapshot, controls) => void` | No | Handles sync throws and async rejections from that item's `onEnd`. |
 | `schedules` | `TimerSchedule[]` | No | Per-item schedules with the same contract as `useScheduledTimer()`. |
 
 ### Values and controls
@@ -227,9 +246,9 @@ The default import stays small. Add the other pieces only when that screen needs
 
 | Piece | Import | Best for | Raw | Gzip | Brotli |
 | --- | --- | --- | ---: | ---: | ---: |
-| ⏱️ Core | `@crup/react-timer-hook` | Stopwatch, countdown, clock, custom lifecycle | 3.82 kB | 1.31 kB | 1.21 kB |
-| 🧭 Timer group | `@crup/react-timer-hook/group` | Many independent row/item timers | 9.75 kB | 3.42 kB | 3.13 kB |
-| 📡 Schedules | `@crup/react-timer-hook/schedules` | Polling, cadence callbacks, overdue timing context | 7.41 kB | 2.57 kB | 2.36 kB |
+| ⏱️ Core | `@crup/react-timer-hook` | Stopwatch, countdown, clock, custom lifecycle | 3.96 kB | 1.37 kB | 1.25 kB |
+| 🧭 Timer group | `@crup/react-timer-hook/group` | Many independent row/item timers | 9.91 kB | 3.51 kB | 3.20 kB |
+| 📡 Schedules | `@crup/react-timer-hook/schedules` | Polling, cadence callbacks, overdue timing context | 7.62 kB | 2.67 kB | 2.46 kB |
 | 🧩 Duration | `@crup/react-timer-hook/duration` | `days`, `hours`, `minutes`, `seconds`, `milliseconds` | 318 B | 224 B | 192 B |
 | 🔎 Diagnostics | `@crup/react-timer-hook/diagnostics` | Optional lifecycle and schedule event logging | 105 B | 115 B | 90 B |
 

docs-site/docs/api/types.mdx

@@ -5,6 +5,18 @@ description: Public TypeScript types exported by the package.
 
 # Types
 
+## Lifecycle error callback
+
+```ts
+onError?: (
+  error: unknown,
+  snapshot: TimerSnapshot,
+  controls: TimerControls,
+) => void;
+```
+
+Use `onError` when `onEnd` can throw or return a rejected promise.
+
 ## Duration parts
 
 ```ts

docs-site/docs/api/use-scheduled-timer.mdx

@@ -19,6 +19,7 @@ type UseScheduledTimerOptions = UseTimerOptions & {
 ```
 
 Schedules run while active and default to `overlap: 'skip'`.
+`onError` comes from `UseTimerOptions` and receives sync throws or async rejections from `onEnd`.
 
 ```ts
 const timer = useScheduledTimer({
@@ -37,3 +38,5 @@ const timer = useScheduledTimer({
 ```
 
 The third callback argument contains `scheduledAt`, `firedAt`, `nextRunAt`, `overdueCount`, and `effectiveEveryMs`.
+
+When the schedule cadence changes, the active scheduler recalculates the next timeout immediately. Changing only the callback keeps the current cadence and uses the latest callback on the next run.

docs-site/docs/api/use-timer-group.mdx

@@ -27,10 +27,15 @@ type TimerGroupItem = {
   autoStart?: boolean;
   endWhen?: (snapshot: TimerSnapshot) => boolean;
   onEnd?: (snapshot: TimerSnapshot, controls: TimerGroupItemControls) => void | Promise<void>;
+  onError?: (error: unknown, snapshot: TimerSnapshot, controls: TimerGroupItemControls) => void;
   schedules?: TimerSchedule[];
 };
 ```
 
+`onError` receives sync throws and async rejections from that item's `onEnd`.
+
+When `items` is controlled by props, pass a new array/object when item definitions change. The store preserves state for existing IDs and syncs new callbacks, deadlines, and schedules without resetting the item generation.
+
 ## Result
 
 ```ts

docs-site/docs/api/use-timer.mdx

@@ -17,6 +17,7 @@ type UseTimerOptions = {
   updateIntervalMs?: number;
   endWhen?: (snapshot: TimerSnapshot) => boolean;
   onEnd?: (snapshot: TimerSnapshot, controls: TimerControls) => void | Promise<void>;
+  onError?: (error: unknown, snapshot: TimerSnapshot, controls: TimerControls) => void;
 };
 ```
 
@@ -26,6 +27,8 @@ type UseTimerOptions = {
 
 `onEnd` fires once per generation. `restart()` creates a new generation.
 
+`onError` receives sync throws and async rejections from `onEnd`.
+
 The root `useTimer()` export is lifecycle-only to keep the default bundle small. Use `@crup/react-timer-hook/schedules` when you need polling schedules and schedule timing context.
 
 ## Controls

docs-site/docs/getting-started.mdx

@@ -5,7 +5,7 @@ description: Install the alpha package and wire a timer into a React component.
 
 # Getting started
 
-Alpha builds are the only intended release channel until stable publishing is explicitly unlocked.
+Install the alpha build while the API is collecting feedback.
 
 ```sh
 npm install @crup/react-timer-hook@alpha

docs-site/docs/index.mdx

@@ -39,7 +39,14 @@ pnpm add @crup/react-timer-hook@alpha
 - `useTimerGroup()` from `/group` for many keyed independent lifecycles
 - `durationParts()` from `/duration` for duration display math
 
-The library owns scheduling and cleanup. Your app owns formatting, timezone, data fetching policy, and business rules.
+Use the root hook first. Add subpaths only when a screen needs schedules, many independent timers, display parts, or diagnostics.
+
+## Use-case shortcuts
+
+- [Core use cases](./use-cases/core): stopwatch, wall clock, absolute deadline, pausable duration countdown.
+- [Schedule use cases](./use-cases/schedules): polling, heartbeat checks, timing context, early cancel.
+- [Timer group use cases](./use-cases/groups): auctions, checkout holds, upload rows, job dashboards.
+- [Composition guide](./use-cases/composition): combine core, duration, schedules, groups, and diagnostics.
 
 ## Recipe routes
 

docs-site/docs/recipes/advanced/index.mdx

@@ -7,9 +7,16 @@ description: Many timers, independent group lifecycles, item polling, and runtim
 
 Use these patterns for lists, dashboards, auctions, reservation holds, jobs, and task boards.
 
-- [Many display countdowns](./many-display-countdowns)
-- [Timer group](./timer-group)
-- [Group controls](./group-controls)
-- [Per-item polling](./per-item-polling)
-- [Dynamic items](./dynamic-items)
+## Core for display-only lists
 
+- [Many display countdowns](./many-display-countdowns): one shared `useTimer()` drives many derived countdown labels.
+
+## Timer group
+
+- [Timer group](./timer-group): many keyed lifecycles with independent state.
+- [Group controls](./group-controls): pause, resume, restart, and cancel many items together.
+- [Dynamic items](./dynamic-items): add, update, and remove timers at runtime.
+
+## Timer group + schedules
+
+- [Per-item polling](./per-item-polling): each row owns its own schedule cadence.

docs-site/docs/recipes/basic/index.mdx

@@ -7,9 +7,13 @@ description: Clocks, stopwatches, countdowns, and manual timer controls.
 
 Start here when you need a single lifecycle or a display-only timer.
 
-- [Wall clock](./wall-clock)
-- [Stopwatch](./stopwatch)
-- [Absolute countdown](./absolute-countdown)
-- [Pausable countdown](./pausable-countdown)
-- [Manual controls](./manual-controls)
+## Core only
 
+- [Wall clock](./wall-clock): use `timer.now` and format the `Date` in your app.
+- [Stopwatch](./stopwatch): use `elapsedMilliseconds` for active elapsed time.
+- [Absolute countdown](./absolute-countdown): derive remaining time from `expiresAt - timer.now`.
+- [Manual controls](./manual-controls): wire `start`, `pause`, `resume`, `reset`, `restart`, and `cancel`.
+
+## Core + duration
+
+- [Pausable countdown](./pausable-countdown): use `elapsedMilliseconds` and `durationParts()` for display math.

docs-site/docs/recipes/intermediate/index.mdx

@@ -7,8 +7,16 @@ description: End callbacks, schedules, early cancellation, backend events, and d
 
 Use these patterns when the timer coordinates with side effects or external app state.
 
-- [Once-only onEnd](./once-only-on-end)
-- [Polling schedule](./polling-schedule)
-- [Poll and cancel](./poll-and-cancel)
-- [Backend event stop](./backend-event-stop)
-- [Diagnostics](./debug-logs)
+## Core lifecycle callbacks
+
+- [Once-only onEnd](./once-only-on-end): run completion logic once per generation.
+- [Backend event stop](./backend-event-stop): cancel a timer from a WebSocket, SSE event, or external subscription.
+
+## Schedules
+
+- [Polling schedule](./polling-schedule): run cadence callbacks while the timer is active.
+- [Poll and cancel](./poll-and-cancel): stop early when backend state says the flow is closed.
+
+## Diagnostics
+
+- [Diagnostics](./debug-logs): emit optional lifecycle and schedule events while investigating behavior.