@veluai/velu 0.2.19 → 0.2.23

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "@veluai/velu",
-  "version": "0.2.19",
-  "type": "module",
-  "bin": "./dist/cli.js",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist/**",
-    "src/runtime/**",
-    "src/navigation.js",
-    "src/template.html",
-    "src/lib/issues.js",
-    "src/lib/extract-mdx-error.js",
-    "src/lib/known-components.js",
-    "runtime/velu-ui/**",
-    "schema/**",
-    "templates/**"
-  ],
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepack": "node scripts/build.mjs",
-    "build:preview-runtime": "vite build -c vite.preview.config.mjs",
-    "test:parity": "node scripts/parity-test.mjs"
-  },
-  "dependencies": {
-    "@apidevtools/swagger-parser": "^10.1.0",
-    "@icons-pack/react-simple-icons": ">=13.0.0 <13.13.0",
-    "@mdx-js/mdx": "^3.1.1",
-    "@mdx-js/react": "^3.1.1",
-    "@mdx-js/rollup": "^3.1.1",
-    "@tailwindcss/vite": "^4.1.0",
-    "@vitejs/plugin-react": "^4.3.4",
-    "chokidar": "^3.6.0",
-    "estree-util-value-to-estree": "^3.5.0",
-    "express": "^4.21.1",
-    "github-slugger": "^2.0.0",
-    "iso-639-1": "^3.1.5",
-    "js-yaml": "^4.1.0",
-    "lucide-react": "^0.460.0",
-    "mdast-util-to-string": "^4.0.0",
-    "prism-react-renderer": "^2.4.0",
-    "prismjs": "^1.29.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-router-dom": "^6.28.0",
-    "rehype-slug": "^6.0.0",
-    "remark-frontmatter": "^5.0.0",
-    "remark-gfm": "^4.0.1",
-    "remark-mdx-frontmatter": "^5.2.0",
-    "tailwindcss": "^4.1.0",
-    "unist-util-visit": "^5.1.0",
-    "vite": "^5.4.11"
-  },
-  "devDependencies": {
-    "@fontsource/outfit": "^5.0.0",
-    "@resvg/resvg-js": "^2.6.2",
-    "esbuild": "^0.28.0",
-    "pagefind": "^1.3.0",
-    "playwright": "^1.48.0",
-    "satori": "^0.12.0"
-  }
-}
+{
+  "name": "@veluai/velu",
+  "version": "0.2.23",
+  "type": "module",
+  "bin": "./dist/cli.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**",
+    "src/runtime/**",
+    "src/navigation.js",
+    "src/template.html",
+    "src/lib/issues.js",
+    "src/lib/extract-mdx-error.js",
+    "src/lib/known-components.js",
+    "runtime/velu-ui/**",
+    "schema/**",
+    "templates/**"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "build:preview-runtime": "vite build -c vite.preview.config.mjs",
+    "test:parity": "node scripts/parity-test.mjs"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.0",
+    "@icons-pack/react-simple-icons": ">=13.0.0 <13.13.0",
+    "@mdx-js/mdx": "^3.1.1",
+    "@mdx-js/react": "^3.1.1",
+    "@mdx-js/rollup": "^3.1.1",
+    "@tailwindcss/vite": "^4.1.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "chokidar": "^3.6.0",
+    "estree-util-value-to-estree": "^3.5.0",
+    "express": "^4.21.1",
+    "github-slugger": "^2.0.0",
+    "iso-639-1": "^3.1.5",
+    "js-yaml": "^4.1.0",
+    "lucide-react": "^0.460.0",
+    "mdast-util-to-string": "^4.0.0",
+    "prism-react-renderer": "^2.4.0",
+    "prismjs": "^1.29.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "tailwindcss": "^4.1.0",
+    "unist-util-visit": "^5.1.0",
+    "vite": "^5.4.11"
+  },
+  "devDependencies": {
+    "@fontsource/outfit": "^5.0.0",
+    "@resvg/resvg-js": "^2.6.2",
+    "esbuild": "^0.28.0",
+    "pagefind": "^1.3.0",
+    "playwright": "^1.48.0",
+    "satori": "^0.12.0"
+  }
+}

package/runtime/velu-ui/components/ChangelogFilters.jsx

@@ -0,0 +1,75 @@
+import React, { useEffect, useState } from 'react';
+
+/**
+ * ChangelogFilters — replaces the table of contents on a changelog page with a
+ * tag filter. The tag set is passed in (collected at build time from each
+ * <Update tags=...>); toggling a tag shows/hides the matching entries purely
+ * from the DOM via the `data-update-tags` attribute each <Update> emits.
+ *
+ * An entry is shown when no tag is selected, or when it carries any selected
+ * tag (OR semantics).
+ *
+ * @param {{ tags?: string[] }} props
+ */
+export default function ChangelogFilters({ tags = [] }) {
+  const [selected, setSelected] = useState([]);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return undefined;
+    const sel = selected.map((s) => s.toLowerCase());
+    const nodes = document.querySelectorAll('.velu-update');
+    nodes.forEach((el) => {
+      const own = (el.getAttribute('data-update-tags') || '')
+        .split('|')
+        .map((t) => t.trim().toLowerCase())
+        .filter(Boolean);
+      const visible = sel.length === 0 || sel.some((s) => own.includes(s));
+      el.hidden = !visible;
+    });
+    return () => {
+      document.querySelectorAll('.velu-update').forEach((el) => {
+        el.hidden = false;
+      });
+    };
+  }, [selected]);
+
+  if (!tags.length) return null;
+
+  const toggle = (tag) => {
+    const lower = tag.toLowerCase();
+    setSelected((prev) =>
+      prev.some((s) => s.toLowerCase() === lower)
+        ? prev.filter((s) => s.toLowerCase() !== lower)
+        : [...prev, tag],
+    );
+  };
+
+  return (
+    <div className="velu-changelog-filters">
+      <div className="velu-changelog-filters__heading">Filters</div>
+      <div
+        className="velu-changelog-filters__list"
+        role="group"
+        aria-label="Filter updates by tag"
+      >
+        {tags.map((tag) => {
+          const active = selected.some((s) => s.toLowerCase() === tag.toLowerCase());
+          return (
+            <button
+              key={tag}
+              type="button"
+              className={
+                'velu-changelog-filter' +
+                (active ? ' velu-changelog-filter--active' : '')
+              }
+              aria-pressed={active}
+              onClick={() => toggle(tag)}
+            >
+              {tag}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/runtime/velu-ui/components/Chatbot.jsx

@@ -195,48 +195,135 @@ function onSourceClick(e, s, onNavigate) {
 }
 
 /* Render partial tokens as paragraphs (split on \n\n, single \n → <br>). */
+/* Flatten the token stream back to a markdown string (code → `…`, citation →
+   [n]) so the assistant's markdown answer can be rendered with formatting. */
+function tokensToMarkdown(tokens) {
+  return tokens
+    .map((tk) => (tk.kind === 'cite' ? `[${tk.n}]` : tk.kind === 'code' ? `\`${tk.v}\`` : tk.v))
+    .join('');
+}
+
+const CITE_RE = /\[(\d+)\]/;
+const INLINE_RULES = [
+  { re: /\*\*([^*]+)\*\*/, type: 'bold' },
+  { re: /__([^_]+)__/, type: 'bold' },
+  { re: /\*([^*\n]+)\*/, type: 'italic' },
+  { re: /(?<![A-Za-z0-9_])_([^_\n]+)_(?![A-Za-z0-9_])/, type: 'italic' },
+  { re: /`([^`]+)`/, type: 'code' },
+  { re: /\[([^\]]+)\]\(([^)]+)\)/, type: 'link' },
+  { re: CITE_RE, type: 'cite' },
+];
+
+/* Inline markdown → React nodes: **bold**, *italic*, `code`, [text](url) links,
+   and [n] citation chips. Builds React elements (never innerHTML) so it's XSS-safe. */
+function renderInline(text, sources, onNavigate, keyBase) {
+  const out = [];
+  let rest = text;
+  let k = 0;
+  while (rest) {
+    let best = null;
+    for (const rule of INLINE_RULES) {
+      const m = rule.re.exec(rest);
+      if (m && (best === null || m.index < best.m.index)) best = { rule, m };
+    }
+    if (!best) {
+      out.push(<React.Fragment key={`${keyBase}-${k++}`}>{rest}</React.Fragment>);
+      break;
+    }
+    const { rule, m } = best;
+    if (m.index > 0) out.push(<React.Fragment key={`${keyBase}-${k++}`}>{rest.slice(0, m.index)}</React.Fragment>);
+    const key = `${keyBase}-${k++}`;
+    if (rule.type === 'bold') out.push(<strong key={key}>{m[1]}</strong>);
+    else if (rule.type === 'italic') out.push(<em key={key}>{m[1]}</em>);
+    else if (rule.type === 'code') out.push(<code key={key}>{m[1]}</code>);
+    else if (rule.type === 'link') out.push(
+      <a key={key} href={m[2]} target="_blank" rel="noopener noreferrer">{m[1]}</a>,
+    );
+    else if (rule.type === 'cite') {
+      const n = Number(m[1]);
+      const src = sources?.find((s) => s.num === n);
+      out.push(
+        <a
+          key={key}
+          className="velu-chatbot__cite"
+          href={sourceHref(src) || '#'}
+          onClick={(e) => onSourceClick(e, src, onNavigate)}
+          title={citeTitle(src)}
+        >
+          {n}
+        </a>,
+      );
+    }
+    rest = rest.slice(m.index + m[0].length);
+  }
+  return out;
+}
+
+/* Block-level markdown → React: headings, bullet/numbered lists, fenced code
+   blocks, blockquotes, and paragraphs (each rendered through renderInline). */
 function renderStream(tokens, sources, onNavigate) {
-  const paragraphs = [[]];
-  for (const tk of tokens) {
-    if (tk.kind === 't' && tk.v.includes('\n\n')) {
-      const split = tk.v.split('\n\n');
-      paragraphs[paragraphs.length - 1].push({ kind: 't', v: split[0] });
-      for (let i = 1; i < split.length; i++) {
-        paragraphs.push([]);
-        if (split[i]) paragraphs[paragraphs.length - 1].push({ kind: 't', v: split[i] });
+  const text = tokensToMarkdown(tokens);
+  const lines = text.replace(/\r/g, '').split('\n');
+  const blocks = [];
+  let i = 0;
+  let b = 0;
+  const listRe = /^\s*([-*+]|\d+\.)\s+/;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim()) { i++; continue; }
+
+    if (line.trim().startsWith('```')) {
+      const buf = [];
+      i++;
+      while (i < lines.length && !lines[i].trim().startsWith('```')) { buf.push(lines[i]); i++; }
+      i++;
+      blocks.push(<pre key={`b${b++}`} className="velu-chatbot__pre"><code>{buf.join('\n')}</code></pre>);
+      continue;
+    }
+
+    const h = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (h) {
+      const lvl = Math.min(h[1].length + 2, 6);
+      const Tag = `h${lvl}`;
+      blocks.push(<Tag key={`b${b++}`}>{renderInline(h[2], sources, onNavigate, `b${b}`)}</Tag>);
+      i++;
+      continue;
+    }
+
+    if (listRe.test(line)) {
+      const ordered = /^\s*\d+\.\s+/.test(line);
+      const items = [];
+      while (i < lines.length && listRe.test(lines[i])) {
+        const content = lines[i].replace(listRe, '');
+        items.push(<li key={`li${b}-${i}`}>{renderInline(content, sources, onNavigate, `li${b}-${i}`)}</li>);
+        i++;
       }
-    } else {
-      paragraphs[paragraphs.length - 1].push(tk);
+      const ListTag = ordered ? 'ol' : 'ul';
+      blocks.push(<ListTag key={`b${b++}`}>{items}</ListTag>);
+      continue;
+    }
+
+    if (line.trim().startsWith('>')) {
+      const buf = [];
+      while (i < lines.length && lines[i].trim().startsWith('>')) { buf.push(lines[i].replace(/^\s*>\s?/, '')); i++; }
+      blocks.push(<blockquote key={`b${b++}`}>{renderInline(buf.join(' '), sources, onNavigate, `bq${b}`)}</blockquote>);
+      continue;
     }
+
+    const buf = [];
+    while (
+      i < lines.length && lines[i].trim()
+      && !listRe.test(lines[i]) && !/^#{1,6}\s/.test(lines[i])
+      && !lines[i].trim().startsWith('```') && !lines[i].trim().startsWith('>')
+    ) { buf.push(lines[i]); i++; }
+    const pnodes = [];
+    buf.forEach((ln, li) => {
+      if (li > 0) pnodes.push(<br key={`p${b}-br${li}`} />);
+      pnodes.push(...renderInline(ln, sources, onNavigate, `p${b}-${li}`));
+    });
+    blocks.push(<p key={`b${b++}`}>{pnodes}</p>);
   }
-  return paragraphs.map((para, pi) => (
-    <p key={pi}>
-      {para.map((tk, i) => {
-        if (tk.kind === 'cite') {
-          const src = sources?.find((s) => s.num === tk.n);
-          return (
-            <a
-              key={i}
-              className="velu-chatbot__cite"
-              href={sourceHref(src) || '#'}
-              onClick={(e) => onSourceClick(e, src, onNavigate)}
-              title={citeTitle(src)}
-            >
-              {tk.n}
-            </a>
-          );
-        }
-        if (tk.kind === 'code') return <code key={i}>{tk.v}</code>;
-        const lines = tk.v.split('\n');
-        return lines.map((line, li) => (
-          <React.Fragment key={`${i}-${li}`}>
-            {li > 0 && <br />}
-            {line}
-          </React.Fragment>
-        ));
-      })}
-    </p>
-  ));
+  return blocks;
 }
 
 /* ── Header ─────────────────────────────────────────────────────────── */

package/runtime/velu-ui/components/ContextMenu.jsx

@@ -9,6 +9,7 @@ import {
   Download,
   Bot,
   Wind,
+  Rss,
 } from 'lucide-react';
 import Cluster from '../primitives/Cluster.jsx';
 import {
@@ -42,11 +43,15 @@ import {
  *   getMarkdown?: () => string|Promise<string>, // override the .md-twin fetch
  *                                     // (instant preview: no .md twin exists —
  *                                     // the raw source comes from the store)
+ *   basePath?: string,                // subpath prefix (e.g. "/docs") for the
+ *                                     // server-served .md twins + /mcp endpoint
  * }} props
  */
 
-// The Markdown URL for a page path (`/` → `/index.md`).
-const mdUrlForPage = (url) => (url === '/' ? '/index.md' : `${url}.md`);
+// The Markdown URL for a page path (`/` → `/index.md`), under an optional
+// subpath prefix (e.g. "/docs" → "/docs/quickstart.md").
+const mdUrlForPage = (url, basePath = '') =>
+  basePath + (url === '/' ? '/index.md' : `${url}.md`);
 
 // key → { icon, label, desc, external?, apiOnly?, kind, url? }
 const REGISTRY = {
@@ -61,11 +66,11 @@ const REGISTRY = {
   aistudio: { icon: Sparkles, label: 'Open in AI Studio', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://aistudio.google.com/app/prompts/new_chat?prompt=${q}` },
   devin: { icon: Bot, label: 'Open in Devin', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://app.devin.ai/?prompt=${q}` },
   windsurf: { icon: Wind, label: 'Open in Windsurf', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://windsurf.com/?q=${q}` },
-  mcp: { icon: Terminal, label: 'Copy MCP install command', desc: 'Copy npx command to install MCP server', kind: 'mcp' },
+  mcp: { icon: Terminal, label: 'Copy MCP install command', desc: 'Copy command to install the MCP server', kind: 'mcp' },
   'add-mcp': { icon: Terminal, label: 'Add MCP server', desc: 'Copy command to add the MCP server', kind: 'mcp' },
   cursor: { icon: CursorIcon, label: 'Connect to Cursor', desc: 'Install MCP Server on Cursor', kind: 'cursor', external: true },
   vscode: { icon: VscodeIcon, label: 'Connect to VS Code', desc: 'Install MCP Server on VS Code', kind: 'vscode', external: true },
-  'devin-mcp': { icon: Terminal, label: 'Connect to Devin', desc: 'Install MCP Server on Devin', kind: 'cursor', external: true },
+  'devin-mcp': { icon: Terminal, label: 'Connect to Devin', desc: 'Copy command to add the MCP server on Devin', kind: 'devin' },
 };
 
 export default function ContextMenu({
@@ -77,6 +82,8 @@ export default function ContextMenu({
   options = [],
   onAssistant,
   getMarkdown,
+  basePath = '',
+  rssHref,
 }) {
   const [open, setOpen] = React.useState(false);
   const [copied, setCopied] = React.useState(false);
@@ -107,7 +114,7 @@ export default function ContextMenu({
     copiedTimer.current = setTimeout(() => setCopied(false), 1600);
   };
 
-  const mdUrl = mdUrlForPage(pageUrl);
+  const mdUrl = mdUrlForPage(pageUrl, basePath);
 
   // Build the descriptor list from the configured options (skip API-only items
   // off API pages, and any unsupported keys).
@@ -166,6 +173,9 @@ export default function ContextMenu({
     setOpen(false);
     const origin = window.location.origin;
     const absMd = origin + mdUrl;
+    const mcpUrl = `${origin}${basePath}/mcp`;
+    // CLI-safe server name (siteName may contain spaces).
+    const serverName = (siteName || 'docs').trim().replace(/\s+/g, '-').toLowerCase() || 'docs';
     switch (it.kind) {
       case 'copy':
         return copyPage();
@@ -192,12 +202,12 @@ export default function ContextMenu({
         return void window.open(it.url(q), '_blank', 'noopener');
       }
       case 'mcp':
-        // Stubbed: the Velu MCP server isn't hosted yet — this is the intended
-        // command, wired to <origin>/mcp once it exists.
-        return copyText(`npx -y @veluai/mcp@latest ${origin}/mcp`);
+        // Hosted HTTP MCP server lives at <origin>/mcp. Copy a client-neutral
+        // command: `mcp-remote` bridges the HTTP server to stdio, so it works
+        // in any MCP client config (Claude, Cursor, VS Code, Windsurf, …).
+        return copyText(`npx mcp-remote ${mcpUrl}`);
       case 'cursor': {
-        const cfg =
-          typeof btoa === 'function' ? btoa(JSON.stringify({ url: `${origin}/mcp` })) : '';
+        const cfg = typeof btoa === 'function' ? btoa(JSON.stringify({ url: mcpUrl })) : '';
         return void window.open(
           `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(siteName)}&config=${cfg}`,
           '_blank',
@@ -205,13 +215,16 @@ export default function ContextMenu({
         );
       }
       case 'vscode': {
-        const cfg = encodeURIComponent(JSON.stringify({ name: siteName, url: `${origin}/mcp` }));
-        return void window.open(
-          `https://insiders.vscode.dev/redirect/mcp/install?${cfg}`,
-          '_blank',
-          'noopener',
+        // Official VS Code install URI: `vscode:mcp/install?<urlencoded JSON>`,
+        // with the transport `type` inside the payload.
+        const cfg = encodeURIComponent(
+          JSON.stringify({ name: siteName, type: 'http', url: mcpUrl }),
         );
+        return void window.open(`vscode:mcp/install?${cfg}`, '_blank', 'noopener');
       }
+      case 'devin':
+        // Devin has no install deep-link — copy its CLI add command instead.
+        return copyText(`devin mcp add ${serverName} ${mcpUrl}`);
       case 'custom':
         return void window.open(it.href, '_blank', 'noopener');
       default:
@@ -220,7 +233,20 @@ export default function ContextMenu({
   };
 
   // Nothing to show → render nothing (keeps the page top clean).
-  if (!eyebrow && !items.length) return null;
+  if (!eyebrow && !items.length && !rssHref) return null;
+
+  const rssLink = rssHref ? (
+    <a
+      className="velu-context-menu__rss"
+      href={rssHref}
+      target="_blank"
+      rel="noopener"
+      aria-label="Subscribe to the RSS feed"
+      title="RSS feed"
+    >
+      <Rss size="1em" aria-hidden="true" />
+    </a>
+  ) : null;
 
   return (
     <Cluster
@@ -232,6 +258,7 @@ export default function ContextMenu({
     >
       {eyebrow ? <span className="velu-context-bar__eyebrow">{eyebrow}</span> : <span />}
 
+      <div className="velu-context-bar__actions">
       {items.length > 0 && (
         <div ref={rootRef} className="velu-context-menu" data-open={open ? 'true' : 'false'}>
           <div className="velu-context-menu__split">
@@ -293,6 +320,8 @@ export default function ContextMenu({
           </ul>
         </div>
       )}
+      {rssLink}
+      </div>
     </Cluster>
   );
 }

package/runtime/velu-ui/components/Update.jsx

@@ -0,0 +1,92 @@
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * Update — a single changelog entry.
+ *
+ * A changelog page is just a normal docs page that contains one or more
+ * <Update> blocks; there is no special page type. Each entry renders as a
+ * two-column row: a sticky left rail with the date/label pill (+ optional
+ * description and tags) and a right column with the entry body (the MDX
+ * children — usually `##` sub-headings and prose).
+ *
+ * The section gets a stable `id` derived from the label so it is linkable
+ * and shows up in the table of contents. The id MUST match the slug the
+ * `extract-toc` remark plugin computes for the same label (see
+ * velu-cli/src/mdx-plugins/extract-toc.js → `slugifyUpdate`), so click→scroll
+ * and scroll-spy line up.
+ *
+ * `data-update-tags` (pipe-joined) is emitted so a future tag-filter can show
+ * / hide entries purely from the DOM.
+ *
+ * SSR-safe & presentational.
+ *
+ * @param {{ label?: string, date?: string, description?: string,
+ *   tags?: string | string[], rss?: any, children?: React.ReactNode,
+ *   className?: string }} props
+ */
+export function slugifyUpdate(value) {
+  const base = String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return `update-${base || 'item'}`;
+}
+
+function toTagList(value) {
+  if (Array.isArray(value)) return value.map(String).filter(Boolean);
+  if (value == null || value === false || value === '') return [];
+  return [String(value)];
+}
+
+export default function Update({
+  label,
+  date,
+  description,
+  tags,
+  rss, // accepted for authoring parity; RSS metadata is handled at build time
+  children,
+  className = '',
+  ...rest
+}) {
+  void rss;
+  const updateLabel = String(label ?? date ?? 'Update');
+  const anchorId = slugifyUpdate(updateLabel);
+  const tagList = toTagList(tags);
+
+  return (
+    <section
+      id={anchorId}
+      data-update-label={updateLabel}
+      data-update-tags={tagList.join('|')}
+      className={`velu-update ${className}`.trim()}
+      {...rest}
+    >
+      <div className="velu-update__meta">
+        <a
+          className="velu-update__anchor"
+          href={`#${anchorId}`}
+          aria-label={`Link to ${updateLabel}`}
+        >
+          {resolveIcon('link', { size: '1em' })}
+        </a>
+        <a className="velu-update__label" href={`#${anchorId}`}>
+          {updateLabel}
+        </a>
+        {description ? (
+          <div className="velu-update__description">{String(description)}</div>
+        ) : null}
+        {tagList.length ? (
+          <div className="velu-update__tags">
+            {tagList.map((tag, i) => (
+              <span key={`${tag}-${i}`} className="velu-update__tag">
+                {tag}
+              </span>
+            ))}
+          </div>
+        ) : null}
+      </div>
+      {children ? <div className="velu-update__content">{children}</div> : null}
+    </section>
+  );
+}

package/runtime/velu-ui/components/changelog-filters.css

@@ -0,0 +1,43 @@
+/* Changelog tag filters — shown in the right rail in place of the TOC on
+   changelog pages. Tokenized; light/dark via [data-theme]. */
+
+.velu-changelog-filters {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-1);
+}
+
+.velu-changelog-filters__heading {
+  font-size: var(--f-h6);
+  font-weight: var(--weight-semibold);
+  color: var(--accent-color);
+}
+
+.velu-changelog-filters__list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--s-2);
+}
+
+.velu-changelog-filter {
+  cursor: pointer;
+  border-radius: 999px;
+  padding: 0.22rem 0.65rem;
+  font-size: var(--f-h6);
+  font-weight: var(--weight-medium);
+  color: var(--text-color);
+  background: color-mix(in srgb, var(--muted-color) 14%, transparent);
+  border: var(--border-width) solid transparent;
+  transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease;
+}
+
+.velu-changelog-filter:hover {
+  border-color: color-mix(in srgb, var(--accent-color) 40%, var(--border-color));
+  background: color-mix(in srgb, var(--accent-color) 8%, transparent);
+}
+
+.velu-changelog-filter--active {
+  color: var(--accent-color);
+  border-color: color-mix(in srgb, var(--accent-color) 55%, transparent);
+  background: color-mix(in srgb, var(--accent-color) 12%, transparent);
+}