@veluai/velu 0.2.0 → 0.2.1

package/dist/cli.js

@@ -25,7 +25,7 @@ ${L.join(`,
 `),$.join(`
 `),"","export const pages = {",c.join(`
 `),"};",`export const navigation = ${JSON.stringify(i)};`,`export const site = ${JSON.stringify(p)};`,""].join(`
-`)}var Ot,At,Lt=j(()=>{B();oe();Y();Be();Ot="virtual:velu-site",At="\0"+Ot});import{visit as lr}from"unist-util-visit";function cr(e,t){let n=Pt(e).replace(/[?#].*$/,""),r=Pt(t).replace(/\/+$/,"");return r&&n.toLowerCase().startsWith(r.toLowerCase())?n.slice(r.length).replace(/^\/+/,""):null}function _t(e,t){return()=>(n,r)=>{typeof e=="function"&&lr(n,o=>{if(o.type!=="mdxJsxFlowElement"&&o.type!=="mdxJsxTextElement"||typeof o.name!="string"||!/^[A-Z]/.test(o.name)||o.name.includes("."))return;let i={};for(let s of o.attributes||[])s.type==="mdxJsxAttribute"&&(s.value==null?i[s.name]=!0:typeof s.value=="string"&&(i[s.name]=s.value));let a=e(o.name,i,{checkRequired:!1});if(a){let s=new Error(a.title);throw s.veluIssue={...a,file:cr(r?.path,t),line:o.position?.start?.line??null,column:o.position?.start?.column??null},s.loc={line:s.veluIssue.line,column:s.veluIssue.column},s}})}}var Pt,Ct=j(()=>{Pt=e=>String(e||"").replace(/\\/g,"/")});import ve from"node:path";import ur from"node:fs";import{createRequire as pr}from"node:module";import fr from"@tailwindcss/vite";import mr from"@vitejs/plugin-react";import dr from"@mdx-js/rollup";import gr from"remark-frontmatter";import hr from"remark-mdx-frontmatter";import yr from"remark-gfm";import vr from"rehype-slug";function br(e){let n=pr(import.meta.url).resolve("@mdx-js/react"),r=ve.resolve(e,"runtime","velu-ui"),o=ur.existsSync(r)?r:ve.resolve(e,"..","velu-ui","src");return[{find:"@mdx-js/react",replacement:n},{find:/^velu-ui$/,replacement:ve.join(o,"index.js")},{find:/^velu-ui\//,replacement:o+"/"}]}function Et({targetDir:e,VITE_ROOT:t,validateProps:n}){return{root:t,plugins:[Tt(e),dr({remarkPlugins:[gr,hr,yr,ne,_t(n,e)],rehypePlugins:[vr],providerImportSource:"@mdx-js/react"}),mr(),fr({optimize:!1})],cacheDir:ve.resolve(e,".velu","vite-cache"),optimizeDeps:{include:["react","react-dom","react-dom/client","react-router-dom","@mdx-js/react","lucide-react","prism-react-renderer","iso-639-1","github-slugger"],exclude:["tailwindcss","@tailwindcss/oxide","playwright","playwright-core","@apidevtools/swagger-parser","satori","@resvg/resvg-js"],esbuildOptions:{loader:{".mdx":"jsx"}}},resolve:{alias:br(t),dedupe:["react","react-dom","@mdx-js/react"]}}}var Ft=j(()=>{Re();Lt();Ct()});function A(e){return{category:"render-crash",severity:"error",file:null,line:null,column:null,frame:null,title:"Something went wrong",detail:"",hint:"",suggestion:null,...e}}function xr(e,t){if(e=String(e),t=String(t),e===t)return 0;if(!e.length)return t.length;if(!t.length)return e.length;let n=Array.from({length:t.length+1},(o,i)=>i),r=new Array(t.length+1);for(let o=1;o<=e.length;o++){r[0]=o;for(let i=1;i<=t.length;i++){let a=e[o-1]===t[i-1]?0:1;r[i]=Math.min(r[i-1]+1,n[i]+1,n[i-1]+a)}[n,r]=[r,n]}return n[t.length]}function be(e,t=[]){if(!e)return null;let n=String(e).toLowerCase(),r=null,o=1/0;for(let a of t){let s=xr(n,String(a).toLowerCase());s<o&&(o=s,r=a)}let i=Math.min(3,Math.max(2,Math.floor(n.length/4)));return o<=i?r:null}function $r(e,t){return e==="warning"?E(t,_.yellow,"\u26A0"):e==="info"?E(t,_.cyan,"\u2139"):E(t,_.red,"\u2716")}function Je(e,{color:t=!1}={}){let n=Ge[e.category]||e.category,r=e.line?`${e.line}${e.column?`:${e.column}`:""}`:"",o=e.file?`${e.file}${r?`:${r}`:""}`:r,i=[];if(i.push(`${$r(e.severity,t)} ${E(t,_.bold,n)}`+(o?`  ${E(t,_.dim,o)}`:"")),e.title&&i.push(`  ${e.title}`),e.detail&&e.detail!==e.title&&i.push(`  ${E(t,_.dim,e.detail)}`),e.frame)for(let a of String(e.frame).split(`
+`)}var Ot,At,Lt=j(()=>{B();oe();Y();Be();Ot="virtual:velu-site",At="\0"+Ot});import{visit as lr}from"unist-util-visit";function cr(e,t){let n=Pt(e).replace(/[?#].*$/,""),r=Pt(t).replace(/\/+$/,"");return r&&n.toLowerCase().startsWith(r.toLowerCase())?n.slice(r.length).replace(/^\/+/,""):null}function _t(e,t){return()=>(n,r)=>{typeof e=="function"&&lr(n,o=>{if(o.type!=="mdxJsxFlowElement"&&o.type!=="mdxJsxTextElement"||typeof o.name!="string"||!/^[A-Z]/.test(o.name)||o.name.includes("."))return;let i={};for(let s of o.attributes||[])s.type==="mdxJsxAttribute"&&(s.value==null?i[s.name]=!0:typeof s.value=="string"&&(i[s.name]=s.value));let a=e(o.name,i,{checkRequired:!1});if(a){let s=new Error(a.title);throw s.veluIssue={...a,file:cr(r?.path,t),line:o.position?.start?.line??null,column:o.position?.start?.column??null},s.loc={line:s.veluIssue.line,column:s.veluIssue.column},s}})}}var Pt,Ct=j(()=>{Pt=e=>String(e||"").replace(/\\/g,"/")});import ve from"node:path";import ur from"node:fs";import{createRequire as pr}from"node:module";import fr from"@tailwindcss/vite";import mr from"@vitejs/plugin-react";import dr from"@mdx-js/rollup";import gr from"remark-frontmatter";import hr from"remark-mdx-frontmatter";import yr from"remark-gfm";import vr from"rehype-slug";function br(e){let n=pr(import.meta.url).resolve("@mdx-js/react"),r=ve.resolve(e,"runtime","velu-ui"),o=ur.existsSync(r)?r:ve.resolve(e,"..","velu-ui","src");return[{find:"@mdx-js/react",replacement:n},{find:/^velu-ui$/,replacement:ve.join(o,"index.js")},{find:/^velu-ui\//,replacement:o+"/"}]}function Et({targetDir:e,VITE_ROOT:t,validateProps:n}){return{root:t,plugins:[Tt(e),dr({remarkPlugins:[gr,hr,yr,ne,_t(n,e)],rehypePlugins:[vr],providerImportSource:"@mdx-js/react"}),mr(),fr({optimize:!1})],cacheDir:ve.resolve(e,".velu","vite-cache"),optimizeDeps:{include:["react","react-dom","react-dom/client","react-router-dom","@mdx-js/react","lucide-react","prism-react-renderer","iso-639-1","github-slugger"],exclude:["tailwindcss","@tailwindcss/oxide","playwright","playwright-core","@apidevtools/swagger-parser","satori","@resvg/resvg-js","pagefind"],esbuildOptions:{loader:{".mdx":"jsx"}}},resolve:{alias:br(t),dedupe:["react","react-dom","@mdx-js/react"]}}}var Ft=j(()=>{Re();Lt();Ct()});function A(e){return{category:"render-crash",severity:"error",file:null,line:null,column:null,frame:null,title:"Something went wrong",detail:"",hint:"",suggestion:null,...e}}function xr(e,t){if(e=String(e),t=String(t),e===t)return 0;if(!e.length)return t.length;if(!t.length)return e.length;let n=Array.from({length:t.length+1},(o,i)=>i),r=new Array(t.length+1);for(let o=1;o<=e.length;o++){r[0]=o;for(let i=1;i<=t.length;i++){let a=e[o-1]===t[i-1]?0:1;r[i]=Math.min(r[i-1]+1,n[i]+1,n[i-1]+a)}[n,r]=[r,n]}return n[t.length]}function be(e,t=[]){if(!e)return null;let n=String(e).toLowerCase(),r=null,o=1/0;for(let a of t){let s=xr(n,String(a).toLowerCase());s<o&&(o=s,r=a)}let i=Math.min(3,Math.max(2,Math.floor(n.length/4)));return o<=i?r:null}function $r(e,t){return e==="warning"?E(t,_.yellow,"\u26A0"):e==="info"?E(t,_.cyan,"\u2139"):E(t,_.red,"\u2716")}function Je(e,{color:t=!1}={}){let n=Ge[e.category]||e.category,r=e.line?`${e.line}${e.column?`:${e.column}`:""}`:"",o=e.file?`${e.file}${r?`:${r}`:""}`:r,i=[];if(i.push(`${$r(e.severity,t)} ${E(t,_.bold,n)}`+(o?`  ${E(t,_.dim,o)}`:"")),e.title&&i.push(`  ${e.title}`),e.detail&&e.detail!==e.title&&i.push(`  ${E(t,_.dim,e.detail)}`),e.frame)for(let a of String(e.frame).split(`
 `))i.push(`  ${a}`);return e.suggestion&&i.push(`  ${E(t,_.cyan,`Did you mean <${e.suggestion}>?`)}`),e.hint&&i.push(`  ${E(t,_.dim,`\u2192 ${e.hint}`)}`),i.join(`
 `)}function xe(e,{color:t=!1}={}){if(!e.length)return E(t,_.cyan,"\u2713 No issues found.");let n=new Map;for(let s of e){let l=s.file||"velu.json";n.has(l)||n.set(l,[]),n.get(l).push(s)}let r=[];for(let[s,l]of n){r.push(E(t,_.bold,s));for(let p of l)r.push(Je({...p,file:null},{color:t}).replace(/^/gm,"  "));r.push("")}let o=e.filter(s=>s.severity!=="warning"&&s.severity!=="info").length,i=e.length-o,a=`${o} error${o===1?"":"s"}`+(i?`, ${i} warning${i===1?"":"s"}`:"");return r.push(E(t,o?_.red:_.yellow,a)),r.join(`
 `)}var Ge,_,E,J=j(()=>{Ge={"mdx-syntax":"MDX syntax",frontmatter:"Frontmatter","unknown-component":"Unknown component","invalid-props":"Invalid options","render-crash":"Render error","config-json":"velu.json","config-schema":"velu.json","config-nav":"Navigation","config-asset":"Asset"};_={reset:"\x1B[0m",red:"\x1B[31m",yellow:"\x1B[33m",cyan:"\x1B[36m",dim:"\x1B[2m",bold:"\x1B[1m"},E=(e,t,n)=>e?`${t}${n}${_.reset}`:n});function wr(e){let t=e,n=0;for(;t&&t.cause&&n<3&&!(t.loc||t.line||/`[^`]+` to be defined/.test(t.message||""));)t=t.cause,n+=1;return t||e}function Ve(e,t){if(!e)return null;let n=Nt(e).replace(/[?#].*$/,""),r=t?Nt(t).replace(/\/+$/,""):"";return r&&n.toLowerCase().startsWith(r.toLowerCase())?n.slice(r.length).replace(/^\/+/,""):!/^([a-zA-Z]:\/|\/)/.test(n)&&!/node_modules/.test(n)?n:null}function Sr(e){return e?String(e).replace(/([a-zA-Z]:\\|\/)[^\s'"()]+/g,t=>/node_modules|[\\/]vite[\\/]|@veluai|velu-cli|velu-ui/.test(t)?"\u2026":t).trim():""}function kr(e){let t=/\((\d+):(\d+)(?:-\d+:\d+)?\)\s*$/.exec(String(e||""));return t?{line:Number(t[1]),column:Number(t[2])}:null}function jr(e){return String(e||"").replace(/\s*\(\d+:\d+(?:-\d+:\d+)?\)\s*$/,"").trim()}function Or(e,t){if(!e||!t)return null;let n=String(e);return/node_modules|[\\/]vite[\\/]|@veluai[\\/]/.test(n)?null:n}function ae(e,t={}){let{projectDir:n="",knownComponents:r=[],file:o=null}=t,i=null;for(let h=e,w=0;h&&w<6;h=h.cause,w+=1)if(h.veluIssue){i=h.veluIssue;break}if(i)return A({...i,file:i.file||o});let a=wr(e)||{},s=a.message||String(e||""),l=/Expected component `([^`]+)` to be defined/.exec(s);if(l){let h=l[1],w=/referenced in your code at `(\d+):(\d+)/.exec(s),F=/\bin `([^`]+)`/.exec(s),x=F?Ve(F[1],n):null;return A({category:"unknown-component",file:x||o,line:w?Number(w[1]):null,column:w?Number(w[2]):null,title:`<${h}> is not a built-in component`,detail:"",hint:"Components are built in \u2014 check the spelling and capitalization (you don\u2019t import them).",suggestion:be(h,r)})}let p=a.loc||(a.line!=null?{line:a.line,column:a.column,file:a.file}:null)||kr(a.reason||s),u=a.id||p&&p.file||a.file||null,c=Ve(u,n)||o,b=!!c&&Ve(u,n)!=null,d=Or(a.frame,b||!!o),$=Sr(jr(a.reason||s)),m=Ar.test(s),L=a.source==="remark-frontmatter"||/\byaml\b|frontmatter/i.test(s)||p&&p.line===1&&/unexpected|expected/i.test(s)&&/---/.test(s);return p||m||d&&b?A({category:L?"frontmatter":"mdx-syntax",file:c,line:p?p.line:null,column:p?p.column:null,frame:d,title:$||(L?"Invalid frontmatter":"MDX syntax error"),detail:"",hint:L?"Check the YAML between the --- markers \u2014 indentation, quotes, and colons.":"Make sure every <Component> has a matching closing tag and that { } braces are balanced."}):/\.map is not a function|is not iterable|reading '|undefined \(reading/i.test(s)?A({category:"invalid-props",file:c,title:"A component received an invalid value",detail:$,hint:"Check the props/options you passed to a component on this page."}):A({category:"render-crash",file:c,title:"This page failed to render",detail:$,hint:"Set VELU_DEBUG=1 for the full stack trace."})}var Nt,Ar,qe=j(()=>{J();Nt=e=>String(e).replace(/\\/g,"/");Ar=/closing tag|unexpected closing|could not parse (?:expression|import|export)|unexpected character|unexpected end of|expected a closing|expected the closing|unexpected `|in expression|misnested|before name/i});function Tr(e){let t=Ge[e.category]||e.category,n=e.file?`${e.file}${e.line?`:${e.line}${e.column?`:${e.column}`:""}`:""}`:"",r=[];return r.push('<div class="velu-err-card">'),r.push('<div class="velu-err-head">'),r.push(`<span class="velu-err-pill">${I(t)}</span>`),r.push("</div>"),e.title&&r.push(`<div class="velu-err-title">${I(e.title)}</div>`),n&&r.push(`<a class="velu-err-loc" title="${I(n)}">${I(n)}</a>`),e.detail&&r.push(`<div class="velu-err-detail">${I(e.detail)}</div>`),e.frame&&r.push(`<pre class="velu-err-frame">${I(e.frame)}</pre>`),e.suggestion&&r.push(`<div class="velu-err-suggest">Did you mean <code>&lt;${I(e.suggestion)}&gt;</code>?</div>`),e.hint&&r.push(`<div class="velu-err-hint">${I(e.hint)}</div>`),r.push("</div>"),r.join("")}function He(e,t={}){let n=Array.isArray(e)?e:[e],r=t.title||(n.length>1?`${n.length} problems to fix`:"There\u2019s a problem to fix"),o=n.map(Tr).join(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veluai/velu",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "bin": "./dist/cli.js",
   "publishConfig": {
@@ -56,6 +56,7 @@
     "@fontsource/outfit": "^5.0.0",
     "@resvg/resvg-js": "^2.6.2",
     "esbuild": "^0.28.0",
+    "pagefind": "^1.3.0",
     "playwright": "^1.48.0",
     "satori": "^0.12.0"
   }

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

@@ -203,6 +203,7 @@ export default function ContextMenu({
       justify="space-between"
       align="flex-end"
       className="velu-context-bar"
+      data-pagefind-ignore=""
     >
       {eyebrow ? <span className="velu-context-bar__eyebrow">{eyebrow}</span> : <span />}
 

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/context-menu.css

@@ -3,7 +3,10 @@
    tokens, light/dark via [data-theme]. */
 
 .velu-context-bar {
-  margin-block-end: var(--s0);
+  /* Tight to the page title below — the eyebrow reads as a kicker on the
+     title, not a detached row. Negative pull cancels the h1's line-height
+     leading so the cap-height of the title sits right under the eyebrow. */
+  margin-block-end: calc(-1 * var(--s-5));
 }
 
 /* Section/group label, top-left — small, uppercase, accent (matches the

package/runtime/velu-ui/components/docs-layout.css

@@ -102,6 +102,16 @@
 /* Region wrapping the scroll area + the overlay arrows. Fills the
    remaining aside height; relative so the arrows position to its
    top/bottom edges. */
+/* Hairline between the top anchor links and the nav sections (the sidebar
+   design's anchor↔sidebar separator). Tokenized; sits flush in the aside flow. */
+.velu-docs-context-divider {
+  flex: none;
+  block-size: var(--border-width);
+  background: var(--border-color);
+  margin-block: var(--s-2);
+  margin-inline: var(--s-2);
+}
+
 .velu-docs-nav-region {
   position: relative;
   flex: 1 1 auto;
@@ -200,10 +210,13 @@
 .velu-docs-layout__aside--right[data-fade-top='true'] {
   --vf-top: var(--s2);
 }
-/* The left nav's under-heading fade (the ::after below each sticky
-   section heading) is shown only while the nav is scrolled up, so a
-   section's first item isn't dimmed at rest. */
-.velu-docs-nav-scroll[data-fade-top='true'] .velu-sidebar__section::after {
+/* The left nav's under-heading fade (the ::after below a sticky section
+   heading) is shown only while the nav is scrolled up AND only under the
+   currently-PINNED section ([data-stuck], set by the runtime). Other sections'
+   headings scroll normally, so their first item must not be dimmed — only the
+   item sliding under the top-pinned heading fades. */
+.velu-docs-nav-scroll[data-fade-top='true']
+  .velu-sidebar__section[data-stuck='true']::after {
   opacity: 1;
 }
 .velu-docs-nav-scroll[data-fade-bottom='true'],

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

@@ -147,6 +147,7 @@
   color: var(--text-color);
 }
 .velu-header__action--outlined:hover {
+  background: var(--surface-color);
   border-color: var(--accent-color);
   color: var(--accent-color);
 }

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

@@ -7,10 +7,51 @@
    rotation, and centralized icon sizing/stroke. All values are tokens. */
 
 .velu-sidebar {
-  border-left: var(--border-width) solid var(--surface-color);
+  position: relative; /* anchors the gliding active indicator */
   margin-left: var(--s1);
 }
 
+/* The single active indicator — a crimson tint band with a flush-left 2px bar
+   that GLIDES between items (one element animating its position/height) instead
+   of each item painting its own active state. z-index 0 keeps it BEHIND the
+   items + sticky headings (both positioned, z-index 1), so the text reads over
+   the tint and a pinned heading's opaque background covers the indicator when an
+   item scrolls under it. Driven imperatively from JS (transform/height/opacity);
+   the easing curve makes the slide feel continuous. */
+.velu-sidebar__indicator {
+  position: absolute;
+  inset-inline-start: 0;
+  inset-inline-end: var(--s-3);
+  inset-block-start: 0;
+  height: 0;
+  opacity: 0;
+  z-index: 0;
+  pointer-events: none;
+  background: color-mix(in srgb, var(--accent-color) 8%, transparent);
+  border-radius: var(--radius-sm);
+  transition:
+    transform 0.3s cubic-bezier(0.32, 0.72, 0, 1),
+    height 0.3s cubic-bezier(0.32, 0.72, 0, 1),
+    opacity 0.2s ease;
+  will-change: transform, height;
+}
+.velu-sidebar__indicator::before {
+  content: '';
+  position: absolute;
+  inset-inline-start: 0;
+  inset-block: 15%;
+  inline-size: 2px;
+  border-start-end-radius: 2px;
+  border-end-end-radius: 2px;
+  background: var(--accent-color);
+}
+/* Honour reduced-motion: snap instead of glide. */
+@media (prefers-reduced-motion: reduce) {
+  .velu-sidebar__indicator {
+    transition: opacity 0.2s ease;
+  }
+}
+
 .velu-sidebar__section {
   /* Sticky section header: each heading pins to the top of the scroll
      region until its own section scrolls past, then the next heading
@@ -21,7 +62,10 @@
      bar is invisible until it's actually covering scrolled content. */
   position: sticky;
   inset-block-start: 0;
-  z-index: 1;
+  /* Above the items (z-index 1) so scrolled rows tuck UNDER the heading (its
+     opaque bg + the ::after fade hide them), not over it; above the gliding
+     indicator (z-index 0) too. */
+  z-index: 2;
   background: var(--page-bg);
   display: flex;
   align-items: center;
@@ -94,21 +138,38 @@
    so these stay CSS until/if a Cluster/Inline primitive exists. */
 .velu-sidebar__item,
 .velu-sidebar__subitem {
+  /* Positioned above the gliding indicator (z-index 0) so the label reads over
+     the tint band. */
+  position: relative;
+  z-index: 1;
   display: flex;
   align-items: center;
   gap: var(--s-3);
   padding-inline: var(--s0);
   color: var(--text-color);
   text-decoration: none;
+  transition: color 0.2s ease;
 }
 
 .velu-sidebar__subitem {
   padding-block: var(--s-5);
 }
 
+/* Active = colour + weight only; the moving indicator paints the bar + tint. */
 .velu-sidebar__item--active {
   color: var(--accent-color);
-  border-left: 2px solid var(--accent-color);
+  font-weight: 500;
+}
+.velu-sidebar__item--active .velu-sidebar__icon {
+  color: var(--accent-color);
+}
+
+/* The label fills the row so the group chevron (and any external-link icon)
+   sit flush at the row's RIGHT end, not crowded against the label — faithful
+   to the design's `flex: 1` label. */
+.velu-sidebar__label {
+  flex: 1;
+  min-inline-size: 0;
 }
 
 .velu-sidebar__summary {

package/runtime/velu-ui/components/theme-toggle.css

@@ -39,6 +39,7 @@
     transform 0.18s cubic-bezier(0.34, 1.56, 0.64, 1);
 }
 .velu-theme-toggle:hover {
+  background: var(--surface-color);
   border-color: var(--accent-color);
 }
 /* Tactile press feedback on click. */

package/runtime/velu-ui/index.js

@@ -42,6 +42,7 @@ export {
   VeluMark,
 } from './components/PageHeader.jsx';
 export { default as Search } from './components/Search.jsx';
+export { default as pagefindSearch } from './lib/pagefind.js';
 export { default as Image } from './components/Image.jsx';
 export {
   default as CodeBlock,

package/runtime/velu-ui/lib/brand-icons.jsx

@@ -6,9 +6,10 @@ import React from 'react';
  * like lucide — no SVG loader). Each takes a `size` prop, mirroring lucide's
  * icon API so they're drop-in in the menu.
  *
- * Monochrome marks (OpenAI, Cursor) use `currentColor` so they follow the menu
- * text/hover color across light + dark. Multi-color marks (Claude, Perplexity,
- * VS Code) keep their brand colors — legible on both themes.
+ * ALL marks use `currentColor` so the icon column reads as one uniform set:
+ * muted/grey at rest, accent on hover (matching the lucide icons beside them).
+ * The brand glyphs keep their distinctive shapes; only the fill follows the
+ * menu's text/hover color across light + dark.
  */
 
 export function MarkdownIcon({ size = '1em', ...rest }) {
@@ -39,7 +40,7 @@ export function OpenAIIcon({ size = '1em', ...rest }) {
 export function ClaudeIcon({ size = '1em', ...rest }) {
   return (
     <svg width={size} height={size} viewBox="0 0 256 257" aria-hidden="true" {...rest}>
-      <path fill="#D97757" d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z" />
+      <path fill="currentColor" d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z" />
     </svg>
   );
 }
@@ -47,7 +48,7 @@ export function ClaudeIcon({ size = '1em', ...rest }) {
 export function PerplexityIcon({ size = '1em', ...rest }) {
   return (
     <svg width={size} height={size} viewBox="0 0 48 48" fill="none" aria-hidden="true" {...rest}>
-      <g stroke="#20808d" strokeLinecap="round" strokeLinejoin="round">
+      <g stroke="currentColor" strokeLinecap="round" strokeLinejoin="round">
         <path d="M24 4.5v39M13.73 16.573v-9.99L24 16.573m0 14.5L13.73 41.417V27.01L24 16.573m0 0l10.27-9.99v9.99" />
         <path d="M13.73 31.396H9.44V16.573h29.12v14.823h-4.29" />
         <path d="M24 16.573L34.27 27.01v14.407L24 31.073" />
@@ -85,15 +86,15 @@ export function VscodeIcon({ size = '1em', ...rest }) {
       </mask>
       <g mask="url(#velu-vsc-mask)">
         <path
-          fill="#0065A9"
+          fill="currentColor"
           d="M96.461 10.796 75.857.876a6.23 6.23 0 0 0-7.107 1.207l-67.451 61.5a4.167 4.167 0 0 0 .004 6.162l5.51 5.009a4.167 4.167 0 0 0 5.32.236l81.228-61.62c2.725-2.067 6.639-.124 6.639 3.297v-.24a6.25 6.25 0 0 0-3.539-5.63Z"
         />
         <path
-          fill="#007ACC"
+          fill="currentColor"
           d="m96.461 89.204-20.604 9.92a6.229 6.229 0 0 1-7.107-1.207l-67.451-61.5a4.167 4.167 0 0 1 .004-6.162l5.51-5.009a4.167 4.167 0 0 1 5.32-.236l81.228 61.62c2.725 2.067 6.639.124 6.639-3.297v.24a6.25 6.25 0 0 1-3.539 5.63Z"
         />
         <path
-          fill="#1F9CF0"
+          fill="currentColor"
           d="M75.858 99.126a6.232 6.232 0 0 1-7.108-1.21c2.306 2.307 6.25.674 6.25-2.588V4.672c0-3.262-3.944-4.895-6.25-2.589a6.232 6.232 0 0 1 7.108-1.21l20.6 9.908A6.25 6.25 0 0 1 100 16.413v67.174a6.25 6.25 0 0 1-3.541 5.633l-20.601 9.906Z"
         />
       </g>

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/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
@@ -39,6 +39,7 @@ import {
   defaultMdxComponents,
   resolveIcon,
   Search,
+  pagefindSearch,
   Logo,
   SocialLinks,
   Tree,
@@ -719,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(
@@ -726,6 +728,22 @@ 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 ?? [];
@@ -1116,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 && (
@@ -1276,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)
@@ -1437,7 +1465,7 @@ 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