@cosmicdrift/kumiko-renderer 0.159.1 → 0.161.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.159.1",
+  "version": "0.161.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.159.1",
-    "@cosmicdrift/kumiko-headless": "0.159.1",
+    "@cosmicdrift/kumiko-framework": "0.161.0",
+    "@cosmicdrift/kumiko-headless": "0.161.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2"
   },

package/src/hooks/__tests__/use-ai-text.test.tsx

@@ -14,6 +14,7 @@ function makeDispatcher(query: Dispatcher["query"]): Dispatcher {
       getState: () => "online",
       subscribe: () => () => {},
     } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
     pendingWrites: () => [],
     pendingFiles: () => [],
   };

package/src/hooks/__tests__/use-mutation.test.tsx

@@ -14,6 +14,7 @@ function makeDispatcher(write: Dispatcher["write"]): Dispatcher {
       getState: () => "online",
       subscribe: () => () => {},
     } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
     pendingWrites: () => [],
     pendingFiles: () => [],
   };

package/src/hooks/__tests__/use-stream-handler.test.tsx

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import type { Dispatcher, DispatcherError } from "@cosmicdrift/kumiko-headless";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { useStreamHandler } from "../use-stream-handler";
+
+function makeDispatcher(streamImpl: unknown): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    stream: streamImpl as Dispatcher["stream"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function wrapperFor(dispatcher: Dispatcher) {
+  return ({ children }: { readonly children: ReactNode }) => (
+    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
+  );
+}
+
+describe("useStreamHandler", () => {
+  test("start accumulates chunks then status=done", async () => {
+    const dispatcher = makeDispatcher(async function* () {
+      yield { i: 0 };
+      yield { i: 1 };
+    });
+
+    const { result } = renderHook(() => useStreamHandler<{ i: number }>("f:stream:x:tail"), {
+      wrapper: wrapperFor(dispatcher),
+    });
+
+    await act(async () => {
+      await result.current.start({ count: 2 });
+    });
+
+    await waitFor(() => expect(result.current.status).toBe("done"));
+    expect(result.current.chunks).toEqual([{ i: 0 }, { i: 1 }]);
+    expect(result.current.error).toBeNull();
+  });
+
+  test("stream error sets status=error and error envelope", async () => {
+    const err: DispatcherError = {
+      code: "access_denied",
+      httpStatus: 403,
+      i18nKey: "errors.access",
+      message: "denied",
+    };
+    const dispatcher = makeDispatcher(async function* () {
+      yield* []; // satisfy generator shape; error is the only outcome
+      throw err;
+    });
+
+    const { result } = renderHook(() => useStreamHandler("f:stream:x:tail"), {
+      wrapper: wrapperFor(dispatcher),
+    });
+
+    await act(async () => {
+      await result.current.start();
+    });
+
+    await waitFor(() => expect(result.current.status).toBe("error"));
+    expect(result.current.error?.code).toBe("access_denied");
+  });
+
+  test("abort during stream resets status to idle (no late done)", async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((r) => {
+      release = r;
+    });
+    const dispatcher = makeDispatcher(async function* (
+      _t: string,
+      _p: unknown,
+      opts?: { signal?: AbortSignal },
+    ) {
+      yield { i: 0 };
+      await gate;
+      if (opts?.signal?.aborted) {
+        const e = { code: "aborted", httpStatus: 0, i18nKey: "x", message: "aborted" };
+        throw e;
+      }
+      yield { i: 1 };
+    });
+
+    const { result } = renderHook(() => useStreamHandler<{ i: number }>("f:stream:x:tail"), {
+      wrapper: wrapperFor(dispatcher),
+    });
+
+    let started!: Promise<void>;
+    act(() => {
+      started = result.current.start();
+    });
+    await waitFor(() => expect(result.current.chunks).toEqual([{ i: 0 }]));
+    act(() => result.current.abort());
+    release();
+    await started;
+    expect(result.current.chunks).toEqual([{ i: 0 }]);
+    expect(result.current.status).toBe("idle");
+  });
+});

package/src/hooks/use-stream-handler.ts

@@ -0,0 +1,135 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDispatcher } from "../context/dispatcher-context";
+
+// React wrapper around dispatcher.stream (#1382). Accumulates yielded
+// chunks into `chunks` (unlike useQuery({live:true}), which only
+// invalidates and re-fetches). Each start() owns an AbortController;
+// a newer start() / unmount aborts the previous run so late chunks
+// cannot clobber fresher state.
+
+export type StreamStatus = "idle" | "streaming" | "done" | "error";
+
+export type UseStreamHandlerResult<TChunk> = {
+  readonly chunks: readonly TChunk[];
+  readonly status: StreamStatus;
+  readonly error: DispatcherError | null;
+  readonly start: (payload?: unknown) => Promise<void>;
+  readonly abort: () => void;
+  readonly reset: () => void;
+};
+
+export type UseStreamHandlerOptions = {
+  // When true, start() runs once on mount with the initial payload.
+  // Default false — streams are usually user-triggered (unlike queries).
+  readonly autoStart?: boolean;
+};
+
+export function useStreamHandler<TChunk = unknown>(
+  type: string,
+  payload: unknown = {},
+  options: UseStreamHandlerOptions = {},
+): UseStreamHandlerResult<TChunk> {
+  const dispatcher = useDispatcher();
+  const { autoStart = false } = options;
+
+  const [chunks, setChunks] = useState<readonly TChunk[]>([]);
+  const [status, setStatus] = useState<StreamStatus>("idle");
+  const [error, setError] = useState<DispatcherError | null>(null);
+
+  const activeCtrl = useRef<AbortController | null>(null);
+  const payloadKey = JSON.stringify(payload);
+  const payloadRef = useRef(payload);
+  payloadRef.current = payload;
+
+  const abort = useCallback((): void => {
+    activeCtrl.current?.abort();
+    activeCtrl.current = null;
+    // User cancel — exit streaming so UI can re-enable the start button.
+    setStatus((s) => (s === "streaming" ? "idle" : s));
+  }, []);
+
+  const reset = useCallback((): void => {
+    abort();
+    setChunks([]);
+    setStatus("idle");
+    setError(null);
+  }, [abort]);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: payload via payloadKey / payloadRef
+  const start = useCallback(
+    async (overridePayload?: unknown): Promise<void> => {
+      activeCtrl.current?.abort();
+      const ctrl = new AbortController();
+      activeCtrl.current = ctrl;
+
+      setChunks([]);
+      setError(null);
+      setStatus("streaming");
+
+      const body = overridePayload !== undefined ? overridePayload : payloadRef.current;
+      try {
+        const accumulated: TChunk[] = [];
+        for await (const chunk of dispatcher.stream<TChunk>(type, body, { signal: ctrl.signal })) {
+          // skip: a newer start() already superseded this run
+          if (ctrl.signal.aborted) {
+            if (activeCtrl.current === null || activeCtrl.current === ctrl) setStatus("idle");
+            return;
+          }
+          accumulated.push(chunk);
+          setChunks([...accumulated]);
+        }
+        // skip: aborted after last chunk, don't mark done
+        if (ctrl.signal.aborted) {
+          if (activeCtrl.current === null || activeCtrl.current === ctrl) setStatus("idle");
+          return;
+        }
+        setStatus("done");
+      } catch (e) {
+        // skip: abort is not an error toast
+        if (ctrl.signal.aborted) {
+          if (activeCtrl.current === null || activeCtrl.current === ctrl) setStatus("idle");
+          return;
+        }
+        const mapped = asDispatcherError(e);
+        // skip: dispatcher-mapped abort (fetch cancelled)
+        if (mapped.code === "aborted") {
+          if (activeCtrl.current === null || activeCtrl.current === ctrl) setStatus("idle");
+          return;
+        }
+        setError(mapped);
+        setStatus("error");
+      }
+    },
+    [dispatcher, type, payloadKey],
+  );
+
+  useEffect(() => {
+    // skip: autoStart off — streams are usually user-triggered
+    if (!autoStart) return;
+    void start();
+    return () => {
+      activeCtrl.current?.abort();
+    };
+  }, [autoStart, start]);
+
+  useEffect(() => {
+    return () => {
+      activeCtrl.current?.abort();
+    };
+  }, []);
+
+  return { chunks, status, error, start, abort, reset };
+}
+
+function asDispatcherError(e: unknown): DispatcherError {
+  if (e && typeof e === "object" && "code" in e && "message" in e && "i18nKey" in e) {
+    return e as DispatcherError;
+  }
+  return {
+    code: "stream_error",
+    httpStatus: 0,
+    i18nKey: "errors.unknown",
+    message: e instanceof Error ? e.message : String(e),
+  };
+}

package/src/index.ts

@@ -94,6 +94,12 @@ export { useMutation } from "./hooks/use-mutation";
 export type { UseQueryOptions, UseQueryResult } from "./hooks/use-query";
 export { useQuery } from "./hooks/use-query";
 export { useStore, useStoreSelector } from "./hooks/use-store";
+export type {
+  StreamStatus,
+  UseStreamHandlerOptions,
+  UseStreamHandlerResult,
+} from "./hooks/use-stream-handler";
+export { useStreamHandler } from "./hooks/use-stream-handler";
 export type {
   LocaleProviderProps,
   TranslationBundle,