docs(fetchium): concise docs and 1.0.0 changelog for #67–#74

docs/src/app/api/fetchium-react/page.md

@@ -7,6 +7,19 @@ description: API reference for the fetchium React integration.
 
 React hooks for using Fetchium queries in React components. Built on top of Signalium's `useReactive` hook.
 
+Use these hooks in ordinary React function components. Inside a Signalium `component()`, which is already reactive, call `fetchQuery` directly instead:
+
+```tsx
+import { component } from 'signalium/react';
+import { fetchQuery } from 'fetchium';
+
+const UserList = component(() => {
+  const query = fetchQuery(GetUsers);
+  if (!query.isReady) return <div>Loading...</div>;
+  return <div>{query.value.total} users</div>;
+});
+```
+
 ```ts
 import { useQuery, useSuspenseQuery } from 'fetchium/react';
 ```
@@ -60,12 +73,11 @@ The resolved `QueryResult<T>` includes pagination helpers:
 #### Requirements
 
 - A `QueryClient` must be provided via `QueryClientContext` using Signalium's `ContextProvider`.
-- The component must be wrapped in a Signalium `component()` or use `useReactive` for the reactive system to function.
+- Call it from an ordinary React function component, not inside a Signalium `component()`.
 
 #### Example
 
 ```tsx
-import { component } from 'signalium/react';
 import { useQuery } from 'fetchium/react';
 
 class GetUsers extends RESTQuery {
@@ -77,7 +89,7 @@ class GetUsers extends RESTQuery {
   };
 }
 
-const UserList = component(() => {
+function UserList() {
   const query = useQuery(GetUsers);
 
   if (query.isPending) {
@@ -100,17 +112,18 @@ const UserList = component(() => {
       </ul>
     </div>
   );
-});
+}
 ```
 
 #### With parameters
 
 ```tsx
-const UserProfile = component(({ userId }: { userId: string }) => {
+function UserProfile({ userId }: { userId: string }) {
   const query = useQuery(GetUser, { id: userId });
+  if (!query.isReady) return null;
 
   return <div>{query.value.name}</div>;
-});
+}
 ```
 
 #### With reactive parameters
@@ -120,20 +133,21 @@ import { signal } from 'signalium';
 
 const searchTerm = signal('');
 
-const SearchResults = component(() => {
+function SearchResults() {
   const query = useQuery(SearchUsers, { q: searchTerm });
+  if (!query.isReady) return null;
 
-  // Component re-renders when searchTerm changes and the query refetches
+  // Re-renders when searchTerm changes and the query refetches
   return <div>{query.value.results.length} results</div>;
-});
+}
 ```
 
 #### Notes
 
 - `useQuery` is a thin wrapper around Signalium v3's `useReactive`, which is deep-by-default. It returns a **structurally-shared snapshot** of the query result, so memoized children that receive subtrees as props keep stable references when the underlying data is unchanged.
 - Fetchium registers a custom snapshot for entity proxies so the snapshot walks into entities (instead of returning them by reference), giving you correct re-rendering on entity field changes.
-- The snapshot is a plain-object copy of the query result to prevent accidental mutation of the entity cache. Treat it as read-only: in development builds the snapshot and every nested object and array in it are frozen, so an in-place `sort()`, a `push()` or an assignment in render throws a `TypeError` at that line. Production snapshots are not frozen, and a mutation there is carried forward until the entity changes. Sort a copy (`[...items].sort()`) or use `draft()` from `fetchium` if you need a mutable copy for mutations.
-- `useQuery` never suspends. Reading `.value` while pending returns `undefined`. Use [`useSuspenseQuery`](#usesuspensequery) to suspend on a cold miss.
+- The snapshot is a read-only copy of the query result. Development builds freeze it, so mutating it throws a `TypeError`. Sort a copy (`[...items].sort()`) or use `draft()` from `fetchium` when you need a mutable copy.
+- `useQuery` never suspends: `.value` is `undefined` until the first value arrives. Use [`useSuspenseQuery`](#usesuspensequery) to suspend.
 
 ---
 
@@ -146,13 +160,11 @@ function useSuspenseQuery<T extends Query>(
 ): ReadyReactivePromise<QueryResult<T>>;
 ```
 
-`useQuery` for components under a React `<Suspense>` boundary. It suspends only on a **cold miss**: the query has never produced a value, neither in memory nor, with a synchronous store, in the persisted cache. Anything else renders at once, including a stale value whose refetch is in flight. Refetches never suspend. Because the hook only returns once a value exists, `value` is always defined.
+Like `useQuery`, but suspends while the query has no value yet. Refetches don't suspend, so `value` is always defined. A failed first fetch is thrown to the nearest error boundary, and resetting the boundary retries it.
 
-A cold fetch that fails is thrown to the nearest error boundary. Resetting the boundary (remounting the component) tries the fetch again.
+Changing params to ones with no value yet suspends again. Wrap the change in `startTransition` to keep showing the previous result.
 
-Changing params to ones with no value yet is a cold miss, so the component suspends. Wrap the change in `startTransition` to keep showing the previous result.
-
-Call it from a plain function component. Like `useQuery`, it cannot run inside a Signalium `component()`, which is a reactive context.
+Like `useQuery`, call it from an ordinary React component, not inside a Signalium `component()`.
 
 ```tsx
 import { Suspense } from 'react';
@@ -167,5 +179,3 @@ function UserName({ id }: { id: number }) {
   <UserName id={42} />
 </Suspense>;
 ```
-
-While suspended, the client keeps the query active, since React discards a suspended render without subscribing to anything. The component's commit takes over.