// ❌ Standard Next.js/React — the full tree hydrates regardless of interactivity
// Every component in this tree downloads and executes JavaScript

export default function MarketingPage() {
  return (
    <>
      <SiteHeader />          {/* Static — never changes. Still hydrated. */}
      <HeroSection />         {/* Static image + headline. Still hydrated. */}
      <FeatureGrid />         {/* 12 static feature cards. All hydrated. */}
      <Testimonials />        {/* 8 static testimonial blocks. All hydrated. */}
      <PricingTable />        {/* Static comparison table. Still hydrated. */}
      <NewsletterForm />      {/* ← The ONE component that needs JS */}
      <Footer />              {/* Static links. Still hydrated. */}
    </>
  )
}
// Total JS parsed for hydration: ~180KB
// JS that actually does anything interactive: ~8KB (the form)
// Wasted hydration: ~172KB

Rendered page:

┌─────────────────────────────────────────────┐
│         SiteHeader (HTML — 0 JS)            │  ← sea
│         HeroSection (HTML — 0 JS)           │  ← sea
│  ╔═══════════════════════════════╗           │
│  ║  SearchBar Island (React)     ║  ← island │
│  ║  client:load · 12KB           ║           │
│  ╚═══════════════════════════════╝           │
│         FeatureGrid (HTML — 0 JS)           │  ← sea
│  ╔═════════════╗  ╔═════════════╗            │
│  ║ VideoPlayer ║  ║ CartWidget  ║  ← islands │
│  ║ client:idle ║  ║ client:load ║            │
│  ╚═════════════╝  ╚═════════════╝            │
│         Footer (HTML — 0 JS)                │  ← sea
└─────────────────────────────────────────────┘

<!-- What Astro generates in the HTML for a React island -->
<astro-island
  uid="abc123"
  component-export="SearchBar"
  component-url="/_astro/SearchBar.abc123.js"
  renderer-url="/_astro/client.react.js"
>
  <script type="application/json">
    {"placeholder":"Search docs...","initialQuery":"","maxResults":10}
  </script>
  <!-- Server-rendered HTML fallback while JS loads -->
  <input type="search" placeholder="Search docs..." />
</astro-island>

// ✅ Valid island props — all JSON-serializable
interface SearchBarProps {
  placeholder: string         // string
  maxResults: number          // number
  categories: string[]        // array of primitives
  config: { fuzzy: boolean }  // plain object
  initialQuery?: string       // optional primitive
}

// ❌ Invalid — cannot be JSON-serialized, cannot cross the island boundary
interface BrokenProps {
  onSearch: (q: string) => void  // Function — NOT serializable
  client: PrismaClient           // Class instance — NOT serializable
  ref: React.RefObject<Element>  // React ref — NOT serializable
  children: React.ReactNode      // JSX/React elements — NOT serializable
}

---
import SearchBar from './SearchBar.tsx'
import VideoPlayer from './VideoPlayer.tsx'
import NewsletterForm from './NewsletterForm.tsx'
import StockTicker from './StockTicker.tsx'
import MobileMenu from './MobileMenu.tsx'
---

<!-- client:load — hydrate immediately on page load. Use for above-the-fold interactive elements. -->
<SearchBar client:load placeholder="Search..." />

<!-- client:idle — hydrate when the browser's main thread is idle (requestIdleCallback).
     Use for non-critical interactive elements that don't need to be ready immediately. -->
<StockTicker client:idle symbols={["AAPL", "GOOGL"]} />

<!-- client:visible — hydrate when the island enters the viewport (IntersectionObserver).
     Use for below-the-fold islands — they don't hydrate until the user scrolls to them. -->
<VideoPlayer client:visible src="/demo.mp4" />

<!-- client:media — hydrate when a CSS media query matches.
     Use for islands that only make sense at specific viewport sizes. -->
<MobileMenu client:media="(max-width: 768px)" />

<!-- client:only="react" — skip SSR entirely, hydrate only on the client.
     Use for islands that depend on browser APIs unavailable during SSR. -->
<BrowserOnlyComponent client:only="react" />

---
import ReactSearch from './Search.tsx'    // React component
import VueChart from './Chart.vue'        // Vue component
import SvelteModal from './Modal.svelte'  // Svelte component
---

<ReactSearch client:load />
<VueChart client:visible data={chartData} />
<SvelteModal client:idle />

<!-- Qwik serializes event handlers into the HTML as qrl references -->
<button on:click="./chunk-abc.js#handleClick_component_A[0]">
  Click me
</button>
<!-- No JS bundle executed on load — Qwik lazy-loads the handler only when the button is clicked -->

// Island A — dispatches a custom event
function SearchBar() {
  const handleSearch = (query: string) => {
    document.dispatchEvent(new CustomEvent('search:query', { detail: { query } }))
  }
  return <input onChange={e => handleSearch(e.target.value)} />
}

// Island B — listens for the custom event
function ResultsPanel() {
  const [query, setQuery] = useState('')
  useEffect(() => {
    const handler = (e: CustomEvent) => setQuery(e.detail.query)
    document.addEventListener('search:query', handler)
    return () => document.removeEventListener('search:query', handler)
  }, [])
  return <ResultsList query={query} />
}

// shared-store.ts — a tiny shared signal store (no framework dependency)
import { atom } from 'nanostores'

export const searchQuery = atom<string>('')

// Island A — writes to the store
import { searchQuery } from './shared-store'

function SearchBar() {
  return <input onChange={e => searchQuery.set(e.target.value)} />
}

// Island B — reads from the store; re-renders when the value changes
import { useStore } from '@nanostores/react'
import { searchQuery } from './shared-store'

function ResultsPanel() {
  const query = useStore(searchQuery)
  return <ResultsList query={query} />
}

Interactive surface area > ~50% of the page
OR
Islands need to share complex state with deeply nested bidirectional updates
OR
You need React Router/Next.js-style client-side navigation between routes

→ In these cases, the island boundary overhead and cross-island coordination cost
  exceeds the JavaScript elimination savings. Use Next.js with RSC + PPR instead.