dsh-scrape 0.0.1 → 0.1.0

package/lib/html.mjs

@@ -0,0 +1,822 @@
+/**
+ * HTML 引擎：把一段 HTML 解析成「带源行号的结构化块」。
+ *
+ * 三条硬约束（决定了下面所有取舍）：
+ * 1) **零依赖**——不引 cheerio/parse5，自己写一个最小分词器（标签 + 文本 + 注释）；
+ * 2) **行号永不漂移**——每个块都记住它在原始 HTML 里的起止行，于是每条内容都能回指
+ *    「URL 第 N 行」；同时保留一份与源文件等长的 `textLines`（剥标签后的可见文本）；
+ * 3) **不执行 JS**——只读服务端返回的 HTML。客户端渲染的页面会被明确标成「疑似 SPA」，
+ *    而不是假装抓到了内容。
+ *
+ * 去噪在这一层做（按元素/属性判定，确定性、可解释），正文密度挑选取在 extract.mjs。
+ */
+
+import { decodeEntities } from './entities.mjs'
+
+/** 空元素（不产生子节点，也不进栈）。 */
+export const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta',
+  'param', 'source', 'track', 'wbr',
+])
+
+/** 结构性噪音元素 → 记到 removed 的哪个分类下（值 = 分类名）。 */
+export const NOISE_ELEMENTS = {
+  script: 'script',
+  style: 'style',
+  noscript: 'noscript',
+  template: 'template',
+  svg: 'svg',
+  canvas: 'canvas',
+  iframe: 'iframe',
+  object: 'iframe',
+  embed: 'iframe',
+  nav: 'nav',
+  footer: 'footer',
+  aside: 'aside',
+  form: 'form',
+  menu: 'nav',
+  dialog: 'dialog',
+  button: 'button',
+  select: 'form',
+  option: 'form',
+  textarea: 'form',
+  input: 'form',
+}
+
+/**
+ * 属性/类名命中即整块丢弃的「界面噪音」。顺序即优先级。
+ * 这是 cookie 条、分享按钮、广告位、面包屑的主要识别方式——它们几乎都有可辨认的 class/id。
+ */
+export const NOISE_ATTR_RULES = [
+  { kind: 'consent', re: /(cookie[-_]?(consent|banner|notice|bar|policy|law)|consent[-_](banner|manager|sdk)|gdpr|onetrust|trustarc|cookiebot|osano|didomi|privacy[-_]?(banner|notice)|cmp[-_](banner|container)|cnil|接受.{0,6}cookie)/i },
+  { kind: 'share', re: /(share[-_]?(this|bar|buttons?|box|toolbar|icons?|links?)?|social[-_]?(share|links?|bar|icons?|buttons?)|addthis|sharethis|addtoany|weixin|weibo|twitter[-_]share|follow[-_]?us)/i },
+  { kind: 'comment', re: /(comment[-_]?(list|section|form|thread|area|box)?$|^comments?$|disqus|respond[-_]?form)/i },
+  { kind: 'ad', re: /(advert|adsense|ad[-_]?(slot|unit|banner|container|box)|sponsor|dfp[-_]|promo[-_]?(banner|box)|sponsored)/i },
+  { kind: 'nav', re: /(breadcrumb|pagination|^pager$|pager[-_]|navbar|nav[-_]?(bar|menu|list)?$|^nav$|site[-_]?nav|top[-_]?bar|sidebar|skip[-_]?link|site[-_]?header|masthead)/i },
+]
+
+/** 块级容器元素（可以承载正文，关闭时产出一个块）。 */
+const BLOCK_CONTAINERS = new Set([
+  'p', 'div', 'section', 'article', 'main', 'header', 'hgroup', 'address',
+  'dd', 'dt', 'figcaption', 'caption', 'details', 'summary', 'body', 'html', 'center',
+])
+
+/** 行内标记元素 → 输出时包什么。 */
+const INLINE_MARKS = {
+  a: null, strong: '**', b: '**', em: '*', i: '*', cite: '*', del: '~~', s: '~~',
+  strike: '~~', mark: null, sub: null, sup: null, small: null, u: null, abbr: null,
+  time: null, q: null, span: null, font: null, ins: null, bdi: null, bdo: null, var: null, dfn: null,
+}
+
+/** 标题元素 → 级别。 */
+const HEADINGS = { h1: 1, h2: 2, h3: 3, h4: 4, h5: 5, h6: 6 }
+
+/**
+ * 把 HTML 切成 token（标签 / 文本 / 注释），并给每个 token 记住所在行。
+ * @param {string} html 已归一换行的 HTML
+ * @returns {Array<object>} token 列表
+ */
+export function tokenizeHtml(html) {
+  const source = String(html ?? '')
+  // 注释、声明（<!doctype …> / <![CDATA[…]]>）、处理指令（<?xml …?>）都要跳过：
+  // 否则 `<!doctype html>` 会被当成正文文字，混进第一段
+  const re = /<!--[\s\S]*?-->|<![^>]*>|<\?[\s\S]*?\?>|<\/?[a-zA-Z][a-zA-Z0-9:_-]*(?:"[^"]*"|'[^']*'|[^>"'])*>/g
+  const tokens = []
+  let line = 1
+  let last = 0
+
+  const countNewlines = (text) => {
+    let count = 0
+    for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) count += 1
+    return count
+  }
+
+  const pushText = (from, to) => {
+    if (to <= from) return
+    // 按行切分文本 token：行号精确到行，`<pre>` 里的换行也不会被吃掉（后续行带前导 \n）
+    const segments = source.slice(from, to).split('\n')
+    for (let i = 0; i < segments.length; i++) {
+      const raw = i === 0 ? segments[i] : `\n${segments[i]}`
+      tokens.push({ type: 'text', raw, line: line + i, endLine: line + i })
+    }
+    line += segments.length - 1
+  }
+
+  for (const match of source.matchAll(re)) {
+    pushText(last, match.index)
+    const raw = match[0]
+    const newlines = countNewlines(raw)
+    if (raw.startsWith('<!--')) {
+      tokens.push({ type: 'comment', raw, line, endLine: line + newlines })
+    } else if (raw.startsWith('<!') || raw.startsWith('<?')) {
+      tokens.push({ type: 'decl', raw, line, endLine: line + newlines })
+    } else {
+      const closing = raw[1] === '/'
+      const nameMatch = /^<\/?\s*([a-zA-Z][a-zA-Z0-9:_-]*)/.exec(raw)
+      const name = nameMatch ? nameMatch[1].toLowerCase() : ''
+      tokens.push({
+        type: closing ? 'close' : 'open',
+        name,
+        raw,
+        attrs: closing ? {} : parseAttrs(raw),
+        line,
+        endLine: line + newlines,
+        selfClosing: /\/\s*>$/.test(raw) || VOID_ELEMENTS.has(name),
+      })
+    }
+    line += newlines
+    last = match.index + raw.length
+  }
+  pushText(last, source.length)
+  return tokens
+}
+
+/**
+ * 解析一个开标签的属性（支持双引号 / 单引号 / 无引号）。
+ * @param {string} raw 原始标签文本
+ * @returns {Record<string,string>} 属性表（键小写，值已解实体）
+ */
+export function parseAttrs(raw) {
+  const attrs = {}
+  let body = String(raw).replace(/^<\s*\/?\s*[a-zA-Z][a-zA-Z0-9:_-]*/, '')
+  body = body.replace(/\/?\s*>$/, '')
+  const re = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g
+  for (const match of body.matchAll(re)) {
+    const key = match[1].toLowerCase()
+    if (!key || key === '/') continue
+    if (key in attrs) continue
+    attrs[key] = decodeEntities(match[2] ?? match[3] ?? match[4] ?? '')
+  }
+  return attrs
+}
+
+/**
+ * 元素的「界面噪音分类」：先看标签，再看 class/id/role/aria-label。
+ * @param {string} name 元素名（小写）
+ * @param {Record<string,string>} attrs 属性
+ * @returns {string|null} 噪音分类，干净元素返回 null
+ */
+export function noiseKindOf(name, attrs) {
+  if (NOISE_ELEMENTS[name]) return NOISE_ELEMENTS[name]
+  const label = [attrs.class ?? '', attrs.id ?? '', attrs.role ?? '', attrs['aria-label'] ?? '', attrs['data-testid'] ?? ''].join(' ')
+  if (!label.trim()) return null
+  if (name === 'a' || name === 'span' || name === 'p') {
+    // 行内元素的 class 经常是 "share-link" 之类，但整段正文也可能叫 "share"；只认强特征
+    if (/(^|[\s_-])(share|social)([\s_-]|$)/i.test(label) && /(share|social)/i.test(label)) return 'share'
+    return null
+  }
+  for (const rule of NOISE_ATTR_RULES) {
+    if (rule.re.test(label)) return rule.kind
+  }
+  if (/^(navigation|menu|search)$/i.test(attrs.role ?? '')) return 'nav'
+  if (/^complementary$/i.test(attrs.role ?? '')) return 'aside'
+  return null
+}
+
+/**
+ * 把相对 URL 补成绝对 URL（补不了就原样返回）。
+ * @param {string} href 原始地址
+ * @param {string} baseUrl 页面最终地址
+ * @returns {string} 绝对地址
+ */
+export function resolveUrl(href, baseUrl) {
+  const value = String(href ?? '').trim()
+  if (!value || value.startsWith('#') || /^(?:mailto|tel|javascript|data):/i.test(value)) return value
+  if (!baseUrl) return value
+  try {
+    return new URL(value, baseUrl).toString()
+  } catch {
+    return value
+  }
+}
+
+/**
+ * SPA / 客户端渲染的信号（只读原始 HTML，不动 JS）。
+ * @param {string} html 原始 HTML
+ * @returns {object} 信号集合
+ */
+export function detectSpaSignals(html) {
+  const source = String(html ?? '')
+  return {
+    nextData: /__NEXT_DATA__/.test(source),
+    nuxt: /__NUXT__|window\.__NUXT__/.test(source),
+    initialState: /__INITIAL_STATE__|__APOLLO_STATE__|__PRELOADED_STATE__|__REDUX_STATE__/.test(source),
+    rootEmpty: /<(?:div|main)[^>]+id=["'](?:root|app|__next|svelte)["'][^>]*>\s*<\/(?:div|main)>/i.test(source),
+    noscriptJs: /<noscript>[\s\S]{0,400}?(?:enable|requires?|需要|请开启|请启用|disabled)[\s\S]{0,100}?javascript/i.test(source),
+    scriptCount: (source.match(/<script\b/gi) ?? []).length,
+    hasMain: /<(?:main|article)\b/i.test(source),
+    hasJsonLd: /application\/ld\+json/i.test(source),
+  }
+}
+
+/**
+ * 收拢空白（HTML 里连续空白等价于一个空格）。
+ * @param {string} text 文本
+ * @returns {string} 收拢后的文本
+ */
+export function collapseWhitespace(text) {
+  return String(text ?? '').replace(/[\s\u00a0\u200b]+/g, ' ')
+}
+
+/**
+ * 把行内片段渲染成 Markdown（链接 / 粗体 / 斜体 / 行内代码 / 删除线）。
+ * 只处理「配对的 open/close」，未闭合的按最内层收尾，绝不丢文字。
+ * @param {Array<object>} parts 片段序列
+ * @returns {string} Markdown 行内文本
+ */
+export function renderInline(parts) {
+  const root = { tag: null, out: [] }
+  const frames = [root]
+  const wrap = (frame, inner) => {
+    const text = inner
+    if (!text) return ''
+    if (frame.tag === 'a') {
+      const href = frame.href && !frame.href.startsWith('#') ? frame.href : ''
+      return href ? `[${text}](${href})` : text
+    }
+    if (frame.tag === 'code') return text.includes('`') ? `\`\` ${text} \`\`` : `\`${text}\``
+    if (frame.tag === 'mark' || frame.tag === 'strong' || frame.tag === 'b') {
+      return frame.tag === 'mark' ? text : `**${text}**`
+    }
+    if (frame.tag === 'em' || frame.tag === 'i' || frame.tag === 'cite' || frame.tag === 'q') return `*${text}*`
+    if (frame.tag === 'del' || frame.tag === 's' || frame.tag === 'strike') return `~~${text}~~`
+    return text
+  }
+
+  for (const part of parts) {
+    const frame = frames[frames.length - 1]
+    if (part.type === 'text') frame.out.push(part.value)
+    else if (part.type === 'open') frames.push({ tag: part.tag, href: part.href, out: [] })
+    else if (part.type === 'close') {
+      if (frames.length === 1) continue
+      const closed = frames.pop()
+      const inner = closed.out.join('').trim()
+      frames[frames.length - 1].out.push(wrap(closed, inner))
+    }
+  }
+  while (frames.length > 1) {
+    const closed = frames.pop()
+    const inner = closed.out.join('').trim()
+    frames[frames.length - 1].out.push(wrap(closed, inner))
+  }
+  return root.out.join('')
+}
+
+/**
+ * 解析 HTML 为「带行号的结构化块」。
+ * @param {string} html 原始 HTML
+ * @param {{baseUrl?:string,maxLinks?:number}} [options] 选项
+ * @returns {{title:string,blocks:Array<object>,textLines:string[],removed:object,links:Array<object>,signals:object,stats:object}} 解析结果
+ */
+export function parseHtml(html, options = {}) {
+  const baseUrl = options.baseUrl ?? ''
+  const maxLinks = options.maxLinks ?? 200
+  const normalized = String(html ?? '').replace(/\r\n?/g, '\n')
+  const rawLines = normalized.split('\n')
+  const tokens = tokenizeHtml(normalized)
+  const signals = detectSpaSignals(normalized)
+
+  const blocks = []
+  const textLines = new Array(rawLines.length).fill('')
+  const removed = { chars: {}, elements: {} }
+  const links = []
+  const stack = []
+  let titleFromTag = ''
+  let titleBuffer = ''
+  let inTitle = false
+  let blockSeq = 0
+  let loose = null
+  let headingFallback = ''
+  const stats = { tokens: tokens.length, elements: 0, noiseElements: 0, links: 0, headings: 0, tables: 0, lists: 0, codeBlocks: 0 }
+
+  /**
+   * 追加可见文本到行号对齐的 textLines。
+   * @param {string} raw 文本
+   * @param {number} line 起始行（1 基）
+   * @returns {void}
+   */
+  const appendVisible = (raw, line) => {
+    // 每个文本 token 的行号已经是「内容所在行」，前导 \n 只是行分隔符，不能算成多一行
+    const segments = String(raw).replace(/^\n/, '').split('\n')
+    for (let i = 0; i < segments.length; i++) {
+      const index = line - 1 + i
+      if (index >= textLines.length) textLines.push('')
+      textLines[index] += ` ${segments[i]}`
+    }
+  }
+
+  /**
+   * 取当前生效的噪音分类（继承祖先）。
+   * @returns {string|null} 噪音分类
+   */
+  const activeNoise = () => {
+    // 噪音标记会向下继承（拒噪分支里 push 的每个子元素都带 noise），所以看栈顶方向第一个带标记的即可
+    for (let i = stack.length - 1; i >= 0; i--) {
+      if (stack[i].noise) return stack[i].noise
+    }
+    return null
+  }
+
+  /**
+   * 取最内层可承载文字的容器。
+   * @returns {object} 容器
+   */
+  const innerContainer = () => {
+    for (let i = stack.length - 1; i >= 0; i--) {
+      if (stack[i].container) return stack[i].container
+    }
+    if (!loose) loose = { kind: 'paragraph', parts: [], firstSeq: blockSeq, line: 1, endLine: 1, depth: 0 }
+    return loose
+  }
+
+  /**
+   * 往容器里塞行内片段。
+   * @param {object} part 片段
+   * @returns {void}
+   */
+  const pushPart = (part) => {
+    const container = innerContainer()
+    if (container.firstSeq === null || container.firstSeq === undefined) container.firstSeq = blockSeq
+    container.parts.push(part)
+  }
+
+  /**
+   * 取最内层的行（表格）。
+   * @returns {object|null} 行上下文
+   */
+  const innermostRow = () => {
+    for (let i = stack.length - 1; i >= 0; i--) if (stack[i].row) return stack[i].row
+    return null
+  }
+
+  /**
+   * 取最内层的列表。
+   * @returns {object|null} 列表上下文
+   */
+  const innermostList = () => {
+    for (let i = stack.length - 1; i >= 0; i--) if (stack[i].list) return stack[i].list
+    return null
+  }
+
+  /**
+   * 造一条块记录。
+   * @param {object} block 块
+   * @returns {void}
+   */
+  const emit = (block) => {
+    const seq = block.seq ?? blockSeq
+    blocks.push({ seq, ...block })
+    blockSeq += 1
+  }
+
+  /**
+   * 收尾一个容器 → 产出块。
+   * @param {object} entry 栈条目
+   * @param {number} endLine 关闭行
+   * @returns {void}
+   */
+  const finalizeContainer = (entry, endLine) => {
+    const container = entry.container
+    if (!container) return
+    const text = container.kind === 'code' ? container.parts.map((p) => p.value ?? '').join('') : renderInline(container.parts)
+    const trimmed = container.kind === 'code' ? text.replace(/^\n+|\n+$/g, '') : text.trim()
+    if (!trimmed) return
+
+    // 单元格 / 列表项 / 引用里的内层块（<td><p>…</p></td>、<li><div>…</div></li>）不单独成块，
+    // 而是把文字吸收进外层容器——否则表格里会冒出游离段落，列表标记也会丢
+    // 只有「段落 / 标题 / 代码」这类内容块会被吸收；嵌套列表项与嵌套表格必须保持独立块
+    const absorbTarget = findAbsorbingContainer(stack)
+    const absorbable = container.kind === 'paragraph' || container.kind === 'heading' || container.kind === 'code'
+    if (absorbable && absorbTarget && absorbTarget !== container) {
+      if (absorbTarget.parts.length > 0) {
+        absorbTarget.parts.push({ type: 'text', value: absorbTarget.kind === 'quote' ? '\n' : ' ' })
+      }
+      absorbTarget.parts.push({ type: 'text', value: trimmed })
+      if (absorbTarget.firstSeq === null || absorbTarget.firstSeq === undefined) absorbTarget.firstSeq = container.firstSeq
+      return
+    }
+
+    if (container.kind === 'cell') {
+      const row = innermostRow()
+      if (row) {
+        row.cells.push(trimmed)
+        if (container.cellType === 'th') row.hasTh = true
+      }
+      return
+    }
+    if (container.kind === 'code') {
+      stats.codeBlocks += 1
+      emit({
+        kind: 'code', line: container.line, endLine, seq: container.firstSeq ?? blockSeq,
+        text: trimmed, lang: container.lang ?? '', inMain: entry.inMain,
+      })
+      return
+    }
+    if (container.kind === 'heading') {
+      stats.headings += 1
+      if (container.level === 1 && !headingFallback) headingFallback = stripInline(trimmed)
+      emit({
+        kind: 'heading', line: container.line, endLine, seq: container.firstSeq ?? blockSeq,
+        text: trimmed, level: container.level, inMain: entry.inMain, id: container.id ?? '',
+      })
+      return
+    }
+    if (container.kind === 'listItem') {
+      emit({
+        kind: 'listItem', line: container.line, endLine, seq: container.firstSeq ?? blockSeq,
+        text: trimmed, ordered: container.ordered, index: container.index, depth: container.depth,
+        inMain: entry.inMain,
+      })
+      return
+    }
+    if (container.kind === 'quote') {
+      emit({
+        kind: 'quote', line: container.line, endLine, seq: container.firstSeq ?? blockSeq,
+        text: trimmed, inMain: entry.inMain,
+      })
+      return
+    }
+    emit({
+      kind: 'paragraph', line: container.line, endLine, seq: container.firstSeq ?? blockSeq,
+      text: trimmed, inMain: entry.inMain,
+    })
+  }
+
+  /**
+   * 收尾一个开标签对应的所有副作用。
+   * @param {object} entry 栈条目
+   * @param {number} endLine 关闭行（1 基）
+   * @returns {void}
+   */
+  const finalizeEntry = (entry, endLine) => {
+    if (entry.name === 'title') {
+      inTitle = false
+      const text = collapseWhitespace(titleBuffer).trim()
+      if (text && !titleFromTag) titleFromTag = text.slice(0, 300)
+      return
+    }
+    if (entry.container) {
+      entry.container.line = entry.container.line ?? entry.line
+      finalizeContainer(entry, endLine)
+      entry.container = null
+    }
+    if (entry.table) {
+      const rows = entry.table.rows.filter((row) => row.cells.length > 0)
+      if (rows.length > 0) {
+        // Markdown 表格必须有表头行：有 <th> 就用首行当表头；没有就把首行提上来（并标注 headerIsTh:false）
+        const headerIsTh = rows.length > 1 && rows[0].hasTh
+        stats.tables += 1
+        emit({
+          kind: 'table', line: entry.line, endLine, seq: entry.seq,
+          header: rows[0].cells, rows: rows.slice(1).map((row) => row.cells), headerIsTh, inMain: entry.inMain,
+        })
+      }
+      entry.table = null
+    }
+    if (entry.list) entry.list = null
+  }
+
+  for (let tokenIndex = 0; tokenIndex < tokens.length; tokenIndex++) {
+    const token = tokens[tokenIndex]
+    blockSeq = tokenIndex
+
+    if (token.type === 'text') {
+      const noise = activeNoise()
+      if (noise) {
+        const chars = collapseWhitespace(token.raw).trim().length
+        if (chars > 0) {
+          removed.chars[noise] = (removed.chars[noise] ?? 0) + chars
+        }
+        continue
+      }
+      if (inTitle) { titleBuffer += decodeEntities(token.raw); continue }
+      const decoded = decodeEntities(token.raw)
+      appendVisible(decoded, token.line)
+      const container = innerContainer()
+      const isCode = container.kind === 'code'
+      const value = isCode ? decoded : collapseWhitespace(decoded)
+      if (!value.trim()) {
+        // 空白 token 不能一律丢：行内元素之间靠它隔开，`<pre>` 里的空行靠它保留
+        if (isCode) {
+          if (value) container.parts.push({ type: 'text', value })
+        } else if (value.length > 0 && container.parts.length > 0) {
+          container.parts.push({ type: 'text', value: ' ' })
+        }
+        continue
+      }
+      if (container.firstSeq === null || container.firstSeq === undefined) container.firstSeq = tokenIndex
+      container.parts.push({ type: 'text', value })
+      continue
+    }
+
+    if (token.type !== 'open' && token.type !== 'close') continue
+
+    if (token.type === 'close') {
+      const index = findLastIndex(stack, (entry) => entry.name === token.name)
+      if (index === -1) continue
+      while (stack.length > index) {
+        const entry = stack.pop()
+        // 行内标记的闭合必须同步写进片段序列，否则 `</a>` 之后的正文会被误并进链接文字
+        if (entry.inline) pushPart({ type: 'close', tag: entry.inline.tag })
+        finalizeEntry(entry, token.line)
+      }
+      continue
+    }
+
+    const name = token.name
+    const attrs = token.attrs ?? {}
+    stats.elements += 1
+    const noise = noiseKindOf(name, attrs)
+    const inheritedNoise = activeNoise()
+    const inMain = hasAncestorMain(stack) || name === 'main' || name === 'article' ||
+      /^main$/i.test(attrs.role ?? '') || /articleBody/i.test(attrs.itemprop ?? '')
+
+    if (name === 'title') {
+      inTitle = true
+      titleBuffer = ''
+      stack.push({ name, kind: 'title', noise: inheritedNoise, line: token.line, inMain })
+      continue
+    }
+
+    if (noise || inheritedNoise) {
+      const kind = noise ?? inheritedNoise
+      if (noise) {
+        stats.noiseElements += 1
+        removed.elements[kind] = (removed.elements[kind] ?? 0) + 1
+      }
+      if (token.selfClosing) continue
+      stack.push({ name, kind: 'noise', noise: kind, line: token.line, inMain })
+      continue
+    }
+
+    if (HEADINGS[name]) {
+      stack.push({
+        name, kind: 'heading', line: token.line, inMain, seq: tokenIndex,
+        container: { kind: 'heading', level: HEADINGS[name], parts: [], firstSeq: null, line: token.line, id: attrs.id ?? '' },
+      })
+      continue
+    }
+
+    if (name === 'ul' || name === 'ol') {
+      stats.lists += 1
+      stack.push({ name, kind: 'list', line: token.line, inMain, list: { ordered: name === 'ol', counter: 0, depth: countAncestors(stack, (entry) => entry.kind === 'list') + 1 } })
+      continue
+    }
+
+    if (name === 'li') {
+      const list = innermostList()
+      let index = null
+      let ordered = false
+      let depth = 1
+      if (list) {
+        list.counter += 1
+        index = list.ordered ? list.counter : null
+        ordered = list.ordered
+        depth = list.depth
+      }
+      stack.push({
+        name, kind: 'li', line: token.line, inMain, seq: tokenIndex,
+        container: { kind: 'listItem', parts: [], firstSeq: null, line: token.line, ordered, index, depth },
+        listOwner: list,
+      })
+      continue
+    }
+
+    if (name === 'table') {
+      stack.push({ name, kind: 'table', line: token.line, inMain, seq: tokenIndex, table: { rows: [], current: null, line: token.line } })
+      continue
+    }
+
+    if (name === 'tr') {
+      const tableEntry = findLast(stack, (entry) => entry.table)
+      if (tableEntry) {
+        const row = { cells: [], hasTh: false, line: token.line }
+        tableEntry.table.rows.push(row)
+        stack.push({ name, kind: 'row', line: token.line, inMain, row })
+      } else {
+        stack.push({ name, kind: 'row', line: token.line, inMain, row: { cells: [], hasTh: false, line: token.line } })
+      }
+      continue
+    }
+
+    if (name === 'td' || name === 'th') {
+      // 没有 <tr> 的畸形表格：补一行，别把单元格文字丢掉
+      if (!innermostRow()) {
+        const tableEntry = findLast(stack, (entry) => entry.table)
+        if (tableEntry) {
+          const row = { cells: [], hasTh: false, line: token.line }
+          tableEntry.table.rows.push(row)
+          stack.push({ name: 'tr', kind: 'row', line: token.line, inMain, row })
+        }
+      }
+      stack.push({
+        name, kind: 'cell', line: token.line, inMain, seq: tokenIndex,
+        container: { kind: 'cell', parts: [], firstSeq: null, line: token.line, cellType: name === 'th' ? 'th' : 'td' },
+      })
+      continue
+    }
+
+    if (name === 'pre') {
+      const lang = languageOf(attrs, '')
+      stack.push({
+        name, kind: 'pre', line: token.line, inMain, seq: tokenIndex,
+        container: { kind: 'code', parts: [], firstSeq: null, line: token.line, lang },
+      })
+      continue
+    }
+
+    if (name === 'code' && hasAncestor(stack, (entry) => entry.kind === 'pre')) {
+      // `<pre><code class="language-js">`：语言在 code 上
+      const preEntry = [...stack].reverse().find((entry) => entry.kind === 'pre')
+      if (preEntry?.container) preEntry.container.lang = languageOf(attrs, preEntry.container.lang)
+      stack.push({ name, kind: 'inline', line: token.line, inMain })
+      continue
+    }
+
+    if (name === 'blockquote') {
+      stack.push({
+        name, kind: 'quote', line: token.line, inMain, seq: tokenIndex,
+        container: { kind: 'quote', parts: [], firstSeq: null, line: token.line },
+      })
+      continue
+    }
+
+    if (name === 'br') {
+      pushPart({ type: 'text', value: '\n' })
+      continue
+    }
+
+    if (name === 'hr') {
+      emit({ kind: 'rule', line: token.line, endLine: token.line, seq: tokenIndex, inMain })
+      continue
+    }
+
+    if (name === 'img') {
+      const alt = collapseWhitespace(attrs.alt ?? '').trim()
+      const src = resolveUrl(attrs.src ?? '', baseUrl)
+      if (alt || src) pushPart({ type: 'text', value: alt ? `![${alt}](${src})` : `![](${src})` })
+      continue
+    }
+
+    if (name in INLINE_MARKS) {
+      if (token.selfClosing) continue
+      if (name === 'a') {
+        const href = resolveUrl(attrs.href ?? '', baseUrl)
+        if (href && !href.startsWith('#') && links.length < maxLinks) {
+          links.push({ url: href, line: token.line })
+          stats.links += 1
+        }
+        stack.push({ name, kind: 'inline', line: token.line, inMain, inline: { tag: 'a', href } })
+        pushPart({ type: 'open', tag: 'a', href })
+        continue
+      }
+      const tag = name === 'b' ? 'strong' : name === 'i' ? 'em' : name
+      stack.push({ name, kind: 'inline', line: token.line, inMain, inline: { tag } })
+      pushPart({ type: 'open', tag })
+      continue
+    }
+
+    if (name === 'code' || name === 'kbd' || name === 'samp' || name === 'tt') {
+      if (token.selfClosing) continue
+      stack.push({ name, kind: 'inline', line: token.line, inMain, inline: { tag: 'code' } })
+      pushPart({ type: 'open', tag: 'code' })
+      continue
+    }
+
+    if (BLOCK_CONTAINERS.has(name)) {
+      stack.push({
+        name, kind: 'block', line: token.line, inMain, seq: tokenIndex,
+        container: { kind: 'paragraph', parts: [], firstSeq: null, line: token.line },
+      })
+      continue
+    }
+
+    // 其余标签（head/meta/link/script 已在噪音里、col/colgroup/tbody/thead/tfoot/…）不进栈也不产块
+    if (!token.selfClosing) stack.push({ name, kind: 'plain', line: token.line, inMain })
+  }
+
+  // EOF：把还开着的元素按最内层优先收尾（浏览器容错的简化版）
+  while (stack.length > 0) {
+    const entry = stack.pop()
+    finalizeEntry(entry, rawLines.length)
+  }
+  if (loose) {
+    const text = renderInline(loose.parts).trim()
+    if (text) emit({ kind: 'paragraph', line: loose.line, endLine: rawLines.length, seq: loose.firstSeq ?? 0, text, inMain: false })
+  }
+
+  blocks.sort((a, b) => a.seq - b.seq)
+
+  // 行号对齐的可见文本：收拢空白，保持与源文件同样的行数
+  for (let i = 0; i < textLines.length; i++) textLines[i] = collapseWhitespace(textLines[i]).trim()
+
+  const title = titleFromTag || headingFallback || firstNonEmpty(textLines).slice(0, 200)
+
+  return { title, blocks, textLines, removed, links, signals, stats: { ...stats, blocks: blocks.length } }
+}
+
+/**
+ * 从 class 里取代码语言（`language-js` / `lang-js`）。
+ * @param {Record<string,string>} attrs 属性
+ * @param {string} fallback 兜底值
+ * @returns {string} 语言名
+ */
+function languageOf(attrs, fallback = '') {
+  const match = /(?:language|lang)-([\w+#.-]+)/i.exec(attrs.class ?? '')
+  return match ? match[1].toLowerCase() : fallback
+}
+
+/**
+ * 找最内层的「吸收型」容器（单元格 / 列表项 / 引用）：它们的子块不单独成块。
+ * @param {Array<object>} stack 元素栈
+ * @returns {object|null} 吸收目标容器
+ */
+function findAbsorbingContainer(stack) {
+  for (let i = stack.length - 1; i >= 0; i--) {
+    const container = stack[i].container
+    if (!container) continue
+    if (container.kind === 'cell' || container.kind === 'listItem' || container.kind === 'quote') return container
+  }
+  return null
+}
+
+/**
+ * 判断祖先里有没有某个元素。
+ * @param {Array<object>} stack 栈
+ * @param {(entry:object)=>boolean} predicate 判定
+ * @returns {boolean} 是否存在
+ */
+function hasAncestor(stack, predicate) {
+  for (let i = stack.length - 1; i >= 0; i--) if (predicate(stack[i])) return true
+  return false
+}
+
+/**
+ * 数祖先里满足条件的个数。
+ * @param {Array<object>} stack 栈
+ * @param {(entry:object)=>boolean} predicate 判定
+ * @returns {number} 个数
+ */
+function countAncestors(stack, predicate) {
+  let count = 0
+  for (const entry of stack) if (predicate(entry)) count += 1
+  return count
+}
+
+/**
+ * 判断当前是否在 `<main>` / `<article>` 里（正文信号的强证据）。
+ * @param {Array<object>} stack 栈
+ * @returns {boolean} 是否在正文容器内
+ */
+function hasAncestorMain(stack) {
+  for (const entry of stack) {
+    if (entry.inMain) return true
+    if (entry.name === 'main' || entry.name === 'article') return true
+  }
+  return false
+}
+
+/**
+ * 从后往前找第一个满足条件的元素下标。
+ * @param {Array<object>} list 列表
+ * @param {(item:object)=>boolean} predicate 判定
+ * @returns {number} 下标，找不到返回 -1
+ */
+function findLastIndex(list, predicate) {
+  for (let i = list.length - 1; i >= 0; i--) if (predicate(list[i])) return i
+  return -1
+}
+
+/**
+ * 从后往前找第一个满足条件的元素。
+ * @param {Array<object>} list 列表
+ * @param {(item:object)=>boolean} predicate 判定
+ * @returns {object|undefined} 元素
+ */
+function findLast(list, predicate) {
+  for (let i = list.length - 1; i >= 0; i--) if (predicate(list[i])) return list[i]
+  return undefined
+}
+
+/**
+ * 去掉行内 Markdown 标记（标题/摘要用纯文本）。
+ * @param {string} text 含标记的文本
+ * @returns {string} 纯文本
+ */
+export function stripInline(text) {
+  return String(text ?? '')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/(\*\*|~~|\*|`)/g, '')
+    .trim()
+}
+
+/**
+ * 取第一个非空行。
+ * @param {string[]} lines 行
+ * @returns {string} 第一个非空行
+ */
+function firstNonEmpty(lines) {
+  for (const line of lines) if (line && line.trim()) return line.trim()
+  return ''
+}