@docsector/docsector-reader 4.5.6 → 4.7.0

package/README.md

@@ -59,7 +59,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🔗 **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
-- 💬 **Assistant Chat UX Enhancements** — Long conversations keep focus on recent messages, load earlier history progressively, deduplicate repeated sources, preserve the assistant panel open state across reloads, include per-message copy actions, and show a floating quick return to the bottom
+- 💬 **Assistant Chat UX Enhancements** — Long conversations keep focus on recent messages, load earlier history progressively, deduplicate repeated sources, preserve the assistant panel open state across reloads, include per-message copy actions and hover-revealed message times, and show a floating quick return to the bottom
 - 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers
 - 🏷️ **Clickable Header Branding** — The configured `branding.logo` and `branding.name` render as a home link in the global header, aligned left on desktop with a compact mobile treatment
 - 📚 **Book Tabs with Per-State Colors** — Define `*.book.js` tabs with icons, order, and `color.active` / `color.inactive`
@@ -67,6 +67,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🦶 **Global Branding Footer** — Built-in `Powered by Docsector` footer renders across documentation and system pages, while respecting each page's own scroll container for full-width layout integration without double scrollbars
 - 🔀 **Internal Shortcut Pages** — Route entries can redirect with `config.link.to`, keeping localized titles while inheriting icon/status from the destination page
 - 📐 **Responsive Subpage Toolbar** — Subpage actions align with the content column on desktop and dock to the bottom on mobile
+- 🆚 **Subpage Templates** — Subpages opt into a structured template via `vs: { template: 'vs' }`; the managed/strict `vs` template owns the order and localized titles of its **Features**, **Performance** and **Security** sections (one `##` heading per section, missing sections dropped gracefully), auto-colorizes `✓`/`✗`/`➕` comparison marks, and highlights the column whose header matches the consumer's `branding.name`
 - ⬆️ **Reading Progress Back to Top** — Documentation subpages can show a floating back-to-top control with circular reading progress that stays above the mobile subpage toolbar
 - 🏷️ **Status Badges** — Mark pages as `done`, `draft`, `empty`, or `new` with visual indicators
 - ✏️ **Edit on GitHub** — Direct links to edit pages on your repository
@@ -301,7 +302,7 @@ Check `checks.discovery.webMcp.status` equals `"pass"`.
 
 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. Conversations restore at the latest message, reveal earlier history progressively in long chats, deduplicate repeated source links, preserve the panel open state across page reloads, and provide per-message copy actions.
+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. Conversations restore at the latest message, reveal earlier history progressively in long chats, deduplicate repeated source links, preserve the panel open state across page reloads, and provide per-message copy actions with hover-revealed message times.
 
 ### Configure
 
@@ -332,8 +333,8 @@ export default {
       accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',
       apiTokenEnv: 'CLOUDFLARE_API_TOKEN',
       model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
-      retrievalType: 'hybrid',
-      maxResults: 6,
+      retrievalType: 'vector',
+      maxResults: 10,
       matchThreshold: 0.4,
       contextExpansion: 1,
       queryRewrite: { enabled: true },
@@ -886,8 +887,8 @@ export default {
       instanceNameEnv: 'AI_SEARCH_INSTANCE_NAME',
       accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',
       apiTokenEnv: 'CLOUDFLARE_API_TOKEN',
-      retrievalType: 'hybrid',
-      maxResults: 6,
+      retrievalType: 'vector',
+      maxResults: 10,
       stream: true
     }
   },
@@ -1137,6 +1138,7 @@ Notes:
 - In `manual.index.js`, route keys are relative to the `manual` book (for example `'/my-section/my-page'` becomes `/manual/my-section/my-page/...`).
 - You only need to set `config.book` when overriding the inferred book from the registry file.
 - When `showcase` or `vs` are enabled, the subpage toolbar aligns with the content width on desktop and becomes a bottom action bar on mobile.
+- A subpage can opt into a **structured template** with the object form `vs: { template: 'vs' }` (the boolean `true` stays `freestyle`). The built-in `vs` template is managed/strict: it owns the order and localized titles of its **Features**, **Performance** and **Security** sections — write one `##` heading per section in the Markdown and omitted sections are dropped gracefully.
 
 2️⃣ Create Markdown files:
 

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.5.6'
+const VERSION = '4.7.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`

package/docsector.config.js

@@ -88,10 +88,10 @@ export default {
       matchThreshold: 0.4,
       contextExpansion: 1,
       queryRewrite: {
-        enabled: true
+        enabled: false
       },
       reranking: {
-        enabled: true,
+        enabled: false,
         model: '@cf/baai/bge-reranker-base',
         matchThreshold: 0.4
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "4.5.6",
+  "version": "4.7.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",
@@ -57,7 +57,8 @@
     "url": "https://github.com/docsector/docsector-reader/issues"
   },
   "scripts": {
-    "dev": "npx wrangler pages dev dist/spa",
+    "dev": "quasar dev",
+    "dev:pages": "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/src/ai-assistant/panel.js

@@ -2,6 +2,39 @@ export function hasAssistantMessageContent(message) {
   return String(message?.content || '').trim().length > 0
 }
 
+export function getAssistantMessageTimestamp(message) {
+  const timestamp = Number(message?.timestamp)
+  if (Number.isFinite(timestamp) && timestamp > 0) {
+    return timestamp
+  }
+
+  const id = String(message?.id || '')
+  const match = id.match(/^(?:user|assistant)-(\d{12,})-/)
+  if (!match) {
+    return null
+  }
+
+  const legacyTimestamp = Number(match[1])
+  return Number.isFinite(legacyTimestamp) && legacyTimestamp > 0 ? legacyTimestamp : null
+}
+
+export function formatAssistantMessageTime(message, locale = 'en-US') {
+  const timestamp = getAssistantMessageTimestamp(message)
+  if (!timestamp) {
+    return ''
+  }
+
+  const date = new Date(timestamp)
+  if (Number.isNaN(date.getTime())) {
+    return ''
+  }
+
+  return new Intl.DateTimeFormat(locale || 'en-US', {
+    hour: '2-digit',
+    minute: '2-digit'
+  }).format(date)
+}
+
 export function listVisibleAssistantMessages(messages = []) {
   return messages.filter((message) => {
     if (message?.role !== 'assistant') {
@@ -12,6 +45,26 @@ export function listVisibleAssistantMessages(messages = []) {
   })
 }
 
+export function hasVisibleAssistantHistoryAfter(messages = [], messageId = '') {
+  const targetId = String(messageId || '')
+  if (!targetId) {
+    return false
+  }
+
+  const targetIndex = messages.findIndex(message => String(message?.id || '') === targetId)
+  if (targetIndex === -1) {
+    return false
+  }
+
+  return messages.slice(targetIndex + 1).some((message) => {
+    if (message?.role === 'assistant') {
+      return hasAssistantMessageContent(message)
+    }
+
+    return hasAssistantMessageContent(message)
+  })
+}
+
 export const ASSISTANT_MESSAGE_WINDOW_SIZE = 60
 export const ASSISTANT_MESSAGE_WINDOW_STEP = 40
 

package/src/ai-assistant/session.js

@@ -1,4 +1,5 @@
 import { dedupeAssistantSources } from './stream'
+import { getAssistantMessageTimestamp } from './panel'
 
 export const ASSISTANT_SESSION_STORAGE_KEY = 'docsector.assistant.session.v1'
 
@@ -17,6 +18,11 @@ function cleanString (value = '', maxLength = Number.MAX_SAFE_INTEGER) {
   return String(value || '').slice(0, maxLength)
 }
 
+function normalizeMessageTimestamp (message) {
+  const timestamp = getAssistantMessageTimestamp(message)
+  return timestamp ? { timestamp } : {}
+}
+
 export function normalizeAssistantSession (session = {}) {
   const messages = (Array.isArray(session?.messages) ? session.messages : [])
     .map((message, index) => {
@@ -24,11 +30,16 @@ export function normalizeAssistantSession (session = {}) {
       const content = cleanString(message?.content, MAX_MESSAGE_CONTENT_LENGTH)
       if (!VALID_ROLES.has(role) || !content.trim()) return null
 
-      return {
+      const normalizedMessage = {
         id: cleanString(message?.id || `${role}-${index + 1}`, 160),
         role,
         content
       }
+
+      return {
+        ...normalizedMessage,
+        ...normalizeMessageTimestamp(message)
+      }
     })
     .filter(Boolean)
     .slice(-MAX_PERSISTED_MESSAGES)
@@ -90,4 +101,4 @@ export function clearAssistantSession ({ storage = null, key = ASSISTANT_SESSION
   } catch {
     // Ignore storage failures.
   }
-}
+}

package/src/components/DAssistantPanel.vue

@@ -8,7 +8,9 @@ import useAssistant from '../composables/useAssistant'
 import {
   ASSISTANT_MESSAGE_WINDOW_SIZE,
   ASSISTANT_MESSAGE_WINDOW_STEP,
+  formatAssistantMessageTime,
   getAssistantMessageWindow,
+  hasVisibleAssistantHistoryAfter,
   isAssistantThinkingState
 } from '../ai-assistant/panel'
 import DPageTokens from './DPageTokens.vue'
@@ -57,6 +59,8 @@ const scrollArea = ref(null)
 const visibleMessageLimit = ref(ASSISTANT_MESSAGE_WINDOW_SIZE)
 const copiedMessageId = ref('')
 const showScrollToBottom = ref(false)
+const retryHistoryDialogOpen = ref(false)
+const pendingRetryMessageId = ref('')
 let scrollFrame = 0
 let copiedMessageTimer = null
 let revealingOlderMessages = false
@@ -131,6 +135,10 @@ const hasMessageContent = (message) => {
   return String(message?.content || '').trim().length > 0
 }
 
+const messageTime = (message) => {
+  return formatAssistantMessageTime(message, locale.value)
+}
+
 const messageHasSources = (message) => {
   return hasSources.value && String(message?.id || '') === latestAssistantMessageId.value
 }
@@ -281,6 +289,41 @@ const messageCopyIcon = (message) => {
   return copiedMessageId.value === String(message?.id || '') ? 'check' : 'content_copy'
 }
 
+const runRetryMessage = async (messageId) => {
+  const id = String(messageId || '')
+  if (!id) return
+  await assistant.retryFromUserMessage(id)
+}
+
+const retryMessage = async (message) => {
+  const id = String(message?.id || '')
+  if (!id || assistant.loading.value) return
+
+  if (hasVisibleAssistantHistoryAfter(assistant.messages.value, id)) {
+    pendingRetryMessageId.value = id
+    retryHistoryDialogOpen.value = true
+    return
+  }
+
+  await runRetryMessage(id)
+}
+
+const clearPendingRetryMessage = () => {
+  pendingRetryMessageId.value = ''
+}
+
+const cancelRetryMessage = () => {
+  retryHistoryDialogOpen.value = false
+  clearPendingRetryMessage()
+}
+
+const confirmRetryMessage = async () => {
+  const id = pendingRetryMessageId.value
+  retryHistoryDialogOpen.value = false
+  clearPendingRetryMessage()
+  await runRetryMessage(id)
+}
+
 const submit = async (value = input.value) => {
   const prompt = String(value || '').trim()
   if (!prompt) return
@@ -419,7 +462,7 @@ onBeforeUnmount(() => {
           <q-btn
             flat dense
             text-color="primary"
-            class="d-assistant-message__copy d-assistant-message__copy--assistant"
+            class="d-assistant-message__action d-assistant-message__copy d-assistant-message__copy--assistant"
             :icon="messageCopyIcon(message)"
             :aria-label="t('assistant.copyMessage')"
             @click="copyMessage(message)"
@@ -483,6 +526,11 @@ onBeforeUnmount(() => {
               </q-list>
             </q-menu>
           </q-chip>
+
+          <span
+            v-if="messageTime(message)"
+            class="d-assistant-message__timestamp"
+          >{{ messageTime(message) }}</span>
         </div>
 
         <div
@@ -491,15 +539,30 @@ onBeforeUnmount(() => {
         >
           <div class="d-assistant-message__hoverlayer">
             <q-btn
+              v-if="!assistant.loading.value"
               flat dense
               text-color="primary"
-              class="d-assistant-message__copy d-assistant-message__copy--user"
+              class="d-assistant-message__action d-assistant-message__retry"
+              icon="refresh"
+              :aria-label="t('assistant.retryMessage')"
+              @click="retryMessage(message)"
+            >
+              <q-tooltip>{{ t('assistant.retryMessage') }}</q-tooltip>
+            </q-btn>
+            <q-btn
+              flat dense
+              text-color="primary"
+              class="d-assistant-message__action d-assistant-message__copy d-assistant-message__copy--user"
               :icon="messageCopyIcon(message)"
               :aria-label="t('assistant.copyMessage')"
               @click="copyMessage(message)"
             >
               <q-tooltip>{{ t('assistant.copyMessage') }}</q-tooltip>
             </q-btn>
+            <span
+              v-if="messageTime(message)"
+              class="d-assistant-message__timestamp"
+            >{{ messageTime(message) }}</span>
           </div>
         </div>
       </div>
@@ -572,6 +635,33 @@ onBeforeUnmount(() => {
       </div>
     </div>
   </footer>
+
+  <q-dialog v-model="retryHistoryDialogOpen" @hide="clearPendingRetryMessage">
+    <q-card class="d-assistant-retry-dialog">
+      <q-card-section class="d-assistant-retry-dialog__header">
+        <q-icon name="warning_amber" size="24px" />
+        <div>
+          <h3>{{ t('assistant.retryHistoryTitle') }}</h3>
+          <p>{{ t('assistant.retryHistoryMessage') }}</p>
+        </div>
+      </q-card-section>
+      <q-card-actions align="right" class="d-assistant-retry-dialog__actions">
+        <q-btn
+          unelevated no-caps
+          color="grey-7"
+          text-color="white"
+          :label="t('assistant.retryHistoryCancel')"
+          @click="cancelRetryMessage"
+        />
+        <q-btn
+          unelevated no-caps
+          color="primary"
+          :label="t('assistant.retryHistoryConfirm')"
+          @click="confirmRetryMessage"
+        />
+      </q-card-actions>
+    </q-card>
+  </q-dialog>
 </aside>
 </template>
 
@@ -636,7 +726,7 @@ onBeforeUnmount(() => {
       color: rgba(255, 255, 255, 0.86)
       border-color: rgba(255, 255, 255, 0.12)
 
-    .d-assistant-message__copy
+    .d-assistant-message__action
       color: rgba(255, 255, 255, 0.84)
 
     .d-assistant-sources-chip__avatar
@@ -862,10 +952,12 @@ onBeforeUnmount(() => {
       color: white
       background: var(--q-primary)
 
-    &:hover .d-assistant-message__hoverlayer .d-assistant-message__copy,
-    &:focus-within .d-assistant-message__hoverlayer .d-assistant-message__copy,
-    .d-assistant-message__hoverlayer:hover .d-assistant-message__copy,
-    .d-assistant-message__hoverlayer:focus-within .d-assistant-message__copy
+    &:hover .d-assistant-message__hoverlayer .d-assistant-message__action,
+    &:focus-within .d-assistant-message__hoverlayer .d-assistant-message__action,
+    .d-assistant-message__hoverlayer:hover .d-assistant-message__action,
+    .d-assistant-message__hoverlayer:focus-within .d-assistant-message__action,
+    &:hover .d-assistant-message__timestamp,
+    &:focus-within .d-assistant-message__timestamp
       opacity: 1
       pointer-events: auto
 
@@ -881,6 +973,10 @@ onBeforeUnmount(() => {
     .d-assistant-message__footer
       justify-content: flex-start
 
+    &:hover .d-assistant-message__timestamp,
+    &:focus-within .d-assistant-message__timestamp
+      opacity: 1
+
   &__content
     max-width: 88%
     min-width: 0
@@ -935,7 +1031,7 @@ onBeforeUnmount(() => {
 
     .d-assistant-sources-chip
       flex: 0 1 auto
-      max-width: calc(100% - 38px)
+      max-width: calc(100% - 92px)
 
     &--user
       width: auto
@@ -946,7 +1042,7 @@ onBeforeUnmount(() => {
       align-items: center
       justify-content: center
 
-  &__copy
+  &__action
     flex: 0 0 auto
     width: 30px
     height: 30px
@@ -960,25 +1056,45 @@ onBeforeUnmount(() => {
 
       i
         font-size: 17px !important
-        margin-left: 3px
+        margin: 0
 
+  &__copy
     &--assistant
       margin-left: -2px
 
+  &__retry
+    color: currentColor
+
   &__hoverlayer
     display: flex
     align-items: center
-    justify-content: center
-    width: 30px
+    justify-content: flex-end
+    gap: 6px
+    width: auto
     height: 30px
     min-width: 30px
     min-height: 30px
 
-    .d-assistant-message__copy
+    .d-assistant-message__action
       opacity: 0
       pointer-events: none
       transition: opacity 0.14s ease
 
+  &__timestamp
+    flex: 0 0 auto
+    margin-left: auto
+    color: currentColor
+    font-size: 0.72rem
+    font-weight: 700
+    font-variant-numeric: tabular-nums
+    line-height: 30px
+    opacity: 0
+    pointer-events: none
+    transition: opacity 0.14s ease
+
+  &__hoverlayer &__timestamp
+    margin-left: 0
+
   &__thinking
     display: flex
     align-items: center
@@ -987,6 +1103,31 @@ onBeforeUnmount(() => {
     opacity: 0.78
     font-weight: 600
 
+.d-assistant-retry-dialog
+  width: min(360px, calc(100vw - 32px))
+  border-radius: 8px
+
+  &__header
+    display: flex
+    align-items: flex-start
+    gap: 12px
+    padding: 18px 18px 10px
+
+    h3
+      margin: 0 0 6px
+      font-size: 1rem
+      line-height: 1.3
+      font-weight: 800
+
+    p
+      margin: 0
+      color: currentColor
+      opacity: 0.72
+      line-height: 1.45
+
+  &__actions
+    padding: 8px 12px 14px
+
 .d-assistant-sources-chip
   max-width: 100%
   min-width: 0

package/src/components/DPageSection.vue

@@ -7,8 +7,10 @@ import DPageTokens from './DPageTokens.vue'
 import { pageValueI18nPath } from '../i18n/path'
 import { buildPageAnchorTree } from './page-anchor-tree'
 import { tokenizePageSectionSource } from './page-section-tokens'
+import { applyTemplateSections } from './page-template-sections'
+import docsectorConfig from 'docsector.config.js'
 
-defineProps({
+const props = defineProps({
   id: {
     type: Number,
     required: true
@@ -16,11 +18,15 @@ defineProps({
   renderPrimaryHeading: {
     type: Boolean,
     default: false
+  },
+  template: {
+    type: Object,
+    default: null
   }
 })
 
 const store = useStore()
-const { t } = useI18n()
+const { t, locale } = useI18n()
 
 const tokenized = computed(() => {
   const absolute = store.state.i18n.absolute
@@ -29,7 +35,15 @@ const tokenized = computed(() => {
     return []
   }
 
-  return tokenizePageSectionSource(t(pageValueI18nPath(absolute, 'source')))
+  const tokens = tokenizePageSectionSource(t(pageValueI18nPath(absolute, 'source')))
+
+  if (Array.isArray(props.template?.sections) && props.template.sections.length > 0) {
+    return applyTemplateSections(tokens, props.template, locale.value, {
+      highlightColumn: docsectorConfig?.branding?.name
+    })
+  }
+
+  return tokens
 })
 
 watch(tokenized, (tokens) => {

package/src/components/DPageTokens.vue

@@ -88,6 +88,7 @@ import DBlockApi from './DBlockApi.vue'
   <div
     v-else-if="token.tag === 'table'"
     class="d-table-wrapper"
+    :class="{ 'd-table-wrapper--vs': token.highlight }"
   >
     <d-page-rich-content
       tag="table"

package/src/components/DSubpage.vue

@@ -9,10 +9,18 @@ import DPageBar from "./DPageBar.vue";
 import DH1 from "./DH1.vue";
 import DPageSection from "./DPageSection.vue";
 import { usesRemoteReadmeHomeContent } from '../home-page-mode'
+import { getTemplate } from '../page-template'
 
 const route = useRoute()
 const store = useStore()
 
+const template = computed(() => {
+  const relative = store.state.page.relative
+  const subpage = relative ? relative.replace(/^\//, '') : 'overview'
+  const templates = route.matched?.[0]?.meta?.subpageTemplates
+  return getTemplate(templates?.[subpage])
+})
+
 const id = computed(() => {
   const path = route.path
 
@@ -42,7 +50,7 @@ const usesRemoteReadmeHome = computed(() => {
   </header>
 
   <main>
-    <d-page-section :id="id" :render-primary-heading="usesRemoteReadmeHome" />
+    <d-page-section :id="id" :render-primary-heading="usesRemoteReadmeHome" :template="template" />
   </main>
 </d-page>
 </template>

package/src/components/page-template-sections.js

@@ -0,0 +1,171 @@
+const stripHtml = (value) => String(value ?? '').replace(/<[^>]*>/g, '')
+
+/**
+ * Normalize a heading/key into a comparable slug: strip HTML and diacritics,
+ * lowercase, and collapse non-alphanumerics into single hyphens.
+ */
+const normalizeKey = (value) => stripHtml(value)
+  .normalize('NFD')
+  .replace(/[̀-ͯ]/g, '')
+  .toLowerCase()
+  .trim()
+  .replace(/[^a-z0-9]+/g, '-')
+  .replace(/^-+|-+$/g, '')
+
+const warnUnknownSection = (templateName, heading, allowed) => {
+  if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+    console.warn(
+      `[docsector] Unknown "${templateName}" template section: "${heading}". ` +
+      `Allowed sections: ${allowed.join(', ')}.`
+    )
+  }
+}
+
+// ? Comparison marks colorized in rendered content (✓ yes, ✗ no, ➕ add-on)
+const MARK_CLASS = { '✓': 'vs-mark--yes', '✗': 'vs-mark--no', '➕': 'vs-mark--dep' }
+const MARKABLE_TAGS = new Set(['p', 'table', 'ul', 'ol'])
+const MARK_PATTERN = /[✓✗➕]/
+
+const colorizeMarks = (html) => String(html ?? '').replace(
+  /[✓✗➕]/g,
+  (glyph) => `<span class="vs-mark ${MARK_CLASS[glyph]}">${glyph}</span>`
+)
+
+// ? Detect tables whose 2nd header matches the consumer-configured highlight column
+const isHighlightColumnTable = (html, label) => {
+  if (!label) {
+    return false
+  }
+
+  const header = html.match(/<thead[\s\S]*?<\/thead>/i)?.[0] ?? html.match(/<tr[\s\S]*?<\/tr>/i)?.[0] ?? ''
+  const cells = [...header.matchAll(/<th[^>]*>([\s\S]*?)<\/th>/gi)].map(cell => cell[1].replace(/<[^>]*>/g, '').trim())
+
+  return cells[1] === label
+}
+
+const transformToken = (token, highlightColumn) => {
+  if (!token || typeof token.content !== 'string') {
+    return token
+  }
+
+  let content = token.content
+  if (MARKABLE_TAGS.has(token.tag) && MARK_PATTERN.test(content)) {
+    content = colorizeMarks(content)
+  }
+
+  // ? Flag (not inject) — the <table> element is created by DPageTokens, not in token.content
+  const highlight = token.tag === 'table' && isHighlightColumnTable(token.content, highlightColumn)
+
+  if (content === token.content && !highlight) {
+    return token
+  }
+
+  return highlight ? { ...token, content, highlight: true } : { ...token, content }
+}
+
+/**
+ * Apply a structured subpage template to a flat token stream (managed/strict).
+ *
+ * The template owns the section structure: each canonical section is rendered in
+ * the template's declared order, with the template's localized title overriding
+ * the markdown heading. Sections absent from the markdown are gracefully omitted.
+ * Markdown content before the first `h2` is kept as an intro. Unknown top-level
+ * `h2` sections are warned about and appended after the canonical sections so no
+ * authored content is lost.
+ *
+ * Freestyle templates (no `sections`) return the tokens unchanged.
+ *
+ * @param {Array} tokens - Tokenized page section source.
+ * @param {Object} template - Resolved template preset.
+ * @param {string} [locale] - Active locale for section titles.
+ * @param {Object} [options] - Render options.
+ * @param {string} [options.highlightColumn] - Header label whose comparison column is emphasized (consumer-provided, e.g. the project name).
+ * @returns {Array} Reordered/relabeled token stream.
+ */
+export function applyTemplateSections (tokens, template, locale = 'en-US', options = {}) {
+  const sections = template?.sections
+  const highlightColumn = options.highlightColumn
+
+  if (!Array.isArray(sections) || sections.length === 0) {
+    return Array.isArray(tokens) ? tokens : []
+  }
+
+  // ? Map every accepted slug (canonical key + each localized title) to its section index
+  const indexBySlug = new Map()
+  sections.forEach((section, index) => {
+    indexBySlug.set(normalizeKey(section.key), index)
+
+    for (const title of Object.values(section.title || {})) {
+      const slug = normalizeKey(title)
+      if (slug && !indexBySlug.has(slug)) {
+        indexBySlug.set(slug, index)
+      }
+    }
+  })
+
+  // ! Partition tokens into intro, canonical buckets and unknown sections
+  const intro = []
+  const buckets = sections.map(() => null)
+  const unknowns = []
+  let current = null
+
+  // @ Walk the flat stream, splitting at h2 boundaries
+  for (const token of Array.isArray(tokens) ? tokens : []) {
+    if (token?.tag === 'h2') {
+      const slug = normalizeKey(token.anchorId ?? token.content)
+      const index = indexBySlug.has(slug) ? indexBySlug.get(slug) : -1
+
+      if (index >= 0) {
+        if (buckets[index] === null) {
+          buckets[index] = []
+        }
+        current = { type: 'section', index }
+      } else {
+        const unknown = { token, body: [] }
+        unknowns.push(unknown)
+        current = { type: 'unknown', unknown }
+      }
+
+      continue
+    }
+
+    if (current === null) {
+      intro.push(token)
+    } else if (current.type === 'section') {
+      buckets[current.index].push(token)
+    } else {
+      current.unknown.body.push(token)
+    }
+  }
+
+  // @@ Rebuild in canonical order
+  const output = [...intro]
+
+  sections.forEach((section, index) => {
+    const body = buckets[index]
+    if (body === null) {
+      return
+    }
+
+    output.push({
+      tag: 'h2',
+      anchorId: section.key,
+      content: section.title?.[locale] || section.title?.['en-US'] || section.key,
+      icon: section.icon
+    })
+    output.push(...body)
+  })
+
+  // ? Append unknown sections (non-destructive) after warning
+  if (unknowns.length > 0) {
+    const allowed = sections.map(section => section.key)
+
+    for (const unknown of unknowns) {
+      warnUnknownSection(template.name, stripHtml(unknown.token.content), allowed)
+      output.push(unknown.token, ...unknown.body)
+    }
+  }
+
+  // : colorize comparison marks (✓/✗/➕) + highlight the configured column
+  return output.map(token => transformToken(token, highlightColumn))
+}

package/src/composables/useAssistant.js

@@ -17,10 +17,13 @@ let assistantSessionPersistencePaused = false
 const ASSISTANT_SESSION_PERSIST_DEBOUNCE = 180
 
 function createMessage (role, content = '') {
+  const timestamp = Date.now()
+
   return {
-    id: `${role}-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+    id: `${role}-${timestamp}-${Math.random().toString(16).slice(2)}`,
     role,
-    content
+    content,
+    timestamp
   }
 }
 
@@ -121,6 +124,11 @@ export default function useAssistant ({ route, locale, getContext } = {}) {
     message.content += content
   }
 
+  const appendAssistantPlaceholder = () => {
+    messages.value.push(createMessage('assistant'))
+    return messages.value[messages.value.length - 1]
+  }
+
   const consumeStream = async (response, assistantMessage) => {
     const reader = response.body.getReader()
     const decoder = new TextDecoder()
@@ -175,22 +183,14 @@ export default function useAssistant ({ route, locale, getContext } = {}) {
     }
   }
 
-  const send = async (content) => {
-    const prompt = String(content || '').trim()
-    if (!prompt || loading.value) return
-
+  const prepareRequest = () => {
     assistantSessionPersistencePaused = true
     cancelPersistAssistantSession()
     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]
-
+  const requestAssistantResponse = async (liveAssistantMessage) => {
     abortController.value = new AbortController()
     loading.value = true
 
@@ -249,6 +249,36 @@ export default function useAssistant ({ route, locale, getContext } = {}) {
     }
   }
 
+  const send = async (content) => {
+    const prompt = String(content || '').trim()
+    if (!prompt || loading.value) return
+
+    prepareRequest()
+
+    messages.value.push(createMessage('user', prompt))
+    const liveAssistantMessage = appendAssistantPlaceholder()
+
+    await requestAssistantResponse(liveAssistantMessage)
+  }
+
+  const retryFromUserMessage = async (messageId) => {
+    const targetId = String(messageId || '')
+    if (!targetId || loading.value) return
+
+    const targetIndex = messages.value.findIndex(message => String(message?.id || '') === targetId)
+    const targetMessage = messages.value[targetIndex]
+    if (targetIndex === -1 || targetMessage?.role !== 'user' || !String(targetMessage?.content || '').trim()) {
+      return
+    }
+
+    prepareRequest()
+
+    messages.value = messages.value.slice(0, targetIndex + 1)
+    const liveAssistantMessage = appendAssistantPlaceholder()
+
+    await requestAssistantResponse(liveAssistantMessage)
+  }
+
   return {
     config: assistantConfig,
     messages,
@@ -257,6 +287,7 @@ export default function useAssistant ({ route, locale, getContext } = {}) {
     error,
     hasMessages,
     send,
+    retryFromUserMessage,
     stop,
     clear
   }

package/src/css/app.sass

@@ -84,6 +84,20 @@ body.body--dark
         color: #B19248
     section
       color: var(--q-light-in-dark-2)
+    // VS comparison marks (dark)
+    .vs-mark--yes
+      color: #3fb950
+    .vs-mark--no
+      color: #ff7b72
+    .vs-mark--dep
+      color: #d29922
+    // VS comparison: highlight the configured column (dark)
+    .d-table-wrapper--vs
+      th:nth-child(2),
+      td:nth-child(2)
+        background: rgba(193, 166, 103, 0.12)
+        border-left-color: rgba(193, 166, 103, 0.45)
+        border-right-color: rgba(193, 166, 103, 0.45)
     // token
     code:not(pre > code)
       color: var(--q-primary-in-dark-bg) !important
@@ -102,7 +116,8 @@ body.body--dark
         border-bottom: 1px dotted #1b4a6c
 
     &.overview,
-    &.showcase
+    &.showcase,
+    &.vs
       blockquote
         border-left-color: #3d444d
         background-color: #161b22 !important
@@ -157,6 +172,25 @@ body.body--dark
   --big-play-button-background: #000 !important
   --big-play-button-background-dark: #000 !important
 
+  // VS comparison marks
+  .vs-mark
+    font-weight: 700
+  .vs-mark--yes
+    color: #1a7f37
+  .vs-mark--no
+    color: #cf222e
+  .vs-mark--dep
+    color: #9a6700
+
+  // VS comparison: highlight the configured column
+  .d-table-wrapper--vs
+    th:nth-child(2),
+    td:nth-child(2)
+      background: rgba(105, 86, 43, 0.07)
+      font-weight: 600
+      border-left: 2px solid rgba(105, 86, 43, 0.35)
+      border-right: 2px solid rgba(105, 86, 43, 0.35)
+
   h1, h2, h3, h4, h5, h6
     font-weight: 600
     padding: 6px
@@ -281,7 +315,8 @@ body.body--dark
       transition: all 0.3s ease
 
   &.overview,
-  &.showcase
+  &.showcase,
+  &.vs
     blockquote
       margin: 1.5em 0
       padding: 0.85em 1.1em

package/src/i18n/helpers.js

@@ -84,6 +84,11 @@ const engineDefaults = {
       sources: 'Sources',
       sourcesCount: '{count} sources',
       copyMessage: 'Copy message',
+      retryMessage: 'Reload message',
+      retryHistoryTitle: 'Reload from this message?',
+      retryHistoryMessage: 'Messages after this question will be removed from the conversation.',
+      retryHistoryConfirm: 'Reload',
+      retryHistoryCancel: 'Cancel',
       copied: 'Message copied',
       loadEarlier: 'Load earlier messages',
       thinking: 'Searching the docs…',
@@ -157,6 +162,11 @@ const engineDefaults = {
       sources: 'Fontes',
       sourcesCount: '{count} fontes',
       copyMessage: 'Copiar mensagem',
+      retryMessage: 'Reenviar mensagem',
+      retryHistoryTitle: 'Reenviar desta mensagem?',
+      retryHistoryMessage: 'As mensagens depois desta pergunta serão removidas da conversa.',
+      retryHistoryConfirm: 'Reenviar',
+      retryHistoryCancel: 'Cancelar',
       copied: 'Mensagem copiada',
       loadEarlier: 'Carregar mensagens anteriores',
       thinking: 'Consultando a documentação…',
@@ -438,11 +448,11 @@ export function buildMessages ({ langModules, mdModules, pages, books, pageEntri
       // Overview
       _.overview.source = load(topPage, path, 'overview', lang, sourceRoot)
       // showcase
-      if (config.subpages?.showcase === true) {
+      if (config.subpages?.showcase) {
         _.showcase.source = load(topPage, path, 'showcase', lang, sourceRoot)
       }
       // Vs
-      if (config.subpages?.vs === true) {
+      if (config.subpages?.vs) {
         _.vs.source = load(topPage, path, 'vs', lang, sourceRoot)
       }
     }

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

@@ -119,6 +119,11 @@
     sources: 'Sources',
     sourcesCount: '{count} sources',
     copyMessage: 'Copy message',
+    retryMessage: 'Reload message',
+    retryHistoryTitle: 'Reload from this message?',
+    retryHistoryMessage: 'Messages after this question will be removed from the conversation.',
+    retryHistoryConfirm: 'Reload',
+    retryHistoryCancel: 'Cancel',
     copied: 'Message copied',
     loadEarlier: 'Load earlier messages',
     thinking: 'Searching the docs…',

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

@@ -118,6 +118,11 @@
     sources: 'Fontes',
     sourcesCount: '{count} fontes',
     copyMessage: 'Copiar mensagem',
+    retryMessage: 'Reenviar mensagem',
+    retryHistoryTitle: 'Reenviar desta mensagem?',
+    retryHistoryMessage: 'As mensagens depois desta pergunta serão removidas da conversa.',
+    retryHistoryConfirm: 'Reenviar',
+    retryHistoryCancel: 'Cancelar',
     copied: 'Mensagem copiada',
     loadEarlier: 'Carregar mensagens anteriores',
     thinking: 'Consultando a documentação…',

package/src/page-template.js

@@ -0,0 +1,118 @@
+export const PAGE_TEMPLATE_FREESTYLE = 'freestyle'
+export const PAGE_TEMPLATE_VS = 'vs'
+
+/**
+ * Subpage template presets.
+ *
+ * A template defines the fixed structure a subpage must follow. `freestyle`
+ * (the default) imposes no structure — the markdown renders exactly as written.
+ * Structured templates declare an ordered `sections` list; the renderer slots
+ * the markdown bodies into that fixed structure (canonical order, template-owned
+ * localized titles, graceful omission of absent sections).
+ */
+const PAGE_TEMPLATE_PRESETS = Object.freeze({
+  [PAGE_TEMPLATE_FREESTYLE]: Object.freeze({
+    name: PAGE_TEMPLATE_FREESTYLE,
+    sections: null
+  }),
+  [PAGE_TEMPLATE_VS]: Object.freeze({
+    name: PAGE_TEMPLATE_VS,
+    sections: Object.freeze([
+      Object.freeze({
+        key: 'features',
+        icon: 'checklist',
+        title: Object.freeze({ 'en-US': 'Features', 'pt-BR': 'Recursos' })
+      }),
+      Object.freeze({
+        key: 'performance',
+        icon: 'speed',
+        title: Object.freeze({ 'en-US': 'Performance', 'pt-BR': 'Desempenho' })
+      }),
+      Object.freeze({
+        key: 'security',
+        icon: 'security',
+        title: Object.freeze({ 'en-US': 'Security', 'pt-BR': 'Segurança' })
+      })
+    ])
+  })
+})
+
+const normalizeTemplateName = (value) => {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_-]+/g, '-')
+
+  if (normalized && Object.prototype.hasOwnProperty.call(PAGE_TEMPLATE_PRESETS, normalized)) {
+    return normalized
+  }
+
+  return PAGE_TEMPLATE_FREESTYLE
+}
+
+const firstDefined = (source, keys) => {
+  for (const key of keys) {
+    if (source?.[key] !== undefined) {
+      return source[key]
+    }
+  }
+
+  return undefined
+}
+
+const toTemplateName = (source) => {
+  if (source === undefined || source === null) {
+    return undefined
+  }
+
+  if (typeof source === 'boolean') {
+    return source ? PAGE_TEMPLATE_FREESTYLE : undefined
+  }
+
+  if (typeof source === 'string') {
+    return normalizeTemplateName(source)
+  }
+
+  if (typeof source === 'object' && !Array.isArray(source)) {
+    const name = firstDefined(source, ['template', 'name', 'type', 'preset'])
+    return name === undefined ? undefined : normalizeTemplateName(name)
+  }
+
+  return undefined
+}
+
+/**
+ * Whether a subpage config value enables that subpage.
+ *
+ * Accepts the boolean shorthand (`true`) or the object form (`{ template }`).
+ */
+export function isSubpageEnabled (value) {
+  return value === true || (typeof value === 'object' && value !== null && !Array.isArray(value))
+}
+
+/**
+ * Resolve a subpage template from one or more config sources.
+ *
+ * Sources may be a template name string, the subpage config value
+ * (`true` | `{ template }`), or undefined. Later sources win; the default is
+ * `freestyle`. Returns the resolved template preset object.
+ */
+export function resolveSubpageTemplate (...sources) {
+  let name = PAGE_TEMPLATE_FREESTYLE
+
+  for (const source of sources) {
+    const resolved = toTemplateName(source)
+    if (resolved !== undefined) {
+      name = resolved
+    }
+  }
+
+  return PAGE_TEMPLATE_PRESETS[name] || PAGE_TEMPLATE_PRESETS[PAGE_TEMPLATE_FREESTYLE]
+}
+
+/**
+ * Get a template preset object by name, falling back to `freestyle`.
+ */
+export function getTemplate (name) {
+  return PAGE_TEMPLATE_PRESETS[normalizeTemplateName(name)] || PAGE_TEMPLATE_PRESETS[PAGE_TEMPLATE_FREESTYLE]
+}

package/src/pages/manual/content/structures/subpage.overview.en-US.md

@@ -8,6 +8,43 @@ Under the hood, routed documentation uses `DSubpage` for this composition.
 
 The implementation generates a deterministic numeric ID from the current route path using a hash function. This ID is passed to `DPageSection` to keep per-page renderer indexes stable across page navigations.
 
+## Subpage templates
+
+Subpages render free-form Markdown by default (the `freestyle` template). A subpage can instead opt into a **structured template** that owns a fixed set of sections, declared per subpage in the page registry:
+
+```javascript
+// src/pages/manual.index.js
+'/WPI/HTTP/HTTP_Server_CLI': {
+  config: {
+    subpages: {
+      vs: { template: 'vs' }   // enable the `vs` subpage with the `vs` template
+    }
+  }
+}
+```
+
+The boolean shorthand (`showcase: true`) still means "enabled, freestyle". The object form `&#123; template: '<name>' &#125;` selects a template.
+
+### Built-in templates
+
+| Template | Structure |
+|---|---|
+| `freestyle` (default) | No fixed structure — Markdown renders as written |
+| `vs` | Fixed comparison sections: Features, Performance, Security |
+
+### Managed (strict) rendering
+
+Structured templates are **managed**: the template owns the section titles, icons and order. In the Markdown you write one `##` heading per section (its slug must match a section key — or one of its localized titles); the renderer then:
+
+- renders sections in the template's canonical order,
+- replaces each heading with the template's localized title,
+- gracefully omits sections you do not include (so a page with partial data just leaves them out),
+- warns in the dev console about unknown headings and appends them after the canonical sections.
+
+Every `vs` subpage therefore shares the same structure. Templates are resolved by `resolveSubpageTemplate()` (`src/page-template.js`) and applied by `applyTemplateSections()` (`src/components/page-template-sections.js`).
+
+Inside comparison tables the engine colorizes the marks `✓` / `✗` / `➕` and highlights the column whose header matches your project's `branding.name`. The engine stays product-agnostic — the highlighted column is configured by the consumer (via `branding.name` in `docsector.config.js`), not hardcoded.
+
 ## Template
 
 ```html
@@ -16,7 +53,7 @@ The implementation generates a deterministic numeric ID from the current route p
     <d-h1 :id="0" />
   </header>
   <main>
-    <d-page-section :id="id" />
+    <d-page-section :id="id" :template="template" />
   </main>
 </d-page>
 ```

package/src/pages/manual/content/structures/subpage.overview.pt-BR.md

@@ -8,6 +8,43 @@ Na implementação, a documentação roteada usa `DSubpage` para essa composiç
 
 A implementação gera um ID numérico determinístico a partir do caminho da rota atual usando uma função hash. Esse ID é passado ao `DPageSection` para manter estáveis os índices internos do renderer em cada página.
 
+## Templates de subpágina
+
+As subpáginas renderizam Markdown livre por padrão (o template `freestyle`). Uma subpágina pode, em vez disso, optar por um **template estruturado** que controla um conjunto fixo de seções, declarado por subpágina no registro de páginas:
+
+```javascript
+// src/pages/manual.index.js
+'/WPI/HTTP/HTTP_Server_CLI': {
+  config: {
+    subpages: {
+      vs: { template: 'vs' }   // habilita a subpágina `vs` com o template `vs`
+    }
+  }
+}
+```
+
+O atalho booleano (`showcase: true`) continua significando "habilitada, freestyle". A forma de objeto `&#123; template: '<nome>' &#125;` seleciona um template.
+
+### Templates nativos
+
+| Template | Estrutura |
+|---|---|
+| `freestyle` (padrão) | Sem estrutura fixa — o Markdown renderiza como foi escrito |
+| `vs` | Seções de comparação fixas: Recursos, Desempenho, Segurança |
+
+### Renderização gerenciada (estrita)
+
+Templates estruturados são **gerenciados**: o template controla os títulos, ícones e a ordem das seções. No Markdown você escreve um heading `##` por seção (cujo slug deve corresponder à chave da seção — ou a um de seus títulos localizados); o renderer então:
+
+- renderiza as seções na ordem canônica do template,
+- substitui cada heading pelo título localizado do template,
+- omite com elegância as seções que você não inclui (uma página com dados parciais simplesmente as deixa de fora),
+- avisa no console de dev sobre headings desconhecidos e os anexa após as seções canônicas.
+
+Toda subpágina `vs` compartilha, portanto, a mesma estrutura. Os templates são resolvidos por `resolveSubpageTemplate()` (`src/page-template.js`) e aplicados por `applyTemplateSections()` (`src/components/page-template-sections.js`).
+
+Dentro das tabelas de comparação o engine coloriza as marcas `✓` / `✗` / `➕` e destaca a coluna cujo header corresponde ao `branding.name` do seu projeto. O engine permanece agnóstico ao produto — a coluna destacada é configurada pelo consumidor (via `branding.name` no `docsector.config.js`), não fica hardcoded.
+
 ## Template
 
 ```html
@@ -16,7 +53,7 @@ A implementação gera um ID numérico determinístico a partir do caminho da ro
     <d-h1 :id="0" />
   </header>
   <main>
-    <d-page-section :id="id" />
+    <d-page-section :id="id" :template="template" />
   </main>
 </d-page>
 ```

package/src/router/routes.js

@@ -2,6 +2,7 @@ import { pageEntries, versions } from 'virtual:docsector-books'
 import boot from 'pages/boot'
 import docsectorConfig from 'docsector.config.js'
 import { resolveHomePageLayout, resolvePageLayout } from '../page-layout'
+import { isSubpageEnabled, resolveSubpageTemplate } from '../page-template'
 
 const normalizeInternalLink = (linkTo) => {
   const normalized = String(linkTo || '').trim()
@@ -85,8 +86,13 @@ for (const entry of pageEntries || []) {
   const config = rawConfig || {}
   const menu = (typeof config.menu === 'object' && config.menu !== null) ? config.menu : {}
   const subpages = {
-    showcase: config?.subpages?.showcase === true,
-    vs: config?.subpages?.vs === true
+    showcase: isSubpageEnabled(config?.subpages?.showcase),
+    vs: isSubpageEnabled(config?.subpages?.vs)
+  }
+  const subpageTemplates = {
+    overview: resolveSubpageTemplate(config?.subpages?.overview).name,
+    showcase: resolveSubpageTemplate(config?.subpages?.showcase).name,
+    vs: resolveSubpageTemplate(config?.subpages?.vs).name
   }
 
   const topPage = config.book ?? config.type ?? entry?.book ?? 'manual'
@@ -159,6 +165,7 @@ for (const entry of pageEntries || []) {
       pageVersion,
       menu,
       subpages,
+      subpageTemplates,
       data: page.data,
       book: topPage,
       // legacy compatibility