dsh-mega-chat-nav 0.1.1

package/src/client/index.ts

@@ -0,0 +1,388 @@
+/**
+ * Browser-half entry for the dsh-mega-chat-nav plugin.
+ *
+ * Registers one surface into the frame-wide floating layer (`shell.overlay`):
+ * a vertical strip on the LEFT edge of the conversation column listing every
+ * user question in the current session as a small button, one dot per turn.
+ * Clicking a button scrolls the chat to that turn's first question.
+ *
+ * The dots are driven by the host-folded `msgNavMessages` session projection
+ * (registered by the plugin's host half): the projection registry folds the
+ * WHOLE event log without touching the chat's paged render window, the
+ * projection cache persists it, and the standard carriers (history tail-page
+ * baseline + session/projection push frames) keep it live. Live-window
+ * questions not yet recorded by the projection are merged on top so a
+ * just-sent question appears immediately.
+ *
+ * Failure policy: nothing here throws at apply time — an external plugin must
+ * never take the GUI down.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the locale plugin's Context merge (ctx.locale).
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+// Type-only: pulls the settings shell's SlotMap merge ('settings.plugins.tab')
+// and the ctx.settingsScope Context merge.
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { SettingsScopeBinder } from '@deepseek-ai/dsh-client-ui-settings/client'
+import { RailDispatch } from './components/RailDispatch.tsx'
+import { SettingsPage } from './components/settings/SettingsPage.tsx'
+import { StandaloneSettings } from './components/settings/StandaloneSettings.tsx'
+import { NavSettingsController } from './settings.ts'
+import type { NavInjected, ObservableFace } from './components/shared/types.ts'
+import { en, zh } from './locales.ts'
+import { goTo, type JumpFailureCode, type JumpPorts, type JumpSnapshot } from './jump.ts'
+
+/** Locale namespace this plugin owns. */
+const NS = 'mega-chat-nav'
+
+/** Services required by this plugin. */
+export const inject = ['slots', 'locale', 'sessions']
+
+/** 会话服务最小面（rc 类型面不全，此处宽松化） */
+interface SessionsFace {
+  binding(sessionId: string): { session: SessionFace } | undefined
+  list: { subscribe(cb: () => void): () => void }
+}
+
+interface SessionSnapshotLike {
+  openState?: string
+  hasMore?: boolean
+  loadingOlder?: boolean
+  chat?: { nodes?: { values(): Iterable<{ key?: string; anchorSeq?: number; visibility?: string; kind?: string; data?: unknown }> } }
+}
+
+interface SessionFace {
+  getSnapshot(): SessionSnapshotLike
+  loadOlder(): Promise<void>
+  subscribe(cb: () => void): () => void
+  projections: { faceOf(key: string): { getSnapshot(): unknown; subscribe(cb: () => void): () => void } }
+}
+
+function sessionsOf(ctx: ClientContext): SessionsFace {
+  return ctx.sessions as unknown as SessionsFace
+}
+
+/** 会话行最小面（结构型，非 SDK 绑定） */
+interface ChatRowLike {
+  key: string
+  anchorSeq: number
+  visibility?: string
+  kind?: string
+  data?: unknown
+}
+
+interface RowPayload {
+  content?: readonly { type?: string; text?: string }[]
+  seq?: number
+  time?: number
+}
+
+/** 提问行 kind */
+const QUESTION_KINDS = ['user', 'steering']
+
+/** 消息首文本块；缺省空串 */
+function firstTextBlock(content: readonly { type?: string; text?: string }[] | undefined): string {
+  const block = content?.find((part) => typeof part?.text === 'string')
+  return block?.text ?? ''
+}
+
+/** 从节点窗口提取提问行（kind 过滤 + 首文本 + 按 anchorSeq 排序） */
+function extractQuestionRows(nodes: Iterable<ChatRowLike>): { key: string; anchorSeq: number; seq: number; time: number; text: string }[] {
+  return [...nodes]
+    .filter((node) => QUESTION_KINDS.includes(node.kind ?? ''))
+    .map((node) => {
+      const payload = (typeof node.data === 'object' && node.data !== null ? node.data : {}) as RowPayload
+      return {
+        key: node.key,
+        anchorSeq: node.anchorSeq,
+        seq: payload.seq ?? -1,
+        time: payload.time ?? 0,
+        text: firstTextBlock(payload.content),
+      }
+    })
+    .sort((a, b) => a.anchorSeq - b.anchorSeq)
+}
+
+
+/** Single-instance guard: a duplicated client injection must not mount twice. */
+declare global {
+  // eslint-disable-next-line no-var
+  var __dshMegaChatNavApplied: boolean | undefined
+}
+
+function claimApply(): boolean {
+  if (globalThis.__dshMegaChatNavApplied === true) return false
+  globalThis.__dshMegaChatNavApplied = true
+  return true
+}
+
+function releaseApply(): void {
+  globalThis.__dshMegaChatNavApplied = undefined
+}
+
+/** Map the session snapshot to the jump-loop port surface. */
+function jumpPortsFor(ctx: ClientContext, sessionId: string): JumpPorts {
+  const sessions = sessionsOf(ctx)
+  return {
+    snap: () => {
+      const binding = sessions.binding(sessionId)
+      const snap = binding?.session.getSnapshot()
+      if (snap === undefined) return undefined
+      return {
+        openState: snap.openState ?? '',
+        hasMore: snap.hasMore ?? false,
+        loadingOlder: snap.loadingOlder ?? false,
+        rows: (snap.chat?.nodes?.values() ?? []) as unknown as JumpSnapshot['rows'],
+      }
+    },
+    loadMore: async () => {
+      const binding = sessions.binding(sessionId)
+      if (binding === undefined) throw new Error('session unavailable')
+      await binding.session.loadOlder()
+    },
+    active: () => document.querySelector('[data-chat-flow]') !== null,
+    locate: (key: string) => {
+      const rows = Array.from(document.querySelectorAll<HTMLElement>('[data-chat-anchor-key]'))
+      for (const row of rows) {
+        if (row.dataset.chatAnchorKey === key) return row
+      }
+      // 包含兜底（key 为完整锚点串，唯一命中）
+      for (const row of rows) {
+        const k = row.dataset.chatAnchorKey
+        if (k !== undefined && k.includes(key)) return row
+      }
+      // seq 兜底：取最后一个匹配（防误命中前一行）
+      if (key.startsWith('seq:')) {
+        const n = key.slice(4)
+        let found: HTMLElement | null = null
+        for (const row of rows) {
+          const k = row.dataset.chatAnchorKey
+          if (k !== undefined && k.includes(n)) found = row
+        }
+        if (found !== null) return found
+      }
+      return null
+    },
+    reveal: (row, mode) => {
+      // 目标行顶部与视口顶留 12px 间距（不贴顶，视觉更舒适）
+      const scrollToRow = (): void => {
+        const port = document.querySelector<HTMLElement>('[data-conversation-scroll]')
+        if (port !== null) {
+          const rowTop = row.getBoundingClientRect().top - port.getBoundingClientRect().top + port.scrollTop
+          port.scrollTo({ top: rowTop - 12, behavior: mode })
+        } else {
+          row.scrollIntoView({ behavior: mode, block: 'start' })
+        }
+      }
+      scrollToRow()
+      // 正文在 loadOlder prepend 落地后可能自动滚回底部（跟随滚动）：
+      // 校验式重滚——仅当目标行明显偏离视口顶（被正文回滚/未到位）才重滚，
+      // 用户主动滚动阅读时不干预
+      const ensure = (): void => {
+        const port = document.querySelector<HTMLElement>('[data-conversation-scroll]')
+        if (port === null) return
+        const rowRect = row.getBoundingClientRect()
+        const portRect = port.getBoundingClientRect()
+        const offset = rowRect.top - portRect.top
+        if (offset < -60 || offset > 120) scrollToRow()
+      }
+      window.setTimeout(ensure, 300)
+      window.setTimeout(ensure, 800)
+      // 跳转确认高亮：监听目标气泡**进入视口（可见）**后才开始闪烁；
+      // 背景经 transition 平滑渐变（非突兀切换），主题色两轮缓慢变化
+      const bubble = row.querySelector<HTMLElement>('[class*="bubble"]')
+        ?? row.querySelector<HTMLElement>('[class*="messageBody"], [class*="bubbleBody"]')
+      if (bubble !== null) {
+        const original = bubble.style.background
+        const themeBg = 'color-mix(in srgb, var(--dsw-alias-brand-primary) 38%, transparent)'
+        bubble.style.transition = 'background 350ms ease'
+        const paint = (on: boolean): void => {
+          bubble.style.background = on ? themeBg : original
+        }
+        // 轮询等待气泡可见（进入滚动容器视口）；4s 兜底后也执行
+        const waitVisible = (): Promise<void> => new Promise((resolve) => {
+          const port = document.querySelector<HTMLElement>('[data-conversation-scroll]')
+          let tries = 0
+          const check = (): void => {
+            const r = bubble.getBoundingClientRect()
+            const portTop = port !== null ? port.getBoundingClientRect().top : 0
+            const portBottom = port !== null ? port.getBoundingClientRect().bottom : window.innerHeight
+            if ((r.bottom > portTop && r.top < portBottom) || tries > 40) resolve()
+            else {
+              tries += 1
+              window.setTimeout(check, 100)
+            }
+          }
+          check()
+        })
+        void waitVisible().then(() => {
+          // 两轮切换共约 1.5s：渐变到主题色 → 渐变回 → 再切 → 再回
+          paint(true)
+          window.setTimeout(() => paint(false), 400)
+          window.setTimeout(() => paint(true), 800)
+          window.setTimeout(() => paint(false), 1200)
+          window.setTimeout(() => { bubble.style.transition = '' }, 1500)
+        })
+      }
+    },
+    scrollport: () => document.querySelector<HTMLElement>('[data-conversation-scroll]'),
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => window.setTimeout(resolve, ms)),
+  }
+}
+
+/**
+ * The session's `msgNavMessages` projection face (getSnapshot + subscribe).
+ * Undefined when the session is not bound or the host unit is not registered
+ * (e.g. a headless composition) — the strip then shows live-window dots only.
+ */
+function navProjectionOf(ctx: ClientContext, sessionId: string): ObservableFace | undefined {
+  const face = sessionsOf(ctx).binding(sessionId)?.session.projections.faceOf('msgNavMessages')
+  if (face === undefined) return undefined
+  return {
+    getSnapshot: () => face.getSnapshot(),
+    subscribe: (listener) => face.subscribe(listener),
+  }
+}
+
+function createInject(ctx: ClientContext, settings: NavSettingsController): NavInjected {
+  const sessions = sessionsOf(ctx)
+  return {
+    readQuestions: (sessionId) => {
+      const snap = sessions.binding(sessionId)?.session.getSnapshot()
+      if (snap === undefined || snap.chat?.nodes === undefined) return []
+      return extractQuestionRows(snap.chat.nodes.values() as unknown as Iterable<ChatRowLike>)
+    },
+    subscribeList: (cb) => sessions.list.subscribe(cb),
+    subscribeContent: (sessionId, cb) => {
+      const binding = sessions.binding(sessionId)
+      if (binding === undefined) return () => {}
+      return binding.session.subscribe(cb)
+    },
+    questionProjection: (sessionId) => navProjectionOf(ctx, sessionId),
+    jump: (sessionId, key, seq, currentSeq) => {
+      const ports = jumpPortsFor(ctx, sessionId)
+      ports.report = (code: JumpFailureCode) => {
+        // Surface the failure through the component via a DOM event the
+        // strip listens for; simplest reliable cross-boundary channel here.
+        window.dispatchEvent(new CustomEvent('mega-chat-nav:jump-failed', { detail: code }))
+      }
+      ports.onLoading = (loading: boolean, pages: number) => {
+        window.dispatchEvent(new CustomEvent('mega-chat-nav:jump-loading', { detail: { loading, pages } }))
+      }
+      void goTo(ports, key, {}, settings.getSnapshot().scrollBehavior, seq, currentSeq)
+    },
+    style: () => settings.getSnapshot().style,
+    setStyle: (style) => settings.setStyle(style),
+    align: () => settings.getSnapshot().align,
+    subscribeSettings: (cb) => settings.subscribe(cb),
+    setAlign: (align) => settings.setAlign(align),
+    bandHeight: () => settings.getSnapshot().bandHeight,
+    setBandHeight: (band) => settings.setBandHeight(band),
+    scrollBehavior: () => settings.getSnapshot().scrollBehavior,
+    setScrollMode: (mode) => settings.setScrollMode(mode),
+    showCount: () => settings.getSnapshot().showCount,
+    setShowCount: (mode) => settings.setShowCount(mode),
+    showSearch: () => settings.getSnapshot().showSearch,
+    setShowSearch: (mode) => settings.setShowSearch(mode),
+    showQuickSettings: () => settings.getSnapshot().showQuickSettings,
+    setShowQuickSettings: (mode) => settings.setShowQuickSettings(mode),
+    showFavorites: () => settings.getSnapshot().showFavorites,
+    setShowFavorites: (mode) => settings.setShowFavorites(mode),
+    showPaging: () => settings.getSnapshot().showPaging,
+    setShowPaging: (mode) => settings.setShowPaging(mode),
+    searchScopes: () => settings.getSnapshot().searchScopes,
+    setSearchScopes: (scopes) => settings.setSearchScopes(scopes),
+    railOffset: () => settings.getSnapshot().railOffset,
+    setRailOffset: (offset) => settings.setRailOffset(offset),
+    cardCount: () => settings.getSnapshot().cardCount,
+    setCardCount: (count) => settings.setCardCount(count),
+    cardItems: () => settings.getSnapshot().cardItems,
+    setCardItems: (items) => settings.setCardItems(items),
+    markTone: () => settings.getSnapshot().markTone,
+    setMarkTone: (tone) => settings.setMarkTone(tone),
+  }
+}
+
+/**
+ * Register the mega-chat-nav surface.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  if (!claimApply()) return
+  ctx.effect(() => releaseApply, 'mega-chat-nav: apply claim')
+
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'mega-chat-nav: dictionaries')
+  const t = ctx.locale.bind(NS)
+
+  const settings = new NavSettingsController()
+  const injected = createInject(ctx, settings)
+
+  ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+    name: 'shell.overlay',
+    id: 'mega-chat-nav',
+    order: 900,
+    locale: NS,
+    inject: () => ({ injected }),
+  }, RailDispatch))
+
+  // mega-settings 成员契约：元信息 seat + 页面 seat（宿主缺席 → 静默等待 → 自足）
+  ctx.slots.inject('mega.settings.member', () => ctx.slots.register({
+    name: 'mega.settings.member',
+    id: 'mega-chat-nav',
+    order: 10,
+    label: () => t('label'),
+    inject: () => ({ description: () => t('desc'), version: PKG_VERSION }),
+  }, ListRow))
+
+  ctx.slots.inject('mega.settings.member.page', () => ctx.slots.register({
+    name: 'mega.settings.member.page',
+    key: 'mega-chat-nav',
+    order: 10,
+    label: () => t('label'),
+    locale: NS,
+    inject: () => ({ injected }),
+  }, SettingsPage))
+
+  // 插件页配置入口：仅当未被 mega-settings 收纳时注册（收纳后注销，避免重复入口）。
+  // mega-settings 可能晚于本插件加载——注册后订阅 member 条目，宿主出现即注销。
+  {
+    let tabDispose: (() => void) | null = null
+    const ensurePluginsTab = (): void => {
+      const hosted = (ctx.slots.entries?.('mega.settings.member')?.length ?? 0) > 0
+      if (hosted) {
+        tabDispose?.()
+        tabDispose = null
+      } else if (tabDispose === null) {
+        tabDispose = ctx.slots.register({
+          name: 'settings.plugins.tab',
+          id: 'mega-chat-nav',
+          order: 100,
+          label: () => t('label'),
+          locale: NS,
+          inject: () => ({ injected, slots: ctx.slots }),
+        }, StandaloneSettings)
+      }
+    }
+    ensurePluginsTab()
+    const offMember = ctx.slots.subscribe?.('mega.settings.member', ensurePluginsTab)
+    ctx.effect(() => () => {
+      tabDispose?.()
+      tabDispose = null
+      offMember?.()
+    }, 'mega-chat-nav: plugins tab ledger')
+  }
+
+  // 设置控制器挂载：settingsScope 服务就绪后绑定 scope（未就绪时配置读写走默认值降级）
+  ctx.inject(['settingsScope'], (scopeCtx) => {
+    settings.attach(scopeCtx.get('settingsScope') as SettingsScopeBinder)
+  })
+}
+
+/** 成员列表行占位（元信息 seat 用；宿主自绘列表时不渲染） */
+function ListRow(): null {
+  return null
+}
+
+/** 构建注入的包版本常量（见 scripts/build-client.mjs） */
+declare const PKG_VERSION: string

package/src/client/jump.ts

@@ -0,0 +1,293 @@
+// 跳转编排（client 装配层自研）：定位目标行——按方向分流（向下滚动 / 向上补历史），
+// 等待渲染并滚动；失败回退。结果码与词条绑定（jump-failed 事件契约）。
+//
+// 关键语义：chat.nodes 只是「虚拟渲染窗口」（DOM 渲染行），目标行在已加载范围内
+// 但未渲染时**不能**当作「需要加载更早历史」——必须按目标 seq 与渲染窗口的关系分流。
+
+/** 跳转循环所需的会话快照面 */
+export interface JumpSnapshot {
+  openState: string
+  hasMore: boolean
+  loadingOlder: boolean
+  rows: Iterable<{ key: string; anchorSeq: number; visibility?: string }>
+}
+
+/** 外部端口：会话读写、DOM 行查找、滚动与时钟（由浏览器半装配） */
+export interface JumpPorts {
+  snap: () => JumpSnapshot | undefined
+  loadMore: () => Promise<void>
+  active: () => boolean
+  locate: (key: string) => HTMLElement | null
+  reveal: (row: HTMLElement, mode: 'smooth' | 'instant') => void
+  /** 会话滚动容器（虚拟渲染按 scrollTop 触发） */
+  scrollport: () => HTMLElement | null
+  now: () => number
+  sleep: (ms: number) => Promise<void>
+  report?: (code: JumpFailureCode, fallback?: boolean) => void
+  /** 扩窗加载进度（loading 状态 + 已加载页数），驱动「正在加载较早记录」提示 */
+  onLoading?: (loading: boolean, pages: number) => void
+}
+
+export type JumpFailureCode = 'VIEW_INACTIVE' | 'TARGET_HIDDEN' | 'NOT_FOUND' | 'TIMEOUT'
+
+interface JumpResult {
+  ok: boolean
+  code?: JumpFailureCode
+  fallback?: boolean
+}
+
+interface JumpOptions {
+  totalTimeoutMs?: number
+  maxPages?: number
+  rowWaitMs?: number
+  pollMs?: number
+}
+
+const BUDGET = {
+  totalTimeoutMs: 30_000,
+  maxPages: 300,
+  rowWaitMs: 8_000,
+  pollMs: 60,
+}
+
+/** 行是否为可渲染锚点行 */
+function isVisibleRow(row: { visibility?: string }): boolean {
+  return row.visibility !== 'hidden'
+}
+
+/** 快照中是否已含目标行 */
+function hasTarget(rows: Iterable<{ key: string; visibility?: string }>, key: string): boolean {
+  for (const row of rows) {
+    if (isVisibleRow(row) && row.key === key) return true
+  }
+  return false
+}
+
+/** 渲染窗口的锚点序号极值；空窗口返回 null */
+function seqRange(rows: Iterable<{ anchorSeq: number }>): { min: number; max: number } | null {
+  let min: number | null = null
+  let max: number | null = null
+  for (const row of rows) {
+    if (min === null || row.anchorSeq < min) min = row.anchorSeq
+    if (max === null || row.anchorSeq > max) max = row.anchorSeq
+  }
+  return min === null || max === null ? null : { min, max }
+}
+
+/** 当前窗口最小锚点序号；空窗口返回 null */
+function smallestSeq(rows: Iterable<{ anchorSeq: number }>): number | null {
+  const range = seqRange(rows)
+  return range === null ? null : range.min
+}
+
+/** 回退目标：排除指定 key 的最近可渲染行（取最新锚点序号） */
+function retreatTo(
+  rows: Iterable<{ key: string; anchorSeq: number; visibility?: string }>,
+  excludeKey: string,
+): { key: string; anchorSeq: number } | null {
+  let best: { key: string; anchorSeq: number } | null = null
+  for (const row of rows) {
+    if (row.visibility === 'hidden') continue
+    if (row.key === excludeKey) continue
+    if (best === null || row.anchorSeq > best.anchorSeq) best = { key: row.key, anchorSeq: row.anchorSeq }
+  }
+  return best
+}
+
+/** 等待某行渲染（预算内轮询）；视图失活返回 null */
+async function waitForRow(ports: JumpPorts, rowKey: string, pollMs: number, rowWaitMs: number): Promise<HTMLElement | null> {
+  for (let waited = 0; waited <= rowWaitMs; waited += pollMs) {
+    if (!ports.active()) return null
+    const row = ports.locate(rowKey)
+    if (row !== null) return row
+    await ports.sleep(pollMs)
+  }
+  return null
+}
+
+/**
+ * 滚动定位：按方向逐屏滚动（触发虚拟渲染）直至目标行出现或到达边界。
+ * 若快照渲染窗口已含目标但 DOM 尚未挂载（渲染延迟），放慢等待 DOM。
+ * 返回命中的行；未命中返回 null。
+ */
+async function scrollLocate(
+  ports: JumpPorts,
+  key: string,
+  dir: 1 | -1,
+  maxSteps: number,
+  stepMs: number,
+): Promise<HTMLElement | null> {
+  const port = ports.scrollport()
+  if (port === null) return null
+  for (let i = 0; i < maxSteps; i++) {
+    const row = ports.locate(key)
+    if (row !== null) return row
+    const before = port.scrollTop
+    const step = Math.max(200, Math.round(port.clientHeight * 0.4))
+    port.scrollBy({ top: dir * step })
+    await ports.sleep(stepMs)
+    const floor = Math.max(0, port.scrollHeight - port.clientHeight)
+    if (Math.abs(port.scrollTop - before) < 2) {
+      // 到边界：反向回扫若干步（虚拟渲染滞后可能已滚过头）
+      if (dir === 1) {
+        for (let i = 0; i < 10; i++) {
+          const row = ports.locate(key)
+          if (row !== null) return row
+          port.scrollBy({ top: -Math.round(port.clientHeight * 0.4) })
+          await ports.sleep(stepMs)
+        }
+      }
+      return null
+    }
+    // 滚动后：虚拟渲染窗口已覆盖目标（数据窗口含目标行）→ 放慢等待 DOM 挂载
+    const snap = ports.snap()
+    if (snap !== undefined && hasTarget(snap.rows, key)) {
+      const rendered = await waitForRow(ports, key, Math.max(100, stepMs), 2500)
+      if (rendered !== null) return rendered
+      return null
+    }
+  }
+  return null
+}
+
+/**
+ * 跳转到 key 对应行：
+ *   - 目标已在渲染窗口 → 等待 DOM 并滚动；
+ *   - 目标在下方/窗口内（targetSeq ≥ 渲染窗口最小值）→ 向下滚动定位（无需加载）；
+ *   - 目标更早（targetSeq < 渲染窗口最小值 或未知）→ 预算内 loadOlder 补历史，每页后向上滚动定位；
+ *   - 全部失败 → 回退最近可渲染行。
+ */
+export async function goTo(
+  ports: JumpPorts,
+  key: string,
+  options: JumpOptions = {},
+  mode: 'smooth' | 'instant' = 'smooth',
+  targetSeq?: number,
+  currentSeq?: number,
+): Promise<JumpResult> {
+  const budget = { ...BUDGET, ...options }
+  const fail = (code: JumpFailureCode, fallback = false): JumpResult => {
+    ports.report?.(code, fallback)
+    return fallback ? { ok: false, code, fallback: true } : { ok: false, code }
+  }
+
+  if (!ports.active()) return fail('VIEW_INACTIVE')
+
+  const deadline = ports.now() + budget.totalTimeoutMs
+  let pages = 0
+  let lastNotified = -1
+  const notifyLoading = (loading: boolean, count: number): void => {
+    const key2 = loading ? count : -1
+    if (key2 === lastNotified) return
+    lastNotified = key2
+    ports.onLoading?.(loading, count)
+  }
+
+  // 阶段一：确保目标进入渲染窗口
+  for (;;) {
+    const snap = ports.snap()
+    if (snap === undefined) { notifyLoading(false, 0); return fail('VIEW_INACTIVE') }
+    if (hasTarget(snap.rows, key)) { notifyLoading(false, 0); break }
+    if (ports.now() > deadline) { notifyLoading(false, 0); return fail('TIMEOUT') }
+
+    // 明确在下方（目标比当前阅读位置晚）：向下滚动定位，绝不加载。
+    // 方向判定优先用当前阅读位置 seq（渲染窗口极值含虚拟缓冲，不可靠）
+    if (targetSeq !== undefined) {
+      const range = seqRange(snap.rows)
+      const below = currentSeq !== undefined
+        ? targetSeq > currentSeq
+        : range !== null && targetSeq > range.max
+      if (below) {
+        const found = await scrollLocate(ports, key, 1, 500, budget.pollMs * 2)
+        if (found !== null) {
+          ports.reveal(found, mode)
+          return { ok: true }
+        }
+        notifyLoading(false, 0)
+        return fail('TARGET_HIDDEN')
+      }
+    }
+
+    // 其余情况：先向上滚动定位（目标可能已加载但位于虚拟缓冲/视口上方未渲染），
+    // 仅在目标距渲染窗口较近时尝试，避免无谓的大范围滚动
+    if (!snap.loadingOlder) {
+      const range = seqRange(snap.rows)
+      const closeEnough = targetSeq === undefined || range === null || targetSeq >= range.min - 40
+      if (closeEnough) {
+        const up = await scrollLocate(ports, key, -1, 40, budget.pollMs * 2)
+        if (up !== null) {
+          notifyLoading(false, 0)
+          ports.reveal(up, mode)
+          return { ok: true }
+        }
+      }
+    }
+
+    // 更早方向：补历史
+    if (snap.openState !== 'open') {
+      if (snap.openState === 'error') { notifyLoading(false, 0); return fail('VIEW_INACTIVE') }
+      await ports.sleep(budget.pollMs)
+      continue
+    }
+    if (snap.hasMore !== true) { notifyLoading(false, 0); return fail('NOT_FOUND') }
+    if (pages >= budget.maxPages) { notifyLoading(false, 0); return fail('TIMEOUT') }
+    notifyLoading(true, pages + 1)
+    if (snap.loadingOlder) {
+      await ports.sleep(budget.pollMs)
+      continue
+    }
+    const before = smallestSeq(snap.rows)
+    await ports.loadMore()
+    pages += 1
+    notifyLoading(true, pages)
+    // loadOlder 的 Promise resolve 可能早于数据落地：轮询等待窗口最小 seq 真正前移
+    let after = before
+    for (let waited = 0; waited <= 5000; waited += budget.pollMs) {
+      const s2 = ports.snap()
+      const cur = smallestSeq(s2 === undefined ? [] : s2.rows)
+      if (cur !== null && (before === null || cur < before)) { after = cur; break }
+      await ports.sleep(budget.pollMs)
+    }
+    if (after === null || (before !== null && after >= before)) {
+      // 加载无进展：最后向上滚动定位一次再判失败
+      const up = await scrollLocate(ports, key, -1, 40, budget.pollMs * 2)
+      if (up !== null) {
+        notifyLoading(false, 0)
+        ports.reveal(up, mode)
+        return { ok: true }
+      }
+      notifyLoading(false, 0)
+      return fail('NOT_FOUND')
+    }
+    // 循环继续：新加载的行在视口上方，顶部迭代会再向上滚动定位
+  }
+
+  // 阶段二：等待渲染并滚动；隐藏则回退
+  const row = await waitForRow(ports, key, budget.pollMs, budget.rowWaitMs)
+  if (row !== null) {
+    ports.reveal(row, mode)
+    return { ok: true }
+  }
+
+  // 目标已入渲染窗口但 DOM 未挂载（虚拟渲染延迟）：双向滚动定位兜底
+  const snap0 = ports.snap()
+  if (snap0 !== undefined && hasTarget(snap0.rows, key)) {
+    const located = await scrollLocate(ports, key, -1, 60, budget.pollMs * 2)
+      ?? await scrollLocate(ports, key, 1, 60, budget.pollMs * 2)
+    if (located !== null) {
+      ports.reveal(located, mode)
+      return { ok: true }
+    }
+  }
+
+  const snap = ports.snap()
+  const fallback = retreatTo(snap === undefined ? [] : snap.rows, key)
+  if (fallback !== null) {
+    const fbRow = await waitForRow(ports, fallback.key, budget.pollMs, budget.rowWaitMs)
+    if (fbRow !== null) {
+      ports.reveal(fbRow, mode)
+      return fail('TARGET_HIDDEN', true)
+    }
+  }
+  return fail('TARGET_HIDDEN', false)
+}