flux-md 0.5.0 → 0.5.5

package/CHANGELOG.md

@@ -4,6 +4,179 @@ 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.5.5 — 2026-05-28
+
+### Performance
+
+- 1× memcpy in the paragraph / container cache assembly (was 2×). Both caches
+  were building the block HTML in two stages — concatenate
+  `committed + active` into an intermediate `String`, then concatenate
+  `<p>` + that into the output — so a long open paragraph or container did two
+  memcpys of the committed inner per append. The fix builds directly into the
+  output buffer and trims trailing whitespace in-place; the container case
+  backs out a provisional `<p>` opener if the body content turns out to be
+  empty (preserving the empty-body fix from 0.5.4). Output is byte-identical.
+
+  200 KB bench (best of 7), chunk=16:
+
+  | shape           | 0.5.4    | 0.5.5    | speedup |
+  |-----------------|---------:|---------:|--------:|
+  | `long_paragraph`| 142 ms   | **96 ms**| 1.48× |
+  | `emphasis_para` | 170 ms   | **116 ms**| 1.47× |
+  | `big_blockquote`| 213 ms   | **157 ms**| 1.36× |
+  | `big_alert`     | 343 ms   | **237 ms**| 1.45× |
+
+  Modest wins at every chunk size for the affected caches; the
+  table / list / fence caches are unchanged (they were already 1× memcpy).
+
+## 0.5.4 — 2026-05-28
+
+### Fixed (mid-stream rendering)
+
+- **GFM tables now form during streaming, not just at finalize.** Streaming a
+  table char-by-char (or in any chunking where the delimiter row's `\n` lands
+  in a different chunk than the row's content) used to leave the block as a
+  `<p>` spanning both lines until `.finalize()` ran. The paragraph cache's
+  delimiter-detection walked from the line AFTER the cut and so missed a
+  delimiter row that completed inside the line the cut had advanced into. The
+  fix re-checks the line containing the cut whenever it has just completed,
+  guarded by a cheap `bytes[cut..].contains('\n')` so long open paragraphs
+  without interior `\n` still take the O(new bytes) per-call path.
+- **Open alerts/blockquotes with an empty body no longer render an empty
+  `<p></p>`.** A `> [!NOTE]\n` shown mid-stream now matches the full renderer:
+  `<div class="markdown-alert ...">…<p class="...title">Note</p></div>` with
+  no empty body paragraph. The container cache was wrapping the body in
+  `<p>…</p>` unconditionally, even when the body was empty.
+
+Both bugs only manifested *before* `finalize()`. The post-finalize output —
+what every existing parity test checks — was already correct, which is why
+neither was caught earlier. A new `tests/midstream_parity.rs` asserts that the
+streamed view of an open block matches what one-shot parsing produces for the
+same prefix (tables, alerts, blockquotes, lists, code fences, math fences).
+
+### Performance
+
+- `big_table` at the artificial `chunk=16` stress case is ~280 ms (was ~145 ms
+  in 0.5.3). The 145 ms was the *incorrect* path: the paragraph cache treated
+  the whole 200 KB table as a single growing paragraph until finalize, never
+  engaging the table cache. The 280 ms is the cost of correctly emitting the
+  table mid-stream at the smallest chunk size. Every realistic LLM streaming
+  chunk size (≥64 bytes) is unchanged — `big_table` at chunk=64 is 73 ms,
+  chunk=256 is 38 ms, etc.
+
+## 0.5.3 — 2026-05-28
+
+### Performance
+
+- **Streaming long open resumable containers is now O(n).** A long
+  `> [!NOTE]` alert, a `>`-quoted explanation, or a flat bullet/ordered list
+  used to re-run scan + inline render over the whole growing inner on every
+  append (O(n²)). Three new tail caches mirror the existing fence/table
+  pattern:
+
+  - `ContainerCache` — single-paragraph blockquote / GitHub alert. Wraps
+    the existing paragraph-cache (inline-boundary commit) with a
+    `>`-stripped inner buffer; the wrapper HTML (`<blockquote>` /
+    alert `<div>`) is built once at arm time, each new `> ` line is
+    stripped once into the inner buffer, only the unsettled inline tail is
+    re-rendered. Bails on a blank `>`-line (paragraph break inside the
+    container), lazy continuation, or `\r`.
+
+  - `ListCache` — tight, flat list (the LLM-emit shape: one sibling marker
+    per line, no blanks, no continuation, no nesting). Opener
+    (`<ul>` / `<ol start=N>`) pre-rendered at arm time; each new sibling
+    line renders directly into the cache as a tight `<li>…</li>` (GFM
+    task-list `[ ] `/`[x] ` supported). Bails on the first blank line
+    (loose-list signal), non-marker line, over-edge marker (nested), or
+    foreign-family marker — the full path handles those.
+
+  Measured at 50 KB (best of 7), before → after:
+
+  | shape           | chunk=16          | chunk=256       |
+  |-----------------|-------------------|-----------------|
+  | `big_blockquote`| 5164 → **22 ms**  | 332 → **8.5 ms**|
+  | `big_list`      | 6141 → **18 ms**  | 391 → **7.4 ms**|
+  | `big_alert`     | 6298 → **28 ms**  | 404 → **11 ms** |
+
+  At 200 KB, `big_list` chunk=256 was extrapolating to ~6.2 s before the
+  cache; now **36 ms** (~170×). Every realistic streaming shape now has a
+  flat chunk-size curve.
+
+  Output is byte-identical. Parity gated by `tests/container_cache.rs`
+  (blockquote + all five alert kinds, dir_auto, CRLF, lazy continuation,
+  multi-paragraph fallback, 400-line stress) and `tests/list_cache.rs` (5
+  marker families, ordered with non-default start, dir_auto, CRLF, loose /
+  nested / multi-line fallback, 400-item stress).
+
+### Documentation
+
+- Reworded the "future plugin slot" comments in `renderers/Math.tsx` and
+  `renderers/Mermaid.tsx`. The actual extension path is the
+  `components.MathBlock` / `components.Mermaid` overrides, which already
+  works end-to-end.
+
+### Known limitations
+
+- The three new caches disarm when `gfmFootnotes` is on, mirroring
+  `TableCache` from 0.5.2: cell-level `[^x]` occurrence ids would diverge
+  across the cache vs. full-reparse boundary. Footnotes + a long container
+  / table stays on the full O(n²) path — rare combination, may be lifted
+  in a later release by tracking per-cache footnote-occ deltas.
+- The blockquote/alert cache covers the *single-paragraph* inner case (the
+  realistic LLM shape). A long open container with a multi-block inner
+  (lists inside, fenced code inside, etc.) still routes through the full
+  path. The bench's `big_blockquote` / `big_alert` are single-paragraph
+  shapes — what these caches were built for.
+
+## 0.5.2 — 2026-05-28
+
+### Performance
+
+- **Streaming a long GFM table is now O(n) at every chunk size.** Tables already
+  rendered visually incrementally (header at the delimiter row, rows append as
+  they arrive) — but `render_table` re-walked every row on every append, so the
+  total work was O(n²) once chunks exceeded ~30 bytes (a row). The fix is an
+  incremental `TableCache` that mirrors the existing code/math `FenceCache`:
+  `<thead>` is pre-rendered once, each newly-complete `<tr>` is folded into the
+  cached prefix, and only the trailing partial row is re-rendered each append.
+  Output is byte-identical; parity gated by `tests/table_cache.rs` (every chunk
+  size 1..=9 × char-by-char against one-shot, with alignments, inline markdown,
+  link refs, CRLF fallback, and a 400-row stress case).
+
+  Measured on a 200 KB table (best of 7 — chunk varies on each row):
+
+  | chunk |  before  | after | speedup |
+  |------:|---------:|------:|--------:|
+  |    16 |   143 ms | 145 ms | ~1× (was already fast) |
+  |    64 | 20807 ms |  78 ms | **267×** |
+  |   128 | 10414 ms |  54 ms | **193×** |
+  |   256 |  5373 ms |  40 ms | **134×** |
+  |   512 |  2608 ms |  34 ms |  **77×** |
+  |  1024 |  1322 ms |  31 ms |  **43×** |
+
+  The pre-fix bench printed only chunks 16 and 256, which hid the regression
+  (16 was fine, 256 was the cliff floor). The bench now sweeps 16/64/128/256/
+  512/1024 so the next regression in this shape can't slip in unnoticed.
+
+  Footnotes are the one combination still on the full O(n²) path: the
+  cell-level `[^x]` occurrence counter would diverge across the
+  cache/full-reparse boundary, so the cache disarms when `gfmFootnotes` is on
+  (rare enough to defer to a later release).
+
+## 0.5.1 — 2026-05-27
+
+### Performance
+
+- A document with a very large number of link-reference definitions is now O(n)
+  instead of O(n²). The committed reference table was cloned on every append
+  (O(refs) per chunk); it's now shared into each render via an `Rc` (O(1)) with a
+  two-level lookup (committed, then the uncommitted tail), and folded in place
+  via `Rc::make_mut` once the render's clone is dropped. A 235 KB
+  reference-definition stream at 16-byte chunks: **~1,395 ms → ~53 ms** (~26×).
+  This was believed to be the last remaining O(n²) streaming shape; in fact a
+  long open GFM table was still O(n²) (fixed in 0.5.2 — `big_table` at
+  chunk=256 went from ~5,400 ms to ~40 ms). Output is unchanged.
+
 ## 0.5.0 — 2026-05-27
 
 ### Fixed

package/package.json

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

package/src/renderers/Math.tsx

@@ -1,9 +1,11 @@
 import { memo } from "react";
 
 /**
- * Math block — preformatted-text only. flux-md is zero-dep, so we don't
- * ship KaTeX/MathJax. If you want rendered math, drop in a renderer via
- * the (future) plugin slot and override this component.
+ * Default math block — emits the LaTeX inside a `<div class="math
+ * math-display">` (or `<span class="math math-inline">` for inline). flux-md
+ * stays zero-dep, so it does not ship KaTeX/MathJax: bring your own typesetter
+ * (run it over the rendered `.math` nodes once a block closes), or override
+ * this slot via `components.MathBlock` to render the LaTeX yourself.
  */
 
 interface Props {

package/src/renderers/Mermaid.tsx

@@ -1,9 +1,10 @@
 import { memo } from "react";
 
 /**
- * Mermaid block — preformatted-text only. flux-md is zero-dep, so we don't
- * ship the Mermaid runtime. The diagram source is shown in a code block;
- * plug in your own renderer at this slot if you want SVG output.
+ * Default mermaid block — renders the diagram source verbatim in a code-like
+ * container. flux-md stays zero-dep and does not ship the Mermaid runtime:
+ * override this slot via `components.Mermaid` to render to SVG with your own
+ * Mermaid build (typically `mermaid.run` over the closed-block source text).
  */
 
 interface Props {