From 4226a9135b3b83fc1143070feae1160866c7b584 Mon Sep 17 00:00:00 2001 From: GCWing Date: Wed, 30 Sep 2026 17:21:05 +0800 Subject: [PATCH] docs: document resource lifecycles and native interaction verification --- src/crates/adapters/webdriver/AGENTS.md | 6 +++++ .../modern/FLOWCHAT_HISTORY_PAGING.md | 22 +++++++++++++++++++ .../modern/FLOWCHAT_VIRTUALIZATION.md | 11 ++++++++++ .../src/infrastructure/peer-device/README.md | 10 ++++++--- src/web-ui/src/tools/editor/AGENTS.md | 16 ++++++++++++++ tests/e2e/AGENTS-CN.md | 12 ++++++++++ tests/e2e/AGENTS.md | 17 ++++++++++++++ 7 files changed, 91 insertions(+), 3 deletions(-) diff --git a/src/crates/adapters/webdriver/AGENTS.md b/src/crates/adapters/webdriver/AGENTS.md index 5cdff38ba5..92c6bde8e8 100644 --- a/src/crates/adapters/webdriver/AGENTS.md +++ b/src/crates/adapters/webdriver/AGENTS.md @@ -21,4 +21,10 @@ platform-integration crate, not a product runtime or tool-policy owner. cargo check -p openbitfun-webdriver ``` +The crate selects Tauri's raw WebView access and the PNG/JPEG codecs it uses; +focused checks must not depend on feature unification from the Desktop host. + +For reveal/focus changes, build Desktop and use the real packaged UI regression +documented in `tests/e2e/AGENTS.md` (`run-interaction-scroll.mjs`). + For documentation-only changes, run `git diff --check`. diff --git a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_HISTORY_PAGING.md b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_HISTORY_PAGING.md index 622e44d0a8..1c24fae4ae 100644 --- a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_HISTORY_PAGING.md +++ b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_HISTORY_PAGING.md @@ -1,5 +1,27 @@ # FlowChat History Paging +## Inactive history residency + +Reader bookmarks retain the semantic snapshot, intent and ordinal range, never +the Turn bodies. A mounted primary, BTW or subagent transcript holds a history +lease. The store accounts the union of canonical and paged Turns, which can alias +the same objects, in the shared reconstructable-resource budget. Derived caches +are reclaimed before inactive history when that budget is exceeded. + +Unleased local history can return to metadata-only under resource-budget pressure, +only when its Turns are unchanged persisted-read objects. Idle time alone does +not evict history; keep the warm path when resources fit the budget. Selection, +hydration, in-flight reads, runtime interactions and live or unsaved projections +prevent eviction. Relay replicas and dispatch observers keep their existing +owners. Drafts, catalogs, permission mailboxes and runtime state are outside this +cache lifecycle. + +On return, a bookmark resolves through the store's existing range reader before +the transcript paints. The viewport owner restores its semantic anchor; a cold +read never navigates to the tail as a fallback. Session, surface and navigation +generation fence the result. Failures expose retry, while stale reads may warm +the cache without replacing a newer reader intent. + ## Prepend geometry snapshot `FlowChatPrependSnapshot` captures the old DOM scroll height in React's diff --git a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIRTUALIZATION.md b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIRTUALIZATION.md index cacd10c5be..f536852278 100644 --- a/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIRTUALIZATION.md +++ b/src/web-ui/src/flow_chat/components/modern/FLOWCHAT_VIRTUALIZATION.md @@ -31,6 +31,17 @@ cancelled rounds precede it. That boundary prevents cross-round grouping from hiding the label; ordinary within-round tool folding remains available. Round ids and virtual row keys stay unchanged, with no viewport writes or mount animation. +Retry history seals the preceding collection once, while the current effective +attempt starts a new collection that can receive following model rounds. Attempt +normalization must not disable grouping for the whole round. Failed attempts stay +in their independent history disclosure and never join the current collection. +For old records, the display policy disregards an unqualified +`disableExploreGrouping` hint only when multiple recorded attempts all use the +native Runtime identity `:attempt:`. Explicit host policies carry +the optional `disableExploreGroupingSource: "host"` provenance; older hints with +unrecognized attempt identities remain authoritative. Projection never rewrites +the saved hint, attempts, or member identities. + ## Measurement compensation and cached offsets When the viewport owner accepts a shift for a measured row wholly above the diff --git a/src/web-ui/src/infrastructure/peer-device/README.md b/src/web-ui/src/infrastructure/peer-device/README.md index 82a2c0533e..ef91be22b8 100644 --- a/src/web-ui/src/infrastructure/peer-device/README.md +++ b/src/web-ui/src/infrastructure/peer-device/README.md @@ -12,9 +12,13 @@ never determines whether an accepted turn continues running. `RelaySessionHistory` owns one subscription per visible surface/session. `SessionRecordReplica` applies both replayed pages and live canonical records using stable IDs, revisions and tombstones; every page comes from the online -host, and a stream-epoch change (host restart) drops the replica before replay. Following Happy's sync owner, -the latest page paints first; older pages share one in-flight reader and are -prefetched with a yield between pages. Receive cursors advance only after applying +host, and a stream-epoch change (host restart) drops the replica before replay. +The latest page paints first; older pages share one in-flight reader. A visible +open or explicit reader request can warm one adjacent page while the document is +visible and the shared resource budget permits it. This never recursively drains +the transcript. Hiding a view pauses optional prefetch only; live records, +reconnect and interaction-mailbox delivery keep their subscriptions. +Receive cursors advance only after applying records, never from a send acknowledgement. Transport reconnect resumes that same subscription. Local Runtime projection machinery is not a second Relay content writer: peer token/body events must not overwrite canonical records. diff --git a/src/web-ui/src/tools/editor/AGENTS.md b/src/web-ui/src/tools/editor/AGENTS.md index 647392272f..eb5df728c8 100644 --- a/src/web-ui/src/tools/editor/AGENTS.md +++ b/src/web-ui/src/tools/editor/AGENTS.md @@ -30,6 +30,22 @@ This directory follows `src/web-ui/AGENTS.md`. ## Focused verification +Document-backed code editors may suspend inactive Monaco views after 30 seconds; +at most three inactive views stay warm across hosts. Visible views and active IME +composition are protected. Find/replace widgets and nonempty queries also keep +their view: Monaco does not include this interaction in `saveViewState`, and a +closed widget still owns the query used by F3. `EditorDocument` retains the exact +model, undo/redo, dirty state and saved view state. Closing a suspended view must +still support saving its model. Standalone, rich-text and Diff editors remain +resident until their state has an independently tested owner; do not rebuild a +document to save view memory. + +For view residency, also run: + +```bash +pnpm --dir src/web-ui run test:run src/tools/editor/services/editorViewResidency.test.ts src/tools/editor/components/CodeEditor.test.tsx +``` + For code editor disk synchronization, encoding reloads, and dirty-state changes: ```bash diff --git a/tests/e2e/AGENTS-CN.md b/tests/e2e/AGENTS-CN.md index 8cb873c0e7..eb887becfe 100644 --- a/tests/e2e/AGENTS-CN.md +++ b/tests/e2e/AGENTS-CN.md @@ -37,3 +37,15 @@ pnpm --dir tests/e2e exec wdio run ./config/wdio.conf.ts --spec "./specs/. ## 验证 优先运行最窄的相关 spec，必要时再扩大范围。 + +验证内置 WebDriver 的滚动、聚焦与外层布局时，先构建 Desktop 和当前前端资源，再运行： + +```bash +node tests/e2e/scripts/run-interaction-scroll.mjs +``` + +该脚本使用真实产品控件、独立的打包前端快照、临时应用存储和私有 WebView 存储，检查点击、 +指针与滚轮动作、元素截图、输入清空与填写、屏外控件定位和超大元素点击坐标。证据 `result.json` +保存在输出的临时目录；不使用 Mock 页面，也不代表远程场景或其他平台已经验证。 +并行构建时，可用 `OPENBITFUN_E2E_FRONTEND_DIR` 指向含 `frontend-revision.json` 的已完成构建快照。 +脚本也复制可执行文件；默认 exe 被开发实例锁定时，可用 `OPENBITFUN_E2E_DESKTOP_BINARY` 指向新链接的产物。 diff --git a/tests/e2e/AGENTS.md b/tests/e2e/AGENTS.md index 7f13f9e92a..8f6fcaba9e 100644 --- a/tests/e2e/AGENTS.md +++ b/tests/e2e/AGENTS.md @@ -38,6 +38,23 @@ pnpm --dir tests/e2e exec wdio run ./config/wdio.conf.ts --spec "./specs/. Prefer the narrowest relevant spec first, then broaden only if needed. +For embedded WebDriver reveal/focus and shell scroll geometry, build Desktop +and current frontend assets, then run: + +```bash +node tests/e2e/scripts/run-interaction-scroll.mjs +``` + +This runner uses real production controls, an independent packaged frontend +snapshot, temporary application storage and a private WebView store. It checks +click, pointer/wheel actions, element screenshot, input clear/send, offscreen reveal +and oversized click targets, and retains `result.json` in its printed temporary +directory. It does not use a mock page or establish remote/platform coverage. +Set `OPENBITFUN_E2E_FRONTEND_DIR` to a completed build directory with +`frontend-revision.json` to reuse an existing snapshot during concurrent builds. +The runner also snapshots the executable; `OPENBITFUN_E2E_DESKTOP_BINARY` can +select a freshly linked artifact when a development instance locks the default exe. + Markdown editor browser interaction tests (no desktop binary required): ```bash