@veluai/velu 0.2.20 → 0.2.23

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 = {
@@ -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,7 +173,7 @@ export default function ContextMenu({
     setOpen(false);
     const origin = window.location.origin;
     const absMd = origin + mdUrl;
-    const mcpUrl = `${origin}/mcp`;
+    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) {
@@ -226,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
@@ -238,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">
@@ -299,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);
+}

package/runtime/velu-ui/components/chatbot.css

@@ -385,6 +385,63 @@
   border-radius: var(--radius-sm);
 }
 
+/* Rendered markdown in answers */
+.velu-chatbot__answer strong {
+  font-weight: 600;
+}
+.velu-chatbot__answer em {
+  font-style: italic;
+}
+.velu-chatbot__answer a:not(.velu-chatbot__cite) {
+  color: var(--accent-color);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+.velu-chatbot__answer h3,
+.velu-chatbot__answer h4,
+.velu-chatbot__answer h5,
+.velu-chatbot__answer h6 {
+  margin: var(--s-2) 0 var(--s-4);
+  font-weight: 600;
+  line-height: var(--lh-heading, 1.3);
+}
+.velu-chatbot__answer h3 { font-size: var(--f-h5); }
+.velu-chatbot__answer h4 { font-size: var(--f-h6); }
+.velu-chatbot__answer h5,
+.velu-chatbot__answer h6 { font-size: var(--f-h7); }
+.velu-chatbot__answer ul,
+.velu-chatbot__answer ol {
+  margin: 0 0 var(--s-3);
+  padding-inline-start: var(--s-1);
+}
+.velu-chatbot__answer li {
+  margin: 0 0 var(--s-5);
+}
+.velu-chatbot__answer li::marker {
+  color: var(--muted-color);
+}
+.velu-chatbot__pre {
+  margin: 0 0 var(--s-3);
+  padding: var(--s-3);
+  overflow-x: auto;
+  background: var(--surface-color);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+}
+.velu-chatbot__pre code {
+  padding: 0;
+  background: none;
+  border: none;
+  font-size: var(--f-h7);
+  white-space: pre;
+}
+.velu-chatbot__answer blockquote {
+  margin: 0 0 var(--s-3);
+  padding-inline-start: var(--s-3);
+  border-inline-start: 2px solid var(--border-color);
+  color: var(--muted-color);
+}
+
 /* Inline citation chip */
 .velu-chatbot__cite {
   display: inline-flex;

package/runtime/velu-ui/components/context-menu.css

@@ -23,11 +23,37 @@
   color: var(--accent-color);
 }
 
+.velu-context-bar__actions {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  flex: none;
+}
+
 .velu-context-menu {
   position: relative;
   flex: none;
 }
 
+/* RSS feed link — a round icon button next to "Copy Page" (changelog pages). */
+.velu-context-menu__rss {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 2.1rem;
+  block-size: 2.1rem;
+  border: var(--border-width) solid var(--border-color);
+  border-radius: 999px;
+  color: var(--muted-color);
+  background: var(--page-bg);
+  transition: color 0.12s ease, border-color 0.12s ease, background 0.12s ease;
+}
+.velu-context-menu__rss:hover {
+  color: var(--accent-color);
+  border-color: var(--accent-color);
+  background: color-mix(in srgb, var(--accent-color) 8%, transparent);
+}
+
 /* The split button: "Copy Page" + a divider + a chevron toggle, joined as one
    segmented control. */
 .velu-context-menu__split {

package/runtime/velu-ui/components/page-feedback.css

@@ -222,6 +222,26 @@
 .velu-feedback__heart--3 {
   color: color-mix(in srgb, var(--accent-color) 82%, #fff);
 }
+/* Register the per-heart custom props so they're typed + animatable inside the
+   keyframes. WebKit (newer iOS Safari) won't interpolate UNregistered custom
+   properties used in @keyframes transforms — without this the hearts never move
+   and the burst is invisible. Browsers without @property ignore these rules and
+   fall back to the inline values (the prior behaviour). */
+@property --hb-tx {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+@property --hb-ty {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+@property --hb-rot {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
 @keyframes velu-feedback-hearts {
   0% {
     transform: translate(-50%, 0) rotate(0deg) scale(0.6);

package/runtime/velu-ui/components/update.css

@@ -0,0 +1,110 @@
+/* Update — changelog entries. Two-column rows: a sticky left rail with the
+   date/label pill, and the entry body on the right. All values are tokens;
+   light/dark via [data-theme]. */
+
+.velu-update {
+  display: grid;
+  grid-template-columns: minmax(8rem, 11rem) minmax(0, 1fr);
+  column-gap: var(--s1);
+  row-gap: var(--s-1);
+  align-items: start;
+  margin-block: var(--s1) var(--s3);
+  /* Clear the fixed header when an entry is jumped to via its anchor. */
+  scroll-margin-top: calc(var(--velu-header-height) + var(--s0));
+}
+
+.velu-update__meta {
+  position: sticky;
+  /* Stick just below the fixed header instead of sliding behind it. */
+  top: calc(var(--velu-header-height) + var(--s0));
+  align-self: start;
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-2);
+  padding-left: var(--s0);
+}
+
+.velu-update__anchor {
+  position: absolute;
+  left: 0;
+  top: 0.3rem;
+  display: inline-flex;
+  /* Hidden until the entry is hovered/focused (like heading anchors). */
+  color: var(--muted-color);
+  opacity: 0;
+  transition: opacity 0.15s ease, color 0.15s ease;
+}
+
+.velu-update:hover .velu-update__anchor,
+.velu-update:focus-within .velu-update__anchor {
+  opacity: 1;
+  color: var(--accent-color);
+}
+
+.velu-update__label {
+  width: fit-content;
+  border-radius: 999px;
+  padding: 0.2rem 0.6rem;
+  font-size: var(--f-h6);
+  font-weight: var(--weight-semibold);
+  line-height: 1.2;
+  color: var(--page-bg);
+  background: var(--accent-color);
+  text-decoration: none;
+}
+
+.velu-update__label:hover {
+  background: color-mix(in srgb, var(--accent-color) 85%, black);
+}
+
+.velu-update__description {
+  color: var(--muted-color);
+  font-size: var(--f-h6);
+  line-height: var(--lh-h6);
+}
+
+.velu-update__tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--s-2);
+}
+
+.velu-update__tag {
+  font-size: var(--f-small, 0.72rem);
+  color: var(--muted-color);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: 999px;
+  padding: 0.1rem 0.45rem;
+}
+
+.velu-update__content {
+  min-width: 0;
+}
+
+.velu-update__content > :first-child {
+  margin-top: 0;
+}
+
+.velu-update__content > :last-child {
+  margin-bottom: 0;
+}
+
+/* Hidden by a tag filter (DOM-driven). */
+.velu-update[hidden] {
+  display: none !important;
+}
+
+@media (max-width: 768px) {
+  .velu-update {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .velu-update__meta {
+    position: static;
+    padding-left: var(--s2);
+  }
+
+  .velu-update__anchor {
+    left: 0;
+  }
+}

package/runtime/velu-ui/index.js

@@ -21,6 +21,8 @@ export { default as Field } from './components/Field.jsx';
 export { default as Prompt } from './components/Prompt.jsx';
 export { default as Steps, Step } from './components/Steps.jsx';
 export { default as Tree, Folder, File } from './components/Tree.jsx';
+export { default as Update } from './components/Update.jsx';
+export { default as ChangelogFilters } from './components/ChangelogFilters.jsx';
 export { default as MethodBadge } from './components/MethodBadge.jsx';
 export { default as ApiPath } from './components/ApiPath.jsx';
 export { default as TryItBar } from './components/TryItBar.jsx';