Skip to content

Improve terminal panel page-load performance - #1101

Merged
ymichael merged 3 commits into
mainfrom
bb/single-thread-page-load-analysis-thr_s7kyv63gjh
Aug 6, 2026
Merged

ymichael merged 3 commits into
mainfrom
bb/single-thread-page-load-analysis-thr_s7kyv63gjh

Conversation

@ymichael

@ymichael ymichael commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • keep terminal queries, xterm, and the terminal WebSocket inactive while the secondary panel is closed
  • preserve persisted terminal tabs while their session query is intentionally unloaded
  • register xterm's WebGL renderer before opening the terminal, with a safe DOM fallback when WebGL is unavailable or loses its context

Performance

Measured with dev-browser 0.2.9 against the worktree dev server using an isolated fixture containing the original thread's 1,576 events and a 3,000-line terminal replay.

Profile Layout work Longest xterm animation frame TBT
Open, DOM-renderer control 1,452.5 ms 719.6 ms 1,215 ms
Open, WebGL renderer 197.7 ms 26.5 ms 360 ms
Closed 203.4 ms None 349 ms

The open-panel path reduces layout work by 86% and the xterm frame stall by 96%. The closed-panel trace creates no terminal API request, terminal WebSocket, or xterm DOM.

Browsers without WebGL2 continue to work through xterm's DOM renderer, but retain its previous replay cost.

Validation

  • pnpm exec vitest run --config vitest.config.ts src/components/thread/terminal/ThreadTerminalView.test.ts src/components/thread/terminal/ThreadTerminalContent.test.tsx
  • pnpm exec turbo run typecheck --filter=@bb/app
  • pnpm exec turbo run build --filter=@bb/app
  • targeted ESLint: zero errors (one pre-existing set-state-in-effect warning)

@SawyerHood

Copy link
Copy Markdown
Collaborator

🚨 SLOP COP 🚨 · review

I am the SlopCop. I am reviewing this pull request for security, code quality, performance, architecture, duplication, and end-to-end behavior.

Stack: #1101 only.

I will post a comment after each review phase. I will not approve or request changes.

@SawyerHood

Copy link
Copy Markdown
Collaborator

🚨 SLOP COP 🚨 · review

Code-quality and architecture phase complete.

I found two medium risks:

  • The optional WebGL import shares a required Promise.all. An import failure stops all terminal setup.
  • Compact layouts use persisted panel state for list queries. A hidden drawer can still fetch terminal sessions.

The codebase scan found no useful shared abstraction that this pull request should reuse. I will include verified findings in the final review.

@SawyerHood

Copy link
Copy Markdown
Collaborator

🚨 SLOP COP 🚨 · review

Security phase complete.

I found no separate security defect. The change does not alter a server or daemon contract. Terminal message validation and link routing stay unchanged.

The WebGL package has no runtime dependencies. Its lock integrity matches the registry. Terminal replay and xterm scrollback keep their existing limits.

@SawyerHood

Copy link
Copy Markdown
Collaborator

🚨 SLOP COP 🚨 · review

Performance phase complete.

The wide closed-panel path now avoids terminal queries, xterm creation, and WebSocket creation. WebGL also reduces layout work for an open terminal.

The compact layout still starts terminal list queries when stored panel state stays open and the drawer is hidden. The new visible-state input can also change clean-terminal closure behavior on compact layouts.

@SawyerHood

Copy link
Copy Markdown
Collaborator

🚨 SLOP COP 🚨 · review

End-to-end phase complete on top pull request #1101.

I started the documented dev server and used the real browser UI. I selected a project, opened the right panel, and started a terminal.

The terminal worked when WebGL2 was unavailable. The DOM fallback displayed the shell. Closing the panel removed xterm.

After a reload with the panel closed, the app made no terminal API request. The full app suite also passed: 318 files and 2,376 tests.

@SawyerHood SawyerHood left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚨 SLOP COP 🚨 · review

I found two medium-severity issues.

  1. The optional WebGL import is part of the required import group. A failed WebGL chunk stops terminal startup instead of using the DOM renderer.
  2. Compact layouts still fetch terminal sessions for a hidden drawer. The query gates use persisted state instead of actual drawer visibility.

I found no separate security issue. I found no useful duplicate implementation or required architecture refactor.

Validation passed:

  • The production build passed.
  • The app type check passed.
  • All 318 app test files passed.
  • All 2,376 app tests passed.
  • The browser test opened and closed a real terminal.
  • The browser used the DOM fallback when WebGL2 was unavailable.
  • A closed wide panel made no terminal API request after reload.

This is a comment-only review. I did not approve or request changes.

@ymichael

ymichael commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator Author

Follow-up in df2318d98: pinned the latest mutually compatible xterm beta set (@xterm/xterm 6.1.0-beta.292, WebGL 0.20.0-beta.291, fit 0.12.0-beta.292, web-links 0.13.0-beta.292) to pick up xtermjs/xterm.js#5529. GPU resize A/B on the large-thread fixture: the stable bundle produced a fully blank terminal frame during a 180-frame panel drag capture; the beta capture retained rendered terminal text throughout, stayed on WebGL, and had zero context losses. Validation: 2,378 app tests, app typecheck, production build, and frozen-lockfile install all pass.

@ymichael
ymichael force-pushed the bb/single-thread-page-load-analysis-thr_s7kyv63gjh branch from df2318d to 454ee19 Compare August 6, 2026 22:33
@ymichael
ymichael merged commit 0149612 into main Aug 6, 2026
@ymichael
ymichael deleted the bb/single-thread-page-load-analysis-thr_s7kyv63gjh branch August 6, 2026 22:38
amadad pushed a commit to amadad/bb that referenced this pull request Aug 14, 2026
## Summary

- keep terminal queries, xterm, and the terminal WebSocket inactive
while the secondary panel is closed
- preserve persisted terminal tabs while their session query is
intentionally unloaded
- register xterm's WebGL renderer before opening the terminal, with a
safe DOM fallback when WebGL is unavailable or loses its context

## Performance

Measured with `dev-browser` 0.2.9 against the worktree dev server using
an isolated fixture containing the original thread's 1,576 events and a
3,000-line terminal replay.

| Profile | Layout work | Longest xterm animation frame | TBT |
| --- | ---: | ---: | ---: |
| Open, DOM-renderer control | 1,452.5 ms | 719.6 ms | 1,215 ms |
| Open, WebGL renderer | 197.7 ms | 26.5 ms | 360 ms |
| Closed | 203.4 ms | None | 349 ms |

The open-panel path reduces layout work by 86% and the xterm frame stall
by 96%. The closed-panel trace creates no terminal API request, terminal
WebSocket, or xterm DOM.

Browsers without WebGL2 continue to work through xterm's DOM renderer,
but retain its previous replay cost.

## Validation

- `pnpm exec vitest run --config vitest.config.ts
src/components/thread/terminal/ThreadTerminalView.test.ts
src/components/thread/terminal/ThreadTerminalContent.test.tsx`
- `pnpm exec turbo run typecheck --filter=@bb/app`
- `pnpm exec turbo run build --filter=@bb/app`
- targeted ESLint: zero errors (one pre-existing `set-state-in-effect`
warning)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants