deer-flow/docs/superpowers/specs/2026-07-31-frontend-performance-remediation-design.md

# Frontend performance remediation — design

## Background

A production-oriented audit identified seventeen performance risks across the
default DeerFlow web deployment. The audit was originally performed against an
older `main`, so this design starts from a source re-audit of
`origin/main@17461ee5` rather than treating the old findings as immutable.

Upstream has already improved three parts of the original report:

- render-facing stream messages are coalesced to an 80 ms budget and the main
  history/live/optimistic merge is memoized;
- processing groups build tool-result and browser-view indexes once instead of
  scanning the group for every tool call;
- binary artifacts are served with `FileResponse`, including byte-range support.

Those changes are preserved. The remaining work is one comprehensive PR made
of independently reviewable commits, with a measurement and regression gate
after each slice.

## Goals

1. Fix every still-reproducible item from the seventeen-item audit rather than
   only the easiest P0 subset.
2. Bound network bytes, client bundle bytes, retained DOM, repeated stream
   computation, animation work, browser-frame copies, artifact preview memory,
   and mock-route filesystem work.
3. Preserve chat ordering, streaming semantics, history pagination, anchored
   scrolling, locale behavior, artifact downloads, Browser Live control, and
   the default Docker/local deployment topology.
4. Add deterministic tests or executable measurements for every fix so later
   changes cannot silently restore the same cost.
5. Deliver the work as one PR whose commits can be reviewed and reverted by
   subsystem.

## Non-goals

- Replacing LangGraph, Streamdown, Nextra, CodeMirror, or the existing query
  layer.
- Changing model, sandbox, agent, or scheduler behavior.
- Optimizing third-party hosted deployments that bypass DeerFlow's bundled
  nginx; the default nginx/Next deployment is the delivery contract here.
- Claiming a performance win from source shape alone. Production build output
  and runtime measurements are required.

## Current finding matrix

| # | Audit topic | Current status on `17461ee5` | Planned disposition |
|---|---|---|---|
| 1 | No explicit gzip/Brotli in bundled nginx | Reproduced | Add portable gzip for compressible static/document responses while excluding SSE and already-compressed media; test the generated nginx config and live headers. |
| 2 | Full-history work on every stream chunk | Partially fixed upstream | Keep the 80 ms render coalescer, then make grouping, usage, and human-input derivation reuse an immutable prefix and recompute only the active tail. Compare incremental results with the existing full derivation in tests. |
| 3 | Loaded message history is not virtualized | Reproduced | Add turn-level dynamic-height windowing with anchored prepend and overscan; keep the active streaming turn mounted. |
| 4 | No component-level code splitting | Reproduced | Lazy-load settings, inactive settings sections, Browser Live, artifact preview/editor, and other interaction-only heavy surfaces. |
| 5 | Docs/blog carry excessive shared dependencies | Needs current production measurement; source risk remains | Establish a fresh route asset baseline, remove workspace-only providers/styles from the root layout, and enforce route budgets. |
| 6 | Root locale cookie makes the whole site dynamic | Reproduced | Make the root layout static; move cookie-aware locale providers to auth/workspace and keep public locale resolution route-owned. |
| 7 | Streaming Markdown repeatedly parses growing text | Reproduced | Align reveal updates to the stream render budget, eliminate the per-animation-frame parse loop, and keep cheap streaming code rendering until the block settles. |
| 8 | Focus can refetch every loaded history page | Reproduced | Disable focus refetch for immutable paged history and explicitly invalidate/refetch on run lifecycle events. |
| 9 | Tool lookup and `steps.indexOf` produce quadratic work | Partially fixed upstream | Preserve the new lookup maps; replace remaining repeated `steps.indexOf(...)` calls with indexed conversion metadata. |
| 10 | Code blocks run and retain two Shiki renders | Reproduced | Lazy-load Shiki and produce one dual-theme CSS-variable rendering, with request/result caching and stale-effect protection. |
| 11 | Below-fold landing case-study images load eagerly | Reproduced | Replace CSS backgrounds with optimized lazy images, correct responsive sizes, and retain the card overlay/hover behavior. |
| 12 | Galaxy and Magic Bento do offscreen/unthrottled work | Reproduced | Pause on invisibility/document hide, honor reduced motion, and coalesce pointer work to one animation frame. |
| 13 | Browser Live uses JSON + base64 + React state per frame | Reproduced | Send JPEGs as binary WebSocket messages, use revocable object URLs, and present only the latest frame per paint. Keep JSON for control metadata. |
| 14 | Text artifact preview reads/renders the full file | Partially fixed upstream | Serve text through range-capable responses, request a bounded preview first, show truncation/load-full affordances, and avoid mounting CodeMirror for oversized previews. |
| 15 | Chat lists render every loaded row in two surfaces | Reproduced | Share normalized query data, virtualize the full chats page, and bound the sidebar to a recent/pinned window with explicit older-chat navigation. |
| 16 | Global styles/translations/background queries are too broad | Reproduced | Scope Markdown/KaTeX/Nextra styles by route, avoid shipping both locale payloads where possible, and mount queries only with their visible feature surface. |
| 17 | Mock API uses synchronous IO and dynamic project tracing | Reproduced | Use async cached reads and a deterministic demo-thread manifest so request handling and output tracing do not scan the project tree. |

## Design

### 1. Reproducible performance baseline and budgets

Add a repository script that builds the production frontend and reports, per
representative route, the transitive first-load JavaScript and CSS from Next's
build manifests. The representative routes are:

- `/`
- `/login`
- `/workspace/chats`
- `/workspace/chats/<fixture-id>`
- `/en/docs`
- `/blog/posts`

The script writes no tracked build artifact. It prints stable JSON plus a human
summary and can compare against a checked-in budget file. Budgets are set only
after the fresh `origin/main` baseline is captured; the PR must improve the
audited routes and may not regress an unrelated route beyond a small explicit
tolerance. A second smoke check starts the production stack and records
`Content-Encoding`, `Cache-Control`, and transferred bytes for HTML, JS, CSS,
JSON, and SSE samples.

Long-thread and large-artifact fixtures provide runtime gates:

- a synthetic history with hundreds of heterogeneous turns;
- a continuously growing Markdown answer with code, math, and citations;
- a multi-megabyte UTF-8 artifact;
- a burst of Browser Live JPEG frames.

Unit tests pin bounded derivation and protocol behavior; browser measurements
record DOM node count, rendered turn count, and frame URL cleanup.

### 2. Delivery, static rendering, and route ownership

The bundled nginx enables gzip for HTML, JavaScript, CSS, JSON, XML, and SVG.
It does not gzip `text/event-stream`, fonts, images, video, archives, or other
already-compressed payloads. Proxy buffering remains disabled for streaming
routes. A config test and a live header smoke test prevent an apparently valid
directive from being placed in the wrong nginx context.

The top-level Next layout becomes request-invariant:

- it owns only document structure, the theme provider, and truly global CSS;
- it does not call `cookies()`;
- Streamdown and KaTeX styles move to the layouts that render rich content;
- landing navigation uses the public default locale, docs derive locale from
  their explicit `[lang]` segment, and blog keeps its own locale selection;
- auth and workspace layouts read the locale cookie and mount `I18nProvider`.

The client provider receives only the selected locale from its server layout
and synchronizes `document.documentElement.lang` when the workspace/auth locale
changes. Translation dictionaries include formatter functions and therefore
cannot cross the React Server Component serialization boundary. The
interactive auth/workspace provider deliberately owns both small dictionaries
so switching language remains immediate, while public landing, docs, and blog
routes resolve one route-owned locale without mounting that provider. This
retains the existing language switch behavior without making public routes
dynamically rendered or putting both dictionaries in every route bundle.

### 3. Bundle boundaries

Interaction-only code must not be reachable from the initial workspace chunk.
The workspace root keeps only a small settings-store listener. The settings
dialog is imported after it opens, and each settings page is imported only when
selected. Browser Live, artifact code/preview tooling, and CodeMirror language
packages are loaded only when their panels and modes are used.

Shiki is loaded through an async highlighter boundary instead of a static
top-level import. One Shiki call emits light and dark token variables in one DOM
tree; theme changes are CSS-only. A bounded cache keys on code, language, line
number mode, and highlighter configuration. Effects ignore stale resolutions
when code changes or the component unmounts.

The baseline script verifies that docs/blog no longer inherit workspace-only
chunks and that a closed settings/artifact/browser surface contributes no
interaction-only chunk to initial workspace loading.

### 4. Bounded chat rendering and derivation

Message virtualization happens at the existing `ThreadMessageGroup` boundary,
not individual tool steps. A small headless `@tanstack/react-virtual` adapter
owns dynamic measurements, overscan, and stable identity keys while the
existing conversation component remains the scroll owner. The newest streaming
group is always in the render window. Prepending an older history page
preserves the visual anchor; bottom-follow behavior continues only when the
user was already pinned to the bottom. Selection, edit/regenerate controls,
human-input cards, artifact links, and run-duration anchors remain inside their
current group. A dependency-size comparison is part of the bundle gate; if the
adapter would break the workspace route budget, the same interface is
implemented locally rather than accepting an initial-load regression.

Full derivation remains the reference algorithm. A new incremental adapter
stores the settled group prefix and recomputes only from the earliest message
whose identity/content/run metadata changed. Tests feed append, in-place stream
mutation, tool result, reasoning, history prepend, checkpoint replacement,
summarization bridge, edit/regenerate, and hidden human-input sequences through
both algorithms and require identical groups.

Turn usage, run-duration anchors, workspace-change anchors, and human-input
state use the same stable-prefix boundary or keyed indexes. The active tail may
change every 80 ms, but historical turns are not rescanned. Remaining
`steps.indexOf(...)` calls are removed by attaching the index while steps are
created.

Paged history uses `refetchOnWindowFocus: false` and a nonzero stale window.
Run finish, stop, regenerate, edit-and-regenerate, and explicit refresh remain
authoritative invalidation points.

### 5. Streaming Markdown

The SDK/coalescer's 80 ms snapshot is the upper-frequency source of renderable
content. The current smooth-reveal hook must not turn one snapshot into a new
full Markdown parse on every animation frame. It will reveal at the same bounded
cadence (or render the coalesced snapshot directly when the delta is small),
while Streamdown's visual animation handles appearance without creating extra
source strings.

Incomplete code blocks continue to use the cheap streaming `<pre>/<code>`
components. Shiki, Mermaid, and other expensive settled rendering activates
only after the relevant block/turn is stable. DOM tests cover cancellation,
rapid target replacement, incomplete fences/lists, reduced motion, and the
final exact content.

### 6. Landing visuals

Case-study cards use `next/image` with `fill`, responsive `sizes`, and lazy
loading. Only genuinely above-the-fold media can be priority-loaded. Source
images may be re-encoded if doing so materially lowers bytes without visible
quality loss; generated files remain deterministic and are compared in the
route transfer report.

Galaxy owns a visibility state derived from `IntersectionObserver`, document
visibility, and `prefers-reduced-motion`. Its RAF exists only while rendering is
allowed. Magic Bento listens for pointer movement only while its section is
active and coalesces geometry reads/writes to one RAF. Both components cancel
pending work and animations on cleanup. Tests use mocked RAF/observers to prove
that offscreen, hidden, reduced-motion, and unmounted states perform no frames.

### 7. Browser Live binary frame path

Browser session capture returns JPEG bytes rather than base64 text. The updated
client requests `frame_format=binary` in the WebSocket URL. The gateway keeps
its bounded lossy frame queue and sends frame entries with
`WebSocket.send_bytes`; URL, tab, rejection, and input messages remain JSON
text. Connections without the capability retain the legacy base64 JSON frame
for rolling-deployment compatibility. The new protocol is self-demultiplexing
by WebSocket message type and does not add an extra binary header.

The client treats binary messages as blobs, keeps only the newest pending frame,
and publishes at most one object URL per animation frame. Replaced and unmounted
URLs are revoked. JSON parsing is performed only for text messages. The static
artifact screenshot fallback and all input/control behavior stay unchanged.
Backend tests cover capability negotiation, byte delivery, the legacy fallback,
queue dropping, metadata text frames, auth, and disconnect cleanup; frontend
tests cover coalescing and URL revocation.

### 8. Bounded artifact previews

Active content remains download-only and binary media remains range-streamed.
Regular text artifacts move to a range-capable inline `FileResponse` path. The
frontend initially asks for a fixed byte range and reads response metadata to
distinguish complete from truncated content. It shows file size and a clear
"Load full file" action when truncated; download always returns the original
file.

The 1 MiB preview limit is owned by the frontend, while the shared HTTP Range
contract lets both regular files and bounded archive members honor it. The
preview handles an incomplete UTF-8 tail safely, and tests cover ASCII,
multibyte boundary, empty, exact-limit, oversized, skill-archive, active, and
binary files. Large text opens in the lightweight preview first; CodeMirror is
not instantiated until content is within its safe budget or the user explicitly
loads the full file.

### 9. Conversation lists, queries, and mock data

`useInfiniteThreads` remains the single cache. A shared selector deduplicates
and sorts pages once so the sidebar and chats page do not repeat normalization.
The full chats page uses fixed/dynamic row virtualization. The sidebar renders a
bounded recent window plus all pinned entries, and routes users to the full
page for older conversations instead of silently auto-loading/rendering an
unbounded list.

Channel/provider, scheduler, and other feature queries mount only with their
visible page/panel. Locale payloads are route-scoped: public routes own one
selected locale, while the interactive auth/workspace boundary owns both for
instant switching. Route-scoped CSS is verified in the build manifest rather
than inferred from import location.

Mock route handlers use promise-based filesystem APIs and a cached,
deterministically generated demo-thread manifest. The workspace redirect and
thread search do not call `readdirSync` or dynamically construct project-wide
paths at request time. A manifest consistency test fails if demo fixtures are
added or removed without regeneration.

## Error handling and compatibility

- Performance fallbacks preserve content: a failed lazy import shows the
  existing surface error boundary; a failed bounded preview offers download;
  unsupported binary Browser Live frames fall back to the latest static
  screenshot.
- No user-authored content is moved into `dangerouslySetInnerHTML` beyond the
  existing Shiki output boundary.
- WebSocket auth, origin, and exact thread-owner checks remain before session
  acquisition.
- Range requests do not weaken the active-content download policy or path
  traversal validation.
- Reduced work must not hide persisted history, discard a Browser Live control
  event, or change the final streamed Markdown text.

## Implementation and commit slices

The single PR is implemented in this order:

1. Baseline/budget tooling and failing regression tests.
2. Nginx compression, static root ownership, route CSS/locale split, landing
   image delivery.
3. Lazy bundle boundaries and single-pass Shiki.
4. Incremental chat derivation, history query policy, message/chat
   virtualization, and bounded Markdown cadence.
5. Visibility-aware landing effects and binary Browser Live frames.
6. Range-bounded text artifact previews and async/cached mock data.
7. Documentation, production build comparison, full frontend/backend checks,
   and review fixes.

Each behavior change follows red-green-refactor. Commits remain independently
testable, but the PR description reports the aggregate before/after result and
maps every audit item to its evidence.

## Verification and completion gate

The PR is not complete until all of the following are true:

- every row in the seventeen-item matrix has a code change or current evidence
  proving that no change is required;
- focused unit/DOM/backend tests pass and demonstrate their initial failure;
- `cd frontend && pnpm check`, `pnpm test`, and `pnpm build` pass;
- relevant Playwright suites pass for streaming, history prepend, settings,
  artifacts, and Browser Live;
- backend artifact/browser tests, the blocking-IO gate for changed async code,
  Ruff lint, and format checks pass;
- nginx configuration validation and live compression/SSE smoke checks pass;
- production route asset/transfer budgets pass and the before/after report is
  included in the PR;
- source review, automated review, PR review threads, and CI contain no
  unresolved actionable finding.

An absence of review comments is not sufficient by itself: the final audit must
walk this matrix and attach authoritative evidence for each row.