flux-md 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,68 @@ 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
+in the worker pool and added two small, streaming-native conveniences.
+
+### Added
+
+- **`FluxClient.pipeFrom(src)`** — hand it a `Response` or a
+  `ReadableStream<Uint8Array>` and it reads the body, `append()`s each decoded
+  chunk, and `finalize()`s. The LLM-native one-liner:
+  `await client.pipeFrom(await fetch("/api/chat"))`.
+- **`onBlock` option** — `new FluxClient({ onBlock })` fires once per block as it
+  commits (document order), for side effects like lazily highlighting a finished
+  code block or analytics. Committed blocks never re-fire.
+
+### Fixed
+
+- **Worker pool: a throwing stream handler no longer breaks sibling streams.** A
+  user `onError` (or any handler) that threw could abort the fatal-error fan-out
+  mid-loop and escape the worker message listener; dispatch is now isolated.
+- **Worker pool: a fatally-failed worker is no longer re-assigned.** `pick()`
+  skipped the `failed` flag, so after a WASM-init failure a new stream could be
+  routed onto the dead worker and hang (a client that didn't `await whenReady()`
+  had no safety net). Failed workers are now excluded from selection.
+- **`<flux-markdown>`: manual `append()`/`finalize()` supersede an in-flight
+  `src` fetch** (mirroring `reset()`), so mixing the two can't interleave.
+- Hardened the CI/publish tarball check (explicit failure if `npm pack` yields
+  no tarball) and documented the `htmlToText` core-HTML-only invariant.
+
 ## 0.7.0 — 2026-05-29
 
 DX, robustness, and accessibility round — the streaming core (perf, CommonMark

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
@@ -262,8 +290,13 @@ class FluxClient {
     pool?: FluxPool;
     config?: ParserConfig;
     onError?: (err: { message: string; fatal?: boolean }) => void; // worker/parse + WASM-init errors
+    onBlock?: (block: Block) => void;                 // fires once per block as it commits
   });
   append(chunk: string): void;                      // queue text for parsing
+  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
@@ -277,9 +310,18 @@ class FluxClient {
 }
 ```
 
+`pipeFrom` is the LLM-native shortcut — hand it a `fetch` response and it
+reads, appends, and finalizes for you:
+
+```ts
+const client = new FluxClient();
+await client.pipeFrom(await fetch("/api/chat")); // streams the body in, then finalizes
+```
+
 Pass `onError` to be notified of worker/parse errors and a fatal WASM-init
 failure (`{ fatal: true }`); without it, errors are only `console.error`'d and a
-load failure surfaces as a rejected `whenReady()`.
+load failure surfaces as a rejected `whenReady()`. Pass `onBlock` to run a side
+effect each time a block commits (e.g. lazy-highlight a finished code block).
 
 #### Per-stream config
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.7.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

@@ -33,9 +33,11 @@ export interface OutlineEntry {
 }
 
 /** Strip tags (→ space) and decode the small entity set the core emits, then
- *  collapse whitespace. The core's HTML is well-formed and escapes `>` inside
- *  attributes, so the simple tag regex is safe here. `&` decodes last so
- *  `&amp;lt;` → `&lt;`, not `<`. */
+ *  collapse whitespace. INVARIANT: the simple `<[^>]*>` strip is only safe
+ *  because every input here is HTML the Rust core produced via escape_html /
+ *  escape_attr — which escape `>` inside attribute values, so no `>` ever
+ *  appears except as a real tag close. This must NOT be fed externally-authored
+ *  HTML. `&amp;` decodes last so `&amp;lt;` → `&lt;`, not `<`. */
 function htmlToText(html: string): string {
   return html
     .replace(/<[^>]*>/g, " ")
@@ -126,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);
   }
@@ -154,13 +168,17 @@ export class FluxPool {
     return this.workers.length;
   }
 
-  // Create a new worker while under cap and every existing worker is busy;
-  // otherwise attach to the least-loaded existing worker.
+  // Create a new worker while under cap and every live worker is busy; otherwise
+  // attach to the least-loaded LIVE worker. A fatally-failed worker is never
+  // handed out (a stream on it would post into a dead worker and hang) — it is
+  // retained only to reject outstanding whenWorkerReady waiters.
   private pick(): PoolWorker {
-    if (this.workers.length < this.cap && this.workers.every((w) => w.streamCount > 0)) {
+    const live = this.workers.filter((w) => !w.failed);
+    if (this.workers.length < this.cap && live.every((w) => w.streamCount > 0)) {
       return this.create();
     }
-    return this.workers.reduce((a, b) => (b.streamCount < a.streamCount ? b : a));
+    if (live.length === 0) return this.create();
+    return live.reduce((a, b) => (b.streamCount < a.streamCount ? b : a));
   }
 
   private create(): PoolWorker {
@@ -189,17 +207,34 @@ export class FluxPool {
       // A fatal (WASM-init) failure dooms every stream on this worker. Reject
       // anyone awaiting readiness, then notify each live stream's client so its
       // onError fires — the message carries no real streamId to route by. The
-      // doomed worker stays in the pool: a later stream that pick()s it rejects
-      // immediately via pw.failed (no auto-recovery — fine for a load failure).
+      // worker is kept only to reject those waiters; pick() never reuses it.
       const err = new Error(msg.message);
       pw.failed = err;
       const waiters = pw.readyWaiters;
       pw.readyWaiters = [];
-      for (const w of waiters) w.reject(err);
-      for (const sid of pw.streamIds) this.handlers.get(sid)?.(msg);
+      for (const w of waiters) {
+        try {
+          w.reject(err);
+        } catch {
+          /* a waiter's rejection handler is the caller's problem, not ours */
+        }
+      }
+      for (const sid of pw.streamIds) this.dispatch(sid, msg);
       return;
     }
-    this.handlers.get(msg.streamId)?.(msg);
+    this.dispatch(msg.streamId, msg);
+  }
+
+  // Route a message to a stream's handler, isolating a throwing client callback
+  // (e.g. a user-supplied onError) so it can neither break the worker message
+  // loop nor starve sibling streams sharing this worker.
+  private dispatch(streamId: number, msg: FromWorker): void {
+    try {
+      this.handlers.get(streamId)?.(msg);
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.error("flux: stream message handler threw", e);
+    }
   }
 }
 
@@ -249,6 +284,8 @@ export class FluxClient {
   private listeners = new Set<() => void>();
   private store: BlockStore = emptyBlockStore();
   private onError?: (err: { message: string; fatal?: boolean }) => void;
+  private onBlock?: (block: Block) => void;
+  private attached = true;
 
   // Perf
   private appendedBytes = 0;
@@ -267,17 +304,23 @@ export class FluxClient {
    * @param options.onError invoked on a worker/parse error or a fatal WASM-init
    *   failure (`fatal: true`). Without it, errors are only `console.error`d and
    *   a load failure surfaces solely as a rejected {@link FluxClient.whenReady}.
+   * @param options.onBlock invoked once per block as it commits (in document
+   *   order, after the store updates) — for side effects like lazily
+   *   highlighting a finished code block or analytics. A committed block never
+   *   re-fires; the streaming tail does not (subscribe for live tail updates).
    */
   constructor(
     options: {
       pool?: FluxPool;
       config?: ParserConfig;
       onError?: (err: { message: string; fatal?: boolean }) => void;
+      onBlock?: (block: Block) => void;
     } = {},
   ) {
     this.pool = options.pool ?? getDefaultPool();
     this.config = options.config;
     this.onError = options.onError;
+    this.onBlock = options.onBlock;
     const { streamId, pw } = this.pool.acquire((msg) => this.onMessage(msg));
     this.streamId = streamId;
     this.pw = pw;
@@ -309,6 +352,77 @@ export class FluxClient {
     this.pool.send(this.pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig() });
   }
 
+  /**
+   * 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 | 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.
+      this.finalize();
+      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 {
+      signal?.removeEventListener("abort", onAbort);
+      try {
+        reader.releaseLock();
+      } catch {
+        /* already released (e.g. by cancel) */
+      }
+    }
+  }
+
   reset() {
     this.store = emptyBlockStore();
     this.appendedBytes = 0;
@@ -324,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) => {
@@ -397,6 +529,12 @@ export class FluxClient {
         this.patchCount += 1;
         this.lastPatchMs = performance.now();
         this.emit();
+        // After subscribers see the new snapshot, fire the per-block hook for
+        // anything that just committed (document order). A throw here is
+        // isolated by the pool's dispatch boundary and won't skip emit().
+        if (this.onBlock) {
+          for (const b of msg.patch.newly_committed) this.onBlock(b);
+        }
         break;
       case "error":
         if (this.onError) {

package/src/element.ts

@@ -105,12 +105,17 @@ export function defineFluxMarkdown(tag = "flux-markdown"): void {
     // --- Self-owned-client methods -------------------------------------------
 
     append(chunk: string): void {
+      // Manual drive supersedes any in-flight `src` fetch (mixing the two is out
+      // of contract; this makes the manual stream win predictably instead of
+      // interleaving a late fetch chunk into it).
+      this.#cancelSrcStream();
       this.#ensureClient();
       this.#client!.append(chunk);
     }
 
     finalize(): void {
       // Only meaningful for a self-owned stream; a no-op if no client yet.
+      this.#cancelSrcStream();
       this.#client?.finalize();
     }
 

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.7.0",
+  "version": "0.9.0",
   "license": "MIT",
   "files": [
     "flux_md_core_bg.wasm",