[post-v3 DX] Diagnose request/static Next.js stack composition mistakes

[olliethedev]

Context

Follow-up from the retained RC3 application validation in better-stack-web#37, with the failed intermediate diagnosis captured in #245.

This is a post-v3 incremental DX improvement. It must not block or reopen v3.

Friction

A real Next.js migration initially placed request-aware BTST pages and ISR pages under the same physical app/p segment/layout. The resulting symptoms did not identify the routing mistake:

1. the request-aware loader prefetched protected data successfully with session headers;
2. the plugin suspense query then refetched through the browser/static stack without headers;
3. the API returned 401;
4. React reported an authentication error, hydration failure, and client-render fallback.

That looked like a broken initialIdentity or query hydration contract and was substantial enough to produce an upstream bug report. The actual fix was the documented physical split:

app/(request)/p/...  -> createNextLayout + request-aware createNextPage
app/(static)/p/...   -> header-free static provider/ISR pages

The architecture is valid, but the failure mode is too indirect.

Proposed better alternative

Add explicit rendering intent and development-time diagnostics without breaking the RC3 helpers.

1. Add named incremental aliases or wrappers:
   • createNextRequestLayout / createNextRequestPage
   • createNextStaticLayout / createNextStaticPage
2. Brand the produced stack/layout context with rendering: "request" | "static" in development builds.
3. Detect incompatible composition where possible: a request-prefetched query rendering through a static/browser stack, a static page under a request identity layout, or different query-client identities across prefetch/provider hydration.
4. Throw one actionable development error before the suspense query runs, including the canonical route-group tree and a link to the Next integration guide.
5. Add an optional repository lint/check that can inspect app/ and flag BTST request/static pages sharing an incompatible layout segment. Runtime code cannot infer the full filesystem shape, so diagnostics and static inspection should complement each other.

Example diagnostic:

[btst/next] Request-prefetched data is rendering through a static/browser stack.
Separate request-aware and static pages into parallel route groups and ensure
createNextPage and StackProvider share the same QueryClient.

Keep createNextPage and createNextLayout as supported aliases so this ships as an incremental minor update.

Acceptance criteria

• Request and static intent is visible in the helper name or required option.
• The reproduced RC3 authenticated Next SSR refetches without request headers after hydration #245 application mistake yields an actionable BTST diagnostic rather than a generic 401/hydration fallback.
• Query-client mismatch diagnostics identify both client instances and the affected query key in development.
• The message shows the canonical (request) / (static) file tree.
• Correct request SSR, anonymous SSR, SSG, and ISR behavior remains unchanged.
• Existing RC3 helper calls remain source-compatible.
• A fixture test covers the incorrect shared-segment composition and corrected route-group split.

Relationship to existing docs work

#175 should document the correct architecture. This issue adds API affordances and diagnostics so a mistake does not require source-level debugging after the guide has been followed imperfectly.

Release boundary

Post-v3 enhancement only. Do not hold v3 publication or require an RC4 for this issue.