@veluai/velu 0.2.38 → 0.2.40

package/docs/aalam.md

@@ -0,0 +1,44 @@
+# Aalam theme
+
+Aalam (ஆலம், banyan) is Velu's Maple equivalent. Use `"theme": "aalam"` in `velu.json`. Running `velu migrate mintlify SOURCE --out DESTINATION` maps Mintlify's `"theme": "maple"` to Aalam automatically.
+
+```json
+{
+  "name": "My docs",
+  "theme": "aalam",
+  "colors": {
+    "primary": "#C2410C",
+    "light": "#EA580C",
+    "dark": "#FB923C"
+  }
+}
+```
+
+The desktop layout places branding, search, and navigation in the left sidebar, with tabs above the article. Below 1024px, navigation becomes a left-opening drawer with a labeled section picker, focus trapping, Escape dismissal, and background scroll locking. Below 1280px, a sticky On this page dropdown replaces the right-hand TOC. Drawer and TOC hierarchy use indentation without vertical lines.
+
+Aalam shares component styles and responsive behavior with Thulir. Its desktop layout was compared with the cached npm renderer `@mintlify/client@0.0.3566` using the same showcase content. This is not a guarantee of pixel-perfect parity: theme controls, icons, compatibility adapters, generated OpenAPI examples, and custom scripts still require review. The left-opening drawer and line-free navigation intentionally follow Velu's requested behavior.
+
+Color semantics match the Mintlify presets: `colors.primary` for the light-mode accent, `colors.light` for the dark-mode accent, and `colors.dark` for CTA colors. The default font is Inter.
+
+## Page icons in the sidebar
+
+Pages can show a Lucide icon next to their sidebar label:
+
+1. Frontmatter on the MDX page:
+
+```mdx
+---
+title: Quickstart
+icon: rocket
+---
+```
+
+2. Or a page object in `velu.json` navigation:
+
+```json
+{ "page": "quickstart", "icon": "zap" }
+```
+
+Frontmatter is used when the nav entry is a plain path string. A nav `icon` wins when both are set.
+
+For the migrated component showcase, run `node packages/velu-cli/test/aalam-browser.mjs` with Playwright installed and the preview running. `VELU_TEST_URL` overrides the default `http://localhost:8473`. The checks cover phone/tablet drawer focus, dismissal, route changes, horizontal overflow, desktop resizing, section selection, content tabs, and sticky TOC heading clearance.

package/docs/mintlify-migration.md

@@ -52,7 +52,7 @@ filenames, endpoint paths, and diagnostic text; review before sharing.
 
 | Area | Migration behavior |
 | --- | --- |
-| Config | Projects supported values against the shipped Velu schema; reports unsupported nested fields individually and preserves the original source config |
+| Config | Projects supported values against the shipped Velu schema; maps Mintlify `mint` to `thulir`, `sequoia` to `vepa`, and `maple` to `aalam`; 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 |
@@ -86,6 +86,8 @@ 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,
+while Thulir preserves Mint's `#sidebar`, `#navigation-items`, `#page-title`,
+`#content`, and `#footer` structure,
 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,
@@ -112,9 +114,12 @@ 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.
+Mintlify's `theme: "mint"` is converted to `theme: "thulir"` and activates the [Thulir preset](thulir.md).
+Mintlify's `theme: "maple"` is converted to `theme: "aalam"` and activates the [Aalam preset](aalam.md).
+Mintlify's `theme: "aspen"` is converted to `theme: "nila"` and activates the [Nila preset](nila.md).
+The presets are not a certification of pixel equality for every component or custom script.
 
-Features without full Velu equivalents require review: other Mintlify themes, advanced
+Features without full Velu equivalents require review: remaining 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,
@@ -137,6 +142,7 @@ 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.
+- The CLI-downloaded `@mintlify/client@0.0.3566` renderer: Mint theme dispatch, computed layout geometry, typography, navigation, API samples, responsive behavior, and footer. The renderer was inspected for interoperability research and is not redistributed.
 - [`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

package/docs/nila.md

@@ -0,0 +1,13 @@
+# Nila theme
+
+Nila is Velu's independently implemented Aspen equivalent. Set `"theme": "nila"` in `velu.json`, or run `velu migrate mintlify SOURCE --out DESTINATION` to map Mintlify's `"theme": "aspen"` automatically. The existing `maple` to `aalam` mapping remains supported.
+
+The layout uses a compact 96px desktop header, sidebar group separators, a 632px reading column at a 1440px viewport, page icons, and light/dark/system preferences. Nila shares the responsive navigation foundation with Thulir: a left-opening drawer, labeled section picker, focus trapping, Escape dismissal, scroll locking, and an on-page TOC dropdown when the right rail is hidden. Vertical hierarchy lines remain disabled in the drawer and mobile TOC.
+
+The reference is the cached npm renderer `@mintlify/client@0.0.3566`, displaying the same source showcase. Theme matching is not a guarantee of identical component behavior: icon artwork, custom CSS selectors, compatibility adapters, generated API examples and interactive playgrounds still require review.
+
+For the migrated showcase, set `VELU_TEST_URL=http://localhost:8474` and run `node packages/velu-cli/test/aalam-browser.mjs`. This shared browser regression covers drawer behavior, section selection, content tabs, responsive widths, and TOC heading clearance.
+
+Mintlify migration enables `navigation.preservePagePaths` when the source uses product, version, or language axes. These axes select the navigation context while retaining source page URLs, rather than adding another path prefix. Native Velu configurations retain their existing prefix behavior unless they opt into this setting.
+
+The navigation stress fixture adds three products (Platform, Analytics, Automation), two versions each, and 32 guides per product/version pair. With that migrated fixture running on port 8474, `node packages/velu-cli/test/nila-navigation-browser.mjs` checks five viewport widths, sidebar scrolling, product/version switching, direct reloads, horizontal overflow, and nested Escape behavior. This fixture has 220 pages including the existing component/API showcase; its additional Guides tab differs from the original four-tab showcase used by the shared browser test above.

package/docs/thulir.md

@@ -0,0 +1,23 @@
+# Thulir theme
+
+Thulir is Velu's equivalent of Mintlify's `mint` theme. The name means a fresh sprout in Tamil.
+
+```json
+{
+  "name": "My docs",
+  "theme": "thulir",
+  "colors": {
+    "primary": "#0D9373",
+    "light": "#12A481",
+    "dark": "#46D6AD"
+  }
+}
+```
+
+`velu migrate mintlify` converts `"theme": "mint"` to `"theme": "thulir"`. Thulir preserves Mint's main renderer hooks, including `#navbar`, `#sidebar`, `#navigation-items`, `#page-title`, `#content`, and `#footer`, so portable custom CSS and browser scripts retain their targets.
+
+The preset includes Mint's desktop grid, Inter typography, navigation states, prose rhythm, compact previous/next links, API document and code columns, responsive drawer behavior, light/dark palette, and advanced footer.
+
+Mint color semantics are preserved: `colors.primary` is the light-mode accent, `colors.light` is the dark-mode accent, and `colors.dark` supplies the header button background. Missing values fall back to `colors.primary`. Header and footer theme controls share the same light/dark/system preference.
+
+The reference is the renderer downloaded by `@mintlify/cli@4.0.1479` (`@mintlify/client@0.0.3566`). Compare identical content at identical viewport sizes when checking parity. The reference fixture covers documentation, GET/POST API pages, desktop/tablet/mobile layouts, and dark mode. Generated OpenAPI example values, icon artwork, and playground interactions can still differ; matching the theme does not imply that every Mintlify component or script has identical behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veluai/velu",
-  "version": "0.2.38",
+  "version": "0.2.40",
   "type": "module",
   "bin": "./dist/cli.js",
   "publishConfig": {
@@ -18,7 +18,10 @@
     "schema/**",
     "templates/**",
     "docs/mintlify-migration.md",
-    "docs/vepa.md"
+    "docs/vepa.md",
+    "docs/thulir.md",
+    "docs/aalam.md",
+    "docs/nila.md"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",

package/runtime/velu-ui/base.css

@@ -389,6 +389,14 @@
   background: var(--muted-color);
 }
 
+/* Kill document-level horizontal scroll. Sticky header + fixed rails
+   share the viewport scrollport — if anything widens the page, the
+   whole chrome (top bar included) slides sideways. Clip here so wide
+   children must scroll inside their own containers instead. */
+html {
+  overflow-x: clip;
+}
+
 /* Unitless line-height ratios (height ÷ font-size from Figma) */
 body {
   font-size: var(--f-body);
@@ -396,6 +404,7 @@ body {
   font-weight: var(--weight-normal);
   background: var(--page-bg);
   color: var(--text-color);
+  overflow-x: clip;
 }
 h1   { font-size: var(--f-h1);   line-height: var(--lh-h1); font-weight: var(--weight-semibold); }
 h2   { font-size: var(--f-h2);   line-height: var(--lh-h2); font-weight: var(--weight-medium); }

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

@@ -78,7 +78,7 @@ 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>}
+      {(preset === 'vepa' || ['thulir', 'aalam', 'nila'].includes(preset)) && <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 */}
@@ -114,6 +114,7 @@ export default function ApiReferencePage({ operation, samples = [], apiOperation
       {operation.body?.fields?.length > 0 && (
         <api-section class="velu-api-page__section">
           <h2 data-component="api-section-heading">Body</h2>
+          {['thulir', 'aalam', 'nila'].includes(preset) && operation.body.contentType && <span className="velu-api-body-type">{operation.body.contentType}</span>}
           {operation.body.fields.map((f, i) => (
             <Field key={i} name={f.name} type={f.type} required={f.required}>
               {f.description}
@@ -179,10 +180,10 @@ function EnumHint({ values }) {
 }
 
 function ResponseSections({ responses, preset }) {
-  if (preset === 'vepa') return <div className="velu-vepa-responses">{responses.map((r, i) => <section key={i}>
+  if (preset === 'vepa' || ['thulir', 'aalam', 'nila'].includes(preset)) 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>)}
+    {(['thulir', 'aalam', 'nila'].includes(preset) ? [...(r.fields || [])].sort((a, b) => Number(Boolean(b.required)) - Number(Boolean(a.required))) : r.fields)?.map((f, j) => <Field key={f.name || j} name={f.name} type={f.type} required={f.required}>{f.description}</Field>)}
   </section>)}</div>;
   return (
     <AccordionGroup className="velu-api-resp">

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

@@ -12,12 +12,19 @@ import CodeBlock, { CodeGroup } from './CodeBlock.jsx';
 export default function ApiSamples({ samples = [], responses = [], preset, title, idPrefix = '' }) {
   const [selected, setSelected] = React.useState('');
   const sample = samples.find((s) => s.key === selected) || samples[0];
+  // Mint displays JSON request bodies across lines. Keep custom/non-JSON
+  // snippets intact, and change whitespace only in a valid JSON body.
+  const sampleCode = ['thulir', 'aalam', 'nila'].includes(preset) && sample?.key === 'curl'
+    ? sample.code.replace(/(--data )'([\s\S]*)'$/, (original, prefix, body) => {
+      try { return `${prefix}'\n${JSON.stringify(JSON.parse(body), null, 2)}\n'`; }
+      catch { return original; }
+    }) : sample?.code;
   const withExample = responses.filter((r) => r.example != null);
   return (
     <div className="velu-api-samples">
-      {sample && preset === 'vepa' ? <section id={idPrefix + 'request-example'} className="velu-vepa-request">
+      {sample && (preset === 'vepa' || ['thulir', 'aalam', 'nila'].includes(preset)) ? <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>
+        <CodeBlock language={sample.language}>{sampleCode}</CodeBlock>
       </section> : samples.length > 0 && (
         <CodeGroup id={idPrefix + 'request-example'} className="velu-api-samples__req">
           {samples.map((s) => (

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

@@ -90,7 +90,10 @@ export default function Callout({
     >
       {iconNode && (
         <span className="velu-callout__icon" aria-hidden="true">
-          {iconNode}
+          {type === 'note' && icon == null ? <>
+            <span className="velu-callout__default-note">{iconNode}</span>
+            <span className="velu-callout__mint-note" style={{ display: 'none' }}>{resolveIcon('circle-alert', { size: '1em' })}</span>
+          </> : iconNode}
         </span>
       )}
       {children}

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

@@ -33,21 +33,6 @@ import Cluster from '../primitives/Cluster.jsx';
  * demo answer (so dev preview / offline still shows the experience).
  */
 
-/* ── Brand mark — the Velu double-hook logo ─────────────────────────── */
-// `size` is the glyph height; width derives from the 32:24 viewBox.
-function VeluMark({ size = 'var(--icon-size-lg)' }) {
-  return (
-    <svg
-      className="velu-chatbot__mark"
-      viewBox="0 0 32 24"
-      fill="currentColor"
-      aria-hidden="true"
-      style={{ width: `calc(${size} * (32 / 24))`, height: size }}
-    >
-      <path d="M 29.656 14.153 C 29.574 14.562 29.351 14.929 29.025 15.193 C 28.699 15.457 28.291 15.601 27.869 15.601 L 21.37 15.601 C 20.534 15.601 19.805 16.163 19.603 16.964 L 18.167 22.637 C 18.068 23.026 17.841 23.372 17.521 23.619 C 17.2 23.866 16.805 24 16.399 24 L 10.438 24 C 10.161 24 9.888 23.938 9.639 23.818 C 9.39 23.698 9.172 23.524 9.001 23.308 C 8.831 23.092 8.712 22.841 8.655 22.574 C 8.598 22.306 8.603 22.029 8.67 21.764 L 10.189 15.764 C 10.287 15.374 10.515 15.029 10.835 14.782 C 11.155 14.535 11.55 14.401 11.956 14.4 L 18.393 14.4 C 19.262 14.4 20.01 13.795 20.18 12.953 L 22.388 2.048 C 22.471 1.639 22.694 1.272 23.019 1.008 C 23.345 0.744 23.754 0.6 24.175 0.6 L 30.177 0.6 C 30.447 0.6 30.713 0.659 30.957 0.773 C 31.201 0.886 31.416 1.052 31.587 1.258 C 31.758 1.464 31.881 1.705 31.946 1.964 C 32.011 2.222 32.017 2.492 31.964 2.753 L 29.656 14.153 Z M 9.611 13.554 C 9.528 13.962 9.305 14.329 8.979 14.593 C 8.653 14.857 8.245 15.001 7.824 15.001 L 1.823 15.001 C 1.553 15.001 1.287 14.942 1.043 14.828 C 0.799 14.714 0.584 14.548 0.413 14.342 C 0.242 14.136 0.119 13.895 0.054 13.637 C -0.011 13.378 -0.017 13.109 0.036 12.848 L 2.344 1.447 C 2.426 1.039 2.649 0.672 2.975 0.408 C 3.301 0.144 3.709 0 4.131 0 L 10.132 0 C 10.402 0 10.668 0.059 10.912 0.173 C 11.155 0.287 11.371 0.453 11.541 0.659 C 11.712 0.865 11.835 1.106 11.9 1.364 C 11.965 1.623 11.972 1.892 11.919 2.153 L 9.611 13.553 L 9.611 13.554 Z" />
-    </svg>
-  );
-}
 
 /* ── "Thinking" loader — 3x3 grid of squares, opacity wave sweeps the
    anti-diagonal so it ripples top-left → bottom-right. ─────────────── */
@@ -346,7 +331,6 @@ function ChatHeader({ onClose, onNew, onHistory, historyOpen, showClose = true }
       className="velu-chatbot__header"
     >
       <Cluster space="var(--s-2)" align="center">
-        <VeluMark />
         <span className="velu-chatbot__brand">
           <span className="velu-chatbot__brand-name">Velu</span>
           <span className="velu-chatbot__brand-sep">/</span>

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

@@ -49,7 +49,7 @@ export default function NavSelect({
       if (!rootRef.current?.contains(e.target)) setOpen(false);
     };
     const onKey = (e) => {
-      if (e.key === 'Escape') setOpen(false);
+      if (e.key === 'Escape') { setOpen(false); rootRef.current?.querySelector('button')?.focus(); }
     };
     document.addEventListener('mousedown', onDoc);
     document.addEventListener('keydown', onKey);
@@ -124,3 +124,4 @@ export default function NavSelect({
     </div>
   );
 }
+

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

@@ -47,26 +47,6 @@ import SocialLinks from './SocialLinks.jsx';
  *           linkComponent?: React.ElementType, className?: string }} props
  */
 
-/* ── Brand mark — the Velu double-hook logo. Color: currentColor for
-   the surrounding wordmark; the mark itself uses --accent-color via
-   the wrapping span. ───────────────────────────────────────────────── */
-function VeluMark() {
-  return (
-    <svg
-      className="velu-footer__mark"
-      viewBox="0 0 32 24"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M29.6564 14.1534C29.5739 14.5616 29.3507 14.9288 29.0248 15.1926C28.699 15.4565 28.2907 15.6007 27.8694 15.6006H21.3702C20.5341 15.6006 19.8051 16.1627 19.6031 16.9638L18.1671 22.6368C18.0685 23.0263 17.8409 23.372 17.5205 23.619C17.2002 23.866 16.8054 24.0001 16.399 24H10.4378C10.1609 24.0001 9.88759 23.9378 9.63868 23.8179C9.38976 23.6979 9.1718 23.5235 9.00135 23.3079C8.8309 23.0923 8.71245 22.8412 8.65499 22.5736C8.59754 22.306 8.6026 22.029 8.66978 21.7636L10.1888 15.7636C10.2874 15.3743 10.5148 15.0287 10.835 14.7817C11.1551 14.5347 11.5496 14.4005 11.9559 14.4004H18.3931C19.2621 14.4004 20.0101 13.7949 20.1801 12.9532L22.3882 2.04774C22.4705 1.63945 22.6936 1.27198 23.0195 1.00793C23.3453 0.74388 23.7538 0.599578 24.1752 0.599605H30.1774C30.4471 0.599529 30.7134 0.658587 30.9572 0.772515C31.201 0.886444 31.4161 1.0524 31.5871 1.25842C31.758 1.46443 31.8806 1.70537 31.9458 1.96383C32.0111 2.2223 32.0175 2.49185 31.9645 2.75305L29.6564 14.1534ZM9.61081 13.5538C9.52825 13.962 9.30507 14.3292 8.97924 14.593C8.65341 14.857 8.24508 15.0011 7.82375 15.001H1.82257C1.55289 15.0011 1.28656 14.942 1.04279 14.8281C0.79902 14.7141 0.583892 14.5482 0.412928 14.3422C0.241965 14.1362 0.11943 13.8952 0.0541639 13.6368C-0.0111017 13.3783 -0.0174699 13.1087 0.0355186 12.8475L2.34359 1.44715C2.42614 1.03904 2.64933 0.671798 2.97516 0.407944C3.30099 0.144089 3.70932 -7.24082e-05 4.13064 7.25899e-08H10.1318C10.4015 -7.55792e-05 10.6678 0.0589818 10.9116 0.172911C11.1554 0.286839 11.3705 0.453799 11.5415 0.659813C11.7124 0.864828 11.835 1.10576 11.9002 1.36423C11.9655 1.62269 11.9719 1.89225 11.9189 2.15344L9.61081 13.553L9.61081 13.5538Z"
-      />
-    </svg>
-  );
-}
-
 export default function PageFooter({
   preset,
   brand,
@@ -77,13 +57,14 @@ export default function PageFooter({
   ...rest
 }) {
   const Link = linkComponent;
-  if (preset === 'vepa') return <VepaFooter brand={brand} columns={columns} socials={socials} linkComponent={Link} />;
+  if (preset === 'vepa' || ['thulir', 'aalam', 'nila'].includes(preset)) {
+    return <VepaFooter preset={preset} brand={brand} columns={columns} socials={socials} linkComponent={Link} />;
+  }
   const brandLabel = brand?.label ?? 'Velu';
   const brandHref = brand?.href;
 
   const brandNode = (
     <Cluster space="var(--s-3)" align="center" className="velu-footer__brand">
-      <VeluMark />
       <span className="velu-footer__wordmark">{brandLabel}</span>
     </Cluster>
   );

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

@@ -48,25 +48,8 @@ import Logo from './Logo.jsx';
  *           linkComponent?: React.ElementType, className?: string }} props
  */
 
-/* Velu brand mark. Color: --accent-color via the wrapping wordmark
-   span; the path uses currentColor. Exported so consumers (e.g. the
-   mobile nav drawer) can render the mark alongside its own chrome. */
-export function VeluMark() {
-  return (
-    <svg
-      className="velu-header__mark"
-      viewBox="0 0 32 24"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M29.6564 14.1534C29.5739 14.5616 29.3507 14.9288 29.0248 15.1926C28.699 15.4565 28.2907 15.6007 27.8694 15.6006H21.3702C20.5341 15.6006 19.8051 16.1627 19.6031 16.9638L18.1671 22.6368C18.0685 23.0263 17.8409 23.372 17.5205 23.619C17.2002 23.866 16.8054 24.0001 16.399 24H10.4378C10.1609 24.0001 9.88759 23.9378 9.63868 23.8179C9.38976 23.6979 9.1718 23.5235 9.00135 23.3079C8.8309 23.0923 8.71245 22.8412 8.65499 22.5736C8.59754 22.306 8.6026 22.029 8.66978 21.7636L10.1888 15.7636C10.2874 15.3743 10.5148 15.0287 10.835 14.7817C11.1551 14.5347 11.5496 14.4005 11.9559 14.4004H18.3931C19.2621 14.4004 20.0101 13.7949 20.1801 12.9532L22.3882 2.04774C22.4705 1.63945 22.6936 1.27198 23.0195 1.00793C23.3453 0.74388 23.7538 0.599578 24.1752 0.599605H30.1774C30.4471 0.599529 30.7134 0.658587 30.9572 0.772515C31.201 0.886444 31.4161 1.0524 31.5871 1.25842C31.758 1.46443 31.8806 1.70537 31.9458 1.96383C32.0111 2.2223 32.0175 2.49185 31.9645 2.75305L29.6564 14.1534ZM9.61081 13.5538C9.52825 13.962 9.30507 14.3292 8.97924 14.593C8.65341 14.857 8.24508 15.0011 7.82375 15.001H1.82257C1.55289 15.0011 1.28656 14.942 1.04279 14.8281C0.79902 14.7141 0.583892 14.5482 0.412928 14.3422C0.241965 14.1362 0.11943 13.8952 0.0541639 13.6368C-0.0111017 13.3783 -0.0174699 13.1087 0.0355186 12.8475L2.34359 1.44715C2.42614 1.03904 2.64933 0.671798 2.97516 0.407944C3.30099 0.144089 3.70932 -7.24082e-05 4.13064 7.25899e-08H10.1318C10.4015 -7.55792e-05 10.6678 0.0589818 10.9116 0.172911C11.1554 0.286839 11.3705 0.453799 11.5415 0.659813C11.7124 0.864828 11.835 1.10576 11.9002 1.36423C11.9655 1.62269 11.9719 1.89225 11.9189 2.15344L9.61081 13.5538Z"
-      />
-    </svg>
-  );
-}
+// Kept for callers importing the former mark; built-in branding is text-only.
+export function VeluMark() { return null; }
 
 function ActionButton({ action, Link, id }) {
   const { label, icon, kind = 'outlined', href, onClick, external, component } = action;
@@ -243,6 +226,8 @@ export default function PageHeader({
   activeTab,
   breadcrumb,
   onMenuClick,
+  menuOpen,
+  menuId,
   linkComponent = 'a',
   className = '',
   ...rest
@@ -280,7 +265,6 @@ export default function PageHeader({
         <Logo logo={brand.logo} alt={brandLabel} />
       ) : (
         <>
-          <VeluMark />
           <span className="velu-header__wordmark">{brandLabel}</span>
         </>
       )}
@@ -290,7 +274,7 @@ export default function PageHeader({
   return (
     <Stack
       as="header"
-      space={preset === 'vepa' ? '0px' : 'var(--s0)'}
+      space={preset === 'vepa' || ['thulir', 'aalam', 'nila'].includes(preset) ? '0px' : 'var(--s0)'}
       data-has-tabs={tabs.length > 0 ? 'true' : 'false'}
       className={`velu-header${scrolled ? ' velu-header--scrolled' : ''}${
         showTabsRow ? '' : ' velu-header--no-tabs'
@@ -391,6 +375,8 @@ export default function PageHeader({
               data-component="breadcrumb-list"
               onClick={onMenuClick}
               aria-label="Open navigation menu"
+              aria-expanded={menuOpen}
+              aria-controls={menuId}
             >
               {breadcrumb.map((c, i) => {
                 const isLast = i === breadcrumb.length - 1;
@@ -432,6 +418,8 @@ export default function PageHeader({
               type="button"
               className="velu-header__menu"
               aria-label="Open navigation menu"
+              aria-expanded={menuOpen}
+              aria-controls={menuId}
               onClick={onMenuClick}
             >
               <Menu aria-hidden="true" focusable="false" />

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

@@ -5,29 +5,23 @@ import Switcher from '../primitives/Switcher.jsx';
 
 /**
  * PageNav — previous / next page navigation for the foot of a docs
- * page. Two cards: the previous page (content flush to the inline
- * start, a "‹ Previous" label) and the next page (flush to the inline
- * end, "Next ›").
+ * page.
  *
- *   <PageNav
- *     linkComponent={RouterLink}
- *     prev={{ label: 'docs.json schema reference', href: '/schema' }}
- *     next={{ label: 'Pages', href: '/pages' }}
- *   />
- *
- * Either side may be omitted (first / last page) — the present card
- * keeps its half-width slot. Cards sit side by side and stack on narrow
- * widths via <Switcher>. Router-agnostic through `linkComponent`.
+ * Default / Thulir: two text cards ("‹ Previous" / "Next ›").
+ * Aalam (Maple): padded tray with a featured destination card
+ * (title + description + label) and a compact Previous when both
+ * sides exist — matching Mintlify Maple's pagination.
  *
  * @typedef {Object} PageRef
- * @property {string} label   page title shown on the card
+ * @property {string} label
  * @property {string} [href]
+ * @property {string} [description]
  *
- * @param {{ prev?: PageRef, next?: PageRef,
+ * @param {{ prev?: PageRef, next?: PageRef, variant?: 'default'|'aalam',
  *           linkComponent?: React.ElementType, className?: string }} props
  */
 
-function NavCard({ page, dir, Link }) {
+function DefaultCard({ page, dir, Link }) {
   const isPrev = dir === 'prev';
   return (
     <Link
@@ -36,11 +30,7 @@ function NavCard({ page, dir, Link }) {
       href={page.href ?? '#'}
     >
       <pagination-title class="velu-pagenav__title">{page.label}</pagination-title>
-      <Cluster
-        space="var(--s-4)"
-        align="center"
-        className="velu-pagenav__dir"
-      >
+      <Cluster space="var(--s-4)" align="center" className="velu-pagenav__dir">
         {isPrev && resolveIcon('chevron-left', { size: '1em' })}
         <span>{isPrev ? 'Previous' : 'Next'}</span>
         {!isPrev && resolveIcon('chevron-right', { size: '1em' })}
@@ -49,13 +39,99 @@ function NavCard({ page, dir, Link }) {
   );
 }
 
+/** Maple featured destination card: title + description | Next/Previous. */
+function MapleFeatured({ page, dir, Link }) {
+  const isPrev = dir === 'prev';
+  const meta = (
+    <div className="velu-pagenav__meta">
+      <pagination-title class="velu-pagenav__title">{page.label}</pagination-title>
+      {page.description ? (
+        <span className="velu-pagenav__desc">{page.description}</span>
+      ) : null}
+    </div>
+  );
+  const rule = <div className="velu-pagenav__rule" aria-hidden="true" />;
+  const label = (
+    <div className="velu-pagenav__dir">
+      {isPrev ? resolveIcon('chevron-left', { size: 12, strokeWidth: 3 }) : null}
+      <span>{isPrev ? 'Previous' : 'Next'}</span>
+      {!isPrev ? resolveIcon('chevron-right', { size: 12, strokeWidth: 3 }) : null}
+    </div>
+  );
+  return (
+    <Link
+      className={`velu-pagenav__featured velu-pagenav__featured--${dir}`}
+      data-component={`pagination-${dir}`}
+      href={page.href ?? '#'}
+    >
+      <div className="velu-pagenav__featured-inner">
+        {isPrev ? (
+          <>
+            {label}
+            {rule}
+            {meta}
+          </>
+        ) : (
+          <>
+            {meta}
+            {rule}
+            {label}
+          </>
+        )}
+      </div>
+    </Link>
+  );
+}
+
+/** Compact Previous control when Next is the featured card. */
+function MapleCompactPrev({ page, Link }) {
+  return (
+    <Link
+      className="velu-pagenav__compact velu-pagenav__compact--prev"
+      data-component="pagination-prev"
+      href={page.href ?? '#'}
+    >
+      {resolveIcon('chevron-left', { size: 12, strokeWidth: 3 })}
+      <span>Previous</span>
+    </Link>
+  );
+}
+
+function AalamNav({ prev, next, Link }) {
+  // Maple: when both exist, Previous is compact and Next is featured.
+  // Only-prev / only-next: the single side is the featured card.
+  if (prev && next) {
+    return (
+      <>
+        <MapleCompactPrev page={prev} Link={Link} />
+        <MapleFeatured page={next} dir="next" Link={Link} />
+      </>
+    );
+  }
+  if (next) return <MapleFeatured page={next} dir="next" Link={Link} />;
+  if (prev) return <MapleFeatured page={prev} dir="prev" Link={Link} />;
+  return null;
+}
+
 export default function PageNav({
   prev,
   next,
+  variant = 'default',
   linkComponent = 'a',
   className = '',
   ...rest
 }) {
+  if (variant === 'aalam') {
+    return (
+      <nav
+        className={`velu-pagenav velu-pagenav--aalam ${className}`.trim()}
+        {...rest}
+      >
+        <AalamNav prev={prev} next={next} Link={linkComponent} />
+      </nav>
+    );
+  }
+
   return (
     <Switcher
       space="var(--s0)"
@@ -64,12 +140,12 @@ export default function PageNav({
       {...rest}
     >
       {prev ? (
-        <NavCard page={prev} dir="prev" Link={linkComponent} />
+        <DefaultCard page={prev} dir="prev" Link={linkComponent} />
       ) : (
         <div aria-hidden="true" />
       )}
       {next ? (
-        <NavCard page={next} dir="next" Link={linkComponent} />
+        <DefaultCard page={next} dir="next" Link={linkComponent} />
       ) : (
         <div aria-hidden="true" />
       )}

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

@@ -8,25 +8,6 @@ import React from 'react';
  * @param {{ href?: string, className?: string }} props
  */
 
-/* Velu brand mark — same path as PageHeader's mark, sized for the
-   badge via .velu-powered-by__mark CSS. */
-function VeluMark() {
-  return (
-    <svg
-      className="velu-powered-by__mark"
-      viewBox="0 0 32 24"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M29.6564 14.1534C29.5739 14.5616 29.3507 14.9288 29.0248 15.1926C28.699 15.4565 28.2907 15.6007 27.8694 15.6006H21.3702C20.5341 15.6006 19.8051 16.1627 19.6031 16.9638L18.1671 22.6368C18.0685 23.0263 17.8409 23.372 17.5205 23.619C17.2002 23.866 16.8054 24.0001 16.399 24H10.4378C10.1609 24.0001 9.88759 23.9378 9.63868 23.8179C9.38976 23.6979 9.1718 23.5235 9.00135 23.3079C8.8309 23.0923 8.71245 22.8412 8.65499 22.5736C8.59754 22.306 8.6026 22.029 8.66978 21.7636L10.1888 15.7636C10.2874 15.3743 10.5148 15.0287 10.835 14.7817C11.1551 14.5347 11.5496 14.4005 11.9559 14.4004H18.3931C19.2621 14.4004 20.0101 13.7949 20.1801 12.9532L22.3882 2.04774C22.4705 1.63945 22.6936 1.27198 23.0195 1.00793C23.3453 0.74388 23.7538 0.599578 24.1752 0.599605H30.1774C30.4471 0.599529 30.7134 0.658587 30.9572 0.772515C31.201 0.886444 31.4161 1.0524 31.5871 1.25842C31.758 1.46443 31.8806 1.70537 31.9458 1.96383C32.0111 2.2223 32.0175 2.49185 31.9645 2.75305L29.6564 14.1534ZM9.61081 13.5538C9.52825 13.962 9.30507 14.3292 8.97924 14.593C8.65341 14.857 8.24508 15.0011 7.82375 15.001H1.82257C1.55289 15.0011 1.28656 14.942 1.04279 14.8281C0.79902 14.7141 0.583892 14.5482 0.412928 14.3422C0.241965 14.1362 0.11943 13.8952 0.0541639 13.6368C-0.0111017 13.3783 -0.0174699 13.1087 0.0355186 12.8475L2.34359 1.44715C2.42614 1.03904 2.64933 0.671798 2.97516 0.407944C3.30099 0.144089 3.70932 -7.24082e-05 4.13064 7.25899e-08H10.1318C10.4015 -7.55792e-05 10.6678 0.0589818 10.9116 0.172911C11.1554 0.286839 11.3705 0.453799 11.5415 0.659813C11.7124 0.864828 11.835 1.10576 11.9002 1.36423C11.9655 1.62269 11.9719 1.89225 11.9189 2.15344L9.61081 13.5538Z"
-      />
-    </svg>
-  );
-}
-
 export default function PoweredBy({
   href = 'https://veludocs.com',
   className = '',
@@ -42,7 +23,6 @@ export default function PoweredBy({
       >
         <span className="velu-powered-by__label">Powered by</span>
         <span className="velu-powered-by__brand">
-          <VeluMark />
           <span className="velu-powered-by__wordmark">Velu</span>
         </span>
       </a>

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

@@ -152,16 +152,28 @@ export default function Sidebar({
   );
 
   // Bring the active item into view inside the parent scroll container
-  // whenever the active route changes — e.g. after navigation, the
-  // selected page is already visible without the user scrolling the
-  // sidebar manually. Uses the shared util (instead of native
-  // scrollIntoView) so `scroll-padding-*` on the parent — which the
-  // docs layout uses to mark the footer-eclipsed band as off-limits —
-  // is reliably honoured.
+  // whenever the active route changes. useLayoutEffect + a frame wait
+  // so nested <details> have opened and sticky headings have laid out
+  // before we measure — otherwise a deep page can stay clipped.
   const rootRef = React.useRef(null);
-  React.useEffect(() => {
-    const el = rootRef.current?.querySelector('[aria-current="page"]');
-    scrollIntoNearestView(el);
+  useIsoLayoutEffect(() => {
+    const nav = rootRef.current;
+    if (!nav) return undefined;
+    let cancelled = false;
+    const reveal = () => {
+      if (cancelled) return;
+      const el = nav.querySelector('[aria-current="page"]');
+      if (!el) return;
+      // Clear sticky section headings so the active row isn't tucked
+      // under a pinned title (honours scroll-padding on the scroller).
+      scrollIntoNearestView(el);
+    };
+    reveal();
+    const id = requestAnimationFrame(reveal);
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(id);
+    };
   }, [activeHref]);
 
   // The single gliding active indicator (crimson tint + flush-left bar). One