A local-first multi-agent app development platform, built on PenguinHarness
fix(web): close a portal panel only for scrolls that moved its trigger (#495)
Yaowei Zhengb26bbe996758
diff --git a/changelog/unreleased/2026-08-26-portal-panel-scroll-dismiss.md b/changelog/unreleased/2026-08-26-portal-panel-scroll-dismiss.mdnew file mode 100644index 00000000..c5041fee--- /dev/null+++ b/changelog/unreleased/2026-08-26-portal-panel-scroll-dismiss.md@@ -0,0 +1,17 @@+# Portal panels stay open while an unrelated container scrolls++- **Date:** 2026-08-26+- **Type:** fix+- **Scope:** `web`+- **PR:** [#495](https://github.com/Prism-Shadow/penguin-harness/pull/495)++[中文版](2026-08-26-portal-panel-scroll-dismiss.zh.md)++Every panel opened through the shared portal-panel hook — `OptionMenu`, `Select`, `InfoPopover` and the composer toolbar's context ring — closed on any scroll anywhere in the document. Clicking the context ring to watch the context fill during a streaming run closed the panel on the next chunk that arrived. These panels now close only when the scrolled container holds the panel's own trigger.++## Details++- The hook listens for `scroll` in the capture phase, because scroll events do not bubble; capture on `window` then hears every scrolling element in the page. The message list scrolls itself on every streamed chunk, and each of those scrolls closed panels anchored in the header and the composer, which had not moved.+- The dismissal is kept rather than replaced by re-positioning: the panel is placed once when it opens and does not follow its trigger, so a scroll that did move the trigger leaves the panel pointing at nothing. The hook now answers `scrollMovesAnchor` — the rule added for [the Session row's context menu](2026-08-26-context-menu-scroll-dismiss.md) — with the trigger element it already holds.+- The panel's own internal scroll still does not close it, and a window resize still closes unconditionally: a resize moves every trigger on the page at once.+- A trigger the rule cannot read (a consumer that attaches no ref) closes on any scroll, as before, so no panel can become one that scrolling never dismisses.diff --git a/changelog/unreleased/2026-08-26-portal-panel-scroll-dismiss.zh.md b/changelog/unreleased/2026-08-26-portal-panel-scroll-dismiss.zh.mdnew file mode 100644index 00000000..ef0fc4fa--- /dev/null+++ b/changelog/unreleased/2026-08-26-portal-panel-scroll-dismiss.zh.md@@ -0,0 +1,17 @@+# 无关容器滚动时浮层面板不再被关闭++- **Date:** 2026-08-26+- **Type:** fix+- **Scope:** `web`+- **PR:** [#495](https://github.com/Prism-Shadow/penguin-harness/pull/495)++[English](2026-08-26-portal-panel-scroll-dismiss.md)++经由共享浮层面板 Hook 打开的所有面板——`OptionMenu`、`Select`、`InfoPopover` 以及输入区工具栏的上下文环——只要文档中任何位置发生滚动就会关闭。流式运行期间点开上下文环观察上下文占用,下一个片段到达时面板就被关掉。现在这些面板只在发生滚动的容器包含该面板自己的触发元素时才关闭。++## 细节++- 该 Hook 在捕获阶段监听 `scroll`,因为滚动事件不冒泡;而在 `window` 上捕获就会听到页面中每一个滚动容器。消息列表在每个流式片段到达时都会自行滚动,这些滚动逐一关掉了锚定在头部与输入区、根本没有移动过的面板。+- 这里保留关闭行为,而不是改为重新定位:面板只在打开时定位一次,并不会跟随触发元素移动,因此当触发元素确实移动时,面板就会指向一个不存在的位置。Hook 现在改用 `scrollMovesAnchor`——为[会话行右键菜单](2026-08-26-context-menu-scroll-dismiss.zh.md)引入的规则——并把自己持有的触发元素交给它判断。+- 面板自身的内部滚动依旧不会关闭它;窗口尺寸变化依旧无条件关闭:一次 resize 会同时移动页面上的每一个触发元素。+- 规则读不到触发元素时(调用方没有挂上 ref)维持原状,任何滚动都会关闭面板,因此不会出现某个面板滚动永远关不掉的情况。diff --git a/packages/web/src/components/ui/info-popover.tsx b/packages/web/src/components/ui/info-popover.tsxindex 8e3ac21c..9bbccf04 100644--- a/packages/web/src/components/ui/info-popover.tsx+++ b/packages/web/src/components/ui/info-popover.tsx@@ -10,10 +10,10 @@** The panel is portaled to document.body and positioned against viewport coordinates by* usePortalPanel, so no ancestor's overflow can clip it (a modal body, a horizontally scrolling- * table) and it closes on outside click / Esc / scroll / resize. Esc there is captured and its- * propagation stopped, which is what lets one Esc dismiss this popover while an enclosing Modal- * stays open. z-[60] for the same reason OptionMenu uses it: a portaled node sits in the root- * stacking context and must clear the modal overlay's z-50.+ * table) and it closes on outside click / Esc / a scroll that moves the trigger / resize. Esc+ * there is captured and its propagation stopped, which is what lets one Esc dismiss this+ * popover while an enclosing Modal stays open. z-[60] for the same reason OptionMenu uses it:+ * a portaled node sits in the root stacking context and must clear the modal overlay's z-50.*/import { useId, useState } from "react";import type { ReactNode } from "react";diff --git a/packages/web/src/components/ui/select.tsx b/packages/web/src/components/ui/select.tsxindex 42068ef0..5380de4b 100644--- a/packages/web/src/components/ui/select.tsx+++ b/packages/web/src/components/ui/select.tsx@@ -4,7 +4,7 @@* `value` / `onChange(e.target.value)` convention. The menu is rendered via* portal to body (fixed positioning from the shared usePortalPanel hook), so it* is never clipped by a Modal or scroll container; it closes on outside click,- * Esc, scroll, or resize. Styling matches Input.+ * Esc, a scroll that moves the trigger, or resize. Styling matches Input.*/import { Children, isValidElement, useId, useState } from "react";import type { ChangeEvent, ReactNode, SelectHTMLAttributes } from "react";diff --git a/packages/web/src/components/ui/use-portal-panel.ts b/packages/web/src/components/ui/use-portal-panel.tsindex 32c68431..714127db 100644--- a/packages/web/src/components/ui/use-portal-panel.ts+++ b/packages/web/src/components/ui/use-portal-panel.ts@@ -7,14 +7,27 @@** Positioned once on expand: opens upward if there isn't enough room below and* there's more room above, and the left edge is clamped within the viewport.- * Closes on: outside click / Esc / any scroll / window resize. Esc uses capture- * and stops propagation — Modal also listens for Esc during the window bubble- * phase and registers earlier, so without stopping propagation it would close- * both the panel and the dialog together; scroll likewise uses capture (scroll- * doesn't bubble), and the panel collapses directly the moment its position- * would go stale from scrolling, rather than leaving it floating out of place.+ * Closes on: outside click / Esc / a scroll that moved the trigger / window+ * resize. Esc uses capture and stops propagation — Modal also listens for Esc+ * during the window bubble phase and registers earlier, so without stopping+ * propagation it would close both the panel and the dialog together; scroll+ * likewise uses capture (scroll doesn't bubble), and the panel collapses+ * directly the moment its position would go stale from scrolling, rather than+ * leaving it floating out of place.+ *+ * "That moved the trigger" is not a nicety. Capture on `window` hears every+ * scrolling element in the document, and the panel took each one as a reason to+ * close — so a chat pane auto-following a streaming reply closed the context+ * ring's panel, which sits in the composer toolbar over content that never moved,+ * on every chunk that arrived. `scrollMovesAnchor` (lib/context-menu.ts, shared with the context+ * menu's own dismissal) decides which scrolls those are, from the trigger this+ * hook already holds. Closing rather than re-positioning stays the behavior: the+ * panel is placed once and does not follow its trigger, so a scroll that DID move+ * it leaves the panel pointing at nothing. A trigger the rule cannot see closes,+ * as before — the panel must never become one that no scroll dismisses.*/import { useEffect, useLayoutEffect, useRef, useState } from "react";+import { scrollMovesAnchor } from "../../lib/context-menu";export interface PortalPanelPosition {topPx?: number;@@ -84,8 +97,13 @@ export function usePortalPanel({// The panel's own internal scroll (when the list exceeds max-h) must not trigger a close: only scrolling of an outer container invalidates the position.const onScroll = (e: Event) => {if (panelRef.current?.contains(e.target as Node)) return;+ // ...and only a container that actually holds the trigger moved the position this+ // panel was placed against; the rest of the document's scrollers did not.+ if (!scrollMovesAnchor(e.target as Node | null, triggerRef.current)) return;onCloseRef.current();};+ // A resize moves every trigger on the page at once, so it closes with no ownership+ // test — the asymmetry with the scroll above is deliberate.const onResize = () => onCloseRef.current();window.addEventListener("mousedown", onPointerDown);window.addEventListener("keydown", onKey, true);diff --git a/packages/web/src/features/chat/context-gauge.tsx b/packages/web/src/features/chat/context-gauge.tsxindex 6038e014..916f37b0 100644--- a/packages/web/src/features/chat/context-gauge.tsx+++ b/packages/web/src/features/chat/context-gauge.tsx@@ -31,8 +31,9 @@** The panel is portaled to document.body and positioned against viewport coordinates by* usePortalPanel, so the composer's own overflow cannot clip it, and it closes on outside click /- * Esc / scroll / resize. It opens upward on its own: the composer sits at the bottom of the page,- * so there is never room below.+ * Esc / a scroll that moves the ring itself / resize — the message list scrolling under a+ * streaming reply leaves it open. It opens upward on its own: the composer sits at the bottom of+ * the page, so there is never room below.*/import { useEffect, useId, useState } from "react";import { createPortal } from "react-dom";@@ -193,7 +194,9 @@ function ContextPanel({unknown: boolean;}) {// A snapshot taken when the panel opens (it only mounts while open), not a live counter: the- // endpoint re-reads a whole Trace shard, and the panel closes on any scroll anyway.+ // endpoint re-reads a whole Trace shard, so polling it through a streaming run is not free.+ // The figures in the header above stay live — they come from the ring's own props — so what+ // holds still is the composition breakdown, for as long as the panel is left open.const [state, setState] = useState<PanelState>({ status: "loading" });// Row id under the pointer — a part key, or `tool:<name>` for the ranking below. One piece of// state for both lists, so a hovered tool row cannot also dim the bar it has no segment in.diff --git a/packages/web/test/portal-panel-dismiss.test.ts b/packages/web/test/portal-panel-dismiss.test.tsnew file mode 100644index 00000000..849483e0--- /dev/null+++ b/packages/web/test/portal-panel-dismiss.test.ts@@ -0,0 +1,90 @@+/**+ * Scroll dismissal for the shared portal panel (src/components/ui/use-portal-panel.ts),+ * which OptionMenu, Select, InfoPopover and the composer toolbar's context ring all open through.+ *+ * The panel listens for scroll in the capture phase because scroll does not bubble, and the+ * price of capture on `window` is that it hears every scrolling element in the document. The+ * rule that closes a panel whose position has gone stale must therefore ask whether the+ * scrolled container holds this panel's trigger — otherwise a chat pane auto-following a+ * streaming reply closes a panel opened in the composer toolbar, over content that never+ * moved.+ *+ * `scrollMovesAnchor` itself is exercised in context-menu.test.ts; what cannot be reached+ * from a node-only suite (`environment: "node"`, no jsdom) is the wiring, and the wiring is+ * where this silently breaks: the rule is answered with the trigger element, so a consumer+ * that never attaches `triggerRef` hands it a null owner and quietly gets the old+ * close-on-any-scroll behavior back for its own panel. So the scan below discovers the+ * hook's consumers rather than listing them, and a fifth one is covered on the day it is+ * written.+ */+import { readdirSync, readFileSync, statSync } from "node:fs";+import { join } from "node:path";+import { fileURLToPath } from "node:url";+import { describe, expect, it } from "vitest";++const SRC = fileURLToPath(new URL("../src", import.meta.url));+const HOOK = join(SRC, "components", "ui", "use-portal-panel.ts");++/** Every .ts/.tsx under src, as absolute paths (required-mark.test.ts convention). */+function sourceFiles(dir = SRC, out: string[] = []): string[] {+ for (const name of readdirSync(dir)) {+ const path = join(dir, name);+ if (statSync(path).isDirectory()) sourceFiles(path, out);+ else if (/\.tsx?$/.test(name)) out.push(path);+ }+ return out;+}++/** The body of a handler declared as `const <name> = ...` up to its closing `};`. */+function handler(src: string, name: string): string {+ const body = new RegExp(`const ${name} = [\\s\\S]*?\\n {4}\\};`).exec(src);+ expect(body, `${name} should be declared in use-portal-panel.ts`).not.toBeNull();+ return body![0];+}++describe("use-portal-panel scroll dismissal", () => {+ const hook = readFileSync(HOOK, "utf8");++ it("asks whether the scroll moved this panel's trigger before closing", () => {+ const onScroll = handler(hook, "onScroll");+ expect(onScroll).toMatch(/if \(!scrollMovesAnchor\(/);+ // The trigger is the owner: the panel is placed against that element's box, so a scroll+ // that did not move it did not invalidate the position.+ expect(onScroll).toContain("triggerRef.current");+ });++ it("still exempts the panel's own internal scroll", () => {+ // A long list scrolling inside the panel must not close the panel around it — the guard+ // that does this predates the ownership test and has to survive it.+ expect(handler(hook, "onScroll")).toContain("panelRef.current?.contains(");+ });++ it("leaves a resize closing unconditionally, because it moves every trigger at once", () => {+ const onResize = /const onResize = .*/.exec(hook);+ expect(onResize).not.toBeNull();+ expect(onResize![0]).toContain("onCloseRef.current()");+ expect(onResize![0]).not.toContain("scrollMovesAnchor");+ });+});++describe("use-portal-panel consumers", () => {+ /** Files that open a panel through the hook — the hook's own module excluded. */+ const consumers = sourceFiles().filter(+ (path) => path !== HOOK && readFileSync(path, "utf8").includes("usePortalPanel({"),+ );++ it("finds the call sites the rule has to cover, including the reported one", () => {+ // A scan that silently matched nothing would pass every assertion below. The context+ // ring is the panel the failure was reported against: it is opened to watch the context+ // fill while a run streams, which is exactly when the message list scrolls itself.+ expect(consumers.length).toBeGreaterThanOrEqual(4);+ expect(consumers).toContain(join(SRC, "features", "chat", "context-gauge.tsx"));+ });++ it("each attaches the hook's triggerRef, so the ownership test has an element to read", () => {+ const missing = consumers+ .filter((path) => !readFileSync(path, "utf8").includes("ref={triggerRef}"))+ .map((path) => path.slice(SRC.length + 1));+ expect(missing).toEqual([]);+ });+});