From 5615da921165562367f33ccde2f527a8e9ea4cc6 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive>
Date: Sun, 24 May 2026 13:14:01 +0200
Subject: [PATCH] terminal: tail pill above floating chrome + autoscroll fix
 (#375)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two bugs on the agent terminal page after the #362 overhaul:

## 1. `↓ N new` pill clipped by the composer

The fixed-overlay composer (z-index 30, agent.css) sits in the
root stacking context. The pill — `position: absolute` inside
`.live.terminal` with no z-index — defaults to its document-order
position in the body's stacking order, which the composer covers.

Fix: bump `.agent-main .tail-pill { z-index: 35 }` so the pill
participates in the root stacking context above the composer.
Scoped to the agent-page overlay layout — the shared `.tail-pill`
rule stays untouched (the dashboard's in-page layout doesn't need
the bump).

## 2. Autoscroll-on-new-message not firing when the operator was
   already at the bottom

`afterAppend()` in terminal.js was calling `isNearBottom()` AFTER
appending the new row. The new row's own height is already in
`scrollHeight` at that point, so for any row taller than the
NEAR_BOTTOM_PX threshold (48px — easily passed by a multi-line
message body, a tool-result summary, a markdown block), the check
returns false and the pill shows + scroll stays put.

Fix: capture `wasNearBottom = isNearBottom()` BEFORE the
`log.appendChild(...)` in each of `row` / `details` /
`detailsDiff`, pass it into `afterAppend(wasNearBottom)`. Now the
auto-scroll triggers whenever the operator was visually at the
bottom an instant before the row landed, regardless of the new
row's height.

Same shared `@hive/shared/terminal.js` is used by the dashboard
+ per-agent UI + the upcoming /flow.html page, so both pages
inherit the fix.

## Validation

`npm run build` clean.

Bundle deltas: shared terminal bundle re-inlined into both consumers
unchanged in size (the wasNearBottom variable is a single bool, no
measurable delta). Agent CSS +0.1kb (z-index property).

Browser smoke test isn't possible from inside iris's container —
worth eyeballing post-deploy:
  - With the operator scrolled to bottom, a tall message lands and
    the view scrolls to keep it visible (instead of pinning the
    pill).
  - The pill appears above the composer when the operator is
    scrolled up and new messages land.

Closes #375.
---
 frontend/packages/agent/src/agent.css    |  5 ++++-
 frontend/packages/shared/src/terminal.js | 21 ++++++++++++++++-----
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/frontend/packages/agent/src/agent.css b/frontend/packages/agent/src/agent.css
index 6222bcb..64ed0fc 100644
--- a/frontend/packages/agent/src/agent.css
+++ b/frontend/packages/agent/src/agent.css
@@ -548,9 +548,12 @@ pre.diff {
   overflow: auto;
 }
 /* Tail pill (↓ N new): nudged up so it floats clear of the composer
-   rather than colliding with the frosted bar. */
+   rather than colliding with the frosted bar. z-index bumped above
+   the composer (z-30) so the pill sits on the top layer instead of
+   being clipped by the floating chrome (issue #375). */
 .agent-main .tail-pill {
   bottom: calc(var(--agent-composer-h) + 0.6em);
+  z-index: 35;
 }
 
 /* Composer chrome — used to live inside `.terminal-wrap`; now lives
diff --git a/frontend/packages/shared/src/terminal.js b/frontend/packages/shared/src/terminal.js
index 0726a8c..1c350ff 100644
--- a/frontend/packages/shared/src/terminal.js
+++ b/frontend/packages/shared/src/terminal.js
@@ -88,8 +88,16 @@ export function create(opts) {
   log.addEventListener('scroll', () => {
     if (isNearBottom()) { unseen = 0; updatePill(); }
   });
-  function afterAppend() {
-    if (currentNoAnim || isNearBottom()) {
+  // Auto-scroll decision uses the PRE-append scroll position
+  // (issue #375). Checking after the append underestimates
+  // "nearness" because the new row's own height has already pushed
+  // `scrollHeight - scrollTop - clientHeight` past the threshold,
+  // even when the user was visually at the bottom an instant ago.
+  // Each row/details/detailsDiff captures `nearBottomBeforeAppend`
+  // and hands it to afterAppend so the auto-scroll triggers
+  // whenever the operator was at the bottom when the row landed.
+  function afterAppend(wasNearBottom) {
+    if (currentNoAnim || wasNearBottom) {
       log.scrollTop = log.scrollHeight;
     } else {
       unseen += 1;
@@ -112,15 +120,17 @@ export function create(opts) {
   }
   function row(cls, text) {
     clearPlaceholder();
+    const wasNearBottom = isNearBottom();
     const e = document.createElement('div');
     e.className = 'row ' + (cls || '') + (currentNoAnim ? ' no-anim' : '');
     e.appendChild(linkify(text));
     log.appendChild(e);
-    afterAppend();
+    afterAppend(wasNearBottom);
     return e;
   }
   function details(cls, summary, body) {
     clearPlaceholder();
+    const wasNearBottom = isNearBottom();
     const d = document.createElement('details');
     d.className = 'row ' + (cls || '') + (currentNoAnim ? ' no-anim' : '');
     const s = document.createElement('summary');
@@ -131,11 +141,12 @@ export function create(opts) {
     pre.appendChild(linkify(body));
     d.appendChild(pre);
     log.appendChild(d);
-    afterAppend();
+    afterAppend(wasNearBottom);
     return d;
   }
   function detailsDiff(cls, summary, body) {
     clearPlaceholder();
+    const wasNearBottom = isNearBottom();
     const d = document.createElement('details');
     d.className = 'row ' + (cls || '') + (currentNoAnim ? ' no-anim' : '');
     const s = document.createElement('summary');
@@ -153,7 +164,7 @@ export function create(opts) {
     }
     d.appendChild(pre);
     log.appendChild(d);
-    afterAppend();
+    afterAppend(wasNearBottom);
     return d;
   }