@agenticgraph/stream-react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) shahzad <shahzadsarwar.work@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @agenticgraph/stream-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React hooks for [AgenticGraph](https://github.com/shahzad-io/agenticgraph) streaming: `useAgenticStream` and `useStreamSelector`, on top of [@agenticgraph/stream-client](https://www.npmjs.com/package/@agenticgraph/stream-client).
+
+**Pre-1.0:** minor versions may contain breaking changes. Read the [CHANGELOG](https://github.com/shahzad-io/agenticgraph-stream-client/blob/main/CHANGELOG.md) before you upgrade.
+
+```bash
+npm install @agenticgraph/stream-client @agenticgraph/stream-react
+```
+
+```tsx
+import { SSETransport } from '@agenticgraph/stream-client';
+import { useAgenticStream } from '@agenticgraph/stream-react';
+
+function Chat({ streamId }: { streamId: string }) {
+  const { text, status, error } = useAgenticStream({
+    transport: new SSETransport({ url: `/agentic-graph/streams/${streamId}` }),
+  });
+
+  return <p>{error ? `Error: ${error.kind}` : text} ({status})</p>;
+}
+```
+
+`text` holds every `text_delta` of the run (every step); `finalText` the current or last step, so after a tool run the final answer.
+
+Requires React 18+. Guide: [agenticgraph.dev/docs/stream-getting-started](https://agenticgraph.dev/docs/stream-getting-started); more in the [repository README](https://github.com/shahzad-io/agenticgraph-stream-client#readme).
+
+## Compatibility
+
+The three packages are released together:
+
+| Package | Version | Works with |
+|---|---|---|
+| `agenticgraph/agenticgraph` (core) | 0.2.x | PHP 8.3+, Laravel 12.61.1+ or 13.12+, Prism 0.102 |
+| `agenticgraph/vector` | 0.1.x | PHP 8.3+, Laravel 12.61.1+ or 13.12+, Prism 0.102, PostgreSQL with pgvector (0.8+ for iterative scan). Core 0.2.x is optional (tracing) |
+| `@agenticgraph/stream-client`, `@agenticgraph/stream-react`, `@agenticgraph/stream-vue` | 0.1.x | Core 0.2.x on the server (stream wire contract v1.1), Node.js 18+, React 18+ or Vue 3.4+ for the adapters |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,145 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  activeNodeSelector: () => import_stream_client2.activeNodeSelector,
+  nodeTextSelector: () => import_stream_client2.nodeTextSelector,
+  thinkingSelector: () => import_stream_client2.thinkingSelector,
+  toolCallSelector: () => import_stream_client2.toolCallSelector,
+  useAgenticStream: () => useAgenticStream,
+  useStreamSelector: () => useStreamSelector
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useAgenticStream.ts
+var import_stream_client = require("@agenticgraph/stream-client");
+var import_react = require("react");
+function useAgenticStream(options) {
+  const { transport, onResume } = options;
+  const [text, setText] = (0, import_react.useState)("");
+  const [finalText, setFinalText] = (0, import_react.useState)("");
+  const [status, setStatus] = (0, import_react.useState)("idle");
+  const [error, setError] = (0, import_react.useState)(null);
+  const [interrupt, setInterrupt] = (0, import_react.useState)(null);
+  const [lastEvent, setLastEvent] = (0, import_react.useState)(null);
+  const [client, setClient] = (0, import_react.useState)(null);
+  const onResumeRef = (0, import_react.useRef)(onResume);
+  onResumeRef.current = onResume;
+  (0, import_react.useEffect)(() => {
+    let stream = null;
+    let unsubEvents;
+    let unsubStatus;
+    let cancelled = false;
+    setText("");
+    setFinalText("");
+    setStatus("idle");
+    setError(null);
+    setInterrupt(null);
+    setLastEvent(null);
+    setClient(null);
+    void (async () => {
+      try {
+        stream = await import_stream_client.AgenticStream.connect({ transport });
+      } catch (failure) {
+        if (!cancelled) {
+          setStatus("error");
+          setError({ kind: "connection", message: failure instanceof Error ? failure.message : String(failure) });
+        }
+        return;
+      }
+      if (cancelled) {
+        await stream.disconnect();
+        return;
+      }
+      setClient(stream);
+      setStatus(stream.status);
+      setError(stream.error);
+      setInterrupt(stream.interrupt);
+      unsubEvents = stream.on((event) => {
+        setLastEvent(event);
+        setText((current) => (0, import_stream_client.appendTextDelta)(current, event));
+        setFinalText((current) => (0, import_stream_client.appendFinalTextDelta)(current, event));
+      });
+      unsubStatus = stream.onStatusChange((nextStatus, snapshot) => {
+        setStatus(nextStatus);
+        setError(snapshot.error);
+        setInterrupt(snapshot.interrupt);
+      });
+    })();
+    return () => {
+      cancelled = true;
+      unsubEvents?.();
+      unsubStatus?.();
+      void stream?.disconnect();
+    };
+  }, [transport]);
+  const resume = (0, import_react.useCallback)(
+    async (decision) => {
+      if (client === null) {
+        throw new Error("useAgenticStream: stream not connected");
+      }
+      await (0, import_stream_client.executeResume)(client, decision, onResumeRef.current);
+    },
+    [client]
+  );
+  return {
+    text,
+    finalText,
+    status,
+    error,
+    interrupt,
+    resume,
+    lastEvent,
+    client
+  };
+}
+
+// src/useStreamSelector.ts
+var import_react2 = require("react");
+function useStreamSelector(client, selector) {
+  const [events, setEvents] = (0, import_react2.useState)([]);
+  const selectorRef = (0, import_react2.useRef)(selector);
+  selectorRef.current = selector;
+  (0, import_react2.useEffect)(() => {
+    if (client === null) {
+      setEvents([]);
+      return;
+    }
+    const unsub = client.on((event) => {
+      setEvents((current) => [...current, event]);
+    });
+    return unsub;
+  }, [client]);
+  return (0, import_react2.useMemo)(() => selectorRef.current(events), [events]);
+}
+
+// src/index.ts
+var import_stream_client2 = require("@agenticgraph/stream-client");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  activeNodeSelector,
+  nodeTextSelector,
+  thinkingSelector,
+  toolCallSelector,
+  useAgenticStream,
+  useStreamSelector
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useAgenticStream.ts","../src/useStreamSelector.ts"],"sourcesContent":["export { useAgenticStream } from './useAgenticStream.js';\nexport type { UseAgenticStreamOptions, UseAgenticStreamReturn } from './useAgenticStream.js';\nexport { useStreamSelector } from './useStreamSelector.js';\nexport {\n  activeNodeSelector,\n  nodeTextSelector,\n  thinkingSelector,\n  toolCallSelector,\n} from '@agenticgraph/stream-client';\nexport type { StreamSelector } from '@agenticgraph/stream-client';\n","import {\n  AgenticStream,\n  executeResume,\n  appendFinalTextDelta,\n  appendTextDelta,\n  type ResumeHandler,\n  type StreamErrorDetail,\n  type StreamEvent,\n  type StreamInterrupt,\n  type StreamStatus,\n  type StreamTransport,\n} from '@agenticgraph/stream-client';\nimport { useCallback, useEffect, useRef, useState } from 'react';\n\nexport interface UseAgenticStreamOptions {\n  transport: StreamTransport;\n  onResume?: ResumeHandler;\n}\n\nexport interface UseAgenticStreamReturn {\n  /** Every text_delta of the run, every step (the narration). */\n  text: string;\n  /** Text of the current or last step; after a tool run, the final answer (LlmResponse::text on the server). */\n  finalText: string;\n  status: StreamStatus;\n  error: StreamErrorDetail | null;\n  interrupt: StreamInterrupt | null;\n  resume: (decision: unknown) => Promise<void>;\n  lastEvent: StreamEvent | null;\n  client: AgenticStream | null;\n}\n\n/**\n * React hook bridging {@link AgenticStream} into reactive state.\n *\n * Text accumulation uses functional `setText` updates (one state slot, O(1) per delta).\n * Status/error/interrupt sync from the core via `onStatusChange` - not reimplemented here.\n * `lastEvent` updates on every event (intentional; use selectors for derived state).\n */\nexport function useAgenticStream(options: UseAgenticStreamOptions): UseAgenticStreamReturn {\n  const { transport, onResume } = options;\n\n  const [text, setText] = useState('');\n  const [finalText, setFinalText] = useState('');\n  const [status, setStatus] = useState<StreamStatus>('idle');\n  const [error, setError] = useState<StreamErrorDetail | null>(null);\n  const [interrupt, setInterrupt] = useState<StreamInterrupt | null>(null);\n  const [lastEvent, setLastEvent] = useState<StreamEvent | null>(null);\n  const [client, setClient] = useState<AgenticStream | null>(null);\n\n  const onResumeRef = useRef(onResume);\n  onResumeRef.current = onResume;\n\n  useEffect(() => {\n    let stream: AgenticStream | null = null;\n    let unsubEvents: (() => void) | undefined;\n    let unsubStatus: (() => void) | undefined;\n    let cancelled = false;\n\n    setText('');\n    setFinalText('');\n    setStatus('idle');\n    setError(null);\n    setInterrupt(null);\n    setLastEvent(null);\n    setClient(null);\n\n    void (async () => {\n      try {\n        stream = await AgenticStream.connect({ transport });\n      } catch (failure) {\n        if (!cancelled) {\n          setStatus('error');\n          setError({ kind: 'connection', message: failure instanceof Error ? failure.message : String(failure) });\n        }\n\n        return;\n      }\n\n      if (cancelled) {\n        await stream.disconnect();\n\n        return;\n      }\n\n      setClient(stream);\n      setStatus(stream.status);\n      setError(stream.error);\n      setInterrupt(stream.interrupt);\n\n      unsubEvents = stream.on((event) => {\n        setLastEvent(event);\n        setText((current) => appendTextDelta(current, event));\n        setFinalText((current) => appendFinalTextDelta(current, event));\n      });\n\n      unsubStatus = stream.onStatusChange((nextStatus, snapshot) => {\n        setStatus(nextStatus);\n        setError(snapshot.error);\n        setInterrupt(snapshot.interrupt);\n      });\n    })();\n\n    return () => {\n      cancelled = true;\n      unsubEvents?.();\n      unsubStatus?.();\n      void stream?.disconnect();\n    };\n  }, [transport]);\n\n  const resume = useCallback(\n    async (decision: unknown) => {\n      if (client === null) {\n        throw new Error('useAgenticStream: stream not connected');\n      }\n\n      await executeResume(client, decision, onResumeRef.current);\n    },\n    [client],\n  );\n\n  return {\n    text,\n    finalText,\n    status,\n    error,\n    interrupt,\n    resume,\n    lastEvent,\n    client,\n  };\n}\n","import type { AgenticStream, StreamEvent, StreamSelector } from '@agenticgraph/stream-client';\nimport { useEffect, useMemo, useRef, useState } from 'react';\n\n/**\n * Derive reactive state from the stream's event history via a selector function.\n * Selector functions should be stable (imported, not inline) to avoid redundant recomputation.\n */\nexport function useStreamSelector<T>(\n  client: AgenticStream | null,\n  selector: StreamSelector<T>,\n): T {\n  const [events, setEvents] = useState<StreamEvent[]>([]);\n  const selectorRef = useRef(selector);\n  selectorRef.current = selector;\n\n  useEffect(() => {\n    if (client === null) {\n      setEvents([]);\n\n      return;\n    }\n\n    const unsub = client.on((event) => {\n      setEvents((current) => [...current, event]);\n    });\n\n    return unsub;\n  }, [client]);\n\n  return useMemo(() => selectorRef.current(events), [events]);\n}\n"],"mappings":"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","names":["import_react","import_stream_client"]}

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import { StreamTransport, ResumeHandler, StreamStatus, StreamErrorDetail, StreamInterrupt, StreamEvent, AgenticStream, StreamSelector } from '@agenticgraph/stream-client';
+export { StreamSelector, activeNodeSelector, nodeTextSelector, thinkingSelector, toolCallSelector } from '@agenticgraph/stream-client';
+
+interface UseAgenticStreamOptions {
+    transport: StreamTransport;
+    onResume?: ResumeHandler;
+}
+interface UseAgenticStreamReturn {
+    /** Every text_delta of the run, every step (the narration). */
+    text: string;
+    /** Text of the current or last step; after a tool run, the final answer (LlmResponse::text on the server). */
+    finalText: string;
+    status: StreamStatus;
+    error: StreamErrorDetail | null;
+    interrupt: StreamInterrupt | null;
+    resume: (decision: unknown) => Promise<void>;
+    lastEvent: StreamEvent | null;
+    client: AgenticStream | null;
+}
+/**
+ * React hook bridging {@link AgenticStream} into reactive state.
+ *
+ * Text accumulation uses functional `setText` updates (one state slot, O(1) per delta).
+ * Status/error/interrupt sync from the core via `onStatusChange` - not reimplemented here.
+ * `lastEvent` updates on every event (intentional; use selectors for derived state).
+ */
+declare function useAgenticStream(options: UseAgenticStreamOptions): UseAgenticStreamReturn;
+
+/**
+ * Derive reactive state from the stream's event history via a selector function.
+ * Selector functions should be stable (imported, not inline) to avoid redundant recomputation.
+ */
+declare function useStreamSelector<T>(client: AgenticStream | null, selector: StreamSelector<T>): T;
+
+export { type UseAgenticStreamOptions, type UseAgenticStreamReturn, useAgenticStream, useStreamSelector };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { StreamTransport, ResumeHandler, StreamStatus, StreamErrorDetail, StreamInterrupt, StreamEvent, AgenticStream, StreamSelector } from '@agenticgraph/stream-client';
+export { StreamSelector, activeNodeSelector, nodeTextSelector, thinkingSelector, toolCallSelector } from '@agenticgraph/stream-client';
+
+interface UseAgenticStreamOptions {
+    transport: StreamTransport;
+    onResume?: ResumeHandler;
+}
+interface UseAgenticStreamReturn {
+    /** Every text_delta of the run, every step (the narration). */
+    text: string;
+    /** Text of the current or last step; after a tool run, the final answer (LlmResponse::text on the server). */
+    finalText: string;
+    status: StreamStatus;
+    error: StreamErrorDetail | null;
+    interrupt: StreamInterrupt | null;
+    resume: (decision: unknown) => Promise<void>;
+    lastEvent: StreamEvent | null;
+    client: AgenticStream | null;
+}
+/**
+ * React hook bridging {@link AgenticStream} into reactive state.
+ *
+ * Text accumulation uses functional `setText` updates (one state slot, O(1) per delta).
+ * Status/error/interrupt sync from the core via `onStatusChange` - not reimplemented here.
+ * `lastEvent` updates on every event (intentional; use selectors for derived state).
+ */
+declare function useAgenticStream(options: UseAgenticStreamOptions): UseAgenticStreamReturn;
+
+/**
+ * Derive reactive state from the stream's event history via a selector function.
+ * Selector functions should be stable (imported, not inline) to avoid redundant recomputation.
+ */
+declare function useStreamSelector<T>(client: AgenticStream | null, selector: StreamSelector<T>): T;
+
+export { type UseAgenticStreamOptions, type UseAgenticStreamReturn, useAgenticStream, useStreamSelector };

package/dist/index.js

@@ -0,0 +1,123 @@
+// src/useAgenticStream.ts
+import {
+  AgenticStream,
+  executeResume,
+  appendFinalTextDelta,
+  appendTextDelta
+} from "@agenticgraph/stream-client";
+import { useCallback, useEffect, useRef, useState } from "react";
+function useAgenticStream(options) {
+  const { transport, onResume } = options;
+  const [text, setText] = useState("");
+  const [finalText, setFinalText] = useState("");
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const [interrupt, setInterrupt] = useState(null);
+  const [lastEvent, setLastEvent] = useState(null);
+  const [client, setClient] = useState(null);
+  const onResumeRef = useRef(onResume);
+  onResumeRef.current = onResume;
+  useEffect(() => {
+    let stream = null;
+    let unsubEvents;
+    let unsubStatus;
+    let cancelled = false;
+    setText("");
+    setFinalText("");
+    setStatus("idle");
+    setError(null);
+    setInterrupt(null);
+    setLastEvent(null);
+    setClient(null);
+    void (async () => {
+      try {
+        stream = await AgenticStream.connect({ transport });
+      } catch (failure) {
+        if (!cancelled) {
+          setStatus("error");
+          setError({ kind: "connection", message: failure instanceof Error ? failure.message : String(failure) });
+        }
+        return;
+      }
+      if (cancelled) {
+        await stream.disconnect();
+        return;
+      }
+      setClient(stream);
+      setStatus(stream.status);
+      setError(stream.error);
+      setInterrupt(stream.interrupt);
+      unsubEvents = stream.on((event) => {
+        setLastEvent(event);
+        setText((current) => appendTextDelta(current, event));
+        setFinalText((current) => appendFinalTextDelta(current, event));
+      });
+      unsubStatus = stream.onStatusChange((nextStatus, snapshot) => {
+        setStatus(nextStatus);
+        setError(snapshot.error);
+        setInterrupt(snapshot.interrupt);
+      });
+    })();
+    return () => {
+      cancelled = true;
+      unsubEvents?.();
+      unsubStatus?.();
+      void stream?.disconnect();
+    };
+  }, [transport]);
+  const resume = useCallback(
+    async (decision) => {
+      if (client === null) {
+        throw new Error("useAgenticStream: stream not connected");
+      }
+      await executeResume(client, decision, onResumeRef.current);
+    },
+    [client]
+  );
+  return {
+    text,
+    finalText,
+    status,
+    error,
+    interrupt,
+    resume,
+    lastEvent,
+    client
+  };
+}
+
+// src/useStreamSelector.ts
+import { useEffect as useEffect2, useMemo, useRef as useRef2, useState as useState2 } from "react";
+function useStreamSelector(client, selector) {
+  const [events, setEvents] = useState2([]);
+  const selectorRef = useRef2(selector);
+  selectorRef.current = selector;
+  useEffect2(() => {
+    if (client === null) {
+      setEvents([]);
+      return;
+    }
+    const unsub = client.on((event) => {
+      setEvents((current) => [...current, event]);
+    });
+    return unsub;
+  }, [client]);
+  return useMemo(() => selectorRef.current(events), [events]);
+}
+
+// src/index.ts
+import {
+  activeNodeSelector,
+  nodeTextSelector,
+  thinkingSelector,
+  toolCallSelector
+} from "@agenticgraph/stream-client";
+export {
+  activeNodeSelector,
+  nodeTextSelector,
+  thinkingSelector,
+  toolCallSelector,
+  useAgenticStream,
+  useStreamSelector
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useAgenticStream.ts","../src/useStreamSelector.ts","../src/index.ts"],"sourcesContent":["import {\n  AgenticStream,\n  executeResume,\n  appendFinalTextDelta,\n  appendTextDelta,\n  type ResumeHandler,\n  type StreamErrorDetail,\n  type StreamEvent,\n  type StreamInterrupt,\n  type StreamStatus,\n  type StreamTransport,\n} from '@agenticgraph/stream-client';\nimport { useCallback, useEffect, useRef, useState } from 'react';\n\nexport interface UseAgenticStreamOptions {\n  transport: StreamTransport;\n  onResume?: ResumeHandler;\n}\n\nexport interface UseAgenticStreamReturn {\n  /** Every text_delta of the run, every step (the narration). */\n  text: string;\n  /** Text of the current or last step; after a tool run, the final answer (LlmResponse::text on the server). */\n  finalText: string;\n  status: StreamStatus;\n  error: StreamErrorDetail | null;\n  interrupt: StreamInterrupt | null;\n  resume: (decision: unknown) => Promise<void>;\n  lastEvent: StreamEvent | null;\n  client: AgenticStream | null;\n}\n\n/**\n * React hook bridging {@link AgenticStream} into reactive state.\n *\n * Text accumulation uses functional `setText` updates (one state slot, O(1) per delta).\n * Status/error/interrupt sync from the core via `onStatusChange` - not reimplemented here.\n * `lastEvent` updates on every event (intentional; use selectors for derived state).\n */\nexport function useAgenticStream(options: UseAgenticStreamOptions): UseAgenticStreamReturn {\n  const { transport, onResume } = options;\n\n  const [text, setText] = useState('');\n  const [finalText, setFinalText] = useState('');\n  const [status, setStatus] = useState<StreamStatus>('idle');\n  const [error, setError] = useState<StreamErrorDetail | null>(null);\n  const [interrupt, setInterrupt] = useState<StreamInterrupt | null>(null);\n  const [lastEvent, setLastEvent] = useState<StreamEvent | null>(null);\n  const [client, setClient] = useState<AgenticStream | null>(null);\n\n  const onResumeRef = useRef(onResume);\n  onResumeRef.current = onResume;\n\n  useEffect(() => {\n    let stream: AgenticStream | null = null;\n    let unsubEvents: (() => void) | undefined;\n    let unsubStatus: (() => void) | undefined;\n    let cancelled = false;\n\n    setText('');\n    setFinalText('');\n    setStatus('idle');\n    setError(null);\n    setInterrupt(null);\n    setLastEvent(null);\n    setClient(null);\n\n    void (async () => {\n      try {\n        stream = await AgenticStream.connect({ transport });\n      } catch (failure) {\n        if (!cancelled) {\n          setStatus('error');\n          setError({ kind: 'connection', message: failure instanceof Error ? failure.message : String(failure) });\n        }\n\n        return;\n      }\n\n      if (cancelled) {\n        await stream.disconnect();\n\n        return;\n      }\n\n      setClient(stream);\n      setStatus(stream.status);\n      setError(stream.error);\n      setInterrupt(stream.interrupt);\n\n      unsubEvents = stream.on((event) => {\n        setLastEvent(event);\n        setText((current) => appendTextDelta(current, event));\n        setFinalText((current) => appendFinalTextDelta(current, event));\n      });\n\n      unsubStatus = stream.onStatusChange((nextStatus, snapshot) => {\n        setStatus(nextStatus);\n        setError(snapshot.error);\n        setInterrupt(snapshot.interrupt);\n      });\n    })();\n\n    return () => {\n      cancelled = true;\n      unsubEvents?.();\n      unsubStatus?.();\n      void stream?.disconnect();\n    };\n  }, [transport]);\n\n  const resume = useCallback(\n    async (decision: unknown) => {\n      if (client === null) {\n        throw new Error('useAgenticStream: stream not connected');\n      }\n\n      await executeResume(client, decision, onResumeRef.current);\n    },\n    [client],\n  );\n\n  return {\n    text,\n    finalText,\n    status,\n    error,\n    interrupt,\n    resume,\n    lastEvent,\n    client,\n  };\n}\n","import type { AgenticStream, StreamEvent, StreamSelector } from '@agenticgraph/stream-client';\nimport { useEffect, useMemo, useRef, useState } from 'react';\n\n/**\n * Derive reactive state from the stream's event history via a selector function.\n * Selector functions should be stable (imported, not inline) to avoid redundant recomputation.\n */\nexport function useStreamSelector<T>(\n  client: AgenticStream | null,\n  selector: StreamSelector<T>,\n): T {\n  const [events, setEvents] = useState<StreamEvent[]>([]);\n  const selectorRef = useRef(selector);\n  selectorRef.current = selector;\n\n  useEffect(() => {\n    if (client === null) {\n      setEvents([]);\n\n      return;\n    }\n\n    const unsub = client.on((event) => {\n      setEvents((current) => [...current, event]);\n    });\n\n    return unsub;\n  }, [client]);\n\n  return useMemo(() => selectorRef.current(events), [events]);\n}\n","export { useAgenticStream } from './useAgenticStream.js';\nexport type { UseAgenticStreamOptions, UseAgenticStreamReturn } from './useAgenticStream.js';\nexport { useStreamSelector } from './useStreamSelector.js';\nexport {\n  activeNodeSelector,\n  nodeTextSelector,\n  thinkingSelector,\n  toolCallSelector,\n} from '@agenticgraph/stream-client';\nexport type { StreamSelector } from '@agenticgraph/stream-client';\n"],"mappings":"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","names":["useEffect","useRef","useState"]}

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@agenticgraph/stream-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "React hooks and selectors for AgenticGraph streaming",
+  "keywords": [
+    "agenticgraph",
+    "laravel",
+    "streaming",
+    "sse",
+    "react",
+    "hooks",
+    "ai",
+    "llm"
+  ],
+  "homepage": "https://agenticgraph.dev/docs/stream-getting-started",
+  "bugs": {
+    "url": "https://github.com/shahzad-io/agenticgraph-stream-client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shahzad-io/agenticgraph-stream-client.git",
+    "directory": "packages/stream-react"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@agenticgraph/stream-client": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.8",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^5.0.5"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}