From 476fabf7aac71c4d68a43c51ddf1d4fa81176be3 Mon Sep 17 00:00:00 2001
From: Darius Cepulis <dcepulis@mux.com>
Date: Thu, 30 Oct 2025 00:39:39 -0500
Subject: [PATCH] feat(site): remove unnecessary hydration workarounds

---
 site/src/components/docs/FrameworkCase.astro  | 30 +++++++++----------
 site/src/components/docs/StyleCase.astro      | 30 +++++++++----------
 .../content/docs/concepts/architecture.mdx    |  2 +-
 .../content/docs/how-to/customize-skins.mdx   |  8 ++---
 .../docs/reference/fullscreen-button.mdx      |  4 +--
 .../content/docs/reference/mute-button.mdx    |  8 ++---
 .../content/docs/reference/play-button.mdx    |  4 +--
 .../content/docs/reference/time-slider.mdx    |  4 +--
 .../content/docs/reference/volume-slider.mdx  |  4 +--
 9 files changed, 45 insertions(+), 49 deletions(-)

diff --git a/site/src/components/docs/FrameworkCase.astro b/site/src/components/docs/FrameworkCase.astro
index c078ed95..5d43425e 100644
--- a/site/src/components/docs/FrameworkCase.astro
+++ b/site/src/components/docs/FrameworkCase.astro
@@ -3,9 +3,15 @@ import type { SupportedFramework } from '@/types/docs';
 
 interface Props {
   frameworks?: SupportedFramework[];
+  /**
+   * I'm running into some crazy problems with hydration.
+   * Putting client:load in one of these conditionals causes Astro to just give up hydrating the whole app for some reason.
+   * If you're running into that, too, this prop may be for you.
+   */
+  withHydrationWorkaround?: boolean;
 }
 
-const { frameworks } = Astro.props;
+const { frameworks, withHydrationWorkaround } = Astro.props;
 const { framework } = Astro.params;
 
 // Only render if current framework matches, or if no frameworks specified (all frameworks)
@@ -13,19 +19,11 @@ const shouldRender = !frameworks || frameworks.includes(framework as SupportedFr
 ---
 
 {
-  /*
-    What I WANT to do is
-    ```
-    {shouldRender && <slot />}
-    ```
-
-    But I'm running into some crazy problems with hydration.
-    Putting client:load in one of these conditionals causes Astro to just give up hydrating the whole app for some reason.
-    TODO: fix this
-
-    So, while I debug those... let's do this
-  */
+  withHydrationWorkaround ? (
+    <div class="contents" hidden={!shouldRender}>
+      <slot />
+    </div>
+  ) : (
+    shouldRender && <slot />
+  )
 }
-<div class="contents" hidden={!shouldRender}>
-  <slot />
-</div>
diff --git a/site/src/components/docs/StyleCase.astro b/site/src/components/docs/StyleCase.astro
index 5c5b8ffc..0afb4c2c 100644
--- a/site/src/components/docs/StyleCase.astro
+++ b/site/src/components/docs/StyleCase.astro
@@ -3,9 +3,15 @@ import type { AnySupportedStyle } from '@/types/docs';
 
 interface Props {
   styles?: AnySupportedStyle[];
+  /**
+   * I'm running into some crazy problems with hydration.
+   * Putting client:load in one of these conditionals causes Astro to just give up hydrating the whole app for some reason.
+   * If you're running into that, too, this prop may be for you.
+   */
+  withHydrationWorkaround?: boolean;
 }
 
-const { styles } = Astro.props;
+const { styles, withHydrationWorkaround } = Astro.props;
 const { style } = Astro.params;
 
 // Only render if current style matches, or if no styles specified (all styles)
@@ -13,19 +19,11 @@ const shouldRender = !styles || styles.includes(style as AnySupportedStyle);
 ---
 
 {
-  /*
-    What I WANT to do is
-    ```
-    {shouldRender && <slot />}
-    ```
-
-    But I'm running into some crazy problems with hydration.
-    Putting client:load in one of these conditionals causes Astro to just give up hydrating the whole app for some reason.
-    TODO: fix this
-
-    So, while I debug those... let's do this
-  */
+  withHydrationWorkaround ? (
+    <div class="contents" hidden={!shouldRender}>
+      <slot />
+    </div>
+  ) : (
+    shouldRender && <slot />
+  )
 }
-<div class="contents" hidden={!shouldRender}>
-  <slot />
-</div>
diff --git a/site/src/content/docs/concepts/architecture.mdx b/site/src/content/docs/concepts/architecture.mdx
index 40360ef1..327bc7bc 100644
--- a/site/src/content/docs/concepts/architecture.mdx
+++ b/site/src/content/docs/concepts/architecture.mdx
@@ -92,7 +92,7 @@ function Player() {
 ```
 </FrameworkCase>
 
-<FrameworkCase frameworks={["html"]}>
+<FrameworkCase frameworks={["html"]} withHydrationWorkaround>
 <TabsRoot
   aria-label="HTML implementation"
   titles={{  html: 'HTML', javascript: 'JavaScript' }}
diff --git a/site/src/content/docs/how-to/customize-skins.mdx b/site/src/content/docs/how-to/customize-skins.mdx
index a6d1301d..ed0066c6 100644
--- a/site/src/content/docs/how-to/customize-skins.mdx
+++ b/site/src/content/docs/how-to/customize-skins.mdx
@@ -25,7 +25,7 @@ While eventually we'll have a CLI that'll eject skins in your preferred framewor
 
 ## Frosted Skin
 
-<FrameworkCase frameworks={["react"]}>
+<FrameworkCase frameworks={["react"]} withHydrationWorkaround>
 
 <TabsRoot
   aria-label="Frosted React implementation"
@@ -42,7 +42,7 @@ While eventually we'll have a CLI that'll eject skins in your preferred framewor
 
 </FrameworkCase>
 
-<FrameworkCase frameworks={["html"]}>
+<FrameworkCase frameworks={["html"]} withHydrationWorkaround>
 
 <TabsRoot
   aria-label="Frosted HTML implementation"
@@ -64,7 +64,7 @@ While eventually we'll have a CLI that'll eject skins in your preferred framewor
 
 ## Minimal Skin
 
-<FrameworkCase frameworks={["react"]}>
+<FrameworkCase frameworks={["react"]} withHydrationWorkaround>
 
 <TabsRoot
   aria-label="Minimal React implementation"
@@ -81,7 +81,7 @@ While eventually we'll have a CLI that'll eject skins in your preferred framewor
 
 </FrameworkCase>
 
-<FrameworkCase frameworks={["html"]}>
+<FrameworkCase frameworks={["html"]} withHydrationWorkaround>
 
 <TabsRoot
   aria-label="Minimal HTML implementation"
diff --git a/site/src/content/docs/reference/fullscreen-button.mdx b/site/src/content/docs/reference/fullscreen-button.mdx
index 0bcdbf24..9424f430 100644
--- a/site/src/content/docs/reference/fullscreen-button.mdx
+++ b/site/src/content/docs/reference/fullscreen-button.mdx
@@ -24,7 +24,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
 ## Example
 
-<FrameworkCase frameworks={["react"]}>
+<FrameworkCase frameworks={["react"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="React implementation"
     titles={{ component: 'Component', css: 'CSS Module' }}
@@ -42,7 +42,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
   </TabsRoot>
 </FrameworkCase>
 
-<FrameworkCase frameworks={["html"]}>
+<FrameworkCase frameworks={["html"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="HTML implementation"
     titles={{ html: 'HTML', css: 'CSS', javascript: 'JS' }}
diff --git a/site/src/content/docs/reference/mute-button.mdx b/site/src/content/docs/reference/mute-button.mdx
index 9605a0a1..14f41bcf 100644
--- a/site/src/content/docs/reference/mute-button.mdx
+++ b/site/src/content/docs/reference/mute-button.mdx
@@ -24,7 +24,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
 ## Example
 
-<FrameworkCase frameworks={["react"]}>
+<FrameworkCase frameworks={["react"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="React implementation"
     titles={{ component: 'Component', css: 'CSS Module' }}
@@ -37,12 +37,12 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
     <TabsPanel value="css" client:load>
       <ServerCode code={cssModuleStr} lang="css" />
     </TabsPanel>
-    
+
     <MuteButtonDemo client:load />
   </TabsRoot>
 </FrameworkCase>
 
-<FrameworkCase frameworks={["html"]}>
+<FrameworkCase frameworks={["html"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="HTML implementation"
     titles={{ html: 'HTML', css: 'CSS', javascript: 'JS' }}
@@ -60,7 +60,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
       <ServerCode code={htmlJsStr} lang="js" />
     </TabsPanel>
 
-    <MuteButtonDemo client:load /> 
+    <MuteButtonDemo client:load />
   </TabsRoot>
 </FrameworkCase>
 
diff --git a/site/src/content/docs/reference/play-button.mdx b/site/src/content/docs/reference/play-button.mdx
index 321e3537..9f31601e 100644
--- a/site/src/content/docs/reference/play-button.mdx
+++ b/site/src/content/docs/reference/play-button.mdx
@@ -24,7 +24,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
 ## Example
 
-<FrameworkCase frameworks={["react"]}>
+<FrameworkCase frameworks={["react"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="React implementation"
     titles={{ component: 'Component', css: 'CSS Module' }}
@@ -42,7 +42,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
   </TabsRoot>
 </FrameworkCase>
 
-<FrameworkCase frameworks={["html"]}>
+<FrameworkCase frameworks={["html"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="HTML implementation"
     titles={{ html: 'HTML', css: 'CSS', javascript: 'JS' }}
diff --git a/site/src/content/docs/reference/time-slider.mdx b/site/src/content/docs/reference/time-slider.mdx
index 1b0f8af6..ae0d04f4 100644
--- a/site/src/content/docs/reference/time-slider.mdx
+++ b/site/src/content/docs/reference/time-slider.mdx
@@ -25,7 +25,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
 ## Example
 
-<FrameworkCase frameworks={["react"]}>
+<FrameworkCase frameworks={["react"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="React implementation"
     titles={{ component: 'Component', css: 'CSS Module' }}
@@ -43,7 +43,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
   </TabsRoot>
 </FrameworkCase>
 
-<FrameworkCase frameworks={["html"]}>
+<FrameworkCase frameworks={["html"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="HTML implementation"
     titles={{ 'html-horizontal': 'HTML (Horizontal)', 'html-vertical': 'HTML (Vertical)', css: 'CSS' }}
diff --git a/site/src/content/docs/reference/volume-slider.mdx b/site/src/content/docs/reference/volume-slider.mdx
index 6e69ed75..2b7e0b04 100644
--- a/site/src/content/docs/reference/volume-slider.mdx
+++ b/site/src/content/docs/reference/volume-slider.mdx
@@ -25,7 +25,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
 ## Example
 
-<FrameworkCase frameworks={["react"]}>
+<FrameworkCase frameworks={["react"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="React implementation"
     titles={{ component: 'Component', css: 'CSS Module' }}
@@ -43,7 +43,7 @@ import { TabsRoot, TabsPanel } from '@/components/Tabs';
   </TabsRoot>
 </FrameworkCase>
 
-<FrameworkCase frameworks={["html"]}>
+<FrameworkCase frameworks={["html"]} withHydrationWorkaround>
   <TabsRoot
     aria-label="HTML implementation"
     titles={{ 'html-horizontal': 'HTML (Horizontal)', 'html-vertical': 'HTML (Vertical)', css: 'CSS' }}