@wingleeio/mugen-markdown 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -227,120 +227,6 @@ function resolveTheme(theme) {
 	return resolved;
 }
 //#endregion
-//#region src/inline.ts
-/** A base format for body text at a given size/weight/colour. */
-function baseFormat(theme, opts = {}) {
-	return {
-		family: theme.fontFamily,
-		monoFamily: theme.monoFamily,
-		size: opts.size ?? theme.fontSize,
-		weight: opts.weight ?? 400,
-		italic: false,
-		mono: false,
-		underline: false,
-		strike: false,
-		color: opts.color ?? (theme.color !== "inherit" ? theme.color : void 0)
-	};
-}
-/** Compose a measurable `Font` shorthand from a format. */
-function composeFont(fmt) {
-	const family = fmt.mono ? fmt.monoFamily : fmt.family;
-	return `${fmt.italic ? "italic " : ""}${fmt.weight} ${fmt.size}px ${family}`;
-}
-function pushRun(out, text, fmt) {
-	if (text.length === 0) return;
-	const run = {
-		text,
-		font: composeFont(fmt)
-	};
-	if (fmt.color != null) run.color = fmt.color;
-	if (fmt.background != null) run.background = fmt.background;
-	const decoration = [fmt.underline ? "underline" : "", fmt.strike ? "line-through" : ""].filter(Boolean).join(" ");
-	if (decoration) run.decoration = decoration;
-	if (fmt.href != null) {
-		run.href = fmt.href;
-		run.as = "a";
-	} else if (fmt.mono) run.as = "code";
-	out.push(run);
-}
-/**
-* Flatten phrasing content into styled runs. Recursive over the inline marks;
-* the result feeds a single `<RichText>` so the whole paragraph wraps as one
-* flow and measures exactly.
-*/
-function flattenInline(nodes, fmt, theme, out) {
-	for (const node of nodes) switch (node.type) {
-		case "text":
-			pushRun(out, node.value, fmt);
-			break;
-		case "strong":
-			flattenInline(node.children, {
-				...fmt,
-				weight: theme.strongWeight
-			}, theme, out);
-			break;
-		case "emphasis":
-			flattenInline(node.children, {
-				...fmt,
-				italic: theme.emphasisItalic ? true : fmt.italic
-			}, theme, out);
-			break;
-		case "delete":
-			flattenInline(node.children, {
-				...fmt,
-				strike: true
-			}, theme, out);
-			break;
-		case "inlineCode":
-			pushRun(out, node.value, {
-				...fmt,
-				mono: true,
-				size: Math.round(fmt.size * theme.inlineCode.sizeScale),
-				color: theme.inlineCode.color !== "inherit" ? theme.inlineCode.color : fmt.color,
-				background: theme.inlineCode.background
-			});
-			break;
-		case "link":
-			flattenInline(node.children, {
-				...fmt,
-				href: node.url,
-				color: theme.link.color,
-				underline: theme.link.underline ? true : fmt.underline
-			}, theme, out);
-			break;
-		case "linkReference":
-			flattenInline(node.children, fmt, theme, out);
-			break;
-		case "break":
-			out.push({
-				text: "",
-				break: true
-			});
-			break;
-		case "image":
-			if (node.alt) pushRun(out, node.alt, {
-				...fmt,
-				color: theme.image.color
-			});
-			break;
-		case "imageReference":
-			if (node.alt) pushRun(out, node.alt, {
-				...fmt,
-				color: theme.image.color
-			});
-			break;
-		case "footnoteReference":
-			pushRun(out, `[${node.label ?? node.identifier}]`, {
-				...fmt,
-				color: theme.link.color
-			});
-			break;
-		default:
-			if ("children" in node && Array.isArray(node.children)) flattenInline(node.children, fmt, theme, out);
-			break;
-	}
-}
-//#endregion
 //#region src/primitives/rich-text.tsx
 function resolveRunFont(run, fallback) {
 	const font = run.font ?? fallback;
@@ -348,6 +234,7 @@ function resolveRunFont(run, fallback) {
 	(0, _wingleeio_mugen.assertMeasurableFont)(font);
 	return font;
 }
+const BOX_PLACEHOLDER = "‌";
 /** Split runs into hard-break-delimited segments, each a list of rich-inline items. */
 function segmentItems(runs, fallback) {
 	const segments = [];
@@ -358,9 +245,19 @@ function segmentItems(runs, fallback) {
 			cur = [];
 			continue;
 		}
-		if (run.text.length === 0) continue;
+		if (run.advance != null) {
+			cur.push({
+				text: BOX_PLACEHOLDER,
+				font: resolveRunFont(run, fallback),
+				extraWidth: Math.max(0, run.advance),
+				break: "never"
+			});
+			continue;
+		}
+		const text = run.text ?? "";
+		if (text.length === 0) continue;
 		const item = {
-			text: run.text,
+			text,
 			font: resolveRunFont(run, fallback)
 		};
 		if (run.letterSpacing != null) item.letterSpacing = run.letterSpacing;
@@ -425,6 +322,15 @@ function renderRichText(props) {
 	};
 	const children = props.runs.map((run, i) => {
 		if (run.break) return (0, react.createElement)("br", { key: i });
+		if (run.advance != null) return (0, react.createElement)("span", {
+			key: i,
+			style: {
+				display: "inline-block",
+				verticalAlign: "middle",
+				lineHeight: 0,
+				whiteSpace: "nowrap"
+			}
+		}, run.content);
 		const tag = run.as ?? (run.href != null ? "a" : "span");
 		const elementProps = {
 			key: i,
@@ -443,7 +349,7 @@ function renderRichText(props) {
 		if (run.title != null) elementProps.title = run.title;
 		if (run.onClick != null) elementProps.onClick = run.onClick;
 		if (run.className != null) elementProps.className = run.className;
-		return (0, react.createElement)(tag, elementProps, run.text);
+		return (0, react.createElement)(tag, elementProps, run.text ?? "");
 	});
 	return (0, react.createElement)("div", {
 		className: props.className,
@@ -471,12 +377,173 @@ const RichText = (0, _wingleeio_mugen.markPrimitive)(renderRichText, {
 		return max;
 	}
 });
+/**
+* Measure a string's rendered advance in px for a given measurable font — the
+* same ruler `RichText` measures with. Use it to size an inline box: a text
+* "pill" reserves `measureInline(label, font) + horizontalPadding`.
+*/
+function measureInline(text, font) {
+	if (text.length === 0) return 0;
+	(0, _wingleeio_mugen.assertMeasurableFont)(font);
+	return (0, _chenglou_pretext_rich_inline.measureRichInlineStats)(prepareCached([{
+		text,
+		font
+	}]), 1e7).maxLineWidth;
+}
 /** Drop the rich-inline prepare cache (tests / memory pressure). */
 function clearRichTextCache() {
 	prepCache.clear();
 	cacheEpoch = -1;
 }
 //#endregion
+//#region src/inline.ts
+/** A base format for body text at a given size/weight/colour. */
+function baseFormat(theme, opts = {}) {
+	return {
+		family: theme.fontFamily,
+		monoFamily: theme.monoFamily,
+		size: opts.size ?? theme.fontSize,
+		weight: opts.weight ?? 400,
+		italic: false,
+		mono: false,
+		underline: false,
+		strike: false,
+		color: opts.color ?? (theme.color !== "inherit" ? theme.color : void 0)
+	};
+}
+/** Compose a measurable `Font` shorthand from a format. */
+function composeFont(fmt) {
+	const family = fmt.mono ? fmt.monoFamily : fmt.family;
+	return `${fmt.italic ? "italic " : ""}${fmt.weight} ${fmt.size}px ${family}`;
+}
+function pushRun(out, text, fmt) {
+	if (text.length === 0) return;
+	const run = {
+		text,
+		font: composeFont(fmt)
+	};
+	if (fmt.color != null) run.color = fmt.color;
+	if (fmt.background != null) run.background = fmt.background;
+	const decoration = [fmt.underline ? "underline" : "", fmt.strike ? "line-through" : ""].filter(Boolean).join(" ");
+	if (decoration) run.decoration = decoration;
+	if (fmt.href != null) {
+		run.href = fmt.href;
+		run.as = "a";
+	} else if (fmt.mono) run.as = "code";
+	out.push(run);
+}
+/** Build the context handed to an inline override. */
+function makeInlineCtx(fmt, theme, inline) {
+	return {
+		theme,
+		fmt,
+		font: (overrides) => composeFont(overrides ? {
+			...fmt,
+			...overrides
+		} : fmt),
+		measure: (text, font) => measureInline(text, font),
+		runs: (nodes, fmtOverrides) => {
+			const sub = [];
+			flattenInline(nodes, fmtOverrides ? {
+				...fmt,
+				...fmtOverrides
+			} : fmt, theme, sub, inline);
+			return sub;
+		}
+	};
+}
+/**
+* Flatten phrasing content into styled runs. Recursive over the inline marks;
+* the result feeds a single `<RichText>` so the whole paragraph wraps as one
+* flow and measures exactly. An `inline` override map can replace how any node
+* type flattens — returning its own runs (e.g. a measured inline box) or `null`
+* to fall through to the default.
+*/
+function flattenInline(nodes, fmt, theme, out, inline) {
+	for (const node of nodes) {
+		if (inline != null) {
+			const override = inline[node.type];
+			if (override != null) {
+				const produced = override(node, makeInlineCtx(fmt, theme, inline));
+				if (produced != null) {
+					for (const run of produced) out.push(run);
+					continue;
+				}
+			}
+		}
+		switch (node.type) {
+			case "text":
+				pushRun(out, node.value, fmt);
+				break;
+			case "strong":
+				flattenInline(node.children, {
+					...fmt,
+					weight: theme.strongWeight
+				}, theme, out, inline);
+				break;
+			case "emphasis":
+				flattenInline(node.children, {
+					...fmt,
+					italic: theme.emphasisItalic ? true : fmt.italic
+				}, theme, out, inline);
+				break;
+			case "delete":
+				flattenInline(node.children, {
+					...fmt,
+					strike: true
+				}, theme, out, inline);
+				break;
+			case "inlineCode":
+				pushRun(out, node.value, {
+					...fmt,
+					mono: true,
+					size: Math.round(fmt.size * theme.inlineCode.sizeScale),
+					color: theme.inlineCode.color !== "inherit" ? theme.inlineCode.color : fmt.color,
+					background: theme.inlineCode.background
+				});
+				break;
+			case "link":
+				flattenInline(node.children, {
+					...fmt,
+					href: node.url,
+					color: theme.link.color,
+					underline: theme.link.underline ? true : fmt.underline
+				}, theme, out, inline);
+				break;
+			case "linkReference":
+				flattenInline(node.children, fmt, theme, out, inline);
+				break;
+			case "break":
+				out.push({
+					text: "",
+					break: true
+				});
+				break;
+			case "image":
+				if (node.alt) pushRun(out, node.alt, {
+					...fmt,
+					color: theme.image.color
+				});
+				break;
+			case "imageReference":
+				if (node.alt) pushRun(out, node.alt, {
+					...fmt,
+					color: theme.image.color
+				});
+				break;
+			case "footnoteReference":
+				pushRun(out, `[${node.label ?? node.identifier}]`, {
+					...fmt,
+					color: theme.link.color
+				});
+				break;
+			default:
+				if ("children" in node && Array.isArray(node.children)) flattenInline(node.children, fmt, theme, out, inline);
+				break;
+		}
+	}
+}
+//#endregion
 //#region src/highlight/languages.ts
 function words(s) {
 	return new Set(s.split(" "));
@@ -1930,7 +1997,7 @@ function createContext(theme, components) {
 				...base
 			};
 			const out = [];
-			flattenInline(nodes, fmt, theme, out);
+			flattenInline(nodes, fmt, theme, out, components.inline);
 			return out;
 		},
 		inlineText(nodes, opts = {}) {
@@ -1940,7 +2007,7 @@ function createContext(theme, components) {
 				...opts.color != null ? { color: opts.color } : null
 			});
 			const out = [];
-			flattenInline(nodes, fmt, theme, out);
+			flattenInline(nodes, fmt, theme, out, components.inline);
 			return (0, react.createElement)(RichText, {
 				runs: out,
 				font: composeFont(fmt),
@@ -2295,6 +2362,7 @@ Object.defineProperty(exports, "definePrimitive", {
 	}
 });
 exports.flattenInline = flattenInline;
+exports.measureInline = measureInline;
 exports.parseMarkdown = parseMarkdown;
 exports.profileFor = profileFor;
 exports.registerLanguage = registerLanguage;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { CSSProperties, JSX, ReactElement, ReactNode } from "react";
 import { ParserOptions } from "@incremark/core";
-import { Blockquote, Blockquote as Blockquote$1, Code, Code as Code$1, Heading, Heading as Heading$1, Html, Html as Html$1, Image, Image as Image$1, Link, List, List as List$1, ListItem, Paragraph, Paragraph as Paragraph$1, PhrasingContent, PhrasingContent as PhrasingContent$1, Root, Root as Root$1, RootContent, RootContent as RootContent$1, Table, Table as Table$1, TableCell, TableRow, ThematicBreak, ThematicBreak as ThematicBreak$1 } from "mdast";
+import { Blockquote, Blockquote as Blockquote$1, Code, Code as Code$1, Delete, Emphasis, Heading, Heading as Heading$1, Html, Html as Html$1, Image, Image as Image$1, InlineCode, Link, Link as Link$1, List, List as List$1, ListItem, Paragraph, Paragraph as Paragraph$1, PhrasingContent, PhrasingContent as PhrasingContent$1, Root, Root as Root$1, RootContent, RootContent as RootContent$1, Strong, Table, Table as Table$1, TableCell, TableRow, Text as Text$1, ThematicBreak, ThematicBreak as ThematicBreak$1 } from "mdast";
 import { BoxProps, Font, Font as Font$1, HStack, HStackProps, MeasurableStyle, PrimitiveComponent, SafeClassName, Text, TextProps, VStack, VStackProps, definePrimitive } from "@wingleeio/mugen";
 
 //#region src/parse.d.ts
@@ -175,8 +175,19 @@ declare function resolveTheme(theme?: DeepPartial<MarkdownTheme>): MarkdownTheme
  * rich-inline layout) and the painted spans use the identical fonts.
  */
 interface RichTextRun {
-  /** The run's text. Ignored when `break` is set. */
-  text: string;
+  /** The run's text. Ignored when `break` or `advance` is set. */
+  text?: string;
+  /**
+   * Render this run as an **inline box** — the inline analogue of mugen's
+   * `Escape`: it reserves exactly `advance` px in the flow (via pretext's
+   * `extraWidth`) and paints {@link content}, whatever it is, without measuring
+   * its insides. The flow wraps it as one non-breaking atom. The caller owns the
+   * contract: `content` must render exactly `advance` px wide and no taller than
+   * the line (use the exported `measureInline` to size text-based boxes).
+   */
+  advance?: number;
+  /** The painted content of an inline box (see {@link advance}). */
+  content?: ReactNode;
   /** Measurable font for this run; falls back to the `<RichText font>` prop. */
   font?: Font$1;
   color?: string;
@@ -217,6 +228,12 @@ interface RichTextProps<C extends string = string> {
  * performs over the rendered spans, so the analytic height matches the paint.
  */
 declare const RichText: <C extends string = string>(props: RichTextProps<C>) => ReactElement;
+/**
+ * Measure a string's rendered advance in px for a given measurable font — the
+ * same ruler `RichText` measures with. Use it to size an inline box: a text
+ * "pill" reserves `measureInline(label, font) + horizontalPadding`.
+ */
+declare function measureInline(text: string, font: Font$1): number;
 /** Drop the rich-inline prepare cache (tests / memory pressure). */
 declare function clearRichTextCache(): void;
 //#endregion
@@ -252,9 +269,11 @@ declare function composeFont(fmt: InlineFormat): Font$1;
 /**
  * Flatten phrasing content into styled runs. Recursive over the inline marks;
  * the result feeds a single `<RichText>` so the whole paragraph wraps as one
- * flow and measures exactly.
+ * flow and measures exactly. An `inline` override map can replace how any node
+ * type flattens — returning its own runs (e.g. a measured inline box) or `null`
+ * to fall through to the default.
  */
-declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[]): void;
+declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[], inline?: InlineComponents): void;
 //#endregion
 //#region src/types.d.ts
 /** Options for building a body/heading inline-text (`RichText`) element. */
@@ -315,10 +334,49 @@ interface MarkdownComponentProps<N> {
  */
 type MarkdownComponent<N> = (props: MarkdownComponentProps<N>) => ReactNode;
 /**
- * The overridable block-level components, keyed by mdast node type and typed to
- * the matching node. Inline marks (bold, italic, code, links) are styled through
- * the {@link MarkdownTheme} rather than as components, because inline content
- * must collapse into a single wrapping flow to be measured exactly.
+ * The context passed to an inline override. It carries the active inline format
+ * (so an override can match the surrounding type) and the helpers to build runs
+ * that stay exactly measurable.
+ */
+interface InlineRenderContext {
+  readonly theme: MarkdownTheme;
+  /** The composed inline format at this node (family, size, weight, colour…). */
+  readonly fmt: InlineFormat;
+  /** Compose a measurable `Font` from the current format plus overrides. */
+  font(overrides?: Partial<InlineFormat>): Font$1;
+  /**
+   * Measure a string's rendered advance in px for a font — to size an inline
+   * box. A text pill reserves `measure(label, font) + horizontalPadding`.
+   */
+  measure(text: string, font: Font$1): number;
+  /** Default-flatten phrasing children into runs, to compose with your own. */
+  runs(nodes: readonly PhrasingContent$1[], fmtOverrides?: Partial<InlineFormat>): RichTextRun[];
+}
+/**
+ * An inline-node override: given the mdast node and the inline context, return
+ * the runs it should flatten to — styled text, an inline box (`{ advance,
+ * content }`), or a mix — or `null` to fall back to the default styling.
+ */
+type InlineComponent<N> = (node: N, ctx: InlineRenderContext) => RichTextRun[] | null;
+/**
+ * Inline-node overrides, keyed by mdast inline type. The index signature admits
+ * custom inline tokens (from a remark plugin) beyond the named ones.
+ */
+interface InlineComponents {
+  text?: InlineComponent<Text$1>;
+  strong?: InlineComponent<Strong>;
+  emphasis?: InlineComponent<Emphasis>;
+  delete?: InlineComponent<Delete>;
+  inlineCode?: InlineComponent<InlineCode>;
+  link?: InlineComponent<Link$1>;
+  [type: string]: InlineComponent<any> | undefined;
+}
+/**
+ * The overridable components. Block-level marks are keyed by mdast node type and
+ * typed to the matching node. Inline marks (bold, italic, code, links) are
+ * styled through the {@link MarkdownTheme} by default, but `inline` lets you
+ * override how an inline node flattens into runs — including a measured inline
+ * box (`{ advance, content }`), the inline twin of mugen's `Escape`.
  */
 interface MarkdownComponents {
   paragraph?: MarkdownComponent<Paragraph$1>;
@@ -330,8 +388,13 @@ interface MarkdownComponents {
   table?: MarkdownComponent<Table$1>;
   image?: MarkdownComponent<Image$1>;
   html?: MarkdownComponent<Html$1>;
+  /** Inline-node overrides (see {@link InlineComponents}). */
+  inline?: InlineComponents;
 }
-type ResolvedMarkdownComponents = Required<MarkdownComponents>;
+/** Block components resolve to defaults; `inline` stays optional. */
+type ResolvedMarkdownComponents = Required<Omit<MarkdownComponents, 'inline'>> & {
+  inline?: InlineComponents;
+};
 /**
  * Identity helper for authoring a typed component set with full inference and
  * `node` narrowing per key:
@@ -556,4 +619,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, 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 };
+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 InlineComponent, type InlineComponents, type InlineFormat, type InlineRenderContext, 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, measureInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { CSSProperties, JSX, ReactElement, ReactNode } from "react";
 import { BoxProps, Font, Font as Font$1, HStack, HStackProps, MeasurableStyle, PrimitiveComponent, SafeClassName, Text, TextProps, VStack, VStackProps, definePrimitive } from "@wingleeio/mugen";
 import { ParserOptions } from "@incremark/core";
-import { Blockquote, Blockquote as Blockquote$1, Code, Code as Code$1, Heading, Heading as Heading$1, Html, Html as Html$1, Image, Image as Image$1, Link, List, List as List$1, ListItem, Paragraph, Paragraph as Paragraph$1, PhrasingContent, PhrasingContent as PhrasingContent$1, Root, Root as Root$1, RootContent, RootContent as RootContent$1, Table, Table as Table$1, TableCell, TableRow, ThematicBreak, ThematicBreak as ThematicBreak$1 } from "mdast";
+import { Blockquote, Blockquote as Blockquote$1, Code, Code as Code$1, Delete, Emphasis, Heading, Heading as Heading$1, Html, Html as Html$1, Image, Image as Image$1, InlineCode, Link, Link as Link$1, List, List as List$1, ListItem, Paragraph, Paragraph as Paragraph$1, PhrasingContent, PhrasingContent as PhrasingContent$1, Root, Root as Root$1, RootContent, RootContent as RootContent$1, Strong, Table, Table as Table$1, TableCell, TableRow, Text as Text$1, ThematicBreak, ThematicBreak as ThematicBreak$1 } from "mdast";
 
 //#region src/parse.d.ts
 /**
@@ -175,8 +175,19 @@ declare function resolveTheme(theme?: DeepPartial<MarkdownTheme>): MarkdownTheme
  * rich-inline layout) and the painted spans use the identical fonts.
  */
 interface RichTextRun {
-  /** The run's text. Ignored when `break` is set. */
-  text: string;
+  /** The run's text. Ignored when `break` or `advance` is set. */
+  text?: string;
+  /**
+   * Render this run as an **inline box** — the inline analogue of mugen's
+   * `Escape`: it reserves exactly `advance` px in the flow (via pretext's
+   * `extraWidth`) and paints {@link content}, whatever it is, without measuring
+   * its insides. The flow wraps it as one non-breaking atom. The caller owns the
+   * contract: `content` must render exactly `advance` px wide and no taller than
+   * the line (use the exported `measureInline` to size text-based boxes).
+   */
+  advance?: number;
+  /** The painted content of an inline box (see {@link advance}). */
+  content?: ReactNode;
   /** Measurable font for this run; falls back to the `<RichText font>` prop. */
   font?: Font$1;
   color?: string;
@@ -217,6 +228,12 @@ interface RichTextProps<C extends string = string> {
  * performs over the rendered spans, so the analytic height matches the paint.
  */
 declare const RichText: <C extends string = string>(props: RichTextProps<C>) => ReactElement;
+/**
+ * Measure a string's rendered advance in px for a given measurable font — the
+ * same ruler `RichText` measures with. Use it to size an inline box: a text
+ * "pill" reserves `measureInline(label, font) + horizontalPadding`.
+ */
+declare function measureInline(text: string, font: Font$1): number;
 /** Drop the rich-inline prepare cache (tests / memory pressure). */
 declare function clearRichTextCache(): void;
 //#endregion
@@ -252,9 +269,11 @@ declare function composeFont(fmt: InlineFormat): Font$1;
 /**
  * Flatten phrasing content into styled runs. Recursive over the inline marks;
  * the result feeds a single `<RichText>` so the whole paragraph wraps as one
- * flow and measures exactly.
+ * flow and measures exactly. An `inline` override map can replace how any node
+ * type flattens — returning its own runs (e.g. a measured inline box) or `null`
+ * to fall through to the default.
  */
-declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[]): void;
+declare function flattenInline(nodes: readonly PhrasingContent$1[], fmt: InlineFormat, theme: MarkdownTheme, out: RichTextRun[], inline?: InlineComponents): void;
 //#endregion
 //#region src/types.d.ts
 /** Options for building a body/heading inline-text (`RichText`) element. */
@@ -315,10 +334,49 @@ interface MarkdownComponentProps<N> {
  */
 type MarkdownComponent<N> = (props: MarkdownComponentProps<N>) => ReactNode;
 /**
- * The overridable block-level components, keyed by mdast node type and typed to
- * the matching node. Inline marks (bold, italic, code, links) are styled through
- * the {@link MarkdownTheme} rather than as components, because inline content
- * must collapse into a single wrapping flow to be measured exactly.
+ * The context passed to an inline override. It carries the active inline format
+ * (so an override can match the surrounding type) and the helpers to build runs
+ * that stay exactly measurable.
+ */
+interface InlineRenderContext {
+  readonly theme: MarkdownTheme;
+  /** The composed inline format at this node (family, size, weight, colour…). */
+  readonly fmt: InlineFormat;
+  /** Compose a measurable `Font` from the current format plus overrides. */
+  font(overrides?: Partial<InlineFormat>): Font$1;
+  /**
+   * Measure a string's rendered advance in px for a font — to size an inline
+   * box. A text pill reserves `measure(label, font) + horizontalPadding`.
+   */
+  measure(text: string, font: Font$1): number;
+  /** Default-flatten phrasing children into runs, to compose with your own. */
+  runs(nodes: readonly PhrasingContent$1[], fmtOverrides?: Partial<InlineFormat>): RichTextRun[];
+}
+/**
+ * An inline-node override: given the mdast node and the inline context, return
+ * the runs it should flatten to — styled text, an inline box (`{ advance,
+ * content }`), or a mix — or `null` to fall back to the default styling.
+ */
+type InlineComponent<N> = (node: N, ctx: InlineRenderContext) => RichTextRun[] | null;
+/**
+ * Inline-node overrides, keyed by mdast inline type. The index signature admits
+ * custom inline tokens (from a remark plugin) beyond the named ones.
+ */
+interface InlineComponents {
+  text?: InlineComponent<Text$1>;
+  strong?: InlineComponent<Strong>;
+  emphasis?: InlineComponent<Emphasis>;
+  delete?: InlineComponent<Delete>;
+  inlineCode?: InlineComponent<InlineCode>;
+  link?: InlineComponent<Link$1>;
+  [type: string]: InlineComponent<any> | undefined;
+}
+/**
+ * The overridable components. Block-level marks are keyed by mdast node type and
+ * typed to the matching node. Inline marks (bold, italic, code, links) are
+ * styled through the {@link MarkdownTheme} by default, but `inline` lets you
+ * override how an inline node flattens into runs — including a measured inline
+ * box (`{ advance, content }`), the inline twin of mugen's `Escape`.
  */
 interface MarkdownComponents {
   paragraph?: MarkdownComponent<Paragraph$1>;
@@ -330,8 +388,13 @@ interface MarkdownComponents {
   table?: MarkdownComponent<Table$1>;
   image?: MarkdownComponent<Image$1>;
   html?: MarkdownComponent<Html$1>;
+  /** Inline-node overrides (see {@link InlineComponents}). */
+  inline?: InlineComponents;
 }
-type ResolvedMarkdownComponents = Required<MarkdownComponents>;
+/** Block components resolve to defaults; `inline` stays optional. */
+type ResolvedMarkdownComponents = Required<Omit<MarkdownComponents, 'inline'>> & {
+  inline?: InlineComponents;
+};
 /**
  * Identity helper for authoring a typed component set with full inference and
  * `node` narrowing per key:
@@ -556,4 +619,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, 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 };
+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 InlineComponent, type InlineComponents, type InlineFormat, type InlineRenderContext, 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, measureInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };

package/dist/index.mjs

@@ -226,120 +226,6 @@ function resolveTheme(theme) {
 	return resolved;
 }
 //#endregion
-//#region src/inline.ts
-/** A base format for body text at a given size/weight/colour. */
-function baseFormat(theme, opts = {}) {
-	return {
-		family: theme.fontFamily,
-		monoFamily: theme.monoFamily,
-		size: opts.size ?? theme.fontSize,
-		weight: opts.weight ?? 400,
-		italic: false,
-		mono: false,
-		underline: false,
-		strike: false,
-		color: opts.color ?? (theme.color !== "inherit" ? theme.color : void 0)
-	};
-}
-/** Compose a measurable `Font` shorthand from a format. */
-function composeFont(fmt) {
-	const family = fmt.mono ? fmt.monoFamily : fmt.family;
-	return `${fmt.italic ? "italic " : ""}${fmt.weight} ${fmt.size}px ${family}`;
-}
-function pushRun(out, text, fmt) {
-	if (text.length === 0) return;
-	const run = {
-		text,
-		font: composeFont(fmt)
-	};
-	if (fmt.color != null) run.color = fmt.color;
-	if (fmt.background != null) run.background = fmt.background;
-	const decoration = [fmt.underline ? "underline" : "", fmt.strike ? "line-through" : ""].filter(Boolean).join(" ");
-	if (decoration) run.decoration = decoration;
-	if (fmt.href != null) {
-		run.href = fmt.href;
-		run.as = "a";
-	} else if (fmt.mono) run.as = "code";
-	out.push(run);
-}
-/**
-* Flatten phrasing content into styled runs. Recursive over the inline marks;
-* the result feeds a single `<RichText>` so the whole paragraph wraps as one
-* flow and measures exactly.
-*/
-function flattenInline(nodes, fmt, theme, out) {
-	for (const node of nodes) switch (node.type) {
-		case "text":
-			pushRun(out, node.value, fmt);
-			break;
-		case "strong":
-			flattenInline(node.children, {
-				...fmt,
-				weight: theme.strongWeight
-			}, theme, out);
-			break;
-		case "emphasis":
-			flattenInline(node.children, {
-				...fmt,
-				italic: theme.emphasisItalic ? true : fmt.italic
-			}, theme, out);
-			break;
-		case "delete":
-			flattenInline(node.children, {
-				...fmt,
-				strike: true
-			}, theme, out);
-			break;
-		case "inlineCode":
-			pushRun(out, node.value, {
-				...fmt,
-				mono: true,
-				size: Math.round(fmt.size * theme.inlineCode.sizeScale),
-				color: theme.inlineCode.color !== "inherit" ? theme.inlineCode.color : fmt.color,
-				background: theme.inlineCode.background
-			});
-			break;
-		case "link":
-			flattenInline(node.children, {
-				...fmt,
-				href: node.url,
-				color: theme.link.color,
-				underline: theme.link.underline ? true : fmt.underline
-			}, theme, out);
-			break;
-		case "linkReference":
-			flattenInline(node.children, fmt, theme, out);
-			break;
-		case "break":
-			out.push({
-				text: "",
-				break: true
-			});
-			break;
-		case "image":
-			if (node.alt) pushRun(out, node.alt, {
-				...fmt,
-				color: theme.image.color
-			});
-			break;
-		case "imageReference":
-			if (node.alt) pushRun(out, node.alt, {
-				...fmt,
-				color: theme.image.color
-			});
-			break;
-		case "footnoteReference":
-			pushRun(out, `[${node.label ?? node.identifier}]`, {
-				...fmt,
-				color: theme.link.color
-			});
-			break;
-		default:
-			if ("children" in node && Array.isArray(node.children)) flattenInline(node.children, fmt, theme, out);
-			break;
-	}
-}
-//#endregion
 //#region src/primitives/rich-text.tsx
 function resolveRunFont(run, fallback) {
 	const font = run.font ?? fallback;
@@ -347,6 +233,7 @@ function resolveRunFont(run, fallback) {
 	assertMeasurableFont(font);
 	return font;
 }
+const BOX_PLACEHOLDER = "‌";
 /** Split runs into hard-break-delimited segments, each a list of rich-inline items. */
 function segmentItems(runs, fallback) {
 	const segments = [];
@@ -357,9 +244,19 @@ function segmentItems(runs, fallback) {
 			cur = [];
 			continue;
 		}
-		if (run.text.length === 0) continue;
+		if (run.advance != null) {
+			cur.push({
+				text: BOX_PLACEHOLDER,
+				font: resolveRunFont(run, fallback),
+				extraWidth: Math.max(0, run.advance),
+				break: "never"
+			});
+			continue;
+		}
+		const text = run.text ?? "";
+		if (text.length === 0) continue;
 		const item = {
-			text: run.text,
+			text,
 			font: resolveRunFont(run, fallback)
 		};
 		if (run.letterSpacing != null) item.letterSpacing = run.letterSpacing;
@@ -424,6 +321,15 @@ function renderRichText(props) {
 	};
 	const children = props.runs.map((run, i) => {
 		if (run.break) return createElement("br", { key: i });
+		if (run.advance != null) return createElement("span", {
+			key: i,
+			style: {
+				display: "inline-block",
+				verticalAlign: "middle",
+				lineHeight: 0,
+				whiteSpace: "nowrap"
+			}
+		}, run.content);
 		const tag = run.as ?? (run.href != null ? "a" : "span");
 		const elementProps = {
 			key: i,
@@ -442,7 +348,7 @@ function renderRichText(props) {
 		if (run.title != null) elementProps.title = run.title;
 		if (run.onClick != null) elementProps.onClick = run.onClick;
 		if (run.className != null) elementProps.className = run.className;
-		return createElement(tag, elementProps, run.text);
+		return createElement(tag, elementProps, run.text ?? "");
 	});
 	return createElement("div", {
 		className: props.className,
@@ -470,12 +376,173 @@ const RichText = markPrimitive(renderRichText, {
 		return max;
 	}
 });
+/**
+* Measure a string's rendered advance in px for a given measurable font — the
+* same ruler `RichText` measures with. Use it to size an inline box: a text
+* "pill" reserves `measureInline(label, font) + horizontalPadding`.
+*/
+function measureInline(text, font) {
+	if (text.length === 0) return 0;
+	assertMeasurableFont(font);
+	return measureRichInlineStats(prepareCached([{
+		text,
+		font
+	}]), 1e7).maxLineWidth;
+}
 /** Drop the rich-inline prepare cache (tests / memory pressure). */
 function clearRichTextCache() {
 	prepCache.clear();
 	cacheEpoch = -1;
 }
 //#endregion
+//#region src/inline.ts
+/** A base format for body text at a given size/weight/colour. */
+function baseFormat(theme, opts = {}) {
+	return {
+		family: theme.fontFamily,
+		monoFamily: theme.monoFamily,
+		size: opts.size ?? theme.fontSize,
+		weight: opts.weight ?? 400,
+		italic: false,
+		mono: false,
+		underline: false,
+		strike: false,
+		color: opts.color ?? (theme.color !== "inherit" ? theme.color : void 0)
+	};
+}
+/** Compose a measurable `Font` shorthand from a format. */
+function composeFont(fmt) {
+	const family = fmt.mono ? fmt.monoFamily : fmt.family;
+	return `${fmt.italic ? "italic " : ""}${fmt.weight} ${fmt.size}px ${family}`;
+}
+function pushRun(out, text, fmt) {
+	if (text.length === 0) return;
+	const run = {
+		text,
+		font: composeFont(fmt)
+	};
+	if (fmt.color != null) run.color = fmt.color;
+	if (fmt.background != null) run.background = fmt.background;
+	const decoration = [fmt.underline ? "underline" : "", fmt.strike ? "line-through" : ""].filter(Boolean).join(" ");
+	if (decoration) run.decoration = decoration;
+	if (fmt.href != null) {
+		run.href = fmt.href;
+		run.as = "a";
+	} else if (fmt.mono) run.as = "code";
+	out.push(run);
+}
+/** Build the context handed to an inline override. */
+function makeInlineCtx(fmt, theme, inline) {
+	return {
+		theme,
+		fmt,
+		font: (overrides) => composeFont(overrides ? {
+			...fmt,
+			...overrides
+		} : fmt),
+		measure: (text, font) => measureInline(text, font),
+		runs: (nodes, fmtOverrides) => {
+			const sub = [];
+			flattenInline(nodes, fmtOverrides ? {
+				...fmt,
+				...fmtOverrides
+			} : fmt, theme, sub, inline);
+			return sub;
+		}
+	};
+}
+/**
+* Flatten phrasing content into styled runs. Recursive over the inline marks;
+* the result feeds a single `<RichText>` so the whole paragraph wraps as one
+* flow and measures exactly. An `inline` override map can replace how any node
+* type flattens — returning its own runs (e.g. a measured inline box) or `null`
+* to fall through to the default.
+*/
+function flattenInline(nodes, fmt, theme, out, inline) {
+	for (const node of nodes) {
+		if (inline != null) {
+			const override = inline[node.type];
+			if (override != null) {
+				const produced = override(node, makeInlineCtx(fmt, theme, inline));
+				if (produced != null) {
+					for (const run of produced) out.push(run);
+					continue;
+				}
+			}
+		}
+		switch (node.type) {
+			case "text":
+				pushRun(out, node.value, fmt);
+				break;
+			case "strong":
+				flattenInline(node.children, {
+					...fmt,
+					weight: theme.strongWeight
+				}, theme, out, inline);
+				break;
+			case "emphasis":
+				flattenInline(node.children, {
+					...fmt,
+					italic: theme.emphasisItalic ? true : fmt.italic
+				}, theme, out, inline);
+				break;
+			case "delete":
+				flattenInline(node.children, {
+					...fmt,
+					strike: true
+				}, theme, out, inline);
+				break;
+			case "inlineCode":
+				pushRun(out, node.value, {
+					...fmt,
+					mono: true,
+					size: Math.round(fmt.size * theme.inlineCode.sizeScale),
+					color: theme.inlineCode.color !== "inherit" ? theme.inlineCode.color : fmt.color,
+					background: theme.inlineCode.background
+				});
+				break;
+			case "link":
+				flattenInline(node.children, {
+					...fmt,
+					href: node.url,
+					color: theme.link.color,
+					underline: theme.link.underline ? true : fmt.underline
+				}, theme, out, inline);
+				break;
+			case "linkReference":
+				flattenInline(node.children, fmt, theme, out, inline);
+				break;
+			case "break":
+				out.push({
+					text: "",
+					break: true
+				});
+				break;
+			case "image":
+				if (node.alt) pushRun(out, node.alt, {
+					...fmt,
+					color: theme.image.color
+				});
+				break;
+			case "imageReference":
+				if (node.alt) pushRun(out, node.alt, {
+					...fmt,
+					color: theme.image.color
+				});
+				break;
+			case "footnoteReference":
+				pushRun(out, `[${node.label ?? node.identifier}]`, {
+					...fmt,
+					color: theme.link.color
+				});
+				break;
+			default:
+				if ("children" in node && Array.isArray(node.children)) flattenInline(node.children, fmt, theme, out, inline);
+				break;
+		}
+	}
+}
+//#endregion
 //#region src/highlight/languages.ts
 function words(s) {
 	return new Set(s.split(" "));
@@ -1929,7 +1996,7 @@ function createContext(theme, components) {
 				...base
 			};
 			const out = [];
-			flattenInline(nodes, fmt, theme, out);
+			flattenInline(nodes, fmt, theme, out, components.inline);
 			return out;
 		},
 		inlineText(nodes, opts = {}) {
@@ -1939,7 +2006,7 @@ function createContext(theme, components) {
 				...opts.color != null ? { color: opts.color } : null
 			});
 			const out = [];
-			flattenInline(nodes, fmt, theme, out);
+			flattenInline(nodes, fmt, theme, out, components.inline);
 			return createElement(RichText, {
 				runs: out,
 				font: composeFont(fmt),
@@ -2256,4 +2323,4 @@ function defineMarkdownComponents(components) {
 	return components;
 }
 //#endregion
-export { CodeBlock, FadeMarkdown, 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, measureInline, parseMarkdown, profileFor, registerLanguage, renderMarkdown, resolveTheme };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wingleeio/mugen-markdown",
-  "version": "0.3.0",
+  "version": "0.4.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>",