@veluai/velu 0.1.9 → 0.1.12

package/README.md

@@ -10,7 +10,7 @@ velu init my-docs
 velu dev my-docs
 ```
 
-Then open <http://localhost:5173>. Editing any `.mdx` page or `velu.json`
+Then open <http://localhost:8358>. Editing any `.mdx` page or `velu.json`
 reloads the browser automatically.
 
 > Requires **Node.js 18+**. Prefer not to install globally? Use

package/dist/cli.js

@@ -1,11 +1,93 @@
 #!/usr/bin/env node
-var $e=Object.defineProperty;var b=(e,t)=>()=>(e&&(t=e(e=0)),t);var M=(e,t)=>{for(var r in t)$e(e,r,{get:t[r],enumerable:!0})};var z={};M(z,{initProject:()=>Ae});import $ from"node:fs/promises";import _ from"node:path";import{fileURLToPath as _e}from"node:url";async function Ae(e,t){try{if((await $.readdir(e)).length>0)throw new Error(`Directory "${t}" already exists and is not empty. Choose a different name or remove the folder first.`)}catch(n){if(n.code!=="ENOENT")throw n}await $.mkdir(e,{recursive:!0}),await $.cp(Te,e,{recursive:!0});let r=_.join(e,"velu.json"),o=JSON.parse(await $.readFile(r,"utf-8"));o.name=t,await $.writeFile(r,JSON.stringify(o,null,2)+`
-`,"utf-8");let s=await B(e);console.log(`[velu] created ${t}/`);for(let n of s)console.log(`         ${n}`);console.log(""),console.log("Next steps:"),console.log(`  cd ${t}`),console.log("  velu dev")}async function B(e,t=e,r=[]){let o=await $.readdir(e,{withFileTypes:!0});for(let s of o){let n=_.join(e,s.name);s.isDirectory()?await B(n,t,r):r.push(_.relative(t,n).split(_.sep).join("/"))}return r.sort()}var Pe,Te,G=b(()=>{Pe=_.dirname(_e(import.meta.url)),Te=_.resolve(Pe,"..","templates","starter")});import{visit as Ee}from"unist-util-visit";import{toString as Le}from"mdast-util-to-string";import Fe from"github-slugger";import{valueToEstree as Re}from"estree-util-value-to-estree";function I(){return e=>{let t=new Fe,r=[];Ee(e,"heading",i=>{let l=Le(i);r.push({depth:i.depth,id:t.slug(l),label:l})});let o={children:[]},s=[{node:o,depth:0}];for(let i of r){for(;s.length>1&&s[s.length-1].depth>=i.depth;)s.pop();let l={id:i.id,label:i.label},a=s[s.length-1].node;a.children||(a.children=[]),a.children.push(l),s.push({node:l,depth:i.depth})}let n=o.children;e.children.unshift({type:"mdxjsEsm",value:"",data:{estree:{type:"Program",sourceType:"module",body:[{type:"ExportNamedDeclaration",specifiers:[],declaration:{type:"VariableDeclaration",kind:"const",declarations:[{type:"VariableDeclarator",id:{type:"Identifier",name:"toc"},init:Re(n)}]}}]}}})}}var D=b(()=>{});import Ie from"node:fs/promises";import q from"node:path";function N(e={},t){let r=e.colors?.primary??Ne;return{name:e.name??t??"docs",colors:{primary:r,light:e.colors?.light??r,dark:e.colors?.dark??r},favicon:e.favicon??null,font:{family:e.font?.family??Oe},navigation:e.navigation??null}}async function J(e){let t=q.join(e,"velu.json"),r;try{r=await Ie.readFile(t,"utf-8")}catch(s){throw s.code==="ENOENT"?new Error(`No velu.json found in ${e}. Run \`velu init <name>\` to scaffold one.`):s}let o;try{o=JSON.parse(r)}catch(s){throw new Error(`velu.json is not valid JSON: ${s.message}`)}return N(o,q.basename(e))}function H(e){let{colors:t,font:r}=e;return[":root:root {",`  --accent-color: ${t.light};`,`  --font-sans: "${r.family}", sans-serif;`,"}",':root:root[data-theme="dark"] {',`  --accent-color: ${t.dark};`,"}"].join(`
-`)}var Ne,Oe,Y=b(()=>{Ne="#dc143c",Oe="Google Sans Flex"});import Ue from"github-slugger";import je from"iso-639-1";function Ve(e){let t=String(e).toLowerCase();return je.getNativeName(t)||e}function F(e){return new Ue().slug(String(e??""))}function Me(e){let t=String(e).replace(/^\/+|\/+$/g,"").split("/").filter(Boolean);return t[t.length-1]==="index"&&t.pop(),"/"+t.join("/")}function W(e){let t={kind:"root",children:T(e??{})};return Q(t.children),t}function T(e){let t=Array.isArray(e.anchors)?e.anchors.map(qe):[];if(Array.isArray(e.products))return[...t,...e.products.map(Be)];if(Array.isArray(e.versions))return[...t,...e.versions.map(ze)];if(Array.isArray(e.languages))return[...t,...e.languages.map(Ge)];if(Array.isArray(e.tabs))return[...t,...e.tabs.map(De)];let r=[...t];return Array.isArray(e.groups)&&r.push(...e.groups.map(K)),Array.isArray(e.pages)&&r.push(...e.pages.map(X)),r}function Be(e){return{kind:"product",label:e.name??e.product,slug:F(e.product),icon:e.icon,color:e.color,default:!!e.default,children:T(e)}}function ze(e){return{kind:"version",label:e.version,slug:F(e.version),default:!!e.default,children:T(e)}}function Ge(e){let t=String(e.language);return{kind:"language",code:t,label:Ve(t),slug:F(t),default:!!e.default,children:T(e)}}function De(e){return{kind:"tab",label:e.tab,slug:F(e.tab),icon:e.icon,href:e.href,children:T(e)}}function qe(e){return{kind:"anchor",label:e.anchor,icon:e.icon,href:e.href,color:e.color}}function K(e){let t=(e.pages??[]).map(X);return e.root&&t.unshift({kind:"page",pagePath:e.root}),{kind:"group",label:e.group,icon:e.icon,expanded:!!e.expanded,root:e.root,children:t}}function X(e){return typeof e=="string"?{kind:"page",pagePath:e}:K(e)}function Q(e){for(let t of Ce){let r=e.filter(o=>o.kind===t);r.length&&!r.some(o=>o.default)&&(r[0].default=!0)}for(let t of e)t.children&&Q(t.children)}function Z(e){let t=[],r=(o,s,n)=>{if(o.kind==="page"){t.push({pagePath:o.pagePath,url:Je(o.pagePath,s),ctx:{...s},ancestors:n,node:o});return}let i=s;o.kind==="product"?i={...s,product:o.default?null:o.slug}:o.kind==="version"?i={...s,version:o.default?null:o.slug}:o.kind==="language"&&(i={...s,language:o.default?null:o.slug});let l=o.kind==="root"?n:[...n,o];for(let a of o.children??[])r(a,i,l)};return r(e,{product:null,version:null,language:null},[]),t}function Je(e,t){let r=[t.product,t.version,t.language].filter(Boolean),o=Me(e).split("/").filter(Boolean);return"/"+[...r,...o].join("/")}var Ce,O=b(()=>{Ce=["product","version","language"]});import He from"node:fs";import ee from"node:path";function te(e,t){let r=[],o=[],s=new Set;for(let n of Z(e)){if(s.has(n.url)){r.push(`duplicate URL "${n.url}" (page "${n.pagePath}") \u2014 keeping the first occurrence`);continue}s.add(n.url);let i=n.pagePath.replace(/^\/+|\/+$/g,""),l=ee.join(t,...i.split("/"))+".mdx",a=He.existsSync(l);a||r.push(`page "${n.pagePath}" \u2192 ${ee.relative(t,l)} not found`),o.push({pagePath:n.pagePath,url:n.url,fileAbsPath:l,exists:a})}return{pageEntries:o,warnings:r}}var oe=b(()=>{O()});import Ye from"node:fs";import re from"node:path";function ie(e){return{name:"velu-site",resolveId(t){return t===se?ne:null},load(t){return t!==ne?null:We(e)}}}function We(e){let t={};try{t=JSON.parse(Ye.readFileSync(re.join(e,"velu.json"),"utf-8"))}catch{}let r=W(t.navigation??{}),{pageEntries:o,warnings:s}=te(r,e);for(let a of s)console.warn(`[velu] nav: ${a}`);let n=[],i=[],l=0;for(let a of o)if(a.exists){let x=JSON.stringify(a.fileAbsPath.split(re.sep).join("/")),c=`__p${l++}`;n.push(`import * as ${c} from ${x};`),i.push(`  ${JSON.stringify(a.url)}: { Component: ${c}.default, frontmatter: ${c}.frontmatter, toc: ${c}.toc },`)}else i.push(`  ${JSON.stringify(a.url)}: { missing: true },`);return["// AUTO-GENERATED by vite-plugin-velu-site. Do not edit.",n.join(`
+var ut=Object.defineProperty;var b=(e,t)=>()=>(e&&(t=e(e=0)),t);var le=(e,t)=>{for(var o in t)ut(e,o,{get:t[o],enumerable:!0})};var Se={};le(Se,{initProject:()=>dt});import U from"node:fs/promises";import z from"node:path";import{fileURLToPath as ft}from"node:url";async function dt(e,t){try{if((await U.readdir(e)).length>0)throw new Error(`Directory "${t}" already exists and is not empty. Choose a different name or remove the folder first.`)}catch(s){if(s.code!=="ENOENT")throw s}await U.mkdir(e,{recursive:!0}),await U.cp(mt,e,{recursive:!0});let o=z.join(e,"velu.json"),n=JSON.parse(await U.readFile(o,"utf-8"));n.name=t,await U.writeFile(o,JSON.stringify(n,null,2)+`
+`,"utf-8");let r=await $e(e);console.log(`[velu] created ${t}/`);for(let s of r)console.log(`         ${s}`);console.log(""),console.log("Next steps:"),console.log(`  cd ${t}`),console.log("  velu dev")}async function $e(e,t=e,o=[]){let n=await U.readdir(e,{withFileTypes:!0});for(let r of n){let s=z.join(e,r.name);r.isDirectory()?await $e(s,t,o):o.push(z.relative(t,s).split(z.sep).join("/"))}return o.sort()}var pt,mt,je=b(()=>{pt=z.dirname(ft(import.meta.url)),mt=z.resolve(pt,"..","templates","starter")});import{visit as gt}from"unist-util-visit";import{toString as ht}from"mdast-util-to-string";import vt from"github-slugger";import{valueToEstree as yt}from"estree-util-value-to-estree";function q(){return e=>{let t=new vt,o=[];gt(e,"heading",i=>{let a=ht(i);o.push({depth:i.depth,id:t.slug(a),label:a})});let n={children:[]},r=[{node:n,depth:0}];for(let i of o){for(;r.length>1&&r[r.length-1].depth>=i.depth;)r.pop();let a={id:i.id,label:i.label},l=r[r.length-1].node;l.children||(l.children=[]),l.children.push(a),r.push({node:a,depth:i.depth})}let s=n.children;e.children.unshift({type:"mdxjsEsm",value:"",data:{estree:{type:"Program",sourceType:"module",body:[{type:"ExportNamedDeclaration",specifiers:[],declaration:{type:"VariableDeclaration",kind:"const",declarations:[{type:"VariableDeclarator",id:{type:"Identifier",name:"toc"},init:yt(s)}]}}]}}})}}var ce=b(()=>{});import xt from"node:fs/promises";import Ae from"node:path";function ue(e={},t){let o=e.colors?.primary??wt;return{name:e.name??t??"docs",colors:{primary:o,light:e.colors?.light??o,dark:e.colors?.dark??o},favicon:e.favicon??null,font:{family:e.font?.family??bt},navigation:e.navigation??null}}async function Pe(e){let t=Ae.join(e,"velu.json"),o;try{o=await xt.readFile(t,"utf-8")}catch(r){throw r.code==="ENOENT"?new Error(`No velu.json found in ${e}. Run \`velu init <name>\` to scaffold one.`):r}let n;try{n=JSON.parse(o)}catch(r){throw new Error(`velu.json is not valid JSON: ${r.message}`)}return ue(n,Ae.basename(e))}function Ce(e){let{colors:t,font:o}=e;return[":root:root {",`  --accent-color: ${t.light};`,`  --font-sans: "${o.family}", sans-serif;`,"}",':root:root[data-theme="dark"] {',`  --accent-color: ${t.dark};`,"}"].join(`
+`)}var wt,bt,Ee=b(()=>{wt="#dc143c",bt="Google Sans Flex"});import kt from"github-slugger";import $t from"iso-639-1";function jt(e){let t=String(e).toLowerCase();return $t.getNativeName(t)||e}function X(e){return new kt().slug(String(e??""))}function At(e){let t=String(e).replace(/^\/+|\/+$/g,"").split("/").filter(Boolean);return t[t.length-1]==="index"&&t.pop(),"/"+t.join("/")}function B(e){let t={kind:"root",children:D(e??{})};return Oe(t.children),t}function D(e){let t=Array.isArray(e.anchors)?e.anchors.map(_t):[];if(Array.isArray(e.products))return[...t,...e.products.map(Pt)];if(Array.isArray(e.versions))return[...t,...e.versions.map(Ct)];if(Array.isArray(e.languages))return[...t,...e.languages.map(Et)];if(Array.isArray(e.tabs))return[...t,...e.tabs.map(Tt)];let o=[...t];return Array.isArray(e.groups)&&o.push(...e.groups.map(Te)),Array.isArray(e.pages)&&o.push(...e.pages.map(_e)),o}function Pt(e){return{kind:"product",label:e.name??e.product,slug:X(e.product),icon:e.icon,color:e.color,default:!!e.default,children:D(e)}}function Ct(e){return{kind:"version",label:e.version,slug:X(e.version),default:!!e.default,children:D(e)}}function Et(e){let t=String(e.language);return{kind:"language",code:t,label:jt(t),slug:X(t),default:!!e.default,children:D(e)}}function Tt(e){return{kind:"tab",label:e.tab,slug:X(e.tab),icon:e.icon,href:e.href,children:D(e)}}function _t(e){return{kind:"anchor",label:e.anchor,icon:e.icon,href:e.href,color:e.color}}function Te(e){let t=(e.pages??[]).map(_e);return e.root&&t.unshift({kind:"page",pagePath:e.root}),{kind:"group",label:e.group,icon:e.icon,expanded:!!e.expanded,root:e.root,children:t}}function _e(e){return typeof e=="string"?{kind:"page",pagePath:e}:Te(e)}function Oe(e){for(let t of St){let o=e.filter(n=>n.kind===t);o.length&&!o.some(n=>n.default)&&(o[0].default=!0)}for(let t of e)t.children&&Oe(t.children)}function Le(e){let t=[],o=(n,r,s)=>{if(n.kind==="page"){t.push({pagePath:n.pagePath,url:Ot(n.pagePath,r),ctx:{...r},ancestors:s,node:n});return}let i=r;n.kind==="product"?i={...r,product:n.default?null:n.slug}:n.kind==="version"?i={...r,version:n.default?null:n.slug}:n.kind==="language"&&(i={...r,language:n.default?null:n.slug});let a=n.kind==="root"?s:[...s,n];for(let l of n.children??[])o(l,i,a)};return o(e,{product:null,version:null,language:null},[]),t}function Ot(e,t){let o=[t.product,t.version,t.language].filter(Boolean),n=At(e).split("/").filter(Boolean);return"/"+[...o,...n].join("/")}var St,Y=b(()=>{St=["product","version","language"]});import Lt from"node:fs";import Ne from"node:path";function V(e,t){let o=[],n=[],r=new Set;for(let s of Le(e)){if(r.has(s.url)){o.push(`duplicate URL "${s.url}" (page "${s.pagePath}") \u2014 keeping the first occurrence`);continue}r.add(s.url);let i=s.pagePath.replace(/^\/+|\/+$/g,""),a=Ne.join(t,...i.split("/"))+".mdx",l=Lt.existsSync(a);l||o.push(`page "${s.pagePath}" \u2192 ${Ne.relative(t,a)} not found`),n.push({pagePath:s.pagePath,url:s.url,fileAbsPath:a,exists:l})}return{pageEntries:n,warnings:o}}var Q=b(()=>{Y()});import Nt from"node:fs";import ee from"node:path";function Re(e){return{name:"velu-site",resolveId(t){return t===Ie?Fe:null},load(t){return t!==Fe?null:Ft(e)}}}function Ft(e){let t={};try{t=JSON.parse(Nt.readFileSync(ee.join(e,"velu.json"),"utf-8"))}catch{}let o=B(t.navigation??{}),{pageEntries:n,warnings:r}=V(o,e);for(let l of r)console.warn(`[velu] nav: ${l}`);let s=[],i=[],a=0;for(let l of n)if(l.exists){let u=JSON.stringify(l.fileAbsPath.split(ee.sep).join("/")),c=JSON.stringify(ee.relative(e,l.fileAbsPath).split(ee.sep).join("/")),f=`__p${a++}`;s.push(`import * as ${f} from ${u};`),i.push(`  ${JSON.stringify(l.url)}: { Component: ${f}.default, frontmatter: ${f}.frontmatter, toc: ${f}.toc, relPath: ${c} },`)}else i.push(`  ${JSON.stringify(l.url)}: { missing: true },`);return["// AUTO-GENERATED by vite-plugin-velu-site. Do not edit.",s.join(`
 `),"","export const pages = {",i.join(`
-`),"};",`export const navigation = ${JSON.stringify(r)};`,""].join(`
-`)}var se,ne,ae=b(()=>{O();oe();se="virtual:velu-site",ne="\0"+se});var me={};M(me,{startDevServer:()=>wt});import le from"node:fs/promises";import ce from"node:fs";import Ke from"node:http";import{spawn as Xe}from"node:child_process";import h from"node:path";import{fileURLToPath as Qe}from"node:url";import{createRequire as Ze}from"node:module";import et from"chokidar";import tt from"express";import ot from"@tailwindcss/vite";import rt from"@vitejs/plugin-react";import nt from"@mdx-js/rollup";import st from"remark-frontmatter";import it from"remark-mdx-frontmatter";import at from"remark-gfm";import lt from"rehype-slug";import{createServer as ct,searchForWorkspaceRoot as ut}from"vite";function gt(e){return`<link rel="stylesheet" href="${`https://fonts.googleapis.com/css2?family=${encodeURIComponent(e).replace(/%20/g,"+")}:wght@300;400;500;600;700&display=swap`}" />`}async function fe(e){try{return await J(e)}catch(t){return console.warn(`[velu] ${t.message} Using defaults.`),N({},h.basename(e))}}async function pe(e,t){let r=await e.moduleGraph.getModuleByUrl(t,!0),o=new Map,s=new Set;async function n(i){if(!(!i||s.has(i.url))){if(s.add(i.url),i.id&&pt.test(i.id)){let l=i.url.includes("?")?"&":"?",a=await e.transformRequest(`${i.url}${l}direct`);a?.code&&o.set(i.url,a.code)}for(let l of i.importedModules)await n(l)}}return await n(r),[...o.values()].join(`
-`)}function yt(e){let t=()=>{process.stdout.isTTY&&!process.env.VELU_NO_BELL&&process.stdout.write("\x07")},r=process.stdout.isTTY,o=c=>r&&process.stdout.write(`\x1B]${c}\x1B\\`),s=()=>{o("0;\u23F3 Velu \u2014 starting\u2026"),o("9;4;3;0")},n=c=>{o(`0;Velu \xB7 ${c.replace(/^https?:\/\//,"")}`),o("9;4;0;0")};if(r&&process.once("exit",()=>o("9;4;0;0")),s(),!e)return console.log("Starting Velu\u2026"),{ready:c=>{console.log(`Velu ready \u2192 ${c}`),n(c),t()}};let i="\x1B[38;2;220;20;60m",l="\x1B[0m";console.log("");for(let c of ht)console.log(`${i}${c}${l}`);console.log("");let a=null;try{a=Xe(process.execPath,["-e",vt],{stdio:["ignore","inherit","ignore"]}),a.on("error",()=>{})}catch{}let x=()=>{if(a){try{a.kill()}catch{}a=null}};return process.once("exit",x),{ready:c=>{x(),process.stdout.write("\x1B[2K\r"),console.log(`  \x1B[32m\u2713${l}  Velu ready  \u2192  \x1B[36m${c}${l}`),n(c),t()}}}async function wt(e){let t=!!process.env.VELU_PROFILE,r=performance.now(),o=(g,u)=>t&&console.log(`[velu-profile] ${g}: ${(performance.now()-u).toFixed(0)}ms`),s=yt(!!process.stdout.isTTY&&!t),n=await fe(e),i=e;try{i=ce.realpathSync(e)}catch{}let a=Ze(import.meta.url).resolve("@mdx-js/react"),x=h.resolve(A,"runtime","velu-ui"),c=ce.existsSync(x)?x:h.resolve(A,"..","velu-ui","src"),ye=[{find:"@mdx-js/react",replacement:a},{find:/^velu-ui$/,replacement:h.join(c,"index.js")},{find:/^velu-ui\//,replacement:c+"/"}],j=Number(process.env.PORT)||5173,E=tt(),C=Ke.createServer(E),p=await ct({root:A,appType:"custom",logLevel:t?"info":"warn",plugins:[ie(e),nt({remarkPlugins:[st,it,at,I],rehypePlugins:[lt],providerImportSource:"@mdx-js/react"}),rt(),ot()],cacheDir:h.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"],esbuildOptions:{loader:{".mdx":"jsx"}}},resolve:{alias:ye,dedupe:["react","react-dom","@mdx-js/react"]},server:{middlewareMode:!0,fs:{allow:[ut(A),e,i]},hmr:{server:C}}});o("vite server created",r),E.use(p.middlewares),E.get(ue,async(g,u,v)=>{if(!n.favicon)return u.status(404).end();let f=h.resolve(e,n.favicon.replace(/^\//,""));u.sendFile(f,y=>{y&&u.status(404).end()})}),E.use("*",async(g,u,v)=>{let f=g.originalUrl,y=performance.now();try{let d=performance.now(),w=await le.readFile(de,"utf-8");w=await p.transformIndexHtml(f,w),o(`transformIndexHtml ${f}`,d);let k="/src/runtime/server-entry.jsx";d=performance.now();let{render:L}=await p.ssrLoadModule(k);o(`ssrLoadModule ${f} (1st req includes dep pre-bundle)`,d),d=performance.now();let m=await L(f);o(`render ${f}`,d),d=performance.now();let P=await pe(p,k);o(`collectSsrCss ${f}`,d);let R=P?`<style data-velu-ssr>${P}</style>`:"",we=`<style data-velu-config>
-${H(n)}
-</style>`,xe=dt.has(n.font.family)?"":gt(n.font.family),be=n.favicon?`<link rel="icon" href="${ue}" />`:"",Se=[R,we,xe,be].filter(Boolean).join(`
-`),ke=w.replace("<!--app-title-->",mt(n.name)).replace("<!--app-head-->",Se).replace("<!--app-html-->",m);u.status(200).set({"Content-Type":"text/html"}).end(ke),o(`TOTAL ${f}`,y)}catch(d){p.ssrFixStacktrace(d),v(d)}}),et.watch(e,{ignoreInitial:!0,ignored:/(^|[\\/])(node_modules|\.git|\.velu)([\\/]|$)/,awaitWriteFinish:{stabilityThreshold:100,pollInterval:20}}).on("all",async(g,u)=>{console.log(`[velu-cli] content ${g}: ${h.relative(e,u)}`);let v=h.basename(u)==="velu.json",f=u.endsWith(".mdx"),y=v||f&&(g==="add"||g==="unlink");if(v&&(n=await fe(e)),y)p.moduleGraph.invalidateAll();else if(f){let d=u.split(h.sep).join("/"),w=p.moduleGraph.getModulesByFile(d);if(w)for(let k of w)p.moduleGraph.invalidateModule(k)}p.ws.send({type:"full-reload"})});async function V(g){let u=new Set,v=12,f=0,y=[],d=()=>f<v?(f+=1,Promise.resolve()):new Promise(m=>y.push(m)).then(()=>{f+=1}),w=()=>{f-=1,y.shift()?.()},k=m=>/[\\/]\.velu[\\/]vite-cache[\\/]|[\\/]deps[\\/]/.test(m)||/[\\/]node_modules[\\/]/.test(m)&&!/velu-ui/.test(m);async function L(m){if(!(!m||u.has(m)||k(m))){u.add(m);try{await d();try{await p.transformRequest(m,{ssr:!1})}finally{w()}let P=await p.moduleGraph.getModuleByUrl(m,!1);P?.importedModules?.size&&await Promise.all([...P.importedModules].map(R=>L(R.url)))}catch{}}}return await L(g),u.size}C.listen(j,async()=>{let g=performance.now(),u=0;try{let{render:v}=await p.ssrLoadModule("/src/runtime/server-entry.jsx");await V("/src/runtime/client-entry.jsx"),typeof p.waitForRequestsIdle=="function"&&await p.waitForRequestsIdle();let[f]=await Promise.all([V("/src/runtime/client-entry.jsx"),v("/"),p.transformIndexHtml("/",await le.readFile(de,"utf-8")),pe(p,"/src/runtime/server-entry.jsx")]);u=f}catch(v){t&&console.log("[velu-profile] warmup error:",v?.message)}o(`cold-start warm-up (${u} client modules)`,g),s.ready(`http://localhost:${j}`)})}var ft,pt,dt,ue,mt,A,de,ht,vt,ge=b(()=>{D();Y();ae();ft=h.dirname(Qe(import.meta.url)),pt=/\.(css|less|sass|scss|styl|stylus|pcss|postcss)(\?|$)/,dt=new Set(["Google Sans Flex","Google Sans Code","Outfit"]),ue="/@velu-favicon",mt=e=>String(e).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");A=h.resolve(ft,".."),de=h.resolve(A,"src","template.html"),ht=[" _    __     __","| |  / /__  / /_  __","| | / / _ \\/ / / / /","| |/ /  __/ / /_/ /","|___/\\___/_/\\__,_/"],vt="const F=['\u280B','\u2819','\u2839','\u2838','\u283C','\u2834','\u2826','\u2827','\u2807','\u280F'],M=['Starting Velu','Setting up your preview','Preparing your docs','Warming things up','Almost ready'];let f=0,m=0;const t=Date.now();const C='\\x1b[38;2;220;20;60m',R='\\x1b[0m',D='\\x1b[2m';const d=()=>{const s=(Date.now()-t)/1000|0;process.stdout.write('\\x1b[2K\\r  '+C+F[f]+R+'  '+M[m]+'\\u2026  '+D+s+'s'+R);f=(f+1)%F.length;};d();setInterval(d,90);setInterval(()=>{if(m<M.length-1)m++;},4000);"});import he from"node:path";import S from"node:process";import{readFileSync as xt}from"node:fs";var[,,ve,U]=S.argv;function bt(){try{return JSON.parse(xt(new URL("../package.json",import.meta.url),"utf8")).version}catch{return"unknown"}}async function St(){switch(ve){case"--version":case"-v":case"version":{console.log(bt());break}case"init":{U||(console.error("Usage: velu init <project-name>"),S.exit(1));let e=U,t=he.resolve(S.cwd(),e),{initProject:r}=await Promise.resolve().then(()=>(G(),z));await r(t,e);break}case"dev":{let e=he.resolve(S.cwd(),U??"."),{startDevServer:t}=await Promise.resolve().then(()=>(ge(),me));await t(e);break}default:console.log("Usage:"),console.log("  velu init <project-name>   scaffold a new docs project"),console.log("  velu dev [dir]             start the dev preview server"),S.exit(ve?1:0)}}St().catch(e=>{console.error(S.env.VELU_DEBUG?e:`Error: ${e.message}`),S.exit(1)});
+`),"};",`export const navigation = ${JSON.stringify(o)};`,""].join(`
+`)}var Ie,Fe,Me=b(()=>{Y();Q();Ie="virtual:velu-site",Fe="\0"+Ie});function h(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 It(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 o=Array.from({length:t.length+1},(r,s)=>s),n=new Array(t.length+1);for(let r=1;r<=e.length;r++){n[0]=r;for(let s=1;s<=t.length;s++){let i=e[r-1]===t[s-1]?0:1;n[s]=Math.min(n[s-1]+1,o[s]+1,o[s-1]+i)}[o,n]=[n,o]}return o[t.length]}function te(e,t=[]){if(!e)return null;let o=String(e).toLowerCase(),n=null,r=1/0;for(let i of t){let a=It(o,String(i).toLowerCase());a<r&&(r=a,n=i)}let s=Math.min(3,Math.max(2,Math.floor(o.length/4)));return r<=s?n:null}function Rt(e,t){return e==="warning"?C(t,$.yellow,"\u26A0"):e==="info"?C(t,$.cyan,"\u2139"):C(t,$.red,"\u2716")}function pe(e,{color:t=!1}={}){let o=fe[e.category]||e.category,n=e.line?`${e.line}${e.column?`:${e.column}`:""}`:"",r=e.file?`${e.file}${n?`:${n}`:""}`:n,s=[];if(s.push(`${Rt(e.severity,t)} ${C(t,$.bold,o)}`+(r?`  ${C(t,$.dim,r)}`:"")),e.title&&s.push(`  ${e.title}`),e.detail&&e.detail!==e.title&&s.push(`  ${C(t,$.dim,e.detail)}`),e.frame)for(let i of String(e.frame).split(`
+`))s.push(`  ${i}`);return e.suggestion&&s.push(`  ${C(t,$.cyan,`Did you mean <${e.suggestion}>?`)}`),e.hint&&s.push(`  ${C(t,$.dim,`\u2192 ${e.hint}`)}`),s.join(`
+`)}function ne(e,{color:t=!1}={}){if(!e.length)return C(t,$.cyan,"\u2713 No issues found.");let o=new Map;for(let a of e){let l=a.file||"velu.json";o.has(l)||o.set(l,[]),o.get(l).push(a)}let n=[];for(let[a,l]of o){n.push(C(t,$.bold,a));for(let u of l)n.push(pe({...u,file:null},{color:t}).replace(/^/gm,"  "));n.push("")}let r=e.filter(a=>a.severity!=="warning"&&a.severity!=="info").length,s=e.length-r,i=`${r} error${r===1?"":"s"}`+(s?`, ${s} warning${s===1?"":"s"}`:"");return n.push(C(t,r?$.red:$.yellow,i)),n.join(`
+`)}var fe,$,C,F=b(()=>{fe={"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"},C=(e,t,o)=>e?`${t}${o}${$.reset}`:o});function Mt(e){let t=e,o=0;for(;t&&t.cause&&o<3&&!(t.loc||t.line||/`[^`]+` to be defined/.test(t.message||""));)t=t.cause,o+=1;return t||e}function me(e,t){if(!e)return null;let o=Ue(e).replace(/[?#].*$/,""),n=t?Ue(t).replace(/\/+$/,""):"";return n&&o.toLowerCase().startsWith(n.toLowerCase())?o.slice(n.length).replace(/^\/+/,""):!/^([a-zA-Z]:\/|\/)/.test(o)&&!/node_modules/.test(o)?o:null}function Ut(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 zt(e){let t=/\((\d+):(\d+)(?:-\d+:\d+)?\)\s*$/.exec(String(e||""));return t?{line:Number(t[1]),column:Number(t[2])}:null}function Bt(e){return String(e||"").replace(/\s*\(\d+:\d+(?:-\d+:\d+)?\)\s*$/,"").trim()}function Gt(e,t){if(!e||!t)return null;let o=String(e);return/node_modules|[\\/]vite[\\/]|@veluai[\\/]/.test(o)?null:o}function H(e,t={}){let{projectDir:o="",knownComponents:n=[],file:r=null}=t,s=null;for(let E=e,A=0;E&&A<6;E=E.cause,A+=1)if(E.veluIssue){s=E.veluIssue;break}if(s)return h({...s,file:s.file||r});let i=Mt(e)||{},a=i.message||String(e||""),l=/Expected component `([^`]+)` to be defined/.exec(a);if(l){let E=l[1],A=/referenced in your code at `(\d+):(\d+)/.exec(a),G=/\bin `([^`]+)`/.exec(a),v=G?me(G[1],o):null;return h({category:"unknown-component",file:v||r,line:A?Number(A[1]):null,column:A?Number(A[2]):null,title:`<${E}> is not a built-in component`,detail:"",hint:"Components are built in \u2014 check the spelling and capitalization (you don\u2019t import them).",suggestion:te(E,n)})}let u=i.loc||(i.line!=null?{line:i.line,column:i.column,file:i.file}:null)||zt(i.reason||a),c=i.id||u&&u.file||i.file||null,f=me(c,o)||r,_=!!f&&me(c,o)!=null,d=Gt(i.frame,_||!!r),j=Ut(Bt(i.reason||a)),m=Vt.test(a),N=i.source==="remark-frontmatter"||/\byaml\b|frontmatter/i.test(a)||u&&u.line===1&&/unexpected|expected/i.test(a)&&/---/.test(a);return u||m||d&&_?h({category:N?"frontmatter":"mdx-syntax",file:f,line:u?u.line:null,column:u?u.column:null,frame:d,title:j||(N?"Invalid frontmatter":"MDX syntax error"),detail:"",hint:N?"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(a)?h({category:"invalid-props",file:f,title:"A component received an invalid value",detail:j,hint:"Check the props/options you passed to a component on this page."}):h({category:"render-crash",file:f,title:"This page failed to render",detail:j,hint:"Set VELU_DEBUG=1 for the full stack trace."})}var Ue,Vt,de=b(()=>{F();Ue=e=>String(e).replace(/\\/g,"/");Vt=/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 Jt(e){let t=fe[e.category]||e.category,o=e.file?`${e.file}${e.line?`:${e.line}${e.column?`:${e.column}`:""}`:""}`:"",n=[];return n.push('<div class="velu-err-card">'),n.push('<div class="velu-err-head">'),n.push(`<span class="velu-err-pill">${O(t)}</span>`),n.push("</div>"),e.title&&n.push(`<div class="velu-err-title">${O(e.title)}</div>`),o&&n.push(`<a class="velu-err-loc" title="${O(o)}">${O(o)}</a>`),e.detail&&n.push(`<div class="velu-err-detail">${O(e.detail)}</div>`),e.frame&&n.push(`<pre class="velu-err-frame">${O(e.frame)}</pre>`),e.suggestion&&n.push(`<div class="velu-err-suggest">Did you mean <code>&lt;${O(e.suggestion)}&gt;</code>?</div>`),e.hint&&n.push(`<div class="velu-err-hint">${O(e.hint)}</div>`),n.push("</div>"),n.join("")}function ge(e,t={}){let o=Array.isArray(e)?e:[e],n=t.title||(o.length>1?`${o.length} problems to fix`:"There\u2019s a problem to fix"),r=o.map(Jt).join(`
+`);return`<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Velu \u2014 error</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    min-height: 100vh;
+    background: #f7f7f8;
+    color: #111827;
+    font: 15px/1.55 system-ui, -apple-system, Segoe UI, sans-serif;
+    padding: 6vh 5vw;
+  }
+  @media (prefers-color-scheme: dark) {
+    body { background: #0c0d10; color: #e7e7ea; }
+    .velu-err-card { background: rgba(239,68,68,0.08); }
+    .velu-err-frame { background: rgba(255,255,255,0.05); color: #e7e7ea; }
+  }
+  .velu-err-wrap { max-width: 820px; margin: 0 auto; }
+  .velu-err-brand { font-weight: 700; letter-spacing: -0.02em; opacity: 0.7; margin-bottom: 0.4rem; }
+  .velu-err-h { font-size: 1.6rem; font-weight: 700; margin: 0 0 1.4rem; letter-spacing: -0.02em; }
+  .velu-err-card {
+    border: 1px solid #ef4444;
+    border-radius: 10px;
+    background: rgba(239,68,68,0.06);
+    padding: 1rem 1.1rem;
+    margin: 0 0 1rem;
+  }
+  .velu-err-head { display: flex; gap: 0.6rem; align-items: center; flex-wrap: wrap; }
+  .velu-err-pill {
+    font: 600 11px/1 ui-monospace, monospace;
+    text-transform: uppercase; letter-spacing: 0.06em;
+    color: #ef4444; border: 1px solid #ef4444; border-radius: 999px;
+    padding: 4px 9px; white-space: nowrap;
+  }
+  .velu-err-loc {
+    display: inline-block;
+    margin-top: 0.7rem;
+    font: 600 15px/1 ui-monospace, SFMono-Regular, Menlo, monospace;
+    color: #ef4444;
+    background: rgba(239,68,68,0.12);
+    border: 1px solid rgba(239,68,68,0.4);
+    border-radius: 7px;
+    padding: 7px 11px;
+    letter-spacing: 0.01em;
+  }
+  .velu-err-title { margin-top: 0.6rem; font-weight: 600; font-size: 1.05rem; }
+  .velu-err-detail { margin-top: 0.25rem; opacity: 0.7; }
+  .velu-err-frame {
+    margin: 0.75rem 0 0; padding: 0.75rem 0.9rem; overflow: auto;
+    background: rgba(0,0,0,0.05); border-radius: 6px;
+    font: 12.5px/1.5 ui-monospace, monospace;
+  }
+  .velu-err-suggest { margin-top: 0.75rem; }
+  .velu-err-suggest code, .velu-err-frame code { color: #ef4444; font-weight: 600; }
+  .velu-err-hint { margin-top: 0.6rem; opacity: 0.6; font-size: 0.92rem; }
+  .velu-err-foot { margin-top: 1.6rem; opacity: 0.5; font-size: 0.85rem; }
+</style>
+</head>
+<body>
+  <div class="velu-err-wrap">
+    <div class="velu-err-brand">velu</div>
+    <h1 class="velu-err-h">${O(n)}</h1>
+    ${r}
+    <div class="velu-err-foot">Fix the file and save \u2014 this page reloads automatically.</div>
+  </div>
+</body>
+</html>`}var O,ze=b(()=>{F();O=e=>String(e??"").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")});var I,he=b(()=>{I=["Callout","Card","CardGroup","Accordion","AccordionGroup","Columns","Field","Prompt","Steps","Step","Tree","Folder","File","Image","CodeBlock","CodeGroup","MethodBadge","ApiPath","TryItBar","ApiField","ApiClient","ApiSidebar"]});import ve from"node:fs";import oe from"node:path";import{fileURLToPath as qt}from"node:url";import Dt from"iso-639-1";function W(e,t){if(!t)return null;let o=e.indexOf(`"${t}"`);return o===-1?null:e.slice(0,o).split(`
+`).length}function Wt(e,t){return t==null||t<0?null:e.slice(0,t).split(`
+`).length}function Be(e,t){if(!t)return null;let o=e.indexOf(`"${t}"`);return o===-1?null:e.slice(0,o).split(`
+`).length}function Kt(e,t,o){let n=[];return a(e,t,"",null),n;function r(l){if(l&&l.$ref){let u=l.$ref.replace(/^#\//,"").split("/"),c=o;for(let f of u)c=c?.[f];return c||{}}return l}function s(l){return Array.isArray(l)?"array":l===null?"null":typeof l}function i(l,u){let c=n.length;a(l,u,"",null,!0);let f=n.length===c;return f||(n.length=c),f}function a(l,u,c,f,_){let d=r(u);if(d){if(d.oneOf){d.oneOf.some(m=>i(l,m))||n.push({path:c,key:f,message:"value does not match any allowed shape"});return}if(d.type&&s(l)!==d.type){n.push({path:c,key:f,message:`expected ${d.type}, got ${s(l)}`});return}if(d.type==="string"&&d.minLength!=null&&l.length<d.minLength&&n.push({path:c,key:f,message:"must not be empty"}),d.type==="object"&&s(l)==="object"){for(let m of d.required||[])m in l||n.push({path:c?`${c}.${m}`:m,key:m,message:`missing required "${m}"`});let j=d.properties||{};if(d.additionalProperties===!1)for(let m of Object.keys(l))m in j||n.push({path:c?`${c}.${m}`:m,key:m,message:`unknown field "${m}"`});for(let[m,N]of Object.entries(j))m in l&&a(l[m],N,c?`${c}.${m}`:m,m,_)}d.type==="array"&&Array.isArray(l)&&d.items&&l.forEach((j,m)=>a(j,d.items,`${c}[${m}]`,f,_))}}}function Zt(e){if(typeof e!="string")return!1;let t=e.trim();return/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(t)||/^(rgb|rgba|hsl|hsla|color|oklch|lab|lch)\(/i.test(t)||/^[a-z][a-z0-9-]*$/i.test(t)}function re(e){let t=[],o=oe.join(e,"velu.json"),n;try{n=ve.readFileSync(o,"utf-8")}catch(i){return i.code==="ENOENT"?t.push(h({category:"config-json",file:"velu.json",title:"No velu.json found",hint:"Run `velu init <name>` to scaffold a project."})):t.push(h({category:"config-json",file:"velu.json",title:"Could not read velu.json"})),t}let r;try{r=JSON.parse(n)}catch(i){let a=/position (\d+)/.exec(i.message||""),l=a?Wt(n,Number(a[1])):null;return t.push(h({category:"config-json",file:"velu.json",line:l,title:"velu.json is not valid JSON",detail:String(i.message||"").replace(/\s+in JSON.*$/,""),hint:"Check for a trailing comma, a missing quote, or an unclosed brace."})),t}let s=null;try{s=JSON.parse(ve.readFileSync(Ht,"utf-8"))}catch{}if(s)for(let i of Kt(r,s,s)){let a=/^unknown field/.test(i.message);t.push(h({category:"config-schema",severity:a?"warning":"error",file:"velu.json",line:W(n,i.key),title:i.path?`${i.path}: ${i.message}`:i.message,hint:a?"Remove it, or check the spelling against the velu.json schema.":""}))}for(let i of["primary","light","dark"]){let a=r.colors?.[i];a!=null&&!Zt(a)&&t.push(h({category:"config-schema",severity:"warning",file:"velu.json",line:W(n,i),title:`colors.${i}: "${a}" doesn\u2019t look like a CSS color`,hint:"Use a hex value like #dc143c, an rgb()/hsl() function, or a CSS color name."}))}if(typeof r.favicon=="string"&&r.favicon.trim()){let i=oe.resolve(e,r.favicon.replace(/^\/+/,""));ve.existsSync(i)||t.push(h({category:"config-asset",file:"velu.json",line:W(n,"favicon"),title:`favicon not found: ${r.favicon}`,hint:"The path is relative to the project root."}))}if(r.navigation&&typeof r.navigation=="object"){let i;try{i=B(r.navigation)}catch(a){t.push(h({category:"config-nav",file:"velu.json",line:W(n,"navigation"),title:"navigation could not be processed",detail:String(a.message||"")})),i=null}if(i){let{pageEntries:a,warnings:l}=V(i,e);for(let u of l){let c=/not found$/.test(u),f=/page "([^"]+)"/.exec(u),_=f?Be(n,f[1]):null;t.push(h({category:"config-nav",severity:c?"error":"warning",file:"velu.json",line:_,title:u,hint:c?"Create the .mdx file, or remove the page from navigation.":""}))}Xt(i,n,t)}}return t}function Xt(e,t,o){let n=new Set,r=s=>{if(!(!s||typeof s!="object")){if(s.language&&!n.has(s.language)){n.add(s.language);let i=String(s.language).toLowerCase();Dt.validate(i)||o.push(h({category:"config-nav",severity:"warning",file:"velu.json",line:Be(t,s.language)||W(t,"language"),title:`"${s.language}" is not a valid ISO 639-1 language code`,hint:'Use a two-letter code like "en", "fr", or "ja".'}))}for(let i of Object.values(s))Array.isArray(i)?i.forEach(r):i&&typeof i=="object"&&r(i)}};r(e)}var Yt,Ht,ye=b(()=>{F();Y();Q();Yt=oe.dirname(qt(import.meta.url)),Ht=oe.resolve(Yt,"..","..","schema","velu.schema.json")});import Qt from"node:fs/promises";import en from"node:fs";import R from"node:path";import{fileURLToPath as tn,pathToFileURL as nn}from"node:url";import{compile as on}from"@mdx-js/mdx";import rn from"remark-frontmatter";import sn from"remark-mdx-frontmatter";import an from"remark-gfm";import ln from"rehype-slug";import{visit as cn}from"unist-util-visit";function xe(){if(ie)return ie;let e=R.dirname(tn(import.meta.url)),t=[R.resolve(e,"..","runtime","velu-ui"),R.resolve(e,"..","..","runtime","velu-ui"),R.resolve(e,"..","..","..","velu-ui","src")],o=null;for(let n of t){let r=R.join(n,"lib","component-schemas.js");if(en.existsSync(r)){o=r;break}}return ie=o?import(nn(o).href).then(n=>n.validateProps).catch(()=>null):Promise.resolve(null),ie}function un(e){let t={};for(let o of e.attributes||[])o.type==="mdxJsxAttribute"&&(o.value==null?t[o.name]=!0:typeof o.value=="string"&&(t[o.name]=o.value));return t}function fn(e,t){return()=>o=>{cn(o,n=>{if((n.type==="mdxJsxFlowElement"||n.type==="mdxJsxTextElement")&&typeof n.name=="string"&&/^[A-Z]/.test(n.name)&&!n.name.includes(".")&&e.push({name:n.name,props:un(n),line:n.position?.start?.line??null,column:n.position?.start?.column??null}),n.type==="mdxjsEsm"&&typeof n.value=="string")for(let r of n.value.matchAll(/\b([A-Z][A-Za-z0-9_]*)\b/g))t.add(r[1])})}}async function pn(e,t){let o=[],n;try{n=await Qt.readFile(t.fileAbsPath,"utf-8")}catch{return o}let r=R.relative(e,t.fileAbsPath).split(R.sep).join("/"),s=[],i=new Set;try{await on({value:n,path:t.fileAbsPath},{remarkPlugins:[rn,sn,an,q,fn(s,i)],rehypePlugins:[ln],providerImportSource:"@mdx-js/react"})}catch(c){return o.push(H(c,{projectDir:e,knownComponents:I,file:r})),o}let a=new Set(I),l=await xe(),u=new Set;for(let c of s)if(!i.has(c.name)){if(!a.has(c.name)){if(u.has(c.name))continue;u.add(c.name),o.push(h({category:"unknown-component",file:r,line:c.line,column:c.column,title:`<${c.name}> is not a built-in component`,hint:"Components are built in \u2014 check the spelling and capitalization (you don\u2019t import them).",suggestion:te(c.name,I)}));continue}if(l){let f=l(c.name,c.props,{checkRequired:!1});f&&o.push(h({...f,file:r,line:c.line,column:c.column}))}}return o}async function Ve(e,t){let o=t.filter(a=>a.exists),n=[],r=8,s=0;async function i(){for(;s<o.length;){let a=o[s++],l=await pn(e,a);for(let u of l)n.push(u)}}return await Promise.all(Array.from({length:Math.min(r,o.length)},i)),n}var ie,we=b(()=>{ce();F();de();he()});import{visit as mn}from"unist-util-visit";function dn(e,t){let o=Ge(e).replace(/[?#].*$/,""),n=Ge(t).replace(/\/+$/,"");return n&&o.toLowerCase().startsWith(n.toLowerCase())?o.slice(n.length).replace(/^\/+/,""):null}function Je(e,t){return()=>(o,n)=>{typeof e=="function"&&mn(o,r=>{if(r.type!=="mdxJsxFlowElement"&&r.type!=="mdxJsxTextElement"||typeof r.name!="string"||!/^[A-Z]/.test(r.name)||r.name.includes("."))return;let s={};for(let a of r.attributes||[])a.type==="mdxJsxAttribute"&&(a.value==null?s[a.name]=!0:typeof a.value=="string"&&(s[a.name]=a.value));let i=e(r.name,s,{checkRequired:!1});if(i){let a=new Error(i.title);throw a.veluIssue={...i,file:dn(n?.path,t),line:r.position?.start?.line??null,column:r.position?.start?.column??null},a.loc={line:a.veluIssue.line,column:a.veluIssue.column},a}})}}var Ge,qe=b(()=>{Ge=e=>String(e||"").replace(/\\/g,"/")});var Qe={};le(Qe,{startDevServer:()=>Mn});import De from"node:fs/promises";import Ye from"node:fs";import gn from"node:http";import{spawn as hn}from"node:child_process";import S from"node:path";import{fileURLToPath as vn}from"node:url";import{createRequire as yn}from"node:module";import xn from"chokidar";import wn from"express";import bn from"@tailwindcss/vite";import kn from"@vitejs/plugin-react";import $n from"@mdx-js/rollup";import Sn from"remark-frontmatter";import jn from"remark-mdx-frontmatter";import An from"remark-gfm";import Pn from"rehype-slug";import{createServer as Cn,searchForWorkspaceRoot as En}from"vite";function Nn(e){return`<link rel="stylesheet" href="${`https://fonts.googleapis.com/css2?family=${encodeURIComponent(e).replace(/%20/g,"+")}:wght@300;400;500;600;700&display=swap`}" />`}function We(e,t){let o=pe(e,{color:!!process.stderr.isTTY});console.error(`
+`+o+`
+`),process.env.VELU_DEBUG&&t&&console.error(t)}async function Ke(e){try{return await Pe(e)}catch{return ue({},S.basename(e))}}async function Ze(e,t){let o=await e.moduleGraph.getModuleByUrl(t,!0),n=new Map,r=new Set;async function s(i){if(!(!i||r.has(i.url))){if(r.add(i.url),i.id&&_n.test(i.id)){let a=i.url.includes("?")?"&":"?",l=await e.transformRequest(`${i.url}${a}direct`);l?.code&&n.set(i.url,l.code)}for(let a of i.importedModules)await s(a)}}return await s(o),[...n.values()].join(`
+`)}function Rn(e,t){let o=()=>{process.stdout.isTTY&&!process.env.VELU_NO_BELL&&process.stdout.write("\x07")},n=process.stdout.isTTY,r=f=>n&&process.stdout.write(`\x1B]${f}\x1B\\`),s=()=>{r(`0;\u23F3 ${t}`),r("9;4;3;0")},i=()=>{r(`0;${t}`),r("9;4;0;0")};if(n&&process.once("exit",()=>r("9;4;0;0")),s(),!e)return console.log("Starting Velu\u2026"),{ready:f=>{console.log(`Velu ready \u2192 ${f}`),i(),o()}};let a="\x1B[38;2;220;20;60m",l="\x1B[0m";console.log("");for(let f of Fn)console.log(`${a}${f}${l}`);console.log("");let u=null;try{u=hn(process.execPath,["-e",In],{stdio:["ignore","inherit","ignore"]}),u.on("error",()=>{})}catch{}let c=()=>{if(u){try{u.kill()}catch{}u=null}};return process.once("exit",c),{ready:f=>{c(),process.stdout.write("\x1B[2K\r"),console.log(`  \x1B[32m\u2713${l}  Velu ready  \u2192  \x1B[36m${f}${l}`),i(),o()}}}async function Mn(e){let t=!!process.env.VELU_PROFILE,o=performance.now(),n=(x,p)=>t&&console.log(`[velu-profile] ${x}: ${(performance.now()-p).toFixed(0)}ms`),r=Rn(!!process.stdout.isTTY&&!t,S.basename(e)),s=await Ke(e),i=a();function a(){let p=re(e).filter(w=>w.severity==="error"&&(w.category==="config-json"||w.category==="config-schema"));return p.length&&console.error(`
+`+ne(p,{color:!!process.stderr.isTTY})+`
+`),p}let l=e;try{l=Ye.realpathSync(e)}catch{}let u=0,c=x=>{let p=performance.now();if(p-u<500)return;u=p;let w=H(x,{projectDir:l,knownComponents:I});We(w,x)};process.on("unhandledRejection",c),process.on("uncaughtException",c);let _=yn(import.meta.url).resolve("@mdx-js/react"),d=S.resolve(K,"runtime","velu-ui"),j=Ye.existsSync(d)?d:S.resolve(K,"..","velu-ui","src"),m=[{find:"@mdx-js/react",replacement:_},{find:/^velu-ui$/,replacement:S.join(j,"index.js")},{find:/^velu-ui\//,replacement:j+"/"}],N=Number(process.env.PORT)||8358,E=await xe(),A=wn(),G=gn.createServer(A),v=await Cn({root:K,appType:"custom",logLevel:t?"info":"warn",plugins:[Re(e),$n({remarkPlugins:[Sn,jn,An,q,Je(E,e)],rehypePlugins:[Pn],providerImportSource:"@mdx-js/react"}),kn(),bn()],cacheDir:S.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"],esbuildOptions:{loader:{".mdx":"jsx"}}},resolve:{alias:m,dedupe:["react","react-dom","@mdx-js/react"]},server:{middlewareMode:!0,fs:{allow:[En(K),e,l]},hmr:{server:G}}});n("vite server created",o),A.use(v.middlewares),A.get(He,async(x,p,w)=>{if(!s.favicon)return p.status(404).end();let g=S.resolve(e,s.favicon.replace(/^\//,""));p.sendFile(g,T=>{T&&p.status(404).end()})}),A.use("*",async(x,p,w)=>{let g=x.originalUrl,T=performance.now();if(i.length)return p.status(200).set({"Content-Type":"text/html"}).end(ge(i,{title:"Fix velu.json to continue"}));try{let y=performance.now(),P=await De.readFile(Xe,"utf-8");P=await v.transformIndexHtml(g,P),n(`transformIndexHtml ${g}`,y);let M="/src/runtime/server-entry.jsx";y=performance.now();let{render:Z}=await v.ssrLoadModule(M);n(`ssrLoadModule ${g} (1st req includes dep pre-bundle)`,y),y=performance.now();let k=await Z(g);n(`render ${g}`,y),y=performance.now();let J=await Ze(v,M);n(`collectSsrCss ${g}`,y);let ae=J?`<style data-velu-ssr>${J}</style>`:"",it=`<style data-velu-config>
+${Ce(s)}
+</style>`,st=On.has(s.font.family)?"":Nn(s.font.family),at=s.favicon?`<link rel="icon" href="${He}" />`:"",lt=[ae,it,st,at].filter(Boolean).join(`
+`),ct=P.replace("<!--app-title-->",Ln(s.name)).replace("<!--app-head-->",lt).replace("<!--app-html-->",k);p.status(200).set({"Content-Type":"text/html"}).end(ct),n(`TOTAL ${g}`,T)}catch(y){v.ssrFixStacktrace(y);let P=H(y,{projectDir:l,knownComponents:I});We(P,y),p.status(200).set({"Content-Type":"text/html"}).end(ge([P]))}}),xn.watch(e,{ignoreInitial:!0,ignored:/(^|[\\/])(node_modules|\.git|\.velu)([\\/]|$)/,awaitWriteFinish:{stabilityThreshold:100,pollInterval:20}}).on("all",async(x,p)=>{console.log(`[velu-cli] content ${x}: ${S.relative(e,p)}`);let w=S.basename(p)==="velu.json",g=p.endsWith(".mdx"),T=w||g&&(x==="add"||x==="unlink");if(w&&(s=await Ke(e),i=a()),T)v.moduleGraph.invalidateAll();else if(g){let y=p.split(S.sep).join("/"),P=v.moduleGraph.getModulesByFile(y);if(P)for(let M of P)v.moduleGraph.invalidateModule(M)}v.ws.send({type:"full-reload"})});async function ke(x){let p=new Set,w=12,g=0,T=[],y=()=>g<w?(g+=1,Promise.resolve()):new Promise(k=>T.push(k)).then(()=>{g+=1}),P=()=>{g-=1,T.shift()?.()},M=k=>/[\\/]\.velu[\\/]vite-cache[\\/]|[\\/]deps[\\/]/.test(k)||/[\\/]node_modules[\\/]/.test(k)&&!/velu-ui/.test(k);async function Z(k){if(!(!k||p.has(k)||M(k))){p.add(k);try{await y();try{await v.transformRequest(k,{ssr:!1})}finally{P()}let J=await v.moduleGraph.getModuleByUrl(k,!1);J?.importedModules?.size&&await Promise.all([...J.importedModules].map(ae=>Z(ae.url)))}catch{}}}return await Z(x),p.size}G.listen(N,async()=>{let x=performance.now(),p=0;try{let{render:w}=await v.ssrLoadModule("/src/runtime/server-entry.jsx");await ke("/src/runtime/client-entry.jsx"),typeof v.waitForRequestsIdle=="function"&&await v.waitForRequestsIdle();let[g]=await Promise.allSettled([ke("/src/runtime/client-entry.jsx"),w("/"),v.transformIndexHtml("/",await De.readFile(Xe,"utf-8")),Ze(v,"/src/runtime/server-entry.jsx")]).then(T=>T.map(y=>y.status==="fulfilled"?y.value:0));p=g}catch(w){t&&console.log("[velu-profile] warmup error:",w?.message)}n(`cold-start warm-up (${p} client modules)`,x),r.ready(`http://localhost:${N}`)})}var Tn,_n,On,He,Ln,K,Xe,Fn,In,et=b(()=>{ce();Ee();Me();de();ze();F();he();ye();we();qe();Tn=S.dirname(vn(import.meta.url)),_n=/\.(css|less|sass|scss|styl|stylus|pcss|postcss)(\?|$)/,On=new Set(["Google Sans Flex","Google Sans Code","Outfit"]),He="/@velu-favicon",Ln=e=>String(e).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");K=S.resolve(Tn,".."),Xe=S.resolve(K,"src","template.html"),Fn=[" _    __     __","| |  / /__  / /_  __","| | / / _ \\/ / / / /","| |/ /  __/ / /_/ /","|___/\\___/_/\\__,_/"],In="const F=['\u280B','\u2819','\u2839','\u2838','\u283C','\u2834','\u2826','\u2827','\u2807','\u280F'],M=['Starting Velu','Setting up your preview','Preparing your docs','Warming things up','Almost ready'];let f=0,m=0;const t=Date.now();const C='\\x1b[38;2;220;20;60m',R='\\x1b[0m',D='\\x1b[2m';const d=()=>{const s=(Date.now()-t)/1000|0;process.stdout.write('\\x1b[2K\\r  '+C+F[f]+R+'  '+M[m]+'\\u2026  '+D+s+'s'+R);f=(f+1)%F.length;};d();setInterval(d,90);setInterval(()=>{if(m<M.length-1)m++;},4000);"});var nt={};le(nt,{default:()=>Vn,runValidate:()=>tt});import Un from"node:fs";import zn from"node:path";function Bn(e){try{let t=JSON.parse(Un.readFileSync(zn.join(e,"velu.json"),"utf-8"));if(!t.navigation||typeof t.navigation!="object")return[];let o=B(t.navigation);return V(o,e).pageEntries}catch{return[]}}async function tt(e){let t=re(e),o=Bn(e),n=await Ve(e,o),r=[...t,...n],s=!!process.stdout.isTTY;return console.log(ne(r,{color:s})),r.some(a=>a.severity!=="warning"&&a.severity!=="info")?1:0}var Vn,ot=b(()=>{Y();Q();ye();we();F();Vn=tt});import be from"node:path";import L from"node:process";import{readFileSync as Gn}from"node:fs";var[,,rt,se]=L.argv;function Jn(){try{return JSON.parse(Gn(new URL("../package.json",import.meta.url),"utf8")).version}catch{return"unknown"}}async function qn(){switch(rt){case"--version":case"-v":case"version":{console.log(Jn());break}case"init":{se||(console.error("Usage: velu init <project-name>"),L.exit(1));let e=se,t=be.resolve(L.cwd(),e),{initProject:o}=await Promise.resolve().then(()=>(je(),Se));await o(t,e);break}case"dev":{let e=be.resolve(L.cwd(),se??"."),{startDevServer:t}=await Promise.resolve().then(()=>(et(),Qe));await t(e);break}case"validate":{let e=be.resolve(L.cwd(),se??"."),{runValidate:t}=await Promise.resolve().then(()=>(ot(),nt)),o=await t(e);L.exit(o);break}default:console.log("Usage:"),console.log("  velu init <project-name>   scaffold a new docs project"),console.log("  velu dev [dir]             start the dev preview server"),console.log("  velu validate [dir]        check velu.json + content for problems"),L.exit(rt?1:0)}}qn().catch(e=>{console.error(L.env.VELU_DEBUG?e:`Error: ${e.message}`),L.exit(1)});

package/package.json

@@ -1,51 +1,55 @@
-{
-  "name": "@veluai/velu",
-  "version": "0.1.9",
-  "type": "module",
-  "bin": "./dist/cli.js",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist/**",
-    "src/runtime/**",
-    "src/navigation.js",
-    "src/template.html",
-    "runtime/velu-ui/**",
-    "schema/**",
-    "templates/**"
-  ],
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepack": "node scripts/build.mjs"
-  },
-  "dependencies": {
-    "@icons-pack/react-simple-icons": ">=13.0.0 <13.13.0",
-    "@mdx-js/react": "^3.1.1",
-    "@mdx-js/rollup": "^3.1.1",
-    "@tailwindcss/vite": "^4.1.0",
-    "@vitejs/plugin-react": "^4.3.4",
-    "chokidar": "^3.6.0",
-    "estree-util-value-to-estree": "^3.5.0",
-    "express": "^4.21.1",
-    "github-slugger": "^2.0.0",
-    "iso-639-1": "^3.1.5",
-    "lucide-react": "^0.460.0",
-    "mdast-util-to-string": "^4.0.0",
-    "prism-react-renderer": "^2.4.0",
-    "prismjs": "^1.29.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-router-dom": "^6.28.0",
-    "rehype-slug": "^6.0.0",
-    "remark-frontmatter": "^5.0.0",
-    "remark-gfm": "^4.0.1",
-    "remark-mdx-frontmatter": "^5.2.0",
-    "tailwindcss": "^4.1.0",
-    "unist-util-visit": "^5.1.0",
-    "vite": "^5.4.11"
-  },
-  "devDependencies": {
-    "esbuild": "^0.28.0"
-  }
-}
+{
+  "name": "@veluai/velu",
+  "version": "0.1.12",
+  "type": "module",
+  "bin": "./dist/cli.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**",
+    "src/runtime/**",
+    "src/navigation.js",
+    "src/template.html",
+    "src/lib/issues.js",
+    "src/lib/extract-mdx-error.js",
+    "src/lib/known-components.js",
+    "runtime/velu-ui/**",
+    "schema/**",
+    "templates/**"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs"
+  },
+  "dependencies": {
+    "@icons-pack/react-simple-icons": ">=13.0.0 <13.13.0",
+    "@mdx-js/mdx": "^3.1.1",
+    "@mdx-js/react": "^3.1.1",
+    "@mdx-js/rollup": "^3.1.1",
+    "@tailwindcss/vite": "^4.1.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "chokidar": "^3.6.0",
+    "estree-util-value-to-estree": "^3.5.0",
+    "express": "^4.21.1",
+    "github-slugger": "^2.0.0",
+    "iso-639-1": "^3.1.5",
+    "lucide-react": "^0.460.0",
+    "mdast-util-to-string": "^4.0.0",
+    "prism-react-renderer": "^2.4.0",
+    "prismjs": "^1.29.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "tailwindcss": "^4.1.0",
+    "unist-util-visit": "^5.1.0",
+    "vite": "^5.4.11"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0"
+  }
+}

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

@@ -0,0 +1,138 @@
+import React from 'react';
+
+/**
+ * ErrorCard — a branded, self-contained card that renders ONE Velu "issue"
+ * (an MDX or velu.json problem). Used by the dev server's per-page error
+ * boundary. Deliberately presentational and dependency-free (no other Velu
+ * components, no effects) so it can never fail while reporting a failure.
+ *
+ * Styled with inline styles + design tokens (with hard fallbacks), so it looks
+ * right even when the page's own CSS hasn't loaded.
+ */
+const DANGER = 'var(--danger-stroke-color, #ef4444)';
+const DANGER_BG =
+  'var(--danger-bg-color, color-mix(in srgb, #ef4444 7%, transparent))';
+const MUTED = 'var(--muted-color, #6b7280)';
+const TEXT = 'var(--text-color, #111827)';
+
+export default function ErrorCard({
+  label,
+  title,
+  file,
+  line,
+  column,
+  frame,
+  detail,
+  hint,
+  suggestion,
+}) {
+  const loc = file
+    ? `${file}${line ? `:${line}${column ? `:${column}` : ''}` : ''}`
+    : null;
+
+  return (
+    <div
+      role="alert"
+      style={{
+        border: `1px solid ${DANGER}`,
+        borderRadius: 'var(--radius-md, 10px)',
+        background: DANGER_BG,
+        padding: 'var(--s2, 1rem)',
+        margin: 'var(--s2, 1rem) 0',
+        fontFamily: 'var(--font-sans, system-ui, sans-serif)',
+        color: TEXT,
+        lineHeight: 1.5,
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          gap: '0.6rem',
+          alignItems: 'center',
+          flexWrap: 'wrap',
+        }}
+      >
+        <span
+          style={{
+            fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+            fontSize: 11,
+            textTransform: 'uppercase',
+            letterSpacing: '0.06em',
+            fontWeight: 600,
+            color: DANGER,
+            border: `1px solid ${DANGER}`,
+            borderRadius: 999,
+            padding: '2px 9px',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {label}
+        </span>
+      </div>
+
+      {title && (
+        <div style={{ marginTop: '0.6rem', fontWeight: 600, fontSize: '1.05rem' }}>
+          {title}
+        </div>
+      )}
+
+      {loc && (
+        <div
+          style={{
+            display: 'inline-block',
+            marginTop: '0.7rem',
+            fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+            fontSize: 15,
+            fontWeight: 600,
+            letterSpacing: '0.01em',
+            color: DANGER,
+            background: 'var(--danger-bg-color, rgba(239,68,68,0.12))',
+            border: `1px solid ${DANGER}`,
+            borderRadius: 7,
+            padding: '7px 11px',
+          }}
+        >
+          {loc}
+        </div>
+      )}
+      {detail && (
+        <div style={{ marginTop: '0.25rem', color: MUTED }}>{detail}</div>
+      )}
+
+      {frame && (
+        <pre
+          style={{
+            marginTop: '0.75rem',
+            marginBottom: 0,
+            padding: '0.75rem 0.9rem',
+            overflow: 'auto',
+            background: 'var(--code-bg-color, rgba(0,0,0,0.05))',
+            borderRadius: 'var(--radius-sm, 6px)',
+            fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+            fontSize: 12.5,
+            lineHeight: 1.5,
+            color: TEXT,
+          }}
+        >
+          {frame}
+        </pre>
+      )}
+
+      {suggestion && (
+        <div style={{ marginTop: '0.75rem' }}>
+          Did you mean{' '}
+          <code style={{ fontWeight: 600, color: DANGER }}>
+            {`<${suggestion}>`}
+          </code>
+          ?
+        </div>
+      )}
+
+      {hint && (
+        <div style={{ marginTop: '0.6rem', color: MUTED, fontSize: '0.92rem' }}>
+          {hint}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -1,70 +1,101 @@
-/* ThemeToggle — circular button with a sun/moon glyph; click flips
-   the theme. Geometry is a 32 × 32 circle with an 18 × 18 glyph
-   centred inside. The pill-with-slider design was replaced earlier;
-   only the circle survives now.
-
-   In light mode: --page-bg circle, sun glyph.
-   In dark mode:  --page-bg circle, moon glyph.
-
-   Visibility model: BOTH icons are always rendered, stacked at the
-   same `position: absolute` slot inside the button. Opacity controls
-   which one is visible. We use opacity (not display: none) because:
-
-     1. Stacked icons render at the exact same point — no layout
-        shift when the theme flips.
-     2. Opacity is not touched anywhere else for these elements, so
-        the cascade is trivial — no risk of a stray rule (preflight,
-        utility class, dev-time fallback) overriding `display: none`
-        and revealing the wrong icon.
-     3. Identical markup on server + client → SSR-safe, no hydration
-        mismatch and no icon flash.
-
-   All values are tokens. */
-
-.velu-theme-toggle {
-  /* `relative` so the absolutely-positioned icons inside are
-     anchored to this button, not the page. */
-  position: relative;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  inline-size: 2rem;
-  block-size: 2rem;
-  border: var(--border-width) solid var(--border-color);
-  border-radius: 999px;
-  padding: 0;
-  background: var(--page-bg);
-  cursor: pointer;
-  transition: border-color 0.12s ease, background 0.12s ease;
-}
-.velu-theme-toggle:hover {
-  border-color: var(--accent-color);
-}
-
-/* Both icons stack here, centred. Default opacity 0 — the per-theme
-   rules below switch one on. */
-.velu-theme-toggle__icon {
-  position: absolute;
-  inset-block-start: 50%;
-  inset-inline-start: 50%;
-  inline-size: 1.125rem;
-  block-size: 1.125rem;
-  margin-block-start: -0.5625rem;     /* half of block-size */
-  margin-inline-start: -0.5625rem;    /* half of inline-size */
-  color: var(--text-color);
-  opacity: 0;
-  transition: opacity 0.2s ease;
-  pointer-events: none;
-}
-
-/* Default (light) → sun on. */
-.velu-theme-toggle__icon--sun {
-  opacity: 1;
-}
-/* Dark theme → moon on, sun off. */
-[data-theme='dark'] .velu-theme-toggle__icon--sun {
-  opacity: 0;
-}
-[data-theme='dark'] .velu-theme-toggle__icon--moon {
-  opacity: 1;
-}
+/* ThemeToggle — circular button with a sun/moon glyph; click flips
+   the theme. Geometry is a 32 × 32 circle with an 18 × 18 glyph
+   centred inside. The pill-with-slider design was replaced earlier;
+   only the circle survives now.
+
+   In light mode: --page-bg circle, sun glyph.
+   In dark mode:  --page-bg circle, moon glyph.
+
+   Visibility model: BOTH icons are always rendered, stacked at the
+   same `position: absolute` slot inside the button. Opacity controls
+   which one is visible. We use opacity (not display: none) because:
+
+     1. Stacked icons render at the exact same point — no layout
+        shift when the theme flips.
+     2. Opacity is not touched anywhere else for these elements, so
+        the cascade is trivial — no risk of a stray rule (preflight,
+        utility class, dev-time fallback) overriding `display: none`
+        and revealing the wrong icon.
+     3. Identical markup on server + client → SSR-safe, no hydration
+        mismatch and no icon flash.
+
+   All values are tokens. */
+
+.velu-theme-toggle {
+  /* `relative` so the absolutely-positioned icons inside are
+     anchored to this button, not the page. */
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 2rem;
+  block-size: 2rem;
+  border: var(--border-width) solid var(--border-color);
+  border-radius: 999px;
+  padding: 0;
+  background: var(--page-bg);
+  cursor: pointer;
+  transition: border-color 0.12s ease, background 0.12s ease,
+    transform 0.18s cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+.velu-theme-toggle:hover {
+  border-color: var(--accent-color);
+}
+/* Tactile press feedback on click. */
+.velu-theme-toggle:active {
+  transform: scale(0.9);
+}
+
+/* Both icons stack here, centred. Each animates in/out on a theme flip:
+   the hidden glyph is faded, shrunk, and rotated off its axis; the active
+   one springs to full size at 0deg. Centring is done with margins (above),
+   so `transform` is free to drive the rotate/scale animation. */
+.velu-theme-toggle__icon {
+  position: absolute;
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+  inline-size: 1.125rem;
+  block-size: 1.125rem;
+  margin-block-start: -0.5625rem;     /* half of block-size */
+  margin-inline-start: -0.5625rem;    /* half of inline-size */
+  color: var(--text-color);
+  opacity: 0;
+  transition: opacity 0.28s ease,
+    transform 0.4s cubic-bezier(0.34, 1.56, 0.64, 1);
+  pointer-events: none;
+}
+
+/* Hidden state per glyph — sun spins out clockwise, moon anti-clockwise,
+   so the swap reads as one rotating through the other. */
+.velu-theme-toggle__icon--sun {
+  transform: rotate(90deg) scale(0.4);
+}
+.velu-theme-toggle__icon--moon {
+  transform: rotate(-90deg) scale(0.4);
+}
+
+/* Exactly one glyph is shown — the sun in light, the moon in dark — at full
+   size, upright. Higher specificity than the hidden defaults above, so it
+   wins for whichever glyph the active theme selects. */
+:root:not([data-theme='dark']) .velu-theme-toggle__icon--sun,
+[data-theme='dark'] .velu-theme-toggle__icon--moon {
+  opacity: 1;
+  transform: rotate(0deg) scale(1);
+}
+
+/* Honour reduced-motion: keep a plain crossfade — no spin, scale, or press. */
+@media (prefers-reduced-motion: reduce) {
+  .velu-theme-toggle {
+    transition: border-color 0.12s ease, background 0.12s ease;
+  }
+  .velu-theme-toggle:active {
+    transform: none;
+  }
+  .velu-theme-toggle__icon {
+    transition: opacity 0.2s ease;
+  }
+  .velu-theme-toggle__icon--sun,
+  .velu-theme-toggle__icon--moon {
+    transform: none;
+  }
+}

package/runtime/velu-ui/index.js

@@ -7,6 +7,7 @@ export { default as NavSelect } from './components/NavSelect.jsx';
 export { default as Toc } from './components/Toc.jsx';
 export { default as TocBar } from './components/TocBar.jsx';
 export { default as Callout } from './components/Callout.jsx';
+export { default as ErrorCard } from './components/ErrorCard.jsx';
 export {
   default as Accordion,
   AccordionGroup,

package/runtime/velu-ui/lib/component-schemas.js

@@ -0,0 +1,100 @@
+// Per-component option schemas — the props whose wrong value would otherwise
+// render incorrectly *silently*. Deliberately small and high-signal; extend a
+// component's entry here when it gains a new constrained option.
+//
+// Pure data + a pure validator (no React, no other imports) so BOTH sides can
+// use it: the live MDX registry (velu-ui/mdx-components.jsx) validates at
+// render time, and `velu validate` (velu-cli) imports this same module to
+// statically check literal attributes — one source of truth, no drift.
+
+// Canonical accepted values (must match the components):
+//   Callout  — VARIANTS keys; the component is CASE-SENSITIVE (VARIANTS[type]).
+//   MethodBadge — METHODS; the component lower-cases the input first.
+export const CALLOUT_TYPES = ['note', 'warning', 'info', 'tip', 'check', 'danger', 'callout'];
+export const METHOD_NAMES = ['get', 'post', 'put', 'patch', 'delete'];
+
+// schema: { enums: { prop: { values, caseSensitive } }, required: [prop, …] }
+const SCHEMAS = {
+  Callout: { enums: { type: { values: CALLOUT_TYPES, caseSensitive: true } } },
+  MethodBadge: { enums: { method: { values: METHOD_NAMES, caseSensitive: false } } },
+  ApiPath: { enums: { method: { values: METHOD_NAMES, caseSensitive: false } } },
+  Image: { required: ['src'] },
+};
+
+// Smallest edit distance match within a set (for "did you mean"). Tiny inputs.
+function closest(value, values) {
+  const v = String(value).toLowerCase();
+  let best = null;
+  let bestD = Infinity;
+  for (const cand of values) {
+    const a = v;
+    const b = cand.toLowerCase();
+    // inline Levenshtein
+    const m = a.length;
+    const n = b.length;
+    const d = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+      let prev = d[0];
+      d[0] = i;
+      for (let j = 1; j <= n; j++) {
+        const tmp = d[j];
+        d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+        prev = tmp;
+      }
+    }
+    if (d[n] < bestD) {
+      bestD = d[n];
+      best = cand;
+    }
+  }
+  return bestD <= 3 ? best : null;
+}
+
+/**
+ * Validate a component's props against its schema.
+ * @param {string} name   component tag name
+ * @param {object} props   props passed to it
+ * @param {{ checkRequired?: boolean }} [opts]  static callers pass
+ *        checkRequired:false because a prop supplied via a {expression}
+ *        isn't a literal they can see, so "missing required" would be a
+ *        false positive.
+ * @returns an issue-shaped object (category 'invalid-props') or null if valid.
+ *   { category, title, detail, hint, suggestion }
+ */
+export function validateProps(name, props = {}, opts = {}) {
+  const { checkRequired = true } = opts;
+  const schema = SCHEMAS[name];
+  if (!schema) return null;
+
+  for (const req of checkRequired ? schema.required || [] : []) {
+    const v = props[req];
+    if (v == null || v === '') {
+      return {
+        category: 'invalid-props',
+        title: `<${name}> is missing the required "${req}" prop`,
+        hint: `Add ${req}="…" to the component.`,
+      };
+    }
+  }
+
+  for (const [prop, rule] of Object.entries(schema.enums || {})) {
+    if (!(prop in props) || props[prop] == null) continue;
+    const raw = props[prop];
+    const ok = rule.caseSensitive
+      ? rule.values.includes(raw)
+      : rule.values.map((s) => s.toLowerCase()).includes(String(raw).toLowerCase());
+    if (!ok) {
+      const guess = closest(raw, rule.values);
+      return {
+        category: 'invalid-props',
+        title: `Invalid "${prop}" on <${name}>: "${raw}"`,
+        detail: `Expected one of: ${rule.values.join(', ')}.`,
+        hint: guess ? `Did you mean "${guess}"?` : '',
+      };
+    }
+  }
+
+  return null;
+}
+
+export default validateProps;

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

@@ -4,7 +4,7 @@
  *
  * `navigator.clipboard` only exists in a secure context (HTTPS or
  * localhost). On a plain-HTTP origin — e.g. previewing the dev server
- * over the LAN at http://<ip>:5173 on a phone — it's `undefined`, so a
+ * over the LAN at http://<ip>:8358 on a phone — it's `undefined`, so a
  * `if (!navigator.clipboard) return` guard makes copy buttons silently
  * no-op. This util falls back to the legacy `execCommand('copy')` via a
  * hidden textarea so copy still works on those origins.

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

@@ -15,6 +15,7 @@ import TryItBar from './components/TryItBar.jsx';
 import ApiField from './components/ApiField.jsx';
 import ApiClient from './components/ApiClient.jsx';
 import ApiSidebar from './components/ApiSidebar.jsx';
+import { validateProps } from './lib/component-schemas.js';
 
 /**
  * defaultMdxComponents — the registry the MDXProvider consumes.
@@ -53,12 +54,31 @@ function PreOverride({ children }) {
   );
 }
 
+/* Wrap a component so its constrained options (see component-schemas.js)
+   are validated at render time. An invalid option throws a marked error
+   (`err.veluIssue`) that the dev server turns into a friendly card on the
+   page AND a clean block in the terminal — the same surface as an unknown
+   component. Components without a schema pass straight through. */
+function checked(name, Comp) {
+  function Checked(props) {
+    const issue = validateProps(name, props);
+    if (issue) {
+      const err = new Error(issue.title);
+      err.veluIssue = issue;
+      throw err;
+    }
+    return <Comp {...props} />;
+  }
+  Checked.displayName = `Checked(${name})`;
+  return Checked;
+}
+
 export const defaultMdxComponents = {
   /* HTML-tag overrides (lowercase keys). */
   pre: PreOverride,
 
   /* Authored component tags (capitalised keys). */
-  Callout,
+  Callout: checked('Callout', Callout),
   Card,
   CardGroup,
   Accordion,
@@ -71,11 +91,11 @@ export const defaultMdxComponents = {
   Tree,
   Folder,
   File,
-  Image,
+  Image: checked('Image', Image),
   CodeBlock,
   CodeGroup,
-  MethodBadge,
-  ApiPath,
+  MethodBadge: checked('MethodBadge', MethodBadge),
+  ApiPath: checked('ApiPath', ApiPath),
   TryItBar,
   ApiField,
   ApiClient,

package/src/lib/extract-mdx-error.js

@@ -0,0 +1,170 @@
+// Normalize a thrown error — from a Vite/MDX transform, an SSR render, or a
+// React error boundary — into the shared `issue` shape (see ./issues.js).
+//
+// Isomorphic: no Node `path` import (path handling is string-based) so the
+// browser ErrorBoundary can reuse it. The single hard rule is PATH SAFETY:
+// never surface an absolute path that isn't under the user's project — those
+// are Velu/Vite internals and must be stripped.
+import { makeIssue, suggestComponent } from './issues.js';
+
+// Unwrap a few layers of `err.cause` when the outer message is generic.
+function unwrap(err) {
+  let e = err;
+  let depth = 0;
+  while (e && e.cause && depth < 3) {
+    // Stop if the current layer already carries useful location info.
+    if (e.loc || e.line || /`[^`]+` to be defined/.test(e.message || '')) break;
+    e = e.cause;
+    depth += 1;
+  }
+  return e || err;
+}
+
+const toPosix = (p) => String(p).replace(/\\/g, '/');
+
+// Make an absolute path project-relative; return null for anything that isn't
+// inside the project (i.e. our internals — never shown).
+function rel(rawPath, projectDir) {
+  if (!rawPath) return null;
+  let p = toPosix(rawPath).replace(/[?#].*$/, ''); // drop ?query / #hash
+  const root = projectDir ? toPosix(projectDir).replace(/\/+$/, '') : '';
+  if (root && p.toLowerCase().startsWith(root.toLowerCase())) {
+    return p.slice(root.length).replace(/^\/+/, '');
+  }
+  // Already-relative, project-owned path (no drive letter, no node_modules).
+  if (!/^([a-zA-Z]:\/|\/)/.test(p) && !/node_modules/.test(p)) return p;
+  return null; // absolute and outside the project → hide it
+}
+
+// Strip any absolute path (and node_modules refs) from a message so internals
+// never leak; collapse them to "…".
+function cleanMessage(msg) {
+  if (!msg) return '';
+  return String(msg)
+    .replace(/([a-zA-Z]:\\|\/)[^\s'"()]+/g, (m) => (/node_modules|[\\/]vite[\\/]|@veluai|velu-cli|velu-ui/.test(m) ? '…' : m))
+    .trim();
+}
+
+// Pull a "(line:col)" / "(line:col-line:col)" position out of a message tail.
+// MDX/vfile errors often carry the location only in the message string, with
+// err.line/err.loc left undefined.
+function parseLocFromMessage(msg) {
+  const m = /\((\d+):(\d+)(?:-\d+:\d+)?\)\s*$/.exec(String(msg || ''));
+  return m ? { line: Number(m[1]), column: Number(m[2]) } : null;
+}
+
+// Drop a trailing "(line:col-…)" from a message once we've surfaced it as a
+// separate location, so it isn't shown twice.
+function stripLocSuffix(msg) {
+  return String(msg || '').replace(/\s*\(\d+:\d+(?:-\d+:\d+)?\)\s*$/, '').trim();
+}
+
+// Phrases that mark a genuine MDX *parse* error (vs a runtime throw).
+const MDX_SYNTAX_RE =
+  /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;
+
+// Keep a code frame only when it clearly belongs to a project file; otherwise
+// drop it (an internal frame would leak paths and confuse the author).
+function safeFrame(frame, fileIsProjectOwned) {
+  if (!frame || !fileIsProjectOwned) return null;
+  const text = String(frame);
+  if (/node_modules|[\\/]vite[\\/]|@veluai[\\/]/.test(text)) return null;
+  return text;
+}
+
+export function extractMdxError(rawErr, opts = {}) {
+  const { projectDir = '', knownComponents = [], file: fileHint = null } = opts;
+
+  // A component (runtime) or the compile-time prop check attaches a ready-made
+  // issue. Trust it directly — it already carries plain-language wording, a
+  // suggestion, and (from the compile-time check) a file:line. Walk the cause
+  // chain since Vite/rollup may re-wrap the thrown error.
+  let tagged = null;
+  for (let e = rawErr, depth = 0; e && depth < 6; e = e.cause, depth += 1) {
+    if (e.veluIssue) {
+      tagged = e.veluIssue;
+      break;
+    }
+  }
+  if (tagged) return makeIssue({ ...tagged, file: tagged.file || fileHint });
+
+  const err = unwrap(rawErr) || {};
+  const message = err.message || String(rawErr || '');
+
+  // 1) Unknown component (MDX render: `_missingMdxReference`). The message
+  // tail carries the spot: "...referenced in your code at `7:1-7:54` in
+  // `<abs path>`" — pull the line/column + file out so the author knows
+  // exactly where to look (path relative-ized for safety).
+  const missing = /Expected component `([^`]+)` to be defined/.exec(message);
+  if (missing) {
+    const name = missing[1];
+    const at = /referenced in your code at `(\d+):(\d+)/.exec(message);
+    const inFile = /\bin `([^`]+)`/.exec(message);
+    const relFile = inFile ? rel(inFile[1], projectDir) : null;
+    return makeIssue({
+      category: 'unknown-component',
+      file: relFile || fileHint,
+      line: at ? Number(at[1]) : null,
+      column: at ? Number(at[2]) : null,
+      title: `<${name}> is not a built-in component`,
+      detail: '',
+      hint: 'Components are built in — check the spelling and capitalization (you don’t import them).',
+      suggestion: suggestComponent(name, knownComponents),
+    });
+  }
+
+  // 2) Compile error carrying a source location (Vite plugin / MDX / vfile).
+  // The location may be on err.loc, on err.line/column, or only inside the
+  // message text — try all three.
+  const loc =
+    err.loc ||
+    (err.line != null ? { line: err.line, column: err.column, file: err.file } : null) ||
+    parseLocFromMessage(err.reason || message);
+  const rawFile = err.id || (loc && loc.file) || err.file || null;
+  const file = rel(rawFile, projectDir) || fileHint;
+  const fileIsProjectOwned = Boolean(file) && rel(rawFile, projectDir) != null;
+  const frame = safeFrame(err.frame, fileIsProjectOwned || Boolean(fileHint));
+  const detail = cleanMessage(stripLocSuffix(err.reason || message));
+  const isSyntax = MDX_SYNTAX_RE.test(message);
+  const isFrontmatter =
+    err.source === 'remark-frontmatter' ||
+    /\byaml\b|frontmatter/i.test(message) ||
+    (loc && loc.line === 1 && /unexpected|expected/i.test(message) && /---/.test(message));
+
+  if (loc || isSyntax || (frame && fileIsProjectOwned)) {
+    return makeIssue({
+      category: isFrontmatter ? 'frontmatter' : 'mdx-syntax',
+      file,
+      line: loc ? loc.line : null,
+      column: loc ? loc.column : null,
+      frame,
+      title: detail || (isFrontmatter ? 'Invalid frontmatter' : 'MDX syntax error'),
+      detail: '',
+      hint: isFrontmatter
+        ? 'Check the YAML between the --- markers — indentation, quotes, and colons.'
+        : 'Make sure every <Component> has a matching closing tag and that { } braces are balanced.',
+    });
+  }
+
+  // 3) Bad prop / option that threw at render time.
+  if (/\.map is not a function|is not iterable|reading '|undefined \(reading/i.test(message)) {
+    return makeIssue({
+      category: 'invalid-props',
+      file,
+      title: 'A component received an invalid value',
+      detail,
+      hint: 'Check the props/options you passed to a component on this page.',
+    });
+  }
+
+  // 4) Anything else that threw while rendering.
+  return makeIssue({
+    category: 'render-crash',
+    file,
+    title: 'This page failed to render',
+    detail,
+    hint: 'Set VELU_DEBUG=1 for the full stack trace.',
+  });
+}
+
+export default extractMdxError;

package/src/lib/issues.js

@@ -0,0 +1,159 @@
+// The shared "issue" model used by BOTH the live `velu dev` error surface and
+// the `velu validate` command — so an author sees the same wording whether a
+// problem shows up live in the browser/terminal or in a batch validation run.
+//
+// An issue is a plain object:
+//   {
+//     category,    // see CATEGORY_LABEL keys below
+//     severity,    // 'error' (default) | 'warning' | 'info'
+//     file,        // project-relative path (posix), or null
+//     line, column,// 1-based numbers, or null
+//     frame,       // a caret-annotated code-frame string, or null
+//     title,       // short, plain-language headline
+//     detail,      // the underlying message (already path-stripped)
+//     hint,        // how to fix it
+//     suggestion,  // a "did you mean <X>" component name, or null
+//   }
+//
+// This module is dependency-free and isomorphic (no Node-only imports), so the
+// browser ErrorBoundary can reuse `levenshtein`/`suggestComponent`.
+
+export const CATEGORY_LABEL = {
+  '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',
+};
+
+// Fill in defaults so callers only set what they know.
+export function makeIssue(partial) {
+  return {
+    category: 'render-crash',
+    severity: 'error',
+    file: null,
+    line: null,
+    column: null,
+    frame: null,
+    title: 'Something went wrong',
+    detail: '',
+    hint: '',
+    suggestion: null,
+    ...partial,
+  };
+}
+
+// Classic Levenshtein edit distance (small inputs — component names).
+export function levenshtein(a, b) {
+  a = String(a);
+  b = String(b);
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let cur = new Array(b.length + 1);
+  for (let i = 1; i <= a.length; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, cur] = [cur, prev];
+  }
+  return prev[b.length];
+}
+
+// Closest known component to `name` within a small edit distance, else null.
+// Compared case-insensitively (so a capitalization typo still matches) but the
+// correctly-cased known name is returned.
+export function suggestComponent(name, known = []) {
+  if (!name) return null;
+  const lower = String(name).toLowerCase();
+  let best = null;
+  let bestD = Infinity;
+  for (const k of known) {
+    const d = levenshtein(lower, String(k).toLowerCase());
+    if (d < bestD) {
+      bestD = d;
+      best = k;
+    }
+  }
+  // Allow a little more slack for longer names, capped at 3 edits.
+  const threshold = Math.min(3, Math.max(2, Math.floor(lower.length / 4)));
+  return bestD <= threshold ? best : null;
+}
+
+// ── Terminal formatting ─────────────────────────────────────────────────────
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+};
+const paint = (on, code, s) => (on ? `${code}${s}${COLORS.reset}` : s);
+
+function severityMark(sev, color) {
+  if (sev === 'warning') return paint(color, COLORS.yellow, '⚠');
+  if (sev === 'info') return paint(color, COLORS.cyan, 'ℹ');
+  return paint(color, COLORS.red, '✖');
+}
+
+// Format a single issue as a multi-line terminal block.
+export function formatIssue(issue, { color = false } = {}) {
+  const label = CATEGORY_LABEL[issue.category] || issue.category;
+  const lineCol = issue.line
+    ? `${issue.line}${issue.column ? `:${issue.column}` : ''}`
+    : '';
+  // Keep the line:col even when grouped output has nulled the file (so the
+  // position still shows under a per-file heading in formatReport).
+  const where = issue.file ? `${issue.file}${lineCol ? `:${lineCol}` : ''}` : lineCol;
+  const lines = [];
+  lines.push(
+    `${severityMark(issue.severity, color)} ${paint(color, COLORS.bold, label)}` +
+      (where ? `  ${paint(color, COLORS.dim, where)}` : ''),
+  );
+  if (issue.title) lines.push(`  ${issue.title}`);
+  if (issue.detail && issue.detail !== issue.title) lines.push(`  ${paint(color, COLORS.dim, issue.detail)}`);
+  if (issue.frame) {
+    for (const f of String(issue.frame).split('\n')) lines.push(`  ${f}`);
+  }
+  if (issue.suggestion) lines.push(`  ${paint(color, COLORS.cyan, `Did you mean <${issue.suggestion}>?`)}`);
+  if (issue.hint) lines.push(`  ${paint(color, COLORS.dim, `→ ${issue.hint}`)}`);
+  return lines.join('\n');
+}
+
+// Format a list of issues as a grouped report (used by `velu validate`).
+export function formatReport(issues, { color = false } = {}) {
+  if (!issues.length) {
+    return paint(color, COLORS.cyan, '✓ No issues found.');
+  }
+  // Group by file (config issues with no file group under "velu.json").
+  const groups = new Map();
+  for (const issue of issues) {
+    const key = issue.file || 'velu.json';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(issue);
+  }
+  const out = [];
+  for (const [file, group] of groups) {
+    out.push(paint(color, COLORS.bold, file));
+    for (const issue of group) {
+      out.push(formatIssue({ ...issue, file: null }, { color }).replace(/^/gm, '  '));
+    }
+    out.push('');
+  }
+  const errors = issues.filter((i) => i.severity !== 'warning' && i.severity !== 'info').length;
+  const warnings = issues.length - errors;
+  const summary =
+    `${errors} error${errors === 1 ? '' : 's'}` +
+    (warnings ? `, ${warnings} warning${warnings === 1 ? '' : 's'}` : '');
+  out.push(paint(color, errors ? COLORS.red : COLORS.yellow, summary));
+  return out.join('\n');
+}

package/src/lib/known-components.js

@@ -0,0 +1,34 @@
+// The capitalized component tags an author may use in `.mdx` content.
+//
+// Kept in sync with velu-ui's `defaultMdxComponents`
+// (packages/velu-ui/src/mdx-components.jsx). Used for "did you mean"
+// suggestions and unknown-component detection on the Node side (dev server +
+// `velu validate`). The browser ErrorBoundary derives the same set directly
+// from `defaultMdxComponents`, so this list only needs to stay roughly in
+// step (a missing entry just costs a suggestion, never correctness).
+export const KNOWN_COMPONENTS = [
+  'Callout',
+  'Card',
+  'CardGroup',
+  'Accordion',
+  'AccordionGroup',
+  'Columns',
+  'Field',
+  'Prompt',
+  'Steps',
+  'Step',
+  'Tree',
+  'Folder',
+  'File',
+  'Image',
+  'CodeBlock',
+  'CodeGroup',
+  'MethodBadge',
+  'ApiPath',
+  'TryItBar',
+  'ApiField',
+  'ApiClient',
+  'ApiSidebar',
+];
+
+export default KNOWN_COMPONENTS;

package/src/runtime/App.jsx

@@ -48,6 +48,7 @@ import {
   VeluMark,
 } from 'velu-ui';
 import { X, ChevronDown, ChevronUp } from 'lucide-react';
+import ErrorBoundary from './ErrorBoundary.jsx';
 
 const CALLOUT_TYPES = [
   'note',
@@ -1351,7 +1352,9 @@ function DocsPage() {
           <MDXProvider components={defaultMdxComponents}>
             <div className="velu-prose">
               {PageComponent ? (
-                <PageComponent />
+                <ErrorBoundary key={pathname} file={entry?.relPath}>
+                  <PageComponent />
+                </ErrorBoundary>
               ) : (
                 <p style={{ color: 'var(--muted-color)' }}>
                   {entry?.missing

package/src/runtime/ErrorBoundary.jsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import { ErrorCard } from 'velu-ui';
+import { extractMdxError } from '../lib/extract-mdx-error.js';
+import { CATEGORY_LABEL } from '../lib/issues.js';
+import { KNOWN_COMPONENTS } from '../lib/known-components.js';
+
+/**
+ * Catches render-time errors from the current page (unknown component, a
+ * component that threw on a bad prop, etc.) and renders a branded ErrorCard in
+ * its place — leaving the surrounding chrome (header, sidebar, TOC) mounted.
+ *
+ * This is the CLIENT-side safety net: when the reader navigates (react-router,
+ * no full reload) to a page that throws, the chrome stays put and only the
+ * body shows the card. On a direct load / reload of a broken page the error
+ * happens during SSR instead — React's renderToString doesn't recover through
+ * error boundaries, so the dev server catches it there and serves the
+ * full-page branded error (and logs it to the terminal).
+ *
+ * In `App.jsx` it's keyed by `pathname`, so navigating to another page (or
+ * fixing the file and reloading) remounts it and clears the error.
+ */
+export default class ErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+
+    const issue = extractMdxError(error, {
+      knownComponents: KNOWN_COMPONENTS,
+      file: this.props.file || null,
+    });
+    return (
+      <ErrorCard
+        label={CATEGORY_LABEL[issue.category] || issue.category}
+        title={issue.title}
+        file={issue.file}
+        line={issue.line}
+        column={issue.column}
+        frame={issue.frame}
+        detail={issue.detail}
+        hint={issue.hint}
+        suggestion={issue.suggestion}
+      />
+    );
+  }
+}