René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[Feature]: Promote `ssr` to Stable — freeze public API and define exit criteria","articleBody":"**Pre-flight checklist**\n- [x] I searched existing issues and did not find a duplicate request.\n- [x] I explained the problem or use case, not just the desired API.\n\n**Problem or use case**\n`ssr` is one of the three modules still marked **Experimental**, yet it is foundational to bQuery's \"one stack, client and server\" promise — teams cannot commit production SSR on a surface that may break between minors. The module's surface has churned across consecutive releases (`flushBoundary`, `createSSRCache`, `createSSRMetrics`, `createEdgeHandler` landed in 1.11.0; cache-aware `renderToResponse` and multi-chunk `renderToStream` evolved again by 1.14.0). There is no published checklist for what would move `ssr` out of Experimental, so adopters have no signal for when it is safe to depend on.\n\n**Proposed solution**\nDefine and publish concrete exit criteria for `ssr`, then freeze the public API for at least one full minor cycle to demonstrate stability. Criteria should cover: (a) a frozen, documented export surface; (b) a stated minimum test-coverage bar including streaming, suspense streaming, island hydration, and edge-handler paths; (c) resolution of the dependent capability gaps tracked in tickets #128, #129, and #130; (d) a documented SSR support matrix per runtime (Node ≥ 24, Bun, Deno, edge). This ticket is the tracking issue; #128–#130 are the substantive prerequisites.\n\n**Possible API or UX shape**\nNo new public API is required for the freeze itself. The deliverable is a \"Stability\" subsection in the SSR guide:\n\n```\n## Stability: targeting Stable in 1.15.0\nExit criteria:\n- [ ] Public exports frozen for one minor (no additive breaking changes)\n- [ ] Directive parity resolved or boundary documented (#128)\n- [ ] Resumability model finalized (#129)\n- [ ] Hydration-mismatch handling productionized (#130)\n- [ ] Per-runtime support matrix published\nFrozen surface: renderToString, renderToStream, renderToStreamSuspense, defer,\nrenderToResponse, createSSRCache, createSSRMetrics, createEdgeHandler,\nhydrateOnVisible|Idle|Interaction|Media, createResumableState\n```\n\n**Alternatives considered**\nLeaving `ssr` Experimental indefinitely while it accretes features — rejected because the competitive frameworks (SvelteKit, Nuxt, React 19 SSR) all offer production-grade SSR, and an Experimental label is the single biggest blocker to bQuery being evaluated for real apps. Promoting without a freeze period — rejected because it would violate the module's own semver promise.\n\n**Relevant area**\n`ssr`\n\n**Additional context**\nThe SSR guide currently lists `renderToString` support for only `bq-text, bq-html, bq-if, bq-show, bq-for, bq-class, bq-style, bq-bind:*`, and `createResumableState()` is described as \"a tiny key/value collector\" — both are tracked as prerequisites below. Competitive baseline: React 19 shipped stable Server Components and streaming SSR in December 2024; SvelteKit and Nuxt offer mature SSR with file-based data loading.\n","author":{"url":"https://github.com/JosunLP","@type":"Person","name":"JosunLP"},"datePublished":"2026-06-26T21:24:22.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/127/bQuery/issues/127"}