@veluai/velu 0.2.19 → 0.2.23

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;
@@ -510,7 +567,10 @@
   opacity: 0;
   transition: opacity 0.12s ease;
 }
-.velu-chatbot__msg--ai:hover .velu-chatbot__msg-actions {
+.velu-chatbot__msg--ai:hover .velu-chatbot__msg-actions,
+/* Keep the row visible once a vote is cast, so the selection stays
+   confirmed after the pointer leaves the message. */
+.velu-chatbot__msg-actions:has(.is-active) {
   opacity: 1;
 }
 .velu-chatbot__msg-action {
@@ -530,6 +590,11 @@
   background: var(--surface-color);
   color: var(--text-color);
 }
+/* Chosen thumb (up/down) — accent tint so the click is clearly registered. */
+.velu-chatbot__msg-action.is-active {
+  background: color-mix(in srgb, var(--accent-color) 12%, transparent);
+  color: var(--accent-color);
+}
 
 /* ── Composer ───────────────────────────────────────────────────────── */
 .velu-chatbot__composer {

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';

package/runtime/velu-ui/lib/docs-assistant.js

@@ -91,6 +91,11 @@ export function createDocsAssistant({ apiBase, host } = {}) {
   if (!base) return null;
   const root = `${base}/api/v1/public/ai-assistant`;
   let bootstrapped = false;
+  // Whether the docs owner's plan + credit balance allow Ask-AI right now.
+  // Set from /bootstrap; the host UI hides the widget when false. Fail-open
+  // (stays true) if bootstrap can't be reached so a transient error doesn't
+  // wrongly hide a working assistant.
+  let askEnabled = true;
   // Highest event seq seen per conversation. The events endpoint replays history
   // after `after_seq`; without this a reused (multi-turn) conversation replays
   // from 0 and the first (old) assistant.completed is returned for every
@@ -104,15 +109,33 @@ export function createDocsAssistant({ apiBase, host } = {}) {
 
   async function bootstrap() {
     if (bootstrapped) return;
-    // Sets the httponly visitor cookie used by every subsequent call.
-    await fetch(`${root}/bootstrap`, {
+    // Sets the httponly visitor cookie used by every subsequent call, and tells
+    // us whether Ask-AI is currently enabled for this site (plan + credits).
+    const res = await fetch(`${root}/bootstrap`, {
       method: 'GET',
       credentials: 'include',
       headers: headers(),
     });
+    try {
+      const data = await res.json();
+      if (typeof data?.ask_ai_enabled === 'boolean') askEnabled = data.ask_ai_enabled;
+    } catch {
+      /* keep fail-open default */
+    }
     bootstrapped = true;
   }
 
+  // Resolve whether the widget should be shown (runs bootstrap once). Returns
+  // true on any error so a transient failure never hides a working assistant.
+  async function isEnabled() {
+    try {
+      await bootstrap();
+    } catch {
+      return true;
+    }
+    return askEnabled;
+  }
+
   // Async generator: yields { conversationId } early, then one
   // { delta, citations, messageId, conversationId } when the answer is ready.
   async function* ask(prompt, { conversationId, signal } = {}) {
@@ -244,7 +267,7 @@ export function createDocsAssistant({ apiBase, host } = {}) {
     return { conversationId, messages };
   }
 
-  return { ask, sendFeedback, listConversations, loadConversation };
+  return { ask, sendFeedback, listConversations, loadConversation, isEnabled };
 }
 
 export default createDocsAssistant;

package/runtime/velu-ui/lib/pagefind.js

@@ -16,7 +16,10 @@ async function loadRuntime() {
   if (_loading) return _loading;
   _loading = (async () => {
     const importer = new Function('p', 'return import(p)');
-    const mod = await importer('/pagefind/pagefind.js');
+    // BASE_URL is '/' normally, '/docs/' under subpath hosting — the index is
+    // emitted relative to the served root, so prefix the runtime URL to match.
+    const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '');
+    const mod = await importer(`${base}/pagefind/pagefind.js`);
     if (typeof mod.init === 'function') await mod.init();
     _pf = mod;
     return mod;

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

@@ -7,6 +7,7 @@ import Field from './components/Field.jsx';
 import Prompt from './components/Prompt.jsx';
 import Steps, { Step } from './components/Steps.jsx';
 import Tree, { Folder, File } from './components/Tree.jsx';
+import Update from './components/Update.jsx';
 import Image from './components/Image.jsx';
 import CodeBlock, { CodeGroup } from './components/CodeBlock.jsx';
 import MethodBadge from './components/MethodBadge.jsx';
@@ -91,6 +92,7 @@ export const defaultMdxComponents = {
   Tree,
   Folder,
   File,
+  Update,
   Image: checked('Image', Image),
   CodeBlock,
   CodeGroup,

package/runtime/velu-ui/styles.css

@@ -30,6 +30,8 @@
 @import './components/prompt.css';
 @import './components/steps.css';
 @import './components/tree.css';
+@import './components/update.css';
+@import './components/changelog-filters.css';
 @import './components/api.css';
 @import './components/api-page.css';
 @import './components/not-found.css';

package/schema/velu.schema.json

@@ -171,10 +171,6 @@
       "$ref": "#/$defs/navContainer",
       "description": "Site navigation. Mintlify-compatible: products > versions > languages > tabs > groups > pages. Switchable axes (product/version/language) become URL path prefixes; the default value of each is unprefixed. Dropdowns are intentionally unsupported."
     },
-    "url": {
-      "type": "string",
-      "description": "Production site origin (e.g. \"https://docs.example.com\"), no trailing slash. Used by the static build for canonical URLs, og:url, and sitemap.xml, and by llms.txt for absolute links."
-    },
     "thumbnails": {
       "type": "object",
       "additionalProperties": false,

package/src/lib/known-components.js

@@ -20,6 +20,7 @@ export const KNOWN_COMPONENTS = [
   'Tree',
   'Folder',
   'File',
+  'Update',
   'Image',
   'CodeBlock',
   'CodeGroup',

package/src/runtime/App.jsx

@@ -14,6 +14,7 @@ import {
   NavSelect,
   Toc,
   TocBar,
+  ChangelogFilters,
   ContextMenu,
   Callout,
   Accordion,
@@ -64,6 +65,12 @@ import ErrorBoundary from './ErrorBoundary.jsx';
 // preview. Identical on SSR + client in each mode, so no hydration mismatch.
 const IS_DEV_PREVIEW = import.meta.env.DEV;
 
+// Subpath-hosting prefix (e.g. "/docs"), from Vite's BASE_URL. Empty at the
+// origin root. The router handles internal <Link>s on its own, but server-served
+// resources the router doesn't own — the .md twins, the /mcp endpoint — are
+// root-relative and need this prefix to resolve under a subpath.
+const BASE_PATH = (import.meta.env.BASE_URL || '/').replace(/\/$/, '');
+
 // Flatten a sidebar section's items (which may nest into sub-groups) into the
 // flat endpoint list <ApiSidebar> wants. API tabs are flat in practice; this
 // only guards the rare case of a normal nested group living beside generated
@@ -780,6 +787,19 @@ function DocsPage() {
     return createDocsAssistant({ apiBase, host: site.assistant?.host });
   }, []);
 
+  // Hide the Ask-AI widget when the docs owner's plan/credits disable it (the
+  // backend bootstrap returns ask_ai_enabled:false). Only applies to a real
+  // configured assistant — the dev-preview/demo widget stays visible.
+  const [askAiHidden, setAskAiHidden] = React.useState(false);
+  React.useEffect(() => {
+    if (!assistant) return undefined;
+    let alive = true;
+    assistant.isEnabled().then((ok) => {
+      if (alive && !ok) setAskAiHidden(true);
+    }).catch(() => {});
+    return () => { alive = false; };
+  }, [assistant]);
+
   // Page-feedback backend: reuses the same injected apiBase as the assistant
   // (baked into every published velu.json), so the "Was this page helpful?"
   // widget can POST to /api/v1/public/feedback. Null in the dev preview, where
@@ -794,6 +814,11 @@ function DocsPage() {
   const frontmatter = entry?.frontmatter ?? {};
   const PageComponent = entry?.Component ?? null;
   const pageToc = entry?.toc ?? [];
+  // Changelog pages (any page with <Update> entries) carry a `changelog`
+  // export. We swap the right-rail TOC for tag filters and expose an RSS link.
+  const changelog = entry?.changelog ?? null;
+  const isChangelog = !!changelog;
+  const changelogTags = changelog?.tags ?? [];
   // No renderable page for this route → show the 404 page (a clean centered
   // takeover: header + footer stay, the docs sidebar/TOC are hidden).
   const isNotFound = !PageComponent;
@@ -911,6 +936,14 @@ function DocsPage() {
       document.removeEventListener('keydown', onKey);
     };
   }, [navOpen]);
+
+  // Close the mobile drawer (and its nav dropdown) whenever the route changes,
+  // so picking a page from the sidebar collapses the drawer instead of leaving
+  // it open over the article.
+  React.useEffect(() => {
+    setDrawerOpen(false);
+    setNavOpen(false);
+  }, [pathname]);
   // Mobile drawer's section picker = the resolved tabs (top-level
   // navigation), so it mirrors the desktop tabs row instead of a
   // hardcoded list. Its button shows the active tab's label.
@@ -1197,8 +1230,9 @@ function DocsPage() {
               onSelect={(item) => item.href && navigate(item.href)}
             />
             {/* Ask AI talks to the deployed site's AI backend — hidden in
-                the local dev preview where there's nothing to talk to. */}
-            {!IS_DEV_PREVIEW && (
+                the local dev preview where there's nothing to talk to, and
+                when the owner's plan/credits disable the assistant. */}
+            {!IS_DEV_PREVIEW && !askAiHidden && (
               <button
                 type="button"
                 className="velu-header__action velu-header__action--outlined"
@@ -1453,6 +1487,8 @@ function DocsPage() {
               samples={entry.samples}
               responses={entry.operation.responses}
             />
+          ) : isChangelog && changelogTags.length ? (
+            <ChangelogFilters tags={changelogTags} />
           ) : (
             <Toc items={toc} activeId={activeId} onSelect={scrollTo} />
           )}
@@ -1474,7 +1510,7 @@ function DocsPage() {
                   new KeyboardEvent('keydown', { key: 'k', ctrlKey: true, metaKey: true }),
                 )
               }
-              onAskAI={IS_DEV_PREVIEW ? undefined : () => askAI('')}
+              onAskAI={IS_DEV_PREVIEW || askAiHidden ? undefined : () => askAI('')}
             />
           </main>
         ) : (
@@ -1485,6 +1521,8 @@ function DocsPage() {
             right-rail <Toc> so both views are driven by the same
             data; whichever one is visible at a given width responds
             to the same scroll-spy state. */}
+        {/* Changelog tag filters are a wide-layout (right-rail) affordance only;
+            on tab/mobile we keep the normal TOC bar (no filters). */}
         <TocBar items={toc} activeId={activeId} onSelect={scrollTo} />
       <main
         className="velu-docs-layout__main"
@@ -1533,12 +1571,14 @@ function DocsPage() {
                 : undefined
             }
             pageUrl={pathname}
+            basePath={BASE_PATH}
             title={frontmatter.title}
             isApi={entry?.api === true}
             siteName={site.name}
             options={site.contextual?.options ?? []}
-            onAssistant={IS_DEV_PREVIEW ? undefined : () => askAI('')}
+            onAssistant={IS_DEV_PREVIEW || askAiHidden ? undefined : () => askAI('')}
             getMarkdown={entry?.getSource}
+            rssHref={isChangelog ? `${BASE_PATH}/rss.xml` : undefined}
           />
 
           {/* Page hero from MDX frontmatter. `.velu-hero` rules
@@ -1614,7 +1654,7 @@ function DocsPage() {
               approaches (see IntersectionObserver above). */}
           {/* Ask-a-question bar — opens the AI chatbot, which runs on the
               deployed site. Hidden in the local dev preview. */}
-          {!IS_DEV_PREVIEW && !chatOpen && (
+          {!IS_DEV_PREVIEW && !chatOpen && !askAiHidden && (
             <AskBar
               onSubmit={askAI}
               style={{
@@ -1672,7 +1712,9 @@ function DocsPage() {
         </div>
       )}
 
-      {/* Ask-AI chatbot — slides in from the inline-end edge. */}
+      {/* Ask-AI chatbot — slides in from the inline-end edge. Hidden when the
+          docs owner's plan/credits disable Ask-AI. */}
+      {!askAiHidden && (
       <Chatbot
         open={chatOpen}
         seedQuestion={chatQuestion}
@@ -1698,6 +1740,7 @@ function DocsPage() {
           setTimeout(go, 50);
         }}
       />
+      )}
     </div>
   );
 }

package/src/runtime/client-entry.jsx

@@ -4,9 +4,14 @@ import { BrowserRouter } from 'react-router-dom';
 import 'velu-ui/styles.css';
 import App from './App.jsx';
 
+// Subpath hosting: Vite sets BASE_URL from the build's `base` (e.g. "/docs/").
+// React Router wants a basename WITHOUT the trailing slash ("/docs"); the root
+// case ("/") becomes undefined so the router behaves as if mounted at origin.
+const basename = (import.meta.env.BASE_URL || '/').replace(/\/$/, '') || undefined;
+
 hydrateRoot(
   document.getElementById('root'),
-  <BrowserRouter>
+  <BrowserRouter basename={basename}>
     <App />
   </BrowserRouter>
 );

package/src/runtime/server-entry.jsx

@@ -7,9 +7,17 @@ import { StaticRouter } from 'react-router-dom/server';
 import 'velu-ui/styles.css';
 import App from './App.jsx';
 
+// Subpath hosting: mirror the client's basename (from Vite's BASE_URL). The
+// prerender is driven by root-relative route paths ("/foo"), so the location
+// handed to StaticRouter must carry the basename prefix ("/docs/foo") for it to
+// match — and so the rendered <Link> hrefs come out prefixed too, matching what
+// the hydrated BrowserRouter produces.
+const basename = (import.meta.env.BASE_URL || '/').replace(/\/$/, '');
+
 export async function render(url) {
+  const location = basename ? `${basename}${url}` : url;
   return renderToString(
-    <StaticRouter location={url}>
+    <StaticRouter basename={basename || undefined} location={location}>
       <App />
     </StaticRouter>
   );

package/templates/starter/index.mdx

@@ -16,16 +16,16 @@ save.
 ## Get going
 
 <CardGroup>
-  <Card title="Quickstart" icon="rocket" href="/quickstart">
+  <Card title="Quickstart" icon="rocket" cta={{ label: "Get started", href: "/quickstart" }}>
     Run the dev server and make your first edit.
   </Card>
-  <Card title="Customize" icon="sliders-horizontal" href="/essentials/settings">
+  <Card title="Customize" icon="sliders-horizontal" cta={{ label: "Customize", href: "/essentials/settings" }}>
     Set your colors, font, and favicon.
   </Card>
-  <Card title="Write content" icon="pen-line" href="/essentials/markdown">
+  <Card title="Write content" icon="pen-line" cta={{ label: "Write content", href: "/essentials/markdown" }}>
     Markdown plus a library of components.
   </Card>
-  <Card title="API reference" icon="terminal" href="/api-reference/introduction">
+  <Card title="API reference" icon="terminal" cta={{ label: "View reference", href: "/api-reference/introduction" }}>
     Document your endpoints.
   </Card>
 </CardGroup>

package/templates/starter/velu.json

@@ -1,7 +1,6 @@
 {
   "$schema": "https://veludocs.com/velu.schema.json",
   "name": "Starter",
-  "url": "https://veludocs.com",
   "colors": {
     "primary": "#dc143c"
   },