@veluai/velu 0.2.25 → 0.2.27

package/src/runtime/ErrorBoundary.jsx

@@ -1,54 +1,54 @@
-import React from 'react';
-import { ErrorCard } from 'velu-ui';
-import { extractMdxError } from '../lib/extract-mdx-error.js';
-import { CATEGORY_LABEL } from '../lib/issues.js';
-import { KNOWN_COMPONENTS } from '../lib/known-components.js';
-
-/**
- * Catches render-time errors from the current page (unknown component, a
- * component that threw on a bad prop, etc.) and renders a branded ErrorCard in
- * its place — leaving the surrounding chrome (header, sidebar, TOC) mounted.
- *
- * This is the CLIENT-side safety net: when the reader navigates (react-router,
- * no full reload) to a page that throws, the chrome stays put and only the
- * body shows the card. On a direct load / reload of a broken page the error
- * happens during SSR instead — React's renderToString doesn't recover through
- * error boundaries, so the dev server catches it there and serves the
- * full-page branded error (and logs it to the terminal).
- *
- * In `App.jsx` it's keyed by `pathname`, so navigating to another page (or
- * fixing the file and reloading) remounts it and clears the error.
- */
-export default class ErrorBoundary extends React.Component {
-  constructor(props) {
-    super(props);
-    this.state = { error: null };
-  }
-
-  static getDerivedStateFromError(error) {
-    return { error };
-  }
-
-  render() {
-    const { error } = this.state;
-    if (!error) return this.props.children;
-
-    const issue = extractMdxError(error, {
-      knownComponents: KNOWN_COMPONENTS,
-      file: this.props.file || null,
-    });
-    return (
-      <ErrorCard
-        label={CATEGORY_LABEL[issue.category] || issue.category}
-        title={issue.title}
-        file={issue.file}
-        line={issue.line}
-        column={issue.column}
-        frame={issue.frame}
-        detail={issue.detail}
-        hint={issue.hint}
-        suggestion={issue.suggestion}
-      />
-    );
-  }
-}
+import React from 'react';
+import { ErrorCard } from 'velu-ui';
+import { extractMdxError } from '../lib/extract-mdx-error.js';
+import { CATEGORY_LABEL } from '../lib/issues.js';
+import { KNOWN_COMPONENTS } from '../lib/known-components.js';
+
+/**
+ * Catches render-time errors from the current page (unknown component, a
+ * component that threw on a bad prop, etc.) and renders a branded ErrorCard in
+ * its place — leaving the surrounding chrome (header, sidebar, TOC) mounted.
+ *
+ * This is the CLIENT-side safety net: when the reader navigates (react-router,
+ * no full reload) to a page that throws, the chrome stays put and only the
+ * body shows the card. On a direct load / reload of a broken page the error
+ * happens during SSR instead — React's renderToString doesn't recover through
+ * error boundaries, so the dev server catches it there and serves the
+ * full-page branded error (and logs it to the terminal).
+ *
+ * In `App.jsx` it's keyed by `pathname`, so navigating to another page (or
+ * fixing the file and reloading) remounts it and clears the error.
+ */
+export default class ErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+
+    const issue = extractMdxError(error, {
+      knownComponents: KNOWN_COMPONENTS,
+      file: this.props.file || null,
+    });
+    return (
+      <ErrorCard
+        label={CATEGORY_LABEL[issue.category] || issue.category}
+        title={issue.title}
+        file={issue.file}
+        line={issue.line}
+        column={issue.column}
+        frame={issue.frame}
+        detail={issue.detail}
+        hint={issue.hint}
+        suggestion={issue.suggestion}
+      />
+    );
+  }
+}

package/src/runtime/client-entry.jsx

@@ -1,27 +1,27 @@
-import React from 'react';
-import { hydrateRoot } from 'react-dom/client';
-import { BrowserRouter } from 'react-router-dom';
-import 'velu-ui/styles.css';
-import App from './App.jsx';
-
-// Subpath hosting: Vite sets BASE_URL from the build's `base` (e.g. "/docs/").
-// React Router wants a basename WITHOUT the trailing slash ("/docs"); the root
-// case ("/") becomes undefined so the router behaves as if mounted at origin.
-const basename = (import.meta.env.BASE_URL || '/').replace(/\/$/, '') || undefined;
-
-hydrateRoot(
-  document.getElementById('root'),
-  <BrowserRouter basename={basename}>
-    <App />
-  </BrowserRouter>
-);
-
-// Dev only: the SSR-inlined critical CSS (<style data-velu-ssr>) exists just
-// to avoid FOUC on first paint. By now Vite has injected its own HMR-managed
-// stylesheet from the `velu-ui/styles.css` import above, so drop the stale
-// inline copy — otherwise it shadows hot CSS updates and edits don't apply.
-if (import.meta.hot) {
-  for (const el of document.querySelectorAll('style[data-velu-ssr]')) {
-    el.remove();
-  }
-}
+import React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import 'velu-ui/styles.css';
+import App from './App.jsx';
+
+// Subpath hosting: Vite sets BASE_URL from the build's `base` (e.g. "/docs/").
+// React Router wants a basename WITHOUT the trailing slash ("/docs"); the root
+// case ("/") becomes undefined so the router behaves as if mounted at origin.
+const basename = (import.meta.env.BASE_URL || '/').replace(/\/$/, '') || undefined;
+
+hydrateRoot(
+  document.getElementById('root'),
+  <BrowserRouter basename={basename}>
+    <App />
+  </BrowserRouter>
+);
+
+// Dev only: the SSR-inlined critical CSS (<style data-velu-ssr>) exists just
+// to avoid FOUC on first paint. By now Vite has injected its own HMR-managed
+// stylesheet from the `velu-ui/styles.css` import above, so drop the stale
+// inline copy — otherwise it shadows hot CSS updates and edits don't apply.
+if (import.meta.hot) {
+  for (const el of document.querySelectorAll('style[data-velu-ssr]')) {
+    el.remove();
+  }
+}

package/src/runtime/server-entry.jsx

@@ -1,24 +1,24 @@
-import React from 'react';
-import { renderToString } from 'react-dom/server';
-import { StaticRouter } from 'react-router-dom/server';
-// Side-effect import: stubbed to empty during SSR, but it registers the
-// stylesheet in Vite's SSR module graph so dev-server.js can collect and
-// inline it into <head> (flicker-free SSR).
-import 'velu-ui/styles.css';
-import App from './App.jsx';
-
-// Subpath hosting: mirror the client's basename (from Vite's BASE_URL). The
-// prerender is driven by root-relative route paths ("/foo"), so the location
-// handed to StaticRouter must carry the basename prefix ("/docs/foo") for it to
-// match — and so the rendered <Link> hrefs come out prefixed too, matching what
-// the hydrated BrowserRouter produces.
-const basename = (import.meta.env.BASE_URL || '/').replace(/\/$/, '');
-
-export async function render(url) {
-  const location = basename ? `${basename}${url}` : url;
-  return renderToString(
-    <StaticRouter basename={basename || undefined} location={location}>
-      <App />
-    </StaticRouter>
-  );
-}
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { StaticRouter } from 'react-router-dom/server';
+// Side-effect import: stubbed to empty during SSR, but it registers the
+// stylesheet in Vite's SSR module graph so dev-server.js can collect and
+// inline it into <head> (flicker-free SSR).
+import 'velu-ui/styles.css';
+import App from './App.jsx';
+
+// Subpath hosting: mirror the client's basename (from Vite's BASE_URL). The
+// prerender is driven by root-relative route paths ("/foo"), so the location
+// handed to StaticRouter must carry the basename prefix ("/docs/foo") for it to
+// match — and so the rendered <Link> hrefs come out prefixed too, matching what
+// the hydrated BrowserRouter produces.
+const basename = (import.meta.env.BASE_URL || '/').replace(/\/$/, '');
+
+export async function render(url) {
+  const location = basename ? `${basename}${url}` : url;
+  return renderToString(
+    <StaticRouter basename={basename || undefined} location={location}>
+      <App />
+    </StaticRouter>
+  );
+}

package/src/template.html

@@ -1,48 +1,48 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title><!--app-title--></title>
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link
-      rel="stylesheet"
-      href="https://fonts.googleapis.com/css2?family=Google+Sans+Code:wght@400;500&family=Google+Sans+Flex:opsz,wght@6..144,1..1000&family=Outfit:wght@300;400;500&display=swap"
-    />
-    <script>
-      // Anti-flash: set the theme BEFORE first paint so CSS vars resolve
-      // correctly on frame 1. Two-state; first visit follows the OS, an
-      // explicit choice (localStorage) is remembered and overrides the OS.
-      (function () {
-        try {
-          var KEY = 'velu-theme';
-          var mq = matchMedia('(prefers-color-scheme: dark)');
-          var saved = localStorage.getItem(KEY);
-          var theme =
-            saved === 'light' || saved === 'dark'
-              ? saved
-              : mq.matches
-                ? 'dark'
-                : 'light';
-          document.documentElement.dataset.theme = theme;
-          // Track the OS only until the user makes an explicit choice.
-          mq.addEventListener('change', function () {
-            var s = localStorage.getItem(KEY);
-            if (s !== 'light' && s !== 'dark')
-              document.documentElement.dataset.theme = mq.matches
-                ? 'dark'
-                : 'light';
-          });
-        } catch (e) {
-          document.documentElement.dataset.theme = 'light';
-        }
-      })();
-    </script>
-    <!--app-head-->
-  </head>
-  <body>
-    <div id="root"><!--app-html--></div>
-    <script type="module" src="/src/runtime/client-entry.jsx"></script>
-  </body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><!--app-title--></title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Google+Sans+Code:wght@400;500&family=Google+Sans+Flex:opsz,wght@6..144,1..1000&family=Outfit:wght@300;400;500&display=swap"
+    />
+    <script>
+      // Anti-flash: set the theme BEFORE first paint so CSS vars resolve
+      // correctly on frame 1. Two-state; first visit follows the OS, an
+      // explicit choice (localStorage) is remembered and overrides the OS.
+      (function () {
+        try {
+          var KEY = 'velu-theme';
+          var mq = matchMedia('(prefers-color-scheme: dark)');
+          var saved = localStorage.getItem(KEY);
+          var theme =
+            saved === 'light' || saved === 'dark'
+              ? saved
+              : mq.matches
+                ? 'dark'
+                : 'light';
+          document.documentElement.dataset.theme = theme;
+          // Track the OS only until the user makes an explicit choice.
+          mq.addEventListener('change', function () {
+            var s = localStorage.getItem(KEY);
+            if (s !== 'light' && s !== 'dark')
+              document.documentElement.dataset.theme = mq.matches
+                ? 'dark'
+                : 'light';
+          });
+        } catch (e) {
+          document.documentElement.dataset.theme = 'light';
+        }
+      })();
+    </script>
+    <!--app-head-->
+  </head>
+  <body>
+    <div id="root"><!--app-html--></div>
+    <script type="module" src="/src/runtime/client-entry.jsx"></script>
+  </body>
+</html>

package/templates/starter/ai-tools/claude-code.mdx

@@ -1,26 +1,26 @@
----
-title: Claude Code
-description: Work on your docs with Claude Code.
----
-
-Claude Code can read your `velu.json` and `.mdx` files to draft pages,
-restructure navigation, and keep content consistent.
-
-<Callout type="tip">
-  Keep page paths and `navigation` in sync — ask Claude to add a page
-  and wire it into the right group in one step.
-</Callout>
-
-## Suggested workflow
-
-<Steps>
-  <Step title="Describe the page">
-    Tell Claude the title and what it should cover.
-  </Step>
-  <Step title="Review the draft">
-    Claude writes the `.mdx` and adds it to `navigation`.
-  </Step>
-  <Step title="Preview">
-    `velu dev` reloads so you can read it in place.
-  </Step>
-</Steps>
+---
+title: Claude Code
+description: Work on your docs with Claude Code.
+---
+
+Claude Code can read your `velu.json` and `.mdx` files to draft pages,
+restructure navigation, and keep content consistent.
+
+<Callout type="tip">
+  Keep page paths and `navigation` in sync — ask Claude to add a page
+  and wire it into the right group in one step.
+</Callout>
+
+## Suggested workflow
+
+<Steps>
+  <Step title="Describe the page">
+    Tell Claude the title and what it should cover.
+  </Step>
+  <Step title="Review the draft">
+    Claude writes the `.mdx` and adds it to `navigation`.
+  </Step>
+  <Step title="Preview">
+    `velu dev` reloads so you can read it in place.
+  </Step>
+</Steps>

package/templates/starter/ai-tools/cursor.mdx

@@ -1,17 +1,17 @@
----
-title: Cursor
-description: Edit your docs in Cursor.
----
-
-Cursor's editor understands your project structure, so it can complete
-`navigation` entries and scaffold pages from a prompt.
-
-<Callout type="note">
-  Point Cursor at `velu.json` when asking it to reorganize the sidebar
-  — that's the single source of truth for structure.
-</Callout>
-
-## Tips
-
-- Reference an existing page as a style example when drafting a new one.
-- Ask for a whole group at once, then refine page by page.
+---
+title: Cursor
+description: Edit your docs in Cursor.
+---
+
+Cursor's editor understands your project structure, so it can complete
+`navigation` entries and scaffold pages from a prompt.
+
+<Callout type="note">
+  Point Cursor at `velu.json` when asking it to reorganize the sidebar
+  — that's the single source of truth for structure.
+</Callout>
+
+## Tips
+
+- Reference an existing page as a style example when drafting a new one.
+- Ask for a whole group at once, then refine page by page.

package/templates/starter/api-reference/introduction.mdx

@@ -1,43 +1,43 @@
----
-title: Introduction
-description: How this API reference is generated.
----
-
-The endpoints in this tab are generated automatically from an OpenAPI
-spec (`openapi.json`). Each operation becomes its own page — with
-parameters, request body, and responses — and an interactive **Try It**
-playground you can use to send real requests.
-
-<Callout type="note">
-  This is a second tab ("API Reference"). Tabs let you keep guides and
-  reference docs in separate top-level sections of the same site. Point
-  the tab's `openapi` field at your own spec to replace this example.
-</Callout>
-
-## How it works
-
-Add an `openapi` field to a tab (or group) in `velu.json`:
-
-```json
-{
-  "tab": "API Reference",
-  "openapi": "/openapi.json"
-}
-```
-
-Velu reads the spec, groups the operations by their tag, and renders a
-page per endpoint. No hand-written endpoint pages required.
-
-## The example API
-
-This starter points at a live demo API — a small **product catalog**
-backed by [dummyjson.com](https://dummyjson.com). Open any endpoint in
-the sidebar, hit **Try It**, and send a real request:
-
-- **Get a product** — try `id` = `1`
-- **Search products** — try `q` = `phone`
-- **Add a product** — the body is pre-filled; Send returns a created product
-
-Requests are routed through the dev server's proxy so they aren't blocked
-by CORS. Set `api.playground.proxy` to `false` to send straight from the
-browser.
+---
+title: Introduction
+description: How this API reference is generated.
+---
+
+The endpoints in this tab are generated automatically from an OpenAPI
+spec (`openapi.json`). Each operation becomes its own page — with
+parameters, request body, and responses — and an interactive **Try It**
+playground you can use to send real requests.
+
+<Callout type="note">
+  This is a second tab ("API Reference"). Tabs let you keep guides and
+  reference docs in separate top-level sections of the same site. Point
+  the tab's `openapi` field at your own spec to replace this example.
+</Callout>
+
+## How it works
+
+Add an `openapi` field to a tab (or group) in `velu.json`:
+
+```json
+{
+  "tab": "API Reference",
+  "openapi": "/openapi.json"
+}
+```
+
+Velu reads the spec, groups the operations by their tag, and renders a
+page per endpoint. No hand-written endpoint pages required.
+
+## The example API
+
+This starter points at a live demo API — a small **product catalog**
+backed by [dummyjson.com](https://dummyjson.com). Open any endpoint in
+the sidebar, hit **Try It**, and send a real request:
+
+- **Get a product** — try `id` = `1`
+- **Search products** — try `q` = `phone`
+- **Add a product** — the body is pre-filled; Send returns a created product
+
+Requests are routed through the dev server's proxy so they aren't blocked
+by CORS. Set `api.playground.proxy` to `false` to send straight from the
+browser.

package/templates/starter/development.mdx

@@ -1,19 +1,19 @@
----
-title: Development
-description: Preview your docs locally as you write.
----
-
-`velu dev` serves your project with server-side rendering and live
-reload, so what you see locally matches production.
-
-<Callout type="note">
-  The dev server reads `velu.json` from the folder you point it at.
-  Run it from your project root, or pass the path: `velu dev ./docs`.
-</Callout>
-
-## What reloads automatically
-
-- Editing any `.mdx` page reloads that page.
-- Editing `velu.json` (colors, font, favicon, navigation) re-renders
-  the whole site.
-- Adding or removing a page file updates the route map.
+---
+title: Development
+description: Preview your docs locally as you write.
+---
+
+`velu dev` serves your project with server-side rendering and live
+reload, so what you see locally matches production.
+
+<Callout type="note">
+  The dev server reads `velu.json` from the folder you point it at.
+  Run it from your project root, or pass the path: `velu dev ./docs`.
+</Callout>
+
+## What reloads automatically
+
+- Editing any `.mdx` page reloads that page.
+- Editing `velu.json` (colors, font, favicon, navigation) re-renders
+  the whole site.
+- Adding or removing a page file updates the route map.

package/templates/starter/essentials/code.mdx

@@ -1,29 +1,29 @@
----
-title: Code blocks
-description: Syntax-highlighted code and groups.
----
-
-Fenced code blocks are upgraded to a rich code component with a copy
-button and a language label.
-
-```js
-export function greet(name) {
-  return `Hello, ${name}!`;
-}
-```
-
-## Code groups
-
-Show the same example in several languages with a `CodeGroup`. Each
-alternative is a `<CodeBlock>` with a `title` (the tab label) and a
-`language` (drives syntax highlighting and the tab's language icon):
-
-<CodeGroup>
-  <CodeBlock title="index.js" language="javascript">
-    {`fetch('/api/hello').then((r) => r.json());`}
-  </CodeBlock>
-  <CodeBlock title="main.py" language="python">
-    {`import requests
-requests.get('/api/hello').json()`}
-  </CodeBlock>
-</CodeGroup>
+---
+title: Code blocks
+description: Syntax-highlighted code and groups.
+---
+
+Fenced code blocks are upgraded to a rich code component with a copy
+button and a language label.
+
+```js
+export function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+## Code groups
+
+Show the same example in several languages with a `CodeGroup`. Each
+alternative is a `<CodeBlock>` with a `title` (the tab label) and a
+`language` (drives syntax highlighting and the tab's language icon):
+
+<CodeGroup>
+  <CodeBlock title="index.js" language="javascript">
+    {`fetch('/api/hello').then((r) => r.json());`}
+  </CodeBlock>
+  <CodeBlock title="main.py" language="python">
+    {`import requests
+requests.get('/api/hello').json()`}
+  </CodeBlock>
+</CodeGroup>

package/templates/starter/essentials/images.mdx

@@ -1,29 +1,29 @@
----
-title: Images
-description: Add images and visual media.
----
-
-Use standard Markdown images, or the `Image` component for captions
-and framing.
-
-```md
-![Alt text](/images/diagram.png)
-```
-
-<Callout type="tip">
-  Put assets in a folder like `/images` at your project root and
-  reference them with an absolute path.
-</Callout>
-
-## Cards with media
-
-Cards can hold images, prose, or anything else:
-
-<CardGroup>
-  <Card title="Light & dark" icon="moon">
-    Assets and colors adapt to the active theme.
-  </Card>
-  <Card title="Responsive" icon="smartphone">
-    Layout reflows cleanly from desktop to mobile.
-  </Card>
-</CardGroup>
+---
+title: Images
+description: Add images and visual media.
+---
+
+Use standard Markdown images, or the `Image` component for captions
+and framing.
+
+```md
+![Alt text](/images/diagram.png)
+```
+
+<Callout type="tip">
+  Put assets in a folder like `/images` at your project root and
+  reference them with an absolute path.
+</Callout>
+
+## Cards with media
+
+Cards can hold images, prose, or anything else:
+
+<CardGroup>
+  <Card title="Light & dark" icon="moon">
+    Assets and colors adapt to the active theme.
+  </Card>
+  <Card title="Responsive" icon="smartphone">
+    Layout reflows cleanly from desktop to mobile.
+  </Card>
+</CardGroup>