@veluai/velu 0.2.35 → 0.2.37

package/src/runtime/App.jsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import VepaToc from './VepaToc.jsx';
 import { Routes, Route, useLocation, useNavigate, Link } from 'react-router-dom';
 import { MDXProvider } from '@mdx-js/react';
 // The project's pages + navigation, generated from velu.json by
@@ -6,6 +7,7 @@ import { MDXProvider } from '@mdx-js/react';
 // url → { Component, frontmatter, toc } (or { missing:true }).
 import { pages, navigation, site } from 'virtual:velu-site';
 import { resolve, normalizeUrl } from '../navigation.js';
+import { resolvePageMode, pageModeChrome } from './page-mode.js';
 import {
   Stack,
   Cluster,
@@ -53,6 +55,7 @@ import {
   ApiField,
   ApiSidebar,
   ApiSamples,
+  ApiReferencePage,
   NotFound,
   VeluMark,
 } from 'velu-ui';
@@ -683,6 +686,19 @@ function ImageDemo() {
 
 const RouterLink = ({ href, ...rest }) => <Link to={href} {...rest} />;
 
+// Look up a heading by its slug id. Prefers a match INSIDE the article: the
+// layout chrome carries stable, Mintlify-compatible ids for custom CSS
+// (#sidebar, #content, #footer, …), and a heading titled "Sidebar" or "Footer"
+// would slug to the same id — document.getElementById would then return the
+// chrome element (earlier in DOM order) and the TOC would scroll to the wrong
+// place.
+function sectionById(id) {
+  if (typeof document === 'undefined' || !id) return null;
+  const article = document.querySelector('.velu-docs-layout__article');
+  const esc = id.replace(/["\\]/g, '\\$&');
+  return article?.querySelector(`[id="${esc}"]`) ?? document.getElementById(id);
+}
+
 // Flatten a nested TOC tree to {id, label, depth} for scroll-spy.
 function flat(nodes, depth = 0, out = []) {
   for (const n of nodes) {
@@ -730,7 +746,7 @@ function useScrollSpy(ids) {
       let best = ids[0];
       let bestDist = Infinity;
       for (const id of ids) {
-        const node = document.getElementById(id);
+        const node = sectionById(id);
         if (!node) continue;
         const top = node.getBoundingClientRect().top;
         if (top >= vh) continue;
@@ -842,6 +858,10 @@ function DocsPage() {
   // No renderable page for this route → show the 404 page (a clean centered
   // takeover: header + footer stay, the docs sidebar/TOC are hidden).
   const isNotFound = !PageComponent;
+  // Mintlify-compatible page layout (`mode` in MDX frontmatter). Unknown
+  // values fall back to the standard sidebar + TOC + footer chrome.
+  const chrome = pageModeChrome(resolvePageMode(frontmatter));
+  const assistantUnavailable = chrome.assistant && !IS_DEV_PREVIEW && (!assistant || askAiHidden);
 
   // Switcher option sets (only render a switcher when an axis has >1
   // option). Anchors are pinned sidebar links shown in the context zone.
@@ -867,6 +887,7 @@ function DocsPage() {
       options={languageOptions}
       linkComponent={RouterLink}
       ariaLabel="Language"
+      idPrefix="localization-select"
     />
   );
   const productSwitcher = productOptions.length > 1 && (
@@ -875,6 +896,7 @@ function DocsPage() {
       options={productOptions}
       linkComponent={RouterLink}
       ariaLabel="Product"
+      component="nav-dropdown-products-selector"
     />
   );
 
@@ -897,14 +919,18 @@ function DocsPage() {
     }
     descTag.setAttribute('content', frontmatter.description || '');
     document.documentElement.lang = nav?.activeLanguageCode || 'en';
+    // Mirrors the SSR'd attribute so custom CSS scoped with
+    // html[data-current-path="/x"] follows client-side navigation too.
+    document.documentElement.dataset.currentPath = pathname;
   }, [pathname, isNotFound, frontmatter.title, frontmatter.description, nav?.activeLanguageCode]);
 
   // Frontmatter title needs an id so scroll-spy + click-to-scroll work
   // against it like any other heading.
   const pageId = React.useMemo(() => {
     if (!frontmatter.title) return null;
+    if (site.theme === 'vepa') return 'page-title';
     return new GithubSlugger().slug(frontmatter.title);
-  }, [frontmatter.title]);
+  }, [frontmatter.title, site.theme]);
 
   // Combined TOC: the frontmatter title is the page's top-level entry,
   // and the MDX-derived headings (h2s) become its children. Without this,
@@ -1040,7 +1066,11 @@ function DocsPage() {
     const tocBarToggle = document.querySelector('.velu-toc-bar__toggle');
     if (tocBarToggle) ro.observe(tocBarToggle);
     return () => ro.disconnect();
-  }, []);
+    // Re-run when page mode changes: custom/assistant drop the tabs
+    // row and shrink the header. A mount-only observer can leave
+    // --velu-header-height at the two-row 7rem default, which leaves
+    // 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
@@ -1161,17 +1191,26 @@ function DocsPage() {
       label: 'Log out',
       onClick: logoutPrivateAccess,
       kind: 'outlined',
+      component: 'logout-link',
     });
   }
 
-  const footerRef = React.useRef(null);
+  // 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.
+  const [footerEl, setFooterEl] = React.useState(null);
   const [footerOverlap, setFooterOverlap] = React.useState(0);
   React.useEffect(() => {
-    const node = footerRef.current;
-    if (!node) return;
+    if (!footerEl) {
+      setFooterOverlap(0);
+      return undefined;
+    }
     const update = () => {
-      const rect = node.getBoundingClientRect();
-      setFooterOverlap(Math.max(0, window.innerHeight - rect.top));
+      const rect = footerEl.getBoundingClientRect();
+      const visible = Math.max(0, window.innerHeight - rect.top);
+      setFooterOverlap(Math.min(visible, footerEl.offsetHeight));
     };
     update();
     window.addEventListener('scroll', update, { passive: true });
@@ -1180,15 +1219,17 @@ function DocsPage() {
       window.removeEventListener('scroll', update);
       window.removeEventListener('resize', update);
     };
-  }, []);
+  }, [footerEl]);
 
   // Sticky AskBar fades out once the user scrolls near the PageFeedback
   // widget — so it doesn't sit on top of the page-foot widgets.
-  const feedbackRef = React.useRef(null);
+  const [feedbackEl, setFeedbackEl] = React.useState(null);
   const [askBarHidden, setAskBarHidden] = React.useState(false);
   React.useEffect(() => {
-    const node = feedbackRef.current;
-    if (!node) return;
+    if (!feedbackEl) {
+      setAskBarHidden(false);
+      return undefined;
+    }
     const FADE_BUFFER = 64; // matches the rootMargin below
     const apply = (rect) => {
       // Hide whenever the feedback's top has reached the (effective)
@@ -1198,20 +1239,20 @@ function DocsPage() {
       // exactly at the same line in both scroll directions.
       setAskBarHidden(rect.top < window.innerHeight - FADE_BUFFER);
     };
-    apply(node.getBoundingClientRect());
+    apply(feedbackEl.getBoundingClientRect());
     const io = new IntersectionObserver(
       ([entry]) => apply(entry.boundingClientRect),
       // Trigger ~64px before the feedback enters the viewport, so the
       // AskBar fades just as the widget starts to peek up from below.
       { rootMargin: '0px 0px -64px 0px' },
     );
-    io.observe(node);
+    io.observe(feedbackEl);
     return () => io.disconnect();
-  }, []);
+  }, [feedbackEl]);
 
   const scrollTo = React.useCallback(
     (id) => {
-      const node = document.getElementById(id);
+      const node = sectionById(id);
       if (!node) return;
       // 1) Set + lock the active id IMMEDIATELY so the spy doesn't
       //    overwrite it during the smooth-scroll animation.
@@ -1242,12 +1283,15 @@ function DocsPage() {
 
   return (
     <div
+      id="body-content"
       className="velu-docs-layout"
-      data-chat-open={chatOpen ? 'true' : 'false'}
+      data-site-theme={site.theme ?? 'velu'}
+      data-chat-open={chatOpen && !chrome.assistant ? 'true' : 'false'}
       data-sidebar-open={sidebarOpen ? 'true' : 'false'}
       data-drawer-open={drawerOpen ? 'true' : 'false'}
       data-api={entry?.api ? 'true' : 'false'}
       data-not-found={isNotFound ? 'true' : undefined}
+      data-page-mode={isNotFound ? undefined : chrome.mode}
     >
       {/* Scrim — visible at mobile while the drawer OR the chatbot
           sheet is open. Sits between the article (z-0) and the
@@ -1264,6 +1308,8 @@ function DocsPage() {
       {/* Site header — brand, centered search, right-side actions,
           tabs row. Configurable: pass any number of actions / tabs. */}
       <PageHeader
+        preset={site.theme}
+        id="navbar"
         linkComponent={RouterLink}
         brand={{
           label: site.name,
@@ -1275,10 +1321,10 @@ function DocsPage() {
             <span className="velu-hide-on-mobile">{versionSwitcher}</span>
           )
         }
-        tabsTrailing={languageSwitcher || undefined}
         center={
           <Cluster space="var(--s-6)" align="center">
             <Search
+              id="search-bar-entry"
               style={{ inlineSize: '30ch' }}
               unavailable={IS_DEV_PREVIEW}
               search={IS_DEV_PREVIEW ? undefined : searchDocs}
@@ -1287,9 +1333,10 @@ function DocsPage() {
             {/* Ask AI talks to the deployed site's AI backend — hidden in
                 the local dev preview where there's nothing to talk to, and
                 when the owner's plan/credits disable the assistant. */}
-            {!IS_DEV_PREVIEW && !askAiHidden && (
+            {!IS_DEV_PREVIEW && !askAiHidden && !chrome.assistant && (
               <button
                 type="button"
+                id="assistant-entry"
                 className="velu-header__action velu-header__action--outlined"
                 onClick={() => askAI('')}
               >
@@ -1302,11 +1349,24 @@ function DocsPage() {
           </Cluster>
         }
         actions={navActions}
-        trailing={<ThemeToggle />}
-        onMenuClick={() => setDrawerOpen((v) => !v)}
-        breadcrumb={nav?.breadcrumb ?? []}
+        trailing={<ThemeToggle variant={site.theme === 'vepa' ? 'menu' : undefined} />}
+        tabsTrailing={
+          chrome.mode === 'custom' || chrome.mode === 'assistant'
+            ? undefined
+            : languageSwitcher || undefined
+        }
+        onMenuClick={chrome.sidebar ? () => setDrawerOpen((v) => !v) : undefined}
+        breadcrumb={
+          chrome.mode === 'custom' || chrome.mode === 'assistant'
+            ? []
+            : (nav?.breadcrumb ?? [])
+        }
         activeTab={nav?.activeTab}
-        tabs={nav?.tabs ?? []}
+        tabs={
+          chrome.mode === 'custom' || chrome.mode === 'assistant'
+            ? []
+            : (nav?.tabs ?? [])
+        }
       />
 
       {/* Fixed left sidebar — pinned to viewport-left below the header.
@@ -1316,6 +1376,7 @@ function DocsPage() {
           honour `inset-block-start` for fixed positioning the same way
           as plain `top`). */}
       <aside
+        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,
@@ -1400,6 +1461,8 @@ function DocsPage() {
                 <li key={it.href} role="none">
                   <a
                     role="menuitem"
+                    data-component="mobile-nav-tabs-item"
+                    data-active={it.href === nav?.activeTab ? 'true' : undefined}
                     className="velu-docs-layout__drawer-docselect-item"
                     href={it.href}
                     tabIndex={navOpen ? 0 : -1}
@@ -1429,10 +1492,11 @@ function DocsPage() {
                 <span className="velu-show-on-mobile">{languageSwitcher}</span>
               )}
               {anchors.length > 0 && (
-                <ul className="velu-docs-anchors">
+                <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"
@@ -1457,7 +1521,7 @@ function DocsPage() {
           {/* Hairline separating the top anchor links from the nav sections
               (faithful to the sidebar design's anchor↔sidebar divider). */}
           {anchors.length > 0 && (
-            <div className="velu-docs-context-divider" aria-hidden="true" />
+            <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
@@ -1466,6 +1530,7 @@ function DocsPage() {
               nav fully to that end. */}
           <div className="velu-docs-nav-region">
             <div
+              id={site.theme === 'vepa' ? 'navigation-items' : 'sidebar-content'}
               ref={leftAsideRef}
               className="velu-docs-nav-scroll velu-hide-scrollbar"
               style={{
@@ -1533,9 +1598,11 @@ function DocsPage() {
           display:none snap. See docs-layout.css. */}
 
       {/* Fixed right TOC — pinned to viewport-right. Hidden while the
-          Ask-AI chatbot is open (the panel takes that edge). */}
-      {!chatOpen && (
+          Ask-AI chatbot is open (the panel takes that edge). Wide /
+          custom / frame / center / assistant hide this rail. */}
+      {!chatOpen && chrome.toc && (
         <aside
+          id="table-of-contents"
           ref={rightAsideRef}
           className="velu-docs-layout__aside velu-docs-layout__aside--right velu-hide-scrollbar"
           style={{
@@ -1549,13 +1616,15 @@ function DocsPage() {
               (where the TOC sits for normal pages). */}
           {entry?.api && entry.operation ? (
             <ApiSamples
+              preset={site.theme}
+              title={frontmatter.title}
               samples={entry.samples}
               responses={entry.operation.responses}
             />
           ) : isChangelog && changelogTags.length ? (
             <ChangelogFilters tags={changelogTags} />
           ) : (
-            <Toc items={toc} activeId={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} />
           )}
         </aside>
       )}
@@ -1578,7 +1647,14 @@ function DocsPage() {
               onAskAI={IS_DEV_PREVIEW || askAiHidden ? undefined : () => askAI('')}
             />
           </main>
-        ) : (
+        ) : chrome.assistant && assistantUnavailable ? (
+          <main className="velu-assistant-disabled">
+            <Search
+              unavailable
+              unavailableMessage="Ask AI is not enabled on this site."
+            />
+          </main>
+        ) : chrome.assistant ? null : (
         <>
         {/* Narrow-layout TOC bar — always in DOM, only visible at
             < 1024px (toggled by @container in toc-bar.css). Shares
@@ -1587,9 +1663,13 @@ function DocsPage() {
             data; whichever one is visible at a given width responds
             to the same scroll-spy state. */}
         {/* Changelog tag filters are a wide-layout (right-rail) affordance only;
-            on tab/mobile we keep the normal TOC bar (no filters). */}
+            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} />
+        )}
       <main
+        id="content-area"
         className="velu-docs-layout__main"
         style={{
           /* No padding-block-end — the article's last child (PoweredBy)
@@ -1611,6 +1691,7 @@ function DocsPage() {
             column, and therefore sits BELOW the TocBar rather than
             overlapping it. Chevron flips direction with the
             `data-sidebar-open` data attribute on the layout root. */}
+        {chrome.sidebar && (
         <button
           type="button"
           className="velu-docs-layout__sidebar-toggle"
@@ -1624,11 +1705,13 @@ function DocsPage() {
             })}
           </span>
         </button>
-        <div className="velu-docs-layout__article" data-pagefind-body="">
+        )}
+        <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 : ""}>
           {/* 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
               when there's neither an eyebrow nor any enabled options. */}
+          {chrome.articleChrome && (
           <ContextMenu
             eyebrow={
               nav?.breadcrumb && nav.breadcrumb.length > 1
@@ -1645,13 +1728,15 @@ function DocsPage() {
             getMarkdown={entry?.getSource}
             rssHref={isChangelog ? `${BASE_PATH}/rss.xml` : undefined}
           />
+          )}
 
           {/* Page hero from MDX frontmatter. `.velu-hero` rules
               (in base.css) keep the title and description tightly
-              grouped and create a clear break before the prose body. */}
-          {(frontmatter.title || frontmatter.description) && (
+              grouped and create a clear break before the prose body.
+              Custom / frame / assistant are a blank canvas — no auto hero. */}
+          {chrome.hero && (frontmatter.title || frontmatter.description) && (
             <div className="velu-hero">
-              {frontmatter.title && <h1 id={pageId}>{frontmatter.title}</h1>}
+              {frontmatter.title && <h1 id={site.theme === 'vepa' ? 'page-title' : pageId}>{frontmatter.title}</h1>}
               {frontmatter.description && (
                 <p
                   style={{
@@ -1672,10 +1757,10 @@ 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}>
-            <div className="velu-prose">
+            <mdx-content key={site.theme === 'vepa' ? pathname : undefined} id={site.theme === 'vepa' && !entry?.api ? 'content' : undefined} class="velu-prose">
               {PageComponent ? (
                 <ErrorBoundary key={pathname} file={entry?.relPath}>
-                  <PageComponent />
+                  {entry?.mdxApi ? <ApiReferencePage {...entry.mdxApi} preset={site.theme}><PageComponent /></ApiReferencePage> : <PageComponent />}
                 </ErrorBoundary>
               ) : (
                 <p style={{ color: 'var(--muted-color)' }}>
@@ -1684,11 +1769,12 @@ function DocsPage() {
                     : 'Page not found.'}
                 </p>
               )}
-            </div>
+            </mdx-content>
           </MDXProvider>
           {/* Page-foot feedback widget — ref'd so the sticky AskBar
               above can hide as the user scrolls near it. */}
-          <div ref={feedbackRef} style={{ marginTop: 'var(--s3)' }}>
+          {chrome.articleChrome && (
+          <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.
                 Handlers are no-ops in the dev preview (pageFeedback null). */}
@@ -1702,10 +1788,12 @@ function DocsPage() {
               }
             />
           </div>
+          )}
           {/* Previous / next page navigation — derived from the
               sidebar reading order of the active section. */}
-          {(nav?.prev || nav?.next) && (
+          {chrome.articleChrome && !frontmatter.hidePagination && (nav?.prev || nav?.next) && (
             <PageNav
+              id="pagination"
               style={{ marginTop: 'var(--s2)' }}
               prev={nav?.prev}
               next={nav?.next}
@@ -1719,7 +1807,7 @@ function DocsPage() {
               approaches (see IntersectionObserver above). */}
           {/* Ask-a-question bar — opens the AI chatbot, which runs on the
               deployed site. Hidden in the local dev preview. */}
-          {!IS_DEV_PREVIEW && !chatOpen && !askAiHidden && (
+          {!IS_DEV_PREVIEW && !chatOpen && !askAiHidden && chrome.articleChrome && (
             <AskBar
               onSubmit={askAI}
               style={{
@@ -1745,14 +1833,14 @@ function DocsPage() {
               configured social icons sit on the LEFT of this same row (no
               full footer section); with link columns they live in the full
               footer below instead. */}
-          {footerHasLinks ? (
-            <PoweredBy />
+          {chrome.articleChrome && (footerHasLinks ? (
+            site.theme === 'vepa' ? null : <PoweredBy />
           ) : (
             <div className="velu-content-foot">
               <SocialLinks socials={footerSocials} />
               <PoweredBy />
             </div>
-          )}
+          ))}
         </div>
       </main>
         </>
@@ -1763,27 +1851,30 @@ function DocsPage() {
           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. */}
-      {footerHasLinks && (
-        <div
-          ref={footerRef}
+      {footerHasLinks && chrome.footer && (
+        <advanced-footer
+          id={site.theme === 'vepa' ? undefined : 'footer'}
+          ref={setFooterEl}
           data-velu-footer
           style={{ position: 'relative', zIndex: 20 }}
         >
           <PageFooter
-            brand={{ href: site.logo?.href || '/' }}
+            preset={site.theme}
+            brand={{ label: site.name, logo: site.logo, href: site.logo?.href || '/' }}
             columns={site.footer.links}
             socials={footerSocials}
           />
-        </div>
+        </advanced-footer>
       )}
 
       {/* Ask-AI chatbot — slides in from the inline-end edge. Hidden when the
           docs owner's plan/credits disable Ask-AI. */}
-      {!askAiHidden && (
+      {!askAiHidden && (!chrome.assistant || !assistantUnavailable) && (
       <Chatbot
-        open={chatOpen}
+        open={chrome.assistant || chatOpen}
+        layout={chrome.assistant ? 'page' : 'panel'}
         seedQuestion={chatQuestion}
-        onClose={() => setChatOpen(false)}
+        onClose={chrome.assistant ? undefined : () => setChatOpen(false)}
         ask={assistant?.ask}
         onFeedback={assistant?.sendFeedback}
         listHistory={assistant?.listConversations}
@@ -1806,6 +1897,7 @@ function DocsPage() {
           // behind the sheet. Desktop keeps the panel open so multi-cite hops
           // stay convenient.
           if (
+            !chrome.assistant &&
             typeof window !== 'undefined' &&
             window.matchMedia('(max-width: 1024px)').matches
           ) {
@@ -1817,7 +1909,7 @@ function DocsPage() {
           let tries = 0;
           const go = () => {
             if (hash) {
-              if (document.getElementById(hash)) { scrollTo(hash); return; }
+              if (sectionById(hash)) { scrollTo(hash); return; }
               if (tries++ < 10) { setTimeout(go, 60); return; }
             }
             window.scrollTo({ top: 0, behavior: 'smooth' });

package/src/runtime/VepaToc.jsx

@@ -0,0 +1,12 @@
+import React from 'react';
+
+export default function VepaToc({ items, activeId, onSelect }) {
+  const render = (entries) => <ul>{entries.map((item) => <li key={item.id}>
+    <a href={`#${item.id}`} aria-current={activeId === item.id ? 'location' : undefined} onClick={(e) => { e.preventDefault(); onSelect(item.id); }}>{item.label}</a>
+    {item.children?.length > 0 && render(item.children)}
+  </li>)}</ul>;
+  return <nav className="velu-vepa-toc" aria-label="On this page">
+    <button type="button" onClick={() => window.scrollTo({ top: 0, behavior: 'smooth' })}>On this page</button>
+    {render(items)}
+  </nav>;
+}

package/src/runtime/client-entry.jsx

@@ -1,7 +1,9 @@
+import './dev-warnings.js';
 import React from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router-dom';
 import 'velu-ui/styles.css';
+import { site } from 'virtual:velu-site';
 import App from './App.jsx';
 
 // Subpath hosting: Vite sets BASE_URL from the build's `base` (e.g. "/docs/").
@@ -9,10 +11,31 @@ import App from './App.jsx';
 // case ("/") becomes undefined so the router behaves as if mounted at origin.
 const basename = (import.meta.env.BASE_URL || '/').replace(/\/$/, '') || undefined;
 
+// Custom JavaScript (Mintlify-compatible): every `.js` file in the project is
+// run on every page. Loaded from an effect so it runs AFTER hydration commits —
+// the page is interactive and a script that mutates the DOM can't cause a
+// hydration mismatch. Classic (non-module) scripts, appended in the discovered
+// order; `async = false` keeps that order for dynamically inserted scripts.
+// Runs once per full page load, not per client-side navigation — same as a
+// <script> tag in the HTML would.
+function CustomScripts() {
+  React.useEffect(() => {
+    for (const url of site.customScripts ?? []) {
+      const el = document.createElement('script');
+      el.src = (basename || '') + url;
+      el.async = false;
+      el.dataset.veluCustom = '';
+      document.body.appendChild(el);
+    }
+  }, []);
+  return null;
+}
+
 hydrateRoot(
   document.getElementById('root'),
   <BrowserRouter basename={basename}>
     <App />
+    <CustomScripts />
   </BrowserRouter>
 );
 

package/src/runtime/dev-warnings.js

@@ -0,0 +1,16 @@
+// velu-ui renders component roots as Mintlify-compatible custom tags
+// (`<card>`, `<callout>`, `<code-block>`, …) so project CSS can use element
+// selectors. Browsers handle unknown elements fine (HTMLUnknownElement), and
+// React renders them fine too, but React's DEVELOPMENT build logs
+//   "Warning: The tag <card> is unrecognized in this browser. …"
+// once per tag name for the ones without a hyphen. Production builds never
+// emit it. This drops exactly that message in dev (server + browser) so
+// `velu dev` output stays readable; every other console.error passes through.
+if (import.meta.env.DEV && typeof console !== 'undefined') {
+  const original = console.error;
+  console.error = function veluFilteredError(...args) {
+    const first = args[0];
+    if (typeof first === 'string' && first.includes('is unrecognized in this browser')) return;
+    original.apply(this, args);
+  };
+}

package/src/runtime/page-mode.js

@@ -0,0 +1,54 @@
+// Page layout modes — Mintlify-compatible `mode` frontmatter.
+// Unknown / missing values fall back to the standard docs chrome.
+
+export const PAGE_MODES = [
+  'default',
+  'wide',
+  'custom',
+  'frame',
+  'center',
+  'assistant',
+];
+
+/**
+ * @param {Record<string, unknown>} [frontmatter]
+ * @returns {'default' | 'wide' | 'custom' | 'frame' | 'center' | 'assistant'}
+ */
+export function resolvePageMode(frontmatter = {}) {
+  const raw = String(frontmatter.mode ?? 'default').trim().toLowerCase();
+  return PAGE_MODES.includes(raw) ? raw : 'default';
+}
+
+/**
+ * Which chrome pieces a mode shows. Used by the docs runtime; CSS also
+ * keys off `data-page-mode` for the corresponding layout (aside margins,
+ * article measure).
+ *
+ *   default   — sidebar + TOC + footer (standard docs page)
+ *   wide      — sidebar + footer; no TOC panel; keeps the right gutter
+ *   custom    — no sidebar/TOC/footer; centered landing canvas
+ *   frame     — custom canvas + sidebar (no TOC)
+ *   center    — no sidebar/TOC; centered reading (changelogs)
+ *   assistant — navbar + full-page Ask AI chat
+ *
+ * @param {string} mode
+ */
+export function pageModeChrome(mode) {
+  const m = PAGE_MODES.includes(mode) ? mode : 'default';
+  const sidebar = m === 'default' || m === 'wide' || m === 'frame';
+  const toc = m === 'default';
+  const footer = m === 'default' || m === 'wide' || m === 'frame' || m === 'center';
+  const hero = m === 'default' || m === 'wide' || m === 'center';
+  return {
+    mode: m,
+    sidebar,
+    toc,
+    footer,
+    hero,
+    // Context menu, feedback, prev/next, AskBar, powered-by — the
+    // docs-page chrome around the MDX body. Custom/frame are a canvas;
+    // assistant replaces the body with chat.
+    articleChrome: hero,
+    assistant: m === 'assistant',
+  };
+}

package/src/runtime/server-entry.jsx

@@ -1,3 +1,4 @@
+import './dev-warnings.js';
 import React from 'react';
 import { renderToString } from 'react-dom/server';
 import { StaticRouter } from 'react-router-dom/server';