Skip to content

[Feature]: Guaranteed hydration correctness — graduate mismatch handling past dev-only warnings #130

Description

@JosunLP

Pre-flight checklist

  • I searched existing issues and did not find a duplicate request.
  • I explained the problem or use case, not just the desired API.

Problem or use case
Hydration-mismatch detection currently lives in verifyHydration as dev-only warnings. In production a mismatch silently yields a wrong or broken UI with no recovery path, which is exactly the failure mode teams need guarantees against before trusting SSR. "Dev-only warnings" is not a stability contract, so this blocks ssr Stable (#127).

Proposed solution
Add a production hydration-mismatch strategy: detect mismatches at hydrate time and offer configurable recovery — warn (dev default), repair (re-render the affected boundary from client state), or error (surface to an error boundary). Provide a stable, documented definition of what constitutes a mismatch and ensure detection covers the directives made SSR-capable in #128. Keep the production path lightweight (boundary-scoped, not whole-document).

Possible API or UX shape

import { hydrate } from "@bquery/bquery/ssr";

hydrate(root, {
  onMismatch: "repair",          // "warn" | "repair" | "error"
  onError: (err, boundary) => reportToDevtools(err, boundary)
});

Alternatives considered
Relying on authors to keep server and client output identical by discipline — fragile, and undermined today by the directive subset in #128. Whole-document re-render on any mismatch — rejected as a performance cliff; boundary-scoped repair is the React/Svelte-aligned approach.

Relevant area
ssr

Additional context
React 19 and Svelte both treat hydration mismatches as first-class with defined recovery; matching that is table stakes for production SSR. Wire the onError hook into the devtools bridge (#146) so mismatches are inspectable.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ssrChanges to the ssr module

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions