flux-md 0.16.2 → 0.18.0

package/src/renderers/CodeBlock.tsx

@@ -1,116 +0,0 @@
-import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { highlight } from "../hi";
-import { extractLang } from "../block-props";
-
-/**
- * Deferred-highlighting code block. Open (streaming) blocks render plain;
- * the moment the parser commits the block (open=false), we run our in-house
- * tokenizer on the source and swap in highlighted HTML. Highlighting is
- * memoized on html identity so closed blocks never re-tokenize.
- */
-
-function decodeText(html: string): string {
-  const m = html.match(/<pre><code[^>]*>([\s\S]*?)<\/code><\/pre>/);
-  if (!m) return "";
-  return m[1]
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&amp;/g, "&");
-}
-
-
-interface Props {
-  html: string;
-  open: boolean;
-}
-
-function CodeBlockImpl({ html, open }: Props) {
-  const lang = extractLang(html) || "text";
-  // Decode once: highlighter and copy handler share the same source.
-  const text = useMemo(() => (open ? "" : decodeText(html)), [html, open]);
-  const highlighted = useMemo(() => {
-    if (!text) return null;
-    return highlight(text, lang);
-  }, [text, lang]);
-
-  const [copied, setCopied] = useState(false);
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Reset "Copied" if the block re-opens or its content changes underneath us.
-  useEffect(() => {
-    if (open) setCopied(false);
-  }, [open, html]);
-
-  useEffect(() => {
-    return () => {
-      if (timerRef.current !== null) clearTimeout(timerRef.current);
-    };
-  }, []);
-
-  const onCopy = useCallback(() => {
-    const write = (typeof navigator !== "undefined" && navigator.clipboard && navigator.clipboard.writeText)
-      ? navigator.clipboard.writeText.bind(navigator.clipboard)
-      : null;
-    if (!write || !text) return;
-    write(text).then(
-      () => {
-        setCopied(true);
-        if (timerRef.current !== null) clearTimeout(timerRef.current);
-        timerRef.current = setTimeout(() => setCopied(false), 1500);
-      },
-      // Permission denied / blocked: stay silent, leave button usable.
-      () => {},
-    );
-  }, [text]);
-
-  return (
-    <div className={"flux-code-block" + (open ? " flux-streaming" : "")}>
-      <div className="flux-code-header">
-        <span className="flux-code-lang">{lang}</span>
-        {open ? (
-          <span className="flux-code-streaming-pill">streaming</span>
-        ) : (
-          <button
-            type="button"
-            className="flux-code-copy"
-            onClick={onCopy}
-            aria-label={copied ? "Copied" : "Copy code"}
-            aria-live="polite"
-          >
-            {copied ? (
-              <>
-                <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
-                  <path d="M20 6 9 17l-5-5" />
-                </svg>
-                <span>Copied</span>
-              </>
-            ) : (
-              <>
-                <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
-                  <rect x="9" y="9" width="11" height="11" rx="2" />
-                  <path d="M5 15V5a2 2 0 0 1 2-2h10" />
-                </svg>
-                <span>Copy</span>
-              </>
-            )}
-          </button>
-        )}
-      </div>
-      <div className="flux-code-body">
-        {highlighted ? (
-          // tabIndex=0 + role/label so keyboard users can scroll long code and
-          // screen readers announce the region with its language.
-          <pre tabIndex={0} role="region" aria-label={`${lang} code`}>
-            <code dangerouslySetInnerHTML={{ __html: highlighted }} />
-          </pre>
-        ) : (
-          <div tabIndex={0} role="region" aria-label={`${lang} code`} dangerouslySetInnerHTML={{ __html: html }} />
-        )}
-      </div>
-    </div>
-  );
-}
-
-export const CodeBlock = memo(CodeBlockImpl);

package/src/renderers/Math.tsx

@@ -1,28 +0,0 @@
-import { memo } from "react";
-
-/**
- * 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 {
-  html: string;
-  open: boolean;
-}
-
-function MathImpl({ html, open }: Props) {
-  return (
-    <div className={"flux-math-block" + (open ? " flux-streaming" : "")}>
-      <div className="flux-math-header">
-        <span className="flux-math-lang">math</span>
-        {open && <span className="flux-code-streaming-pill">streaming</span>}
-      </div>
-      <div className="flux-math-body" dangerouslySetInnerHTML={{ __html: html }} />
-    </div>
-  );
-}
-
-export const MathBlock = memo(MathImpl);

package/src/renderers/Mermaid.tsx

@@ -1,27 +0,0 @@
-import { memo } from "react";
-
-/**
- * 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 {
-  html: string;
-  open: boolean;
-}
-
-function MermaidImpl({ html, open }: Props) {
-  return (
-    <div className={"flux-mermaid-block" + (open ? " flux-streaming" : "")}>
-      <div className="flux-mermaid-header">
-        <span className="flux-mermaid-lang">mermaid</span>
-        {open && <span className="flux-code-streaming-pill">streaming</span>}
-      </div>
-      <div className="flux-mermaid-body" dangerouslySetInnerHTML={{ __html: html }} />
-    </div>
-  );
-}
-
-export const Mermaid = memo(MermaidImpl);

package/src/server.tsx

@@ -1,221 +0,0 @@
-import { createElement, type ReactNode } from "react";
-import initWasmAsync, { FluxParser, initSync } from "./wasm/flux_md_core.js";
-import { htmlToReact } from "./html-to-react";
-import { blockKindProps } from "./react";
-import type { Block, Components, ParserConfig } from "./types";
-
-/**
- * Synchronous, worker-free server / static rendering for flux-md.
- *
- * The browser path runs the Rust→WASM core in a Web Worker, but the very same
- * `FluxParser` is a plain synchronous class — so on the server (Node, RSC, a
- * build step) you can parse a finished markdown string with no worker and no
- * async ceremony:
- *
- * ```ts
- * import { initFlux, renderToString } from "flux-md/server";
- * await initFlux();                       // once, at startup
- * const html = renderToString(markdown);  // sync, no worker
- * ```
- *
- * For React server rendering (RSC, static generation, SSR) use {@link
- * FluxMarkdownStatic} — a hookless, RSC-safe component with the same `components`
- * overrides. It targets **render-once** contexts; the streaming, interactive
- * `<FluxMarkdown>` (client-side code highlighting, Mermaid, live updates) is a
- * separate component. If you SSR-then-hydrate, use the *same* component on both
- * sides.
- */
-
-let ready = false;
-
-/** Has the sync WASM core been initialized in this process? */
-export function isFluxReady(): boolean {
-  return ready;
-}
-
-/** Initialize the sync core from compiled WASM bytes (or a `WebAssembly.Module`).
- *  Idempotent. Use on runtimes without a filesystem (edge) or to control exactly
- *  when init happens; otherwise {@link initFlux} auto-loads the co-located WASM. */
-export function initFluxSync(wasm: BufferSource | WebAssembly.Module): void {
-  if (ready) return;
-  initSync({ module: wasm });
-  ready = true;
-}
-
-let initPromise: Promise<void> | null = null;
-
-/** Initialize the sync core once. In Node it reads the package's co-located
- *  `.wasm` off disk (Node's `fetch` can't load `file://`); on the web it fetches
- *  the bundler-resolved asset URL. Pass `{ wasm }` to supply bytes yourself
- *  (edge runtimes). Safe to call repeatedly / concurrently. */
-export function initFlux(opts?: { wasm?: BufferSource | WebAssembly.Module }): Promise<void> {
-  if (ready) return Promise.resolve();
-  if (opts?.wasm) {
-    initFluxSync(opts.wasm);
-    return Promise.resolve();
-  }
-  if (!initPromise) {
-    initPromise = (async () => {
-      const wasmUrl = new URL("./wasm/flux_md_core_bg.wasm", import.meta.url);
-      if (wasmUrl.protocol === "file:") {
-        // Node: read the bytes (Node's fetch can't load file://). The literal
-        // `node:` specifier is externalized by bundlers, so node:fs never reaches
-        // a web bundle (this branch is also file:-only, never true in browsers).
-        // @ts-ignore — no @types/node in this package; node:fs/promises is a builtin.
-        const { readFile } = await import("node:fs/promises");
-        initFluxSync(await readFile(wasmUrl));
-      } else {
-        await initWasmAsync({ module_or_path: wasmUrl });
-        ready = true;
-      }
-    })().catch((err) => {
-      // Drop the cached rejected promise so a transient failure (e.g. a flaky
-      // .wasm fetch on the web path) can be retried by the next initFlux()
-      // instead of poisoning every subsequent call until a process restart.
-      initPromise = null;
-      throw err;
-    });
-  }
-  return initPromise;
-}
-
-// Configure a one-shot parser exactly as the worker does, so server output is
-// byte-identical to the streamed/browser output (defaults: autolinks + alerts
-// on, raw HTML escaped, footnotes/math off).
-function makeParser(config?: ParserConfig): FluxParser {
-  const p = new FluxParser();
-  p.setGfmAutolinks(config?.gfmAutolinks ?? true);
-  p.setGfmAlerts(config?.gfmAlerts ?? true);
-  p.setGfmFootnotes(config?.gfmFootnotes ?? false);
-  p.setGfmMath(config?.gfmMath ?? false);
-  p.setDirAuto(config?.dirAuto ?? false);
-  p.setA11y(config?.a11y ?? false);
-  p.setUnsafeHtml(config?.unsafeHtml ?? false);
-  p.setComponentTags(config?.componentTags ?? []);
-  p.setInlineComponentTags(config?.inlineComponentTags ?? []);
-  // Engage the safe raw-HTML sanitizer when either list is provided (even []).
-  p.setHtmlSanitize(
-    config?.htmlAllowlist !== undefined || config?.dropHtmlTags !== undefined,
-    config?.htmlAllowlist ?? [],
-    config?.dropHtmlTags ?? [],
-  );
-  p.setBlockData(config?.blockData ?? false);
-  return p;
-}
-
-function requireReady(): void {
-  if (!ready) {
-    throw new Error(
-      "flux-md/server: WASM not initialized. Call `await initFlux()` (or `initFluxSync(bytes)`) once before rendering.",
-    );
-  }
-}
-
-/**
- * Parse a complete markdown string to its block array synchronously (committed +
- * any trailing block, in document order). Requires {@link initFlux} to have run.
- */
-export function parseToBlocks(markdown: string, opts?: { config?: ParserConfig }): Block[] {
-  requireReady();
-  const p = makeParser(opts?.config);
-  try {
-    p.append(markdown);
-    p.finalize();
-    return p.allBlocks() as Block[];
-  } finally {
-    p.free();
-  }
-}
-
-/**
- * Render a complete markdown string to an HTML string synchronously — no worker,
- * no React. The concatenated per-block HTML (XSS-safe with `unsafeHtml` off).
- * For component dispatch / a `<FluxMarkdown>`-matching React tree, use
- * {@link FluxMarkdownStatic} with your framework's server renderer instead.
- */
-export function renderToString(markdown: string, opts?: { config?: ParserConfig }): string {
-  return parseToBlocks(markdown, opts)
-    .map((b) => b.html)
-    .join("");
-}
-
-// Hookless block renderer (RSC-safe): mirrors the client renderer's dispatch
-// (block-kind overrides, a Component block dispatched by tag, tag-level overrides
-// via htmlToReact) but uses no hooks and skips the client-only interactive
-// renderers (Mermaid; client-side code highlighting) — those activate on the
-// client after hydration. Kept in step with react.tsx's renderBlockContent.
-function renderStaticBlock(block: Block, components?: Components): ReactNode {
-  const kind = block.kind.type;
-  if (components) {
-    if (kind === "Component") {
-      const tag = (block.kind.data as { tag?: string } | undefined)?.tag;
-      const override = (tag && components[tag]) || components.Component;
-      if (override) return createElement(override, { key: block.id, ...blockKindProps(block, components) });
-    }
-    const blockOverride = components[kind];
-    if (blockOverride) return createElement(blockOverride, { key: block.id, ...blockKindProps(block, components) });
-  }
-  const className =
-    "flux-block flux-block-" +
-    kind.toLowerCase() +
-    (block.open ? " flux-open" : "") +
-    (block.speculative ? " flux-speculative" : "");
-  if (components) {
-    return createElement("div", { key: block.id, className }, htmlToReact(block.html, components));
-  }
-  return createElement("div", { key: block.id, className, dangerouslySetInnerHTML: { __html: block.html } });
-}
-
-interface FluxMarkdownStaticProps {
-  /** The complete markdown to render (server/static use is for finished content). */
-  content: string;
-  /** Parser config (same shape as the streaming client's). */
-  config?: ParserConfig;
-  /** Tag-level / block-kind / component-tag overrides (see {@link Components}). */
-  components?: Components;
-  /** Appended to the root's `className` (the `flux-md` class is always present). */
-  className?: string;
-  /** Set on the root element. */
-  id?: string;
-  /** Set on the root element (e.g. `"article"`). */
-  role?: string;
-  /** Make the root a live region (parity with `<FluxMarkdown>` if you hydrate). */
-  "aria-live"?: "off" | "polite" | "assertive";
-  /** Live-region atomicity; pair with `aria-live`. */
-  "aria-atomic"?: boolean;
-}
-
-/**
- * Synchronous, worker-free React rendering of finished markdown — a React Server
- * Component, or any one-shot SSR / static render. Emits the `flux-md` root +
- * per-block structure with the same `components` overrides (inline/block
- * component tags dispatch here too). Requires {@link initFlux} (or
- * {@link initFluxSync}) to have run. Uses no hooks (RSC-safe). A **render-once**
- * component: for live streaming, client-side code highlighting, or Mermaid use
- * the client `<FluxMarkdown>` instead (and if you SSR-then-hydrate, render the
- * *same* component on both sides).
- */
-export function FluxMarkdownStatic({
-  content,
-  config,
-  components,
-  className,
-  id,
-  role,
-  "aria-live": ariaLive,
-  "aria-atomic": ariaAtomic,
-}: FluxMarkdownStaticProps): ReactNode {
-  const blocks = parseToBlocks(content, { config });
-  const comps = components && Object.keys(components).length > 0 ? components : undefined;
-  return createElement(
-    "div",
-    {
-      className: className ? `flux-md ${className}` : "flux-md",
-      id,
-      role,
-      "aria-live": ariaLive,
-      "aria-atomic": ariaAtomic,
-    },
-    blocks.map((b) => renderStaticBlock(b, comps)),
-  );
-}

package/src/svelte.ts

@@ -1,179 +0,0 @@
-import type { ActionReturn } from "svelte/action";
-import { readable, type Readable } from "svelte/store";
-import { FluxClient } from "./client";
-import type { ParserConfig } from "./types-core";
-import { mountFluxMarkdown, tailOpenBlockId, type DomComponents, type MountOptions } from "./dom";
-
-/**
- * Svelte action that mounts a streaming {@link FluxClient} into the host node.
- * Plain `.ts` — no `.svelte` compile step — so `use:` works unchanged in
- * Svelte 4 and 5. The action owns only lifecycle: it mounts on creation and
- * tears the mount down on destroy. The caller keeps ownership of the client
- * (the worker/stream); the action never calls `client.destroy()`.
- *
- * ```svelte
- * <div use:fluxMarkdown={{ client, stickToBottom: true }} />
- * ```
- */
-export interface FluxMarkdownParams {
-  client: FluxClient;
-  components?: DomComponents;
-  sanitize?: (h: string) => string;
-  virtualize?: boolean;
-  stickToBottom?: boolean;
-}
-
-export function fluxMarkdown(
-  node: HTMLElement,
-  params: FluxMarkdownParams,
-): ActionReturn<FluxMarkdownParams> {
-  let { client, ...options } = params;
-  let handle = mountFluxMarkdown(client, node, options as MountOptions);
-
-  return {
-    update(next: FluxMarkdownParams) {
-      // Svelte fires update on every params change, even when nothing the mount
-      // depends on moved (a fresh object literal with identical field values).
-      // Remount only when an input the renderer reads actually changed identity;
-      // otherwise the live mount keeps streaming untouched.
-      if (
-        next.client === client &&
-        next.components === options.components &&
-        next.sanitize === options.sanitize &&
-        next.virtualize === options.virtualize &&
-        next.stickToBottom === options.stickToBottom
-      ) {
-        return;
-      }
-      handle.destroy();
-      ({ client, ...options } = next);
-      handle = mountFluxMarkdown(client, node, options as MountOptions);
-    },
-    destroy() {
-      // Only the mount is torn down. The caller owns the client.
-      handle.destroy();
-    },
-  };
-}
-
-/**
- * A fine-grained Svelte `Readable` store of the streaming **tail** block id — the
- * one block that may still re-render — driven by the client's own subscribe loop.
- * The store sets a new value only when the tail id changes, so a `$tail`
- * subscription or `derived(tail, …)` re-evaluates *only* for the tail, never for
- * the committed body. Subscribing renders nothing: {@link fluxMarkdown} draws the
- * document; this mirrors `MountHandle.openBlockId` through Svelte's primitive for
- * any extra tail-scoped work. The client subscription is owned by the store and
- * torn down when the last subscriber leaves (Svelte's `readable` stop fn).
- *
- * ```svelte
- * const tail = tailBlockId(client); // $tail is the open block id, or null
- * ```
- */
-export function tailBlockId(client: FluxClient): Readable<number | null> {
-  return readable<number | null>(tailOpenBlockId(client.getSnapshot()), (set) => {
-    // `set` is identity-checked by Svelte's store, so pure tail-html growth that
-    // keeps the same open id never re-fires subscribers. The returned stop fn
-    // unsubscribes from the client when no one is listening.
-    const unsubscribe = client.subscribe(() => set(tailOpenBlockId(client.getSnapshot())));
-    return unsubscribe;
-  });
-}
-
-/**
- * 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();
-    },
-  };
-}