@sigrea/react 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @sigrea/react
 
-`@sigrea/react` adapts [@sigrea/core](https://www.npmjs.com/package/@sigrea/core) molecule modules and signals for use in React components. It binds scope-aware lifecycles to `useEffect`, synchronizes signal subscriptions with React rendering, and provides hooks for both shallow and deep reactivity.
+`@sigrea/react` adapts [@sigrea/core](https://www.npmjs.com/package/@sigrea/core) molecule modules and signals for use in React components. It binds scope-aware lifecycles to React commits, synchronizes signal subscriptions with React rendering, and provides hooks for both shallow and deep reactivity.
 
 - **Signal subscriptions.** `useSignal` subscribes to signals and computed values, triggering re-renders when they change.
 - **Computed subscriptions.** `useComputed` subscribes to computed values and memoizes them per component instance.
@@ -30,7 +30,7 @@
 npm install @sigrea/react @sigrea/core react react-dom
 ```
 
-Requires React 18+ and Node.js 20 or later.
+Requires React 18+ and Node.js 24 or later.
 
 ## Quick Start
 
@@ -130,10 +130,12 @@ export function ProfileForm() {
 ### useSignal
 
 ```tsx
-function useSignal<T>(signal: Signal<T> | ReadonlySignal<T>): T
+function useSignal<T>(
+  signal: Signal<T> | ReadonlySignal<T> | Computed<T>
+): T
 ```
 
-Subscribes to a signal or computed value and returns its current value. The component re-renders when the signal changes.
+Subscribes to a signal or computed value and returns its current value. The component re-renders when the source changes.
 
 ### useComputed
 
@@ -141,7 +143,7 @@ Subscribes to a signal or computed value and returns its current value. The comp
 function useComputed<T>(source: Computed<T>): T
 ```
 
-Subscribes to a computed value and returns its current value. The component re-renders when the computed value changes, and the subscription is cleaned up when the component unmounts.
+Subscribes to a computed value and returns its current value. This behaves like `useSignal(source)` for computed sources, but keeps the call site explicit when the source is known to be computed.
 
 ### useDeepSignal
 
@@ -164,10 +166,12 @@ Mounts a molecule factory and returns its MoleculeInstance. The molecule's scope
 
 **Lifecycle Timing**
 
-Molecule lifecycles are bound to React's layout effects for precise timing control:
+Molecule lifecycles are bound to React commits for precise timing control:
 
-- In **browser environments**, molecule mounting happens synchronously after DOM updates but before paint (via `useLayoutEffect`). This matches Vue 3's `onMounted` timing, ensuring consistent behavior across frameworks.
-- In **SSR environments**, lifecycle callbacks are deferred to `useEffect` to avoid hydration warnings while maintaining the same cleanup guarantees.
+- In **browser environments**, molecule mounting happens synchronously after the component commits but before paint (via `useLayoutEffect`). This matches Vue 3's `onMounted` timing, ensuring consistent behavior across frameworks.
+- In **SSR environments**, `useMolecule` supports both `renderToString` and streaming server rendering (`renderToPipeableStream`, `renderToReadableStream`). The molecule instance is created during render so components can read its state, but it is never mounted on the server.
+- `onMount`, `watch`, and `watchEffect` registered during setup do not run during server rendering.
+- After a **server render** finishes, the unmounted molecule instance is disposed automatically in a microtask so setup-scope `onDispose` cleanups do not leak across requests.
 
 This design ensures that `onMount` callbacks and `watch` effects activate at the right moment—early enough to set up subscriptions before the first paint, yet safely after the component has committed to the DOM.
 
@@ -220,7 +224,7 @@ createRoot(document.getElementById("root")!).render(<App />);
 
 ## Development
 
-This repo targets Node.js 20 or later.
+This repo targets Node.js 24 or later.
 
 If you use mise:
 

package/dist/index.cjs

@@ -4,6 +4,19 @@ const react = require('react');
 const core = require('@sigrea/core');
 
 const useIsomorphicLayoutEffect = typeof window !== "undefined" ? react.useLayoutEffect : react.useEffect;
+const isServerEnvironment = typeof window === "undefined";
+function schedulePendingDispose(stateRef, instance, token) {
+  queueMicrotask(() => {
+    const current = stateRef.current;
+    if (current === void 0 || current.instance !== instance || current.subscribers > 0 || current.disposed || current.pendingDisposeToken !== token) {
+      return;
+    }
+    current.disposed = true;
+    current.pendingDisposeToken = null;
+    stateRef.current = void 0;
+    core.disposeMolecule(instance);
+  });
+}
 function useMolecule(molecule, ...args) {
   const props = args.length === 0 ? void 0 : args[0];
   if (props !== void 0 && (typeof props !== "object" || props === null)) {
@@ -22,13 +35,19 @@ function useMolecule(molecule, ...args) {
     }
     const snapshot = props === void 0 ? void 0 : { ...props };
     const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
-    stateRef.current = {
+    const nextState = {
       instance: molecule(...moleculeArgs),
       molecule,
       subscribers: 0,
       disposed: false,
       pendingDisposeToken: null
     };
+    stateRef.current = nextState;
+    if (isServerEnvironment) {
+      const token = Symbol("pending-server-dispose");
+      nextState.pendingDisposeToken = token;
+      schedulePendingDispose(stateRef, nextState.instance, token);
+    }
   }
   const state = stateRef.current;
   if (state === void 0) {
@@ -64,16 +83,7 @@ function useMolecule(molecule, ...args) {
         core.unmountMolecule(instance);
         const token = Symbol("pending-dispose");
         latest.pendingDisposeToken = token;
-        queueMicrotask(() => {
-          const current = stateRef.current;
-          if (current === void 0 || current.instance !== instance || current.subscribers > 0 || current.disposed || current.pendingDisposeToken !== token) {
-            return;
-          }
-          current.disposed = true;
-          current.pendingDisposeToken = null;
-          stateRef.current = void 0;
-          core.disposeMolecule(instance);
-        });
+        schedulePendingDispose(stateRef, instance, token);
       }
     };
   }, [instance]);

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 
 declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
-type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T> | Computed<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): T;
 
 declare function useComputed<T>(source: Computed<T>): T;

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 
 declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
-type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T> | Computed<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): T;
 
 declare function useComputed<T>(source: Computed<T>): T;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 
 declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
-type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
+type ReadableSignal<T> = Signal<T> | ReadonlySignal<T> | Computed<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): T;
 
 declare function useComputed<T>(source: Computed<T>): T;

package/dist/index.mjs

@@ -2,6 +2,19 @@ import { useRef, useLayoutEffect, useEffect, useCallback, useSyncExternalStore,
 import { disposeMolecule, mountMolecule, unmountMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
 
 const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+const isServerEnvironment = typeof window === "undefined";
+function schedulePendingDispose(stateRef, instance, token) {
+  queueMicrotask(() => {
+    const current = stateRef.current;
+    if (current === void 0 || current.instance !== instance || current.subscribers > 0 || current.disposed || current.pendingDisposeToken !== token) {
+      return;
+    }
+    current.disposed = true;
+    current.pendingDisposeToken = null;
+    stateRef.current = void 0;
+    disposeMolecule(instance);
+  });
+}
 function useMolecule(molecule, ...args) {
   const props = args.length === 0 ? void 0 : args[0];
   if (props !== void 0 && (typeof props !== "object" || props === null)) {
@@ -20,13 +33,19 @@ function useMolecule(molecule, ...args) {
     }
     const snapshot = props === void 0 ? void 0 : { ...props };
     const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
-    stateRef.current = {
+    const nextState = {
       instance: molecule(...moleculeArgs),
       molecule,
       subscribers: 0,
       disposed: false,
       pendingDisposeToken: null
     };
+    stateRef.current = nextState;
+    if (isServerEnvironment) {
+      const token = Symbol("pending-server-dispose");
+      nextState.pendingDisposeToken = token;
+      schedulePendingDispose(stateRef, nextState.instance, token);
+    }
   }
   const state = stateRef.current;
   if (state === void 0) {
@@ -62,16 +81,7 @@ function useMolecule(molecule, ...args) {
         unmountMolecule(instance);
         const token = Symbol("pending-dispose");
         latest.pendingDisposeToken = token;
-        queueMicrotask(() => {
-          const current = stateRef.current;
-          if (current === void 0 || current.instance !== instance || current.subscribers > 0 || current.disposed || current.pendingDisposeToken !== token) {
-            return;
-          }
-          current.disposed = true;
-          current.pendingDisposeToken = null;
-          stateRef.current = void 0;
-          disposeMolecule(instance);
-        });
+        schedulePendingDispose(stateRef, instance, token);
       }
     };
   }, [instance]);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrea/react",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "React adapter bindings for Sigrea molecule modules.",
 	"license": "MIT",
 	"type": "module",
@@ -17,7 +17,7 @@
 		"url": "https://github.com/sigrea/react/issues"
 	},
 	"engines": {
-		"node": ">=20"
+		"node": ">=24"
 	},
 	"sideEffects": false,
 	"exports": {
@@ -29,16 +29,8 @@
 	},
 	"main": "./dist/index.cjs",
 	"types": "./dist/index.d.ts",
-	"files": [
-		"dist"
-	],
-	"keywords": [
-		"signals",
-		"reactivity",
-		"react",
-		"molecule",
-		"typescript"
-	],
+	"files": ["dist"],
+	"keywords": ["signals", "reactivity", "react", "molecule", "typescript"],
 	"scripts": {
 		"dev": "vite --config playground/vite.config.ts",
 		"build": "unbuild",
@@ -53,13 +45,13 @@
 		"cicheck": "pnpm test && pnpm typecheck && pnpm format:fix"
 	},
 	"peerDependencies": {
-		"@sigrea/core": "^0.5.0",
+		"@sigrea/core": "^0.6.0",
 		"react": "^18.0.0 || ^19.0.0",
 		"react-dom": "^18.0.0 || ^19.0.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
-		"@sigrea/core": "^0.5.0",
+		"@sigrea/core": "^0.6.0",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
 		"@vitejs/plugin-react": "^4.3.3",
@@ -77,9 +69,6 @@
 		"vitest": "^3.2.4"
 	},
 	"pnpm": {
-		"onlyBuiltDependencies": [
-			"lefthook",
-			"@biomejs/biome"
-		]
+		"onlyBuiltDependencies": ["lefthook", "@biomejs/biome"]
 	}
 }