refactor(timer): share schedule runtime

Author: crup

README.md

@@ -15,18 +15,17 @@
 
 ## Why this exists
 
-Timer hooks look simple until real apps need pause/resume semantics, Strict Mode cleanup, async callbacks, polling that does not overlap, and lists with dozens of independent timers.
+Timers get messy when a product needs pause and resume, countdowns tied to server time, async work, or a screen full of independent rows.
 
-`@crup/react-timer-hook` starts with a ~1.2 kB timer core and lets your app compose the heavier pieces only when it needs them:
+`@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.
-- 🔋 Batteries are optional: schedules, timer groups, duration helpers, and diagnostics live in subpath imports.
+- 🔋 Add-ons are opt-in: schedules, timer groups, duration helpers, and diagnostics live in subpath imports.
 - 🧭 `useTimerGroup()` from `/group` for many keyed lifecycles with one shared scheduler.
-- 📡 `useScheduledTimer()` from `/schedules` for polling, overdue timing context, and opt-in diagnostics.
-- 🧩 `durationParts()` from `/duration` for display math without locale or timezone opinions.
-- 🧼 No formatting, timezone, audio, retry, cache, or data-fetching policy baked in.
-- 🧪 Built for rerenders, Strict Mode, async callbacks, cleanup, and many timers.
-- 🤖 Agent-friendly docs through hosted `llms.txt`, `llms-full.txt`, and an optional MCP docs helper.
+- 📡 `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.
+- 🤖 AI-ready docs are available through hosted `llms.txt`, `llms-full.txt`, and an optional MCP docs helper.
 
 ## Install
 
@@ -49,7 +48,7 @@ import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
 Each recipe has a live playground and a focused code sample:
 
 - Basic: [wall clock](https://crup.github.io/react-timer-hook/recipes/basic/wall-clock/), [stopwatch](https://crup.github.io/react-timer-hook/recipes/basic/stopwatch/), [absolute countdown](https://crup.github.io/react-timer-hook/recipes/basic/absolute-countdown/), [pausable countdown](https://crup.github.io/react-timer-hook/recipes/basic/pausable-countdown/), [manual controls](https://crup.github.io/react-timer-hook/recipes/basic/manual-controls/)
-- 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/), [debug logs](https://crup.github.io/react-timer-hook/recipes/intermediate/debug-logs/)
+- 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/)
 
 ## Quick examples
@@ -143,7 +142,7 @@ const timers = useTimerGroup({
 });
 ```
 
-## API tables
+## API reference
 
 ### `useTimer()` settings
 
@@ -165,13 +164,13 @@ Import from `@crup/react-timer-hook/schedules` when you need polling or schedule
 | `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. |
 | `schedules` | `TimerSchedule[]` | No | Scheduled side effects that run while the timer is active. Async overlap defaults to `skip`. |
-| `debug` | `TimerDebug` | No | Opt-in semantic diagnostics. No logs are emitted by default. |
+| `diagnostics` | `TimerDiagnostics` | No | Optional lifecycle and schedule events. No logs are emitted unless you pass a logger. |
 
 ### `TimerSchedule`
 
 | Key | Type | Required | Description |
 | --- | --- | --- | --- |
-| `id` | `string` | No | Stable identifier used in debug events and schedule context. Falls back to the array index. |
+| `id` | `string` | No | Stable identifier used in diagnostics events and schedule context. Falls back to the array index. |
 | `everyMs` | `number` | Yes | Schedule cadence in milliseconds. Must be positive and finite. |
 | `leading` | `boolean` | No | Runs the schedule immediately when the timer starts or resumes into a new generation. Defaults to `false`. |
 | `overlap` | `'skip' \| 'allow'` | No | Controls async overlap. Defaults to `skip`, so a pending callback prevents another run. |
@@ -185,7 +184,7 @@ Import from `@crup/react-timer-hook/group` when many keyed items need independen
 | --- | --- | --- | --- |
 | `updateIntervalMs` | `number` | No | Shared scheduler cadence for the group. Defaults to `1000`. |
 | `items` | `TimerGroupItem[]` | No | Initial/synced timer item definitions. Each item has its own lifecycle state. |
-| `debug` | `TimerDebug` | No | Opt-in semantic diagnostics for group lifecycle and schedule events. |
+| `diagnostics` | `TimerDiagnostics` | No | Optional lifecycle and schedule events for group timers. |
 
 ### `TimerGroupItem`
 
@@ -224,15 +223,15 @@ Import from `@crup/react-timer-hook/group` when many keyed items need independen
 
 ## Bundle size
 
-The core import stays small. Extra capabilities are opt-in batteries.
+The default import stays small. Add the other pieces only when that screen needs them.
 
-| Entry | Raw | Gzip | Brotli |
-| --- | ---: | ---: | ---: |
-| core | 3.82 kB | 1.31 kB | 1.21 kB |
-| timer group add-on | 8.94 kB | 2.97 kB | 2.70 kB |
-| schedules add-on | 6.88 kB | 2.32 kB | 2.13 kB |
-| duration helper | 318 B | 224 B | 192 B |
-| diagnostics helper | 105 B | 115 B | 99 B |
+| 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 |
+| 🧩 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 |
 
 CI writes a size summary to the GitHub Actions UI and posts bundle-size reports on pull requests.
 

docs-site/docs/api/types.mdx

@@ -52,17 +52,16 @@ type TimerSchedule = {
 
 `scheduledAt` is the intended fire time. `firedAt` is when the browser actually ran the callback. `overdueCount` reports how many schedule windows were missed before this callback because the browser, tab, or previous work delayed execution.
 
-## Debug
+## Diagnostics
 
-Debug is opt-in. The package does not emit logs by default.
+Diagnostics are opt-in. The package does not emit logs by default.
 
 ```ts
-type TimerDebug =
-  | boolean
-  | TimerDebugLogger
+type TimerDiagnostics =
+  | TimerDiagnosticsLogger
   | {
       enabled?: boolean;
-      logger?: TimerDebugLogger;
+      logger: TimerDiagnosticsLogger;
       includeTicks?: boolean;
       label?: string;
     };

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

@@ -9,12 +9,12 @@ description: Optional schedule-enabled timer API for polling and timing context.
 import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
 ```
 
-`useScheduledTimer()` includes the lifecycle API from `useTimer()` plus schedule callbacks and opt-in debug events. It lives in a subpath so the root import stays small for clocks, stopwatches, and countdowns that do not need polling.
+`useScheduledTimer()` includes the lifecycle API from `useTimer()` plus schedule callbacks and optional diagnostics. It lives in a subpath so the root import stays small for clocks, stopwatches, and countdowns that do not need polling.
 
 ```ts
 type UseScheduledTimerOptions = UseTimerOptions & {
   schedules?: TimerSchedule[];
-  debug?: TimerDebug;
+  diagnostics?: TimerDiagnostics;
 };
 ```
 

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

@@ -19,7 +19,7 @@ Item schedules use the same `TimerSchedule` contract as `useScheduledTimer()`, i
 type UseTimerGroupOptions = {
   updateIntervalMs?: number;
   items?: TimerGroupItem[];
-  debug?: TimerDebug;
+  diagnostics?: TimerDiagnostics;
 };
 
 type TimerGroupItem = {

docs-site/docs/project/contributing.mdx

@@ -30,5 +30,5 @@ Timer rules:
 - Do not schedule work during render.
 - Use recursive `setTimeout`, not `setInterval`.
 - Keep timezone and formatting outside the library.
-- Keep debug logs opt-in.
+- Keep diagnostics opt-in.
 - Add tests for Strict Mode and async callbacks when lifecycle behavior changes.

docs-site/docs/project/debug-logs.mdx

@@ -1,22 +1,22 @@
 ---
-title: Debug logs
+title: Diagnostics
 description: Opt-in semantic diagnostics for timer lifecycles and schedules.
 ---
 
-# Debug logs
+# Diagnostics
 
-Debug logs are off by default.
+Diagnostics are off by default.
 
 ```tsx
 import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
 import { consoleTimerDiagnostics } from '@crup/react-timer-hook/diagnostics';
 
 useScheduledTimer({
   autoStart: true,
-  debug: consoleTimerDiagnostics({ label: 'auction-card' }),
+  diagnostics: consoleTimerDiagnostics({ label: 'auction-card' }),
 });
 ```
 
-Debug events are semantic: `timer:start`, `timer:pause`, `timer:resume`, `timer:reset`, `timer:restart`, `timer:cancel`, `timer:end`, `scheduler:start`, `scheduler:stop`, `schedule:start`, `schedule:skip`, `schedule:end`, `schedule:error`, and `callback:error`.
+Events are semantic: `timer:start`, `timer:pause`, `timer:resume`, `timer:reset`, `timer:restart`, `timer:cancel`, `timer:end`, `scheduler:start`, `scheduler:stop`, `schedule:start`, `schedule:skip`, `schedule:end`, `schedule:error`, and `callback:error`.
 
 Raw timeout handles are not exposed.

docs-site/docs/recipes/intermediate/debug-logs.mdx

@@ -1,16 +1,16 @@
 ---
-title: Debug logs
+title: Diagnostics
 description: Opt into semantic lifecycle and schedule events.
 ---
 
 import RecipePlayground from '@site/src/components/RecipePlayground';
 import { DebugLogsSample } from '../../../samples/recipes';
 
-# Debug logs
+# Diagnostics
 
-Debug logs are opt-in and semantic. They do not expose timeout handles.
+Diagnostics are opt-in and semantic. They do not expose timeout handles.
 
-<RecipePlayground title="Debug logs">
+<RecipePlayground title="Diagnostics">
   <DebugLogsSample />
 </RecipePlayground>
 
@@ -19,6 +19,6 @@ import { consoleTimerDiagnostics } from '@crup/react-timer-hook/diagnostics';
 import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
 
 useScheduledTimer({
-  debug: consoleTimerDiagnostics({ label: 'auction-card' }),
+  diagnostics: consoleTimerDiagnostics({ label: 'auction-card' }),
 });
 ```

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

@@ -1,6 +1,6 @@
 ---
 title: Intermediate recipes
-description: End callbacks, schedules, early cancellation, backend events, and debug logs.
+description: End callbacks, schedules, early cancellation, backend events, and diagnostics.
 ---
 
 # Intermediate recipes
@@ -11,5 +11,4 @@ Use these patterns when the timer coordinates with side effects or external app
 - [Polling schedule](./polling-schedule)
 - [Poll and cancel](./poll-and-cancel)
 - [Backend event stop](./backend-event-stop)
-- [Debug logs](./debug-logs)
-
+- [Diagnostics](./debug-logs)

docs-site/samples/recipes.tsx

@@ -254,15 +254,15 @@ export function DebugLogsSample() {
   const [logs, setLogs] = useState<string[]>([]);
   const timer = useScheduledTimer({
     updateIntervalMs: 1000,
-    debug: {
+    diagnostics: {
       label: 'docs-demo',
       includeTicks: false,
       logger: event => setLogs(previous => [`${event.type} (${event.status})`, ...previous].slice(0, 5)),
     },
   });
 
   return (
-    <DemoShell eyebrow="Debug events" title={logs[0] ?? 'No events yet'} status={timer.status}>
+    <DemoShell eyebrow="Diagnostics" title={logs[0] ?? 'No events yet'} status={timer.status}>
       <EventStream events={logs.length ? logs : ['start, pause, resume, cancel, or restart to emit events']} />
       <TimerControlsPanel timer={timer} allowCancel />
     </DemoShell>

docs-site/static/llms-full.txt

@@ -78,6 +78,6 @@ Local docs MCP server:
 }
 ```
 
-## Non-goals
+## Boundaries
 
-No formatting, no timezone handling, no mode enums, no data-fetching cache, and no raw timeout handle exposure.
+Use the hook for timer lifecycle, elapsed time, schedules, and controls. Keep UI display and data fetching in your app.