Files
PaperClipAI/tests/perf
DottaandClaude Opus 5.5 8c0c7c6abb perf(ui): load the @task mention pool after the task page settles; add a cold-load perf spec (#21557)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - People often open a task by its URL, for example from a link in a
message or after a reload
> - #20592 made a hard load of a task URL read the chat's first frame
from one `chat-bootstrap` request
> - The task page still sends a large read as it mounts: 100 full
recently updated tasks for the `@task` mention picker. On staging this
read returned 395 KB and took 3.9 s of server time
> - The hosted database is CPU-bound, so reads that do not affect the
first frame must not compete with the reads that do
> - Also, no test measured a cold direct load under realistic latency or
guarded the one-bootstrap request shape
> - This pull request starts the mention pool after the task page
settles. It also adds a cold-load perf spec with a delay on each API
request and an always-on request-shape test
> - The benefit is less concurrent server work during a cold task open,
and a regression guard for the one-round-trip first frame

## Linked Issues or Issue Description

Refs #20592 (hard-load chat bootstrap that this pull request measures
and guards). Refs #20355 (the `chat-bootstrap` endpoints).

**What existing behavior does this improve?**
The task page loads the `@task` mention pool when it mounts.

**Subsystem affected**
Board UI task page (`ui/src/pages/IssueDetail.tsx`) and the issue-detail
perf harness (`tests/perf/issue-detail`).

**Current behavior**
`GET /api/companies/:id/issues?limit=100&sortField=updated&sortDir=desc`
starts with the chat's first-frame reads. It starts before the first
chat frame in 14 of 14 local cold loads. The picker needs it only after
the person types `@`.

**Proposed behavior**
The read starts after the page has painted and its own reads have
finished. On a page that keeps reading, it starts after at most 5 s.

**Reason and benefit**
The read never affects the first frame. Deferring it removes a large
concurrent read from the busiest part of a cold open.

**Breaking changes**
None. If the person types `@task` in the first moments after a cold
load, the task suggestions can appear about half a second later.

## What Changed

- `ui/src/hooks/usePageSettled.ts`: new hook. It returns `true` once
`whenPageSettles` runs (the page has painted, the tab is visible, no
query is fetching, and the browser is idle), or after
`PAGE_SETTLED_MAX_WAIT_MS` (5 s). The cap keeps a long-running read from
keeping the picker empty.
- `ui/src/pages/IssueDetail.tsx`: the mention-pool query is enabled only
when `usePageSettled()` is true.
- `ui/src/hooks/usePageSettled.test.tsx`: tests that the hook waits for
in-flight reads and that the cap applies.
- `ui/src/pages/IssueDetail.test.tsx`: mocks the hook to `true`, so
existing tests keep their behavior.
- `tests/perf/issue-detail/cold-bootstrap.perf.spec.ts`: new spec. It
delays every API response (300 ms by default) and opens the task URL in
a new browser context, with the JavaScript in the HTTP cache and no app
storage. The finish event is the first readable frame: the history is
revealed, the latest saved message is visible and the composer is
editable.
- The request-shape test always runs. It requires one `chat-bootstrap`
request and no per-endpoint first-frame read before the frame. Reads
that start after the live socket is created are excluded, because they
are its catch-up refresh.
- The benchmark runs only when `PAPERCLIP_ISSUE_PERF_COLD_RUNS` is set.
It writes the median, the spread, the request count before the frame,
the last requests before the frame, the JavaScript bytes transferred and
a request timeline.
- The delay uses CDP `Fetch` interception instead of Playwright routing,
because routing disables the HTTP cache.
- `tests/perf/issue-detail/README.md`: documents the spec.
- My earlier draft also added a deadline for a stalled bootstrap. Master
already has one (`CHAT_BOOTSTRAP_SHARE_DEADLINE_MS`, 5 s), so this pull
request does not include it.

## Verification

Measurement setup:
- Production UI builds of master `4a78124a3e` and of this branch, served
by one local server (`PAPERCLIP_UI_DEV_MIDDLEWARE=false`, embedded
PostgreSQL).
- A delay of 300 ms on each API request.
- Cold direct task URL with 24 saved comments and a plan.
- Master and the branch alternated: 2 rounds of 7 runs each.
- The host was shared with other agent sessions.

| Build | Runs | First readable frame, median | p25–p75 | Min–max | API
requests before frame (median) | Mention pool started before frame |
|---|---:|---:|---:|---:|---:|---:|
| master | 14 | 1,422 ms | 1,336–1,525 | 1,284–7,398 | 50 | 14 / 14 |
| this branch | 14 | 1,390 ms | 1,338–1,457 | 1,272–2,207 | 49 | 0 / 14
|

- The spec adds the API delay through CDP request interception, so the
HTTP cache stays on. The measured loads downloaded 0 KiB of JavaScript
in every run. The spec records this as `jsTransferBytes`. Each build has
one outlier (7,398 ms on master, 2,207 ms on this branch), from host
contention.
- With this branch, the mention pool starts after the frame in every run
(350–400 ms after it in an earlier set).
- The first-frame timing is neutral locally. The local database answers
the pool read in milliseconds, so it does not compete with other reads.
The intended benefit is lower concurrent server load on a busy database.
This pull request does not show it as a local latency gain.
- On master and on this branch, the hard load adopts the bootstrap and
the frame is no longer held by task reads. The frame now comes right
after the shell reads return: `auth/get-session` and
`instance/settings/experimental`, then `companies` and
`workspace-preferences/me`. Profiling marks confirm this: the chat
thread mounts after `workspace-preferences/me` returns, and all
readiness gates are ready within 30 ms.
- The request-shape test passed 5 of 5 on master and 5 of 5 on this
branch.
- `layout-stability.spec.ts`, `plan-startup.spec.ts` and
`cold-bootstrap.perf.spec.ts` against this branch's build: 18 passed.
- `ui` Vitest for `usePageSettled.test.tsx` and `IssueDetail.test.tsx`:
278 passed. The `ui` typecheck passed. `pnpm check:token-gates` passed.
- `pnpm verify` exits 2 because `tests/perf/issue-detail/README.md` is a
global CI input. Required CI supplies the broad coverage.

To reproduce the measurement:

```sh
PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:3287 PAPERCLIP_ISSUE_PERF_COLD_RUNS=7 PAPERCLIP_ISSUE_PERF_LABEL=branch \
  pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts cold-bootstrap -g benchmark
```

## Risks

- Low risk. The only product change is when one read starts.
- If the page keeps a query in flight, the pool waits up to 5 s. During
that time, `@task` suggestions list only agents, projects and members.
- The request-shape test treats reads that start after the live socket
is created as catch-up refreshes. If the socket connects before the task
page mounts, such a test would not see a first-frame read that started
later. The test still requires exactly one bootstrap request before the
frame.
- The perf spec is not in the default CI browser suites. It runs when
the issue-detail harness runs.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used in Claude Code
with tool use (shell, file editing, Playwright browser runs). It wrote
the change, the tests and the measurements.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 22:30:03 -06:00
..