pending-task-kit 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ueaner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -24,13 +24,18 @@ pnpm add pending-task-kit zustand
   fields precisely so they can't collide with a key your own data happens to use). Anything
   else your app wants attached to a task — a display title, a link, a user/tenant id to scope
   by — goes in the fully free-form `metadata`; filter on it with the store's `pruneTasksBy`.
-- **Handler** (`PendingTaskHandler`) — per `type`, defines `check(task)` that polls your
-  backend and returns `{ status: "pending" | "success" | "failure", progress?, data? }` —
-  `data` is a free-form payload (a link, a message, whatever your `onResult` needs; see
+- **Handler** (`PendingTaskHandler`) — per `type`, defines `check(task, signal)` that polls
+  your backend and returns `{ status: "pending" | "success" | "failure", progress?, data? }`
+  — `data` is a free-form payload (a link, a message, whatever your `onResult` needs; see
   below), plus per-type tuning (`pollIntervalMs`, `ttlMs`, `finalCheckOnExpiry`,
-  `silentOnSuccess`/`silentOnFailure`).
+  `silentOnSuccess`/`silentOnFailure`, `retryBackoffMs` — see "Cancellation and retry
+  backoff" below). `signal` is an `AbortSignal` you can ignore entirely (existing handlers
+  that only take `task` keep working unmodified) or wire into your own request.
 - **Registry** (`PendingTaskRegistry`) — a plain `{ [type]: handler }` map.
-- **Store** — a zustand store, persisted to `localStorage`, holding the task list.
+- **Store** — a zustand store, persisted to `localStorage`, holding the task list. Warns
+  once (`console.warn`) if the tracked task count crosses `taskListWarnThreshold` (default
+  200) — the whole list is one JSON blob rewritten on every change, so a very large list
+  risks the ~5MB per-origin quota.
 - **Poller** (`PendingTaskPoller`) — the engine: scans tasks on an interval, calls the
   matching handler, and resolves each task to `success`/`failure` (dispatched via
   `onResult`), to `error` (dispatched unless `silentOnFailure`) when `check()` itself kept
@@ -125,6 +130,42 @@ function PendingTaskNotifier() {
 
 Mount `<PendingTaskNotifier />` once near your app root.
 
+## Cancellation, retry backoff, and observability (all optional)
+
+`stop()` aborts the `AbortSignal` passed to whichever `handler.check()` call is currently in
+flight, if any — wire it into your own request (`fetch(url, { signal })`) if you want a
+stopped poller to actually cancel outstanding network work instead of only discarding the
+response once it arrives. Losing leadership to another tab is only ever discovered *after*
+`check()` has already settled, so that's the only thing that ever aborts it; handlers that
+ignore `signal` keep working exactly as before.
+
+A `check()` that keeps throwing retries on the same fixed `pollIntervalMs`/
+`defaultPollIntervalMs` cadence as everything else by default — set a handler's
+`retryBackoffMs(failureCount)` to back off instead, once a task has actually failed at least
+once:
+
+```ts
+const registry = {
+  search: {
+    check: async (task, signal) => { /* ... */ },
+    retryBackoffMs: (failureCount) => Math.min(1_000 * 2 ** failureCount, 60_000), // capped exponential
+  },
+}
+```
+
+`onLeaderChange(isLeader)` fires when this tab's own belief about holding poll leadership
+flips (not once per tick), and `onTick({ durationMs, taskCount })` fires at the end of every
+tick that actually ran — both purely observational, for wiring into your own metrics/logging:
+
+```ts
+const poller = new PendingTaskPoller({
+  store,
+  registry,
+  onLeaderChange: (isLeader) => metrics.gauge("pending_task_poller.is_leader", isLeader ? 1 : 0),
+  onTick: ({ durationMs, taskCount }) => metrics.histogram("pending_task_poller.tick_ms", durationMs),
+})
+```
+
 ## Cross-tab poll-leader election (on by default)
 
 When multiple tabs share the same store — they already do, since tasks sync across tabs via
@@ -254,6 +295,52 @@ import { clearResultRelay } from "pending-task-kit"
 clearResultRelay(resultRelayKey) // same key you passed, or `${storageKey}-result-relay`
 ```
 
+## Runtime environment notes
+
+A grab-bag of behaviors that are intentional trade-offs rather than bugs, collected here so
+they're documented somewhere instead of only in source comments:
+
+- **Wall-clock dependent** (`Date.now()` throughout). A clock stepping *backward* just delays
+  polling/lease-renewal/dedupe harmlessly. A clock jumping *forward* can make a batch of tasks
+  expire silently all at once and make leases/dedupe records expire early — fencing (see
+  "Cross-tab poll-leader election") still keeps leadership *correct* through that, just less
+  available for a moment.
+- **Leadership rotates routinely, even in foreground tabs.** The lease's TTL defaults to 8s
+  (`pollTickMs` × 4), and it's only *renewed* by ticks that actually have a due task to check
+  — so with the default 10s `pollIntervalMs` the lease expires between checks anyway and the
+  next due tick re-contends for it, in whichever tab gets there first. Backgrounded tabs make
+  this much more pronounced: Chrome (and others) throttle a backgrounded tab's timers down to
+  as infrequently as once a minute, so a backgrounded leader readily loses leadership to
+  another (possibly also backgrounded) tab, and two backgrounded tabs can end up trading
+  leadership back and forth. Correctness is unaffected (Web Locks serialize the handoff,
+  fencing catches any stale response) — it's purely a responsiveness/battery trade-off already
+  inherent to how browsers treat inactive tabs.
+- **`stop()` doesn't hook `pagehide`/`beforeunload` for you.** A hard page unload (closing the
+  tab, navigating away) leaves that tick's in-memory batch unflushed and this tab's lease to
+  expire on its own TTL (default 8s) rather than being released immediately — the same
+  "closed/crashed/frozen tab" case `pollLeaseTtlMs` is already designed to bound.
+- **The React binding's tab-refocus recovery has no non-React equivalent.**
+  `usePendingTaskPoller` calls `forceCheckAll()` on `visibilitychange`; if you're using the core
+  API directly, wire that up yourself if you want the same "don't sit stale after tabbing back
+  in" behavior.
+- **A consumer callback that throws becomes an uncaught exception**, deliberately — surfaced on
+  a fresh microtask rather than silently swallowed or left as an unhandled rejection, so a bug
+  in your own `onResult`/`onCheckError`/etc. is as visible as any other uncaught error in your
+  app, not hidden inside this package.
+- **`zustand`'s own `persist` middleware logs its own `console.warn` on a storage failure** (SSR,
+  storage fully unavailable) — that noise comes from zustand itself, not from this package,
+  which otherwise degrades storage failures quietly (see `hasUnpersistedWrites`).
+- **A task whose `type` doesn't match any registry entry** (typo'd, or a handler that was
+  removed/renamed after the task was created) just sits until its TTL expires, with no warning.
+  Parameterize `TType` with a literal string union (rather than leaving it as plain `string`) to
+  get exhaustiveness checking on your own registry instead.
+- **The Playwright suite (`test-e2e/`) only runs against Chromium** — Safari/WebKit's
+  `navigator.locks` implementation is a known area where behavior could differ; add a WebKit
+  project to `playwright.config.ts` if that matters for your users.
+- **This package is pre-1.0.** Per semver convention for `0.x`, a `minor` bump *may* include a
+  breaking change — 0.2.0 already exercises that by dropping the CommonJS build (see
+  `CHANGELOG.md`), and future `0.x` releases make no stability guarantee either.
+
 ## What's deliberately out of scope
 
 - Toast/notification UI (`onResult` is a plain callback — bring your own).
@@ -264,3 +351,26 @@ clearResultRelay(resultRelayKey) // same key you passed, or `${storageKey}-resul
   `start()`/`stop()` (or the React binding's `enabled`) are how you gate polling on being
   logged in; `onCheckError` lets you recognize an auth failure and react to it (e.g. call
   `stop()`) without the engine knowing what "unauthorized" means.
+
+## Contributing
+
+`pnpm typecheck && pnpm lint && pnpm test && pnpm build` should all pass; `pnpm test:e2e` runs
+a small real-Chromium Playwright suite (`test-e2e/`) that specifically exercises cross-tab
+`navigator.locks` arbitration and genuine `storage` events — the one thing the jsdom-based
+`pnpm test` suite structurally can't do.
+
+This package uses [Changesets](https://github.com/changesets/changesets) for versioning.
+Every change that should land in a release needs a changeset: run `pnpm changeset`, describe
+the change, and pick `patch`/`minor`/`major` — commit the generated file in `.changeset/`
+alongside your change. CI's `changeset status --since` check fails a PR that changed something
+without one, so this isn't just a convention. The check doesn't look at file types, so a
+docs/CI/test-only PR trips it too — `pnpm changeset --empty` is the sanctioned escape hatch
+for those (commit the empty changeset it generates).
+
+Releases are tag-triggered (`.github/workflows/release.yml`), not merge-triggered: run
+`pnpm changeset version` (bumps `package.json` and updates `CHANGELOG.md`), commit that, tag the
+commit `vX.Y.Z` matching the version it just bumped to, and push the tag. The release job then
+does a clean checkout of exactly that tag, rebuilds and re-verifies everything from scratch, and
+publishes with `--provenance` — so what gets published is always traceable to a tagged, reviewed
+commit, never to whatever happened to be sitting in a working tree. Needs an `NPM_TOKEN` repo
+secret with publish access.

package/README.zh-CN.md

@@ -21,13 +21,17 @@ pnpm add pending-task-kit zustand
   者由引擎自己维护,之所以作为独立字段,正是为了不与你自己数据里可能用到的 key 冲突)。
   你的应用想附加到任务上的其它任何东西——展示用的标题、链接、用来做归属的用户/租户
   id——都放进完全自由形式的 `metadata` 里;配合 store 的 `pruneTasksBy` 按它过滤。
-- **Handler**(`PendingTaskHandler`)—— 按 `type` 划分,定义 `check(task)`,负责轮询你的
-  后端并返回 `{ status: "pending" | "success" | "failure", progress?, data? }`——`data` 是
-  自由形式的负载(一个链接、一条消息,或任何你 `onResult` 需要的东西;见下文),此外还有
-  按类型调节的选项(`pollIntervalMs`、`ttlMs`、`finalCheckOnExpiry`、
-  `silentOnSuccess`/`silentOnFailure`)。
+- **Handler**(`PendingTaskHandler`)—— 按 `type` 划分,定义 `check(task, signal)`,负责
+  轮询你的后端并返回 `{ status: "pending" | "success" | "failure", progress?, data? }`——
+  `data` 是自由形式的负载(一个链接、一条消息,或任何你 `onResult` 需要的东西;见下文),
+  此外还有按类型调节的选项(`pollIntervalMs`、`ttlMs`、`finalCheckOnExpiry`、
+  `silentOnSuccess`/`silentOnFailure`、`retryBackoffMs`——见下文"取消与重试 backoff"一节)。
+  `signal` 是一个 `AbortSignal`,可以完全不管(只写 `task` 一个参数的现有 handler 不受
+  影响),也可以接进你自己的请求里。
 - **Registry**(`PendingTaskRegistry`)—— 一个普通的 `{ [type]: handler }` 映射。
-- **Store** —— 一个 zustand store,持久化到 `localStorage`,保存任务列表。
+- **Store** —— 一个 zustand store,持久化到 `localStorage`,保存任务列表。跟踪的任务数量
+  超过 `taskListWarnThreshold`(默认 200)时会 `console.warn` 一次——整份列表是单个 JSON
+  blob,每次变化都要整个重写,数量太大会有撞上 ~5MB 单 origin 配额的风险。
 - **Poller**(`PendingTaskPoller`)—— 引擎本体:按间隔扫描任务,调用对应的 handler,并将
   每个任务归结为 `success`/`failure`(通过 `onResult` 派发)、`error`(当 `check()` 本身
   持续抛错直到达到 `maxFailureCount` 时派发,除非设置了 `silentOnFailure`),或者在 TTL
@@ -120,6 +124,40 @@ function PendingTaskNotifier() {
 
 在应用根部挂载一次 `<PendingTaskNotifier />` 即可。
 
+## 取消、重试 backoff 与观测(均为可选)
+
+`stop()` 会中止当前正在飞行中的那次 `handler.check()` 调用所拿到的 `AbortSignal`(如果
+有的话)——接进你自己的请求里(`fetch(url, { signal })`),就能让一个已停止的 poller
+真正取消掉还在进行的网络请求,而不是等响应回来后才丢弃它。leadership 被另一个标签页
+抢走这件事,永远只能在 `check()` 已经 settle 之后才被发现,所以这是唯一会触发中止的
+时机;不理会 `signal` 的 handler 行为不受任何影响。
+
+`check()` 持续失败时,默认按和其它情况一样固定的 `pollIntervalMs`/
+`defaultPollIntervalMs` 节奏重试——给 handler 设置 `retryBackoffMs(failureCount)`,可以
+在任务至少失败过一次之后改用这个退避策略:
+
+```ts
+const registry = {
+  search: {
+    check: async (task, signal) => { /* ... */ },
+    retryBackoffMs: (failureCount) => Math.min(1_000 * 2 ** failureCount, 60_000), // 有上限的指数退避
+  },
+}
+```
+
+`onLeaderChange(isLeader)` 会在本标签页对"自己是否持有 leadership"的判断发生翻转时
+触发(不是每个 tick 都触发),`onTick({ durationMs, taskCount })` 会在每个真正执行过的
+tick 结束时触发——两者都是纯观测性的,方便接入你自己的监控/日志:
+
+```ts
+const poller = new PendingTaskPoller({
+  store,
+  registry,
+  onLeaderChange: (isLeader) => metrics.gauge("pending_task_poller.is_leader", isLeader ? 1 : 0),
+  onTick: ({ durationMs, taskCount }) => metrics.histogram("pending_task_poller.tick_ms", durationMs),
+})
+```
+
 ## 跨标签页轮询选主(默认开启)
 
 多个标签页共享同一个 store 时(它们本来就是共享的——任务本身已经通过 `storage` 事件
@@ -239,6 +277,46 @@ import { clearResultRelay } from "pending-task-kit"
 clearResultRelay(resultRelayKey) // 用你传入的那个 key,没传的话就是 `${storageKey}-result-relay`
 ```
 
+## 运行时环境说明
+
+下面这些行为都是刻意的取舍,不是 bug——集中写在这里,而不是只散落在源码注释里:
+
+- **全链路依赖墙钟(`Date.now()`)**。时钟往回走只会让轮询/续约/去重变慢一点,无害。
+  时钟往前跳可能让一批任务同时静默过期,也可能让 lease/去重记录提前过期——fencing
+  (见"跨标签页轮询选主"一节)仍然保证 leadership 判断是*正确*的,只是那一刻可用性会
+  打折。
+- **leadership 会例行轮换,前台标签页也一样**。lease 的 TTL 默认 8 秒(`pollTickMs` × 4),
+  而且只在*有到期任务要检查*的 tick 上才续约——所以默认 `pollIntervalMs` 为 10 秒时,lease
+  在两次 check 之间本来就会过期,下一个 due 的 tick 重新竞争,谁先到谁当 leader。后台标签页
+  会让这更明显:Chrome(以及其它浏览器)会把后台标签页的计时器节流到最低每分钟一次,正在
+  后台的 leader 很容易把 leadership 让给另一个(可能也在后台的)标签页,甚至两个后台标签页
+  反复交替当 leader。正确性不受影响(Web Locks 保证串行化交接,fencing 兜住任何过期响应),
+  纯粹是浏览器对非活跃标签页本来就有的性能/省电取舍。
+- **`stop()` 不会自动帮你挂 `pagehide`/`beforeunload`**。硬性卸载页面(关掉标签页、
+  跳转离开)会让那一次 tick 的内存 batch 没来得及落盘,这个标签页的 lease 也要等自己的
+  TTL(默认 8 秒)自然过期,而不是立刻释放——这和 `pollLeaseTtlMs` 本来就要兜住的
+  "标签页被关闭/崩溃/冻结"是同一类场景。
+- **React 绑定的"标签页重新聚焦时恢复"没有非 React 版本**。`usePendingTaskPoller` 会在
+  `visibilitychange` 时调用 `forceCheckAll()`;如果你直接用核心 API,想要同样的"切回来
+  别让数据卡在旧状态"效果,需要自己接一下这个事件。
+- **consumer 回调抛出的异常会变成一个 uncaught 异常**,这是故意的——在一个新的
+  microtask 里重新抛出,而不是被静默吞掉或者变成一个 unhandled rejection,这样你自己
+  `onResult`/`onCheckError` 等回调里的 bug 就和你应用里其它 uncaught 错误一样显眼,不会
+  被这个包藏起来。
+- **`zustand` 自己的 `persist` 中间件在存储失败时会打自己的 `console.warn`**(SSR、存储
+  完全不可用等场景)——这条噪音来自 zustand 自身,不是这个包发出的;这个包自己对存储
+  失败的处理是安静降级的(见 `hasUnpersistedWrites`)。
+- **`type` 和 registry 里任何 handler 都对不上的任务**(打错字,或者 handler 在任务创建
+  之后被删除/改名了),会一直挂到 TTL 才过期,期间没有任何提示。把 `TType` 参数化成一个
+  字面量字符串联合类型(而不是留成普通的 `string`),就能对你自己的 registry 做穷举
+  检查。
+- **Playwright 套件(`test-e2e/`)目前只跑 Chromium**——Safari/WebKit 的 `navigator.locks`
+  实现是一个已知的可能存在差异的区域;如果这对你的用户重要,可以给
+  `playwright.config.ts` 加一个 WebKit project。
+- **这个包还是 0.x 版本**。按 semver 对 0.x 的约定,`minor` 版本号升级*可能*包含破坏性
+  改动——0.2.0 就已经动用了这个空间(移除了 CommonJS 构建,见 `CHANGELOG.md`),以后的
+  0.x 版本同样不做稳定性保证。
+
 ## 刻意排除在范围之外的东西
 
 - Toast/通知 UI(`onResult` 只是一个普通回调——UI 部分自己实现)。
@@ -248,3 +326,24 @@ clearResultRelay(resultRelayKey) // 用你传入的那个 key,没传的话就是
   只是个普通闭包,所以它会自然捕获你应用自己用的认证方式;`start()`/`stop()`(或 React
   绑定里的 `enabled`)是你用来控制"是否应该轮询"的开关;`onCheckError` 让你能够识别出一次
   认证失败并做出反应(比如调用 `stop()`),而引擎本身完全不需要知道"未授权"是什么意思。
+
+## 贡献指南
+
+`pnpm typecheck && pnpm lint && pnpm test && pnpm build` 应该全部通过;`pnpm test:e2e`
+会跑一个基于真实 Chromium 的小型 Playwright 套件(`test-e2e/`),专门验证跨标签页
+`navigator.locks` 仲裁和真实的 `storage` 事件——这正是基于 jsdom 的 `pnpm test` 那套
+测试结构性做不到的事。
+
+这个包用 [Changesets](https://github.com/changesets/changesets) 管理版本号。任何应该
+出现在发布记录里的改动都需要一个 changeset:运行 `pnpm changeset`,描述改动内容,选
+`patch`/`minor`/`major`——把生成的文件和你的改动一起提交到 `.changeset/` 下。CI 里的
+`changeset status --since` 检查会让"改了代码却没加 changeset"的 PR 直接失败,不只是
+约定。这个检查不看文件类型,纯文档/CI/测试改动的 PR 也会触发——这种情况的正规逃生口是
+`pnpm changeset --empty`(把它生成的空 changeset 一并提交即可)。
+
+发布是打 tag 触发的(`.github/workflows/release.yml`),不是合并到 main 就自动触发:
+先跑 `pnpm changeset version`(会更新 `package.json` 和 `CHANGELOG.md`),提交这个改动,
+在这个 commit 上打一个和刚刚升级到的版本号一致的 `vX.Y.Z` tag,再推送这个 tag。发布
+job 会对那个 tag 做一次干净的 checkout,从零重新构建、重新跑一遍所有验证,再带着
+`--provenance` 发布——这样发出去的东西永远能追溯到一个打过 tag、经过审查的 commit,
+而不是工作区里当时恰好放着的任何东西。需要一个有发布权限的 `NPM_TOKEN` 仓库密钥。

package/dist/{engine-ClhasLko.d.cts → engine-BJ7pokhW.d.ts}

@@ -47,9 +47,34 @@ interface PendingTaskCheckResult {
     data?: unknown;
 }
 interface PendingTaskHandler<TType extends string = string> {
-    check: (task: PendingTask<TType>) => Promise<PendingTaskCheckResult>;
+    /**
+     * `signal` is aborted when the poller is `stop()`-ed while this particular call is still in
+     * flight (nothing else aborts it — losing leadership to another tab is only ever discovered
+     * *after* `check()` has already settled, so there's nothing in-flight left to cancel at that
+     * point; see `PendingTaskPoller`'s class doc comment). Wire it into your own request (e.g.
+     * `fetch(url, { signal })`) if you want a stopped poller to actually cancel outstanding
+     * network work instead of just discarding the response when it eventually arrives. Handlers
+     * that ignore the parameter keep working exactly as before — nothing requires reading it.
+     */
+    check: (task: PendingTask<TType>, signal: AbortSignal) => Promise<PendingTaskCheckResult>;
     /** How often (ms) this task type is checked. Defaults to the poller's `defaultPollIntervalMs`. */
     pollIntervalMs?: number;
+    /**
+     * Optional backoff for the failure-retry cadence specifically — a `check()` that keeps
+     * throwing, before `maxFailureCount` is reached. Given the just-incremented failure count,
+     * return the delay (ms) before the next retry. Only consulted once a task has actually failed
+     * at least once; a task that's still cleanly polling (never failed, or already recovered back
+     * to `failureCount` 0) keeps using `pollIntervalMs`/`defaultPollIntervalMs` regardless. Leave
+     * unset to keep today's behavior: failures retry on the same fixed cadence as everything else.
+     *
+     * A non-finite or non-positive return (`NaN`, `Infinity`, `0`, negative) falls back to the
+     * normal `pollIntervalMs`/`defaultPollIntervalMs` cadence rather than being trusted outright
+     * — `0`/negative would otherwise retry on essentially every tick, and `NaN` would make the
+     * task never look due again. A throw is treated the same way (as if unset for this task this
+     * tick) and surfaced as an uncaught exception rather than either being silently swallowed or
+     * taking down the rest of the tick's tasks — the same treatment `onCheckError` gets.
+     */
+    retryBackoffMs?: (failureCount: number) => number;
     /** How long (ms) an untracked-to-completion task is kept before being dropped. */
     ttlMs?: number;
     /** Force one last `check()` exactly at TTL expiry instead of silently dropping the task. */
@@ -69,6 +94,8 @@ interface PendingTaskResultEventDetail<TType extends string = string> {
 
 declare const DEFAULT_TTL_MS: number;
 declare const DEFAULT_STORAGE_KEY = "pending-tasks";
+/** Default for `CreatePendingTaskStoreOptions.taskListWarnThreshold` — see its doc comment. */
+declare const DEFAULT_TASK_LIST_WARN_THRESHOLD = 200;
 interface PendingTaskStoreState<TType extends string = string> {
     tasks: PendingTask<TType>[];
     addTask: (task: PendingTask<TType>) => void;
@@ -110,6 +137,17 @@ type PendingTaskStore<TType extends string = string> = UseBoundStore<StoreApi<Pe
 interface CreatePendingTaskStoreOptions {
     /** localStorage key. Defaults to `"pending-tasks"`. Must be unique per app if you run multiple stores. */
     storageKey?: string;
+    /**
+     * Soft warning threshold for the tracked task count, checked on every write. The whole list
+     * is persisted as a single JSON blob on every change — a very large list risks the ~5MB
+     * per-origin localStorage quota and makes every write (and every other tab's `storage`-event
+     * re-parse) slower, but nothing previously surfaced that risk until it actually broke. Once
+     * the count crosses this threshold, `console.warn`s exactly once for this store's lifetime
+     * (never again after, even if the count keeps climbing) — not a hard limit, tasks keep being
+     * tracked normally either way. Defaults to `DEFAULT_TASK_LIST_WARN_THRESHOLD` (200); set to
+     * `Infinity` to disable if your app genuinely needs to track more.
+     */
+    taskListWarnThreshold?: number;
 }
 declare function isPendingTaskShape(value: unknown): value is PendingTask;
 /** Parses the raw string a zustand-persist localStorage entry holds, tolerating garbage/foreign values. */
@@ -245,6 +283,26 @@ interface PendingTaskPollerOptions<TType extends string = string> {
      * awaiting inline.
      */
     acceptRelayedResult?: (detail: PendingTaskResultEventDetail<TType>) => boolean;
+    /**
+     * Fires whenever *this tab's* belief about whether it currently holds poll leadership flips
+     * (claimed for the first time, or lost to another tab / this poller being `stop()`-ed) — not
+     * on every tick, only on an actual change. Only meaningful (and only ever called) when
+     * `crossTabPollLeaderElection` is on; there's no "leader" concept to report when it's off.
+     * Purely observational — wire it into your own metrics/logging, the engine's behavior doesn't
+     * change based on whether this is set.
+     */
+    onLeaderChange?: (isLeader: boolean) => void;
+    /**
+     * Fires once at the end of every tick that actually ran (ticks skipped because one was
+     * already in flight, or because there were no tasks at all, don't count). `taskCount` is how
+     * many tasks were in the store when the tick started (not just the due ones); `durationMs`
+     * covers the whole tick, including every awaited `handler.check()` call, since this engine
+     * processes a tick's due tasks sequentially. Purely observational, same as `onLeaderChange`.
+     */
+    onTick?: (info: {
+        durationMs: number;
+        taskCount: number;
+    }) => void;
 }
 /**
  * Framework-agnostic polling engine: scans the store's tasks on an interval, calls the
@@ -261,10 +319,11 @@ interface PendingTaskPollerOptions<TType extends string = string> {
  * Framework bindings (see `./react`) are thin wrappers that call `start()`/`stop()` at the
  * right lifecycle moments and expose `forceCheckAll()` for e.g. tab-focus recovery.
  *
- * Note: `stop()` prevents any *new* tick from starting, but a tick already awaiting
- * `handler.check()` when `stop()` is called will still run to completion (there is no
- * `AbortSignal` plumbed into the handler contract). Design handlers to be safe to finish
- * even if the caller has logically "stopped" — e.g. don't assume side effects are undone.
+ * Note: `stop()` prevents any *new* tick from starting, and aborts the `AbortSignal` passed to
+ * whatever `handler.check()` call is currently in flight (if any) — but only handlers that
+ * actually wire that signal into their own request will see it actually cancelled; one that
+ * ignores it still runs to completion. Design handlers to be safe to finish even if the caller
+ * has logically "stopped" regardless — e.g. don't assume side effects are undone.
  */
 declare class PendingTaskPoller<TType extends string = string> {
     private readonly options;
@@ -279,6 +338,15 @@ declare class PendingTaskPoller<TType extends string = string> {
     private pendingForce;
     private stopped;
     private latestTasksCache;
+    /** This tab's own most recently reported leadership status, for `onLeaderChange` — tracked
+     *  here (rather than derived fresh each time from `fence`) purely so that callback fires only
+     *  on an actual flip, not once per tick it happens to still hold/still lack leadership. */
+    private isLeaderTab;
+    /** The `AbortController` backing whichever `handler.check()` call is currently in flight, if
+     *  any — reachable from `stop()` (a synchronous method with no other way to reach into an
+     *  in-progress `runTick`) so it can actually cancel that request. See `PendingTaskHandler.check`'s
+     *  doc comment for why this is the *only* thing that ever aborts it. */
+    private inFlightAbortController;
     /** Task ids that already got their one `finalCheckOnExpiry` attempt, so a repeatedly-failing
      *  final check doesn't get retried every tick. Reset on process restart — worst case that
      *  costs one extra check, never an infinite retry loop.
@@ -295,6 +363,14 @@ declare class PendingTaskPoller<TType extends string = string> {
     /** Re-check every tracked task right now, bypassing each task's poll interval (e.g. on tab focus). */
     forceCheckAll(): void;
     private claimLeadership;
+    /** Updates `isLeaderTab` and fires `onLeaderChange`, but only on an actual flip — see that
+     *  option's doc comment, including the "only ever called when `crossTabPollLeaderElection` is
+     *  on" part, which this enforces itself rather than relying on every call site to remember to
+     *  guard it (a call site that forgot would otherwise be a real, undetected bug — the whole
+     *  reason this guard lives here instead of at each of this method's several call sites). Safe
+     *  to call redundantly (e.g. after every successful claim/reconfirm in a tick, not just the
+     *  first) since a no-op call is just an equality check. */
+    private setLeaderStatus;
     /**
      * Re-confirms that poll leadership is still this tab's — and still the *same continuous
      * tenure* as when `fence` was captured, not just "is nobody else currently holding it" (a
@@ -359,4 +435,4 @@ declare class PendingTaskPoller<TType extends string = string> {
     private runTick;
 }
 
-export { type CreatePendingTaskStoreOptions as C, DEFAULT_MAX_FAILURE_COUNT as D, type PendingTaskStore as P, type PendingTaskRegistry as a, type PendingTask as b, type PendingTaskResultEventDetail as c, DEFAULT_POLL_INTERVAL_MS as d, DEFAULT_POLL_LEASE_TTL_MULTIPLIER as e, DEFAULT_POLL_TICK_MS as f, DEFAULT_RESULT_EVENT as g, DEFAULT_STORAGE_KEY as h, DEFAULT_TTL_MS as i, type PendingTaskCheckResult as j, type PendingTaskHandler as k, type PendingTaskMetadata as l, PendingTaskPoller as m, type PendingTaskPollerOptions as n, type PendingTaskResultStatus as o, type PendingTaskStatus as p, type PendingTaskStoreState as q, createPendingTaskStore as r, isPendingTaskShape as s, parseTasksFromStorageValue as t };
+export { type CreatePendingTaskStoreOptions as C, DEFAULT_MAX_FAILURE_COUNT as D, type PendingTaskStore as P, type PendingTaskRegistry as a, type PendingTask as b, type PendingTaskResultEventDetail as c, DEFAULT_POLL_INTERVAL_MS as d, DEFAULT_POLL_LEASE_TTL_MULTIPLIER as e, DEFAULT_POLL_TICK_MS as f, DEFAULT_RESULT_EVENT as g, DEFAULT_STORAGE_KEY as h, DEFAULT_TASK_LIST_WARN_THRESHOLD as i, DEFAULT_TTL_MS as j, type PendingTaskCheckResult as k, type PendingTaskHandler as l, type PendingTaskMetadata as m, PendingTaskPoller as n, type PendingTaskPollerOptions as o, type PendingTaskResultStatus as p, type PendingTaskStatus as q, type PendingTaskStoreState as r, createPendingTaskStore as s, isPendingTaskShape as t, parseTasksFromStorageValue as u };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PendingTaskStore, a as PendingTaskRegistry, b as PendingTask, c as PendingTaskResultEventDetail } from './engine-ClhasLko.js';
-export { C as CreatePendingTaskStoreOptions, D as DEFAULT_MAX_FAILURE_COUNT, d as DEFAULT_POLL_INTERVAL_MS, e as DEFAULT_POLL_LEASE_TTL_MULTIPLIER, f as DEFAULT_POLL_TICK_MS, g as DEFAULT_RESULT_EVENT, h as DEFAULT_STORAGE_KEY, i as DEFAULT_TTL_MS, j as PendingTaskCheckResult, k as PendingTaskHandler, l as PendingTaskMetadata, m as PendingTaskPoller, n as PendingTaskPollerOptions, o as PendingTaskResultStatus, p as PendingTaskStatus, q as PendingTaskStoreState, r as createPendingTaskStore, s as isPendingTaskShape, t as parseTasksFromStorageValue } from './engine-ClhasLko.js';
+import { P as PendingTaskStore, a as PendingTaskRegistry, b as PendingTask, c as PendingTaskResultEventDetail } from './engine-BJ7pokhW.js';
+export { C as CreatePendingTaskStoreOptions, D as DEFAULT_MAX_FAILURE_COUNT, d as DEFAULT_POLL_INTERVAL_MS, e as DEFAULT_POLL_LEASE_TTL_MULTIPLIER, f as DEFAULT_POLL_TICK_MS, g as DEFAULT_RESULT_EVENT, h as DEFAULT_STORAGE_KEY, i as DEFAULT_TASK_LIST_WARN_THRESHOLD, j as DEFAULT_TTL_MS, k as PendingTaskCheckResult, l as PendingTaskHandler, m as PendingTaskMetadata, n as PendingTaskPoller, o as PendingTaskPollerOptions, p as PendingTaskResultStatus, q as PendingTaskStatus, r as PendingTaskStoreState, s as createPendingTaskStore, t as isPendingTaskShape, u as parseTasksFromStorageValue } from './engine-BJ7pokhW.js';
 import 'zustand';
 
 /**