Pre-flight checklist
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.
Pre-flight checklist
Problem or use case
Hydration-mismatch detection currently lives in
verifyHydrationas 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 blocksssrStable (#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), orerror(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
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
ssrAdditional 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
onErrorhook into the devtools bridge (#146) so mismatches are inspectable.