@zccz14/ux 0.3.0 → 0.5.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,164 @@ 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# @zccz14/ux
+
+`@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
+
+- **Sidebar** — one animated icon-collapse sidebar: 16rem expanded, 3rem collapsed, 200 ms width transition. Midas, 1Exchange and 1earn-style shells without animation are replaced by this behavior.
+- **Navigation groups only** — the sidebar has no separate bottom section. Settings and status destinations live in the navigation groups like every other destination, so the bottom edge of every app's sidebar looks the same.
+- **AppHeader** — sidebar trigger, current page title, your `headerSlot`, and the Linkit account control (`LinkitMyInfo`), in that order. Role badges such as 超级管理员 stay out of the shell: administrator affordances live in the administrator navigation group and pages.
+- **Favicon** — the same mark becomes the page favicon: the shell serialises the rendered logo into `link[rel="icon"]`, pins the colour the mark currently shows (a favicon has no app stylesheet, so `currentColor` would otherwise fall back to black), and re-renders it whenever the theme changes. Pass `favicon={false}` to keep an app-owned icon.
+- **Logo** — you pass one mark; the shell renders it inside a fixed 1.75rem box and controls the display size itself, so the logo size is identical everywhere. Pass a mark that follows the current colour (an icon using `currentColor`, or an SVG with mode-aware fills) so it keeps working in both themes. The title beside the logo disappears while collapsed.
+- **Linkit integration** — the viewer's language selects the shell copy (中文/English), and theme, language and account controls all live in the `LinkitMyInfo` dialog. The shell never reads the theme itself: it renders whatever colour scheme its own CSS resolves (see [Styling](#styling)).
+
+## Installation
+
+```sh
+npm install @zccz14/ux
+```
+
+Peer dependencies: `react` (18 or 19), `react-dom`, `react-router-dom` 7, `@base-ui/react` ≥ 1.6, `linkit-react-components` ≥ 0.6.
+
+## Usage
+
+```tsx
+import { AuthMiniProvider } from "auth-mini-react-components";
+import { LinkitProvider } from "linkit-react-components";
+import { AppLayout } from "@zccz14/ux";
+import { MessagesSquareIcon, ServerIcon } from "lucide-react";
+import { HashRouter, Navigate, Route, Routes } from "react-router-dom";
+
+import "@zccz14/ux/styles.css";
+import "linkit-react-components/styles.css";
+import { CybionMark } from "./cybion-mark";
+
+export function App() {
+  return (
+    <AuthMiniProvider
+      authMiniBaseUrl="https://auth.ntnl.io"
+      audiences={["cybion.ntnl.io", "linkit.ntnl.io"]}
+      autoRedirectToLogin
+    >
+      <LinkitProvider linkitBaseUrl="https://linkit.ntnl.io" lang="zh-CN">
+        <HashRouter>
+          <AppLayout
+            logo={<CybionMark />}
+            title="Cybion"
+            nav={[
+              {
+                label: "工作台",
+                items: [
+                  { to: "/threads", label: "对话", icon: <MessagesSquareIcon /> },
+                  { to: "/system", label: "系统资源", icon: <ServerIcon /> },
+                ],
+              },
+            ]}
+            headerSlot={<RefreshButton />}
+          >
+            <Routes>
+              <Route path="/threads" element={<ThreadsPage />} />
+              <Route path="*" element={<Navigate replace to="/threads" />} />
+            </Routes>
+          </AppLayout>
+        </HashRouter>
+      </LinkitProvider>
+    </AuthMiniProvider>
+  );
+}
+```
+
+`AppLayout` must render below `AuthMiniProvider → LinkitProvider` (it renders `LinkitMyInfo` and reads `useLinkit()`), and inside a router (navigation items render router links).
+
+## API
+
+### `AppLayout` props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `logo` | `ReactNode` | yes | The logo mark. The shell renders it at its own fixed 1.75rem size and mirrors it into the page favicon; pass a mark that follows the current colour. |
+| `favicon` | `boolean` | no | Defaults to `true`: the logo mark is written to `link[rel="icon"]` and re-rendered on theme changes. Set `false` to leave the app's own icon alone. |
+| `title` | `string` | yes | App name beside the logo. Hidden while the sidebar is collapsed. |
+| `nav` | `AppNavGroup[]` | yes | Navigation groups rendered in the sidebar. |
+| `headerSlot` | `ReactNode` | no | Rendered immediately left of `LinkitMyInfo` in the AppHeader. Use it for page-level actions such as refresh. |
+| `pageTitle` | `ReactNode` | no | Overrides the page title derived from the active navigation item. Use it for detail routes with their own title. |
+| `children` | `ReactNode` | yes | Page content, rendered in the scrollable main region. |
+
+### Navigation types
+
+```ts
+type AppNavItem = { to: string; label: string; icon: ReactNode };
+type AppNavGroup = { label: string; items: AppNavItem[] };
+```
+
+`to` is a router path. Each item renders a `NavLink`, so active items receive `aria-current="page"` and the standard active styling. Route matching uses longest-prefix wins, and `/` matches only exactly.
+
+## Behavior
+
+- **Page title** — the AppHeader shows the active navigation item's `label`, matched from `location.pathname`. `pageTitle` wins when supplied.
+- **Collapse** — the header trigger or `⌘B` / `Ctrl+B` toggles the sidebar; the choice persists in the `sidebar_state` cookie.
+- **Mobile** — below 768px the sidebar becomes a modal navigation drawer: the trigger opens it, tapping a link or the backdrop closes it.
+- **Collapsed tooltips** — icon-only items reveal their label in a tooltip on hover and focus.
+- **Reduced motion** — `prefers-reduced-motion: reduce` disables the animations.
+- **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.
+, `$…$`, `\(…\)`, `\[…\]` and `math`-tagged code fences, because models emit all of them. The stylesheet and fonts are imported by the component itself, so a formula is never unstyled; the runtime (~76 KB gzipped) is fetched only by a surface whose content can actually contain a formula, and stays cached for the rest of the session. Until that chunk arrives — and always when rendering on a server — a formula shows as the source it was written as, the same state a still-streaming formula is in. Broken math degrades to one `.katex-error` span carrying the parser message.
+- **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 chain away, and two pieces are deliberately kept out of the main bundle even for apps that do: Mermaid (loaded by the first diagram, so a surface without one never downloads it) and the math runtime (KaTeX's ~76 KB gzipped JavaScript, loaded by the first surface whose content may contain a formula). What stays static is KaTeX's stylesheet — about 3.6 KB gzipped, with fonts the browser only fetches once a formula is on screen — because a formula must never render unstyled. `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 +276,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,64 +1,67 @@
-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 { Dialog as h } from "@base-ui/react/dialog";
-import { Tooltip as m } 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 { jsxs as d, jsx as n, Fragment as T } from "react/jsx-runtime";
+import { useEffect as g, useRef as v, useState as x, useCallback as _, useSyncExternalStore as L } from "react";
+import { Dialog as f } from "@base-ui/react/dialog";
+import { Tooltip as h } from "@base-ui/react/tooltip";
+import { useLinkit as z, LinkitMyInfo as F } from "linkit-react-components";
+import { useLocation as C, NavLink as $ } from "react-router-dom";
+import I from "react-markdown";
+import A from "remark-gfm";
+import "katex/dist/katex.min.css";
+const R = {
   closeNavigation: "Close navigation",
   navigation: "Navigation",
   toggleSidebar: "Toggle sidebar"
-}, T = {
+}, W = {
   closeNavigation: "关闭导航",
   navigation: "导航",
   toggleSidebar: "切换侧边栏"
 };
-function A(e) {
-  return e.toLowerCase().startsWith("zh") ? T : P;
+function j(e) {
+  return e.toLowerCase().startsWith("zh") ? W : R;
 }
-const $ = 'link[rel~="icon"]';
-function R(e) {
+const B = 'link[rel~="icon"]';
+function q(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 D(e) {
   if (e instanceof SVGSVGElement)
     return {
-      href: `data:image/svg+xml,${encodeURIComponent(R(e))}`,
+      href: `data:image/svg+xml,${encodeURIComponent(q(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: r } = e, a = t || r;
+  return /\.svg([?#]|$)/i.test(a) ? { href: a, type: "image/svg+xml" } : { href: a };
 }
-function j() {
-  const e = document.querySelector($);
+function V() {
+  const e = document.querySelector(B);
   if (e)
     return e;
   const t = document.createElement("link");
   return t.rel = "icon", document.head.append(t), t;
 }
-function z(e, t) {
-  k(() => {
+function G(e, t) {
+  g(() => {
     if (!t)
       return;
-    const o = () => {
-      var l;
-      const p = (l = e.current) == null ? void 0 : l.querySelector("svg, img");
-      if (!p)
+    const r = () => {
+      var m;
+      const o = (m = e.current) == null ? void 0 : m.querySelector("svg, img");
+      if (!o)
         return;
-      const { href: u, type: s } = W(p), c = j();
+      const { href: u, type: s } = D(o), c = V();
       s ? c.type = s : c.removeAttribute("type"), c.getAttribute("href") !== u && c.setAttribute("href", u);
     };
-    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);
+    r();
+    const a = new MutationObserver(r);
+    a.observe(document.documentElement, { attributes: !0, attributeFilter: ["class", "style"] }), e.current && a.observe(e.current, { childList: !0, subtree: !0 });
+    const i = window.matchMedia("(prefers-color-scheme: dark)");
+    return i.addEventListener("change", r), () => {
+      a.disconnect(), i.removeEventListener("change", r);
     };
   }, [t, e]);
 }
-function B() {
+function K() {
   return /* @__PURE__ */ d(
     "svg",
     {
@@ -76,7 +79,7 @@ function B() {
     }
   );
 }
-function F() {
+function H() {
   return /* @__PURE__ */ d(
     "svg",
     {
@@ -94,174 +97,194 @@ 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 U() {
+  return /* @__PURE__ */ d(
+    "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" })
+      ]
+    }
+  );
 }
-function K(e) {
-  document.cookie = `${f}=${e}; path=/; max-age=${q}`;
+const k = "sidebar_state", Q = 3600 * 24 * 7, P = "(max-width: 767px)";
+function X() {
+  const e = document.cookie.split("; ").find((t) => t.startsWith(`${k}=`));
+  return e ? e.slice(k.length + 1) !== "false" : !0;
 }
-function G(e) {
-  const t = window.matchMedia(w);
+function J(e) {
+  document.cookie = `${k}=${e}; path=/; max-age=${Q}`;
+}
+function Y(e) {
+  const t = window.matchMedia(P);
   return t.addEventListener("change", e), () => t.removeEventListener("change", e);
 }
-function V() {
-  return C(
-    G,
-    () => window.matchMedia(w).matches,
+function Z() {
+  return L(
+    Y,
+    () => window.matchMedia(P).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 ee() {
+  const e = Z(), [t, r] = x(X), [a, i] = x(!1), o = _((s) => {
+    r(s), J(s);
+  }, []), u = _(() => {
     if (e) {
-      r((s) => !s);
+      i((s) => !s);
       return;
     }
-    p(!t);
-  }, [e, t, p]);
-  return k(() => {
+    o(!t);
+  }, [e, t, o]);
+  return g(() => {
     function s(c) {
       (c.metaKey || c.ctrlKey) && c.key === "b" && (c.preventDefault(), u());
     }
     return window.addEventListener("keydown", s), () => window.removeEventListener("keydown", s);
-  }, [u]), { isMobile: e, open: t, openMobile: i, setOpenMobile: r, toggleSidebar: u };
+  }, [u]), { isMobile: e, open: t, openMobile: a, setOpenMobile: i, toggleSidebar: u };
 }
-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 E(e, t) {
+  let r;
+  for (const a of e)
+    for (const i of a.items)
+      (i.to === "/" ? t === "/" : t === i.to || t.startsWith(`${i.to}/`)) && (!r || i.to.length > r.to.length) && (r = i);
+  return r;
 }
-function U({
+function te({
   collapsed: e,
   end: t,
-  item: o,
-  onNavigate: i
+  item: r,
+  onNavigate: a
 }) {
-  return /* @__PURE__ */ d(m.Root, { children: [
+  return /* @__PURE__ */ d(h.Root, { children: [
     /* @__PURE__ */ d(
-      m.Trigger,
+      h.Trigger,
       {
         render: /* @__PURE__ */ n(
-          I,
+          $,
           {
             className: "ux-nav-item",
             end: t,
-            onClick: i,
-            to: o.to
+            onClick: a,
+            to: r.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: r.icon }),
+          /* @__PURE__ */ n("span", { className: "ux-nav-item__text", children: r.label })
         ]
       }
     ),
-    /* @__PURE__ */ n(m.Portal, { children: /* @__PURE__ */ n(
-      m.Positioner,
+    /* @__PURE__ */ n(h.Portal, { children: /* @__PURE__ */ n(
+      h.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(h.Popup, { className: "ux-tooltip", hidden: !e, children: r.label })
       }
     ) })
   ] });
 }
-function N({
+function M({
   copy: e,
   logo: t,
-  logoRef: o,
-  nav: i,
-  onNavigate: r,
-  state: p,
+  logoRef: r,
+  nav: a,
+  onNavigate: i,
+  state: o,
   title: u
 }) {
-  const { pathname: s } = y(), c = _(i, s);
-  return /* @__PURE__ */ d(L, { children: [
+  const { pathname: s } = C(), c = E(a, s);
+  return /* @__PURE__ */ d(T, { 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__logo", ref: r, children: t }),
       /* @__PURE__ */ n("span", { className: "ux-sidebar__title", children: u })
     ] }),
-    /* @__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: a.map((m) => /* @__PURE__ */ d("div", { className: "ux-nav-group", children: [
+      /* @__PURE__ */ n("div", { className: "ux-nav-group__label", children: m.label }),
+      m.items.map((l) => (
         // 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,
+          te,
           {
-            collapsed: p === "collapsed",
-            end: a !== c || a.to === s,
-            item: a,
-            onNavigate: r
+            collapsed: o === "collapsed",
+            end: l !== c || l.to === s,
+            item: l,
+            onNavigate: i
           },
-          a.to
+          l.to
         )
       ))
-    ] }, l.label)) })
+    ] }, m.label)) })
   ] });
 }
-function te({
+function Ce({
   children: e,
   favicon: t = !0,
-  headerSlot: o,
-  logo: i,
-  nav: r,
-  pageTitle: p,
+  headerSlot: r,
+  logo: a,
+  nav: i,
+  pageTitle: o,
   title: u
 }) {
-  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 w;
+  const { pathname: s } = C(), { lang: c } = z(), m = j(c), l = ee(), N = v(null), O = o ?? ((w = E(i, s)) == null ? void 0 : w.label);
+  return G(N, t), /* @__PURE__ */ n(h.Provider, { delay: 0, children: /* @__PURE__ */ d(
     "div",
     {
       className: "ux-app-layout",
-      "data-state": a.open ? "expanded" : "collapsed",
+      "data-state": l.open ? "expanded" : "collapsed",
       children: [
         /* @__PURE__ */ n("aside", { className: "ux-sidebar", children: /* @__PURE__ */ n(
-          N,
+          M,
           {
-            copy: l,
-            logo: i,
-            logoRef: b,
-            nav: r,
-            state: a.open ? "expanded" : "collapsed",
+            copy: m,
+            logo: a,
+            logoRef: N,
+            nav: i,
+            state: l.open ? "expanded" : "collapsed",
             title: u
           }
         ) }),
-        a.isMobile ? /* @__PURE__ */ n(
-          h.Root,
+        l.isMobile ? /* @__PURE__ */ n(
+          f.Root,
           {
-            open: a.openMobile,
-            onOpenChange: a.setOpenMobile,
-            children: /* @__PURE__ */ d(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 }),
+            open: l.openMobile,
+            onOpenChange: l.setOpenMobile,
+            children: /* @__PURE__ */ d(f.Portal, { children: [
+              /* @__PURE__ */ n(f.Backdrop, { className: "ux-drawer-backdrop" }),
+              /* @__PURE__ */ d(f.Popup, { className: "ux-drawer", children: [
+                /* @__PURE__ */ n(f.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: () => l.setOpenMobile(!1),
+                    children: /* @__PURE__ */ n(K, {})
                   }
                 ),
                 /* @__PURE__ */ n(
-                  N,
+                  M,
                   {
-                    copy: l,
-                    logo: i,
-                    nav: r,
-                    onNavigate: () => a.setOpenMobile(!1),
+                    copy: m,
+                    logo: a,
+                    nav: i,
+                    onNavigate: () => l.setOpenMobile(!1),
                     state: "expanded",
                     title: u
                   }
@@ -275,18 +298,18 @@ function te({
             /* @__PURE__ */ n(
               "button",
               {
-                "aria-expanded": a.isMobile ? a.openMobile : a.open,
-                "aria-label": l.toggleSidebar,
+                "aria-expanded": l.isMobile ? l.openMobile : l.open,
+                "aria-label": m.toggleSidebar,
                 className: "ux-app-header__trigger",
                 type: "button",
-                onClick: a.toggleSidebar,
-                children: /* @__PURE__ */ n(F, {})
+                onClick: l.toggleSidebar,
+                children: /* @__PURE__ */ n(H, {})
               }
             ),
             /* @__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(O, {})
+            /* @__PURE__ */ n("p", { className: "ux-app-header__title", children: O }),
+            /* @__PURE__ */ n("div", { className: "ux-app-header__slot", children: r }),
+            /* @__PURE__ */ n(F, {})
           ] }),
           /* @__PURE__ */ n("main", { className: "ux-main", children: e })
         ] })
@@ -294,6 +317,147 @@ function te({
     }
   ) });
 }
+let ne = 0;
+function re() {
+  return document.documentElement.classList.contains("dark") ? "dark" : "neutral";
+}
+function ae() {
+  const e = getComputedStyle(document.documentElement).fontFamily.trim();
+  return e === "" ? "sans-serif" : e;
+}
+function ie(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 oe(e, t) {
+  try {
+    const { default: r } = await import("mermaid");
+    r.initialize({
+      startOnLoad: !1,
+      securityLevel: "strict",
+      theme: re(),
+      themeVariables: { fontFamily: ae(), fontSize: `${ie(t)}px` }
+    });
+    const { svg: a } = await r.render(`ux-mermaid-${++ne}`, e);
+    return a;
+  } catch {
+    return null;
+  }
+}
+function se({ source: e }) {
+  const [t, r] = x(null), a = v(null), i = v(0);
+  return g(() => {
+    const o = async () => {
+      const s = ++i.current, c = await oe(e, a.current);
+      i.current === s && r(c);
+    };
+    o();
+    const u = new MutationObserver(() => void o());
+    return u.observe(document.documentElement, { attributes: !0, attributeFilter: ["class"] }), () => {
+      i.current += 1, u.disconnect();
+    };
+  }, [e]), t === null ? /* @__PURE__ */ n(
+    "pre",
+    {
+      className: "ux-markdown__mermaid-source",
+      "data-mermaid": "source",
+      ref: (o) => {
+        a.current = o;
+      },
+      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: (o) => {
+        a.current = o;
+      },
+      role: "img"
+    }
+  );
+}
+let p = null, b = null;
+const y = /* @__PURE__ */ new Set();
+function le(e) {
+  return y.add(e), () => {
+    y.delete(e);
+  };
+}
+function ce() {
+  return p !== null;
+}
+const ue = /^ {0,3}(?:```|~~~)\s*math\b/m;
+function de(e) {
+  return e.includes("$") || e.includes("\\(") || e.includes("\\[") || ue.test(e);
+}
+function me() {
+  return b ?? (b = Promise.all([import("remark-math-extended"), import("rehype-katex")]).then(([e, t]) => {
+    p = {
+      remarkPlugins: [e.default],
+      rehypePlugins: [
+        [t.default, { strict: "ignore", errorColor: "var(--ux-destructive)" }]
+      ]
+    };
+    for (const r of y)
+      r();
+  }).catch(() => {
+    b = null;
+  })), b;
+}
+function he(e) {
+  const t = e == null ? void 0 : e.children[0];
+  if ((t == null ? void 0 : t.type) !== "element" || t.tagName !== "code")
+    return null;
+  const r = t.properties.className;
+  if (!Array.isArray(r) || !r.includes("language-mermaid"))
+    return null;
+  const a = t.children[0];
+  return (a == null ? void 0 : a.type) === "text" ? a.value : null;
+}
+const pe = {
+  a: ({ children: e, href: t, node: r, ...a }) => t ? ge(t) ? /* @__PURE__ */ d("a", { ...a, href: t, rel: "noopener noreferrer", target: "_blank", children: [
+    e,
+    /* @__PURE__ */ n(U, {})
+  ] }) : /* @__PURE__ */ n("a", { ...a, href: t, children: e }) : /* @__PURE__ */ n("span", { ...a, children: e }),
+  pre: ({ children: e, node: t, ...r }) => {
+    const a = he(t);
+    return a === null ? /* @__PURE__ */ n("pre", { ...r, children: e }) : /* @__PURE__ */ n(se, { source: a });
+  },
+  // 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, ...r }) => /* @__PURE__ */ n("div", { className: "ux-markdown__table", children: /* @__PURE__ */ n("table", { ...r, children: e }) })
+}, fe = /* @__PURE__ */ new Set(["http", "https", "mailto"]);
+function ge(e) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(e) || e.startsWith("//");
+}
+function be(e) {
+  const t = e.trim(), r = t.indexOf(":");
+  if (r === -1)
+    return t;
+  const a = t.slice(0, r).toLowerCase();
+  return /^[a-z][a-z0-9+.-]*$/.test(a) ? fe.has(a) ? t : "" : t;
+}
+const S = [A], ve = [];
+function Pe({ content: e }) {
+  const t = L(le, ce, () => !1);
+  return g(() => {
+    !t && de(e) && me();
+  }, [e, t]), /* @__PURE__ */ n("div", { className: "ux-markdown", children: /* @__PURE__ */ n(
+    I,
+    {
+      components: pe,
+      rehypePlugins: t && p ? p.rehypePlugins : ve,
+      remarkPlugins: t && p ? [...S, ...p.remarkPlugins] : S,
+      urlTransform: be,
+      children: e
+    }
+  ) });
+}
 export {
-  te as AppLayout
+  Ce as AppLayout,
+  Pe 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.5.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",