Opus finding
Middleware comment claims headers merge with route handler responses, but Next.js middleware does not merge response headers with downstream handlers
lowdocs-gapmedium
- apps/web/middleware.ts:8-11
The comment asserts that middleware-set headers are merged with what route handlers return. In Next.js, headers set on `NextResponse.next()` are forwarded with the request to the downstream handler and become response headers, but they don't unconditionally 'merge' — a downstream handler can override or replace them, and the merge semantics depend on `NextResponse.next({ headers })` vs `response.headers.set`. Using `response.headers.set` on the returned NextResponse.next() applies them to the response sent to the client, which is what the author wants — but the comment's claim that the merge happens with whatever the route handler returns is misleading: if a route handler sets the same header, the route handler's value wins (or vice versa depending on order). This is a doc/comment risk only; behavior is correct enough for the listed examples, but the explanation could mislead future maintainers about override precedence.
Recommendation
Clarify the comment to state that these headers are appended to the response chain via `NextResponse.next()` and that route handlers may override them by setting the same header in their own Response. Optionally, add an integration test confirming that /receipts.rss Content-Type wins over any middleware-applied Content-Type (none is applied here, but worth asserting).