@veluai/velu 0.1.16 → 0.2.1

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

@@ -0,0 +1,273 @@
+import React from 'react';
+import {
+  Copy,
+  Check,
+  ChevronDown,
+  ArrowUpRight,
+  Sparkles,
+  Terminal,
+  Download,
+  Bot,
+  Wind,
+} from 'lucide-react';
+import Cluster from '../primitives/Cluster.jsx';
+import {
+  MarkdownIcon,
+  OpenAIIcon,
+  ClaudeIcon,
+  PerplexityIcon,
+  CursorIcon,
+  VscodeIcon,
+} from '../lib/brand-icons.jsx';
+
+/**
+ * ContextMenu — the per-page agent/IDE action bar shown at the top of every
+ * page: the section eyebrow on the left, and a "Copy Page" split-button with a
+ * dropdown on the right. The dropdown items are driven by the Mintlify-
+ * compatible `contextual.options` config.
+ *
+ * The primary button copies the page's Markdown (the `.md` twin). Items either
+ * copy, open the Markdown, download the spec, or open the page in an AI tool /
+ * IDE. All side effects happen in click handlers (SSR-safe — no window at
+ * render).
+ *
+ * @param {{
+ *   eyebrow?: string,                 // section/group label
+ *   pageUrl: string,                  // page path, e.g. "/quickstart"
+ *   title?: string,                   // page title (for AI prompts / filenames)
+ *   isApi?: boolean,                  // API page → enable download-spec
+ *   siteName?: string,                // for MCP deep-link labels
+ *   options?: Array<string|{title,description,href,icon}>,
+ *   onAssistant?: () => void,         // 'assistant' option → in-site Ask AI
+ * }} props
+ */
+
+// The Markdown URL for a page path (`/` → `/index.md`).
+const mdUrlForPage = (url) => (url === '/' ? '/index.md' : `${url}.md`);
+
+// key → { icon, label, desc, external?, apiOnly?, kind, url? }
+const REGISTRY = {
+  copy: { icon: Copy, label: 'Copy page', desc: 'Copy page as Markdown for LLMs', kind: 'copy' },
+  view: { icon: MarkdownIcon, label: 'View as Markdown', desc: 'Open the raw Markdown', kind: 'view', external: true },
+  'download-spec': { icon: Download, label: 'Download OpenAPI spec', desc: 'Save this endpoint as YAML', kind: 'spec', apiOnly: true },
+  assistant: { icon: Sparkles, label: 'Ask AI', desc: 'Ask the docs assistant about this page', kind: 'assistant' },
+  chatgpt: { icon: OpenAIIcon, label: 'Open in ChatGPT', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://chatgpt.com/?hints=search&q=${q}` },
+  claude: { icon: ClaudeIcon, label: 'Open in Claude', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://claude.ai/new?q=${q}` },
+  perplexity: { icon: PerplexityIcon, label: 'Open in Perplexity', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://www.perplexity.ai/search?q=${q}` },
+  grok: { icon: Bot, label: 'Open in Grok', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://grok.com/?q=${q}` },
+  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' },
+  '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 },
+};
+
+export default function ContextMenu({
+  eyebrow,
+  pageUrl,
+  title = '',
+  isApi = false,
+  siteName = 'docs',
+  options = [],
+  onAssistant,
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [copied, setCopied] = React.useState(false);
+  const rootRef = React.useRef(null);
+  const copiedTimer = React.useRef(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    const onDoc = (e) => {
+      if (!rootRef.current?.contains(e.target)) setOpen(false);
+    };
+    const onKey = (e) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('mousedown', onDoc);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDoc);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  React.useEffect(() => () => clearTimeout(copiedTimer.current), []);
+
+  const flashCopied = () => {
+    setCopied(true);
+    clearTimeout(copiedTimer.current);
+    copiedTimer.current = setTimeout(() => setCopied(false), 1600);
+  };
+
+  const mdUrl = mdUrlForPage(pageUrl);
+
+  // Build the descriptor list from the configured options (skip API-only items
+  // off API pages, and any unsupported keys).
+  const items = [];
+  for (const o of options) {
+    if (typeof o === 'object' && o) {
+      items.push({ icon: ArrowUpRight, label: o.title, desc: o.description, external: true, kind: 'custom', href: o.href });
+      continue;
+    }
+    const def = REGISTRY[o];
+    if (!def) continue; // e.g. download-pdf — no static pipeline
+    if (def.apiOnly && !isApi) continue;
+    items.push({ ...def, key: o });
+  }
+
+  const copyText = async (text) => {
+    try {
+      await navigator.clipboard.writeText(text);
+      flashCopied();
+    } catch {
+      /* clipboard blocked — no-op */
+    }
+  };
+
+  const copyPage = async () => {
+    try {
+      const md = await fetch(mdUrl).then((r) => r.text());
+      await copyText(md);
+    } catch {
+      /* fetch failed — no-op */
+    }
+  };
+
+  const run = async (it) => {
+    setOpen(false);
+    const origin = window.location.origin;
+    const absMd = origin + mdUrl;
+    switch (it.kind) {
+      case 'copy':
+        return copyPage();
+      case 'view':
+        return void window.open(mdUrl, '_blank', 'noopener');
+      case 'spec': {
+        try {
+          const text = await fetch(mdUrl).then((r) => r.text());
+          const blob = new Blob([text], { type: 'text/yaml' });
+          const a = document.createElement('a');
+          a.href = URL.createObjectURL(blob);
+          a.download = `${(title || 'openapi').replace(/[^a-z0-9]+/gi, '-').toLowerCase()}.yaml`;
+          a.click();
+          URL.revokeObjectURL(a.href);
+        } catch {
+          /* no-op */
+        }
+        return;
+      }
+      case 'assistant':
+        return onAssistant?.();
+      case 'ai': {
+        const q = encodeURIComponent(`Read ${absMd} and answer my questions about this page.`);
+        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`);
+      case 'cursor': {
+        const cfg =
+          typeof btoa === 'function' ? btoa(JSON.stringify({ url: `${origin}/mcp` })) : '';
+        return void window.open(
+          `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(siteName)}&config=${cfg}`,
+          '_blank',
+          'noopener',
+        );
+      }
+      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',
+        );
+      }
+      case 'custom':
+        return void window.open(it.href, '_blank', 'noopener');
+      default:
+        return undefined;
+    }
+  };
+
+  // Nothing to show → render nothing (keeps the page top clean).
+  if (!eyebrow && !items.length) return null;
+
+  return (
+    <Cluster
+      space="var(--s-2)"
+      justify="space-between"
+      align="flex-end"
+      className="velu-context-bar"
+      data-pagefind-ignore=""
+    >
+      {eyebrow ? <span className="velu-context-bar__eyebrow">{eyebrow}</span> : <span />}
+
+      {items.length > 0 && (
+        <div ref={rootRef} className="velu-context-menu" data-open={open ? 'true' : 'false'}>
+          <div className="velu-context-menu__split">
+            <button
+              type="button"
+              className="velu-context-menu__copy"
+              onClick={copyPage}
+              aria-label="Copy page as Markdown"
+            >
+              <span className="velu-context-menu__copy-icon" aria-hidden="true">
+                {copied ? <Check size="1em" /> : <Copy size="1em" />}
+              </span>
+              <span>{copied ? 'Copied' : 'Copy Page'}</span>
+            </button>
+            <button
+              type="button"
+              className="velu-context-menu__toggle"
+              aria-haspopup="menu"
+              aria-expanded={open}
+              aria-label="More actions"
+              onClick={() => setOpen((v) => !v)}
+            >
+              <ChevronDown size="1em" aria-hidden="true" focusable="false" />
+            </button>
+          </div>
+
+          <ul className="velu-context-menu__menu" role="menu" aria-hidden={!open}>
+            {items.map((it, i) => {
+              const Icon = it.icon;
+              return (
+                <li key={it.key ?? it.href ?? i} role="none">
+                  <button
+                    type="button"
+                    role="menuitem"
+                    className="velu-context-menu__item"
+                    tabIndex={open ? 0 : -1}
+                    onClick={() => run(it)}
+                  >
+                    <span className="velu-context-menu__item-icon" aria-hidden="true">
+                      <Icon size="1.1em" />
+                    </span>
+                    <span className="velu-context-menu__item-text">
+                      <span className="velu-context-menu__item-title">
+                        {it.label}
+                        {it.external && (
+                          <ArrowUpRight
+                            className="velu-context-menu__item-ext"
+                            size="0.85em"
+                            aria-hidden="true"
+                          />
+                        )}
+                      </span>
+                      {it.desc && <span className="velu-context-menu__item-desc">{it.desc}</span>}
+                    </span>
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      )}
+    </Cluster>
+  );
+}

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

@@ -0,0 +1,63 @@
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * NotFound — the 404 page ("Direction 1 · Classic" from the design):
+ * a big accent-colored numeral, a short message, and a three-action row
+ * (Back to Home / Search the docs / Ask AI). Centered; the host layout
+ * supplies the header + footer. Pure tokens, so light/dark follow
+ * [data-theme] automatically.
+ *
+ * @param {{
+ *   homeHref?: string,
+ *   linkComponent?: React.ElementType,
+ *   onSearch?: () => void,
+ *   onAskAI?: () => void,
+ *   eyebrow?: string, title?: string, body?: string,
+ * }} props
+ */
+export default function NotFound({
+  homeHref = '/',
+  linkComponent = 'a',
+  onSearch,
+  onAskAI,
+  eyebrow = 'Error 404',
+  title = 'This page wandered off',
+  body = 'The page you’re looking for doesn’t exist or may have moved. Pick up the trail below.',
+}) {
+  const Link = linkComponent;
+  return (
+    <section className="velu-404">
+      <p className="velu-404__eyebrow">{eyebrow}</p>
+      <div className="velu-404__num" aria-hidden="true">
+        404
+      </div>
+      <h1 className="velu-404__title">{title}</h1>
+      <p className="velu-404__body">{body}</p>
+      <div className="velu-404__actions">
+        <Link className="velu-404__btn velu-404__btn--primary" href={homeHref}>
+          <span className="velu-404__btn-ic" aria-hidden="true">
+            {resolveIcon('house', { size: '1em' })}
+          </span>
+          Back to Home
+        </Link>
+        {onSearch && (
+          <button type="button" className="velu-404__btn" onClick={onSearch}>
+            <span className="velu-404__btn-ic" aria-hidden="true">
+              {resolveIcon('search', { size: '1em' })}
+            </span>
+            Search the docs
+          </button>
+        )}
+        {onAskAI && (
+          <button type="button" className="velu-404__btn" onClick={onAskAI}>
+            <span className="velu-404__btn-ic" aria-hidden="true">
+              {resolveIcon('sparkles', { size: '1em' })}
+            </span>
+            Ask AI
+          </button>
+        )}
+      </div>
+    </section>
+  );
+}

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

@@ -162,10 +162,14 @@ function PaletteRow({ item, selected, navMode, onHover, onSelect }) {
   );
 }
 
-/* The revealed palette — scrim + centered panel. */
-function SearchPalette({ results, placeholder, onSelect, onClose }) {
+/* The revealed palette — scrim + centered panel. When `search` (an async
+   query → results function, e.g. the Pagefind client) is provided, results
+   come from it; otherwise the static `results` list is filtered in-memory. */
+function SearchPalette({ results, search, placeholder, onSelect, onClose }) {
   const [query, setQuery] = useState('');
   const [selected, setSelected] = useState(0);
+  const [asyncResults, setAsyncResults] = useState([]);
+  const [searching, setSearching] = useState(false);
   const inputRef = useRef(null);
   // 'keyboard' | 'mouse' — which input last moved the selection; gates
   // the rows' scrollIntoView so mouse hover doesn't jitter the list.
@@ -175,7 +179,32 @@ function SearchPalette({ results, placeholder, onSelect, onClose }) {
     inputRef.current?.focus();
   }, []);
 
+  // Async source (Pagefind): debounce the query, fetch results.
+  useEffect(() => {
+    if (!search) return undefined;
+    const q = query.trim();
+    if (!q) {
+      setAsyncResults([]);
+      setSearching(false);
+      return undefined;
+    }
+    let cancelled = false;
+    setSearching(true);
+    const t = setTimeout(async () => {
+      const r = await search(q).catch(() => []);
+      if (!cancelled) {
+        setAsyncResults(Array.isArray(r) ? r : []);
+        setSearching(false);
+      }
+    }, 150);
+    return () => {
+      cancelled = true;
+      clearTimeout(t);
+    };
+  }, [query, search]);
+
   const filtered = useMemo(() => {
+    if (search) return asyncResults;
     const q = query.trim().toLowerCase();
     if (!q) {
       // Empty query → just the recents.
@@ -185,15 +214,18 @@ function SearchPalette({ results, placeholder, onSelect, onClose }) {
       const hay = `${r.title} ${r.breadcrumb.join(' ')} ${r.desc}`.toLowerCase();
       return hay.includes(q);
     });
-  }, [query, results]);
+  }, [search, asyncResults, query, results]);
 
   const grouped = useMemo(() => {
     const map = new Map();
     filtered.forEach((r) => {
-      if (!map.has(r.group)) map.set(r.group, []);
-      map.get(r.group).push(r);
+      const g = r.group || 'Pages';
+      if (!map.has(g)) map.set(g, []);
+      map.get(g).push(r);
     });
-    return GROUP_ORDER.filter((g) => map.has(g)).map((g) => [g, map.get(g)]);
+    const known = GROUP_ORDER.filter((g) => map.has(g));
+    const extra = [...map.keys()].filter((g) => !GROUP_ORDER.includes(g));
+    return [...known, ...extra].map((g) => [g, map.get(g)]);
   }, [filtered]);
 
   const flat = useMemo(
@@ -266,19 +298,34 @@ function SearchPalette({ results, placeholder, onSelect, onClose }) {
         </div>
 
         <div className="velu-search__list" role="listbox">
-          {grouped.length === 0 && (
-            <div className="velu-search__empty">
-              <span className="velu-search__empty-icon" aria-hidden="true">
-                {resolveIcon('search-x', { size: '1em' })}
-              </span>
-              <div className="velu-search__empty-title">
-                No results for &ldquo;{query}&rdquo;
+          {grouped.length === 0 &&
+            (search && !query.trim() ? (
+              <div className="velu-search__empty">
+                <span className="velu-search__empty-icon" aria-hidden="true">
+                  {resolveIcon('search', { size: '1em' })}
+                </span>
+                <div className="velu-search__empty-title">Search the docs</div>
+                <div className="velu-search__empty-sub">
+                  Type to find pages and sections.
+                </div>
               </div>
-              <div className="velu-search__empty-sub">
-                Try a different keyword or browse the sidebar.
+            ) : searching ? (
+              <div className="velu-search__empty">
+                <div className="velu-search__empty-sub">Searching…</div>
               </div>
-            </div>
-          )}
+            ) : (
+              <div className="velu-search__empty">
+                <span className="velu-search__empty-icon" aria-hidden="true">
+                  {resolveIcon('search-x', { size: '1em' })}
+                </span>
+                <div className="velu-search__empty-title">
+                  No results for &ldquo;{query}&rdquo;
+                </div>
+                <div className="velu-search__empty-sub">
+                  Try a different keyword or browse the sidebar.
+                </div>
+              </div>
+            ))}
           {grouped.map(([group, items]) => (
             <div key={group}>
               <div className="velu-search__group">{group}</div>
@@ -346,6 +393,7 @@ function SearchUnavailable({ message, onClose }) {
 
 export default function Search({
   results = DEFAULT_RESULTS,
+  search,
   placeholder = 'Search documentation',
   onSelect,
   unavailable = false,
@@ -401,6 +449,7 @@ export default function Search({
         ) : (
           <SearchPalette
             results={results}
+            search={search}
             placeholder={placeholder}
             onSelect={onSelect}
             onClose={() => setOpen(false)}

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

@@ -41,6 +41,11 @@ import scrollIntoNearestView from '../lib/scrollIntoNearestView.js';
 
 const SidebarCtx = React.createContext({ activeHref: undefined, Link: 'a' });
 
+// Positioning must happen before paint (no flash); fall back to useEffect on
+// the server so React doesn't warn about useLayoutEffect during SSR.
+const useIsoLayoutEffect =
+  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
+
 function isActive(item, activeHref) {
   return Boolean(
     item.active || (item.href != null && item.href === activeHref)
@@ -166,6 +171,47 @@ export default function Sidebar({
     scrollIntoNearestView(el);
   }, [activeHref]);
 
+  // The single gliding active indicator (crimson tint + flush-left bar). One
+  // element animates its position/height to the active item, so selection feels
+  // continuous rather than each item popping its own bar. It lives in the scroll
+  // content, so its offset is scroll-stable (no re-measure on scroll) and a
+  // pinned sticky heading's opaque background covers it when an item tucks under.
+  const [ind, setInd] = React.useState({ top: 0, h: 0, show: false });
+  const measure = React.useCallback(() => {
+    const nav = rootRef.current;
+    if (!nav) return;
+    const el = nav.querySelector('[aria-current="page"]');
+    if (!el) {
+      setInd((s) => (s.show ? { ...s, show: false } : s));
+      return;
+    }
+    const top = el.getBoundingClientRect().top - nav.getBoundingClientRect().top;
+    const h = el.offsetHeight;
+    // Bail when nothing moved → no needless re-render (and no animation jitter).
+    setInd((s) =>
+      s.show && Math.abs(s.top - top) < 0.5 && Math.abs(s.h - h) < 0.5
+        ? s
+        : { top, h, show: true },
+    );
+  }, []);
+  // Re-measure on selection / tab change…
+  useIsoLayoutEffect(() => {
+    measure();
+  }, [activeHref, sections, measure]);
+  // …and whenever the nav's layout changes (a group expands/collapses → the
+  // active item moves), plus on viewport resize.
+  React.useEffect(() => {
+    const nav = rootRef.current;
+    if (!nav || typeof ResizeObserver === 'undefined') return undefined;
+    const ro = new ResizeObserver(() => measure());
+    ro.observe(nav);
+    window.addEventListener('resize', measure);
+    return () => {
+      ro.disconnect();
+      window.removeEventListener('resize', measure);
+    };
+  }, [measure]);
+
   return (
     <SidebarCtx.Provider value={ctx}>
       <Stack
@@ -176,6 +222,15 @@ export default function Sidebar({
         aria-label="Documentation"
         {...rest}
       >
+        <span
+          className="velu-sidebar__indicator"
+          aria-hidden="true"
+          style={{
+            transform: `translateY(${ind.top}px)`,
+            height: `${ind.h}px`,
+            opacity: ind.show ? 1 : 0,
+          }}
+        />
         {/* Each section is its own Stack so the heading sits TIGHT to
             its list (small inner gap), while the nav's larger gap
             separates one section from the next — compact but still

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

@@ -139,13 +139,6 @@
   gap: var(--s2);
 }
 
-/* Playground right column: live response (when present) stacked above the
-   same request/response code samples shown in the page's right rail. */
-.velu-api-pg-aside {
-  display: flex;
-  flex-direction: column;
-  gap: var(--s2);
-}
 /* Breathing room inside each sample group — the code panels were reading
    as cramped against the rail edge. */
 .velu-api-samples > * {

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

@@ -265,6 +265,9 @@
   overflow: hidden;
   max-inline-size: 100%;
   min-inline-size: 0;
+  /* Own query container so the body grid reflows to the client's width
+     (it lives in a modal, outside the docs layout container). */
+  container: api-client / inline-size;
 }
 
 /* Modal close button — sits in its own row at the top of the client,
@@ -413,25 +416,62 @@
   background: transparent;
 }
 
-/* Two-column body. Falls back to single column on narrow widths via
-   a Switcher-style flex-wrap trick: flex-basis with a calc() that
-   flips when the container drops below the threshold. */
+/* Body grid with named areas so the three slots — form / live response /
+   code samples — can be placed AND reordered independently.
+   Wide (the client is its own query container, set on .velu-api-client):
+     form fills the left column; response sits top-right with the samples
+     below it. When there's no response yet, the samples take the whole right
+     column.
+   Narrow (single column): the live response moves ABOVE the form so a Send
+   result is visible without scrolling past the inputs; form then samples
+   follow. */
 .velu-api-client__body {
-  display: flex;
-  flex-wrap: wrap;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  grid-template-areas: 'form aside';
+  align-items: start;
   gap: var(--s2);
   padding: var(--s2);
 }
-.velu-api-client__left,
+.velu-api-client__body[data-has-response='true'] {
+  grid-template-areas:
+    'form response'
+    'form aside';
+}
+.velu-api-client__left {
+  grid-area: form;
+}
+.velu-api-client__response {
+  grid-area: response;
+}
 .velu-api-client__right {
-  flex-grow: 1;
-  flex-basis: calc((40rem - 100%) * 999);
+  grid-area: aside;
+}
+.velu-api-client__left,
+.velu-api-client__right,
+.velu-api-client__response {
   display: flex;
   flex-direction: column;
   gap: var(--s1);
   min-inline-size: 0;
 }
 
+@container api-client (max-width: 40rem) {
+  .velu-api-client__body,
+  .velu-api-client__body[data-has-response='true'] {
+    grid-template-columns: 1fr;
+    grid-template-areas:
+      'form'
+      'aside';
+  }
+  .velu-api-client__body[data-has-response='true'] {
+    grid-template-areas:
+      'response'
+      'form'
+      'aside';
+  }
+}
+
 .velu-api-client__title {
   margin: 0;
   font-size: var(--f-h3);