@pyreon/server 0.14.0 → 0.16.0

package/src/island.ts

@@ -45,11 +45,34 @@
  * ## Hydration strategies
  *
  * Control when an island hydrates via the `hydrate` option:
- *   - "load" (default) — hydrate immediately on page load
- *   - "idle"           — hydrate when the browser is idle (requestIdleCallback)
- *   - "visible"        — hydrate when the island scrolls into the viewport
- *   - "media(query)"   — hydrate when a media query matches
- *   - "never"          — never hydrate (render-only, no client JS)
+ *   - "load" (default)         — hydrate immediately on page load
+ *   - "idle"                   — hydrate when the browser is idle (requestIdleCallback)
+ *   - "visible"                — hydrate when the island scrolls into the viewport
+ *   - "interaction"            — hydrate on first user interaction (focus/click/pointerenter/touchstart)
+ *   - "interaction(<events>)"  — hydrate on first matching event (e.g. "interaction(focus)" or "interaction(click,touchstart)")
+ *   - "media(query)"           — hydrate when a media query matches
+ *   - "never"                  — never hydrate (render-only, no client JS)
+ *
+ * Use `interaction` for components that are interactive but not visible on
+ * load — modals, dropdowns, command palettes. The component stays as a
+ * non-hydrated DOM region until the user reaches for it (clicks the trigger,
+ * tabs through the page, hovers, taps).
+ *
+ * ## Prefetch hint
+ *
+ * Pair a deferred-hydration strategy (`visible` / `interaction` / `media(...)`)
+ * with a `prefetch` hint to start fetching the island's chunk BEFORE it's needed
+ * for hydration — the chunk is warm in the module cache by the time the
+ * hydration trigger fires, so hydration is instant instead of blank-while-fetching.
+ *
+ *   - "none" (default) — no prefetch
+ *   - "idle"           — call loader() during browser idle time (requestIdleCallback)
+ *   - "visible"        — call loader() ~200px before the island scrolls into view
+ *
+ * Pair `hydrate: 'visible'` with `prefetch: 'idle'` for the canonical "fetch
+ * during idle, hydrate on scroll-in" pattern. Prefetch is a no-op (silently
+ * skipped) for `hydrate: 'load'` (loader runs synchronously already) and
+ * `hydrate: 'never'` (defeats the zero-JS strategy).
  */
 
 import type { ComponentFn, Props, VNode } from '@pyreon/core'
@@ -57,19 +80,35 @@ import { h } from '@pyreon/core'
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
-export type HydrationStrategy = 'load' | 'idle' | 'visible' | 'never' | `media(${string})`
+export type HydrationStrategy =
+  | 'load'
+  | 'idle'
+  | 'visible'
+  | 'interaction'
+  | 'never'
+  | `media(${string})`
+  | `interaction(${string})`
+
+export type PrefetchStrategy = 'none' | 'idle' | 'visible'
 
 export interface IslandOptions {
   /** Unique name — must match the key in the client-side hydrateIslands() registry */
   name: string
   /** When to hydrate on the client (default: "load") */
   hydrate?: HydrationStrategy
+  /**
+   * Pre-warm the island's chunk before its hydration trigger fires.
+   * Best paired with `hydrate: 'visible'` or `hydrate: 'media(...)'`.
+   * Default: "none". No-op when paired with `hydrate: 'load'` or `'never'`.
+   */
+  prefetch?: PrefetchStrategy
 }
 
 export interface IslandMeta {
   readonly __island: true
   readonly name: string
   readonly hydrate: HydrationStrategy
+  readonly prefetch: PrefetchStrategy
 }
 
 // ─── Server-side island factory ──────────────────────────────────────────────
@@ -86,30 +125,35 @@ export function island<P extends Props = Props>(
   loader: () => Promise<{ default: ComponentFn<P> } | ComponentFn<P>>,
   options: IslandOptions,
 ): ComponentFn<P> & IslandMeta {
-  const { name, hydrate = 'load' } = options
+  const { name, hydrate = 'load', prefetch = 'none' } = options
 
   const IslandWrapper = async function IslandWrapper(props: P): Promise<VNode | null> {
     const mod = await loader()
     const Comp = typeof mod === 'function' ? mod : mod.default
-    const serializedProps = serializeIslandProps(props)
+    const serializedProps = serializeIslandProps(props, name)
 
-    return h(
-      'pyreon-island',
-      {
-        'data-component': name,
-        'data-props': serializedProps,
-        'data-hydrate': hydrate,
-      },
-      h(Comp, props),
-    )
+    // Only emit data-prefetch when it actually changes behavior. `none` is the
+    // default and pointless on `load` / `never` — keep the rendered HTML clean.
+    const attrs: Record<string, string> = {
+      'data-component': name,
+      'data-props': serializedProps,
+      'data-hydrate': hydrate,
+    }
+    if (prefetch !== 'none' && hydrate !== 'load' && hydrate !== 'never') {
+      attrs['data-prefetch'] = prefetch
+    }
+
+    return h('pyreon-island', attrs, h(Comp, props))
   }
 
-  // Attach metadata so the Vite plugin can detect islands for code-splitting
+  // Attach metadata so tooling (CLI project scanner, MCP, future codegen) can
+  // detect islands without runtime introspection.
   const wrapper = IslandWrapper as unknown as ComponentFn<P> & IslandMeta
   Object.defineProperties(wrapper, {
     __island: { value: true, enumerable: true },
     name: { value: name, enumerable: true, writable: false, configurable: true },
     hydrate: { value: hydrate, enumerable: true },
+    prefetch: { value: prefetch, enumerable: true },
   })
 
   return wrapper
@@ -118,20 +162,61 @@ export function island<P extends Props = Props>(
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /**
- * Serialize component props to a JSON string for embedding in HTML attributes.
- * Strips non-serializable values (functions, symbols, children).
+ * Serialize island props to JSON for embedding in `data-props`.
+ *
+ * **Prop contract** (what survives the SSR → client roundtrip):
+ *
+ * - ✅ JSON-native: strings, finite numbers, booleans, null, arrays, plain objects
+ * - ❌ **Dropped silently**: `children`, functions, symbols, `undefined` (a warning
+ *   fires in dev when `children` is dropped — it's the most common surprise)
+ * - ❌ **Coerced**: `Date` becomes an ISO string (no auto-revival on the client),
+ *   `Map` / `Set` / class instances lose their type
+ * - ⚠️ **`BigInt` is unsupported**: `JSON.stringify` throws on `BigInt` values.
+ *   We catch the throw, log in dev, and emit `{}` rather than 500ing the SSR.
+ *   Convert to string yourself before passing as a prop.
+ *
+ * For anything more complex than JSON, pass an ID and have the island component
+ * fetch / restore the rich value on the client.
  */
-function serializeIslandProps(props: Record<string, unknown>): string {
+function serializeIslandProps(
+  props: Record<string, unknown>,
+  islandName: string,
+): string {
   const clean: Record<string, unknown> = {}
+  let droppedChildren = false
   for (const [key, value] of Object.entries(props)) {
-    // Skip non-serializable or internal props
-    if (key === 'children') continue
+    if (key === 'children') {
+      if (value !== undefined) droppedChildren = true
+      continue
+    }
     if (typeof value === 'function') continue
     if (typeof value === 'symbol') continue
     if (value === undefined) continue
     clean[key] = value
   }
+  if (droppedChildren && process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[Pyreon] island "${islandName}" was passed children, but island props ` +
+        `do not support children — they were dropped. Render the children inside ` +
+        `the island component itself.`,
+    )
+  }
   // The SSR renderer's renderProp() already applies escapeHtml() to attribute
   // values, so the JSON is safe to embed in HTML attributes without double-escaping.
-  return JSON.stringify(clean)
+  try {
+    return JSON.stringify(clean)
+  } catch (err) {
+    // JSON.stringify throws on BigInt and on circular references. Don't 500
+    // the SSR — emit empty props and warn so the dev sees it before users do.
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[Pyreon] island "${islandName}" props could not be serialized (likely ` +
+          `BigInt or circular reference). Falling back to empty props. Original ` +
+          `error: ${(err as Error).message}`,
+      )
+    }
+    return '{}'
+  }
 }

package/src/manifest.ts

@@ -13,8 +13,9 @@ export default defineManifest({
     'mode: "string" (renderToString) or "stream" (renderToStream with Suspense out-of-order)',
     'Middleware chain — `(ctx) => Response | void | Promise<…>`, short-circuit on first Response',
     'prerender({ handler, paths, outDir, origin?, onPage? }) — SSG with onPage callback',
-    'island(loader, { name, hydrate }) — lazy island with hydration strategy',
+    'island(loader, { name, hydrate, prefetch? }) — lazy island with hydration strategy + optional prefetch hint',
     'Hydration strategies: "load" | "idle" | "visible" | "media(...)" | "never"',
+    'Prefetch hints: "idle" | "visible" — pre-warm the chunk before the hydration trigger fires',
     'useRequestLocals() bridges middleware `ctx.locals` into the component tree',
     'Loader-data inline-script escaping — `</script>` becomes `<\\/script>`',
   ],
@@ -87,22 +88,77 @@ export default createHandler({
       name: 'island',
       kind: 'function',
       signature:
-        'island(loader: () => Promise<ComponentFn>, options: { name: string; hydrate?: HydrationStrategy }): ComponentFn',
+        'island(loader: () => Promise<ComponentFn>, options: { name: string; hydrate?: HydrationStrategy; prefetch?: PrefetchStrategy }): ComponentFn',
       summary:
-        'Wrap a lazily-loaded component in a `<pyreon-island>` boundary with a hydration strategy. The rest of the page stays HTML-only; only the island fetches its JS bundle and hydrates. Strategies: `"load"` (immediate), `"idle"` (`requestIdleCallback`), `"visible"` (IntersectionObserver), `"media(query)"` (matchMedia), `"never"` (HTML-only, no JS). Props passed to islands are JSON-serialized — non-JSON values (functions, symbols, undefined, children) are stripped.',
-      example: `const SearchBar = island(
-  () => import("./SearchBar"),
-  { name: "SearchBar", hydrate: "visible" }
+        'Wrap a lazily-loaded component in a `<pyreon-island>` boundary with a hydration strategy. The rest of the page stays HTML-only; only the island fetches its JS bundle and hydrates. Strategies: `"load"` (immediate), `"idle"` (`requestIdleCallback`), `"visible"` (IntersectionObserver), `"interaction"` (first focus/click/pointerenter/touchstart — also `"interaction(<events>)"` for custom event lists; clicks are REPLAYED on the equivalent live element after hydration so the first click both wakes the island AND fires the action), `"media(query)"` (matchMedia), `"never"` (HTML-only, no JS). Props passed to islands are JSON-serialized — non-JSON values (functions, symbols, undefined, children) are stripped. Pair with `prefetch: "idle"` or `"visible"` to pre-warm the chunk BEFORE the hydration trigger fires — eliminates the blank-while-fetching flash on deferred-strategy islands. Prefetch is a no-op for `hydrate: "load"` (loader runs synchronously already) and `hydrate: "never"` (defeats the zero-JS strategy).',
+      example: `// Visible-hydration paired with idle-prefetch — chunk arrives during
+// browser idle so by scroll-in, hydration is instant.
+const Comments = island(
+  () => import("./Comments"),
+  { name: "Comments", hydrate: "visible", prefetch: "idle" }
 )
 
-// Hydration strategies: "load" | "idle" | "visible" | "media" | "never"`,
+// Interaction-hydration — perfect for modals / dropdowns / command palettes.
+const CommandPalette = island(
+  () => import("./CommandPalette"),
+  { name: "CommandPalette", hydrate: "interaction" }, // first focus/click/pointerenter/touchstart
+)
+
+// Hydration strategies: "load" | "idle" | "visible" | "interaction" | "media" | "never"
+// Prefetch strategies:  "none" (default) | "idle" | "visible"`,
       mistakes: [
         'Passing function props (event handlers, callbacks) — silently stripped during JSON serialization, the island sees `undefined`',
         'Passing children to an island — stripped; islands cannot render arbitrary descendant trees from props',
-        'Forgetting to call `hydrateIslands({ Name: () => import("./Path") })` on the client — islands render as HTML and never hydrate',
+        'Forgetting to wire client-side hydration — under `@pyreon/vite-plugin` use `hydrateIslandsAuto(registry)` (the registry is auto-generated from `island()` calls); without a plugin use the manual `hydrateIslands({ Name: () => import("./Path") })`',
         'Using a duplicate `name` across two islands — the client-side registry collapses them, only one loader will fire',
+        'Setting `prefetch: "idle"` on a `hydrate: "load"` island — load runs the loader synchronously, prefetch is redundant (silently suppressed; no `data-prefetch` attribute is emitted)',
+        'Setting any `prefetch` on a `hydrate: "never"` island — defeats the whole zero-JS point of `never` (silently suppressed)',
+        'Registering a `hydrate: "never"` island in `hydrateIslands({ ... })` — defeats the strategy by pulling the component module into the client bundle. The whole point of `never` is zero client JS. The runtime short-circuits never-strategy before the registry lookup so missing entries are silent (no `data-island-error="no-loader"`); the auto-registry omits never-strategy islands by design.',
+        'Using `"interaction"` for visible-on-load components — defeats the strategy. Use `"load"` for above-the-fold interactive content; reserve `"interaction"` for modals / dropdowns / command palettes that are interactive but only shown on user demand',
+        'Relying on focus/pointerenter to trigger the SAME action as click for `"interaction"` — only clicks are replayed post-hydration. Non-click events trigger hydration but no replay (focus can\\\'t be reliably re-dispatched once the user has tabbed past; pointerenter is passive)',
+      ],
+      seeAlso: ['createHandler', 'hydrateIslands', 'hydrateIslandsAuto'],
+    },
+    {
+      name: 'hydrateIslands',
+      kind: 'function',
+      signature:
+        'hydrateIslands(registry: Record<string, () => Promise<ComponentFn | { default: ComponentFn }>>): () => void',
+      summary:
+        'Client-side counterpart to `island()`. Walks every `<pyreon-island>` element on the page and schedules hydration per its `data-hydrate` strategy. Manual form: the user maintains the `Name → loader` mapping by hand (must match every `island()` `name` field). Returns a cleanup function that disconnects pending observers / listeners. Use `hydrateIslandsAuto()` under `@pyreon/vite-plugin` to skip the manual sync. Imported from `@pyreon/server/client`, NOT from `@pyreon/server` (server-only entry).',
+      example: `import { hydrateIslands } from "@pyreon/server/client"
+
+hydrateIslands({
+  Counter:  () => import("./Counter"),
+  SearchBar: () => import("./SearchBar"),
+  // hydrate: "never" islands are intentionally omitted —
+  // registering them defeats the zero-JS contract.
+})`,
+      mistakes: [
+        'Registry key must match the `island()` `name` field exactly — typo / drift causes runtime `data-island-error="no-loader"`. Use `hydrateIslandsAuto()` to eliminate this manual sync.',
+        'Including a `hydrate: "never"` island in the registry — defeats the strategy by pulling its module into the client bundle. Skip never-islands; the runtime short-circuits silently for them.',
+        'Importing from `@pyreon/server` instead of `@pyreon/server/client` — the main entry is server-only and stubs/throws on client-side use.',
+      ],
+      seeAlso: ['island', 'hydrateIslandsAuto'],
+    },
+    {
+      name: 'hydrateIslandsAuto',
+      kind: 'function',
+      signature:
+        'hydrateIslandsAuto(registry: AutoIslandRegistry): () => void',
+      summary:
+        'Auto-discovered counterpart to `hydrateIslands()`. Under `@pyreon/vite-plugin` (`pyreon({ islands: true })` is the default), the plugin pre-scans your source for `island()` declarations and emits a `virtual:pyreon/islands-registry` virtual module. The user imports it into `entry-client.ts` and passes it here. Eliminates the manual `Name → loader` sync that drives the #1 author foot-gun for islands. Never-strategy islands are omitted from the auto-registry by design — their components stay out of the client bundle.',
+      example: `// src/entry-client.ts
+import { hydrateIslandsAuto } from "@pyreon/server/client"
+import * as registry from "virtual:pyreon/islands-registry"
+
+hydrateIslandsAuto(registry)`,
+      mistakes: [
+        'Calling without the registry argument — the function takes the imported virtual module explicitly. The user-side `import` is what lets the plugin\\\'s `resolveId` hook run; importing from inside `@pyreon/server/client` would fail at build time because Rolldown\\\'s static-import analysis runs before plugin resolveId hooks for workspace sources.',
+        'Using under a non-Vite bundler — the virtual module only exists under `@pyreon/vite-plugin`. Fall back to manual `hydrateIslands({ ... })` for non-Vite consumers.',
+        'Setting `pyreon({ islands: false })` and still calling `hydrateIslandsAuto()` — the plugin emits a stub registry that throws at runtime with a clear error message. Either re-enable islands (the default) or use `hydrateIslands({ ... })` instead.',
       ],
-      seeAlso: ['createHandler', 'hydrateIslands'],
+      seeAlso: ['hydrateIslands', 'island'],
     },
     {
       name: 'prerender',