@veluai/velu 0.2.37 → 0.2.39

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,11 @@ 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).
+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 +141,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/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/docs/vepa.md

@@ -49,7 +49,8 @@ published package or used at runtime.
 | 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 |
-| Mobile navigation | Below 1024 px; 48 px topbar and 56 px breadcrumb strip |
+| 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veluai/velu",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "type": "module",
   "bin": "./dist/cli.js",
   "publishConfig": {
@@ -18,7 +18,9 @@
     "schema/**",
     "templates/**",
     "docs/mintlify-migration.md",
-    "docs/vepa.md"
+    "docs/vepa.md",
+    "docs/thulir.md",
+    "docs/aalam.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'].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'].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'].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'].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'].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'].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/PageFooter.jsx

@@ -77,7 +77,9 @@ 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'].includes(preset)) {
+    return <VepaFooter preset={preset} brand={brand} columns={columns} socials={socials} linkComponent={Link} />;
+  }
   const brandLabel = brand?.label ?? 'Velu';
   const brandHref = brand?.href;
 

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

@@ -243,6 +243,8 @@ export default function PageHeader({
   activeTab,
   breadcrumb,
   onMenuClick,
+  menuOpen,
+  menuId,
   linkComponent = 'a',
   className = '',
   ...rest
@@ -290,7 +292,7 @@ export default function PageHeader({
   return (
     <Stack
       as="header"
-      space={preset === 'vepa' ? '0px' : 'var(--s0)'}
+      space={preset === 'vepa' || ['thulir', 'aalam'].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 +393,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 +436,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/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

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

@@ -16,6 +16,7 @@ import ThemePreferenceMenu from './ThemePreferenceMenu.jsx';
  * visits, per the anti-flash script in the template).
  */
 export default function ThemeToggle({ className = '', variant, ...rest }) {
+  if (variant === 'inline') return <ThemePreferenceMenu inline />;
   if (variant === 'menu') return <ThemePreferenceMenu />;
   function toggle() {
     const root = document.documentElement;

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

@@ -83,9 +83,11 @@ export default function TocBar({
   activeId,
   onSelect = () => {},
   className = '',
+  label,
   ...rest
 }) {
   const [expanded, setExpanded] = React.useState(false);
+  const listId = React.useId();
 
   // Reading progress through the page: scrollY / (scrollable-distance).
   // Listens to window scroll + resize; clamped to [0, 1]. Stays at 0
@@ -138,6 +140,17 @@ export default function TocBar({
   // right-rail Toc uses — keeps the active item visible if the list is
   // long enough to scroll inside the bar.
   const rootRef = React.useRef(null);
+  React.useEffect(() => {
+    if (!expanded) return;
+    const close = (event) => {
+      if (event.type === 'keydown' && event.key === 'Escape') {
+        setExpanded(false); rootRef.current?.querySelector('button')?.focus();
+      } else if (event.type === 'pointerdown' && !rootRef.current?.contains(event.target)) setExpanded(false);
+    };
+    document.addEventListener('keydown', close);
+    document.addEventListener('pointerdown', close);
+    return () => { document.removeEventListener('keydown', close); document.removeEventListener('pointerdown', close); };
+  }, [expanded]);
   React.useEffect(() => {
     if (!expanded || activeId == null) return;
     const el = rootRef.current?.querySelector('[data-toc-bar-active="true"]');
@@ -156,10 +169,11 @@ export default function TocBar({
         className="velu-toc-bar__toggle"
         onClick={() => setExpanded((v) => !v)}
         aria-expanded={expanded}
+        aria-controls={listId}
       >
         {/* Reading-progress ring — fills as the reader scrolls. */}
         <ProgressRing progress={progress} />
-        <span className="velu-toc-bar__title">{headerLabel}</span>
+        <span className="velu-toc-bar__title">{label ?? headerLabel}</span>
         <ChevronDown
           className="velu-toc-bar__chevron"
           aria-hidden="true"
@@ -171,7 +185,7 @@ export default function TocBar({
           parent's `data-expanded` attribute via CSS, not by
           conditional rendering. `aria-hidden` keeps the collapsed
           list out of the accessibility tree. */}
-      <ul className="velu-toc-bar__list" aria-hidden={!expanded}>
+      <ul id={listId} className="velu-toc-bar__list" aria-hidden={!expanded}>
         {flat.map((item) => {
           const active = item.id === activeId;
           return (
@@ -183,6 +197,11 @@ export default function TocBar({
               }}
               data-toc-bar-active={active ? 'true' : undefined}
               onClick={() => handleSelect(item.id)}
+              role="link"
+              aria-current={active ? 'location' : undefined}
+              onKeyDown={(event) => {
+                if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); handleSelect(item.id); }
+              }}
               tabIndex={expanded ? 0 : -1}
             >
               {item.label}

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

@@ -10,9 +10,11 @@ import resolveIcon from '../lib/resolveIcon.jsx';
  * description and tags) and a right column with the entry body (the MDX
  * children — usually `##` sub-headings and prose).
  *
- * The section gets a stable `id` derived from the label so it is linkable
- * and shows up in the table of contents. The id MUST match the slug the
- * `extract-toc` remark plugin computes for the same label (see
+ * The section gets a stable `id` derived from description (preferred) or
+ * label so each entry is linkable and shows up in the table of contents.
+ * Preferring `description` keeps same-month releases unique (e.g. two
+ * "September 2026" rows with 0.2.37 / 0.2.36). The id MUST match the slug
+ * the `extract-toc` remark plugin computes (see
  * velu-cli/src/mdx-plugins/extract-toc.js → `slugifyUpdate`), so click→scroll
  * and scroll-spy line up.
  *
@@ -25,12 +27,20 @@ import resolveIcon from '../lib/resolveIcon.jsx';
  *   tags?: string | string[], rss?: any, children?: React.ReactNode,
  *   className?: string }} props
  */
-export function slugifyUpdate(value) {
-  const base = String(value || '')
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return `update-${base || 'item'}`;
+export function slugifyUpdate(label, description) {
+  const slugPart = (value) =>
+    String(value || '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+  const labelPart = slugPart(label);
+  const descPart = description == null || description === '' ? '' : slugPart(description);
+  const base = descPart
+    ? labelPart
+      ? `${labelPart}-${descPart}`
+      : descPart
+    : labelPart || 'item';
+  return `update-${base}`;
 }
 
 function toTagList(value) {
@@ -51,7 +61,9 @@ export default function Update({
 }) {
   void rss;
   const updateLabel = String(label ?? date ?? 'Update');
-  const anchorId = slugifyUpdate(updateLabel);
+  const updateDescription =
+    description == null || description === '' ? undefined : String(description);
+  const anchorId = slugifyUpdate(updateLabel, updateDescription);
   const tagList = toTagList(tags);
 
   return (