@sigrea/react 0.2.1 → 0.3.1

package/README.md

@@ -1,25 +1,26 @@
 # @sigrea/react
 
-`@sigrea/react` adapts [@sigrea/core](https://www.npmjs.com/package/@sigrea/core) logic 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 `useEffect`, 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.
 - **Deep signal subscriptions.** `useDeepSignal` subscribes to deep signal objects and exposes them for direct mutation.
-- **Logic lifecycles.** `useLogic` mounts logic factories and binds their lifecycles to React components.
+- **Molecule lifecycles.** `useMolcule` mounts molecule factories and binds their lifecycles to React components.
 
 ## Table of Contents
 
 - [Install](#install)
 - [Quick Start](#quick-start)
   - [Consume a Signal](#consume-a-signal)
-  - [Bridge Framework-Agnostic Logic](#bridge-framework-agnostic-logic)
+  - [Bridge Framework-Agnostic Molecules](#bridge-framework-agnostic-molecules)
   - [Work with Deep Signals](#work-with-deep-signals)
 - [API Reference](#api-reference)
   - [useSignal](#usesignal)
   - [useComputed](#usecomputed)
   - [useDeepSignal](#usedeepsignal)
-  - [useLogic](#uselogic)
+  - [useMolcule](#usemolcule)
 - [Testing](#testing)
+- [Handling Scope Cleanup Errors](#handling-scope-cleanup-errors)
 - [Development](#development)
 - [License](#license)
 
@@ -47,13 +48,13 @@ export function CounterLabel() {
 }
 ```
 
-### Bridge Framework-Agnostic Logic
+### Bridge Framework-Agnostic Molecules
 
 ```tsx
-import { defineLogic, signal } from "@sigrea/core";
-import { useLogic, useSignal } from "@sigrea/react";
+import { molecule, signal } from "@sigrea/core";
+import { useMolcule, useSignal } from "@sigrea/react";
 
-const CounterLogic = defineLogic<{ initialCount: number }>()((props) => {
+const CounterMolecule = molecule((props: { initialCount: number }) => {
   const count = signal(props.initialCount);
 
   const increment = () => {
@@ -68,7 +69,7 @@ const CounterLogic = defineLogic<{ initialCount: number }>()((props) => {
 });
 
 export function Counter(props: { initialCount: number }) {
-  const counter = useLogic(CounterLogic, props);
+  const counter = useMolcule(CounterMolecule, props);
   const value = useSignal(counter.count);
 
   return (
@@ -132,27 +133,24 @@ function useDeepSignal<T extends object>(signal: DeepSignal<T>): T
 
 Exposes a deep signal object for direct mutation within the component. Updates to nested properties trigger re-renders, and the subscription is cleaned up when the component unmounts.
 
-### useLogic
+### useMolcule
 
 ```tsx
-function useLogic<TProps, TReturn>(
-  logic: LogicFunction<TProps, TReturn>,
+function useMolcule<TProps, TReturn>(
+  molecule: MoleculeFactory<TProps, TReturn>,
   props?: TProps
 ): TReturn
 ```
 
-Mounts a logic factory and returns its public API. The logic'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 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.
 
 ## Testing
 
 ```tsx
 // tests/Counter.test.tsx
 import { render, screen, fireEvent } from "@testing-library/react";
-import { cleanupLogics } from "@sigrea/core";
 import { Counter } from "../components/Counter";
 
-afterEach(() => cleanupLogics());
-
 it("increments and displays the updated count", () => {
   render(<Counter initialCount={10} />);
 
@@ -163,15 +161,54 @@ it("increments and displays the updated count", () => {
 });
 ```
 
+## Handling Scope Cleanup Errors
+
+For global error handling configuration, see [@sigrea/core - Handling Scope Cleanup Errors](https://github.com/sigrea/core#handling-scope-cleanup-errors).
+
+In React apps, configure the handler in your application entry point before rendering:
+
+```tsx
+// index.tsx or main.tsx
+import { setScopeCleanupErrorHandler } from "@sigrea/core";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+setScopeCleanupErrorHandler((error, context) => {
+  console.error(`Cleanup failed:`, error);
+
+  // Forward to monitoring service
+  if (typeof Sentry !== "undefined") {
+    Sentry.captureException(error, {
+      tags: { scopeId: context.scopeId, phase: context.phase },
+    });
+  }
+});
+
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
 ## Development
 
-Development scripts prefer pnpm. npm or yarn work too, but pnpm keeps dependency resolution identical to CI.
+This repo targets Node.js 20 or later.
+
+If you use mise:
+
+- `mise trust -y` — trust `mise.toml` (first run only).
+- `mise run ci` — run CI-equivalent checks locally.
+- `mise run notes` — preview release notes (optional).
+
+You can also run pnpm scripts directly:
 
 - `pnpm install` — install dependencies.
 - `pnpm test` — run the Vitest suite once (no watch).
+- `pnpm typecheck` — run TypeScript type checking.
+- `pnpm test:coverage` — collect coverage.
 - `pnpm build` — compile via unbuild to produce dual CJS/ESM bundles.
+- `pnpm cicheck` — run CI checks locally.
 - `pnpm dev` — launch the playground counter demo.
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for workflow details.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/index.cjs

@@ -3,21 +3,23 @@
 const react = require('react');
 const core = require('@sigrea/core');
 
-function useLogic(logic, ...args) {
+function useMolcule(molecule, ...args) {
   const props = args.length === 0 ? void 0 : args[0];
-  const stateRef = react.useRef(void 0);
+  const stateRef = react.useRef(
+    void 0
+  );
   const currentState = stateRef.current;
-  const shouldRemount = currentState === void 0 || currentState.logic !== logic || !Object.is(currentState.props, props);
+  const shouldRemount = currentState === void 0 || currentState.molecule !== molecule || !Object.is(currentState.props, props);
   if (shouldRemount) {
     if (currentState !== void 0) {
       currentState.pendingDisposeToken = null;
-      core.cleanupLogic(currentState.instance);
+      core.disposeMolecule(currentState.instance);
       stateRef.current = void 0;
     }
-    const logicArgs = props === void 0 ? [] : [props];
+    const moleculeArgs = props === void 0 ? [] : [props];
     stateRef.current = {
-      instance: core.mountLogic(logic, ...logicArgs),
-      logic,
+      instance: molecule(...moleculeArgs),
+      molecule,
       props,
       subscribers: 0,
       disposed: false,
@@ -26,7 +28,9 @@ function useLogic(logic, ...args) {
   }
   const state = stateRef.current;
   if (state === void 0) {
-    throw new Error("useLogic failed to mount the requested logic instance.");
+    throw new Error(
+      "useMolcule failed to mount the requested molecule instance."
+    );
   }
   const instance = state.instance;
   react.useEffect(() => {
@@ -42,7 +46,7 @@ function useLogic(logic, ...args) {
     return () => {
       const latest = stateRef.current;
       if (latest === void 0 || latest.instance !== instance) {
-        core.cleanupLogic(instance);
+        core.disposeMolecule(instance);
         return;
       }
       latest.subscribers -= 1;
@@ -60,7 +64,7 @@ function useLogic(logic, ...args) {
           current.disposed = true;
           current.pendingDisposeToken = null;
           stateRef.current = void 0;
-          core.cleanupLogic(instance);
+          core.disposeMolecule(instance);
         });
       }
     };
@@ -102,6 +106,6 @@ function useDeepSignal(source) {
 
 exports.useComputed = useComputed;
 exports.useDeepSignal = useDeepSignal;
-exports.useLogic = useLogic;
+exports.useMolcule = useMolcule;
 exports.useSignal = useSignal;
 exports.useSnapshot = useSnapshot;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
 
-declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): T;
@@ -11,4 +11,4 @@ declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
 
 declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
 
-export { useComputed, useDeepSignal, useLogic, useSignal, useSnapshot };
+export { useComputed, useDeepSignal, useMolcule, useSignal, useSnapshot };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
 
-declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): T;
@@ -11,4 +11,4 @@ declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
 
 declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
 
-export { useComputed, useDeepSignal, useLogic, useSignal, useSnapshot };
+export { useComputed, useDeepSignal, useMolcule, useSignal, useSnapshot };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { LogicFunction, LogicArgs, LogicInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
+import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal, Computed, DeepSignal, SnapshotHandler } from '@sigrea/core';
 
-declare function useLogic<TReturn extends object, TProps = void>(logic: LogicFunction<TReturn, TProps>, ...args: LogicArgs<TProps>): LogicInstance<TReturn>;
+declare function useMolcule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): T;
@@ -11,4 +11,4 @@ declare function useDeepSignal<T extends object>(source: DeepSignal<T>): T;
 
 declare function useSnapshot<T>(handler: SnapshotHandler<T>): T;
 
-export { useComputed, useDeepSignal, useLogic, useSignal, useSnapshot };
+export { useComputed, useDeepSignal, useMolcule, useSignal, useSnapshot };

package/dist/index.mjs

@@ -1,21 +1,23 @@
 import { useRef, useEffect, useCallback, useSyncExternalStore, useMemo } from 'react';
-import { cleanupLogic, mountLogic, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
+import { disposeMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
 
-function useLogic(logic, ...args) {
+function useMolcule(molecule, ...args) {
   const props = args.length === 0 ? void 0 : args[0];
-  const stateRef = useRef(void 0);
+  const stateRef = useRef(
+    void 0
+  );
   const currentState = stateRef.current;
-  const shouldRemount = currentState === void 0 || currentState.logic !== logic || !Object.is(currentState.props, props);
+  const shouldRemount = currentState === void 0 || currentState.molecule !== molecule || !Object.is(currentState.props, props);
   if (shouldRemount) {
     if (currentState !== void 0) {
       currentState.pendingDisposeToken = null;
-      cleanupLogic(currentState.instance);
+      disposeMolecule(currentState.instance);
       stateRef.current = void 0;
     }
-    const logicArgs = props === void 0 ? [] : [props];
+    const moleculeArgs = props === void 0 ? [] : [props];
     stateRef.current = {
-      instance: mountLogic(logic, ...logicArgs),
-      logic,
+      instance: molecule(...moleculeArgs),
+      molecule,
       props,
       subscribers: 0,
       disposed: false,
@@ -24,7 +26,9 @@ function useLogic(logic, ...args) {
   }
   const state = stateRef.current;
   if (state === void 0) {
-    throw new Error("useLogic failed to mount the requested logic instance.");
+    throw new Error(
+      "useMolcule failed to mount the requested molecule instance."
+    );
   }
   const instance = state.instance;
   useEffect(() => {
@@ -40,7 +44,7 @@ function useLogic(logic, ...args) {
     return () => {
       const latest = stateRef.current;
       if (latest === void 0 || latest.instance !== instance) {
-        cleanupLogic(instance);
+        disposeMolecule(instance);
         return;
       }
       latest.subscribers -= 1;
@@ -58,7 +62,7 @@ function useLogic(logic, ...args) {
           current.disposed = true;
           current.pendingDisposeToken = null;
           stateRef.current = void 0;
-          cleanupLogic(instance);
+          disposeMolecule(instance);
         });
       }
     };
@@ -98,4 +102,4 @@ function useDeepSignal(source) {
   return useSnapshot(handler);
 }
 
-export { useComputed, useDeepSignal, useLogic, useSignal, useSnapshot };
+export { useComputed, useDeepSignal, useMolcule, useSignal, useSnapshot };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sigrea/react",
-	"version": "0.2.1",
-	"description": "React adapter bindings for Sigrea logic modules.",
+	"version": "0.3.1",
+	"description": "React adapter bindings for Sigrea molecule modules.",
 	"license": "MIT",
 	"type": "module",
 	"packageManager": "pnpm@10.0.0",
@@ -36,7 +36,7 @@
 		"signals",
 		"reactivity",
 		"react",
-		"logic",
+		"molecule",
 		"typescript"
 	],
 	"scripts": {
@@ -49,10 +49,11 @@
 		"test:coverage": "vitest --coverage",
 		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"format": "biome check .",
-		"format:fix": "biome check --write ."
+		"format:fix": "biome check --write .",
+		"cicheck": "pnpm test && pnpm typecheck && pnpm format:fix"
 	},
 	"peerDependencies": {
-		"@sigrea/core": "^0.3.1",
+		"@sigrea/core": "^0.4.3",
 		"react": "^18.0.0 || ^19.0.0",
 		"react-dom": "^18.0.0 || ^19.0.0"
 	},