@veluai/velu 0.2.37 → 0.2.39

package/schema/velu.schema.json

@@ -9,8 +9,8 @@
   "properties": {
     "theme": {
       "type": "string",
-      "enum": ["velu", "vepa"],
-      "description": "Visual preset. Vepa follows the Mintlify Sequoia layout; light/dark preference is independent. Defaults to velu."
+      "enum": ["velu", "vepa", "thulir", "aalam"],
+      "description": "Visual preset. Vepa follows Mintlify Sequoia, Thulir follows Mintlify Mint, and Aalam follows Mintlify Maple; light/dark preference is independent. Defaults to velu."
     },
     "$schema": {
       "type": "string",
@@ -283,14 +283,34 @@
     },
     "pages": {
       "type": "array",
-      "description": "Ordered list of page paths (no extension, relative to the project root) and/or nested groups.",
+      "description": "Ordered list of page paths (no extension, relative to the project root), page objects with optional icons, and/or nested groups.",
       "items": {
         "oneOf": [
           { "type": "string" },
+          { "$ref": "#/$defs/pageEntry" },
           { "$ref": "#/$defs/group" }
         ]
       }
     },
+    "pageEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["page"],
+      "properties": {
+        "page": {
+          "type": "string",
+          "description": "Page path without extension, relative to the project root."
+        },
+        "icon": {
+          "type": "string",
+          "description": "Lucide icon id shown beside the page in the sidebar."
+        },
+        "title": {
+          "type": "string",
+          "description": "Optional sidebar label override (otherwise frontmatter title)."
+        }
+      }
+    },
     "group": {
       "type": "object",
       "additionalProperties": false,

package/src/navigation.js

@@ -187,12 +187,20 @@ function normalizeGroup(g) {
 }
 
 /** A `pages[]` entry is a string (page path), a generated OpenAPI page
- *  ({ apiPage, label, method }), or a nested group. */
+ *  ({ apiPage, label, method }), a page object ({ page, icon? }), or a
+ *  nested group. Page icons also come from MDX frontmatter `icon`. */
 function normalizePageEntry(entry) {
   if (typeof entry === 'string') return { kind: 'page', pagePath: entry };
   if (entry && entry.apiPage) {
     return { kind: 'page', pagePath: entry.apiPage, label: entry.label, method: entry.method, api: true };
   }
+  // Mintlify / Velu page object: { page: "path", icon?: "rocket", ... }
+  if (entry && typeof entry.page === 'string') {
+    const node = { kind: 'page', pagePath: entry.page };
+    if (entry.icon) node.icon = entry.icon;
+    if (entry.title || entry.label) node.label = entry.title ?? entry.label;
+    return node;
+  }
   return normalizeGroup(entry);
 }
 
@@ -392,13 +400,18 @@ function sidebarSectionsHaveApi(sections) {
 }
 
 /** Flatten sidebar sections (incl. nested groups) to an ordered list of
- *  page links {label, href} — the page reading order for prev/next. */
+ *  page links {label, href, description?} — the page reading order for
+ *  prev/next. */
 function flattenSidebar(sections) {
   const out = [];
   const walk = (items) => {
     for (const it of items) {
       if (it.items) walk(it.items);
-      else out.push({ label: it.label, href: it.href });
+      else {
+        const page = { label: it.label, href: it.href };
+        if (it.description) page.description = it.description;
+        out.push(page);
+      }
     }
   };
   for (const s of sections) walk(s.items);
@@ -454,6 +467,12 @@ function itemFor(pageNode, pagesMap, ctx) {
   // method badge); normal pages source their label from frontmatter.
   const label = pageNode.label ?? fm?.sidebarTitle ?? fm?.title ?? titleCase(lastSeg(href));
   const item = { label, href };
+  const icon = pageNode.icon ?? fm?.icon;
+  if (icon) item.icon = icon;
+  const description = fm?.description;
+  if (typeof description === 'string' && description.trim()) {
+    item.description = description.trim();
+  }
   const method = pageNode.method ?? pagesMap[href]?.operation?.method;
   if (method) item.method = method;
   return item;

package/src/runtime/App.jsx

@@ -59,7 +59,7 @@ import {
   NotFound,
   VeluMark,
 } from 'velu-ui';
-import { X, ChevronDown, ChevronUp } from 'lucide-react';
+import { X, ChevronDown } from 'lucide-react';
 import ErrorBoundary from './ErrorBoundary.jsx';
 
 // True under `velu dev`, false in the deployed production build (Vite injects
@@ -894,6 +894,7 @@ function DocsPage() {
     <NavSelect
       value={nav.activeProduct}
       options={productOptions}
+      icon={productOptions.find((p) => p.active)?.icon}
       linkComponent={RouterLink}
       ariaLabel="Product"
       component="nav-dropdown-products-selector"
@@ -928,7 +929,7 @@ function DocsPage() {
   // against it like any other heading.
   const pageId = React.useMemo(() => {
     if (!frontmatter.title) return null;
-    if (site.theme === 'vepa') return 'page-title';
+    if (site.theme === 'vepa' || ['thulir', 'aalam'].includes(site.theme)) return 'page-title';
     return new GithubSlugger().slug(frontmatter.title);
   }, [frontmatter.title, site.theme]);
 
@@ -962,6 +963,49 @@ function DocsPage() {
   // of sidebarOpen so neither breakpoint's default leaks into the
   // other.
   const [drawerOpen, setDrawerOpen] = React.useState(false);
+  const drawerRef = React.useRef(null);
+  const [drawerViewport, setDrawerViewport] = React.useState(false);
+  React.useEffect(() => {
+    const root = drawerRef.current?.parentElement;
+    if (!root) return;
+    const observer = new ResizeObserver(([entry]) => {
+      const narrow = entry.contentRect.width <= (['thulir', 'aalam'].includes(site.theme) ? 1023 : 640);
+      setDrawerViewport(narrow);
+      if (!narrow) setDrawerOpen(false);
+    });
+    observer.observe(root);
+    return () => observer.disconnect();
+  }, [site.theme]);
+  React.useEffect(() => {
+    if (!drawerOpen || !drawerViewport) return;
+    const drawer = drawerRef.current;
+    const previousFocus = document.activeElement;
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    const siblings = [...drawer.parentElement.children].filter(e => e !== drawer && !e.classList.contains('velu-docs-layout__scrim'));
+    const inertStates = siblings.map(e => e.inert);
+    siblings.forEach(e => { e.inert = true; });
+    drawer.querySelector('.velu-docs-layout__drawer-close')?.focus();
+    const onKey = e => {
+      if (e.key === 'Escape') {
+        if (drawer.querySelector('.velu-docs-layout__drawer-docselect[data-open="true"]')) return;
+        setDrawerOpen(false); return;
+      }
+      if (e.key !== 'Tab') return;
+      const items = [...drawer.querySelectorAll('a[href],button,input,select,textarea,[tabindex]')].filter(el => !el.disabled && el.tabIndex >= 0 && el.getClientRects().length && getComputedStyle(el).visibility !== 'hidden');
+      const first = items[0], last = items.at(-1);
+      if (!first) { e.preventDefault(); return; }
+      if (e.shiftKey && (document.activeElement === first || !drawer.contains(document.activeElement))) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && (document.activeElement === last || !drawer.contains(document.activeElement))) { e.preventDefault(); first.focus(); }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('keydown', onKey);
+      document.body.style.overflow = previousOverflow;
+      siblings.forEach((e,i) => { e.inert = inertStates[i]; });
+      if (previousFocus?.isConnected) previousFocus.focus({preventScroll:true});
+    };
+  }, [drawerOpen, drawerViewport]);
 
   // Drawer's nav dropdown — list of section links (Home/Docs/Blog),
   // mirrors the desktop tabs. Click-outside + Escape close.
@@ -973,7 +1017,7 @@ function DocsPage() {
       if (!navRef.current?.contains(e.target)) setNavOpen(false);
     };
     const onKey = (e) => {
-      if (e.key === 'Escape') setNavOpen(false);
+      if (e.key === 'Escape') { setNavOpen(false); navRef.current?.querySelector('button')?.focus(); }
     };
     document.addEventListener('mousedown', onDocClick);
     document.addEventListener('keydown', onKey);
@@ -1072,40 +1116,30 @@ function DocsPage() {
     // a gap above the full-page Ask AI canvas.
   }, [chrome.mode]);
 
-  // The asides (left sidebar + right TOC) scroll independently of the
-  // page. On scroll/resize we set data-fade-top/-bottom on each scroll
-  // region so CSS can fade its edges (and reveal the nav arrows) only
-  // when there's content beyond them. Written imperatively (no
-  // re-render). Re-binds on chatOpen toggle (the right TOC
-  // mounts/unmounts with it).
+  // The right TOC scrolls independently of the page. On scroll/resize
+  // we set data-fade-top/-bottom so CSS can fade its edges only when
+  // there's content beyond them. Written imperatively (no re-render).
+  // Re-binds on chatOpen toggle (the right TOC mounts/unmounts with it).
   const leftAsideRef = React.useRef(null);
   const rightAsideRef = React.useRef(null);
   React.useEffect(() => {
-    const els = [leftAsideRef.current, rightAsideRef.current].filter(Boolean);
-    if (!els.length) return;
+    const el = rightAsideRef.current;
+    if (!el) return undefined;
     const update = () => {
-      for (const el of els) {
-        el.dataset.fadeTop = el.scrollTop > 0 ? 'true' : 'false';
-        el.dataset.fadeBottom =
-          el.scrollTop + el.clientHeight < el.scrollHeight - 1
-            ? 'true'
-            : 'false';
-      }
+      el.dataset.fadeTop = el.scrollTop > 0 ? 'true' : 'false';
+      el.dataset.fadeBottom =
+        el.scrollTop + el.clientHeight < el.scrollHeight - 1
+          ? 'true'
+          : 'false';
     };
     update();
-    // Recompute on scroll AND on any size change of the scroll region
-    // or its content (ResizeObserver) + window resize — so the fade
-    // reflects hidden content persistently, not just during a scroll
-    // gesture (e.g. after a route change shifts the nav's height).
     const ro = new ResizeObserver(update);
-    els.forEach((el) => {
-      el.addEventListener('scroll', update, { passive: true });
-      ro.observe(el);
-      if (el.firstElementChild) ro.observe(el.firstElementChild);
-    });
+    el.addEventListener('scroll', update, { passive: true });
+    ro.observe(el);
+    if (el.firstElementChild) ro.observe(el.firstElementChild);
     window.addEventListener('resize', update);
     return () => {
-      els.forEach((el) => el.removeEventListener('scroll', update));
+      el.removeEventListener('scroll', update);
       ro.disconnect();
       window.removeEventListener('resize', update);
     };
@@ -1113,9 +1147,8 @@ function DocsPage() {
 
   // Flag the sidebar section heading currently pinned at the top of the
   // scroll region (CSS sticky gives no "is-stuck" hook). When the pinned
-  // heading changes as you scroll, the new one gets data-stuck and
-  // animates in (see sidebar.css). Re-binds on page/tab change since the
-  // section set changes with it.
+  // heading changes as you scroll, the new one gets data-stuck.
+  // Re-binds on page/tab change since the section set changes with it.
   React.useEffect(() => {
     const scroller = leftAsideRef.current;
     if (!scroller) return;
@@ -1198,8 +1231,8 @@ function DocsPage() {
   // Callback ref so this rebinds when the footer mounts/unmounts.
   // Custom and assistant unmount the footer; a mount-once listener
   // would keep reading the detached node (getBoundingClientRect top
-  // is 0) and treat the footer as covering the full viewport, which
-  // crushes the fixed sidebar via --velu-aside-bottom.
+  // is 0). footerOverlap still pads the right TOC so the last items
+  // can scroll clear of the footer as it rises under content + TOC.
   const [footerEl, setFooterEl] = React.useState(null);
   const [footerOverlap, setFooterOverlap] = React.useState(0);
   React.useEffect(() => {
@@ -1349,17 +1382,19 @@ function DocsPage() {
           </Cluster>
         }
         actions={navActions}
-        trailing={<ThemeToggle variant={site.theme === 'vepa' ? 'menu' : undefined} />}
+        trailing={<ThemeToggle variant={site.theme === 'aalam' ? 'inline' : site.theme === 'vepa' || site.theme === 'thulir' ? 'menu' : undefined} />}
         tabsTrailing={
           chrome.mode === 'custom' || chrome.mode === 'assistant'
             ? undefined
             : languageSwitcher || undefined
         }
         onMenuClick={chrome.sidebar ? () => setDrawerOpen((v) => !v) : undefined}
+        menuOpen={drawerOpen}
+        menuId={site.theme === 'vepa' ? 'sidebar-content' : 'sidebar'}
         breadcrumb={
           chrome.mode === 'custom' || chrome.mode === 'assistant'
             ? []
-            : (nav?.breadcrumb ?? [])
+            : ['thulir', 'aalam'].includes(site.theme) ? (nav?.breadcrumb ?? []).slice(-2) : (nav?.breadcrumb ?? [])
         }
         activeTab={nav?.activeTab}
         tabs={
@@ -1369,23 +1404,19 @@ function DocsPage() {
         }
       />
 
-      {/* Fixed left sidebar — pinned to viewport-left below the header.
-          Does NOT scroll with the page; the footer rises over its bottom
-          edge thanks to the higher z-index on the footer below.
-          `top` + `bottom` give a robust height (some browsers don't
-          honour `inset-block-start` for fixed positioning the same way
-          as plain `top`). */}
+      {/* Fixed left sidebar — pinned to viewport-left, full height.
+          The site footer is indented under content + TOC only, so the
+          rail never lifts for the footer. `top` + `bottom` give a
+          robust height (some browsers don't honour `inset-block-start`
+          for fixed positioning the same way as plain `top`). */}
       <aside
+        ref={drawerRef}
+        role={drawerViewport ? 'dialog' : undefined}
+        aria-modal={drawerViewport && drawerOpen ? true : undefined}
+        aria-label={drawerViewport ? 'Navigation' : undefined}
+        inert={drawerViewport && !drawerOpen ? '' : undefined}
         id={site.theme === 'vepa' ? 'sidebar-content' : 'sidebar'}
         className="velu-docs-layout__aside velu-docs-layout__aside--left"
-        style={{
-          /* Bottom edge stays a fixed gap above the viewport bottom,
-             AND lifts to keep that gap above the footer as it scrolls
-             into view (footerOverlap = how far the footer intrudes).
-             Set as a custom prop so the mobile drawer's
-             `inset-block-end: 0` override still wins. */
-          '--velu-aside-bottom': `calc(${footerOverlap}px + var(--s4))`,
-        }}
         // Close the mobile drawer as soon as a nav link is activated.
         // The pathname effect below also closes it on route change; this
         // covers same-route hash jumps and feels snappier on touch devices.
@@ -1413,11 +1444,11 @@ function DocsPage() {
               ) : (
                 <>
                   <VeluMark />
-                  <span className="velu-header__wordmark">{site.name}</span>
+                  <span className="velu-header__wordmark" title={site.name}>{site.name}</span>
                 </>
               )}
             </RouterLink>
-            <ThemeToggle />
+            <ThemeToggle variant={site.theme === 'vepa' || site.theme === 'thulir' ? 'menu' : undefined} />
             <button
               type="button"
               className="velu-docs-layout__drawer-close"
@@ -1427,21 +1458,45 @@ function DocsPage() {
               <X aria-hidden="true" focusable="false" />
             </button>
           </div>
+          {site.theme === 'aalam' && productSwitcher && (
+            <div className="velu-docs-aside-product">{productSwitcher}</div>
+          )}
+          {site.theme === 'aalam' && (
+            <div className="velu-docs-aside-search">
+              <Search
+                id="search-bar-entry-sidebar"
+                unavailable={IS_DEV_PREVIEW}
+                search={IS_DEV_PREVIEW ? undefined : searchDocs}
+                onSelect={(item) => item.href && navigate(item.href)}
+              />
+            </div>
+          )}
           {/* Nav dropdown — custom button + menu, fills drawer width.
               Items mirror the desktop tabs (Home / Docs / Blog).
               Click-outside + Escape close (see navOpen useEffect
-              above). Chevron rotates 180° on open. */}
+              above). Chevron rotates 180° on open. Shown only when
+              there is more than one tab to switch between. */}
+          {navItems.length > 1 && (
           <div
             ref={navRef}
             className="velu-docs-layout__drawer-docselect"
             data-open={navOpen ? 'true' : 'false'}
           >
+            <label htmlFor="drawer-section-picker">Documentation section</label>
             <button
+              id="drawer-section-picker"
               type="button"
               className="velu-docs-layout__drawer-docselect-btn"
               onClick={() => setNavOpen((o) => !o)}
               aria-haspopup="menu"
               aria-expanded={navOpen}
+              aria-controls="drawer-section-options"
+              onKeyDown={(e) => {
+                if (e.key === 'ArrowDown') {
+                  e.preventDefault(); setNavOpen(true);
+                  requestAnimationFrame(() => navRef.current?.querySelector('[role="menuitem"]')?.focus());
+                }
+              }}
             >
               <span className="velu-docs-layout__drawer-docselect-label">
                 {activeNavLabel}
@@ -1453,9 +1508,16 @@ function DocsPage() {
               />
             </button>
             <ul
+              id="drawer-section-options"
               className="velu-docs-layout__drawer-docselect-menu"
               role="menu"
               aria-hidden={!navOpen}
+              onKeyDown={(e) => {
+                const items = [...e.currentTarget.querySelectorAll('[role="menuitem"]')];
+                const index = items.indexOf(document.activeElement);
+                const next = e.key === 'ArrowDown' ? (index + 1) % items.length : e.key === 'ArrowUp' ? (index + items.length - 1) % items.length : e.key === 'Home' ? 0 : e.key === 'End' ? items.length - 1 : null;
+                if (next !== null) { e.preventDefault(); items[next]?.focus(); }
+              }}
             >
               {navItems.map((it) => (
                 <li key={it.href} role="none">
@@ -1474,24 +1536,25 @@ function DocsPage() {
               ))}
             </ul>
           </div>
+          )}
           {/* Context zone — product switcher + anchors at the top of
               the sidebar (all breakpoints), plus version/language
               switchers that only show on mobile (desktop has them in
-              the header). Rendered only when there's something to show
-              so simple projects keep a bare sidebar. */}
-          {(productSwitcher ||
-            versionSwitcher ||
+              the header). Aalam (Maple) puts product above search and
+              pins version to the sidebar footer instead. */}
+          {((productSwitcher && site.theme !== 'aalam') ||
+            (versionSwitcher && site.theme !== 'aalam') ||
             languageSwitcher ||
-            anchors.length > 0) && (
+            (anchors.length > 0 && site.theme !== 'aalam')) && (
             <Stack space="var(--s-1)" className="velu-docs-context">
-              {productSwitcher}
-              {versionSwitcher && (
+              {site.theme !== 'aalam' && productSwitcher}
+              {versionSwitcher && site.theme !== 'aalam' && (
                 <span className="velu-show-on-mobile">{versionSwitcher}</span>
               )}
               {languageSwitcher && (
                 <span className="velu-show-on-mobile">{languageSwitcher}</span>
               )}
-              {anchors.length > 0 && (
+              {anchors.length > 0 && site.theme !== 'aalam' && (
                 <ul className="velu-docs-anchors" data-component="nav-anchors">
                   {anchors.map((a, i) => (
                     <li key={i}>
@@ -1520,26 +1583,50 @@ function DocsPage() {
           )}
           {/* Hairline separating the top anchor links from the nav sections
               (faithful to the sidebar design's anchor↔sidebar divider). */}
-          {anchors.length > 0 && (
+          {anchors.length > 0 && site.theme !== 'aalam' && (
             <sidebar-nav-group-divider class="velu-docs-context-divider" aria-hidden="true" />
           )}
           {/* Only this region scrolls — the context zone above stays
-              pinned. The up/down arrows overlay its top/bottom edges and
-              appear (via the data-fade-* attrs the scroll handler sets)
-              when there's content beyond that edge; clicking jumps the
-              nav fully to that end. */}
+              pinned. Active page links scroll into view on navigation
+              (Sidebar / ApiSidebar). Aalam (Maple) scrolls the whole
+              left column, including anchors, in one overflow. */}
           <div className="velu-docs-nav-region">
             <div
-              id={site.theme === 'vepa' ? 'navigation-items' : 'sidebar-content'}
+              id={site.theme === 'vepa' || ['thulir', 'aalam'].includes(site.theme) ? 'navigation-items' : 'sidebar-content'}
               ref={leftAsideRef}
-              className="velu-docs-nav-scroll velu-hide-scrollbar"
+              className={`velu-docs-nav-scroll${site.theme === 'aalam' ? '' : ' velu-hide-scrollbar'}`}
               style={{
-                /* Just breathing room — the aside's bottom edge already
-                   stays above the footer (see --velu-aside-bottom). */
-                paddingBlockEnd: 'var(--s1)',
+                /* scroll-padding only — keep content clear of sticky
+                   headings / footer without shortening the scrollbar. */
+                scrollPaddingBlockStart: '2.75rem',
                 scrollPaddingBlockEnd: 'var(--s1)',
               }}
             >
+              {site.theme === 'aalam' && anchors.length > 0 && (
+                <ul className="velu-docs-anchors" data-component="nav-anchors">
+                  {anchors.map((a, i) => (
+                    <li key={i}>
+                      <a
+                        data-component="nav-anchor"
+                        className="velu-docs-anchors__link"
+                        href={a.href}
+                        target="_blank"
+                        rel="noreferrer"
+                      >
+                        {a.icon && (
+                          <span
+                            className="velu-docs-anchors__icon"
+                            aria-hidden="true"
+                          >
+                            {resolveIcon(a.icon, { size: 16 })}
+                          </span>
+                        )}
+                        <span>{a.label}</span>
+                      </a>
+                    </li>
+                  ))}
+                </ul>
+              )}
               {/* Sidebar STYLE is chosen per-tab, not per-page: if this tab
                   holds any API page, the whole tab uses the flat API sidebar
                   (so opening an intro page next to API operations doesn't flip
@@ -1562,31 +1649,11 @@ function DocsPage() {
                 />
               )}
             </div>
-            <button
-              type="button"
-              className="velu-docs-nav-arrow velu-docs-nav-arrow--up"
-              aria-label="Scroll navigation to top"
-              onClick={() =>
-                leftAsideRef.current?.scrollTo({ top: 0, behavior: 'smooth' })
-              }
-            >
-              <ChevronUp aria-hidden="true" focusable="false" />
-            </button>
-            <button
-              type="button"
-              className="velu-docs-nav-arrow velu-docs-nav-arrow--down"
-              aria-label="Scroll navigation to bottom"
-              onClick={() =>
-                leftAsideRef.current?.scrollTo({
-                  top: leftAsideRef.current.scrollHeight,
-                  behavior: 'smooth',
-                })
-              }
-            >
-              <ChevronDown aria-hidden="true" focusable="false" />
-            </button>
           </div>
         </Stack>
+        {site.theme === 'aalam' && versionSwitcher && (
+          <div className="velu-docs-aside-footer">{versionSwitcher}</div>
+        )}
       </aside>
 
       {/* No separate rail element — at narrow widths the sidebar's
@@ -1621,10 +1688,17 @@ function DocsPage() {
               samples={entry.samples}
               responses={entry.operation.responses}
             />
-          ) : isChangelog && changelogTags.length ? (
+          ) : isChangelog && changelogTags.length && site.theme !== 'vepa' ? (
             <ChangelogFilters tags={changelogTags} />
+          ) : site.theme === 'vepa' || ['thulir', 'aalam'].includes(site.theme) ? (
+            <>
+              {isChangelog && changelogTags.length > 0 ? (
+                <ChangelogFilters tags={changelogTags} />
+              ) : null}
+              <VepaToc items={pageToc} activeId={['thulir', 'aalam'].includes(site.theme) && activeId === pageId ? pageToc[0]?.id : activeId} onSelect={scrollTo} />
+            </>
           ) : (
-            site.theme === 'vepa' ? <VepaToc items={pageToc} activeId={activeId} onSelect={scrollTo} /> : <Toc id="table-of-contents-content" items={toc} activeId={activeId} onSelect={scrollTo} />
+            <Toc id="table-of-contents-content" items={toc} activeId={activeId} onSelect={scrollTo} />
           )}
         </aside>
       )}
@@ -1666,7 +1740,7 @@ function DocsPage() {
             on tab/mobile we keep the normal TOC bar (no filters). Hidden
             entirely when the page mode has no table of contents. */}
         {chrome.toc && (
-        <TocBar items={toc} activeId={activeId} onSelect={scrollTo} />
+        <TocBar items={toc} activeId={activeId} onSelect={scrollTo} label={['thulir', 'aalam'].includes(site.theme) ? 'On this page' : undefined} />
         )}
       <main
         id="content-area"
@@ -1706,7 +1780,7 @@ function DocsPage() {
           </span>
         </button>
         )}
-        <div id={site.theme === 'vepa' ? undefined : 'content'} data-contextual-actions={site.contextual?.options?.length ? 'true' : 'false'} className="velu-docs-layout__article" data-pagefind-body={chrome.assistant ? undefined : ""}>
+        <div id={site.theme === 'vepa' || ['thulir', 'aalam'].includes(site.theme) ? undefined : 'content'} data-contextual-actions={site.contextual?.options?.length ? 'true' : 'false'} className="velu-docs-layout__article" data-pagefind-body={chrome.assistant ? undefined : ""}>
           {/* Per-page agent/IDE action bar: the section eyebrow + a
               "Copy Page" split-button whose dropdown is driven by the
               Mintlify-compatible `contextual` config. Renders nothing
@@ -1736,7 +1810,7 @@ function DocsPage() {
               Custom / frame / assistant are a blank canvas — no auto hero. */}
           {chrome.hero && (frontmatter.title || frontmatter.description) && (
             <div className="velu-hero">
-              {frontmatter.title && <h1 id={site.theme === 'vepa' ? 'page-title' : pageId}>{frontmatter.title}</h1>}
+              {frontmatter.title && <h1 id={site.theme === 'vepa' || ['thulir', 'aalam'].includes(site.theme) ? 'page-title' : pageId}>{frontmatter.title}</h1>}
               {frontmatter.description && (
                 <p
                   style={{
@@ -1757,7 +1831,7 @@ function DocsPage() {
               level. Falls back to a not-found / missing-file notice
               when the route has no page (or its file is absent). */}
           <MDXProvider components={defaultMdxComponents}>
-            <mdx-content key={site.theme === 'vepa' ? pathname : undefined} id={site.theme === 'vepa' && !entry?.api ? 'content' : undefined} class="velu-prose">
+            <mdx-content key={site.theme === 'vepa' ? pathname : undefined} id={(site.theme === 'vepa' || ['thulir', 'aalam'].includes(site.theme)) && !entry?.api ? 'content' : undefined} class="velu-prose">
               {PageComponent ? (
                 <ErrorBoundary key={pathname} file={entry?.relPath}>
                   {entry?.mdxApi ? <ApiReferencePage {...entry.mdxApi} preset={site.theme}><PageComponent /></ApiReferencePage> : <PageComponent />}
@@ -1773,7 +1847,7 @@ function DocsPage() {
           </MDXProvider>
           {/* Page-foot feedback widget — ref'd so the sticky AskBar
               above can hide as the user scrolls near it. */}
-          {chrome.articleChrome && (
+          {chrome.articleChrome && !['thulir', 'aalam'].includes(site.theme) && (
           <div ref={setFeedbackEl} style={{ marginTop: 'var(--s3)' }}>
             {/* key resets the widget's vote state on page change. "Yes"
                 submits immediately; "No" submits once its form is sent.
@@ -1794,7 +1868,8 @@ function DocsPage() {
           {chrome.articleChrome && !frontmatter.hidePagination && (nav?.prev || nav?.next) && (
             <PageNav
               id="pagination"
-              style={{ marginTop: 'var(--s2)' }}
+              style={['thulir', 'aalam'].includes(site.theme) ? undefined : { marginTop: 'var(--s2)' }}
+              variant={site.theme === 'aalam' ? 'aalam' : 'default'}
               prev={nav?.prev}
               next={nav?.next}
               linkComponent={RouterLink}
@@ -1834,7 +1909,7 @@ function DocsPage() {
               full footer section); with link columns they live in the full
               footer below instead. */}
           {chrome.articleChrome && (footerHasLinks ? (
-            site.theme === 'vepa' ? null : <PoweredBy />
+            site.theme === 'vepa' || ['thulir', 'aalam'].includes(site.theme) ? null : <PoweredBy />
           ) : (
             <div className="velu-content-foot">
               <SocialLinks socials={footerSocials} />
@@ -1847,13 +1922,13 @@ function DocsPage() {
         )}
       </div>
 
-      {/* Full site footer — only when the config provides link columns. Spans
-          full width below the article; its raised z-index eclipses the bottoms
-          of the fixed sidebar and TOC as the page scrolls into it, and the ref
-          is watched so the asides can pad their bottom by the overlap. */}
+      {/* Full site footer — only when the config provides link columns.
+          Indented under content + TOC (see docs-layout.css); the left
+          rail stays full-height beside it. Right TOC pads for the
+          overlap via footerOverlap below. */}
       {footerHasLinks && chrome.footer && (
         <advanced-footer
-          id={site.theme === 'vepa' ? undefined : 'footer'}
+          id={site.theme === 'vepa' || ['thulir', 'aalam'].includes(site.theme) ? undefined : 'footer'}
           ref={setFooterEl}
           data-velu-footer
           style={{ position: 'relative', zIndex: 20 }}

package/templates/starter/ai-tools/claude-code.mdx

@@ -1,6 +1,7 @@
 ---
 title: Claude Code
 description: Work on your docs with Claude Code.
+icon: bot
 ---
 
 Claude Code can read your `velu.json` and `.mdx` files to draft pages,

package/templates/starter/ai-tools/cursor.mdx

@@ -1,6 +1,7 @@
 ---
 title: Cursor
 description: Edit your docs in Cursor.
+icon: sparkles
 ---
 
 Cursor's editor understands your project structure, so it can complete