react-inp-chunker 0.1.2 → 0.2.0

package/dist/production/index.cjs

@@ -0,0 +1,195 @@
+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-zVnq18IN.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
+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 } = options ?? {};
+	const stableProcessItem = useEffectEvent((item, index) => processItem(item, index));
+	const stableOnItem = useEffectEvent((result, item, index) => {
+		onItem?.(result, item, index);
+	});
+	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,
+			...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,
+		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 } = options ?? {};
+	const stableTask = useEffectEvent(() => task());
+	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,
+			...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 { ChunkScheduler, ChunkSnapshot } from '../core/chunk-scheduler.js';\nimport { createTaskController } from './task-controller.js';\nimport { useEffectEvent } from './use-effect-event.js';\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\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  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  } = 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\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      ...(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 are Effect Events: stable by\n    // construction, intentionally excluded 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    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\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 } = 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\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        ...(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,172 @@
+import { n as createChunkScheduler, t as createDeferredTask } from "./deferred-task-BGsfee-L.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
+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 } = options ?? {};
+	const stableProcessItem = useEffectEvent((item, index) => processItem(item, index));
+	const stableOnItem = useEffectEvent((result, item, index) => {
+		onItem?.(result, item, index);
+	});
+	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,
+			...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,
+		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 } = options ?? {};
+	const stableTask = useEffectEvent(() => task());
+	const [controller] = useState(() => createTaskController());
+	const snapshot = useSyncExternalStore(controller.subscribe, () => controller.getSnapshot() ?? IDLE_SNAPSHOT, () => IDLE_SNAPSHOT);
+	useEffect(() => {
+		const deferredTask = createDeferredTask({
+			task: stableTask,
+			...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

package/dist/production/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"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 { ChunkScheduler, ChunkSnapshot } from '../core/chunk-scheduler.js';\nimport { createTaskController } from './task-controller.js';\nimport { useEffectEvent } from './use-effect-event.js';\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\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  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  } = 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\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      ...(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 are Effect Events: stable by\n    // construction, intentionally excluded 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    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\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 } = 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\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        ...(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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-inp-chunker",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Headless React/TypeScript primitives that chunk heavy synchronous work and yield to the main thread, so long-running updates never cost you Interaction to Next Paint (INP).",
   "keywords": [
     "react",
@@ -15,7 +15,7 @@
     "concurrent",
     "headless"
   ],
-  "homepage": "https://github.com/suprabhat02/react-inp-chunker#readme",
+  "homepage": "https://suprabhat02.github.io/react-inp-chunker/",
   "bugs": "https://github.com/suprabhat02/react-inp-chunker/issues",
   "repository": {
     "type": "git",
@@ -26,18 +26,48 @@
   "type": "module",
   "sideEffects": false,
   "engines": {
-    "node": ">=22.12"
+    "node": ">=18"
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "production": {
+        "import": {
+          "types": "./dist/index.d.ts",
+          "default": "./dist/production/index.js"
+        },
+        "require": {
+          "types": "./dist/index.d.cts",
+          "default": "./dist/production/index.cjs"
+        }
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js",
-      "require": "./dist/core/index.cjs"
+      "production": {
+        "import": {
+          "types": "./dist/core/index.d.ts",
+          "default": "./dist/production/core/index.js"
+        },
+        "require": {
+          "types": "./dist/core/index.d.cts",
+          "default": "./dist/production/core/index.cjs"
+        }
+      },
+      "import": {
+        "types": "./dist/core/index.d.ts",
+        "default": "./dist/core/index.js"
+      },
+      "require": {
+        "types": "./dist/core/index.d.cts",
+        "default": "./dist/core/index.cjs"
+      }
     },
     "./package.json": "./package.json"
   },
@@ -46,6 +76,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "core",
     "README.md",
     "LICENSE"
   ],
@@ -56,6 +87,7 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
+    "typecheck:react18": "tsc -p tsconfig.react18.json",
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -63,52 +95,63 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "size": "size-limit",
-    "verify": "npm run lint && npm run format:check && npm run typecheck && npm run test:coverage && npm run build && npm run size",
-    "prepublishOnly": "npm run verify"
+    "verify": "npm run lint && npm run format:check && npm run typecheck && npm run test:coverage && npm run build && npm run api:check && npm run lint:package && npm run types:resolution && npm run types:consumer && npm run size",
+    "prepublishOnly": "npm run verify",
+    "bench": "npm run build && node bench/overhead.mjs",
+    "api:check": "node scripts/api-surface.mjs",
+    "api:update": "node scripts/api-surface.mjs --update",
+    "lint:package": "publint --strict",
+    "types:resolution": "node scripts/check-type-resolution.mjs",
+    "types:consumer": "tsc -p consumer/tsconfig.bundler.json && tsc -p consumer/tsconfig.nodenext.json",
+    "test:browser": "npm run build && node tests/browser/yielding.mjs"
   },
   "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.2",
     "@eslint/js": "10.0.1",
+    "@size-limit/preset-small-lib": "14.3.0",
     "@testing-library/react": "16.3.3",
-    "@types/node": "24.1.0",
+    "@types/node": "^26.6.5",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "@vitest/coverage-v8": "5.0.5",
     "eslint": "10.13.0",
     "eslint-plugin-react-hooks": "7.1.1",
+    "fast-check": "^4.5.0",
     "globals": "17.13.0",
-    "jsdom": "26.1.0",
+    "jsdom": "^30.1.3",
+    "playwright": "^1.63.0",
     "prettier": "3.9.10",
+    "publint": "^0.3.12",
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "size-limit": "14.3.0",
-    "@size-limit/preset-small-lib": "14.3.0",
     "tsdown": "0.23.2",
-    "typescript": "6.0.3",
-    "typescript-eslint": "8.72.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "8.72.1",
     "vitest": "5.0.5"
   },
   "size-limit": [
     {
       "name": "core (import { createChunkScheduler })",
-      "path": "dist/core/index.js",
+      "path": "dist/production/core/index.js",
       "import": "{ createChunkScheduler }",
-      "limit": "1.3 kB"
+      "limit": "1.4 kB"
     },
     {
       "name": "useChunkedTask",
-      "path": "dist/index.js",
+      "path": "dist/production/index.js",
       "import": "{ useChunkedTask }",
       "limit": "2.2 kB"
     },
     {
       "name": "useDeferredTask",
-      "path": "dist/index.js",
+      "path": "dist/production/index.js",
       "import": "{ useDeferredTask }",
-      "limit": "1.6 kB"
+      "limit": "1.8 kB"
     },
     {
       "name": "everything",
-      "path": "dist/index.js",
+      "path": "dist/production/index.js",
       "limit": "3.5 kB"
     }
   ]