flux-md 0.3.1

package/src/client.ts

@@ -0,0 +1,315 @@
+import type { Block, FromWorker, ParserConfig, Patch, ToWorker, WorkerLike } from "./types";
+
+/**
+ * The ordered-block store backing a stream, extracted as a pure function so
+ * its reference-stability contract is testable without a Worker.
+ *
+ * **The contract that prevents extra React re-renders:** a block, once
+ * committed, is never re-sent by the parser, so `applyPatch` never replaces it
+ * in the map. Its object reference stays identical across every later patch —
+ * which is exactly what `blocksEqual` (the BlockView memo) checks, so committed
+ * blocks never re-render (and never re-parse) as the stream grows. Only the
+ * `active` tail gets fresh references each patch, and only it re-renders.
+ */
+export interface BlockStore {
+  committed: Map<number, Block>;
+  committedOrder: number[];
+  active: Block[];
+  snapshot: Block[];
+}
+
+export function emptyBlockStore(): BlockStore {
+  return { committed: new Map(), committedOrder: [], active: [], snapshot: [] };
+}
+
+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);
+    store.committed.set(b.id, b);
+  }
+  store.active = patch.active;
+  // Fresh array each patch (immutable for React reference checks), but the
+  // committed entries inside it are the same object references as before.
+  const next: Block[] = new Array(store.committedOrder.length + store.active.length);
+  for (let i = 0; i < store.committedOrder.length; i++) {
+    next[i] = store.committed.get(store.committedOrder[i])!;
+  }
+  for (let i = 0; i < store.active.length; i++) {
+    next[store.committedOrder.length + i] = store.active[i];
+  }
+  store.snapshot = next;
+}
+
+// --------------------------------------------------------------------------
+// Worker pool
+// --------------------------------------------------------------------------
+
+interface PoolWorker {
+  worker: WorkerLike;
+  ready: boolean;
+  streamCount: number;
+  readyResolvers: Array<() => void>;
+}
+
+/**
+ * A pool of Web Workers, each multiplexing many `FluxParser`s keyed by stream
+ * id. This is what lets flux-md scale past `hardwareConcurrency` concurrent
+ * streams without oversubscribing OS threads: 50 streams share (at most) the
+ * cap's worth of workers instead of spawning 50.
+ *
+ * Worker creation is **lazy and load-aware**: while under the cap, each new
+ * stream gets its own worker (so 1 stream = 1 worker, identical to the old
+ * behavior); once at the cap, new streams attach to the least-loaded worker.
+ *
+ * The constructor injects a `WorkerLike` factory so the routing and lifecycle
+ * logic is unit-testable with a fake worker — no real Worker or WASM needed.
+ */
+export class FluxPool {
+  private workers: PoolWorker[] = [];
+  private handlers = new Map<number, (msg: FromWorker) => void>();
+  private nextStreamId = 1;
+
+  constructor(
+    private factory: () => WorkerLike,
+    private cap: number,
+  ) {}
+
+  /** Reserve a stream id and assign a worker, registering its message handler. */
+  acquire(handler: (msg: FromWorker) => void): { streamId: number; pw: PoolWorker } {
+    const streamId = this.nextStreamId++;
+    const pw = this.pick();
+    pw.streamCount++;
+    this.handlers.set(streamId, handler);
+    return { streamId, pw };
+  }
+
+  /** 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.streamCount = Math.max(0, pw.streamCount - 1);
+    try {
+      pw.worker.postMessage({ type: "dispose", streamId });
+    } catch {
+      /* worker already gone */
+    }
+  }
+
+  send(pw: PoolWorker, msg: ToWorker): void {
+    pw.worker.postMessage(msg);
+  }
+
+  /** Resolves when the given worker has finished WASM init. */
+  whenWorkerReady(pw: PoolWorker): Promise<void> {
+    if (pw.ready) return Promise.resolve();
+    return new Promise((resolve) => pw.readyResolvers.push(resolve));
+  }
+
+  /** Terminate every worker (test teardown / full shutdown). */
+  disposeAll(): void {
+    for (const pw of this.workers) {
+      try {
+        pw.worker.terminate();
+      } catch {
+        /* ignore */
+      }
+    }
+    this.workers = [];
+    this.handlers.clear();
+  }
+
+  get workerCount(): number {
+    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.
+  private pick(): PoolWorker {
+    if (this.workers.length < this.cap && this.workers.every((w) => w.streamCount > 0)) {
+      return this.create();
+    }
+    return this.workers.reduce((a, b) => (b.streamCount < a.streamCount ? b : a));
+  }
+
+  private create(): PoolWorker {
+    const pw: PoolWorker = { worker: this.factory(), ready: false, streamCount: 0, readyResolvers: [] };
+    pw.worker.addEventListener("message", (ev) => this.onMessage(pw, ev.data));
+    this.workers.push(pw);
+    return pw;
+  }
+
+  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();
+      return;
+    }
+    this.handlers.get(msg.streamId)?.(msg);
+  }
+}
+
+function poolCap(): number {
+  const hc = typeof navigator !== "undefined" ? navigator.hardwareConcurrency : 0;
+  return Math.min(hc || 4, 8);
+}
+
+let defaultPool: FluxPool | null = null;
+
+/** The process-wide default pool every `FluxClient` shares unless given one. */
+export function getDefaultPool(): FluxPool {
+  if (!defaultPool) {
+    defaultPool = new FluxPool(
+      () => new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }) as unknown as WorkerLike,
+      poolCap(),
+    );
+  }
+  return defaultPool;
+}
+
+// --------------------------------------------------------------------------
+// Client
+// --------------------------------------------------------------------------
+
+/**
+ * Subscriber-driven store backing a single streaming parser. Each client owns
+ * one stream within a shared {@link FluxPool}; many clients multiplex over a
+ * small set of workers (see the pool for the scaling story).
+ *
+ * The store exposes:
+ *   - subscribe(listener): for React's useSyncExternalStore
+ *   - getSnapshot(): the current ordered list of blocks
+ *   - getMetrics(): per-stream perf metrics
+ *
+ * Mutation methods:
+ *   - append(chunk): forward to the worker
+ *   - finalize(): mark the stream done
+ *   - reset(): start fresh
+ */
+export class FluxClient {
+  private pool: FluxPool;
+  private pw: PoolWorker;
+  private streamId: number;
+  private config?: ParserConfig;
+  private configSent = false;
+  private listeners = new Set<() => void>();
+  private store: BlockStore = emptyBlockStore();
+
+  // Perf
+  private appendedBytes = 0;
+  private patchCount = 0;
+  private totalParseMicros = 0;
+  private lastPatchMs = 0;
+  private firstAppendMs = 0;
+  private retainedBytes = 0;
+  private wasmMemoryBytes = 0;
+
+  /**
+   * @param options.pool   worker pool to join (defaults to the shared
+   *   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.
+   */
+  constructor(options: { pool?: FluxPool; config?: ParserConfig } = {}) {
+    this.pool = options.pool ?? getDefaultPool();
+    this.config = options.config;
+    const { streamId, pw } = this.pool.acquire((msg) => this.onMessage(msg));
+    this.streamId = streamId;
+    this.pw = pw;
+  }
+
+  get ready(): boolean {
+    return this.pw.ready;
+  }
+
+  whenReady(): Promise<void> {
+    return this.pool.whenWorkerReady(this.pw);
+  }
+
+  // The config rides on the first message a stream sends; the worker applies it
+  // when it creates the parser. postMessage is FIFO per worker, so it always
+  // lands before any append is processed. Returns undefined after the first use.
+  private firstConfig(): ParserConfig | undefined {
+    if (this.configSent || !this.config) return undefined;
+    this.configSent = true;
+    return this.config;
+  }
+
+  append(chunk: string) {
+    if (this.firstAppendMs === 0) this.firstAppendMs = performance.now();
+    this.pool.send(this.pw, { type: "append", streamId: this.streamId, chunk, config: this.firstConfig() });
+  }
+
+  finalize() {
+    this.pool.send(this.pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig() });
+  }
+
+  reset() {
+    this.store = emptyBlockStore();
+    this.appendedBytes = 0;
+    this.patchCount = 0;
+    this.totalParseMicros = 0;
+    this.lastPatchMs = 0;
+    this.firstAppendMs = 0;
+    this.retainedBytes = 0;
+    this.wasmMemoryBytes = 0;
+    // Same streamId + worker — the worker frees and lazily recreates the parser.
+    this.pool.send(this.pw, { type: "reset", streamId: this.streamId });
+    this.emit();
+  }
+
+  destroy() {
+    // Free this stream's parser; the shared worker stays warm for siblings.
+    this.pool.release(this.streamId, this.pw);
+    this.listeners.clear();
+  }
+
+  subscribe = (fn: () => void) => {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  };
+
+  getSnapshot = (): Block[] => this.store.snapshot;
+
+  getMetrics() {
+    const elapsed = this.firstAppendMs ? Math.max(1, performance.now() - this.firstAppendMs) : 1;
+    return {
+      bytes: this.appendedBytes,
+      patches: this.patchCount,
+      meanParseMicros: this.patchCount > 0 ? this.totalParseMicros / this.patchCount : 0,
+      totalParseMs: this.totalParseMicros / 1000,
+      throughputKBs: (this.appendedBytes / 1024) / (elapsed / 1000),
+      committedBlocks: this.store.committed.size,
+      activeBlocks: this.store.active.length,
+      lastPatchAgoMs: this.lastPatchMs === 0 ? 0 : performance.now() - this.lastPatchMs,
+      retainedBytes: this.retainedBytes,
+      // NOTE: with the worker pool, this is the *shared* worker's WASM heap —
+      // clients on the same worker report the same number. Use Math.max (not
+      // sum) when aggregating across clients; summing double-counts.
+      wasmMemoryBytes: this.wasmMemoryBytes,
+    };
+  }
+
+  private onMessage(msg: FromWorker) {
+    switch (msg.type) {
+      case "patch":
+        applyPatch(this.store, msg.patch);
+        this.appendedBytes = msg.appendedBytes;
+        this.totalParseMicros += msg.parseMicros;
+        this.retainedBytes = msg.retainedBytes;
+        this.wasmMemoryBytes = msg.wasmMemoryBytes;
+        this.patchCount += 1;
+        this.lastPatchMs = performance.now();
+        this.emit();
+        break;
+      case "error":
+        // eslint-disable-next-line no-console
+        console.error("flux worker error:", msg.message);
+        break;
+    }
+  }
+
+  private emit() {
+    for (const fn of this.listeners) fn();
+  }
+}

package/src/hi.ts

@@ -0,0 +1,244 @@
+/**
+ * In-house syntax highlighter. Native RegExp only — no Shiki, no Prism, no
+ * Highlight.js. Covers the languages an LLM typically emits:
+ * js/ts/tsx/jsx, rust, python, go, bash, json, html, css, sql. Unknown
+ * languages fall through to plain escaped text. ~6KB minified.
+ *
+ * Highlighting is per-block, runs once when the block closes. We never
+ * highlight an open (streaming) block — that's what gives us the big perf
+ * win vs Streamdown's per-chunk Shiki invocation.
+ */
+
+const KEYWORDS_JS = new Set(
+  "async await break case catch class const continue debugger default delete do else export extends false finally for from function if import in instanceof let new null of return static super switch this throw true try typeof undefined var void while with yield".split(
+    " ",
+  ),
+);
+const KEYWORDS_TS = new Set([
+  ...KEYWORDS_JS,
+  ...["any", "as", "boolean", "declare", "enum", "interface", "is", "keyof", "module", "namespace", "never", "number", "private", "protected", "public", "readonly", "string", "type", "unknown", "satisfies"],
+]);
+const KEYWORDS_RUST = new Set(
+  "as async await break const continue crate dyn else enum extern false fn for if impl in let loop match mod move mut pub ref return Self self static struct super trait true type unsafe use where while".split(
+    " ",
+  ),
+);
+const KEYWORDS_PY = new Set(
+  "False None True and as assert async await break class continue def del elif else except finally for from global if import in is lambda nonlocal not or pass raise return try while with yield".split(
+    " ",
+  ),
+);
+const KEYWORDS_GO = new Set(
+  "break case chan const continue default defer else fallthrough for func go goto if import interface map package range return select struct switch type var nil true false".split(
+    " ",
+  ),
+);
+const KEYWORDS_BASH = new Set(
+  "if then elif else fi case esac for select while until do done function in time coproc return break continue".split(
+    " ",
+  ),
+);
+const KEYWORDS_SQL = new Set(
+  "SELECT FROM WHERE JOIN LEFT RIGHT INNER OUTER ON GROUP BY ORDER HAVING LIMIT OFFSET INSERT INTO VALUES UPDATE SET DELETE CREATE TABLE DROP ALTER INDEX VIEW IF EXISTS NOT NULL DEFAULT PRIMARY KEY FOREIGN REFERENCES UNIQUE AS WITH UNION ALL DISTINCT IS BETWEEN LIKE IN AND OR".split(
+    " ",
+  ),
+);
+
+// Each language is described by an ordered list of (token-class, regex) pairs.
+// The regex must be sticky (y flag) so it only matches at the current cursor.
+// First match wins.
+type Pat = [string, RegExp];
+
+const jsPats: Pat[] = [
+  ["com", /\/\/[^\n]*/y],
+  ["com", /\/\*[\s\S]*?\*\//y],
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["str", /'(?:\\.|[^'\\\n])*'/y],
+  ["str", /`(?:\\.|[^`\\])*`/y],
+  ["rx", /\/(?:\\.|\[(?:\\.|[^\]\\])*\]|[^/\\\n])+\/[gimsuy]*/y],
+  ["num", /\b(?:0x[\da-fA-F_]+|0b[01_]+|0o[0-7_]+|\d[\d_]*(?:\.\d[\d_]*)?(?:[eE][+-]?\d+)?)\b/y],
+  ["ident", /[A-Za-z_$][\w$]*/y],
+  ["pun", /[+\-*/=<>!&|^~?:;,.[\](){}]/y],
+  ["ws", /\s+/y],
+];
+
+const rustPats: Pat[] = [
+  ["com", /\/\/[^\n]*/y],
+  ["com", /\/\*[\s\S]*?\*\//y],
+  ["str", /b?"(?:\\.|[^"\\])*"/y],
+  ["str", /b?'(?:\\.|[^'\\])'/y],
+  ["lt", /'[a-zA-Z_][\w]*/y],
+  ["num", /\b\d[\d_]*(?:\.\d[\d_]*)?(?:[ui](?:8|16|32|64|128|size)|f(?:32|64))?\b/y],
+  ["mac", /[A-Za-z_]\w*!/y],
+  ["attr", /#!?\[[^\]]*\]/y],
+  ["ident", /[A-Za-z_]\w*/y],
+  ["pun", /[+\-*/=<>!&|^~?:;,.\[\](){}@]/y],
+  ["ws", /\s+/y],
+];
+
+const pyPats: Pat[] = [
+  ["com", /#[^\n]*/y],
+  ["str", /[fFrRbB]{0,2}"""[\s\S]*?"""/y],
+  ["str", /[fFrRbB]{0,2}'''[\s\S]*?'''/y],
+  ["str", /[fFrRbB]{0,2}"(?:\\.|[^"\\\n])*"/y],
+  ["str", /[fFrRbB]{0,2}'(?:\\.|[^'\\\n])*'/y],
+  ["num", /\b(?:0x[\da-fA-F_]+|0b[01_]+|0o[0-7_]+|\d[\d_]*(?:\.\d[\d_]*)?(?:[eE][+-]?\d+)?[jJ]?)\b/y],
+  ["dec", /@[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*/y],
+  ["ident", /[A-Za-z_]\w*/y],
+  ["pun", /[+\-*/=<>!&|^~?:;,.[\](){}@%]/y],
+  ["ws", /\s+/y],
+];
+
+const goPats: Pat[] = [
+  ["com", /\/\/[^\n]*/y],
+  ["com", /\/\*[\s\S]*?\*\//y],
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["str", /`[^`]*`/y],
+  ["str", /'(?:\\.|[^'\\\n])'/y],
+  ["num", /\b\d[\d_]*(?:\.\d[\d_]*)?\b/y],
+  ["ident", /[A-Za-z_]\w*/y],
+  ["pun", /[+\-*/=<>!&|^~?:;,.[\](){}]/y],
+  ["ws", /\s+/y],
+];
+
+const bashPats: Pat[] = [
+  ["com", /#[^\n]*/y],
+  ["str", /"(?:\\.|\$\([^)]*\)|[^"\\])*"/y],
+  ["str", /'[^']*'/y],
+  ["var", /\$\{[^}]+\}|\$\w+|\$[*@#?!$0-9]/y],
+  ["num", /\b\d+\b/y],
+  ["ident", /[A-Za-z_][\w-]*/y],
+  ["pun", /[|&;<>(){}[\]=]/y],
+  ["ws", /\s+/y],
+];
+
+const jsonPats: Pat[] = [
+  ["str", /"(?:\\.|[^"\\\n])*"/y],
+  ["num", /-?\b\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\b/y],
+  ["kw", /\b(?:true|false|null)\b/y],
+  ["pun", /[{}[\]:,]/y],
+  ["ws", /\s+/y],
+];
+
+const sqlPats: Pat[] = [
+  ["com", /--[^\n]*/y],
+  ["com", /\/\*[\s\S]*?\*\//y],
+  ["str", /'(?:''|[^'])*'/y],
+  ["str", /"(?:""|[^"])*"/y],
+  ["num", /\b\d+(?:\.\d+)?\b/y],
+  ["ident", /[A-Za-z_][\w]*/y],
+  ["pun", /[+\-*/=<>!,;.(){}]/y],
+  ["ws", /\s+/y],
+];
+
+const htmlPats: Pat[] = [
+  ["com", /<!--[\s\S]*?-->/y],
+  ["tag", /<\/?[A-Za-z][\w-]*/y],
+  ["str", /"[^"]*"/y],
+  ["str", /'[^']*'/y],
+  ["attr", /[A-Za-z][\w-]*(?==)/y],
+  ["pun", /[=/>]/y],
+  ["txt", /[^<>"'=]+/y],
+];
+
+const cssPats: Pat[] = [
+  ["com", /\/\*[\s\S]*?\*\//y],
+  ["str", /"[^"]*"/y],
+  ["str", /'[^']*'/y],
+  ["num", /-?\d+(?:\.\d+)?(?:px|em|rem|%|vh|vw|s|ms|deg)?/y],
+  ["sel", /[#.]?[A-Za-z][\w-]*/y],
+  ["pun", /[:;,{}()]/y],
+  ["ws", /\s+/y],
+];
+
+const LANGS: Record<string, { pats: Pat[]; kw?: Set<string> }> = {
+  js: { pats: jsPats, kw: KEYWORDS_JS },
+  javascript: { pats: jsPats, kw: KEYWORDS_JS },
+  ts: { pats: jsPats, kw: KEYWORDS_TS },
+  tsx: { pats: jsPats, kw: KEYWORDS_TS },
+  jsx: { pats: jsPats, kw: KEYWORDS_JS },
+  typescript: { pats: jsPats, kw: KEYWORDS_TS },
+  rust: { pats: rustPats, kw: KEYWORDS_RUST },
+  rs: { pats: rustPats, kw: KEYWORDS_RUST },
+  py: { pats: pyPats, kw: KEYWORDS_PY },
+  python: { pats: pyPats, kw: KEYWORDS_PY },
+  go: { pats: goPats, kw: KEYWORDS_GO },
+  bash: { pats: bashPats, kw: KEYWORDS_BASH },
+  sh: { pats: bashPats, kw: KEYWORDS_BASH },
+  shell: { pats: bashPats, kw: KEYWORDS_BASH },
+  json: { pats: jsonPats },
+  sql: { pats: sqlPats, kw: KEYWORDS_SQL },
+  html: { pats: htmlPats },
+  xml: { pats: htmlPats },
+  css: { pats: cssPats },
+};
+
+function escapeHtml(s: string): string {
+  let out = "";
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "<") out += "&lt;";
+    else if (c === ">") out += "&gt;";
+    else if (c === "&") out += "&amp;";
+    else if (c === '"') out += "&quot;";
+    else out += c;
+  }
+  return out;
+}
+
+export function highlight(code: string, lang: string): string {
+  const conf = LANGS[lang.toLowerCase()];
+  if (!conf) return escapeHtml(code);
+
+  let out = "";
+  let pos = 0;
+  const pats = conf.pats;
+  const kw = conf.kw;
+  // Linear pass with sticky regex tracking lastIndex.
+  while (pos < code.length) {
+    let matched = false;
+    for (let i = 0; i < pats.length; i++) {
+      const [cls, re] = pats[i];
+      re.lastIndex = pos;
+      const m = re.exec(code);
+      if (!m || m.index !== pos) continue;
+      const text = m[0];
+      const after = pos + text.length;
+      let finalCls = cls;
+      if (cls === "ident") {
+        if (kw && kw.has(text)) {
+          finalCls = "kw";
+        } else if (after < code.length && code[after] === "(") {
+          finalCls = "fn";
+        } else if (text.length > 1 && text[0] >= "A" && text[0] <= "Z") {
+          finalCls = "ty";
+        } else {
+          // Plain identifier — no span needed.
+          out += escapeHtml(text);
+          pos = after;
+          matched = true;
+          break;
+        }
+      }
+      if (cls === "ws") {
+        out += text;
+      } else {
+        out += `<span class="t-${finalCls}">${escapeHtml(text)}</span>`;
+      }
+      pos = after;
+      matched = true;
+      break;
+    }
+    if (!matched) {
+      // No pattern matched (shouldn't happen with a catch-all ws/other) — emit
+      // one char as plain text to make progress.
+      out += escapeHtml(code[pos]);
+      pos += 1;
+    }
+  }
+  return out;
+}
+
+export function supportedLangs(): string[] {
+  return Object.keys(LANGS);
+}