Island architecture

// src/islands.ts — declarations
import { island } from '@pyreon/server'

export const Counter = island(() => import('./components/Counter'), {
  name: 'Counter',
  hydrate: 'load',
})

export const Comments = island(() => import('./components/Comments'), {
  name: 'Comments',
  hydrate: 'visible',
  prefetch: 'idle', // pre-warm the chunk during browser idle
})

export const CommandPalette = island(() => import('./components/CommandPalette'), {
  name: 'CommandPalette',
  hydrate: 'interaction', // first focus/click/pointerenter/touchstart
})

export const StaticBadge = island(() => import('./components/StaticBadge'), {
  name: 'StaticBadge',
  hydrate: 'never', // server-rendered only, no client JS
})

// src/App.tsx — usage
import { Counter, Comments, CommandPalette, StaticBadge } from './islands'

export default function App() {
  return (
    <main>
      <h1>Static heading (no JS)</h1>
      <Counter initial={5} />
      <p>
        Static paragraph. <StaticBadge label="zero JS" />
      </p>
      <CommandPalette />
      <Comments />
    </main>
  )
}

// src/entry-client.ts — auto-discovered registry under @pyreon/vite-plugin
import { hydrateIslandsAuto } from '@pyreon/server/client'
// @ts-expect-error virtual module — provided by @pyreon/vite-plugin
import * as registry from 'virtual:pyreon/islands-registry'

hydrateIslandsAuto(registry)

// Canonical pattern — visible hydration + idle prefetch
const Comments = island(() => import('./Comments'), {
  name: 'Comments',
  hydrate: 'visible',
  prefetch: 'idle', // chunk warm before user scrolls
})

// src/entry-client.ts — manual form (non-Vite consumers)
import { hydrateIslands } from '@pyreon/server/client'

hydrateIslands({
  Counter: () => import('./components/Counter'),
  Comments: () => import('./components/Comments'),
  CommandPalette: () => import('./components/CommandPalette'),
  // StaticBadge has hydrate: 'never' — DO NOT register; the runtime
  // short-circuits never-strategy before the registry lookup, and
  // registering would defeat the strategy by pulling its module
  // into the client bundle graph.
})

// BROKEN — registering a hydrate: 'never' island
hydrateIslands({
  StaticBadge: () => import('./components/StaticBadge'), // defeats zero-JS
})
// The whole point of 'never' is shipping zero client JS. Registering
// pulls the component module into the client bundle graph; the runtime
// short-circuits and never calls the loader, but the bundler still
// includes it. Caught by the `island-never-with-registry-entry` detector.

// BROKEN — using 'interaction' for an above-the-fold interactive component
const HeaderCTA = island(() => import('./HeaderCTA'), {
  name: 'HeaderCTA',
  hydrate: 'interaction',
})
// Defeats the strategy. 'interaction' is for modals / dropdowns /
// command palettes that are interactive BUT NOT VISIBLE on load.
// Use 'load' for above-the-fold interactive content.

// BROKEN — relying on focus/pointerenter to fire the click action
const CmdPalette = island(() => import('./CmdPalette'), {
  name: 'CmdPalette',
  hydrate: 'interaction',
})
// The user tabs to the palette button (focus event) → island hydrates →
// but no replay fires for focus. Only CLICK events are replayed
// post-hydration on the equivalent live element. Non-click events trigger
// hydration but not action — the user has to click again to fire it.

// BROKEN — prefetch on a 'load' island
const Counter = island(() => import('./Counter'), {
  name: 'Counter',
  hydrate: 'load',
  prefetch: 'idle', // pointless — load runs the loader synchronously
})
// The framework silently suppresses the data-prefetch attribute, so
// nothing breaks at runtime — but the user is signaling intent that
// doesn't apply. Drop the prefetch field.

// BROKEN — passing children to an island
const Comments = island(() => import('./Comments'), { name: 'Comments' })

;<Comments>
  <p>Initial content</p> {/* stripped during JSON serialization */}
</Comments>
// Island props are JSON-serialized for SSR → client transit. Children
// (along with functions, symbols, undefined) are stripped. The island
// renders only what its component returns from its OWN body, not what
// the parent passes as children.

// BROKEN — duplicate `name` across two islands
export const A = island(() => import('./A'), { name: 'Widget' })
export const B = island(() => import('./B'), { name: 'Widget' })
// The client-side registry is keyed by name; only the FIRST loader fires.
// The second island silently fails to hydrate. Use distinct names.