@veluai/velu 0.2.35 → 0.2.37

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

@@ -63,9 +63,9 @@ function hasActiveDescendant(item, activeHref) {
 function Icon({ icon }) {
   const node = resolveIcon(icon);
   return node ? (
-    <span className="velu-sidebar__icon" aria-hidden="true">
+    <sidebar-group-icon class="velu-sidebar__icon" aria-hidden="true">
       {node}
-    </span>
+    </sidebar-group-icon>
   ) : null;
 }
 
@@ -99,7 +99,7 @@ function Node({ item, depth }) {
     return (
       <li>
         <details open={hasActiveDescendant(item, activeHref) || undefined}>
-          <summary className={`${base} velu-sidebar__summary`}>
+          <summary className={`${base} velu-sidebar__summary`} data-component="sidebar-group-header">
             <Icon icon={icon} />
             <span className="velu-sidebar__label">{label}</span>
             <Chevron />
@@ -124,10 +124,11 @@ function Node({ item, depth }) {
     : { href };
 
   return (
-    <li>
+    <li data-active={active ? 'true' : undefined}>
       <LinkTag
         className={cls}
         aria-current={active ? 'page' : undefined}
+        data-active={active ? 'true' : undefined}
         {...linkProps}
       >
         <Icon icon={icon} />
@@ -228,8 +229,19 @@ export default function Sidebar({
             separates one section from the next — compact but still
             visibly grouped. */}
         {sections.map((section, i) => (
-          <Stack key={i} space="var(--s-4)">
-            <h5 className="velu-sidebar__section">
+          <Stack
+            key={i}
+            as="sidebar-group"
+            space="var(--s-4)"
+            data-active={
+              section.items.some(
+                (it) => isActive(it, activeHref) || hasActiveDescendant(it, activeHref),
+              )
+                ? 'true'
+                : undefined
+            }
+          >
+            <h5 className="velu-sidebar__section" data-component="sidebar-title">
               <Icon icon={section.icon} />
               {section.title}
             </h5>

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

@@ -33,7 +33,7 @@ export function Step({
   ...rest
 }) {
   return (
-    <div className={`velu-step ${className}`.trim()} {...rest}>
+    <step className={`velu-step ${className}`.trim()} {...rest}>
       <div className="velu-step__circle" aria-hidden="true">
         {index}
       </div>
@@ -44,7 +44,7 @@ export function Step({
       {children != null && children !== false && (
         <div className="velu-step__body">{children}</div>
       )}
-    </div>
+    </step>
   );
 }
 Step.displayName = 'Step';
@@ -58,8 +58,8 @@ export default function Steps({ children, className = '', ...rest }) {
     return cloneElement(child, { index: child.props.index ?? i });
   });
   return (
-    <div className={`velu-steps ${className}`.trim()} {...rest}>
+    <steps className={`velu-steps ${className}`.trim()} {...rest}>
       {numbered}
-    </div>
+    </steps>
   );
 }

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

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

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

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

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

@@ -127,9 +127,11 @@ const Row = React.forwardRef(function Row(
   ref
 ) {
   return (
-    <div
+    <toc-item
       ref={ref}
       data-toc-active={active ? 'true' : undefined}
+      data-active={active ? 'true' : undefined}
+      data-active-deepest={active ? 'true' : undefined}
       onMouseEnter={() => onEnter(idx)}
       onClick={() => onClick(item.id)}
       style={{
@@ -166,7 +168,7 @@ const Row = React.forwardRef(function Row(
       >
         {item.label}
       </span>
-    </div>
+    </toc-item>
   );
 });
 
@@ -434,7 +436,7 @@ export default function Toc({
   }, [activeIdx]);
 
   return (
-    <div
+    <toc
       ref={rootRef}
       onMouseLeave={() => setHoverIdx(null)}
       style={{
@@ -532,6 +534,6 @@ export default function Toc({
           fontSize={fontSize}
         />
       ))}
-    </div>
+    </toc>
   );
 }

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

@@ -25,9 +25,9 @@ import resolveIcon from '../lib/resolveIcon.jsx';
 
 export default function Tree({ children, className = '', ...rest }) {
   return (
-    <div className={`velu-tree ${className}`.trim()} {...rest}>
+    <tree className={`velu-tree ${className}`.trim()} {...rest}>
       {children}
-    </div>
+    </tree>
   );
 }
 
@@ -54,6 +54,7 @@ export function Folder({
   // the <details> is not [open], so the rail collapses with them.
   return (
     <details
+      data-component="tree-folder"
       className={`velu-tree__group ${className}`.trim()}
       open={defaultOpen || undefined}
       {...rest}
@@ -76,12 +77,12 @@ export function File({
   ...rest
 }) {
   return (
-    <div
-      className={`velu-tree__item velu-tree__item--file ${className}`.trim()}
+    <tree-file
+      class={`velu-tree__item velu-tree__item--file ${className}`.trim()}
       {...rest}
     >
       <ItemIcon icon={icon} />
       <span className="velu-tree__label">{name}</span>
-    </div>
+    </tree-file>
   );
 }

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

@@ -78,6 +78,7 @@ export default function TryItBar({
       </div>
       <button
         type="button"
+        data-component="tryit-button"
         className="velu-try-it__cta"
         onClick={onTry}
         data-loading={loading ? 'true' : undefined}

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

@@ -55,7 +55,7 @@ export default function Update({
   const tagList = toTagList(tags);
 
   return (
-    <section
+    <update
       id={anchorId}
       data-update-label={updateLabel}
       data-update-tags={tagList.join('|')}
@@ -87,6 +87,6 @@ export default function Update({
         ) : null}
       </div>
       {children ? <div className="velu-update__content">{children}</div> : null}
-    </section>
+    </update>
   );
 }

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

@@ -0,0 +1,40 @@
+import React from 'react';
+import Logo from './Logo.jsx';
+import SocialLinks from './SocialLinks.jsx';
+import ThemePreferenceMenu from './ThemePreferenceMenu.jsx';
+
+export default function VepaFooter({ brand, columns = [], socials = [], linkComponent: Link = 'a' }) {
+  const single = columns.length === 1;
+  const completeHeadings = columns.every((c) => c.title);
+  return <footer id="footer" className="vepa-footer" data-layout={columns.length <= 3 ? 'compact' : 'expanded'} data-single={single} data-headings={completeHeadings}>
+    <div className="vepa-footer__inner">
+      <div className="vepa-footer__top">
+        <div className="vepa-footer__brand-column">
+          <Link href={brand?.href || '/'} className="vepa-footer__brand">
+            {brand?.logo ? <Logo logo={brand.logo} alt={brand.label} /> : <span>{brand?.label || 'Velu'}</span>}
+          </Link>
+          <SocialLinks socials={socials} className="vepa-footer__brand-socials" />
+        </div>
+        <div className="vepa-footer__columns" style={{ '--footer-columns': columns.length }}>
+          {columns.map((column, i) => <div className="vepa-footer__column" key={i}>
+            <div className="vepa-footer__links">
+              {column.title && !single && <p className="vepa-footer__heading">{column.title}</p>}
+              {(column.items || []).map((item, j) => {
+                const external = /^https?:\/\//.test(item.href || '');
+                const Tag = external ? 'a' : Link;
+                return <Tag className="vepa-footer__link" key={j} href={item.href || '#'} {...(external ? { target: '_blank', rel: 'noreferrer' } : {})}>{item.label}</Tag>;
+              })}
+            </div>
+          </div>)}
+        </div>
+        <SocialLinks socials={socials} className="vepa-footer__end-socials" />
+      </div>
+      {!completeHeadings && <SocialLinks socials={socials} className="vepa-footer__mobile-socials" />}
+      <div className="vepa-footer__divider" />
+      <div className="vepa-footer__bottom">
+        <a href="https://veludocs.com" target="_blank" rel="noreferrer" className="vepa-footer__powered">Powered by <strong>Velu</strong></a>
+        <ThemePreferenceMenu inline />
+      </div>
+    </div>
+  </footer>;
+}

package/runtime/velu-ui/components/callout.css

@@ -0,0 +1,28 @@
+/* Callout — admonition box. Static styles live here (not inline) so a
+   project's custom CSS can override them with a plain `callout { ... }`
+   element selector, as on Mintlify. The per-variant colours arrive as inline
+   custom properties (--velu-callout-bg / --velu-callout-stroke) set by
+   Callout.jsx from the type / stroke / bg props. */
+.velu-callout {
+  display: flow-root; /* contains the floated icon, no clipping */
+  padding: var(--s0) var(--s3);
+  background: var(--velu-callout-bg);
+  border: var(--border-width) solid var(--velu-callout-stroke);
+  border-radius: var(--radius-sm);
+  color: var(--text-color);
+  font-size: var(--f-body);
+  line-height: var(--lh-body);
+}
+
+/* The icon is FLOATED into the text flow (not a fixed column): it sits on the
+   first line and the text wraps beside it, then flows back under it. One
+   line-box tall so it's centred on the first line. */
+.velu-callout__icon {
+  float: left;
+  display: inline-flex;
+  align-items: center;
+  block-size: calc(var(--f-body) * var(--lh-body));
+  margin-inline-end: var(--s-1);
+  color: var(--velu-callout-stroke);
+  font-size: var(--f-body);
+}

package/runtime/velu-ui/components/card.css

@@ -2,6 +2,7 @@
    (cta hover, image clip, group grid) so this has CSS. Namespaced. */
 
 .velu-card {
+  position: relative;
   display: flex;
   flex-direction: column;
   border: var(--border-width) solid var(--border-color);
@@ -11,6 +12,14 @@
   color: var(--text-color);
   text-decoration: none;
 }
+.velu-card__link { position: absolute; inset: 0; z-index: 1; border-radius: inherit; }
+.velu-card:has(> .velu-card__link):hover { border-color: var(--accent-color); }
+.velu-card__link:focus-visible { outline: 2px solid var(--accent-color); outline-offset: -2px; }
+/* Nested controls must sit above the stretched-link overlay, or clicks hit the card href. */
+.velu-card :is(a, button, input, select, textarea, summary, label):not(.velu-card__link) {
+  position: relative;
+  z-index: 2;
+}
 
 /* CTA card: the whole card is the click target (stretched-link pattern —
    the CTA stays the single real <a>; a ::after overlay makes the entire

package/runtime/velu-ui/components/chatbot.css

@@ -45,6 +45,31 @@
     0 0 var(--s2) color-mix(in srgb, #000 18%, transparent),
     0 0 var(--s0) color-mix(in srgb, #000 8%, transparent);
 }
+
+/* Full-page Ask AI (`mode: assistant`). Sits under the navbar and
+   replaces the docs body instead of sliding in as a side panel. */
+.velu-chatbot--page {
+  inset-block-start: var(--velu-header-height, 3.5rem);
+  inset-block-end: 0;
+  inset-inline: 0;
+  inline-size: 100%;
+  max-inline-size: none;
+  transform: none;
+  border-inline-start: 0;
+  border-block-start: var(--border-width) solid var(--surface-color);
+  box-shadow: none;
+  z-index: 5;
+  /* Side gutters so the full-page chat isn't flush to the viewport. */
+  padding-inline: var(--s4);
+}
+.velu-chatbot--page .velu-chatbot__header,
+.velu-chatbot--page .velu-chatbot__body,
+.velu-chatbot--page .velu-chatbot__composer,
+.velu-chatbot--page .velu-chatbot__history {
+  max-inline-size: 42rem;
+  inline-size: 100%;
+  margin-inline: auto;
+}
 /* base.css applies a global `* { max-width: 66ch }`; reset it so the
    panel's structural elements size to flex/the panel, not 66ch. */
 .velu-chatbot * {
@@ -118,6 +143,23 @@
   .velu-chatbot--open {
     transform: translateY(0);
   }
+  /* Page-mode assistant stays a full-viewport chat, not a bottom sheet. */
+  .velu-chatbot--page,
+  .velu-chatbot--page.velu-chatbot--open {
+    inset-block-start: var(--velu-header-height, 3.5rem);
+    inset-block-end: 0;
+    inset-inline: 0;
+    inline-size: 100%;
+    max-inline-size: none;
+    block-size: auto;
+    transform: none;
+    border-radius: 0;
+    padding-block-start: 0;
+    box-shadow: none;
+  }
+  .velu-chatbot--page .velu-chatbot__drag-handle {
+    display: none;
+  }
 }
 
 /* ── Header ─────────────────────────────────────────────────────────── */

package/runtime/velu-ui/components/docs-layout.css

@@ -71,8 +71,13 @@
 }
 
 .velu-docs-layout__aside--left {
+  /* Shared surface token for the rail and its sticky descendants. Project
+     CSS can override this once on #sidebar; section headers and their fade
+     then remain visually continuous with the customized rail. */
+  --velu-sidebar-bg: var(--page-bg);
   inset-inline-start: 0;
   inline-size: var(--velu-sidebar-width);
+  background: var(--velu-sidebar-bg);
   /* Left gutter so the nav sits inset from the viewport edge rather
      than hugging it. (At mobile the @container block resets this to 0
      — the drawer manages its own padding.) */
@@ -803,6 +808,81 @@
   }
 }
 
+/* ── Page modes (frontmatter `mode`) ─────────────────────────────────── */
+/* Mintlify-compatible layouts. Default is the current chrome (sidebar +
+   TOC + footer) and needs no extra rules. */
+
+/* Wide: drop the right rail, keep the right gutter, let the article
+   use the extra width inside that gutter. */
+.velu-docs-layout[data-page-mode='wide'] .velu-docs-layout__aside--right,
+.velu-docs-layout[data-page-mode='frame'] .velu-docs-layout__aside--right {
+  display: none;
+}
+.velu-docs-layout[data-page-mode='wide'] .velu-docs-layout__article {
+  max-inline-size: none;
+}
+
+/* Frame is custom canvas + sidebar: no TOC gutter; the landing column
+   is centered in the remaining width next to the sidebar. */
+.velu-docs-layout[data-page-mode='frame'] .velu-docs-layout__center {
+  margin-inline-end: 0;
+}
+
+/* Custom / center / assistant: no sidebar, no TOC. */
+.velu-docs-layout[data-page-mode='custom'] .velu-docs-layout__aside,
+.velu-docs-layout[data-page-mode='center'] .velu-docs-layout__aside,
+.velu-docs-layout[data-page-mode='assistant'] .velu-docs-layout__aside {
+  display: none;
+}
+.velu-docs-layout[data-page-mode='custom'] .velu-docs-layout__center,
+.velu-docs-layout[data-page-mode='center'] .velu-docs-layout__center,
+.velu-docs-layout[data-page-mode='assistant'] .velu-docs-layout__center {
+  margin-inline: 0;
+}
+.velu-docs-layout[data-page-mode='custom'] .velu-docs-layout__sidebar-toggle,
+.velu-docs-layout[data-page-mode='center'] .velu-docs-layout__sidebar-toggle,
+.velu-docs-layout[data-page-mode='assistant'] .velu-docs-layout__sidebar-toggle,
+.velu-docs-layout[data-page-mode='wide'] .velu-toc-bar,
+.velu-docs-layout[data-page-mode='custom'] .velu-toc-bar,
+.velu-docs-layout[data-page-mode='frame'] .velu-toc-bar,
+.velu-docs-layout[data-page-mode='center'] .velu-toc-bar,
+.velu-docs-layout[data-page-mode='assistant'] .velu-toc-bar {
+  display: none;
+}
+
+/* Custom / frame are a landing canvas: center a max-w-4xl column.
+   Frame keeps the sidebar; custom does not. */
+.velu-docs-layout[data-page-mode='custom'] .velu-docs-layout__main,
+.velu-docs-layout[data-page-mode='frame'] .velu-docs-layout__main {
+  padding-block: calc(var(--s5) * 2);
+  padding-inline: var(--s4);
+}
+.velu-docs-layout[data-page-mode='custom'] .velu-docs-layout__article,
+.velu-docs-layout[data-page-mode='frame'] .velu-docs-layout__article {
+  max-inline-size: 56rem;
+  margin-inline: auto;
+}
+.velu-docs-layout[data-page-mode='custom'] .velu-prose > :is(h1, h2, h3, p),
+.velu-docs-layout[data-page-mode='frame'] .velu-prose > :is(h1, h2, h3, p) {
+  max-width: none;
+  text-align: center;
+}
+
+/* Assistant page: the chat fills the viewport below the header. Hide
+   the empty centre column when the chat is showing (no disabled-search
+   fallback). */
+.velu-docs-layout[data-page-mode='assistant']
+  .velu-docs-layout__center:not(:has(.velu-assistant-disabled)) {
+  display: none;
+}
+.velu-assistant-disabled {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-block-size: 70vh;
+  padding: var(--s4) var(--s2);
+}
+
 /* ── 404 takeover ─────────────────────────────────────────────────────── */
 /* On a not-found route the docs chrome (both fixed asides) is hidden and the
    centre column spans full width to center the <NotFound> content. The header

package/runtime/velu-ui/components/page-header.css

@@ -39,6 +39,12 @@
     color-mix(in srgb, #000 55%, transparent);
 }
 
+.velu-header--no-tabs {
+  /* Tabs row is gone — restore bottom padding so brand / search /
+     actions don't sit on the header hairline. Matches the top inset. */
+  padding-block-end: var(--s-1);
+}
+
 /* Once the user has scrolled even a single pixel, the header becomes
    a translucent frosted-glass overlay so the article content shows
    through faintly underneath. color-mix keeps the recipe token-driven:

package/runtime/velu-ui/components/sidebar.css

@@ -58,15 +58,15 @@
      takes over (iOS-list style). It sticks within its section wrapper
      (Sidebar.jsx renders each section in its own Stack), which bounds
      the push-out. Full-width opaque background so scrolling items
-     don't show behind it; --page-bg matches the surroundings, so the
-     bar is invisible until it's actually covering scrolled content. */
+     don't show behind it; --velu-sidebar-bg is owned by the left rail and can
+     be customized there, so the bar remains continuous with its surroundings. */
   position: sticky;
   inset-block-start: 0;
   /* Above the items (z-index 1) so scrolled rows tuck UNDER the heading (its
      opaque bg + the ::after fade hide them), not over it; above the gliding
      indicator (z-index 0) too. */
   z-index: 2;
-  background: var(--page-bg);
+  background: var(--velu-sidebar-bg, var(--page-bg));
   display: flex;
   align-items: center;
   gap: var(--s-2);
@@ -95,8 +95,8 @@
   block-size: var(--s3);
   background: linear-gradient(
     to bottom,
-    var(--page-bg),
-    color-mix(in srgb, var(--page-bg) 55%, transparent),
+    var(--velu-sidebar-bg, var(--page-bg)),
+    color-mix(in srgb, var(--velu-sidebar-bg, var(--page-bg)) 55%, transparent),
     transparent
   );
   pointer-events: none;

package/runtime/velu-ui/element-selectors.css

@@ -0,0 +1,66 @@
+/* Element selectors (Mintlify-compatible).
+
+   Component roots that have no semantic HTML meaning are rendered as the same
+   custom tag names Mintlify uses (`<card>`, `<callout>`, `<code-block>`, …) so
+   a project's custom CSS can target them as `card { … }`, exactly like on
+   Mintlify. Each element keeps its `velu-*` class, so the component CSS is
+   unchanged; this file only gives the unknown tags the display the `div` /
+   `span` they replaced had, and exempts them from the `* { max-width }`
+   measure reset in base.css (which lists `div` and `span` but obviously not
+   these). Class rules (specificity 0,1,0) still beat these tag rules (0,0,1).
+
+   Roots that must stay native for behaviour or accessibility (`<a>`,
+   `<button>`, `<details>`, `<summary>`, `<ul>`, `<textarea>`, headings…)
+   carry `data-component="<mintlify-name>"` instead. */
+
+/* Block-level: replaced a <div> / <section>. */
+accordion-group,
+advanced-footer,
+api-section,
+callout,
+card,
+card-group,
+chat-assistant-floating-input,
+chat-assistant-sheet-content,
+chat-assistant-sheet-header,
+chat-assistant-disclaimer-text,
+code-block,
+code-group,
+columns,
+contextual-feedback-container,
+contextual-feedback-form,
+feedback-toolbar,
+field,
+mdx-content,
+nav-tabs,
+not-found-container,
+not-found-status-code,
+option-dropdown,
+prompt,
+sidebar-group,
+sidebar-nav-group-divider,
+step,
+steps,
+toc,
+toc-item,
+topbar-right-container,
+tree,
+tree-file,
+update {
+  display: block;
+  max-width: none;
+}
+
+/* Inline: replaced a <span>. */
+breadcrumb-item,
+code-block-icon,
+eyebrow,
+method-pill,
+nav-dropdown-item-icon,
+nav-dropdown-item-title,
+pagination-title,
+sidebar-group-icon,
+starter-question-text {
+  display: inline;
+  max-width: none;
+}

package/runtime/velu-ui/primitives/Cluster.jsx

@@ -22,11 +22,22 @@ import React from 'react';
  * @param {string} [props.justify='flex-start']
  * @param {string} [props.align='flex-start']
  */
+
+// React 18 sets props on custom elements (tag names with a hyphen, e.g. the
+// Mintlify-compatible `as="sidebar-group"`) as attributes verbatim, so
+// `className` would come out as a literal className="" attribute. Hand those
+// tags `class` instead. (React 19 maps className for custom elements itself,
+// and accepts `class` too.)
+const isCustomTag = (Tag) => typeof Tag === 'string' && Tag.includes('-');
+const classProp = (Tag, className) =>
+  className == null ? {} : { [isCustomTag(Tag) ? 'class' : 'className']: className };
+
 export default function Cluster({
   as: Tag = 'div',
   space = 'var(--s1)',
   justify = 'flex-start',
   align = 'flex-start',
+  className,
   style,
   children,
   ...rest
@@ -41,6 +52,7 @@ export default function Cluster({
         gap: space,
         ...style,
       }}
+      {...classProp(Tag, className)}
       {...rest}
     >
       {children}