react-inp-chunker 0.1.2 → 0.3.0

package/dist/production/deferred-task-yh5pWlSj.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-task-yh5pWlSj.cjs","names":[],"sources":["../../src/core/chunk-machine.ts","../../src/core/diagnostics.production.ts","../../src/core/scheduler.ts","../../src/core/chunk-scheduler.ts","../../src/core/deferred-task.ts"],"sourcesContent":["/**\n * The state machine a chunk task moves through. Deliberately separate from\n * `chunk-scheduler.ts`'s async orchestration: this file is pure, synchronous,\n * and has nothing to fake-timer around, which is what makes it possible to\n * exhaustively test every (state, event) pair — all of them, not a sample.\n *\n *          START                    CANCEL\n *   idle ---------> processing ----------------> cancelled\n *                    |      ^                   ^         ^\n *              PAUSE |      | RESUME      CANCEL|         | CANCEL\n *                    v      |                   |         |\n *                   paused -+-------------------+         |\n *                    |                                    |\n *          COMPLETE  |  ERROR                              |\n *                    v                                     |\n *                   done / error  (terminal, absorb everything)\n *\n * `done`, `cancelled` and `error` are terminal: once reached, every further\n * event is a no-op that returns the same state object (referentially equal,\n * so a React reducer built on this never re-renders for a dead task). A\n * scheduler is one-shot by design — to run another task, create another\n * scheduler. That one rule is what keeps this table small enough to verify\n * completely instead of \"pretty thoroughly\".\n */\n\nexport type ChunkStatus =\n  'idle' | 'processing' | 'paused' | 'done' | 'cancelled' | 'error';\n\nexport type ChunkEvent =\n  | { readonly type: 'START' }\n  | { readonly type: 'PAUSE' }\n  | { readonly type: 'RESUME' }\n  | { readonly type: 'CANCEL' }\n  | { readonly type: 'COMPLETE' }\n  | { readonly type: 'ERROR'; readonly error: unknown };\n\nexport interface ChunkMachineState {\n  readonly status: ChunkStatus;\n  readonly error?: unknown;\n}\n\nexport const initialChunkState: ChunkMachineState = { status: 'idle' };\n\nexport type TerminalChunkStatus = 'done' | 'cancelled' | 'error';\n\nconst TERMINAL_STATUSES: ReadonlySet<ChunkStatus> = new Set<ChunkStatus>([\n  'done',\n  'cancelled',\n  'error',\n]);\n\nexport function isTerminal(status: ChunkStatus): status is TerminalChunkStatus {\n  return TERMINAL_STATUSES.has(status);\n}\n\nfunction transitionIdle(state: ChunkMachineState, event: ChunkEvent): ChunkMachineState {\n  switch (event.type) {\n    case 'START':\n      return { status: 'processing' };\n    case 'CANCEL':\n      return { status: 'cancelled' };\n    case 'PAUSE':\n    case 'RESUME':\n    case 'COMPLETE':\n    case 'ERROR':\n      return state;\n  }\n}\n\nfunction transitionProcessing(\n  state: ChunkMachineState,\n  event: ChunkEvent,\n): ChunkMachineState {\n  switch (event.type) {\n    case 'PAUSE':\n      return { status: 'paused' };\n    case 'CANCEL':\n      return { status: 'cancelled' };\n    case 'COMPLETE':\n      return { status: 'done' };\n    case 'ERROR':\n      return { status: 'error', error: event.error };\n    case 'START':\n    case 'RESUME':\n      return state;\n  }\n}\n\nfunction transitionPaused(\n  state: ChunkMachineState,\n  event: ChunkEvent,\n): ChunkMachineState {\n  switch (event.type) {\n    case 'RESUME':\n      return { status: 'processing' };\n    case 'CANCEL':\n      return { status: 'cancelled' };\n    case 'START':\n    case 'PAUSE':\n    case 'COMPLETE':\n    case 'ERROR':\n      return state;\n  }\n}\n\n/**\n * Advances the machine by one event. Pure: same inputs always produce an\n * equal output, and the input state is never mutated.\n */\nexport function transition(\n  state: ChunkMachineState,\n  event: ChunkEvent,\n): ChunkMachineState {\n  switch (state.status) {\n    case 'idle':\n      return transitionIdle(state, event);\n    case 'processing':\n      return transitionProcessing(state, event);\n    case 'paused':\n      return transitionPaused(state, event);\n    case 'done':\n    case 'cancelled':\n    case 'error':\n      // Terminal: absorb every event and return the same reference, so a\n      // React reducer built on this never re-renders for a dead task.\n      return state;\n  }\n}\n","import type * as RealDiagnostics from './diagnostics.js';\nimport type { Diagnostics } from './diagnostics.js';\n\n/**\n * The production twin of `diagnostics.ts`, swapped in at build time for the\n * files behind this package's `production` export condition (see\n * tsdown.config.ts). Development guidance is worth about a kilobyte of\n * message strings, which is a quarter of this package — worth paying while\n * building, not worth shipping to users.\n *\n * Relying on a bundler to prove `process.env.NODE_ENV !== 'production'`\n * false and drop the branch does not work: the guard that keeps the check\n * safe outside Node (`typeof process !== 'undefined'`) is not a constant,\n * so esbuild — and therefore Vite — leaves the whole thing in. Swapping the\n * module removes the question.\n */\nexport const isDevelopment = false;\n\nconst NOTHING: Diagnostics = {\n  check: () => undefined,\n  sliceEnded: () => undefined,\n  resumed: () => undefined,\n};\n\nexport function createDiagnostics(): Diagnostics {\n  return NOTHING;\n}\n\nexport function warnDev(): void {\n  // No-op: every call site passes a message string built from values that\n  // only matter for the warning text itself, so there's nothing to do with\n  // the argument here — dropping it is what makes this (and the string\n  // concatenation at every call site) disappear under tree-shaking.\n}\n\n/**\n * Fails the build if this stops being a drop-in replacement for the real\n * module — a missing export, or a signature that drifted.\n */\nconst _sameShape: typeof RealDiagnostics = { isDevelopment, createDiagnostics, warnDev };\nexport type { _sameShape };\n","/**\n * The main-thread yielding primitives this package is built around.\n *\n * Framework-agnostic on purpose: nothing here imports React, so it works\n * just as well inside a Node CLI script chewing through a big array as it\n * does inside a browser tab. The React bindings in `src/react/` are a thin\n * layer on top of this.\n *\n * Strategy, in priority order:\n *  1. `scheduler.yield()` — the purpose-built API (Baseline across Chromium\n *     and Firefox as of 2026; continuations resume ahead of same-priority\n *     work queued elsewhere on the page).\n *  2. `MessageChannel` — posts a message to a dedicated port and resolves on\n *     delivery. Not clamped to the ~4ms floor `setTimeout` gets once timers\n *     are nested, so it yields sooner than (2).\n *  3. `setTimeout(0)` — universally available, the floor of the floor.\n *\n * Every feature check below is written so it can never throw on a global\n * that doesn't exist — `typeof x` on an undeclared identifier is safe in\n * JS, and every property access goes through optional chaining. That's what\n * makes this file safe to import under SSR, in a test environment with no\n * DOM, or in a browser that only half-implements one of these APIs.\n */\n\nexport type YieldStrategy = 'scheduler-yield' | 'message-channel' | 'set-timeout';\n\n/** Default time slice: roughly the granularity React's own scheduler uses. */\nexport const DEFAULT_TIME_SLICE_MS = 5;\n\ninterface SchedulerYieldGlobal {\n  scheduler?: {\n    yield?: () => Promise<void>;\n  };\n}\n\ninterface NavigatorSchedulingGlobal {\n  navigator?: {\n    scheduling?: {\n      isInputPending?: () => boolean;\n    };\n  };\n}\n\n/** True when `scheduler.yield()` is present on this runtime. */\nexport function supportsSchedulerYield(): boolean {\n  const schedulerGlobal = (globalThis as SchedulerYieldGlobal).scheduler;\n  return typeof schedulerGlobal?.yield === 'function';\n}\n\n/** True when the `MessageChannel` constructor is present on this runtime. */\nexport function supportsMessageChannel(): boolean {\n  return typeof MessageChannel === 'function';\n}\n\n/** True when `navigator.scheduling.isInputPending()` is present. */\nexport function supportsInputPending(): boolean {\n  const navigatorGlobal = (globalThis as NavigatorSchedulingGlobal).navigator;\n  return typeof navigatorGlobal?.scheduling?.isInputPending === 'function';\n}\n\n/**\n * Resolves the input-pending probe once, for callers that would otherwise\n * run the feature detection on every item of a long task: walking\n * `navigator.scheduling.isInputPending` through optional calls is wasted\n * work a million times over. Returns a function that always answers\n * `false` where the API is missing, so callers need no second branch.\n */\nexport function resolveInputPending(): () => boolean {\n  return supportsInputPending() ? isInputPending : returnsFalse;\n}\n\nfunction returnsFalse(): boolean {\n  return false;\n}\n\n/**\n * Best-effort read of whether the browser has pending input right now.\n * Returns `false` — never throws — when the API is unavailable or errors,\n * since the caller's fallback (a plain time budget) is always safe.\n */\nexport function isInputPending(): boolean {\n  try {\n    const navigatorGlobal = (globalThis as NavigatorSchedulingGlobal).navigator;\n    return navigatorGlobal?.scheduling?.isInputPending?.() ?? false;\n  } catch {\n    return false;\n  }\n}\n\n/** Picks the best strategy this runtime actually supports. */\nexport function resolveYieldStrategy(): YieldStrategy {\n  if (supportsSchedulerYield()) return 'scheduler-yield';\n  if (supportsMessageChannel()) return 'message-channel';\n  return 'set-timeout';\n}\n\nfunction yieldViaMessageChannel(): Promise<void> {\n  return new Promise((resolve) => {\n    // A fresh channel per call, deliberately — not a shared module-level\n    // singleton. Two chunk schedulers can easily be yielding in the same\n    // tick (two independent useChunkedTask calls on one page is a normal\n    // app, not an edge case), and a shared port's onmessage handler would\n    // get clobbered by whichever call registered second, permanently\n    // hanging the first caller's promise. A new MessageChannel is a few\n    // microseconds; a silently-hung promise is a production incident.\n    const channel = new MessageChannel();\n    channel.port1.onmessage = () => {\n      // Closed the moment its one message lands. A port with a listener is\n      // a live handle: in Node it keeps the process from ever exiting (a\n      // CLI script would finish its work and then hang), and in a browser\n      // without scheduler.yield() a long task opens hundreds of these.\n      channel.port1.close();\n      resolve();\n    };\n    channel.port2.postMessage(null);\n  });\n}\n\nfunction yieldViaSetTimeout(): Promise<void> {\n  return new Promise((resolve) => {\n    setTimeout(resolve, 0);\n  });\n}\n\nexport interface YieldToMainOptions {\n  /**\n   * Force a specific strategy instead of auto-detecting one. Exists for\n   * deterministic tests of each fallback path; application code should\n   * leave this unset.\n   */\n  strategy?: YieldStrategy;\n}\n\n/**\n * Yields control back to the browser's main thread, resolving once the\n * browser has had a chance to handle any pending input, then resuming the\n * caller. Never rejects: a runtime that half-implements `scheduler.yield()`\n * (the property exists but the call throws, or the returned promise\n * rejects) falls through to the next strategy rather than propagating the\n * failure into unrelated application code.\n */\nexport async function yieldToMain(options?: YieldToMainOptions): Promise<void> {\n  const strategy = options?.strategy ?? resolveYieldStrategy();\n\n  if (strategy === 'scheduler-yield') {\n    const schedulerGlobal = (globalThis as SchedulerYieldGlobal).scheduler;\n    if (typeof schedulerGlobal?.yield === 'function') {\n      try {\n        await schedulerGlobal.yield();\n        return;\n      } catch {\n        // Fall through to the next strategy below.\n      }\n    }\n    await (supportsMessageChannel() ? yieldViaMessageChannel() : yieldViaSetTimeout());\n    return;\n  }\n\n  if (strategy === 'message-channel') {\n    if (supportsMessageChannel()) {\n      await yieldViaMessageChannel();\n      return;\n    }\n    await yieldViaSetTimeout();\n    return;\n  }\n\n  await yieldViaSetTimeout();\n}\n\n/** `performance.now()` when available, `Date.now()` otherwise. Never throws. */\nexport function now(): number {\n  try {\n    if (typeof performance !== 'undefined' && typeof performance.now === 'function') {\n      return performance.now();\n    }\n  } catch {\n    // fall through\n  }\n  return Date.now();\n}\n\n/**\n * A time slice of zero, a negative number or NaN is meaningless, so those\n * fall back to the default rather than producing a task that yields after\n * every item (or never).\n */\nexport function normalizeTimeSliceMs(value: number | undefined): number {\n  if (typeof value !== 'number' || Number.isNaN(value) || value <= 0) {\n    return DEFAULT_TIME_SLICE_MS;\n  }\n  return value;\n}\n\n/**\n * Batch sizes are whole items, at least one. Anything else — a fraction,\n * zero, a negative, NaN — falls back to 1, the safe default.\n */\nexport function normalizeBatchSize(value: number | undefined): number {\n  if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) return 1;\n  return Math.floor(value);\n}\n\nexport interface ShouldYieldOptions {\n  /** `now()` timestamp when the current uninterrupted run of work began. */\n  sliceStartedAt: number;\n  /** Max ms to run before yielding regardless of input-pending state. */\n  timeSliceMs?: number;\n}\n\n/**\n * Whether the caller should yield right now: either the time slice has run\n * out, or the browser is reporting pending input (a stronger, earlier\n * signal than the clock — used only when the runtime exposes it).\n */\nexport function shouldYieldNow(options: ShouldYieldOptions): boolean {\n  const timeSliceMs = options.timeSliceMs ?? DEFAULT_TIME_SLICE_MS;\n  const elapsed = now() - options.sliceStartedAt;\n  if (elapsed >= timeSliceMs) return true;\n  return isInputPending();\n}\n","import {\n  type ChunkEvent,\n  type ChunkMachineState,\n  type ChunkStatus,\n  initialChunkState,\n  isTerminal,\n  transition,\n} from './chunk-machine.js';\nimport { createDiagnostics, isDevelopment, warnDev } from './diagnostics.js';\nimport {\n  type YieldStrategy,\n  normalizeBatchSize,\n  normalizeTimeSliceMs,\n  now,\n  resolveInputPending,\n  yieldToMain,\n} from './scheduler.js';\n\nexport interface ChunkSchedulerOptions<T, R> {\n  readonly items: readonly T[];\n  readonly processItem: (item: T, index: number) => R;\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\n  /**\n   * Items to process between clock checks. Default 1, which bounds a slice\n   * at one item: the safe choice, and the right one unless profiling says\n   * otherwise.\n   *\n   * Reading the clock costs around 300ns in a browser (where it is also\n   * coarsened to 0.1ms), so for items measured in nanoseconds that read,\n   * not the work, dominates. Raising this amortizes it — at the cost of\n   * checking the clock, pause and cancel only at batch boundaries, so a\n   * slice can run up to `batchSize` items past its budget. Pick a value\n   * whose worst-case cost you know: `batchSize * your slowest item` is the\n   * overshoot you are accepting.\n   */\n  readonly batchSize?: number;\n  /**\n   * Keep every result for `getResults()`. Default true. Set false when\n   * results are consumed through `onItem`: the array is then never built,\n   * which matters when `items` is large enough for retaining one result\n   * per item to cost real memory. `getResults()` then returns an empty\n   * array once the task settles.\n   */\n  readonly collectResults?: boolean;\n  /** Called after each item is successfully processed. */\n  readonly onItem?: (result: R, item: T, index: number) => void;\n  /**\n   * Called when `processItem` throws. Return `'skip'` to drop that one item\n   * and keep going — its index and error are recorded in `skipped`, on both\n   * the live snapshot and the settled result — or return `'abort'` to end\n   * the task the way it always has, as an `'error'` result carrying\n   * whatever was collected before the throw. Omitting `onItem` defaults to\n   * `'abort'`, so existing callers see no behavior change.\n   *\n   * Only ever called for `processItem` throwing. An `onItem` that throws\n   * still aborts unconditionally: that's the caller's own progress handler\n   * misbehaving, not a per-item failure there's anything to recover from.\n   */\n  readonly onError?: (error: unknown, item: T, index: number) => 'skip' | 'abort';\n  /** External cancellation source — aborting it is equivalent to calling cancel(). */\n  readonly signal?: AbortSignal;\n  /** Testing-only: forces a specific yield strategy instead of auto-detecting one. */\n  readonly yieldStrategy?: YieldStrategy;\n  /**\n   * Called every time a slice ends and the task is about to yield, with how\n   * long that slice ran and how many items are done so far. Unlike the\n   * development-only diagnostics above, this ships in the production\n   * build — wire it to your own telemetry so you can verify, on real\n   * traffic, that this task is actually staying under `timeSliceMs`,\n   * instead of trusting this package's own benchmark numbers.\n   */\n  readonly onSlice?: (durationMs: number, processed: number) => void;\n  /** Called right after each yield resolves and work is about to resume. Pairs with `onSlice`. */\n  readonly onYield?: () => void;\n}\n\n/** One item `onError` chose to skip, in the order it happened. */\nexport interface SkippedChunkItem {\n  readonly index: number;\n  readonly error: unknown;\n}\n\nexport interface ChunkSchedulerResult<R> {\n  readonly status: 'done' | 'cancelled' | 'error';\n  readonly results: readonly R[];\n  readonly error?: unknown;\n  /** Items `onError` skipped. Omitted when nothing was skipped. */\n  readonly skipped?: readonly SkippedChunkItem[];\n  /**\n   * The `AbortSignal`'s `reason`, present only when this cancellation came\n   * from that signal aborting rather than a direct `cancel()` call.\n   */\n  readonly reason?: unknown;\n}\n\nexport interface ChunkSnapshot<R = unknown> {\n  readonly status: ChunkStatus;\n  readonly processed: number;\n  readonly total: number;\n  readonly error?: unknown;\n  /**\n   * Present only once the task has settled, and always in the same\n   * snapshot that first reports a terminal status — so a reader can never\n   * observe `status: 'done'` without the results that go with it.\n   */\n  readonly results?: readonly R[];\n  /**\n   * Items `onError` has skipped so far — growing live as skips happen,\n   * unlike `results` above: there's nothing unsafe about reading this\n   * mid-run. Omitted entirely until the first skip.\n   */\n  readonly skipped?: readonly SkippedChunkItem[];\n  /**\n   * The `AbortSignal`'s `reason`, present as soon as that signal aborts —\n   * before the task finishes settling, the same as `error` above.\n   */\n  readonly reason?: unknown;\n}\n\nexport interface ChunkScheduler<R> {\n  start(): void;\n  pause(): void;\n  resume(): void;\n  cancel(): void;\n  getSnapshot(): ChunkSnapshot<R>;\n  /**\n   * The accumulated results, but only once the task has reached a terminal\n   * state — `undefined` while idle/processing/paused. Computed once, cheaply,\n   * at the moment of that transition; never recomputed on every item, so\n   * reading it (e.g. every time the snapshot changes) never costs an O(n)\n   * array copy per item for a large task. For incremental consumption while\n   * the task is still running, use the `onItem` option instead.\n   */\n  getResults(): readonly R[] | undefined;\n  subscribe(listener: () => void): () => void;\n  /** Resolves exactly once, when the task reaches a terminal state. Never rejects. */\n  readonly settled: Promise<ChunkSchedulerResult<R>>;\n}\n\n/**\n * `items[index]` for an index the caller has already bounds-checked.\n *\n * The loop below only ever indexes below `items.length`, but\n * `noUncheckedIndexedAccess` widens every index read to `T | undefined`,\n * and `T` may itself include `undefined` — so no runtime check can narrow\n * it. This states the invariant in one place instead of asserting at each\n * use, and compiles to a plain index read.\n */\nfunction at<T>(items: readonly T[], index: number): T {\n  return items[index] as T;\n}\n\n/**\n * Loose, `typeof`-only thenable check — the same test `await` itself uses,\n * not an `instanceof Promise` (which would miss any other Promise-like:\n * a different realm's Promise, a userland polyfill). Good enough for a\n * one-shot development warning; never throws on anything a caller could\n * plausibly have returned.\n */\nfunction isThenable(value: unknown): boolean {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    typeof (value as { then?: unknown }).then === 'function'\n  );\n}\n\n/**\n * Builds a one-shot, controllable scheduler that processes `items` through\n * `processItem`, yielding to the main thread on a time budget (and sooner,\n * if the browser reports pending input) so a large array never produces a\n * single long task.\n *\n * One-shot means exactly that: once the task reaches `done`, `cancelled` or\n * `error`, this instance is finished — start()/pause()/resume() on it are\n * no-ops from then on. To run another task, create another scheduler. For a\n * React hook, that falls out naturally: new deps → new effect → new\n * scheduler, which is the idiomatic React data-flow anyway.\n */\nexport function createChunkScheduler<T, R>(\n  options: ChunkSchedulerOptions<T, R>,\n): ChunkScheduler<R> {\n  const { items, processItem, onItem, onError, signal, yieldStrategy, onSlice, onYield } =\n    options;\n  const timeSliceMs = normalizeTimeSliceMs(options.timeSliceMs);\n  const batchSize = normalizeBatchSize(options.batchSize);\n  const collectResults = options.collectResults ?? true;\n  const total = items.length;\n\n  if (isDevelopment && !collectResults && onItem === undefined) {\n    warnDev(\n      'collectResults is false and no onItem was passed — every result will be computed and then discarded, with nothing to retrieve once the task settles. Pass onItem to consume results as they finish, or drop collectResults: false if you need the final array.',\n    );\n  }\n\n  // Resolved once per scheduler, not per item: the feature detection behind\n  // it walks `navigator.scheduling.isInputPending` through optional calls,\n  // which is wasted work on every item of a million-item task.\n  const inputPending = resolveInputPending();\n  const diagnostics = createDiagnostics('item', batchSize);\n  let warnedAboutAsyncResult = false;\n\n  let machineState: ChunkMachineState = initialChunkState;\n  let processed = 0;\n  let loopStarted = false;\n  let settledFlag = false;\n  const results: R[] = [];\n  let finalResults: readonly R[] | undefined;\n  const skipped: SkippedChunkItem[] = [];\n  let cancelReason: unknown;\n\n  // Built on demand rather than after every item. useSyncExternalStore\n  // requires repeated calls between notifications to return the *same*\n  // reference, which `snapshot` holds until something actually changes;\n  // `snapshotStale` is what marks it as needing a rebuild. Allocating a\n  // fresh snapshot per item (as this once did) is pure garbage for a task\n  // that only publishes progress at slice boundaries.\n  let snapshot: ChunkSnapshot<R> = { status: machineState.status, processed, total };\n  let snapshotStale = false;\n  const listeners = new Set<() => void>();\n\n  let settleFn!: (result: ChunkSchedulerResult<R>) => void;\n  const settledPromise = new Promise<ChunkSchedulerResult<R>>((resolve) => {\n    settleFn = resolve;\n  });\n\n  // The gate a paused loop blocks on. Recreated per pause; opened by either\n  // resume() or cancel() so a cancelled-while-paused task can never hang.\n  let pauseResolve: (() => void) | undefined;\n  let pausePromise: Promise<void> | undefined;\n\n  function waitForWake(): Promise<void> {\n    pausePromise ??= new Promise((resolve) => {\n      pauseResolve = resolve;\n    });\n    return pausePromise;\n  }\n\n  function openGate(): void {\n    pauseResolve?.();\n    pauseResolve = undefined;\n    pausePromise = undefined;\n  }\n\n  function notify(): void {\n    for (const listener of listeners) listener();\n  }\n\n  function getSnapshot(): ChunkSnapshot<R> {\n    if (snapshotStale) {\n      snapshotStale = false;\n      snapshot = {\n        status: machineState.status,\n        processed,\n        total,\n        ...(machineState.error !== undefined ? { error: machineState.error } : {}),\n        ...(finalResults !== undefined ? { results: finalResults } : {}),\n        ...(skipped.length > 0 ? { skipped: skipped.slice() } : {}),\n        ...(cancelReason !== undefined ? { reason: cancelReason } : {}),\n      };\n    }\n    return snapshot;\n  }\n\n  function dispatch(event: ChunkEvent): { changed: boolean } {\n    const next = transition(machineState, event);\n    const changed = next !== machineState;\n    if (changed) {\n      machineState = next;\n      snapshotStale = true;\n      notify();\n    }\n    return { changed };\n  }\n\n  function settle(result: ChunkSchedulerResult<R>): void {\n    // Structurally unreachable, not merely untested: `finish()` — the only\n    // caller of `settle()` — is itself only ever reached from one of two\n    // mutually exclusive places, each gated by `loopStarted`: runLoop()'s\n    // own completion (which only runs after `loopStarted` was already set\n    // true by start()) or settleIfNeverStarted() (which refuses to run\n    // once `loopStarted` is true). Either way, by the time this instance\n    // can ever reach a terminal state the second time, there is no longer\n    // any code path left that would call settle() again. Kept anyway as\n    // defense-in-depth against a future refactor breaking that invariant.\n    /* v8 ignore next */\n    if (settledFlag) return;\n    settledFlag = true;\n    detachSignal();\n    settleFn(result);\n  }\n\n  /**\n   * Publishes the accumulated results exactly once, at the moment the task\n   * settles — not per item, and never as a second copy. Always called\n   * *before* the terminal status is announced, so the notification that\n   * reports `done` already carries the results: a subscriber can never\n   * observe one without the other.\n   */\n  function publishResults(): readonly R[] {\n    finalResults = results;\n    snapshotStale = true;\n    return finalResults;\n  }\n\n  function settleWith(\n    status: 'done' | 'cancelled' | 'error',\n    published: readonly R[],\n    error?: unknown,\n  ): void {\n    settle({\n      status,\n      results: published,\n      ...(error !== undefined ? { error } : {}),\n      ...(skipped.length > 0 ? { skipped: skipped.slice() } : {}),\n      ...(status === 'cancelled' && cancelReason !== undefined\n        ? { reason: cancelReason }\n        : {}),\n    });\n  }\n\n  /**\n   * Settling as cancelled, for both places that can do it: the loop\n   * noticing, and cancel() on a task whose loop never ran. The CANCEL\n   * transition was announced earlier, before there were any results to\n   * carry, so this notifies again now that there are.\n   */\n  function finishCancelled(): void {\n    settleWith('cancelled', publishResults());\n    notify();\n  }\n\n  // If the machine reached a terminal state without the processing loop\n  // ever running (e.g. cancel() called before start(), or the signal was\n  // already aborted), the loop will never call finish() itself — so this\n  // does it. Guarded by !loopStarted, which this also sets, so it can never\n  // race with (or double-finish against) the loop's own completion path.\n  function settleIfNeverStarted(): void {\n    const { status } = machineState;\n    if (loopStarted || !isTerminal(status)) return;\n    loopStarted = true;\n    // 'cancelled' is the only status reachable here: 'done' and 'error'\n    // both require the loop to have run, and that sets `loopStarted`,\n    // which short-circuits this function above.\n    finishCancelled();\n  }\n\n  function handleAbort(): void {\n    cancelReason = signal?.reason;\n    cancel();\n  }\n\n  function detachSignal(): void {\n    signal?.removeEventListener('abort', handleAbort);\n  }\n\n  if (signal?.aborted) {\n    cancelReason = signal.reason;\n    dispatch({ type: 'CANCEL' });\n  } else {\n    signal?.addEventListener('abort', handleAbort);\n  }\n\n  async function runLoop(): Promise<void> {\n    let sliceStartedAt = now();\n    let index = 0;\n\n    try {\n      while (index < total) {\n        // Re-read on every pass rather than trusting a single wake from the\n        // pause gate: a resume() can be undone by a *reentrant* pause()\n        // triggered synchronously from a subscriber's own notification\n        // (resume() dispatches, notify() runs listeners synchronously, a\n        // listener calls pause() before resume() returns). Continuing the\n        // loop instead of falling through is what lets this see that and\n        // block again on a fresh gate, without consuming an item.\n        const status: ChunkStatus = machineState.status;\n        if (status === 'cancelled') break;\n        if (status === 'paused') {\n          await waitForWake();\n          sliceStartedAt = now();\n          if (isDevelopment) diagnostics.resumed(sliceStartedAt, index);\n          continue;\n        }\n\n        // One batch between clock checks. At the default batchSize of 1\n        // this is exactly \"one item, then check\", and the inner loop costs\n        // nothing beyond the comparison.\n        const batchEnd = index + batchSize <= total ? index + batchSize : total;\n        while (index < batchEnd) {\n          const item = at(items, index);\n          let result: R;\n          try {\n            result = processItem(item, index);\n          } catch (caught) {\n            // Default ('abort', same as omitting onError) rethrows into the\n            // outer try below, so a caller with no onError sees exactly the\n            // same error-and-stop behavior this always had.\n            if ((onError?.(caught, item, index) ?? 'abort') !== 'skip') throw caught;\n            skipped.push({ index, error: caught });\n            processed = index + 1;\n            snapshotStale = true;\n            index += 1;\n            continue;\n          }\n          if (isDevelopment && !warnedAboutAsyncResult && isThenable(result)) {\n            warnedAboutAsyncResult = true;\n            warnDev(\n              'processItem returned a Promise. createChunkScheduler calls it synchronously and never awaits the result, so results will contain unresolved Promise objects instead of the values they resolve to. Resolve the value before returning it, or chunk the async work a different way.',\n            );\n          }\n          if (collectResults) results.push(result);\n          processed = index + 1;\n          onItem?.(result, item, index);\n          index += 1;\n        }\n        snapshotStale = true;\n\n        // One clock read per batch, shared by the budget check and the\n        // development diagnostics. Both diagnostic calls compile away in a\n        // production build, along with this module.\n        const checkedAt = now();\n        if (isDevelopment) diagnostics.check(checkedAt, index);\n\n        if (checkedAt - sliceStartedAt >= timeSliceMs || inputPending()) {\n          if (isDevelopment) diagnostics.sliceEnded(checkedAt, index);\n          onSlice?.(checkedAt - sliceStartedAt, index);\n          await yieldToMain(\n            yieldStrategy !== undefined ? { strategy: yieldStrategy } : undefined,\n          );\n          notify(); // surface the progress made during this slice\n          sliceStartedAt = now();\n          onYield?.();\n          if (isDevelopment) diagnostics.resumed(sliceStartedAt, index);\n        }\n      }\n    } catch (error) {\n      const published = publishResults();\n      dispatch({ type: 'ERROR', error });\n      settleWith('error', published, error);\n      return;\n    }\n\n    if (machineState.status === 'cancelled') {\n      finishCancelled();\n      return;\n    }\n\n    const published = publishResults();\n    dispatch({ type: 'COMPLETE' });\n    settleWith('done', published);\n  }\n\n  function start(): void {\n    dispatch({ type: 'START' });\n    if (machineState.status === 'processing' && !loopStarted) {\n      loopStarted = true;\n      void runLoop();\n    }\n    settleIfNeverStarted();\n  }\n\n  function pause(): void {\n    dispatch({ type: 'PAUSE' });\n  }\n\n  function resume(): void {\n    const { changed } = dispatch({ type: 'RESUME' });\n    if (changed) openGate();\n  }\n\n  function cancel(): void {\n    dispatch({ type: 'CANCEL' });\n    openGate();\n    settleIfNeverStarted();\n  }\n\n  return {\n    start,\n    pause,\n    resume,\n    cancel,\n    getSnapshot,\n    getResults: () => finalResults,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    settled: settledPromise,\n  };\n}\n","import {\n  type ChunkEvent,\n  type ChunkMachineState,\n  type ChunkStatus,\n  initialChunkState,\n  isTerminal,\n  transition,\n} from './chunk-machine.js';\nimport { createDiagnostics, isDevelopment } from './diagnostics.js';\nimport {\n  type YieldStrategy,\n  normalizeBatchSize,\n  normalizeTimeSliceMs,\n  now,\n  resolveInputPending,\n  yieldToMain,\n} from './scheduler.js';\n\n/**\n * A generator is how you tell `createDeferredTask` where it's safe to yield\n * — arbitrary heavy work (a multi-phase algorithm, a big canvas render)\n * doesn't have a natural \"array of items\" shape the way `createChunkScheduler`\n * expects, so instead you mark checkpoints yourself:\n *\n * ```ts\n * function* renderFrames(frameCount: number) {\n *   for (let i = 0; i < frameCount; i++) {\n *     renderOneExpensiveFrame(i);\n *     yield; // \"it's safe to pause here if we're over budget\"\n *   }\n *   return frameCount;\n * }\n * ```\n *\n * Everything between two `yield`s runs as one uninterruptible synchronous\n * segment — put them wherever your function can safely stop, the same way\n * you'd think about chunk boundaries by hand, just without writing the\n * scheduling code yourself.\n */\nexport type DeferredGenerator<T> = Generator<void, T, void>;\n\nexport interface DeferredTaskOptions<T> {\n  readonly task: () => DeferredGenerator<T>;\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\n  /**\n   * Segments (the code between two `yield`s) to run between clock checks.\n   * Default 1, which bounds a slice at one segment.\n   *\n   * Reading the clock costs around 300ns in a browser, so a generator that\n   * yields after a few nanoseconds of work spends most of its time asking\n   * the time. Raising this amortizes that — at the cost of checking the\n   * clock, pause and cancel only at batch boundaries, so a slice can run up\n   * to `batchSize` segments past its budget.\n   */\n  readonly batchSize?: number;\n  readonly signal?: AbortSignal;\n  /** Testing-only: forces a specific yield strategy instead of auto-detecting one. */\n  readonly yieldStrategy?: YieldStrategy;\n  /**\n   * Called every time a segment-batch ends and the task is about to yield,\n   * with how long that slice ran and how many segments are done so far.\n   * Ships in the production build — see the identical option on\n   * `createChunkScheduler` for why.\n   */\n  readonly onSlice?: (durationMs: number, segmentsDone: number) => void;\n  /** Called right after each yield resolves and work is about to resume. Pairs with `onSlice`. */\n  readonly onYield?: () => void;\n}\n\nexport interface DeferredTaskResult<T> {\n  readonly status: 'done' | 'cancelled' | 'error';\n  readonly value?: T;\n  readonly error?: unknown;\n  /**\n   * The `AbortSignal`'s `reason`, present only when this cancellation came\n   * from that signal aborting rather than a direct `cancel()` call.\n   */\n  readonly reason?: unknown;\n}\n\nexport interface DeferredTaskSnapshot<T = unknown> {\n  readonly status: ChunkStatus;\n  readonly error?: unknown;\n  /**\n   * Present only once the task has settled with `done`, and always in the\n   * same snapshot that first reports it — so a reader can never observe\n   * `status: 'done'` without the value that goes with it.\n   */\n  readonly value?: T;\n  /**\n   * The `AbortSignal`'s `reason`, present as soon as that signal aborts —\n   * before the task finishes settling, the same as `error` above.\n   */\n  readonly reason?: unknown;\n}\n\nexport interface DeferredTask<T> {\n  start(): void;\n  pause(): void;\n  resume(): void;\n  cancel(): void;\n  getSnapshot(): DeferredTaskSnapshot<T>;\n  /** The returned value once the task has settled with `done` — `undefined` otherwise. */\n  getValue(): T | undefined;\n  subscribe(listener: () => void): () => void;\n  readonly settled: Promise<DeferredTaskResult<T>>;\n}\n\n/**\n * The generator-driven sibling of `createChunkScheduler`, for heavy work\n * that isn't shaped like \"one function applied to each item of an array\".\n * Same state machine, same yield primitives, same one-shot-instance\n * contract — see that file's doc comment for the reasoning, which applies\n * here unchanged.\n */\nexport function createDeferredTask<T>(options: DeferredTaskOptions<T>): DeferredTask<T> {\n  const { task, signal, yieldStrategy, onSlice, onYield } = options;\n  const timeSliceMs = normalizeTimeSliceMs(options.timeSliceMs);\n  const batchSize = normalizeBatchSize(options.batchSize);\n  // Resolved once per task rather than per segment; see chunk-scheduler.ts.\n  const inputPending = resolveInputPending();\n  const diagnostics = createDiagnostics('segment', batchSize);\n\n  let machineState: ChunkMachineState = initialChunkState;\n  let loopStarted = false;\n  let settledFlag = false;\n  let settledValue: T | undefined;\n  let cancelReason: unknown;\n\n  // Built on demand, and only when something has actually changed.\n  // useSyncExternalStore requires repeated calls between notifications to\n  // return the *same* reference; a fresh object literal on every call (as\n  // this used to be) reads as \"changed every render\" and sends React into\n  // an infinite re-render loop. Mirrors chunk-scheduler.ts exactly.\n  let snapshot: DeferredTaskSnapshot<T> = { status: machineState.status };\n  let snapshotStale = false;\n\n  const listeners = new Set<() => void>();\n\n  let settleFn!: (result: DeferredTaskResult<T>) => void;\n  const settledPromise = new Promise<DeferredTaskResult<T>>((resolve) => {\n    settleFn = resolve;\n  });\n\n  let pauseResolve: (() => void) | undefined;\n  let pausePromise: Promise<void> | undefined;\n\n  function waitForWake(): Promise<void> {\n    pausePromise ??= new Promise((resolve) => {\n      pauseResolve = resolve;\n    });\n    return pausePromise;\n  }\n\n  function openGate(): void {\n    pauseResolve?.();\n    pauseResolve = undefined;\n    pausePromise = undefined;\n  }\n\n  function notify(): void {\n    for (const listener of listeners) listener();\n  }\n\n  function getSnapshot(): DeferredTaskSnapshot<T> {\n    if (snapshotStale) {\n      snapshotStale = false;\n      snapshot = {\n        status: machineState.status,\n        ...(machineState.error !== undefined ? { error: machineState.error } : {}),\n        ...(settledValue !== undefined ? { value: settledValue } : {}),\n        ...(cancelReason !== undefined ? { reason: cancelReason } : {}),\n      };\n    }\n    return snapshot;\n  }\n\n  function dispatch(event: ChunkEvent): { changed: boolean } {\n    const next = transition(machineState, event);\n    const changed = next !== machineState;\n    if (changed) {\n      machineState = next;\n      snapshotStale = true;\n      notify();\n    }\n    return { changed };\n  }\n\n  function settle(result: DeferredTaskResult<T>): void {\n    // Structurally unreachable, not merely untested — see the identical\n    // guard in chunk-scheduler.ts's settle() for the full invariant: the\n    // only caller, finish(), is reached from exactly one of two mutually\n    // exclusive, `loopStarted`-gated paths per instance, so there is never\n    // a second call left to make once this instance has settled once.\n    // Kept as defense-in-depth against a future refactor breaking that.\n    /* v8 ignore next */\n    if (settledFlag) return;\n    settledFlag = true;\n    detachSignal();\n    settleFn(result);\n  }\n\n  /**\n   * Publishes the returned value before the terminal status is announced,\n   * so the notification that reports `done` already carries it.\n   */\n  function publishValue(resolvedValue: T | undefined): void {\n    settledValue = resolvedValue;\n    snapshotStale = true;\n  }\n\n  function settleWith(\n    status: 'done' | 'cancelled' | 'error',\n    resolvedValue?: T,\n    error?: unknown,\n  ): void {\n    if (status === 'done') {\n      settle({\n        status,\n        ...(resolvedValue !== undefined ? { value: resolvedValue } : {}),\n      });\n      return;\n    }\n    if (status === 'error') {\n      settle({ status, error });\n      return;\n    }\n    settle({ status, ...(cancelReason !== undefined ? { reason: cancelReason } : {}) });\n  }\n\n  /**\n   * Settling as cancelled, for both places that can do it. The CANCEL\n   * transition was announced earlier, so this notifies again now that the\n   * task has actually settled.\n   */\n  function finishCancelled(): void {\n    settleWith('cancelled');\n    notify();\n  }\n\n  function settleIfNeverStarted(): void {\n    const { status } = machineState;\n    if (loopStarted || !isTerminal(status)) return;\n    loopStarted = true;\n    // 'cancelled' is the only status reachable here: 'done' and 'error'\n    // both require the loop to have run, and that sets `loopStarted`,\n    // which short-circuits this function above.\n    finishCancelled();\n  }\n\n  function handleAbort(): void {\n    cancelReason = signal?.reason;\n    cancel();\n  }\n\n  function detachSignal(): void {\n    signal?.removeEventListener('abort', handleAbort);\n  }\n\n  if (signal?.aborted) {\n    cancelReason = signal.reason;\n    dispatch({ type: 'CANCEL' });\n  } else {\n    signal?.addEventListener('abort', handleAbort);\n  }\n\n  async function runLoop(): Promise<void> {\n    let sliceStartedAt = now();\n    let segment = 0;\n    const generator = task();\n\n    // `step` always holds the result of the *last* generator.next() call —\n    // including, on an early break below, a stale not-done step from before\n    // that break, which the post-loop checks account for explicitly.\n    let step: IteratorResult<void, T> = { done: false, value: undefined };\n    try {\n      for (;;) {\n        // Captured once per iteration and compared via this local, not via\n        // repeated `machineState.status` property reads — narrowing a\n        // direct property access to a literal here would otherwise survive\n        // (in TS's eyes) across the `await` below, even though the whole\n        // point of that await is that `machineState` can change out from\n        // under us while it's pending.\n        const status: ChunkStatus = machineState.status;\n        if (status === 'cancelled') {\n          generator.return(undefined as unknown as T);\n          break;\n        }\n\n        if (status === 'paused') {\n          await waitForWake();\n          sliceStartedAt = now();\n          if (isDevelopment) diagnostics.resumed(sliceStartedAt, segment);\n          // Don't fall through to generator.next() just because the gate\n          // opened — re-enter the loop and read machineState.status fresh.\n          // A resume() can be undone by a *reentrant* pause() triggered\n          // synchronously from a subscriber's own notification (resume()\n          // dispatches, notify() runs listeners synchronously, a listener\n          // calls pause() before resume() returns) — so waking from one\n          // gate is not proof we're actually clear to proceed. Looping\n          // back here is what lets the top-of-loop checks see that and\n          // either re-block on a fresh gate (status is paused again) or\n          // notice cancellation, instead of blindly running one more\n          // generator step first.\n          continue;\n        }\n\n        // The cancellation check above MUST run before this call, not\n        // after: calling the generator is where its actual (synchronous)\n        // work for this segment happens. An earlier draft called\n        // generator.next() at the *bottom* of the loop, right after the\n        // yieldToMain() await below — so a cancel() landing during that\n        // await would still let one more segment's worth of work run\n        // before the next loop iteration finally noticed. Checking first,\n        // every time, closes that race: nothing the generator does can run\n        // once cancellation has been observed.\n        // One batch of segments between clock checks. At the default\n        // batchSize of 1 this runs exactly one segment, then checks.\n        let done = false;\n        for (let inBatch = 0; inBatch < batchSize; inBatch++) {\n          step = generator.next();\n          segment += 1;\n          if (step.done) {\n            done = true;\n            break;\n          }\n        }\n        if (done) break;\n\n        // One clock read per batch, shared by the budget check and the\n        // development diagnostics, which compile away in production.\n        const checkedAt = now();\n        if (isDevelopment) diagnostics.check(checkedAt, segment);\n\n        if (checkedAt - sliceStartedAt >= timeSliceMs || inputPending()) {\n          if (isDevelopment) diagnostics.sliceEnded(checkedAt, segment);\n          onSlice?.(checkedAt - sliceStartedAt, segment);\n          await yieldToMain(\n            yieldStrategy !== undefined ? { strategy: yieldStrategy } : undefined,\n          );\n          notify();\n          sliceStartedAt = now();\n          onYield?.();\n          if (isDevelopment) diagnostics.resumed(sliceStartedAt, segment);\n        }\n      }\n    } catch (error) {\n      dispatch({ type: 'ERROR', error });\n      settleWith('error', undefined, error);\n      return;\n    }\n\n    if (machineState.status === 'cancelled') {\n      finishCancelled();\n      return;\n    }\n\n    // step.done is always true by the time we get here: the only ways out\n    // of the loop above are the top-of-loop 'cancelled' break (handled by\n    // the early return just above, before this line) and the batch loop's\n    // own `done` break — so the \": undefined\" side of this ternary can't\n    // actually run. It stays only because it's what makes TypeScript\n    // narrow step.value's type correctly; the real type is kept rather\n    // than cast away.\n    /* v8 ignore next */\n    const returned = step.done ? step.value : undefined;\n    publishValue(returned);\n    dispatch({ type: 'COMPLETE' });\n    settleWith('done', returned);\n  }\n\n  function start(): void {\n    dispatch({ type: 'START' });\n    if (machineState.status === 'processing' && !loopStarted) {\n      loopStarted = true;\n      void runLoop();\n    }\n    settleIfNeverStarted();\n  }\n\n  function pause(): void {\n    dispatch({ type: 'PAUSE' });\n  }\n\n  function resume(): void {\n    const { changed } = dispatch({ type: 'RESUME' });\n    if (changed) openGate();\n  }\n\n  function cancel(): void {\n    dispatch({ type: 'CANCEL' });\n    openGate();\n    settleIfNeverStarted();\n  }\n\n  return {\n    start,\n    pause,\n    resume,\n    cancel,\n    getSnapshot,\n    getValue: () => settledValue,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    settled: settledPromise,\n  };\n}\n"],"mappings":"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"}

package/dist/production/index.cjs

@@ -0,0 +1,216 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+const require_deferred_task = require("./deferred-task-yh5pWlSj.cjs");
+let react = require("react");
+react = __toESM(react, 1);
+// src/react/task-controller.ts
+function createTaskController() {
+	let current = null;
+	let detachFromCurrent;
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => {
+		for (const listener of listeners) listener();
+	};
+	return {
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		getSnapshot: () => current?.getSnapshot(),
+		getCurrent: () => current,
+		replace: (task) => {
+			detachFromCurrent?.();
+			current = task;
+			detachFromCurrent = task?.subscribe(notify);
+			notify();
+		}
+	};
+}
+// src/react/use-effect-event.ts
+function useEffectEventFallback(callback) {
+	const latest = (0, react.useRef)(callback);
+	(0, react.useInsertionEffect)(() => {
+		latest.current = callback;
+	});
+	return (0, react.useCallback)((...args) => latest.current(...args), []);
+}
+const useEffectEvent = react.useEffectEvent ?? useEffectEventFallback;
+// src/react/useChunkedTask.ts
+/** Stable empty array so a never-skipped task doesn't hand out a fresh `[]` every render. */
+const NO_SKIPPED = [];
+const IDLE_STATUS = "idle";
+/**
+* Chunks a heavy, synchronous per-item computation over `items` so it never
+* blocks the main thread for longer than a time slice — the thing that
+* costs you Interaction to Next Paint. Starts automatically by default;
+* pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.
+* behind a button).
+*
+* `processItem` and `onItem` can be fresh closures every render — the hook
+* always calls the latest version (via `useEffectEvent`) without that
+* causing the task to restart. What *does* restart the task is `items`
+* changing identity (a new array reference), or `timeSliceMs`/`autoStart`
+* changing. That's deliberate: a new `items` array means new work, and
+* memoizing it when you don't want that is the caller's call to make, the
+* same as any other React dependency.
+*/
+function useChunkedTask(items, processItem, options) {
+	const { timeSliceMs, batchSize, collectResults, autoStart = true, onItem, onError, onSlice, onYield } = options ?? {};
+	const stableProcessItem = useEffectEvent((item, index) => processItem(item, index));
+	const stableOnItem = useEffectEvent((result, item, index) => {
+		onItem?.(result, item, index);
+	});
+	const stableOnError = useEffectEvent((error, item, index) => onError?.(error, item, index) ?? "abort");
+	const stableOnSlice = useEffectEvent((durationMs, processed) => {
+		onSlice?.(durationMs, processed);
+	});
+	const stableOnYield = useEffectEvent(() => {
+		onYield?.();
+	});
+	const [controller] = (0, react.useState)(() => createTaskController());
+	const idleSnapshot = (0, react.useMemo)(() => ({
+		status: IDLE_STATUS,
+		processed: 0,
+		total: items.length
+	}), [items.length]);
+	const snapshot = (0, react.useSyncExternalStore)(controller.subscribe, () => controller.getSnapshot() ?? idleSnapshot, () => idleSnapshot);
+	(0, react.useEffect)(() => {
+		const scheduler = require_deferred_task.createChunkScheduler({
+			items,
+			processItem: stableProcessItem,
+			onItem: stableOnItem,
+			onError: stableOnError,
+			onSlice: stableOnSlice,
+			onYield: stableOnYield,
+			...timeSliceMs !== void 0 ? { timeSliceMs } : {},
+			...batchSize !== void 0 ? { batchSize } : {},
+			...collectResults !== void 0 ? { collectResults } : {}
+		});
+		controller.replace(scheduler);
+		if (autoStart) scheduler.start();
+		return () => {
+			scheduler.cancel();
+			controller.replace(null);
+		};
+	}, [
+		items,
+		timeSliceMs,
+		batchSize,
+		collectResults,
+		autoStart,
+		controller
+	]);
+	const start = (0, react.useCallback)(() => controller.getCurrent()?.start(), [controller]);
+	const pause = (0, react.useCallback)(() => controller.getCurrent()?.pause(), [controller]);
+	const resume = (0, react.useCallback)(() => controller.getCurrent()?.resume(), [controller]);
+	const cancel = (0, react.useCallback)(() => controller.getCurrent()?.cancel(), [controller]);
+	return {
+		status: snapshot.status,
+		processed: snapshot.processed,
+		total: snapshot.total,
+		error: snapshot.error,
+		results: snapshot.results,
+		skipped: snapshot.skipped ?? NO_SKIPPED,
+		isIdle: snapshot.status === "idle",
+		isProcessing: snapshot.status === "processing",
+		isPaused: snapshot.status === "paused",
+		isDone: snapshot.status === "done",
+		isCancelled: snapshot.status === "cancelled",
+		isError: snapshot.status === "error",
+		start,
+		pause,
+		resume,
+		cancel
+	};
+}
+// src/react/useDeferredTask.ts
+const IDLE_SNAPSHOT = { status: "idle" };
+/**
+* Runs an arbitrary heavy, synchronous generator function in chunks, so it
+* never produces a long task on its own. Where `useChunkedTask` chunks "one
+* function applied to every item of an array" automatically, this hook
+* leaves the chunk boundaries to you — put `yield` wherever your function
+* can safely pause (see `DeferredGenerator`'s doc comment for an example).
+*
+* `task` is only called when the effect (re)creates the underlying task, not
+* on every render — list whatever it closes over in `deps`, the same way
+* you would for `useMemo` or `useEffect`.
+*/
+function useDeferredTask(task, deps, options) {
+	const { timeSliceMs, batchSize, autoStart = true, onSlice, onYield } = options ?? {};
+	const stableTask = useEffectEvent(() => task());
+	const stableOnSlice = useEffectEvent((durationMs, segmentsDone) => {
+		onSlice?.(durationMs, segmentsDone);
+	});
+	const stableOnYield = useEffectEvent(() => {
+		onYield?.();
+	});
+	const [controller] = (0, react.useState)(() => createTaskController());
+	const snapshot = (0, react.useSyncExternalStore)(controller.subscribe, () => controller.getSnapshot() ?? IDLE_SNAPSHOT, () => IDLE_SNAPSHOT);
+	(0, react.useEffect)(() => {
+		const deferredTask = require_deferred_task.createDeferredTask({
+			task: stableTask,
+			onSlice: stableOnSlice,
+			onYield: stableOnYield,
+			...timeSliceMs !== void 0 ? { timeSliceMs } : {},
+			...batchSize !== void 0 ? { batchSize } : {}
+		});
+		controller.replace(deferredTask);
+		if (autoStart) deferredTask.start();
+		return () => {
+			deferredTask.cancel();
+			controller.replace(null);
+		};
+	}, [
+		...deps,
+		timeSliceMs,
+		batchSize,
+		autoStart,
+		controller
+	]);
+	const start = (0, react.useCallback)(() => controller.getCurrent()?.start(), [controller]);
+	const pause = (0, react.useCallback)(() => controller.getCurrent()?.pause(), [controller]);
+	const resume = (0, react.useCallback)(() => controller.getCurrent()?.resume(), [controller]);
+	const cancel = (0, react.useCallback)(() => controller.getCurrent()?.cancel(), [controller]);
+	return {
+		status: snapshot.status,
+		error: snapshot.error,
+		value: snapshot.value,
+		isIdle: snapshot.status === "idle",
+		isProcessing: snapshot.status === "processing",
+		isPaused: snapshot.status === "paused",
+		isDone: snapshot.status === "done",
+		isCancelled: snapshot.status === "cancelled",
+		isError: snapshot.status === "error",
+		start,
+		pause,
+		resume,
+		cancel
+	};
+}
+exports.useChunkedTask = useChunkedTask;
+exports.useDeferredTask = useDeferredTask;
+
+//# sourceMappingURL=index.cjs.map

package/dist/production/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["useRef","useCallback","React","useState","useMemo","useSyncExternalStore","createChunkScheduler","useCallback","useState","useSyncExternalStore","createDeferredTask","useCallback"],"sources":["../../src/react/task-controller.ts","../../src/react/use-effect-event.ts","../../src/react/useChunkedTask.ts","../../src/react/useDeferredTask.ts"],"sourcesContent":["/**\n * The glue between a task handle (`ChunkScheduler<R>`, `DeferredTask<T>` —\n * anything with `subscribe`/`getSnapshot`) recreated from scratch whenever a\n * hook's deps change, inside an effect, and `useSyncExternalStore`, which\n * wants one stable `subscribe` function for a component's whole lifetime.\n *\n * `useSyncExternalStore` resubscribes whenever the `subscribe` function\n * identity changes — fine for correctness, but it means the naive approach\n * (pass the current task's own `.subscribe` directly) either churns\n * subscriptions every render or, worse, drifts: the component keeps\n * `subscribe`d to whichever task was current when it last resubscribed, not\n * necessarily the one `getSnapshot` is reading from after a swap.\n *\n * A controller sidesteps that: it's created once per hook instance (lazy\n * `useState` initializer in the hook, so it's stable without touching a\n * ref), hands `useSyncExternalStore` a `subscribe`/`getSnapshot` pair that\n * never change identity, and internally forwards to whichever task is\n * \"current\" — re-pointing itself via `replace()` every time the effect\n * swaps in a new one. Generic over the task shape so both `useChunkedTask`\n * and `useDeferredTask` share this one implementation.\n *\n * Every property below is an arrow function, deliberately — not method\n * shorthand — so none of them close over `this`, and `controller.subscribe`\n * can be handed to `useSyncExternalStore` directly as a plain function\n * reference without an unbound-method footgun.\n */\nexport interface SubscribableTask<Snapshot> {\n  subscribe(listener: () => void): () => void;\n  getSnapshot(): Snapshot;\n}\n\nexport interface TaskController<Task extends SubscribableTask<unknown>> {\n  subscribe: (listener: () => void) => () => void;\n  getSnapshot: () => ReturnType<Task['getSnapshot']> | undefined;\n  getCurrent: () => Task | null;\n  /** Swaps in a new task (or none), detaching from the previous one first. */\n  replace: (task: Task | null) => void;\n}\n\nexport function createTaskController<\n  Task extends SubscribableTask<unknown>,\n>(): TaskController<Task> {\n  let current: Task | null = null;\n  let detachFromCurrent: (() => void) | undefined;\n  const listeners = new Set<() => void>();\n\n  const notify = (): void => {\n    for (const listener of listeners) listener();\n  };\n\n  return {\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    getSnapshot: () =>\n      current?.getSnapshot() as ReturnType<Task['getSnapshot']> | undefined,\n    getCurrent: () => current,\n    replace: (task) => {\n      detachFromCurrent?.();\n      current = task;\n      detachFromCurrent = task?.subscribe(notify);\n      notify();\n    },\n  };\n}\n","import * as React from 'react';\nimport { useCallback, useInsertionEffect, useRef } from 'react';\n\n/**\n * `useEffectEvent` only became a stable React export in 19.2. On React 18\n * and 19.0–19.1 it doesn't exist at all — and a named\n * `import { useEffectEvent } from 'react'` then fails outright: at module\n * link time under Node ESM (\"Named export 'useEffectEvent' not found\"), or\n * as \"useEffectEvent is not a function\" on first render in a bundler. Both\n * versions are inside this package's declared peer range, so that has to\n * work, not just type-check.\n *\n * So the native hook is read as a property of the namespace object, where a\n * missing export is plain `undefined` rather than a link error, and used\n * whenever the running React has it. Otherwise the fallback keeps the same\n * contract: a stable function identity that always calls the latest\n * callback. The latest callback is committed from an insertion effect —\n * after render, before any layout or passive effect of the same commit can\n * observe it — so effects always see the current closure, without the\n * render-time ref mutation the React Compiler rejects.\n */\ntype EffectEventHook = <Args extends readonly unknown[], Return>(\n  callback: (...args: Args) => Return,\n) => (...args: Args) => Return;\n\nexport function useEffectEventFallback<Args extends readonly unknown[], Return>(\n  callback: (...args: Args) => Return,\n): (...args: Args) => Return {\n  const latest = useRef(callback);\n  useInsertionEffect(() => {\n    latest.current = callback;\n  });\n  return useCallback((...args: Args) => latest.current(...args), []);\n}\n\n// Through `unknown` on purpose: React 18's types have no `useEffectEvent`\n// member at all, so a direct assertion wouldn't compile against them.\nconst nativeUseEffectEvent = (\n  React as unknown as { readonly useEffectEvent?: EffectEventHook }\n).useEffectEvent;\n\nexport const useEffectEvent: EffectEventHook =\n  nativeUseEffectEvent ?? useEffectEventFallback;\n","import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';\n\nimport type { ChunkStatus } from '../core/chunk-machine.js';\nimport { createChunkScheduler } from '../core/chunk-scheduler.js';\nimport type {\n  ChunkScheduler,\n  ChunkSnapshot,\n  SkippedChunkItem,\n} from '../core/chunk-scheduler.js';\nimport { createTaskController } from './task-controller.js';\nimport { useEffectEvent } from './use-effect-event.js';\n\n/** Stable empty array so a never-skipped task doesn't hand out a fresh `[]` every render. */\nconst NO_SKIPPED: readonly SkippedChunkItem[] = [];\n\nexport interface UseChunkedTaskOptions<T, R> {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\n  /**\n   * Items to process between clock checks. Default 1. Raise it only for\n   * items measured in nanoseconds, where reading the clock costs more than\n   * the work; a slice can then run up to `batchSize` items past its budget.\n   * See the `batchSize` note on `createChunkScheduler`.\n   */\n  readonly batchSize?: number;\n  /**\n   * Keep every result in `results`. Default true. Set false when results\n   * are consumed through `onItem`, to avoid retaining one result per item;\n   * `results` is then an empty array once the task settles.\n   */\n  readonly collectResults?: boolean;\n  /** Start processing automatically when the task is (re)created. Default `true`. */\n  readonly autoStart?: boolean;\n  /**\n   * Called synchronously after each item is processed. This is the cheap\n   * way to consume results incrementally while the task is still running —\n   * write into a ref-backed buffer, a canvas, a chart, whatever you need —\n   * without paying for an array copy on every yield checkpoint.\n   */\n  readonly onItem?: (result: R, item: T, index: number) => void;\n  /**\n   * Called when `processItem` throws. Return `'skip'` to drop that item and\n   * keep going — it shows up in `skipped` — or `'abort'` to end the task as\n   * an error, carrying whatever was collected before the throw. Omitting\n   * this defaults to `'abort'`, so existing callers see no behavior change.\n   */\n  readonly onError?: (error: unknown, item: T, index: number) => 'skip' | 'abort';\n  /**\n   * Called every time a slice ends and the task is about to yield, with how\n   * long that slice ran and how many items are done so far. Ships in the\n   * production build, unlike this package's own dev-only diagnostics — wire\n   * it to your own telemetry to verify, on real traffic, that this task is\n   * actually staying under `timeSliceMs`.\n   */\n  readonly onSlice?: (durationMs: number, processed: number) => void;\n  /** Called right after each yield resolves and work is about to resume. Pairs with `onSlice`. */\n  readonly onYield?: () => void;\n}\n\nexport interface UseChunkedTaskState<R> {\n  readonly status: ChunkStatus;\n  readonly processed: number;\n  readonly total: number;\n  readonly error: unknown;\n  /** The full results array once the task has settled — `undefined` until then. */\n  readonly results: readonly R[] | undefined;\n  /** Items `onError` has skipped so far, growing live as skips happen. Empty when unused. */\n  readonly skipped: readonly SkippedChunkItem[];\n  readonly isIdle: boolean;\n  readonly isProcessing: boolean;\n  readonly isPaused: boolean;\n  readonly isDone: boolean;\n  readonly isCancelled: boolean;\n  readonly isError: boolean;\n  readonly start: () => void;\n  readonly pause: () => void;\n  readonly resume: () => void;\n  readonly cancel: () => void;\n}\n\nconst IDLE_STATUS: ChunkStatus = 'idle';\n\n/**\n * Chunks a heavy, synchronous per-item computation over `items` so it never\n * blocks the main thread for longer than a time slice — the thing that\n * costs you Interaction to Next Paint. Starts automatically by default;\n * pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.\n * behind a button).\n *\n * `processItem` and `onItem` can be fresh closures every render — the hook\n * always calls the latest version (via `useEffectEvent`) without that\n * causing the task to restart. What *does* restart the task is `items`\n * changing identity (a new array reference), or `timeSliceMs`/`autoStart`\n * changing. That's deliberate: a new `items` array means new work, and\n * memoizing it when you don't want that is the caller's call to make, the\n * same as any other React dependency.\n */\nexport function useChunkedTask<T, R>(\n  items: readonly T[],\n  processItem: (item: T, index: number) => R,\n  options?: UseChunkedTaskOptions<T, R>,\n): UseChunkedTaskState<R> {\n  const {\n    timeSliceMs,\n    batchSize,\n    collectResults,\n    autoStart = true,\n    onItem,\n    onError,\n    onSlice,\n    onYield,\n  } = options ?? {};\n\n  // Stable identity, always runs the latest processItem/onItem passed this\n  // render — the React-Compiler-safe replacement for a ref mutated during\n  // render. Effect Events are meant to be called from inside an effect\n  // (here: from the scheduler's async loop, which the effect below owns),\n  // never during render itself.\n  const stableProcessItem = useEffectEvent((item: T, index: number) =>\n    processItem(item, index),\n  );\n  const stableOnItem = useEffectEvent((result: R, item: T, index: number) => {\n    onItem?.(result, item, index);\n  });\n  const stableOnError = useEffectEvent(\n    (error: unknown, item: T, index: number): 'skip' | 'abort' =>\n      onError?.(error, item, index) ?? 'abort',\n  );\n  const stableOnSlice = useEffectEvent((durationMs: number, processed: number) => {\n    onSlice?.(durationMs, processed);\n  });\n  const stableOnYield = useEffectEvent(() => {\n    onYield?.();\n  });\n\n  // Created once, lazily, via useState rather than a ref mutated during\n  // render — the controller itself is inert (no subscriptions, no timers)\n  // until an effect calls replace() on it, so a discarded render (double\n  // render in dev, or one React throws away) never leaks anything.\n  const [controller] = useState(() => createTaskController<ChunkScheduler<R>>());\n\n  // What getSnapshot() reports before the effect below has ever run —\n  // including during SSR, where effects never run at all.\n  const idleSnapshot = useMemo<ChunkSnapshot<R>>(\n    () => ({ status: IDLE_STATUS, processed: 0, total: items.length }),\n    [items.length],\n  );\n\n  const snapshot = useSyncExternalStore(\n    controller.subscribe,\n    () => controller.getSnapshot() ?? idleSnapshot,\n    () => idleSnapshot,\n  );\n\n  useEffect(() => {\n    const scheduler = createChunkScheduler<T, R>({\n      items,\n      processItem: stableProcessItem,\n      onItem: stableOnItem,\n      onError: stableOnError,\n      onSlice: stableOnSlice,\n      onYield: stableOnYield,\n      ...(timeSliceMs !== undefined ? { timeSliceMs } : {}),\n      ...(batchSize !== undefined ? { batchSize } : {}),\n      ...(collectResults !== undefined ? { collectResults } : {}),\n    });\n    controller.replace(scheduler);\n    if (autoStart) scheduler.start();\n\n    return () => {\n      // Safe even if the task already finished on its own — cancel() on a\n      // terminal scheduler is a documented no-op, not an error.\n      scheduler.cancel();\n      controller.replace(null);\n    };\n    // stableProcessItem/stableOnItem/stableOnError/stableOnSlice/stableOnYield\n    // are Effect Events: stable by construction, intentionally excluded\n    // from the reactive dependency set\n    // (that's the whole point of useEffectEvent) rather than omitted by\n    // oversight.\n  }, [items, timeSliceMs, batchSize, collectResults, autoStart, controller]);\n\n  const start = useCallback(() => controller.getCurrent()?.start(), [controller]);\n  const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);\n  const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);\n  const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);\n\n  return {\n    status: snapshot.status,\n    processed: snapshot.processed,\n    total: snapshot.total,\n    error: snapshot.error,\n    // From the snapshot, not a direct read of the scheduler: the engine\n    // publishes results before it announces a terminal status, so the two\n    // always arrive together and a concurrent render can never tear them\n    // apart.\n    results: snapshot.results,\n    skipped: snapshot.skipped ?? NO_SKIPPED,\n    isIdle: snapshot.status === 'idle',\n    isProcessing: snapshot.status === 'processing',\n    isPaused: snapshot.status === 'paused',\n    isDone: snapshot.status === 'done',\n    isCancelled: snapshot.status === 'cancelled',\n    isError: snapshot.status === 'error',\n    start,\n    pause,\n    resume,\n    cancel,\n  };\n}\n","import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';\n\nimport type { ChunkStatus } from '../core/chunk-machine.js';\nimport { createDeferredTask } from '../core/deferred-task.js';\nimport type {\n  DeferredGenerator,\n  DeferredTask,\n  DeferredTaskSnapshot,\n} from '../core/deferred-task.js';\nimport { createTaskController } from './task-controller.js';\nimport { useEffectEvent } from './use-effect-event.js';\n\nexport interface UseDeferredTaskOptions {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\n  /**\n   * Generator segments to run between clock checks. Default 1. Raise it\n   * only for segments measured in nanoseconds; a slice can then run up to\n   * `batchSize` segments past its budget.\n   */\n  readonly batchSize?: number;\n  /** Start processing automatically when the task is (re)created. Default `true`. */\n  readonly autoStart?: boolean;\n  /**\n   * Called every time a segment-batch ends and the task is about to yield,\n   * with how long that slice ran and how many segments are done so far.\n   * Ships in the production build — see the identical option on\n   * `useChunkedTask`/`createChunkScheduler` for why.\n   */\n  readonly onSlice?: (durationMs: number, segmentsDone: number) => void;\n  /** Called right after each yield resolves and work is about to resume. Pairs with `onSlice`. */\n  readonly onYield?: () => void;\n}\n\nexport interface UseDeferredTaskState<T> {\n  readonly status: ChunkStatus;\n  readonly error: unknown;\n  /** The returned value once the task settles with `done` — `undefined` until then. */\n  readonly value: T | undefined;\n  readonly isIdle: boolean;\n  readonly isProcessing: boolean;\n  readonly isPaused: boolean;\n  readonly isDone: boolean;\n  readonly isCancelled: boolean;\n  readonly isError: boolean;\n  readonly start: () => void;\n  readonly pause: () => void;\n  readonly resume: () => void;\n  readonly cancel: () => void;\n}\n\nconst IDLE_SNAPSHOT: DeferredTaskSnapshot<never> = { status: 'idle' };\n\n/**\n * Runs an arbitrary heavy, synchronous generator function in chunks, so it\n * never produces a long task on its own. Where `useChunkedTask` chunks \"one\n * function applied to every item of an array\" automatically, this hook\n * leaves the chunk boundaries to you — put `yield` wherever your function\n * can safely pause (see `DeferredGenerator`'s doc comment for an example).\n *\n * `task` is only called when the effect (re)creates the underlying task, not\n * on every render — list whatever it closes over in `deps`, the same way\n * you would for `useMemo` or `useEffect`.\n */\nexport function useDeferredTask<T>(\n  task: () => DeferredGenerator<T>,\n  deps: readonly unknown[],\n  options?: UseDeferredTaskOptions,\n): UseDeferredTaskState<T> {\n  const { timeSliceMs, batchSize, autoStart = true, onSlice, onYield } = options ?? {};\n\n  // Stable identity, always runs the latest `task` passed this render —\n  // see useChunkedTask.ts for why this is useEffectEvent rather than a ref\n  // mutated during render.\n  const stableTask = useEffectEvent(() => task());\n  const stableOnSlice = useEffectEvent((durationMs: number, segmentsDone: number) => {\n    onSlice?.(durationMs, segmentsDone);\n  });\n  const stableOnYield = useEffectEvent(() => {\n    onYield?.();\n  });\n\n  const [controller] = useState(() => createTaskController<DeferredTask<T>>());\n\n  const snapshot = useSyncExternalStore(\n    controller.subscribe,\n    () => controller.getSnapshot() ?? IDLE_SNAPSHOT,\n    () => IDLE_SNAPSHOT,\n  );\n\n  useEffect(\n    () => {\n      const deferredTask = createDeferredTask<T>({\n        task: stableTask,\n        onSlice: stableOnSlice,\n        onYield: stableOnYield,\n        ...(timeSliceMs !== undefined ? { timeSliceMs } : {}),\n        ...(batchSize !== undefined ? { batchSize } : {}),\n      });\n      controller.replace(deferredTask);\n      if (autoStart) deferredTask.start();\n\n      return () => {\n        deferredTask.cancel();\n        controller.replace(null);\n      };\n    },\n    // `deps` plays the role `items` plays for useChunkedTask: it's the\n    // caller's declaration of \"this is new work\". `stableTask` is an Effect\n    // Event — stable by construction, intentionally excluded from the\n    // reactive dependency set rather than omitted by oversight. `deps` is a\n    // caller-supplied array, the same pattern (and the same reason it can't\n    // be statically verified) as useMemo/useEffect's own deps parameter.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [...deps, timeSliceMs, batchSize, autoStart, controller],\n  );\n\n  const start = useCallback(() => controller.getCurrent()?.start(), [controller]);\n  const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);\n  const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);\n  const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);\n\n  return {\n    status: snapshot.status,\n    error: snapshot.error,\n    // From the snapshot: the engine publishes the value before it\n    // announces `done`, so a concurrent render can never see one without\n    // the other. See useChunkedTask.ts.\n    value: snapshot.value,\n    isIdle: snapshot.status === 'idle',\n    isProcessing: snapshot.status === 'processing',\n    isPaused: snapshot.status === 'paused',\n    isDone: snapshot.status === 'done',\n    isCancelled: snapshot.status === 'cancelled',\n    isError: snapshot.status === 'error',\n    start,\n    pause,\n    resume,\n    cancel,\n  };\n}\n"],"mappings":"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"}

package/dist/production/index.js

@@ -0,0 +1,193 @@
+import { n as createChunkScheduler, t as createDeferredTask } from "./deferred-task-DkHdsliy.js";
+import * as React from "react";
+import { useCallback, useEffect, useInsertionEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+// src/react/task-controller.ts
+function createTaskController() {
+	let current = null;
+	let detachFromCurrent;
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => {
+		for (const listener of listeners) listener();
+	};
+	return {
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		getSnapshot: () => current?.getSnapshot(),
+		getCurrent: () => current,
+		replace: (task) => {
+			detachFromCurrent?.();
+			current = task;
+			detachFromCurrent = task?.subscribe(notify);
+			notify();
+		}
+	};
+}
+// src/react/use-effect-event.ts
+function useEffectEventFallback(callback) {
+	const latest = useRef(callback);
+	useInsertionEffect(() => {
+		latest.current = callback;
+	});
+	return useCallback((...args) => latest.current(...args), []);
+}
+const useEffectEvent = React.useEffectEvent ?? useEffectEventFallback;
+// src/react/useChunkedTask.ts
+/** Stable empty array so a never-skipped task doesn't hand out a fresh `[]` every render. */
+const NO_SKIPPED = [];
+const IDLE_STATUS = "idle";
+/**
+* Chunks a heavy, synchronous per-item computation over `items` so it never
+* blocks the main thread for longer than a time slice — the thing that
+* costs you Interaction to Next Paint. Starts automatically by default;
+* pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.
+* behind a button).
+*
+* `processItem` and `onItem` can be fresh closures every render — the hook
+* always calls the latest version (via `useEffectEvent`) without that
+* causing the task to restart. What *does* restart the task is `items`
+* changing identity (a new array reference), or `timeSliceMs`/`autoStart`
+* changing. That's deliberate: a new `items` array means new work, and
+* memoizing it when you don't want that is the caller's call to make, the
+* same as any other React dependency.
+*/
+function useChunkedTask(items, processItem, options) {
+	const { timeSliceMs, batchSize, collectResults, autoStart = true, onItem, onError, onSlice, onYield } = options ?? {};
+	const stableProcessItem = useEffectEvent((item, index) => processItem(item, index));
+	const stableOnItem = useEffectEvent((result, item, index) => {
+		onItem?.(result, item, index);
+	});
+	const stableOnError = useEffectEvent((error, item, index) => onError?.(error, item, index) ?? "abort");
+	const stableOnSlice = useEffectEvent((durationMs, processed) => {
+		onSlice?.(durationMs, processed);
+	});
+	const stableOnYield = useEffectEvent(() => {
+		onYield?.();
+	});
+	const [controller] = useState(() => createTaskController());
+	const idleSnapshot = useMemo(() => ({
+		status: IDLE_STATUS,
+		processed: 0,
+		total: items.length
+	}), [items.length]);
+	const snapshot = useSyncExternalStore(controller.subscribe, () => controller.getSnapshot() ?? idleSnapshot, () => idleSnapshot);
+	useEffect(() => {
+		const scheduler = createChunkScheduler({
+			items,
+			processItem: stableProcessItem,
+			onItem: stableOnItem,
+			onError: stableOnError,
+			onSlice: stableOnSlice,
+			onYield: stableOnYield,
+			...timeSliceMs !== void 0 ? { timeSliceMs } : {},
+			...batchSize !== void 0 ? { batchSize } : {},
+			...collectResults !== void 0 ? { collectResults } : {}
+		});
+		controller.replace(scheduler);
+		if (autoStart) scheduler.start();
+		return () => {
+			scheduler.cancel();
+			controller.replace(null);
+		};
+	}, [
+		items,
+		timeSliceMs,
+		batchSize,
+		collectResults,
+		autoStart,
+		controller
+	]);
+	const start = useCallback(() => controller.getCurrent()?.start(), [controller]);
+	const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);
+	const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);
+	const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);
+	return {
+		status: snapshot.status,
+		processed: snapshot.processed,
+		total: snapshot.total,
+		error: snapshot.error,
+		results: snapshot.results,
+		skipped: snapshot.skipped ?? NO_SKIPPED,
+		isIdle: snapshot.status === "idle",
+		isProcessing: snapshot.status === "processing",
+		isPaused: snapshot.status === "paused",
+		isDone: snapshot.status === "done",
+		isCancelled: snapshot.status === "cancelled",
+		isError: snapshot.status === "error",
+		start,
+		pause,
+		resume,
+		cancel
+	};
+}
+// src/react/useDeferredTask.ts
+const IDLE_SNAPSHOT = { status: "idle" };
+/**
+* Runs an arbitrary heavy, synchronous generator function in chunks, so it
+* never produces a long task on its own. Where `useChunkedTask` chunks "one
+* function applied to every item of an array" automatically, this hook
+* leaves the chunk boundaries to you — put `yield` wherever your function
+* can safely pause (see `DeferredGenerator`'s doc comment for an example).
+*
+* `task` is only called when the effect (re)creates the underlying task, not
+* on every render — list whatever it closes over in `deps`, the same way
+* you would for `useMemo` or `useEffect`.
+*/
+function useDeferredTask(task, deps, options) {
+	const { timeSliceMs, batchSize, autoStart = true, onSlice, onYield } = options ?? {};
+	const stableTask = useEffectEvent(() => task());
+	const stableOnSlice = useEffectEvent((durationMs, segmentsDone) => {
+		onSlice?.(durationMs, segmentsDone);
+	});
+	const stableOnYield = useEffectEvent(() => {
+		onYield?.();
+	});
+	const [controller] = useState(() => createTaskController());
+	const snapshot = useSyncExternalStore(controller.subscribe, () => controller.getSnapshot() ?? IDLE_SNAPSHOT, () => IDLE_SNAPSHOT);
+	useEffect(() => {
+		const deferredTask = createDeferredTask({
+			task: stableTask,
+			onSlice: stableOnSlice,
+			onYield: stableOnYield,
+			...timeSliceMs !== void 0 ? { timeSliceMs } : {},
+			...batchSize !== void 0 ? { batchSize } : {}
+		});
+		controller.replace(deferredTask);
+		if (autoStart) deferredTask.start();
+		return () => {
+			deferredTask.cancel();
+			controller.replace(null);
+		};
+	}, [
+		...deps,
+		timeSliceMs,
+		batchSize,
+		autoStart,
+		controller
+	]);
+	const start = useCallback(() => controller.getCurrent()?.start(), [controller]);
+	const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);
+	const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);
+	const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);
+	return {
+		status: snapshot.status,
+		error: snapshot.error,
+		value: snapshot.value,
+		isIdle: snapshot.status === "idle",
+		isProcessing: snapshot.status === "processing",
+		isPaused: snapshot.status === "paused",
+		isDone: snapshot.status === "done",
+		isCancelled: snapshot.status === "cancelled",
+		isError: snapshot.status === "error",
+		start,
+		pause,
+		resume,
+		cancel
+	};
+}
+export { useChunkedTask, useDeferredTask };
+
+//# sourceMappingURL=index.js.map