@shivaedev/effect-react 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.2.2 - 2026-10-12
+
+### Added
+
+- Publish `@shivaedev/effect-react/testing.ts` with `render`, `Rendered`, `eventually` and `expectNoReactWarnings` for happy-dom render tests using native atom registries and test RPC layers. `render` exposes its registry, supports rerendering and releases its root, registry and container on unmount. React DOM and Vitest are optional peers needed by the testing entry.
+- Add opt-in `useQuery(atom, { keepPreviousData: true })` to retain the last successful value while a changed query payload loads or fails. Query identity changes still reset displayed data by default, and registry changes clear it even with retention enabled. Native results, typed failures and interruption remain visible.
+- `@shivaedev/effect-react/router.ts` exports `loadQuery(registry, atom, loaderContext)` for TanStack Router loaders. It reads contract query atoms in the application's shared registry, throws typed failures as their original tagged errors, and releases an aborted loader's subscription. TanStack Router is an optional peer.
+
+### Changed
+
+- Document the package's purpose, native atom mental model, query/action usage, session ownership and editor/create workflows; publish the north star and package roadmap with the README.
+- Build package JavaScript, declarations and source maps with TypeScript 7.
+- The reference PostgreSQL order handlers use the shared server live helper and support composing PostgreSQL change delivery. The reference fixture proves commits from two HTTP server processes and a pg-boss worker, rollback silence, and live resync after listener loss.
+
+### Fixed
+
+- Keep the last successful query value during same-identity refreshes, including live invalidation, and after failed refreshes even when the native result has no retained success. `refreshing` reports pending work alongside displayed data.
+
 ## 0.2.1 - 2026-10-05
 
 ### Changed

package/README.md

@@ -1,88 +1,485 @@
 # @shivaedev/effect-react
 
-Small React hooks and a session boundary for native Effect atoms. Query data survives refreshes and failures when the underlying `AsyncResult` contains a previous success. Actions expose ordinary RPC success values and typed failures as native atom state.
+React screens should not rebuild loading, refresh, save and session rules around every native Effect atom. This package gives queries and actions readable state, joins a record to its editable form, and keeps each session's client state together.
 
-This package targets Effect and `@effect/atom-react` **4.0.0-rc.112** and React 19. Native atoms own identity, caching, invalidation, serialization and cancellation. There is no second query cache or RPC contract language.
+## Why you want this
 
-## Native RPC usage
+A refresh should not blank a useful screen. A save response should not erase what someone typed while waiting. Signing in as someone else should not inherit the previous person's draft. These hooks and the session boundary handle those transitions around native atoms and forms:
 
-Given an `Api` service constructed with native `AtomRpc.Service`, and RPCs `Orders` and `RenameOrder`:
+```ts
+const editor = useEditor({
+  query: api.get.query({ id }),
+  fields: InvoiceLineFields,
+  values: (line) => ({ name: line.name, quantity: String(line.quantity) }),
+  save: (values) => api.save.run({ id, ...values }),
+  runtime: InvoiceLinesClient.runtime,
+});
+```
+
+`api` is the application's native RPC binding, and `InvoiceLineFields` describes its inputs. The editor creates the form when the row arrives. A refresh updates untouched fields and keeps edited ones; a save receives the server's normalized result while keeping edits made during the request. The component renders the form and decides what its loading and error messages say.
+
+## Using it
+
+### How to think about it
+
+State belongs to an **atom in a registry**. A query hook reads that atom's native `AsyncResult`; an action hook reads and dispatches a native action atom. Two readers of the same query share its execution. Changing the query atom resets displayed data by default. An application can use `useQuery(atom, { keepPreviousData: true })` to keep the last successful value while a changed payload loads or fails. This retained display belongs to the hook and clears when its registry changes; native atoms still own execution and caching. Editors keep the default reset so a new record starts a new form.
+
+`useQuery` and `useAction` turn native results into `data`, `cause`, `pending` and `refreshing`. A query's same-identity refresh always keeps the last successful value, including after a typed failure, so a component can show data and an error together. An action uses the native result's retained success. Keep the atom's identity stable for the same work: declare it outside render or use the native family's identity, such as `AtomRpc.Service.query(...)`.
+
+An **editor** joins a query atom, an effect-form field schema and a save Effect. The query provides the row; `values(row)` converts it to input values; the schema decodes those values before the save runs. effect-form owns the draft and the per-field merge. A **create form** uses the same submission rules without a query and starts a fresh form after success.
+
+A **session generation** is the string returned by `identify(session)`. `SessionBoundary` owns its client, registry and React subtree. Your auth owner supplies the session and decides when to replace or end it. Cache policy, RPC declarations and transport stay with native Effect and the application; this package supplies their React state and lifecycle boundary.
+
+### 1. Once per application: own the registry
+
+For a screen without a session boundary, wrap it in the native provider:
+
+```tsx
+import { RegistryProvider } from "@effect/atom-react";
+
+export function App() {
+  return <RegistryProvider><Orders /></RegistryProvider>;
+}
+```
+
+`Orders` is the application's feature component. For authenticated screens, use `SessionBoundary` at the authenticated root instead:
+
+```tsx
+import { SessionBoundary } from "@shivaedev/effect-react/session-boundary.ts";
+import { makeOrderClient, OrderScreens } from "./orders.tsx";
+
+interface Session {
+  readonly id: string;
+  readonly credentialGeneration: number;
+  readonly token: string;
+}
+
+export function App({ session, recheck }: {
+  readonly session: Session | undefined;
+  readonly recheck: () => void;
+}) {
+  return (
+    <SessionBoundary
+      session={session}
+      identify={(current) => `${current.id}:${current.credentialGeneration}`}
+      connect={(current) => makeOrderClient(current.token)}
+      recheck={recheck}
+      signedOut={<p>Signed out</p>}
+    >
+      {(client) => <OrderScreens client={client} />}
+    </SessionBoundary>
+  );
+}
+```
+
+`makeOrderClient` and `OrderScreens` belong to the application. A changed generation creates a new client and registry, remounts the screens and disposes the outgoing registry. `undefined` renders `signedOut`. Updating the session object with the same generation keeps the existing client: `connect` does not receive a rotated token until the identity changes. Include the credential generation when the client captures its token, as above.
+
+A query that fails with a tagged `Unauthorized` asks `recheck` to run and keeps its retained data. The auth owner can retry the same session or remove it; the hook does not sign the user out. The boundary also handles React StrictMode's effect replay and preserves component state across hiding and revealing an `<Activity>` subtree, supplying a live registry when revealed.
+
+### 2. Once per feature: native queries and actions
+
+The hooks accept native atoms directly. This complete component module shows query and action state without RPC setup:
 
 ```tsx
-import { RegistryProvider } from "@effect/atom-react"
-import { useAction, useQuery } from "@shivaedev/effect-react/result-state.ts"
-import { Option } from "effect"
-
-function Orders() {
-  const orders = useQuery(Api.query("Orders", {}, {
-    reactivityKeys: ["orders"],
-    timeToLive: "1 minute",
-  }))
-  const rename = useAction(Api.mutation("RenameOrder"))
-
-  function save(id: string, title: string) {
-    rename.dispatch({
-      payload: { id, title },
-      reactivityKeys: ["orders"],
-    })
+import { RegistryProvider } from "@effect/atom-react";
+import { useAction, useQuery } from "@shivaedev/effect-react/result-state.ts";
+import { Effect, Option } from "effect";
+import * as Atom from "effect/unstable/reactivity/Atom";
+
+const report = Atom.make(Effect.succeed({ id: 1, title: "Quarterly report" }));
+const rename = Atom.fn<string>()((title) =>
+  title.trim() === ""
+    ? Effect.fail("Title required" as const)
+    : Effect.succeed({ id: 1, title: title.trim() }),
+);
+
+function Report() {
+  const query = useQuery(report);
+  const action = useAction(rename);
+  return (
+    <section>
+      {Option.match(query.data, {
+        onNone: () => <p>Loading…</p>,
+        onSome: (row) => <h1>{row.title}</h1>,
+      })}
+      {query.refreshing && <p>Refreshing…</p>}
+      {Option.isSome(query.cause) && <p role="alert">Could not load</p>}
+      <button onClick={query.refresh}>Refresh</button>
+      <button disabled={action.pending} onClick={() => action.dispatch("Annual report")}>
+        Rename
+      </button>
+      {Option.isSome(action.data) && <output>{action.data.value.title}</output>}
+      {Option.isSome(action.cause) && <p role="alert">Could not rename</p>}
+    </section>
+  );
+}
+
+export function App() {
+  return <RegistryProvider><Report /></RegistryProvider>;
+}
+```
+
+The example's action returns a value; it does not persist the report or invalidate its query. In an application, use the native RPC query and mutation atoms instead:
+
+```ts
+const notes = useQuery(NotesClient.query("ListNotes", undefined, {
+  reactivityKeys: ["notes"],
+}));
+const create = useAction(NotesClient.mutation("CreateNote"));
+
+create.dispatch({
+  payload: { title: "Morning walk" },
+  reactivityKeys: ["notes"],
+});
+```
+
+`NotesClient` is an application's `AtomRpc.Service` with `ListNotes` and `CreateNote` RPCs. The native mutation's reactivity keys refresh the matching query after success. The package's rendered native RPC fixture exercises this shape through a real repository, including a rejected save that preserves the list.
+
+An action's `dispatch(input)` returns `void`. Read the atom's latest result from `data`, `cause` or `result`. With the default `Atom.fn` action, a later dispatch interrupts the earlier work and the shared state reports the later result. Disable duplicate submissions or give independent work distinct native action atoms. When one caller needs its own success or failure, run the actual RPC Effect through its runtime, as the editor's `save` does; shared atom state cannot identify one invocation's completion.
+
+### Route loaders with TanStack Router
+
+TanStack Router owns routes, navigation, loader data and error components. `@shivaedev/effect-react/router.ts` supplies `loadQuery(registry, atom, loaderContext)` to read a contract query atom in the same registry as React. The atom runs through its native RPC runtime; the loader does not create another runtime or query cache.
+
+This example assumes an application-owned `api.get.query({ id })` returning `{ id, title }`, with a declared `NoteMissing` rejection:
+
+```tsx
+import { RegistryContext } from "@effect/atom-react";
+import { createRootRouteWithContext, createRoute, createRouter, Outlet, RouterProvider, useRouterState } from "@tanstack/react-router";
+import type { ErrorComponentProps } from "@tanstack/react-router";
+import { Predicate } from "effect";
+import * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry";
+import { loadQuery } from "@shivaedev/effect-react/router.ts";
+import { api } from "./notes-client.ts";
+
+const registry = AtomRegistry.make();
+const root = createRootRouteWithContext<{ registry: AtomRegistry.AtomRegistry }>()({
+  component: Shell,
+});
+const note = createRoute({
+  getParentRoute: () => root,
+  path: "/notes/$id",
+  loader: (context) => loadQuery(context.context.registry, api.get.query(context.params), context),
+  component: Note,
+  errorComponent: Failure,
+});
+const router = createRouter({
+  context: { registry },
+  routeTree: root.addChildren([note]),
+  defaultPendingMs: Infinity,
+});
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: typeof router;
   }
+}
+
+function Shell() {
+  const pending = useRouterState({ select: (state) => state.isLoading });
+  return <main>{pending && <p>Loading…</p>}<Outlet /></main>;
+}
+function Note() {
+  const row = note.useLoaderData();
+  return <h1>{row.title}</h1>;
+}
+function Failure({ error }: ErrorComponentProps) {
+  return <p role="alert">{Predicate.isTagged(error, "NoteMissing") ? "Note missing" : "Could not load"}</p>;
+}
+export function App() {
+  return <RegistryContext.Provider value={registry}><RouterProvider router={router} /></RegistryContext.Provider>;
+}
+```
+
+`defaultPendingMs: Infinity` keeps the current route's data visible during navigation; the shell reads TanStack's `isLoading` to display pending state. The new route commits when its loader settles. This is TanStack's pending policy, separate from `useQuery`'s retained display. The render fixture proves navigation between two note payloads, shared loader/component query execution, and a declared RPC failure reaching the error component as the original tagged error.
+
+`loadQuery` waits through a native query refresh instead of returning its retained success. Typed failures are thrown directly, so the route can inspect `_tag` rather than an Effect fiber wrapper. Defects remain failed Promises. TanStack's loader `abortController` cancels the waiting subscription and rejects with `name: "AbortError"`; other readers of the same query can still complete. The application owns the registry's lifetime and disposes it when its client or session ends. Use the same registry for router context and `RegistryContext.Provider`.
+
+Install the optional router peer when using this entry point:
+
+```sh
+pnpm add @tanstack/react-router
+```
+
+### 3. Once per feature: an editor and a create form
+
+The next module assumes `./invoice-lines-client.ts` exports a contract-bound `api` with `get`, `save` and `create`, and its native `InvoiceLinesClient`. `get` returns `{ id, name, quantity }`; both commands return the saved row. The [contract guide](https://github.com/ShivaeDev/platform/blob/main/packages/effect-contract/README.md) describes that binding.
+
+```tsx
+import { useCreate } from "@shivaedev/effect-react/create.ts";
+import { useEditor } from "@shivaedev/effect-react/editor.ts";
+import { useField } from "@shivaedev/effect-form/react.ts";
+import type { Form } from "@shivaedev/effect-form/shape.ts";
+import { Option, Schema } from "effect";
+import { api, InvoiceLinesClient } from "./invoice-lines-client.ts";
+
+const InvoiceLineFields = Schema.Struct({
+  name: Schema.String,
+  quantity: Schema.NumberFromString,
+});
+type Fields = typeof InvoiceLineFields.fields;
+
+function Inputs<A, E, ER>({ form }: { readonly form: Form<Fields, A, E, ER> }) {
+  const name = useField(form, "name");
+  const quantity = useField(form, "quantity");
+  return (
+    <>
+      <label>
+        Name
+        <input name="name" value={name.value} onBlur={name.onBlur}
+          onChange={(event) => name.onChange(event.target.value)} />
+      </label>
+      {name.error && <p role="alert">{name.error}</p>}
+      <label>
+        Quantity
+        <input name="quantity" value={quantity.value} onBlur={quantity.onBlur}
+          onChange={(event) => quantity.onChange(event.target.value)} />
+      </label>
+      {quantity.error && <p role="alert">{quantity.error}</p>}
+    </>
+  );
+}
 
-  if (Option.isNone(orders.data)) {
-    return Option.isSome(orders.cause)
-      ? <button onClick={orders.refresh}>Retry</button>
-      : <p>Loading…</p>
+export function InvoiceLineEditor({ id }: { readonly id: number }) {
+  const editor = useEditor({
+    query: api.get.query({ id }),
+    fields: InvoiceLineFields,
+    values: (line) => ({ name: line.name, quantity: String(line.quantity) }),
+    save: (values) => api.save.run({ id, ...values }),
+    runtime: InvoiceLinesClient.runtime,
+  });
+  if (editor.form === undefined) {
+    return Option.isSome(editor.query.cause)
+      ? <button onClick={editor.query.refresh}>Retry</button>
+      : <p>Loading…</p>;
   }
-  return <OrderList orders={orders.data.value} refreshing={orders.refreshing}
-    pending={rename.pending} onRename={save} />
+  return (
+    <form onSubmit={(event) => { event.preventDefault(); editor.save(); }}>
+      <Inputs form={editor.form} />
+      {Option.isSome(editor.query.cause) && <p role="alert">Could not refresh</p>}
+      {Option.isSome(editor.failure) && <p role="alert">Could not save</p>}
+      <button type="submit" disabled={editor.saving}>Save</button>
+      <button type="button" onClick={editor.query.refresh}>Refresh</button>
+      <button type="button" onClick={editor.revert}>Revert</button>
+      <p>{editor.saving ? "Saving" : editor.dirty ? "Unsaved" : "Saved"}</p>
+    </form>
+  );
 }
 
-function App() {
-  return <RegistryProvider><Orders /></RegistryProvider>
+export function InvoiceLineCreate() {
+  const create = useCreate({
+    fields: InvoiceLineFields,
+    initialValues: { name: "", quantity: "" },
+    create: api.create.run,
+    runtime: InvoiceLinesClient.runtime,
+  });
+  return (
+    <form onSubmit={(event) => { event.preventDefault(); create.save(); }}>
+      <Inputs form={create.form} />
+      {Option.isSome(create.failure) && <p role="alert">Could not create</p>}
+      <button type="submit" disabled={create.saving}>Create</button>
+      {Option.isSome(create.created) && <output>Created {create.created.value.name}</output>}
+    </form>
+  );
 }
 ```
 
-`Api` and `OrderList` above are application definitions. The hooks also accept non-RPC atoms built with `Atom.make`, `Atom.fn` or an atom runtime. Stable atom identities should be declared outside render, created with native `Atom.family`, or memoized; native `Api.query(...)` already supplies its own family.
+The form holds strings for both inputs. Its schema decodes `quantity` to a number before `save` or `create` receives it. `values(row)` converts server rows back to input values. The runtime supplies the services needed by schema decoding and the command Effect.
 
-## Editing
+The editor's form is absent until its first row arrives. A different query atom creates a new form, so another record starts without the previous draft. Refresh results adopt untouched fields and leave edited fields alone. Saved rows supply server normalization while edits made during the save remain dirty. A refresh failure keeps the draft, and `query.refresh()` retries.
 
-`useEditor` from `@shivaedev/effect-react/editor.ts` and `useCreate` from `@shivaedev/effect-react/create.ts` bind `@shivaedev/effect-form` to a query atom and a save Effect, for example from an `@shivaedev/effect-contract` binding `api`. `@shivaedev/effect-form` is an optional peer dependency: install it only when you import these modules; the other modules do not load it. See the [editing guide](../../docs/framework/editing.md).
+`save()` ignores a second call while saving. Submitting through effect-form's own `useSubmit(form).run()` or setting `form.submit` also settles the editor or create hook: an editor receives the saved row, and a create records its result and resets.
+
+A successful create replaces its form with one at `initialValues`, keeping fields edited after submission began, including while an async schema decoded it. The next entry starts without the previous entry's displayed field errors. `created` holds the successful result as an `Option`.
+
+### Field rejections and other failures
+
+A tagged error with string `_tag` and `message`, and a `field` naming a form field, becomes that field's message by default. Other save failures appear in `failure`. Use `rejectField` when the server uses a different shape or field name:
 
 ```ts
 const editor = useEditor({
-  query: api.get.query({ id }),
-  fields: InvoiceLineFields,
-  values: (line) => ({ name: line.name, quantity: String(line.quantity) }),
-  save: (values) => api.save.run({ id, ...values }),
-  runtime: InvoiceLinesClient.runtime,
-})
-// editor.query: QueryState; editor.form: Form | undefined until data first arrives
-// editor.save(), editor.saving, editor.dirty, editor.failure (non-field failures), editor.revert()
+  query,
+  fields: Schema.Struct({ title: Schema.String }),
+  values: (row) => ({ title: row.title }),
+  save,
+  runtime,
+  rejectField: (error) => error._tag === "SubtitleRejected"
+    ? { field: "title", message: error.message }
+    : undefined,
+});
+```
+
+Here `save` has a tagged `SubtitleRejected` failure referring to the server's `subtitle`, while the form calls the input `title`. If a tagged error's field type includes names outside the form, `rejectField` is required at compile time. This includes a broad `string` field or an optional field whose type is broader than the form's names. The mapper can return `undefined` to leave an error as a non-field failure.
+
+### Resume and refresh policy
+
+Keep the signal and query identities stable:
+
+```ts
+import { resumeSignal } from "@shivaedev/effect-react/resume-signal.ts";
+import { Effect } from "effect";
+import * as Atom from "effect/unstable/reactivity/Atom";
+
+const resume = resumeSignal({ window });
+const query = Atom.makeRefreshOnSignal(resume)(Atom.make(Effect.succeed("ready")));
+```
+
+`resumeSignal` changes on visible `visibilitychange` and visible `online` events. Hidden browser events do not refresh the query. An optional `native` source subscribes a callback and returns its unsubscribe function; its callback also changes the signal. Registry disposal removes the listeners. This module uses the shared [effect-contract resume implementation](https://github.com/ShivaeDev/platform/blob/main/packages/effect-contract/src/resume.ts).
+
+Use native stale-while-revalidate policy when a resume should refresh only stale data:
+
+```ts
+const query = Atom.swr(atom, {
+  focusSignal: resume,
+  revalidateOnFocus: true,
+  staleTime: "1 hour",
+});
 ```
 
-The form is created from the first successful value and replaced when the query atom changes, so a different id never inherits a draft. Each new query value and each saved result is received per field: untouched fields adopt it, fields edited meanwhile keep local input. A tagged failure shaped `{ _tag, field, message }` whose `field` names a form field, such as an `@shivaedev/effect-contract` `fieldRejection`, becomes that field's message; pass `rejectField` to map differently. When a tagged rejection's `field` type names a field the form lacks, `rejectField` is required at compile time. Other failures appear in `failure`. `save()` does nothing while a save is running; submitting through the form's own `submit` atom settles the same way. Render fields with `useField(editor.form, name)` from `@shivaedev/effect-form/react`.
+`atom` is the underlying native query. `Atom.swr` owns the staleness decision; the signal only reports that the application resumed.
+
+### API
+
+`useQuery(atom)` and `useAction(atom)` return these shared fields:
 
-`useCreate({ fields, initialValues, create, runtime, rejectField })` returns the same save state with an always-present `form` and `created: Option<A>`. After success it replaces the form with a fresh one at `initialValues`, carrying over fields changed while the create was in flight, so their messages and submitted state do not leak into the next entry.
+| Field | Meaning |
+| --- | --- |
+| `result` | Native `AsyncResult<A, E>`. |
+| `data` | `Option<A>` from the current or retained success. Queries can retain displayed data even when the native `result` has no value. |
+| `cause` | `Option<Cause<E>>` from a failed result. |
+| `pending` | The native result is waiting. |
+| `refreshing` | The result is waiting and successful data is available. |
 
-## State
+`useQuery(atom, options?)` adds `refresh(): void`; `useAction` adds `dispatch(input): void`. `QueryOptions.keepPreviousData` defaults to `false` and controls retention across query atom changes. Same-identity refresh retention is always enabled. `result` and `cause` describe the current native query even when `data` displays a previous atom's success. Success, input and typed failure types are inferred from the supplied atom.
 
-Both hooks return:
+| Defining module | Exports |
+| --- | --- |
+| `result-state.ts` | `useQuery`, `useAction`, `isUnauthorized`; `ResultState`, `QueryOptions`, `QueryState`, `ActionState`. |
+| `session-boundary.ts` | `SessionBoundary`, `useSessionRecheck`; `SessionBoundaryProps`. |
+| `editor.ts` | `useEditor`; `Editor`, `EditorConfig`. |
+| `create.ts` | `useCreate`; `Create`, `CreateConfig`. |
+| `resume-signal.ts` | `resumeSignal`; `ResumeSource`, `ResumeWindow`, `ResumeOptions`. |
+| `router.ts` | `loadQuery`. |
+| `save-state.ts` | `useSaveState`; `SaveState`. |
+| `field-rejection.ts` | `fieldRejectionOf`, `rejecting`; `FieldRejection`, `RejectField`, `FieldRejectionMapping`, `AtomServices`. |
+| `testing.ts` | `render`, `eventually`, `expectNoReactWarnings`; `Rendered`. |
+| `submission.ts` | `submission`; `Submission`, `SubmissionConfig`. |
 
-- `result`: the unchanged native `AsyncResult`, including its discriminant and typed failure.
-- `data`: `Option<A>`, using the current or previous successful result. A valid `undefined` success remains `Some(undefined)`.
-- `cause`: `Option<Cause<E>>`, preserving failures, defects and interruption information.
-- `pending`: whether the native result is waiting, including refreshes.
-- `refreshing`: waiting while successful data is available.
+Import the defining `.ts` module, such as `@shivaedev/effect-react/editor.ts`. There is no root import. `SessionBoundaryProps` supplies `session`, `identify`, `connect`, `recheck`, a client-to-children function and optional `signedOut`; `useSessionRecheck()` reads that boundary's callback.
 
-`useQuery(atom)` additionally returns `refresh()`. It does not carry data across different query atoms. `useAction(atom)` additionally returns `dispatch(input): void`. Read its ordinary success value from `data` and errors from `cause` or the discriminated `result`. Dispatch does not return a completion promise. For imperative per-invocation outcomes (such as closing only the editor whose save succeeded), execute the actual native RPC Effect through your application runtime.
+`Editor` exposes `query`, optional `form` and `SaveState`; `Create` exposes `form`, `created` and `SaveState`. `SaveState` has `save`, `saving`, `dirty`, `failure` and `revert`. Prefer the two complete hooks when binding a form to a command. The lower-level form modules expose the same composition pieces: `submission` makes a form and its submission snapshot reader, `rejecting` maps save failures through a submitter, and `useSaveState` observes submission and invokes a success callback.
+
+### Render tests in happy-dom
+
+Use `@shivaedev/effect-react/testing.ts` with Vitest's `happy-dom` environment. Install effect-contract for the example's query and command declarations, and the testing peers and environment in your app's dev dependencies:
+
+```sh
+pnpm add @shivaedev/effect-contract
+pnpm add -D vitest happy-dom react-dom@19.2.8 @types/react-dom
+```
+
+Configure Vitest with `test: { environment: "happy-dom" }`, or select that environment for your DOM test project. This complete `notes.dom.test.tsx` renders a component that runs a declared query and command against native RPC test handlers:
+
+```tsx
+import { Effect, Option, Ref, Schema } from "effect";
+import * as AtomRpc from "effect/unstable/reactivity/AtomRpc";
+import { RpcTest } from "effect/unstable/rpc";
+import { act, createElement } from "react";
+import { expect, it } from "vitest";
+import { bind } from "@shivaedev/effect-contract/bind.ts";
+import { contract } from "@shivaedev/effect-contract/contract.ts";
+import { collection } from "@shivaedev/effect-contract/keys.ts";
+import { command, query } from "@shivaedev/effect-contract/operation.ts";
+import { useAction, useQuery } from "@shivaedev/effect-react/result-state.ts";
+import { eventually, expectNoReactWarnings, render } from "@shivaedev/effect-react/testing.ts";
 
-## Scope and concurrency
+Object.assign(globalThis, { "IS_REACT_ACT_ENVIRONMENT": true });
+expectNoReactWarnings();
 
-Mount `SessionBoundary` at the authenticated root. For each session key it builds one credential-bound client and one registry, remounts its subtree when the key changes, renders `signedOut` without a session and disposes the outgoing registry. `connect` runs once per key, so a client must read a rotating credential per request, or the key must include a credential generation. A subtree hidden by `<Activity>` keeps its state and gets a fresh registry on reveal. Inside it, `useQuery` and `useAction` call the boundary's `recheck` when a result fails with a tagged `Unauthorized` error; they keep retained data until the auth owner ends the session. See [client lifecycle](../../docs/framework/client-lifecycle.md). SSR isolation is not implemented.
+const notes = collection("notes", Schema.Number);
+const List = query("list", { reads: () => [notes.list], success: Schema.Array(Schema.String) });
+const Add = command("add", { invalidates: () => [notes.list], payload: { title: Schema.String } });
+const Notes = contract("notes", { commands: [Add], queries: [List] });
+
+const handlers = Notes.toLayer(
+	Effect.gen(function* () {
+		const stored = yield* Ref.make<readonly string[]>([]);
+		return Notes.of({
+			"notes.add": ({ title }) => Ref.update(stored, (all) => [...all, title]),
+			"notes.list": () => Ref.get(stored).pipe(Effect.delay("20 millis")),
+		});
+	}),
+);
+class Client extends AtomRpc.Service<Client>()("test/Notes", {
+	group: Notes,
+	makeEffect: RpcTest.makeClient(Notes, { flatten: true }),
+	protocol: handlers,
+}) {}
+const api = bind(Notes, Client);
+const add = Client.runtime.fn(api.add.run);
+function NotesView() {
+	const list = useQuery(api.list.query());
+	const action = useAction(add);
+	return createElement(
+		"section",
+		null,
+		createElement("output", null, Option.getOrElse(list.data, () => []).join(", ")),
+		createElement(
+			"button",
+			{
+				disabled: list.pending || action.pending,
+				onClick: () => action.dispatch({ title: "Morning walk" }),
+				type: "button",
+			},
+			"Add",
+		),
+	);
+}
+
+it("renders a query and refetches it after a command through a test RPC layer", async () => {
+	const view = await render(createElement(NotesView));
+	try {
+		await eventually(() => expect(view.container.querySelector("button")?.disabled).toBe(false));
+		expect(view.container.querySelector("output")?.textContent).toBe("");
+		await act(async () => view.container.querySelector("button")?.click());
+		await eventually(() => {
+			expect(view.container.querySelector("output")?.textContent).toBe("Morning walk");
+			expect(view.container.querySelector("button")?.disabled).toBe(false);
+		});
+	} finally {
+		await view.unmount();
+	}
+});
+```
+
+`render(node)` returns the attached `container`, its fresh native `registry`, `render(nextNode)` to update the same root and registry, and `unmount()` to release the root, registry and container. Always unmount in `finally`. Keep component interactions inside React's `act`. `eventually(assert)` retries the assertion for up to three seconds, allowing pending responses to settle inside `act` between attempts; it throws the last assertion failure on timeout. `expectNoReactWarnings()` registers a Vitest hook that fails a test if it logged to `console.error`.
+
+The RPC layer stays application-owned: replace these in-memory handlers with the service Layer your component needs. This test proves rendered query data and command-triggered invalidation in happy-dom, without an HTTP server or a physical browser. The generic `effect-test` package has no React dependency.
+
+### Testing a feature through its stack
+
+The [order feature’s application-owned kit](https://github.com/ShivaeDev/platform/tree/main/packages/effect-react/src/test-support/order-example) uses `test-story` above `effect-test` to compose real PostgreSQL, HTTP RPC and the actual React components. Its screen traits mount fresh native atom registries and scoped roots; its verbs dispatch DOM events and wait for rendered output. The [stories](https://github.com/ShivaeDev/platform/blob/main/packages/effect-react/src/orderStory.dom.spec.tsx) verify list refresh through `useAction` and rejected-input retention and retry through `useEditor`, with persistence read from a separate PostgreSQL pool. These tests require `PLATFORM_EFFECT_SQL_TEST_DATABASE_URL`; DOM and loopback HTTP establish no physical browser, SSR or mobile behavior.
+
+### Install, setup and limits
+
+```sh
+pnpm add @shivaedev/effect-react @effect/atom-react@4.0.0-rc.112 effect@4.0.0-rc.112 react@19.2.8
+```
+
+For editor, create or lower-level form modules, also install the optional form peer:
+
+```sh
+pnpm add @shivaedev/effect-form
+```
 
-`resumeSignal({ window, native })` is an atom that increments when the page becomes visible, when the network returns while visible, and when an injected native resume source fires. Feed it to native `Atom.makeRefreshOnSignal` or to `Atom.swr` as `focusSignal`.
+Query, action, session and resume modules do not require effect-form. The package declares Node 24 or newer and peers on Effect, atom-react and React; this repository checks Effect and atom-react `4.0.0-rc.112` with React `19.2.8`.
 
-State belongs to the **supplied atom in the registry**, not to an individual hook call. In particular, native `Api.mutation("RenameOrder")` returns the same atom for that operation. Components using it share pending/result state and the native action's concurrency behavior. With the default native action, a later dispatch interrupts the earlier one; shared state then represents the later action. Disable duplicate submissions, or create distinct native action atoms when independent lifetimes are needed. Native registry retention and disposal govern cleanup. The package adds no optimistic policy, offline queue, form state or parallel action scheduler.
+- Query identity, TTL, invalidation and action concurrency remain native atom policies. Put the registry at the lifetime boundary those policies need.
+- Action state describes the atom's latest result. A `dispatch` is not a Promise or a separate result handle.
+- A session generation is application-defined. Credentials captured by `connect` require a changed generation when they rotate.
+- The package has no SSR registry/hydration adapter, offline write queue or optimistic reconciliation policy.
+- DOM tests and an injected resume source do not prove real-browser or mobile lifecycle behavior. The real HTTP order fixture proves its local composition, not a deployed host's auth, cancellation or rendering policy.
 
-## Validation
+The full design is in [the north star](https://github.com/ShivaeDev/platform/blob/main/packages/effect-react/docs/north-star.md). Implementation status and unresolved choices are in [the roadmap](https://github.com/ShivaeDev/platform/blob/main/packages/effect-react/docs/roadmap.md).
 
-React DOM tests exercise native atom execution, refresh retention, typed failures and query identity changes. Compiler fixtures check success/input/error inference. The package smoke test installs its tarball into a standalone consumer and checks both compiler versions and NodeNext resolution.
+The [reference PostgreSQL feature](https://github.com/ShivaeDev/platform/blob/main/docs/framework/composed-example.md) uses the same leased database infrastructure and a scoped story verb for its real server and rendered clients. It is a test fixture, not a copyable app; an app template is still needed. Its stories verify commit visibility, live refresh of a second editor, retained local edits and rollback without publication.

package/dist/client/create.d.ts

@@ -0,0 +1,17 @@
+import { type Effect, Option, type Schema } from "effect";
+import type * as Atom from "effect/unstable/reactivity/Atom";
+import type { Decoded, Encoded, FieldFailure, Fields, Form, Services } from "@shivaedev/effect-form/shape.ts";
+import type { AtomServices, FieldRejectionMapping } from "#field-rejection.ts";
+import { type SaveState } from "./saveState.ts";
+export type CreateConfig<TFields extends Fields, TCreated, TSaveError, R, TRuntimeError> = {
+    readonly fields: Schema.Struct<TFields>;
+    readonly initialValues: Encoded<TFields>;
+    readonly create: (values: Decoded<TFields>) => Effect.Effect<TCreated, TSaveError, AtomServices<R>>;
+    readonly runtime: Atom.AtomRuntime<Services<TFields, R>, TRuntimeError>;
+} & FieldRejectionMapping<TFields, TSaveError>;
+export interface Create<TFields extends Fields, TCreated, TSaveError, TRuntimeError> extends SaveState<TSaveError | TRuntimeError> {
+    readonly created: Option.Option<TCreated>;
+    readonly form: Form<TFields, TCreated, TSaveError | FieldFailure, TRuntimeError>;
+}
+export declare function useCreate<TFields extends Fields, TCreated, TSaveError, R, TRuntimeError>(config: CreateConfig<TFields, TCreated, TSaveError, R, TRuntimeError>): Create<TFields, TCreated, TSaveError, TRuntimeError>;
+//# sourceMappingURL=create.d.ts.map

package/dist/client/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/client/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAS,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AACjE,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAC;AAE7D,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC9G,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,EAAE,KAAK,SAAS,EAAgB,MAAM,gBAAgB,CAAC;AAC9D,MAAM,MAAM,YAAY,CAAC,OAAO,SAAS,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,IAAI;IAC1F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IACpG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;CACxE,GAAG,qBAAqB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AAC/C,MAAM,WAAW,MAAM,CAAC,OAAO,SAAS,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,CAAE,SAAQ,SAAS,CAAC,UAAU,GAAG,aAAa,CAAC;IACjI,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,YAAY,EAAE,aAAa,CAAC,CAAC;CACjF;AAKD,wBAAgB,SAAS,CAAC,OAAO,SAAS,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EACvF,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,CAAC,GACnE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,CAAC,CAiBtD"}