@veluai/velu 0.2.36 → 0.2.38

package/docs/mintlify-migration.md

@@ -0,0 +1,159 @@
+# Migrate Mintlify documentation to Velu
+
+```sh
+velu migrate mintlify ./mintlify-docs --out ./velu-docs --dry-run
+velu migrate mintlify ./mintlify-docs --out ./velu-docs
+cd velu-docs
+velu validate .
+velu dev .
+```
+
+From this repository, replace `velu` with `node packages/velu-cli/bin/cli.js`.
+The command is included in the bundled public CLI. It has not been published
+until a package release is made.
+
+The source is a local repository/content directory containing `docs.json` or
+legacy `mint.json`. The command creates a **new directory** and leaves the source
+untouched. Without `--out`, it creates a sibling named `<source>-velu`. Existing
+destinations, destinations inside the source, and filename collisions are rejected.
+Files are staged before the completed directory is moved into place.
+
+`docs.json` takes precedence if both configs exist. Use `--config mint.json` to
+select the legacy file. JSON comments/trailing commas and local JSON/YAML config
+`$ref` files are supported. Config references cannot escape the source directory;
+remote references, fragments, and cycles fail with an explicit error.
+
+## Preview and CI
+
+| Option | Behavior |
+| --- | --- |
+| `--dry-run` | Runs analysis, transformations, and MDX compilation in memory; writes nothing |
+| `--json` | Prints only the machine-readable report |
+| `--strict` | Refuses to write output if there are warnings or errors |
+| `--out <directory>` | Sets the new destination |
+| `--config docs.json\|mint.json` | Selects the source configuration |
+| `--help` | Prints usage |
+
+Exit codes are `0` for completion without compatibility errors, `1` for invocation
+or filesystem failures, `2` for compatibility errors, and `3` when strict mode
+requires review. **Normal mode writes a reviewable migration even with code 2.**
+Warnings alone return 0 unless strict mode is enabled. The report still labels
+any migration with findings `needs-review`.
+
+Every migration writes `VELU-MIGRATION.md` and `velu-migration-report.json`.
+It also archives the fully resolved original config in
+`.velu-migration/source-config.json`, outside the publicly served assets.
+The JSON report includes per-file actions and SHA-256 output hashes, script
+conversions, skipped paths, and findings with source locations. Reports do not
+contain source script bodies or unsupported config values. They can contain
+filenames, endpoint paths, and diagnostic text; review before sharing.
+
+## Coverage
+
+| Area | Migration behavior |
+| --- | --- |
+| Config | Projects supported values against the shipped Velu schema; reports unsupported nested fields individually and preserves the original source config |
+| Legacy config | Converts navigation arrays, prefix-based tabs, anchors, topbar links/CTA, footer socials, and API base URL/example languages |
+| Navigation | Retains groups, tabs, products, versions, languages, root pages, and supported OpenAPI references; maps simple dropdown containers to tabs and merges global anchors/tabs with a review finding |
+| Branding | Copies logos/favicons, colors, navbar/footer, contextual menu and SEO; maps `description` to SEO metadata, body font family to `font`, and a dual favicon to one local variant |
+| Content | Converts content `.md` to `.mdx`; preserves frontmatter, prose, fenced examples, MDX expressions, and local components; compiles every migrated MDX file |
+| Components | Maps Note/Tip/Warning/Info/Check/Danger to Callout, ParamField/ResponseField to Field, Expandable to Accordion, CardGroup `cols` to `limit`, and Accordion `default-open` to `defaultOpen` |
+| React adapters | Adds an editable `snippets/velu-mintlify-compat.jsx` for Tabs/Tab, Frame, Tooltip, Badge, Button, and Panel; imports only used adapters into each MDX page |
+| Snippets | Preserves JSX/TSX modules; converts snippet-directory `.js` files to `.jsx` to avoid global execution; updates MDX and JS/TS module imports, including root-relative and extensionless imports |
+| Custom JavaScript | Preserves browser `.js` files byte-for-byte and inventories their execution risks; Velu loads them after hydration, once per full page load, in path order |
+| Custom CSS | Preserves styles; parses declarations to rewrite relative `url(...)` asset references to site-root paths; reports selectors/imports needing review |
+| Assets | Copies files and mirrors ordinary images, fonts, media, downloads, CSS/JS, and explicitly linked data into `public/` for existing URLs; retains originals for branding and local imports |
+| OpenAPI navigation | Preserves specs and references, reports missing/remote sources and the need to compare generated routes |
+| OpenAPI MDX pages | Materializes `openapi: spec.json GET /path`, or `GET /path` with a root spec reference, into an editable API playground snapshot without changing the page path or removing its body; supports single local specs with internal references |
+| npm scripts | Rewrites exact `mint`/`mintlify` dev, validate, version/v, and update invocations, including common package-manager launchers; adds the running Velu version as a dev dependency when Mintlify usage is found |
+| Ignore rules | Honors `.mintignore` using gitignore semantics, including negation; excludes dependencies, build caches, environment files, and known tooling directories |
+| Project tooling | Preserves shell scripts, package manifests, lockfiles, and CI workflows; flags Mintlify commands requiring manual replacement |
+
+## Custom scripts and remaining work
+
+Migration never executes project scripts, installs dependencies, or downloads
+remote assets/specs. Run your package manager afterward when `package.json` has
+changed; lockfiles and Mintlify dependencies are retained for review.
+
+Mintlify and Velu share many DOM selectors, but arbitrary JavaScript cannot be
+translated reliably without understanding its behavior. The report identifies
+Mintlify browser APIs (`window.mintlify`, user events), Next.js internals,
+DOMContentLoaded/load timing, module syntax in classic scripts, Node.js code in
+globally loaded `.js` files, and DOM-dependent code. These checks are static
+heuristics, not proof of complete runtime parity. For DOM-ready callbacks, check
+`document.readyState` and initialize immediately when the event has already fired.
+Verify behavior after client-side navigation as well as a full refresh.
+
+The `css-dom` finding flags styles aimed at shared chrome IDs such as `#content`,
+`#sidebar-content`, and `#footer`. Vepa aligns these common hooks with Sequoia,
+including a content-body-only `#content` and route-specific body remounting, but
+a shared ID does not guarantee identical nesting or dimensions for every component.
+Selectors are preserved for review,
+not automatically rewritten. Compare desktop and mobile pages with custom CSS
+enabled; successful asset copying is not a visual parity score.
+
+Endpoint snapshots are exported as `veluApi` metadata in MDX. Velu uses this
+metadata for API layout, request/response samples, and sidebar method badges;
+the original MDX body appears between the Try It bar and schema fields. Keep
+the export when editing a migrated endpoint. Re-migrate after OpenAPI changes
+to regenerate the snapshot.
+
+Files under `public/` and dot directories are not automatically loaded by Velu;
+their inclusion needs review. Root `.js` files are deliberately not rewritten
+because blindly changing lifecycle logic, globals, or selectors can alter behavior.
+Place Node tooling outside the docs content root or use `.cjs`/`.mjs` so it is not
+loaded as a browser script.
+
+The React adapters preserve basic interactions, not every Mintlify prop or exact
+appearance. Panel renders inline, Tooltip uses a text-only native tooltip, and
+Tabs supports keyboard navigation but does not synchronize selections across
+separate tab groups. Unknown components are reported as errors instead of being
+replaced with empty placeholders. Font Awesome/Tabler icon names may need Lucide
+equivalents. Original references in code examples and prose remain unchanged.
+
+Mintlify's `theme: "sequoia"` is converted to `theme: "vepa"` and activates the [Vepa preset](vepa.md).
+The preset is not a certification of pixel equality for every component or custom script.
+
+Features without full Velu equivalents require review: other Mintlify themes, advanced
+fonts and styling, redirects, analytics/support integrations, hosting settings,
+authentication, personalization, hidden-page routing, legacy version filtering,
+complex dropdown/global navigation, AsyncAPI, manually authored `api:` pages,
+multi-file/remote endpoint snapshots, OpenAPI overlays and `x-mint` extensions.
+Access/visibility settings are reported as errors; they must be migrated before
+publishing. Unlisted content is copied but Velu currently renders navigation
+pages only. Snapshot API pages must be regenerated or edited when their specs
+change. Existing generated robots/sitemap/LLM files can still contain old domains.
+
+`mint broken-links`, `mint a11y`, `mint export`, cloud/account commands, compound
+shell commands, and CLI flags have no automatically assumed equivalent. These
+scripts and workflows are retained with findings. In particular, `velu validate`
+is not a complete replacement for Mintlify's separate broken-link/a11y tools,
+and the public Velu package does not expose the internal static build command.
+
+## Parity research
+
+Inspected on 2026-09-08:
+
+- Published [`@mintlify/cli@4.0.1479`](https://www.npmjs.com/package/@mintlify/cli/v/4.0.1479): command dispatch/options in `bin/cli.js`; starter source in `bin/init.js`.
+- Published [`@mintlify/common@1.0.1132`](https://www.npmjs.com/package/@mintlify/common/v/1.0.1132): content/snippet categories and `.mintignore` semantics in `dist/getFileCategory.js` and `dist/mintIgnore.js`.
+- Published [`@mintlify/prebuild@1.0.1286`](https://www.npmjs.com/package/@mintlify/prebuild/v/1.0.1286): split config references and config loading.
+- [`docs.json` schema](https://www.mintlify.com/docs.json), [custom scripts documentation](https://www.mintlify.com/docs/customize/custom-scripts), and [official starter](https://github.com/mintlify/starter).
+
+The current `@mintlify/validation@0.1.849` tarball was also retrieved, but it did
+not contain its declared `dist/` implementation. Legacy conversion is implemented
+locally; it does not depend on executing Mintlify's upgrade code. No Mintlify
+implementation code or package is vendored as a runtime dependency.
+
+## Verification
+
+```sh
+node --test packages/velu-cli/test/migrate.test.mjs
+node --test packages/velu-cli/test/*.test.mjs
+node packages/velu-cli/scripts/build.mjs
+node packages/velu-cli/dist/cli.js migrate --help
+```
+
+Tests cover clean and review-required outputs, source immutability, JSONC/YAML
+references, ignore negation, collisions/junctions, script preservation, AST
+rewrites, assets, endpoint snapshots, generated-project validation, and CLI exit
+codes. No network is needed for the migration tests.

package/docs/vepa.md

@@ -0,0 +1,97 @@
+# Vepa (வேப்பம்) compatibility
+
+Enable the preset in `velu.json`:
+
+```json
+{
+  "name": "Documentation",
+  "theme": "vepa",
+  "colors": { "primary": "#16A34A", "light": "#07C983" },
+  "navigation": { "groups": [{ "group": "Guide", "pages": ["index"] }] }
+}
+```
+
+Mintlify migration converts `theme: "sequoia"` to `theme: "vepa"`. The normal Velu appearance is
+still the default when `theme` is omitted. The visual preset is separate from
+the reader's Light / Dark / System preference.
+
+For Vepa, `colors.primary` is the light-mode accent and `colors.light` is the
+dark-mode accent, matching Mintlify. The primary color also tints the gray ramp.
+`font.family` overrides Inter. Development, prerendered builds, and the browser
+preview share these normalizers.
+
+## Reference inspected
+
+The npm CLI does not ship the renderer inside its own package. Its previewing
+dependency retrieves a separately versioned client from Mintlify's release host.
+Research was pinned on 2026-09-08 to:
+
+- [`@mintlify/cli@4.0.1479`](https://www.npmjs.com/package/@mintlify/cli/v/4.0.1479)
+- [`@mintlify/previewing@4.0.1358`](https://www.npmjs.com/package/@mintlify/previewing/v/4.0.1358), `dist/constants.js`, `dist/util.js`, and `dist/local-preview/client.js`
+- [Client 0.0.3566](https://releases.mintlify.com/mint-0.0.3566.tar.gz), compiled Sequoia topbar, sidebar, page-header, and TOC modules
+- [`@mintlify/common@1.0.1132`](https://www.npmjs.com/package/@mintlify/common/v/1.0.1132), color composition
+
+Client archive SHA-256:
+`a2b758fd67159a066e14fa7e78599047b0fd7f5ae78477e7364efdc232ef7ee5`
+
+The downloaded client is research material only. It is not included in Velu's
+published package or used at runtime.
+
+## Measured geometry
+
+| Region | Vepa preset |
+| --- | --- |
+| Desktop topbar | 48 px; navigation tabs add 48 px |
+| Logo | 22 px high |
+| Desktop search trigger | 256 × 32 px |
+| Left sidebar | 288 px |
+| Default article at 1440 px viewport | 648 px; left edge 396 px |
+| Table of contents | 288 px rail with 32 px side padding |
+| API examples | 472 px rail including a 24 px outer gutter; 448 px sample cards |
+| API rail breakpoint | Hidden below 1280 px; article reclaims its space |
+| On-page TOC bar | Sticky TocBar below 1280 px (when the right rail hides), same as default Velu |
+| Mobile navigation | Below 640 px; crumbs + burger (tabs stay on tablet with horizontal scroll) |
+| Title | Inter, 500 weight, 36/40 px; 30/36 px below 640 px |
+
+The API rail deliberately has its own width and padding. Applying the normal
+TOC's width leaves too little room for request tabs and response examples. Long
+code lines scroll inside their code panel instead of widening the page.
+
+The preset includes a plain TOC, tinted light/dark surfaces, a three-way theme
+menu, responsive columns, and mode-specific content widths. Card links retain
+their destinations, and navigation uses `sidebarTitle` when supplied.
+
+For custom styles, Vepa exposes `#page-title` on the title, `#content` on the
+ordinary MDX body (excluding the header), and `#sidebar-content` on the sidebar.
+The MDX body remounts on route changes so DOM decorations do not leak into the
+next page. Body font overrides inherit into prose; component headings retain
+their own typography. API pages use their own content structure.
+
+Migrated endpoint MDX exports a `veluApi` snapshot containing the operation,
+samples, and API settings. Both runtimes use it to activate the API layout and
+navigation method badges. Author imports and exports stay at module scope;
+custom content renders after the Try It bar and before the schema fields.
+
+## Verification and limits
+
+```sh
+node --test packages/velu-cli/test/vepa.test.mjs
+node packages/velu-cli/scripts/check-vepa-layout.mjs http://localhost:8358 /api-reference/products/listproducts /api-reference/products/addproduct
+```
+
+The browser check covers GET/POST pages at 1440, 1280, 1100, 768, and 390 px in
+light/dark mode. It checks rail size, sample width, column overlap, document
+overflow, closed drawers, language tabs, system preference changes, and runtime
+errors. Supply routes from your own running site.
+
+This is a source-informed compatibility preset, **not yet verified pixel-for-pixel
+across Mintlify's complete component/state matrix**. Velu still uses its own
+search, API playground, syntax highlighting, icons, feedback, and content
+components. Font availability can also affect screenshots. Hosted Mintlify
+services are not reproduced by copying theme settings. Custom scripts and CSS
+that depend on Mintlify's exact DOM, globals, lifecycle, or unsupported components
+need testing on the migrated site.
+
+Below the API rail breakpoint, samples move inline after the Try It bar and
+before custom content. Inline and desktop samples use distinct IDs. This
+document records the current scope rather than asserting complete parity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veluai/velu",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "type": "module",
   "bin": "./dist/cli.js",
   "publishConfig": {
@@ -16,7 +16,9 @@
     "src/lib/known-components.js",
     "runtime/velu-ui/**",
     "schema/**",
-    "templates/**"
+    "templates/**",
+    "docs/mintlify-migration.md",
+    "docs/vepa.md"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -26,6 +28,7 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
+    "@babel/parser": "7.28.0",
     "@icons-pack/react-simple-icons": ">=13.0.0 <13.13.0",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
@@ -36,10 +39,13 @@
     "estree-util-value-to-estree": "^3.5.0",
     "express": "^4.21.1",
     "github-slugger": "^2.0.0",
+    "ignore": "7.0.5",
     "iso-639-1": "^3.1.5",
     "js-yaml": "^4.1.0",
+    "jsonc-parser": "3.3.1",
     "lucide-react": "^0.460.0",
     "mdast-util-to-string": "^4.0.0",
+    "postcss": "8.5.0",
     "prism-react-renderer": "^2.4.0",
     "prismjs": "^1.29.0",
     "react": "^18.3.1",

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

@@ -27,7 +27,7 @@ import { sendApiRequest } from '../lib/api-send.js';
  */
 const LOCATION_LABEL = { path: 'Path Parameters', query: 'Query Parameters', header: 'Header Parameters' };
 
-export default function ApiReferencePage({ operation, samples = [], apiOperations = [], api = {} }) {
+export default function ApiReferencePage({ operation, samples = [], apiOperations = [], api = {}, children, preset }) {
   const [open, setOpen] = useState(false);
   // Which operation the playground is currently showing. Defaults to this
   // page's own operation; the dropdown can switch it to any sibling.
@@ -78,6 +78,9 @@ export default function ApiReferencePage({ operation, samples = [], apiOperation
         className="velu-api-page__tryit"
       />
 
+      {preset === 'vepa' && <div className="velu-api-page__inline-samples"><ApiSamples idPrefix="inline-" samples={samples} responses={operation.responses} preset={preset} title={operation.title} /></div>}
+      {children && <div className="velu-api-page__custom-content">{children}</div>}
+
       {/* Authorizations */}
       {operation.auth?.length > 0 && (
         <api-section class="velu-api-page__section">
@@ -124,7 +127,7 @@ export default function ApiReferencePage({ operation, samples = [], apiOperation
       {operation.responses?.length > 0 && (
         <api-section class="velu-api-page__section">
           <h2 data-component="api-section-heading">Response</h2>
-          <ResponseSections responses={operation.responses} />
+          <ResponseSections responses={operation.responses} preset={preset} />
         </api-section>
       )}
 
@@ -175,7 +178,12 @@ function EnumHint({ values }) {
   );
 }
 
-function ResponseSections({ responses }) {
+function ResponseSections({ responses, preset }) {
+  if (preset === 'vepa') return <div className="velu-vepa-responses">{responses.map((r, i) => <section key={i}>
+    <div className="velu-vepa-responses__status">{r.status}{r.contentType && ` · ${r.contentType}`}</div>
+    {r.description && <p>{r.description}</p>}
+    {r.fields?.map((f, j) => <Field key={j} name={f.name} type={f.type} required={f.required}>{f.description}</Field>)}
+  </section>)}</div>;
   return (
     <AccordionGroup className="velu-api-resp">
       {responses.map((r, i) => {

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

@@ -9,12 +9,17 @@ import CodeBlock, { CodeGroup } from './CodeBlock.jsx';
  *
  * @param {{ samples: {key,label,language,code}[], responses: object[] }} props
  */
-export default function ApiSamples({ samples = [], responses = [] }) {
+export default function ApiSamples({ samples = [], responses = [], preset, title, idPrefix = '' }) {
+  const [selected, setSelected] = React.useState('');
+  const sample = samples.find((s) => s.key === selected) || samples[0];
   const withExample = responses.filter((r) => r.example != null);
   return (
     <div className="velu-api-samples">
-      {samples.length > 0 && (
-        <CodeGroup id="request-example" className="velu-api-samples__req">
+      {sample && preset === 'vepa' ? <section id={idPrefix + 'request-example'} className="velu-vepa-request">
+        <div className="velu-vepa-request__header"><span>{title}</span><select aria-label="Request example language" value={sample.key} onChange={(e) => setSelected(e.target.value)}>{samples.map((s) => <option key={s.key} value={s.key}>{s.label}</option>)}</select></div>
+        <CodeBlock language={sample.language}>{sample.code}</CodeBlock>
+      </section> : samples.length > 0 && (
+        <CodeGroup id={idPrefix + 'request-example'} className="velu-api-samples__req">
           {samples.map((s) => (
             <CodeBlock key={s.key} title={s.label} language={s.language}>
               {s.code}
@@ -23,7 +28,7 @@ export default function ApiSamples({ samples = [], responses = [] }) {
         </CodeGroup>
       )}
       {withExample.length > 0 && (
-        <CodeGroup id="response-example" className="velu-api-samples__res">
+        <CodeGroup id={idPrefix + 'response-example'} className="velu-api-samples__res">
           {withExample.map((r) => (
             <CodeBlock key={r.status} title={r.status} language="json">
               {JSON.stringify(r.example, null, 2)}

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

@@ -5,9 +5,9 @@ import Switcher from '../primitives/Switcher.jsx';
 /**
  * Card + CardGroup — content / horizontal / image / CTA cards.
  *
- * The card itself is NEVER a link and has NO hover state. The only
- * interactive element is the CTA: pass `cta={{ label, href }}` to render a
- * single "Click Here ›" link. Everything else is static presentation.
+ * Pass `href` (without `cta`) to make the whole card a stretched link.
+ * Nested links/buttons inside the card stay clickable above that overlay.
+ * Pass `cta={{ label, href }}` for a single "Click Here ›" control instead.
  *
  * Fully tokenized (border-width, border-color, radius scale, spacing, type,
  * line-height, accent, icon-stroke) → light/dark automatic via [data-theme].
@@ -22,7 +22,7 @@ import Switcher from '../primitives/Switcher.jsx';
  * `icon` is a lucide id string (shared resolveIcon).
  *
  * @param {{ title?: React.ReactNode, icon?: string, horizontal?: boolean,
- *   img?: string, imgAlt?: string,
+ *   img?: string, imgAlt?: string, href?: string,
  *   cta?: {label: React.ReactNode, href: string},
  *   children?: React.ReactNode, className?: string }} props
  */
@@ -34,6 +34,7 @@ export function Card({
   img,
   imgAlt = '',
   cta,
+  href,
   children,
   className = '',
   ...rest
@@ -72,6 +73,7 @@ export function Card({
 
   return (
     <card className={cls} {...rest}>
+      {href && !cta && <a className="velu-card__link" href={href} aria-label={typeof title === 'string' ? title : 'Read more'} />}
       {img && (
         <div className="velu-card__media" data-component-part="card-image">
           <img src={img} alt={imgAlt} loading="lazy" />
@@ -122,6 +124,7 @@ export function CardGroup({
       space={space}
       min={min}
       limit={limit}
+      style={{ '--vepa-columns': Math.max(1, Math.min(4, Number(limit) || 2)) }}
       {...rest}
     >
       {children}

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

@@ -336,7 +336,7 @@ function renderStream(tokens, sources, onNavigate) {
 }
 
 /* ── Header ─────────────────────────────────────────────────────────── */
-function ChatHeader({ onClose, onNew, onHistory, historyOpen }) {
+function ChatHeader({ onClose, onNew, onHistory, historyOpen, showClose = true }) {
   return (
     <Cluster
       as="chat-assistant-sheet-header"
@@ -370,6 +370,7 @@ function ChatHeader({ onClose, onNew, onHistory, historyOpen }) {
         >
           {resolveIcon('plus', { size: '1em' })}
         </button>
+        {showClose && (
         <button
           type="button"
           className="velu-chatbot__iconbtn"
@@ -378,6 +379,7 @@ function ChatHeader({ onClose, onNew, onHistory, historyOpen }) {
         >
           {resolveIcon('x', { size: '1em' })}
         </button>
+        )}
       </Cluster>
     </Cluster>
   );
@@ -655,6 +657,7 @@ export default function Chatbot({
   listHistory,
   loadConversation,
   suggestions,
+  layout = 'panel',
   className = '',
   ...rest
 }) {
@@ -882,8 +885,9 @@ export default function Chatbot({
   const isBottomSheet = () =>
     typeof window !== 'undefined' &&
     window.matchMedia('(max-width: 1024px)').matches;
+  const isPage = layout === 'page';
   const onDragStart = (e) => {
-    if (!isBottomSheet()) return;
+    if (isPage || !isBottomSheet()) return;
     dragRef.current = { active: true, startY: e.clientY, currentY: 0 };
     e.currentTarget.setPointerCapture?.(e.pointerId);
   };
@@ -906,7 +910,7 @@ export default function Chatbot({
     if (!open) setDragOffset(0);
   }, [open]);
 
-  const cls = `velu-chatbot${open ? ' velu-chatbot--open' : ''} ${className}`.trim();
+  const cls = `velu-chatbot${open || isPage ? ' velu-chatbot--open' : ''}${isPage ? ' velu-chatbot--page' : ''} ${className}`.trim();
   const dragStyle =
     dragOffset > 0
       ? { transform: `translateY(${dragOffset}px)`, transition: 'none' }
@@ -917,7 +921,7 @@ export default function Chatbot({
       id="chat-assistant-sheet"
       data-component="chat-assistant-sheet"
       className={cls}
-      aria-hidden={!open}
+      aria-hidden={isPage ? false : !open}
       aria-label="Ask AI"
       style={dragStyle}
       {...rest}
@@ -939,6 +943,7 @@ export default function Chatbot({
         onNew={newChat}
         onHistory={() => setHistoryOpen((o) => !o)}
         historyOpen={historyOpen}
+        showClose={!isPage}
       />
 
       {historyOpen && (

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

@@ -49,6 +49,7 @@ export default function Columns({
       space={space}
       min={min}
       limit={cols}
+      style={{ '--vepa-columns': Math.max(1, Math.min(4, Number(cols) || 2)) }}
       {...rest}
     >
       {children}

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

@@ -1,4 +1,5 @@
 import React from 'react';
+import VepaFooter from './VepaFooter.jsx';
 import Stack from '../primitives/Stack.jsx';
 import Cluster from '../primitives/Cluster.jsx';
 import SocialLinks from './SocialLinks.jsx';
@@ -67,6 +68,7 @@ function VeluMark() {
 }
 
 export default function PageFooter({
+  preset,
   brand,
   columns = [],
   socials = [],
@@ -75,6 +77,7 @@ export default function PageFooter({
   ...rest
 }) {
   const Link = linkComponent;
+  if (preset === 'vepa') return <VepaFooter brand={brand} columns={columns} socials={socials} linkComponent={Link} />;
   const brandLabel = brand?.label ?? 'Velu';
   const brandHref = brand?.href;
 

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

@@ -74,7 +74,7 @@ function ActionButton({ action, Link, id }) {
   // Mintlify-compatible hooks: `#topbar-cta-button` on the first primary
   // action, `[data-component="navbar-link"]` on every action (overridable per
   // action, e.g. component: 'logout-link').
-  const hooks = { id, 'data-component': component ?? 'navbar-link' };
+  const hooks = { id, 'data-component': component ?? 'navbar-link', 'data-component-name': kind === 'primary' ? 'primary-header-button' : undefined };
   const content = (
     <>
       {icon && (
@@ -232,6 +232,7 @@ function KebabMenu({ actions, Link }) {
 }
 
 export default function PageHeader({
+  preset,
   brand,
   brandTrailing,
   center,
@@ -266,6 +267,12 @@ export default function PageHeader({
     return () => window.removeEventListener('scroll', onScroll);
   }, []);
 
+  const showTabsRow =
+    tabs.length > 0 ||
+    (breadcrumb && breadcrumb.length > 0) ||
+    Boolean(tabsTrailing) ||
+    Boolean(onMenuClick);
+
   // A configured logo replaces the mark + wordmark entirely (Mintlify-style).
   const brandBlock = (
     <Cluster space="var(--s-3)" align="center" className="velu-header__brand" style={{ flexWrap: 'nowrap' }}>
@@ -283,8 +290,11 @@ export default function PageHeader({
   return (
     <Stack
       as="header"
-      space="var(--s0)"
-      className={`velu-header${scrolled ? ' velu-header--scrolled' : ''} ${className}`.trim()}
+      space={preset === 'vepa' ? '0px' : 'var(--s0)'}
+      data-has-tabs={tabs.length > 0 ? 'true' : 'false'}
+      className={`velu-header${scrolled ? ' velu-header--scrolled' : ''}${
+        showTabsRow ? '' : ' velu-header--no-tabs'
+      } ${className}`.trim()}
       {...rest}
     >
       {/* Top row — 3-column grid: brand | center | actions. */}
@@ -349,10 +359,7 @@ export default function PageHeader({
           takes their place. Burger stays at the trailing edge via
           margin-inline-start: auto on the burger button itself, so
           its position is unaffected by the breadcrumb's length. */}
-      {(tabs.length > 0 ||
-        (breadcrumb && breadcrumb.length > 0) ||
-        tabsTrailing ||
-        onMenuClick) && (
+      {showTabsRow && (
         <Cluster
           as="nav-tabs"
           space="var(--s0)"

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

@@ -0,0 +1,57 @@
+import React from 'react';
+import { Sun, Moon, Monitor, Check } from 'lucide-react';
+
+export default function ThemePreferenceMenu({ inline = false }) {
+  const [open, setOpen] = React.useState(false);
+  const [preference, setPreference] = React.useState('system');
+  const root = React.useRef(null);
+  const trigger = React.useRef(null);
+  React.useEffect(() => {
+    const media = window.matchMedia('(prefers-color-scheme: dark)');
+    const sync = () => {
+      let pref = 'system';
+      try { pref = localStorage.getItem('velu-theme') || 'system'; } catch {}
+      setPreference(pref);
+      document.documentElement.dataset.theme = pref === 'system' ? (media.matches ? 'dark' : 'light') : pref;
+    };
+    sync();
+    media.addEventListener('change', sync);
+    window.addEventListener('storage', sync);
+    window.addEventListener('velu-theme-change', sync);
+    return () => { media.removeEventListener('change', sync); window.removeEventListener('storage', sync); window.removeEventListener('velu-theme-change', sync); };
+  }, []);
+  React.useEffect(() => {
+    if (!open) return;
+    root.current?.querySelector('[aria-checked="true"]')?.focus();
+    const outside = (e) => { if (!root.current?.contains(e.target)) setOpen(false); };
+    document.addEventListener('pointerdown', outside);
+    return () => document.removeEventListener('pointerdown', outside);
+  }, [open]);
+  const choose = (value) => {
+    setPreference(value);
+    try { value === 'system' ? localStorage.removeItem('velu-theme') : localStorage.setItem('velu-theme', value); } catch {}
+    document.documentElement.dataset.theme = value === 'system' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : value;
+    window.dispatchEvent(new Event('velu-theme-change'));
+    setOpen(false);
+    trigger.current?.focus();
+  };
+  const Icon = preference === 'system' ? Monitor : preference === 'dark' ? Moon : Sun;
+  if (inline) return <div className="vepa-footer-theme" role="group" aria-label="Color theme">
+    {[[Monitor, 'system', 'System'], [Sun, 'light', 'Light'], [Moon, 'dark', 'Dark']].map(([Glyph, value, label]) => <button key={value} type="button" aria-label={`${label} theme`} aria-pressed={preference === value} onClick={() => choose(value)}><Glyph size={16} aria-hidden="true" /></button>)}
+  </div>;
+  return <div ref={root} className="velu-theme-menu" onKeyDown={(e) => {
+    if (e.key === 'Escape') { setOpen(false); trigger.current?.focus(); }
+    if (e.key === 'Tab') setOpen(false);
+    if (open && ['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) {
+      e.preventDefault();
+      const items = [...root.current.querySelectorAll('[role="menuitemradio"]')];
+      const i = items.indexOf(document.activeElement);
+      items[e.key === 'Home' ? 0 : e.key === 'End' ? 2 : (i + (e.key === 'ArrowUp' ? 2 : 1)) % 3]?.focus();
+    }
+  }}>
+    <button ref={trigger} type="button" className="velu-theme-menu__trigger" aria-label="Theme preference" aria-haspopup="menu" aria-expanded={open} onClick={() => setOpen(!open)}><Icon size={16} aria-hidden="true" /></button>
+    {open && <div className="velu-theme-menu__options" role="menu" aria-label="Theme preference">
+      {[[Sun, 'light', 'Light'], [Moon, 'dark', 'Dark'], [Monitor, 'system', 'System']].map(([Glyph, value, label]) => <button key={value} type="button" role="menuitemradio" aria-checked={preference === value} tabIndex={-1} onClick={() => choose(value)}><Glyph size={16} aria-hidden="true" /><span>{label}</span>{preference === value && <Check size={14} aria-hidden="true" />}</button>)}
+    </div>}
+  </div>;
+}

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

@@ -1,5 +1,6 @@
 import React from 'react';
 import { Sun, Moon } from 'lucide-react';
+import ThemePreferenceMenu from './ThemePreferenceMenu.jsx';
 
 /**
  * ThemeToggle — pill-shaped two-state light/dark switch. The thumb
@@ -14,7 +15,8 @@ import { Sun, Moon } from 'lucide-react';
  * explicit choice (which then overrides the OS preference on future
  * visits, per the anti-flash script in the template).
  */
-export default function ThemeToggle({ className = '', ...rest }) {
+export default function ThemeToggle({ className = '', variant, ...rest }) {
+  if (variant === 'menu') return <ThemePreferenceMenu />;
   function toggle() {
     const root = document.documentElement;
     const next = root.dataset.theme === 'dark' ? 'light' : 'dark';