@pylonsync/react 0.3.369 → 0.3.371

package/dist/index.d.ts

@@ -14,8 +14,9 @@ export type { PylonRouter } from "./useRouter";
 import { type Storage as PylonStorage } from "@pylonsync/sync";
 export { useQuery, useQueryOne, useReactiveQuery, useMutation, useInfiniteQuery, usePaginatedQuery, useEntityMutation, useAction, useQueryRaw, useQueryOneRaw, useLiveList, useLiveRow, useInsert, useUpdate, useDelete, useFn, useAggregate, useSearch, } from "./hooks";
 export type { QueryOptions, QueryFilter, IncludeSpec, UseQueryReturn, UseQueryOneReturn, UseReactiveQueryReturn, UseMutationReturn, UseInfiniteQueryReturn, UsePaginatedQueryReturn, PaginatedQueryStatus, UseFnReturn, AggregateSpec, UseAggregateReturn, SearchSpec, UseSearchReturn, } from "./hooks";
-export { useRoom } from "./useRoom";
+export { useRoom, useRoomMessages } from "./useRoom";
 export type { RoomPeer, RoomSnapshot, UseRoomOptions, UseRoomReturn, } from "./useRoom";
+export type { RoomMessage } from "@pylonsync/sync";
 export { useShard, connectShard } from "./useShard";
 export type { UseShardOptions, UseShardReturn, ShardClient, } from "./useShard";
 export { useSession } from "./useSession";

package/dist/useRoom.d.ts

@@ -1,4 +1,4 @@
-import { type SyncEngine } from '@pylonsync/sync';
+import { type RoomMessage, type SyncEngine } from '@pylonsync/sync';
 export interface RoomPeer {
     user_id: string;
     data: any;
@@ -90,4 +90,30 @@ export declare const __roomRegistryInternals: {
     isPolling(room: SharedRoom): boolean;
 };
 export declare function useRoom(roomId: string, userId: string, options?: UseRoomOptions): UseRoomReturn;
+/**
+ * Subscribe to broadcasts on a room — both from other members
+ * (`useRoom(...).broadcast`) and from the server
+ * (`ctx.rooms.broadcast` in a mutation or action).
+ *
+ * `useRoom` is send-only; this is the receive half. Streaming agent
+ * output is the motivating case: the handler broadcasts each delta,
+ * and every device watching the room renders it, including tabs that
+ * weren't the one that started the run.
+ *
+ * ```tsx
+ * const [text, setText] = useState("");
+ * useRoomMessages(`chat-${chatId}`, (msg) => {
+ *   if (msg.topic === "agent.delta") {
+ *     setText((t) => t + (msg.payload as { text: string }).text);
+ *   }
+ * });
+ * ```
+ *
+ * `from` is the sending user's id, or `""` for a server broadcast.
+ *
+ * The callback is held in a ref, so an inline arrow function doesn't
+ * resubscribe on every render — only a changed `roomId` does. Requires
+ * `init()`; without an engine (SSR, tests) this is a no-op.
+ */
+export declare function useRoomMessages(roomId: string, onMessage: (message: RoomMessage) => void): void;
 export {};

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.369",
+  "version": "0.3.371",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,8 +14,8 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.369",
-    "@pylonsync/sync": "0.3.369"
+    "@pylonsync/sdk": "0.3.371",
+    "@pylonsync/sync": "0.3.371"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/index.ts

@@ -105,13 +105,14 @@ export type {
 } from "./hooks";
 
 // Room hook
-export { useRoom } from "./useRoom";
+export { useRoom, useRoomMessages } from "./useRoom";
 export type {
   RoomPeer,
   RoomSnapshot,
   UseRoomOptions,
   UseRoomReturn,
 } from "./useRoom";
+export type { RoomMessage } from "@pylonsync/sync";
 
 // Shard hook for real-time sims (games, MMO, live docs, etc.)
 export { useShard, connectShard } from "./useShard";

package/src/useRoom.ts

@@ -1,7 +1,12 @@
 "use client";
 
 import { useState, useEffect, useCallback, useRef } from 'react';
-import { pylonFetch, type RoomMember, type SyncEngine } from '@pylonsync/sync';
+import {
+  pylonFetch,
+  type RoomMember,
+  type RoomMessage,
+  type SyncEngine,
+} from '@pylonsync/sync';
 import { getBaseUrl, getReactStorage, storageKey } from './index';
 import { getSync } from './db';
 
@@ -679,3 +684,45 @@ export function useRoom(
 
   return { peers, isConnected, setPresence, broadcast, leave, error };
 }
+
+/**
+ * Subscribe to broadcasts on a room — both from other members
+ * (`useRoom(...).broadcast`) and from the server
+ * (`ctx.rooms.broadcast` in a mutation or action).
+ *
+ * `useRoom` is send-only; this is the receive half. Streaming agent
+ * output is the motivating case: the handler broadcasts each delta,
+ * and every device watching the room renders it, including tabs that
+ * weren't the one that started the run.
+ *
+ * ```tsx
+ * const [text, setText] = useState("");
+ * useRoomMessages(`chat-${chatId}`, (msg) => {
+ *   if (msg.topic === "agent.delta") {
+ *     setText((t) => t + (msg.payload as { text: string }).text);
+ *   }
+ * });
+ * ```
+ *
+ * `from` is the sending user's id, or `""` for a server broadcast.
+ *
+ * The callback is held in a ref, so an inline arrow function doesn't
+ * resubscribe on every render — only a changed `roomId` does. Requires
+ * `init()`; without an engine (SSR, tests) this is a no-op.
+ */
+export function useRoomMessages(
+  roomId: string,
+  onMessage: (message: RoomMessage) => void,
+): void {
+  const handlerRef = useRef(onMessage);
+  handlerRef.current = onMessage;
+
+  useEffect(() => {
+    if (!roomId) return;
+    const engine = tryGetSync();
+    if (!engine) return;
+    return engine.subscribeRoomMessages(roomId, (msg) => {
+      handlerRef.current(msg);
+    });
+  }, [roomId]);
+}