@veluai/velu 0.2.46 → 0.2.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veluai/velu",
-  "version": "0.2.46",
+  "version": "0.2.48",
   "type": "module",
   "bin": "./dist/cli.js",
   "publishConfig": {

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

@@ -3,6 +3,7 @@ import React, {
   isValidElement,
   useCallback,
   useEffect,
+  useId,
   useRef,
   useState,
 } from 'react';
@@ -152,9 +153,165 @@ function CopyButton({ code }) {
   );
 }
 
-function CodeBody({ code, language, lineNumbers, highlight }) {
+const REPORT_REASONS = [
+  'This code is incorrect',
+  'This example is outdated',
+  "This example doesn't run",
+  'Something else',
+];
+
+function reportBody({ code, language, label, reason, detail }) {
+  const pageUrl =
+    typeof window !== 'undefined' ? window.location.href.split('#')[0] : '';
+  return [
+    reason,
+    detail,
+    label ? `Example: ${label}` : '',
+    language && language !== 'text' ? `Language: ${language}` : '',
+    pageUrl,
+    code ? `\`\`\`${language && language !== 'text' ? language : ''}\n${code}\n\`\`\`` : '',
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+function ReportIssue({ open, onOpen, onClose }) {
+  return (
+    <button
+      type="button"
+      className="velu-code-block__report-btn"
+      data-component="code-block-report-button"
+      aria-label={open ? 'Close report' : 'Report issue'}
+      title="Report issue"
+      aria-expanded={open}
+      onClick={() => (open ? onClose() : onOpen())}
+    >
+      {resolveIcon(open ? 'x' : 'flag', { size: '1em' })}
+    </button>
+  );
+}
+
+function ReportForm({ code, language, label, onClose }) {
+  const reasonName = useId();
+  const [reason, setReason] = useState('');
+  const [detail, setDetail] = useState('');
+  const [sent, setSent] = useState(false);
+  const canSubmit = Boolean(reason || detail.trim());
+
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === 'Escape') onClose();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [onClose]);
+
+  useEffect(() => {
+    if (!sent) return;
+    const t = setTimeout(onClose, 1600);
+    return () => clearTimeout(t);
+  }, [sent, onClose]);
+
+  function submit(e) {
+    e.preventDefault();
+    if (!canSubmit || sent) return;
+    const snippet = normalize(code);
+    const payload = {
+      code: snippet,
+      language,
+      label,
+      reason,
+      detail: detail.trim(),
+    };
+    payload.body = reportBody(payload);
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent('velu:report-code', { detail: payload }));
+    }
+    setSent(true);
+  }
+
+  return (
+    <form className="velu-code-block__report" onSubmit={submit}>
+      {sent ? (
+        <div className="velu-code-block__report-thanks" role="status">
+          {resolveIcon('check', { size: '1.1em' })}
+          <span>Thanks — we&apos;ll take a look.</span>
+        </div>
+      ) : (
+        <>
+          <p className="velu-code-block__report-title">
+            Report an issue with this example
+          </p>
+          <fieldset className="velu-code-block__report-reasons">
+            <legend className="velu-code-block__report-legend">
+              What&apos;s wrong?
+            </legend>
+            {REPORT_REASONS.map((r) => (
+              <label key={r} className="velu-code-block__report-reason">
+                    <input
+                      type="radio"
+                      name={reasonName}
+                      value={r}
+                  checked={reason === r}
+                  onChange={() => setReason(r)}
+                />
+                <span>{r}</span>
+              </label>
+            ))}
+          </fieldset>
+          <textarea
+            className="velu-code-block__report-detail"
+            placeholder="What should we fix?"
+            rows={3}
+            value={detail}
+            onChange={(e) => setDetail(e.target.value)}
+          />
+          <div className="velu-code-block__report-actions">
+            <button
+              type="button"
+              className="velu-code-block__report-cancel"
+              onClick={onClose}
+            >
+              Cancel
+            </button>
+            <button
+              type="submit"
+              className="velu-code-block__report-submit"
+              disabled={!canSubmit}
+            >
+              Submit
+            </button>
+          </div>
+        </>
+      )}
+    </form>
+  );
+}
+
+function useCodeReportsEnabled() {
+  const [enabled, setEnabled] = useState(false);
+  useEffect(() => {
+    // `velu dev` is a local preview — reports only exist on the published site.
+    if (import.meta.env.DEV) return undefined;
+    const sync = () => {
+      setEnabled(
+        typeof document !== 'undefined' &&
+          document.documentElement.dataset.veluCodeReports === 'on',
+      );
+    };
+    sync();
+    window.addEventListener('velu:code-reports-enabled', sync);
+    return () => window.removeEventListener('velu:code-reports-enabled', sync);
+  }, []);
+  return enabled;
+}
+
+function CodeBody({ code, language, lineNumbers, highlight, label }) {
+  const reportsEnabled = useCodeReportsEnabled();
   const canonical = resolveLang(language) || 'text';
   const highlightSet = parseHighlight(highlight);
+  const [reportOpen, setReportOpen] = useState(false);
+  const closeReport = useCallback(() => setReportOpen(false), []);
 
   // Initial render uses 'text' (no highlighting) — this guarantees SSR
   // and the first client render produce identical HTML regardless of
@@ -175,45 +332,67 @@ function CodeBody({ code, language, lineNumbers, highlight }) {
   }, [canonical]);
 
   return (
-    <div className="velu-code-block__body">
-      <CopyButton code={normalize(code)} />
-      <Highlight
-        code={normalize(code)}
-        language={renderLang}
-        theme={NO_THEME}
-      >
-        {({ tokens, getLineProps, getTokenProps }) => (
-          <pre className="velu-code-block__pre">
-            {tokens.map((line, i) => {
-              const lineProps = getLineProps({ line });
-              const isHi = highlightSet?.has(i + 1);
-              return (
-                <div
-                  key={i}
-                  {...lineProps}
-                  className={`velu-code-block__line ${
-                    lineProps.className || ''
-                  } ${isHi ? 'velu-code-block__line--highlight' : ''}`.trim()}
-                >
-                  {lineNumbers && (
-                    <span
-                      className="velu-code-block__line-number"
-                      aria-hidden="true"
-                    >
-                      {i + 1}
-                    </span>
-                  )}
-                  <span className="velu-code-block__line-code">
-                    {line.map((token, j) => (
-                      <span key={j} {...getTokenProps({ token })} />
-                    ))}
-                  </span>
-                </div>
-              );
-            })}
-          </pre>
+    <div
+      className={`velu-code-block__body${
+        reportOpen ? ' velu-code-block__body--report' : ''
+      }`}
+    >
+      <div className="velu-code-block__actions">
+        {reportsEnabled && (
+          <ReportIssue
+            open={reportOpen}
+            onOpen={() => setReportOpen(true)}
+            onClose={closeReport}
+          />
         )}
-      </Highlight>
+        {(!reportOpen || !reportsEnabled) && <CopyButton code={normalize(code)} />}
+      </div>
+      {reportsEnabled && reportOpen ? (
+        <ReportForm
+          code={code}
+          language={language}
+          label={label}
+          onClose={closeReport}
+        />
+      ) : (
+        <Highlight
+          code={normalize(code)}
+          language={renderLang}
+          theme={NO_THEME}
+        >
+          {({ tokens, getLineProps, getTokenProps }) => (
+            <pre className="velu-code-block__pre">
+              {tokens.map((line, i) => {
+                const lineProps = getLineProps({ line });
+                const isHi = highlightSet?.has(i + 1);
+                return (
+                  <div
+                    key={i}
+                    {...lineProps}
+                    className={`velu-code-block__line ${
+                      lineProps.className || ''
+                    } ${isHi ? 'velu-code-block__line--highlight' : ''}`.trim()}
+                  >
+                    {lineNumbers && (
+                      <span
+                        className="velu-code-block__line-number"
+                        aria-hidden="true"
+                      >
+                        {i + 1}
+                      </span>
+                    )}
+                    <span className="velu-code-block__line-code">
+                      {line.map((token, j) => (
+                        <span key={j} {...getTokenProps({ token })} />
+                      ))}
+                    </span>
+                  </div>
+                );
+              })}
+            </pre>
+          )}
+        </Highlight>
+      )}
     </div>
   );
 }
@@ -254,6 +433,7 @@ export function CodeBlock({
         language={language}
         lineNumbers={lineNumbers}
         highlight={highlight}
+        label={label}
       />
     </code-block>
   );
@@ -333,6 +513,8 @@ export function CodeGroup({
     lineNumbers = false,
     highlight,
     children: code,
+    title,
+    filename,
   } = block;
   const cls = `velu-code-block velu-code-block--group ${className}`.trim();
 
@@ -391,6 +573,7 @@ export function CodeGroup({
         language={language}
         lineNumbers={lineNumbers}
         highlight={highlight}
+        label={title || filename}
       />
     </code-group>
   );

package/runtime/velu-ui/components/code-block.css

@@ -107,21 +107,31 @@
 }
 
 /* Body: the code area, monospace, horizontally scrollable for long lines.
-   Positioned so the copy button can absolutely anchor to its top-left. */
+   Positioned so the action cluster can absolutely anchor to its top-right. */
 .velu-code-block__body {
   position: relative;
   background: var(--page-bg);
   padding: var(--s0);
+  padding-inline-end: calc(var(--s0) + 4.25em);
   overflow-x: auto;
 }
+.velu-code-block__body--report {
+  overflow: visible;
+  padding-inline-end: var(--s0);
+}
 
-/* Copy button — always visible. Frosted background so it remains
-   legible over whatever code sits beneath it. */
-.velu-code-block__copy {
+/* Copy + report — frosted cluster so they stay legible over the code. */
+.velu-code-block__actions {
   position: absolute;
   inset-block-start: var(--s-2);
   inset-inline-end: var(--s-2);
-  z-index: 1;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  gap: var(--s-3);
+}
+.velu-code-block__copy,
+.velu-code-block__report-btn {
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -136,8 +146,117 @@
   color: var(--muted-color);
   cursor: pointer;
 }
-.velu-code-block__copy:hover {
+.velu-code-block__copy:hover,
+.velu-code-block__report-btn:hover {
+  color: var(--text-color);
+}
+
+/* Report-issue panel replaces the snippet so a wrong example can be flagged
+   without leaving the block. */
+.velu-code-block__report {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-2);
+  min-block-size: 8rem;
+  padding-inline-end: 2em;
+  margin: 0;
+  border: 0;
+}
+.velu-code-block__report-title {
+  margin: 0;
+  font-size: var(--f-h5);
+  font-weight: var(--weight-medium);
+  line-height: var(--lh-h5);
+  color: var(--text-color);
+}
+.velu-code-block__report-reasons {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-3);
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.velu-code-block__report-legend {
+  padding: 0;
+  margin-block-end: var(--s-3);
+  font-size: var(--f-h6);
+  color: var(--muted-color);
+}
+.velu-code-block__report-reason {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  font-size: var(--f-h6);
+  line-height: var(--lh-h6);
+  color: var(--text-color);
+  cursor: pointer;
+}
+.velu-code-block__report-reason input {
+  margin: 0;
+  accent-color: var(--accent-color);
+}
+.velu-code-block__report-detail {
+  display: block;
+  width: 100%;
+  resize: vertical;
+  min-block-size: 4.5em;
+  padding: var(--s-2) var(--s-1);
+  background: var(--surface-color);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+  color: var(--text-color);
+  font: inherit;
+  font-size: var(--f-h6);
+  line-height: var(--lh-h6);
+}
+.velu-code-block__report-detail:focus {
+  outline: 2px solid var(--accent-color);
+  outline-offset: -1px;
+}
+.velu-code-block__report-detail::placeholder {
+  color: var(--muted-color);
+}
+.velu-code-block__report-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--s-2);
+}
+.velu-code-block__report-cancel,
+.velu-code-block__report-submit {
+  padding: var(--s-3) var(--s-1);
+  border-radius: var(--radius-sm);
+  font: inherit;
+  font-size: var(--f-h6);
+  font-weight: var(--weight-medium);
+  line-height: var(--lh-h6);
+  cursor: pointer;
+}
+.velu-code-block__report-cancel {
+  background: transparent;
+  border: var(--border-width) solid var(--border-color);
+  color: var(--text-color);
+}
+.velu-code-block__report-submit {
+  background: var(--accent-color);
+  border: var(--border-width) solid var(--accent-color);
+  color: var(--page-bg);
+}
+.velu-code-block__report-submit:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+.velu-code-block__report-thanks {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  min-block-size: 6rem;
   color: var(--text-color);
+  font-size: var(--f-h5);
+  font-weight: var(--weight-medium);
+}
+.velu-code-block__report-thanks svg {
+  color: var(--accent-color);
 }
 
 .velu-code-block__pre {

package/runtime/velu-ui/lib/page-feedback.js

@@ -49,7 +49,9 @@ export function createPageFeedback({ apiBase, host } = {}) {
       // sensible default when the reader didn't pick a reason (e.g. on "Yes").
       reason_text:
         (reason && String(reason).trim()) || (helpful ? 'Helpful' : 'Not helpful'),
-      details: detail ? String(detail) : null,
+      details: detail
+        ? String(detail).slice(0, 16000)
+        : null,
     };
     try {
       await fetch(url, {
@@ -66,7 +68,25 @@ export function createPageFeedback({ apiBase, host } = {}) {
     }
   }
 
-  return { submit };
+  /**
+   * Paid-plan flag for the code-block Report issue control. Fail closed.
+   */
+  async function config() {
+    const cfgUrl = `${base}/api/v1/public/feedback/config`;
+    try {
+      const res = await fetch(cfgUrl, {
+        credentials: 'include',
+        headers: { 'X-Velu-Site-Host': siteHost(host) },
+      });
+      if (!res.ok) return { codeReportsEnabled: false };
+      const data = await res.json();
+      return { codeReportsEnabled: !!data.code_reports_enabled };
+    } catch {
+      return { codeReportsEnabled: false };
+    }
+  }
+
+  return { submit, config };
 }
 
 export default createPageFeedback;

package/runtime/velu-ui/themes/thulir.css

@@ -304,7 +304,9 @@
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block { border-radius: 16px; border-color: rgb(from var(--vepa-gray-950) r g b / 10%); }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block :is(pre,code) { font: 400 14px/24px var(--font-mono); }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__body { padding: 16px; border-radius: 16px; }
-:is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__copy { border: 0; background: transparent; width: 24px; height: 24px; top: 12px; right: 12px; }
+:is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__actions { top: 12px; right: 12px; }
+:is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__copy,
+:is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__report-btn { border: 0; background: transparent; width: 24px; height: 24px; }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__header { height: 36px; padding: 0 12px; align-items: stretch; }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__tabs { gap: 16px; }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__tab { padding: 0 6px; border-radius: 0; font: 400 12px/20px var(--font-sans); height: 36px; }

package/schema/velu.schema.json

@@ -320,6 +320,7 @@
         "group": { "type": "string", "description": "Sidebar section heading." },
         "icon": { "type": "string", "description": "lucide icon id." },
         "expanded": { "type": "boolean", "description": "Start expanded." },
+        "public": { "type": "boolean", "description": "Allow unauthenticated access to this group. Per-page group restrictions still apply." },
         "root": { "type": "string", "description": "Landing page path for the group." },
         "openapi": { "$ref": "#/$defs/openapiRef" },
         "api": { "$ref": "#/$defs/api" },

package/src/navigation.js

@@ -179,6 +179,7 @@ function normalizeGroup(g) {
   if (g.root) pages.unshift({ kind: 'page', pagePath: g.root });
   return {
     kind: 'group',
+    ...(g.public !== undefined ? { public: g.public } : {}),
     label: g.group,
     icon: g.icon,
     expanded: Boolean(g.expanded),

package/src/runtime/App.jsx

@@ -89,6 +89,8 @@ function docsAuthActionUrl(action) {
 // Resolve it to a relative base. Do not read `window` here: prerender runs
 // this useMemo during renderToString in Node.
 function resolvePublicApiBase(configuredBase) {
+  // Private readers must reach the router that verifies and forwards their session.
+  if (site.readerPrivate) return BASE_PATH;
   if (!configuredBase) return null;
   if (configuredBase !== '__VELU_SAME_ORIGIN__') return configuredBase;
   return BASE_PATH;
@@ -801,7 +803,7 @@ function DocsPage() {
   // URL path — e.g. essentials/markdown.mdx lives under the "Writing Content"
   // group). Page rows show the path to the page; anchor rows include the page.
   const searchDocs = React.useCallback(async (q) => {
-    const results = await pagefindSearch(q);
+    const results = site.readerRestricted ? await fetch((import.meta.env.BASE_URL || '/') + 'api/v1/public/search?q=' + encodeURIComponent(q), {credentials:'same-origin',cache:'no-store'}).then(r=>r.ok?r.json():[]) : await pagefindSearch(q);
     if (!Array.isArray(results)) return results;
     return results.map((r) => {
       const res = resolve(r.href.split('#')[0], navigation, pages);
@@ -847,6 +849,31 @@ function DocsPage() {
     return createPageFeedback({ apiBase, host: site.assistant?.host });
   }, []);
 
+  React.useEffect(() => {
+    if (IS_DEV_PREVIEW) return undefined;
+    const onReport = (e) => {
+      const d = e.detail || {};
+      pageFeedback?.submit({
+        helpful: false,
+        reason: 'Incorrect code example',
+        detail: d.body || d.detail || '',
+      });
+    };
+    window.addEventListener('velu:report-code', onReport);
+    return () => window.removeEventListener('velu:report-code', onReport);
+  }, [pageFeedback]);
+
+  React.useEffect(() => {
+    if (IS_DEV_PREVIEW || !pageFeedback?.config) return undefined;
+    let alive = true;
+    pageFeedback.config().then((cfg) => {
+      if (!alive || !cfg.codeReportsEnabled) return;
+      document.documentElement.dataset.veluCodeReports = 'on';
+      window.dispatchEvent(new Event('velu:code-reports-enabled'));
+    }).catch(() => {});
+    return () => { alive = false; };
+  }, [pageFeedback]);
+
   const frontmatter = entry?.frontmatter ?? {};
   const PageComponent = entry?.Component ?? null;
   const pageToc = entry?.toc ?? [];
@@ -1196,7 +1223,11 @@ function DocsPage() {
       headers: { 'content-type': 'application/json' },
       body: '{}',
     });
-    if (response.ok) window.location.reload();
+    if (response.ok) {
+      const result = response.status === 204 ? null : await response.json();
+      if (result?.redirect) window.location.assign(result.redirect);
+      else window.location.reload();
+    }
   }, []);
 
   const navActions = [];

package/src/runtime/client-entry.jsx

@@ -1,9 +1,9 @@
 import './dev-warnings.js';
 import React from 'react';
-import { hydrateRoot } from 'react-dom/client';
+import { createRoot, hydrateRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router-dom';
 import 'velu-ui/styles.css';
-import { site } from 'virtual:velu-site';
+import { site, initializeReader } from 'virtual:velu-site';
 import App from './App.jsx';
 
 // Subpath hosting: Vite sets BASE_URL from the build's `base` (e.g. "/docs/").
@@ -31,7 +31,9 @@ function CustomScripts() {
   return null;
 }
 
-hydrateRoot(
+function mount() {
+const renderRoot = site.guarded ? (_, children) => createRoot(document.getElementById('root')).render(children) : hydrateRoot;
+renderRoot(
   document.getElementById('root'),
   <BrowserRouter basename={basename}>
     <App />
@@ -39,6 +41,10 @@ hydrateRoot(
   </BrowserRouter>
 );
 
+}
+if (site.guarded) initializeReader().then(mount).catch(()=>{ document.getElementById("root").textContent="Unable to load documentation. Reload to sign in again."; });
+else mount();
+
 // 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