@j13b/react-state 0.1.0

package/dist/hooks/use_runner_feedback_effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_feedback_effect.js","names":[],"sources":["../../src/hooks/use_runner_feedback_effect.ts"],"sourcesContent":["/**\n * @module hooks/use_runner_feedback_effect\n *\n * This module provides a React hook for handling feedback messages from a Runner.\n * It allows components to react to changes in the feedback state of async operations.\n */\n\nimport { IRunnerBroadcast } from '@j13b/state';\nimport { useSignalValueEffect } from './use_signal_value_effect.js';\n\n/**\n * A React hook that executes a callback whenever the feedback message of a Runner changes.\n *\n * This hook is useful for displaying operation feedback to users, such as loading messages,\n * progress updates, or error notifications. It automatically handles cleanup when the\n * component unmounts.\n *\n * @example\n * ```tsx\n * useRunnerFeedbackEffect(\n *   (feedback) => {\n *     // Update UI with feedback message\n *     setMessage(feedback);\n *   },\n *   myRunner.broadcast\n * );\n * ```\n *\n * @param callback - A function that will be called with the new feedback message whenever it changes\n * @param task - The Runner's broadcast interface to subscribe to\n * @returns void\n */\nexport function useRunnerFeedbackEffect(\n  callback: (feedback: string) => void,\n  task: IRunnerBroadcast<any>\n) {\n  return useSignalValueEffect(state => {\n    callback(state.feedback);\n  }, task.stateBroadcast);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,wBACd,UACA,MACA;CACA,OAAO,sBAAqB,UAAS;EACnC,SAAS,MAAM,QAAQ;CACzB,GAAG,KAAK,cAAc;AACxB"}

package/dist/hooks/use_runner_progress.d.ts

@@ -0,0 +1,3 @@
+import { IRunnerBroadcast } from '@j13b/state';
+export declare function useRunnerProgress(task: IRunnerBroadcast<any>): number;
+//# sourceMappingURL=use_runner_progress.d.ts.map

package/dist/hooks/use_runner_progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_progress.d.ts","sourceRoot":"","sources":["../../src/hooks/use_runner_progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,UAE5D"}

package/dist/hooks/use_runner_progress.js

@@ -0,0 +1,9 @@
+import { useSignalValue } from "./use_signal_value.js";
+//#region src/hooks/use_runner_progress.ts
+function useRunnerProgress(task) {
+	return useSignalValue(task.stateBroadcast).progress;
+}
+//#endregion
+export { useRunnerProgress };
+
+//# sourceMappingURL=use_runner_progress.js.map

package/dist/hooks/use_runner_progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_progress.js","names":[],"sources":["../../src/hooks/use_runner_progress.ts"],"sourcesContent":["/**\n * A React hook that subscribes to the progress state of a Runner.\n *\n * @template T - The type of the Runner's value\n * @param {IRunnerBroadcast<T>} task - The Runner broadcast interface to subscribe to\n * @returns {number} A number between 0 and 1 representing the current progress of the task\n *\n * @example\n * ```tsx\n * const progress = useRunnerProgress(saveRunner.broadcast);\n * // progress will be a number between 0 and 1\n * // 0 = not started, 1 = complete\n * ```\n *\n * @remarks\n * This hook is useful for tracking the progress of long-running operations\n * such as file uploads, data processing, or any task that can report progress.\n * The component will automatically re-render when the progress value changes.\n */\nimport { IRunnerBroadcast } from '@j13b/state';\nimport { useSignalValue } from './use_signal_value.js';\n\nexport function useRunnerProgress(task: IRunnerBroadcast<any>) {\n  return useSignalValue(task.stateBroadcast).progress;\n}\n"],"mappings":";;AAsBA,SAAgB,kBAAkB,MAA6B;CAC7D,OAAO,eAAe,KAAK,cAAc,CAAC,CAAC;AAC7C"}

package/dist/hooks/use_runner_progress_effect.d.ts

@@ -0,0 +1,26 @@
+import { IRunnerBroadcast } from '@j13b/state';
+/**
+ * Hook that executes a callback whenever the progress of a Runner operation changes.
+ *
+ * @template T - The type of the Runner's value
+ * @param callback - Function to be called when progress changes. Receives the current progress value (0-1)
+ * @param task - The Runner broadcast interface to track progress from
+ * @returns void
+ *
+ * @example
+ * ```tsx
+ * useRunnerProgressEffect(
+ *   (progress) => {
+ *     console.log(`Operation is ${progress * 100}% complete`);
+ *   },
+ *   myRunner.broadcast
+ * );
+ * ```
+ *
+ * @remarks
+ * - The callback will be called with a number between 0 and 1 representing progress
+ * - The effect is automatically cleaned up when the component unmounts
+ * - This hook is built on top of useSignalValueEffect for efficient state tracking
+ */
+export declare function useRunnerProgressEffect(callback: (progress: number) => void, task: IRunnerBroadcast<any>): void;
+//# sourceMappingURL=use_runner_progress_effect.d.ts.map

package/dist/hooks/use_runner_progress_effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_progress_effect.d.ts","sourceRoot":"","sources":["../../src/hooks/use_runner_progress_effect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,QAK5B"}

package/dist/hooks/use_runner_progress_effect.js

@@ -0,0 +1,34 @@
+import { useSignalValueEffect } from "./use_signal_value_effect.js";
+//#region src/hooks/use_runner_progress_effect.ts
+/**
+* Hook that executes a callback whenever the progress of a Runner operation changes.
+*
+* @template T - The type of the Runner's value
+* @param callback - Function to be called when progress changes. Receives the current progress value (0-1)
+* @param task - The Runner broadcast interface to track progress from
+* @returns void
+*
+* @example
+* ```tsx
+* useRunnerProgressEffect(
+*   (progress) => {
+*     console.log(`Operation is ${progress * 100}% complete`);
+*   },
+*   myRunner.broadcast
+* );
+* ```
+*
+* @remarks
+* - The callback will be called with a number between 0 and 1 representing progress
+* - The effect is automatically cleaned up when the component unmounts
+* - This hook is built on top of useSignalValueEffect for efficient state tracking
+*/
+function useRunnerProgressEffect(callback, task) {
+	return useSignalValueEffect((state) => {
+		callback(state.progress);
+	}, task.stateBroadcast);
+}
+//#endregion
+export { useRunnerProgressEffect };
+
+//# sourceMappingURL=use_runner_progress_effect.js.map

package/dist/hooks/use_runner_progress_effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_progress_effect.js","names":[],"sources":["../../src/hooks/use_runner_progress_effect.ts"],"sourcesContent":["/**\n * @module hooks/use_runner_progress_effect\n *\n * This module provides a React hook for tracking the progress of a Runner operation.\n * It allows components to react to progress changes in long-running operations.\n */\n\nimport { IRunnerBroadcast } from '@j13b/state';\nimport { useSignalValueEffect } from './use_signal_value_effect.js';\n\n/**\n * Hook that executes a callback whenever the progress of a Runner operation changes.\n *\n * @template T - The type of the Runner's value\n * @param callback - Function to be called when progress changes. Receives the current progress value (0-1)\n * @param task - The Runner broadcast interface to track progress from\n * @returns void\n *\n * @example\n * ```tsx\n * useRunnerProgressEffect(\n *   (progress) => {\n *     console.log(`Operation is ${progress * 100}% complete`);\n *   },\n *   myRunner.broadcast\n * );\n * ```\n *\n * @remarks\n * - The callback will be called with a number between 0 and 1 representing progress\n * - The effect is automatically cleaned up when the component unmounts\n * - This hook is built on top of useSignalValueEffect for efficient state tracking\n */\nexport function useRunnerProgressEffect(\n  callback: (progress: number) => void,\n  task: IRunnerBroadcast<any>\n) {\n  return useSignalValueEffect(state => {\n    callback(state.progress);\n  }, task.stateBroadcast);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,wBACd,UACA,MACA;CACA,OAAO,sBAAqB,UAAS;EACnC,SAAS,MAAM,QAAQ;CACzB,GAAG,KAAK,cAAc;AACxB"}

package/dist/hooks/use_runner_status.d.ts

@@ -0,0 +1,24 @@
+import { IRunnerBroadcast } from '@j13b/state';
+/**
+ * A hook that subscribes to a runner's status changes and returns the current status.
+ * The component will re-render whenever the runner's status changes.
+ *
+ * @template T - The type of the runner's value
+ * @param broadcast - The broadcast interface of the runner to subscribe to
+ * @returns The current status of the runner (INITIAL, PENDING, SUCCESS, ERROR)
+ *
+ * @example
+ * ```tsx
+ * const status = useRunnerStatus(runner.broadcast);
+ *
+ * return (
+ *   <div>
+ *     {status === 'PENDING' && <Spinner />}
+ *     {status === 'ERROR' && <ErrorMessage />}
+ *     {status === 'SUCCESS' && <SuccessMessage />}
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useRunnerStatus(broadcast: IRunnerBroadcast<any>): import('@j13b/state').Status;
+//# sourceMappingURL=use_runner_status.d.ts.map

package/dist/hooks/use_runner_status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_status.d.ts","sourceRoot":"","sources":["../../src/hooks/use_runner_status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,gBAAgB,CAAC,GAAG,CAAC,gCAE/D"}

package/dist/hooks/use_runner_status.js

@@ -0,0 +1,30 @@
+import { useSignalValue } from "./use_signal_value.js";
+//#region src/hooks/use_runner_status.ts
+/**
+* A hook that subscribes to a runner's status changes and returns the current status.
+* The component will re-render whenever the runner's status changes.
+*
+* @template T - The type of the runner's value
+* @param broadcast - The broadcast interface of the runner to subscribe to
+* @returns The current status of the runner (INITIAL, PENDING, SUCCESS, ERROR)
+*
+* @example
+* ```tsx
+* const status = useRunnerStatus(runner.broadcast);
+*
+* return (
+*   <div>
+*     {status === 'PENDING' && <Spinner />}
+*     {status === 'ERROR' && <ErrorMessage />}
+*     {status === 'SUCCESS' && <SuccessMessage />}
+*   </div>
+* );
+* ```
+*/
+function useRunnerStatus(broadcast) {
+	return useSignalValue(broadcast.stateBroadcast).status;
+}
+//#endregion
+export { useRunnerStatus };
+
+//# sourceMappingURL=use_runner_status.js.map

package/dist/hooks/use_runner_status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_status.js","names":[],"sources":["../../src/hooks/use_runner_status.ts"],"sourcesContent":["import { IRunnerBroadcast } from '@j13b/state';\nimport { useSignalValue } from './use_signal_value.js';\n\n/**\n * A hook that subscribes to a runner's status changes and returns the current status.\n * The component will re-render whenever the runner's status changes.\n *\n * @template T - The type of the runner's value\n * @param broadcast - The broadcast interface of the runner to subscribe to\n * @returns The current status of the runner (INITIAL, PENDING, SUCCESS, ERROR)\n *\n * @example\n * ```tsx\n * const status = useRunnerStatus(runner.broadcast);\n *\n * return (\n *   <div>\n *     {status === 'PENDING' && <Spinner />}\n *     {status === 'ERROR' && <ErrorMessage />}\n *     {status === 'SUCCESS' && <SuccessMessage />}\n *   </div>\n * );\n * ```\n */\nexport function useRunnerStatus(broadcast: IRunnerBroadcast<any>) {\n  return useSignalValue(broadcast.stateBroadcast).status;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,gBAAgB,WAAkC;CAChE,OAAO,eAAe,UAAU,cAAc,CAAC,CAAC;AAClD"}

package/dist/hooks/use_runner_status_effect.d.ts

@@ -0,0 +1,25 @@
+import { IRunnerBroadcast, Status } from '@j13b/state';
+/**
+ * A hook that runs an effect whenever a runner's status changes.
+ * This is useful for side effects that need to respond to runner status changes
+ * without causing a re-render.
+ *
+ * @template T - The type of the runner's value
+ * @param callback - The effect to run when the runner's status changes
+ * @param task - The broadcast interface of the runner to subscribe to
+ *
+ * @example
+ * ```tsx
+ * useRunnerStatusEffect(
+ *   status => {
+ *     if (status === 'ERROR') {
+ *       // Handle error state
+ *       showErrorToast();
+ *     }
+ *   },
+ *   runner.broadcast
+ * );
+ * ```
+ */
+export declare function useRunnerStatusEffect(callback: (value: Status) => void, task: IRunnerBroadcast<any>): void;
+//# sourceMappingURL=use_runner_status_effect.d.ts.map

package/dist/hooks/use_runner_status_effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_status_effect.d.ts","sourceRoot":"","sources":["../../src/hooks/use_runner_status_effect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EACjC,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,QAK5B"}

package/dist/hooks/use_runner_status_effect.js

@@ -0,0 +1,33 @@
+import { useSignalValueEffect } from "./use_signal_value_effect.js";
+//#region src/hooks/use_runner_status_effect.ts
+/**
+* A hook that runs an effect whenever a runner's status changes.
+* This is useful for side effects that need to respond to runner status changes
+* without causing a re-render.
+*
+* @template T - The type of the runner's value
+* @param callback - The effect to run when the runner's status changes
+* @param task - The broadcast interface of the runner to subscribe to
+*
+* @example
+* ```tsx
+* useRunnerStatusEffect(
+*   status => {
+*     if (status === 'ERROR') {
+*       // Handle error state
+*       showErrorToast();
+*     }
+*   },
+*   runner.broadcast
+* );
+* ```
+*/
+function useRunnerStatusEffect(callback, task) {
+	return useSignalValueEffect((state) => {
+		callback(state.status);
+	}, task.stateBroadcast);
+}
+//#endregion
+export { useRunnerStatusEffect };
+
+//# sourceMappingURL=use_runner_status_effect.js.map

package/dist/hooks/use_runner_status_effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_runner_status_effect.js","names":[],"sources":["../../src/hooks/use_runner_status_effect.ts"],"sourcesContent":["import { IRunnerBroadcast, Status } from '@j13b/state';\nimport { useSignalValueEffect } from './use_signal_value_effect.js';\n\n/**\n * A hook that runs an effect whenever a runner's status changes.\n * This is useful for side effects that need to respond to runner status changes\n * without causing a re-render.\n *\n * @template T - The type of the runner's value\n * @param callback - The effect to run when the runner's status changes\n * @param task - The broadcast interface of the runner to subscribe to\n *\n * @example\n * ```tsx\n * useRunnerStatusEffect(\n *   status => {\n *     if (status === 'ERROR') {\n *       // Handle error state\n *       showErrorToast();\n *     }\n *   },\n *   runner.broadcast\n * );\n * ```\n */\nexport function useRunnerStatusEffect(\n  callback: (value: Status) => void,\n  task: IRunnerBroadcast<any>\n) {\n  return useSignalValueEffect(state => {\n    callback(state.status);\n  }, task.stateBroadcast);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,sBACd,UACA,MACA;CACA,OAAO,sBAAqB,UAAS;EACnC,SAAS,MAAM,MAAM;CACvB,GAAG,KAAK,cAAc;AACxB"}

package/dist/hooks/use_signal_value.d.ts

@@ -0,0 +1,39 @@
+import { IBroadcast } from '@j13b/state';
+/**
+ * A hook that subscribes to a signal's value changes and returns the current value.
+ * The component re-renders when the signal broadcasts. Notifications are batched
+ * by React: a burst of synchronous emissions (e.g. several `set()` calls in one
+ * event tick) renders once with the latest value — intermediate states are never
+ * painted.
+ *
+ * Built on React 18's `useSyncExternalStore`, which makes the hook:
+ * - Tear-free under concurrent rendering (React re-checks the snapshot after render).
+ * - SSR-safe: on the server the current value is rendered via the server snapshot
+ *   without subscribing (no `useLayoutEffect` warnings).
+ *
+ * The snapshot is the broadcast's monotonically increasing `version` rather than
+ * the value itself. This guarantees that no emission is silently ignored:
+ * `Signal.transform()` mutates the value in place and returns the SAME reference,
+ * so value/reference equality (`Object.is`) cannot detect the change — the version
+ * counter is what makes in-place transforms render. A consequence is that a
+ * `set()` of an identical value also triggers one render, since without a deep
+ * comparison it is indistinguishable from an in-place mutation.
+ *
+ * The subscription object returned by `broadcast.subscribe()` is strongly held by
+ * the unsubscribe closure for the lifetime of the subscription (the signal itself
+ * only holds it via WeakRef), and is unsubscribed when the component unmounts or
+ * the broadcast changes.
+ *
+ * @template TValue - The type of the signal's value
+ * @param broadcast - The broadcast interface of the signal to subscribe to
+ * @returns The current value of the signal
+ *
+ * @example
+ * ```tsx
+ * const value = useSignalValue(signal.broadcast);
+ *
+ * return <div>Current value: {value}</div>;
+ * ```
+ */
+export declare function useSignalValue<TValue>(broadcast: IBroadcast<TValue>): TValue;
+//# sourceMappingURL=use_signal_value.d.ts.map

package/dist/hooks/use_signal_value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_signal_value.d.ts","sourceRoot":"","sources":["../../src/hooks/use_signal_value.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,UAqBnE"}

package/dist/hooks/use_signal_value.js

@@ -0,0 +1,51 @@
+import { useCallback, useSyncExternalStore } from "react";
+//#region src/hooks/use_signal_value.ts
+/**
+* A hook that subscribes to a signal's value changes and returns the current value.
+* The component re-renders when the signal broadcasts. Notifications are batched
+* by React: a burst of synchronous emissions (e.g. several `set()` calls in one
+* event tick) renders once with the latest value — intermediate states are never
+* painted.
+*
+* Built on React 18's `useSyncExternalStore`, which makes the hook:
+* - Tear-free under concurrent rendering (React re-checks the snapshot after render).
+* - SSR-safe: on the server the current value is rendered via the server snapshot
+*   without subscribing (no `useLayoutEffect` warnings).
+*
+* The snapshot is the broadcast's monotonically increasing `version` rather than
+* the value itself. This guarantees that no emission is silently ignored:
+* `Signal.transform()` mutates the value in place and returns the SAME reference,
+* so value/reference equality (`Object.is`) cannot detect the change — the version
+* counter is what makes in-place transforms render. A consequence is that a
+* `set()` of an identical value also triggers one render, since without a deep
+* comparison it is indistinguishable from an in-place mutation.
+*
+* The subscription object returned by `broadcast.subscribe()` is strongly held by
+* the unsubscribe closure for the lifetime of the subscription (the signal itself
+* only holds it via WeakRef), and is unsubscribed when the component unmounts or
+* the broadcast changes.
+*
+* @template TValue - The type of the signal's value
+* @param broadcast - The broadcast interface of the signal to subscribe to
+* @returns The current value of the signal
+*
+* @example
+* ```tsx
+* const value = useSignalValue(signal.broadcast);
+*
+* return <div>Current value: {value}</div>;
+* ```
+*/
+function useSignalValue(broadcast) {
+	const subscribe = useCallback((onStoreChange) => {
+		const subscription = broadcast.subscribe(onStoreChange);
+		return () => subscription.unsubscribe();
+	}, [broadcast]);
+	const getSnapshot = useCallback(() => broadcast.version, [broadcast]);
+	useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+	return broadcast.get();
+}
+//#endregion
+export { useSignalValue };
+
+//# sourceMappingURL=use_signal_value.js.map

package/dist/hooks/use_signal_value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_signal_value.js","names":[],"sources":["../../src/hooks/use_signal_value.ts"],"sourcesContent":["import { useCallback, useSyncExternalStore } from 'react';\nimport { IBroadcast } from '@j13b/state';\n\n/**\n * A hook that subscribes to a signal's value changes and returns the current value.\n * The component re-renders when the signal broadcasts. Notifications are batched\n * by React: a burst of synchronous emissions (e.g. several `set()` calls in one\n * event tick) renders once with the latest value — intermediate states are never\n * painted.\n *\n * Built on React 18's `useSyncExternalStore`, which makes the hook:\n * - Tear-free under concurrent rendering (React re-checks the snapshot after render).\n * - SSR-safe: on the server the current value is rendered via the server snapshot\n *   without subscribing (no `useLayoutEffect` warnings).\n *\n * The snapshot is the broadcast's monotonically increasing `version` rather than\n * the value itself. This guarantees that no emission is silently ignored:\n * `Signal.transform()` mutates the value in place and returns the SAME reference,\n * so value/reference equality (`Object.is`) cannot detect the change — the version\n * counter is what makes in-place transforms render. A consequence is that a\n * `set()` of an identical value also triggers one render, since without a deep\n * comparison it is indistinguishable from an in-place mutation.\n *\n * The subscription object returned by `broadcast.subscribe()` is strongly held by\n * the unsubscribe closure for the lifetime of the subscription (the signal itself\n * only holds it via WeakRef), and is unsubscribed when the component unmounts or\n * the broadcast changes.\n *\n * @template TValue - The type of the signal's value\n * @param broadcast - The broadcast interface of the signal to subscribe to\n * @returns The current value of the signal\n *\n * @example\n * ```tsx\n * const value = useSignalValue(signal.broadcast);\n *\n * return <div>Current value: {value}</div>;\n * ```\n */\nexport function useSignalValue<TValue>(broadcast: IBroadcast<TValue>) {\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => {\n      // `subscription` must be strongly referenced: the signal only keeps a\n      // WeakRef to it, so this closure is what keeps the callback alive.\n      const subscription = broadcast.subscribe(onStoreChange);\n      return () => subscription.unsubscribe();\n    },\n    [broadcast]\n  );\n\n  // Version snapshot (deliberate): transform() mutates in place and returns the\n  // same reference, so Object.is on the value would miss changes. The version\n  // increments on every set(), so no emission is ignored (React coalesces a\n  // synchronous burst into a single render of the latest value). Do not\n  // snapshot the value.\n  const getSnapshot = useCallback(() => broadcast.version, [broadcast]);\n\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  return broadcast.get();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,eAAuB,WAA+B;CACpE,MAAM,YAAY,aACf,kBAA8B;EAG7B,MAAM,eAAe,UAAU,UAAU,aAAa;EACtD,aAAa,aAAa,YAAY;CACxC,GACA,CAAC,SAAS,CACZ;CAOA,MAAM,cAAc,kBAAkB,UAAU,SAAS,CAAC,SAAS,CAAC;CAEpE,qBAAqB,WAAW,aAAa,WAAW;CAExD,OAAO,UAAU,IAAI;AACvB"}

package/dist/hooks/use_signal_value_effect.d.ts

@@ -0,0 +1,35 @@
+import { IBroadcast } from '@j13b/state';
+/**
+ * A hook that runs an effect whenever a signal's value changes.
+ * This is useful for side effects that need to respond to signal value changes
+ * without causing a re-render.
+ *
+ * Contract:
+ * - The callback fires exactly once with the current value on mount, and again
+ *   once whenever the `broadcast` identity changes (with the new broadcast's
+ *   current value).
+ * - After that, it fires exactly once per emission — including emissions of an
+ *   identical value (every `set()` notifies subscribers). No double-fires.
+ * - The latest `callback` prop is always used; changing the callback does not
+ *   re-subscribe or re-fire.
+ * - The subscription object is strongly held for the component's lifetime (the
+ *   signal itself only holds it via WeakRef) and is cleaned up on unmount or
+ *   when the broadcast changes.
+ *
+ * @template T - The type of the signal's value
+ * @param callback - The effect to run when the signal's value changes
+ * @param broadcast - The broadcast interface of the signal to subscribe to
+ *
+ * @example
+ * ```tsx
+ * useSignalValueEffect(
+ *   value => {
+ *     // Do something with the new value
+ *     console.log('Value changed:', value);
+ *   },
+ *   signal.broadcast
+ * );
+ * ```
+ */
+export declare function useSignalValueEffect<T>(callback: (value: T) => void, broadcast: IBroadcast<T>): void;
+//# sourceMappingURL=use_signal_value_effect.d.ts.map

package/dist/hooks/use_signal_value_effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_signal_value_effect.d.ts","sourceRoot":"","sources":["../../src/hooks/use_signal_value_effect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAC5B,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,QAyBzB"}

package/dist/hooks/use_signal_value_effect.js

@@ -0,0 +1,54 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+//#region src/hooks/use_signal_value_effect.ts
+var useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+/**
+* A hook that runs an effect whenever a signal's value changes.
+* This is useful for side effects that need to respond to signal value changes
+* without causing a re-render.
+*
+* Contract:
+* - The callback fires exactly once with the current value on mount, and again
+*   once whenever the `broadcast` identity changes (with the new broadcast's
+*   current value).
+* - After that, it fires exactly once per emission — including emissions of an
+*   identical value (every `set()` notifies subscribers). No double-fires.
+* - The latest `callback` prop is always used; changing the callback does not
+*   re-subscribe or re-fire.
+* - The subscription object is strongly held for the component's lifetime (the
+*   signal itself only holds it via WeakRef) and is cleaned up on unmount or
+*   when the broadcast changes.
+*
+* @template T - The type of the signal's value
+* @param callback - The effect to run when the signal's value changes
+* @param broadcast - The broadcast interface of the signal to subscribe to
+*
+* @example
+* ```tsx
+* useSignalValueEffect(
+*   value => {
+*     // Do something with the new value
+*     console.log('Value changed:', value);
+*   },
+*   signal.broadcast
+* );
+* ```
+*/
+function useSignalValueEffect(callback, broadcast) {
+	const callbackRef = useRef(callback);
+	useIsomorphicLayoutEffect(() => {
+		callbackRef.current = callback;
+	}, [callback]);
+	useIsomorphicLayoutEffect(() => {
+		const subscription = broadcast.subscribe((value) => {
+			callbackRef.current(value);
+		});
+		callbackRef.current(broadcast.get());
+		return () => {
+			subscription.unsubscribe();
+		};
+	}, [broadcast]);
+}
+//#endregion
+export { useSignalValueEffect };
+
+//# sourceMappingURL=use_signal_value_effect.js.map

package/dist/hooks/use_signal_value_effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_signal_value_effect.js","names":[],"sources":["../../src/hooks/use_signal_value_effect.ts"],"sourcesContent":["import { useEffect, useLayoutEffect, useRef } from 'react';\nimport type { IBroadcast } from '@j13b/state';\n\n// useLayoutEffect warns during server-side rendering; fall back to useEffect\n// there. Effects never run on the server either way, so behavior is identical.\nconst useIsomorphicLayoutEffect =\n  typeof window !== 'undefined' ? useLayoutEffect : useEffect;\n\n/**\n * A hook that runs an effect whenever a signal's value changes.\n * This is useful for side effects that need to respond to signal value changes\n * without causing a re-render.\n *\n * Contract:\n * - The callback fires exactly once with the current value on mount, and again\n *   once whenever the `broadcast` identity changes (with the new broadcast's\n *   current value).\n * - After that, it fires exactly once per emission — including emissions of an\n *   identical value (every `set()` notifies subscribers). No double-fires.\n * - The latest `callback` prop is always used; changing the callback does not\n *   re-subscribe or re-fire.\n * - The subscription object is strongly held for the component's lifetime (the\n *   signal itself only holds it via WeakRef) and is cleaned up on unmount or\n *   when the broadcast changes.\n *\n * @template T - The type of the signal's value\n * @param callback - The effect to run when the signal's value changes\n * @param broadcast - The broadcast interface of the signal to subscribe to\n *\n * @example\n * ```tsx\n * useSignalValueEffect(\n *   value => {\n *     // Do something with the new value\n *     console.log('Value changed:', value);\n *   },\n *   signal.broadcast\n * );\n * ```\n */\nexport function useSignalValueEffect<T>(\n  callback: (value: T) => void,\n  broadcast: IBroadcast<T>\n) {\n  const callbackRef = useRef(callback);\n\n  // Declared before the subscription effect so the ref is up to date when the\n  // subscription effect (re-)runs in the same commit.\n  useIsomorphicLayoutEffect(() => {\n    callbackRef.current = callback;\n  }, [callback]);\n\n  useIsomorphicLayoutEffect(() => {\n    // `subscription` is strongly referenced by this effect's closure: the\n    // signal only keeps a WeakRef to it, so this is what keeps it alive.\n    const subscription = broadcast.subscribe(value => {\n      callbackRef.current(value);\n    });\n\n    // Fire exactly once with the current value on mount / broadcast change.\n    // Subsequent emissions arrive through the subscription above.\n    callbackRef.current(broadcast.get());\n\n    return () => {\n      subscription.unsubscribe();\n    };\n  }, [broadcast]);\n}\n"],"mappings":";;AAKA,IAAM,4BACJ,OAAO,WAAW,cAAc,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCpD,SAAgB,qBACd,UACA,WACA;CACA,MAAM,cAAc,OAAO,QAAQ;CAInC,gCAAgC;EAC9B,YAAY,UAAU;CACxB,GAAG,CAAC,QAAQ,CAAC;CAEb,gCAAgC;EAG9B,MAAM,eAAe,UAAU,WAAU,UAAS;GAChD,YAAY,QAAQ,KAAK;EAC3B,CAAC;EAID,YAAY,QAAQ,UAAU,IAAI,CAAC;EAEnC,aAAa;GACX,aAAa,YAAY;EAC3B;CACF,GAAG,CAAC,SAAS,CAAC;AAChB"}

package/dist/hooks/use_update.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A hook that provides a way to force component re-renders.
+ *
+ * @returns A function that triggers a re-render when called
+ *
+ * @example
+ * ```tsx
+ * const update = useUpdate();
+ *
+ * // Force a re-render
+ * update();
+ * ```
+ */
+export declare const useUpdate: () => () => void;
+//# sourceMappingURL=use_update.d.ts.map

package/dist/hooks/use_update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_update.d.ts","sourceRoot":"","sources":["../../src/hooks/use_update.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,QAEH,MAAM,IACxB,CAAC"}

package/dist/hooks/use_update.js

@@ -0,0 +1,24 @@
+import { useReducer } from "react";
+//#region src/hooks/use_update.ts
+var updateReducer = (num) => (num + 1) % 1e6;
+/**
+* A hook that provides a way to force component re-renders.
+*
+* @returns A function that triggers a re-render when called
+*
+* @example
+* ```tsx
+* const update = useUpdate();
+*
+* // Force a re-render
+* update();
+* ```
+*/
+var useUpdate = () => {
+	const [, update] = useReducer(updateReducer, 0);
+	return update;
+};
+//#endregion
+export { useUpdate };
+
+//# sourceMappingURL=use_update.js.map

package/dist/hooks/use_update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_update.js","names":[],"sources":["../../src/hooks/use_update.ts"],"sourcesContent":["import { useReducer } from 'react';\n\nconst updateReducer = (num: number): number => (num + 1) % 1_000_000;\n\n/**\n * A hook that provides a way to force component re-renders.\n *\n * @returns A function that triggers a re-render when called\n *\n * @example\n * ```tsx\n * const update = useUpdate();\n *\n * // Force a re-render\n * update();\n * ```\n */\nexport const useUpdate = () => {\n  const [, update] = useReducer(updateReducer, 0);\n  return update as () => void;\n};\n"],"mappings":";;AAEA,IAAM,iBAAiB,SAAyB,MAAM,KAAK;;;;;;;;;;;;;;AAe3D,IAAa,kBAAkB;CAC7B,MAAM,GAAG,UAAU,WAAW,eAAe,CAAC;CAC9C,OAAO;AACT"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * React bindings for @j13b/state.
+ * Hooks for subscribing to Signals, Runners, and Broadcasts from React
+ * components. Requires react and @j13b/state as peer dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { useSignalValue, useRunnerStatus } from '@j13b/react-state';
+ * ```
+ */
+export * from './hooks/use_signal_value.js';
+export * from './hooks/use_signal_value_effect.js';
+export * from './hooks/use_update.js';
+export * from './hooks/use_runner_status.js';
+export * from './hooks/use_runner_status_effect.js';
+export * from './hooks/use_runner_error.js';
+export * from './hooks/use_runner_error_effect.js';
+export * from './hooks/use_runner_progress.js';
+export * from './hooks/use_runner_progress_effect.js';
+export * from './hooks/use_runner_feedback.js';
+export * from './hooks/use_runner_feedback_effect.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uCAAuC,CAAC;AACtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uCAAuC,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+import { useSignalValue } from "./hooks/use_signal_value.js";
+import { useSignalValueEffect } from "./hooks/use_signal_value_effect.js";
+import { useUpdate } from "./hooks/use_update.js";
+import { useRunnerStatus } from "./hooks/use_runner_status.js";
+import { useRunnerStatusEffect } from "./hooks/use_runner_status_effect.js";
+import { useRunnerError } from "./hooks/use_runner_error.js";
+import { useRunnerErrorEffect } from "./hooks/use_runner_error_effect.js";
+import { useRunnerProgress } from "./hooks/use_runner_progress.js";
+import { useRunnerProgressEffect } from "./hooks/use_runner_progress_effect.js";
+import { useRunnerFeedback } from "./hooks/use_runner_feedback.js";
+import { useRunnerFeedbackEffect } from "./hooks/use_runner_feedback_effect.js";
+export { useRunnerError, useRunnerErrorEffect, useRunnerFeedback, useRunnerFeedbackEffect, useRunnerProgress, useRunnerProgressEffect, useRunnerStatus, useRunnerStatusEffect, useSignalValue, useSignalValueEffect, useUpdate };

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@j13b/react-state",
+  "version": "0.1.0",
+  "description": "React bindings for @j13b/state — hooks for Signals, Runners, and Broadcasts.",
+  "license": "Apache-2.0",
+  "author": "Jared J Barnes",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "vite build && node scripts/build-cjs.mjs",
+    "check:types": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "prepublishOnly": "npm run check:types && npm run test:run && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaredjbarnes/react-state.git"
+  },
+  "homepage": "https://github.com/jaredjbarnes/react-state#readme",
+  "bugs": {
+    "url": "https://github.com/jaredjbarnes/react-state/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "hooks",
+    "signal",
+    "signals",
+    "state",
+    "reactive",
+    "broadcast",
+    "subscription"
+  ],
+  "peerDependencies": {
+    "@j13b/state": "^0.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@j13b/state": "^0.2.0",
+    "@testing-library/react": "^14.3.1",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "jsdom": "^24.1.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.4.0",
+    "vite": "^8.1.3",
+    "vite-plugin-dts": "^4.2.0",
+    "vitest": "^4.1.9"
+  }
+}