From 49fd4e6dbf2de3fd2ffd9368c4bfb2dec3ca1c0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Best?= <github@francoisbest.com>
Date: Fri, 26 Jun 2026 20:29:10 +0200
Subject: [PATCH 1/8] doc: version-gate unreleased content so production
 deploys from next

nuqs.dev deploys from `master` only to keep unreleased-feature docs out of
production. Gating that content inline by the published npm version lets
`next` become the single deploy source and ends the cherry-pick churn
between branches.
---
 packages/docs/content/docs/adapters.mdx       |  8 +-
 packages/docs/content/docs/installation.mdx   |  5 +-
 packages/docs/content/docs/options.mdx        |  2 +
 packages/docs/mdx-components.tsx              |  2 +
 packages/docs/src/app/styles/tweaks.css       | 18 ++++
 .../src/components/feature-support-matrix.tsx | 63 +++++++++---
 .../docs/src/components/sidebar-footer.tsx    | 23 +----
 .../docs/src/components/since-version.tsx     | 90 +++++++++++++++++
 packages/docs/src/lib/get-llm-text.ts         | 17 +++-
 .../docs/src/lib/published-version.test.ts    | 97 +++++++++++++++++++
 packages/docs/src/lib/published-version.ts    | 68 +++++++++++++
 .../docs/src/lib/strip-unreleased.test.ts     | 86 ++++++++++++++++
 packages/docs/src/lib/strip-unreleased.ts     | 51 ++++++++++
 13 files changed, 493 insertions(+), 37 deletions(-)
 create mode 100644 packages/docs/src/components/since-version.tsx
 create mode 100644 packages/docs/src/lib/published-version.test.ts
 create mode 100644 packages/docs/src/lib/published-version.ts
 create mode 100644 packages/docs/src/lib/strip-unreleased.test.ts
 create mode 100644 packages/docs/src/lib/strip-unreleased.ts

diff --git a/packages/docs/content/docs/adapters.mdx b/packages/docs/content/docs/adapters.mdx
index ad9108833..9547875e4 100644
--- a/packages/docs/content/docs/adapters.mdx
+++ b/packages/docs/content/docs/adapters.mdx
@@ -23,7 +23,7 @@ wrapping it with a `NuqsAdapter{:ts}` context provider:
 - <Remix className='inline mr-1.5' role="presentation" /> [Remix](#remix)
 - <ReactRouter className='inline mr-1.5' role="presentation" /> [React Router v6](#react-router-v6)
 - <ReactRouter className='inline mr-1.5' role="presentation" /> [React Router v7](#react-router-v7)
-- <ReactRouter className='inline mr-1.5' role="presentation" /> [React Router v8](#react-router-v8)
+- <SinceVersion v="2.9.0" disclaimer="inline"><ReactRouter className='inline mr-1.5' role="presentation" /> [React Router v8](#react-router-v8)</SinceVersion>
 - <TanStackRouter className='inline mr-1.5 not-prose' role="presentation"/> [TanStack Router](#tanstack-router)
 </HumanContent>
 
@@ -34,7 +34,9 @@ wrapping it with a `NuqsAdapter{:ts}` context provider:
 - [Remix](#remix)
 - [React Router v6](#react-router-v6)
 - [React Router v7](#react-router-v7)
+<SinceVersion v="2.9.0">
 - [React Router v8](#react-router-v8)
+</SinceVersion>
 - [TanStack Router](#tanstack-router)
 </LLMContent>
 
@@ -247,6 +249,8 @@ export default function App() {
 }
 ```
 
+<SinceVersion v="2.9.0">
+
 ## <HumanContent><ReactRouter className='inline mr-2 -mt-1' role="presentation"/></HumanContent>React Router v8 [#react-router-v8]
 
 ```tsx title="app/root.tsx"
@@ -275,6 +279,8 @@ export default function App() {
 
 </Callout>
 
+</SinceVersion>
+
 ## <HumanContent><TanStackRouter className='inline mr-2 -mt-1 not-prose' role="presentation"/></HumanContent>TanStack Router [#tanstack-router]
 
 ```tsx title="src/routes/__root.tsx"
diff --git a/packages/docs/content/docs/installation.mdx b/packages/docs/content/docs/installation.mdx
index ef2e020db..2dc08c2b9 100644
--- a/packages/docs/content/docs/installation.mdx
+++ b/packages/docs/content/docs/installation.mdx
@@ -37,7 +37,7 @@ npm install nuqs
 - <Remix className='inline mr-1.5' role="presentation" /> [Remix](/docs/adapters#remix): `@remix-run/react@^2`
 - <ReactRouter className='inline mr-1.5' role="presentation" /> [React Router v6](/docs/adapters#react-router-v6): `react-router-dom@^6`
 - <ReactRouter className='inline mr-1.5' role="presentation" /> [React Router v7](/docs/adapters#react-router-v7): `react-router@^7`
-- <ReactRouter className='inline mr-1.5' role="presentation" /> [React Router v8](/docs/adapters#react-router-v8): `react-router@^8`
+- <SinceVersion v="2.9.0" disclaimer="inline"><ReactRouter className='inline mr-1.5' role="presentation" /> [React Router v8](/docs/adapters#react-router-v8): `react-router@^8`</SinceVersion>
 - <TanStackRouter className='inline mr-1.5 not-prose' role="presentation"/> [TanStack Router](/docs/adapters#tanstack-router): `@tanstack/react-router@^1`
 </HumanContent>
 
@@ -47,6 +47,9 @@ npm install nuqs
 - [Remix](/docs/adapters#remix): `@remix-run/react@^2`
 - [React Router v6](/docs/adapters#react-router-v6): `react-router-dom@^6`
 - [React Router v7](/docs/adapters#react-router-v7): `react-router@^7`
+<SinceVersion v="2.9.0">
+- [React Router v8](/docs/adapters#react-router-v8): `react-router@^8`
+</SinceVersion>
 - [TanStack Router](/docs/adapters#tanstack-router): `@tanstack/react-router@^1`
 </LLMContent>
 
diff --git a/packages/docs/content/docs/options.mdx b/packages/docs/content/docs/options.mdx
index 01dcaa42e..17603ae79 100644
--- a/packages/docs/content/docs/options.mdx
+++ b/packages/docs/content/docs/options.mdx
@@ -404,6 +404,7 @@ adapter prop:
 </NuqsAdapter>
 ```
 
+<SinceVersion v="2.9.0">
 <Callout title="Don't break the Back button" type="warn">
 Setting `history: 'push'{:ts}` globally will add a new entry to the navigation
 history for **every** search param update across your whole app, which is likely
@@ -413,6 +414,7 @@ Prefer opting into `history: 'push'{:ts}` on a per-hook or per-call basis, only
 where the search params contribute to a navigation-like experience (eg: tabs,
 modals).
 </Callout>
+</SinceVersion>
 
 ### Processing `URLSearchParams`
 
diff --git a/packages/docs/mdx-components.tsx b/packages/docs/mdx-components.tsx
index 019371ae9..6144f5e59 100644
--- a/packages/docs/mdx-components.tsx
+++ b/packages/docs/mdx-components.tsx
@@ -1,5 +1,6 @@
 import { HumanContent, LLMContent } from '@/src/components/audience'
 import { FeatureSupportMatrix } from '@/src/components/feature-support-matrix'
+import { SinceVersion } from '@/src/components/since-version'
 import { Callout } from 'fumadocs-ui/components/callout'
 import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
@@ -23,6 +24,7 @@ const components = {
   FeatureSupportMatrix,
   HumanContent,
   LLMContent,
+  SinceVersion,
   Suspense,
   Tab,
   Tabs,
diff --git a/packages/docs/src/app/styles/tweaks.css b/packages/docs/src/app/styles/tweaks.css
index dc5670ede..11c65a1f7 100644
--- a/packages/docs/src/app/styles/tweaks.css
+++ b/packages/docs/src/app/styles/tweaks.css
@@ -13,6 +13,24 @@
     margin-left: -5.5px;
     margin-right: 5.5px;
   }
+
+  /*
+    Inline "visible from" cue for unreleased content shown on preview/local
+    (see <SinceVersion disclaimer="inline">). Rendered as a ::after pseudo-element
+    so it never fragments the host markdown list the way a block wrapper would.
+  */
+  .nuqs-since-version::after {
+    content: ' (visible from nuqs@' attr(data-since) ')';
+    @apply text-zinc-500 dark:text-zinc-400;
+    font-size: 0.85em;
+  }
+
+  /* Collapse a list item whose only content is a hidden inline gate (production),
+     so it leaves no stray bullet. The gate's marker is targeted via :has() because
+     the emptied <li> retains whitespace/comment nodes and so is not :empty. */
+  .prose li:has(> .nuqs-gated-empty) {
+    display: none;
+  }
 }
 
 /* Center-align copy button in code blocks with single line */
diff --git a/packages/docs/src/components/feature-support-matrix.tsx b/packages/docs/src/components/feature-support-matrix.tsx
index da6c2a319..8178f09fd 100644
--- a/packages/docs/src/components/feature-support-matrix.tsx
+++ b/packages/docs/src/components/feature-support-matrix.tsx
@@ -1,3 +1,4 @@
+import { getPublishedVersion, isReleased } from '@/src/lib/published-version'
 import { cn } from '@/src/lib/utils'
 import { Callout } from 'fumadocs-ui/components/callout'
 import { CheckCircle, XCircle } from 'lucide-react'
@@ -80,7 +81,7 @@ export function renderFeatureSupportMatrixText(
   return sentences.join(' ')
 }
 
-export function FeatureSupportMatrix({
+export async function FeatureSupportMatrix({
   introducedInVersion,
   deprecatedInVersion,
   highlightUnsupported = false,
@@ -92,22 +93,17 @@ export function FeatureSupportMatrix({
     includeAllFrameworksSupport: true
   })
   const unsupportedLabel = getUnsupportedFrameworksText(notSupportedIn)
+  const released = isReleased(introducedInVersion, await getPublishedVersion())
 
   return (
-    <Callout
-      type={deprecatedInVersion ? 'warning' : 'success'}
-      className="pr-1"
-    >
+    <Callout type={calloutTone(released, deprecatedInVersion)} className="pr-1">
       <div className="flex flex-wrap gap-4">
         <span className="text-balance">
-          Introduced in version <strong>{introducedInVersion}</strong>
-          {deprecatedInVersion ? (
-            <>
-              , and deprecated in version <strong>{deprecatedInVersion}</strong>
-            </>
-          ) : (
-            '.'
-          )}
+          <VersionLine
+            introducedInVersion={introducedInVersion}
+            deprecatedInVersion={deprecatedInVersion}
+            released={released}
+          />
         </span>
         {!hideFrameworks && (
           <div className="not-prose ml-auto flex items-center gap-1 text-xl">
@@ -207,6 +203,47 @@ export function FeatureSupportMatrix({
   )
 }
 
+function calloutTone(
+  released: boolean,
+  deprecatedInVersion?: string
+): 'info' | 'warning' | 'success' {
+  if (!released) {
+    return 'info'
+  }
+  return deprecatedInVersion ? 'warning' : 'success'
+}
+
+function VersionLine({
+  introducedInVersion,
+  deprecatedInVersion,
+  released
+}: Pick<
+  FeatureSupportMatrixProps,
+  'introducedInVersion' | 'deprecatedInVersion'
+> & { released: boolean }) {
+  if (!released) {
+    return (
+      <>
+        Coming in version <strong>{introducedInVersion}</strong> — not yet
+        released.
+      </>
+    )
+  }
+  if (deprecatedInVersion) {
+    return (
+      <>
+        Introduced in version <strong>{introducedInVersion}</strong>, and
+        deprecated in version <strong>{deprecatedInVersion}</strong>
+      </>
+    )
+  }
+  return (
+    <>
+      Introduced in version <strong>{introducedInVersion}</strong>.
+    </>
+  )
+}
+
 function parseSupportFrameworks(markdown: string): 'all' | Frameworks[] {
   const frameworksValue = markdown.match(/frameworks:\s*('all'|"all"|\[[\s\S]*?\])/)
     ?.[1]
diff --git a/packages/docs/src/components/sidebar-footer.tsx b/packages/docs/src/components/sidebar-footer.tsx
index ab4533c1a..f47f4eb5a 100644
--- a/packages/docs/src/components/sidebar-footer.tsx
+++ b/packages/docs/src/components/sidebar-footer.tsx
@@ -1,13 +1,7 @@
-'use client'
+import { getPublishedVersion } from '@/src/lib/published-version'
 
-import { useEffect, useState } from 'react'
-
-export function SidebarFooter() {
-  const [version, setVersion] = useState<string | null>(null)
-  useEffect(() => {
-    getLatestVersion().then(setVersion).catch(console.error)
-  }, [])
-  if (!version) return null
+export async function SidebarFooter() {
+  const version = await getPublishedVersion()
   return (
     <footer className="ml-2 flex w-full items-baseline gap-2 text-zinc-600 dark:text-zinc-400">
       <a
@@ -20,14 +14,3 @@ export function SidebarFooter() {
     </footer>
   )
 }
-
-async function getLatestVersion() {
-  try {
-    const res = await fetch('https://registry.npmjs.org/nuqs').then(r =>
-      r.json()
-    )
-    return res['dist-tags'].latest
-  } catch {
-    return 'latest'
-  }
-}
diff --git a/packages/docs/src/components/since-version.tsx b/packages/docs/src/components/since-version.tsx
new file mode 100644
index 000000000..1791c447b
--- /dev/null
+++ b/packages/docs/src/components/since-version.tsx
@@ -0,0 +1,90 @@
+import { getPublishedVersion, isReleased } from '@/src/lib/published-version'
+import type { ReactNode } from 'react'
+
+type SinceVersionProps = {
+  v: string
+  /**
+   * How the preview cue is rendered. `block` (default) wraps the content in a
+   * dashed-border fieldset; `inline` renders a `::after` pseudo-element instead,
+   * for gating a single item without breaking its host list.
+   */
+  disclaimer?: 'block' | 'inline'
+  children?: ReactNode
+}
+
+/**
+ * Gates documentation for a feature introduced in nuqs version `v`.
+ *
+ * - In production the content renders only once `v` has shipped to the published
+ *   GA; before that it is hidden.
+ * - On preview & local deployments everything renders with a cue marking what
+ *   won't be live in production yet: a dashed-border fieldset for `block`
+ *   gates, or an inline `::after` note for `inline` gates.
+ *
+ * The LLM outputs are gated separately at the Markdown layer (see
+ * `stripUnreleased`), so this component only governs the HTML docs.
+ */
+export async function SinceVersion({
+  v,
+  disclaimer = 'block',
+  children
+}: SinceVersionProps) {
+  const published = await getPublishedVersion()
+  const released = isReleased(v, published)
+  const isPreview = process.env.VERCEL_ENV !== 'production'
+
+  if (released) {
+    if (isPreview) {
+      warnStaleGate(v, published)
+    }
+    return <>{children}</>
+  }
+
+  // Unreleased in production: hide it. An inline gate renders a marker so its
+  // host <li> can be collapsed via CSS — a list item emptied by a null child
+  // keeps whitespace/comment nodes, so it is not `:empty`. A block gate just
+  // renders nothing.
+  if (!isPreview) {
+    return disclaimer === 'inline' ? (
+      <span className="nuqs-gated-empty" hidden />
+    ) : null
+  }
+
+  // Preview & local: show the unreleased content with a cue. The inline cue is a
+  // ::after pseudo-element (see tweaks.css) so it never fragments a host list.
+  if (disclaimer === 'inline') {
+    return (
+      <span className="nuqs-since-version" data-since={v}>
+        {children}
+      </span>
+    )
+  }
+
+  return (
+    <fieldset className="my-4 rounded-xl border border-dashed border-zinc-400/60 px-4 pb-1 dark:border-zinc-600">
+      <legend className="not-prose px-2 text-sm text-zinc-500 dark:text-zinc-400">
+        Visible from <code className="text-xs">nuqs@{v}</code>
+      </legend>
+      {children}
+    </fieldset>
+  )
+}
+
+const warnedStaleGates = new Set<string>()
+
+/**
+ * Nudge (preview & local only, deduped per version) when a gate has shipped and
+ * is now a no-op, so it can be cleaned up. Reached only on the non-production
+ * passthrough branch above.
+ */
+function warnStaleGate(v: string, published: string) {
+  if (warnedStaleGates.has(v)) {
+    return
+  }
+  warnedStaleGates.add(v)
+  console.warn(
+    `[SinceVersion] nuqs@${v} has shipped (latest: ${published}). This gate is ` +
+      `now a no-op: search the docs content for <SinceVersion v="${v}"> and ` +
+      `remove each wrapper, keeping its inner content.`
+  )
+}
diff --git a/packages/docs/src/lib/get-llm-text.ts b/packages/docs/src/lib/get-llm-text.ts
index 272f71011..e75e2564c 100644
--- a/packages/docs/src/lib/get-llm-text.ts
+++ b/packages/docs/src/lib/get-llm-text.ts
@@ -3,6 +3,8 @@ import {
   parseFeatureSupportMatrixProps,
   renderFeatureSupportMatrixText
 } from '@/src/components/feature-support-matrix'
+import { getPublishedVersion, isPublished } from './published-version'
+import { stripUnreleased } from './strip-unreleased'
 import { github } from './utils'
 
 export const llmFooter = `---
@@ -64,7 +66,10 @@ function stripAuthoringImports(markdown: string) {
   return output.join('\n')
 }
 
-function stripFeatureSupportMatrix(markdown: string) {
+function stripFeatureSupportMatrix(
+  markdown: string,
+  isVisible: (version: string) => boolean
+) {
   const lines = markdown.split('\n')
   const output: string[] = []
   const matrixLines: string[] = []
@@ -76,6 +81,9 @@ function stripFeatureSupportMatrix(markdown: string) {
     if (!props) {
       return ''
     }
+    if (!isVisible(props.introducedInVersion)) {
+      return ''
+    }
     return renderFeatureSupportMatrixText(props)
   }
 
@@ -124,9 +132,14 @@ function stripFeatureSupportMatrix(markdown: string) {
 
 export async function getLLMText(page: Page) {
   const processed = await page.data.getText('processed')
+  const published = await getPublishedVersion()
+  const isVisible = (version: string) => isPublished(version, published)
 
   // Collapse 3+ consecutive newlines to 2 (removes extra blank lines from removed content)
-  const normalized = stripFeatureSupportMatrix(stripAuthoringImports(processed))
+  const normalized = stripFeatureSupportMatrix(
+    stripUnreleased(stripAuthoringImports(processed), isVisible),
+    isVisible
+  )
     .replace(/\n{3,}/g, '\n\n')
     // Strip Fumadocs inline code syntax highlighting hints (e.g. `code{:ts}` -> `code`)
     .replace(/`([^`]+)\{:\w+\}`/g, '`$1`')
diff --git a/packages/docs/src/lib/published-version.test.ts b/packages/docs/src/lib/published-version.test.ts
new file mode 100644
index 000000000..1d7fc9c23
--- /dev/null
+++ b/packages/docs/src/lib/published-version.test.ts
@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  getPublishedVersion,
+  isPublished,
+  isReleased
+} from './published-version.ts'
+
+describe('isReleased', () => {
+  it('is true when the introduced version equals the published version', () => {
+    expect(isReleased('2.9.0', '2.9.0')).toBe(true)
+  })
+
+  it('is false when the introduced version is newer than the published one', () => {
+    expect(isReleased('2.9.0', '2.8.0')).toBe(false)
+  })
+
+  it('is true when the introduced version is older than the published one', () => {
+    expect(isReleased('2.4.0', '2.9.0')).toBe(true)
+  })
+
+  it('compares numerically, not lexically (2.10.0 is newer than 2.9.0)', () => {
+    expect(isReleased('2.10.0', '2.9.0')).toBe(false)
+    expect(isReleased('2.9.0', '2.10.0')).toBe(true)
+  })
+
+  it('compares the patch segment', () => {
+    expect(isReleased('2.9.1', '2.9.0')).toBe(false)
+    expect(isReleased('2.9.0', '2.9.1')).toBe(true)
+  })
+})
+
+describe('isPublished', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it('gates unreleased content in production', () => {
+    vi.stubEnv('VERCEL_ENV', 'production')
+    expect(isPublished('2.9.0', '2.8.0')).toBe(false)
+  })
+
+  it('shows unreleased content on preview deployments', () => {
+    vi.stubEnv('VERCEL_ENV', 'preview')
+    expect(isPublished('2.9.0', '2.8.0')).toBe(true)
+  })
+
+  it('shows unreleased content on local dev (VERCEL_ENV unset)', () => {
+    vi.stubEnv('VERCEL_ENV', undefined)
+    expect(isPublished('2.9.0', '2.8.0')).toBe(true)
+  })
+
+  it('still shows released content in production', () => {
+    vi.stubEnv('VERCEL_ENV', 'production')
+    expect(isPublished('2.4.0', '2.9.0')).toBe(true)
+  })
+})
+
+describe('getPublishedVersion', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('returns the latest dist-tag from the npm registry', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ 'dist-tags': { latest: '2.8.9' } })
+      })
+    )
+    await expect(getPublishedVersion()).resolves.toBe('2.8.9')
+  })
+
+  it('throws on a non-ok registry response (fail loud)', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 503,
+        statusText: 'Service Unavailable',
+        json: async () => ({})
+      })
+    )
+    await expect(getPublishedVersion()).rejects.toThrow(/npm/i)
+  })
+
+  it('throws when the response is missing dist-tags.latest (fail loud)', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ 'dist-tags': {} })
+      })
+    )
+    await expect(getPublishedVersion()).rejects.toThrow(/dist-tags\.latest/)
+  })
+})
diff --git a/packages/docs/src/lib/published-version.ts b/packages/docs/src/lib/published-version.ts
new file mode 100644
index 000000000..bab51d1f4
--- /dev/null
+++ b/packages/docs/src/lib/published-version.ts
@@ -0,0 +1,68 @@
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/nuqs'
+
+/**
+ * The latest GA version of nuqs published on npm.
+ *
+ * Resolved once at build (`force-cache`, no time-based revalidation) and frozen
+ * into the statically generated output, so the docs reveal newly-released
+ * content only on the next deployment. Throws on a registry failure to fail the
+ * build loudly — leaving the current deployment up — rather than ship a docs
+ * site gated against a wrong version.
+ */
+export async function getPublishedVersion(): Promise<string> {
+  const response = await fetch(NPM_REGISTRY_URL, { cache: 'force-cache' })
+  if (!response.ok) {
+    throw new Error(
+      `Failed to resolve the latest nuqs version from npm (${response.status} ${response.statusText})`
+    )
+  }
+  const { 'dist-tags': distTags } = (await response.json()) as {
+    'dist-tags'?: { latest?: string }
+  }
+  if (!distTags?.latest) {
+    throw new Error('npm registry response is missing dist-tags.latest for nuqs')
+  }
+  return distTags.latest
+}
+
+/**
+ * Whether a feature introduced in `version` has shipped to the published GA.
+ * Pure and environment-agnostic — the production-truth check, used by both
+ * `isPublished` and the preview affordance.
+ */
+export function isReleased(version: string, published: string): boolean {
+  return compareVersions(version, published) <= 0
+}
+
+/**
+ * Whether content introduced in `version` should be visible.
+ *
+ * Preview & local deployments show everything (`VERCEL_ENV` is a Vercel system
+ * variable, available at both build and runtime); production gates on the
+ * published GA version.
+ */
+export function isPublished(version: string, published: string): boolean {
+  if (process.env.VERCEL_ENV !== 'production') {
+    return true
+  }
+  return isReleased(version, published)
+}
+
+/**
+ * Compares two GA semver strings (`major.minor.patch`), returning a negative
+ * number when `a < b`, zero when equal, and a positive number when `a > b`.
+ * Prerelease tags are ignored — betas never move the `latest` dist-tag.
+ */
+function compareVersions(a: string, b: string): number {
+  const parse = (version: string) =>
+    version.split('.').map(segment => parseInt(segment, 10) || 0)
+  const left = parse(a)
+  const right = parse(b)
+  for (let i = 0; i < 3; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0)
+    if (diff !== 0) {
+      return diff
+    }
+  }
+  return 0
+}
diff --git a/packages/docs/src/lib/strip-unreleased.test.ts b/packages/docs/src/lib/strip-unreleased.test.ts
new file mode 100644
index 000000000..f9928a49b
--- /dev/null
+++ b/packages/docs/src/lib/strip-unreleased.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import { stripUnreleased } from './strip-unreleased.ts'
+
+const showAll = () => true
+const hideAll = () => false
+
+describe('stripUnreleased', () => {
+  it('unwraps a visible block, keeping its content and dropping the tags', () => {
+    const input = [
+      'before',
+      '<SinceVersion v="2.9.0">',
+      'gated',
+      '</SinceVersion>',
+      'after'
+    ].join('\n')
+    expect(stripUnreleased(input, showAll)).toBe(
+      ['before', 'gated', 'after'].join('\n')
+    )
+  })
+
+  it('removes a hidden block entirely, including its content', () => {
+    const input = [
+      'before',
+      '<SinceVersion v="2.9.0">',
+      'gated',
+      '</SinceVersion>',
+      'after'
+    ].join('\n')
+    expect(stripUnreleased(input, hideAll)).toBe(['before', 'after'].join('\n'))
+  })
+
+  it('keeps a visible outer block while dropping a hidden nested one', () => {
+    const input = [
+      '<SinceVersion v="2.9.0">',
+      'outer',
+      '<SinceVersion v="3.0.0">',
+      'inner',
+      '</SinceVersion>',
+      'tail',
+      '</SinceVersion>'
+    ].join('\n')
+    const isVisible = (v: string) => v === '2.9.0'
+    expect(stripUnreleased(input, isVisible)).toBe(['outer', 'tail'].join('\n'))
+  })
+
+  it('drops a whole hidden block even when it nests a visible one', () => {
+    const input = [
+      '<SinceVersion v="3.0.0">',
+      'outer',
+      '<SinceVersion v="2.9.0">',
+      'inner',
+      '</SinceVersion>',
+      'tail',
+      '</SinceVersion>'
+    ].join('\n')
+    const isVisible = (v: string) => v === '2.9.0'
+    expect(stripUnreleased(input, isVisible)).toBe('')
+  })
+
+  it('gates a tag that carries extra attributes alongside v', () => {
+    const input = [
+      'before',
+      '<SinceVersion v="2.9.0" disclaimer="block">',
+      'gated',
+      '</SinceVersion>',
+      'after'
+    ].join('\n')
+    expect(stripUnreleased(input, hideAll)).toBe(['before', 'after'].join('\n'))
+    expect(stripUnreleased(input, showAll)).toBe(
+      ['before', 'gated', 'after'].join('\n')
+    )
+  })
+
+  it('leaves SinceVersion-like text inside a fenced code block untouched', () => {
+    const input = [
+      'intro',
+      '```tsx',
+      '<SinceVersion v="9.9.9">',
+      'not a real tag',
+      '</SinceVersion>',
+      '```',
+      'outro'
+    ].join('\n')
+    expect(stripUnreleased(input, hideAll)).toBe(input)
+  })
+})
diff --git a/packages/docs/src/lib/strip-unreleased.ts b/packages/docs/src/lib/strip-unreleased.ts
new file mode 100644
index 000000000..6304ea0e9
--- /dev/null
+++ b/packages/docs/src/lib/strip-unreleased.ts
@@ -0,0 +1,51 @@
+const OPEN_TAG = /^<SinceVersion\s+[^>]*?\bv=['"]([^'"]+)['"][^>]*>/
+const CLOSE_TAG = '</SinceVersion>'
+
+/**
+ * Applies `<SinceVersion>` gating to the Markdown source of the LLM outputs,
+ * the text-layer counterpart to the `SinceVersion` React component.
+ *
+ * Hidden blocks (those whose version `isVisible` rejects) are removed along with
+ * their content; visible blocks are unwrapped, keeping the content and dropping
+ * only the wrapper tags. Tags inside fenced code blocks are left untouched, and
+ * nesting is handled — a block nested inside a hidden one stays hidden.
+ */
+export function stripUnreleased(
+  markdown: string,
+  isVisible: (version: string) => boolean
+): string {
+  const output: string[] = []
+  let inFence = false
+  let depth = 0 // number of open <SinceVersion> wrappers
+  let hiddenFrom = -1 // depth at which the outermost hidden block began, or -1
+
+  for (const line of markdown.split('\n')) {
+    if (line.startsWith('```')) {
+      inFence = !inFence
+    }
+
+    if (!inFence) {
+      const open = line.trimStart().match(OPEN_TAG)
+      if (open) {
+        depth++
+        if (hiddenFrom === -1 && !isVisible(open[1]!)) {
+          hiddenFrom = depth
+        }
+        continue
+      }
+      if (line.trimStart().startsWith(CLOSE_TAG)) {
+        if (depth === hiddenFrom) {
+          hiddenFrom = -1
+        }
+        depth = Math.max(0, depth - 1)
+        continue
+      }
+    }
+
+    if (hiddenFrom === -1) {
+      output.push(line)
+    }
+  }
+
+  return output.join('\n')
+}

From e3191600bc6f087772c90172ab28fffe1436e6b8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Best?= <github@francoisbest.com>
Date: Fri, 26 Jun 2026 20:39:55 +0200
Subject: [PATCH 2/8] chore: register the SinceVersion component as a Knip
 entry

MDX components are wired through `mdx-components` and resolved at runtime,
so Knip can't trace their usage and flags the export as unused. List it
alongside the sibling audience and feature-support-matrix entries.
---
 knip.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/knip.json b/knip.json
index 16ebe7f72..3f433c961 100644
--- a/knip.json
+++ b/knip.json
@@ -51,6 +51,7 @@
         "src/components/audience.tsx",
         "src/components/code-block-highlighter.ts",
         "src/components/feature-support-matrix.tsx",
+        "src/components/since-version.tsx",
         "src/components/frameworks.tsx",
         "src/schemas/changelog-dto.gen.ts"
       ],

From 064a83942d9815f8b0a90253b2855c8861037bba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Best?= <github@francoisbest.com>
Date: Fri, 26 Jun 2026 23:03:41 +0200
Subject: [PATCH 3/8] ci: drop the retired master and beta branches from the
 push trigger

Neither branch sources npm publishes anymore (handled by the
draft/validate/finalize workflow dispatched from `next`), so running the
CI matrix on pushes to them is dead config. `next` and PRs still run it.
---
 .github/workflows/ci-cd.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index b7bc60291..7bbb3efb4 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -3,8 +3,6 @@ name: CI/CD
 on:
   push:
     branches:
-      - master
-      - beta
       - next
   pull_request:
     types: [opened, reopened, synchronize]

From 962aa9dd7e26bde133a5e2573d834c7377fa3b97 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Best?= <github@francoisbest.com>
Date: Fri, 26 Jun 2026 23:04:06 +0200
Subject: [PATCH 4/8] ci: remove the obsolete master PR-base enforcement
 workflow

It auto-closed any PR targeting `master`; with `master` retired there are no such PRs left to guard against.
---
 .github/workflows/pr-base-enforcement.yml | 27 -----------------------
 1 file changed, 27 deletions(-)
 delete mode 100644 .github/workflows/pr-base-enforcement.yml

diff --git a/.github/workflows/pr-base-enforcement.yml b/.github/workflows/pr-base-enforcement.yml
deleted file mode 100644
index 6a8822c67..000000000
--- a/.github/workflows/pr-base-enforcement.yml
+++ /dev/null
@@ -1,27 +0,0 @@
-name: Prevent PRs targetting master
-
-on:
-  pull_request:
-    types: [opened, edited]
-    branches:
-      - master
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  prevent-pr-targetting-master:
-    runs-on: ubuntu-24.04-arm
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-        with:
-          persist-credentials: false
-      - name: Post comment to update base branch
-        run: gh pr comment ${{ github.event.pull_request.number }} --body "⚠️ Pull requests targetting the \`master\` branch are not allowed. Please update the base branch to \`next\` before reopening."
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - name: Close PR
-        run: gh pr close ${{ github.event.pull_request.number }} --repo ${{ github.repository }}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

From 9023c1d7c3ddece2f84f5d0bf6df370cf1df20ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Best?= <github@francoisbest.com>
Date: Sat, 27 Jun 2026 22:00:58 +0200
Subject: [PATCH 5/8] doc: tweak flagged content markers

---
 packages/docs/src/app/styles/tweaks.css        | 4 ++--
 packages/docs/src/components/since-version.tsx | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/docs/src/app/styles/tweaks.css b/packages/docs/src/app/styles/tweaks.css
index 11c65a1f7..2703f1575 100644
--- a/packages/docs/src/app/styles/tweaks.css
+++ b/packages/docs/src/app/styles/tweaks.css
@@ -20,8 +20,8 @@
     so it never fragments the host markdown list the way a block wrapper would.
   */
   .nuqs-since-version::after {
-    content: ' (visible from nuqs@' attr(data-since) ')';
-    @apply text-zinc-500 dark:text-zinc-400;
+    content: ' 🏗️ visible from nuqs@' attr(data-since) ' 🏗️';
+    @apply text-amber-500 dark:text-amber-400;
     font-size: 0.85em;
   }
 
diff --git a/packages/docs/src/components/since-version.tsx b/packages/docs/src/components/since-version.tsx
index 1791c447b..2d6173091 100644
--- a/packages/docs/src/components/since-version.tsx
+++ b/packages/docs/src/components/since-version.tsx
@@ -61,9 +61,9 @@ export async function SinceVersion({
   }
 
   return (
-    <fieldset className="my-4 rounded-xl border border-dashed border-zinc-400/60 px-4 pb-1 dark:border-zinc-600">
-      <legend className="not-prose px-2 text-sm text-zinc-500 dark:text-zinc-400">
-        Visible from <code className="text-xs">nuqs@{v}</code>
+    <fieldset className="my-4 rounded-xl border border-dashed border-amber-400/60 px-4 pb-1 dark:border-amber-600">
+      <legend className="not-prose px-2 text-sm text-amber-500">
+        🏗️ Visible from <code className="text-xs">nuqs@{v}</code> 🏗️
       </legend>
       {children}
     </fieldset>

From b5be8a5aa0f2308db89910212af787e244ac3d66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Best?= <github@francoisbest.com>
Date: Sat, 27 Jun 2026 22:35:52 +0200
Subject: [PATCH 6/8] doc: add more gated content

---
 packages/docs/content/docs/adapters.mdx        | 6 +++---
 packages/docs/src/components/since-version.tsx | 5 ++++-
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/docs/content/docs/adapters.mdx b/packages/docs/content/docs/adapters.mdx
index 9547875e4..90b62d81e 100644
--- a/packages/docs/content/docs/adapters.mdx
+++ b/packages/docs/content/docs/adapters.mdx
@@ -214,10 +214,10 @@ export function ReactRouter() {
 
   - `nuqs/adapters/react-router/v6`
   - `nuqs/adapters/react-router/v7`
-  - `nuqs/adapters/react-router/v8`
+  - <SinceVersion v="2.9.0" disclaimer='inline'>`nuqs/adapters/react-router/v8`</SinceVersion>
 
   The main difference is where the React Router hooks are imported from:
-  `react-router-dom` for v6, and `react-router` for v7 & v8.
+  `react-router-dom` for v6, and `react-router` for v7<SinceVersion v="2.9.0" disclaimer='inline'> & v8</SinceVersion>.
 </Callout>
 
 <Callout type="warn" title="Deprecation notice">
@@ -226,7 +226,7 @@ export function ReactRouter() {
   and no longer receives security updates. The `nuqs/adapters/react-router/v6`
   adapter will be removed in nuqs@3.0.0.
 
-  Upgrade to [React Router v7](#react-router-v7) or [v8](#react-router-v8) and use the
+  Upgrade to [React Router v7](#react-router-v7)<SinceVersion v="2.9.0" disclaimer="inline"> or [v8](#react-router-v8)</SinceVersion> and use the
   appropriate adapter below.
 
 </Callout>
diff --git a/packages/docs/src/components/since-version.tsx b/packages/docs/src/components/since-version.tsx
index 2d6173091..844ee33fa 100644
--- a/packages/docs/src/components/since-version.tsx
+++ b/packages/docs/src/components/since-version.tsx
@@ -54,7 +54,10 @@ export async function SinceVersion({
   // ::after pseudo-element (see tweaks.css) so it never fragments a host list.
   if (disclaimer === 'inline') {
     return (
-      <span className="nuqs-since-version" data-since={v}>
+      <span
+        className="nuqs-since-version underline decoration-amber-500 decoration-dashed decoration-1 underline-offset-2"
+        data-since={v}
+      >
         {children}
       </span>
     )

From 5533b2b51e1eda704c43adee8a8d195e3ba78bf6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Best?= <github@francoisbest.com>
Date: Sat, 27 Jun 2026 22:45:58 +0200
Subject: [PATCH 7/8] doc: add more gated content

---
 packages/docs/content/docs/adapters.mdx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/docs/content/docs/adapters.mdx b/packages/docs/content/docs/adapters.mdx
index 90b62d81e..b803011eb 100644
--- a/packages/docs/content/docs/adapters.mdx
+++ b/packages/docs/content/docs/adapters.mdx
@@ -169,8 +169,7 @@ export default function App() {
   no longer receives security updates. The `nuqs/adapters/remix` adapter will be
   removed in nuqs@3.0.0.
 
-  Remix has converged into React Router. Migrate to [React Router v7](#react-router-v7)
-  or [v8](#react-router-v8) and use the appropriate adapter below.
+  Remix has converged into React Router. Migrate to [React Router v7](#react-router-v7)<SinceVersion v="2.9.0" disclaimer="inline"> or [v8](#react-router-v8)</SinceVersion> and use the appropriate adapter below.
 
 </Callout>
 

From 6a3daa81ac01867f3abd2e87ada60e6b084d77bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Best?= <github@francoisbest.com>
Date: Sat, 27 Jun 2026 23:20:06 +0200
Subject: [PATCH 8/8] test: replace global fetch mock with msw

---
 packages/docs/package.json                    |  1 +
 .../docs/src/lib/published-version.test.ts    | 42 ++++++++-----------
 packages/scripts/package.json                 |  2 +-
 pnpm-lock.yaml                                |  9 +++-
 pnpm-workspace.yaml                           |  3 ++
 5 files changed, 30 insertions(+), 27 deletions(-)

diff --git a/packages/docs/package.json b/packages/docs/package.json
index d6a5fffb2..e0718c3f5 100644
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -75,6 +75,7 @@
     "@types/react": "catalog:react19",
     "@types/react-dom": "catalog:react19",
     "hast-util-to-jsx-runtime": "^2.3.6",
+    "msw": "catalog:msw",
     "postcss": "^8.5.6",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "shadcn": "^3.8.2",
diff --git a/packages/docs/src/lib/published-version.test.ts b/packages/docs/src/lib/published-version.test.ts
index 1d7fc9c23..35be60d72 100644
--- a/packages/docs/src/lib/published-version.test.ts
+++ b/packages/docs/src/lib/published-version.test.ts
@@ -1,4 +1,6 @@
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 import {
   getPublishedVersion,
   isPublished,
@@ -56,42 +58,32 @@ describe('isPublished', () => {
 })
 
 describe('getPublishedVersion', () => {
-  afterEach(() => {
-    vi.unstubAllGlobals()
-  })
+  const registry = 'https://registry.npmjs.org/nuqs'
+  const server = setupServer()
+  beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+  afterEach(() => server.resetHandlers())
+  afterAll(() => server.close())
 
   it('returns the latest dist-tag from the npm registry', async () => {
-    vi.stubGlobal(
-      'fetch',
-      vi.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({ 'dist-tags': { latest: '2.8.9' } })
-      })
+    server.use(
+      http.get(registry, () =>
+        HttpResponse.json({ 'dist-tags': { latest: '2.8.9' } })
+      )
     )
     await expect(getPublishedVersion()).resolves.toBe('2.8.9')
   })
 
   it('throws on a non-ok registry response (fail loud)', async () => {
-    vi.stubGlobal(
-      'fetch',
-      vi.fn().mockResolvedValue({
-        ok: false,
-        status: 503,
-        statusText: 'Service Unavailable',
-        json: async () => ({})
-      })
+    server.use(
+      http.get(registry, () =>
+        HttpResponse.json({}, { status: 503, statusText: 'Service Unavailable' })
+      )
     )
     await expect(getPublishedVersion()).rejects.toThrow(/npm/i)
   })
 
   it('throws when the response is missing dist-tags.latest (fail loud)', async () => {
-    vi.stubGlobal(
-      'fetch',
-      vi.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({ 'dist-tags': {} })
-      })
-    )
+    server.use(http.get(registry, () => HttpResponse.json({ 'dist-tags': {} })))
     await expect(getPublishedVersion()).rejects.toThrow(/dist-tags\.latest/)
   })
 })
diff --git a/packages/scripts/package.json b/packages/scripts/package.json
index f05ce28d8..0ef1bd748 100644
--- a/packages/scripts/package.json
+++ b/packages/scripts/package.json
@@ -23,7 +23,7 @@
     "@types/minimist": "^1.2.5",
     "@types/node": "^24.10.10",
     "@types/semver": "^7.7.1",
-    "msw": "^2.14.6",
+    "msw": "catalog:msw",
     "typescript": "catalog:typescript",
     "vitest": "catalog:vitest"
   }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 987c8be28..9a8bf1f56 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -16,6 +16,10 @@ catalogs:
     knip:
       specifier: ^6.14.2
       version: 6.14.2
+  msw:
+    msw:
+      specifier: ^2.14.6
+      version: 2.14.6
   next:
     next:
       specifier: 16.2.7
@@ -263,6 +267,9 @@ importers:
       hast-util-to-jsx-runtime:
         specifier: ^2.3.6
         version: 2.3.6
+      msw:
+        specifier: catalog:msw
+        version: 2.14.6(@types/node@24.10.10)(typescript@5.9.3)
       postcss:
         specifier: ^8.5.6
         version: 8.5.15
@@ -923,7 +930,7 @@ importers:
         specifier: ^7.7.1
         version: 7.7.1
       msw:
-        specifier: ^2.14.6
+        specifier: catalog:msw
         version: 2.14.6(@types/node@24.10.10)(typescript@5.9.3)
       typescript:
         specifier: catalog:typescript
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 417e08838..1057b37b3 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -9,6 +9,9 @@ catalogs:
   knip:
     knip: ^6.14.2
 
+  msw:
+    msw: ^2.14.6
+
   vitest:
     vitest: ^4.1.0
     '@vitest/browser-playwright': ^4.1.0