docs: document waitForResponse recipe for deferred mutations

[jbrecht]

Closes #24.

What

Documents the page.waitForResponse(...) recipe as the reliable path for the standard Next.js App Router transition (startTransition + Server Action + router.refresh()), where settleUntil: 'networkidle' can race the deferred dispatch and settle on the pre-mutation UI.

The recipe arms the response wait before the action and awaits it after — it can't resolve until the matching request has fired and returned, closing the transition gap with no settleMs guess. Placement inside run() is required (waitFor runs too late to arm the listener).

Changes (docs-only, docs/writing-tutorials.md)

• Added the waitForResponse recipe to the deferred-mutation warning blockquote.
• Reframed the reliable options in precedence order: named DOM signal (waitFor) > known endpoint (waitForResponse) > network quiet (settleUntil: 'networkidle', now reserved for when you have neither).
• Added a waitForResponse row to the Settling table and scoped the settleUntil row accordingly, so the table and prose agree.
• Updated the settling rule-of-thumb.

Why guidance over code

Resolves #24 in favor of documentation rather than a new settleUntil: 'mutation' heuristic, per the issue's own "revisit only if the guidance proves insufficient in real authoring" framing. A request-aware heuristic would trade one subtle race (pre-mutation transient) for another (settling early on background polling, or hanging when a mutation fires no request). Consumers can drop their settleMs workarounds using the documented recipe with no release.

Review

Reviewed by the code-reviewer agent: recipe is technically sound (correct waitForResponse signature, arm-before/await-after pattern genuinely closes the gap), prose/fences/anchors clean. The one flagged consistency gap (table still steering known-endpoint cases to networkidle) was fixed before push.

🤖 Generated with Claude Code