flux-md 0.5.1 → 0.6.0

package/src/types-core.ts

@@ -0,0 +1,138 @@
+export type BlockKindTag =
+  | "Paragraph"
+  | "Heading"
+  | "CodeBlock"
+  | "MathBlock"
+  | "Mermaid"
+  | "List"
+  | "Blockquote"
+  | "Alert"
+  | "Table"
+  | "Rule"
+  | "Html"
+  | "Component";
+
+export interface BlockKind {
+  type: BlockKindTag;
+  data?: unknown;
+}
+
+export interface Block {
+  id: number;
+  kind: BlockKind;
+  start: number;
+  end: number;
+  html: string;
+  open: boolean;
+  speculative: boolean;
+}
+
+export interface Patch {
+  newly_committed: Block[];
+  active: Block[];
+}
+
+/** Props passed to a block-kind override (e.g. `components.CodeBlock`). */
+export interface BlockComponentProps {
+  /** The full parsed block, including `kind` (with `kind.data`) and offsets. */
+  block: Block;
+  /** Rendered, XSS-safe HTML for this block. */
+  html: string;
+  /** True while the block is still streaming (its HTML may still change). */
+  open: boolean;
+  /** True if the block was closed speculatively and may yet be revised. */
+  speculative: boolean;
+  /** Decoded source text — present for `CodeBlock` / `MathBlock`. */
+  text?: string;
+  /** Info-string language — present for `CodeBlock` (from `kind.data.lang`). */
+  language?: string;
+  /** Component tag name — present for `Component` blocks (from `kind.data.tag`). */
+  tag?: string;
+  /**
+   * Sanitized attributes — present for `Component` blocks. The name-form depends
+   * on the consumer: the JSX renderer maps `class`→`className`/`for`→`htmlFor`
+   * so `{...attrs}` spreads cleanly onto an element; the DOM renderer keeps the
+   * literal HTML names (`class`/`for`) because it applies them via
+   * `setAttribute`. For `Component` blocks, `html` is the **inner**
+   * rendered-markdown HTML (not the `<tag>…</tag>` wrapper), so an override can
+   * wrap it itself.
+   */
+  attrs?: Record<string, string>;
+}
+
+/**
+ * Per-stream parser configuration. Omitted fields use the library defaults
+ * (autolinks + alerts on, raw HTML escaped, footnotes off) — so the default
+ * `new FluxClient()` behaves exactly as before. Config is applied when the
+ * stream's parser is created and is **immutable** for that stream's lifetime
+ * (a `reset()` keeps it; use a new client for different flags).
+ */
+export interface ParserConfig {
+  /** GFM extended autolinks (bare www./http(s)://ftp:// + emails). Default true. */
+  gfmAutolinks?: boolean;
+  /** GitHub alerts (`> [!NOTE]` → callouts). Default true. */
+  gfmAlerts?: boolean;
+  /** GFM footnotes (`[^1]` + `[^1]:` → footnote section). Default false. */
+  gfmFootnotes?: boolean;
+  /**
+   * Math: `$…$` / `\(…\)` inline and `$$…$$` / `\[…\]` display. Default false
+   * (so `$` in prose / currency stays literal). Emits KaTeX-ready markup
+   * (`<span class="math math-inline">` / `<div class="math math-display">`)
+   * carrying the LaTeX — bring your own KaTeX pass (flux-md stays zero-dep).
+   */
+  gfmMath?: boolean;
+  /**
+   * Emit `dir="auto"` on block-level text elements (`p`, `h1`–`h6`,
+   * `blockquote`, `ul`/`ol`/`li`, `table`) so the browser detects each block's
+   * direction independently — correct for documents mixing English with
+   * Arabic/Hebrew. Default false; code blocks always stay LTR. Recommended for
+   * apps that render RTL or mixed-direction content.
+   */
+  dirAuto?: boolean;
+  /** Pass raw HTML through unescaped. Default false. **Never enable for untrusted input.** */
+  unsafeHtml?: boolean;
+  /**
+   * Opt-in allowlist of custom component tag names (e.g. `["Thinking",
+   * "Callout"]`). A `<Tag>…</Tag>` whose name is listed renders as a component
+   * whose inner content is parsed as **markdown** — safely, without `unsafeHtml`
+   * (the tag is allowlisted and its attributes are sanitized: event handlers
+   * dropped, dangerous URL schemes neutralized). The block is dispatched by the
+   * renderer via `components[tag]` (or `components.Component`). Empty/omitted =
+   * off. Names match case-sensitively.
+   */
+  componentTags?: string[];
+}
+
+// Each message carries a `streamId` so one worker can multiplex many parsers
+// (the worker pool). `ready` is the exception — it's worker-level (WASM loaded),
+// not stream-level. The first message for a stream may carry `config`, applied
+// when that stream's parser is created.
+export type ToWorker =
+  | { type: "append"; streamId: number; chunk: string; config?: ParserConfig }
+  | { type: "finalize"; streamId: number; config?: ParserConfig }
+  | { type: "reset"; streamId: number }
+  | { type: "dispose"; streamId: number };
+
+export type FromWorker =
+  | { type: "ready" }
+  | {
+      type: "patch";
+      streamId: number;
+      patch: Patch;
+      appendedBytes: number;
+      parseMicros: number;
+      retainedBytes: number;
+      wasmMemoryBytes: number;
+    }
+  | { type: "error"; streamId: number; message: string };
+
+/**
+ * Minimal structural interface satisfied by the DOM `Worker`. Injectable so the
+ * pool's routing/lifecycle logic can be unit-tested with a fake worker — no
+ * real Worker or WASM required.
+ */
+export interface WorkerLike {
+  postMessage(msg: ToWorker): void;
+  addEventListener(type: "message", listener: (ev: { data: FromWorker }) => void): void;
+  terminate(): void;
+}

package/src/types-react.ts

@@ -0,0 +1,14 @@
+import type { ComponentType } from "react";
+
+/**
+ * Override map for {@link FluxMarkdown}. Keys are either lowercase HTML tag
+ * names (`table`, `a`, `code`, `h1`… — react-markdown style, applied inside a
+ * block's HTML) or capitalized block-kind names (`BlockKindTag`, e.g.
+ * `CodeBlock`, `Table` — replace the whole block renderer). Values are a React
+ * component or an HTML tag string.
+ *
+ * Tag-level components receive the element's parsed attributes (with
+ * `class`→`className`, `style` as an object) plus `children`. Block-kind
+ * components receive `BlockComponentProps`. There is no `node` prop.
+ */
+export type Components = Record<string, ComponentType<any> | string>;

package/src/types.ts

@@ -1,150 +1,7 @@
-export type BlockKindTag =
-  | "Paragraph"
-  | "Heading"
-  | "CodeBlock"
-  | "MathBlock"
-  | "Mermaid"
-  | "List"
-  | "Blockquote"
-  | "Alert"
-  | "Table"
-  | "Rule"
-  | "Html"
-  | "Component";
-
-export interface BlockKind {
-  type: BlockKindTag;
-  data?: unknown;
-}
-
-export interface Block {
-  id: number;
-  kind: BlockKind;
-  start: number;
-  end: number;
-  html: string;
-  open: boolean;
-  speculative: boolean;
-}
-
-export interface Patch {
-  newly_committed: Block[];
-  active: Block[];
-}
-
-import type { ComponentType } from "react";
-
-/**
- * Override map for {@link FluxMarkdown}. Keys are either lowercase HTML tag
- * names (`table`, `a`, `code`, `h1`… — react-markdown style, applied inside a
- * block's HTML) or capitalized block-kind names ({@link BlockKindTag}, e.g.
- * `CodeBlock`, `Table` — replace the whole block renderer). Values are a React
- * component or an HTML tag string.
- *
- * Tag-level components receive the element's parsed attributes (with
- * `class`→`className`, `style` as an object) plus `children`. Block-kind
- * components receive {@link BlockComponentProps}. There is no `node` prop.
- */
-export type Components = Record<string, ComponentType<any> | string>;
-
-/** Props passed to a block-kind override (e.g. `components.CodeBlock`). */
-export interface BlockComponentProps {
-  /** The full parsed block, including `kind` (with `kind.data`) and offsets. */
-  block: Block;
-  /** Rendered, XSS-safe HTML for this block. */
-  html: string;
-  /** True while the block is still streaming (its HTML may still change). */
-  open: boolean;
-  /** True if the block was closed speculatively and may yet be revised. */
-  speculative: boolean;
-  /** Decoded source text — present for `CodeBlock` / `MathBlock`. */
-  text?: string;
-  /** Info-string language — present for `CodeBlock` (from `kind.data.lang`). */
-  language?: string;
-  /** Component tag name — present for `Component` blocks (from `kind.data.tag`). */
-  tag?: string;
-  /**
-   * Sanitized attributes — present for `Component` blocks. Names are React-form
-   * (`class`→`className`, `for`→`htmlFor`) so `{...attrs}` spreads cleanly onto
-   * an element. For `Component` blocks, `html` is the **inner** rendered-markdown
-   * HTML (not the `<tag>…</tag>` wrapper), so an override can wrap it itself.
-   */
-  attrs?: Record<string, string>;
-}
-
-/**
- * Per-stream parser configuration. Omitted fields use the library defaults
- * (autolinks + alerts on, raw HTML escaped, footnotes off) — so the default
- * `new FluxClient()` behaves exactly as before. Config is applied when the
- * stream's parser is created and is **immutable** for that stream's lifetime
- * (a `reset()` keeps it; use a new client for different flags).
- */
-export interface ParserConfig {
-  /** GFM extended autolinks (bare www./http(s)://ftp:// + emails). Default true. */
-  gfmAutolinks?: boolean;
-  /** GitHub alerts (`> [!NOTE]` → callouts). Default true. */
-  gfmAlerts?: boolean;
-  /** GFM footnotes (`[^1]` + `[^1]:` → footnote section). Default false. */
-  gfmFootnotes?: boolean;
-  /**
-   * Math: `$…$` / `\(…\)` inline and `$$…$$` / `\[…\]` display. Default false
-   * (so `$` in prose / currency stays literal). Emits KaTeX-ready markup
-   * (`<span class="math math-inline">` / `<div class="math math-display">`)
-   * carrying the LaTeX — bring your own KaTeX pass (flux-md stays zero-dep).
-   */
-  gfmMath?: boolean;
-  /**
-   * Emit `dir="auto"` on block-level text elements (`p`, `h1`–`h6`,
-   * `blockquote`, `ul`/`ol`/`li`, `table`) so the browser detects each block's
-   * direction independently — correct for documents mixing English with
-   * Arabic/Hebrew. Default false; code blocks always stay LTR. Recommended for
-   * apps that render RTL or mixed-direction content.
-   */
-  dirAuto?: boolean;
-  /** Pass raw HTML through unescaped. Default false. **Never enable for untrusted input.** */
-  unsafeHtml?: boolean;
-  /**
-   * Opt-in allowlist of custom component tag names (e.g. `["Thinking",
-   * "Callout"]`). A `<Tag>…</Tag>` whose name is listed renders as a component
-   * whose inner content is parsed as **markdown** — safely, without `unsafeHtml`
-   * (the tag is allowlisted and its attributes are sanitized: event handlers
-   * dropped, dangerous URL schemes neutralized). The block is dispatched on the
-   * React side via `components[tag]` (or `components.Component`). Empty/omitted =
-   * off. Names match case-sensitively.
-   */
-  componentTags?: string[];
-}
-
-// Each message carries a `streamId` so one worker can multiplex many parsers
-// (the worker pool). `ready` is the exception — it's worker-level (WASM loaded),
-// not stream-level. The first message for a stream may carry `config`, applied
-// when that stream's parser is created.
-export type ToWorker =
-  | { type: "append"; streamId: number; chunk: string; config?: ParserConfig }
-  | { type: "finalize"; streamId: number; config?: ParserConfig }
-  | { type: "reset"; streamId: number }
-  | { type: "dispose"; streamId: number };
-
-export type FromWorker =
-  | { type: "ready" }
-  | {
-      type: "patch";
-      streamId: number;
-      patch: Patch;
-      appendedBytes: number;
-      parseMicros: number;
-      retainedBytes: number;
-      wasmMemoryBytes: number;
-    }
-  | { type: "error"; streamId: number; message: string };
-
-/**
- * Minimal structural interface satisfied by the DOM `Worker`. Injectable so the
- * pool's routing/lifecycle logic can be unit-tested with a fake worker — no
- * real Worker or WASM required.
- */
-export interface WorkerLike {
-  postMessage(msg: ToWorker): void;
-  addEventListener(type: "message", listener: (ev: { data: FromWorker }) => void): void;
-  terminate(): void;
-}
+// Public type surface, split so framework-neutral consumers (`flux-md/client`,
+// `flux-md/dom`) typecheck without resolving react: the neutral types live in
+// ./types-core, the lone React-coupled `Components` type in ./types-react.
+// Re-exported here so `flux-md/types`, index.ts, and every existing import see
+// the identical surface as before.
+export * from "./types-core";
+export * from "./types-react";

package/src/vue.ts

@@ -0,0 +1,100 @@
+import { defineComponent, h, onMounted, onUnmounted, ref, watch } from "vue";
+import type { PropType, Ref } from "vue";
+import type { FluxClient } from "./client";
+import { mountFluxMarkdown, type DomComponents, type MountHandle, type MountOptions } from "./dom";
+
+/**
+ * Vue 3 bindings for {@link mountFluxMarkdown}. Thin lifecycle glue: mount the
+ * framework-neutral DOM renderer on `onMounted`, tear it down on `onUnmounted`.
+ *
+ * The renderer owns all subscribe/diffing; this layer never re-implements it
+ * and — per the renderer's contract — never calls `client.destroy()` (the
+ * caller owns the worker/stream). Shipped as plain `.ts` (no SFC compiler in
+ * the pipeline) via `defineComponent` + `h()`.
+ */
+
+/** Everything `mountFluxMarkdown` accepts, plus the client to subscribe to. */
+export type UseFluxMarkdownOptions = { client: FluxClient } & MountOptions;
+
+/**
+ * Composable that mounts the renderer into a container ref. Returns
+ * `{ container }` — bind it as the `ref` of the element you want filled.
+ *
+ * `getOpts` must read its fields lazily (e.g. `() => ({ client: props.client,
+ * ... })`) so the watcher sees live prop identities. We watch the five
+ * identities individually — `[client, components, sanitize, virtualize,
+ * stickToBottom]` — rather than a freshly-composed object, which would change
+ * identity every call and remount on every patch. On any of those changing we
+ * destroy and remount; `batch`/`highlightCode` still flow through to the mount
+ * but are intentionally not remount triggers.
+ */
+export function useFluxMarkdown(getOpts: () => UseFluxMarkdownOptions): {
+  container: Ref<HTMLElement | null>;
+} {
+  const container = ref<HTMLElement | null>(null);
+  let handle: MountHandle | null = null;
+
+  function mount(): void {
+    if (!container.value) return;
+    const { client, ...mountOptions } = getOpts();
+    handle = mountFluxMarkdown(client, container.value, mountOptions);
+  }
+
+  function teardown(): void {
+    // handle.destroy() is the ONLY teardown — it unsubscribes and removes the
+    // renderer root. The caller owns client.destroy(); we never call it.
+    handle?.destroy();
+    handle = null;
+  }
+
+  onMounted(mount);
+
+  watch(
+    [
+      () => getOpts().client,
+      () => getOpts().components,
+      () => getOpts().sanitize,
+      () => getOpts().virtualize,
+      () => getOpts().stickToBottom,
+    ],
+    () => {
+      // Only after the initial onMounted has run does `handle` exist; before
+      // that the watcher firing (it won't, being lazy) would no-op anyway.
+      teardown();
+      mount();
+    },
+  );
+
+  // Vue auto-stops this watcher when the owning component unmounts, so a manual
+  // stop is unnecessary; we only need to drop the renderer.
+  onUnmounted(teardown);
+
+  return { container };
+}
+
+/**
+ * Component wrapper around {@link useFluxMarkdown}. Renders a single `<div>`
+ * whose ref is the mount container.
+ */
+export const FluxMarkdown = defineComponent({
+  name: "FluxMarkdown",
+  props: {
+    client: { type: Object as PropType<FluxClient>, required: true },
+    components: { type: Object as PropType<DomComponents>, default: undefined },
+    sanitize: { type: Function as PropType<(html: string) => string>, default: undefined },
+    virtualize: { type: Boolean, default: undefined },
+    stickToBottom: { type: Boolean, default: undefined },
+  },
+  setup(props) {
+    // Read props inside the getter so the watch tracks their live identities;
+    // destructuring here would snapshot them and the watcher would never fire.
+    const { container } = useFluxMarkdown(() => ({
+      client: props.client,
+      components: props.components,
+      sanitize: props.sanitize,
+      virtualize: props.virtualize,
+      stickToBottom: props.stickToBottom,
+    }));
+    return () => h("div", { ref: container });
+  },
+});