flux-md 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ Notable changes to flux-md. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## 0.12.0 — 2026-05-30
+
+### Added
+
+- **Optional default theme — `import "flux-md/styles.css"`.** A drop-in stylesheet
+  for good-looking output out of the box, **including the built-in syntax
+  highlighter's colors** (without any CSS, `highlight()` output is uncolored).
+  Scoped to `.flux-md`, driven by `--flux-*` CSS variables (re-theme by overriding
+  a few), light by default with automatic dark via `prefers-color-scheme` (force
+  with `class="flux-md flux-dark"` / `flux-light`). Opt-in and zero-runtime — the
+  rendered HTML is unchanged; skip the import to bring your own CSS.
+
+## 0.11.0 — 2026-05-30
+
+### Added
+
+- **Opt-in live region + root attributes** on `<FluxMarkdown>` and
+  `mountFluxMarkdown`. The root accepts `className` (appended to `flux-md`),
+  `id`, `role`, and `aria-live` / `aria-atomic`. Set `aria-live="polite"` to
+  announce streamed content to screen readers — `polite` coalesces rapid updates
+  and does **not** read every token. Off by default; covers React and the DOM
+  mount (so the Web Component and the Vue/Svelte/Solid adapters too).
+
+### Docs
+
+- A repository root README, a "Structured block data" guide in the package
+  README, and a runnable **Data Studio** demo in the playground — a
+  sort/filter/CSV table and a live table of contents built entirely from
+  `block.data`, mid-stream.
+
 ## 0.10.0 — 2026-05-30
 
 Server-side rendering safety, plus an opt-in structured-data channel so consumers

package/README.md

@@ -280,6 +280,32 @@ if you hit a transform edge, `mountFluxMarkdown` from `flux-md/dom` inside
 | Heavy renderers (syntax, math, mermaid) | Deferred until block close | Re-run per chunk |
 | XSS sanitization | Allowlist in Rust + URL scheme check | Downstream sanitizer pass on the JS thread |
 
+## Styling
+
+flux-md emits semantic HTML under a `.flux-md` root and **ships no CSS by
+default** — bring your own design system, or opt into the bundled theme:
+
+```ts
+import "flux-md/styles.css";
+```
+
+It gives good-looking output out of the box, **including the built-in syntax
+highlighter's colors** (without any CSS, `highlight()` renders uncolored). The
+theme is scoped to `.flux-md`, zero-runtime, and **does not change the rendered
+HTML** — skip the import and nothing is styled.
+
+Re-theme by overriding a few CSS variables; it's light by default and switches to
+dark automatically via `prefers-color-scheme` (force a mode with
+`class="flux-md flux-dark"` or `flux-light`):
+
+```css
+.flux-md {
+  --flux-accent: #7c3aed;   /* links */
+  --flux-bg-code: #faf7ff;  /* code background */
+  --flux-t-kw: #c026d3;     /* syntax: keywords (also --flux-t-str/num/com/fn/ty/…) */
+}
+```
+
 ## Public API
 
 ### `FluxClient`
@@ -412,6 +438,13 @@ Subscribes to a `FluxClient`, renders each block keyed by its stable parser-assi
 <FluxMarkdown client={client} />
 ```
 
+The root element accepts opt-in `className` (appended to `flux-md`), `id`,
+`role`, and `aria-live` / `aria-atomic`. Set `aria-live="polite"` to make the
+output a live region so screen readers announce streamed content as it settles —
+`polite` coalesces rapid updates and does **not** read every token. The same
+options exist on the DOM mount (`mountFluxMarkdown(client, el, { ariaLive: "polite" })`),
+covering the Web Component and the Vue/Svelte/Solid adapters.
+
 #### Custom components / overrides
 
 Pass a `components` map to replace how elements render. Keys come in **two

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "flux-md",
-  "version": "0.10.0",
+  "version": "0.12.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"],
+  "sideEffects": ["./src/worker.ts", "./src/styles.css"],
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -16,7 +16,8 @@
     "./svelte": "./src/svelte.ts",
     "./solid": "./src/solid.tsx",
     "./highlight": "./src/hi.ts",
-    "./types": "./src/types.ts"
+    "./types": "./src/types.ts",
+    "./styles.css": "./src/styles.css"
   },
   "files": [
     "src",
@@ -30,12 +31,21 @@
     "solid-js": "^1.8.0"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "vue": { "optional": true },
-    "svelte": { "optional": true },
-    "solid-js": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@types/bun": "^1.3.14",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
     "happy-dom": "^15.11.6",
@@ -49,6 +59,7 @@
   "scripts": {
     "test": "bun test",
     "test:ssr-cold": "bun test/ssr-cold.mjs",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "prepublishOnly": "cd ../.. && bun run build:wasm"
   },
   "keywords": ["markdown", "streaming", "wasm", "rust", "react", "vue", "svelte", "solid", "web-component", "custom-element", "incremental", "llm", "ai", "math", "katex", "latex", "bidi", "rtl"],

package/src/dom.ts

@@ -61,6 +61,19 @@ export interface MountOptions {
   highlightCode?: boolean;
   /** Coalesce patches into one DOM write per animation frame. Default true. */
   batch?: boolean;
+  /** 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"`, `"log"`). */
+  role?: string;
+  /**
+   * Make the root a live region so screen readers announce streamed content.
+   * `"polite"` coalesces rapid updates (does not read every token). Off by default.
+   */
+  ariaLive?: "off" | "polite" | "assertive";
+  /** Live-region atomicity; pair with `ariaLive`. Off by default. */
+  ariaAtomic?: boolean;
 }
 
 // Per-kind off-screen size estimate for `contain-intrinsic-size`. Duplicated
@@ -99,7 +112,11 @@ export function mountFluxMarkdown(
   const batch = options.batch !== false && typeof requestAnimationFrame === "function";
 
   const root = document.createElement("div");
-  root.className = "flux-md";
+  root.className = options.className ? `flux-md ${options.className}` : "flux-md";
+  if (options.id) root.id = options.id;
+  if (options.role) root.setAttribute("role", options.role);
+  if (options.ariaLive) root.setAttribute("aria-live", options.ariaLive);
+  if (options.ariaAtomic !== undefined) root.setAttribute("aria-atomic", String(options.ariaAtomic));
   container.appendChild(root);
 
   // CSS-only stick-to-bottom: a permanent sentinel pinned as the last child.

package/src/react.tsx

@@ -101,6 +101,20 @@ interface FluxMarkdownProps {
    * run through it. When omitted, rendering is byte-identical and zero-cost.
    */
   sanitize?: (html: string) => string;
+  /** 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"`, `"log"`). */
+  role?: string;
+  /**
+   * Make the root a live region so screen readers announce streamed content.
+   * `"polite"` (recommended) coalesces rapid updates and announces when the
+   * reader is idle — it does **not** read every token. Off by default.
+   */
+  "aria-live"?: "off" | "polite" | "assertive";
+  /** Live-region atomicity; pair with `aria-live`. Off by default. */
+  "aria-atomic"?: boolean;
 }
 
 // The original render path: subscribe to a (required, caller- or hook-owned)
@@ -111,13 +125,24 @@ function FluxMarkdownFromClient({
   virtualize,
   stickToBottom,
   sanitize,
+  className,
+  id,
+  role,
+  "aria-live": ariaLive,
+  "aria-atomic": ariaAtomic,
 }: FluxMarkdownProps & { client: FluxClient }) {
   const blocks = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
   // Normalize "no overrides" to a stable `undefined` so memo comparisons and
   // the fast path don't churn on an empty object identity.
   const comps = components && Object.keys(components).length > 0 ? components : undefined;
   return (
-    <div className="flux-md">
+    <div
+      className={className ? `flux-md ${className}` : "flux-md"}
+      id={id}
+      role={role}
+      aria-live={ariaLive}
+      aria-atomic={ariaAtomic}
+    >
       {blocks.map((b) => (
         <BlockView key={b.id} block={b} components={comps} virtualize={virtualize} sanitize={sanitize} />
       ))}

package/src/renderers/CodeBlock.tsx

@@ -1,5 +1,6 @@
 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;
@@ -19,10 +20,6 @@ function decodeText(html: string): string {
     .replace(/&/g, "&");
 }
 
-function extractLang(html: string): string {
-  const m = html.match(/data-lang="([^"]+)"/);
-  return m ? m[1] : "";
-}
 
 interface Props {
   html: string;

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/wasm/package.json

@@ -2,7 +2,7 @@
   "name": "flux-md-core",
   "type": "module",
   "description": "Incremental, streaming-aware markdown parser with speculative closure",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "license": "MIT",
   "files": [
     "flux_md_core_bg.wasm",