@veluai/velu 0.2.24 → 0.2.27

package/src/runtime/App.jsx

@@ -1,1754 +1,1754 @@
-import React from 'react';
-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
-// vite-plugin-velu-site (see src/vite-plugin-velu-site.js). `pages` is
-// url → { Component, frontmatter, toc } (or { missing:true }).
-import { pages, navigation, site } from 'virtual:velu-site';
-import { resolve, normalizeUrl } from '../navigation.js';
-import {
-  Stack,
-  Cluster,
-  ThemeToggle,
-  Sidebar,
-  NavSelect,
-  Toc,
-  TocBar,
-  ChangelogFilters,
-  ContextMenu,
-  Callout,
-  Accordion,
-  AccordionGroup,
-  Card,
-  CardGroup,
-  Switcher,
-  Image,
-  CodeBlock,
-  CodeGroup,
-  Columns,
-  Field,
-  Prompt,
-  Steps,
-  Step,
-  AskBar,
-  Chatbot,
-  PageFeedback,
-  PageNav,
-  PageFooter,
-  PageHeader,
-  PoweredBy,
-  defaultMdxComponents,
-  resolveIcon,
-  Search,
-  pagefindSearch,
-  createDocsAssistant,
-  createPageFeedback,
-  Logo,
-  SocialLinks,
-  Tree,
-  Folder,
-  File,
-  TryItBar,
-  ApiClient,
-  ApiField,
-  ApiSidebar,
-  ApiSamples,
-  NotFound,
-  VeluMark,
-} from 'velu-ui';
-import { X, ChevronDown, ChevronUp } from 'lucide-react';
-import ErrorBoundary from './ErrorBoundary.jsx';
-
-// True under `velu dev`, false in the deployed production build (Vite injects
-// this). AI features (Ask AI, the Ask-a-question bar) and full-text search run
-// on the deployed site, so they're hidden / shown-as-unavailable in the local
-// preview. Identical on SSR + client in each mode, so no hydration mismatch.
-const IS_DEV_PREVIEW = import.meta.env.DEV;
-
-// Subpath-hosting prefix (e.g. "/docs"), from Vite's BASE_URL. Empty at the
-// origin root. The router handles internal <Link>s on its own, but server-served
-// resources the router doesn't own — the .md twins, the /mcp endpoint — are
-// root-relative and need this prefix to resolve under a subpath.
-const BASE_PATH = (import.meta.env.BASE_URL || '/').replace(/\/$/, '');
-
-// Flatten a sidebar section's items (which may nest into sub-groups) into the
-// flat endpoint list <ApiSidebar> wants. API tabs are flat in practice; this
-// only guards the rare case of a normal nested group living beside generated
-// API operations in the same tab, so its leaf pages still get a working link.
-function sectionToEndpoints(items) {
-  const out = [];
-  for (const it of items ?? []) {
-    if (it.items) out.push(...sectionToEndpoints(it.items));
-    else
-      out.push({
-        method: it.method,
-        label: it.label,
-        href: it.href,
-        icon: it.icon,
-      });
-  }
-  return out;
-}
-
-const CALLOUT_TYPES = [
-  'note',
-  'warning',
-  'info',
-  'tip',
-  'check',
-  'danger',
-  'callout',
-];
-
-function CalloutGallery() {
-  return (
-    <Stack space="var(--s0)">
-      {CALLOUT_TYPES.map((t) => (
-        <Callout key={t} type={t}>
-          This is a {t}. This is a {t}. This is a {t}. This is a {t}.
-        </Callout>
-      ))}
-      <p style={{ color: 'var(--muted-color)' }}>
-        Custom callouts can be built with a custom icon &amp; color:
-      </p>
-      <Callout
-        icon="sparkles"
-        stroke="var(--accent-color)"
-        bg="color-mix(in srgb, var(--accent-color) 8%, transparent)"
-      >
-        A custom callout — lucide id <code>"sparkles"</code> with custom{' '}
-        <code>stroke</code> &amp; <code>bg</code>.
-      </Callout>
-
-      <Callout type="info">
-        This is a multi-line callout. It keeps going and going so the text
-        wraps onto several lines — the icon sits on the first line, the text
-        wraps beside it, and every line after flows back under the icon (no
-        hanging indent). Resize the window to watch the wrapping reflow while
-        the icon stays put on line one. This is a multi-line callout. It keeps
-        going so the text wraps onto several lines.
-      </Callout>
-    </Stack>
-  );
-}
-
-function AccordionDemo() {
-  return (
-    <Stack space="var(--s1)">
-      <Accordion title="This is an accordion">
-        This is content inside the accordion. Hover the header to see the
-        surface tint; the chevron rotates when expanded.
-      </Accordion>
-      <Accordion title="This is an accordion (open by default)" defaultOpen>
-        This one renders expanded — header takes the surface tint and a
-        divider separates it from this content.
-      </Accordion>
-      <AccordionGroup>
-        <Accordion title="This is an accordion">
-          Grouped items share one bordered box with dividers between them.
-        </Accordion>
-        <Accordion title="This is an accordion" defaultOpen>
-          This is content inside the accordion.
-        </Accordion>
-        <Accordion title="This is an accordion">
-          No per-item border or radius — the group owns the chrome.
-        </Accordion>
-      </AccordionGroup>
-    </Stack>
-  );
-}
-
-function CardDemo() {
-  return (
-    <Stack space="var(--s2)">
-      <Card icon="align-justify" title="Card Title">
-        This is how you use a card with an icon and a link. (Cards are not
-        clickable — only the CTA card's link is.)
-      </Card>
-
-      <Card icon="align-justify" title="Card Title" horizontal>
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
-        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
-        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
-        commodo consequat.
-      </Card>
-
-      <Card
-        img="https://picsum.photos/seed/velu/1200/560"
-        imgAlt="Yosemite valley"
-        title="Card Title"
-      >
-        This is how you use a card with an icon. The image fills the container
-        and is clipped to the card radius.
-      </Card>
-
-      <Card
-        icon="align-justify"
-        title="Card Title"
-        cta={{ label: 'Click Here', href: '#cards' }}
-      >
-        This is how you use a card with an icon and a link. The "Click Here"
-        link below is the only clickable element.
-      </Card>
-
-      <CardGroup>
-        <Card icon="align-justify" title="Card Title">
-          This is how you use a card with an icon and a link.
-        </Card>
-        <Card icon="align-justify" title="Card Title">
-          This is how you use a card with an icon and a link.
-        </Card>
-      </CardGroup>
-    </Stack>
-  );
-}
-
-function SwitcherBox({ children }) {
-  return (
-    <div
-      style={{
-        border: 'var(--border-width) solid var(--border-color)',
-        borderRadius: 'var(--radius-sm)',
-        padding: 'var(--s0) var(--s3)',
-      }}
-    >
-      {children}
-    </div>
-  );
-}
-
-function SwitcherDemo() {
-  return (
-    <Stack space="var(--s1)">
-      <p style={{ color: 'var(--muted-color)' }}>
-        Resize the window — these flip between a row and a column at the
-        container threshold, with no media queries.
-      </p>
-      <Switcher space="var(--s0)" threshold="30rem">
-        <SwitcherBox>One</SwitcherBox>
-        <SwitcherBox>Two</SwitcherBox>
-        <SwitcherBox>Three</SwitcherBox>
-      </Switcher>
-      <p style={{ color: 'var(--muted-color)' }}>
-        With <code>limit={2}</code>: more than 2 items forces vertical
-        regardless of width.
-      </p>
-      <Switcher space="var(--s0)" threshold="30rem" limit={2}>
-        <SwitcherBox>One</SwitcherBox>
-        <SwitcherBox>Two</SwitcherBox>
-        <SwitcherBox>Three</SwitcherBox>
-      </Switcher>
-    </Stack>
-  );
-}
-
-const DEMO_JS = `let greeting = function (name) {
-  console.log(\`Hello, \${name}!\`);
-};`;
-const DEMO_RB = `def greeting(name)
-  puts "Hello, #{name}!"
-end`;
-const DEMO_PY = `def greeting(name):
-    print(f"Hello, {name}!")`;
-
-function CodeBlockDemo() {
-  return (
-    <Stack space="var(--s2)">
-      <p style={{ color: 'var(--muted-color)' }}>Code Group</p>
-      <CodeGroup>
-        <CodeBlock title="Javascript" language="javascript">
-          {DEMO_JS}
-        </CodeBlock>
-        <CodeBlock title="Ruby" language="ruby">
-          {DEMO_RB}
-        </CodeBlock>
-        <CodeBlock title="Python" language="python">
-          {DEMO_PY}
-        </CodeBlock>
-      </CodeGroup>
-
-      <p style={{ color: 'var(--muted-color)' }}>Code (with file name)</p>
-      <CodeBlock filename="index.js" language="javascript">
-        {DEMO_JS}
-      </CodeBlock>
-
-      <p style={{ color: 'var(--muted-color)' }}>
-        With line numbers (icon suppressed via <code>withIcon={'{false}'}</code>)
-      </p>
-      <CodeBlock
-        filename="index.js"
-        language="javascript"
-        withIcon={false}
-        lineNumbers
-      >
-        {DEMO_JS}
-      </CodeBlock>
-
-      <p style={{ color: 'var(--muted-color)' }}>
-        Line highlight — single line (<code>highlight="2"</code>)
-      </p>
-      <CodeBlock
-        filename="index.js"
-        language="javascript"
-        lineNumbers
-        highlight="2"
-      >
-        {DEMO_JS}
-      </CodeBlock>
-
-      <p style={{ color: 'var(--muted-color)' }}>
-        Line highlight — range + single (<code>highlight="1-2,4"</code>)
-      </p>
-      <CodeBlock
-        filename="server.js"
-        language="javascript"
-        lineNumbers
-        highlight="1-2,4"
-      >
-        {`const express = require('express');
-const app = express();
-
-app.get('/', (req, res) => res.send('Hello'));
-
-app.listen(3000);`}
-      </CodeBlock>
-    </Stack>
-  );
-}
-
-function ApiDemo() {
-  const path = '/project/preview/{projectId}';
-  const curl = `curl --request POST \\
-  --url https://api.mintlify.com/v1/project/update/{projectId} \\
-  --header 'Authorization: Bearer <token>'`;
-  return (
-    <Stack space="var(--s2)">
-      <p style={{ color: 'var(--muted-color)' }}>Try-it bar</p>
-      <Stack space="var(--s-1)">
-        <TryItBar method="POST" path={path} />
-        <TryItBar method="GET" path={path} />
-        <TryItBar method="PUT" path={path} />
-        <TryItBar method="DELETE" path={path} />
-        <TryItBar method="PATCH" path={path} />
-      </Stack>
-
-      <p style={{ color: 'var(--muted-color)' }}>API sidebar</p>
-      <ApiSidebar
-        activeHref="/api/status"
-        sections={[
-          {
-            title: 'Admin',
-            icon: 'rocket',
-            endpoints: [
-              { method: 'POST', label: 'Trigger', href: '/api/trigger' },
-              {
-                method: 'GET',
-                label: 'Get deployment-status',
-                href: '/api/status',
-              },
-              {
-                method: 'DELETE',
-                label: 'Trigger Preview deployment',
-                href: '/api/preview',
-              },
-            ],
-          },
-        ]}
-      />
-
-      <p style={{ color: 'var(--muted-color)' }}>API Client</p>
-      {/* Only the ApiClient breaks out of the 46rem prose column — the
-          TryItBars above stay at the normal column width. clamp keeps
-          it ≥ 100% (so it never collapses when the main-area calc goes
-          negative on narrow screens) and ≤ 64rem. */}
-      <div
-        style={{
-          width:
-            'clamp(100%, calc(100vw - 240px - 280px - var(--s4) * 2), 64rem)',
-        }}
-      >
-        <ApiClient
-          method="DELETE"
-          label="Trigger Delete"
-          path={path}
-          onClose={() => {}}
-          description="Trigger a documentation deployment programmatically to publish updates outside of Git workflows."
-          aside={
-            <Stack space="var(--s1)">
-              <Callout type="danger">401 — Unauthorized</Callout>
-              <CodeGroup>
-                <CodeBlock title="Response" language="json">
-                  {`{\n  "status": 401,\n  "error": "Unauthorized"\n}`}
-                </CodeBlock>
-                <CodeBlock title="Headers" language="http">
-                  {`HTTP/1.1 401 Unauthorized
-date: Mon, 27 Apr 2026 12:00:55 GMT
-content-type: application/json; charset=utf-8
-content-length: 24
-connection: close
-x-powered-by: Express
-access-control-allow-origin: *`}
-                </CodeBlock>
-              </CodeGroup>
-              <CodeGroup>
-                <CodeBlock title="Curl" language="bash">
-                  {curl}
-                </CodeBlock>
-                <CodeBlock title="Ruby" language="ruby">
-                  {`require 'net/http'
-uri = URI('https://api.mintlify.com/v1/project/update/<projectId>')
-req = Net::HTTP::Post.new(uri)
-req['Authorization'] = 'Bearer <token>'
-Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }`}
-                </CodeBlock>
-                <CodeBlock title="Python" language="python">
-                  {`import requests
-requests.post(
-    'https://api.mintlify.com/v1/project/update/<projectId>',
-    headers={'Authorization': 'Bearer <token>'},
-)`}
-                </CodeBlock>
-              </CodeGroup>
-              <CodeGroup>
-                <CodeBlock title="202" language="json">
-                  {`{\n  "statusId": "<string>"\n}`}
-                </CodeBlock>
-                <CodeBlock title="200" language="json">
-                  {`{\n  "statusId": "<string>",\n  "completedAt": "2026-04-27T12:00:55Z"\n}`}
-                </CodeBlock>
-              </CodeGroup>
-            </Stack>
-          }
-        >
-          <AccordionGroup>
-            <Accordion title="Authorization" defaultOpen>
-              <Stack space="var(--s1)">
-                <ApiField
-                  name="Authorization"
-                  type="string"
-                  required
-                  prefix="Bearer"
-                >
-                  The Authorization header expects a Bearer token. Use an
-                  admin API key (prefixed with <code>mint_</code>).
-                </ApiField>
-              </Stack>
-            </Accordion>
-            <Accordion title="Path" defaultOpen>
-              <Stack space="var(--s1)">
-                <ApiField name="projectId" type="string" required>
-                  Your project ID. Copy it from the API keys page.
-                </ApiField>
-                <ApiField name="bodyId" type="string" required>
-                  Your body ID. Copy it from the API keys page.
-                </ApiField>
-              </Stack>
-            </Accordion>
-            <Accordion title="Query">
-              <Stack space="var(--s1)">
-                <ApiField name="branch" type="string">
-                  Git branch to deploy. Defaults to the production branch.
-                </ApiField>
-                <ApiField name="dryRun" type="boolean" default="false">
-                  When true, validates the deployment without publishing.
-                </ApiField>
-              </Stack>
-            </Accordion>
-            <Accordion title="Headers">
-              <Stack space="var(--s1)">
-                <ApiField name="X-Idempotency-Key" type="string">
-                  Optional unique key so retried requests don't trigger
-                  duplicate deployments.
-                </ApiField>
-              </Stack>
-            </Accordion>
-            <Accordion title="Body">
-              <Stack space="var(--s1)">
-                <ApiField name="message" type="string">
-                  Deployment message shown in the activity log.
-                </ApiField>
-                <ApiField name="notify" type="boolean" default="true">
-                  Whether to notify when the deployment completes.
-                </ApiField>
-              </Stack>
-            </Accordion>
-          </AccordionGroup>
-        </ApiClient>
-      </div>
-    </Stack>
-  );
-}
-
-function TreeDemo() {
-  return (
-    <Tree>
-      <Folder name="app">
-        <File name="layout.tsx" />
-        <File name="page.tsx" />
-        <Folder name="api" defaultOpen={false}>
-          <File name="route.ts" />
-        </Folder>
-      </Folder>
-      <File name="package.json" />
-    </Tree>
-  );
-}
-
-function StepsDemo() {
-  return (
-    <Steps>
-      <Step title="Install the CLI">Run the install script.</Step>
-      <Step title="Bootstrap a new project">
-        Scaffold a fresh velu project with a single command, then drop in the
-        starter MDX so you can begin editing right away. The CLI prompts for a
-        project name and target directory, copies the template files, and
-        installs dependencies in the background while you keep working.
-      </Step>
-      <Step title="Add your first page">
-        Drop an MDX file into the <code>content/</code> directory.
-      </Step>
-      <Step title="Configure navigation">
-        Edit <code>velu.config.js</code> and add your page paths under the
-        sidebar tree. Nested groups are supported, every item can carry an
-        icon, and external links are flagged automatically. Save the file and
-        the dev server hot-reloads with the new structure.
-      </Step>
-      <Step title="Preview locally">
-        Run <code>velu dev</code> — the local preview opens at
-        <code> localhost:5173</code> with SSR + HMR. Edits to any MDX or React
-        component reflect instantly. The right-rail TOC is generated from the
-        page's headings; the comet trail follows scroll.
-      </Step>
-      <Step title="Push and ship">Open a PR. Done.</Step>
-    </Steps>
-  );
-}
-
-function PromptDemo() {
-  return (
-    <Prompt title="Generate clear, concise documentation." openInCursor>
-      {`You are a **technical writing assistant**. Write documentation that is clear, accurate, and concise.
-- Use second-person voice
-- Avoid jargon
-- Lead with what the reader can do, not how it works internally
-- Code blocks use the project's language conventions
-- Every example must be runnable as-is`}
-    </Prompt>
-  );
-}
-
-function FieldDemo() {
-  const desc =
-    'An example of a parameter field. An example of a parameter field. An example of a parameter field. An example of a parameter field. An example of a parameter field. An example of a parameter field';
-  return (
-    <div>
-      <Field
-        name="param"
-        pre="pre"
-        type="string"
-        required
-        default={3}
-        post="post"
-      >
-        {desc}
-      </Field>
-      <Field
-        name="param"
-        pre="pre"
-        type="string"
-        required
-        default={3}
-        post="post"
-      >
-        {desc}
-      </Field>
-      <Field
-        name="param"
-        pre="pre"
-        type="string"
-        required
-        default={3}
-        post="post"
-      >
-        {desc}
-      </Field>
-    </div>
-  );
-}
-
-function ColumnsDemo() {
-  return (
-    <Stack space="var(--s2)">
-      <p style={{ color: 'var(--muted-color)' }}>
-        Two equal columns (<code>cols=&#123;2&#125;</code>) — collapses to a
-        single stack when items would fall below their per-item min width.
-      </p>
-      <Columns cols={2}>
-        <Card
-          icon="align-justify"
-          title="Card Title"
-          cta={{ label: 'Click Here', href: '#columns' }}
-        >
-          This is how you use a card with an icon and a link. Clicking on
-          this card brings you to the Columns page.
-        </Card>
-        <Card
-          icon="align-justify"
-          title="Card Title"
-          cta={{ label: 'Click Here', href: '#columns' }}
-        >
-          This is how you use a card with an icon and a link. Clicking on
-          this card brings you to the Columns page.
-        </Card>
-      </Columns>
-
-      <p style={{ color: 'var(--muted-color)' }}>
-        Heterogeneous children — a Card alongside a CodeBlock.
-      </p>
-      <Columns cols={2}>
-        <Card icon="sparkles" title="With a card">
-          Cards, callouts, code, images — anything composes in a column.
-        </Card>
-        <CodeBlock filename="hello.js" language="javascript">
-          {DEMO_JS}
-        </CodeBlock>
-      </Columns>
-
-      <p style={{ color: 'var(--muted-color)' }}>
-        Three columns (<code>cols=&#123;3&#125;</code>) with a stacked column
-        in the middle.
-      </p>
-      <Columns cols={3}>
-        <Card icon="rocket" title="Left">
-          Single card on the left.
-        </Card>
-        <Stack space="var(--s0)">
-          <Card icon="book" title="Top">
-            Two cards stacked via Stack inside one column.
-          </Card>
-          <Card icon="brain" title="Bottom">
-            Stack lets a column carry heterogeneous, multi-item content.
-          </Card>
-        </Stack>
-        <Card icon="zap" title="Right">
-          Single card on the right.
-        </Card>
-      </Columns>
-    </Stack>
-  );
-}
-
-const DEMO_IMG = 'https://picsum.photos/seed/velu-yosemite/1200/600';
-const DEMO_SHOT = 'https://picsum.photos/seed/velu-shot/600/1000';
-
-function ImageDemo() {
-  return (
-    <Stack space="var(--s2)">
-      <p style={{ color: 'var(--muted-color)' }}>Image</p>
-      <Image src={DEMO_IMG} alt="" />
-
-      <p style={{ color: 'var(--muted-color)' }}>
-        Image with caption (caption can be markdown later)
-      </p>
-      <Image src={DEMO_IMG} alt="" caption="Caption for this image" />
-
-      <p style={{ color: 'var(--muted-color)' }}>Image with window chrome</p>
-      <Image src={DEMO_IMG} alt="" chrome="window" />
-
-      <p style={{ color: 'var(--muted-color)' }}>Image with display frame</p>
-      <Image src={DEMO_SHOT} alt="" chrome="frame" caption="Caption can also be added" />
-    </Stack>
-  );
-}
-
-const RouterLink = ({ href, ...rest }) => <Link to={href} {...rest} />;
-
-// Flatten a nested TOC tree to {id, label, depth} for scroll-spy.
-function flat(nodes, depth = 0, out = []) {
-  for (const n of nodes) {
-    out.push({ id: n.id, label: n.label, depth });
-    if (n.children) flat(n.children, depth + 1, out);
-  }
-  return out;
-}
-
-// Scroll-spy: active = the section whose top last crossed the trigger line.
-/**
- * useScrollSpy — tracks the section currently in view, with an
- * explicit "lock" override for click-driven scrolls.
- *
- * Without the lock, clicking a TOC item triggers a smooth-scroll
- * animation; during the ~500ms animation the scroll listener fires
- * many times with the page at intermediate positions, and the
- * "closest section" answer flickers across multiple sections
- * before settling — visible as the TocBar label briefly showing
- * the wrong heading. The lock blocks spy updates for a configurable
- * window so the click's intended `activeId` survives the animation.
- *
- * Returns `[activeId, setActive]` where `setActive(id)` writes the
- * active id directly AND locks the spy for ~800ms.
- */
-function useScrollSpy(ids) {
-  const [activeId, setActiveId] = React.useState(ids[0]);
-  const lockUntilRef = React.useRef(0);
-  React.useEffect(() => {
-    const onScroll = () => {
-      if (Date.now() < lockUntilRef.current) return;
-      // Trigger line reads from --velu-scroll-offset (published by
-      // App.jsx as header + tocbar-toggle + 1rem). Same offset CSS
-      // uses for scroll-margin, so a heading freshly scrolled into
-      // view sits exactly at the trigger. Semantics: pick the
-      // section whose top is CLOSEST to the trigger; tie-break
-      // favours later sections in document order.
-      const trigger =
-        parseFloat(
-          getComputedStyle(document.documentElement).getPropertyValue(
-            '--velu-scroll-offset',
-          ),
-        ) || 0;
-      const vh = window.innerHeight;
-      let best = ids[0];
-      let bestDist = Infinity;
-      for (const id of ids) {
-        const node = document.getElementById(id);
-        if (!node) continue;
-        const top = node.getBoundingClientRect().top;
-        if (top >= vh) continue;
-        const dist = Math.abs(top - trigger);
-        if (dist <= bestDist) {
-          bestDist = dist;
-          best = id;
-        }
-      }
-      setActiveId(best);
-    };
-    window.addEventListener('scroll', onScroll, { passive: true });
-    onScroll();
-    return () => window.removeEventListener('scroll', onScroll);
-  }, [ids]);
-
-  const setActive = React.useCallback((id) => {
-    setActiveId(id);
-    // ~800ms covers the default smooth-scroll animation duration.
-    lockUntilRef.current = Date.now() + 800;
-  }, []);
-
-  return [activeId, setActive];
-}
-
-// Slugger used for the frontmatter-derived h1 id — same library as
-// extract-toc + rehype-slug, so the id we render in the DOM matches
-// what the TOC's `pageId` will compute. (One instance per page render
-// is fine; the slugger is stateful only across calls on the SAME
-// instance.)
-import GithubSlugger from 'github-slugger';
-
-function DocsPage() {
-  // Resolve the current route → page entry + navigation context. Both
-  // SSR and client compute these from the same pathname + the same
-  // shared `resolve()`, so the render is identical (hydration-safe).
-  const location = useLocation();
-  const navigate = useNavigate();
-  const pathname = normalizeUrl(location.pathname);
-  const entry = pages[pathname];
-  // `navigation`/`pages` are module constants in dev/build (the deps never
-  // change there); the instant preview's virtual-site substitute reassigns
-  // the `pages` live binding as pages finish compiling, so listing them re-
-  // resolves nav (sidebar labels, breadcrumb, prev/next) as titles arrive.
-  const nav = React.useMemo(
-    () => resolve(pathname, navigation, pages),
-    [pathname, navigation, pages],
-  );
-
-  // Search source: Pagefind for content/excerpts, but resolve each result's
-  // breadcrumb from the real NAVIGATION (a page's nav group can differ from its
-  // URL path — e.g. essentials/markdown.mdx lives under the "Writing Content"
-  // group). Page rows show the path to the page; anchor rows include the page.
-  const searchDocs = React.useCallback(async (q) => {
-    const results = await pagefindSearch(q);
-    if (!Array.isArray(results)) return results;
-    return results.map((r) => {
-      const res = resolve(r.href.split('#')[0], navigation, pages);
-      if (!res?.breadcrumb?.length) return r;
-      const labels = res.breadcrumb.map((c) => c.label);
-      const crumbs = r.kind === 'anchor' ? labels : labels.slice(0, -1);
-      return crumbs.length ? { ...r, breadcrumb: crumbs } : r;
-    });
-  }, []);
-
-  // Ask-AI backend: wire the chatbot to the public docs-AI-assistant API only
-  // in a real build AND when an apiBase is configured (velu.json → assistant).
-  // Otherwise `ask` stays undefined and the Chatbot uses its canned demo answer
-  // (dev preview, or a site that hasn't enabled the assistant).
-  const assistant = React.useMemo(() => {
-    if (IS_DEV_PREVIEW) return null;
-    const apiBase = site.assistant?.apiBase;
-    if (!apiBase) return null;
-    return createDocsAssistant({ apiBase, host: site.assistant?.host });
-  }, []);
-
-  // Hide the Ask-AI widget when the docs owner's plan/credits disable it (the
-  // backend bootstrap returns ask_ai_enabled:false). Only applies to a real
-  // configured assistant — the dev-preview/demo widget stays visible.
-  const [askAiHidden, setAskAiHidden] = React.useState(false);
-  React.useEffect(() => {
-    if (!assistant) return undefined;
-    let alive = true;
-    assistant.isEnabled().then((ok) => {
-      if (alive && !ok) setAskAiHidden(true);
-    }).catch(() => {});
-    return () => { alive = false; };
-  }, [assistant]);
-
-  // Page-feedback backend: reuses the same injected apiBase as the assistant
-  // (baked into every published velu.json), so the "Was this page helpful?"
-  // widget can POST to /api/v1/public/feedback. Null in the dev preview, where
-  // the widget stays purely visual.
-  const pageFeedback = React.useMemo(() => {
-    if (IS_DEV_PREVIEW) return null;
-    const apiBase = site.assistant?.apiBase;
-    if (!apiBase) return null;
-    return createPageFeedback({ apiBase, host: site.assistant?.host });
-  }, []);
-
-  const frontmatter = entry?.frontmatter ?? {};
-  const PageComponent = entry?.Component ?? null;
-  const pageToc = entry?.toc ?? [];
-  // Changelog pages (any page with <Update> entries) carry a `changelog`
-  // export. We swap the right-rail TOC for tag filters and expose an RSS link.
-  const changelog = entry?.changelog ?? null;
-  const isChangelog = !!changelog;
-  const changelogTags = changelog?.tags ?? [];
-  // 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;
-
-  // Switcher option sets (only render a switcher when an axis has >1
-  // option). Anchors are pinned sidebar links shown in the context zone.
-  const productOptions = nav?.products ?? [];
-  const versionOptions = nav?.versions ?? [];
-  const languageOptions = nav?.languages ?? [];
-  const anchors = nav?.anchors ?? [];
-  const versionSwitcher = versionOptions.length > 1 && (
-    <NavSelect
-      size="sm"
-      value={nav.activeVersion}
-      options={versionOptions}
-      linkComponent={RouterLink}
-      ariaLabel="Version"
-    />
-  );
-  const languageSwitcher = languageOptions.length > 1 && (
-    <NavSelect
-      bare
-      icon="globe"
-      value={nav.activeLanguage}
-      valueCode={nav.activeLanguageCode}
-      options={languageOptions}
-      linkComponent={RouterLink}
-      ariaLabel="Language"
-    />
-  );
-  const productSwitcher = productOptions.length > 1 && (
-    <NavSelect
-      value={nav.activeProduct}
-      options={productOptions}
-      linkComponent={RouterLink}
-      ariaLabel="Product"
-    />
-  );
-
-  // Keep document.title / meta description / <html lang> in sync on client-side
-  // navigation. The HTML is SSR'd with a per-page (build) or generic (dev) title;
-  // without this the tab title would stay frozen on the first page as you
-  // navigate the SPA, and JS-executing crawlers would read the stale value.
-  React.useEffect(() => {
-    const t = frontmatter.title;
-    document.title = isNotFound
-      ? `Page not found - ${site.name}`
-      : t && t !== site.name
-        ? `${t} - ${site.name}`
-        : site.name;
-    let descTag = document.querySelector('meta[name="description"]');
-    if (!descTag) {
-      descTag = document.createElement('meta');
-      descTag.setAttribute('name', 'description');
-      document.head.appendChild(descTag);
-    }
-    descTag.setAttribute('content', frontmatter.description || '');
-    document.documentElement.lang = nav?.activeLanguageCode || 'en';
-  }, [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;
-    return new GithubSlugger().slug(frontmatter.title);
-  }, [frontmatter.title]);
-
-  // Combined TOC: the frontmatter title is the page's top-level entry,
-  // and the MDX-derived headings (h2s) become its children. Without this,
-  // the right rail starts from the first h2 — orphaning the page title
-  // that sits visibly above the article.
-  const toc = React.useMemo(() => {
-    if (!frontmatter.title || !pageId) return pageToc;
-    return [{ id: pageId, label: frontmatter.title, children: pageToc }];
-  }, [pageId, frontmatter.title, pageToc]);
-
-  // Flat list of section ids for scroll-spy — sourced from the same
-  // nested TOC tree we pass to the right-rail <Toc>, so spy + render
-  // can't drift out of sync with the MDX content.
-  const ids = React.useMemo(() => flat(toc).map((s) => s.id), [toc]);
-  const [activeId, setActive] = useScrollSpy(ids);
-
-  // Ask-AI chatbot: opens (slides in from the side) when a question is
-  // submitted in the AskBar. While it's open the TOC is hidden.
-  const [chatOpen, setChatOpen] = React.useState(false);
-  const [chatQuestion, setChatQuestion] = React.useState('');
-
-  // Left sidebar open/closed (narrow widths) — chevron toggle. Defaults
-  // open per design; safe to default true since the narrow-width
-  // sidebar is in-flow and doesn't obscure content.
-  const [sidebarOpen, setSidebarOpen] = React.useState(true);
-  // Mobile drawer open/closed (< 640px) — burger / breadcrumb / X /
-  // scrim drive this. Defaults closed so refreshing the page at
-  // mobile doesn't surface the drawer over the article. Independent
-  // of sidebarOpen so neither breakpoint's default leaks into the
-  // other.
-  const [drawerOpen, setDrawerOpen] = React.useState(false);
-
-  // Drawer's nav dropdown — list of section links (Home/Docs/Blog),
-  // mirrors the desktop tabs. Click-outside + Escape close.
-  const [navOpen, setNavOpen] = React.useState(false);
-  const navRef = React.useRef(null);
-  React.useEffect(() => {
-    if (!navOpen) return;
-    const onDocClick = (e) => {
-      if (!navRef.current?.contains(e.target)) setNavOpen(false);
-    };
-    const onKey = (e) => {
-      if (e.key === 'Escape') setNavOpen(false);
-    };
-    document.addEventListener('mousedown', onDocClick);
-    document.addEventListener('keydown', onKey);
-    return () => {
-      document.removeEventListener('mousedown', onDocClick);
-      document.removeEventListener('keydown', onKey);
-    };
-  }, [navOpen]);
-
-  // Close the mobile drawer (and its nav dropdown) whenever the route changes,
-  // so picking a page from the sidebar collapses the drawer instead of leaving
-  // it open over the article.
-  React.useEffect(() => {
-    setDrawerOpen(false);
-    setNavOpen(false);
-  }, [pathname]);
-  // Mobile drawer's section picker = the resolved tabs (top-level
-  // navigation), so it mirrors the desktop tabs row instead of a
-  // hardcoded list. Its button shows the active tab's label.
-  const navItems = nav?.tabs ?? [];
-  const activeNavLabel =
-    navItems.find((t) => t.href === nav?.activeTab)?.label ??
-    navItems[0]?.label ??
-    '';
-  const askAI = React.useCallback((q) => {
-    setChatQuestion(q);
-    setChatOpen(true);
-  }, []);
-
-  // Measure the live sticky chrome — header + (collapsed) TocBar
-  // toggle — and publish three CSS variables on `:root`:
-  //
-  //   --velu-header-height   live header height
-  //   --velu-tocbar-height   TocBar's TOGGLE row height (always-
-  //                          visible bit; 0 when the bar isn't shown)
-  //   --velu-scroll-offset   header + tocbar-toggle + 1rem
-  //
-  // Measuring just the toggle row (NOT the expanded list) is
-  // important: the expanded dropdown's max-block-size is large, and
-  // including it in the offset would inflate scroll-margin /
-  // scroll-spy trigger as soon as the user expands the dropdown —
-  // causing the page geometry to lurch and the spy / active label
-  // to flicker.
-  React.useEffect(() => {
-    if (typeof window === 'undefined') return;
-    const header = document.querySelector('.velu-header');
-    if (!header) return;
-    const root = document.documentElement;
-    const remPx = parseFloat(getComputedStyle(root).fontSize) || 16;
-    // Skip same-value writes: these CSS vars affect layout, and an
-    // unconditional write on every ResizeObserver fire can feed back into
-    // layout (scrollbar appear/disappear flutter at narrow widths — observed
-    // as a permanent relayout storm inside the instant-preview iframe).
-    let lastHeaderH = -1;
-    let lastTocBarH = -1;
-    const apply = () => {
-      const headerH = Math.round(header.getBoundingClientRect().height);
-      // Re-query each apply — the TocBar toggle button is mounted
-      // after first paint and its parent may also remount on
-      // theme/viewport changes.
-      const tocBarToggle = document.querySelector('.velu-toc-bar__toggle');
-      const tocBarH = tocBarToggle
-        ? Math.round(tocBarToggle.getBoundingClientRect().height)
-        : 0;
-      if (headerH === lastHeaderH && tocBarH === lastTocBarH) return;
-      lastHeaderH = headerH;
-      lastTocBarH = tocBarH;
-      if (headerH > 0)
-        root.style.setProperty('--velu-header-height', `${headerH}px`);
-      root.style.setProperty('--velu-tocbar-height', `${tocBarH}px`);
-      // +1rem of breathing room between the chrome and the heading
-      // it's anchoring. The rem is read live so it stays in tokens.
-      root.style.setProperty(
-        '--velu-scroll-offset',
-        `${headerH + tocBarH + remPx}px`,
-      );
-    };
-    apply();
-    const ro = new ResizeObserver(apply);
-    ro.observe(header);
-    // Observe the toggle row only (not the expanded list) so the
-    // offset stays put when the user opens the dropdown.
-    const tocBarToggle = document.querySelector('.velu-toc-bar__toggle');
-    if (tocBarToggle) ro.observe(tocBarToggle);
-    return () => ro.disconnect();
-  }, []);
-
-  // 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).
-  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 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';
-      }
-    };
-    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);
-    });
-    window.addEventListener('resize', update);
-    return () => {
-      els.forEach((el) => el.removeEventListener('scroll', update));
-      ro.disconnect();
-      window.removeEventListener('resize', update);
-    };
-  }, [chatOpen, pathname]);
-
-  // 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.
-  React.useEffect(() => {
-    const scroller = leftAsideRef.current;
-    if (!scroller) return;
-    let prev = null;
-    const update = () => {
-      const top = scroller.getBoundingClientRect().top;
-      let stuck = null;
-      for (const h of scroller.querySelectorAll('.velu-sidebar__section')) {
-        if (h.getBoundingClientRect().top <= top + 1) stuck = h;
-      }
-      if (stuck !== prev) {
-        prev?.removeAttribute('data-stuck');
-        stuck?.setAttribute('data-stuck', 'true');
-        prev = stuck;
-      }
-    };
-    update();
-    scroller.addEventListener('scroll', update, { passive: true });
-    return () => scroller.removeEventListener('scroll', update);
-  }, [pathname, chatOpen]);
-
-  // Footer config (from velu.json via virtual:velu-site). Link columns →
-  // full footer section; socials with no columns → inline next to PoweredBy.
-  const footerSocials = site.footer?.socials ?? [];
-  const footerHasLinks = (site.footer?.links?.length ?? 0) > 0;
-
-  // Header top-right actions, built from velu.json's `navbar`: secondary
-  // `links` (plain text links) then the `primary` CTA (a filled button, or an
-  // outlined GitHub button). Empty when unconfigured — no placeholder buttons.
-  const navActions = [];
-  for (const l of site.navbar?.links ?? []) {
-    navActions.push({
-      label: l.label,
-      href: l.href,
-      icon: l.icon || undefined,
-      kind: 'link',
-      external: l.external,
-    });
-  }
-  if (site.navbar?.primary) {
-    const p = site.navbar.primary;
-    navActions.push({
-      label: p.label,
-      href: p.href,
-      kind: p.kind === 'github' ? 'outlined' : 'primary',
-      icon: p.kind === 'github' ? 'github' : undefined,
-      external: p.external,
-    });
-  }
-
-  const footerRef = React.useRef(null);
-  const [footerOverlap, setFooterOverlap] = React.useState(0);
-  React.useEffect(() => {
-    const node = footerRef.current;
-    if (!node) return;
-    const update = () => {
-      const rect = node.getBoundingClientRect();
-      setFooterOverlap(Math.max(0, window.innerHeight - rect.top));
-    };
-    update();
-    window.addEventListener('scroll', update, { passive: true });
-    window.addEventListener('resize', update);
-    return () => {
-      window.removeEventListener('scroll', update);
-      window.removeEventListener('resize', update);
-    };
-  }, []);
-
-  // 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 [askBarHidden, setAskBarHidden] = React.useState(false);
-  React.useEffect(() => {
-    const node = feedbackRef.current;
-    if (!node) return;
-    const FADE_BUFFER = 64; // matches the rootMargin below
-    const apply = (rect) => {
-      // Hide whenever the feedback's top has reached the (effective)
-      // viewport-bottom line — covers both "feedback is in view" AND
-      // "feedback is already scrolled past" without flickering back on.
-      // Threshold matches the IO's rootMargin so the show/hide flip is
-      // exactly at the same line in both scroll directions.
-      setAskBarHidden(rect.top < window.innerHeight - FADE_BUFFER);
-    };
-    apply(node.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);
-    return () => io.disconnect();
-  }, []);
-
-  const scrollTo = React.useCallback(
-    (id) => {
-      const node = document.getElementById(id);
-      if (!node) return;
-      // 1) Set + lock the active id IMMEDIATELY so the spy doesn't
-      //    overwrite it during the smooth-scroll animation.
-      setActive(id);
-      // 2) Compute the target scroll position MANUALLY (instead of
-      //    scrollIntoView). The browser clamps to max-scroll
-      //    automatically; the target is baked in at click time and
-      //    doesn't drift if layout shifts mid-animation.
-      const offset =
-        parseFloat(
-          getComputedStyle(document.documentElement).getPropertyValue(
-            '--velu-scroll-offset',
-          ),
-        ) || 0;
-      const top = node.getBoundingClientRect().top + window.scrollY - offset;
-      window.scrollTo({ top, behavior: 'smooth' });
-    },
-    [setActive],
-  );
-
-  const kicker = {
-    fontFamily: 'var(--font-mono)',
-    fontSize: 11,
-    letterSpacing: '0.6px',
-    textTransform: 'uppercase',
-    color: 'var(--muted-color)',
-  };
-
-  return (
-    <div
-      className="velu-docs-layout"
-      data-chat-open={chatOpen ? '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}
-    >
-      {/* Scrim — visible at mobile while the drawer OR the chatbot
-          sheet is open. Sits between the article (z-0) and the
-          drawer/chatbot (z-35 / z-50) and blocks pointer events to
-          everything beneath; click closes whichever surface is up. */}
-      <div
-        className="velu-docs-layout__scrim"
-        aria-hidden="true"
-        onClick={() => {
-          setDrawerOpen(false);
-          setChatOpen(false);
-        }}
-      />
-      {/* Site header — brand, centered search, right-side actions,
-          tabs row. Configurable: pass any number of actions / tabs. */}
-      <PageHeader
-        linkComponent={RouterLink}
-        brand={{
-          label: site.name,
-          href: site.logo?.href || '/',
-          logo: site.logo,
-        }}
-        brandTrailing={
-          versionSwitcher && (
-            <span className="velu-hide-on-mobile">{versionSwitcher}</span>
-          )
-        }
-        tabsTrailing={languageSwitcher || undefined}
-        center={
-          <Cluster space="var(--s-6)" align="center">
-            <Search
-              style={{ inlineSize: '30ch' }}
-              unavailable={IS_DEV_PREVIEW}
-              search={IS_DEV_PREVIEW ? undefined : searchDocs}
-              onSelect={(item) => item.href && navigate(item.href)}
-            />
-            {/* 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 && (
-              <button
-                type="button"
-                className="velu-header__action velu-header__action--outlined"
-                onClick={() => askAI('')}
-              >
-                <span className="velu-header__action-icon" aria-hidden="true">
-                  {resolveIcon('sparkles', { size: '1.5em' })}
-                </span>
-                <span>Ask AI</span>
-              </button>
-            )}
-          </Cluster>
-        }
-        actions={navActions}
-        trailing={<ThemeToggle />}
-        onMenuClick={() => setDrawerOpen((v) => !v)}
-        breadcrumb={nav?.breadcrumb ?? []}
-        activeTab={nav?.activeTab}
-        tabs={nav?.tabs ?? []}
-      />
-
-      {/* 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`). */}
-      <aside
-        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))`,
-        }}
-      >
-        {/* Drawer body — Stack with 32px gap composes the slots
-            (topbar / tab-dropdown / context / nav). The aside is a flex
-            column (CSS): the pinned slots keep their height and only the
-            nav region scrolls (see velu-docs-nav-scroll below). At wide
-            widths the topbar + docselect are `display: none`. */}
-        <Stack space="var(--s0)" className="velu-docs-aside-stack">
-          <div className="velu-docs-layout__drawer-head">
-            <RouterLink
-              href="/"
-              className="velu-docs-layout__drawer-brand"
-            >
-              {site.logo ? (
-                <Logo logo={site.logo} alt={site.name} />
-              ) : (
-                <>
-                  <VeluMark />
-                  <span className="velu-header__wordmark">{site.name}</span>
-                </>
-              )}
-            </RouterLink>
-            <ThemeToggle />
-            <button
-              type="button"
-              className="velu-docs-layout__drawer-close"
-              aria-label="Close navigation"
-              onClick={() => setDrawerOpen(false)}
-            >
-              <X aria-hidden="true" focusable="false" />
-            </button>
-          </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. */}
-          <div
-            ref={navRef}
-            className="velu-docs-layout__drawer-docselect"
-            data-open={navOpen ? 'true' : 'false'}
-          >
-            <button
-              type="button"
-              className="velu-docs-layout__drawer-docselect-btn"
-              onClick={() => setNavOpen((o) => !o)}
-              aria-haspopup="menu"
-              aria-expanded={navOpen}
-            >
-              <span className="velu-docs-layout__drawer-docselect-label">
-                {activeNavLabel}
-              </span>
-              <ChevronDown
-                className="velu-docs-layout__drawer-docselect-chev"
-                aria-hidden="true"
-                focusable="false"
-              />
-            </button>
-            <ul
-              className="velu-docs-layout__drawer-docselect-menu"
-              role="menu"
-              aria-hidden={!navOpen}
-            >
-              {navItems.map((it) => (
-                <li key={it.href} role="none">
-                  <a
-                    role="menuitem"
-                    className="velu-docs-layout__drawer-docselect-item"
-                    href={it.href}
-                    tabIndex={navOpen ? 0 : -1}
-                    onClick={() => setNavOpen(false)}
-                  >
-                    {it.label}
-                  </a>
-                </li>
-              ))}
-            </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 ||
-            languageSwitcher ||
-            anchors.length > 0) && (
-            <Stack space="var(--s-1)" className="velu-docs-context">
-              {productSwitcher}
-              {versionSwitcher && (
-                <span className="velu-show-on-mobile">{versionSwitcher}</span>
-              )}
-              {languageSwitcher && (
-                <span className="velu-show-on-mobile">{languageSwitcher}</span>
-              )}
-              {anchors.length > 0 && (
-                <ul className="velu-docs-anchors">
-                  {anchors.map((a, i) => (
-                    <li key={i}>
-                      <a
-                        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: '1em' })}
-                          </span>
-                        )}
-                        <span>{a.label}</span>
-                      </a>
-                    </li>
-                  ))}
-                </ul>
-              )}
-            </Stack>
-          )}
-          {/* 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" />
-          )}
-          {/* 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. */}
-          <div className="velu-docs-nav-region">
-            <div
-              ref={leftAsideRef}
-              className="velu-docs-nav-scroll velu-hide-scrollbar"
-              style={{
-                /* Just breathing room — the aside's bottom edge already
-                   stays above the footer (see --velu-aside-bottom). */
-                paddingBlockEnd: 'var(--s1)',
-                scrollPaddingBlockEnd: 'var(--s1)',
-              }}
-            >
-              {/* 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
-                  the sidebar shape). */}
-              {nav?.sidebarHasApi ? (
-                <ApiSidebar
-                  sections={(nav?.sidebarSections ?? []).map((s) => ({
-                    title: s.title,
-                    icon: s.icon,
-                    endpoints: sectionToEndpoints(s.items),
-                  }))}
-                  activeHref={pathname}
-                  linkComponent={RouterLink}
-                />
-              ) : (
-                <Sidebar
-                  sections={nav?.sidebarSections ?? []}
-                  activeHref={pathname}
-                  linkComponent={RouterLink}
-                />
-              )}
-            </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>
-      </aside>
-
-      {/* No separate rail element — at narrow widths the sidebar's
-          aside ANIMATES its `inline-size` between 240px (open) and
-          --velu-rail-width (closed), and its inner Sidebar nav fades
-          out via opacity. The aside's border-inline-end therefore
-          becomes the rail's right border when collapsed. This makes
-          the collapse a smooth width+opacity transition instead of a
-          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 && (
-        <aside
-          ref={rightAsideRef}
-          className="velu-docs-layout__aside velu-docs-layout__aside--right velu-hide-scrollbar"
-          style={{
-            /* Dynamic footer-overlap padding only — static geometry
-               lives in docs-layout.css. */
-            paddingBlockEnd: `calc(var(--s3) + ${footerOverlap}px + 2rem)`,
-            scrollPaddingBlockEnd: `calc(${footerOverlap}px + 2rem)`,
-          }}
-        >
-          {/* API reference pages put their code samples in the right rail
-              (where the TOC sits for normal pages). */}
-          {entry?.api && entry.operation ? (
-            <ApiSamples
-              samples={entry.samples}
-              responses={entry.operation.responses}
-            />
-          ) : isChangelog && changelogTags.length ? (
-            <ChangelogFilters tags={changelogTags} />
-          ) : (
-            <Toc items={toc} activeId={activeId} onSelect={scrollTo} />
-          )}
-        </aside>
-      )}
-
-      {/* Center column. Margin to reserve aside space lives in
-          docs-layout.css (drops to 0 at narrow widths via @container,
-          and the right margin collapses to 0 while the chatbot is
-          open via [data-chat-open="true"]). */}
-      <div className="velu-docs-layout__center">
-        {isNotFound ? (
-          <main className="velu-404-main">
-            <NotFound
-              homeHref="/"
-              linkComponent={RouterLink}
-              onSearch={() =>
-                window.dispatchEvent(
-                  new KeyboardEvent('keydown', { key: 'k', ctrlKey: true, metaKey: true }),
-                )
-              }
-              onAskAI={IS_DEV_PREVIEW || askAiHidden ? undefined : () => askAI('')}
-            />
-          </main>
-        ) : (
-        <>
-        {/* Narrow-layout TOC bar — always in DOM, only visible at
-            < 1024px (toggled by @container in toc-bar.css). Shares
-            its `items` + `activeId` + `onSelect` API with the
-            right-rail <Toc> so both views are driven by the same
-            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). */}
-        <TocBar items={toc} activeId={activeId} onSelect={scrollTo} />
-      <main
-        className="velu-docs-layout__main"
-        style={{
-          /* No padding-block-end — the article's last child (PoweredBy)
-             owns the gap to the footer via its own margin-bottom, so
-             padding-bottom here would double-count it. `position:
-             relative` makes <main> the offsetParent for the absolutely
-             positioned sidebar-toggle below — so its `top: 0` lands
-             at the top of the article area, BELOW the sticky TocBar
-             (which lives outside <main>). Padding-inline lives in CSS
-             so the @container query can collapse the start side when
-             the sidebar is closed (no "ghost column" on the left). */
-          position: 'relative',
-          color: 'var(--text-color)',
-        }}
-      >
-        {/* Sidebar toggle — narrow-layout only (hidden by @container
-            at wide widths). Lives inside <main> so its absolute
-            position is relative to the article area, not the centre
-            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. */}
-        <button
-          type="button"
-          className="velu-docs-layout__sidebar-toggle"
-          onClick={() => setSidebarOpen((v) => !v)}
-          aria-label={sidebarOpen ? 'Collapse sidebar' : 'Expand sidebar'}
-          aria-expanded={sidebarOpen}
-        >
-          <span aria-hidden="true">
-            {resolveIcon(sidebarOpen ? 'chevron-left' : 'chevron-right', {
-              size: '1em',
-            })}
-          </span>
-        </button>
-        <div className="velu-docs-layout__article" data-pagefind-body="">
-          {/* 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. */}
-          <ContextMenu
-            eyebrow={
-              nav?.breadcrumb && nav.breadcrumb.length > 1
-                ? nav.breadcrumb[nav.breadcrumb.length - 2].label
-                : undefined
-            }
-            pageUrl={pathname}
-            basePath={BASE_PATH}
-            title={frontmatter.title}
-            isApi={entry?.api === true}
-            siteName={site.name}
-            options={site.contextual?.options ?? []}
-            onAssistant={IS_DEV_PREVIEW || askAiHidden ? undefined : () => askAI('')}
-            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) && (
-            <div className="velu-hero">
-              {frontmatter.title && <h1 id={pageId}>{frontmatter.title}</h1>}
-              {frontmatter.description && (
-                <p
-                  style={{
-                    color: 'var(--muted-color)',
-                    fontSize: 'var(--f-h4)',
-                    lineHeight: 'var(--lh-h4)',
-                  }}
-                >
-                  {frontmatter.description}
-                </p>
-              )}
-            </div>
-          )}
-
-          {/* Article body — the current route's MDX page, rendered
-              through the velu-ui MDX component registry. `velu-prose`
-              gives a consistent vertical rhythm scaled by heading
-              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">
-              {PageComponent ? (
-                <ErrorBoundary key={pathname} file={entry?.relPath}>
-                  <PageComponent />
-                </ErrorBoundary>
-              ) : (
-                <p style={{ color: 'var(--muted-color)' }}>
-                  {entry?.missing
-                    ? 'This page is listed in navigation but its .mdx file was not found.'
-                    : 'Page not found.'}
-                </p>
-              )}
-            </div>
-          </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)' }}>
-            {/* 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). */}
-            <PageFeedback
-              key={pathname}
-              onVote={(v) => {
-                if (v === 'yes') pageFeedback?.submit({ helpful: true });
-              }}
-              onSubmit={({ reason, detail }) =>
-                pageFeedback?.submit({ helpful: false, reason, detail })
-              }
-            />
-          </div>
-          {/* Previous / next page navigation — derived from the
-              sidebar reading order of the active section. */}
-          {(nav?.prev || nav?.next) && (
-            <PageNav
-              style={{ marginTop: 'var(--s2)' }}
-              prev={nav?.prev}
-              next={nav?.next}
-              linkComponent={RouterLink}
-            />
-          )}
-          {/* "Ask a question" bar — sticky to viewport-bottom while the
-              article column is in view; lives inside the prose-column
-              div so its width matches the article. Submitting opens
-              the Ask-AI chatbot; fades out as the PageFeedback widget
-              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 && (
-            <AskBar
-              onSubmit={askAI}
-              style={{
-                position: 'sticky',
-                insetBlockEnd: 'var(--s1)',
-                /* Once the user has scrolled near the feedback widget the
-                   AskBar fades and collapses to zero flow space — height,
-                   margin, padding all drop to 0 so the next element
-                   (PoweredBy) sits directly under PageNav at its own
-                   32px margin, with no phantom gap. */
-                marginTop: askBarHidden ? 0 : 'var(--s2)',
-                height: askBarHidden ? 0 : 'auto',
-                overflow: 'hidden',
-                opacity: askBarHidden ? 0 : 1,
-                transform: askBarHidden ? 'translateY(20%)' : 'translateY(0)',
-                pointerEvents: askBarHidden ? 'none' : 'auto',
-                transition: 'opacity 0.2s ease, transform 0.2s ease',
-              }}
-            />
-          )}
-          {/* Content foot — "Powered by Velu" at the bottom-right of the
-              article column. When the footer has no link columns, the
-              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 />
-          ) : (
-            <div className="velu-content-foot">
-              <SocialLinks socials={footerSocials} />
-              <PoweredBy />
-            </div>
-          )}
-        </div>
-      </main>
-        </>
-        )}
-      </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. */}
-      {footerHasLinks && (
-        <div
-          ref={footerRef}
-          data-velu-footer
-          style={{ position: 'relative', zIndex: 20 }}
-        >
-          <PageFooter
-            brand={{ href: site.logo?.href || '/' }}
-            columns={site.footer.links}
-            socials={footerSocials}
-          />
-        </div>
-      )}
-
-      {/* Ask-AI chatbot — slides in from the inline-end edge. Hidden when the
-          docs owner's plan/credits disable Ask-AI. */}
-      {!askAiHidden && (
-      <Chatbot
-        open={chatOpen}
-        seedQuestion={chatQuestion}
-        onClose={() => setChatOpen(false)}
-        ask={assistant?.ask}
-        onFeedback={assistant?.sendFeedback}
-        listHistory={assistant?.listConversations}
-        loadConversation={assistant?.loadConversation}
-        suggestions={site.assistant?.suggestions}
-        onNavigate={(to) => {
-          navigate(to);
-          // After the destination page mounts, scroll to the cited section
-          // (its heading id) — or the top of the page when there's no anchor.
-          const hash = to.includes('#') ? to.slice(to.indexOf('#') + 1) : '';
-          let tries = 0;
-          const go = () => {
-            if (hash) {
-              if (document.getElementById(hash)) { scrollTo(hash); return; }
-              if (tries++ < 10) { setTimeout(go, 60); return; }
-            }
-            window.scrollTo({ top: 0, behavior: 'smooth' });
-          };
-          setTimeout(go, 50);
-        }}
-      />
-      )}
-    </div>
-  );
-}
-
-export default function App() {
-  return (
-    <Routes>
-      <Route path="*" element={<DocsPage />} />
-    </Routes>
-  );
-}
+import React from 'react';
+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
+// vite-plugin-velu-site (see src/vite-plugin-velu-site.js). `pages` is
+// url → { Component, frontmatter, toc } (or { missing:true }).
+import { pages, navigation, site } from 'virtual:velu-site';
+import { resolve, normalizeUrl } from '../navigation.js';
+import {
+  Stack,
+  Cluster,
+  ThemeToggle,
+  Sidebar,
+  NavSelect,
+  Toc,
+  TocBar,
+  ChangelogFilters,
+  ContextMenu,
+  Callout,
+  Accordion,
+  AccordionGroup,
+  Card,
+  CardGroup,
+  Switcher,
+  Image,
+  CodeBlock,
+  CodeGroup,
+  Columns,
+  Field,
+  Prompt,
+  Steps,
+  Step,
+  AskBar,
+  Chatbot,
+  PageFeedback,
+  PageNav,
+  PageFooter,
+  PageHeader,
+  PoweredBy,
+  defaultMdxComponents,
+  resolveIcon,
+  Search,
+  pagefindSearch,
+  createDocsAssistant,
+  createPageFeedback,
+  Logo,
+  SocialLinks,
+  Tree,
+  Folder,
+  File,
+  TryItBar,
+  ApiClient,
+  ApiField,
+  ApiSidebar,
+  ApiSamples,
+  NotFound,
+  VeluMark,
+} from 'velu-ui';
+import { X, ChevronDown, ChevronUp } from 'lucide-react';
+import ErrorBoundary from './ErrorBoundary.jsx';
+
+// True under `velu dev`, false in the deployed production build (Vite injects
+// this). AI features (Ask AI, the Ask-a-question bar) and full-text search run
+// on the deployed site, so they're hidden / shown-as-unavailable in the local
+// preview. Identical on SSR + client in each mode, so no hydration mismatch.
+const IS_DEV_PREVIEW = import.meta.env.DEV;
+
+// Subpath-hosting prefix (e.g. "/docs"), from Vite's BASE_URL. Empty at the
+// origin root. The router handles internal <Link>s on its own, but server-served
+// resources the router doesn't own — the .md twins, the /mcp endpoint — are
+// root-relative and need this prefix to resolve under a subpath.
+const BASE_PATH = (import.meta.env.BASE_URL || '/').replace(/\/$/, '');
+
+// Flatten a sidebar section's items (which may nest into sub-groups) into the
+// flat endpoint list <ApiSidebar> wants. API tabs are flat in practice; this
+// only guards the rare case of a normal nested group living beside generated
+// API operations in the same tab, so its leaf pages still get a working link.
+function sectionToEndpoints(items) {
+  const out = [];
+  for (const it of items ?? []) {
+    if (it.items) out.push(...sectionToEndpoints(it.items));
+    else
+      out.push({
+        method: it.method,
+        label: it.label,
+        href: it.href,
+        icon: it.icon,
+      });
+  }
+  return out;
+}
+
+const CALLOUT_TYPES = [
+  'note',
+  'warning',
+  'info',
+  'tip',
+  'check',
+  'danger',
+  'callout',
+];
+
+function CalloutGallery() {
+  return (
+    <Stack space="var(--s0)">
+      {CALLOUT_TYPES.map((t) => (
+        <Callout key={t} type={t}>
+          This is a {t}. This is a {t}. This is a {t}. This is a {t}.
+        </Callout>
+      ))}
+      <p style={{ color: 'var(--muted-color)' }}>
+        Custom callouts can be built with a custom icon &amp; color:
+      </p>
+      <Callout
+        icon="sparkles"
+        stroke="var(--accent-color)"
+        bg="color-mix(in srgb, var(--accent-color) 8%, transparent)"
+      >
+        A custom callout — lucide id <code>"sparkles"</code> with custom{' '}
+        <code>stroke</code> &amp; <code>bg</code>.
+      </Callout>
+
+      <Callout type="info">
+        This is a multi-line callout. It keeps going and going so the text
+        wraps onto several lines — the icon sits on the first line, the text
+        wraps beside it, and every line after flows back under the icon (no
+        hanging indent). Resize the window to watch the wrapping reflow while
+        the icon stays put on line one. This is a multi-line callout. It keeps
+        going so the text wraps onto several lines.
+      </Callout>
+    </Stack>
+  );
+}
+
+function AccordionDemo() {
+  return (
+    <Stack space="var(--s1)">
+      <Accordion title="This is an accordion">
+        This is content inside the accordion. Hover the header to see the
+        surface tint; the chevron rotates when expanded.
+      </Accordion>
+      <Accordion title="This is an accordion (open by default)" defaultOpen>
+        This one renders expanded — header takes the surface tint and a
+        divider separates it from this content.
+      </Accordion>
+      <AccordionGroup>
+        <Accordion title="This is an accordion">
+          Grouped items share one bordered box with dividers between them.
+        </Accordion>
+        <Accordion title="This is an accordion" defaultOpen>
+          This is content inside the accordion.
+        </Accordion>
+        <Accordion title="This is an accordion">
+          No per-item border or radius — the group owns the chrome.
+        </Accordion>
+      </AccordionGroup>
+    </Stack>
+  );
+}
+
+function CardDemo() {
+  return (
+    <Stack space="var(--s2)">
+      <Card icon="align-justify" title="Card Title">
+        This is how you use a card with an icon and a link. (Cards are not
+        clickable — only the CTA card's link is.)
+      </Card>
+
+      <Card icon="align-justify" title="Card Title" horizontal>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
+        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+        commodo consequat.
+      </Card>
+
+      <Card
+        img="https://picsum.photos/seed/velu/1200/560"
+        imgAlt="Yosemite valley"
+        title="Card Title"
+      >
+        This is how you use a card with an icon. The image fills the container
+        and is clipped to the card radius.
+      </Card>
+
+      <Card
+        icon="align-justify"
+        title="Card Title"
+        cta={{ label: 'Click Here', href: '#cards' }}
+      >
+        This is how you use a card with an icon and a link. The "Click Here"
+        link below is the only clickable element.
+      </Card>
+
+      <CardGroup>
+        <Card icon="align-justify" title="Card Title">
+          This is how you use a card with an icon and a link.
+        </Card>
+        <Card icon="align-justify" title="Card Title">
+          This is how you use a card with an icon and a link.
+        </Card>
+      </CardGroup>
+    </Stack>
+  );
+}
+
+function SwitcherBox({ children }) {
+  return (
+    <div
+      style={{
+        border: 'var(--border-width) solid var(--border-color)',
+        borderRadius: 'var(--radius-sm)',
+        padding: 'var(--s0) var(--s3)',
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+function SwitcherDemo() {
+  return (
+    <Stack space="var(--s1)">
+      <p style={{ color: 'var(--muted-color)' }}>
+        Resize the window — these flip between a row and a column at the
+        container threshold, with no media queries.
+      </p>
+      <Switcher space="var(--s0)" threshold="30rem">
+        <SwitcherBox>One</SwitcherBox>
+        <SwitcherBox>Two</SwitcherBox>
+        <SwitcherBox>Three</SwitcherBox>
+      </Switcher>
+      <p style={{ color: 'var(--muted-color)' }}>
+        With <code>limit={2}</code>: more than 2 items forces vertical
+        regardless of width.
+      </p>
+      <Switcher space="var(--s0)" threshold="30rem" limit={2}>
+        <SwitcherBox>One</SwitcherBox>
+        <SwitcherBox>Two</SwitcherBox>
+        <SwitcherBox>Three</SwitcherBox>
+      </Switcher>
+    </Stack>
+  );
+}
+
+const DEMO_JS = `let greeting = function (name) {
+  console.log(\`Hello, \${name}!\`);
+};`;
+const DEMO_RB = `def greeting(name)
+  puts "Hello, #{name}!"
+end`;
+const DEMO_PY = `def greeting(name):
+    print(f"Hello, {name}!")`;
+
+function CodeBlockDemo() {
+  return (
+    <Stack space="var(--s2)">
+      <p style={{ color: 'var(--muted-color)' }}>Code Group</p>
+      <CodeGroup>
+        <CodeBlock title="Javascript" language="javascript">
+          {DEMO_JS}
+        </CodeBlock>
+        <CodeBlock title="Ruby" language="ruby">
+          {DEMO_RB}
+        </CodeBlock>
+        <CodeBlock title="Python" language="python">
+          {DEMO_PY}
+        </CodeBlock>
+      </CodeGroup>
+
+      <p style={{ color: 'var(--muted-color)' }}>Code (with file name)</p>
+      <CodeBlock filename="index.js" language="javascript">
+        {DEMO_JS}
+      </CodeBlock>
+
+      <p style={{ color: 'var(--muted-color)' }}>
+        With line numbers (icon suppressed via <code>withIcon={'{false}'}</code>)
+      </p>
+      <CodeBlock
+        filename="index.js"
+        language="javascript"
+        withIcon={false}
+        lineNumbers
+      >
+        {DEMO_JS}
+      </CodeBlock>
+
+      <p style={{ color: 'var(--muted-color)' }}>
+        Line highlight — single line (<code>highlight="2"</code>)
+      </p>
+      <CodeBlock
+        filename="index.js"
+        language="javascript"
+        lineNumbers
+        highlight="2"
+      >
+        {DEMO_JS}
+      </CodeBlock>
+
+      <p style={{ color: 'var(--muted-color)' }}>
+        Line highlight — range + single (<code>highlight="1-2,4"</code>)
+      </p>
+      <CodeBlock
+        filename="server.js"
+        language="javascript"
+        lineNumbers
+        highlight="1-2,4"
+      >
+        {`const express = require('express');
+const app = express();
+
+app.get('/', (req, res) => res.send('Hello'));
+
+app.listen(3000);`}
+      </CodeBlock>
+    </Stack>
+  );
+}
+
+function ApiDemo() {
+  const path = '/project/preview/{projectId}';
+  const curl = `curl --request POST \\
+  --url https://api.mintlify.com/v1/project/update/{projectId} \\
+  --header 'Authorization: Bearer <token>'`;
+  return (
+    <Stack space="var(--s2)">
+      <p style={{ color: 'var(--muted-color)' }}>Try-it bar</p>
+      <Stack space="var(--s-1)">
+        <TryItBar method="POST" path={path} />
+        <TryItBar method="GET" path={path} />
+        <TryItBar method="PUT" path={path} />
+        <TryItBar method="DELETE" path={path} />
+        <TryItBar method="PATCH" path={path} />
+      </Stack>
+
+      <p style={{ color: 'var(--muted-color)' }}>API sidebar</p>
+      <ApiSidebar
+        activeHref="/api/status"
+        sections={[
+          {
+            title: 'Admin',
+            icon: 'rocket',
+            endpoints: [
+              { method: 'POST', label: 'Trigger', href: '/api/trigger' },
+              {
+                method: 'GET',
+                label: 'Get deployment-status',
+                href: '/api/status',
+              },
+              {
+                method: 'DELETE',
+                label: 'Trigger Preview deployment',
+                href: '/api/preview',
+              },
+            ],
+          },
+        ]}
+      />
+
+      <p style={{ color: 'var(--muted-color)' }}>API Client</p>
+      {/* Only the ApiClient breaks out of the 46rem prose column — the
+          TryItBars above stay at the normal column width. clamp keeps
+          it ≥ 100% (so it never collapses when the main-area calc goes
+          negative on narrow screens) and ≤ 64rem. */}
+      <div
+        style={{
+          width:
+            'clamp(100%, calc(100vw - 240px - 280px - var(--s4) * 2), 64rem)',
+        }}
+      >
+        <ApiClient
+          method="DELETE"
+          label="Trigger Delete"
+          path={path}
+          onClose={() => {}}
+          description="Trigger a documentation deployment programmatically to publish updates outside of Git workflows."
+          aside={
+            <Stack space="var(--s1)">
+              <Callout type="danger">401 — Unauthorized</Callout>
+              <CodeGroup>
+                <CodeBlock title="Response" language="json">
+                  {`{\n  "status": 401,\n  "error": "Unauthorized"\n}`}
+                </CodeBlock>
+                <CodeBlock title="Headers" language="http">
+                  {`HTTP/1.1 401 Unauthorized
+date: Mon, 27 Apr 2026 12:00:55 GMT
+content-type: application/json; charset=utf-8
+content-length: 24
+connection: close
+x-powered-by: Express
+access-control-allow-origin: *`}
+                </CodeBlock>
+              </CodeGroup>
+              <CodeGroup>
+                <CodeBlock title="Curl" language="bash">
+                  {curl}
+                </CodeBlock>
+                <CodeBlock title="Ruby" language="ruby">
+                  {`require 'net/http'
+uri = URI('https://api.mintlify.com/v1/project/update/<projectId>')
+req = Net::HTTP::Post.new(uri)
+req['Authorization'] = 'Bearer <token>'
+Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }`}
+                </CodeBlock>
+                <CodeBlock title="Python" language="python">
+                  {`import requests
+requests.post(
+    'https://api.mintlify.com/v1/project/update/<projectId>',
+    headers={'Authorization': 'Bearer <token>'},
+)`}
+                </CodeBlock>
+              </CodeGroup>
+              <CodeGroup>
+                <CodeBlock title="202" language="json">
+                  {`{\n  "statusId": "<string>"\n}`}
+                </CodeBlock>
+                <CodeBlock title="200" language="json">
+                  {`{\n  "statusId": "<string>",\n  "completedAt": "2026-04-27T12:00:55Z"\n}`}
+                </CodeBlock>
+              </CodeGroup>
+            </Stack>
+          }
+        >
+          <AccordionGroup>
+            <Accordion title="Authorization" defaultOpen>
+              <Stack space="var(--s1)">
+                <ApiField
+                  name="Authorization"
+                  type="string"
+                  required
+                  prefix="Bearer"
+                >
+                  The Authorization header expects a Bearer token. Use an
+                  admin API key (prefixed with <code>mint_</code>).
+                </ApiField>
+              </Stack>
+            </Accordion>
+            <Accordion title="Path" defaultOpen>
+              <Stack space="var(--s1)">
+                <ApiField name="projectId" type="string" required>
+                  Your project ID. Copy it from the API keys page.
+                </ApiField>
+                <ApiField name="bodyId" type="string" required>
+                  Your body ID. Copy it from the API keys page.
+                </ApiField>
+              </Stack>
+            </Accordion>
+            <Accordion title="Query">
+              <Stack space="var(--s1)">
+                <ApiField name="branch" type="string">
+                  Git branch to deploy. Defaults to the production branch.
+                </ApiField>
+                <ApiField name="dryRun" type="boolean" default="false">
+                  When true, validates the deployment without publishing.
+                </ApiField>
+              </Stack>
+            </Accordion>
+            <Accordion title="Headers">
+              <Stack space="var(--s1)">
+                <ApiField name="X-Idempotency-Key" type="string">
+                  Optional unique key so retried requests don't trigger
+                  duplicate deployments.
+                </ApiField>
+              </Stack>
+            </Accordion>
+            <Accordion title="Body">
+              <Stack space="var(--s1)">
+                <ApiField name="message" type="string">
+                  Deployment message shown in the activity log.
+                </ApiField>
+                <ApiField name="notify" type="boolean" default="true">
+                  Whether to notify when the deployment completes.
+                </ApiField>
+              </Stack>
+            </Accordion>
+          </AccordionGroup>
+        </ApiClient>
+      </div>
+    </Stack>
+  );
+}
+
+function TreeDemo() {
+  return (
+    <Tree>
+      <Folder name="app">
+        <File name="layout.tsx" />
+        <File name="page.tsx" />
+        <Folder name="api" defaultOpen={false}>
+          <File name="route.ts" />
+        </Folder>
+      </Folder>
+      <File name="package.json" />
+    </Tree>
+  );
+}
+
+function StepsDemo() {
+  return (
+    <Steps>
+      <Step title="Install the CLI">Run the install script.</Step>
+      <Step title="Bootstrap a new project">
+        Scaffold a fresh velu project with a single command, then drop in the
+        starter MDX so you can begin editing right away. The CLI prompts for a
+        project name and target directory, copies the template files, and
+        installs dependencies in the background while you keep working.
+      </Step>
+      <Step title="Add your first page">
+        Drop an MDX file into the <code>content/</code> directory.
+      </Step>
+      <Step title="Configure navigation">
+        Edit <code>velu.config.js</code> and add your page paths under the
+        sidebar tree. Nested groups are supported, every item can carry an
+        icon, and external links are flagged automatically. Save the file and
+        the dev server hot-reloads with the new structure.
+      </Step>
+      <Step title="Preview locally">
+        Run <code>velu dev</code> — the local preview opens at
+        <code> localhost:5173</code> with SSR + HMR. Edits to any MDX or React
+        component reflect instantly. The right-rail TOC is generated from the
+        page's headings; the comet trail follows scroll.
+      </Step>
+      <Step title="Push and ship">Open a PR. Done.</Step>
+    </Steps>
+  );
+}
+
+function PromptDemo() {
+  return (
+    <Prompt title="Generate clear, concise documentation." openInCursor>
+      {`You are a **technical writing assistant**. Write documentation that is clear, accurate, and concise.
+- Use second-person voice
+- Avoid jargon
+- Lead with what the reader can do, not how it works internally
+- Code blocks use the project's language conventions
+- Every example must be runnable as-is`}
+    </Prompt>
+  );
+}
+
+function FieldDemo() {
+  const desc =
+    'An example of a parameter field. An example of a parameter field. An example of a parameter field. An example of a parameter field. An example of a parameter field. An example of a parameter field';
+  return (
+    <div>
+      <Field
+        name="param"
+        pre="pre"
+        type="string"
+        required
+        default={3}
+        post="post"
+      >
+        {desc}
+      </Field>
+      <Field
+        name="param"
+        pre="pre"
+        type="string"
+        required
+        default={3}
+        post="post"
+      >
+        {desc}
+      </Field>
+      <Field
+        name="param"
+        pre="pre"
+        type="string"
+        required
+        default={3}
+        post="post"
+      >
+        {desc}
+      </Field>
+    </div>
+  );
+}
+
+function ColumnsDemo() {
+  return (
+    <Stack space="var(--s2)">
+      <p style={{ color: 'var(--muted-color)' }}>
+        Two equal columns (<code>cols=&#123;2&#125;</code>) — collapses to a
+        single stack when items would fall below their per-item min width.
+      </p>
+      <Columns cols={2}>
+        <Card
+          icon="align-justify"
+          title="Card Title"
+          cta={{ label: 'Click Here', href: '#columns' }}
+        >
+          This is how you use a card with an icon and a link. Clicking on
+          this card brings you to the Columns page.
+        </Card>
+        <Card
+          icon="align-justify"
+          title="Card Title"
+          cta={{ label: 'Click Here', href: '#columns' }}
+        >
+          This is how you use a card with an icon and a link. Clicking on
+          this card brings you to the Columns page.
+        </Card>
+      </Columns>
+
+      <p style={{ color: 'var(--muted-color)' }}>
+        Heterogeneous children — a Card alongside a CodeBlock.
+      </p>
+      <Columns cols={2}>
+        <Card icon="sparkles" title="With a card">
+          Cards, callouts, code, images — anything composes in a column.
+        </Card>
+        <CodeBlock filename="hello.js" language="javascript">
+          {DEMO_JS}
+        </CodeBlock>
+      </Columns>
+
+      <p style={{ color: 'var(--muted-color)' }}>
+        Three columns (<code>cols=&#123;3&#125;</code>) with a stacked column
+        in the middle.
+      </p>
+      <Columns cols={3}>
+        <Card icon="rocket" title="Left">
+          Single card on the left.
+        </Card>
+        <Stack space="var(--s0)">
+          <Card icon="book" title="Top">
+            Two cards stacked via Stack inside one column.
+          </Card>
+          <Card icon="brain" title="Bottom">
+            Stack lets a column carry heterogeneous, multi-item content.
+          </Card>
+        </Stack>
+        <Card icon="zap" title="Right">
+          Single card on the right.
+        </Card>
+      </Columns>
+    </Stack>
+  );
+}
+
+const DEMO_IMG = 'https://picsum.photos/seed/velu-yosemite/1200/600';
+const DEMO_SHOT = 'https://picsum.photos/seed/velu-shot/600/1000';
+
+function ImageDemo() {
+  return (
+    <Stack space="var(--s2)">
+      <p style={{ color: 'var(--muted-color)' }}>Image</p>
+      <Image src={DEMO_IMG} alt="" />
+
+      <p style={{ color: 'var(--muted-color)' }}>
+        Image with caption (caption can be markdown later)
+      </p>
+      <Image src={DEMO_IMG} alt="" caption="Caption for this image" />
+
+      <p style={{ color: 'var(--muted-color)' }}>Image with window chrome</p>
+      <Image src={DEMO_IMG} alt="" chrome="window" />
+
+      <p style={{ color: 'var(--muted-color)' }}>Image with display frame</p>
+      <Image src={DEMO_SHOT} alt="" chrome="frame" caption="Caption can also be added" />
+    </Stack>
+  );
+}
+
+const RouterLink = ({ href, ...rest }) => <Link to={href} {...rest} />;
+
+// Flatten a nested TOC tree to {id, label, depth} for scroll-spy.
+function flat(nodes, depth = 0, out = []) {
+  for (const n of nodes) {
+    out.push({ id: n.id, label: n.label, depth });
+    if (n.children) flat(n.children, depth + 1, out);
+  }
+  return out;
+}
+
+// Scroll-spy: active = the section whose top last crossed the trigger line.
+/**
+ * useScrollSpy — tracks the section currently in view, with an
+ * explicit "lock" override for click-driven scrolls.
+ *
+ * Without the lock, clicking a TOC item triggers a smooth-scroll
+ * animation; during the ~500ms animation the scroll listener fires
+ * many times with the page at intermediate positions, and the
+ * "closest section" answer flickers across multiple sections
+ * before settling — visible as the TocBar label briefly showing
+ * the wrong heading. The lock blocks spy updates for a configurable
+ * window so the click's intended `activeId` survives the animation.
+ *
+ * Returns `[activeId, setActive]` where `setActive(id)` writes the
+ * active id directly AND locks the spy for ~800ms.
+ */
+function useScrollSpy(ids) {
+  const [activeId, setActiveId] = React.useState(ids[0]);
+  const lockUntilRef = React.useRef(0);
+  React.useEffect(() => {
+    const onScroll = () => {
+      if (Date.now() < lockUntilRef.current) return;
+      // Trigger line reads from --velu-scroll-offset (published by
+      // App.jsx as header + tocbar-toggle + 1rem). Same offset CSS
+      // uses for scroll-margin, so a heading freshly scrolled into
+      // view sits exactly at the trigger. Semantics: pick the
+      // section whose top is CLOSEST to the trigger; tie-break
+      // favours later sections in document order.
+      const trigger =
+        parseFloat(
+          getComputedStyle(document.documentElement).getPropertyValue(
+            '--velu-scroll-offset',
+          ),
+        ) || 0;
+      const vh = window.innerHeight;
+      let best = ids[0];
+      let bestDist = Infinity;
+      for (const id of ids) {
+        const node = document.getElementById(id);
+        if (!node) continue;
+        const top = node.getBoundingClientRect().top;
+        if (top >= vh) continue;
+        const dist = Math.abs(top - trigger);
+        if (dist <= bestDist) {
+          bestDist = dist;
+          best = id;
+        }
+      }
+      setActiveId(best);
+    };
+    window.addEventListener('scroll', onScroll, { passive: true });
+    onScroll();
+    return () => window.removeEventListener('scroll', onScroll);
+  }, [ids]);
+
+  const setActive = React.useCallback((id) => {
+    setActiveId(id);
+    // ~800ms covers the default smooth-scroll animation duration.
+    lockUntilRef.current = Date.now() + 800;
+  }, []);
+
+  return [activeId, setActive];
+}
+
+// Slugger used for the frontmatter-derived h1 id — same library as
+// extract-toc + rehype-slug, so the id we render in the DOM matches
+// what the TOC's `pageId` will compute. (One instance per page render
+// is fine; the slugger is stateful only across calls on the SAME
+// instance.)
+import GithubSlugger from 'github-slugger';
+
+function DocsPage() {
+  // Resolve the current route → page entry + navigation context. Both
+  // SSR and client compute these from the same pathname + the same
+  // shared `resolve()`, so the render is identical (hydration-safe).
+  const location = useLocation();
+  const navigate = useNavigate();
+  const pathname = normalizeUrl(location.pathname);
+  const entry = pages[pathname];
+  // `navigation`/`pages` are module constants in dev/build (the deps never
+  // change there); the instant preview's virtual-site substitute reassigns
+  // the `pages` live binding as pages finish compiling, so listing them re-
+  // resolves nav (sidebar labels, breadcrumb, prev/next) as titles arrive.
+  const nav = React.useMemo(
+    () => resolve(pathname, navigation, pages),
+    [pathname, navigation, pages],
+  );
+
+  // Search source: Pagefind for content/excerpts, but resolve each result's
+  // breadcrumb from the real NAVIGATION (a page's nav group can differ from its
+  // URL path — e.g. essentials/markdown.mdx lives under the "Writing Content"
+  // group). Page rows show the path to the page; anchor rows include the page.
+  const searchDocs = React.useCallback(async (q) => {
+    const results = await pagefindSearch(q);
+    if (!Array.isArray(results)) return results;
+    return results.map((r) => {
+      const res = resolve(r.href.split('#')[0], navigation, pages);
+      if (!res?.breadcrumb?.length) return r;
+      const labels = res.breadcrumb.map((c) => c.label);
+      const crumbs = r.kind === 'anchor' ? labels : labels.slice(0, -1);
+      return crumbs.length ? { ...r, breadcrumb: crumbs } : r;
+    });
+  }, []);
+
+  // Ask-AI backend: wire the chatbot to the public docs-AI-assistant API only
+  // in a real build AND when an apiBase is configured (velu.json → assistant).
+  // Otherwise `ask` stays undefined and the Chatbot uses its canned demo answer
+  // (dev preview, or a site that hasn't enabled the assistant).
+  const assistant = React.useMemo(() => {
+    if (IS_DEV_PREVIEW) return null;
+    const apiBase = site.assistant?.apiBase;
+    if (!apiBase) return null;
+    return createDocsAssistant({ apiBase, host: site.assistant?.host });
+  }, []);
+
+  // Hide the Ask-AI widget when the docs owner's plan/credits disable it (the
+  // backend bootstrap returns ask_ai_enabled:false). Only applies to a real
+  // configured assistant — the dev-preview/demo widget stays visible.
+  const [askAiHidden, setAskAiHidden] = React.useState(false);
+  React.useEffect(() => {
+    if (!assistant) return undefined;
+    let alive = true;
+    assistant.isEnabled().then((ok) => {
+      if (alive && !ok) setAskAiHidden(true);
+    }).catch(() => {});
+    return () => { alive = false; };
+  }, [assistant]);
+
+  // Page-feedback backend: reuses the same injected apiBase as the assistant
+  // (baked into every published velu.json), so the "Was this page helpful?"
+  // widget can POST to /api/v1/public/feedback. Null in the dev preview, where
+  // the widget stays purely visual.
+  const pageFeedback = React.useMemo(() => {
+    if (IS_DEV_PREVIEW) return null;
+    const apiBase = site.assistant?.apiBase;
+    if (!apiBase) return null;
+    return createPageFeedback({ apiBase, host: site.assistant?.host });
+  }, []);
+
+  const frontmatter = entry?.frontmatter ?? {};
+  const PageComponent = entry?.Component ?? null;
+  const pageToc = entry?.toc ?? [];
+  // Changelog pages (any page with <Update> entries) carry a `changelog`
+  // export. We swap the right-rail TOC for tag filters and expose an RSS link.
+  const changelog = entry?.changelog ?? null;
+  const isChangelog = !!changelog;
+  const changelogTags = changelog?.tags ?? [];
+  // 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;
+
+  // Switcher option sets (only render a switcher when an axis has >1
+  // option). Anchors are pinned sidebar links shown in the context zone.
+  const productOptions = nav?.products ?? [];
+  const versionOptions = nav?.versions ?? [];
+  const languageOptions = nav?.languages ?? [];
+  const anchors = nav?.anchors ?? [];
+  const versionSwitcher = versionOptions.length > 1 && (
+    <NavSelect
+      size="sm"
+      value={nav.activeVersion}
+      options={versionOptions}
+      linkComponent={RouterLink}
+      ariaLabel="Version"
+    />
+  );
+  const languageSwitcher = languageOptions.length > 1 && (
+    <NavSelect
+      bare
+      icon="globe"
+      value={nav.activeLanguage}
+      valueCode={nav.activeLanguageCode}
+      options={languageOptions}
+      linkComponent={RouterLink}
+      ariaLabel="Language"
+    />
+  );
+  const productSwitcher = productOptions.length > 1 && (
+    <NavSelect
+      value={nav.activeProduct}
+      options={productOptions}
+      linkComponent={RouterLink}
+      ariaLabel="Product"
+    />
+  );
+
+  // Keep document.title / meta description / <html lang> in sync on client-side
+  // navigation. The HTML is SSR'd with a per-page (build) or generic (dev) title;
+  // without this the tab title would stay frozen on the first page as you
+  // navigate the SPA, and JS-executing crawlers would read the stale value.
+  React.useEffect(() => {
+    const t = frontmatter.title;
+    document.title = isNotFound
+      ? `Page not found - ${site.name}`
+      : t && t !== site.name
+        ? `${t} - ${site.name}`
+        : site.name;
+    let descTag = document.querySelector('meta[name="description"]');
+    if (!descTag) {
+      descTag = document.createElement('meta');
+      descTag.setAttribute('name', 'description');
+      document.head.appendChild(descTag);
+    }
+    descTag.setAttribute('content', frontmatter.description || '');
+    document.documentElement.lang = nav?.activeLanguageCode || 'en';
+  }, [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;
+    return new GithubSlugger().slug(frontmatter.title);
+  }, [frontmatter.title]);
+
+  // Combined TOC: the frontmatter title is the page's top-level entry,
+  // and the MDX-derived headings (h2s) become its children. Without this,
+  // the right rail starts from the first h2 — orphaning the page title
+  // that sits visibly above the article.
+  const toc = React.useMemo(() => {
+    if (!frontmatter.title || !pageId) return pageToc;
+    return [{ id: pageId, label: frontmatter.title, children: pageToc }];
+  }, [pageId, frontmatter.title, pageToc]);
+
+  // Flat list of section ids for scroll-spy — sourced from the same
+  // nested TOC tree we pass to the right-rail <Toc>, so spy + render
+  // can't drift out of sync with the MDX content.
+  const ids = React.useMemo(() => flat(toc).map((s) => s.id), [toc]);
+  const [activeId, setActive] = useScrollSpy(ids);
+
+  // Ask-AI chatbot: opens (slides in from the side) when a question is
+  // submitted in the AskBar. While it's open the TOC is hidden.
+  const [chatOpen, setChatOpen] = React.useState(false);
+  const [chatQuestion, setChatQuestion] = React.useState('');
+
+  // Left sidebar open/closed (narrow widths) — chevron toggle. Defaults
+  // open per design; safe to default true since the narrow-width
+  // sidebar is in-flow and doesn't obscure content.
+  const [sidebarOpen, setSidebarOpen] = React.useState(true);
+  // Mobile drawer open/closed (< 640px) — burger / breadcrumb / X /
+  // scrim drive this. Defaults closed so refreshing the page at
+  // mobile doesn't surface the drawer over the article. Independent
+  // of sidebarOpen so neither breakpoint's default leaks into the
+  // other.
+  const [drawerOpen, setDrawerOpen] = React.useState(false);
+
+  // Drawer's nav dropdown — list of section links (Home/Docs/Blog),
+  // mirrors the desktop tabs. Click-outside + Escape close.
+  const [navOpen, setNavOpen] = React.useState(false);
+  const navRef = React.useRef(null);
+  React.useEffect(() => {
+    if (!navOpen) return;
+    const onDocClick = (e) => {
+      if (!navRef.current?.contains(e.target)) setNavOpen(false);
+    };
+    const onKey = (e) => {
+      if (e.key === 'Escape') setNavOpen(false);
+    };
+    document.addEventListener('mousedown', onDocClick);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDocClick);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [navOpen]);
+
+  // Close the mobile drawer (and its nav dropdown) whenever the route changes,
+  // so picking a page from the sidebar collapses the drawer instead of leaving
+  // it open over the article.
+  React.useEffect(() => {
+    setDrawerOpen(false);
+    setNavOpen(false);
+  }, [pathname]);
+  // Mobile drawer's section picker = the resolved tabs (top-level
+  // navigation), so it mirrors the desktop tabs row instead of a
+  // hardcoded list. Its button shows the active tab's label.
+  const navItems = nav?.tabs ?? [];
+  const activeNavLabel =
+    navItems.find((t) => t.href === nav?.activeTab)?.label ??
+    navItems[0]?.label ??
+    '';
+  const askAI = React.useCallback((q) => {
+    setChatQuestion(q);
+    setChatOpen(true);
+  }, []);
+
+  // Measure the live sticky chrome — header + (collapsed) TocBar
+  // toggle — and publish three CSS variables on `:root`:
+  //
+  //   --velu-header-height   live header height
+  //   --velu-tocbar-height   TocBar's TOGGLE row height (always-
+  //                          visible bit; 0 when the bar isn't shown)
+  //   --velu-scroll-offset   header + tocbar-toggle + 1rem
+  //
+  // Measuring just the toggle row (NOT the expanded list) is
+  // important: the expanded dropdown's max-block-size is large, and
+  // including it in the offset would inflate scroll-margin /
+  // scroll-spy trigger as soon as the user expands the dropdown —
+  // causing the page geometry to lurch and the spy / active label
+  // to flicker.
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const header = document.querySelector('.velu-header');
+    if (!header) return;
+    const root = document.documentElement;
+    const remPx = parseFloat(getComputedStyle(root).fontSize) || 16;
+    // Skip same-value writes: these CSS vars affect layout, and an
+    // unconditional write on every ResizeObserver fire can feed back into
+    // layout (scrollbar appear/disappear flutter at narrow widths — observed
+    // as a permanent relayout storm inside the instant-preview iframe).
+    let lastHeaderH = -1;
+    let lastTocBarH = -1;
+    const apply = () => {
+      const headerH = Math.round(header.getBoundingClientRect().height);
+      // Re-query each apply — the TocBar toggle button is mounted
+      // after first paint and its parent may also remount on
+      // theme/viewport changes.
+      const tocBarToggle = document.querySelector('.velu-toc-bar__toggle');
+      const tocBarH = tocBarToggle
+        ? Math.round(tocBarToggle.getBoundingClientRect().height)
+        : 0;
+      if (headerH === lastHeaderH && tocBarH === lastTocBarH) return;
+      lastHeaderH = headerH;
+      lastTocBarH = tocBarH;
+      if (headerH > 0)
+        root.style.setProperty('--velu-header-height', `${headerH}px`);
+      root.style.setProperty('--velu-tocbar-height', `${tocBarH}px`);
+      // +1rem of breathing room between the chrome and the heading
+      // it's anchoring. The rem is read live so it stays in tokens.
+      root.style.setProperty(
+        '--velu-scroll-offset',
+        `${headerH + tocBarH + remPx}px`,
+      );
+    };
+    apply();
+    const ro = new ResizeObserver(apply);
+    ro.observe(header);
+    // Observe the toggle row only (not the expanded list) so the
+    // offset stays put when the user opens the dropdown.
+    const tocBarToggle = document.querySelector('.velu-toc-bar__toggle');
+    if (tocBarToggle) ro.observe(tocBarToggle);
+    return () => ro.disconnect();
+  }, []);
+
+  // 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).
+  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 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';
+      }
+    };
+    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);
+    });
+    window.addEventListener('resize', update);
+    return () => {
+      els.forEach((el) => el.removeEventListener('scroll', update));
+      ro.disconnect();
+      window.removeEventListener('resize', update);
+    };
+  }, [chatOpen, pathname]);
+
+  // 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.
+  React.useEffect(() => {
+    const scroller = leftAsideRef.current;
+    if (!scroller) return;
+    let prev = null;
+    const update = () => {
+      const top = scroller.getBoundingClientRect().top;
+      let stuck = null;
+      for (const h of scroller.querySelectorAll('.velu-sidebar__section')) {
+        if (h.getBoundingClientRect().top <= top + 1) stuck = h;
+      }
+      if (stuck !== prev) {
+        prev?.removeAttribute('data-stuck');
+        stuck?.setAttribute('data-stuck', 'true');
+        prev = stuck;
+      }
+    };
+    update();
+    scroller.addEventListener('scroll', update, { passive: true });
+    return () => scroller.removeEventListener('scroll', update);
+  }, [pathname, chatOpen]);
+
+  // Footer config (from velu.json via virtual:velu-site). Link columns →
+  // full footer section; socials with no columns → inline next to PoweredBy.
+  const footerSocials = site.footer?.socials ?? [];
+  const footerHasLinks = (site.footer?.links?.length ?? 0) > 0;
+
+  // Header top-right actions, built from velu.json's `navbar`: secondary
+  // `links` (plain text links) then the `primary` CTA (a filled button, or an
+  // outlined GitHub button). Empty when unconfigured — no placeholder buttons.
+  const navActions = [];
+  for (const l of site.navbar?.links ?? []) {
+    navActions.push({
+      label: l.label,
+      href: l.href,
+      icon: l.icon || undefined,
+      kind: 'link',
+      external: l.external,
+    });
+  }
+  if (site.navbar?.primary) {
+    const p = site.navbar.primary;
+    navActions.push({
+      label: p.label,
+      href: p.href,
+      kind: p.kind === 'github' ? 'outlined' : 'primary',
+      icon: p.kind === 'github' ? 'github' : undefined,
+      external: p.external,
+    });
+  }
+
+  const footerRef = React.useRef(null);
+  const [footerOverlap, setFooterOverlap] = React.useState(0);
+  React.useEffect(() => {
+    const node = footerRef.current;
+    if (!node) return;
+    const update = () => {
+      const rect = node.getBoundingClientRect();
+      setFooterOverlap(Math.max(0, window.innerHeight - rect.top));
+    };
+    update();
+    window.addEventListener('scroll', update, { passive: true });
+    window.addEventListener('resize', update);
+    return () => {
+      window.removeEventListener('scroll', update);
+      window.removeEventListener('resize', update);
+    };
+  }, []);
+
+  // 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 [askBarHidden, setAskBarHidden] = React.useState(false);
+  React.useEffect(() => {
+    const node = feedbackRef.current;
+    if (!node) return;
+    const FADE_BUFFER = 64; // matches the rootMargin below
+    const apply = (rect) => {
+      // Hide whenever the feedback's top has reached the (effective)
+      // viewport-bottom line — covers both "feedback is in view" AND
+      // "feedback is already scrolled past" without flickering back on.
+      // Threshold matches the IO's rootMargin so the show/hide flip is
+      // exactly at the same line in both scroll directions.
+      setAskBarHidden(rect.top < window.innerHeight - FADE_BUFFER);
+    };
+    apply(node.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);
+    return () => io.disconnect();
+  }, []);
+
+  const scrollTo = React.useCallback(
+    (id) => {
+      const node = document.getElementById(id);
+      if (!node) return;
+      // 1) Set + lock the active id IMMEDIATELY so the spy doesn't
+      //    overwrite it during the smooth-scroll animation.
+      setActive(id);
+      // 2) Compute the target scroll position MANUALLY (instead of
+      //    scrollIntoView). The browser clamps to max-scroll
+      //    automatically; the target is baked in at click time and
+      //    doesn't drift if layout shifts mid-animation.
+      const offset =
+        parseFloat(
+          getComputedStyle(document.documentElement).getPropertyValue(
+            '--velu-scroll-offset',
+          ),
+        ) || 0;
+      const top = node.getBoundingClientRect().top + window.scrollY - offset;
+      window.scrollTo({ top, behavior: 'smooth' });
+    },
+    [setActive],
+  );
+
+  const kicker = {
+    fontFamily: 'var(--font-mono)',
+    fontSize: 11,
+    letterSpacing: '0.6px',
+    textTransform: 'uppercase',
+    color: 'var(--muted-color)',
+  };
+
+  return (
+    <div
+      className="velu-docs-layout"
+      data-chat-open={chatOpen ? '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}
+    >
+      {/* Scrim — visible at mobile while the drawer OR the chatbot
+          sheet is open. Sits between the article (z-0) and the
+          drawer/chatbot (z-35 / z-50) and blocks pointer events to
+          everything beneath; click closes whichever surface is up. */}
+      <div
+        className="velu-docs-layout__scrim"
+        aria-hidden="true"
+        onClick={() => {
+          setDrawerOpen(false);
+          setChatOpen(false);
+        }}
+      />
+      {/* Site header — brand, centered search, right-side actions,
+          tabs row. Configurable: pass any number of actions / tabs. */}
+      <PageHeader
+        linkComponent={RouterLink}
+        brand={{
+          label: site.name,
+          href: site.logo?.href || '/',
+          logo: site.logo,
+        }}
+        brandTrailing={
+          versionSwitcher && (
+            <span className="velu-hide-on-mobile">{versionSwitcher}</span>
+          )
+        }
+        tabsTrailing={languageSwitcher || undefined}
+        center={
+          <Cluster space="var(--s-6)" align="center">
+            <Search
+              style={{ inlineSize: '30ch' }}
+              unavailable={IS_DEV_PREVIEW}
+              search={IS_DEV_PREVIEW ? undefined : searchDocs}
+              onSelect={(item) => item.href && navigate(item.href)}
+            />
+            {/* 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 && (
+              <button
+                type="button"
+                className="velu-header__action velu-header__action--outlined"
+                onClick={() => askAI('')}
+              >
+                <span className="velu-header__action-icon" aria-hidden="true">
+                  {resolveIcon('sparkles', { size: '1.5em' })}
+                </span>
+                <span>Ask AI</span>
+              </button>
+            )}
+          </Cluster>
+        }
+        actions={navActions}
+        trailing={<ThemeToggle />}
+        onMenuClick={() => setDrawerOpen((v) => !v)}
+        breadcrumb={nav?.breadcrumb ?? []}
+        activeTab={nav?.activeTab}
+        tabs={nav?.tabs ?? []}
+      />
+
+      {/* 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`). */}
+      <aside
+        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))`,
+        }}
+      >
+        {/* Drawer body — Stack with 32px gap composes the slots
+            (topbar / tab-dropdown / context / nav). The aside is a flex
+            column (CSS): the pinned slots keep their height and only the
+            nav region scrolls (see velu-docs-nav-scroll below). At wide
+            widths the topbar + docselect are `display: none`. */}
+        <Stack space="var(--s0)" className="velu-docs-aside-stack">
+          <div className="velu-docs-layout__drawer-head">
+            <RouterLink
+              href="/"
+              className="velu-docs-layout__drawer-brand"
+            >
+              {site.logo ? (
+                <Logo logo={site.logo} alt={site.name} />
+              ) : (
+                <>
+                  <VeluMark />
+                  <span className="velu-header__wordmark">{site.name}</span>
+                </>
+              )}
+            </RouterLink>
+            <ThemeToggle />
+            <button
+              type="button"
+              className="velu-docs-layout__drawer-close"
+              aria-label="Close navigation"
+              onClick={() => setDrawerOpen(false)}
+            >
+              <X aria-hidden="true" focusable="false" />
+            </button>
+          </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. */}
+          <div
+            ref={navRef}
+            className="velu-docs-layout__drawer-docselect"
+            data-open={navOpen ? 'true' : 'false'}
+          >
+            <button
+              type="button"
+              className="velu-docs-layout__drawer-docselect-btn"
+              onClick={() => setNavOpen((o) => !o)}
+              aria-haspopup="menu"
+              aria-expanded={navOpen}
+            >
+              <span className="velu-docs-layout__drawer-docselect-label">
+                {activeNavLabel}
+              </span>
+              <ChevronDown
+                className="velu-docs-layout__drawer-docselect-chev"
+                aria-hidden="true"
+                focusable="false"
+              />
+            </button>
+            <ul
+              className="velu-docs-layout__drawer-docselect-menu"
+              role="menu"
+              aria-hidden={!navOpen}
+            >
+              {navItems.map((it) => (
+                <li key={it.href} role="none">
+                  <a
+                    role="menuitem"
+                    className="velu-docs-layout__drawer-docselect-item"
+                    href={it.href}
+                    tabIndex={navOpen ? 0 : -1}
+                    onClick={() => setNavOpen(false)}
+                  >
+                    {it.label}
+                  </a>
+                </li>
+              ))}
+            </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 ||
+            languageSwitcher ||
+            anchors.length > 0) && (
+            <Stack space="var(--s-1)" className="velu-docs-context">
+              {productSwitcher}
+              {versionSwitcher && (
+                <span className="velu-show-on-mobile">{versionSwitcher}</span>
+              )}
+              {languageSwitcher && (
+                <span className="velu-show-on-mobile">{languageSwitcher}</span>
+              )}
+              {anchors.length > 0 && (
+                <ul className="velu-docs-anchors">
+                  {anchors.map((a, i) => (
+                    <li key={i}>
+                      <a
+                        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: '1em' })}
+                          </span>
+                        )}
+                        <span>{a.label}</span>
+                      </a>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </Stack>
+          )}
+          {/* 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" />
+          )}
+          {/* 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. */}
+          <div className="velu-docs-nav-region">
+            <div
+              ref={leftAsideRef}
+              className="velu-docs-nav-scroll velu-hide-scrollbar"
+              style={{
+                /* Just breathing room — the aside's bottom edge already
+                   stays above the footer (see --velu-aside-bottom). */
+                paddingBlockEnd: 'var(--s1)',
+                scrollPaddingBlockEnd: 'var(--s1)',
+              }}
+            >
+              {/* 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
+                  the sidebar shape). */}
+              {nav?.sidebarHasApi ? (
+                <ApiSidebar
+                  sections={(nav?.sidebarSections ?? []).map((s) => ({
+                    title: s.title,
+                    icon: s.icon,
+                    endpoints: sectionToEndpoints(s.items),
+                  }))}
+                  activeHref={pathname}
+                  linkComponent={RouterLink}
+                />
+              ) : (
+                <Sidebar
+                  sections={nav?.sidebarSections ?? []}
+                  activeHref={pathname}
+                  linkComponent={RouterLink}
+                />
+              )}
+            </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>
+      </aside>
+
+      {/* No separate rail element — at narrow widths the sidebar's
+          aside ANIMATES its `inline-size` between 240px (open) and
+          --velu-rail-width (closed), and its inner Sidebar nav fades
+          out via opacity. The aside's border-inline-end therefore
+          becomes the rail's right border when collapsed. This makes
+          the collapse a smooth width+opacity transition instead of a
+          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 && (
+        <aside
+          ref={rightAsideRef}
+          className="velu-docs-layout__aside velu-docs-layout__aside--right velu-hide-scrollbar"
+          style={{
+            /* Dynamic footer-overlap padding only — static geometry
+               lives in docs-layout.css. */
+            paddingBlockEnd: `calc(var(--s3) + ${footerOverlap}px + 2rem)`,
+            scrollPaddingBlockEnd: `calc(${footerOverlap}px + 2rem)`,
+          }}
+        >
+          {/* API reference pages put their code samples in the right rail
+              (where the TOC sits for normal pages). */}
+          {entry?.api && entry.operation ? (
+            <ApiSamples
+              samples={entry.samples}
+              responses={entry.operation.responses}
+            />
+          ) : isChangelog && changelogTags.length ? (
+            <ChangelogFilters tags={changelogTags} />
+          ) : (
+            <Toc items={toc} activeId={activeId} onSelect={scrollTo} />
+          )}
+        </aside>
+      )}
+
+      {/* Center column. Margin to reserve aside space lives in
+          docs-layout.css (drops to 0 at narrow widths via @container,
+          and the right margin collapses to 0 while the chatbot is
+          open via [data-chat-open="true"]). */}
+      <div className="velu-docs-layout__center">
+        {isNotFound ? (
+          <main className="velu-404-main">
+            <NotFound
+              homeHref="/"
+              linkComponent={RouterLink}
+              onSearch={() =>
+                window.dispatchEvent(
+                  new KeyboardEvent('keydown', { key: 'k', ctrlKey: true, metaKey: true }),
+                )
+              }
+              onAskAI={IS_DEV_PREVIEW || askAiHidden ? undefined : () => askAI('')}
+            />
+          </main>
+        ) : (
+        <>
+        {/* Narrow-layout TOC bar — always in DOM, only visible at
+            < 1024px (toggled by @container in toc-bar.css). Shares
+            its `items` + `activeId` + `onSelect` API with the
+            right-rail <Toc> so both views are driven by the same
+            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). */}
+        <TocBar items={toc} activeId={activeId} onSelect={scrollTo} />
+      <main
+        className="velu-docs-layout__main"
+        style={{
+          /* No padding-block-end — the article's last child (PoweredBy)
+             owns the gap to the footer via its own margin-bottom, so
+             padding-bottom here would double-count it. `position:
+             relative` makes <main> the offsetParent for the absolutely
+             positioned sidebar-toggle below — so its `top: 0` lands
+             at the top of the article area, BELOW the sticky TocBar
+             (which lives outside <main>). Padding-inline lives in CSS
+             so the @container query can collapse the start side when
+             the sidebar is closed (no "ghost column" on the left). */
+          position: 'relative',
+          color: 'var(--text-color)',
+        }}
+      >
+        {/* Sidebar toggle — narrow-layout only (hidden by @container
+            at wide widths). Lives inside <main> so its absolute
+            position is relative to the article area, not the centre
+            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. */}
+        <button
+          type="button"
+          className="velu-docs-layout__sidebar-toggle"
+          onClick={() => setSidebarOpen((v) => !v)}
+          aria-label={sidebarOpen ? 'Collapse sidebar' : 'Expand sidebar'}
+          aria-expanded={sidebarOpen}
+        >
+          <span aria-hidden="true">
+            {resolveIcon(sidebarOpen ? 'chevron-left' : 'chevron-right', {
+              size: '1em',
+            })}
+          </span>
+        </button>
+        <div className="velu-docs-layout__article" data-pagefind-body="">
+          {/* 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. */}
+          <ContextMenu
+            eyebrow={
+              nav?.breadcrumb && nav.breadcrumb.length > 1
+                ? nav.breadcrumb[nav.breadcrumb.length - 2].label
+                : undefined
+            }
+            pageUrl={pathname}
+            basePath={BASE_PATH}
+            title={frontmatter.title}
+            isApi={entry?.api === true}
+            siteName={site.name}
+            options={site.contextual?.options ?? []}
+            onAssistant={IS_DEV_PREVIEW || askAiHidden ? undefined : () => askAI('')}
+            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) && (
+            <div className="velu-hero">
+              {frontmatter.title && <h1 id={pageId}>{frontmatter.title}</h1>}
+              {frontmatter.description && (
+                <p
+                  style={{
+                    color: 'var(--muted-color)',
+                    fontSize: 'var(--f-h4)',
+                    lineHeight: 'var(--lh-h4)',
+                  }}
+                >
+                  {frontmatter.description}
+                </p>
+              )}
+            </div>
+          )}
+
+          {/* Article body — the current route's MDX page, rendered
+              through the velu-ui MDX component registry. `velu-prose`
+              gives a consistent vertical rhythm scaled by heading
+              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">
+              {PageComponent ? (
+                <ErrorBoundary key={pathname} file={entry?.relPath}>
+                  <PageComponent />
+                </ErrorBoundary>
+              ) : (
+                <p style={{ color: 'var(--muted-color)' }}>
+                  {entry?.missing
+                    ? 'This page is listed in navigation but its .mdx file was not found.'
+                    : 'Page not found.'}
+                </p>
+              )}
+            </div>
+          </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)' }}>
+            {/* 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). */}
+            <PageFeedback
+              key={pathname}
+              onVote={(v) => {
+                if (v === 'yes') pageFeedback?.submit({ helpful: true });
+              }}
+              onSubmit={({ reason, detail }) =>
+                pageFeedback?.submit({ helpful: false, reason, detail })
+              }
+            />
+          </div>
+          {/* Previous / next page navigation — derived from the
+              sidebar reading order of the active section. */}
+          {(nav?.prev || nav?.next) && (
+            <PageNav
+              style={{ marginTop: 'var(--s2)' }}
+              prev={nav?.prev}
+              next={nav?.next}
+              linkComponent={RouterLink}
+            />
+          )}
+          {/* "Ask a question" bar — sticky to viewport-bottom while the
+              article column is in view; lives inside the prose-column
+              div so its width matches the article. Submitting opens
+              the Ask-AI chatbot; fades out as the PageFeedback widget
+              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 && (
+            <AskBar
+              onSubmit={askAI}
+              style={{
+                position: 'sticky',
+                insetBlockEnd: 'var(--s1)',
+                /* Once the user has scrolled near the feedback widget the
+                   AskBar fades and collapses to zero flow space — height,
+                   margin, padding all drop to 0 so the next element
+                   (PoweredBy) sits directly under PageNav at its own
+                   32px margin, with no phantom gap. */
+                marginTop: askBarHidden ? 0 : 'var(--s2)',
+                height: askBarHidden ? 0 : 'auto',
+                overflow: 'hidden',
+                opacity: askBarHidden ? 0 : 1,
+                transform: askBarHidden ? 'translateY(20%)' : 'translateY(0)',
+                pointerEvents: askBarHidden ? 'none' : 'auto',
+                transition: 'opacity 0.2s ease, transform 0.2s ease',
+              }}
+            />
+          )}
+          {/* Content foot — "Powered by Velu" at the bottom-right of the
+              article column. When the footer has no link columns, the
+              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 />
+          ) : (
+            <div className="velu-content-foot">
+              <SocialLinks socials={footerSocials} />
+              <PoweredBy />
+            </div>
+          )}
+        </div>
+      </main>
+        </>
+        )}
+      </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. */}
+      {footerHasLinks && (
+        <div
+          ref={footerRef}
+          data-velu-footer
+          style={{ position: 'relative', zIndex: 20 }}
+        >
+          <PageFooter
+            brand={{ href: site.logo?.href || '/' }}
+            columns={site.footer.links}
+            socials={footerSocials}
+          />
+        </div>
+      )}
+
+      {/* Ask-AI chatbot — slides in from the inline-end edge. Hidden when the
+          docs owner's plan/credits disable Ask-AI. */}
+      {!askAiHidden && (
+      <Chatbot
+        open={chatOpen}
+        seedQuestion={chatQuestion}
+        onClose={() => setChatOpen(false)}
+        ask={assistant?.ask}
+        onFeedback={assistant?.sendFeedback}
+        listHistory={assistant?.listConversations}
+        loadConversation={assistant?.loadConversation}
+        suggestions={site.assistant?.suggestions}
+        onNavigate={(to) => {
+          navigate(to);
+          // After the destination page mounts, scroll to the cited section
+          // (its heading id) — or the top of the page when there's no anchor.
+          const hash = to.includes('#') ? to.slice(to.indexOf('#') + 1) : '';
+          let tries = 0;
+          const go = () => {
+            if (hash) {
+              if (document.getElementById(hash)) { scrollTo(hash); return; }
+              if (tries++ < 10) { setTimeout(go, 60); return; }
+            }
+            window.scrollTo({ top: 0, behavior: 'smooth' });
+          };
+          setTimeout(go, 50);
+        }}
+      />
+      )}
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="*" element={<DocsPage />} />
+    </Routes>
+  );
+}