@wingleeio/mugen-markdown 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -1963,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.
@@ -1985,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
@@ -2006,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

@@ -369,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.
@@ -496,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
@@ -537,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 CodeBlockHeader, 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

@@ -369,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.
@@ -496,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
@@ -537,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 CodeBlockHeader, 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, 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, naturalWidthOf } from "@wingleeio/mugen";
+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
@@ -1962,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.
@@ -1984,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
@@ -2004,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.2.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>",