@sigrea/react 0.4.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
 
@@ -51,32 +51,50 @@ export function CounterLabel() {
 ### Bridge Framework-Agnostic Molecules
 
 ```tsx
-import { molecule, signal } from "@sigrea/core";
+import { molecule, readonly, signal } from "@sigrea/core";
 import { useMolecule, useSignal } from "@sigrea/react";
 
-const CounterMolecule = molecule((props: { initialCount: number }) => {
+type CounterProps = {
+  initialCount: number;
+  initialStep: number;
+};
+
+const CounterMolecule = molecule((props: CounterProps) => {
   const count = signal(props.initialCount);
+  const step = signal(props.initialStep);
 
-  const increment = () => {
-    count.value += 1;
-  };
+  function setStep(next: number) {
+    step.value = next;
+  }
 
-  const reset = () => {
+  function increment() {
+    count.value += step.value;
+  }
+
+  function reset() {
     count.value = props.initialCount;
-  };
+  }
 
-  return { count, increment, reset };
+  return {
+    count: readonly(count),
+    step: readonly(step),
+    setStep,
+    increment,
+    reset,
+  };
 });
 
-export function Counter(props: { initialCount: number }) {
+export function Counter(props: CounterProps) {
   const counter = useMolecule(CounterMolecule, props);
-  const value = useSignal(counter.count);
+  const count = useSignal(counter.count);
+  const step = useSignal(counter.step);
 
   return (
     <div>
-      <span>{value}</span>
+      <span>{count}</span>
       <button onClick={counter.increment}>Increment</button>
       <button onClick={counter.reset}>Reset</button>
+      <button onClick={() => counter.setStep(step + 1)}>Step +</button>
     </div>
   );
 }
@@ -88,7 +106,7 @@ export function Counter(props: { initialCount: number }) {
 import { deepSignal } from "@sigrea/core";
 import { useDeepSignal } from "@sigrea/react";
 
-const form = deepSignal({ name: "Sigrea" });
+const form = deepSignal({ name: "Mendako" });
 
 export function ProfileForm() {
   const state = useDeepSignal(form);
@@ -112,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
 
@@ -123,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
 
@@ -136,13 +156,28 @@ Exposes a deep signal object for direct mutation within the component. Updates t
 ### useMolecule
 
 ```tsx
-function useMolecule<TProps, TReturn>(
-  molecule: MoleculeFactory<TProps, TReturn>,
-  props?: TProps
-): TReturn
+function useMolecule<TReturn extends object, TProps extends object | void = void>(
+  molecule: MoleculeFactory<TReturn, TProps>,
+  ...args: MoleculeArgs<TProps>
+): MoleculeInstance<TReturn>
 ```
 
-Mounts a molecule factory and returns its public API. The molecule's scope is bound to the component lifecycle: `onMount` callbacks run after the component mounts, and `onUnmount` callbacks run before it unmounts.
+Mounts a molecule factory and returns its MoleculeInstance. The molecule's scope is bound to the component lifecycle: `onMount` callbacks run after the component mounts, and `onUnmount` callbacks run before it unmounts.
+
+**Lifecycle Timing**
+
+Molecule lifecycles are bound to React commits for precise timing control:
+
+- 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.
+
+**Props Handling**
+
+Props are treated as an initial snapshot. Updating component props does not recreate the molecule instance or update the snapshot; model dynamic values via signals or explicit molecule methods (for example, `setStep`).
 
 ## Testing
 
@@ -189,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

@@ -3,28 +3,51 @@
 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)) {
+    throw new TypeError("useMolecule props must be an object.");
+  }
   const stateRef = react.useRef(
     void 0
   );
   const currentState = stateRef.current;
-  const shouldRemount = currentState === void 0 || currentState.molecule !== molecule || !Object.is(currentState.props, props);
+  const shouldRemount = currentState === void 0 || currentState.molecule !== molecule;
   if (shouldRemount) {
     if (currentState !== void 0) {
       currentState.pendingDisposeToken = null;
       core.disposeMolecule(currentState.instance);
       stateRef.current = void 0;
     }
-    const moleculeArgs = props === void 0 ? [] : [props];
-    stateRef.current = {
+    const snapshot = props === void 0 ? void 0 : { ...props };
+    const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
+    const nextState = {
       instance: molecule(...moleculeArgs),
       molecule,
-      props,
       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) {
@@ -33,7 +56,7 @@ function useMolecule(molecule, ...args) {
     );
   }
   const instance = state.instance;
-  react.useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const state2 = stateRef.current;
     if (state2 === void 0 || state2.instance !== instance) {
       return () => {
@@ -43,6 +66,9 @@ function useMolecule(molecule, ...args) {
       state2.pendingDisposeToken = null;
     }
     state2.subscribers += 1;
+    if (state2.subscribers === 1) {
+      core.mountMolecule(instance);
+    }
     return () => {
       const latest = stateRef.current;
       if (latest === void 0 || latest.instance !== instance) {
@@ -54,18 +80,10 @@ function useMolecule(molecule, ...args) {
         latest.subscribers = 0;
       }
       if (!latest.disposed && latest.subscribers === 0) {
+        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

@@ -1,8 +1,8 @@
 import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
 
-declare function useMolecule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+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

@@ -1,8 +1,8 @@
 import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
 
-declare function useMolecule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+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

@@ -1,8 +1,8 @@
 import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
 
-declare function useMolecule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+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

@@ -1,28 +1,51 @@
-import { useRef, useEffect, useCallback, useSyncExternalStore, useMemo } from 'react';
-import { disposeMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
+import { useRef, useLayoutEffect, useEffect, useCallback, useSyncExternalStore, useMemo } from 'react';
+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)) {
+    throw new TypeError("useMolecule props must be an object.");
+  }
   const stateRef = useRef(
     void 0
   );
   const currentState = stateRef.current;
-  const shouldRemount = currentState === void 0 || currentState.molecule !== molecule || !Object.is(currentState.props, props);
+  const shouldRemount = currentState === void 0 || currentState.molecule !== molecule;
   if (shouldRemount) {
     if (currentState !== void 0) {
       currentState.pendingDisposeToken = null;
       disposeMolecule(currentState.instance);
       stateRef.current = void 0;
     }
-    const moleculeArgs = props === void 0 ? [] : [props];
-    stateRef.current = {
+    const snapshot = props === void 0 ? void 0 : { ...props };
+    const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
+    const nextState = {
       instance: molecule(...moleculeArgs),
       molecule,
-      props,
       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) {
@@ -31,7 +54,7 @@ function useMolecule(molecule, ...args) {
     );
   }
   const instance = state.instance;
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const state2 = stateRef.current;
     if (state2 === void 0 || state2.instance !== instance) {
       return () => {
@@ -41,6 +64,9 @@ function useMolecule(molecule, ...args) {
       state2.pendingDisposeToken = null;
     }
     state2.subscribers += 1;
+    if (state2.subscribers === 1) {
+      mountMolecule(instance);
+    }
     return () => {
       const latest = stateRef.current;
       if (latest === void 0 || latest.instance !== instance) {
@@ -52,18 +78,10 @@ function useMolecule(molecule, ...args) {
         latest.subscribers = 0;
       }
       if (!latest.disposed && latest.subscribers === 0) {
+        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.4.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,17 +45,20 @@
 		"cicheck": "pnpm test && pnpm typecheck && pnpm format:fix"
 	},
 	"peerDependencies": {
-		"@sigrea/core": "^0.4.3",
+		"@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",
-		"@vitejs/plugin-react": "^4.3.3",
+		"@sigrea/core": "^0.6.0",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
-		"changelogen": "^0.6.2",
+		"@vitejs/plugin-react": "^4.3.3",
 		"@vitest/coverage-v8": "^3.2.4",
+		"baseline-browser-mapping": "^2.9.13",
+		"changelogen": "^0.6.2",
+		"jsdom": "^24.1.3",
 		"lefthook": "1.13.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
@@ -71,13 +66,9 @@
 		"typescript": "5.9.3",
 		"unbuild": "3.6.1",
 		"vite": "^5.4.6",
-		"vitest": "^3.2.4",
-		"jsdom": "^24.1.3"
+		"vitest": "^3.2.4"
 	},
 	"pnpm": {
-		"onlyBuiltDependencies": [
-			"lefthook",
-			"@biomejs/biome"
-		]
+		"onlyBuiltDependencies": ["lefthook", "@biomejs/biome"]
 	}
 }