* ♻️ refactor(conversation): unify spacer + scroll-to-user hooks

Merge `useConversationSpacer` and `useScrollToUserMessage` into a single
`useConversationScroll` hook to eliminate the races that caused occasional
"send message but viewport doesn't pin to the new user message" regressions.

Race fixes:
- Single `prevLengthRef` and a single send-detection effect, replacing two
  hooks with independent length tracking that could disagree across renders.
- `virtuaRef` is passed in and dereferenced at call time instead of reading
  `virtuaRef.current?.scrollToIndex` during render — removes the window
  where the ref hadn't been attached yet when a send fired.
- Pin state is an explicit `{ index, seenActive }` ref with three clear
  transitions (send / layout-bump / user-scroll-up) instead of several
  cooperating refs + derived flags.
- Retries are layout-driven: each `spacerLayoutVersion` bump re-fires
  `scrollToIndex` exactly once. The old 0/32/96ms timer fan-out is gone.

Also bumps `AT_BOTTOM_THRESHOLD` 100 → 300 so `atBottom` stays stable
while the spacer is settling.

* ♻️ refactor(conversation): extract sub-hooks from useConversationScroll

Split the unified conversation scroll hook into four cooperating sub-hooks
in the same file so each layer has one clear concern:

- useSpacerLayoutSignal — ResizeObserver on the spacer node → version bumps
- useSpacerHeight       — natural height / mount lifecycle / shrink state
- usePinController      — pin state machine + virtua-aware scroll dispatch
- useScrollShrink       — scrollOffset delta → cancel pin / shrink spacer

The main hook now owns just the send-detection effect, the pin re-fire on
layout settle, and derived output. Behavior is unchanged — same 15 tests
pass — but each piece is now readable in isolation.

* ⚡️ perf(conversation): narrow VirtualizedList subscription to a boolean

VirtualizedList only needs to know whether the second-to-last message is
the user's — the full displayMessages array was never used. Move the
derivation into `dataSelectors.isSecondLastMessageFromUser` so the
component re-renders on role transitions, not on every assistant token.

* ✅ test(e2e): cover conversation scroll behavior across the auto-scroll setting

Adds three scenarios under `@AGENT-SCROLL-*` that exercise the merged
`useConversationScroll` hook end-to-end through the real chat UI:

- AGENT-SCROLL-001 — with auto-scroll ON, the viewport ends up near the
  bottom once a long response has finished streaming.
- AGENT-SCROLL-002 — with auto-scroll OFF, the user's message stays
  pinned to the top and the viewport does not chase the assistant.
- AGENT-SCROLL-003 — with auto-scroll ON, scrolling up mid-stream cancels
  the pin and the viewport is not yanked back to the bottom afterwards.

Also extends the LLM mock with `setConfig` / `resetConfig` so scenario 3
can slow the response down enough for the mid-stream manual scroll, and
adds `presetResponses.longScrollArticle` (long enough to overflow the
viewport so scroll assertions are meaningful).

* ✅ test(e2e): cover send-time pin-to-top as its own scenario

AGENT-SCROLL-004 exercises the core pin behavior of `useConversationScroll`
independent of the auto-scroll setting: after sending a message, the user's
turn must be anchored to the top of the scrollport. Uses the slow-response
mock so the assertion runs while the spacer is still mounted.

* ✅ test(e2e): tune scroll scenarios after runtime validation

Run outcomes against a cold Next dev server (paradedb + next dev -p 3006):

- AGENT-SCROLL-001 (enabled → viewport stays near bottom) — passing
- AGENT-SCROLL-002 (disabled → user msg pinned to top) — passing
- AGENT-SCROLL-004 (send pins user msg to top) — passing
- AGENT-SCROLL-003 (mid-stream scroll-up cancels pin) — skipped

Scenario 3 is marked `@skip` until the LLM mock supports truly chunked
SSE streaming. The current mock fulfils the whole body at once, which
collapses the "mid-stream" window to a handful of ms and makes the
manual-scroll timing race-prone. The cancel-pin path is already
covered at the unit level in `useConversationScroll.test.ts`, so the
e2e placeholder just keeps the scenario on the radar.

Other tweaks for dev-mode reliability:
- Bumped setting-toggle step timeout to 90 s (turbopack cold compile of
  `/settings/chat-appearance` can exceed the default 30 s on first hit)
- Relaxed the inner `networkidle` / `toBeVisible` waits there to match
- Added a matching negative-path Then ("not pinned") that would power
  the skipped scenario once the mock is upgraded

* 🐛 fix(conversation): rebind pin tracking on every new turn

The message index refs that drive `latestAssistantSignature` and the
messages `ResizeObserver` were plain `useRef`s updated inside the send-
detection effect. On the render triggered by spacer state updates right
after a send, `[dataSource, displayMessages]` could be unchanged, so the
signature memo returned its cached value and the observer effect never
rebound to the new turn's user/assistant DOM nodes. Under certain commit
orderings this left spacer height tracking the previous turn and let
the pin-to-user anchor drift.

Turn the indices into state, include `assistantMessageIndex` in the
signature memo's deps, and forward the state (not a ref) to
`useSpacerHeight`. The observer now reliably rebinds to the fresh
nodes on the very next render.

Adds a unit regression covering the observer-rebind path and an e2e
scenario (`AGENT-SCROLL-005`) that sends two consecutive turns and
checks that the second user message still pins to the top.

# 🚀 LobeHub v2.1.53 (20260427)

**Release Date:** April 27, 2026
**Since v2.1.52:** 194 merged PRs · 17 contributors

> Introduce Heterogeneous Agent — Claude Code and Codex run as
first-class desktop runtimes, paired with a new Agent Signal package,
sharper desktop UX, and a wave of flagship model additions.

---

## ✨ Highlights

- **Introduce Heterogeneous Agent** — Claude Code and Codex run as
first-class desktop agents: subagent rendering, partial-message
streaming, multi-turn resume, terminal error surfacing, rich tool
inspectors, and runtime polish. (#14162, #13754, #14067, #14001, #13970,
#13942)
- **Screen capture & Quick Chat tray** — New desktop screen capture
overlay (macOS permission-gated) with Quick Chat tray and upload
pipeline improvements; chat input auto-focuses on overlay mount.
(#13818, #14097, #14105)
- **Desktop topic & tab UX** — Dedicated topic popup window with
cross-window sync, Cmd+W/Cmd+T tab shortcuts, TabBar polish, recent
working directories expanded to 20, and human approval notifications.
(#13957, #13983, #13972, #14036, #14092)
- **Git workflow built-in** — One-click pull/push from the branch chip,
ahead/behind badge, and submodule/worktree repo detection. (#14041,
#13980, #13978)
- **Agent Signal package** — New `@lobechat/agent-signal` runtime for
dynamic memory feedback signals, with OTel metrics and self-iteration in
Lab. (#14157, #14170, #14159, #14169, #14187)
- **New models** — Claude Opus 4.7 with `xhigh` effort tier, GPT-5.5,
DeepSeek V4 Flash/Pro with reasoning slider, Kimi K2.6, MiMo-V2.5/Pro,
gpt-image-2, Qwen3.6 Flash/Plus, and Pixverse-c1. (#13903, #14147,
#14114, #14004, #14089, #14039, #13923)
- **New providers** — OpenCode Zen, OpenCode Go, and Azure OpenAI Router
runtime. (#13943, #14064, #13823)
- **Mobile settings overhaul** — Full settings menu and responsive
profile layout for mobile. (#14019)

---

## 🏗️ Heterogeneous Agent

- Claude Code runtime, working-directory awareness, and sidebar polish.
(#13970)
- CC subagent rendering with persistent streamed text; parallel-tool
orphan fix. (#14001, #13968, #14024)
- Per-step usage persisted to each step assistant message. (#13964)
- Per-phase workflow expand defaults; full-expand toggle with
three-level expansion. (#14171, #13906)
- Hetero-mode actions bar; tool inspector polish. (#13963, #14034,
#14030)
- Codex desktop integration with rich tool rendering and devtools
preview. (#14067, #14100)
- Codex terminal error surfacing and CLI output tracing. (#14166)
- Tighten `isCanUseVision` default and add aggregator fallback. (#14172)
- Persist `ccSessionId` in topic metadata for CC multi-turn resume.
(#13902)
- CC account card, topic filter, and integration polish. (#13955,
#13942, #13950)
- Token-level deltas streamed via `--include-partial-messages`. (#13929)

---

## 🧠 Agent Signal & Self-Iteration

- New `@lobechat/agent-signal` package with dynamic feedback signals.
(#14157)
- AgentSignalRuntime wired through agent-tracing and observability-otel
metrics. (#14170, #14159)
- Self-iteration feature flag added to Lab; front-side flag check.
(#14169, #14186)
- Signal policy for receiving memory feedback dynamically. (#14187)

---

## 💬 Conversation

- Queue follow-up sends during running CC turns. (#14179)
- Persist per-topic chat scroll position; pin user message + fold long
messages. (#14191, #14056)
- Inline resend when editing last user message. (#14080)
- Disable first-block markdown streaming to prevent flicker. (#14193,
#13904)
- Prevent Markdown stream replay when vlist remounts streaming items.
(#14086)
- Stop repinning after manual scroll; unify scroll-to-user + spacer
hooks. (#14099, #14132)

---

## 📱 Platforms & Integrations

### Desktop / Electron

- Screen capture overlay, Quick Chat tray, and upload pipeline
improvements. (#13818)
- macOS permission gate for screen capture; auto-focus chat panel input.
(#14097, #14105)
- Dedicated topic popup window with cross-window sync. (#13957)
- TabBar polish: `+` button for new topic, dark theme blend, close icon
by default. (#13972, #14203, #13973)
- Recent working directories expanded from 5 to 20; submodule/worktree
repo detection. (#14036, #13978)
- Cmd+W / Cmd+T tab shortcuts and global shortcut consolidation.
(#13983, #13880)
- Linux icon configuration; human approval desktop notifications.
(#14042, #14092)

### Git Workflow

- One-click pull/push from branch chip; ahead/behind badge with
refactored GitCtr. (#14041, #13980)

### Mobile

- Full settings menu and responsive profile layout. (#14019)
- Agent route added to mobile router; mobile agent topic route
registered. (#14103, #14158)
- Session list skeleton row layout corrected. (#14040)

### Bot / Messaging

- DM strategy support; bot emoji and markdown render optimization.
(#14201, #14091, #14140)
- Slack webhook fix; bot platform setup guide reference. (#14052,
#14121)

---

## 🤖 Models & Providers

### New models

- **Claude Opus 4.7** with `xhigh` effort tier; strip temperature/top_p.
(#13903, #13909)
- **GPT-5.5**. (#14147)
- **DeepSeek V4** Flash/Pro cards with reasoning slider; cache-hit and
Pro discount pricing. (#14114, #14209, #14196, #14131)
- **Kimi K2.6** model with LobeHub-hosted card. (#14004, #14006)
- **MiMo-V2.5 / V2.5-Pro**. (#14089)
- **gpt-image-2**, **Qwen3.6 Flash/Plus**, **Pixverse-c1**. (#14039,
#13923)

### New providers

- **OpenCode Zen** and **OpenCode Go** with env-var support. (#13943,
#14064)
- **Azure OpenAI Router** runtime support. (#13823)
- Model alias mapping for image and video runtimes. (#13896)
- Seedance video models migrated to Dreamina. (#14144)

### Runtime reliability

- Sanitize invalid tool_call arguments to unbreak strict providers.
(#14033)
- Tolerate null `function.name` in streaming tool_call deltas. (#14139)
- Preserve Gemini 3 `thoughtSignature` in `call_tools_batch`
normalization. (#14032)
- Downgrade `image_url` parts when target model lacks vision. (#14029)
- Preserve Cloudflare provider error context. (#14136)
- Use `safety_identifier` for OpenAI Responses API. (#14148)
- Unwrap underlying PG error in `formatErrorEventData`. (#14038)

---

## 🖥️ User Experience

- **Onboarding** — Preset agent naming suggestions, structured hunk ops
for `updateDocument`, persona analytics snapshot, footer promotion
pipeline, wrap-up button. (#13931, #13989, #13930, #13853, #13934)
- **Document workflow** — Agent documents promoted as primary workspace
panel; history management and compare workflow; web-crawl docs
associated with agent documents. (#13924, #13725, #13893)
- **cmdk** — Agent identity surfaced on topic search results;
topic/message search scoped to current agent. (#14204, #13960)
- **Floating chat panel** and workspace improvements. (#13887)
- **Topic completion status** with dropdown action and filter. (#14005)

---

## 🔧 Tooling

- Redis-backed feature flag provider for runtime config. (#14098)
- Vite upgraded to 8.0.0 with Rolldown strict execution order. (#12720,
#14058)
- `@lobechat/model-bank` automated npm release with provenance. (#14015,
#14017, #14018)
- Skill activation fallback when `activateTools` cannot find identifier.
(#14010)
- Cron tool: timezone and existing jobs injected into system prompt;
clarified `lobe-gtd` and `lobe-cron` descriptions. (#14012, #14013)

---

## 🔒 Security & Reliability

- **Security:** uuid bumped to v14 (advisory). (#14083)
- **Security:** validate avatar URL and scope old-avatar deletion to
owner. (#13982)
- **Security:** clear OIDC sessions on better-auth signout; return 401
(not 500) for expired OIDC JWT. (#13916, #14014)
- **Reliability:** scope pending-approval check to current assistant
turn. (#14182)
- **Reliability:** sanitize heterogeneous-agent attachment cache
filenames. (#13937)
- **Reliability:** reduce subagent task status error noise. (#14026)

---

## 👥 Contributors

Huge thanks to **17 contributors** who shipped **194 merged PRs** this
week.

@hardy · @shaun0927 · @hezhijie0327 · @sxjeru · @arvinxx · @Innei ·
@tjx666 · @lijian · @neko · @rdmclin2 · @AmAzing129 · @sudongyuer ·
@CanisMinor · @rivertwilight

Plus @lobehubbot and renovate[bot] for maintenance.

---

**Full Changelog**:
v2.1.52...v2.1.53