@veluai/velu 0.2.35 → 0.2.37

package/docs/mintlify-migration.md

@@ -0,0 +1,159 @@
+# Migrate Mintlify documentation to Velu
+
+```sh
+velu migrate mintlify ./mintlify-docs --out ./velu-docs --dry-run
+velu migrate mintlify ./mintlify-docs --out ./velu-docs
+cd velu-docs
+velu validate .
+velu dev .
+```
+
+From this repository, replace `velu` with `node packages/velu-cli/bin/cli.js`.
+The command is included in the bundled public CLI. It has not been published
+until a package release is made.
+
+The source is a local repository/content directory containing `docs.json` or
+legacy `mint.json`. The command creates a **new directory** and leaves the source
+untouched. Without `--out`, it creates a sibling named `<source>-velu`. Existing
+destinations, destinations inside the source, and filename collisions are rejected.
+Files are staged before the completed directory is moved into place.
+
+`docs.json` takes precedence if both configs exist. Use `--config mint.json` to
+select the legacy file. JSON comments/trailing commas and local JSON/YAML config
+`$ref` files are supported. Config references cannot escape the source directory;
+remote references, fragments, and cycles fail with an explicit error.
+
+## Preview and CI
+
+| Option | Behavior |
+| --- | --- |
+| `--dry-run` | Runs analysis, transformations, and MDX compilation in memory; writes nothing |
+| `--json` | Prints only the machine-readable report |
+| `--strict` | Refuses to write output if there are warnings or errors |
+| `--out <directory>` | Sets the new destination |
+| `--config docs.json\|mint.json` | Selects the source configuration |
+| `--help` | Prints usage |
+
+Exit codes are `0` for completion without compatibility errors, `1` for invocation
+or filesystem failures, `2` for compatibility errors, and `3` when strict mode
+requires review. **Normal mode writes a reviewable migration even with code 2.**
+Warnings alone return 0 unless strict mode is enabled. The report still labels
+any migration with findings `needs-review`.
+
+Every migration writes `VELU-MIGRATION.md` and `velu-migration-report.json`.
+It also archives the fully resolved original config in
+`.velu-migration/source-config.json`, outside the publicly served assets.
+The JSON report includes per-file actions and SHA-256 output hashes, script
+conversions, skipped paths, and findings with source locations. Reports do not
+contain source script bodies or unsupported config values. They can contain
+filenames, endpoint paths, and diagnostic text; review before sharing.
+
+## Coverage
+
+| Area | Migration behavior |
+| --- | --- |
+| Config | Projects supported values against the shipped Velu schema; reports unsupported nested fields individually and preserves the original source config |
+| Legacy config | Converts navigation arrays, prefix-based tabs, anchors, topbar links/CTA, footer socials, and API base URL/example languages |
+| Navigation | Retains groups, tabs, products, versions, languages, root pages, and supported OpenAPI references; maps simple dropdown containers to tabs and merges global anchors/tabs with a review finding |
+| Branding | Copies logos/favicons, colors, navbar/footer, contextual menu and SEO; maps `description` to SEO metadata, body font family to `font`, and a dual favicon to one local variant |
+| Content | Converts content `.md` to `.mdx`; preserves frontmatter, prose, fenced examples, MDX expressions, and local components; compiles every migrated MDX file |
+| Components | Maps Note/Tip/Warning/Info/Check/Danger to Callout, ParamField/ResponseField to Field, Expandable to Accordion, CardGroup `cols` to `limit`, and Accordion `default-open` to `defaultOpen` |
+| React adapters | Adds an editable `snippets/velu-mintlify-compat.jsx` for Tabs/Tab, Frame, Tooltip, Badge, Button, and Panel; imports only used adapters into each MDX page |
+| Snippets | Preserves JSX/TSX modules; converts snippet-directory `.js` files to `.jsx` to avoid global execution; updates MDX and JS/TS module imports, including root-relative and extensionless imports |
+| Custom JavaScript | Preserves browser `.js` files byte-for-byte and inventories their execution risks; Velu loads them after hydration, once per full page load, in path order |
+| Custom CSS | Preserves styles; parses declarations to rewrite relative `url(...)` asset references to site-root paths; reports selectors/imports needing review |
+| Assets | Copies files and mirrors ordinary images, fonts, media, downloads, CSS/JS, and explicitly linked data into `public/` for existing URLs; retains originals for branding and local imports |
+| OpenAPI navigation | Preserves specs and references, reports missing/remote sources and the need to compare generated routes |
+| OpenAPI MDX pages | Materializes `openapi: spec.json GET /path`, or `GET /path` with a root spec reference, into an editable API playground snapshot without changing the page path or removing its body; supports single local specs with internal references |
+| npm scripts | Rewrites exact `mint`/`mintlify` dev, validate, version/v, and update invocations, including common package-manager launchers; adds the running Velu version as a dev dependency when Mintlify usage is found |
+| Ignore rules | Honors `.mintignore` using gitignore semantics, including negation; excludes dependencies, build caches, environment files, and known tooling directories |
+| Project tooling | Preserves shell scripts, package manifests, lockfiles, and CI workflows; flags Mintlify commands requiring manual replacement |
+
+## Custom scripts and remaining work
+
+Migration never executes project scripts, installs dependencies, or downloads
+remote assets/specs. Run your package manager afterward when `package.json` has
+changed; lockfiles and Mintlify dependencies are retained for review.
+
+Mintlify and Velu share many DOM selectors, but arbitrary JavaScript cannot be
+translated reliably without understanding its behavior. The report identifies
+Mintlify browser APIs (`window.mintlify`, user events), Next.js internals,
+DOMContentLoaded/load timing, module syntax in classic scripts, Node.js code in
+globally loaded `.js` files, and DOM-dependent code. These checks are static
+heuristics, not proof of complete runtime parity. For DOM-ready callbacks, check
+`document.readyState` and initialize immediately when the event has already fired.
+Verify behavior after client-side navigation as well as a full refresh.
+
+The `css-dom` finding flags styles aimed at shared chrome IDs such as `#content`,
+`#sidebar-content`, and `#footer`. Vepa aligns these common hooks with Sequoia,
+including a content-body-only `#content` and route-specific body remounting, but
+a shared ID does not guarantee identical nesting or dimensions for every component.
+Selectors are preserved for review,
+not automatically rewritten. Compare desktop and mobile pages with custom CSS
+enabled; successful asset copying is not a visual parity score.
+
+Endpoint snapshots are exported as `veluApi` metadata in MDX. Velu uses this
+metadata for API layout, request/response samples, and sidebar method badges;
+the original MDX body appears between the Try It bar and schema fields. Keep
+the export when editing a migrated endpoint. Re-migrate after OpenAPI changes
+to regenerate the snapshot.
+
+Files under `public/` and dot directories are not automatically loaded by Velu;
+their inclusion needs review. Root `.js` files are deliberately not rewritten
+because blindly changing lifecycle logic, globals, or selectors can alter behavior.
+Place Node tooling outside the docs content root or use `.cjs`/`.mjs` so it is not
+loaded as a browser script.
+
+The React adapters preserve basic interactions, not every Mintlify prop or exact
+appearance. Panel renders inline, Tooltip uses a text-only native tooltip, and
+Tabs supports keyboard navigation but does not synchronize selections across
+separate tab groups. Unknown components are reported as errors instead of being
+replaced with empty placeholders. Font Awesome/Tabler icon names may need Lucide
+equivalents. Original references in code examples and prose remain unchanged.
+
+Mintlify's `theme: "sequoia"` is converted to `theme: "vepa"` and activates the [Vepa preset](vepa.md).
+The preset is not a certification of pixel equality for every component or custom script.
+
+Features without full Velu equivalents require review: other Mintlify themes, advanced
+fonts and styling, redirects, analytics/support integrations, hosting settings,
+authentication, personalization, hidden-page routing, legacy version filtering,
+complex dropdown/global navigation, AsyncAPI, manually authored `api:` pages,
+multi-file/remote endpoint snapshots, OpenAPI overlays and `x-mint` extensions.
+Access/visibility settings are reported as errors; they must be migrated before
+publishing. Unlisted content is copied but Velu currently renders navigation
+pages only. Snapshot API pages must be regenerated or edited when their specs
+change. Existing generated robots/sitemap/LLM files can still contain old domains.
+
+`mint broken-links`, `mint a11y`, `mint export`, cloud/account commands, compound
+shell commands, and CLI flags have no automatically assumed equivalent. These
+scripts and workflows are retained with findings. In particular, `velu validate`
+is not a complete replacement for Mintlify's separate broken-link/a11y tools,
+and the public Velu package does not expose the internal static build command.
+
+## Parity research
+
+Inspected on 2026-09-08:
+
+- Published [`@mintlify/cli@4.0.1479`](https://www.npmjs.com/package/@mintlify/cli/v/4.0.1479): command dispatch/options in `bin/cli.js`; starter source in `bin/init.js`.
+- Published [`@mintlify/common@1.0.1132`](https://www.npmjs.com/package/@mintlify/common/v/1.0.1132): content/snippet categories and `.mintignore` semantics in `dist/getFileCategory.js` and `dist/mintIgnore.js`.
+- Published [`@mintlify/prebuild@1.0.1286`](https://www.npmjs.com/package/@mintlify/prebuild/v/1.0.1286): split config references and config loading.
+- [`docs.json` schema](https://www.mintlify.com/docs.json), [custom scripts documentation](https://www.mintlify.com/docs/customize/custom-scripts), and [official starter](https://github.com/mintlify/starter).
+
+The current `@mintlify/validation@0.1.849` tarball was also retrieved, but it did
+not contain its declared `dist/` implementation. Legacy conversion is implemented
+locally; it does not depend on executing Mintlify's upgrade code. No Mintlify
+implementation code or package is vendored as a runtime dependency.
+
+## Verification
+
+```sh
+node --test packages/velu-cli/test/migrate.test.mjs
+node --test packages/velu-cli/test/*.test.mjs
+node packages/velu-cli/scripts/build.mjs
+node packages/velu-cli/dist/cli.js migrate --help
+```
+
+Tests cover clean and review-required outputs, source immutability, JSONC/YAML
+references, ignore negation, collisions/junctions, script preservation, AST
+rewrites, assets, endpoint snapshots, generated-project validation, and CLI exit
+codes. No network is needed for the migration tests.

package/docs/vepa.md

@@ -0,0 +1,96 @@
+# Vepa (வேப்பம்) compatibility
+
+Enable the preset in `velu.json`:
+
+```json
+{
+  "name": "Documentation",
+  "theme": "vepa",
+  "colors": { "primary": "#16A34A", "light": "#07C983" },
+  "navigation": { "groups": [{ "group": "Guide", "pages": ["index"] }] }
+}
+```
+
+Mintlify migration converts `theme: "sequoia"` to `theme: "vepa"`. The normal Velu appearance is
+still the default when `theme` is omitted. The visual preset is separate from
+the reader's Light / Dark / System preference.
+
+For Vepa, `colors.primary` is the light-mode accent and `colors.light` is the
+dark-mode accent, matching Mintlify. The primary color also tints the gray ramp.
+`font.family` overrides Inter. Development, prerendered builds, and the browser
+preview share these normalizers.
+
+## Reference inspected
+
+The npm CLI does not ship the renderer inside its own package. Its previewing
+dependency retrieves a separately versioned client from Mintlify's release host.
+Research was pinned on 2026-09-08 to:
+
+- [`@mintlify/cli@4.0.1479`](https://www.npmjs.com/package/@mintlify/cli/v/4.0.1479)
+- [`@mintlify/previewing@4.0.1358`](https://www.npmjs.com/package/@mintlify/previewing/v/4.0.1358), `dist/constants.js`, `dist/util.js`, and `dist/local-preview/client.js`
+- [Client 0.0.3566](https://releases.mintlify.com/mint-0.0.3566.tar.gz), compiled Sequoia topbar, sidebar, page-header, and TOC modules
+- [`@mintlify/common@1.0.1132`](https://www.npmjs.com/package/@mintlify/common/v/1.0.1132), color composition
+
+Client archive SHA-256:
+`a2b758fd67159a066e14fa7e78599047b0fd7f5ae78477e7364efdc232ef7ee5`
+
+The downloaded client is research material only. It is not included in Velu's
+published package or used at runtime.
+
+## Measured geometry
+
+| Region | Vepa preset |
+| --- | --- |
+| Desktop topbar | 48 px; navigation tabs add 48 px |
+| Logo | 22 px high |
+| Desktop search trigger | 256 × 32 px |
+| Left sidebar | 288 px |
+| Default article at 1440 px viewport | 648 px; left edge 396 px |
+| Table of contents | 288 px rail with 32 px side padding |
+| API examples | 472 px rail including a 24 px outer gutter; 448 px sample cards |
+| API rail breakpoint | Hidden below 1280 px; article reclaims its space |
+| Mobile navigation | Below 1024 px; 48 px topbar and 56 px breadcrumb strip |
+| Title | Inter, 500 weight, 36/40 px; 30/36 px below 640 px |
+
+The API rail deliberately has its own width and padding. Applying the normal
+TOC's width leaves too little room for request tabs and response examples. Long
+code lines scroll inside their code panel instead of widening the page.
+
+The preset includes a plain TOC, tinted light/dark surfaces, a three-way theme
+menu, responsive columns, and mode-specific content widths. Card links retain
+their destinations, and navigation uses `sidebarTitle` when supplied.
+
+For custom styles, Vepa exposes `#page-title` on the title, `#content` on the
+ordinary MDX body (excluding the header), and `#sidebar-content` on the sidebar.
+The MDX body remounts on route changes so DOM decorations do not leak into the
+next page. Body font overrides inherit into prose; component headings retain
+their own typography. API pages use their own content structure.
+
+Migrated endpoint MDX exports a `veluApi` snapshot containing the operation,
+samples, and API settings. Both runtimes use it to activate the API layout and
+navigation method badges. Author imports and exports stay at module scope;
+custom content renders after the Try It bar and before the schema fields.
+
+## Verification and limits
+
+```sh
+node --test packages/velu-cli/test/vepa.test.mjs
+node packages/velu-cli/scripts/check-vepa-layout.mjs http://localhost:8358 /api-reference/products/listproducts /api-reference/products/addproduct
+```
+
+The browser check covers GET/POST pages at 1440, 1280, 1100, 768, and 390 px in
+light/dark mode. It checks rail size, sample width, column overlap, document
+overflow, closed drawers, language tabs, system preference changes, and runtime
+errors. Supply routes from your own running site.
+
+This is a source-informed compatibility preset, **not yet verified pixel-for-pixel
+across Mintlify's complete component/state matrix**. Velu still uses its own
+search, API playground, syntax highlighting, icons, feedback, and content
+components. Font availability can also affect screenshots. Hosted Mintlify
+services are not reproduced by copying theme settings. Custom scripts and CSS
+that depend on Mintlify's exact DOM, globals, lifecycle, or unsupported components
+need testing on the migrated site.
+
+Below the API rail breakpoint, samples move inline after the Try It bar and
+before custom content. Inline and desktop samples use distinct IDs. This
+document records the current scope rather than asserting complete parity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veluai/velu",
-  "version": "0.2.35",
+  "version": "0.2.37",
   "type": "module",
   "bin": "./dist/cli.js",
   "publishConfig": {
@@ -16,7 +16,9 @@
     "src/lib/known-components.js",
     "runtime/velu-ui/**",
     "schema/**",
-    "templates/**"
+    "templates/**",
+    "docs/mintlify-migration.md",
+    "docs/vepa.md"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -26,6 +28,7 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
+    "@babel/parser": "7.28.0",
     "@icons-pack/react-simple-icons": ">=13.0.0 <13.13.0",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
@@ -36,10 +39,13 @@
     "estree-util-value-to-estree": "^3.5.0",
     "express": "^4.21.1",
     "github-slugger": "^2.0.0",
+    "ignore": "7.0.5",
     "iso-639-1": "^3.1.5",
     "js-yaml": "^4.1.0",
+    "jsonc-parser": "3.3.1",
     "lucide-react": "^0.460.0",
     "mdast-util-to-string": "^4.0.0",
+    "postcss": "8.5.0",
     "prism-react-renderer": "^2.4.0",
     "prismjs": "^1.29.0",
     "react": "^18.3.1",

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

@@ -39,7 +39,7 @@ export function Accordion({
     .join(' ');
 
   return (
-    <details className={cls} open={defaultOpen || undefined} {...rest}>
+    <details className={cls} data-component="accordion" open={defaultOpen || undefined} {...rest}>
       <summary className="velu-accordion__summary">
         <span className="velu-accordion__chevron" aria-hidden="true">
           {resolveIcon('chevron-right', { size: '1em' })}
@@ -54,9 +54,9 @@ export function Accordion({
 export function AccordionGroup({ children, className = '', ...rest }) {
   return (
     <GroupCtx.Provider value={true}>
-      <div className={`velu-accordion-group ${className}`.trim()} {...rest}>
+      <accordion-group class={`velu-accordion-group ${className}`.trim()} {...rest}>
         {children}
-      </div>
+      </accordion-group>
     </GroupCtx.Provider>
   );
 }

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

@@ -110,10 +110,11 @@ export default function ApiClient({
         align="flex-start"
         className="velu-api-client__head"
       >
-        <div className="velu-api-client__op" ref={opRef}>
+        <option-dropdown class="velu-api-client__op" ref={opRef}>
           {canSwitch ? (
             <button
               type="button"
+              id="endpoints-menu-trigger"
               className="velu-api-client__op-btn"
               onClick={() => setMenuOpen((v) => !v)}
               aria-haspopup="listbox"
@@ -166,7 +167,7 @@ export default function ApiClient({
               ))}
             </ul>
           )}
-        </div>
+        </option-dropdown>
         <TryItBar
           method={method}
           path={path}
@@ -183,6 +184,7 @@ export default function ApiClient({
           visible without scrolling past the inputs; the form and code samples
           follow. See api.css. */}
       <div
+        id="api-playground-input"
         className="velu-api-client__body"
         data-has-response={response != null ? 'true' : undefined}
       >

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

@@ -27,7 +27,7 @@ import { sendApiRequest } from '../lib/api-send.js';
  */
 const LOCATION_LABEL = { path: 'Path Parameters', query: 'Query Parameters', header: 'Header Parameters' };
 
-export default function ApiReferencePage({ operation, samples = [], apiOperations = [], api = {} }) {
+export default function ApiReferencePage({ operation, samples = [], apiOperations = [], api = {}, children, preset }) {
   const [open, setOpen] = useState(false);
   // Which operation the playground is currently showing. Defaults to this
   // page's own operation; the dropdown can switch it to any sibling.
@@ -78,16 +78,19 @@ export default function ApiReferencePage({ operation, samples = [], apiOperation
         className="velu-api-page__tryit"
       />
 
+      {preset === 'vepa' && <div className="velu-api-page__inline-samples"><ApiSamples idPrefix="inline-" samples={samples} responses={operation.responses} preset={preset} title={operation.title} /></div>}
+      {children && <div className="velu-api-page__custom-content">{children}</div>}
+
       {/* Authorizations */}
       {operation.auth?.length > 0 && (
-        <section className="velu-api-page__section">
-          <h2>Authorizations</h2>
+        <api-section class="velu-api-page__section">
+          <h2 data-component="api-section-heading">Authorizations</h2>
           {operation.auth.map((a, i) => (
             <Field key={i} name={a.name} pre={a.prefix} type={a.type} required={a.required} post={a.in}>
               {a.description}
             </Field>
           ))}
-        </section>
+        </api-section>
       )}
 
       {/* Parameters, by location */}
@@ -95,37 +98,37 @@ export default function ApiReferencePage({ operation, samples = [], apiOperation
         const rows = operation.parameters?.[loc] || [];
         if (!rows.length) return null;
         return (
-          <section key={loc} className="velu-api-page__section">
-            <h2>{LOCATION_LABEL[loc]}</h2>
+          <api-section key={loc} class="velu-api-page__section">
+            <h2 data-component="api-section-heading">{LOCATION_LABEL[loc]}</h2>
             {rows.map((p, i) => (
               <Field key={i} name={p.name} type={p.type} required={p.required}>
                 {p.description}
                 {p.enum && <EnumHint values={p.enum} />}
               </Field>
             ))}
-          </section>
+          </api-section>
         );
       })}
 
       {/* Request body */}
       {operation.body?.fields?.length > 0 && (
-        <section className="velu-api-page__section">
-          <h2>Body</h2>
+        <api-section class="velu-api-page__section">
+          <h2 data-component="api-section-heading">Body</h2>
           {operation.body.fields.map((f, i) => (
             <Field key={i} name={f.name} type={f.type} required={f.required}>
               {f.description}
               {f.enum && <EnumHint values={f.enum} />}
             </Field>
           ))}
-        </section>
+        </api-section>
       )}
 
       {/* Responses */}
       {operation.responses?.length > 0 && (
-        <section className="velu-api-page__section">
-          <h2>Response</h2>
-          <ResponseSections responses={operation.responses} />
-        </section>
+        <api-section class="velu-api-page__section">
+          <h2 data-component="api-section-heading">Response</h2>
+          <ResponseSections responses={operation.responses} preset={preset} />
+        </api-section>
       )}
 
       {/* Try-It playground — rendered as an overlay above the page, with a
@@ -175,7 +178,12 @@ function EnumHint({ values }) {
   );
 }
 
-function ResponseSections({ responses }) {
+function ResponseSections({ responses, preset }) {
+  if (preset === 'vepa') return <div className="velu-vepa-responses">{responses.map((r, i) => <section key={i}>
+    <div className="velu-vepa-responses__status">{r.status}{r.contentType && ` · ${r.contentType}`}</div>
+    {r.description && <p>{r.description}</p>}
+    {r.fields?.map((f, j) => <Field key={j} name={f.name} type={f.type} required={f.required}>{f.description}</Field>)}
+  </section>)}</div>;
   return (
     <AccordionGroup className="velu-api-resp">
       {responses.map((r, i) => {

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

@@ -9,12 +9,17 @@ import CodeBlock, { CodeGroup } from './CodeBlock.jsx';
  *
  * @param {{ samples: {key,label,language,code}[], responses: object[] }} props
  */
-export default function ApiSamples({ samples = [], responses = [] }) {
+export default function ApiSamples({ samples = [], responses = [], preset, title, idPrefix = '' }) {
+  const [selected, setSelected] = React.useState('');
+  const sample = samples.find((s) => s.key === selected) || samples[0];
   const withExample = responses.filter((r) => r.example != null);
   return (
     <div className="velu-api-samples">
-      {samples.length > 0 && (
-        <CodeGroup className="velu-api-samples__req">
+      {sample && preset === 'vepa' ? <section id={idPrefix + 'request-example'} className="velu-vepa-request">
+        <div className="velu-vepa-request__header"><span>{title}</span><select aria-label="Request example language" value={sample.key} onChange={(e) => setSelected(e.target.value)}>{samples.map((s) => <option key={s.key} value={s.key}>{s.label}</option>)}</select></div>
+        <CodeBlock language={sample.language}>{sample.code}</CodeBlock>
+      </section> : samples.length > 0 && (
+        <CodeGroup id={idPrefix + 'request-example'} className="velu-api-samples__req">
           {samples.map((s) => (
             <CodeBlock key={s.key} title={s.label} language={s.language}>
               {s.code}
@@ -23,7 +28,7 @@ export default function ApiSamples({ samples = [], responses = [] }) {
         </CodeGroup>
       )}
       {withExample.length > 0 && (
-        <CodeGroup className="velu-api-samples__res">
+        <CodeGroup id={idPrefix + 'response-example'} className="velu-api-samples__res">
           {withExample.map((r) => (
             <CodeBlock key={r.status} title={r.status} language="json">
               {JSON.stringify(r.example, null, 2)}

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

@@ -48,7 +48,7 @@ export default function AskBar({
   const isEmpty = value.trim().length === 0;
 
   return (
-    <div className={`velu-ask-bar ${className}`.trim()} {...rest}>
+    <chat-assistant-floating-input class={`velu-ask-bar ${className}`.trim()} {...rest}>
       <textarea
         className="velu-ask-bar__input"
         placeholder={placeholder}
@@ -59,6 +59,7 @@ export default function AskBar({
       />
       <button
         type="button"
+        data-component="chat-assistant-send-button"
         className="velu-ask-bar__send"
         onClick={submit}
         disabled={isEmpty}
@@ -66,6 +67,6 @@ export default function AskBar({
       >
         {resolveIcon('arrow-up', { size: '1em' })}
       </button>
-    </div>
+    </chat-assistant-floating-input>
   );
 }

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

@@ -73,42 +73,27 @@ export default function Callout({
   // (.lucide rule in base.css), not set per-icon.
   const iconNode = resolveIcon(icon ?? v.icon, { size: '1em' });
 
+  // Static styles live in callout.css so a project's custom CSS can override
+  // them with a plain `callout { ... }` element selector (inline styles would
+  // beat any stylesheet). Only the per-instance colours are inline, as custom
+  // properties the stylesheet reads.
   return (
-    <div
-      className={className}
+    <callout
+      className={`velu-callout ${className}`.trim()}
+      data-type={type}
       style={{
-        display: 'flow-root', // contains the floated icon, no clipping
-        padding: 'var(--s0) var(--s3)',
-        background: bgColor,
-        border: `var(--border-width) solid ${strokeColor}`,
-        borderRadius: 'var(--radius-sm)',
-        color: 'var(--text-color)',
-        fontSize: 'var(--f-body)',
-        lineHeight: 'var(--lh-body)',
+        '--velu-callout-bg': bgColor,
+        '--velu-callout-stroke': strokeColor,
         ...style,
       }}
       {...rest}
     >
       {iconNode && (
-        <span
-          aria-hidden="true"
-          style={{
-            float: 'left',
-            display: 'inline-flex',
-            alignItems: 'center',
-            // one line-box tall (body font-size × body line-height token) so
-            // the icon is centered on the FIRST line; text wraps beside it
-            // then flows back under it (no hanging indent).
-            blockSize: 'calc(var(--f-body) * var(--lh-body))',
-            marginInlineEnd: 'var(--s-1)',
-            color: strokeColor,
-            fontSize: 'var(--f-body)',
-          }}
-        >
+        <span className="velu-callout__icon" aria-hidden="true">
           {iconNode}
         </span>
       )}
       {children}
-    </div>
+    </callout>
   );
 }

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

@@ -5,9 +5,9 @@ import Switcher from '../primitives/Switcher.jsx';
 /**
  * Card + CardGroup — content / horizontal / image / CTA cards.
  *
- * The card itself is NEVER a link and has NO hover state. The only
- * interactive element is the CTA: pass `cta={{ label, href }}` to render a
- * single "Click Here ›" link. Everything else is static presentation.
+ * Pass `href` (without `cta`) to make the whole card a stretched link.
+ * Nested links/buttons inside the card stay clickable above that overlay.
+ * Pass `cta={{ label, href }}` for a single "Click Here ›" control instead.
  *
  * Fully tokenized (border-width, border-color, radius scale, spacing, type,
  * line-height, accent, icon-stroke) → light/dark automatic via [data-theme].
@@ -22,7 +22,7 @@ import Switcher from '../primitives/Switcher.jsx';
  * `icon` is a lucide id string (shared resolveIcon).
  *
  * @param {{ title?: React.ReactNode, icon?: string, horizontal?: boolean,
- *   img?: string, imgAlt?: string,
+ *   img?: string, imgAlt?: string, href?: string,
  *   cta?: {label: React.ReactNode, href: string},
  *   children?: React.ReactNode, className?: string }} props
  */
@@ -34,6 +34,7 @@ export function Card({
   img,
   imgAlt = '',
   cta,
+  href,
   children,
   className = '',
   ...rest
@@ -49,13 +50,13 @@ export function Card({
     .join(' ');
 
   const iconEl = icon ? (
-    <span className="velu-card__icon" aria-hidden="true">
+    <span className="velu-card__icon" data-component-part="card-icon" aria-hidden="true">
       {resolveIcon(icon, { size: '1em' })}
     </span>
   ) : null;
 
   const ctaEl = cta ? (
-    <a className="velu-card__cta" href={cta.href}>
+    <a className="velu-card__cta" data-component-part="card-cta" href={cta.href}>
       {cta.label}
       <span className="velu-card__cta-icon" aria-hidden="true">
         {resolveIcon('chevron-right', { size: '1em' })}
@@ -64,21 +65,22 @@ export function Card({
   ) : null;
 
   const titleEl = title ? (
-    <div className="velu-card__title">{title}</div>
+    <div className="velu-card__title" data-component-part="card-title">{title}</div>
   ) : null;
   const textEl = children ? (
-    <div className="velu-card__text">{children}</div>
+    <div className="velu-card__text" data-component-part="card-content">{children}</div>
   ) : null;
 
   return (
-    <div className={cls} {...rest}>
+    <card className={cls} {...rest}>
+      {href && !cta && <a className="velu-card__link" href={href} aria-label={typeof title === 'string' ? title : 'Read more'} />}
       {img && (
-        <div className="velu-card__media">
+        <div className="velu-card__media" data-component-part="card-image">
           <img src={img} alt={imgAlt} loading="lazy" />
         </div>
       )}
 
-      <div className="velu-card__body">
+      <div className="velu-card__body" data-component-part="card-content-container">
         {horizontal ? (
           <>
             {iconEl}
@@ -97,7 +99,7 @@ export function Card({
           </>
         )}
       </div>
-    </div>
+    </card>
   );
 }
 
@@ -117,10 +119,12 @@ export function CardGroup({
 }) {
   return (
     <Switcher
+      as="card-group"
       className={`velu-card-group ${className}`.trim()}
       space={space}
       min={min}
       limit={limit}
+      style={{ '--vepa-columns': Math.max(1, Math.min(4, Number(limit) || 2)) }}
       {...rest}
     >
       {children}