flux-md 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ 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
+652/652, GFM) was already comprehensive, so this release sharpens the surface
+around it.
+
+### Added
+
+- **`onError` on `FluxClient`** — `new FluxClient({ onError })` receives worker
+  and parse errors (previously only `console.error`'d). A **WASM-init failure**
+  now also surfaces: `whenReady()` **rejects** instead of hanging forever, and
+  `onError` fires with `{ fatal: true }`.
+- **`a11y` parser option** (`ParserConfig.a11y` / `setA11y` / `<flux-markdown
+  a11y>`) — opt-in accessibility markup that intentionally deviates from strict
+  GFM byte-output: wraps a task-list checkbox + its text in a `<label>` (so the
+  box is programmatically associated for screen readers), and adds
+  `scope="col"` to table header cells. **Off by default** (conformance output
+  unchanged). Streaming output stays byte-identical to one-shot.
+- **`FluxClient.outline()`** — a heading table-of-contents (level / text /
+  stable id) from the current snapshot, in document order; works mid-stream.
+- **`FluxClient.toPlaintext()`** — the rendered document as plain text (tags
+  stripped, entities decoded, blocks blank-line separated) for search indexing
+  / summaries.
+
+### Fixed
+
+- **`<flux-markdown>` `src` race** — rapidly changing `src` (or switching
+  between a `src` URL and inline `markdown`/`textContent`) could interleave two
+  fetch streams into one parser, corrupting the parse tree. The element now
+  supersedes any in-flight fetch (monotonic token + `AbortController`) at a
+  single chokepoint.
+
+### Docs / packaging
+
+- README documents the one-line Vite `optimizeDeps.exclude` requirement.
+- `"sideEffects": ["./src/worker.ts"]` so bundlers can drop unused framework
+  adapters from the export surface.
+- CI now publishes via a tag-triggered workflow with `npm publish --provenance`,
+  and asserts every published tarball ships a non-empty WASM artifact.
+
 ## 0.6.0 — 2026-05-28
 
 ### Added — flux-md is no longer React-only

package/README.md

@@ -23,6 +23,20 @@ Web Workers); it does not run under SSR/RSC. The framework packages — `react`,
 need the one whose binding you import. The core (`flux-md`, `flux-md/client`,
 `flux-md/dom`, `flux-md/element`) needs none.
 
+> **Vite — one-line config.** Vite's dependency pre-bundling (esbuild) hoists
+> the wasm-bindgen glue into `.vite/deps/`, which breaks the relative
+> `new URL("…_bg.wasm", import.meta.url)` lookup so the worker can't load WASM
+> (you'll see a 404 / "magic word" error). Exclude flux-md from pre-bundling:
+>
+> ```ts
+> // vite.config.ts
+> export default defineConfig({
+>   optimizeDeps: { exclude: ["flux-md"] },
+> });
+> ```
+>
+> No other bundler needs this — it's specific to Vite's optimizer.
+
 ## Quick start
 
 ```ts
@@ -244,19 +258,40 @@ if you hit a transform edge, `mountFluxMarkdown` from `flux-md/dom` inside
 
 ```ts
 class FluxClient {
-  constructor(options?: { pool?: FluxPool; config?: ParserConfig });
+  constructor(options?: {
+    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
-  whenReady(): Promise<void>;                       // resolves once WASM loaded
+  whenReady(): Promise<void>;                       // resolves once WASM loaded; rejects on init failure
   subscribe(listener: () => void): () => void;      // React-friendly store
   getSnapshot(): Block[];                           // ordered current blocks
+  outline(): { level: number; text: string; id: number }[]; // heading table-of-contents (works mid-stream)
+  toPlaintext(): string;                            // rendered document as plain text (search / summaries)
   getMetrics(): { bytes, patches, totalParseMs, throughputKBs,
                    retainedBytes, wasmMemoryBytes, ... };
 }
 ```
 
+`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()`. Pass `onBlock` to run a side
+effect each time a block commits (e.g. lazy-highlight a finished code block).
+
 #### Per-stream config
 
 ```ts
@@ -267,6 +302,7 @@ const client = new FluxClient({
     gfmFootnotes: true,   // [^1] + [^1]: → footnote section (default false)
     gfmMath: true,        // $…$ / \(…\) inline + $$…$$ / \[…\] display math (default false)
     dirAuto: true,        // per-block dir="auto" for RTL/bidi text (default false)
+    a11y: true,           // task-list <label> + <th scope="col"> a11y markup (default false)
     unsafeHtml: false,    // pass raw HTML through (default false — keep it false for untrusted input)
     componentTags: ["Thinking", "Callout"], // custom tags with markdown inside (default none)
   },
@@ -288,6 +324,10 @@ When to enable each flag:
   definitions. Off by default; see the footnote streaming caveat above.
 - `dirAuto: true` — when content can be RTL / mixed-direction. Emits per-block
   `dir="auto"` so the browser detects direction independently per block.
+- `a11y: true` — opt-in accessibility markup that deviates from strict GFM
+  byte-output: wraps task-list checkboxes in a `<label>` (screen-reader
+  association) and adds `scope="col"` to table headers. Off by default so
+  conformance output stays exact.
 - `unsafeHtml: true` — only when rendering trusted HTML. For untrusted /
   LLM-produced HTML, pair this with `<FluxMarkdown sanitize={…} />` (DOMPurify or
   similar — see [Security](#security)).

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "flux-md",
-  "version": "0.6.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"],
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {

package/src/client.ts

@@ -22,6 +22,34 @@ export function emptyBlockStore(): BlockStore {
   return { committed: new Map(), committedOrder: [], active: [], snapshot: [] };
 }
 
+/** A heading entry for building a table of contents — see {@link FluxClient.outline}. */
+export interface OutlineEntry {
+  /** Heading level 1–6. */
+  level: number;
+  /** Plain-text heading content (tags stripped, entities decoded). */
+  text: string;
+  /** Stable block id — usable as a scroll target / React key. */
+  id: number;
+}
+
+/** Strip tags (→ space) and decode the small entity set the core emits, then
+ *  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, " ")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
 export function applyPatch(store: BlockStore, patch: Patch): void {
   for (const b of patch.newly_committed) {
     if (!store.committed.has(b.id)) store.committedOrder.push(b.id);
@@ -47,8 +75,12 @@ export function applyPatch(store: BlockStore, patch: Patch): void {
 interface PoolWorker {
   worker: WorkerLike;
   ready: boolean;
+  /** Set once WASM init fails; whenWorkerReady rejects with this thereafter. */
+  failed: Error | null;
   streamCount: number;
-  readyResolvers: Array<() => void>;
+  /** Live stream ids on this worker — so a fatal failure can notify each one. */
+  streamIds: Set<number>;
+  readyWaiters: Array<{ resolve: () => void; reject: (e: Error) => void }>;
 }
 
 /**
@@ -79,6 +111,7 @@ export class FluxPool {
     const streamId = this.nextStreamId++;
     const pw = this.pick();
     pw.streamCount++;
+    pw.streamIds.add(streamId);
     this.handlers.set(streamId, handler);
     return { streamId, pw };
   }
@@ -86,6 +119,7 @@ export class FluxPool {
   /** Free a stream's parser in its worker; keep the worker warm for siblings. */
   release(streamId: number, pw: PoolWorker): void {
     this.handlers.delete(streamId);
+    pw.streamIds.delete(streamId);
     pw.streamCount = Math.max(0, pw.streamCount - 1);
     try {
       pw.worker.postMessage({ type: "dispose", streamId });
@@ -98,10 +132,11 @@ export class FluxPool {
     pw.worker.postMessage(msg);
   }
 
-  /** Resolves when the given worker has finished WASM init. */
+  /** Resolves when the given worker has finished WASM init; rejects if it failed. */
   whenWorkerReady(pw: PoolWorker): Promise<void> {
     if (pw.ready) return Promise.resolve();
-    return new Promise((resolve) => pw.readyResolvers.push(resolve));
+    if (pw.failed) return Promise.reject(pw.failed);
+    return new Promise((resolve, reject) => pw.readyWaiters.push({ resolve, reject }));
   }
 
   /** Terminate every worker (test teardown / full shutdown). */
@@ -121,17 +156,28 @@ 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 {
-    const pw: PoolWorker = { worker: this.factory(), ready: false, streamCount: 0, readyResolvers: [] };
+    const pw: PoolWorker = {
+      worker: this.factory(),
+      ready: false,
+      failed: null,
+      streamCount: 0,
+      streamIds: new Set(),
+      readyWaiters: [],
+    };
     pw.worker.addEventListener("message", (ev) => this.onMessage(pw, ev.data));
     this.workers.push(pw);
     return pw;
@@ -140,12 +186,43 @@ export class FluxPool {
   private onMessage(pw: PoolWorker, msg: FromWorker): void {
     if (msg.type === "ready") {
       pw.ready = true;
-      const resolvers = pw.readyResolvers;
-      pw.readyResolvers = [];
-      for (const r of resolvers) r();
+      const waiters = pw.readyWaiters;
+      pw.readyWaiters = [];
+      for (const w of waiters) w.resolve();
       return;
     }
-    this.handlers.get(msg.streamId)?.(msg);
+    if (msg.type === "error" && msg.fatal) {
+      // 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
+      // 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) {
+        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.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);
+    }
   }
 }
 
@@ -194,6 +271,8 @@ export class FluxClient {
   private configSent = false;
   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;
@@ -209,10 +288,26 @@ export class FluxClient {
    *   process-wide pool — pass a dedicated `FluxPool` only for isolation).
    * @param options.config per-stream parser flags (see {@link ParserConfig});
    *   omitted fields use library defaults. Applied once, immutable thereafter.
+   * @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 } = {}) {
+  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;
@@ -244,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;
@@ -290,6 +416,37 @@ export class FluxClient {
     };
   }
 
+  /**
+   * A heading outline of the current snapshot (committed + active), in document
+   * order — for a table of contents. Works mid-stream; entries appear as their
+   * headings stream in. The `id` is stable, so a built ToC won't re-key.
+   */
+  outline(): OutlineEntry[] {
+    const out: OutlineEntry[] = [];
+    for (const b of this.store.snapshot) {
+      if (b.kind.type === "Heading") {
+        out.push({ level: (b.kind.data as number) ?? 1, text: htmlToText(b.html), id: b.id });
+      }
+    }
+    return out;
+  }
+
+  /**
+   * The rendered document as plain text — tags stripped, entities decoded,
+   * blocks separated by blank lines. Derived from the rendered HTML (the source
+   * markdown is parsed away in WASM and not retained client-side), so it is a
+   * readable approximation for search indexing / summaries, not a round-trip of
+   * the original source.
+   */
+  toPlaintext(): string {
+    const parts: string[] = [];
+    for (const b of this.store.snapshot) {
+      const t = htmlToText(b.html);
+      if (t) parts.push(t);
+    }
+    return parts.join("\n\n");
+  }
+
   private onMessage(msg: FromWorker) {
     switch (msg.type) {
       case "patch":
@@ -301,10 +458,20 @@ 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":
-        // eslint-disable-next-line no-console
-        console.error("flux worker error:", msg.message);
+        if (this.onError) {
+          this.onError({ message: msg.message, fatal: msg.fatal });
+        } else {
+          // eslint-disable-next-line no-console
+          console.error("flux worker error:", msg.message);
+        }
         break;
     }
   }

package/src/element.ts

@@ -38,6 +38,7 @@ const CONFIG_ATTRS = [
   "gfm-footnotes",
   "gfm-math",
   "dir-auto",
+  "a11y",
   "unsafe-html",
 ];
 
@@ -61,6 +62,14 @@ export function defineFluxMarkdown(tag = "flux-markdown"): void {
     #sanitize: ((html: string) => string) | undefined = undefined;
     #handle: MountHandle | null = null;
     #connected = false;
+    // In-flight `src` fetch supersession. A self-owned client is REUSED across
+    // src changes (not torn down), so two concurrent #streamFromSrc runs would
+    // capture the same client and reset() even reuses the worker streamId — an
+    // identity guard alone can't separate them. Each run captures the current
+    // #srcSeq; a newer src (or teardown) bumps it and aborts the fetch, so a
+    // stale run bails before interleaving its chunks into the parser.
+    #srcSeq = 0;
+    #srcAbort: AbortController | null = null;
 
     // --- Accessor properties (objects/functions can't be attributes) ---------
 
@@ -96,17 +105,24 @@ 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();
     }
 
     reset(): void {
-      // Keep config; just clear the current stream's blocks.
+      // Keep config; just clear the current stream's blocks. Also abandon any
+      // in-flight `src` fetch so it can't append into the freshly-reset stream.
+      this.#cancelSrcStream();
       this.#client?.reset();
     }
 
@@ -171,6 +187,8 @@ export function defineFluxMarkdown(tag = "flux-markdown"): void {
 
     disconnectedCallback(): void {
       this.#connected = false;
+      // Stop any in-flight `src` fetch before we (maybe) destroy its client.
+      this.#cancelSrcStream();
       // ALWAYS tear down the mount (the only teardown path for the renderer).
       this.#handle?.destroy();
       this.#handle = null;
@@ -210,6 +228,7 @@ export function defineFluxMarkdown(tag = "flux-markdown"): void {
       set("gfm-footnotes", "gfmFootnotes");
       set("gfm-math", "gfmMath");
       set("dir-auto", "dirAuto");
+      set("a11y", "a11y");
       set("unsafe-html", "unsafeHtml");
 
       const tags = this.getAttribute("component-tags");
@@ -252,6 +271,8 @@ export function defineFluxMarkdown(tag = "flux-markdown"): void {
     // Destroys the client only if self-owned, then clears it and the mount so
     // the next mount targets a fresh client.
     #teardownClient(): void {
+      // A swap/destroy abandons the current client; stop feeding it from src.
+      this.#cancelSrcStream();
       this.#handle?.destroy();
       this.#handle = null;
       if (this.#ownsClient) this.#client?.destroy();
@@ -263,6 +284,12 @@ export function defineFluxMarkdown(tag = "flux-markdown"): void {
     // in priority order: `src` (fetch+stream) > `markdown` (one-shot) >
     // textContent (one-shot). A caller-owned client never reaches here.
     #resolveInitialContent(): void {
+      // Single chokepoint: every content-source resolution supersedes any
+      // in-flight `src` fetch. This covers the src→markdown / src→textContent
+      // transitions too — #oneShot reuses (resets + finalizes) the same client,
+      // so without this a still-pending fetch would append into the finished
+      // stream. (#streamFromSrc bumps again; the extra bump is harmless.)
+      this.#cancelSrcStream();
       const src = this.getAttribute("src");
       if (src) {
         void this.#streamFromSrc(src);
@@ -301,17 +328,38 @@ export function defineFluxMarkdown(tag = "flux-markdown"): void {
       this.#client!.finalize();
     }
 
+    // Abort any in-flight `src` fetch and invalidate its read loop, so it can
+    // no longer append into a client we're about to reuse, swap, or destroy.
+    #cancelSrcStream(): void {
+      this.#srcSeq++;
+      this.#srcAbort?.abort();
+      this.#srcAbort = null;
+    }
+
     // Fetch a URL and stream its body. TextDecoder with {stream:true} carries a
     // multibyte sequence that straddles a chunk boundary into the next decode.
     async #streamFromSrc(src: string): Promise<void> {
+      // Supersede any prior in-flight src, then tag this run with a fresh token.
+      this.#cancelSrcStream();
+      const token = this.#srcSeq;
+      const abort = new AbortController();
+      this.#srcAbort = abort;
+
       this.#ensureClient();
       this.#client!.reset();
       const owned = this.#client!;
+      // True while THIS run is still the active stream: not superseded by a
+      // newer src, and the client wasn't swapped/destroyed out from under us.
+      const current = () => this.#srcSeq === token && this.#client === owned;
+
       try {
-        const res = await fetch(src);
+        const res = await fetch(src, { signal: abort.signal });
+        if (!current()) return;
         const body = res.body;
         if (!body) {
-          owned.append(await res.text());
+          const text = await res.text();
+          if (!current()) return;
+          owned.append(text);
           owned.finalize();
           return;
         }
@@ -319,16 +367,15 @@ export function defineFluxMarkdown(tag = "flux-markdown"): void {
         const decoder = new TextDecoder();
         for (;;) {
           const { done, value } = await reader.read();
-          // The element may have been disconnected (and `owned` destroyed) or
-          // the client swapped mid-stream; stop feeding a stale client.
-          if (this.#client !== owned) return;
+          if (!current()) return;
           if (done) break;
           if (value) owned.append(decoder.decode(value, { stream: true }));
         }
-        if (this.#client !== owned) return;
         owned.append(decoder.decode()); // flush any trailing partial sequence
         owned.finalize();
       } catch (err) {
+        // A supersede/disconnect aborts the fetch — intentional, not an error.
+        if (abort.signal.aborted || !current()) return;
         // eslint-disable-next-line no-console
         console.error("<flux-markdown>: failed to stream src", src, err);
       }

package/src/types-core.ts

@@ -89,6 +89,13 @@ export interface ParserConfig {
    * apps that render RTL or mixed-direction content.
    */
   dirAuto?: boolean;
+  /**
+   * Opt-in accessibility markup that deviates from strict GFM byte-output:
+   * wraps a task-list checkbox + its text in a `<label>` (programmatic
+   * association for screen readers) and adds `scope="col"` to table header
+   * cells. Default false (so CommonMark/GFM conformance output is unchanged).
+   */
+  a11y?: boolean;
   /** Pass raw HTML through unescaped. Default false. **Never enable for untrusted input.** */
   unsafeHtml?: boolean;
   /**
@@ -124,7 +131,9 @@ export type FromWorker =
       retainedBytes: number;
       wasmMemoryBytes: number;
     }
-  | { type: "error"; streamId: number; message: string };
+  // `fatal` marks a worker-level failure (WASM init) that dooms every stream on
+  // the worker — not a single parse error. It carries no meaningful streamId.
+  | { type: "error"; streamId: number; message: string; fatal?: boolean };
 
 /**
  * Minimal structural interface satisfied by the DOM `Worker`. Injectable so the

package/src/wasm/flux_md_core.d.ts

@@ -14,6 +14,12 @@ export class FluxParser {
      * memory cost against alternatives.
      */
     retainedBytes(): number;
+    /**
+     * Opt-in accessibility markup that deviates from strict GFM byte-output:
+     * `<label>`-wrap a task-list checkbox with its text, and add `scope="col"`
+     * to table header cells. Off by default (conformance output unchanged).
+     */
+    setA11y(on: boolean): void;
     /**
      * Set the opt-in component-tag allowlist (e.g. `["Thinking", "Callout"]`).
      * A `<Tag>…</Tag>` whose name is listed renders as a component whose inner
@@ -67,6 +73,7 @@ export interface InitOutput {
     readonly fluxparser_finalize: (a: number, b: number) => void;
     readonly fluxparser_new: () => number;
     readonly fluxparser_retainedBytes: (a: number) => number;
+    readonly fluxparser_setA11y: (a: number, b: number) => void;
     readonly fluxparser_setComponentTags: (a: number, b: number, c: number) => void;
     readonly fluxparser_setDirAuto: (a: number, b: number) => void;
     readonly fluxparser_setGfmAlerts: (a: number, b: number) => void;

package/src/wasm/flux_md_core.js

@@ -73,6 +73,15 @@ export class FluxParser {
         const ret = wasm.fluxparser_retainedBytes(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * Opt-in accessibility markup that deviates from strict GFM byte-output:
+     * `<label>`-wrap a task-list checkbox with its text, and add `scope="col"`
+     * to table header cells. Off by default (conformance output unchanged).
+     * @param {boolean} on
+     */
+    setA11y(on) {
+        wasm.fluxparser_setA11y(this.__wbg_ptr, on);
+    }
     /**
      * Set the opt-in component-tag allowlist (e.g. `["Thinking", "Callout"]`).
      * A `<Tag>…</Tag>` whose name is listed renders as a component whose inner

package/src/wasm/flux_md_core_bg.wasm.d.ts

@@ -7,6 +7,7 @@ export const fluxparser_bufferLen: (a: number) => number;
 export const fluxparser_finalize: (a: number, b: number) => void;
 export const fluxparser_new: () => number;
 export const fluxparser_retainedBytes: (a: number) => number;
+export const fluxparser_setA11y: (a: number, b: number) => void;
 export const fluxparser_setComponentTags: (a: number, b: number, c: number) => void;
 export const fluxparser_setDirAuto: (a: number, b: number) => void;
 export const fluxparser_setGfmAlerts: (a: number, b: number) => void;

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

package/src/worker.ts

@@ -27,8 +27,16 @@ async function setup() {
   // init() returns the wasm-bindgen instance; capture its `.memory` export so
   // we can report WASM-side memory usage on every patch. No parser yet — they
   // are created per stream, on demand.
-  wasmExports = await init({ module_or_path: wasmUrl });
-  post({ type: "ready" });
+  try {
+    wasmExports = await init({ module_or_path: wasmUrl });
+    post({ type: "ready" });
+  } catch (e: unknown) {
+    // WASM failed to load/instantiate: this worker can never parse anything.
+    // Report it so the pool rejects whenReady() (rather than hanging forever)
+    // and clients' onError fires. streamId is irrelevant for a worker-level
+    // failure — the pool routes a fatal error to every stream it hosts.
+    post({ type: "error", streamId: -1, message: e instanceof Error ? e.message : String(e), fatal: true });
+  }
 }
 
 function getOrCreate(streamId: number): FluxParser {
@@ -44,6 +52,7 @@ function getOrCreate(streamId: number): FluxParser {
     p.setGfmFootnotes(c?.gfmFootnotes ?? false);
     p.setGfmMath(c?.gfmMath ?? false);
     p.setDirAuto(c?.dirAuto ?? false);
+    p.setA11y(c?.a11y ?? false);
     p.setUnsafeHtml(c?.unsafeHtml ?? false);
     p.setComponentTags(c?.componentTags ?? []);
     parsers.set(streamId, p);