what-server 0.2.0

package/index.d.ts

@@ -0,0 +1,237 @@
+// What Framework Server - TypeScript Definitions
+
+import { VNode, VNodeChild, Signal } from '../core';
+
+// --- SSR ---
+
+/** Render VNode tree to HTML string */
+export function renderToString(vnode: VNode): string;
+
+/** Render VNode tree as async iterator for streaming */
+export function renderToStream(vnode: VNode): AsyncGenerator<string>;
+
+// --- Page Configuration ---
+
+export interface PageConfig {
+  /** Rendering mode */
+  mode?: 'static' | 'server' | 'client' | 'hybrid';
+  /** Page title */
+  title?: string;
+  /** Meta tags */
+  meta?: Record<string, string>;
+  /** Page component */
+  component: (data?: any) => VNode;
+  /** Islands to hydrate */
+  islands?: string[];
+  /** Scripts to load */
+  scripts?: string[];
+  /** Stylesheets to load */
+  styles?: string[];
+}
+
+export function definePage(config: Partial<PageConfig>): PageConfig;
+
+/** Generate static HTML for a page */
+export function generateStaticPage(page: PageConfig, data?: any): string;
+
+/** Mark component as server-only (no client JS) */
+export function server<P>(component: (props: P) => VNode): (props: P) => VNode;
+
+// --- Islands ---
+
+export interface IslandOptions {
+  /** Hydration mode */
+  mode?: 'static' | 'idle' | 'visible' | 'load' | 'media' | 'action';
+  /** Media query for 'media' mode */
+  media?: string;
+  /** Priority (higher = hydrate first) */
+  priority?: number;
+  /** Shared stores this island uses */
+  stores?: string[];
+}
+
+/** Register an island component */
+export function island(
+  name: string,
+  loader: () => Promise<any>,
+  options?: IslandOptions
+): void;
+
+/** Island component wrapper for SSR */
+export function Island(props: {
+  name: string;
+  props?: Record<string, any>;
+  mode?: IslandOptions['mode'];
+  priority?: number;
+  stores?: string[];
+  children?: VNodeChild;
+}): VNode;
+
+/** Hydrate all islands on the page */
+export function hydrateIslands(): void;
+
+/** Auto-discover and register islands */
+export function autoIslands(registry: Record<string, {
+  loader: () => Promise<any>;
+  mode?: IslandOptions['mode'];
+  media?: string;
+  priority?: number;
+  stores?: string[];
+} | (() => Promise<any>)>): void;
+
+/** Boost hydration priority for an island */
+export function boostIslandPriority(name: string, newPriority?: number): void;
+
+// --- Shared Island State ---
+
+export interface IslandStore<T extends Record<string, any>> {
+  _signals: Record<keyof T, Signal<any>>;
+  _subscribe: (key: keyof T, fn: (value: any) => void) => () => void;
+  _batch: (fn: () => void) => void;
+  _getSnapshot: () => T;
+  _hydrate: (data: Partial<T>) => void;
+}
+
+/** Create a shared store for islands */
+export function createIslandStore<T extends Record<string, any>>(
+  name: string,
+  initialState: T
+): T & IslandStore<T>;
+
+/** Get or create a shared store */
+export function useIslandStore<T extends Record<string, any>>(
+  name: string,
+  fallbackInitial?: T
+): T & IslandStore<T>;
+
+/** Serialize all shared stores for SSR */
+export function serializeIslandStores(): string;
+
+/** Hydrate shared stores from SSR data */
+export function hydrateIslandStores(serialized: string | Record<string, any>): void;
+
+// --- Progressive Enhancement ---
+
+/** Enhance elements matching selector */
+export function enhance(selector: string, handler: (el: Element) => void): void;
+
+/** Enhance forms for AJAX submission */
+export function enhanceForms(selector?: string): void;
+
+// --- Debugging ---
+
+export interface IslandStatus {
+  registered: string[];
+  hydrated: number;
+  pending: number;
+  queue: { name: string; priority: number }[];
+  stores: string[];
+}
+
+export function getIslandStatus(): IslandStatus;
+
+// --- Server Actions ---
+
+export interface ActionOptions {
+  id?: string;
+  onError?: (error: Error) => void;
+  onSuccess?: (result: any) => void;
+  revalidate?: string[];
+}
+
+/** Define a server action */
+export function action<T extends any[], R>(
+  fn: (...args: T) => Promise<R>,
+  options?: ActionOptions
+): (...args: T) => Promise<R>;
+
+/** Create a form action handler */
+export function formAction<R>(
+  actionFn: (data: Record<string, any>) => Promise<R>,
+  options?: {
+    onSuccess?: (result: R, form?: HTMLFormElement) => void;
+    onError?: (error: Error, form?: HTMLFormElement) => void;
+    resetOnSuccess?: boolean;
+  }
+): (formDataOrEvent: FormData | Event) => Promise<R>;
+
+// --- useAction Hook ---
+
+export interface UseActionResult<T extends any[], R> {
+  trigger: (...args: T) => Promise<R>;
+  isPending: () => boolean;
+  error: () => Error | null;
+  data: () => R | null;
+  reset: () => void;
+}
+
+export function useAction<T extends any[], R>(
+  actionFn: (...args: T) => Promise<R>
+): UseActionResult<T, R>;
+
+// --- useFormAction Hook ---
+
+export interface UseFormActionResult<R> extends UseActionResult<[FormData], R> {
+  handleSubmit: (e: Event) => Promise<R>;
+  formRef: { current: HTMLFormElement | null };
+}
+
+export function useFormAction<R>(
+  actionFn: (data: Record<string, any>) => Promise<R>,
+  options?: { resetOnSuccess?: boolean }
+): UseFormActionResult<R>;
+
+// --- Optimistic Updates ---
+
+export interface UseOptimisticResult<T, A> {
+  value: () => T;
+  isPending: () => boolean;
+  addOptimistic: (action: A) => void;
+  resolve: (action: A) => void;
+  rollback: (action: A, realValue: T) => void;
+  set: (value: T) => void;
+}
+
+export function useOptimistic<T, A>(
+  initialValue: T,
+  reducer: (currentValue: T, action: A) => T
+): UseOptimisticResult<T, A>;
+
+// --- Mutations ---
+
+export interface UseMutationResult<T extends any[], R> {
+  mutate: (...args: T) => Promise<R>;
+  isPending: () => boolean;
+  error: () => Error | null;
+  data: () => R | null;
+  reset: () => void;
+}
+
+export function useMutation<T extends any[], R>(
+  mutationFn: (...args: T) => Promise<R>,
+  options?: {
+    onSuccess?: (result: R, ...args: T) => void;
+    onError?: (error: Error, ...args: T) => void;
+    onSettled?: (data: R | null, error: Error | null, ...args: T) => void;
+  }
+): UseMutationResult<T, R>;
+
+// --- Revalidation ---
+
+export function onRevalidate(path: string, callback: () => void): () => void;
+export function invalidatePath(path: string): void;
+
+// --- Server Handler ---
+
+export interface ActionResponse {
+  status: number;
+  body: any;
+}
+
+export function handleActionRequest(
+  req: any,
+  actionId: string,
+  args: any[]
+): Promise<ActionResponse>;
+
+export function getRegisteredActions(): string[];

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "what-server",
+  "version": "0.2.0",
+  "description": "What Framework - SSR, islands architecture, static generation",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./islands": {
+      "import": "./src/islands.js"
+    },
+    "./actions": {
+      "import": "./src/actions.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "ssr",
+    "islands",
+    "static-generation",
+    "server-rendering",
+    "what-framework"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "what-core": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aspect/what-fw"
+  }
+}

package/src/actions.js

@@ -0,0 +1,305 @@
+// What Framework - Server Actions
+// Call server-side functions from client code seamlessly.
+// Similar to Next.js Server Actions / SolidStart server functions.
+//
+// Usage:
+//   // Define on server
+//   const saveUser = action(async (formData) => {
+//     'use server';
+//     const user = await db.users.create(formData);
+//     return { success: true, id: user.id };
+//   });
+//
+//   // Call from client
+//   const result = await saveUser({ name: 'John' });
+
+import { signal, batch } from 'what-core';
+
+// Registry of server actions
+const actionRegistry = new Map();
+let actionIdCounter = 0;
+
+// --- Define a server action ---
+
+export function action(fn, options = {}) {
+  const id = options.id || `action_${++actionIdCounter}`;
+  const { onError, onSuccess, revalidate } = options;
+
+  // Server-side: register the action
+  if (typeof window === 'undefined') {
+    actionRegistry.set(id, { fn, options });
+  }
+
+  // Create the callable wrapper
+  async function callAction(...args) {
+    // Server-side: call directly
+    if (typeof window === 'undefined') {
+      return fn(...args);
+    }
+
+    // Client-side: call via fetch
+    try {
+      const response = await fetch('/__what_action', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-What-Action': id,
+        },
+        body: JSON.stringify({ args }),
+      });
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({ message: 'Action failed' }));
+        throw new Error(error.message || 'Action failed');
+      }
+
+      const result = await response.json();
+
+      if (onSuccess) onSuccess(result);
+      if (revalidate) {
+        // Trigger revalidation of specified paths
+        for (const path of revalidate) {
+          invalidatePath(path);
+        }
+      }
+
+      return result;
+    } catch (error) {
+      if (onError) onError(error);
+      throw error;
+    }
+  }
+
+  callAction._actionId = id;
+  callAction._isAction = true;
+
+  return callAction;
+}
+
+// --- Form action helper ---
+// For forms that submit to server actions.
+
+export function formAction(actionFn, options = {}) {
+  const { onSuccess, onError, resetOnSuccess = true } = options;
+
+  return async (formDataOrEvent) => {
+    let formData;
+    let form;
+
+    if (formDataOrEvent instanceof Event) {
+      formDataOrEvent.preventDefault();
+      form = formDataOrEvent.target;
+      formData = new FormData(form);
+    } else {
+      formData = formDataOrEvent;
+    }
+
+    // Convert FormData to plain object
+    const data = {};
+    for (const [key, value] of formData.entries()) {
+      if (data[key]) {
+        // Handle multiple values (e.g., checkboxes)
+        if (Array.isArray(data[key])) {
+          data[key].push(value);
+        } else {
+          data[key] = [data[key], value];
+        }
+      } else {
+        data[key] = value;
+      }
+    }
+
+    try {
+      const result = await actionFn(data);
+      if (onSuccess) onSuccess(result, form);
+      if (resetOnSuccess && form) form.reset();
+      return result;
+    } catch (error) {
+      if (onError) onError(error, form);
+      throw error;
+    }
+  };
+}
+
+// --- useAction hook ---
+// Returns action state and trigger function.
+
+export function useAction(actionFn) {
+  const isPending = signal(false);
+  const error = signal(null);
+  const data = signal(null);
+
+  async function trigger(...args) {
+    isPending.set(true);
+    error.set(null);
+
+    try {
+      const result = await actionFn(...args);
+      data.set(result);
+      return result;
+    } catch (e) {
+      error.set(e);
+      throw e;
+    } finally {
+      isPending.set(false);
+    }
+  }
+
+  return {
+    trigger,
+    isPending: () => isPending(),
+    error: () => error(),
+    data: () => data(),
+    reset: () => {
+      error.set(null);
+      data.set(null);
+    },
+  };
+}
+
+// --- useFormAction hook ---
+// Combines useAction with form handling.
+
+export function useFormAction(actionFn, options = {}) {
+  const { resetOnSuccess = true } = options;
+  const formRef = { current: null };
+  const actionState = useAction(formAction(actionFn, { resetOnSuccess }));
+
+  function handleSubmit(e) {
+    e.preventDefault();
+    const formData = new FormData(e.target);
+    formRef.current = e.target;
+    return actionState.trigger(formData);
+  }
+
+  return {
+    ...actionState,
+    handleSubmit,
+    formRef,
+  };
+}
+
+// --- Optimistic updates ---
+
+export function useOptimistic(initialValue, reducer) {
+  const value = signal(initialValue);
+  const pending = signal([]);
+
+  function addOptimistic(action) {
+    const optimisticValue = reducer(value.peek(), action);
+    batch(() => {
+      pending.set([...pending.peek(), action]);
+      value.set(optimisticValue);
+    });
+  }
+
+  function resolve(action) {
+    pending.set(pending.peek().filter(a => a !== action));
+  }
+
+  function rollback(action, realValue) {
+    batch(() => {
+      pending.set(pending.peek().filter(a => a !== action));
+      value.set(realValue);
+    });
+  }
+
+  return {
+    value: () => value(),
+    isPending: () => pending().length > 0,
+    addOptimistic,
+    resolve,
+    rollback,
+    set: (v) => value.set(v),
+  };
+}
+
+// --- Path revalidation ---
+
+const revalidationCallbacks = new Map();
+
+export function onRevalidate(path, callback) {
+  if (!revalidationCallbacks.has(path)) {
+    revalidationCallbacks.set(path, new Set());
+  }
+  revalidationCallbacks.get(path).add(callback);
+
+  return () => {
+    revalidationCallbacks.get(path)?.delete(callback);
+  };
+}
+
+export function invalidatePath(path) {
+  const callbacks = revalidationCallbacks.get(path);
+  if (callbacks) {
+    for (const cb of callbacks) {
+      try { cb(); } catch (e) { console.error('[what] Revalidation error:', e); }
+    }
+  }
+}
+
+// --- Server-side action handler ---
+// Add this to your server middleware.
+
+export function handleActionRequest(req, actionId, args) {
+  const action = actionRegistry.get(actionId);
+  if (!action) {
+    return { status: 404, body: { message: `Action "${actionId}" not found` } };
+  }
+
+  return action.fn(...args)
+    .then(result => ({ status: 200, body: result }))
+    .catch(error => ({
+      status: 500,
+      body: { message: error.message || 'Action failed' },
+    }));
+}
+
+// --- Get all registered actions (for SSR/build) ---
+
+export function getRegisteredActions() {
+  return [...actionRegistry.keys()];
+}
+
+// --- Mutation helper ---
+// Like useSWR mutation but simpler.
+
+export function useMutation(mutationFn, options = {}) {
+  const { onSuccess, onError, onSettled } = options;
+
+  const state = {
+    isPending: signal(false),
+    error: signal(null),
+    data: signal(null),
+  };
+
+  async function mutate(...args) {
+    state.isPending.set(true);
+    state.error.set(null);
+
+    try {
+      const result = await mutationFn(...args);
+      state.data.set(result);
+      if (onSuccess) onSuccess(result, ...args);
+      return result;
+    } catch (error) {
+      state.error.set(error);
+      if (onError) onError(error, ...args);
+      throw error;
+    } finally {
+      state.isPending.set(false);
+      if (onSettled) onSettled(state.data.peek(), state.error.peek(), ...args);
+    }
+  }
+
+  return {
+    mutate,
+    isPending: () => state.isPending(),
+    error: () => state.error(),
+    data: () => state.data(),
+    reset: () => {
+      state.error.set(null);
+      state.data.set(null);
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1,217 @@
+// What Framework - Server
+// SSR, static site generation, server components.
+// Zero-JS pages by default. Islands opt-in to client JS.
+
+import { h } from 'what-core';
+
+// --- Render to String ---
+// Renders a VNode tree to an HTML string. Used for SSR and static gen.
+
+export function renderToString(vnode) {
+  if (vnode == null || vnode === false || vnode === true) return '';
+
+  // Text
+  if (typeof vnode === 'string' || typeof vnode === 'number') {
+    return escapeHtml(String(vnode));
+  }
+
+  // Array
+  if (Array.isArray(vnode)) {
+    return vnode.map(renderToString).join('');
+  }
+
+  // Component
+  if (typeof vnode.tag === 'function') {
+    const result = vnode.tag({ ...vnode.props, children: vnode.children });
+    return renderToString(result);
+  }
+
+  // Element
+  const { tag, props, children } = vnode;
+  const attrs = renderAttrs(props || {});
+  const open = `<${tag}${attrs}>`;
+
+  // Void elements
+  if (VOID_ELEMENTS.has(tag)) return open;
+
+  const inner = children.map(renderToString).join('');
+  return `${open}${inner}</${tag}>`;
+}
+
+// --- Stream Render ---
+// Returns an async iterator for streaming SSR.
+
+export async function* renderToStream(vnode) {
+  if (vnode == null || vnode === false || vnode === true) return;
+
+  if (typeof vnode === 'string' || typeof vnode === 'number') {
+    yield escapeHtml(String(vnode));
+    return;
+  }
+
+  if (Array.isArray(vnode)) {
+    for (const child of vnode) {
+      yield* renderToStream(child);
+    }
+    return;
+  }
+
+  if (typeof vnode.tag === 'function') {
+    const result = vnode.tag({ ...vnode.props, children: vnode.children });
+    // Support async components
+    const resolved = result instanceof Promise ? await result : result;
+    yield* renderToStream(resolved);
+    return;
+  }
+
+  const { tag, props, children } = vnode;
+  const attrs = renderAttrs(props || {});
+  yield `<${tag}${attrs}>`;
+
+  if (!VOID_ELEMENTS.has(tag)) {
+    for (const child of children) {
+      yield* renderToStream(child);
+    }
+    yield `</${tag}>`;
+  }
+}
+
+// --- Static Site Generation ---
+
+export function definePage(config) {
+  return {
+    // 'static' = pre-render at build time (default)
+    // 'server' = render on each request
+    // 'client' = render in browser (SPA)
+    // 'hybrid' = static shell + islands
+    mode: 'static',
+    ...config,
+  };
+}
+
+// Generate static HTML for a page
+export function generateStaticPage(page, data = {}) {
+  const vnode = page.component(data);
+  const html = renderToString(vnode);
+  const islands = page.islands || [];
+
+  return wrapDocument({
+    title: page.title || '',
+    meta: page.meta || {},
+    body: html,
+    islands,
+    scripts: page.mode === 'static' ? [] : page.scripts || [],
+    styles: page.styles || [],
+    mode: page.mode,
+  });
+}
+
+function wrapDocument({ title, meta, body, islands, scripts, styles, mode }) {
+  const metaTags = Object.entries(meta)
+    .map(([name, content]) => `<meta name="${name}" content="${escapeHtml(content)}">`)
+    .join('\n    ');
+
+  const styleTags = styles
+    .map(href => `<link rel="stylesheet" href="${escapeHtml(href)}">`)
+    .join('\n    ');
+
+  const islandScript = islands.length > 0 ? `
+    <script type="module">
+      import { hydrateIslands } from '/@what/islands.js';
+      hydrateIslands();
+    </script>` : '';
+
+  const scriptTags = scripts
+    .map(src => `<script type="module" src="${escapeHtml(src)}"></script>`)
+    .join('\n    ');
+
+  const clientScript = mode === 'client' ? `
+    <script type="module" src="/@what/client.js"></script>` : '';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    ${metaTags}
+    <title>${escapeHtml(title)}</title>
+    ${styleTags}
+  </head>
+  <body>
+    <div id="app">${body}</div>
+    ${islandScript}
+    ${scriptTags}
+    ${clientScript}
+  </body>
+</html>`;
+}
+
+// --- Server Component ---
+// Renders on the server, sends HTML to client. No JS shipped.
+
+export function server(Component) {
+  Component._server = true;
+  return Component;
+}
+
+// --- Helpers ---
+
+function renderAttrs(props) {
+  let out = '';
+  for (const [key, val] of Object.entries(props)) {
+    if (key === 'key' || key === 'ref' || key === 'children' || key === 'dangerouslySetInnerHTML') continue;
+    if (key.startsWith('on') && key.length > 2) continue; // Skip event handlers in SSR
+    if (val === false || val == null) continue;
+
+    if (key === 'className' || key === 'class') {
+      out += ` class="${escapeHtml(String(val))}"`;
+    } else if (key === 'style' && typeof val === 'object') {
+      const css = Object.entries(val)
+        .map(([p, v]) => `${camelToKebab(p)}:${v}`)
+        .join(';');
+      out += ` style="${escapeHtml(css)}"`;
+    } else if (val === true) {
+      out += ` ${key}`;
+    } else {
+      out += ` ${key}="${escapeHtml(String(val))}"`;
+    }
+  }
+
+  // Handle dangerouslySetInnerHTML separately
+  if (props.dangerouslySetInnerHTML) {
+    // This is handled in the content rendering, not attrs
+  }
+
+  return out;
+}
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function camelToKebab(str) {
+  return str.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+// Re-export server actions
+export {
+  action,
+  formAction,
+  useAction,
+  useFormAction,
+  useOptimistic,
+  useMutation,
+  onRevalidate,
+  invalidatePath,
+  handleActionRequest,
+  getRegisteredActions,
+} from './actions.js';

package/src/islands.js

@@ -0,0 +1,399 @@
+// What Framework - Islands Architecture
+// Each interactive piece of the page is an "island" — a self-contained
+// component that hydrates independently. The rest is static HTML.
+//
+// Features:
+//   - Multiple hydration modes (load, idle, visible, action, media, static)
+//   - Shared state across islands
+//   - Priority-based hydration queue
+//   - Progressive enhancement
+//
+// Modes:
+//   'static'  - No JS shipped. Pure HTML. (nav, footer, etc.)
+//   'idle'    - Hydrate when browser is idle (requestIdleCallback)
+//   'visible' - Hydrate when scrolled into view (IntersectionObserver)
+//   'load'    - Hydrate immediately on page load
+//   'media'   - Hydrate when media query matches (e.g., mobile-only)
+//   'action'  - Hydrate on first user interaction (click, focus, hover)
+
+import { mount, signal, batch } from 'what-core';
+
+const islandRegistry = new Map();
+const hydratedIslands = new Set();
+const hydrationQueue = [];
+let isProcessingQueue = false;
+
+// --- Shared Island State ---
+// Global reactive store that persists across islands and page navigations
+
+const sharedStores = new Map();
+
+export function createIslandStore(name, initialState) {
+  if (sharedStores.has(name)) {
+    return sharedStores.get(name);
+  }
+
+  const store = {};
+  const signals = {};
+
+  // Create signals for each key in initial state
+  for (const [key, value] of Object.entries(initialState)) {
+    signals[key] = signal(value);
+    Object.defineProperty(store, key, {
+      get: () => signals[key](),
+      set: (val) => signals[key].set(val),
+      enumerable: true,
+    });
+  }
+
+  // Methods to interact with store
+  store._signals = signals;
+  store._subscribe = (key, fn) => {
+    if (signals[key]) {
+      return signals[key].subscribe(fn);
+    }
+  };
+  store._batch = (fn) => batch(fn);
+  store._getSnapshot = () => {
+    const snapshot = {};
+    for (const [key, sig] of Object.entries(signals)) {
+      snapshot[key] = sig.peek();
+    }
+    return snapshot;
+  };
+  store._hydrate = (data) => {
+    batch(() => {
+      for (const [key, value] of Object.entries(data)) {
+        if (signals[key]) {
+          signals[key].set(value);
+        }
+      }
+    });
+  };
+
+  sharedStores.set(name, store);
+  return store;
+}
+
+// Get or create a shared store
+export function useIslandStore(name, fallbackInitial = {}) {
+  if (sharedStores.has(name)) {
+    return sharedStores.get(name);
+  }
+  return createIslandStore(name, fallbackInitial);
+}
+
+// Serialize all shared stores for SSR
+export function serializeIslandStores() {
+  const data = {};
+  for (const [name, store] of sharedStores) {
+    data[name] = store._getSnapshot();
+  }
+  return JSON.stringify(data);
+}
+
+// Hydrate shared stores from SSR data
+export function hydrateIslandStores(serialized) {
+  try {
+    const data = typeof serialized === 'string' ? JSON.parse(serialized) : serialized;
+    for (const [name, storeData] of Object.entries(data)) {
+      const store = useIslandStore(name, storeData);
+      store._hydrate(storeData);
+    }
+  } catch (e) {
+    console.warn('[what] Failed to hydrate island stores:', e);
+  }
+}
+
+// --- Register an island component ---
+
+export function island(name, loader, opts = {}) {
+  islandRegistry.set(name, {
+    loader,  // () => import('./MyComponent.js')
+    mode: opts.mode || 'idle',
+    media: opts.media || null,
+    priority: opts.priority || 0, // Higher = hydrate first
+    stores: opts.stores || [],    // Shared stores this island uses
+  });
+}
+
+// --- Island wrapper for SSR ---
+// Renders the static HTML with a marker the client can find.
+
+export function Island({ name, props = {}, children, mode, priority, stores }) {
+  const entry = islandRegistry.get(name);
+  const resolvedMode = mode || entry?.mode || 'idle';
+  const resolvedPriority = priority ?? entry?.priority ?? 0;
+  const resolvedStores = stores || entry?.stores || [];
+
+  // Server: render as a div with data attributes for hydration
+  return {
+    tag: 'div',
+    props: {
+      'data-island': name,
+      'data-island-mode': resolvedMode,
+      'data-island-props': JSON.stringify(props),
+      'data-island-priority': resolvedPriority,
+      'data-island-stores': JSON.stringify(resolvedStores),
+    },
+    children: children || [],
+    key: null,
+    _vnode: true,
+  };
+}
+
+// --- Priority Hydration Queue ---
+
+function enqueueHydration(task) {
+  // Insert in priority order (higher priority first)
+  let inserted = false;
+  for (let i = 0; i < hydrationQueue.length; i++) {
+    if (task.priority > hydrationQueue[i].priority) {
+      hydrationQueue.splice(i, 0, task);
+      inserted = true;
+      break;
+    }
+  }
+  if (!inserted) {
+    hydrationQueue.push(task);
+  }
+
+  processQueue();
+}
+
+function processQueue() {
+  if (isProcessingQueue || hydrationQueue.length === 0) return;
+  isProcessingQueue = true;
+
+  // Process one task at a time to avoid blocking
+  const task = hydrationQueue.shift();
+
+  Promise.resolve(task.hydrate())
+    .catch(e => console.error('[what] Island hydration failed:', task.name, e))
+    .finally(() => {
+      isProcessingQueue = false;
+      // Continue processing after a microtask
+      queueMicrotask(processQueue);
+    });
+}
+
+// Boost priority for an island (e.g., on user interaction)
+export function boostIslandPriority(name, newPriority = 100) {
+  for (const task of hydrationQueue) {
+    if (task.name === name) {
+      task.priority = newPriority;
+      // Re-sort queue
+      hydrationQueue.sort((a, b) => b.priority - a.priority);
+      break;
+    }
+  }
+}
+
+// --- Client-side hydration ---
+
+export function hydrateIslands() {
+  // First, hydrate any shared stores from the page
+  const storeScript = document.querySelector('script[data-island-stores]');
+  if (storeScript) {
+    hydrateIslandStores(storeScript.textContent);
+  }
+
+  const islands = document.querySelectorAll('[data-island]');
+
+  for (const el of islands) {
+    const name = el.dataset.island;
+    const mode = el.dataset.islandMode || 'idle';
+    const props = JSON.parse(el.dataset.islandProps || '{}');
+    const priority = parseInt(el.dataset.islandPriority || '0', 10);
+    const stores = JSON.parse(el.dataset.islandStores || '[]');
+    const entry = islandRegistry.get(name);
+
+    if (!entry) {
+      console.warn(`[what] Island "${name}" not registered`);
+      continue;
+    }
+
+    // Skip if already hydrated
+    if (hydratedIslands.has(el)) continue;
+
+    scheduleHydration(el, entry, props, mode, priority, name, stores);
+  }
+}
+
+function scheduleHydration(el, entry, props, mode, priority, name, stores) {
+  const hydrate = async () => {
+    if (hydratedIslands.has(el)) return;
+    hydratedIslands.add(el);
+
+    const mod = await entry.loader();
+    const Component = mod.default || mod;
+
+    // Inject shared stores into props
+    const storeProps = {};
+    for (const storeName of stores) {
+      storeProps[storeName] = useIslandStore(storeName);
+    }
+
+    mount(Component({ ...props, ...storeProps }), el);
+
+    // Clean up data attributes
+    el.removeAttribute('data-island');
+    el.removeAttribute('data-island-mode');
+    el.removeAttribute('data-island-props');
+    el.removeAttribute('data-island-priority');
+    el.removeAttribute('data-island-stores');
+
+    // Dispatch event for analytics/debugging
+    el.dispatchEvent(new CustomEvent('island:hydrated', {
+      bubbles: true,
+      detail: { name, mode },
+    }));
+  };
+
+  switch (mode) {
+    case 'load':
+      // Immediate hydration via queue (respects priority)
+      enqueueHydration({ name, priority: priority + 1000, hydrate });
+      break;
+
+    case 'idle':
+      if ('requestIdleCallback' in window) {
+        requestIdleCallback(() => {
+          enqueueHydration({ name, priority, hydrate });
+        });
+      } else {
+        setTimeout(() => {
+          enqueueHydration({ name, priority, hydrate });
+        }, 200);
+      }
+      break;
+
+    case 'visible': {
+      const observer = new IntersectionObserver((entries, obs) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            obs.disconnect();
+            enqueueHydration({ name, priority, hydrate });
+            break;
+          }
+        }
+      }, { rootMargin: '200px' });
+      observer.observe(el);
+      break;
+    }
+
+    case 'media': {
+      const mq = window.matchMedia(entry.media || '(max-width: 768px)');
+      if (mq.matches) {
+        enqueueHydration({ name, priority, hydrate });
+      } else {
+        mq.addEventListener('change', (e) => {
+          if (e.matches) {
+            enqueueHydration({ name, priority, hydrate });
+          }
+        }, { once: true });
+      }
+      break;
+    }
+
+    case 'action': {
+      const events = ['click', 'focus', 'mouseover', 'touchstart'];
+      const handler = () => {
+        events.forEach(e => el.removeEventListener(e, handler));
+        // Boost priority since user interacted
+        enqueueHydration({ name, priority: priority + 500, hydrate });
+      };
+      events.forEach(e => el.addEventListener(e, handler, { once: true, passive: true }));
+      break;
+    }
+
+    case 'static':
+      // Never hydrate
+      break;
+
+    default:
+      enqueueHydration({ name, priority, hydrate });
+  }
+}
+
+// --- Auto-discover islands from data attributes ---
+// Call this once on the client to set up all islands.
+
+export function autoIslands(registry) {
+  for (const [name, config] of Object.entries(registry)) {
+    island(name, config.loader || config, {
+      mode: config.mode || 'idle',
+      media: config.media,
+      priority: config.priority || 0,
+      stores: config.stores || [],
+    });
+  }
+
+  if (typeof document !== 'undefined') {
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', hydrateIslands);
+    } else {
+      hydrateIslands();
+    }
+  }
+}
+
+// --- Progressive Enhancement Helpers ---
+
+// Mark an element as progressively enhanced
+export function enhance(selector, handler) {
+  if (typeof document === 'undefined') return;
+
+  const elements = document.querySelectorAll(selector);
+  for (const el of elements) {
+    if (el.dataset.enhanced) continue;
+    el.dataset.enhanced = 'true';
+    handler(el);
+  }
+}
+
+// Form enhancement: submit via fetch instead of page reload
+export function enhanceForms(selector = 'form[data-enhance]') {
+  enhance(selector, (form) => {
+    form.addEventListener('submit', async (e) => {
+      e.preventDefault();
+
+      const formData = new FormData(form);
+      const method = form.method.toUpperCase() || 'POST';
+      const action = form.action || location.href;
+
+      try {
+        const response = await fetch(action, {
+          method,
+          body: method === 'GET' ? undefined : formData,
+          headers: {
+            'X-Requested-With': 'XMLHttpRequest',
+          },
+        });
+
+        form.dispatchEvent(new CustomEvent('form:response', {
+          bubbles: true,
+          detail: { response, ok: response.ok },
+        }));
+      } catch (error) {
+        form.dispatchEvent(new CustomEvent('form:error', {
+          bubbles: true,
+          detail: { error },
+        }));
+      }
+    });
+  });
+}
+
+// --- Debugging ---
+
+export function getIslandStatus() {
+  const status = {
+    registered: [...islandRegistry.keys()],
+    hydrated: hydratedIslands.size,
+    pending: hydrationQueue.length,
+    queue: hydrationQueue.map(t => ({ name: t.name, priority: t.priority })),
+    stores: [...sharedStores.keys()],
+  };
+  return status;
+}