@docsector/docsector-reader 4.3.2 → 4.4.0

package/.env.example

@@ -0,0 +1,18 @@
+# -----------------------------------------------------------------------------
+# Docsector Reader / Cloudflare environment example
+# -----------------------------------------------------------------------------
+# This project can run with Cloudflare Pages Functions and AI Search.
+#
+# For production, set values as Cloudflare Pages environment variables/secrets.
+# For local wrangler pages dev, prefer .dev.vars.
+# For local Node tooling, .env can be used when your runner loads it.
+
+# AI Assistant (Cloudflare AI Search REST fallback)
+AI_SEARCH_INSTANCE_NAME=
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_API_TOKEN=
+
+# Optional: Web Bot Auth runtime variables
+# WEB_BOT_AUTH_JWKS=
+# WEB_BOT_AUTH_PRIVATE_JWK=
+# WEB_BOT_AUTH_KEY_ID=

package/README.md

@@ -25,14 +25,15 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🧠 **Markdown Negotiation** — Requests with `Accept: text/markdown` receive markdown responses, while browsers keep HTML by default
 - 🔐 **Web Bot Auth Directory** — Optional signed JWKS directory at `/.well-known/http-message-signatures-directory` for bot identity verification
 - 🤖 **Open in ChatGPT / Claude** — One-click links to open the current page directly in ChatGPT or Claude for Q&A
-- 🤖 **LLM Bot Detection** — Automatically serves raw Markdown to known AI crawlers (GPTBot, ClaudeBot, PerplexityBot, GrokBot, and others)
-- 🗺️ **Sitemap Generation** — Automatic `sitemap.xml` generation at build time with all page URLs (requires `siteUrl` in config)
-- 🤖 **AI-Friendly robots.txt** — Scaffold includes a `robots.txt` explicitly allowing 23 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, GrokBot, etc.)
+- 🤖 **LLM Bot Detection** — Automatically serves raw Markdown to known AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Cloudflare-AI-Search, GrokBot, and others)
+- 🗺️ **Sitemap Generation** — Automatic `sitemap.xml` generation at build time with root-relative URLs by default and absolute URLs when `siteUrl` is configured
+- 🤖 **AI-Friendly robots.txt** — Scaffold includes a `robots.txt` explicitly allowing 24 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Cloudflare-AI-Search, GrokBot, etc.) and advertises `Sitemap: /sitemap.xml`
 - 🧭 **Content Signals** — Optional `Content-Signal` directive for declaring AI usage policy (`ai-train`, `search`, `ai-input`) in `robots.txt`
 - 🧩 **Agent Skills Discovery Index** — Optional `/.well-known/agent-skills/index.json` with RFC v0.2.0 schema and SHA-256 digests
 - ✍️ **Docsector Authoring Skill** — Publishable `SKILL.md` that teaches agents Docsector blocks, page patterns, MCP lookup, and WebMCP tools
 - 🪪 **MCP Server Card** — Optional `/.well-known/mcp/server-card.json` for MCP server discovery before connection
 - 🌐 **WebMCP Browser Tools** — Optional registration of in-page tools via `navigator.modelContext` for browser agents
+- 🤖 **AI Assistant Panel** — Optional documentation assistant drawer backed by Cloudflare AI Search through an internal same-origin endpoint
 - 🔗 **Homepage Link Headers** — Auto-generated `Link` response headers for agent discovery (`api-catalog`, `service-doc`, `service-desc`, `describedby`) per RFC 8288 / RFC 9727
 - 🔌 **MCP Server** — Auto-generated [MCP](https://modelcontextprotocol.io) server at `/mcp` for AI assistant integration (Claude Desktop, VS Code, etc.)
 - 📄 **llms.txt / llms-full.txt** — Auto-generated [llms.txt](https://llmstxt.org) index and full-content file for LLM discovery (requires `siteUrl` in config)
@@ -42,6 +43,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 ## ✨ Features
 
 - 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
+- 📋 **Clickable Inline Code** — Backtick-rendered inline code snippets are clickable across pages, subpages, and AI assistant answers
 - 🔽 **Nested Markdown Lists** — Ordered and unordered lists preserve sublist hierarchy across multiple indentation levels
 - ☑️ **Markdown Task Lists** — GitBook-style `- [ ]` and `- [x]` items render as read-only checkboxes with nested subtasks
 - 🖼️ **Block Image Captions & Zoom** — Standalone Markdown images render as zoomable figures, and raw `figure` / `picture` markup supports separate alt text and captions
@@ -52,7 +54,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🌍 **Internationalization (i18n)** — Multi-language support with HJSON locale files and per-page translations
 - 🌗 **Dark/Light Mode** — Automatic theme switching with Quasar Dark Plugin
 - 🧰 **Docsector CLI Skill Installer** — Install the built-in authoring skill into older scaffolds with `docsector install-skill`
-- 🔗 **Anchor Navigation** — Right-side source-ordered Table of Contents tree with stable scroll tracking, auto-scroll to the active section, and active-heading resolution based on the last heading that crossed the content threshold
+- 🔗 **Anchor Navigation** — Right-side source-ordered Table of Contents tree with stable scroll tracking, resize-safe drawer state, auto-scroll to the active section, and active-heading resolution based on the last heading that crossed the content threshold
 - 🖱️ **Active Menu Item UX** — Active menu entries keep pointer cursor, clear URL hash without redundant navigation, and prevent accidental label text selection
 - 🔎 **Search** — Menu search across all documentation content and tags
 - 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers
@@ -291,9 +293,116 @@ Check `checks.discovery.webMcp.status` equals `"pass"`.
 
 ---
 
+## 🤖 AI Assistant Panel
+
+Docsector Reader can add an opt-in assistant panel for documentation Q&A. Users open it from the global header while reading pages and subpages; it is not a dedicated documentation route. The drawer posts to a same-origin Cloudflare Pages Function, and that function calls Cloudflare AI Search so secrets, rate-limit strategy, provider errors, and future auth stay server-side.
+
+The panel is disabled by default. When enabled, desktop pages get a dedicated right-side assistant rail that can sit beside the table of contents on wide screens. Mobile uses a fullscreen dialog.
+
+### Configure
+
+```javascript
+export default {
+  // ...other config
+
+  siteUrl: 'https://my-docs.example.com',
+
+  aiAssistant: {
+    enabled: true,
+    provider: 'aiSearch',
+    endpoint: '/assistant',
+    ui: {
+      title: 'Docs Assistant',
+      drawerWidth: 380,
+      wideBreakpoint: 1280,
+      showCitations: true,
+      suggestedPrompts: [
+        'How do I get started?',
+        'Summarize this page.',
+        'Where is the related API reference?'
+      ]
+    },
+    aiSearch: {
+      binding: 'AI_SEARCH',
+      instanceNameEnv: 'AI_SEARCH_INSTANCE_NAME',
+      accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',
+      apiTokenEnv: 'CLOUDFLARE_API_TOKEN',
+      model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+      retrievalType: 'hybrid',
+      maxResults: 6,
+      matchThreshold: 0.4,
+      contextExpansion: 1,
+      queryRewrite: { enabled: true },
+      reranking: { enabled: false },
+      stream: true
+    }
+  }
+}
+```
+
+### Cloudflare setup
+
+Use Cloudflare AI Search as the first provider path:
+
+- Create an AI Search instance in Cloudflare.
+- Build and deploy the Docsector site first; build output always publishes `/sitemap.xml` and adds `Sitemap: /sitemap.xml` to `robots.txt` for crawler discovery.
+- Use a Website data source. For the cleanest retrieval, point its specific sitemap to `/ai-search-sitemap.xml`; otherwise the crawler can discover `/sitemap.xml` from `robots.txt`.
+- Add metadata fields such as title, path, locale, book, version, and subpage if you want filtering later.
+- Set `AI_SEARCH_INSTANCE_NAME` as a Cloudflare Pages environment variable or local `.dev.vars` entry.
+- Bind the instance to Pages as `AI_SEARCH` when available, or set encrypted Pages secrets for `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` with AI Search run access.
+- Keep AI Search public endpoints optional; the built-in UI uses the configured internal endpoint by default.
+
+### Build output
+
+When enabled, `docsector build` can generate:
+
+| File | Purpose |
+|---|---|
+| `functions/assistant.js` | Cloudflare Pages Function for browser assistant requests |
+| `dist/spa/sitemap.xml` | Default crawler sitemap advertised from `robots.txt` |
+| `dist/spa/robots.txt` | Crawler policy with `Sitemap: /sitemap.xml` |
+| `dist/spa/ai-search-sitemap.xml` | Markdown-focused sitemap for AI Search crawling |
+| `dist/spa/.well-known/ai-search/manifest.json` | Source metadata for indexed documentation pages |
+| `dist/spa/_routes.json` | Routes the internal assistant endpoint to the Pages Function |
+
+### Validate
+
+```bash
+npx docsector build
+cat dist/spa/sitemap.xml
+cat dist/spa/robots.txt
+cat dist/spa/ai-search-sitemap.xml
+cat dist/spa/.well-known/ai-search/manifest.json
+npx wrangler pages dev dist/spa
+```
+
+Workers AI, AI Search, and remote bindings can incur Cloudflare usage during local development.
+
+### Environment variables quick guide
+
+Docsector now ships `.env.example` so teams can standardize Cloudflare variables.
+
+Use the right place for each environment:
+
+- Cloudflare Pages production/preview: set vars in Pages settings (recommended).
+- Local `wrangler pages dev`: use `.dev.vars` for Function runtime variables.
+- Local Node-based tools: `.env` works when your runner actually loads it.
+
+Minimum variables when not using direct AI Search binding:
+
+```bash
+AI_SEARCH_INSTANCE_NAME=...
+CLOUDFLARE_ACCOUNT_ID=...
+CLOUDFLARE_API_TOKEN=...
+```
+
+If you bind AI Search as `AI_SEARCH`, the Assistant tries binding first and uses REST fallback when binding is not available.
+
+---
+
 ## � llms.txt (LLM Discovery)
 
-Docsector Reader automatically generates [llms.txt](https://llmstxt.org) files at build time when `siteUrl` is configured (same requirement as sitemap.xml).
+Docsector Reader automatically generates [llms.txt](https://llmstxt.org) files at build time when `siteUrl` is configured. `sitemap.xml` is generated even without `siteUrl`; `llms.txt` keeps the `siteUrl` requirement because it contains absolute Markdown links.
 
 | File | Purpose |
 |---|---|
@@ -499,6 +608,7 @@ Notes:
 - `aiTrain`, `search`, and `aiInput` accept `yes` / `no` (or booleans).
 - Default scope is only `User-agent: *`.
 - Build patch is idempotent: repeated builds do not duplicate `Content-Signal` lines.
+- Build also keeps `Sitemap: /sitemap.xml` discoverable in `robots.txt` so crawlers can find the generated sitemap automatically.
 
 ### Validate
 
@@ -751,6 +861,27 @@ export default {
     agentFallback: true
   },
 
+  aiAssistant: {
+    enabled: false,
+    provider: 'aiSearch',
+    endpoint: '/assistant',
+    ui: {
+      title: 'Docsector Assistant',
+      drawerWidth: 380,
+      wideBreakpoint: 1280,
+      showCitations: true
+    },
+    aiSearch: {
+      binding: 'AI_SEARCH',
+      instanceNameEnv: 'AI_SEARCH_INSTANCE_NAME',
+      accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',
+      apiTokenEnv: 'CLOUDFLARE_API_TOKEN',
+      retrievalType: 'hybrid',
+      maxResults: 6,
+      stream: true
+    }
+  },
+
   mcpServerCard: {
     enabled: true,
     path: '/.well-known/mcp/server-card.json',

package/bin/docsector.js

@@ -24,7 +24,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '4.3.2'
+const VERSION = '4.4.0'
 const AUTHORING_SKILL_NAME = 'docsector-documentation-authoring'
 const AUTHORING_SKILL_DESCRIPTION = 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.'
 const AUTHORING_SKILL_PUBLIC_PATH = `/.well-known/agent-skills/${AUTHORING_SKILL_NAME}/SKILL.md`
@@ -152,6 +152,11 @@ export default {
     editBaseUrl: 'https://github.com/your-org/your-repo/edit/main/src/pages'
   },
 
+  // @ Site URL (optional)
+  // Set this for absolute URLs in sitemap.xml, llms.txt, and AI metadata.
+  // sitemap.xml is still generated with root-relative URLs when omitted.
+  // siteUrl: 'https://docs.example.com',
+
   // @ MCP (Model Context Protocol)
   // Uncomment to enable an MCP server at /mcp for AI assistant integration.
   // Requires Cloudflare Pages Functions (or compatible serverless platform).
@@ -587,11 +592,33 @@ node_modules
 .quasar
 dist
 functions
+.env
+.dev.vars
 npm-debug.log*
 .DS_Store
 .thumbs.db
 `
 
+const TEMPLATE_ENV_EXAMPLE = `\
+# -----------------------------------------------------------------------------
+# Docsector Reader / Cloudflare environment example
+# -----------------------------------------------------------------------------
+# Copy to .env (or .dev.vars for wrangler pages dev) and fill with real values.
+#
+# AI Assistant (Cloudflare AI Search REST fallback)
+AI_SEARCH_INSTANCE_NAME=
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_API_TOKEN=
+
+# Optional: AI Search instance binding name (defaults to AI_SEARCH in config)
+# AI_SEARCH=
+
+# Optional: Web Bot Auth runtime variables
+# WEB_BOT_AUTH_JWKS=
+# WEB_BOT_AUTH_PRIVATE_JWK=
+# WEB_BOT_AUTH_KEY_ID=
+`
+
 const TEMPLATE_MARKDOWNLINT = `\
 {
   "MD013": false,
@@ -608,6 +635,7 @@ const TEMPLATE_ROBOTS_TXT = `\
 User-agent: *
 Allow: /
 Content-Signal: ai-train=yes, search=yes, ai-input=yes
+Sitemap: /sitemap.xml
 
 # Explicitly allow AI crawlers
 # OpenAI
@@ -678,6 +706,10 @@ Allow: /
 User-agent: DuckAssistBot
 Allow: /
 
+# Cloudflare
+User-agent: Cloudflare-AI-Search
+Allow: /
+
 # xAI
 User-agent: GrokBot
 Allow: /
@@ -758,6 +790,7 @@ npm run build
 \`\`\`
 
 The optimized SPA output will be in \`dist/spa/\`.
+Docsector also generates \`dist/spa/sitemap.xml\` and keeps \`robots.txt\` discoverable with \`Sitemap: /sitemap.xml\`. Set \`siteUrl\` in \`docsector.config.js\` when you want absolute sitemap URLs.
 `
 
 // =============================================================================
@@ -918,6 +951,7 @@ function initProject (name) {
     ['package.json', getTemplatePackageJson(name)],
     ['quasar.config.js', TEMPLATE_QUASAR_CONFIG],
     ['docsector.config.js', TEMPLATE_DOCSECTOR_CONFIG],
+    ['.env.example', TEMPLATE_ENV_EXAMPLE],
     ['.markdownlint.json', TEMPLATE_MARKDOWNLINT],
     ['index.html', TEMPLATE_INDEX_HTML],
     ['postcss.config.cjs', TEMPLATE_POSTCSS],
@@ -948,6 +982,7 @@ function initProject (name) {
   console.log(`    ${name}/`)
   console.log('    ├── docsector.config.js')
   console.log('    ├── quasar.config.js')
+  console.log('    ├── .env.example')
   console.log('    ├── .markdownlint.json')
   console.log('    ├── package.json')
   console.log('    ├── index.html')

package/docsector.config.js

@@ -49,12 +49,56 @@ export default {
     editBaseUrl: 'https://github.com/docsector/docsector-reader/edit/main/src/pages'
   },
 
+  // @ Site URL
+  // Used for absolute sitemap, llms.txt, MCP, and AI Search metadata URLs.
+  siteUrl: 'https://docsector.com',
+
   // @ MCP
   mcp: {
     serverName: 'docsector-docs',
     toolSuffix: 'docsector'
   },
 
+  // @ AI Assistant
+  aiAssistant: {
+    enabled: true,
+    provider: 'aiSearch',
+    endpoint: '/assistant',
+    ui: {
+      title: 'Docsector AI Assistant',
+      subtitle: 'Ask, search, or explain the docs.',
+      drawerWidth: 380,
+      wideBreakpoint: 1280,
+      showCitations: true,
+      suggestedPrompts: [
+        'How do I get started?',
+        'Summarize this page.',
+        'Where is the related API reference?'
+      ]
+    },
+    aiSearch: {
+      binding: 'AI_SEARCH',
+      instanceNameEnv: 'AI_SEARCH_INSTANCE_NAME',
+      namespace: '',
+      accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',
+      apiTokenEnv: 'CLOUDFLARE_API_TOKEN',
+      model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+      retrievalType: 'vector',
+      maxResults: 6,
+      matchThreshold: 0.4,
+      contextExpansion: 1,
+      queryRewrite: {
+        enabled: true
+      },
+      reranking: {
+        enabled: false,
+        model: '@cf/baai/bge-reranker-base',
+        matchThreshold: 0.4
+      },
+      stream: true
+    }
+  },
+
   // @ Agent Skills
   agentSkills: {
     enabled: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "4.3.2",
+  "version": "4.4.0",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",
@@ -33,6 +33,7 @@
     "index.html",
     "postcss.config.cjs",
     ".eslintrc.cjs",
+    ".env.example",
     "jsconfig.json",
     "README.md",
     "LICENSE.md"
@@ -56,7 +57,7 @@
     "url": "https://github.com/docsector/docsector-reader/issues"
   },
   "scripts": {
-    "dev": "quasar dev",
+    "dev": "npx wrangler pages dev dist/spa",
     "build": "quasar build",
     "lint": "eslint --ext .js,.vue ./",
     "format": "prettier --write \"**/*.{js,vue,scss,html,md,json}\" --ignore-path .gitignore",

package/public/robots.txt

@@ -1,2 +1,6 @@
 User-agent: *
 Allow: /
+Sitemap: /sitemap.xml
+
+User-agent: Cloudflare-AI-Search
+Allow: /

package/src/ai-assistant/config.js

@@ -0,0 +1,91 @@
+export const DEFAULT_ASSISTANT_ENDPOINT = '/assistant'
+export const DEFAULT_ASSISTANT_PROVIDER = 'aiSearch'
+export const DEFAULT_ASSISTANT_DRAWER_WIDTH = 380
+export const DEFAULT_ASSISTANT_WIDE_BREAKPOINT = 1280
+
+const DEFAULT_SUGGESTED_PROMPTS = [
+  'How do I get started?',
+  'Summarize this page.',
+  'Where is the related API reference?'
+]
+
+function toBoolean (value, fallback = false) {
+  if (typeof value === 'boolean') return value
+  return fallback
+}
+
+function toPositiveInteger (value, fallback, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.min(max, Math.max(min, Math.round(number)))
+}
+
+function toBoundedNumber (value, fallback, { min = 0, max = 1 } = {}) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.min(max, Math.max(min, number))
+}
+
+function toCleanString (value, fallback = '') {
+  if (typeof value !== 'string') return fallback
+  const trimmed = value.trim()
+  return trimmed || fallback
+}
+
+function normalizeSuggestedPrompts (value) {
+  const prompts = Array.isArray(value) ? value : DEFAULT_SUGGESTED_PROMPTS
+  const normalized = prompts
+    .map(prompt => toCleanString(prompt))
+    .filter(Boolean)
+    .slice(0, 6)
+
+  return normalized.length > 0 ? normalized : [...DEFAULT_SUGGESTED_PROMPTS]
+}
+
+export function isAssistantEnabled (config = {}) {
+  return config?.aiAssistant?.enabled === true
+}
+
+export function normalizeAiAssistantConfig (config = {}) {
+  const assistant = config.aiAssistant || {}
+  const provider = toCleanString(assistant.provider, DEFAULT_ASSISTANT_PROVIDER)
+  const aiSearch = assistant.aiSearch || {}
+  const ui = assistant.ui || {}
+
+  return {
+    enabled: assistant.enabled === true,
+    provider,
+    endpoint: toCleanString(assistant.endpoint, DEFAULT_ASSISTANT_ENDPOINT),
+    ui: {
+      title: toCleanString(ui.title, 'Docsector Assistant'),
+      subtitle: toCleanString(ui.subtitle, 'Ask, search, or explain the docs.'),
+      drawerWidth: toPositiveInteger(ui.drawerWidth, DEFAULT_ASSISTANT_DRAWER_WIDTH, { min: 320, max: 520 }),
+      wideBreakpoint: toPositiveInteger(ui.wideBreakpoint, DEFAULT_ASSISTANT_WIDE_BREAKPOINT, { min: 960, max: 2400 }),
+      showCitations: toBoolean(ui.showCitations, true),
+      suggestedPrompts: normalizeSuggestedPrompts(ui.suggestedPrompts)
+    },
+    aiSearch: {
+      binding: toCleanString(aiSearch.binding, 'AI_SEARCH'),
+      instanceName: toCleanString(aiSearch.instanceName || aiSearch.instanceId, ''),
+      instanceNameEnv: toCleanString(aiSearch.instanceNameEnv, 'AI_SEARCH_INSTANCE_NAME'),
+      namespace: toCleanString(aiSearch.namespace, ''),
+      accountIdEnv: toCleanString(aiSearch.accountIdEnv, 'CLOUDFLARE_ACCOUNT_ID'),
+      apiTokenEnv: toCleanString(aiSearch.apiTokenEnv, 'CLOUDFLARE_API_TOKEN'),
+      model: toCleanString(aiSearch.model, '@cf/meta/llama-3.3-70b-instruct-fp8-fast'),
+      retrievalType: toCleanString(aiSearch.retrievalType, 'hybrid'),
+      maxResults: toPositiveInteger(aiSearch.maxResults, 6, { min: 1, max: 50 }),
+      matchThreshold: toBoundedNumber(aiSearch.matchThreshold, 0.4),
+      contextExpansion: toPositiveInteger(aiSearch.contextExpansion, 1, { min: 0, max: 3 }),
+      queryRewrite: {
+        enabled: toBoolean(aiSearch.queryRewrite?.enabled, true),
+        model: toCleanString(aiSearch.queryRewrite?.model, '')
+      },
+      reranking: {
+        enabled: toBoolean(aiSearch.reranking?.enabled, false),
+        model: toCleanString(aiSearch.reranking?.model, '@cf/baai/bge-reranker-base'),
+        matchThreshold: toBoundedNumber(aiSearch.reranking?.matchThreshold, 0.4)
+      },
+      stream: aiSearch.stream !== false
+    }
+  }
+}

package/src/ai-assistant/indexing.js

@@ -0,0 +1,50 @@
+function escapeXml (value) {
+  return String(value || '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+export function createAiSearchIndexArtifacts ({ siteUrl = '', entries = [], generatedAt = new Date().toISOString() } = {}) {
+  const baseUrl = String(siteUrl || '').replace(/\/+$/g, '')
+
+  const pages = (Array.isArray(entries) ? entries : [])
+    .filter(entry => entry && entry.path && entry.markdownPath)
+    .map(entry => {
+      const markdownPath = String(entry.markdownPath).replace(/^\/+/, '')
+      const routePath = String(entry.path).replace(/^\/+/, '')
+      const markdownUrl = baseUrl ? `${baseUrl}/${markdownPath}` : `/${markdownPath}`
+      const url = baseUrl ? `${baseUrl}/${routePath}` : `/${routePath}`
+      return {
+        title: entry.title || routePath,
+        path: routePath,
+        markdownUrl,
+        url,
+        locale: entry.locale || '',
+        book: entry.book || '',
+        version: entry.version || '',
+        subpage: entry.subpage || ''
+      }
+    })
+
+  const sitemapUrls = pages.map(page => [
+    '  <url>',
+    `    <loc>${escapeXml(page.markdownUrl)}</loc>`,
+    `    <lastmod>${escapeXml(generatedAt.slice(0, 10))}</lastmod>`,
+    '  </url>'
+  ].join('\n')).join('\n')
+
+  const sitemap = pages.length > 0
+    ? `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${sitemapUrls}\n</urlset>\n`
+    : ''
+
+  return {
+    manifest: {
+      generatedAt,
+      pages
+    },
+    sitemap
+  }
+}

package/src/ai-assistant/layout.js

@@ -0,0 +1,56 @@
+export const DEFAULT_TOC_WIDTH = 308
+export const DEFAULT_RIGHT_GAP = 24
+export const DEFAULT_MIN_CONTENT_WIDTH = 680
+export const DEFAULT_MOBILE_BREAKPOINT = 768
+
+function toWidth (value, fallback) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.max(0, Math.round(number))
+}
+
+export function getAssistantRightRailState ({
+  tocOpen = false,
+  assistantOpen = false,
+  screenWidth = 1440,
+  tocWidth = DEFAULT_TOC_WIDTH,
+  assistantWidth = 380,
+  gap = DEFAULT_RIGHT_GAP,
+  minContentWidth = DEFAULT_MIN_CONTENT_WIDTH,
+  mobileBreakpoint = DEFAULT_MOBILE_BREAKPOINT
+} = {}) {
+  const width = toWidth(screenWidth, 1440)
+  const isMobile = width < mobileBreakpoint
+  const normalizedTocWidth = toWidth(tocWidth, DEFAULT_TOC_WIDTH)
+  const normalizedAssistantWidth = toWidth(assistantWidth, 380)
+  const normalizedGap = toWidth(gap, DEFAULT_RIGHT_GAP)
+
+  if (isMobile) {
+    return {
+      isMobile,
+      showToc: tocOpen,
+      showAssistant: assistantOpen,
+      tocWidth: 0,
+      assistantWidth: 0,
+      totalWidth: 0,
+      backToTopRightOffset: `${normalizedGap}px`
+    }
+  }
+
+  const requestedWidth = (tocOpen ? normalizedTocWidth : 0) + (assistantOpen ? normalizedAssistantWidth : 0)
+  const canShowBoth = !tocOpen || !assistantOpen || (width - requestedWidth >= minContentWidth)
+  const showToc = tocOpen && (canShowBoth || !assistantOpen)
+  const showAssistant = assistantOpen
+  const totalWidth = (showToc ? normalizedTocWidth : 0) + (showAssistant ? normalizedAssistantWidth : 0)
+  const backOffset = totalWidth > 0 ? totalWidth + normalizedGap : normalizedGap
+
+  return {
+    isMobile,
+    showToc,
+    showAssistant,
+    tocWidth: showToc ? normalizedTocWidth : 0,
+    assistantWidth: showAssistant ? normalizedAssistantWidth : 0,
+    totalWidth,
+    backToTopRightOffset: `${backOffset}px`
+  }
+}

package/src/ai-assistant/messages.js

@@ -0,0 +1,41 @@
+const VALID_ROLES = new Set(['system', 'developer', 'user', 'assistant', 'tool'])
+
+function cleanContent (value, maxLength) {
+  const content = String(value || '').replace(/\s+$/g, '')
+  if (!Number.isFinite(maxLength) || maxLength <= 0 || content.length <= maxLength) {
+    return content
+  }
+
+  return content.slice(0, maxLength).trimEnd()
+}
+
+export function normalizeAssistantMessages (messages = [], { maxMessages = 12, maxContentLength = 4000 } = {}) {
+  return (Array.isArray(messages) ? messages : [])
+    .map(message => {
+      const role = VALID_ROLES.has(message?.role) ? message.role : 'user'
+      const content = cleanContent(message?.content, maxContentLength)
+      return content ? { role, content } : null
+    })
+    .filter(Boolean)
+    .slice(-Math.max(1, maxMessages))
+}
+
+export function createAssistantRequestPayload ({ messages = [], route, locale, context } = {}, options = {}) {
+  const normalizedMessages = normalizeAssistantMessages(messages, options)
+  const path = typeof route?.path === 'string' ? route.path : ''
+  const hash = typeof route?.hash === 'string' ? route.hash : ''
+
+  return {
+    messages: normalizedMessages,
+    locale: typeof locale === 'string' && locale.trim() ? locale.trim() : 'en-US',
+    route: {
+      path,
+      hash
+    },
+    context: {
+      title: typeof context?.title === 'string' ? context.title.trim() : '',
+      markdownUrl: typeof context?.markdownUrl === 'string' ? context.markdownUrl.trim() : '',
+      selectedText: cleanContent(context?.selectedText, options.maxSelectedTextLength || 1200)
+    }
+  }
+}

package/src/ai-assistant/panel.js

@@ -0,0 +1,22 @@
+export function hasAssistantMessageContent(message) {
+  return String(message?.content || '').trim().length > 0
+}
+
+export function listVisibleAssistantMessages(messages = []) {
+  return messages.filter((message) => {
+    if (message?.role !== 'assistant') {
+      return true
+    }
+
+    return hasAssistantMessageContent(message)
+  })
+}
+
+export function isAssistantThinkingState({ loading = false, messages = [] } = {}) {
+  if (!loading) {
+    return false
+  }
+
+  const lastMessage = messages[messages.length - 1]
+  return Boolean(lastMessage && lastMessage.role === 'assistant' && !hasAssistantMessageContent(lastMessage))
+}