@zccz14/ux 0.2.1 → 0.4.0

package/README.md

@@ -1,12 +1,13 @@
 # @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
 
 - **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)).
 
@@ -74,7 +75,8 @@ export function App() {
 
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
-| `logo` | `ReactNode` | yes | The logo mark. The shell renders it at its own fixed 1.75rem size; pass a mark that follows the current colour. |
+| `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. |
@@ -97,11 +99,48 @@ type AppNavGroup = { label: string; items: AppNavItem[] };
 - **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.
+- **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.
 
@@ -113,13 +152,14 @@ Theme state itself is not the shell's business: whatever toggles `.dark` on `<ht
 2. Move legacy header buttons (refresh, settings, language, theme) into `headerSlot`. Role badges are dropped: administrator affordances belong to the administrator navigation group and pages, and theme/language preferences live in the `LinkitMyInfo` profile dialog (`linkit-react-components` 0.6+).
 3. Move any sidebar footer item (settings, environment status) into the last navigation group.
 4. Pass the single logo mark and delete per-call sizes; the shell normalizes every mark to its 1.75rem box.
+5. Delete the app's own `applyFavicon` / favicon effect: the shell now owns `link[rel="icon"]`. Keep a hand-written favicon only by passing `favicon={false}`.
 
 ## 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/app-layout.d.ts

@@ -1,2 +1,2 @@
 import type { AppLayoutProps } from "./types.js";
-export declare function AppLayout({ children, headerSlot, logo, nav, pageTitle, title, }: AppLayoutProps): import("react").JSX.Element;
+export declare function AppLayout({ children, favicon, headerSlot, logo, nav, pageTitle, title, }: AppLayoutProps): import("react").JSX.Element;

package/dist/favicon.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject } from "react";
+/**
+ * Mirrors the rendered logo into the page favicon: the tab shows the same mark
+ * as the sidebar, including its current colour, and follows theme changes.
+ */
+export declare function useLogoFavicon(logo: RefObject<HTMLElement | null>, enabled: boolean): void;

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,23 +1,70 @@
-import { jsxs as s, jsx as e, Fragment as y } from "react/jsx-runtime";
-import { useState as f, useCallback as g, useEffect as w, useSyncExternalStore as M } 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 p } from "@base-ui/react/tooltip";
-import { useLinkit as L, LinkitMyInfo as S } from "linkit-react-components";
-import { useLocation as v, NavLink as C } from "react-router-dom";
-const O = {
+import { useLinkit as E, LinkitMyInfo as O } from "linkit-react-components";
+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"
-}, P = {
+}, A = {
   closeNavigation: "关闭导航",
   navigation: "导航",
   toggleSidebar: "切换侧边栏"
 };
-function I(a) {
-  return a.toLowerCase().startsWith("zh") ? P : O;
+function W(e) {
+  return e.toLowerCase().startsWith("zh") ? A : $;
 }
-function E() {
-  return /* @__PURE__ */ s(
+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 B(e) {
+  if (e instanceof SVGSVGElement)
+    return {
+      href: `data:image/svg+xml,${encodeURIComponent(j(e))}`,
+      type: "image/svg+xml"
+    };
+  const { currentSrc: t, src: a } = e, r = t || a;
+  return /\.svg([?#]|$)/i.test(r) ? { href: r, type: "image/svg+xml" } : { href: r };
+}
+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 D(e, t) {
+  v(() => {
+    if (!t)
+      return;
+    const a = () => {
+      var m;
+      const i = (m = e.current) == null ? void 0 : m.querySelector("svg, img");
+      if (!i)
+        return;
+      const { href: d, type: s } = B(i), l = q();
+      s ? l.type = s : l.removeAttribute("type"), l.getAttribute("href") !== d && l.setAttribute("href", d);
+    };
+    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 K() {
+  return /* @__PURE__ */ u(
     "svg",
     {
       "aria-hidden": "true",
@@ -28,14 +75,14 @@ function E() {
       strokeWidth: "2",
       viewBox: "0 0 24 24",
       children: [
-        /* @__PURE__ */ e("path", { d: "M18 6 6 18" }),
-        /* @__PURE__ */ e("path", { d: "m6 6 12 12" })
+        /* @__PURE__ */ n("path", { d: "M18 6 6 18" }),
+        /* @__PURE__ */ n("path", { d: "m6 6 12 12" })
       ]
     }
   );
 }
-function T() {
-  return /* @__PURE__ */ s(
+function V() {
+  return /* @__PURE__ */ u(
     "svg",
     {
       "aria-hidden": "true",
@@ -46,177 +93,200 @@ function T() {
       strokeWidth: "2",
       viewBox: "0 0 24 24",
       children: [
-        /* @__PURE__ */ e("rect", { height: "18", rx: "2", width: "18", x: "3", y: "3" }),
-        /* @__PURE__ */ e("path", { d: "M9 3v18" })
+        /* @__PURE__ */ n("rect", { height: "18", rx: "2", width: "18", x: "3", y: "3" }),
+        /* @__PURE__ */ n("path", { d: "M9 3v18" })
       ]
     }
   );
 }
-const m = "sidebar_state", W = 3600 * 24 * 7, N = "(max-width: 767px)";
-function $() {
-  const a = document.cookie.split("; ").find((n) => n.startsWith(`${m}=`));
-  return a ? a.slice(m.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 j(a) {
-  document.cookie = `${m}=${a}; path=/; max-age=${W}`;
+function Q(e) {
+  document.cookie = `${b}=${e}; path=/; max-age=${H}`;
 }
-function B(a) {
-  const n = window.matchMedia(N);
-  return n.addEventListener("change", a), () => n.removeEventListener("change", a);
+function X(e) {
+  const t = window.matchMedia(_);
+  return t.addEventListener("change", e), () => t.removeEventListener("change", e);
 }
-function A() {
-  return M(
-    B,
-    () => window.matchMedia(N).matches,
+function J() {
+  return C(
+    X,
+    () => window.matchMedia(_).matches,
     () => !1
   );
 }
-function D() {
-  const a = A(), [n, t] = f($), [l, r] = f(!1), d = g((c) => {
-    t(c), j(c);
-  }, []), u = g(() => {
-    if (a) {
-      r((c) => !c);
+function Y() {
+  const e = J(), [t, a] = g(U), [r, o] = g(!1), i = y((s) => {
+    a(s), Q(s);
+  }, []), d = y(() => {
+    if (e) {
+      o((s) => !s);
       return;
     }
-    d(!n);
-  }, [a, n, d]);
-  return w(() => {
-    function c(i) {
-      (i.metaKey || i.ctrlKey) && i.key === "b" && (i.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", c), () => window.removeEventListener("keydown", c);
-  }, [u]), { isMobile: a, open: n, openMobile: l, setOpenMobile: r, toggleSidebar: u };
-}
-function k(a, n) {
-  let t;
-  for (const l of a)
-    for (const r of l.items)
-      (r.to === "/" ? n === "/" : n === r.to || n.startsWith(`${r.to}/`)) && (!t || r.to.length > t.to.length) && (t = r);
-  return t;
-}
-function K({
-  collapsed: a,
-  end: n,
-  item: t,
-  onNavigate: l
+    return window.addEventListener("keydown", s), () => window.removeEventListener("keydown", s);
+  }, [d]), { isMobile: e, open: t, openMobile: r, setOpenMobile: o, toggleSidebar: d };
+}
+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 Z({
+  collapsed: e,
+  end: t,
+  item: a,
+  onNavigate: r
 }) {
-  return /* @__PURE__ */ s(p.Root, { children: [
-    /* @__PURE__ */ s(
+  return /* @__PURE__ */ u(p.Root, { children: [
+    /* @__PURE__ */ u(
       p.Trigger,
       {
-        render: /* @__PURE__ */ e(
-          C,
+        render: /* @__PURE__ */ n(
+          z,
           {
             className: "ux-nav-item",
-            end: n,
-            onClick: l,
-            to: t.to
+            end: t,
+            onClick: r,
+            to: a.to
           }
         ),
         children: [
-          /* @__PURE__ */ e("span", { className: "ux-nav-item__icon", children: t.icon }),
-          /* @__PURE__ */ e("span", { className: "ux-nav-item__text", children: t.label })
+          /* @__PURE__ */ n("span", { className: "ux-nav-item__icon", children: a.icon }),
+          /* @__PURE__ */ n("span", { className: "ux-nav-item__text", children: a.label })
         ]
       }
     ),
-    /* @__PURE__ */ e(p.Portal, { children: /* @__PURE__ */ e(
+    /* @__PURE__ */ n(p.Portal, { children: /* @__PURE__ */ n(
       p.Positioner,
       {
         className: "ux-tooltip-positioner",
         side: "right",
         sideOffset: 6,
-        children: /* @__PURE__ */ e(p.Popup, { className: "ux-tooltip", hidden: !a, children: t.label })
+        children: /* @__PURE__ */ n(p.Popup, { className: "ux-tooltip", hidden: !e, children: a.label })
       }
     ) })
   ] });
 }
-function x({
-  copy: a,
-  logo: n,
-  nav: t,
-  onNavigate: l,
-  state: r,
+function N({
+  copy: e,
+  logo: t,
+  logoRef: a,
+  nav: r,
+  onNavigate: o,
+  state: i,
   title: d
 }) {
-  const { pathname: u } = v(), c = k(t, u);
-  return /* @__PURE__ */ s(y, { children: [
-    /* @__PURE__ */ s("div", { className: "ux-sidebar__header", children: [
-      /* @__PURE__ */ e("span", { className: "ux-sidebar__logo", children: n }),
-      /* @__PURE__ */ e("span", { className: "ux-sidebar__title", children: d })
+  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__ */ e("nav", { "aria-label": a.navigation, className: "ux-sidebar__nav", children: t.map((i) => /* @__PURE__ */ s("div", { className: "ux-nav-group", children: [
-      /* @__PURE__ */ e("div", { className: "ux-nav-group__label", children: i.label }),
-      i.items.map((o) => (
+    /* @__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__ */ e(
-          K,
+        /* @__PURE__ */ n(
+          Z,
           {
-            collapsed: r === "collapsed",
-            end: o !== c || o.to === u,
-            item: o,
-            onNavigate: l
+            collapsed: i === "collapsed",
+            end: c !== l || c.to === s,
+            item: c,
+            onNavigate: o
           },
-          o.to
+          c.to
         )
       ))
-    ] }, i.label)) })
+    ] }, m.label)) })
   ] });
 }
-function H({
-  children: a,
-  headerSlot: n,
-  logo: t,
-  nav: l,
-  pageTitle: r,
+function _e({
+  children: e,
+  favicon: t = !0,
+  headerSlot: a,
+  logo: r,
+  nav: o,
+  pageTitle: i,
   title: d
 }) {
-  var b;
-  const { pathname: u } = v(), { lang: c } = L(), i = I(c), o = D(), _ = r ?? ((b = k(l, u)) == null ? void 0 : b.label);
-  return /* @__PURE__ */ e(p.Provider, { delay: 0, children: /* @__PURE__ */ s(
+  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": o.open ? "expanded" : "collapsed",
+      "data-state": c.open ? "expanded" : "collapsed",
       children: [
-        /* @__PURE__ */ e("aside", { className: "ux-sidebar", children: /* @__PURE__ */ e(
-          x,
+        /* @__PURE__ */ n("aside", { className: "ux-sidebar", children: /* @__PURE__ */ n(
+          N,
           {
-            copy: i,
-            logo: t,
-            nav: l,
-            state: o.open ? "expanded" : "collapsed",
+            copy: m,
+            logo: r,
+            logoRef: x,
+            nav: o,
+            state: c.open ? "expanded" : "collapsed",
             title: d
           }
         ) }),
-        o.isMobile ? /* @__PURE__ */ e(
+        c.isMobile ? /* @__PURE__ */ n(
           h.Root,
           {
-            open: o.openMobile,
-            onOpenChange: o.setOpenMobile,
-            children: /* @__PURE__ */ s(h.Portal, { children: [
-              /* @__PURE__ */ e(h.Backdrop, { className: "ux-drawer-backdrop" }),
-              /* @__PURE__ */ s(h.Popup, { className: "ux-drawer", children: [
-                /* @__PURE__ */ e(h.Title, { className: "ux-visually-hidden", children: i.navigation }),
-                /* @__PURE__ */ e(
+            open: c.openMobile,
+            onOpenChange: c.setOpenMobile,
+            children: /* @__PURE__ */ u(h.Portal, { children: [
+              /* @__PURE__ */ n(h.Backdrop, { className: "ux-drawer-backdrop" }),
+              /* @__PURE__ */ u(h.Popup, { className: "ux-drawer", children: [
+                /* @__PURE__ */ n(h.Title, { className: "ux-visually-hidden", children: m.navigation }),
+                /* @__PURE__ */ n(
                   "button",
                   {
-                    "aria-label": i.closeNavigation,
+                    "aria-label": m.closeNavigation,
                     className: "ux-drawer__close",
                     type: "button",
-                    onClick: () => o.setOpenMobile(!1),
-                    children: /* @__PURE__ */ e(E, {})
+                    onClick: () => c.setOpenMobile(!1),
+                    children: /* @__PURE__ */ n(K, {})
                   }
                 ),
-                /* @__PURE__ */ e(
-                  x,
+                /* @__PURE__ */ n(
+                  N,
                   {
-                    copy: i,
-                    logo: t,
-                    nav: l,
-                    onNavigate: () => o.setOpenMobile(!1),
+                    copy: m,
+                    logo: r,
+                    nav: o,
+                    onNavigate: () => c.setOpenMobile(!1),
                     state: "expanded",
                     title: d
                   }
@@ -225,30 +295,140 @@ function H({
             ] })
           }
         ) : null,
-        /* @__PURE__ */ s("div", { className: "ux-shell", children: [
-          /* @__PURE__ */ s("header", { className: "ux-app-header", children: [
-            /* @__PURE__ */ e(
+        /* @__PURE__ */ u("div", { className: "ux-shell", children: [
+          /* @__PURE__ */ u("header", { className: "ux-app-header", children: [
+            /* @__PURE__ */ n(
               "button",
               {
-                "aria-expanded": o.isMobile ? o.openMobile : o.open,
-                "aria-label": i.toggleSidebar,
+                "aria-expanded": c.isMobile ? c.openMobile : c.open,
+                "aria-label": m.toggleSidebar,
                 className: "ux-app-header__trigger",
                 type: "button",
-                onClick: o.toggleSidebar,
-                children: /* @__PURE__ */ e(T, {})
+                onClick: c.toggleSidebar,
+                children: /* @__PURE__ */ n(V, {})
               }
             ),
-            /* @__PURE__ */ e("span", { "aria-hidden": "true", className: "ux-app-header__separator" }),
-            /* @__PURE__ */ e("p", { className: "ux-app-header__title", children: _ }),
-            /* @__PURE__ */ e("div", { className: "ux-app-header__slot", children: n }),
-            /* @__PURE__ */ e(S, {})
+            /* @__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: a }),
+            /* @__PURE__ */ n(O, {})
           ] }),
-          /* @__PURE__ */ e("main", { className: "ux-main", children: a })
+          /* @__PURE__ */ n("main", { className: "ux-main", children: e })
         ] })
       ]
     }
   ) });
 }
+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 {
-  H 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

@@ -9,6 +9,7 @@ export type AppNavGroup = {
     items: AppNavItem[];
 };
 export type AppLayoutProps = {
+    favicon?: boolean;
     logo: ReactNode;
     title: string;
     nav: AppNavGroup[];
@@ -16,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.2.1",
-  "description": "Unified AppLayout shell for the NTNL app family: one animated icon sidebar, a fixed-size logo box, 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",