@docsector/docsector-reader 4.3.2 → 4.4.0

package/src/components/quasar-api-extends.json

@@ -0,0 +1,235 @@
+{
+  "props": {
+    "readonly": {
+      "type": "Boolean",
+      "desc": "Put component in readonly mode",
+      "category": "state"
+    },
+    "disable": {
+      "type": "Boolean",
+      "desc": "Put component in disabled mode",
+      "category": "state"
+    },
+    "color": {
+      "type": "String",
+      "tsType": "NamedColor",
+      "desc": "Color name for component from the Quasar Color Palette",
+      "examples": ["'primary'", "'teal'", "'teal-10'"],
+      "category": "style"
+    },
+    "text-color": {
+      "type": "String",
+      "tsType": "NamedColor",
+      "desc": "Overrides text color (if needed); Color name from the Quasar Color Palette",
+      "examples": ["'primary'", "'teal'", "'teal-10'"],
+      "category": "style"
+    },
+    "dense": {
+      "type": "Boolean",
+      "desc": "Dense mode; occupies less space",
+      "category": "style"
+    },
+    "size": {
+      "type": "String",
+      "desc": "Size in CSS units, including unit name",
+      "examples": ["'16px'", "'2rem'"],
+      "category": "style"
+    },
+    "dark": {
+      "type": ["Boolean", "null"],
+      "default": "null",
+      "desc": "Notify the component that the background is a dark color",
+      "category": "style"
+    },
+    "icon": {
+      "type": "String",
+      "desc": "Icon name following Quasar convention; Make sure you have the icon library installed unless you are using 'img:' prefix; If 'none' (String) is used as value then no icon is rendered (but screen real estate will still be used for it)",
+      "examples": [
+        "'map'",
+        "'ion-add'",
+        "'img:https://cdn.quasar.dev/logo-v2/svg/logo.svg'",
+        "'img:path/to/some_image.png'"
+      ],
+      "category": "content"
+    },
+    "flat": {
+      "type": "Boolean",
+      "desc": "Applies a 'flat' design (no default shadow)",
+      "category": "style"
+    },
+    "bordered": {
+      "type": "Boolean",
+      "desc": "Applies a default border to the component",
+      "category": "style"
+    },
+    "square": {
+      "type": "Boolean",
+      "desc": "Removes border-radius so borders are squared",
+      "category": "style"
+    },
+    "rounded": {
+      "type": "Boolean",
+      "desc": "Applies a small standard border-radius for a squared shape of the component",
+      "category": "style"
+    },
+    "tabindex": {
+      "type": ["Number", "String"],
+      "desc": "Tabindex HTML attribute value",
+      "examples": ["100", "'0'"],
+      "category": "general"
+    },
+    "transition": {
+      "type": "String",
+      "desc": "One of Quasar's embedded transitions",
+      "examples": ["'fade'", "'slide-down'"],
+      "category": "transition"
+    },
+    "animation-speed": {
+      "type": ["String", "Number"],
+      "desc": "Animation speed (in milliseconds, without unit)",
+      "examples": ["500", "'1200'"],
+      "category": "style"
+    },
+    "model-value": {
+      "desc": "Model of the component; Either use this property (along with a listener for 'update:model-value' event) OR use v-model directive",
+      "required": true,
+      "syncable": true,
+      "category": "model"
+    },
+    "html": {
+      "type": "Boolean",
+      "desc": "Force use of textContent instead of innerHTML to render text; Use it when the text might be unsafe (from user input)",
+      "category": "behavior"
+    },
+    "tag": {
+      "type": "String",
+      "desc": "HTML tag to use",
+      "category": "content"
+    },
+    "scroll-target": {
+      "type": ["Element", "String"],
+      "desc": "CSS selector or DOM element to be used as a custom scroll container instead of the auto detected one",
+      "examples": [
+        ".scroll-target-class",
+        "#scroll-target-id",
+        "$refs.scrollTarget",
+        "document.body"
+      ],
+      "category": "behavior"
+    },
+    "ripple": {
+      "type": ["Boolean", "Object"],
+      "desc": "Configure material ripple (disable it by setting it to 'false' or supply a config object)",
+      "default": "true",
+      "examples": [
+        "false",
+        "{ early: true, center: true, color: 'teal', keyCodes: [] }"
+      ],
+      "category": "style"
+    },
+    "evt": {
+      "type": "Event",
+      "desc": "JS event object"
+    }
+  },
+  "slots": {
+    "default": {
+      "desc": "Default slot in the devland unslotted content of the component"
+    }
+  },
+  "events": {
+    "update:model-value": {
+      "desc": "Emitted when the component needs to change the model; Is also used by v-model",
+      "params": {
+        "value": {
+          "type": "Any",
+          "desc": "New model value",
+          "required": true
+        }
+      }
+    },
+    "show": {
+      "desc": "Emitted after component has triggered show()",
+      "params": {
+        "evt": {
+          "extends": "evt",
+          "required": true
+        }
+      }
+    },
+    "before-show": {
+      "desc": "Emitted when component triggers show() but before it finishes doing it",
+      "params": {
+        "evt": {
+          "extends": "evt",
+          "required": true
+        }
+      }
+    },
+    "after-show": {
+      "desc": "Emitted when component show animation is finished"
+    },
+    "hide": {
+      "desc": "Emitted after component has triggered hide()",
+      "params": {
+        "evt": {
+          "extends": "evt",
+          "required": true
+        }
+      }
+    },
+    "before-hide": {
+      "desc": "Emitted when component triggers hide() but before it finishes doing it",
+      "params": {
+        "evt": {
+          "extends": "evt",
+          "required": true
+        }
+      }
+    },
+    "after-hide": {
+      "desc": "Emitted when component hide animation is finished"
+    },
+    "click": {
+      "desc": "Emitted when user clicks/taps on the component",
+      "params": {
+        "evt": {
+          "extends": "evt",
+          "required": true
+        }
+      }
+    }
+  },
+  "methods": {
+    "show": {
+      "desc": "Triggers component to show",
+      "params": {
+        "evt": {
+          "extends": "evt",
+          "required": false
+        }
+      },
+      "returns": null
+    },
+    "hide": {
+      "desc": "Triggers component to hide",
+      "params": {
+        "evt": {
+          "extends": "evt",
+          "required": false
+        }
+      },
+      "returns": null
+    },
+    "toggle": {
+      "desc": "Triggers component to toggle between show/hide",
+      "params": {
+        "evt": {
+          "extends": "evt",
+          "required": false
+        }
+      },
+      "returns": null
+    }
+  }
+}

package/src/composables/useAssistant.js

@@ -0,0 +1,201 @@
+import { computed, ref, watch } from 'vue'
+
+import docsectorConfig from 'docsector.config.js'
+import { normalizeAiAssistantConfig } from '../ai-assistant/config'
+import { createAssistantRequestPayload } from '../ai-assistant/messages'
+import { clearAssistantSession, loadAssistantSession, saveAssistantSession } from '../ai-assistant/session'
+import { extractAssistantStreamDelta, normalizeAssistantSourceChunks, parseServerSentEvents } from '../ai-assistant/stream'
+
+const assistantConfig = normalizeAiAssistantConfig(docsectorConfig)
+const assistantMessages = ref([])
+const assistantSources = ref([])
+let assistantSessionReady = false
+let assistantSessionWatcherReady = false
+
+function createMessage (role, content = '') {
+  return {
+    id: `${role}-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+    role,
+    content
+  }
+}
+
+function getCompletionText (payload) {
+  return payload?.choices?.[0]?.message?.content
+    || payload?.response
+    || payload?.content
+    || ''
+}
+
+function persistAssistantSession () {
+  saveAssistantSession({
+    messages: assistantMessages.value,
+    sources: assistantSources.value
+  })
+}
+
+function ensureAssistantSession () {
+  if (!assistantSessionReady) {
+    const session = loadAssistantSession()
+    assistantMessages.value = session.messages
+    assistantSources.value = session.sources
+    assistantSessionReady = true
+  }
+
+  if (!assistantSessionWatcherReady) {
+    watch([assistantMessages, assistantSources], persistAssistantSession, { deep: true })
+    assistantSessionWatcherReady = true
+  }
+}
+
+export default function useAssistant ({ route, locale, getContext } = {}) {
+  ensureAssistantSession()
+
+  const messages = assistantMessages
+  const sources = assistantSources
+  const loading = ref(false)
+  const error = ref('')
+  const abortController = ref(null)
+
+  const hasMessages = computed(() => messages.value.length > 0)
+
+  const clear = () => {
+    messages.value = []
+    sources.value = []
+    error.value = ''
+    clearAssistantSession()
+  }
+
+  const stop = () => {
+    abortController.value?.abort()
+    abortController.value = null
+    loading.value = false
+  }
+
+  const appendAssistantContent = (message, content) => {
+    if (!content) return
+    message.content += content
+  }
+
+  const consumeStream = async (response, assistantMessage) => {
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    let reading = true
+
+    while (reading) {
+      const { done, value } = await reader.read()
+      if (done) {
+        reading = false
+        break
+      }
+
+      buffer += decoder.decode(value, { stream: true })
+      const parts = buffer.split(/\r?\n\r?\n/)
+      buffer = parts.pop() || ''
+
+      for (const part of parts) {
+        const events = parseServerSentEvents(`${part}\n\n`)
+        for (const event of events) {
+          const delta = extractAssistantStreamDelta(event)
+          if (delta.done) return
+          appendAssistantContent(assistantMessage, delta.content)
+          if (delta.chunks.length > 0) {
+            sources.value = delta.chunks
+          }
+        }
+      }
+    }
+
+    if (buffer.trim()) {
+      const events = parseServerSentEvents(`${buffer}\n\n`)
+      for (const event of events) {
+        const delta = extractAssistantStreamDelta(event)
+        appendAssistantContent(assistantMessage, delta.content)
+        if (delta.chunks.length > 0) {
+          sources.value = delta.chunks
+        }
+      }
+    }
+  }
+
+  const send = async (content) => {
+    const prompt = String(content || '').trim()
+    if (!prompt || loading.value) return
+
+    error.value = ''
+    sources.value = []
+
+    const userMessage = createMessage('user', prompt)
+    const assistantMessage = createMessage('assistant')
+    messages.value.push(userMessage, assistantMessage)
+    // Use the reactive proxy from the array so streamed mutations trigger
+    // live re-renders (raw object mutations bypass Vue reactivity).
+    const liveAssistantMessage = messages.value[messages.value.length - 1]
+
+    abortController.value = new AbortController()
+    loading.value = true
+
+    try {
+      const payload = createAssistantRequestPayload({
+        messages: messages.value
+          .filter(message => message.content.trim())
+          .map(({ role, content }) => ({ role, content })),
+        route: route?.value || route,
+        locale: locale?.value || locale,
+        context: typeof getContext === 'function' ? getContext() : {}
+      })
+
+      const response = await fetch(assistantConfig.endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+        signal: abortController.value.signal
+      })
+
+      if (!response.ok) {
+        let message = `Assistant request failed with ${response.status}`
+        try {
+          const payload = await response.json()
+          message = payload?.error?.message || message
+        } catch {
+          // keep status message
+        }
+        throw new Error(message)
+      }
+
+      const contentType = response.headers.get('content-type') || ''
+      if (contentType.includes('text/event-stream') && response.body) {
+        await consumeStream(response, liveAssistantMessage)
+      } else {
+        const payload = await response.json()
+        liveAssistantMessage.content = getCompletionText(payload)
+        sources.value = normalizeAssistantSourceChunks(payload?.chunks)
+      }
+
+      if (!liveAssistantMessage.content.trim()) {
+        liveAssistantMessage.content = 'No answer was returned for this request.'
+      }
+    } catch (err) {
+      if (err?.name !== 'AbortError') {
+        error.value = err?.message || 'Assistant request failed.'
+        liveAssistantMessage.content = ''
+      }
+    } finally {
+      loading.value = false
+      abortController.value = null
+    }
+  }
+
+  return {
+    config: assistantConfig,
+    messages,
+    sources,
+    loading,
+    error,
+    hasMessages,
+    send,
+    stop,
+    clear
+  }
+}

package/src/i18n/helpers.js

@@ -28,6 +28,7 @@ const engineDefaults = {
       newVersion: 'New in',
       copyPage: 'Copy page',
       copyPageCaption: 'Copy page as Markdown for LLMs',
+      copyInlineCode: 'Click to copy inline code',
       copied: 'Copied!',
       viewAsMarkdown: 'View as Markdown',
       viewAsMarkdownCaption: 'View this page as plain text',
@@ -77,6 +78,7 @@ const engineDefaults = {
       newVersion: 'Novo em',
       copyPage: 'Copiar página',
       copyPageCaption: 'Copiar página como Markdown para LLMs',
+      copyInlineCode: 'Clique para copiar o código inline',
       copied: 'Copiado!',
       viewAsMarkdown: 'Ver como Markdown',
       viewAsMarkdownCaption: 'Ver esta página como texto simples',

package/src/i18n/languages/en-US.hjson

@@ -35,6 +35,7 @@
     newVersion: 'New in',
     copyPage: 'Copy page',
     copyPageCaption: 'Copy page as Markdown for LLMs',
+    copyInlineCode: 'Click to copy inline code',
     copied: 'Copied!',
     viewAsMarkdown: 'View as Markdown',
     viewAsMarkdownCaption: 'View this page as plain text',
@@ -105,6 +106,27 @@
     changelog: 'Changelog'
   },
 
+  assistant: {
+    title: 'Docsector Assistant',
+    subtitle: "I'm here to help you with the docs.",
+    open: 'Open assistant',
+    close: 'Close assistant',
+    clear: 'Clear conversation',
+    placeholder: 'Ask, search, or explain...',
+    send: 'Send',
+    stop: 'Stop',
+    context: 'Based on your context',
+    sources: 'Sources',
+    sourcesCount: '{count} sources',
+    thinking: 'Searching the docs…',
+    resize: 'Resize assistant',
+    greeting: {
+      morning: 'Good morning',
+      afternoon: 'Good afternoon',
+      evening: 'Good evening'
+    }
+  },
+
   // @
   system: {
     documentation: 'Documentation',

package/src/i18n/languages/pt-BR.hjson

@@ -34,6 +34,7 @@
     newVersion: 'Novo em',
     copyPage: 'Copiar página',
     copyPageCaption: 'Copiar página como Markdown para LLMs',
+    copyInlineCode: 'Clique para copiar o código inline',
     copied: 'Copiado!',
     viewAsMarkdown: 'Ver como Markdown',
     viewAsMarkdownCaption: 'Ver esta página como texto simples',
@@ -104,6 +105,27 @@
     changelog: 'Changelog'
   },
 
+  assistant: {
+    title: 'Assistente Docsector',
+    subtitle: 'Estou aqui para ajudar com a documentação.',
+    open: 'Abrir assistente',
+    close: 'Fechar assistente',
+    clear: 'Limpar conversa',
+    placeholder: 'Pergunte, pesquise ou explique...',
+    send: 'Enviar',
+    stop: 'Parar',
+    context: 'Com base no seu contexto',
+    sources: 'Fontes',
+    sourcesCount: '{count} fontes',
+    thinking: 'Consultando a documentação…',
+    resize: 'Redimensionar assistente',
+    greeting: {
+      morning: 'Bom dia',
+      afternoon: 'Boa tarde',
+      evening: 'Boa noite'
+    }
+  },
+
   // @
   system: {
     documentation: 'Documentação',

package/src/layouts/DefaultLayout.vue

@@ -15,6 +15,17 @@
         <q-icon class="q-mb-xs q-mr-sm" :name="headerTitleIcon" />
         {{ headerTitleText }}
       </q-toolbar-title>
+      <q-btn
+        v-if="assistantEnabled"
+        class="filled d-header__assistant-toggle"
+        :class="assistantOpen ? 'active' : null"
+        square
+        icon="auto_awesome"
+        :aria-label="t('assistant.open')"
+        @click="toggleAssistant"
+      >
+        <q-tooltip>{{ t('assistant.open') }}</q-tooltip>
+      </q-btn>
       <q-btn class="filled" square icon="settings" aria-label="Configuration" @click="openSettingsDialog" />
     </q-toolbar>
 
@@ -59,12 +70,15 @@ import { useMeta, colors } from 'quasar'
 
 import DMenu from '../components/DMenu.vue'
 import docsectorConfig from 'docsector.config.js'
+import { normalizeAiAssistantConfig } from '../ai-assistant/config'
 import { allBooks, booksByVersion } from 'virtual:docsector-books'
 import { pageTitleI18nPath } from '../i18n/path'
 
 defineOptions({ name: 'LayoutDefault' })
 
 const branding = docsectorConfig.branding || {}
+const assistantConfig = normalizeAiAssistantConfig(docsectorConfig)
+const assistantEnabled = assistantConfig.enabled === true
 
 const route = useRoute()
 const router = useRouter()
@@ -75,6 +89,8 @@ const layout = ref({
   menu: false
 })
 
+const assistantOpen = computed(() => store.state.layout.assistant)
+
 const headerTitleIcon = computed(() => {
   return route.matched[0].meta.icon ?? route.meta.icon
 })
@@ -271,6 +287,10 @@ function openSettingsDialog () {
   store.commit('settings/dialog', true)
 }
 
+function toggleAssistant () {
+  store.commit('layout/setAssistant', !store.state.layout.assistant)
+}
+
 function getFirstRoutePathByBook (bookId) {
   const routes = router.options?.routes || []
   const versionId = activeVersionId.value
@@ -356,6 +376,8 @@ store.commit('page/resetAnchors')
     color: var(--d-book-tab-active-color, #ffffff)
   .q-btn
     border-radius: 0
+  .d-header__assistant-toggle.active
+    background: rgba(255, 255, 255, 0.16)
   .q-btn:before
     box-shadow: 0 0 5px rgba(0, 0, 0, 0.2), 0 0 2px rgba(0, 0, 0, 0.14), 0 0 1px -2px rgba(0, 0, 0, 0.12)
     border-radius: 0

package/src/markdown-agent.js

@@ -0,0 +1,32 @@
+export const MARKDOWN_AGENT_USER_AGENT_SOURCE = [
+  'GPTBot',
+  'ChatGPT-User',
+  'OAI-SearchBot',
+  'ClaudeBot',
+  'Claude-User',
+  'Claude-SearchBot',
+  'anthropic-ai',
+  'Google-Extended',
+  'Gemini-Deep-Research',
+  'PerplexityBot',
+  'Perplexity-User',
+  'Bytespider',
+  'CCBot',
+  'Meta-ExternalAgent',
+  'FacebookBot',
+  'Amazonbot',
+  'Applebot-Extended',
+  'cohere-ai',
+  'DuckAssistBot',
+  'GrokBot',
+  'AI2Bot',
+  'YouBot',
+  'PetalBot',
+  'Cloudflare-AI-Search'
+].join('|')
+
+export const MARKDOWN_AGENT_USER_AGENT_PATTERN = new RegExp(MARKDOWN_AGENT_USER_AGENT_SOURCE, 'i')
+
+export function matchesMarkdownAgentUserAgent (userAgent = '') {
+  return MARKDOWN_AGENT_USER_AGENT_PATTERN.test(String(userAgent || ''))
+}

package/src/pages/manual/basic/ai-assistant.overview.en-US.md

@@ -0,0 +1,69 @@
+## Overview
+
+The AI Assistant adds an optional documentation chat panel to Docsector pages. It is designed for semantic RAG workflows on Cloudflare while keeping the browser integration simple: users open a drawer from the global header, and the Cloudflare Pages Function talks to the configured AI provider.
+
+The first provider is Cloudflare AI Search. It can crawl Docsector's generated Markdown sitemap, retrieve relevant chunks with hybrid search, and stream an answer with source chunks that the panel can show as citations.
+
+## What It Adds
+
+- A right-side assistant drawer on desktop.
+- A fullscreen assistant dialog on mobile.
+- Suggested prompts, current-page context, streaming responses, and source links.
+- Build-time AI Search artifacts when `siteUrl` is configured.
+- A same-origin internal endpoint so credentials stay server-side.
+
+## Enable It
+
+```javascript
+export default {
+  siteUrl: 'https://docs.example.com',
+
+  aiAssistant: {
+    enabled: true,
+    provider: 'aiSearch',
+    endpoint: '/assistant',
+    aiSearch: {
+      binding: 'AI_SEARCH',
+      instanceNameEnv: 'AI_SEARCH_INSTANCE_NAME',
+      accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',
+      apiTokenEnv: 'CLOUDFLARE_API_TOKEN',
+      retrievalType: 'hybrid',
+      maxResults: 6,
+      stream: true
+    }
+  }
+}
+```
+
+Set `AI_SEARCH_INSTANCE_NAME` in Cloudflare Pages environment variables for deployed environments, or in `.dev.vars` when running `wrangler pages dev` locally.
+
+## Cloudflare AI Search
+
+Create an AI Search instance and configure a Website data source. Docsector always publishes `/sitemap.xml` during build and advertises it from `robots.txt`, so Cloudflare's crawler can discover the site automatically.
+
+For cleaner retrieval, point the specific sitemap setting to:
+
+```text
+https://docs.example.com/ai-search-sitemap.xml
+```
+
+The AI Search sitemap points to Markdown URLs, which are cleaner for retrieval than rendered SPA HTML. The manifest at `/.well-known/ai-search/manifest.json` lists titles, routes, locales, books, versions, and subpages for the same source set.
+
+## Runtime Endpoint
+
+The generated Pages Function accepts chat messages, current route metadata, locale, and optional selected page text. It forwards the request to AI Search by binding when available, or by REST using encrypted Cloudflare environment variables. The endpoint is an internal API for the drawer, not a page users navigate to.
+
+The browser never needs a Cloudflare API token.
+
+## 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
+```
+
+Remote AI Search and Workers AI bindings can incur Cloudflare usage during local development.