@veluai/velu 0.1.16 → 0.2.1

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

@@ -0,0 +1,113 @@
+// Pagefind client — queries the static search index that `velu build` writes to
+// /pagefind/. The index is a chunked, lazy-loaded WASM bundle: the browser only
+// downloads the fragments it needs per query, so search scales to huge sites
+// without shipping one giant index. Generated at build time; absent in dev
+// (the dev preview shows search as "unavailable").
+//
+// The runtime is loaded via a NON-analyzable dynamic import (a Function-wrapped
+// import) so neither Vite nor the bundler tries to resolve /pagefind/pagefind.js
+// at build time — it only exists in the deployed output.
+
+let _pf = null;
+let _loading = null;
+
+async function loadRuntime() {
+  if (_pf) return _pf;
+  if (_loading) return _loading;
+  _loading = (async () => {
+    const importer = new Function('p', 'return import(p)');
+    const mod = await importer('/pagefind/pagefind.js');
+    if (typeof mod.init === 'function') await mod.init();
+    _pf = mod;
+    return mod;
+  })();
+  try {
+    return await _loading;
+  } catch (err) {
+    _loading = null;
+    throw err;
+  }
+}
+
+const stripHtml = (s) => String(s || '').replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+
+// Pagefind returns directory URLs (/quickstart/, /a/b/, /); normalize to the
+// router's path form (/quickstart, /a/b, /). Preserve any #anchor.
+function normalizeUrl(url) {
+  if (!url) return '/';
+  let [path, hash] = String(url).split('#');
+  path = path.replace(/index\.html?$/i, '').replace(/\.html?$/i, '');
+  if (path.length > 1) path = path.replace(/\/+$/, '');
+  if (!path) path = '/';
+  return hash ? `${path}#${hash}` : path;
+}
+
+// Breadcrumb from the URL path (everything but the leaf), title-cased.
+function crumbsFromUrl(url) {
+  const segs = String(url).split('#')[0].split('/').filter(Boolean);
+  segs.pop();
+  return segs.map((s) => s.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()));
+}
+
+/**
+ * Run a query against the static Pagefind index.
+ * @returns {Promise<Array<SearchResult>|null>} palette-shaped results, or null
+ *   when the index can't be loaded (→ caller can show "unavailable").
+ */
+export default async function pagefindSearch(query) {
+  const q = String(query || '').trim();
+  if (!q) return [];
+
+  let pf;
+  try {
+    pf = await loadRuntime();
+  } catch {
+    return null; // index not present (e.g. not built) → unavailable
+  }
+
+  let response;
+  try {
+    response = await pf.search(q);
+  } catch {
+    return [];
+  }
+
+  const hits = await Promise.all(response.results.slice(0, 8).map((r) => r.data()));
+  const out = [];
+  const seen = new Set(); // dedupe by href
+  for (const hit of hits) {
+    const href = normalizeUrl(hit.url);
+    const title = hit.meta?.title || crumbsFromUrl(hit.url).pop() || href;
+    if (!seen.has(href)) {
+      seen.add(href);
+      out.push({
+        id: href,
+        group: 'Pages',
+        breadcrumb: crumbsFromUrl(hit.url),
+        title,
+        kind: 'page',
+        desc: stripHtml(hit.excerpt),
+        href,
+      });
+    }
+    // Heading-level matches → deep-linkable anchor rows. Skip the page's own
+    // top section (pagefind repeats it as a sub-result with the page title).
+    for (const sub of hit.sub_results || []) {
+      const subHref = normalizeUrl(sub.url);
+      if (seen.has(subHref) || !subHref.includes('#') || sub.title === title) continue;
+      seen.add(subHref);
+      out.push({
+        id: subHref,
+        group: 'Pages',
+        breadcrumb: [title],
+        title: sub.title || title,
+        kind: 'anchor',
+        desc: stripHtml(sub.excerpt),
+        href: subHref,
+      });
+      if (out.length >= 12) break;
+    }
+    if (out.length >= 12) break;
+  }
+  return out;
+}

package/runtime/velu-ui/styles.css

@@ -21,6 +21,7 @@
 @import './primitives/switcher.css';
 @import './components/sidebar.css';
 @import './components/nav-select.css';
+@import './components/context-menu.css';
 @import './components/accordion.css';
 @import './components/card.css';
 @import './components/image.css';
@@ -31,6 +32,7 @@
 @import './components/tree.css';
 @import './components/api.css';
 @import './components/api-page.css';
+@import './components/not-found.css';
 @import './components/ask-bar.css';
 @import './components/chatbot.css';
 @import './components/page-feedback.css';

package/schema/velu.schema.json

@@ -40,43 +40,7 @@
       "type": "string",
       "description": "Path to the favicon, relative to the project root."
     },
-    "api": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "API reference behaviour for OpenAPI-generated pages.",
-      "properties": {
-        "server": {
-          "type": "string",
-          "description": "Base URL override for the playground + code samples (otherwise the spec's first server is used)."
-        },
-        "playground": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "display": {
-              "type": "string",
-              "enum": ["interactive", "simple", "none"],
-              "description": "Playground mode. \"none\" disables the proxy / live send."
-            },
-            "proxy": {
-              "type": "boolean",
-              "description": "Send Try-It requests through the dev proxy to avoid CORS (default true)."
-            }
-          }
-        },
-        "examples": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "languages": {
-              "type": "array",
-              "items": { "type": "string", "enum": ["curl", "javascript", "python", "ruby"] },
-              "description": "Which request-snippet languages to generate."
-            }
-          }
-        }
-      }
-    },
+    "api": { "$ref": "#/$defs/api" },
     "logo": {
       "description": "Site logo shown in the header, replacing the name wordmark. A single path used in both themes, or per-theme light/dark images with an optional click-through href. Paths are relative to the project root.",
       "oneOf": [
@@ -206,6 +170,78 @@
     "navigation": {
       "$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,
+      "description": "Auto-generated OG (social share) image options. Build-only.",
+      "properties": {
+        "background": {
+          "type": "string",
+          "description": "Project-relative path to a background image for the OG cards (e.g. \"/images/og-background.png\"). Defaults to a brand-color glow."
+        }
+      }
+    },
+    "seo": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Search-engine optimization. Build-only: meta tags and sitemap behaviour applied when the site is built (not in the dev preview).",
+      "properties": {
+        "metatags": {
+          "type": "object",
+          "description": "Extra meta tags injected on every page, as a flat key→value map (e.g. \"google-site-verification\", \"og:image\").",
+          "additionalProperties": { "type": "string" }
+        },
+        "indexing": {
+          "type": "string",
+          "enum": ["navigable", "all"],
+          "description": "\"navigable\" (default) indexes only pages in navigation; \"all\" also includes hidden pages."
+        }
+      }
+    },
+    "contextual": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-page context menu — the \"Copy Page\" split-button + dropdown of agent/IDE actions shown at the top of each page. Mintlify-compatible. Unset → copy, view, chatgpt, claude.",
+      "required": ["options"],
+      "properties": {
+        "options": {
+          "type": "array",
+          "description": "Menu items, in order. Known string options, or custom { title, description, href } entries.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "copy", "assistant", "view", "download-pdf", "download-spec",
+                  "chatgpt", "claude", "perplexity", "grok", "aistudio", "devin", "windsurf",
+                  "mcp", "add-mcp", "cursor", "vscode", "devin-mcp"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["title", "href"],
+                "properties": {
+                  "title": { "type": "string", "description": "Menu item label." },
+                  "description": { "type": "string", "description": "Secondary line under the label." },
+                  "href": { "type": "string", "description": "URL to open." },
+                  "icon": { "type": "string", "description": "Lucide icon id." }
+                }
+              }
+            ]
+          }
+        },
+        "display": {
+          "type": "string",
+          "enum": ["header", "toc"],
+          "description": "Where the menu renders. Default \"header\"."
+        }
+      }
     }
   },
   "$defs": {
@@ -243,6 +279,7 @@
         "expanded": { "type": "boolean", "description": "Start expanded." },
         "root": { "type": "string", "description": "Landing page path for the group." },
         "openapi": { "$ref": "#/$defs/openapiRef" },
+        "api": { "$ref": "#/$defs/api" },
         "pages": { "$ref": "#/$defs/pages" }
       }
     },
@@ -255,11 +292,49 @@
         "icon": { "type": "string" },
         "href": { "type": "string", "description": "External/override link instead of in-site pages." },
         "openapi": { "$ref": "#/$defs/openapiRef" },
+        "api": { "$ref": "#/$defs/api" },
         "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
         "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
         "pages": { "$ref": "#/$defs/pages" }
       }
     },
+    "api": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "API reference behaviour for OpenAPI-generated pages. Set at the root, or on a tab/group with `openapi` to override it for just that section.",
+      "properties": {
+        "server": {
+          "type": "string",
+          "description": "Base URL override for the playground + code samples (otherwise the spec's first server is used)."
+        },
+        "playground": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "display": {
+              "type": "string",
+              "enum": ["interactive", "simple", "none"],
+              "description": "Playground mode. \"none\" disables the proxy / live send."
+            },
+            "proxy": {
+              "type": "boolean",
+              "description": "Send Try-It requests through the dev proxy to avoid CORS (default true)."
+            }
+          }
+        },
+        "examples": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "languages": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["curl", "javascript", "python", "ruby"] },
+              "description": "Which request-snippet languages to generate."
+            }
+          }
+        }
+      }
+    },
     "openapiRef": {
       "description": "Path or URL to an OpenAPI spec (JSON/YAML), or an array of them. Auto-generates a page per operation, grouped by tag.",
       "oneOf": [

package/src/runtime/App.jsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Routes, Route, useLocation, Link } from 'react-router-dom';
+import { Routes, Route, useLocation, useNavigate, Link } from 'react-router-dom';
 import { MDXProvider } from '@mdx-js/react';
 // The project's pages + navigation, generated from velu.json by
 // vite-plugin-velu-site (see src/vite-plugin-velu-site.js). `pages` is
@@ -14,6 +14,7 @@ import {
   NavSelect,
   Toc,
   TocBar,
+  ContextMenu,
   Callout,
   Accordion,
   AccordionGroup,
@@ -38,6 +39,7 @@ import {
   defaultMdxComponents,
   resolveIcon,
   Search,
+  pagefindSearch,
   Logo,
   SocialLinks,
   Tree,
@@ -48,6 +50,7 @@ import {
   ApiField,
   ApiSidebar,
   ApiSamples,
+  NotFound,
   VeluMark,
 } from 'velu-ui';
 import { X, ChevronDown, ChevronUp } from 'lucide-react';
@@ -717,6 +720,7 @@ function DocsPage() {
   // SSR and client compute these from the same pathname + the same
   // shared `resolve()`, so the render is identical (hydration-safe).
   const location = useLocation();
+  const navigate = useNavigate();
   const pathname = normalizeUrl(location.pathname);
   const entry = pages[pathname];
   const nav = React.useMemo(
@@ -724,9 +728,28 @@ function DocsPage() {
     [pathname],
   );
 
+  // Search source: Pagefind for content/excerpts, but resolve each result's
+  // breadcrumb from the real NAVIGATION (a page's nav group can differ from its
+  // URL path — e.g. essentials/markdown.mdx lives under the "Writing Content"
+  // group). Page rows show the path to the page; anchor rows include the page.
+  const searchDocs = React.useCallback(async (q) => {
+    const results = await pagefindSearch(q);
+    if (!Array.isArray(results)) return results;
+    return results.map((r) => {
+      const res = resolve(r.href.split('#')[0], navigation, pages);
+      if (!res?.breadcrumb?.length) return r;
+      const labels = res.breadcrumb.map((c) => c.label);
+      const crumbs = r.kind === 'anchor' ? labels : labels.slice(0, -1);
+      return crumbs.length ? { ...r, breadcrumb: crumbs } : r;
+    });
+  }, []);
+
   const frontmatter = entry?.frontmatter ?? {};
   const PageComponent = entry?.Component ?? null;
   const pageToc = entry?.toc ?? [];
+  // 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;
 
   // Switcher option sets (only render a switcher when an axis has >1
   // option). Anchors are pinned sidebar links shown in the context zone.
@@ -763,6 +786,27 @@ function DocsPage() {
     />
   );
 
+  // Keep document.title / meta description / <html lang> in sync on client-side
+  // navigation. The HTML is SSR'd with a per-page (build) or generic (dev) title;
+  // without this the tab title would stay frozen on the first page as you
+  // navigate the SPA, and JS-executing crawlers would read the stale value.
+  React.useEffect(() => {
+    const t = frontmatter.title;
+    document.title = isNotFound
+      ? `Page not found - ${site.name}`
+      : t && t !== site.name
+        ? `${t} - ${site.name}`
+        : site.name;
+    let descTag = document.querySelector('meta[name="description"]');
+    if (!descTag) {
+      descTag = document.createElement('meta');
+      descTag.setAttribute('name', 'description');
+      document.head.appendChild(descTag);
+    }
+    descTag.setAttribute('content', frontmatter.description || '');
+    document.documentElement.lang = nav?.activeLanguageCode || 'en';
+  }, [pathname, isNotFound, frontmatter.title, frontmatter.description, nav?.activeLanguageCode]);
+
   // Frontmatter title needs an id so scroll-spy + click-to-scroll work
   // against it like any other heading.
   const pageId = React.useMemo(() => {
@@ -1059,6 +1103,7 @@ function DocsPage() {
       data-sidebar-open={sidebarOpen ? 'true' : 'false'}
       data-drawer-open={drawerOpen ? 'true' : 'false'}
       data-api={entry?.api ? 'true' : 'false'}
+      data-not-found={isNotFound ? 'true' : undefined}
     >
       {/* Scrim — visible at mobile while the drawer OR the chatbot
           sheet is open. Sits between the article (z-0) and the
@@ -1089,7 +1134,12 @@ function DocsPage() {
         tabsTrailing={languageSwitcher || undefined}
         center={
           <Cluster space="var(--s-6)" align="center">
-            <Search style={{ inlineSize: '30ch' }} unavailable={IS_DEV_PREVIEW} />
+            <Search
+              style={{ inlineSize: '30ch' }}
+              unavailable={IS_DEV_PREVIEW}
+              search={IS_DEV_PREVIEW ? undefined : searchDocs}
+              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 && (
@@ -1249,6 +1299,11 @@ function DocsPage() {
               )}
             </Stack>
           )}
+          {/* Hairline separating the top anchor links from the nav sections
+              (faithful to the sidebar design's anchor↔sidebar divider). */}
+          {anchors.length > 0 && (
+            <div className="velu-docs-context-divider" aria-hidden="true" />
+          )}
           {/* Only this region scrolls — the context zone above stays
               pinned. The up/down arrows overlay its top/bottom edges and
               appear (via the data-fade-* attrs the scroll handler sets)
@@ -1353,6 +1408,21 @@ function DocsPage() {
           and the right margin collapses to 0 while the chatbot is
           open via [data-chat-open="true"]). */}
       <div className="velu-docs-layout__center">
+        {isNotFound ? (
+          <main className="velu-404-main">
+            <NotFound
+              homeHref="/"
+              linkComponent={RouterLink}
+              onSearch={() =>
+                window.dispatchEvent(
+                  new KeyboardEvent('keydown', { key: 'k', ctrlKey: true, metaKey: true }),
+                )
+              }
+              onAskAI={IS_DEV_PREVIEW ? undefined : () => askAI('')}
+            />
+          </main>
+        ) : (
+        <>
         {/* Narrow-layout TOC bar — always in DOM, only visible at
             < 1024px (toggled by @container in toc-bar.css). Shares
             its `items` + `activeId` + `onSelect` API with the
@@ -1395,7 +1465,25 @@ function DocsPage() {
             })}
           </span>
         </button>
-        <div className="velu-docs-layout__article">
+        <div className="velu-docs-layout__article" data-pagefind-body="">
+          {/* Per-page agent/IDE action bar: the section eyebrow + a
+              "Copy Page" split-button whose dropdown is driven by the
+              Mintlify-compatible `contextual` config. Renders nothing
+              when there's neither an eyebrow nor any enabled options. */}
+          <ContextMenu
+            eyebrow={
+              nav?.breadcrumb && nav.breadcrumb.length > 1
+                ? nav.breadcrumb[nav.breadcrumb.length - 2].label
+                : undefined
+            }
+            pageUrl={pathname}
+            title={frontmatter.title}
+            isApi={entry?.api === true}
+            siteName={site.name}
+            options={site.contextual?.options ?? []}
+            onAssistant={IS_DEV_PREVIEW ? undefined : () => askAI('')}
+          />
+
           {/* Page hero from MDX frontmatter. `.velu-hero` rules
               (in base.css) keep the title and description tightly
               grouped and create a clear break before the prose body. */}
@@ -1494,6 +1582,8 @@ function DocsPage() {
           )}
         </div>
       </main>
+        </>
+        )}
       </div>
 
       {/* Full site footer — only when the config provides link columns. Spans

package/templates/starter/velu.json

@@ -1,10 +1,14 @@
 {
   "$schema": "https://veludocs.com/velu.schema.json",
   "name": "Starter",
+  "url": "https://veludocs.com",
   "colors": {
     "primary": "#dc143c"
   },
   "favicon": "/favicon.svg",
+  "contextual": {
+    "options": ["copy", "view", "chatgpt", "claude", "mcp", "cursor", "vscode"]
+  },
   "navigation": {
     "anchors": [
       { "anchor": "Documentation", "icon": "book-open", "href": "https://veludocs.com" },