@intrig/plugin-react 0.0.1

package/src/lib/templates/docs/__snapshots__/sse-hook.spec.ts.snap

@@ -0,0 +1,2008 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`reactSseHookDocs > handles case-insensitive path parameter detection 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamOrderUpdates } from "@intrig/react/orders/{orderId}/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamOrderUpdatesResp, streamOrderUpdates] = useStreamOrderUpdates({
+  clearOnUnmount: true,
+});
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamOrderUpdates } from "@intrig/react/orders/{orderId}/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamOrderUpdatesResp, streamOrderUpdates] = useStreamOrderUpdates({
+    clearOnUnmount: true,
+  });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamOrderUpdates(streamOrderUpdatesParams); // start stream
+  }, [streamOrderUpdates]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamOrderUpdatesResp)) {
+      setMessages((prev) => [...prev, streamOrderUpdatesResp.data]);
+    }
+  }, [streamOrderUpdatesResp]);
+
+  if (isError(streamOrderUpdatesResp)) return <>An error occurred</>;
+  if (isPending(streamOrderUpdatesResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamOrderUpdatesResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { StreamOrderUpdatesParams } from "@intrig/react/orders/{orderId}/StreamOrderUpdates.params";
+import type { StreamOrderUpdatesResponseBody } from "@intrig/react/orders/{orderId}/StreamOrderUpdates.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamOrderUpdates(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: StreamOrderUpdatesParams;
+  body?: unknown;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<StreamOrderUpdatesResponseBody /* or event payload type */, any>,
+  // Start streaming:
+  (req: { params?: StreamOrderUpdatesParams; body?: unknown }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamOrderUpdatesResp.data\` **only while** \`isPending(streamOrderUpdatesResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamOrderUpdatesResp, streamOrderUpdates] = useStreamOrderUpdates({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  streamOrderUpdates(streamOrderUpdatesParams);
+}, [streamOrderUpdates]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamOrderUpdatesResp))
+    setMessages((m) => [...m, streamOrderUpdatesResp.data]);
+}, [streamOrderUpdatesResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamOrderUpdatesResp)
+  ? streamOrderUpdatesResp.data
+  : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [streamOrderUpdatesResp, streamOrderUpdates, clearStreamOrderUpdates] =
+  useStreamOrderUpdates();
+
+const start = () => streamOrderUpdates(streamOrderUpdatesParams);
+const stop = () => clearStreamOrderUpdates();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamOrderUpdates } from "@intrig/react/orders/{orderId}/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamOrderUpdatesResp, streamOrderUpdates] = useStreamOrderUpdates({
+    clearOnUnmount: true,
+  });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamOrderUpdates(streamOrderUpdatesParams);
+  }, [streamOrderUpdates]);
+
+  useEffect(() => {
+    if (isPending(streamOrderUpdatesResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, streamOrderUpdatesResp.data]));
+    }
+  }, [streamOrderUpdatesResp]);
+
+  if (isError(streamOrderUpdatesResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamOrderUpdatesResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamOrderUpdatesResp) && (
+        <>Completed ({events.length} events)</>
+      )}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamOrderUpdates\` when appropriate.
+"
+`;
+
+exports[`reactSseHookDocs > handles complex SSE endpoint with body and multiple params 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamAnalytics } from "@intrig/react/analytics/{dashboardId}/stream/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamAnalyticsResp, streamAnalytics] = useStreamAnalytics({
+  clearOnUnmount: true,
+});
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamAnalytics } from "@intrig/react/analytics/{dashboardId}/stream/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamAnalyticsResp, streamAnalytics] = useStreamAnalytics({
+    clearOnUnmount: true,
+  });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamAnalytics(streamAnalyticsRequest, streamAnalyticsParams); // start stream
+  }, [streamAnalytics]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamAnalyticsResp)) {
+      setMessages((prev) => [...prev, streamAnalyticsResp.data]);
+    }
+  }, [streamAnalyticsResp]);
+
+  if (isError(streamAnalyticsResp)) return <>An error occurred</>;
+  if (isPending(streamAnalyticsResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamAnalyticsResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { StreamAnalyticsRequest } from "@intrig/react/demo_api/components/schemas/StreamAnalyticsRequest";
+import type { StreamAnalyticsParams } from "@intrig/react/analytics/{dashboardId}/stream/StreamAnalytics.params";
+import type { StreamAnalyticsResponseBody } from "@intrig/react/analytics/{dashboardId}/stream/StreamAnalytics.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamAnalytics(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: StreamAnalyticsParams;
+  body?: StreamAnalyticsRequest;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<StreamAnalyticsResponseBody /* or event payload type */, any>,
+  // Start streaming:
+  (req: {
+    params?: StreamAnalyticsParams;
+    body?: StreamAnalyticsRequest;
+  }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamAnalyticsResp.data\` **only while** \`isPending(streamAnalyticsResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamAnalyticsResp, streamAnalytics] = useStreamAnalytics({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  streamAnalytics(streamAnalyticsRequest, streamAnalyticsParams);
+}, [streamAnalytics]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamAnalyticsResp))
+    setMessages((m) => [...m, streamAnalyticsResp.data]);
+}, [streamAnalyticsResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamAnalyticsResp)
+  ? streamAnalyticsResp.data
+  : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [streamAnalyticsResp, streamAnalytics, clearStreamAnalytics] =
+  useStreamAnalytics();
+
+const start = () =>
+  streamAnalytics(streamAnalyticsRequest, streamAnalyticsParams);
+const stop = () => clearStreamAnalytics();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamAnalytics } from "@intrig/react/analytics/{dashboardId}/stream/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamAnalyticsResp, streamAnalytics] = useStreamAnalytics({
+    clearOnUnmount: true,
+  });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamAnalytics(streamAnalyticsRequest, streamAnalyticsParams);
+  }, [streamAnalytics]);
+
+  useEffect(() => {
+    if (isPending(streamAnalyticsResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, streamAnalyticsResp.data]));
+    }
+  }, [streamAnalyticsResp]);
+
+  if (isError(streamAnalyticsResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamAnalyticsResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamAnalyticsResp) && (
+        <>Completed ({events.length} events)</>
+      )}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamAnalytics\` when appropriate.
+"
+`;
+
+exports[`reactSseHookDocs > handles empty variables array 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamGlobalEvents } from "@intrig/react/events/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamGlobalEventsResp, streamGlobalEvents] = useStreamGlobalEvents({
+  clearOnUnmount: true,
+});
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamGlobalEvents } from "@intrig/react/events/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamGlobalEventsResp, streamGlobalEvents] = useStreamGlobalEvents({
+    clearOnUnmount: true,
+  });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamGlobalEvents({}); // start stream
+  }, [streamGlobalEvents]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamGlobalEventsResp)) {
+      setMessages((prev) => [...prev, streamGlobalEventsResp.data]);
+    }
+  }, [streamGlobalEventsResp]);
+
+  if (isError(streamGlobalEventsResp)) return <>An error occurred</>;
+  if (isPending(streamGlobalEventsResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamGlobalEventsResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamGlobalEvents(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: unknown;
+  body?: unknown;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<StreamGlobalEventsResponseBody /* or event payload type */, any>,
+  // Start streaming:
+  (req: { params?: unknown; body?: unknown }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamGlobalEventsResp.data\` **only while** \`isPending(streamGlobalEventsResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamGlobalEventsResp, streamGlobalEvents] = useStreamGlobalEvents({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  streamGlobalEvents({});
+}, [streamGlobalEvents]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamGlobalEventsResp))
+    setMessages((m) => [...m, streamGlobalEventsResp.data]);
+}, [streamGlobalEventsResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamGlobalEventsResp)
+  ? streamGlobalEventsResp.data
+  : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [streamGlobalEventsResp, streamGlobalEvents, clearStreamGlobalEvents] =
+  useStreamGlobalEvents();
+
+const start = () => streamGlobalEvents({});
+const stop = () => clearStreamGlobalEvents();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamGlobalEvents } from "@intrig/react/events/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamGlobalEventsResp, streamGlobalEvents] = useStreamGlobalEvents({
+    clearOnUnmount: true,
+  });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamGlobalEvents({});
+  }, [streamGlobalEvents]);
+
+  useEffect(() => {
+    if (isPending(streamGlobalEventsResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, streamGlobalEventsResp.data]));
+    }
+  }, [streamGlobalEventsResp]);
+
+  if (isError(streamGlobalEventsResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamGlobalEventsResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamGlobalEventsResp) && (
+        <>Completed ({events.length} events)</>
+      )}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamGlobalEvents\` when appropriate.
+"
+`;
+
+exports[`reactSseHookDocs > handles multiple path params 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamProjectNotifications } from "@intrig/react/projects/{projectId}/notifications/{notificationId}/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamProjectNotificationsResp, streamProjectNotifications] =
+  useStreamProjectNotifications({ clearOnUnmount: true });
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamProjectNotifications } from "@intrig/react/projects/{projectId}/notifications/{notificationId}/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamProjectNotificationsResp, streamProjectNotifications] =
+    useStreamProjectNotifications({ clearOnUnmount: true });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamProjectNotifications(streamProjectNotificationsParams); // start stream
+  }, [streamProjectNotifications]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamProjectNotificationsResp)) {
+      setMessages((prev) => [...prev, streamProjectNotificationsResp.data]);
+    }
+  }, [streamProjectNotificationsResp]);
+
+  if (isError(streamProjectNotificationsResp)) return <>An error occurred</>;
+  if (isPending(streamProjectNotificationsResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamProjectNotificationsResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { StreamProjectNotificationsParams } from "@intrig/react/projects/{projectId}/notifications/{notificationId}/StreamProjectNotifications.params";
+import type { StreamProjectNotificationsResponseBody } from "@intrig/react/projects/{projectId}/notifications/{notificationId}/StreamProjectNotifications.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamProjectNotifications(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: StreamProjectNotificationsParams;
+  body?: unknown;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<
+    StreamProjectNotificationsResponseBody /* or event payload type */,
+    any
+  >,
+  // Start streaming:
+  (req: { params?: StreamProjectNotificationsParams; body?: unknown }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamProjectNotificationsResp.data\` **only while** \`isPending(streamProjectNotificationsResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamProjectNotificationsResp, streamProjectNotifications] =
+  useStreamProjectNotifications({ clearOnUnmount: true });
+
+useEffect(() => {
+  streamProjectNotifications(streamProjectNotificationsParams);
+}, [streamProjectNotifications]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamProjectNotificationsResp))
+    setMessages((m) => [...m, streamProjectNotificationsResp.data]);
+}, [streamProjectNotificationsResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamProjectNotificationsResp)
+  ? streamProjectNotificationsResp.data
+  : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [
+  streamProjectNotificationsResp,
+  streamProjectNotifications,
+  clearStreamProjectNotifications,
+] = useStreamProjectNotifications();
+
+const start = () =>
+  streamProjectNotifications(streamProjectNotificationsParams);
+const stop = () => clearStreamProjectNotifications();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamProjectNotifications } from "@intrig/react/projects/{projectId}/notifications/{notificationId}/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamProjectNotificationsResp, streamProjectNotifications] =
+    useStreamProjectNotifications({ clearOnUnmount: true });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamProjectNotifications(streamProjectNotificationsParams);
+  }, [streamProjectNotifications]);
+
+  useEffect(() => {
+    if (isPending(streamProjectNotificationsResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() =>
+        setEvents((xs) => [...xs, streamProjectNotificationsResp.data]),
+      );
+    }
+  }, [streamProjectNotificationsResp]);
+
+  if (isError(streamProjectNotificationsResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamProjectNotificationsResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamProjectNotificationsResp) && (
+        <>Completed ({events.length} events)</>
+      )}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamProjectNotifications\` when appropriate.
+"
+`;
+
+exports[`reactSseHookDocs > handles query params mixed with path params 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamSystemMetrics } from "@intrig/react/systems/{systemId}/metrics/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamSystemMetricsResp, streamSystemMetrics] = useStreamSystemMetrics({
+  clearOnUnmount: true,
+});
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamSystemMetrics } from "@intrig/react/systems/{systemId}/metrics/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamSystemMetricsResp, streamSystemMetrics] = useStreamSystemMetrics(
+    { clearOnUnmount: true },
+  );
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamSystemMetrics(streamSystemMetricsParams); // start stream
+  }, [streamSystemMetrics]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamSystemMetricsResp)) {
+      setMessages((prev) => [...prev, streamSystemMetricsResp.data]);
+    }
+  }, [streamSystemMetricsResp]);
+
+  if (isError(streamSystemMetricsResp)) return <>An error occurred</>;
+  if (isPending(streamSystemMetricsResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamSystemMetricsResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { StreamSystemMetricsParams } from "@intrig/react/systems/{systemId}/metrics/StreamSystemMetrics.params";
+import type { StreamSystemMetricsResponseBody } from "@intrig/react/systems/{systemId}/metrics/StreamSystemMetrics.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamSystemMetrics(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: StreamSystemMetricsParams;
+  body?: unknown;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<
+    StreamSystemMetricsResponseBody /* or event payload type */,
+    any
+  >,
+  // Start streaming:
+  (req: { params?: StreamSystemMetricsParams; body?: unknown }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamSystemMetricsResp.data\` **only while** \`isPending(streamSystemMetricsResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamSystemMetricsResp, streamSystemMetrics] = useStreamSystemMetrics({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  streamSystemMetrics(streamSystemMetricsParams);
+}, [streamSystemMetrics]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamSystemMetricsResp))
+    setMessages((m) => [...m, streamSystemMetricsResp.data]);
+}, [streamSystemMetricsResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamSystemMetricsResp)
+  ? streamSystemMetricsResp.data
+  : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [streamSystemMetricsResp, streamSystemMetrics, clearStreamSystemMetrics] =
+  useStreamSystemMetrics();
+
+const start = () => streamSystemMetrics(streamSystemMetricsParams);
+const stop = () => clearStreamSystemMetrics();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamSystemMetrics } from "@intrig/react/systems/{systemId}/metrics/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamSystemMetricsResp, streamSystemMetrics] = useStreamSystemMetrics(
+    { clearOnUnmount: true },
+  );
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamSystemMetrics(streamSystemMetricsParams);
+  }, [streamSystemMetrics]);
+
+  useEffect(() => {
+    if (isPending(streamSystemMetricsResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, streamSystemMetricsResp.data]));
+    }
+  }, [streamSystemMetricsResp]);
+
+  if (isError(streamSystemMetricsResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamSystemMetricsResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamSystemMetricsResp) && (
+        <>Completed ({events.length} events)</>
+      )}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamSystemMetrics\` when appropriate.
+"
+`;
+
+exports[`reactSseHookDocs > snapshot — path params only (no request body) 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamUserActivity } from "@intrig/react/users/{userId}/activity/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamUserActivityResp, streamUserActivity] = useStreamUserActivity({
+  clearOnUnmount: true,
+});
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamUserActivity } from "@intrig/react/users/{userId}/activity/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamUserActivityResp, streamUserActivity] = useStreamUserActivity({
+    clearOnUnmount: true,
+  });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamUserActivity(streamUserActivityParams); // start stream
+  }, [streamUserActivity]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamUserActivityResp)) {
+      setMessages((prev) => [...prev, streamUserActivityResp.data]);
+    }
+  }, [streamUserActivityResp]);
+
+  if (isError(streamUserActivityResp)) return <>An error occurred</>;
+  if (isPending(streamUserActivityResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamUserActivityResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { StreamUserActivityParams } from "@intrig/react/users/{userId}/activity/StreamUserActivity.params";
+import type { StreamUserActivityResponseBody } from "@intrig/react/users/{userId}/activity/StreamUserActivity.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamUserActivity(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: StreamUserActivityParams;
+  body?: unknown;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<StreamUserActivityResponseBody /* or event payload type */, any>,
+  // Start streaming:
+  (req: { params?: StreamUserActivityParams; body?: unknown }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamUserActivityResp.data\` **only while** \`isPending(streamUserActivityResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamUserActivityResp, streamUserActivity] = useStreamUserActivity({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  streamUserActivity(streamUserActivityParams);
+}, [streamUserActivity]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamUserActivityResp))
+    setMessages((m) => [...m, streamUserActivityResp.data]);
+}, [streamUserActivityResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamUserActivityResp)
+  ? streamUserActivityResp.data
+  : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [streamUserActivityResp, streamUserActivity, clearStreamUserActivity] =
+  useStreamUserActivity();
+
+const start = () => streamUserActivity(streamUserActivityParams);
+const stop = () => clearStreamUserActivity();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamUserActivity } from "@intrig/react/users/{userId}/activity/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamUserActivityResp, streamUserActivity] = useStreamUserActivity({
+    clearOnUnmount: true,
+  });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamUserActivity(streamUserActivityParams);
+  }, [streamUserActivity]);
+
+  useEffect(() => {
+    if (isPending(streamUserActivityResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, streamUserActivityResp.data]));
+    }
+  }, [streamUserActivityResp]);
+
+  if (isError(streamUserActivityResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamUserActivityResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamUserActivityResp) && (
+        <>Completed ({events.length} events)</>
+      )}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamUserActivity\` when appropriate.
+"
+`;
+
+exports[`reactSseHookDocs > snapshot — request body and path params 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamTaskProgress } from "@intrig/react/tasks/{taskId}/progress/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamTaskProgressResp, streamTaskProgress] = useStreamTaskProgress({
+  clearOnUnmount: true,
+});
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamTaskProgress } from "@intrig/react/tasks/{taskId}/progress/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamTaskProgressResp, streamTaskProgress] = useStreamTaskProgress({
+    clearOnUnmount: true,
+  });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamTaskProgress(streamTaskProgressRequest, streamTaskProgressParams); // start stream
+  }, [streamTaskProgress]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamTaskProgressResp)) {
+      setMessages((prev) => [...prev, streamTaskProgressResp.data]);
+    }
+  }, [streamTaskProgressResp]);
+
+  if (isError(streamTaskProgressResp)) return <>An error occurred</>;
+  if (isPending(streamTaskProgressResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamTaskProgressResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { StreamTaskProgressRequest } from "@intrig/react/demo_api/components/schemas/StreamTaskProgressRequest";
+import type { StreamTaskProgressParams } from "@intrig/react/tasks/{taskId}/progress/StreamTaskProgress.params";
+import type { StreamTaskProgressResponseBody } from "@intrig/react/tasks/{taskId}/progress/StreamTaskProgress.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamTaskProgress(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: StreamTaskProgressParams;
+  body?: StreamTaskProgressRequest;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<StreamTaskProgressResponseBody /* or event payload type */, any>,
+  // Start streaming:
+  (req: {
+    params?: StreamTaskProgressParams;
+    body?: StreamTaskProgressRequest;
+  }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamTaskProgressResp.data\` **only while** \`isPending(streamTaskProgressResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamTaskProgressResp, streamTaskProgress] = useStreamTaskProgress({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  streamTaskProgress(streamTaskProgressRequest, streamTaskProgressParams);
+}, [streamTaskProgress]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamTaskProgressResp))
+    setMessages((m) => [...m, streamTaskProgressResp.data]);
+}, [streamTaskProgressResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamTaskProgressResp)
+  ? streamTaskProgressResp.data
+  : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [streamTaskProgressResp, streamTaskProgress, clearStreamTaskProgress] =
+  useStreamTaskProgress();
+
+const start = () =>
+  streamTaskProgress(streamTaskProgressRequest, streamTaskProgressParams);
+const stop = () => clearStreamTaskProgress();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamTaskProgress } from "@intrig/react/tasks/{taskId}/progress/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamTaskProgressResp, streamTaskProgress] = useStreamTaskProgress({
+    clearOnUnmount: true,
+  });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamTaskProgress(streamTaskProgressRequest, streamTaskProgressParams);
+  }, [streamTaskProgress]);
+
+  useEffect(() => {
+    if (isPending(streamTaskProgressResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, streamTaskProgressResp.data]));
+    }
+  }, [streamTaskProgressResp]);
+
+  if (isError(streamTaskProgressResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamTaskProgressResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamTaskProgressResp) && (
+        <>Completed ({events.length} events)</>
+      )}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamTaskProgress\` when appropriate.
+"
+`;
+
+exports[`reactSseHookDocs > snapshot — request body only (no path params) 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamCustomEvents } from "@intrig/react/events/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamCustomEventsResp, streamCustomEvents] = useStreamCustomEvents({
+  clearOnUnmount: true,
+});
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamCustomEvents } from "@intrig/react/events/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamCustomEventsResp, streamCustomEvents] = useStreamCustomEvents({
+    clearOnUnmount: true,
+  });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamCustomEvents(streamCustomEventsRequest, {}); // start stream
+  }, [streamCustomEvents]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamCustomEventsResp)) {
+      setMessages((prev) => [...prev, streamCustomEventsResp.data]);
+    }
+  }, [streamCustomEventsResp]);
+
+  if (isError(streamCustomEventsResp)) return <>An error occurred</>;
+  if (isPending(streamCustomEventsResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamCustomEventsResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { StreamCustomEventsRequest } from "@intrig/react/demo_api/components/schemas/StreamCustomEventsRequest";
+import type { StreamCustomEventsResponseBody } from "@intrig/react/events/StreamCustomEvents.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamCustomEvents(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: unknown;
+  body?: StreamCustomEventsRequest;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<StreamCustomEventsResponseBody /* or event payload type */, any>,
+  // Start streaming:
+  (req: { params?: unknown; body?: StreamCustomEventsRequest }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamCustomEventsResp.data\` **only while** \`isPending(streamCustomEventsResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamCustomEventsResp, streamCustomEvents] = useStreamCustomEvents({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  streamCustomEvents(streamCustomEventsRequest, {});
+}, [streamCustomEvents]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamCustomEventsResp))
+    setMessages((m) => [...m, streamCustomEventsResp.data]);
+}, [streamCustomEventsResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamCustomEventsResp)
+  ? streamCustomEventsResp.data
+  : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [streamCustomEventsResp, streamCustomEvents, clearStreamCustomEvents] =
+  useStreamCustomEvents();
+
+const start = () => streamCustomEvents(streamCustomEventsRequest, {});
+const stop = () => clearStreamCustomEvents();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamCustomEvents } from "@intrig/react/events/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamCustomEventsResp, streamCustomEvents] = useStreamCustomEvents({
+    clearOnUnmount: true,
+  });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamCustomEvents(streamCustomEventsRequest, {});
+  }, [streamCustomEvents]);
+
+  useEffect(() => {
+    if (isPending(streamCustomEventsResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, streamCustomEventsResp.data]));
+    }
+  }, [streamCustomEventsResp]);
+
+  if (isError(streamCustomEventsResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamCustomEventsResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamCustomEventsResp) && (
+        <>Completed ({events.length} events)</>
+      )}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamCustomEvents\` when appropriate.
+"
+`;
+
+exports[`reactSseHookDocs > snapshot — simple REST descriptor (no body, no path params) 1`] = `
+"# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useStreamLogs } from "@intrig/react/logs/client";
+\`\`\`
+
+### 2) Utility guards
+
+\`\`\`ts
+import { isPending, isSuccess, isError } from "@intrig/react";
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+
+\`\`\`ts
+const [streamLogsResp, streamLogs] = useStreamLogs({ clearOnUnmount: true });
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useStreamLogs } from "@intrig/react/logs/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+
+export default function Example() {
+  const [streamLogsResp, streamLogs] = useStreamLogs({ clearOnUnmount: true });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamLogs({}); // start stream
+  }, [streamLogs]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(streamLogsResp)) {
+      setMessages((prev) => [...prev, streamLogsResp.data]);
+    }
+  }, [streamLogsResp]);
+
+  if (isError(streamLogsResp)) return <>An error occurred</>;
+  if (isPending(streamLogsResp))
+    return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(streamLogsResp)) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function useStreamLogs(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean; // recommended for streams
+  key?: string; // isolate multiple subscriptions
+  params?: unknown;
+  body?: unknown;
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<StreamLogsResponseBody /* or event payload type */, any>,
+  // Start streaming:
+  (req: { params?: unknown; body?: unknown }) => void,
+  // Clear/close stream:
+  () => void,
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`streamLogsResp.data\` **only while** \`isPending(streamLogsResp)\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+
+\`\`\`tsx
+const [streamLogsResp, streamLogs] = useStreamLogs({ clearOnUnmount: true });
+
+useEffect(() => {
+  streamLogs({});
+}, [streamLogs]);
+\`\`\`
+
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(streamLogsResp))
+    setMessages((m) => [...m, streamLogsResp.data]);
+}, [streamLogsResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+
+\`\`\`tsx
+const latest = isPending(streamLogsResp) ? streamLogsResp.data : undefined;
+\`\`\`
+
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+
+\`\`\`tsx
+const [streamLogsResp, streamLogs, clearStreamLogs] = useStreamLogs();
+
+const start = () => streamLogs({});
+const stop = () => clearStreamLogs();
+\`\`\`
+
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { useStreamLogs } from "@intrig/react/logs/client";
+import { isPending, isSuccess, isError } from "@intrig/react";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+
+function MyComponent() {
+  const [streamLogsResp, streamLogs] = useStreamLogs({ clearOnUnmount: true });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    streamLogs({});
+  }, [streamLogs]);
+
+  useEffect(() => {
+    if (isPending(streamLogsResp)) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, streamLogsResp.data]));
+    }
+  }, [streamLogsResp]);
+
+  if (isError(streamLogsResp)) return <>Stream error</>;
+  return (
+    <>
+      {isPending(streamLogsResp) && (
+        <pre>{JSON.stringify(events, null, 2)}</pre>
+      )}
+      {isSuccess(streamLogsResp) && <>Completed ({events.length} events)</>}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`clearStreamLogs\` when appropriate.
+"
+`;