@docsector/docsector-reader 3.6.0 → 4.0.1

package/src/components/DSubpage.vue

@@ -1,13 +1,17 @@
 <script setup>
 import { computed } from 'vue'
 import { useRoute } from 'vue-router'
+import { useStore } from 'vuex'
+import { homePageSourceMode } from 'virtual:docsector-homepage-override'
 // components
 import DPage from "./DPage.vue";
 import DPageBar from "./DPageBar.vue";
 import DH1 from "./DH1.vue";
 import DPageSection from "./DPageSection.vue";
+import { usesRemoteReadmeHomeContent } from '../home-page-mode'
 
 const route = useRoute()
+const store = useStore()
 
 const id = computed(() => {
   const path = route.path
@@ -19,6 +23,13 @@ const id = computed(() => {
 
   return hash >>> 0
 })
+
+const usesRemoteReadmeHome = computed(() => {
+  return usesRemoteReadmeHomeContent({
+    pageBase: store.state.page.base,
+    homePageSourceMode
+  })
+})
 </script>
 
 <template>
@@ -26,11 +37,12 @@ const id = computed(() => {
   <header>
     <d-page-bar />
     <hr />
-    <d-h1 :id="0" />
+    <d-h1 v-if="!usesRemoteReadmeHome" :id="0" />
+    <span v-else id="0" aria-hidden="true"></span>
   </header>
 
   <main>
-    <d-page-section :id="id" />
+    <d-page-section :id="id" :render-primary-heading="usesRemoteReadmeHome" />
   </main>
 </d-page>
 </template>

package/src/components/page-section-tokens.js

@@ -15,6 +15,8 @@ const ALERT_MESSAGE_TYPES = new Set([
 
 const CARDS_MARKER_PREFIX = '@@DOCSECTOR_CARDS_'
 const QUICK_LINKS_MARKER_PREFIX = '@@DOCSECTOR_QUICK_LINKS_'
+const TIMELINE_MARKER_PREFIX = '@@DOCSECTOR_TIMELINE_'
+const STEPPER_MARKER_PREFIX = '@@DOCSECTOR_STEPPER_'
 const EXPANDABLE_MARKER_PREFIX = '@@DOCSECTOR_EXPANDABLE_'
 const FILE_MARKER_PREFIX = '@@DOCSECTOR_FILE_'
 const EMBEDDED_URL_MARKER_PREFIX = '@@DOCSECTOR_EMBEDDED_URL_'
@@ -147,11 +149,11 @@ const extractQuickLinksBlocks = (source = '') => {
   const map = new Map()
   let index = 0
 
-  const blockPattern = /<d-quick-links\b([^>]*)>([\s\S]*?)<\/d-quick-links>/gi
+  const blockPattern = /<d-block-quick-links\b([^>]*)>([\s\S]*?)<\/d-block-quick-links>/gi
   const replaced = String(source).replace(blockPattern, (_, blockAttrsRaw, inner) => {
     const blockAttrs = parseCustomTagAttributes(blockAttrsRaw)
     const items = []
-    const itemPattern = /<d-quick-link\b([^>]*)\/?\s*>/gi
+    const itemPattern = /<d-block-quick-link\b([^>]*)\/?\s*>/gi
 
     let itemMatch = itemPattern.exec(inner)
     while (itemMatch !== null) {
@@ -195,11 +197,11 @@ const extractCardsBlocks = (source = '') => {
   const map = new Map()
   let index = 0
 
-  const blockPattern = /<d-(?:block-)?cards\b([^>]*)>([\s\S]*?)<\/d-(?:block-)?cards>/gi
+  const blockPattern = /<d-block-cards\b([^>]*)>([\s\S]*?)<\/d-block-cards>/gi
   const replaced = String(source).replace(blockPattern, (_, blockAttrsRaw, inner) => {
     const blockAttrs = parseCustomTagAttributes(blockAttrsRaw)
     const items = []
-    const itemPattern = /<d-(?:block-)?card\b([^>]*)\/?\s*>/gi
+    const itemPattern = /<d-block-card\b([^>]*)\/?\s*>/gi
 
     let itemMatch = itemPattern.exec(inner)
     while (itemMatch !== null) {
@@ -244,11 +246,166 @@ const parseExpandableOpenState = (raw = '') => {
   return ['1', 'true', 'yes', 'on'].includes(String(raw).trim().toLowerCase())
 }
 
+const parseTimelineTags = (raw = '') => {
+  return decodeHtmlEntities(raw)
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean)
+    .map((label) => ({
+      label,
+      color: '',
+      textColor: '',
+      icon: ''
+    }))
+}
+
+const parseTimelineTagLabel = (raw = '') => {
+  return decodeHtmlEntities(String(raw).replace(/<[^>]+>/g, ' '))
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+const createTimelineTag = (rawAttrs = '', rawLabel = '') => {
+  const attrs = parseCustomTagAttributes(rawAttrs)
+  const label = parseTimelineTagLabel(attrs.label || rawLabel)
+
+  if (label === '') {
+    return null
+  }
+
+  return {
+    label,
+    color: decodeHtmlEntities(attrs.color || '').trim(),
+    textColor: decodeHtmlEntities(attrs['text-color'] || attrs.textColor || '').trim(),
+    icon: decodeHtmlEntities(attrs.icon || '').trim()
+  }
+}
+
+const extractTimelineItemTags = (source = '') => {
+  const tags = []
+
+  const replaceBlock = (match, rawAttrs, rawLabel = '') => {
+    const tag = createTimelineTag(rawAttrs, rawLabel)
+
+    if (tag !== null) {
+      tags.push(tag)
+      return '\n'
+    }
+
+    return match
+  }
+
+  const replaced = String(source).replace(
+    /<d-block-timeline-tag\b([^>]*?)(?:\/\s*>|>([\s\S]*?)<\/d-block-timeline-tag>)/gi,
+    replaceBlock
+  )
+
+  return {
+    content: replaced,
+    tags
+  }
+}
+
+const extractTimelineBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const blockPattern = /<d-block-timeline\b([^>]*)>([\s\S]*?)<\/d-block-timeline>/gi
+  const replaced = String(source).replace(blockPattern, (match, _rawAttrs, inner) => {
+    const items = []
+    const itemPattern = /<d-block-timeline-item\b([^>]*)>([\s\S]*?)<\/d-block-timeline-item>/gi
+
+    let itemMatch = itemPattern.exec(inner)
+    while (itemMatch !== null) {
+      const attrs = parseCustomTagAttributes(itemMatch[1])
+      const date = decodeHtmlEntities(attrs.date || '').trim()
+      const { content: itemContent, tags } = extractTimelineItemTags(itemMatch[2])
+
+      if (date) {
+        items.push({
+          date,
+          tags: [...parseTimelineTags(attrs.tags || ''), ...tags],
+          anchor: decodeHtmlEntities(attrs.anchor || attrs.id || '').trim(),
+          content: itemContent
+        })
+      }
+
+      itemMatch = itemPattern.exec(inner)
+    }
+
+    if (items.length === 0) {
+      return match
+    }
+
+    const marker = `${TIMELINE_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      items
+    })
+
+    return `\n${marker}\n`
+  })
+
+  return {
+    source: replaced,
+    timelineMap: map
+  }
+}
+
+const extractStepperBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const blockPattern = /<d-block-stepper\b([^>]*)>([\s\S]*?)<\/d-block-stepper>/gi
+  const replaced = String(source).replace(blockPattern, (match, _rawAttrs, inner) => {
+    const steps = []
+    const stepPattern = /<d-block-step\b([^>]*)>([\s\S]*?)<\/d-block-step>/gi
+
+    let stepMatch = stepPattern.exec(inner)
+    while (stepMatch !== null) {
+      const attrs = parseCustomTagAttributes(stepMatch[1])
+      const title = attrs.title || ''
+
+      if (title) {
+        steps.push({
+          title,
+          icon: attrs.icon || '',
+          activeIcon: attrs['active-icon'] || '',
+          doneIcon: attrs['done-icon'] || '',
+          errorIcon: attrs['error-icon'] || '',
+          content: stepMatch[2]
+        })
+      }
+
+      stepMatch = stepPattern.exec(inner)
+    }
+
+    if (steps.length === 0) {
+      return match
+    }
+
+    const marker = `${STEPPER_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      steps
+    })
+
+    return `\n${marker}\n`
+  })
+
+  return {
+    source: replaced,
+    stepperMap: map
+  }
+}
+
 const extractExpandableBlocks = (source = '') => {
   const map = new Map()
   let index = 0
 
-  const blockPattern = /<d-expandable\b([^>]*)>([\s\S]*?)<\/d-expandable>/gi
+  const blockPattern = /<d-block-expandable\b([^>]*)>([\s\S]*?)<\/d-block-expandable>/gi
   const replaced = String(source).replace(blockPattern, (_, rawAttrs, inner) => {
     const attrs = parseCustomTagAttributes(rawAttrs)
     const marker = `${EXPANDABLE_MARKER_PREFIX}${index}@@`
@@ -314,10 +471,10 @@ const extractFileBlocks = (source = '') => {
     return `\n${marker}\n`
   }
 
-  const replacedSelfClosing = String(source).replace(/<d-file\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+  const replacedSelfClosing = String(source).replace(/<d-block-file\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
     return replaceBlock(match, rawAttrs)
   })
-  const replaced = replacedSelfClosing.replace(/<d-file\b([^>]*)>([\s\S]*?)<\/d-file>/gi, replaceBlock)
+  const replaced = replacedSelfClosing.replace(/<d-block-file\b([^>]*)>([\s\S]*?)<\/d-block-file>/gi, replaceBlock)
 
   return {
     source: replaced,
@@ -349,10 +506,10 @@ const extractEmbeddedUrlBlocks = (source = '') => {
     return `\n${marker}\n`
   }
 
-  const replacedSelfClosing = String(source).replace(/<d-embedded-url\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+  const replacedSelfClosing = String(source).replace(/<d-block-embedded-url\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
     return replaceBlock(match, rawAttrs)
   })
-  const replaced = replacedSelfClosing.replace(/<d-embedded-url\b([^>]*)>([\s\S]*?)<\/d-embedded-url>/gi, replaceBlock)
+  const replaced = replacedSelfClosing.replace(/<d-block-embedded-url\b([^>]*)>([\s\S]*?)<\/d-block-embedded-url>/gi, replaceBlock)
 
   return {
     source: replaced,
@@ -403,6 +560,12 @@ const escapeHtml = (value = '') => {
     .replace(/'/g, '&#39;')
 }
 
+const stripHtmlTags = (value = '') => {
+  return decodeHtmlEntities(String(value).replace(/<[^>]+>/g, ' '))
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
 const extractTagAttributes = (html = '', tagName = '') => {
   const match = String(html).match(new RegExp(`<${tagName}\\b([^>]*)\\/?>(?![\\s\\S]*<${tagName}\\b)`, 'i'))
 
@@ -635,6 +798,35 @@ const getHeadingAnchorId = (markdown, currentTag, element, env, parserState) =>
   return parserState.headingSlugger.slug(headingText)
 }
 
+const getTimelineItemTitle = (tokens = []) => {
+  for (const token of tokens) {
+    if (typeof token?.content !== 'string') {
+      continue
+    }
+
+    const text = stripHtmlTags(token.content)
+    if (text !== '') {
+      return text
+    }
+  }
+
+  return ''
+}
+
+const getTimelineItemAnchorId = ({ item, itemTokens, itemIndex, parserState }) => {
+  const explicitAnchor = decodeHtmlEntities(item.anchor || '').trim()
+
+  if (explicitAnchor !== '') {
+    return parserState.headingSlugger.slug(explicitAnchor)
+  }
+
+  const title = getTimelineItemTitle(itemTokens)
+  const fallbackTitle = title || `item-${itemIndex + 1}`
+  const seed = [item.date, fallbackTitle].filter(Boolean).join(' ')
+
+  return parserState.headingSlugger.slug(seed)
+}
+
 export const tokenizePageSectionSource = (source = '', options = {}) => {
   const {
     allowHeadingTokens = true,
@@ -642,7 +834,31 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
   } = options
   const normalizedSource = normalizePageSectionSource(source)
   const { source: sourceWithShieldedCode, codeSegmentsMap } = shieldMarkdownCodeSegments(normalizedSource)
-  const { source: sourceWithExpandables, expandableMap } = extractExpandableBlocks(sourceWithShieldedCode)
+  const { source: sourceWithTimelines, timelineMap } = extractTimelineBlocks(sourceWithShieldedCode)
+
+  timelineMap.forEach((data, marker) => {
+    timelineMap.set(marker, {
+      ...data,
+      items: data.items.map((item) => ({
+        ...item,
+        content: restoreShieldedCodeSegments(item.content, codeSegmentsMap)
+      }))
+    })
+  })
+
+  const { source: sourceWithSteppers, stepperMap } = extractStepperBlocks(sourceWithTimelines)
+
+  stepperMap.forEach((data, marker) => {
+    stepperMap.set(marker, {
+      ...data,
+      steps: data.steps.map((step) => ({
+        ...step,
+        content: restoreShieldedCodeSegments(step.content, codeSegmentsMap)
+      }))
+    })
+  })
+
+  const { source: sourceWithExpandables, expandableMap } = extractExpandableBlocks(sourceWithSteppers)
 
   expandableMap.forEach((data, marker) => {
     expandableMap.set(marker, {
@@ -815,6 +1031,53 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
         case 'inline': {
           const anchorId = getHeadingAnchorId(markdown, tag, element, markdownEnv, parserState)
 
+          if (timelineMap.has(element.content.trim())) {
+            const data = timelineMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'timeline',
+              items: data.items.map((item, itemIndex) => {
+                const itemTokens = tokenizePageSectionSource(item.content, {
+                  allowHeadingTokens: false,
+                  parserState
+                })
+
+                return {
+                  date: item.date,
+                  tags: item.tags,
+                  anchorId: getTimelineItemAnchorId({
+                    item,
+                    itemTokens,
+                    itemIndex,
+                    parserState
+                  }),
+                  tokens: itemTokens
+                }
+              })
+            })
+            break
+          }
+
+          if (stepperMap.has(element.content.trim())) {
+            const data = stepperMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'stepper',
+              steps: data.steps.map((step) => ({
+                title: step.title,
+                icon: step.icon,
+                activeIcon: step.activeIcon,
+                doneIcon: step.doneIcon,
+                errorIcon: step.errorIcon,
+                tokens: tokenizePageSectionSource(step.content, {
+                  allowHeadingTokens: false,
+                  parserState
+                })
+              }))
+            })
+            break
+          }
+
           if (expandableMap.has(element.content.trim())) {
             const data = expandableMap.get(element.content.trim())
 

package/src/composables/useActiveAnchor.js

@@ -0,0 +1,42 @@
+export const DEFAULT_ACTIVE_ANCHOR_OFFSET = 50
+
+const toFiniteNumber = (value) => {
+  const normalized = Number(value)
+  return Number.isFinite(normalized) ? normalized : 0
+}
+
+export function getActiveAnchorId({
+  anchors = [],
+  scrollTop = 0,
+  scrollOffset = DEFAULT_ACTIVE_ANCHOR_OFFSET,
+  rootAnchorId = 0,
+  getAnchorOffsetTop = () => undefined
+} = {}) {
+  const thresholdTop = Math.max(0, toFiniteNumber(scrollTop)) + Math.max(0, toFiniteNumber(scrollOffset))
+  let activeAnchorId = rootAnchorId
+  const seenAnchors = new Set()
+
+  for (const anchorId of Array.isArray(anchors) ? anchors : []) {
+    if (anchorId === null || anchorId === undefined || anchorId === false || anchorId === 0 || anchorId === '0') {
+      continue
+    }
+
+    if (seenAnchors.has(anchorId)) {
+      continue
+    }
+
+    seenAnchors.add(anchorId)
+
+    const resolvedOffsetTop = Number(getAnchorOffsetTop(anchorId))
+
+    if (!Number.isFinite(resolvedOffsetTop)) {
+      continue
+    }
+
+    if (thresholdTop >= resolvedOffsetTop) {
+      activeAnchorId = anchorId
+    }
+  }
+
+  return activeAnchorId
+}

package/src/composables/useNavigator.js

@@ -3,6 +3,8 @@ import { useStore } from 'vuex'
 import { useRouter, useRoute } from 'vue-router'
 import { ref } from 'vue'
 
+import { DEFAULT_ACTIVE_ANCHOR_OFFSET, getActiveAnchorId } from './useActiveAnchor'
+
 export default function useNavigator() {
   const store = useStore()
   const router = useRouter()
@@ -46,7 +48,10 @@ export default function useNavigator() {
   const select = (id) => {
     const normalized = normalizeStoreAnchorId(id)
 
-    store.commit('page/setAnchor', normalized)
+    if (store.state.page.anchor !== normalized) {
+      store.commit('page/setAnchor', normalized)
+    }
+
     store.commit('page/pushNodesExpanded', normalized)
   }
 
@@ -78,27 +83,29 @@ export default function useNavigator() {
       return
     }
 
-    const scrollPositionTop = scroll.position.top + 50
-    const anchors = store.state.page.anchors
+    const activeAnchorId = getActiveAnchorId({
+      anchors: store.state.page.anchors,
+      scrollTop: scroll?.position?.top,
+      scrollOffset: DEFAULT_ACTIVE_ANCHOR_OFFSET,
+      rootAnchorId: 0,
+      getAnchorOffsetTop: (anchorId) => {
+        const domAnchorId = normalizeDomAnchorId(anchorId)
 
-    for (let i = 0; i < anchors.length; i++) {
-      const anchorId = anchors[i]
-      const domAnchorId = normalizeDomAnchorId(anchorId)
+        if (domAnchorId === '') {
+          return undefined
+        }
 
-      if (domAnchorId === '0') {
-        continue
-      }
+        const Anchor = document.getElementById(domAnchorId)
 
-      const Anchor = document.getElementById(domAnchorId)
-      let AnchorOffsetTop = 20
-      if (Anchor !== null && typeof Anchor === 'object') {
-        AnchorOffsetTop = Anchor.offsetTop
-      }
+        if (Anchor !== null && typeof Anchor === 'object') {
+          return Anchor.offsetTop
+        }
 
-      if (scrollPositionTop >= AnchorOffsetTop) {
-        select(anchorId)
+        return undefined
       }
-    }
+    })
+
+    select(activeAnchorId)
   }
 
   const navigate = (value, toAnchor = true) => {

package/src/home-page-mode.js

@@ -0,0 +1,5 @@
+export const REMOTE_README_HOME_PAGE_MODE = 'remote-readme'
+
+export function usesRemoteReadmeHomeContent ({ pageBase = '', homePageSourceMode = 'local' } = {}) {
+  return pageBase === 'home' && homePageSourceMode === REMOTE_README_HOME_PAGE_MODE
+}

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

@@ -45,6 +45,11 @@
       download: 'Download',
       open: 'Open'
     },
+    stepper: {
+      continue: 'Continue',
+      back: 'Back',
+      finish: 'Finish'
+    },
     openInChatGPT: 'Open in ChatGPT',
     openInChatGPTCaption: 'Ask ChatGPT about this page',
     openInClaude: 'Open in Claude',

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

@@ -44,6 +44,11 @@
       download: 'Baixar',
       open: 'Abrir'
     },
+    stepper: {
+      continue: 'Continuar',
+      back: 'Voltar',
+      finish: 'Finalizar'
+    },
     openInChatGPT: 'Abrir no ChatGPT',
     openInChatGPTCaption: 'Pergunte ao ChatGPT sobre esta página',
     openInClaude: 'Abrir no Claude',

package/src/pages/guide/i18n-and-markdown.overview.en-US.md

@@ -118,14 +118,14 @@ echo "Example"
 
 ### Expandable Content
 
-Use `<d-expandable>` to hide secondary content without removing rich Markdown features from the page:
+Use `<d-block-expandable>` to hide secondary content without removing rich Markdown features from the page:
 
 ```markdown
-<d-expandable title="More details">
+<d-block-expandable title="More details">
 
 Optional explanations, operational notes, or longer examples.
 
-</d-expandable>
+</d-block-expandable>
 ```
 
 Set `open="true"` when the block should start expanded.
@@ -134,12 +134,12 @@ The expandable body supports paragraphs, lists, alerts, code blocks, Mermaid dia
 
 ### File Blocks
 
-Use `<d-file>` to publish downloadable attachments from repo-tracked files or external storage without leaving Markdown:
+Use `<d-block-file>` to publish downloadable attachments from repo-tracked files or external storage without leaving Markdown:
 
 ```html
-<d-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
+<d-block-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
 Download the example attachment used in this manual.
-</d-file>
+</d-block-file>
 ```
 
 Store repo-tracked files under `public/files/` and prefer absolute site paths such as `/files/...`.

package/src/pages/guide/i18n-and-markdown.overview.pt-BR.md

@@ -118,14 +118,14 @@ echo "Exemplo"
 
 ### Conteúdo Expansível
 
-Use `<d-expandable>` para esconder conteúdo secundário sem perder os recursos ricos de Markdown da página:
+Use `<d-block-expandable>` para esconder conteúdo secundário sem perder os recursos ricos de Markdown da página:
 
 ```markdown
-<d-expandable title="Mais detalhes">
+<d-block-expandable title="Mais detalhes">
 
 Explicações opcionais, notas operacionais ou exemplos maiores.
 
-</d-expandable>
+</d-block-expandable>
 ```
 
 Defina `open="true"` quando o bloco precisar começar aberto.
@@ -134,12 +134,12 @@ O corpo do expansível suporta parágrafos, listas, alertas, blocos de código,
 
 ### Blocos de Arquivo
 
-Use `<d-file>` para publicar anexos baixáveis a partir de arquivos versionados no repositório ou de storage externo sem sair do Markdown:
+Use `<d-block-file>` para publicar anexos baixáveis a partir de arquivos versionados no repositório ou de storage externo sem sair do Markdown:
 
 ```html
-<d-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
+<d-block-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
 Baixe o anexo de exemplo usado neste manual.
-</d-file>
+</d-block-file>
 ```
 
 Guarde arquivos versionados no repositório em `public/files/` e prefira caminhos absolutos do site, como `/files/...`.

package/src/pages/guide/theming.overview.en-US.md

@@ -48,7 +48,7 @@ Components use CSS custom properties for theme-aware styling:
 
 ## Customizing Code Block Colors
 
-The `DPageSourceCode` component has separate color schemes for light and dark modes, using Prism.js token classes. Override `token.*` classes in the `.source-code` SASS block to customize syntax highlighting colors.
+The `DBlockSourceCode` component has separate color schemes for light and dark modes, using Prism.js token classes. Override `token.*` classes in the `.source-code` SASS block to customize syntax highlighting colors.
 
 ## Font Families
 

package/src/pages/guide/theming.overview.pt-BR.md

@@ -48,7 +48,7 @@ Os componentes usam propriedades CSS customizadas para estilização consciente
 
 ## Customizando Cores dos Blocos de Código
 
-O componente `DPageSourceCode` tem esquemas de cores separados para modos claro e escuro, usando classes de token do Prism.js. Sobrescreva as classes `token.*` no bloco SASS `.source-code` para customizar as cores de syntax highlighting.
+O componente `DBlockSourceCode` tem esquemas de cores separados para modos claro e escuro, usando classes de token do Prism.js. Sobrescreva as classes `token.*` no bloco SASS `.source-code` para customizar as cores de syntax highlighting.
 
 ## Famílias de Fontes
 

package/src/pages/manual/basic/d-page-anchor.overview.en-US.md

@@ -39,7 +39,7 @@ The root node (from DH1) shows the page title from i18n when no label is set:
 
 ## Scroll Synchronization
 
-When the user scrolls the page content, the `DPage` scroll observer calls `useNavigator().scrolling()`, which iterates over registered anchors and selects the one closest to the current scroll position. This keeps the table of contents in sync with the visible content.
+When the user scrolls the page content, the `DPage` scroll observer calls `useNavigator().scrolling()`, which selects the last registered heading that crossed the content threshold. Missing or stale anchors are ignored so the table of contents stays in sync with the visible section instead of jumping ahead.
 
 ## Lifecycle
 

package/src/pages/manual/basic/d-page-anchor.overview.pt-BR.md

@@ -39,7 +39,7 @@ O nó raiz (do DH1) mostra o título da página do i18n quando nenhum label é d
 
 ## Sincronização de Scroll
 
-Quando o usuário faz scroll no conteúdo da página, o observador de scroll do `DPage` chama `useNavigator().scrolling()`, que itera sobre as âncoras registradas e seleciona a mais próxima da posição de scroll atual. Isso mantém o índice sincronizado com o conteúdo visível.
+Quando o usuário faz scroll no conteúdo da página, o observador de scroll do `DPage` chama `useNavigator().scrolling()`, que seleciona o último heading registrado que cruzou o limite superior da área de conteúdo. Âncoras ausentes ou obsoletas são ignoradas para manter o índice sincronizado com a seção realmente visível, sem saltar adiante.
 
 ## Ciclo de Vida