refactor(timer): split optional runtime entrypoints

Author: crup

README.md

@@ -1,6 +1,6 @@
 # @crup/react-timer-hook
 
-> React timer hooks for countdowns, stopwatches, clocks, polling schedules, and many independent timer lifecycles.
+> Tiny React timer primitives for countdowns, stopwatches, clocks, polling schedules, and many independent timer lifecycles.
 
 [![npm alpha](https://img.shields.io/npm/v/%40crup%2Freact-timer-hook/alpha?label=npm%20alpha&color=00b894)](https://www.npmjs.com/package/@crup/react-timer-hook?activeTab=versions)
 [![npm downloads](https://img.shields.io/npm/dm/%40crup%2Freact-timer-hook?color=0f766e)](https://www.npmjs.com/package/@crup/react-timer-hook)
@@ -17,11 +17,12 @@
 
 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.
 
-`@crup/react-timer-hook` keeps the API small and lets your app decide what time means:
+`@crup/react-timer-hook` keeps the root import small and lets your app opt into heavier features only when needed:
 
-- ⏱️ `useTimer()` for one lifecycle: stopwatch, countdown, clock, schedule, or custom flow.
-- 🧭 `useTimerGroup()` for many keyed lifecycles with one shared scheduler.
-- 🧩 `durationParts()` for display math without locale or timezone opinions.
+- ⏱️ `useTimer()` from the root package for one lifecycle: stopwatch, countdown, clock, or custom flow.
+- 🧭 `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.
@@ -36,7 +37,13 @@ pnpm add @crup/react-timer-hook@alpha
 ```
 
 ```tsx
-import { durationParts, useTimer, useTimerGroup } from '@crup/react-timer-hook';
+import { useTimer } from '@crup/react-timer-hook';
+import { durationParts } from '@crup/react-timer-hook/duration';
+import { useTimerGroup } from '@crup/react-timer-hook/group';
+import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
+
+// Or choose convenience over minimum entry size:
+import { durationParts, useScheduledTimer, useTimer, useTimerGroup } from '@crup/react-timer-hook/full';
 ```
 
 ## Live recipes
@@ -99,7 +106,9 @@ export function AuctionTimer({ auctionId, expiresAt }: {
 Schedules run while the timer is active. Slow async work is skipped by default with `overlap: 'skip'`.
 
 ```tsx
-const timer = useTimer({
+import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
+
+const timer = useScheduledTimer({
   autoStart: true,
   updateIntervalMs: 1000,
   endWhen: snapshot => snapshot.now >= expiresAt,
@@ -123,6 +132,8 @@ const timer = useTimer({
 Use `useTimerGroup()` when every row needs its own pause, resume, cancel, restart, schedules, or `onEnd`.
 
 ```tsx
+import { useTimerGroup } from '@crup/react-timer-hook/group';
+
 const timers = useTimerGroup({
   updateIntervalMs: 1000,
   items: auctions.map(auction => ({
@@ -138,11 +149,14 @@ const timers = useTimerGroup({
 
 Current build:
 
-| File | Raw | Gzip | Brotli |
+| Entry | Raw | Gzip | Brotli |
 | --- | ---: | ---: | ---: |
-| `dist/index.js` | 12.80 kB | 3.88 kB | 3.47 kB |
-| `dist/index.cjs` | 14.04 kB | 4.12 kB | 3.70 kB |
-| `dist/index.d.ts` | 4.32 kB | 1.04 kB | 951 B |
+| core | 3.91 kB | 1.34 kB | 1.23 kB |
+| full | 15.03 kB | 4.69 kB | 4.18 kB |
+| timer group add-on | 9.05 kB | 3.01 kB | 2.74 kB |
+| schedules add-on | 6.99 kB | 2.35 kB | 2.16 kB |
+| duration helper | 374 B | 262 B | 229 B |
+| diagnostics helper | 156 B | 155 B | 139 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

@@ -20,7 +20,7 @@ type DurationParts = {
 ```
 
 ```ts
-import { durationParts } from '@crup/react-timer-hook';
+import { durationParts } from '@crup/react-timer-hook/duration';
 
 const parts = durationParts(90_500);
 ```

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

@@ -0,0 +1,39 @@
+---
+title: useScheduledTimer
+description: Optional schedule-enabled timer API for polling and timing context.
+---
+
+# useScheduledTimer
+
+```ts
+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.
+
+```ts
+type UseScheduledTimerOptions = UseTimerOptions & {
+  schedules?: TimerSchedule[];
+  debug?: TimerDebug;
+};
+```
+
+Schedules run while active and default to `overlap: 'skip'`.
+
+```ts
+const timer = useScheduledTimer({
+  autoStart: true,
+  schedules: [
+    {
+      id: 'poll',
+      everyMs: 5000,
+      overlap: 'skip',
+      callback: async (snapshot, controls, context) => {
+        console.log(context.overdueCount);
+      },
+    },
+  ],
+});
+```
+
+The third callback argument contains `scheduledAt`, `firedAt`, `nextRunAt`, `overdueCount`, and `effectiveEveryMs`.

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

@@ -6,12 +6,14 @@ description: API reference for many keyed independent timer lifecycles driven by
 # useTimerGroup
 
 ```ts
+import { useTimerGroup } from '@crup/react-timer-hook/group';
+
 function useTimerGroup(options?: UseTimerGroupOptions): TimerGroupResult;
 ```
 
 Use `useTimerGroup()` when every row needs independent pause, resume, cancel, restart, schedules, or `onEnd`.
 
-Item schedules use the same `TimerSchedule` contract as `useTimer()`, including the third schedule context argument for intended fire time, actual fire time, next run time, and overdue interval count.
+Item schedules use the same `TimerSchedule` contract as `useScheduledTimer()`, including the third schedule context argument for intended fire time, actual fire time, next run time, and overdue interval count.
 
 ```ts
 type UseTimerGroupOptions = {

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

@@ -17,8 +17,6 @@ type UseTimerOptions = {
   updateIntervalMs?: number;
   endWhen?: (snapshot: TimerSnapshot) => boolean;
   onEnd?: (snapshot: TimerSnapshot, controls: TimerControls) => void | Promise<void>;
-  schedules?: TimerSchedule[];
-  debug?: TimerDebug;
 };
 ```
 
@@ -28,7 +26,7 @@ type UseTimerOptions = {
 
 `onEnd` fires once per generation. `restart()` creates a new generation.
 
-Schedules run while active and default to `overlap: 'skip'`. The schedule callback receives a third `context` argument with `scheduledAt`, `firedAt`, `nextRunAt`, `overdueCount`, and `effectiveEveryMs`, so delayed browser timers can be measured without exposing timeout handles.
+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

@@ -13,14 +13,24 @@ pnpm add @crup/react-timer-hook@alpha
 ```
 
 ```tsx
-import { durationParts, useTimer, useTimerGroup } from '@crup/react-timer-hook';
+import { useTimer } from '@crup/react-timer-hook';
+import { durationParts } from '@crup/react-timer-hook/duration';
+import { useTimerGroup } from '@crup/react-timer-hook/group';
+import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
 import type { TimerSnapshot } from '@crup/react-timer-hook';
 ```
 
+Prefer one convenience import over the smallest entrypoints?
+
+```tsx
+import { durationParts, useScheduledTimer, useTimer, useTimerGroup } from '@crup/react-timer-hook/full';
+```
+
 ## First timer
 
 ```tsx
-import { durationParts, useTimer } from '@crup/react-timer-hook';
+import { useTimer } from '@crup/react-timer-hook';
+import { durationParts } from '@crup/react-timer-hook/duration';
 
 export function BreakTimer() {
   const durationMs = 5 * 60 * 1000;

docs-site/docs/index.mdx

@@ -9,7 +9,7 @@ import { StopwatchSample, AbsoluteCountdownSample, TimerGroupSample } from '../s
 
 # React timer hooks
 
-`@crup/react-timer-hook` gives React apps a small timer lifecycle primitive instead of a formatting-heavy timer component.
+`@crup/react-timer-hook` gives React apps a small root timer primitive and optional subpath hooks for schedules, groups, diagnostics, and duration helpers.
 
 It is built for Strict Mode, rerenders, async callbacks, cleanup, and pages with many independent timers.
 
@@ -35,8 +35,9 @@ pnpm add @crup/react-timer-hook@alpha
 ## Public API
 
 - `useTimer()` for one lifecycle
-- `useTimerGroup()` for many keyed independent lifecycles
-- `durationParts()` for duration display math
+- `useScheduledTimer()` from `/schedules` for polling and schedule timing context
+- `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.
 

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

@@ -8,13 +8,12 @@ description: Opt-in semantic diagnostics for timer lifecycles and schedules.
 Debug logs are off by default.
 
 ```tsx
-useTimer({
+import { useScheduledTimer } from '@crup/react-timer-hook/schedules';
+import { consoleTimerDiagnostics } from '@crup/react-timer-hook/diagnostics';
+
+useScheduledTimer({
   autoStart: true,
-  debug: {
-    label: 'auction-card',
-    includeTicks: false,
-    logger: event => console.debug('[timer]', event),
-  },
+  debug: consoleTimerDiagnostics({ label: 'auction-card' }),
 });
 ```
 

docs-site/docs/recipes/advanced/per-item-polling.mdx

@@ -15,10 +15,11 @@ Each item can define schedules with different cadence and callbacks.
 </RecipePlayground>
 
 ```tsx
+import { useTimerGroup } from '@crup/react-timer-hook/group';
+
 items: jobs.map(job => ({
   id: job.id,
   autoStart: true,
   schedules: [{ id: 'status', everyMs: job.pollMs, callback: refresh }],
 }))
 ```
-

docs-site/docs/recipes/advanced/timer-group.mdx

@@ -15,6 +15,8 @@ Use `useTimerGroup()` when every row needs its own pause, resume, restart, cance
 </RecipePlayground>
 
 ```tsx
+import { useTimerGroup } from '@crup/react-timer-hook/group';
+
 const timers = useTimerGroup({
   items: jobs.map(job => ({
     id: job.id,
@@ -23,4 +25,3 @@ const timers = useTimerGroup({
   })),
 });
 ```
-