flux-md 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.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

@@ -262,8 +262,10 @@ 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(src: ReadableStream<Uint8Array> | Response): Promise<void>; // read → append → finalize
   finalize(): void;                                 // mark stream complete
   reset(): void;                                    // wipe and reuse
   destroy(): void;                                  // free this stream's parser
@@ -277,9 +279,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.8.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, " ")
@@ -154,13 +156,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 +195,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 +272,7 @@ 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;
 
   // Perf
   private appendedBytes = 0;
@@ -267,17 +291,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 +339,37 @@ export class FluxClient {
     this.pool.send(this.pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig() });
   }
 
+  /**
+   * 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`).
+   */
+  async pipeFrom(source: ReadableStream<Uint8Array> | Response): Promise<void> {
+    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();
+    const decoder = new TextDecoder();
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        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();
+    }
+  }
+
   reset() {
     this.store = emptyBlockStore();
     this.appendedBytes = 0;
@@ -397,6 +458,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/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.8.0",
   "license": "MIT",
   "files": [
     "flux_md_core_bg.wasm",