flux-md 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ Notable changes to flux-md. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## 0.9.0 — 2026-05-29
+
+Kills the React streaming boilerplate. The common case — render an LLM stream —
+goes from ~17 lines of hand-rolled lifecycle to one:
+
+```tsx
+<FluxMarkdown stream={stream} />
+```
+
+### Added
+
+- **`stream` prop on React `<FluxMarkdown>`** — pass an `AsyncIterable<string>`
+  (SSE deltas), a `Response`, or a `ReadableStream<Uint8Array>` and the
+  component owns an internal client, pipes the stream, supersedes it on change,
+  and destroys it on unmount. The `client` prop is unchanged (now optional);
+  passing a `client` keeps the existing caller-owned behavior.
+- **`useFluxStream(stream, options?)` hook (React)** — same lifecycle, returns
+  the owned `FluxClient` (so you can read `outline()` / `getMetrics()` or pass it
+  to `<FluxMarkdown client={…} />`).
+- **`pipeFrom` now also accepts an `AsyncIterable<string>`** and an optional
+  `{ signal }` — the signal is checked every iteration, so an aborted stream
+  appends no further chunks and is **not** finalized (and a byte reader is
+  `cancel()`'d). Existing `pipeFrom(Response | ReadableStream)` calls are
+  unchanged.
+
+### Notes
+
+- A stream is single-use, so React StrictMode's dev-only double-mount may
+  truncate it in development; production mounts once and is unaffected (the
+  prior manual `useEffect` form had the same caveat).
+- Rules of Hooks are respected — `<FluxMarkdown>` dispatches to one of two
+  sibling components, never a conditional hook.
+
 ## 0.8.0 — 2026-05-29
 
 A self-review of 0.7.0 (adversarial multi-agent pass) fixed two robustness gaps

package/README.md

@@ -52,33 +52,61 @@ for await (const delta of streamFromAi()) {
 client.finalize();
 ```
 
-In React:
+In React — pass the stream straight to `<FluxMarkdown>`. It owns the client,
+pipes the stream, supersedes it if it changes, and cleans up on unmount:
+
+```tsx
+import { FluxMarkdown } from "flux-md/react";
+
+export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
+  return <FluxMarkdown stream={stream} />;
+}
+```
+
+`stream` accepts an `AsyncIterable<string>` (e.g. SSE deltas), a `Response`, or
+a `ReadableStream<Uint8Array>` — so `<FluxMarkdown stream={await fetch("/api/chat")} />`
+works too.
+
+Need the client handle (for `outline()` / `getMetrics()` / a shared client)? Use
+the `useFluxStream` hook — same lifecycle, returns the owned client:
+
+```tsx
+import { FluxMarkdown, useFluxStream } from "flux-md/react";
+
+export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
+  const client = useFluxStream(stream);
+  return <FluxMarkdown client={client} />;
+}
+```
+
+<details>
+<summary>Full manual control (caller-owned client)</summary>
+
+When you want to drive the stream yourself, pass a `client` you own — the
+component never destroys it:
 
 ```tsx
 import { useEffect, useState } from "react";
 import { FluxClient, FluxMarkdown } from "flux-md";
 
 export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
-  // One client per component instance. Destroy on unmount, not on stream change.
   const [client] = useState(() => new FluxClient());
   useEffect(() => () => client.destroy(), [client]);
-
   useEffect(() => {
-    let cancelled = false;
-    (async () => {
-      for await (const chunk of stream) {
-        if (cancelled) return; // stream changed / unmounted mid-flight
-        client.append(chunk);
-      }
-      if (!cancelled) client.finalize();
-    })();
-    return () => { cancelled = true; };
+    const ac = new AbortController();
+    client.pipeFrom(stream, { signal: ac.signal }); // pipeFrom also accepts AsyncIterable
+    return () => ac.abort();
   }, [client, stream]);
-
   return <FluxMarkdown client={client} />;
 }
 ```
 
+</details>
+
+> **StrictMode note:** a stream (SSE generator / `Response`) can be consumed only
+> once, so React StrictMode's dev-only double-mount may truncate it in
+> development. Production mounts once and is unaffected.
+
 Multiple concurrent streams just need multiple clients — each runs in its own worker, so they don't share main-thread budget.
 
 ## Framework bindings
@@ -265,7 +293,10 @@ class FluxClient {
     onBlock?: (block: Block) => void;                 // fires once per block as it commits
   });
   append(chunk: string): void;                      // queue text for parsing
-  pipeFrom(src: ReadableStream<Uint8Array> | Response): Promise<void>; // read → append → finalize
+  pipeFrom(                                         // read → append → finalize
+    src: ReadableStream<Uint8Array> | Response | AsyncIterable<string>,
+    opts?: { signal?: AbortSignal },                // abort to supersede (no finalize)
+  ): Promise<void>;
   finalize(): void;                                 // mark stream complete
   reset(): void;                                    // wipe and reuse
   destroy(): void;                                  // free this stream's parser

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Zero-dep streaming markdown for the browser. Rust→WASM core, Web Worker per stream, incremental parse with speculative closure.",
   "type": "module",
   "sideEffects": ["./src/worker.ts"],

package/src/client.ts

@@ -128,6 +128,18 @@ export class FluxPool {
     }
   }
 
+  /** Inverse of {@link release}: re-register a stream's handler so it receives
+   *  patches again. For React StrictMode's dev double-mount, which destroys a
+   *  client on the simulated unmount and remounts the SAME instance. The worker
+   *  lazily recreates the disposed parser on the next append. */
+  reattach(streamId: number, pw: PoolWorker, handler: (msg: FromWorker) => void): void {
+    if (!this.handlers.has(streamId)) {
+      pw.streamCount++;
+      pw.streamIds.add(streamId);
+    }
+    this.handlers.set(streamId, handler);
+  }
+
   send(pw: PoolWorker, msg: ToWorker): void {
     pw.worker.postMessage(msg);
   }
@@ -273,6 +285,7 @@ export class FluxClient {
   private store: BlockStore = emptyBlockStore();
   private onError?: (err: { message: string; fatal?: boolean }) => void;
   private onBlock?: (block: Block) => void;
+  private attached = true;
 
   // Perf
   private appendedBytes = 0;
@@ -340,15 +353,42 @@ export class FluxClient {
   }
 
   /**
-   * Pipe a byte stream straight in: read it to completion, `append()` each
-   * decoded chunk, then `finalize()`. The LLM-native path — `await
-   * client.pipeFrom(await fetch("/api/chat"))` (pass a `Response` or its
-   * `ReadableStream` body). `TextDecoder({ stream: true })` carries a multibyte
-   * sequence that straddles a chunk boundary into the next read. Resolves once
-   * finalized; rejects (without finalizing) if the stream errors/aborts — abort
-   * the underlying fetch to cancel. Browser-only (uses `TextDecoder`).
+   * Pipe a source straight in: read it to completion, `append()` each chunk,
+   * then `finalize()`. The LLM-native path — e.g.
+   * `await client.pipeFrom(await fetch("/api/chat"))`. Accepts:
+   *   - a `Response` or its `ReadableStream<Uint8Array>` body (bytes; decoded
+   *     with `TextDecoder({ stream: true })` so a multibyte sequence straddling
+   *     a chunk boundary carries into the next read), or
+   *   - an `AsyncIterable<string>` (e.g. an SSE delta generator) — string chunks
+   *     appended verbatim.
+   *
+   * Pass `opts.signal` to supersede/cancel: the signal is checked on every
+   * iteration, so once aborted no further chunk is appended and **finalize is
+   * skipped** (a superseded stream must not finalize). For a byte source the
+   * reader is also `cancel()`'d to tear down the upstream. Resolves once
+   * finalized (or cleanly on abort); rejects if the source itself errors.
+   * Browser-only for byte sources (uses `TextDecoder`).
    */
-  async pipeFrom(source: ReadableStream<Uint8Array> | Response): Promise<void> {
+  async pipeFrom(
+    source: ReadableStream<Uint8Array> | Response | AsyncIterable<string>,
+    opts?: { signal?: AbortSignal },
+  ): Promise<void> {
+    const signal = opts?.signal;
+
+    if (signal?.aborted) return; // already superseded before we started
+
+    // AsyncIterable<string> (SSE deltas, generators). Detected by elimination:
+    // a ReadableStream has `getReader`, a Response has `body` — neither here.
+    if (!("getReader" in source) && !("body" in source)) {
+      for await (const chunk of source as AsyncIterable<string>) {
+        if (signal?.aborted) return; // superseded/unmounted: drop late chunks, no finalize
+        this.append(chunk);
+      }
+      if (!signal?.aborted) this.finalize();
+      return;
+    }
+
+    // Byte source: a Response (use its body) or a ReadableStream directly.
     const body = "body" in source ? source.body : source;
     if (!body) {
       // An empty Response body (e.g. 204) is a completed, empty stream.
@@ -356,17 +396,30 @@ export class FluxClient {
       return;
     }
     const reader = body.getReader();
+    // A pending read() can't observe `aborted` until the next chunk; cancel()
+    // on abort tears down the upstream and resolves the pending read so the
+    // loop's post-read check fires and bails without finalizing.
+    const onAbort = () => {
+      reader.cancel().catch(() => {});
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
     const decoder = new TextDecoder();
     try {
       for (;;) {
         const { done, value } = await reader.read();
+        if (signal?.aborted) return; // superseded: no finalize (cancel already fired)
         if (done) break;
         if (value) this.append(decoder.decode(value, { stream: true }));
       }
       this.append(decoder.decode()); // flush any trailing partial sequence
       this.finalize();
     } finally {
-      reader.releaseLock();
+      signal?.removeEventListener("abort", onAbort);
+      try {
+        reader.releaseLock();
+      } catch {
+        /* already released (e.g. by cancel) */
+      }
     }
   }
 
@@ -385,9 +438,27 @@ export class FluxClient {
   }
 
   destroy() {
+    if (!this.attached) return; // idempotent
     // Free this stream's parser; the shared worker stays warm for siblings.
     this.pool.release(this.streamId, this.pw);
     this.listeners.clear();
+    this.attached = false;
+  }
+
+  /**
+   * Re-register with the pool after {@link destroy} so the client receives
+   * patches again. Needed only for React StrictMode's dev double-mount, where
+   * the renderer destroys on the simulated unmount then remounts the SAME
+   * client instance; apps don't normally call this. No-op if still attached.
+   */
+  reattach() {
+    if (this.attached) return;
+    this.pool.reattach(this.streamId, this.pw, (msg) => this.onMessage(msg));
+    this.attached = true;
+    // The worker discarded this stream's config on `dispose` (unlike `reset`,
+    // which keeps it), so re-send it on the next message — otherwise the parser
+    // would be rebuilt with library defaults (gfmMath / componentTags / … lost).
+    this.configSent = false;
   }
 
   subscribe = (fn: () => void) => {

package/src/react.tsx

@@ -1,6 +1,16 @@
-import { createElement, memo, useMemo, useSyncExternalStore, type CSSProperties } from "react";
+import {
+  createElement,
+  memo,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+} from "react";
 import type { Block, BlockComponentProps, Components } from "./types";
-import type { FluxClient } from "./client";
+import { FluxClient } from "./client";
+import type { ParserConfig } from "./types-core";
 import { CodeBlock } from "./renderers/CodeBlock";
 import { MathBlock } from "./renderers/Math";
 import { Mermaid } from "./renderers/Mermaid";
@@ -48,7 +58,23 @@ import { htmlToReact } from "./html-to-react";
  */
 
 interface FluxMarkdownProps {
-  client: FluxClient;
+  /**
+   * A caller-owned client (you drive `append`/`finalize` and own its lifecycle —
+   * the component never destroys it). Mutually exclusive with `stream`; if both
+   * are given, `client` wins (a dev warning fires).
+   */
+  client?: FluxClient;
+  /**
+   * A stream to render directly — the 1-line common case. Pass a `Response`, a
+   * `ReadableStream<Uint8Array>`, or an `AsyncIterable<string>` (e.g. SSE
+   * deltas) and the component owns an internal client, pipes the stream, and
+   * destroys it on unmount. A new `stream` identity supersedes the old.
+   */
+  stream?: AsyncIterable<string> | ReadableStream<Uint8Array> | Response;
+  /** Parser config for the internally-created client (stream mode only). */
+  streamConfig?: ParserConfig;
+  /** Called if piping the `stream` rejects (the source errored). Not the worker error channel. */
+  onStreamError?: (err: Error) => void;
   components?: Components;
   /**
    * Skip layout/paint for off-screen blocks via CSS `content-visibility: auto`
@@ -77,7 +103,15 @@ interface FluxMarkdownProps {
   sanitize?: (html: string) => string;
 }
 
-function FluxMarkdownImpl({ client, components, virtualize, stickToBottom, sanitize }: FluxMarkdownProps) {
+// The original render path: subscribe to a (required, caller- or hook-owned)
+// client and render its blocks. NEVER creates or destroys a client.
+function FluxMarkdownFromClient({
+  client,
+  components,
+  virtualize,
+  stickToBottom,
+  sanitize,
+}: FluxMarkdownProps & { client: FluxClient }) {
   const blocks = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
   // Normalize "no overrides" to a stable `undefined` so memo comparisons and
   // the fast path don't churn on an empty object identity.
@@ -92,6 +126,88 @@ function FluxMarkdownImpl({ client, components, virtualize, stickToBottom, sanit
   );
 }
 
+/**
+ * Own a {@link FluxClient} for the lifetime of a component and drive it from a
+ * `stream` (a `Response`, `ReadableStream<Uint8Array>`, or
+ * `AsyncIterable<string>`). Returns the client (read `outline()` / `getMetrics()`
+ * off it, or pass it to `<FluxMarkdown client={…} />`). The client is created
+ * once and destroyed on unmount; a new `stream` identity supersedes the old
+ * (the prior pipe is aborted, the parser is reset, the new stream is piped).
+ *
+ * Caveat (matches the manual `useEffect` form): a single-use stream — a
+ * `Response`/`ReadableStream`, or an async generator — can only be consumed
+ * once, so React **StrictMode**'s dev-only double-mount may truncate it in
+ * development. Production mounts once and is unaffected. If you need dev-exact
+ * streaming, drive a caller-owned client manually.
+ */
+export function useFluxStream(
+  stream: AsyncIterable<string> | ReadableStream<Uint8Array> | Response | null | undefined,
+  options?: { config?: ParserConfig; onError?: (err: Error) => void },
+): FluxClient {
+  // One client per hook instance. (React StrictMode double-invokes this
+  // initializer in DEV, constructing a throwaway second client whose worker
+  // slot isn't reclaimed — a minor dev-only artifact; production runs it once.
+  // The committed client is what's used, and its lifecycle below is correct.)
+  const [client] = useState(() => new FluxClient({ config: options?.config }));
+  // Read onError through a ref so its identity never re-subscribes the stream.
+  const onErrorRef = useRef(options?.onError);
+  onErrorRef.current = options?.onError;
+  // Track the last stream so we reset() only on a genuine source change — never
+  // on a StrictMode replay of the same stream (which would discard its head).
+  const prevStream = useRef<typeof stream>(undefined);
+
+  // Own the client's pool attachment. On (re)mount, reattach (StrictMode's
+  // dev double-mount destroys on the simulated unmount, then remounts the SAME
+  // instance — without reattach its patches would be dropped and it'd render
+  // blank); destroy on real unmount.
+  useEffect(() => {
+    client.reattach();
+    return () => client.destroy();
+  }, [client]);
+
+  // Consume the current stream; supersede (abort, no finalize) on change/unmount.
+  useEffect(() => {
+    if (stream == null) return;
+    const ac = new AbortController();
+    if (prevStream.current !== undefined && prevStream.current !== stream) {
+      client.reset(); // a different stream replaced a prior one
+    }
+    prevStream.current = stream;
+    client.pipeFrom(stream, { signal: ac.signal }).catch((e) => {
+      if (!ac.signal.aborted) {
+        onErrorRef.current?.(e instanceof Error ? e : new Error(String(e)));
+      }
+    });
+    return () => ac.abort();
+  }, [stream, client]);
+
+  return client;
+}
+
+// Stream mode: own a client via the hook, then render the normal client path.
+function FluxMarkdownFromStream(props: FluxMarkdownProps) {
+  const client = useFluxStream(props.stream, {
+    config: props.streamConfig,
+    onError: props.onStreamError,
+  });
+  return <FluxMarkdownFromClient {...props} client={client} />;
+}
+
+// Dispatch by rendering one of two SIBLING components (never a hook in a branch,
+// which would violate the Rules of Hooks): `stream` mode owns a client, `client`
+// mode uses the caller's. `memo` skips re-render when props are unchanged. If
+// both are given `client` wins (it owns the lifecycle); passing neither is a
+// usage error and throws (rather than crashing cryptically downstream).
+function FluxMarkdownImpl(props: FluxMarkdownProps) {
+  if (props.stream != null && props.client == null) {
+    return <FluxMarkdownFromStream {...props} />;
+  }
+  if (props.client == null) {
+    throw new Error("<FluxMarkdown>: pass either a `client` or a `stream` prop.");
+  }
+  return <FluxMarkdownFromClient {...(props as FluxMarkdownProps & { client: FluxClient })} />;
+}
+
 export const FluxMarkdown = memo(FluxMarkdownImpl);
 
 function decodeEntities(s: string): string {

package/src/wasm/package.json

@@ -2,7 +2,7 @@
   "name": "flux-md-core",
   "type": "module",
   "description": "Incremental, streaming-aware markdown parser with speculative closure",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "MIT",
   "files": [
     "flux_md_core_bg.wasm",