@wingleeio/mugen-markdown 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -162,7 +162,16 @@ const defaultTheme = {
 		background: "rgba(127, 127, 127, 0.12)",
 		color: "inherit",
 		radius: 8,
-		highlight: defaultTokenColors
+		highlight: defaultTokenColors,
+		header: {
+			show: false,
+			height: 38,
+			fontSize: 12,
+			background: "rgba(127, 127, 127, 0.06)",
+			color: "rgba(127, 127, 127, 0.85)",
+			borderColor: "rgba(127, 127, 127, 0.18)",
+			buttonBackground: "rgba(127, 127, 127, 0.04)"
+		}
 	},
 	blockquote: {
 		padding: 14,
@@ -1311,7 +1320,7 @@ function lineCount(value) {
 function measureCodeBlock(props, ctx) {
 	(0, _wingleeio_mugen.assertMeasurableFont)(props.font);
 	const pad = props.padding ?? 0;
-	return lineCount(props.value) * props.lineHeight + 2 * pad;
+	return (props.header ? props.header.height : 0) + lineCount(props.value) * props.lineHeight + 2 * pad;
 }
 const colorsCache = /* @__PURE__ */ new WeakMap();
 function resolveTokenColors(overrides) {
@@ -1375,9 +1384,124 @@ function HighlightedCode(props) {
 		style: overlayStyle
 	}));
 }
+function legacyCopy(text) {
+	if (typeof document === "undefined") return false;
+	const ta = document.createElement("textarea");
+	ta.value = text;
+	ta.setAttribute("readonly", "");
+	ta.style.position = "fixed";
+	ta.style.top = "0";
+	ta.style.left = "0";
+	ta.style.opacity = "0";
+	ta.style.pointerEvents = "none";
+	document.body.appendChild(ta);
+	ta.select();
+	let ok = false;
+	try {
+		ok = document.execCommand("copy");
+	} catch {
+		ok = false;
+	}
+	document.body.removeChild(ta);
+	return ok;
+}
+async function copyText(text) {
+	const clip = typeof navigator !== "undefined" ? navigator.clipboard : void 0;
+	if (clip?.writeText != null) try {
+		await clip.writeText(text);
+		return true;
+	} catch {}
+	return legacyCopy(text);
+}
+/** Copies the block's raw text; flips to "Copied" for ~1.6s on success. */
+function CopyButton(props) {
+	const [copied, setCopied] = (0, react.useState)(false);
+	const [hovered, setHovered] = (0, react.useState)(false);
+	const timer = (0, react.useRef)(null);
+	(0, react.useEffect)(() => () => {
+		if (timer.current != null) clearTimeout(timer.current);
+	}, []);
+	const onClick = () => {
+		copyText(props.value).then((ok) => {
+			if (!ok) return;
+			setCopied(true);
+			if (timer.current != null) clearTimeout(timer.current);
+			timer.current = setTimeout(() => setCopied(false), 1600);
+		}).catch(() => {});
+	};
+	const style = {
+		display: "inline-flex",
+		flex: "0 0 auto",
+		alignItems: "center",
+		justifyContent: "center",
+		whiteSpace: "nowrap",
+		cursor: "pointer",
+		borderRadius: 8,
+		border: `1px solid ${props.borderColor ?? "rgba(127, 127, 127, 0.2)"}`,
+		...props.background != null ? { background: props.background } : null,
+		...props.color != null ? { color: props.color } : null,
+		padding: "4px 9px",
+		minWidth: "4.6em",
+		fontFamily: "inherit",
+		fontSize: `${props.fontSize}px`,
+		lineHeight: 1,
+		opacity: hovered || copied ? 1 : .82,
+		transition: "opacity 120ms ease"
+	};
+	return (0, react.createElement)("button", {
+		type: "button",
+		onClick,
+		onMouseEnter: () => setHovered(true),
+		onMouseLeave: () => setHovered(false),
+		"aria-label": copied ? "Copied" : "Copy code",
+		style
+	}, copied ? "Copied" : "Copy");
+}
+/** The fixed-height chrome bar: language label left, copy button right. */
+function CodeHeader(props) {
+	const barStyle = {
+		display: "flex",
+		flex: "0 0 auto",
+		alignItems: "center",
+		justifyContent: "space-between",
+		gap: 8,
+		height: `${props.height}px`,
+		boxSizing: "border-box",
+		padding: "0 12px",
+		fontFamily: props.fontFamily,
+		...props.radius != null ? {
+			borderTopLeftRadius: `${props.radius}px`,
+			borderTopRightRadius: `${props.radius}px`
+		} : null,
+		...props.background != null ? { background: props.background } : null,
+		...props.borderColor != null ? { borderBottom: `1px solid ${props.borderColor}` } : null
+	};
+	const labelStyle = {
+		minWidth: 0,
+		overflow: "hidden",
+		textOverflow: "ellipsis",
+		whiteSpace: "nowrap",
+		fontSize: `${props.fontSize}px`,
+		letterSpacing: "0.02em",
+		fontVariantLigatures: "none",
+		...props.color != null ? { color: props.color } : null
+	};
+	return (0, react.createElement)("div", { style: barStyle }, (0, react.createElement)("span", {
+		key: "lang",
+		style: labelStyle
+	}, props.label), (0, react.createElement)(CopyButton, {
+		key: "copy",
+		value: props.value,
+		fontSize: props.fontSize,
+		color: props.color,
+		borderColor: props.borderColor,
+		background: props.buttonBackground
+	}));
+}
 function renderCodeBlock(props) {
 	const pad = props.padding ?? 0;
 	const profile = props.highlight === false ? null : profileFor(props.lang);
+	const header = props.header;
 	const preStyle = {
 		margin: 0,
 		padding: `${pad}px`,
@@ -1386,7 +1510,10 @@ function renderCodeBlock(props) {
 		boxSizing: "border-box",
 		...props.background != null ? { background: props.background } : null,
 		...props.color != null ? { color: props.color } : null,
-		...props.radius != null ? { borderRadius: `${props.radius}px` } : null,
+		...props.radius != null ? header == null ? { borderRadius: `${props.radius}px` } : {
+			borderBottomLeftRadius: `${props.radius}px`,
+			borderBottomRightRadius: `${props.radius}px`
+		} : null,
 		...profile != null ? {
 			position: "relative",
 			tabSize: 8
@@ -1399,17 +1526,13 @@ function renderCodeBlock(props) {
 		margin: 0,
 		padding: 0
 	};
-	if (profile == null) return (0, react.createElement)("pre", {
-		className: props.className,
+	const pre = (0, react.createElement)("pre", {
+		...header == null ? { className: props.className } : null,
 		style: preStyle
-	}, (0, react.createElement)("code", {
+	}, profile == null ? (0, react.createElement)("code", {
 		style: codeStyle,
 		...props.lang ? { "data-lang": props.lang } : null
-	}, props.value));
-	return (0, react.createElement)("pre", {
-		className: props.className,
-		style: preStyle
-	}, (0, react.createElement)(HighlightedCode, {
+	}, props.value) : (0, react.createElement)(HighlightedCode, {
 		value: props.value,
 		lang: props.lang,
 		font: props.font,
@@ -1419,6 +1542,20 @@ function renderCodeBlock(props) {
 		colors: resolveTokenColors(props.highlight === false ? void 0 : props.highlight),
 		codeStyle
 	}));
+	if (header == null) return pre;
+	return (0, react.createElement)("div", { className: props.className }, (0, react.createElement)(CodeHeader, {
+		key: "header",
+		label: header.label ?? props.lang ?? "code",
+		value: props.value,
+		height: header.height,
+		fontSize: header.fontSize,
+		fontFamily: header.fontFamily ?? "monospace",
+		...props.radius != null ? { radius: props.radius } : null,
+		background: header.background,
+		color: header.color,
+		borderColor: header.borderColor,
+		buttonBackground: header.buttonBackground
+	}), pre);
 }
 /** A measurable fenced-code primitive (no wrapping; height from line count). */
 const CodeBlock = (0, _wingleeio_mugen.markPrimitive)(renderCodeBlock, {
@@ -1632,7 +1769,16 @@ const defaultComponents = {
 			background: c.background,
 			radius: c.radius,
 			highlight: c.highlight,
-			...c.color !== "inherit" ? { color: c.color } : null
+			...c.color !== "inherit" ? { color: c.color } : null,
+			...c.header.show ? { header: {
+				height: c.header.height,
+				fontSize: c.header.fontSize,
+				fontFamily: ctx.theme.monoFamily,
+				background: c.header.background,
+				color: c.header.color,
+				borderColor: c.header.borderColor,
+				buttonBackground: c.header.buttonBackground
+			} } : null
 		});
 	},
 	list: ({ node, ctx }) => renderList(node, ctx),
@@ -1817,6 +1963,256 @@ function renderMarkdown(source, options = {}) {
 	return createContext(resolveTheme(options.theme), mergeComponents(options.components)).renderBlocks(ast.children);
 }
 //#endregion
+//#region src/primitives/fade.tsx
+/**
+* Streaming fade-in for `<Markdown fade>`.
+*
+* The same trick the code highlighter uses, pointed at motion instead of
+* colour: the markdown DOM commits and lays out instantly (so heights,
+* selection, and stick-to-bottom stay honest), and a background-coloured veil
+* is painted over just-arrived characters and dissolved — which *reads* as the
+* text fading in. Nothing about the row ever animates; layout is done the
+* moment the text lands.
+*
+* Unlike a list-level overlay, the veil canvas lives **inside** the markdown's
+* own box (`position: absolute; inset: 0`), so it scrolls with the content and
+* needs no viewport-geometry tracking. The painter idles (no rAF) until a
+* DOM mutation arrives, so leaving `fade` on for a settled block costs nothing.
+*/
+const EMA_SEED_MS = 160;
+const MIN_FADE_MS = 120;
+const MAX_FADE_MS = 400;
+const MAX_VEILS = 32;
+function commonPrefixLength(a, b) {
+	const n = Math.min(a.length, b.length);
+	let i = 0;
+	while (i < n && a.charCodeAt(i) === b.charCodeAt(i)) i++;
+	return i;
+}
+function inChrome(node, container) {
+	for (let p = node.parentElement; p != null && p !== container; p = p.parentElement) if (p.tagName === "BUTTON") return true;
+	return false;
+}
+function contentTextFilter(container) {
+	return { acceptNode: (n) => inChrome(n, container) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT };
+}
+/** `container.textContent`, minus interactive chrome (see {@link inChrome}). */
+function contentText(container) {
+	const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, contentTextFilter(container));
+	let s = "";
+	for (let n = walker.nextNode(); n != null; n = walker.nextNode()) s += n.data;
+	return s;
+}
+let scratch;
+function scratchCtx() {
+	if (scratch === void 0) {
+		const c = typeof document === "undefined" ? null : document.createElement("canvas");
+		if (c == null) return scratch = null;
+		c.width = 1;
+		c.height = 1;
+		scratch = c.getContext("2d", { willReadFrequently: true });
+	}
+	return scratch;
+}
+/** The opaque colour behind `el`: every ancestor's backgroundColor composited. */
+function effectiveBackground(el, cache) {
+	const cached = cache.get(el);
+	if (cached !== void 0) return cached;
+	const layers = [];
+	for (let cur = el; cur != null; cur = cur.parentElement) {
+		const bg = getComputedStyle(cur).backgroundColor;
+		if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") layers.push(bg);
+	}
+	const s = scratchCtx();
+	if (s == null) return "#808080";
+	s.globalAlpha = 1;
+	s.fillStyle = "#ffffff";
+	s.fillRect(0, 0, 1, 1);
+	for (let i = layers.length - 1; i >= 0; i--) {
+		try {
+			s.fillStyle = layers[i];
+		} catch {
+			continue;
+		}
+		s.fillRect(0, 0, 1, 1);
+	}
+	const d = s.getImageData(0, 0, 1, 1).data;
+	const css = `rgb(${d[0]}, ${d[1]}, ${d[2]})`;
+	cache.set(el, css);
+	return css;
+}
+/**
+* Paints the dissolving veil over a single content element's newly-arrived text.
+* Driven by a MutationObserver: a rAF loop runs only while veils are alive, then
+* stops until the next mutation, so an idle (settled) block uses no frames.
+*/
+var FadePainter = class {
+	content = null;
+	canvas = null;
+	ctx = null;
+	prevText = "";
+	veils = [];
+	ema = EMA_SEED_MS;
+	lastAppend = 0;
+	raf = 0;
+	running = false;
+	mo = null;
+	attach(content, canvas) {
+		if (typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+		const ctx = canvas.getContext("2d");
+		if (ctx == null) return;
+		this.content = content;
+		this.canvas = canvas;
+		this.ctx = ctx;
+		this.prevText = contentText(content);
+		this.mo = new MutationObserver(() => this.wake());
+		this.mo.observe(content, {
+			subtree: true,
+			childList: true,
+			characterData: true
+		});
+	}
+	destroy() {
+		this.mo?.disconnect();
+		this.mo = null;
+		if (this.raf !== 0) cancelAnimationFrame(this.raf);
+		this.raf = 0;
+		this.running = false;
+		this.content = null;
+		this.canvas = null;
+		this.ctx = null;
+	}
+	wake() {
+		if (this.running || this.content == null) return;
+		this.running = true;
+		this.raf = requestAnimationFrame(this.frame);
+	}
+	frame = () => {
+		const content = this.content;
+		const canvas = this.canvas;
+		const ctx = this.ctx;
+		if (content == null || canvas == null || ctx == null) {
+			this.running = false;
+			return;
+		}
+		const now = performance.now();
+		const text = contentText(content);
+		if (text !== this.prevText) {
+			const prefix = commonPrefixLength(this.prevText, text);
+			this.veils = this.veils.map((v) => ({
+				...v,
+				start: Math.min(v.start, prefix),
+				end: Math.min(v.end, prefix)
+			})).filter((v) => v.end > v.start);
+			if (text.length > prefix) {
+				if (this.lastAppend > 0) this.ema = this.ema * .7 + Math.min(now - this.lastAppend, 1e3) * .3;
+				this.lastAppend = now;
+				this.veils.push({
+					start: prefix,
+					end: text.length,
+					t0: now
+				});
+				if (this.veils.length > MAX_VEILS) this.veils.splice(0, this.veils.length - MAX_VEILS);
+			}
+			this.prevText = text;
+		}
+		const duration = Math.min(MAX_FADE_MS, Math.max(MIN_FADE_MS, this.ema * 3));
+		const boost = 1 + .3 * Math.max(0, this.veils.length - 2);
+		this.veils = this.veils.filter((v) => (now - v.t0) * boost < duration);
+		const dpr = typeof devicePixelRatio === "number" && devicePixelRatio > 0 ? devicePixelRatio : 1;
+		const w = content.clientWidth;
+		const h = content.clientHeight;
+		if (canvas.width !== Math.round(w * dpr) || canvas.height !== Math.round(h * dpr)) {
+			canvas.width = Math.round(w * dpr);
+			canvas.height = Math.round(h * dpr);
+		}
+		ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+		ctx.clearRect(0, 0, w, h);
+		if (this.veils.length > 0) {
+			const origin = canvas.getBoundingClientRect();
+			const bgCache = /* @__PURE__ */ new Map();
+			const groups = /* @__PURE__ */ new Map();
+			const minStart = this.veils.reduce((m, v) => Math.min(m, v.start), Infinity);
+			const walker = document.createTreeWalker(content, NodeFilter.SHOW_TEXT, contentTextFilter(content));
+			let base = 0;
+			let node = walker.nextNode();
+			while (node != null) {
+				const len = node.data.length;
+				if (len > 0 && base + len > minStart) for (let vi = 0; vi < this.veils.length; vi++) {
+					const v = this.veils[vi];
+					const s = Math.max(v.start - base, 0);
+					const e = Math.min(v.end - base, len);
+					if (e <= s) continue;
+					const parent = node.parentElement;
+					if (parent == null) continue;
+					const bg = effectiveBackground(parent, bgCache);
+					const key = `${vi}|${bg}`;
+					let group = groups.get(key);
+					if (group === void 0) {
+						const p = Math.min(1, (now - v.t0) * boost / duration);
+						group = {
+							alpha: Math.pow(1 - p, 1.6),
+							bg,
+							path: new Path2D()
+						};
+						groups.set(key, group);
+					}
+					const range = document.createRange();
+					range.setStart(node, s);
+					range.setEnd(node, e);
+					for (const r of range.getClientRects()) group.path.rect(r.left - origin.left - 1, r.top - origin.top - 1, r.width + 2, r.height + 2);
+				}
+				base += len;
+				node = walker.nextNode();
+			}
+			for (const group of groups.values()) {
+				ctx.globalAlpha = group.alpha;
+				ctx.fillStyle = group.bg;
+				ctx.fill(group.path);
+			}
+			ctx.globalAlpha = 1;
+		}
+		if (this.veils.length > 0) this.raf = requestAnimationFrame(this.frame);
+		else {
+			this.running = false;
+			this.raf = 0;
+		}
+	};
+};
+function renderFadeMarkdown(props) {
+	const contentRef = (0, react.useRef)(null);
+	const canvasRef = (0, react.useRef)(null);
+	(0, react.useEffect)(() => {
+		const content = contentRef.current;
+		const canvas = canvasRef.current;
+		if (content == null || canvas == null) return;
+		const painter = new FadePainter();
+		painter.attach(content, canvas);
+		return () => painter.destroy();
+	}, []);
+	return (0, react.createElement)("div", { style: { position: "relative" } }, (0, react.createElement)("div", { ref: contentRef }, props.children), (0, react.createElement)("canvas", {
+		ref: canvasRef,
+		"aria-hidden": true,
+		style: {
+			position: "absolute",
+			inset: 0,
+			width: "100%",
+			height: "100%",
+			pointerEvents: "none"
+		}
+	}));
+}
+/**
+* Wraps a measured markdown subtree with a streaming fade-in canvas. Its height
+* is exactly the subtree's height — the canvas overlay is out of flow and never
+* measured.
+*/
+const FadeMarkdown = (0, _wingleeio_mugen.markPrimitive)(renderFadeMarkdown, {
+	name: "FadeMarkdown",
+	measure: (props, ctx) => (0, _wingleeio_mugen.measureChildren)(props.children, ctx),
+	naturalWidth: (props, ctx) => (0, _wingleeio_mugen.naturalWidthOf)(props.children, ctx)
+});
+//#endregion
 //#region src/markdown.tsx
 /**
 * Render markdown as a tree of mugen primitives.
@@ -1839,7 +2235,9 @@ function renderMarkdown(source, options = {}) {
 * and a deep-partial `theme`.
 */
 function Markdown(props) {
-	return renderMarkdown(props.source, props);
+	const content = renderMarkdown(props.source, props);
+	if (props.fade && content != null) return (0, react.createElement)(FadeMarkdown, null, content);
+	return content;
 }
 Markdown.displayName = "Markdown";
 //#endregion
@@ -1860,6 +2258,7 @@ function defineMarkdownComponents(components) {
 }
 //#endregion
 exports.CodeBlock = CodeBlock;
+exports.FadeMarkdown = FadeMarkdown;
 Object.defineProperty(exports, "HStack", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.cts

@@ -110,6 +110,21 @@ interface MarkdownTheme {
      * change a block's measured height.
      */
     highlight: CodeTokenColors | false;
+    /**
+     * Optional chrome bar above the code — the language on the left, a
+     * copy-to-clipboard button on the right. `show: false` (the default) keeps
+     * the bare `<pre>`. When shown, the bar's fixed `height` is folded into the
+     * block's measured height, so computed and painted heights stay identical.
+     */
+    header: {
+      /** Render the chrome bar. Off by default. */show: boolean; /** Fixed bar height in px (counted in the measured height). */
+      height: number; /** Label + button font size in px. */
+      fontSize: number; /** Bar background. */
+      background: string; /** Label + button text colour. */
+      color: string; /** Bottom hairline + button border colour. */
+      borderColor: string; /** Copy-button fill. */
+      buttonBackground: string;
+    };
   };
   blockquote: {
     padding: number;
@@ -354,6 +369,13 @@ declare function renderMarkdown(source: string, options?: RenderMarkdownOptions)
 interface MarkdownProps extends RenderMarkdownOptions {
   /** The markdown source to render. */
   source: string;
+  /**
+   * Fade just-arrived text in as the source streams. The DOM still commits and
+   * lays out instantly (heights stay exact); a veil over new characters
+   * dissolves, which reads as a fade-in. Leaving it on for a settled block is
+   * free. Honours `prefers-reduced-motion`.
+   */
+  fade?: boolean;
 }
 /**
  * Render markdown as a tree of mugen primitives.
@@ -383,8 +405,9 @@ declare namespace Markdown {
 //#region src/primitives/code-block.d.ts
 /**
  * A fenced code block. Code does not wrap — long lines scroll horizontally — so
- * its height is simply `lineCount × lineHeight + 2 × padding`, independent of the
- * row width. That makes it trivially and exactly measurable.
+ * its height is simply `lineCount × lineHeight + 2 × padding` (plus an optional
+ * fixed-height {@link CodeBlockHeader} bar), independent of the row width. That
+ * makes it trivially and exactly measurable.
  *
  * Syntax highlighting is layered on as pure paint, never layout: the `<code>`
  * text renders immediately (plain, selectable, accessible), the language is
@@ -393,6 +416,27 @@ declare namespace Markdown {
  * turns `color: transparent` in the same frame. Highlighting therefore can't
  * block first paint and can't ever change the measured height.
  */
+/**
+ * Optional chrome bar above the code: the language on the left, a
+ * copy-to-clipboard button on the right. Its fixed `height` is added to the
+ * block's measured height, so the block still measures exactly what it paints.
+ * Pure decoration otherwise — the bar never wraps and never grows.
+ */
+interface CodeBlockHeader {
+  /** Left-aligned label; falls back to {@link CodeBlockProps.lang}, then `code`. */
+  label?: string;
+  /** Fixed bar height in px (folded into the measured height). */
+  height: number;
+  /** Label + button font size in px. */
+  fontSize: number;
+  /** Monospace family for the label/button; defaults to `monospace`. */
+  fontFamily?: string;
+  background?: string;
+  color?: string;
+  borderColor?: string;
+  /** Copy-button fill. */
+  buttonBackground?: string;
+}
 interface CodeBlockProps<C extends string = string> {
   /** Raw code text. Newlines determine the line count. */
   value: string;
@@ -413,6 +457,11 @@ interface CodeBlockProps<C extends string = string> {
    * registered profile are highlighted either way.
    */
   highlight?: Partial<CodeTokenColors> | false;
+  /**
+   * A chrome bar above the code (language label + copy button). Omit for the
+   * bare `<pre>`. Its `height` is folded into the measured height.
+   */
+  header?: CodeBlockHeader;
   style?: MeasurableStyle;
   className?: SafeClassName<C>;
 }
@@ -454,6 +503,18 @@ interface TableBlockProps<C extends string = string> {
 /** A measurable GFM-table primitive with aligned, content-proportional columns. */
 declare const TableBlock: <C extends string = string>(props: TableBlockProps<C>) => ReactElement;
 //#endregion
+//#region src/primitives/fade.d.ts
+interface FadeMarkdownProps {
+  /** The rendered markdown subtree to veil. */
+  children?: ReactNode;
+}
+/**
+ * Wraps a measured markdown subtree with a streaming fade-in canvas. Its height
+ * is exactly the subtree's height — the canvas overlay is out of flow and never
+ * measured.
+ */
+declare const FadeMarkdown: (props: FadeMarkdownProps) => ReactElement;
+//#endregion
 //#region src/highlight/languages.d.ts
 /**
  * Language profiles for the built-in tokenizer. A profile is a small data
@@ -495,4 +556,4 @@ declare function registerLanguage(names: string | readonly string[], p: Language
 /** The profile for a fence language, or `null` when the language is unknown. */
 declare function profileFor(lang: string | undefined): LanguageProfile | null;
 //#endregion
-export { type Blockquote, type BoxProps, type Code, CodeBlock, type CodeBlockProps, type CodeTokenColors, type DeepPartial, type Font, HStack, type HStackProps, type Heading, type Html, type Image, type InlineFormat, type InlineTextOptions, type LanguageProfile, type Link, type List, type ListItem, Markdown, type MarkdownComponent, type MarkdownComponentProps, type MarkdownComponents, type MarkdownParseOptions, type MarkdownProps, type MarkdownRenderContext, type MarkdownTheme, type Paragraph, type PhrasingContent, type PrimitiveComponent, type RenderMarkdownOptions, type ResolvedMarkdownComponents, RichText, type RichTextProps, type RichTextRun, type Root, type RootContent, type Table, TableBlock, type TableBlockProps, type TableCell, type TableRow, Text, type TextProps, type ThematicBreak, type TokenType, VStack, type VStackProps, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };
+export { type Blockquote, type BoxProps, type Code, CodeBlock, type CodeBlockHeader, type CodeBlockProps, type CodeTokenColors, type DeepPartial, FadeMarkdown, type Font, HStack, type HStackProps, type Heading, type Html, type Image, type InlineFormat, type InlineTextOptions, type LanguageProfile, type Link, type List, type ListItem, Markdown, type MarkdownComponent, type MarkdownComponentProps, type MarkdownComponents, type MarkdownParseOptions, type MarkdownProps, type MarkdownRenderContext, type MarkdownTheme, type Paragraph, type PhrasingContent, type PrimitiveComponent, type RenderMarkdownOptions, type ResolvedMarkdownComponents, RichText, type RichTextProps, type RichTextRun, type Root, type RootContent, type Table, TableBlock, type TableBlockProps, type TableCell, type TableRow, Text, type TextProps, type ThematicBreak, type TokenType, VStack, type VStackProps, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };

package/dist/index.d.mts

@@ -110,6 +110,21 @@ interface MarkdownTheme {
      * change a block's measured height.
      */
     highlight: CodeTokenColors | false;
+    /**
+     * Optional chrome bar above the code — the language on the left, a
+     * copy-to-clipboard button on the right. `show: false` (the default) keeps
+     * the bare `<pre>`. When shown, the bar's fixed `height` is folded into the
+     * block's measured height, so computed and painted heights stay identical.
+     */
+    header: {
+      /** Render the chrome bar. Off by default. */show: boolean; /** Fixed bar height in px (counted in the measured height). */
+      height: number; /** Label + button font size in px. */
+      fontSize: number; /** Bar background. */
+      background: string; /** Label + button text colour. */
+      color: string; /** Bottom hairline + button border colour. */
+      borderColor: string; /** Copy-button fill. */
+      buttonBackground: string;
+    };
   };
   blockquote: {
     padding: number;
@@ -354,6 +369,13 @@ declare function renderMarkdown(source: string, options?: RenderMarkdownOptions)
 interface MarkdownProps extends RenderMarkdownOptions {
   /** The markdown source to render. */
   source: string;
+  /**
+   * Fade just-arrived text in as the source streams. The DOM still commits and
+   * lays out instantly (heights stay exact); a veil over new characters
+   * dissolves, which reads as a fade-in. Leaving it on for a settled block is
+   * free. Honours `prefers-reduced-motion`.
+   */
+  fade?: boolean;
 }
 /**
  * Render markdown as a tree of mugen primitives.
@@ -383,8 +405,9 @@ declare namespace Markdown {
 //#region src/primitives/code-block.d.ts
 /**
  * A fenced code block. Code does not wrap — long lines scroll horizontally — so
- * its height is simply `lineCount × lineHeight + 2 × padding`, independent of the
- * row width. That makes it trivially and exactly measurable.
+ * its height is simply `lineCount × lineHeight + 2 × padding` (plus an optional
+ * fixed-height {@link CodeBlockHeader} bar), independent of the row width. That
+ * makes it trivially and exactly measurable.
  *
  * Syntax highlighting is layered on as pure paint, never layout: the `<code>`
  * text renders immediately (plain, selectable, accessible), the language is
@@ -393,6 +416,27 @@ declare namespace Markdown {
  * turns `color: transparent` in the same frame. Highlighting therefore can't
  * block first paint and can't ever change the measured height.
  */
+/**
+ * Optional chrome bar above the code: the language on the left, a
+ * copy-to-clipboard button on the right. Its fixed `height` is added to the
+ * block's measured height, so the block still measures exactly what it paints.
+ * Pure decoration otherwise — the bar never wraps and never grows.
+ */
+interface CodeBlockHeader {
+  /** Left-aligned label; falls back to {@link CodeBlockProps.lang}, then `code`. */
+  label?: string;
+  /** Fixed bar height in px (folded into the measured height). */
+  height: number;
+  /** Label + button font size in px. */
+  fontSize: number;
+  /** Monospace family for the label/button; defaults to `monospace`. */
+  fontFamily?: string;
+  background?: string;
+  color?: string;
+  borderColor?: string;
+  /** Copy-button fill. */
+  buttonBackground?: string;
+}
 interface CodeBlockProps<C extends string = string> {
   /** Raw code text. Newlines determine the line count. */
   value: string;
@@ -413,6 +457,11 @@ interface CodeBlockProps<C extends string = string> {
    * registered profile are highlighted either way.
    */
   highlight?: Partial<CodeTokenColors> | false;
+  /**
+   * A chrome bar above the code (language label + copy button). Omit for the
+   * bare `<pre>`. Its `height` is folded into the measured height.
+   */
+  header?: CodeBlockHeader;
   style?: MeasurableStyle;
   className?: SafeClassName<C>;
 }
@@ -454,6 +503,18 @@ interface TableBlockProps<C extends string = string> {
 /** A measurable GFM-table primitive with aligned, content-proportional columns. */
 declare const TableBlock: <C extends string = string>(props: TableBlockProps<C>) => ReactElement;
 //#endregion
+//#region src/primitives/fade.d.ts
+interface FadeMarkdownProps {
+  /** The rendered markdown subtree to veil. */
+  children?: ReactNode;
+}
+/**
+ * Wraps a measured markdown subtree with a streaming fade-in canvas. Its height
+ * is exactly the subtree's height — the canvas overlay is out of flow and never
+ * measured.
+ */
+declare const FadeMarkdown: (props: FadeMarkdownProps) => ReactElement;
+//#endregion
 //#region src/highlight/languages.d.ts
 /**
  * Language profiles for the built-in tokenizer. A profile is a small data
@@ -495,4 +556,4 @@ declare function registerLanguage(names: string | readonly string[], p: Language
 /** The profile for a fence language, or `null` when the language is unknown. */
 declare function profileFor(lang: string | undefined): LanguageProfile | null;
 //#endregion
-export { type Blockquote, type BoxProps, type Code, CodeBlock, type CodeBlockProps, type CodeTokenColors, type DeepPartial, type Font, HStack, type HStackProps, type Heading, type Html, type Image, type InlineFormat, type InlineTextOptions, type LanguageProfile, type Link, type List, type ListItem, Markdown, type MarkdownComponent, type MarkdownComponentProps, type MarkdownComponents, type MarkdownParseOptions, type MarkdownProps, type MarkdownRenderContext, type MarkdownTheme, type Paragraph, type PhrasingContent, type PrimitiveComponent, type RenderMarkdownOptions, type ResolvedMarkdownComponents, RichText, type RichTextProps, type RichTextRun, type Root, type RootContent, type Table, TableBlock, type TableBlockProps, type TableCell, type TableRow, Text, type TextProps, type ThematicBreak, type TokenType, VStack, type VStackProps, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };
+export { type Blockquote, type BoxProps, type Code, CodeBlock, type CodeBlockHeader, type CodeBlockProps, type CodeTokenColors, type DeepPartial, FadeMarkdown, type Font, HStack, type HStackProps, type Heading, type Html, type Image, type InlineFormat, type InlineTextOptions, type LanguageProfile, type Link, type List, type ListItem, Markdown, type MarkdownComponent, type MarkdownComponentProps, type MarkdownComponents, type MarkdownParseOptions, type MarkdownProps, type MarkdownRenderContext, type MarkdownTheme, type Paragraph, type PhrasingContent, type PrimitiveComponent, type RenderMarkdownOptions, type ResolvedMarkdownComponents, RichText, type RichTextProps, type RichTextRun, type Root, type RootContent, type Table, TableBlock, type TableBlockProps, type TableCell, type TableRow, Text, type TextProps, type ThematicBreak, type TokenType, VStack, type VStackProps, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { Fragment, createElement, useEffect, useLayoutEffect, useRef } from "react";
-import { HStack, HStack as HStack$1, Text, VStack, VStack as VStack$1, assertMeasurableFont, definePrimitive, definePrimitive as definePrimitive$1, fontEpoch, fontLonghands, fontWithLineHeight, markPrimitive, naturalWidthOf } from "@wingleeio/mugen";
+import { Fragment, createElement, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { HStack, HStack as HStack$1, Text, VStack, VStack as VStack$1, assertMeasurableFont, definePrimitive, definePrimitive as definePrimitive$1, fontEpoch, fontLonghands, fontWithLineHeight, markPrimitive, measureChildren, naturalWidthOf } from "@wingleeio/mugen";
 import { createIncremarkParser } from "@incremark/core";
 import { measureRichInlineStats, prepareRichInline } from "@chenglou/pretext/rich-inline";
 //#region src/parse.ts
@@ -161,7 +161,16 @@ const defaultTheme = {
 		background: "rgba(127, 127, 127, 0.12)",
 		color: "inherit",
 		radius: 8,
-		highlight: defaultTokenColors
+		highlight: defaultTokenColors,
+		header: {
+			show: false,
+			height: 38,
+			fontSize: 12,
+			background: "rgba(127, 127, 127, 0.06)",
+			color: "rgba(127, 127, 127, 0.85)",
+			borderColor: "rgba(127, 127, 127, 0.18)",
+			buttonBackground: "rgba(127, 127, 127, 0.04)"
+		}
 	},
 	blockquote: {
 		padding: 14,
@@ -1310,7 +1319,7 @@ function lineCount(value) {
 function measureCodeBlock(props, ctx) {
 	assertMeasurableFont(props.font);
 	const pad = props.padding ?? 0;
-	return lineCount(props.value) * props.lineHeight + 2 * pad;
+	return (props.header ? props.header.height : 0) + lineCount(props.value) * props.lineHeight + 2 * pad;
 }
 const colorsCache = /* @__PURE__ */ new WeakMap();
 function resolveTokenColors(overrides) {
@@ -1374,9 +1383,124 @@ function HighlightedCode(props) {
 		style: overlayStyle
 	}));
 }
+function legacyCopy(text) {
+	if (typeof document === "undefined") return false;
+	const ta = document.createElement("textarea");
+	ta.value = text;
+	ta.setAttribute("readonly", "");
+	ta.style.position = "fixed";
+	ta.style.top = "0";
+	ta.style.left = "0";
+	ta.style.opacity = "0";
+	ta.style.pointerEvents = "none";
+	document.body.appendChild(ta);
+	ta.select();
+	let ok = false;
+	try {
+		ok = document.execCommand("copy");
+	} catch {
+		ok = false;
+	}
+	document.body.removeChild(ta);
+	return ok;
+}
+async function copyText(text) {
+	const clip = typeof navigator !== "undefined" ? navigator.clipboard : void 0;
+	if (clip?.writeText != null) try {
+		await clip.writeText(text);
+		return true;
+	} catch {}
+	return legacyCopy(text);
+}
+/** Copies the block's raw text; flips to "Copied" for ~1.6s on success. */
+function CopyButton(props) {
+	const [copied, setCopied] = useState(false);
+	const [hovered, setHovered] = useState(false);
+	const timer = useRef(null);
+	useEffect(() => () => {
+		if (timer.current != null) clearTimeout(timer.current);
+	}, []);
+	const onClick = () => {
+		copyText(props.value).then((ok) => {
+			if (!ok) return;
+			setCopied(true);
+			if (timer.current != null) clearTimeout(timer.current);
+			timer.current = setTimeout(() => setCopied(false), 1600);
+		}).catch(() => {});
+	};
+	const style = {
+		display: "inline-flex",
+		flex: "0 0 auto",
+		alignItems: "center",
+		justifyContent: "center",
+		whiteSpace: "nowrap",
+		cursor: "pointer",
+		borderRadius: 8,
+		border: `1px solid ${props.borderColor ?? "rgba(127, 127, 127, 0.2)"}`,
+		...props.background != null ? { background: props.background } : null,
+		...props.color != null ? { color: props.color } : null,
+		padding: "4px 9px",
+		minWidth: "4.6em",
+		fontFamily: "inherit",
+		fontSize: `${props.fontSize}px`,
+		lineHeight: 1,
+		opacity: hovered || copied ? 1 : .82,
+		transition: "opacity 120ms ease"
+	};
+	return createElement("button", {
+		type: "button",
+		onClick,
+		onMouseEnter: () => setHovered(true),
+		onMouseLeave: () => setHovered(false),
+		"aria-label": copied ? "Copied" : "Copy code",
+		style
+	}, copied ? "Copied" : "Copy");
+}
+/** The fixed-height chrome bar: language label left, copy button right. */
+function CodeHeader(props) {
+	const barStyle = {
+		display: "flex",
+		flex: "0 0 auto",
+		alignItems: "center",
+		justifyContent: "space-between",
+		gap: 8,
+		height: `${props.height}px`,
+		boxSizing: "border-box",
+		padding: "0 12px",
+		fontFamily: props.fontFamily,
+		...props.radius != null ? {
+			borderTopLeftRadius: `${props.radius}px`,
+			borderTopRightRadius: `${props.radius}px`
+		} : null,
+		...props.background != null ? { background: props.background } : null,
+		...props.borderColor != null ? { borderBottom: `1px solid ${props.borderColor}` } : null
+	};
+	const labelStyle = {
+		minWidth: 0,
+		overflow: "hidden",
+		textOverflow: "ellipsis",
+		whiteSpace: "nowrap",
+		fontSize: `${props.fontSize}px`,
+		letterSpacing: "0.02em",
+		fontVariantLigatures: "none",
+		...props.color != null ? { color: props.color } : null
+	};
+	return createElement("div", { style: barStyle }, createElement("span", {
+		key: "lang",
+		style: labelStyle
+	}, props.label), createElement(CopyButton, {
+		key: "copy",
+		value: props.value,
+		fontSize: props.fontSize,
+		color: props.color,
+		borderColor: props.borderColor,
+		background: props.buttonBackground
+	}));
+}
 function renderCodeBlock(props) {
 	const pad = props.padding ?? 0;
 	const profile = props.highlight === false ? null : profileFor(props.lang);
+	const header = props.header;
 	const preStyle = {
 		margin: 0,
 		padding: `${pad}px`,
@@ -1385,7 +1509,10 @@ function renderCodeBlock(props) {
 		boxSizing: "border-box",
 		...props.background != null ? { background: props.background } : null,
 		...props.color != null ? { color: props.color } : null,
-		...props.radius != null ? { borderRadius: `${props.radius}px` } : null,
+		...props.radius != null ? header == null ? { borderRadius: `${props.radius}px` } : {
+			borderBottomLeftRadius: `${props.radius}px`,
+			borderBottomRightRadius: `${props.radius}px`
+		} : null,
 		...profile != null ? {
 			position: "relative",
 			tabSize: 8
@@ -1398,17 +1525,13 @@ function renderCodeBlock(props) {
 		margin: 0,
 		padding: 0
 	};
-	if (profile == null) return createElement("pre", {
-		className: props.className,
+	const pre = createElement("pre", {
+		...header == null ? { className: props.className } : null,
 		style: preStyle
-	}, createElement("code", {
+	}, profile == null ? createElement("code", {
 		style: codeStyle,
 		...props.lang ? { "data-lang": props.lang } : null
-	}, props.value));
-	return createElement("pre", {
-		className: props.className,
-		style: preStyle
-	}, createElement(HighlightedCode, {
+	}, props.value) : createElement(HighlightedCode, {
 		value: props.value,
 		lang: props.lang,
 		font: props.font,
@@ -1418,6 +1541,20 @@ function renderCodeBlock(props) {
 		colors: resolveTokenColors(props.highlight === false ? void 0 : props.highlight),
 		codeStyle
 	}));
+	if (header == null) return pre;
+	return createElement("div", { className: props.className }, createElement(CodeHeader, {
+		key: "header",
+		label: header.label ?? props.lang ?? "code",
+		value: props.value,
+		height: header.height,
+		fontSize: header.fontSize,
+		fontFamily: header.fontFamily ?? "monospace",
+		...props.radius != null ? { radius: props.radius } : null,
+		background: header.background,
+		color: header.color,
+		borderColor: header.borderColor,
+		buttonBackground: header.buttonBackground
+	}), pre);
 }
 /** A measurable fenced-code primitive (no wrapping; height from line count). */
 const CodeBlock = markPrimitive(renderCodeBlock, {
@@ -1631,7 +1768,16 @@ const defaultComponents = {
 			background: c.background,
 			radius: c.radius,
 			highlight: c.highlight,
-			...c.color !== "inherit" ? { color: c.color } : null
+			...c.color !== "inherit" ? { color: c.color } : null,
+			...c.header.show ? { header: {
+				height: c.header.height,
+				fontSize: c.header.fontSize,
+				fontFamily: ctx.theme.monoFamily,
+				background: c.header.background,
+				color: c.header.color,
+				borderColor: c.header.borderColor,
+				buttonBackground: c.header.buttonBackground
+			} } : null
 		});
 	},
 	list: ({ node, ctx }) => renderList(node, ctx),
@@ -1816,6 +1962,256 @@ function renderMarkdown(source, options = {}) {
 	return createContext(resolveTheme(options.theme), mergeComponents(options.components)).renderBlocks(ast.children);
 }
 //#endregion
+//#region src/primitives/fade.tsx
+/**
+* Streaming fade-in for `<Markdown fade>`.
+*
+* The same trick the code highlighter uses, pointed at motion instead of
+* colour: the markdown DOM commits and lays out instantly (so heights,
+* selection, and stick-to-bottom stay honest), and a background-coloured veil
+* is painted over just-arrived characters and dissolved — which *reads* as the
+* text fading in. Nothing about the row ever animates; layout is done the
+* moment the text lands.
+*
+* Unlike a list-level overlay, the veil canvas lives **inside** the markdown's
+* own box (`position: absolute; inset: 0`), so it scrolls with the content and
+* needs no viewport-geometry tracking. The painter idles (no rAF) until a
+* DOM mutation arrives, so leaving `fade` on for a settled block costs nothing.
+*/
+const EMA_SEED_MS = 160;
+const MIN_FADE_MS = 120;
+const MAX_FADE_MS = 400;
+const MAX_VEILS = 32;
+function commonPrefixLength(a, b) {
+	const n = Math.min(a.length, b.length);
+	let i = 0;
+	while (i < n && a.charCodeAt(i) === b.charCodeAt(i)) i++;
+	return i;
+}
+function inChrome(node, container) {
+	for (let p = node.parentElement; p != null && p !== container; p = p.parentElement) if (p.tagName === "BUTTON") return true;
+	return false;
+}
+function contentTextFilter(container) {
+	return { acceptNode: (n) => inChrome(n, container) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT };
+}
+/** `container.textContent`, minus interactive chrome (see {@link inChrome}). */
+function contentText(container) {
+	const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, contentTextFilter(container));
+	let s = "";
+	for (let n = walker.nextNode(); n != null; n = walker.nextNode()) s += n.data;
+	return s;
+}
+let scratch;
+function scratchCtx() {
+	if (scratch === void 0) {
+		const c = typeof document === "undefined" ? null : document.createElement("canvas");
+		if (c == null) return scratch = null;
+		c.width = 1;
+		c.height = 1;
+		scratch = c.getContext("2d", { willReadFrequently: true });
+	}
+	return scratch;
+}
+/** The opaque colour behind `el`: every ancestor's backgroundColor composited. */
+function effectiveBackground(el, cache) {
+	const cached = cache.get(el);
+	if (cached !== void 0) return cached;
+	const layers = [];
+	for (let cur = el; cur != null; cur = cur.parentElement) {
+		const bg = getComputedStyle(cur).backgroundColor;
+		if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") layers.push(bg);
+	}
+	const s = scratchCtx();
+	if (s == null) return "#808080";
+	s.globalAlpha = 1;
+	s.fillStyle = "#ffffff";
+	s.fillRect(0, 0, 1, 1);
+	for (let i = layers.length - 1; i >= 0; i--) {
+		try {
+			s.fillStyle = layers[i];
+		} catch {
+			continue;
+		}
+		s.fillRect(0, 0, 1, 1);
+	}
+	const d = s.getImageData(0, 0, 1, 1).data;
+	const css = `rgb(${d[0]}, ${d[1]}, ${d[2]})`;
+	cache.set(el, css);
+	return css;
+}
+/**
+* Paints the dissolving veil over a single content element's newly-arrived text.
+* Driven by a MutationObserver: a rAF loop runs only while veils are alive, then
+* stops until the next mutation, so an idle (settled) block uses no frames.
+*/
+var FadePainter = class {
+	content = null;
+	canvas = null;
+	ctx = null;
+	prevText = "";
+	veils = [];
+	ema = EMA_SEED_MS;
+	lastAppend = 0;
+	raf = 0;
+	running = false;
+	mo = null;
+	attach(content, canvas) {
+		if (typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+		const ctx = canvas.getContext("2d");
+		if (ctx == null) return;
+		this.content = content;
+		this.canvas = canvas;
+		this.ctx = ctx;
+		this.prevText = contentText(content);
+		this.mo = new MutationObserver(() => this.wake());
+		this.mo.observe(content, {
+			subtree: true,
+			childList: true,
+			characterData: true
+		});
+	}
+	destroy() {
+		this.mo?.disconnect();
+		this.mo = null;
+		if (this.raf !== 0) cancelAnimationFrame(this.raf);
+		this.raf = 0;
+		this.running = false;
+		this.content = null;
+		this.canvas = null;
+		this.ctx = null;
+	}
+	wake() {
+		if (this.running || this.content == null) return;
+		this.running = true;
+		this.raf = requestAnimationFrame(this.frame);
+	}
+	frame = () => {
+		const content = this.content;
+		const canvas = this.canvas;
+		const ctx = this.ctx;
+		if (content == null || canvas == null || ctx == null) {
+			this.running = false;
+			return;
+		}
+		const now = performance.now();
+		const text = contentText(content);
+		if (text !== this.prevText) {
+			const prefix = commonPrefixLength(this.prevText, text);
+			this.veils = this.veils.map((v) => ({
+				...v,
+				start: Math.min(v.start, prefix),
+				end: Math.min(v.end, prefix)
+			})).filter((v) => v.end > v.start);
+			if (text.length > prefix) {
+				if (this.lastAppend > 0) this.ema = this.ema * .7 + Math.min(now - this.lastAppend, 1e3) * .3;
+				this.lastAppend = now;
+				this.veils.push({
+					start: prefix,
+					end: text.length,
+					t0: now
+				});
+				if (this.veils.length > MAX_VEILS) this.veils.splice(0, this.veils.length - MAX_VEILS);
+			}
+			this.prevText = text;
+		}
+		const duration = Math.min(MAX_FADE_MS, Math.max(MIN_FADE_MS, this.ema * 3));
+		const boost = 1 + .3 * Math.max(0, this.veils.length - 2);
+		this.veils = this.veils.filter((v) => (now - v.t0) * boost < duration);
+		const dpr = typeof devicePixelRatio === "number" && devicePixelRatio > 0 ? devicePixelRatio : 1;
+		const w = content.clientWidth;
+		const h = content.clientHeight;
+		if (canvas.width !== Math.round(w * dpr) || canvas.height !== Math.round(h * dpr)) {
+			canvas.width = Math.round(w * dpr);
+			canvas.height = Math.round(h * dpr);
+		}
+		ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+		ctx.clearRect(0, 0, w, h);
+		if (this.veils.length > 0) {
+			const origin = canvas.getBoundingClientRect();
+			const bgCache = /* @__PURE__ */ new Map();
+			const groups = /* @__PURE__ */ new Map();
+			const minStart = this.veils.reduce((m, v) => Math.min(m, v.start), Infinity);
+			const walker = document.createTreeWalker(content, NodeFilter.SHOW_TEXT, contentTextFilter(content));
+			let base = 0;
+			let node = walker.nextNode();
+			while (node != null) {
+				const len = node.data.length;
+				if (len > 0 && base + len > minStart) for (let vi = 0; vi < this.veils.length; vi++) {
+					const v = this.veils[vi];
+					const s = Math.max(v.start - base, 0);
+					const e = Math.min(v.end - base, len);
+					if (e <= s) continue;
+					const parent = node.parentElement;
+					if (parent == null) continue;
+					const bg = effectiveBackground(parent, bgCache);
+					const key = `${vi}|${bg}`;
+					let group = groups.get(key);
+					if (group === void 0) {
+						const p = Math.min(1, (now - v.t0) * boost / duration);
+						group = {
+							alpha: Math.pow(1 - p, 1.6),
+							bg,
+							path: new Path2D()
+						};
+						groups.set(key, group);
+					}
+					const range = document.createRange();
+					range.setStart(node, s);
+					range.setEnd(node, e);
+					for (const r of range.getClientRects()) group.path.rect(r.left - origin.left - 1, r.top - origin.top - 1, r.width + 2, r.height + 2);
+				}
+				base += len;
+				node = walker.nextNode();
+			}
+			for (const group of groups.values()) {
+				ctx.globalAlpha = group.alpha;
+				ctx.fillStyle = group.bg;
+				ctx.fill(group.path);
+			}
+			ctx.globalAlpha = 1;
+		}
+		if (this.veils.length > 0) this.raf = requestAnimationFrame(this.frame);
+		else {
+			this.running = false;
+			this.raf = 0;
+		}
+	};
+};
+function renderFadeMarkdown(props) {
+	const contentRef = useRef(null);
+	const canvasRef = useRef(null);
+	useEffect(() => {
+		const content = contentRef.current;
+		const canvas = canvasRef.current;
+		if (content == null || canvas == null) return;
+		const painter = new FadePainter();
+		painter.attach(content, canvas);
+		return () => painter.destroy();
+	}, []);
+	return createElement("div", { style: { position: "relative" } }, createElement("div", { ref: contentRef }, props.children), createElement("canvas", {
+		ref: canvasRef,
+		"aria-hidden": true,
+		style: {
+			position: "absolute",
+			inset: 0,
+			width: "100%",
+			height: "100%",
+			pointerEvents: "none"
+		}
+	}));
+}
+/**
+* Wraps a measured markdown subtree with a streaming fade-in canvas. Its height
+* is exactly the subtree's height — the canvas overlay is out of flow and never
+* measured.
+*/
+const FadeMarkdown = markPrimitive(renderFadeMarkdown, {
+	name: "FadeMarkdown",
+	measure: (props, ctx) => measureChildren(props.children, ctx),
+	naturalWidth: (props, ctx) => naturalWidthOf(props.children, ctx)
+});
+//#endregion
 //#region src/markdown.tsx
 /**
 * Render markdown as a tree of mugen primitives.
@@ -1838,7 +2234,9 @@ function renderMarkdown(source, options = {}) {
 * and a deep-partial `theme`.
 */
 function Markdown(props) {
-	return renderMarkdown(props.source, props);
+	const content = renderMarkdown(props.source, props);
+	if (props.fade && content != null) return createElement(FadeMarkdown, null, content);
+	return content;
 }
 Markdown.displayName = "Markdown";
 //#endregion
@@ -1858,4 +2256,4 @@ function defineMarkdownComponents(components) {
 	return components;
 }
 //#endregion
-export { CodeBlock, HStack, Markdown, RichText, TableBlock, Text, VStack, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };
+export { CodeBlock, FadeMarkdown, HStack, Markdown, RichText, TableBlock, Text, VStack, baseFormat, clearParseCache, clearRichTextCache, composeFont, defaultComponents, defaultTheme, defaultTokenColors, defineMarkdownComponents, definePrimitive, flattenInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wingleeio/mugen-markdown",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Measurable markdown for mugen — incremark-parsed, rendered with mugen primitives so the virtualizer's tree walker computes exact row heights.",
   "license": "MIT",
   "author": "Wing Lee <contact@winglee.io>",
@@ -65,7 +65,7 @@
     "tsdown": "^0.22.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8",
-    "@wingleeio/mugen": "0.3.0"
+    "@wingleeio/mugen": "0.3.4"
   },
   "scripts": {
     "build": "tsdown",