@haruhimemoe/ui 0.7.0 → 0.9.0

package/dist/components/mdx/CodeBlock.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../utils/cx.js";
+import { CodeCopyButton } from "./CodeCopyButton.js";
+import { getHighlighter, THEME } from "./highlighter.js";
+const BASE = "block min-h-6 border-l-2 px-3";
+const LINE = `${BASE} border-transparent`;
+// Never both border colors on one element: Tailwind emits border-h1 before border-transparent.
+const MARKED = `${BASE} border-h1 bg-b4 forced-colors:border-[Highlight]`;
+/** Shiki's tokens per line, or null to render plain text. */
+const tokenize = async (code, lang) => {
+    if (!lang)
+        return null;
+    const highlighter = await getHighlighter();
+    if (!highlighter?.getLoadedLanguages().includes(lang.toLowerCase()))
+        return null;
+    try {
+        return highlighter.codeToTokens(code, { lang: lang.toLowerCase(), theme: THEME }).tokens;
+    }
+    catch {
+        return null;
+    }
+};
+const tokenStyle = (token) => ({
+    color: token.color,
+    fontStyle: (token.fontStyle ?? 0) & 1 ? "italic" : undefined,
+    fontWeight: (token.fontStyle ?? 0) & 2 ? "bold" : undefined,
+});
+/**
+ * @function CodeBlock
+ * @param props {CodeBlockProps} the code, optional language, title, highlighted line numbers and
+ *        wrapper class
+ * @returns {Promise<JSX.Element>} a header (name and copy button) over a highlighted `<pre>`
+ */
+export async function CodeBlock({ code, lang, title, highlight = [], className, ...rest }) {
+    const text = code.replace(/\r\n?/g, "\n").replace(/\n$/, "");
+    const tokens = await tokenize(text, lang);
+    const lines = tokens ?? text.split("\n").map((content) => [{ content, offset: 0 }]);
+    const marked = new Set(highlight);
+    const name = title ?? lang;
+    return (_jsxs("div", { className: cx("mt-3 overflow-hidden rounded-md border border-b3 bg-b6", className), ...rest, children: [_jsxs("div", { className: "flex min-h-9 items-center justify-between gap-3 border-b3 border-b px-3 py-1 text-c3 text-sm", children: [_jsx("span", { className: "truncate", children: name ?? "Code" }), _jsx(CodeCopyButton, { code: text, label: title ? `Copy ${title}` : "Copy code" })] }), _jsx("pre", { role: "group", 
+                // biome-ignore lint/a11y/noNoninteractiveTabindex: a scrollable region needs keyboard focus
+                tabIndex: 0, "aria-label": name ? `Code: ${name}` : "Code", className: "overflow-x-auto py-3 text-c2 text-sm leading-6", children: _jsx("code", { children: lines.flatMap((line, index) => {
+                        const span = (_jsx("span", { className: marked.has(index + 1) ? MARKED : LINE, "data-highlighted": marked.has(index + 1) ? "" : undefined, children: line.map((token, i) => tokens ? (_jsx("span", { style: tokenStyle(token), children: token.content }, i)) : (token.content)) }, index));
+                        // A plain "\n" text node between line spans (no key needed on a bare string): kept
+                        // out of the last line so there's no trailing phantom newline.
+                        return index < lines.length - 1 ? [span, "\n"] : [span];
+                    }) }) })] }));
+}

package/dist/components/mdx/CodeCopyButton.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/mdx/CodeCopyButton.tsx
+ * @desc The copy button CodeBlock renders beside a code fence's header: copies the plain code
+ *       text and reports "Copied" or "Copy failed" in a polite live region, like CopyButton. A
+ *       server component (CodeBlock) renders this client file, so it takes a finished class
+ *       string and never imports cx, keeping tailwind-merge out of the client bundle.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** The code to copy, and the button's accessible name (e.g. "Copy x.ts" or "Copy code"). */
+export type CodeCopyButtonProps = {
+    code: string;
+    label: string;
+};
+/**
+ * @function CodeCopyButton
+ * @param props {CodeCopyButtonProps} the code to copy and the button's accessible name
+ * @returns {JSX.Element} the copy button and an `<output>` announcing "Copied" or "Copy failed"
+ */
+export declare function CodeCopyButton({ code, label }: CodeCopyButtonProps): import("react").JSX.Element;

package/dist/components/mdx/CodeCopyButton.js

@@ -0,0 +1,34 @@
+/**
+ * @file src/components/mdx/CodeCopyButton.tsx
+ * @desc The copy button CodeBlock renders beside a code fence's header: copies the plain code
+ *       text and reports "Copied" or "Copy failed" in a polite live region, like CopyButton. A
+ *       server component (CodeBlock) renders this client file, so it takes a finished class
+ *       string and never imports cx, keeping tailwind-merge out of the client bundle.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { StatusOutput } from "../actions/StatusOutput.js";
+import { useLatestStatus } from "../actions/useLatestStatus.js";
+const BUTTON = "inline-flex min-h-6 min-w-6 items-center justify-center rounded px-2 py-0.5 text-c2 text-sm hover:bg-b4 hover:text-c1";
+/**
+ * @function CodeCopyButton
+ * @param props {CodeCopyButtonProps} the code to copy and the button's accessible name
+ * @returns {JSX.Element} the copy button and an `<output>` announcing "Copied" or "Copy failed"
+ */
+export function CodeCopyButton({ code, label }) {
+    const { status, start, settle } = useLatestStatus();
+    const copy = async () => {
+        const run = start();
+        try {
+            await navigator.clipboard.writeText(code);
+            settle(run, "copied");
+        }
+        catch {
+            settle(run, "failed");
+        }
+    };
+    return (_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(StatusOutput, { run: status?.run ?? null, children: status?.result === "copied" ? "Copied" : "Copy failed" }), _jsx("button", { type: "button", "aria-label": label, className: BUTTON, onClick: copy, children: "Copy" })] }));
+}

package/dist/components/mdx/MdxBlockquote.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file src/components/mdx/MdxBlockquote.tsx
+ * @desc react-markdown/MDX's `blockquote` override: a blockquote carrying `data-callout` (set by
+ *       the `remarkCallouts` plugin on a GitHub-style `> [!NOTE]` blockquote) renders as a
+ *       Callout of that type, with every other prop (className, id, …) forwarded to it; any other
+ *       blockquote renders plainly. Drops the `node` prop react-markdown passes to every
+ *       component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps } from "react";
+/** Every native `<blockquote>` prop, plus `node` (dropped) and the callout plugin's marker. */
+export type MdxBlockquoteProps = ComponentProps<"blockquote"> & {
+    node?: unknown;
+    "data-callout"?: string;
+};
+/**
+ * @function MdxBlockquote
+ * @param props {MdxBlockquoteProps} native blockquote props and an optional `data-callout` type
+ * @returns {JSX.Element} a Callout for a known `data-callout` type, otherwise a plain blockquote
+ */
+export declare function MdxBlockquote({ node: _node, "data-callout": callout, children, ...props }: MdxBlockquoteProps): import("react").JSX.Element;

package/dist/components/mdx/MdxBlockquote.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Callout } from "./Callout.js";
+const TYPES = ["note", "tip", "warning"];
+/**
+ * @function MdxBlockquote
+ * @param props {MdxBlockquoteProps} native blockquote props and an optional `data-callout` type
+ * @returns {JSX.Element} a Callout for a known `data-callout` type, otherwise a plain blockquote
+ */
+export function MdxBlockquote({ node: _node, "data-callout": callout, children, ...props }) {
+    if (callout && TYPES.includes(callout)) {
+        // Callout's props are a div's (ComponentProps<"blockquote"> isn't literally
+        // ComponentProps<"div">, e.g. `ref`), but every field react-markdown passes here (className,
+        // id, aria-*, data-*) is one Callout already forwards straight onto its own div.
+        return (_jsx(Callout, { type: callout, ...props, children: children }));
+    }
+    return _jsx("blockquote", { ...props, children: children });
+}

package/dist/components/mdx/MdxHeading.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file src/components/mdx/MdxHeading.tsx
+ * @desc react-markdown/MDX's `h2`/`h3` override: gives the heading a stable id (the given `id`,
+ *       from remark's heading-id plugin, or a slug of its own text) and a hover-revealed anchor
+ *       link beside it. Drops the `node` prop react-markdown passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps } from "react";
+/** Every native heading prop, plus the `node` react-markdown passes (dropped). */
+export type MdxHeadingProps = ComponentProps<"h2"> & {
+    node?: unknown;
+};
+/**
+ * @function MdxH2
+ * @param props {MdxHeadingProps} native h2 props and an optional id
+ * @returns {JSX.Element} an `<h2>` with a slug id and an anchor link
+ */
+export declare const MdxH2: ({ node: _node, id, children, ...props }: MdxHeadingProps) => import("react").JSX.Element;
+/**
+ * @function MdxH3
+ * @param props {MdxHeadingProps} native h3 props and an optional id
+ * @returns {JSX.Element} an `<h3>` with a slug id and an anchor link
+ */
+export declare const MdxH3: ({ node: _node, id, children, ...props }: MdxHeadingProps) => import("react").JSX.Element;

package/dist/components/mdx/MdxHeading.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { slugify } from "../../remark/slugify.js";
+import { textOf } from "./textOf.js";
+const WRAP = "group flex items-baseline gap-2 [&:first-child>:first-child]:mt-0";
+// The ! wins over Prose's [&_a]:text-h1 and [&_a]:underline, which outrank plain utilities.
+const ANCHOR = "inline-flex min-h-6 min-w-6 items-center justify-center rounded text-c4! no-underline! hover:text-h1!";
+const heading = (Tag) => function MdxHeading({ node: _node, id, children, ...props }) {
+    const text = textOf(children);
+    const slug = id ?? slugify(text);
+    return (_jsxs("div", { className: WRAP, children: [_jsx(Tag, { id: slug || undefined, ...props, children: children }), slug ? (_jsx("a", { href: `#${slug}`, "aria-label": `Link to section: ${text}`, className: ANCHOR, children: "#" })) : null] }));
+};
+/**
+ * @function MdxH2
+ * @param props {MdxHeadingProps} native h2 props and an optional id
+ * @returns {JSX.Element} an `<h2>` with a slug id and an anchor link
+ */
+export const MdxH2 = heading("h2");
+/**
+ * @function MdxH3
+ * @param props {MdxHeadingProps} native h3 props and an optional id
+ * @returns {JSX.Element} an `<h3>` with a slug id and an anchor link
+ */
+export const MdxH3 = heading("h3");

package/dist/components/mdx/MdxLink.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file src/components/mdx/MdxLink.tsx
+ * @desc react-markdown/MDX's `a` override: an external `http(s)` href opens in a new tab with a
+ *       safe rel (full props spread, like the `<a>` AutoLink itself renders for an off-app href);
+ *       a same-page hash link is a plain anchor, since AutoLink's own `isExternalHref` check
+ *       doesn't treat `#usage` as external and would otherwise send it through next/link, which
+ *       has no reason to handle a same-page jump; everything else (internal paths, `mailto:` and
+ *       other schemes) goes through AutoLink, which already picks `next/link` or a plain `<a>` by
+ *       href and spreads every other prop onto whichever element it renders. No `href` at all (a
+ *       README `<a name>`/`<a id>` anchor via rehype-raw) renders a plain `<a>` with no `href`
+ *       attribute, not a focusable empty link. Drops the `node` prop react-markdown passes to
+ *       every component, so it never reaches the DOM.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { ComponentProps } from "react";
+/** Every native `<a>` prop, plus the `node` react-markdown passes (dropped, never rendered). */
+export type MdxLinkProps = ComponentProps<"a"> & {
+    node?: unknown;
+};
+/**
+ * @function MdxLink
+ * @param props {MdxLinkProps} the link's href and native anchor props
+ * @returns {JSX.Element} an external link (new tab, `rel="noopener noreferrer"`), a plain anchor
+ *          for a same-page hash, or an AutoLink (next/link or a plain anchor, by href) otherwise,
+ *          every other prop forwarded in full
+ */
+export declare function MdxLink({ node: _node, href, children, ...props }: MdxLinkProps): import("react").JSX.Element;

package/dist/components/mdx/MdxLink.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AutoLink } from "../basics/AutoLink.js";
+/**
+ * @function MdxLink
+ * @param props {MdxLinkProps} the link's href and native anchor props
+ * @returns {JSX.Element} an external link (new tab, `rel="noopener noreferrer"`), a plain anchor
+ *          for a same-page hash, or an AutoLink (next/link or a plain anchor, by href) otherwise,
+ *          every other prop forwarded in full
+ */
+export function MdxLink({ node: _node, href, children, ...props }) {
+    if (href === undefined) {
+        return _jsx("a", { ...props, children: children });
+    }
+    if (/^https?:\/\//i.test(href)) {
+        return (_jsx("a", { href: href, target: "_blank", rel: "noopener noreferrer", ...props, children: children }));
+    }
+    if (href.startsWith("#")) {
+        return (_jsx("a", { href: href, ...props, children: children }));
+    }
+    // AutoLink's props are next/link's (anchor attributes plus next/link-only props like
+    // `prefetch`); every prop MdxLink accepts from react-markdown is a native anchor attribute,
+    // which AutoLink spreads straight onto whichever element it renders. Narrow cast, like
+    // AutoLink's own `href` handling: ComponentProps<"a"> isn't literally ComponentProps<Link>,
+    // but every field here is one AutoLink already knows how to forward.
+    return (_jsx(AutoLink, { href: href, ...props, children: children }));
+}

package/dist/components/mdx/MdxPre.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file src/components/mdx/MdxPre.tsx
+ * @desc react-markdown/MDX's `pre` override: a fenced code block (a `<pre>` wrapping a single
+ *       child with a `language-*` class, a `data-meta` prop, or the literal `code` element type)
+ *       is handed to CodeBlock with its parsed meta; detecting the fence by the child's props
+ *       rather than only `child.type === "code"` means an app that overrides the `code` component
+ *       (through `mdxComponents`' own map or MDX's `useMDXComponents`) still gets highlighting.
+ *       Anything else renders as a plain, focusable `<pre>`. Drops the `node` prop react-markdown
+ *       passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type ComponentProps } from "react";
+/** Every native `<pre>` prop, plus the `node` react-markdown passes (dropped). */
+export type MdxPreProps = ComponentProps<"pre"> & {
+    node?: unknown;
+};
+/**
+ * @function MdxPre
+ * @param props {MdxPreProps} native pre props; a single `code` child carries the language class
+ *        and the fence's meta string in `data-meta`
+ * @returns {JSX.Element} a CodeBlock for a fenced `code` child, otherwise a plain, focusable pre
+ */
+export declare function MdxPre({ node: _node, children, ...props }: MdxPreProps): import("react").JSX.Element;

package/dist/components/mdx/MdxPre.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @file src/components/mdx/MdxPre.tsx
+ * @desc react-markdown/MDX's `pre` override: a fenced code block (a `<pre>` wrapping a single
+ *       child with a `language-*` class, a `data-meta` prop, or the literal `code` element type)
+ *       is handed to CodeBlock with its parsed meta; detecting the fence by the child's props
+ *       rather than only `child.type === "code"` means an app that overrides the `code` component
+ *       (through `mdxComponents`' own map or MDX's `useMDXComponents`) still gets highlighting.
+ *       Anything else renders as a plain, focusable `<pre>`. Drops the `node` prop react-markdown
+ *       passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { Children, isValidElement } from "react";
+import { CodeBlock } from "./CodeBlock.js";
+import { parseCodeMeta } from "./parseCodeMeta.js";
+import { textOf } from "./textOf.js";
+/**
+ * @function MdxPre
+ * @param props {MdxPreProps} native pre props; a single `code` child carries the language class
+ *        and the fence's meta string in `data-meta`
+ * @returns {JSX.Element} a CodeBlock for a fenced `code` child, otherwise a plain, focusable pre
+ */
+export function MdxPre({ node: _node, children, ...props }) {
+    const [child] = Children.toArray(children);
+    const isFence = isValidElement(child) &&
+        (child.type === "code" ||
+            /(?:^|\s)language-/.test(child.props.className ?? "") ||
+            child.props["data-meta"] !== undefined);
+    if (!isFence || !isValidElement(child)) {
+        return (_jsx("pre", { 
+            // biome-ignore lint/a11y/noNoninteractiveTabindex: a scrollable region needs keyboard focus
+            tabIndex: 0, ...props, children: children }));
+    }
+    const lang = /(?:^|\s)language-(\S+)/.exec(child.props.className ?? "")?.[1];
+    const { title, highlight } = parseCodeMeta(child.props["data-meta"]);
+    return (_jsx(CodeBlock, { code: textOf(child.props.children), lang: lang, title: title, highlight: highlight }));
+}

package/dist/components/mdx/MdxTable.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file src/components/mdx/MdxTable.tsx
+ * @desc react-markdown/MDX's `table` override: wraps the table in a named, focusable scroll
+ *       region (a table can overflow its column on narrow screens), named by its caption when
+ *       one is given. Drops the `node` prop react-markdown passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type ComponentProps } from "react";
+/** Every native `<table>` prop, plus the `node` react-markdown passes (dropped). */
+export type MdxTableProps = ComponentProps<"table"> & {
+    node?: unknown;
+};
+/**
+ * @function MdxTable
+ * @param props {MdxTableProps} native table props; a `caption` child names the scroll region
+ * @returns {JSX.Element} a horizontally scrollable, focusable, labelled region wrapping the table
+ */
+export declare function MdxTable({ node: _node, children, ...props }: MdxTableProps): import("react").JSX.Element;

package/dist/components/mdx/MdxTable.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @file src/components/mdx/MdxTable.tsx
+ * @desc react-markdown/MDX's `table` override: wraps the table in a named, focusable scroll
+ *       region (a table can overflow its column on narrow screens), named by its caption when
+ *       one is given. Drops the `node` prop react-markdown passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { Children, isValidElement } from "react";
+import { textOf } from "./textOf.js";
+/**
+ * @function MdxTable
+ * @param props {MdxTableProps} native table props; a `caption` child names the scroll region
+ * @returns {JSX.Element} a horizontally scrollable, focusable, labelled region wrapping the table
+ */
+export function MdxTable({ node: _node, children, ...props }) {
+    const caption = Children.toArray(children).find((child) => isValidElement(child) && child.type === "caption");
+    return (_jsx("div", { role: "group", "aria-label": textOf(caption) || "Table", 
+        // biome-ignore lint/a11y/noNoninteractiveTabindex: a scrollable region needs keyboard focus
+        tabIndex: 0, className: "overflow-x-auto", children: _jsx("table", { ...props, children: children }) }));
+}

package/dist/components/mdx/highlighter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file src/components/mdx/highlighter.ts
+ * @desc The highlighter CodeBlock asks for. Nothing here names Shiki outside `import type`, so
+ *       an app without Shiki builds: `@haruhimemoe/ui/shiki` (src/shiki.ts) registers the real
+ *       loader when an app imports it. The loader lives in a `globalThis` slot keyed by
+ *       `Symbol.for`, so it survives duplicate copies of this module. The first highlighter is
+ *       cached; with no loader registered, or a loader that rejects, code renders plain (warned
+ *       once, outside production) rather than throwing.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { HighlighterCore } from "shiki/core";
+/** The Shiki CSS-variables theme name CodeBlock renders with. */
+export declare const THEME = "haruhime";
+/** Loads a Shiki highlighter: what `@haruhimemoe/ui/shiki` registers. */
+export type HighlighterLoader = () => Promise<HighlighterCore>;
+/**
+ * @function setHighlighterLoader
+ * @param loader {HighlighterLoader} loads the Shiki highlighter; replaces any earlier one
+ * @returns {void} registers the loader in the global slot and drops the cached highlighter
+ */
+export declare const setHighlighterLoader: (loader: HighlighterLoader) => void;
+/**
+ * @function getHighlighter
+ * @param loader {HighlighterLoader | undefined} loads the highlighter; defaults to the registered
+ *        one, overridable in tests
+ * @returns {Promise<HighlighterCore | null>} the cached highlighter, or null when no loader is
+ *          registered or it failed to load
+ */
+export declare const getHighlighter: (loader?: HighlighterLoader | undefined) => Promise<HighlighterCore | null>;
+/**
+ * @function resetHighlighter
+ * @returns {void} clears the registered loader, the cached highlighter and the warned flag
+ *          (tests only)
+ */
+export declare const resetHighlighter: () => void;

package/dist/components/mdx/highlighter.js

@@ -0,0 +1,66 @@
+/**
+ * @file src/components/mdx/highlighter.ts
+ * @desc The highlighter CodeBlock asks for. Nothing here names Shiki outside `import type`, so
+ *       an app without Shiki builds: `@haruhimemoe/ui/shiki` (src/shiki.ts) registers the real
+ *       loader when an app imports it. The loader lives in a `globalThis` slot keyed by
+ *       `Symbol.for`, so it survives duplicate copies of this module. The first highlighter is
+ *       cached; with no loader registered, or a loader that rejects, code renders plain (warned
+ *       once, outside production) rather than throwing.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** The Shiki CSS-variables theme name CodeBlock renders with. */
+export const THEME = "haruhime";
+const SLOT = Symbol.for("@haruhimemoe/ui/highlighter");
+// No node types in the build (tsconfig.build.json "types": []), so read process through globalThis.
+const isProduction = () => globalThis.process?.env
+    ?.NODE_ENV === "production";
+let cached;
+let warned = false;
+const warnOnce = (message, error) => {
+    if (warned || isProduction())
+        return;
+    warned = true;
+    if (error === undefined)
+        console.warn(message);
+    else
+        console.warn(message, error);
+};
+/**
+ * @function setHighlighterLoader
+ * @param loader {HighlighterLoader} loads the Shiki highlighter; replaces any earlier one
+ * @returns {void} registers the loader in the global slot and drops the cached highlighter
+ */
+export const setHighlighterLoader = (loader) => {
+    globalThis[SLOT] = loader;
+    cached = undefined;
+};
+/**
+ * @function getHighlighter
+ * @param loader {HighlighterLoader | undefined} loads the highlighter; defaults to the registered
+ *        one, overridable in tests
+ * @returns {Promise<HighlighterCore | null>} the cached highlighter, or null when no loader is
+ *          registered or it failed to load
+ */
+export const getHighlighter = (loader = globalThis[SLOT]) => {
+    if (!loader) {
+        warnOnce('@haruhimemoe/ui: code blocks aren\'t highlighted. Install shiki and add `import "@haruhimemoe/ui/shiki";` once, e.g. in mdx-components.tsx.');
+        return Promise.resolve(null);
+    }
+    cached ??= loader().catch((error) => {
+        warnOnce("@haruhimemoe/ui: Shiki didn't load, so code blocks aren't highlighted.", error);
+        return null;
+    });
+    return cached;
+};
+/**
+ * @function resetHighlighter
+ * @returns {void} clears the registered loader, the cached highlighter and the warned flag
+ *          (tests only)
+ */
+export const resetHighlighter = () => {
+    globalThis[SLOT] = undefined;
+    cached = undefined;
+    warned = false;
+};

package/dist/components/mdx/mdxComponents.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/mdx/mdxComponents.ts
+ * @desc The element override map for @next/mdx's `useMDXComponents` and react-markdown's
+ *       `components` prop: links, headings (h2/h3), fenced code, tables and callout blockquotes.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { MdxBlockquote } from "./MdxBlockquote.js";
+import { MdxLink } from "./MdxLink.js";
+import { MdxPre } from "./MdxPre.js";
+import { MdxTable } from "./MdxTable.js";
+/** The element overrides for @next/mdx's useMDXComponents and react-markdown's `components`. */
+export declare const mdxComponents: {
+    a: typeof MdxLink;
+    blockquote: typeof MdxBlockquote;
+    h2: ({ node: _node, id, children, ...props }: import("./MdxHeading.js").MdxHeadingProps) => import("react").JSX.Element;
+    h3: ({ node: _node, id, children, ...props }: import("./MdxHeading.js").MdxHeadingProps) => import("react").JSX.Element;
+    pre: typeof MdxPre;
+    table: typeof MdxTable;
+};

package/dist/components/mdx/mdxComponents.js

@@ -0,0 +1,22 @@
+/**
+ * @file src/components/mdx/mdxComponents.ts
+ * @desc The element override map for @next/mdx's `useMDXComponents` and react-markdown's
+ *       `components` prop: links, headings (h2/h3), fenced code, tables and callout blockquotes.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { MdxBlockquote } from "./MdxBlockquote.js";
+import { MdxH2, MdxH3 } from "./MdxHeading.js";
+import { MdxLink } from "./MdxLink.js";
+import { MdxPre } from "./MdxPre.js";
+import { MdxTable } from "./MdxTable.js";
+/** The element overrides for @next/mdx's useMDXComponents and react-markdown's `components`. */
+export const mdxComponents = {
+    a: MdxLink,
+    blockquote: MdxBlockquote,
+    h2: MdxH2,
+    h3: MdxH3,
+    pre: MdxPre,
+    table: MdxTable,
+};

package/dist/components/mdx/parseCodeMeta.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/mdx/parseCodeMeta.ts
+ * @desc Parses a fenced code block's meta string (the text after the language on ```ts fences)
+ *       into a title (`title="..."` or `title='...'`) and a sorted, deduped list of highlighted
+ *       line numbers (`{1,3-5}`), capped at 10000 lines so a huge or malicious range can't hang
+ *       the render.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** A parsed code fence meta string. */
+export type CodeMeta = {
+    title?: string;
+    highlight: number[];
+};
+/**
+ * @function parseCodeMeta
+ * @param meta {string | null | undefined} the code fence's meta string, if any
+ * @returns {CodeMeta} the title (when present) and the sorted, deduped, capped highlight lines
+ */
+export declare const parseCodeMeta: (meta?: string | null) => CodeMeta;

package/dist/components/mdx/parseCodeMeta.js

@@ -0,0 +1,40 @@
+/**
+ * @file src/components/mdx/parseCodeMeta.ts
+ * @desc Parses a fenced code block's meta string (the text after the language on ```ts fences)
+ *       into a title (`title="..."` or `title='...'`) and a sorted, deduped list of highlighted
+ *       line numbers (`{1,3-5}`), capped at 10000 lines so a huge or malicious range can't hang
+ *       the render.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+const TITLE = /\btitle=(?:"([^"]*)"|'([^']*)')/;
+const RANGES = /\{([^}]*)\}/;
+const MAX_LINES = 10000;
+/**
+ * @function parseCodeMeta
+ * @param meta {string | null | undefined} the code fence's meta string, if any
+ * @returns {CodeMeta} the title (when present) and the sorted, deduped, capped highlight lines
+ */
+export const parseCodeMeta = (meta) => {
+    const text = meta ?? "";
+    const lines = new Set();
+    for (const part of RANGES.exec(text)?.[1]?.split(",") ?? []) {
+        const match = /^\s*(\d+)\s*(?:-\s*(\d+)\s*)?$/.exec(part);
+        if (!match)
+            continue;
+        let from = Number(match[1]);
+        let to = match[2] === undefined ? from : Number(match[2]);
+        if (from > to)
+            [from, to] = [to, from];
+        from = Math.max(from, 1);
+        for (let line = from; line <= to && lines.size < MAX_LINES; line++)
+            lines.add(line);
+    }
+    const title = TITLE.exec(text);
+    const result = { highlight: [...lines].sort((a, b) => a - b) };
+    const name = title?.[1] ?? title?.[2];
+    if (name)
+        result.title = name;
+    return result;
+};

package/dist/components/mdx/textOf.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file src/components/mdx/textOf.ts
+ * @desc Flattens a ReactNode tree to plain text: strings and numbers pass through, arrays and
+ *       element children are recursively joined, and null/undefined/boolean contribute nothing.
+ *       Used to get a code block's plain text for Shiki and the copy button, since react-markdown
+ *       hands components React children, not a string.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type ReactNode } from "react";
+/**
+ * @function textOf
+ * @param node {ReactNode} the node (or tree of nodes) to flatten
+ * @returns {string} the concatenated text content
+ */
+export declare const textOf: (node: ReactNode) => string;

package/dist/components/mdx/textOf.js

@@ -0,0 +1,28 @@
+/**
+ * @file src/components/mdx/textOf.ts
+ * @desc Flattens a ReactNode tree to plain text: strings and numbers pass through, arrays and
+ *       element children are recursively joined, and null/undefined/boolean contribute nothing.
+ *       Used to get a code block's plain text for Shiki and the copy button, since react-markdown
+ *       hands components React children, not a string.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { isValidElement } from "react";
+/**
+ * @function textOf
+ * @param node {ReactNode} the node (or tree of nodes) to flatten
+ * @returns {string} the concatenated text content
+ */
+export const textOf = (node) => {
+    if (node === null || node === undefined || typeof node === "boolean")
+        return "";
+    if (typeof node === "string" || typeof node === "number" || typeof node === "bigint") {
+        return String(node);
+    }
+    if (Array.isArray(node))
+        return node.map(textOf).join("");
+    if (isValidElement(node))
+        return textOf(node.props.children);
+    return "";
+};