@zccz14/ux 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @zccz14/ux
 
-`@zccz14/ux` provides the shared `AppLayout` shell for the NTNL app family (Cybion, NormAI, CTX, Linkit, Midas, HIT, 1Exchange, DeepSeek-LB, OpenAI-LB). One implementation of the sidebar, the AppHeader, and the Linkit account control keeps the interaction identical across apps and replaces the per-app copies of that chrome.
+`@zccz14/ux` provides the shared app shell and the shared Markdown renderer for the NTNL app family (Cybion, NormAI, CTX, Linkit, Midas, HIT, 1Exchange, DeepSeek-LB, OpenAI-LB). One implementation of the sidebar, the AppHeader and the Linkit account control keeps the interaction identical across apps; one implementation of `<Markdown>` keeps rendered content — replies, checkpoints, manuals, documents, articles — identical too. Both replace the per-app copies they supersede.
 
 ## What the shell owns
 
@@ -102,9 +102,45 @@ type AppNavGroup = { label: string; items: AppNavItem[] };
 - **Favicon** — an `<svg>` logo is serialised to a `data:image/svg+xml` icon with its rendered colour pinned; an `<img>` logo reuses the image URL. The icon is rewritten when `.dark` flips, when `prefers-color-scheme` changes, and when the mark itself is swapped.
 - **Layout contract** — the shell is viewport-locked (`100svh`); the main region is the page's only scroll container and applies the standard `1rem` / `1.5rem` padding. Pages own their inner layout.
 
+## Markdown
+
+`<Markdown content={...} />` is the single renderer for every piece of Markdown in the family.
+
+```tsx
+import { Markdown } from "@zccz14/ux";
+
+<Markdown content={reply} />;
+```
+
+One prop, on purpose. There is no `math`, `mermaid`, `components`, `remarkPlugins` or `urlTransform` switch: a surface either renders Markdown the family way, or it renders through something else. Every capability below is always on, because the point of the component is that a reply in Cybion, a checkpoint, a manual preview and a CTX article look the same.
+
+### What it renders
+
+- **GitHub Flavored Markdown** — tables, task lists, strikethrough, autolinks.
+- **Math through KaTeX** — `$E=mc^2$`, `$$…$$`, `\(…\)`, `\[…\]` and `math`-tagged code fences, because models emit all of them. KaTeX's stylesheet and fonts are imported by the component itself, so a formula is never unstyled. Broken math degrades to one `.katex-error` span carrying the parser message; math that is still streaming — no closing delimiter yet — stays source instead of flickering.
+- **Mermaid diagrams** — a `mermaid`-tagged fence becomes an SVG, loaded on demand: a surface without a diagram never downloads mermaid. The chart follows the current theme and the surrounding text size, and re-renders when `.dark` flips. An unparseable diagram falls back to its own source block.
+- **Links** — absolute URLs open in a new tab with `rel="noopener noreferrer"` and an external marker; in-page anchors and relative paths stay in the app. Only `http(s)` and `mailto` survive: `javascript:`, `data:` and friends degrade to plain text.
+- **Tables and code** — a wide table or a long code block scrolls inside its own box, so the transcript or article around it never grows a horizontal scrollbar.
+- **Raw HTML** — never rendered. The pipeline has no `rehype-raw`, so HTML in the source is shown as text.
+
+### Typography is owned here
+
+The component wraps its content in `.ux-markdown`, and that block is the family's typographic contract: every size is expressed in `em` off the inherited font size, and no measure is imposed. The same content therefore keeps identical proportions in a 14px chat bubble and a 16px article page. The host decides two things and only two — the font size of the container the content is dropped into, and the width of that container. Do not wrap the component in `prose` classes: the stylesheet is the single source of the look, and `scripts/check-styles.mjs` enforces it.
+
+### Why the pipeline is a runtime dependency
+
+`react-markdown`, `remark-gfm`, `remark-math-extended`, `rehype-katex`, `katex` and `mermaid` are `dependencies`, not peers, so an app wires nothing. An app that never renders Markdown tree-shakes the whole pipeline away, with one deliberate exception: `katex/dist/katex.min.css` is a module-level side effect of the renderer (about 3.6 KB gzipped, plus fonts the browser fetches only when a formula appears). `scripts/check-package.mjs` fails the build if the manifest ever claims `sideEffects: false`, which would let a bundler drop that stylesheet and render every formula as bare LaTeX with no error to notice.
+
+## Migrating an app from its local Markdown renderer
+
+1. Delete the app's own renderer — the `react-markdown` wrapper, its plugin wiring, its `components` map, its `Mermaid`/`MarkdownPre` pair, and any `mermaid`/`rehype-katex`/`remark-*`/`katex` dependency entries that only served it.
+2. Replace each call site with `<Markdown content={markdown} />` and drop the surrounding `prose …` classes: the typography lives in `.ux-markdown`, and the container only owes the content a font size and a width.
+3. Keep app-specific node mapping out of the way — if a surface really needs different output (inline mention tokens, a clamped preview), it belongs in the library, not in a local fork of the plugin chain.
+4. Keep the KaTeX stylesheet import out of the app: the component owns it.
+
 ## Styling
 
-Import `@zccz14/ux/styles.css` once. It consumes the app's shadcn theme tokens and falls back to its own values, so the shell stays readable even when a token is missing: `--background`, `--foreground`, `--border`, `--accent`, `--muted`, `--ring`, `--sidebar`, `--sidebar-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`.
+Import `@zccz14/ux/styles.css` once. It consumes the app's shadcn theme tokens and falls back to its own values, so the shell stays readable even when a token is missing: `--background`, `--foreground`, `--border`, `--accent`, `--muted`, `--ring`, `--sidebar`, `--sidebar-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`. The Markdown layer reads `--muted`, `--muted-foreground`, `--primary` and `--destructive` through the same `--ux-*` layer (`--ux-muted`, `--ux-muted-foreground`, `--ux-primary`, `--ux-destructive`).
 
 Those tokens are read through a `--ux-*` layer declared twice — a light set on `:root` and a dark set on `.dark` — so every fallback has a dark counterpart. A missing `--sidebar` therefore renders dark in dark mode instead of a light sidebar. The shell also sets `color-scheme` per mode, so native scrollbars and controls follow the theme without help from a theme provider.
 
@@ -121,9 +157,9 @@ Theme state itself is not the shell's business: whatever toggles `.dark` on `<ht
 ## Development
 
 ```sh
-npm install
-npm run typecheck
-npm test
-npm run build
-npm run pack:check
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+pnpm run pack:check
 ```

package/dist/icons.d.ts

@@ -1,2 +1,3 @@
 export declare function CloseIcon(): import("react").JSX.Element;
 export declare function PanelLeftIcon(): import("react").JSX.Element;
+export declare function ExternalLinkIcon(): import("react").JSX.Element;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { AppLayout } from "./app-layout.js";
-export type { AppLayoutProps, AppNavGroup, AppNavItem } from "./types.js";
+export { Markdown } from "./markdown.js";
+export type { AppLayoutProps, AppNavGroup, AppNavItem, MarkdownProps } from "./types.js";

package/dist/index.js

@@ -1,65 +1,70 @@
-import { jsxs as d, jsx as n, Fragment as L } from "react/jsx-runtime";
-import { useEffect as k, useRef as M, useState as v, useCallback as x, useSyncExternalStore as C } from "react";
+import { jsxs as u, jsx as n, Fragment as L } from "react/jsx-runtime";
+import { useEffect as v, useRef as f, useState as g, useCallback as y, useSyncExternalStore as C } from "react";
 import { Dialog as h } from "@base-ui/react/dialog";
-import { Tooltip as m } from "@base-ui/react/tooltip";
+import { Tooltip as p } from "@base-ui/react/tooltip";
 import { useLinkit as E, LinkitMyInfo as O } from "linkit-react-components";
-import { useLocation as y, NavLink as I } from "react-router-dom";
-const P = {
+import { useLocation as w, NavLink as z } from "react-router-dom";
+import T from "react-markdown";
+import P from "rehype-katex";
+import F from "remark-gfm";
+import I from "remark-math-extended";
+import "katex/dist/katex.min.css";
+const $ = {
   closeNavigation: "Close navigation",
   navigation: "Navigation",
   toggleSidebar: "Toggle sidebar"
-}, T = {
+}, A = {
   closeNavigation: "关闭导航",
   navigation: "导航",
   toggleSidebar: "切换侧边栏"
 };
-function A(e) {
-  return e.toLowerCase().startsWith("zh") ? T : P;
+function W(e) {
+  return e.toLowerCase().startsWith("zh") ? A : $;
 }
-const $ = 'link[rel~="icon"]';
-function R(e) {
+const R = 'link[rel~="icon"]';
+function j(e) {
   const t = e.cloneNode(!0);
   return t.setAttribute("xmlns", "http://www.w3.org/2000/svg"), t.style.color = getComputedStyle(e).color, new XMLSerializer().serializeToString(t);
 }
-function W(e) {
+function B(e) {
   if (e instanceof SVGSVGElement)
     return {
-      href: `data:image/svg+xml,${encodeURIComponent(R(e))}`,
+      href: `data:image/svg+xml,${encodeURIComponent(j(e))}`,
       type: "image/svg+xml"
     };
-  const { currentSrc: t, src: o } = e, i = t || o;
-  return /\.svg([?#]|$)/i.test(i) ? { href: i, type: "image/svg+xml" } : { href: i };
+  const { currentSrc: t, src: a } = e, r = t || a;
+  return /\.svg([?#]|$)/i.test(r) ? { href: r, type: "image/svg+xml" } : { href: r };
 }
-function j() {
-  const e = document.querySelector($);
+function q() {
+  const e = document.querySelector(R);
   if (e)
     return e;
   const t = document.createElement("link");
   return t.rel = "icon", document.head.append(t), t;
 }
-function z(e, t) {
-  k(() => {
+function D(e, t) {
+  v(() => {
     if (!t)
       return;
-    const o = () => {
-      var l;
-      const p = (l = e.current) == null ? void 0 : l.querySelector("svg, img");
-      if (!p)
+    const a = () => {
+      var m;
+      const i = (m = e.current) == null ? void 0 : m.querySelector("svg, img");
+      if (!i)
         return;
-      const { href: u, type: s } = W(p), c = j();
-      s ? c.type = s : c.removeAttribute("type"), c.getAttribute("href") !== u && c.setAttribute("href", u);
+      const { href: d, type: s } = B(i), l = q();
+      s ? l.type = s : l.removeAttribute("type"), l.getAttribute("href") !== d && l.setAttribute("href", d);
     };
-    o();
-    const i = new MutationObserver(o);
-    i.observe(document.documentElement, { attributes: !0, attributeFilter: ["class", "style"] }), e.current && i.observe(e.current, { childList: !0, subtree: !0 });
-    const r = window.matchMedia("(prefers-color-scheme: dark)");
-    return r.addEventListener("change", o), () => {
-      i.disconnect(), r.removeEventListener("change", o);
+    a();
+    const r = new MutationObserver(a);
+    r.observe(document.documentElement, { attributes: !0, attributeFilter: ["class", "style"] }), e.current && r.observe(e.current, { childList: !0, subtree: !0 });
+    const o = window.matchMedia("(prefers-color-scheme: dark)");
+    return o.addEventListener("change", a), () => {
+      r.disconnect(), o.removeEventListener("change", a);
     };
   }, [t, e]);
 }
-function B() {
-  return /* @__PURE__ */ d(
+function K() {
+  return /* @__PURE__ */ u(
     "svg",
     {
       "aria-hidden": "true",
@@ -76,8 +81,8 @@ function B() {
     }
   );
 }
-function F() {
-  return /* @__PURE__ */ d(
+function V() {
+  return /* @__PURE__ */ u(
     "svg",
     {
       "aria-hidden": "true",
@@ -94,81 +99,101 @@ function F() {
     }
   );
 }
-const f = "sidebar_state", q = 3600 * 24 * 7, w = "(max-width: 767px)";
-function D() {
-  const e = document.cookie.split("; ").find((t) => t.startsWith(`${f}=`));
-  return e ? e.slice(f.length + 1) !== "false" : !0;
+function G() {
+  return /* @__PURE__ */ u(
+    "svg",
+    {
+      "aria-hidden": "true",
+      className: "ux-markdown__external-link",
+      fill: "none",
+      stroke: "currentColor",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      strokeWidth: "2",
+      viewBox: "0 0 24 24",
+      children: [
+        /* @__PURE__ */ n("path", { d: "M15 3h6v6" }),
+        /* @__PURE__ */ n("path", { d: "M10 14 21 3" }),
+        /* @__PURE__ */ n("path", { d: "M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" })
+      ]
+    }
+  );
+}
+const b = "sidebar_state", H = 3600 * 24 * 7, _ = "(max-width: 767px)";
+function U() {
+  const e = document.cookie.split("; ").find((t) => t.startsWith(`${b}=`));
+  return e ? e.slice(b.length + 1) !== "false" : !0;
 }
-function K(e) {
-  document.cookie = `${f}=${e}; path=/; max-age=${q}`;
+function Q(e) {
+  document.cookie = `${b}=${e}; path=/; max-age=${H}`;
 }
-function G(e) {
-  const t = window.matchMedia(w);
+function X(e) {
+  const t = window.matchMedia(_);
   return t.addEventListener("change", e), () => t.removeEventListener("change", e);
 }
-function V() {
+function J() {
   return C(
-    G,
-    () => window.matchMedia(w).matches,
+    X,
+    () => window.matchMedia(_).matches,
     () => !1
   );
 }
-function Q() {
-  const e = V(), [t, o] = v(D), [i, r] = v(!1), p = x((s) => {
-    o(s), K(s);
-  }, []), u = x(() => {
+function Y() {
+  const e = J(), [t, a] = g(U), [r, o] = g(!1), i = y((s) => {
+    a(s), Q(s);
+  }, []), d = y(() => {
     if (e) {
-      r((s) => !s);
+      o((s) => !s);
       return;
     }
-    p(!t);
-  }, [e, t, p]);
-  return k(() => {
-    function s(c) {
-      (c.metaKey || c.ctrlKey) && c.key === "b" && (c.preventDefault(), u());
+    i(!t);
+  }, [e, t, i]);
+  return v(() => {
+    function s(l) {
+      (l.metaKey || l.ctrlKey) && l.key === "b" && (l.preventDefault(), d());
     }
     return window.addEventListener("keydown", s), () => window.removeEventListener("keydown", s);
-  }, [u]), { isMobile: e, open: t, openMobile: i, setOpenMobile: r, toggleSidebar: u };
+  }, [d]), { isMobile: e, open: t, openMobile: r, setOpenMobile: o, toggleSidebar: d };
 }
-function _(e, t) {
-  let o;
-  for (const i of e)
-    for (const r of i.items)
-      (r.to === "/" ? t === "/" : t === r.to || t.startsWith(`${r.to}/`)) && (!o || r.to.length > o.to.length) && (o = r);
-  return o;
+function M(e, t) {
+  let a;
+  for (const r of e)
+    for (const o of r.items)
+      (o.to === "/" ? t === "/" : t === o.to || t.startsWith(`${o.to}/`)) && (!a || o.to.length > a.to.length) && (a = o);
+  return a;
 }
-function U({
+function Z({
   collapsed: e,
   end: t,
-  item: o,
-  onNavigate: i
+  item: a,
+  onNavigate: r
 }) {
-  return /* @__PURE__ */ d(m.Root, { children: [
-    /* @__PURE__ */ d(
-      m.Trigger,
+  return /* @__PURE__ */ u(p.Root, { children: [
+    /* @__PURE__ */ u(
+      p.Trigger,
       {
         render: /* @__PURE__ */ n(
-          I,
+          z,
           {
             className: "ux-nav-item",
             end: t,
-            onClick: i,
-            to: o.to
+            onClick: r,
+            to: a.to
           }
         ),
         children: [
-          /* @__PURE__ */ n("span", { className: "ux-nav-item__icon", children: o.icon }),
-          /* @__PURE__ */ n("span", { className: "ux-nav-item__text", children: o.label })
+          /* @__PURE__ */ n("span", { className: "ux-nav-item__icon", children: a.icon }),
+          /* @__PURE__ */ n("span", { className: "ux-nav-item__text", children: a.label })
         ]
       }
     ),
-    /* @__PURE__ */ n(m.Portal, { children: /* @__PURE__ */ n(
-      m.Positioner,
+    /* @__PURE__ */ n(p.Portal, { children: /* @__PURE__ */ n(
+      p.Positioner,
       {
         className: "ux-tooltip-positioner",
         side: "right",
         sideOffset: 6,
-        children: /* @__PURE__ */ n(m.Popup, { className: "ux-tooltip", hidden: !e, children: o.label })
+        children: /* @__PURE__ */ n(p.Popup, { className: "ux-tooltip", hidden: !e, children: a.label })
       }
     ) })
   ] });
@@ -176,116 +201,116 @@ function U({
 function N({
   copy: e,
   logo: t,
-  logoRef: o,
-  nav: i,
-  onNavigate: r,
-  state: p,
-  title: u
+  logoRef: a,
+  nav: r,
+  onNavigate: o,
+  state: i,
+  title: d
 }) {
-  const { pathname: s } = y(), c = _(i, s);
-  return /* @__PURE__ */ d(L, { children: [
-    /* @__PURE__ */ d("div", { className: "ux-sidebar__header", children: [
-      /* @__PURE__ */ n("span", { className: "ux-sidebar__logo", ref: o, children: t }),
-      /* @__PURE__ */ n("span", { className: "ux-sidebar__title", children: u })
+  const { pathname: s } = w(), l = M(r, s);
+  return /* @__PURE__ */ u(L, { children: [
+    /* @__PURE__ */ u("div", { className: "ux-sidebar__header", children: [
+      /* @__PURE__ */ n("span", { className: "ux-sidebar__logo", ref: a, children: t }),
+      /* @__PURE__ */ n("span", { className: "ux-sidebar__title", children: d })
     ] }),
-    /* @__PURE__ */ n("nav", { "aria-label": e.navigation, className: "ux-sidebar__nav", children: i.map((l) => /* @__PURE__ */ d("div", { className: "ux-nav-group", children: [
-      /* @__PURE__ */ n("div", { className: "ux-nav-group__label", children: l.label }),
-      l.items.map((a) => (
+    /* @__PURE__ */ n("nav", { "aria-label": e.navigation, className: "ux-sidebar__nav", children: r.map((m) => /* @__PURE__ */ u("div", { className: "ux-nav-group", children: [
+      /* @__PURE__ */ n("div", { className: "ux-nav-group__label", children: m.label }),
+      m.items.map((c) => (
         // NavLink would mark a parent section current on its children's
         // routes; follow matchActiveItem instead so only the deepest
         // match (or the exact path) stays marked.
         /* @__PURE__ */ n(
-          U,
+          Z,
           {
-            collapsed: p === "collapsed",
-            end: a !== c || a.to === s,
-            item: a,
-            onNavigate: r
+            collapsed: i === "collapsed",
+            end: c !== l || c.to === s,
+            item: c,
+            onNavigate: o
           },
-          a.to
+          c.to
         )
       ))
-    ] }, l.label)) })
+    ] }, m.label)) })
   ] });
 }
-function te({
+function _e({
   children: e,
   favicon: t = !0,
-  headerSlot: o,
-  logo: i,
-  nav: r,
-  pageTitle: p,
-  title: u
+  headerSlot: a,
+  logo: r,
+  nav: o,
+  pageTitle: i,
+  title: d
 }) {
-  var g;
-  const { pathname: s } = y(), { lang: c } = E(), l = A(c), a = Q(), b = M(null), S = p ?? ((g = _(r, s)) == null ? void 0 : g.label);
-  return z(b, t), /* @__PURE__ */ n(m.Provider, { delay: 0, children: /* @__PURE__ */ d(
+  var k;
+  const { pathname: s } = w(), { lang: l } = E(), m = W(l), c = Y(), x = f(null), S = i ?? ((k = M(o, s)) == null ? void 0 : k.label);
+  return D(x, t), /* @__PURE__ */ n(p.Provider, { delay: 0, children: /* @__PURE__ */ u(
     "div",
     {
       className: "ux-app-layout",
-      "data-state": a.open ? "expanded" : "collapsed",
+      "data-state": c.open ? "expanded" : "collapsed",
       children: [
         /* @__PURE__ */ n("aside", { className: "ux-sidebar", children: /* @__PURE__ */ n(
           N,
           {
-            copy: l,
-            logo: i,
-            logoRef: b,
-            nav: r,
-            state: a.open ? "expanded" : "collapsed",
-            title: u
+            copy: m,
+            logo: r,
+            logoRef: x,
+            nav: o,
+            state: c.open ? "expanded" : "collapsed",
+            title: d
           }
         ) }),
-        a.isMobile ? /* @__PURE__ */ n(
+        c.isMobile ? /* @__PURE__ */ n(
           h.Root,
           {
-            open: a.openMobile,
-            onOpenChange: a.setOpenMobile,
-            children: /* @__PURE__ */ d(h.Portal, { children: [
+            open: c.openMobile,
+            onOpenChange: c.setOpenMobile,
+            children: /* @__PURE__ */ u(h.Portal, { children: [
               /* @__PURE__ */ n(h.Backdrop, { className: "ux-drawer-backdrop" }),
-              /* @__PURE__ */ d(h.Popup, { className: "ux-drawer", children: [
-                /* @__PURE__ */ n(h.Title, { className: "ux-visually-hidden", children: l.navigation }),
+              /* @__PURE__ */ u(h.Popup, { className: "ux-drawer", children: [
+                /* @__PURE__ */ n(h.Title, { className: "ux-visually-hidden", children: m.navigation }),
                 /* @__PURE__ */ n(
                   "button",
                   {
-                    "aria-label": l.closeNavigation,
+                    "aria-label": m.closeNavigation,
                     className: "ux-drawer__close",
                     type: "button",
-                    onClick: () => a.setOpenMobile(!1),
-                    children: /* @__PURE__ */ n(B, {})
+                    onClick: () => c.setOpenMobile(!1),
+                    children: /* @__PURE__ */ n(K, {})
                   }
                 ),
                 /* @__PURE__ */ n(
                   N,
                   {
-                    copy: l,
-                    logo: i,
-                    nav: r,
-                    onNavigate: () => a.setOpenMobile(!1),
+                    copy: m,
+                    logo: r,
+                    nav: o,
+                    onNavigate: () => c.setOpenMobile(!1),
                     state: "expanded",
-                    title: u
+                    title: d
                   }
                 )
               ] })
             ] })
           }
         ) : null,
-        /* @__PURE__ */ d("div", { className: "ux-shell", children: [
-          /* @__PURE__ */ d("header", { className: "ux-app-header", children: [
+        /* @__PURE__ */ u("div", { className: "ux-shell", children: [
+          /* @__PURE__ */ u("header", { className: "ux-app-header", children: [
             /* @__PURE__ */ n(
               "button",
               {
-                "aria-expanded": a.isMobile ? a.openMobile : a.open,
-                "aria-label": l.toggleSidebar,
+                "aria-expanded": c.isMobile ? c.openMobile : c.open,
+                "aria-label": m.toggleSidebar,
                 className: "ux-app-header__trigger",
                 type: "button",
-                onClick: a.toggleSidebar,
-                children: /* @__PURE__ */ n(F, {})
+                onClick: c.toggleSidebar,
+                children: /* @__PURE__ */ n(V, {})
               }
             ),
             /* @__PURE__ */ n("span", { "aria-hidden": "true", className: "ux-app-header__separator" }),
             /* @__PURE__ */ n("p", { className: "ux-app-header__title", children: S }),
-            /* @__PURE__ */ n("div", { className: "ux-app-header__slot", children: o }),
+            /* @__PURE__ */ n("div", { className: "ux-app-header__slot", children: a }),
             /* @__PURE__ */ n(O, {})
           ] }),
           /* @__PURE__ */ n("main", { className: "ux-main", children: e })
@@ -294,6 +319,116 @@ function te({
     }
   ) });
 }
+let ee = 0;
+function te() {
+  return document.documentElement.classList.contains("dark") ? "dark" : "neutral";
+}
+function ne() {
+  const e = getComputedStyle(document.documentElement).fontFamily.trim();
+  return e === "" ? "sans-serif" : e;
+}
+function re(e) {
+  const t = e ? Number.parseFloat(getComputedStyle(e).fontSize) : Number.NaN;
+  return !Number.isFinite(t) || t <= 0 ? 16 : Math.min(Math.max(t, 10), 20);
+}
+async function ae(e, t) {
+  try {
+    const { default: a } = await import("mermaid");
+    a.initialize({
+      startOnLoad: !1,
+      securityLevel: "strict",
+      theme: te(),
+      themeVariables: { fontFamily: ne(), fontSize: `${re(t)}px` }
+    });
+    const { svg: r } = await a.render(`ux-mermaid-${++ee}`, e);
+    return r;
+  } catch {
+    return null;
+  }
+}
+function oe({ source: e }) {
+  const [t, a] = g(null), r = f(null), o = f(0);
+  return v(() => {
+    const i = async () => {
+      const s = ++o.current, l = await ae(e, r.current);
+      o.current === s && a(l);
+    };
+    i();
+    const d = new MutationObserver(() => void i());
+    return d.observe(document.documentElement, { attributes: !0, attributeFilter: ["class"] }), () => {
+      o.current += 1, d.disconnect();
+    };
+  }, [e]), t === null ? /* @__PURE__ */ n(
+    "pre",
+    {
+      className: "ux-markdown__mermaid-source",
+      "data-mermaid": "source",
+      ref: (i) => {
+        r.current = i;
+      },
+      children: /* @__PURE__ */ n("code", { className: "language-mermaid", children: e })
+    }
+  ) : /* @__PURE__ */ n(
+    "div",
+    {
+      "aria-label": "Mermaid diagram",
+      className: "ux-markdown__mermaid",
+      "data-mermaid": "diagram",
+      dangerouslySetInnerHTML: { __html: t },
+      ref: (i) => {
+        r.current = i;
+      },
+      role: "img"
+    }
+  );
+}
+function ie(e) {
+  const t = e == null ? void 0 : e.children[0];
+  if ((t == null ? void 0 : t.type) !== "element" || t.tagName !== "code")
+    return null;
+  const a = t.properties.className;
+  if (!Array.isArray(a) || !a.includes("language-mermaid"))
+    return null;
+  const r = t.children[0];
+  return (r == null ? void 0 : r.type) === "text" ? r.value : null;
+}
+const se = {
+  a: ({ children: e, href: t, node: a, ...r }) => t ? le(t) ? /* @__PURE__ */ u("a", { ...r, href: t, rel: "noopener noreferrer", target: "_blank", children: [
+    e,
+    /* @__PURE__ */ n(G, {})
+  ] }) : /* @__PURE__ */ n("a", { ...r, href: t, children: e }) : /* @__PURE__ */ n("span", { ...r, children: e }),
+  pre: ({ children: e, node: t, ...a }) => {
+    const r = ie(t);
+    return r === null ? /* @__PURE__ */ n("pre", { ...a, children: e }) : /* @__PURE__ */ n(oe, { source: r });
+  },
+  // A wide table scrolls on its own; the transcript or article around it never grows a horizontal
+  // scrollbar, so the columns past the fold stay reachable.
+  table: ({ children: e, node: t, ...a }) => /* @__PURE__ */ n("div", { className: "ux-markdown__table", children: /* @__PURE__ */ n("table", { ...a, children: e }) })
+}, ce = /* @__PURE__ */ new Set(["http", "https", "mailto"]);
+function le(e) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(e) || e.startsWith("//");
+}
+function de(e) {
+  const t = e.trim(), a = t.indexOf(":");
+  if (a === -1)
+    return t;
+  const r = t.slice(0, a).toLowerCase();
+  return /^[a-z][a-z0-9+.-]*$/.test(r) ? ce.has(r) ? t : "" : t;
+}
+const ue = [F, I], me = [[P, { strict: "ignore", errorColor: "var(--ux-destructive)" }]];
+function Me({ content: e }) {
+  return /* @__PURE__ */ n("div", { className: "ux-markdown", children: /* @__PURE__ */ n(
+    T,
+    {
+      components: se,
+      rehypePlugins: me,
+      remarkPlugins: ue,
+      urlTransform: de,
+      children: e
+    }
+  ) });
+}
 export {
-  te as AppLayout
+  _e as AppLayout,
+  Me as Markdown
 };

package/dist/markdown.d.ts

@@ -0,0 +1,3 @@
+import type { MarkdownProps } from "./types.js";
+import "katex/dist/katex.min.css";
+export declare function Markdown({ content }: MarkdownProps): import("react").JSX.Element;

package/dist/mermaid.d.ts

@@ -0,0 +1,3 @@
+export declare function Mermaid({ source }: {
+    source: string;
+}): import("react").JSX.Element;

package/dist/styles.css

@@ -13,6 +13,10 @@
   --ux-foreground: var(--foreground, #0f172a);
   --ux-border: var(--border, #e2e8f0);
   --ux-accent: var(--accent, var(--muted, #f1f5f9));
+  --ux-muted: var(--muted, #f1f5f9);
+  --ux-muted-foreground: var(--muted-foreground, #64748b);
+  --ux-primary: var(--primary, #2563eb);
+  --ux-destructive: var(--destructive, #dc2626);
   --ux-ring: var(--ring, #2563eb);
   --ux-sidebar: var(--sidebar, #fafafa);
   --ux-sidebar-foreground: var(--sidebar-foreground, var(--foreground, #0f172a));
@@ -27,6 +31,10 @@
   --ux-foreground: var(--foreground, #f2f2f2);
   --ux-border: var(--border, #383838);
   --ux-accent: var(--accent, var(--muted, #303030));
+  --ux-muted: var(--muted, #262626);
+  --ux-muted-foreground: var(--muted-foreground, #a3a3a3);
+  --ux-primary: var(--primary, #60a5fa);
+  --ux-destructive: var(--destructive, #f87171);
   --ux-ring: var(--ring, #d4d4d4);
   --ux-sidebar: var(--sidebar, #161616);
   --ux-sidebar-foreground: var(--sidebar-foreground, var(--foreground, #f2f2f2));
@@ -462,3 +470,236 @@
     transition: none;
   }
 }
+
+/* --- Markdown --- */
+
+/*
+ * One typographic scale for every Markdown surface in the family: replies, checkpoints, manuals,
+ * documents and articles all render through <Markdown>. Every size here is relative to the
+ * inherited font size and no measure is imposed, so the same content keeps identical proportions
+ * inside a 14px chat bubble and a 16px article page — the host container decides the column, this
+ * block decides the rhythm.
+ */
+
+.ux-markdown {
+  min-width: 0;
+  line-height: 1.7;
+  overflow-wrap: break-word;
+}
+
+.ux-markdown > :first-child {
+  margin-top: 0;
+}
+
+.ux-markdown > :last-child {
+  margin-bottom: 0;
+}
+
+.ux-markdown p,
+.ux-markdown ul,
+.ux-markdown ol,
+.ux-markdown blockquote,
+.ux-markdown pre,
+.ux-markdown .ux-markdown__table,
+.ux-markdown .ux-markdown__mermaid {
+  margin: 0.75em 0;
+}
+
+.ux-markdown h1,
+.ux-markdown h2,
+.ux-markdown h3,
+.ux-markdown h4,
+.ux-markdown h5,
+.ux-markdown h6 {
+  margin: 1.5em 0 0.5em;
+  font-weight: 600;
+  line-height: 1.3;
+  letter-spacing: -0.01em;
+  text-wrap: balance;
+}
+
+.ux-markdown h1 {
+  font-size: 1.5em;
+}
+
+.ux-markdown h2 {
+  font-size: 1.25em;
+}
+
+.ux-markdown h3 {
+  font-size: 1.125em;
+}
+
+.ux-markdown h4,
+.ux-markdown h5,
+.ux-markdown h6 {
+  font-size: 1em;
+}
+
+.ux-markdown ul,
+.ux-markdown ol {
+  padding-left: 1.5em;
+}
+
+.ux-markdown ul {
+  list-style: disc;
+}
+
+.ux-markdown ol {
+  list-style: decimal;
+}
+
+.ux-markdown li {
+  margin: 0.25em 0;
+}
+
+.ux-markdown li > ul,
+.ux-markdown li > ol {
+  margin: 0.25em 0;
+}
+
+/* GFM task lists: the marker column disappears and the checkbox takes its place. */
+.ux-markdown ul.contains-task-list {
+  padding-left: 0.25em;
+  list-style: none;
+}
+
+.ux-markdown li.task-list-item {
+  list-style: none;
+}
+
+.ux-markdown li.task-list-item > input[type="checkbox"] {
+  margin: 0 0.4em 0 0;
+  vertical-align: 0.05em;
+}
+
+.ux-markdown blockquote {
+  padding-left: 1em;
+  color: var(--ux-muted-foreground);
+  border-left: 2px solid var(--ux-border);
+}
+
+.ux-markdown blockquote > :first-child {
+  margin-top: 0;
+}
+
+.ux-markdown blockquote > :last-child {
+  margin-bottom: 0;
+}
+
+.ux-markdown hr {
+  margin: 2em 0;
+  border: 0;
+  border-top: 1px solid var(--ux-border);
+}
+
+.ux-markdown a {
+  color: var(--ux-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+}
+
+.ux-markdown a:hover {
+  text-decoration-thickness: 2px;
+}
+
+/* Sized in `em` so the marker tracks the text it follows instead of sitting at a fixed 12px. */
+.ux-markdown .ux-markdown__external-link {
+  display: inline-block;
+  width: 0.75em;
+  height: 0.75em;
+  margin-left: 0.2em;
+  vertical-align: -0.05em;
+  color: var(--ux-muted-foreground);
+}
+
+.ux-markdown code {
+  padding: 0.15em 0.35em;
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+  font-size: 0.875em;
+  background: var(--ux-muted);
+  border-radius: 0.25rem;
+}
+
+.ux-markdown pre {
+  padding: 0.875em 1em;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  line-height: 1.55;
+  background: var(--ux-muted);
+  border-radius: 0.5rem;
+}
+
+.ux-markdown pre code {
+  padding: 0;
+  font-size: 0.8125em;
+  background: none;
+  border-radius: 0;
+}
+
+.ux-markdown .ux-markdown__table {
+  max-width: 100%;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+}
+
+/* Wide tables scroll; short ones still fill the column rather than shrinking to their content. */
+.ux-markdown table {
+  width: 100%;
+  min-width: max-content;
+  font-size: 0.9375em;
+  text-align: left;
+  border-collapse: collapse;
+}
+
+.ux-markdown th,
+.ux-markdown td {
+  padding: 0.4em 0.75em;
+  vertical-align: top;
+  border-bottom: 1px solid var(--ux-border);
+}
+
+.ux-markdown th {
+  font-weight: 600;
+}
+
+.ux-markdown tr:last-child td {
+  border-bottom: 0;
+}
+
+.ux-markdown img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 0.375rem;
+}
+
+.ux-markdown del {
+  color: var(--ux-muted-foreground);
+}
+
+.ux-markdown strong {
+  font-weight: 600;
+}
+
+/* Display math scrolls inside its own line instead of widening the surface around it. */
+.ux-markdown .katex-display {
+  padding: 0.25em 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+.ux-markdown .katex-error {
+  color: var(--ux-destructive);
+}
+
+.ux-markdown .ux-markdown__mermaid {
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+}
+
+.ux-markdown .ux-markdown__mermaid svg {
+  display: block;
+  max-width: none;
+  height: auto;
+  margin: 0 auto;
+}

package/dist/types.d.ts

@@ -17,3 +17,6 @@ export type AppLayoutProps = {
     pageTitle?: ReactNode;
     children: ReactNode;
 };
+export type MarkdownProps = {
+    content: string;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zccz14/ux",
-  "version": "0.3.0",
-  "description": "Unified AppLayout shell for the NTNL app family: one animated icon sidebar, a fixed-size logo that doubles as the page favicon, and the Linkit-integrated AppHeader.",
+  "version": "0.4.0",
+  "description": "Unified app shell and Markdown renderer for the NTNL app family: one animated icon sidebar, a fixed-size logo that doubles as the page favicon, the Linkit-integrated AppHeader, and the single Markdown surface every app renders through.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
   },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.build.json && cp src/styles.css dist/styles.css",
-    "test": "vitest run && node scripts/check-styles.mjs",
+    "test": "vitest run && node scripts/check-styles.mjs && node scripts/check-package.mjs",
     "typecheck": "tsc --noEmit",
     "pack:check": "npm pack --dry-run"
   },
@@ -44,10 +44,19 @@
     "react-dom": "^18.0.0 || ^19.0.0",
     "react-router-dom": "^7.0.0"
   },
+  "dependencies": {
+    "katex": "^0.16.47",
+    "mermaid": "^11.17.2",
+    "react-markdown": "^10.1.0",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-math-extended": "^6.1.1"
+  },
   "devDependencies": {
     "@base-ui/react": "^1.6.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
+    "@types/hast": "^3.0.5",
     "@types/react": "^19.1.16",
     "@types/react-dom": "^19.1.9",
     "auth-mini-react-components": "^0.6.10",