@veluai/velu 0.1.13 → 0.1.15

package/src/runtime/App.jsx

@@ -1,1476 +1,1506 @@
-import React from 'react';
-import { Routes, Route, useLocation, 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 } from 'virtual:velu-site';
-import { resolve, normalizeUrl } from '../navigation.js';
-import {
-  Stack,
-  Cluster,
-  ThemeToggle,
-  Sidebar,
-  NavSelect,
-  Toc,
-  TocBar,
-  Callout,
-  Accordion,
-  AccordionGroup,
-  Card,
-  CardGroup,
-  Switcher,
-  Image,
-  CodeBlock,
-  CodeGroup,
-  Columns,
-  Field,
-  Prompt,
-  Steps,
-  Step,
-  AskBar,
-  Chatbot,
-  PageFeedback,
-  PageNav,
-  PageFooter,
-  PageHeader,
-  PoweredBy,
-  defaultMdxComponents,
-  resolveIcon,
-  Search,
-  Tree,
-  Folder,
-  File,
-  TryItBar,
-  ApiClient,
-  ApiField,
-  ApiSidebar,
-  VeluMark,
-} from 'velu-ui';
-import { X, ChevronDown, ChevronUp } from 'lucide-react';
-import ErrorBoundary from './ErrorBoundary.jsx';
-
-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 pathname = normalizeUrl(location.pathname);
-  const entry = pages[pathname];
-  const nav = React.useMemo(
-    () => resolve(pathname, navigation, pages),
-    [pathname],
-  );
-
-  const frontmatter = entry?.frontmatter ?? {};
-  const PageComponent = entry?.Component ?? null;
-  const pageToc = entry?.toc ?? [];
-
-  // 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"
-    />
-  );
-
-  // 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]);
-  // 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;
-    const apply = () => {
-      const headerH = 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
-        ? tocBarToggle.getBoundingClientRect().height
-        : 0;
-      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]);
-
-  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'}
-    >
-      {/* 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: 'Velu', href: '/' }}
-        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' }} />
-            <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={[
-          {
-            label: 'Book Demo',
-            kind: 'primary',
-            href: '#',
-          },
-        ]}
-        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"
-            >
-              <VeluMark />
-              <span className="velu-header__wordmark">Velu</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>
-          )}
-          {/* 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
-                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)`,
-          }}
-        >
-          <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">
-        {/* 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. */}
-        <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">
-          {/* 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)' }}>
-            <PageFeedback />
-          </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). */}
-          <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',
-            }}
-          />
-          {/* "Powered by Velu" attribution — bottom-right of the
-              article column, just under the AskBar. Muted so it reads
-              as a footer-of-content note, not a brand statement. */}
-          <PoweredBy />
-        </div>
-      </main>
-      </div>
-
-      {/* Site footer — spans full width below the article. Its raised
-          z-index ensures it visually eclipses the bottoms of the fixed
-          left sidebar and right TOC as the page scrolls into it. The
-          ref is watched so the asides can pad their bottom by the same
-          overlap amount, keeping every item scrollable into view. */}
-      <div
-        ref={footerRef}
-        data-velu-footer
-        style={{ position: 'relative', zIndex: 20 }}
-      >
-      <PageFooter
-        brand={{ href: '#' }}
-        columns={[
-          {
-            title: 'Resources',
-            items: [
-              { label: 'Showcase', href: '#' },
-              { label: 'Enterprise', href: '#' },
-              { label: 'Status', href: '#' },
-            ],
-          },
-          {
-            title: 'Company',
-            items: [
-              { label: 'Careers', href: '#' },
-              { label: 'Blog', href: '#' },
-              { label: 'Community', href: '#' },
-            ],
-          },
-          {
-            title: 'Policies',
-            items: [
-              { label: 'Subprocessors', href: '#' },
-              { label: 'Terms of Service', href: '#' },
-            ],
-          },
-        ]}
-        socials={[
-          { kind: 'github', href: 'https://github.com/aravindc26/velu-cli' },
-          { kind: 'x', href: 'https://x.com/' },
-          { kind: 'youtube', href: 'https://youtube.com/' },
-          { kind: 'linkedin', href: 'https://linkedin.com/' },
-        ]}
-      />
-      </div>
-
-      {/* Ask-AI chatbot — slides in from the inline-end edge. */}
-      <Chatbot
-        open={chatOpen}
-        seedQuestion={chatQuestion}
-        onClose={() => setChatOpen(false)}
-      />
-    </div>
-  );
-}
-
-export default function App() {
-  return (
-    <Routes>
-      <Route path="*" element={<DocsPage />} />
-    </Routes>
-  );
-}
+import React from 'react';
+import { Routes, Route, useLocation, 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,
+  Callout,
+  Accordion,
+  AccordionGroup,
+  Card,
+  CardGroup,
+  Switcher,
+  Image,
+  CodeBlock,
+  CodeGroup,
+  Columns,
+  Field,
+  Prompt,
+  Steps,
+  Step,
+  AskBar,
+  Chatbot,
+  PageFeedback,
+  PageNav,
+  PageFooter,
+  PageHeader,
+  PoweredBy,
+  defaultMdxComponents,
+  resolveIcon,
+  Search,
+  Logo,
+  SocialLinks,
+  Tree,
+  Folder,
+  File,
+  TryItBar,
+  ApiClient,
+  ApiField,
+  ApiSidebar,
+  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;
+
+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 pathname = normalizeUrl(location.pathname);
+  const entry = pages[pathname];
+  const nav = React.useMemo(
+    () => resolve(pathname, navigation, pages),
+    [pathname],
+  );
+
+  const frontmatter = entry?.frontmatter ?? {};
+  const PageComponent = entry?.Component ?? null;
+  const pageToc = entry?.toc ?? [];
+
+  // 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"
+    />
+  );
+
+  // 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]);
+  // 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;
+    const apply = () => {
+      const headerH = 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
+        ? tocBarToggle.getBoundingClientRect().height
+        : 0;
+      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'}
+    >
+      {/* 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} />
+            {/* Ask AI talks to the deployed site's AI backend — hidden in
+                the local dev preview where there's nothing to talk to. */}
+            {!IS_DEV_PREVIEW && (
+              <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>
+          )}
+          {/* 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
+                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)`,
+          }}
+        >
+          <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">
+        {/* 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. */}
+        <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">
+          {/* 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)' }}>
+            <PageFeedback />
+          </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 && (
+            <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. */}
+      <Chatbot
+        open={chatOpen}
+        seedQuestion={chatQuestion}
+        onClose={() => setChatOpen(false)}
+      />
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="*" element={<DocsPage />} />
+    </Routes>
+  );
+}