@veluai/velu 0.2.20 → 0.2.24

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"
   },