flux-md 0.15.0 → 0.16.0

package/README.md

@@ -241,7 +241,11 @@ controlled-string helpers wrap; in vanilla you call it directly.
 
 `mountFluxMarkdown(client, container, options?)` returns `{ destroy(), refresh() }`.
 Options: `components`, `sanitize`, `virtualize`, `stickToBottom`, `highlightCode`
-(default true), `batch` (default true — one DOM write per `requestAnimationFrame`).
+(default true), `batch` (default true — one DOM write per `requestAnimationFrame`),
+`morphOpenBlocks` (default false — morph a growing generic open block's subtree in
+place instead of rebuilding it via `innerHTML`, so only the changed parts repaint
+and focus/selection in the streaming tail survive; the rendered result is
+equivalent to the default rebuild path).
 Block-kind overrides use `components` keyed by block-kind (`CodeBlock`, `Table`,
 `Alert`, `Component`, …) with values `(props) => HTMLElement | string`. Tag-level
 (lowercase `a`/`table`/`code`) overrides are **React-only** — there's no virtual
@@ -995,6 +999,43 @@ genuinely hostile content where CSS-overlay/clickjacking matters, render inside
 a sandboxed `<iframe>` instead — sanitization stops injection, not every
 visual-overlay trick.
 
+### Supply-chain transparency
+
+flux-md is **zero runtime dependency** — no third-party packages are pulled in
+at runtime. The parsing core is Rust compiled to WebAssembly, reproducibly
+buildable from `crates/flux-md-core/` via `bun run build:wasm`.
+
+**Native code (WebAssembly).** The shipped `flux_md_core_bg.wasm` (~200 KB) is
+first-party, built from the Rust source in this repo, and runs inside a sandboxed
+Web Worker (browser) or Node worker thread. Supply-chain scanners such as
+[Socket.dev](https://socket.dev) will flag it as `nativeCode` — this is accurate
+and expected. The WASM is not a vendored third-party binary; it is reproducible
+from source.
+
+**Network access.** flux-md performs network I/O in exactly two scenarios, both
+caller-driven:
+
+- `<flux-markdown src="URL">` — the Web Component fetches the URL you supply and
+  streams the response. No URL is ever chosen by flux-md itself.
+- The wasm-bindgen glue (`wasm/flux_md_core.js`) loads the co-located `.wasm`
+  asset via `fetch(new URL("…_bg.wasm", import.meta.url))` — bundlers resolve
+  this to a local build artifact, not a remote endpoint.
+
+flux-md has no telemetry, no analytics, and no first-party remote endpoints.
+Socket will flag the `networkAccess` signal — it is accurate and expected. In
+privileged contexts (browser extensions, Electron, environments where the
+same-origin policy may not apply), treat the `src` attribute value as you would
+any external URL and allowlist it in your CSP / security policy.
+
+**Filesystem access (Node/SSR only).** `flux-md/server` reads the package's
+own `.wasm` file off disk on Node.js (Node's `fetch` cannot load `file://`
+URLs). This is a Node-only path; it reads only the package-internal asset and
+never touches caller-supplied paths. Socket will flag `filesystemAccess` — also
+accurate and expected.
+
+The `socket.yml` at the repository root documents these signals with their
+justifications for Socket's GitHub app.
+
 ## Scaling
 
 `FluxClient`s share a **worker pool** (`getDefaultPool()`), so concurrency

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.15.0",
+  "version": "0.16.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", "./src/styles.css"],
@@ -22,8 +22,7 @@
   },
   "files": [
     "src",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
   "peerDependencies": {
     "react": ">=18",

package/src/block-props.ts

@@ -2,6 +2,7 @@ import type {
   Block,
   BlockComponentProps,
   CodeBlockData,
+  ContainerData,
   HeadingData,
   ListData,
   MathBlockData,
@@ -86,7 +87,7 @@ export function blockProps(block: Block): BlockComponentProps {
     speculative: block.speculative,
   };
   const data = block.kind.data as
-    | { lang?: string | null; code?: string; latex?: string; start?: number; ordered?: boolean; tag?: string; attrs?: [string, string][] }
+    | { lang?: string | null; code?: string; latex?: string; start?: number; ordered?: boolean; items?: { html: string }[]; tag?: string; attrs?: [string, string][] }
     | undefined;
   if (block.kind.type === "CodeBlock") {
     // Prefer the structured `code` (present when blockData is on) over the HTML
@@ -105,9 +106,10 @@ export function blockProps(block: Block): BlockComponentProps {
     }
   } else if (block.kind.type === "List") {
     // Structured list data is present only when blockData is on (the `start` key
-    // rides the opt-in channel); surface it as the typed convenience field.
+    // rides the opt-in channel); surface it as the typed convenience field,
+    // including the opt-in per-item HTML (`items`) for a keyed renderer.
     if (data && typeof data.start === "number") {
-      props.list = { ordered: !!data.ordered, start: data.start } as ListData;
+      props.list = { ordered: !!data.ordered, start: data.start, items: data.items } as ListData;
     }
   } else if (block.kind.type === "Component") {
     props.tag = data?.tag ?? "";
@@ -126,6 +128,14 @@ export function blockProps(block: Block): BlockComponentProps {
     if (typeof block.kind.data === "object" && block.kind.data !== null) {
       props.heading = block.kind.data as HeadingData;
     }
+  } else if (block.kind.type === "Blockquote" || block.kind.type === "Alert") {
+    // When `blockData` is on, a Blockquote's `kind.data` is `{ nested }` and an
+    // Alert's is `{ kind, nested }`; off, a Blockquote has no `data` and an Alert
+    // only `{ kind }`. Surface the keyed `nested` sub-blocks only when present.
+    const cd = block.kind.data as { nested?: { html: string }[] } | undefined;
+    if (cd && Array.isArray(cd.nested)) {
+      props.container = { nested: cd.nested } as ContainerData;
+    }
   }
   return props;
 }

package/src/client.ts

@@ -271,6 +271,15 @@ export function getDefaultPool(): FluxPool {
   return defaultPool;
 }
 
+/** TEST-ONLY: drop the process-wide default pool so the next {@link getDefaultPool}
+ *  rebuilds it (lazily, with the current global `Worker`). Lets a test file that
+ *  drives the default pool start from a clean, deterministic state regardless of
+ *  which other file warmed it first in bun's shared test process. Not part of the
+ *  public API and a no-op for normal runtime use. */
+export function __resetDefaultPool(): void {
+  defaultPool = null;
+}
+
 // --------------------------------------------------------------------------
 // Client
 // --------------------------------------------------------------------------
@@ -307,6 +316,20 @@ export class FluxClient {
   private lastContent = "";
   private contentDone = false;
 
+  // Opt-in rAF coalescing (see constructor `coalesce`). When on AND
+  // requestAnimationFrame exists, intra-frame emit()s collapse into ONE
+  // rAF-scheduled flush to listeners — the React useSyncExternalStore path then
+  // renders once per frame instead of once per patch (the DOM renderer already
+  // batches to 1/frame independently). Lossless: committed blocks are
+  // reference-stable, so a dropped intermediate notify only skips a tail-only
+  // render that the next flush supersedes. The finalize/done patch is exempt and
+  // flushes synchronously, never deferred to the next frame.
+  private coalesce = false;
+  private rafHandle: number | null = null;
+  // Set by finalize(); the next patch's emit flushes synchronously (a 'done'
+  // notification must not be deferred a frame) and clears it.
+  private finalizePending = false;
+
   // Perf
   private appendedBytes = 0;
   private patchCount = 0;
@@ -315,6 +338,11 @@ export class FluxClient {
   private firstAppendMs = 0;
   private retainedBytes = 0;
   private wasmMemoryBytes = 0;
+  // Render-path observability (advanced ONLY when an onRenderMetrics hook is
+  // wired into a renderer; zero-cost otherwise). renderCount = React BlockView
+  // body renders; rebuildCount = DOM node rebuilds.
+  private renderCount = 0;
+  private rebuildCount = 0;
 
   /**
    * @param options.pool   worker pool to join (defaults to the shared
@@ -328,6 +356,14 @@ export class FluxClient {
    *   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).
+   * @param options.coalesce opt-in (default `false`): collapse multiple
+   *   intra-frame patch notifications into ONE `requestAnimationFrame`-scheduled
+   *   flush to subscribers, so a React `useSyncExternalStore` consumer renders at
+   *   most once per frame instead of once per patch. Lossless — committed blocks
+   *   are reference-stable, so only superseded tail-only renders are skipped. The
+   *   stream-completion (finalize) patch always flushes synchronously, and a
+   *   pending frame is cancelled on `reset()`/`destroy()`. No effect when
+   *   `requestAnimationFrame` is unavailable (e.g. SSR) — emits stay synchronous.
    */
   constructor(
     options: {
@@ -335,12 +371,14 @@ export class FluxClient {
       config?: ParserConfig;
       onError?: (err: { message: string; fatal?: boolean }) => void;
       onBlock?: (block: Block) => void;
+      coalesce?: boolean;
     } = {},
   ) {
     this.pool = options.pool ?? getDefaultPool();
     this.config = options.config;
     this.onError = options.onError;
     this.onBlock = options.onBlock;
+    this.coalesce = options.coalesce ?? false;
   }
 
   /**
@@ -392,6 +430,9 @@ export class FluxClient {
 
   finalize() {
     const pw = this.ensureAcquired();
+    // The terminal patch this triggers must reach subscribers synchronously, not
+    // a frame late — mark it so the next emit flushes now even under coalescing.
+    this.finalizePending = true;
     this.pool.send(pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig() });
   }
 
@@ -514,6 +555,11 @@ export class FluxClient {
   }
 
   reset() {
+    // Only notify subscribers if there was content to clear: resetting an
+    // already-empty store leaves the view empty either way, so skip the no-op
+    // emit (which would otherwise drive every subscriber through a wasted,
+    // output-identical render pass).
+    const hadContent = this.store.snapshot.length > 0;
     this.store = emptyBlockStore();
     this.appendedBytes = 0;
     this.patchCount = 0;
@@ -524,10 +570,14 @@ export class FluxClient {
     this.wasmMemoryBytes = 0;
     this.lastContent = ""; // setContent baseline: the worker drops the parser here
     this.contentDone = false;
+    // A frame coalesced from the just-cleared stream is now stale — cancel it so
+    // it can't fire a notify referencing content reset() just dropped.
+    this.cancelFrame();
+    this.finalizePending = false;
     // Same streamId + worker — the worker frees and lazily recreates the parser.
     const pw = this.ensureAcquired();
     this.pool.send(pw, { type: "reset", streamId: this.streamId });
-    this.emit();
+    if (hadContent) this.emit(true); // clear-the-view notify is synchronous
   }
 
   destroy() {
@@ -538,6 +588,9 @@ export class FluxClient {
     // We deliberately do NOT null this.pw here: StrictMode's destroy()→reattach()
     // on the SAME instance needs the same pw/streamId to re-register.
     if (this.pw) this.pool.release(this.streamId, this.pw);
+    // Drop any pending coalesced frame so it can't fire into cleared listeners.
+    this.cancelFrame();
+    this.finalizePending = false;
     this.listeners.clear();
     this.attached = false;
   }
@@ -578,6 +631,25 @@ export class FluxClient {
 
   getSnapshot = (): Block[] => this.store.snapshot;
 
+  /**
+   * Internal: a renderer with an `onRenderMetrics` hook calls this once per
+   * actual React block render so `getMetrics().renderCount` aggregates churn.
+   * No-op cost when no hook is wired (it is simply never called). Not part of
+   * the public API surface — the underscore marks it renderer-internal.
+   */
+  __noteRender(): void {
+    this.renderCount++;
+  }
+
+  /**
+   * Internal: the DOM renderer calls this once per actual node rebuild (the
+   * changed-block branch) when an `onRenderMetrics` hook is wired, so
+   * `getMetrics().rebuildCount` aggregates churn. Never called without a hook.
+   */
+  __noteRebuild(): void {
+    this.rebuildCount++;
+  }
+
   getMetrics() {
     const elapsed = this.firstAppendMs ? Math.max(1, performance.now() - this.firstAppendMs) : 1;
     return {
@@ -594,6 +666,11 @@ export class FluxClient {
       // clients on the same worker report the same number. Use Math.max (not
       // sum) when aggregating across clients; summing double-counts.
       wasmMemoryBytes: this.wasmMemoryBytes,
+      // Render-path churn (0 unless an onRenderMetrics hook is wired into a
+      // renderer): renderCount = React block-body renders, rebuildCount = DOM
+      // node rebuilds. Committed blocks memo-skip, so they contribute once.
+      renderCount: this.renderCount,
+      rebuildCount: this.rebuildCount,
     };
   }
 
@@ -644,7 +721,11 @@ export class FluxClient {
         this.wasmMemoryBytes = msg.wasmMemoryBytes;
         this.patchCount += 1;
         this.lastPatchMs = performance.now();
-        this.emit();
+        // The post-finalize (done) patch must notify synchronously — never defer
+        // stream completion to the next frame. One-shot: cleared after use.
+        const sync = this.finalizePending;
+        this.finalizePending = false;
+        this.emit(sync);
         // 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().
@@ -663,7 +744,38 @@ export class FluxClient {
     }
   }
 
-  private emit() {
+  /**
+   * Notify subscribers of a new snapshot.
+   *
+   * With `coalesce` off (default) this is fully synchronous, exactly as before.
+   * With it on and `requestAnimationFrame` available, a normal emit only
+   * *schedules* a single per-frame flush — repeated intra-frame emits collapse
+   * into one notify. `sync` forces an immediate flush (stream completion / reset)
+   * and cancels any frame already pending so the snapshot is delivered once.
+   */
+  private emit(sync = false) {
+    if (this.coalesce && !sync && typeof requestAnimationFrame === "function") {
+      if (this.rafHandle !== null) return; // a flush is already scheduled this frame
+      this.rafHandle = requestAnimationFrame(() => {
+        this.rafHandle = null;
+        this.flushNow();
+      });
+      return;
+    }
+    // Synchronous path: drop any pending frame so its notify can't double-fire
+    // after this one, then flush immediately.
+    this.cancelFrame();
+    this.flushNow();
+  }
+
+  private flushNow() {
     for (const fn of this.listeners) fn();
   }
+
+  private cancelFrame() {
+    if (this.rafHandle !== null) {
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(this.rafHandle);
+      this.rafHandle = null;
+    }
+  }
 }