flux-md 0.11.0 → 0.13.0

package/src/styles.css

@@ -0,0 +1,182 @@
+/*
+ * flux-md — optional default theme.
+ *
+ *   import "flux-md/styles.css";
+ *
+ * Opt-in: import it for good-looking output out of the box (including the
+ * built-in syntax highlighter's colors); skip it to bring your own CSS — the
+ * rendered HTML is identical either way. Everything is scoped to `.flux-md`
+ * (the renderer's root) and driven by CSS custom properties, so you re-theme by
+ * overriding a few `--flux-*` vars rather than rewriting selectors.
+ *
+ * Light by default; dark automatically via `prefers-color-scheme`. Force a mode
+ * with `<div class="flux-md flux-dark">` or `flux-light`.
+ */
+
+.flux-md {
+  /* surfaces + text (light) */
+  --flux-fg: #1f2328;
+  --flux-fg-muted: #59636e;
+  --flux-fg-faint: #818b98;
+  --flux-border: #d1d9e0;
+  --flux-bg-code: #f6f8fa;
+  --flux-bg-inline: rgba(129, 139, 152, 0.16);
+  --flux-bg-quote: rgba(129, 139, 152, 0.08);
+  --flux-accent: #0969da;
+  /* syntax tokens (light) */
+  --flux-t-kw: #cf222e;
+  --flux-t-str: #0a3069;
+  --flux-t-num: #0550ae;
+  --flux-t-com: #59636e;
+  --flux-t-fn: #6639ba;
+  --flux-t-ty: #953800;
+  --flux-t-mac: #1f6feb;
+  --flux-t-attr: #116329;
+  --flux-t-tag: #116329;
+  --flux-t-var: #953800;
+  --flux-t-pun: var(--flux-fg);
+  /* sizing */
+  --flux-radius: 6px;
+  --flux-gap: 16px;
+
+  color: var(--flux-fg);
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  line-height: 1.6;
+  font-size: 1rem;
+  word-wrap: break-word;
+  overflow-wrap: anywhere;
+}
+
+/* Dark — automatic, and as an explicit `.flux-dark` escape hatch. */
+@media (prefers-color-scheme: dark) {
+  .flux-md:not(.flux-light) {
+    --flux-fg: #e6edf3;
+    --flux-fg-muted: #9198a1;
+    --flux-fg-faint: #6e7681;
+    --flux-border: #3d444d;
+    --flux-bg-code: #151b23;
+    --flux-bg-inline: rgba(101, 108, 118, 0.2);
+    --flux-bg-quote: rgba(101, 108, 118, 0.1);
+    --flux-accent: #4493f8;
+    --flux-t-kw: #ff7b72;
+    --flux-t-str: #a5d6ff;
+    --flux-t-num: #79c0ff;
+    --flux-t-com: #8b949e;
+    --flux-t-fn: #d2a8ff;
+    --flux-t-ty: #ffa657;
+    --flux-t-mac: #79c0ff;
+    --flux-t-attr: #7ee787;
+    --flux-t-tag: #7ee787;
+    --flux-t-var: #ffa657;
+  }
+}
+.flux-md.flux-dark {
+  --flux-fg: #e6edf3;
+  --flux-fg-muted: #9198a1;
+  --flux-fg-faint: #6e7681;
+  --flux-border: #3d444d;
+  --flux-bg-code: #151b23;
+  --flux-bg-inline: rgba(101, 108, 118, 0.2);
+  --flux-bg-quote: rgba(101, 108, 118, 0.1);
+  --flux-accent: #4493f8;
+  --flux-t-kw: #ff7b72;
+  --flux-t-str: #a5d6ff;
+  --flux-t-num: #79c0ff;
+  --flux-t-com: #8b949e;
+  --flux-t-fn: #d2a8ff;
+  --flux-t-ty: #ffa657;
+  --flux-t-mac: #79c0ff;
+  --flux-t-attr: #7ee787;
+  --flux-t-tag: #7ee787;
+  --flux-t-var: #ffa657;
+}
+
+/* ---- block rhythm ---------------------------------------------------------- */
+.flux-md > * { margin: 0 0 var(--flux-gap) 0; }
+.flux-md > *:last-child { margin-bottom: 0; }
+
+/* ---- headings -------------------------------------------------------------- */
+.flux-md h1, .flux-md h2, .flux-md h3,
+.flux-md h4, .flux-md h5, .flux-md h6 {
+  font-weight: 600;
+  line-height: 1.25;
+  margin: 24px 0 var(--flux-gap);
+}
+.flux-md h1 { font-size: 2em; padding-bottom: 0.3em; border-bottom: 1px solid var(--flux-border); }
+.flux-md h2 { font-size: 1.5em; padding-bottom: 0.3em; border-bottom: 1px solid var(--flux-border); }
+.flux-md h3 { font-size: 1.25em; }
+.flux-md h4 { font-size: 1em; }
+.flux-md h5 { font-size: 0.875em; }
+.flux-md h6 { font-size: 0.85em; color: var(--flux-fg-muted); }
+.flux-md > h1:first-child, .flux-md > h2:first-child, .flux-md > h3:first-child { margin-top: 0; }
+
+/* ---- inline ---------------------------------------------------------------- */
+.flux-md a { color: var(--flux-accent); text-decoration: none; }
+.flux-md a:hover { text-decoration: underline; }
+.flux-md strong { font-weight: 600; }
+.flux-md em { font-style: italic; }
+.flux-md del { color: var(--flux-fg-muted); }
+.flux-md img { max-width: 100%; height: auto; }
+
+/* ---- lists ----------------------------------------------------------------- */
+.flux-md ul, .flux-md ol { padding-left: 2em; }
+.flux-md li { margin: 0.25em 0; }
+.flux-md li > ul, .flux-md li > ol { margin: 0.25em 0; }
+.flux-md li::marker { color: var(--flux-fg-faint); }
+.flux-md input[type="checkbox"] { margin: 0 0.4em 0 0; }
+
+/* ---- blockquote + alerts --------------------------------------------------- */
+.flux-md blockquote {
+  margin: 0 0 var(--flux-gap);
+  padding: 0.4em 1em;
+  color: var(--flux-fg-muted);
+  border-left: 0.25em solid var(--flux-border);
+  background: var(--flux-bg-quote);
+}
+.flux-md blockquote > :last-child { margin-bottom: 0; }
+
+/* ---- tables ---------------------------------------------------------------- */
+.flux-md table { border-collapse: collapse; width: 100%; display: block; overflow-x: auto; }
+.flux-md th, .flux-md td { padding: 6px 13px; border: 1px solid var(--flux-border); }
+.flux-md th { font-weight: 600; background: var(--flux-bg-code); }
+.flux-md tr:nth-child(2n) td { background: var(--flux-bg-quote); }
+
+/* ---- code ------------------------------------------------------------------ */
+.flux-md code, .flux-md pre {
+  font-family: ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace;
+  font-size: 0.9em;
+}
+.flux-md :not(pre) > code {
+  padding: 0.2em 0.4em;
+  border-radius: var(--flux-radius);
+  background: var(--flux-bg-inline);
+}
+.flux-md pre {
+  padding: 14px 16px;
+  overflow-x: auto;
+  border-radius: var(--flux-radius);
+  background: var(--flux-bg-code);
+  line-height: 1.5;
+}
+.flux-md pre code { padding: 0; background: none; border: 0; }
+
+/* ---- rule ------------------------------------------------------------------ */
+.flux-md hr { height: 1px; border: 0; background: var(--flux-border); margin: 24px 0; }
+
+/* ---- syntax highlighter (the built-in `highlight()` token spans) ----------- */
+.flux-md .t-kw   { color: var(--flux-t-kw); }
+.flux-md .t-str,
+.flux-md .t-rx   { color: var(--flux-t-str); }
+.flux-md .t-num,
+.flux-md .t-lt   { color: var(--flux-t-num); }
+.flux-md .t-com  { color: var(--flux-t-com); font-style: italic; }
+.flux-md .t-fn   { color: var(--flux-t-fn); }
+.flux-md .t-ty   { color: var(--flux-t-ty); }
+.flux-md .t-mac,
+.flux-md .t-dec  { color: var(--flux-t-mac); }
+.flux-md .t-attr,
+.flux-md .t-sel  { color: var(--flux-t-attr); }
+.flux-md .t-tag  { color: var(--flux-t-tag); }
+.flux-md .t-var  { color: var(--flux-t-var); }
+.flux-md .t-pun  { color: var(--flux-t-pun); }
+.flux-md .t-txt  { color: inherit; }

package/src/svelte.ts

@@ -1,5 +1,6 @@
 import type { ActionReturn } from "svelte/action";
-import type { FluxClient } from "./client";
+import { FluxClient } from "./client";
+import type { ParserConfig } from "./types-core";
 import { mountFluxMarkdown, type DomComponents, type MountOptions } from "./dom";
 
 /**
@@ -53,3 +54,101 @@ export function fluxMarkdown(
     },
   };
 }
+
+/**
+ * Controlled-string sibling of {@link fluxMarkdown}: instead of taking a
+ * caller-owned client, this action OWNS a single {@link FluxClient} (constructed
+ * from `config`) and drives it from a CONTROLLED full string — the bridge for
+ * Svelte UIs that hold a streaming message as one growing `content` prop rather
+ * than feeding the client by hand. Each update passes the whole document-so-far
+ * and {@link FluxClient.setContent} diffs it: a prefix-extension appends only the
+ * delta; any divergence resets and reparses.
+ *
+ * ```svelte
+ * <div use:fluxMarkdownString={{ content, streaming: !done }} />
+ * ```
+ *
+ * Pass `streaming: false` once the content is final to finalize the stream and
+ * commit its last block (only then does a finished code fence highlight + show
+ * its copy button). When `streaming` is omitted or `true` the stream is left
+ * OPEN — right for a still-growing string, but a *complete static* string keeps
+ * its last block in the streaming state until you pass `{ streaming: false }`.
+ * (Inferring "done" from an absent flag is deliberately avoided — it would
+ * re-finalize on every token and trip an O(n²) reparse.)
+ *
+ * SSR-safe by construction: a Svelte action runs ONLY in the browser, and the
+ * `FluxClient` constructor is worker-free — the first worker is spawned lazily by
+ * `setContent`, which only runs here (never during a server render).
+ *
+ * Lifecycle differs from {@link fluxMarkdown}: this action constructs the client
+ * once (a later `config` change is ignored, like a created-once instance) and
+ * `destroy()`s it on teardown — it OWNS the client. The mount-option reconcile
+ * (`components`/`sanitize`/`virtualize`/`stickToBottom`) matches `fluxMarkdown`,
+ * but the remount reuses the SAME client so its `setContent` diff baseline
+ * survives.
+ */
+export interface FluxMarkdownStringParams extends Omit<FluxMarkdownParams, "client"> {
+  /** The full document-so-far. Diffed against the prior value on every update. */
+  content: string;
+  /** Leave the stream open while true/omitted; `false` finalizes (commits the tail). */
+  streaming?: boolean;
+  /** Per-stream parser flags. Applied once at construction; later changes are ignored. */
+  config?: ParserConfig;
+}
+
+/** Strip the action-only inputs (`content`/`streaming`/`config`), leaving the
+ *  fields {@link mountFluxMarkdown} reads — so they never leak into the mount. */
+function mountOptionsOf(p: FluxMarkdownStringParams): Omit<FluxMarkdownParams, "client"> {
+  const { content: _c, streaming: _s, config: _cfg, ...rest } = p;
+  void _c;
+  void _s;
+  void _cfg;
+  return rest;
+}
+
+export function fluxMarkdownString(
+  node: HTMLElement,
+  params: FluxMarkdownStringParams,
+): ActionReturn<FluxMarkdownStringParams> {
+  // This action OWNS the client — construct it once from `config` (a later
+  // `config` change is ignored, mirroring the created-once React hook). The
+  // content/streaming diff baseline lives INSIDE the client (setContent), so we
+  // keep no outer copy; only the mount-option fields are tracked for the remount
+  // comparison.
+  let options = mountOptionsOf(params);
+  const client = new FluxClient({ config: params.config });
+  let handle = mountFluxMarkdown(client, node, options as MountOptions);
+  // First worker-bound op: spawns the lazy Worker — browser-only, never SSR.
+  client.setContent(params.content, { done: params.streaming === false });
+
+  return {
+    update(next: FluxMarkdownStringParams) {
+      // Content/streaming are the primary changing inputs, so reconcile them on
+      // EVERY update — setContent self-no-ops when the string is unchanged, so
+      // this is cheap. (Unlike fluxMarkdown, we cannot early-return: that would
+      // swallow content updates.)
+      client.setContent(next.content, { done: next.streaming === false });
+
+      // Then reconcile mount options exactly like fluxMarkdown: remount only when
+      // a field the renderer reads actually changed identity, and reuse the SAME
+      // client so its setContent diff baseline (lastContent) survives the remount.
+      if (
+        next.components === options.components &&
+        next.sanitize === options.sanitize &&
+        next.virtualize === options.virtualize &&
+        next.stickToBottom === options.stickToBottom
+      ) {
+        return;
+      }
+      handle.destroy();
+      options = mountOptionsOf(next);
+      handle = mountFluxMarkdown(client, node, options as MountOptions);
+    },
+    destroy() {
+      // This action OWNS the client (unlike fluxMarkdown) — tear down the mount
+      // AND destroy the client so its pool slot is freed.
+      handle.destroy();
+      client.destroy();
+    },
+  };
+}

package/src/vue.ts

@@ -1,6 +1,7 @@
 import { defineComponent, h, onMounted, onUnmounted, ref, watch } from "vue";
 import type { PropType, Ref } from "vue";
-import type { FluxClient } from "./client";
+import { FluxClient } from "./client";
+import type { ParserConfig } from "./types-core";
 import { mountFluxMarkdown, type DomComponents, type MountHandle, type MountOptions } from "./dom";
 
 /**
@@ -98,3 +99,59 @@ export const FluxMarkdown = defineComponent({
     return () => h("div", { ref: container });
   },
 });
+
+/**
+ * Own a {@link FluxClient} driven by a CONTROLLED full string — the Vue analogue
+ * of React's `useFluxMarkdownString`, for UIs that hold a streaming message as a
+ * single growing string (a `ref`/computed) rather than as a stream. Pass a getter
+ * for the whole document-so-far; on every change {@link FluxClient.setContent}
+ * diffs it and does the minimal work (prefix-extension appends only the delta;
+ * any divergence resets and reparses).
+ *
+ * Pass `streaming: false` (via `getOptions`) once the content is final to
+ * finalize the stream and commit its last block. If `streaming` is omitted or
+ * `true` the stream is left OPEN — inferring "done" from an absent flag is
+ * deliberately avoided (it would re-finalize on every token for callers that
+ * grow the string without the flag — an O(n²) reparse trap). `config` is read
+ * once at construction and is immutable thereafter, so it is not a change
+ * trigger.
+ *
+ * **Returns the owned client** — a deliberate divergence from {@link useFluxMarkdown}
+ * (which returns `{ container }`). Mirroring React's hook, this composes with the
+ * component as `<FluxMarkdown :client="client" />` (and lets you read
+ * `outline()` / `getMetrics()` off it). The client is created in the composable
+ * body (constructor is worker-free → SSR-safe) and destroyed on unmount.
+ *
+ * SSR-safety: `setContent` is what spawns a Worker (via `append`), so it is
+ * called ONLY in `onMounted` and a NON-immediate `watch` — never during the
+ * server render path (`setup` constructs the client but neither lifecycle hook
+ * nor the non-immediate watch fires on the server).
+ */
+export function useFluxMarkdownString(
+  getContent: () => string,
+  getOptions?: () => { config?: ParserConfig; streaming?: boolean },
+): FluxClient {
+  // One client per composable instance. Constructor is worker-free, so this is
+  // safe to run in setup() during SSR; config is read once and is immutable.
+  const client = new FluxClient({ config: getOptions?.()?.config });
+
+  // Reconcile the parser to the controlled string. setContent diffs internally,
+  // so this is correct whether `content` grows by a token or is swapped wholesale.
+  // `streaming === false` (never `!streaming`) → only an explicit false finalizes;
+  // an absent/true flag leaves the stream open.
+  const apply = (): void => {
+    client.setContent(getContent(), { done: getOptions?.()?.streaming === false });
+  };
+
+  // Initial feed + every change. NOT { immediate: true }: an immediate watch runs
+  // in setup() — i.e. during SSR — and would spawn a Worker on the server. The
+  // initial feed is onMounted (client-only); the watch covers later changes.
+  onMounted(apply);
+  watch([getContent, () => getOptions?.()?.streaming], apply);
+
+  // This composable OWNS the client (unlike useFluxMarkdown, which takes one), so
+  // it destroys it here. Vue auto-stops the watcher on unmount.
+  onUnmounted(() => client.destroy());
+
+  return client;
+}

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

package/src/worker-core.ts

@@ -0,0 +1,174 @@
+import type { FromWorker, ParserConfig, Patch, ToWorker } from "./types-core";
+
+/** The slice of `FluxParser` the worker drives — narrowed to an interface so the
+ *  message/readiness state machine is unit-testable with a fake parser, no WASM.
+ *  (Same testability move as {@link FluxPool} taking an injected worker factory.) */
+export interface ParserLike {
+  append(chunk: string): Patch;
+  finalize(): Patch;
+  free(): void;
+  retainedBytes(): number;
+}
+
+/** Dependencies injected into {@link WorkerCore}, isolating it from the worker
+ *  globals (`self`, `queueMicrotask`) and the WASM module so it can be tested. */
+export interface WorkerCoreDeps {
+  /** Create + configure a parser for a stream (prod: `new FluxParser()` + setX). */
+  makeParser(config: ParserConfig | undefined): ParserLike;
+  /** Post a message to the main thread (prod: `self.postMessage`). */
+  post(msg: FromWorker): void;
+  /** Current WASM heap size in bytes, reported on each patch (0 if unknown). */
+  memBytes(): number;
+  /** Defer a flush to a future microtask (prod: `queueMicrotask`). */
+  schedule(fn: () => void): void;
+}
+
+/**
+ * The worker's message reducer + WASM-readiness gate, extracted from the worker
+ * shell so its trickiest invariant is testable without a real Worker or WASM.
+ *
+ * **The invariant:** WASM `init()` is async, and the client does NOT wait for
+ * readiness before appending — so chunks can arrive first. A parser must never
+ * be constructed before init resolves (`new FluxParser()` against an
+ * uninitialized module throws `fluxparser_new of undefined` and silently drops
+ * that chunk). So while `ready` is false, appends only accumulate in `pending`
+ * (scheduleFlush is a no-op) and `finalize` is deferred; {@link markReady}
+ * drains both — appends first (creating each parser + applying buffered text),
+ * then any deferred finalize — once init has completed.
+ */
+export class WorkerCore {
+  // One parser per stream id; WASM is loaded once and shared by all of them.
+  private parsers = new Map<number, ParserLike>();
+  private config = new Map<number, ParserConfig>();
+  private pending = new Map<number, string>();
+  private totalAppended = new Map<number, number>();
+  private finalizePending = new Set<number>();
+  private flushScheduled = false;
+  private ready = false;
+
+  constructor(private deps: WorkerCoreDeps) {}
+
+  /** Handle one message from the main thread (append/finalize/reset/dispose). */
+  handle(msg: ToWorker): void {
+    const id = msg.streamId;
+    // Stash any per-stream config carried on the first message (FIFO guarantees
+    // it arrives before the parser is created in flush/finalize).
+    if ((msg.type === "append" || msg.type === "finalize") && msg.config) {
+      this.config.set(id, msg.config);
+    }
+    switch (msg.type) {
+      case "append":
+        this.pending.set(id, (this.pending.get(id) ?? "") + msg.chunk);
+        this.scheduleFlush();
+        break;
+      case "finalize":
+        // Before WASM is ready, defer: markReady() finalizes it after init (the
+        // buffered input is drained first). Otherwise finalize now.
+        if (!this.ready) this.finalizePending.add(id);
+        else this.doFinalize(id);
+        break;
+      case "reset":
+        // Free and recreate lazily on the next append — same stream id, **same
+        // config** (kept). The client resets its local state synchronously.
+        this.parsers.get(id)?.free();
+        this.parsers.delete(id);
+        this.pending.delete(id);
+        this.finalizePending.delete(id); // a reset cancels a not-yet-run early finalize
+        this.totalAppended.delete(id);
+        break;
+      case "dispose":
+        this.dispose(id);
+        break;
+    }
+  }
+
+  /** Called once WASM init resolves: open the gate and drain what was buffered. */
+  markReady(): void {
+    this.ready = true;
+    this.deps.post({ type: "ready" });
+    // Order matters: flush appends first (creating each parser + applying
+    // buffered text), then finalize any stream that already requested it.
+    if (this.pending.size > 0) this.flush();
+    if (this.finalizePending.size > 0) {
+      for (const id of this.finalizePending) this.doFinalize(id);
+      this.finalizePending.clear();
+    }
+  }
+
+  private getOrCreate(streamId: number): ParserLike {
+    let p = this.parsers.get(streamId);
+    if (!p) {
+      p = this.deps.makeParser(this.config.get(streamId));
+      this.parsers.set(streamId, p);
+    }
+    return p;
+  }
+
+  private dispose(streamId: number): void {
+    this.parsers.get(streamId)?.free();
+    this.parsers.delete(streamId);
+    this.config.delete(streamId);
+    this.pending.delete(streamId);
+    this.finalizePending.delete(streamId);
+    this.totalAppended.delete(streamId);
+  }
+
+  private emitPatch(streamId: number, patch: Patch, parser: ParserLike, parseMicros: number): void {
+    this.deps.post({
+      type: "patch",
+      streamId,
+      patch,
+      appendedBytes: this.totalAppended.get(streamId) ?? 0,
+      parseMicros,
+      retainedBytes: parser.retainedBytes(),
+      wasmMemoryBytes: this.deps.memBytes(),
+    });
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushScheduled || !this.ready) return; // before ready, input just accumulates in `pending`
+    this.flushScheduled = true;
+    this.deps.schedule(() => this.flush());
+  }
+
+  private flush(): void {
+    this.flushScheduled = false;
+    if (!this.ready || this.pending.size === 0) return; // buffer stays put until WASM is ready
+    // Process every stream with buffered input this microtask.
+    for (const [streamId, chunk] of this.pending) {
+      this.pending.delete(streamId);
+      if (chunk.length === 0) continue;
+      const t0 = performance.now();
+      try {
+        // getOrCreate (→ makeParser) is inside the try: with `ready` gating it
+        // can't hit the init race, but any other construction failure becomes a
+        // posted error rather than an uncaught exception that kills the worker.
+        const parser = this.getOrCreate(streamId);
+        const patch = parser.append(chunk) as Patch;
+        const dt = (performance.now() - t0) * 1000;
+        this.totalAppended.set(streamId, (this.totalAppended.get(streamId) ?? 0) + chunk.length);
+        this.emitPatch(streamId, patch, parser, dt);
+      } catch (e: unknown) {
+        this.deps.post({ type: "error", streamId, message: e instanceof Error ? e.message : String(e) });
+      }
+    }
+  }
+
+  // Drain a stream's buffered input (if any), then finalize its parser. Shared by
+  // the `finalize` message path and markReady()'s post-ready drain.
+  private doFinalize(streamId: number): void {
+    const buffered = this.pending.get(streamId);
+    this.pending.delete(streamId);
+    try {
+      const parser = this.getOrCreate(streamId);
+      if (buffered && buffered.length > 0) {
+        parser.append(buffered);
+        this.totalAppended.set(streamId, (this.totalAppended.get(streamId) ?? 0) + buffered.length);
+      }
+      const patch = parser.finalize() as Patch;
+      this.emitPatch(streamId, patch, parser, 0);
+    } catch (e: unknown) {
+      this.deps.post({ type: "error", streamId, message: e instanceof Error ? e.message : String(e) });
+    }
+  }
+}