@coherent.js/client 1.1.1 → 2.0.0-rc.0

package/types/index.d.ts

@@ -1,8 +1,10 @@
 /**
  * Coherent.js Client Types
- * TypeScript definitions for client-side functionality
+ * TypeScript definitions for @coherent.js/client: hydration, event
+ * delegation, state serialization, mismatch detection and HMR.
  *
- * @version 1.0.0-beta.1
+ * The router is the `@coherent.js/client/router` entry point; its types are
+ * re-exported here.
  */
 
 // Import core types for component integration
@@ -28,39 +30,45 @@ export type {
 };
 
 // ============================================================================
-// DOM and Browser Types
-// ============================================================================
-
-/** HTML element with Coherent.js data attributes */
-export interface CoherentHTMLElement extends HTMLElement {
-  'data-coherent-state'?: string;
-  'data-coherent-component'?: string;
-  'data-coherent-id'?: string;
-  'data-action'?: string;
-  'data-event'?: string;
-  'data-count'?: string;
-  'data-step'?: string;
-  'data-active'?: string;
-  'data-loading'?: string;
-  'data-disabled'?: string;
-  'data-selected'?: string;
-  'data-expanded'?: string;
-  'data-visible'?: string;
-  __coherentInstance?: HydratedInstance;
-}
-
-// ============================================================================
-// Event Handler Types - Specific DOM Events
+// Events
 // ============================================================================
 
 /**
- * Generic event handler type.
- * The handler receives the DOM event, the element, and optional custom data.
+ * What a delegated handler (an `on*` prop bound by `hydrate()`) receives: the
+ * native event plus the component it belongs to.
  */
-export type EventHandler<E extends Event = Event> = (
-  event: E,
-  element: HTMLElement,
-  data?: any
+export interface CoherentEvent<S = any, E extends Event = Event> {
+  /** The native DOM event */
+  originalEvent: E;
+  /** The event type, e.g. `'click'` */
+  type: string;
+  /** The element whose handler runs (the one carrying the handler) */
+  target: Element;
+  /** Same as `target` */
+  currentTarget: Element;
+  /** Whether the default action was prevented */
+  readonly defaultPrevented: boolean;
+  /** Whether a handler stopped propagation to ancestor handlers */
+  propagationStopped: boolean;
+  /** Prevent the default action (all delegated types but touch/wheel/scroll) */
+  preventDefault(): void;
+  /** Stop ancestor handlers and native propagation */
+  stopPropagation(): void;
+  /** Like stopPropagation(), also for other native listeners */
+  stopImmediatePropagation(): void;
+  /** The hydrated component function */
+  component: ((props?: any) => CoherentNode) | null;
+  /** The component's state when the event fired */
+  state: S | null;
+  /** Merge state and re-render the component */
+  setState: ((newState: Partial<S> | ((prev: S) => Partial<S>)) => void) | null;
+  /** The props the component last rendered with (state included) */
+  props: Record<string, any> | null;
+}
+
+/** A delegated event handler. */
+export type EventHandler<E extends Event = Event, S = any> = (
+  event: CoherentEvent<S, E>
 ) => void | Promise<void>;
 
 /** Click event handler (MouseEvent) */
@@ -96,14 +104,9 @@ export type TouchHandler = EventHandler<TouchEvent>;
 /** Wheel event handler (WheelEvent) */
 export type WheelHandler = EventHandler<WheelEvent>;
 
-/**
- * State-aware event handler used in components.
- * Receives event, current state, and setState function.
- */
+/** A delegated handler typed by the component's state. */
 export type StateAwareHandler<S = any, E extends Event = Event> = (
-  event: E,
-  state: S,
-  setState: (newState: Partial<S> | ((prev: S) => Partial<S>)) => void
+  event: CoherentEvent<S, E>
 ) => void | Promise<void>;
 
 // ============================================================================
@@ -130,98 +133,46 @@ export interface SerializableState {
 // Hydration Types
 // ============================================================================
 
-/** Hydration options */
+/** Options for {@link hydrate} */
 export interface HydrationOptions {
+  /** State to hydrate with; defaults to the container's `data-state` */
   initialState?: SerializableState;
-  autoHydrate?: boolean;
-  selector?: string;
-  preserveState?: boolean;
-  enableEvents?: boolean;
-  debugMode?: boolean;
-  timeout?: number;
-  onError?: (error: Error, element?: HTMLElement) => void;
-  onSuccess?: (element: HTMLElement, state: SerializableState) => void;
-  transforms?: StateTransforms;
-  validators?: StateValidators;
-  /** Enable mismatch detection (dev mode default: true) */
+  /**
+   * Compare the server DOM with the component's output. Defaults to on when
+   * `strict` or `onMismatch` is given or `process.env.NODE_ENV` is
+   * `'development'`, off otherwise.
+   */
   detectMismatch?: boolean;
   /** Throw on mismatch instead of warning */
   strict?: boolean;
-  /** Custom mismatch handler */
+  /** Receive mismatches instead of the console warning */
   onMismatch?: (mismatches: HydrationMismatch[]) => void;
   /** Additional props to pass to component */
   props?: Record<string, any>;
 }
 
-/** State transformation functions */
-export interface StateTransforms {
-  [key: string]: (value: any) => any;
-}
-
-/** State validation functions */
-export interface StateValidators {
-  [key: string]: (value: any) => boolean;
-}
-
-/** Hydration mismatch information */
+/** One difference between the server DOM and the component's output */
 export interface HydrationMismatch {
+  /** Position in the virtual tree, e.g. `children[1].@class` */
   path: string;
-  type: 'text' | 'attribute' | 'tag' | 'children' | 'missing' | 'extra';
+  type:
+    | 'text'
+    | 'tagName'
+    | 'attribute'
+    | 'children_count'
+    | 'missing_dom_child'
+    | 'extra_dom_child';
   expected: any;
   actual: any;
-}
-
-/** Component hydration result */
-export interface HydrationResult {
-  success: boolean;
-  element: HTMLElement;
-  state: SerializableState;
-  component?: ClientComponent;
-  error?: Error;
-  duration?: number;
-}
-
-/** Batch hydration result */
-export interface BatchHydrationResult {
-  total: number;
-  successful: number;
-  failed: number;
-  results: HydrationResult[];
-  errors: Array<{ element: HTMLElement; error: Error }>;
-  duration: number;
-}
-
-/**
- * Hydrated component instance returned by hydrate().
- * Provides control methods for state management and lifecycle.
- */
-export interface HydratedInstance {
-  /** The DOM element being hydrated */
-  element: HTMLElement;
-  /** The component function */
-  component: CoherentComponent;
-  /** Current props */
-  props: Record<string, any>;
-  /** Current state */
-  state: SerializableState;
-  /** Whether hydration is complete */
-  isHydrated: boolean;
-
-  /** Update props and re-render */
-  update(newProps?: Record<string, any>): HydratedInstance;
-  /** Re-render with current state */
-  rerender(): void;
-  /** Destroy the instance and clean up */
-  destroy(): void;
-  /** Set state and trigger re-render */
-  setState(newState: Partial<SerializableState> | ((prev: SerializableState) => Partial<SerializableState>)): void;
+  /** CSS-like path of the DOM element, for debugging */
+  domPath: string;
 }
 
 /**
  * Control object returned by the clean hydrate() API.
  */
 export interface HydrateControl {
-  /** Unmount the component and clean up event handlers */
+  /** Unmount the component and clean up event handlers; terminal */
   unmount(): void;
   /** Re-render with optional new props */
   rerender(newProps?: Record<string, any>): void;
@@ -231,90 +182,15 @@ export interface HydrateControl {
   setState(newState: Partial<SerializableState> | ((prev: SerializableState) => Partial<SerializableState>)): void;
 }
 
-export interface MakeHydratableOptions {
-  componentName?: string;
-  initialState?: SerializableState;
-}
-
-// ============================================================================
-// Client Component Types
-// ============================================================================
-
-/** Client-side component interface */
-export interface ClientComponent {
-  readonly element: HTMLElement;
-  readonly state: SerializableState;
-  readonly isHydrated: boolean;
-  readonly id: string;
-
-  setState(newState: Partial<SerializableState>): void;
-  updateState(updater: (state: SerializableState) => Partial<SerializableState>): void;
-  getState(): SerializableState;
-  resetState(): void;
-
-  render(): void;
-  destroy(): void;
-  refresh(): void;
-
-  addEventListener(event: string, handler: EventHandler): void;
-  removeEventListener(event: string, handler: EventHandler): void;
-  trigger(event: string, data?: any): void;
-
-  serialize(): string;
-  toJSON(): SerializableState;
-}
-
-/** Component factory function */
-export type ComponentFactory = (element: HTMLElement, initialState?: SerializableState) => ClientComponent;
-
-/** Component registry entry */
-export interface ComponentRegistryEntry {
-  name: string;
-  factory: ComponentFactory;
-  selector?: string;
-  autoHydrate?: boolean;
-}
-
 // ============================================================================
-// Event System Types
+// Event Delegation Types
 // ============================================================================
 
-/** Event binding configuration */
-export interface EventBinding {
-  event: string;
-  selector?: string;
-  handler: EventHandler;
-  options?: EventListenerOptions | boolean;
-  delegate?: boolean;
-  once?: boolean;
-}
-
-/** Event manager interface */
-export interface EventManager {
-  bind(element: HTMLElement, bindings: EventBinding[]): void;
-  unbind(element: HTMLElement, event?: string): void;
-  trigger(element: HTMLElement, event: string, data?: any): void;
-  delegate(container: HTMLElement, selector: string, event: string, handler: EventHandler): void;
-  undelegate(container: HTMLElement, selector?: string, event?: string): void;
-  once(element: HTMLElement, event: string, handler: EventHandler): void;
-  debounce(handler: EventHandler, delay: number): EventHandler;
-  throttle(handler: EventHandler, limit: number): EventHandler;
-}
-
-/** Custom event data */
-export interface CustomEventData {
-  detail: any;
-  bubbles?: boolean;
-  cancelable?: boolean;
-  composed?: boolean;
-}
-
-// ============================================================================
-// Event Delegation Types (Plan 02-01)
-// ============================================================================
-
-/** A component whose state a delegated handler may read and write */
+/** The component a delegated handler belongs to */
 export interface HandlerComponentRef {
+  component?: (props?: any) => CoherentNode;
+  state?: any;
+  props?: Record<string, any>;
   getState?: () => any;
   setState?: (state: any) => void;
   [key: string]: any;
@@ -322,14 +198,19 @@ export interface HandlerComponentRef {
 
 /** A registered handler and the component it belongs to */
 export interface RegisteredHandler {
-  handler: StateAwareHandler;
+  handler: StateAwareHandler<any, any>;
   componentRef: HandlerComponentRef | null;
 }
 
 /**
  * Routes document-level events to handlers registered by id.
  *
- * Focus and blur are delegated in the capture phase, since they do not bubble.
+ * Listeners are non-passive, so handlers can call `preventDefault()`, except
+ * for scroll-blocking types (touchstart, touchmove, wheel, scroll). Handlers
+ * run from the target's nearest `data-coherent-{type}` element outwards, like
+ * bubbling, until one stops propagation. Focus and blur are captured, since
+ * they do not bubble natively; other non-bubbling events (mouseenter, load,
+ * ...) only reach a handler on the target itself.
  */
 export class EventDelegation {
   constructor(registry?: HandlerRegistry);
@@ -343,10 +224,16 @@ export class EventDelegation {
   /** Attach listeners to `root`; idempotent, and a no-op without a document */
   initialize(root?: Document | Element | null): void;
 
-  /** Dispatch one delegated event to its registered handler */
+  /**
+   * Delegate `eventType` too. hydrate() calls this for every event type a
+   * component handles, so any DOM event works, not only the defaults.
+   */
+  listen(eventType: string): void;
+
+  /** Dispatch one delegated event to its registered handlers */
   handleEvent(event: Event, eventType: string): void;
 
-  /** Remove every listener attached by `initialize()` */
+  /** Remove every listener attached by `initialize()` and `listen()` */
   destroy(): void;
 
   isInitialized(): boolean;
@@ -361,7 +248,7 @@ export class HandlerRegistry {
   /** Register a handler, optionally bound to a component */
   register(
     handlerId: string,
-    handler: StateAwareHandler,
+    handler: StateAwareHandler<any, any>,
     componentRef?: HandlerComponentRef | null
   ): void;
 
@@ -380,489 +267,239 @@ export class HandlerRegistry {
 }
 
 // ============================================================================
-// State Management Types
+// Hot Module Replacement Types
 // ============================================================================
 
-/** Client state manager */
-export interface ClientStateManager {
-  get<T = any>(key: string): T | undefined;
-  set<T = any>(key: string, value: T): void;
-  has(key: string): boolean;
-  delete(key: string): boolean;
-  clear(): void;
-  keys(): string[];
-  values(): any[];
-  entries(): Array<[string, any]>;
-  size(): number;
-
-  subscribe(key: string, callback: (value: any, oldValue?: any) => void): () => void;
-  unsubscribe(key: string, callback?: Function): void;
-
-  persist(key: string, storage?: Storage): void;
-  unpersist(key: string): void;
-
-  batch(fn: () => void): void;
-
-  toJSON(): Record<string, any>;
-  fromJSON(data: Record<string, any>): void;
-}
-
-/** State synchronization options */
-export interface StateSyncOptions {
-  key: string;
-  storage?: Storage;
-  serializer?: {
-    stringify: (value: any) => string;
-    parse: (value: string) => any;
-  };
-  debounce?: number;
-  validate?: (value: any) => boolean;
-  transform?: (value: any) => any;
+/** Hot context API for a module (see {@link createHotContext}) */
+export interface HotContext {
+  /** Data persisted across HMR updates of this module */
+  readonly data: Record<string, any>;
+  /** Accept self updates; without it an update reloads the page */
+  accept(callback?: (newModule: any) => void): void;
+  /** Accept updates of dependencies */
+  acceptDeps(deps: string | string[], callback: (modules: Record<string, any>) => void): void;
+  /** Cleanup before the module is replaced; receives `data` */
+  dispose(callback: (data: Record<string, any>) => void): void;
+  /** Called when the module is removed from the module graph */
+  prune(callback: () => void): void;
+  /** Ask the dev server to propagate the update to importers */
+  invalidate(message?: string): void;
+}
+
+/** Tracked timers, listeners and fetches of one module */
+export interface HMRModuleContext {
+  setTimeout(callback: (...args: any[]) => void, delay?: number, ...args: any[]): ReturnType<typeof setTimeout>;
+  setInterval(callback: (...args: any[]) => void, delay?: number, ...args: any[]): ReturnType<typeof setInterval>;
+  clearTimeout(id: ReturnType<typeof setTimeout>): void;
+  clearInterval(id: ReturnType<typeof setInterval>): void;
+  addEventListener(
+    target: EventTarget,
+    event: string,
+    handler: EventListenerOrEventListenerObject,
+    options?: AddEventListenerOptions | boolean
+  ): void;
+  createAbortController(): AbortController;
+  /** fetch() aborted on module disposal and by the caller's own `signal` */
+  fetch(url: string | URL, options?: RequestInit): Promise<Response>;
 }
 
-// ============================================================================
-// Hot Module Replacement Types
-// ============================================================================
-
-/** HMR update information */
-export interface HMRUpdate {
-  type: 'component' | 'style' | 'script' | 'template' | 'full-reload';
-  id: string;
-  path: string;
-  content?: string;
-  timestamp: number;
-  /** File that changed (for error display) */
+/** An error shown by the overlay */
+export interface HMRErrorDetails {
+  message: string;
   file?: string;
-  /** Line number for error */
   line?: number;
-  /** Column number for error */
   column?: number;
+  frame?: string;
+  stack?: string;
 }
 
-/** HMR event listener */
-export type HMRListener = (update: HMRUpdate) => void | Promise<void>;
-
-/** HMR configuration */
-export interface HMRConfig {
-  enabled: boolean;
-  websocketUrl?: string;
-  reconnectInterval?: number;
-  maxReconnectAttempts?: number;
-  debug?: boolean;
-  onUpdate?: HMRListener;
-  onError?: (error: Error) => void;
-  onReconnect?: () => void;
-  /** Show error overlay */
-  overlay?: boolean;
-  /** Show connection indicator */
-  indicator?: boolean;
-}
+/** WebSocket client that applies dev-server updates */
+export class HMRClient {
+  constructor();
 
-/** HMR client interface */
-export interface HMRClient {
-  readonly isConnected: boolean;
-  readonly config: HMRConfig;
+  socket: WebSocket | null;
+  connected: boolean;
+  reconnectAttempts: number;
+  maxReconnectAttempts: number;
+  reconnectDelay: number;
+  hadDisconnect: boolean;
+  reconnectTimeout: ReturnType<typeof setTimeout> | null;
+  initialized: boolean;
 
-  connect(): Promise<void>;
+  /** Connect once per page (no-op without `window`) */
+  initialize(): void;
+  /** Open the WebSocket, reconnecting with backoff when it closes */
+  connect(): void;
+  /** Close the socket without reconnecting */
   disconnect(): void;
+  isConnected(): boolean;
+  scheduleReconnect(): void;
+  handleMessage(event: MessageEvent): void;
+  /** Re-import a changed module; reloads the page when it does not accept updates */
+  handleUpdate(data: { filePath?: string; webPath?: string; updateType?: string }): Promise<void>;
+  /** Import an updated module (overridable) */
+  importModule(url: string): Promise<any>;
+  /** Reload the page */
+  reload(): void;
+  handleUpdateError(error: Error, filePath: string): void;
+  showError(error: HMRErrorDetails): void;
+  hideError(): void;
+}
+
+/** Hot contexts and update handlers by module id */
+export class ModuleTracker {
+  constructor();
 
-  onUpdate(listener: HMRListener): () => void;
-  onError(listener: (error: Error) => void): () => void;
-  onReconnect(listener: () => void): () => void;
-
-  updateComponent(id: string, factory: ComponentFactory): void;
-  updateStyle(id: string, css: string): void;
-  reloadPage(): void;
-}
-
-/** Hot context API for modules (Vite-compatible) */
-export interface HotContext {
-  /** Accept self updates */
-  accept(): void;
-  /** Accept updates from dependencies */
-  accept(deps: string | string[], callback?: (modules: any[]) => void): void;
-  /** Dispose callback for cleanup */
-  dispose(callback: (data: any) => void): void;
-  /** Prune callback when module is removed */
-  prune(callback: () => void): void;
-  /** Invalidate to trigger parent update */
-  invalidate(): void;
-  /** Decline to fall back to full reload */
-  decline(): void;
-  /** Data persisted across HMR updates */
-  data: Record<string, any>;
-}
-
-/** Module tracker for HMR boundary detection */
-export interface ModuleTracker {
-  /** Track a module with its hot context */
-  track(moduleId: string, context: HotContext): void;
-  /** Check if module is a boundary */
-  isBoundary(moduleId: string): boolean;
-  /** Get hot context for module */
-  getContext(moduleId: string): HotContext | undefined;
-  /** Clear tracked modules */
+  modules: Map<string, any>;
+  socket: WebSocket | null;
+
+  setSocket(socket: WebSocket | null): void;
+  createHotContext(moduleId: string): HotContext;
+  canHotUpdate(moduleId: string): boolean;
+  isHmrBoundary(moduleId: string, moduleExports?: Record<string, any>): boolean;
+  extractComponentName(moduleId: string): string | null;
+  executeDispose(moduleId: string): Record<string, any> | null;
+  executeAccept(moduleId: string, newModule?: any): boolean;
+  executeAcceptDeps(moduleId: string, updatedDeps: Record<string, any>): boolean;
+  executePrune(moduleId: string): void;
+  hasModule(moduleId: string): boolean;
+  getModuleData(moduleId: string): Record<string, any> | null;
   clear(): void;
 }
 
-/** Cleanup tracker for resource management during HMR */
-export interface CleanupTracker {
-  /** Track a timer for cleanup */
-  trackTimer(moduleId: string, timerId: number): void;
-  /** Track an event listener for cleanup */
-  trackListener(moduleId: string, element: EventTarget, event: string, handler: EventListener): void;
-  /** Track a fetch request for cleanup */
-  trackFetch(moduleId: string, controller: AbortController): void;
-  /** Clean up all resources for a module */
-  cleanup(moduleId: string): void;
-  /** Clear all tracked resources */
-  clearAll(): void;
-}
-
-/** State capturer for preserving form state during HMR */
-export interface StateCapturer {
-  /** Capture current input values and scroll positions */
-  capture(): Record<string, any>;
-  /** Restore captured state */
-  restore(state: Record<string, any>): void;
-}
-
-/** Error overlay for displaying HMR errors */
-export interface ErrorOverlay {
-  /** Show error overlay */
-  show(error: { message: string; file?: string; line?: number; column?: number; frame?: string }): void;
-  /** Hide error overlay */
-  hide(): void;
-  /** Check if overlay is visible */
-  isVisible(): boolean;
-}
-
-/** Connection indicator for WebSocket status */
-export interface ConnectionIndicator {
-  /** Show indicator with status */
-  show(status: 'connected' | 'disconnected' | 'connecting' | 'error'): void;
-  /** Hide indicator */
-  hide(): void;
-  /** Update status */
-  setStatus(status: 'connected' | 'disconnected' | 'connecting' | 'error'): void;
-}
-
-// ============================================================================
-// Performance Types
-// ============================================================================
-
-/** Performance metrics */
-export interface PerformanceMetrics {
-  hydrationTime: number;
-  componentCount: number;
-  eventBindings: number;
-  memoryUsage?: number;
-  renderTime?: number;
-  stateUpdates: number;
-}
+/** Tracks module resources so HMR can release them */
+export class CleanupTracker {
+  constructor();
 
-/** Performance monitor interface */
-export interface PerformanceMonitor {
-  start(label: string): void;
-  end(label: string): number;
-  measure(label: string, fn: () => any): any;
-  measureAsync(label: string, fn: () => Promise<any>): Promise<any>;
-  getMetrics(): PerformanceMetrics;
-  reset(): void;
-  report(): void;
-}
+  moduleResources: Map<string, any>;
 
-// ============================================================================
-// Router Types
-// ============================================================================
+  createContext(moduleId: string): HMRModuleContext;
+  cleanup(moduleId: string): void;
+  checkForLeaks(moduleId: string): void;
+  hasResources(moduleId: string): boolean;
+  getResourceCounts(moduleId: string): {
+    timers: number;
+    intervals: number;
+    listeners: number;
+    abortControllers: number;
+  } | null;
+}
+
+/** Preserves form input and scroll state across HMR updates */
+export class StateCapturer {
+  constructor();
 
-/** Route configuration */
-export interface RouteConfig {
-  /** Route path pattern */
-  path: string;
-  /** Component to render (can be async for code splitting) */
-  component: CoherentComponent | (() => Promise<CoherentComponent>);
-  /** Route metadata */
-  meta?: Record<string, any>;
-  /** Before enter guard */
-  beforeEnter?: (to: Route, from: Route | null) => boolean | Promise<boolean>;
-  /** Before leave guard */
-  beforeLeave?: (to: Route, from: Route) => boolean | Promise<boolean>;
-  /** Prefetch priority */
-  priority?: number;
-  /** Custom transition for this route */
-  transition?: RouteTransition;
+  capturedInputs: Map<string, any>;
+  scrollPositions: Map<string, { top: number; left: number }>;
+  layoutSnapshot: Record<string, any> | null;
+
+  getInputKey(input: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement): string;
+  getElementPath(element: Element): string;
+  captureFormState(): Map<string, any>;
+  restoreFormState(): void;
+  findInputsByKey(key: string): HTMLElement[];
+  captureScrollPositions(): Map<string, { top: number; left: number }>;
+  getScrollableKey(element: Element): string;
+  captureLayout(): void;
+  layoutChangedSignificantly(): boolean;
+  findElementByKey(key: string): HTMLElement | null;
+  restoreScrollPositions(): void;
+  captureAll(): void;
+  restoreAll(): void;
+  clear(): void;
 }
 
-/** Current route state */
-export interface Route {
-  path: string;
-  component?: CoherentComponent;
-  meta?: Record<string, any>;
-  hash?: string;
-  query?: Record<string, string>;
-}
+/** Full-screen overlay for HMR errors */
+export class ErrorOverlay {
+  constructor();
 
-/** Route transition configuration */
-export interface RouteTransition {
-  enter: string;
-  leave: string;
-  duration: number;
-}
+  overlay: { host: HTMLElement; shadow: ShadowRoot } | null;
+  editor: string;
 
-/** Scroll behavior configuration */
-export interface ScrollBehaviorConfig {
-  enabled?: boolean;
-  behavior?: ScrollBehavior;
-  position?: 'top' | 'saved';
-  delay?: number;
-  savePosition?: boolean;
-  custom?: (to: Route, from: Route | null, savedPosition: { x: number; y: number } | null) => { x: number; y: number } | { el: Element };
+  createOverlay(): { host: HTMLElement; shadow: ShadowRoot };
+  show(error: HMRErrorDetails): void;
+  hide(): void;
+  openInEditor(file: string, line?: number): void;
+  setEditor(editor: string): void;
 }
 
-/** Router configuration */
-export interface RouterConfig {
-  mode?: 'history' | 'hash';
-  base?: string;
-  prefetch?: {
-    enabled?: boolean;
-    strategy?: 'hover' | 'visible' | 'idle';
-    delay?: number;
-    maxConcurrent?: number;
-    priority?: {
-      critical?: number;
-      high?: number;
-      normal?: number;
-      low?: number;
-    };
-  };
-  transitions?: {
-    enabled?: boolean;
-    default?: RouteTransition;
-    routes?: Record<string, RouteTransition>;
-    onStart?: (from: string | null, to: string) => void;
-    onComplete?: (from: string | null, to: string) => void;
-  };
-  codeSplitting?: {
-    enabled?: boolean;
-    strategy?: 'route';
-    chunkNaming?: string;
-    preload?: string[];
-    onLoad?: (path: string, component: any, loadTime: number) => void;
-  };
-  scrollBehavior?: ScrollBehaviorConfig;
-}
+/** Small dot showing the HMR connection status */
+export class ConnectionIndicator {
+  constructor();
 
-/** Router statistics */
-export interface RouterStats {
-  navigations: number;
-  prefetches: number;
-  transitionsCompleted: number;
-  chunksLoaded: number;
-  scrollRestores: number;
-  routesRegistered: number;
-  prefetchQueueSize: number;
-  activePrefetches: number;
-  loadedChunks: number;
-  savedPositions: number;
-  historyLength: number;
-}
+  indicator: HTMLElement | null;
 
-/** Router instance */
-export interface Router {
-  addRoute(path: string, config: RouteConfig): void;
-  push(path: string, options?: Partial<Route>): Promise<boolean>;
-  replace(path: string, options?: Partial<Route>): Promise<boolean>;
-  back(): void;
-  forward(): void;
-  prefetchRoute(path: string, priority?: number): Promise<void>;
-  prefetchRoutes(paths: string[], priority?: number): void;
-  setupPrefetchStrategy(element: HTMLElement, path: string): void;
-  getRoute(path: string): RouteConfig | undefined;
-  getRoutes(): RouteConfig[];
-  getCurrentRoute(): Route | null;
-  getStats(): RouterStats;
-  clearCaches(): void;
+  create(): void;
+  update(status: 'connected' | 'disconnected' | 'reconnecting' | 'error'): void;
+  destroy(): void;
 }
 
 // ============================================================================
-// Utility Types
+// Router Types (the router itself is the @coherent.js/client/router entry)
 // ============================================================================
 
-/** DOM ready state */
-export type ReadyState = 'loading' | 'interactive' | 'complete';
-
-/** DOM ready callback */
-export type ReadyCallback = () => void | Promise<void>;
-
-/** Selector types */
-export type Selector = string | HTMLElement | NodeList | HTMLElement[];
-
-/** Animation frame callback */
-export type AnimationCallback = (timestamp: number) => void;
-
-/** Intersection observer entry with extended data */
-export interface ExtendedIntersectionObserverEntry extends IntersectionObserverEntry {
-  element: HTMLElement;
-  isVisible: boolean;
-  percentage: number;
-}
+export type {
+  RouteConfig,
+  Route,
+  RouteTransition,
+  ScrollBehaviorConfig,
+  RouterConfig,
+  RouterStats,
+  Router,
+} from './router.js';
 
 // ============================================================================
-// Main Functions
+// Hydration
 // ============================================================================
 
-/** Extract initial state from DOM element */
-declare function extractInitialState(
-  element: HTMLElement,
-  options?: Pick<HydrationOptions, 'initialState' | 'transforms' | 'validators'>
-): SerializableState | null;
-
 /**
  * Hydrate a server-rendered component (clean API).
  * Returns a control object with unmount, rerender, getState, and setState.
+ * Hydrating a container again replaces its previous hydration.
  */
 export function hydrate(
-  component: CoherentComponent,
+  component: CoherentComponent | ((props: any) => CoherentNode),
   container: HTMLElement,
   options?: HydrationOptions
 ): HydrateControl;
 
-/** Register a component for auto-hydration */
-declare function registerComponent(
-  name: string,
-  factory: ComponentFactory,
-  options?: Partial<ComponentRegistryEntry>
-): void;
-
-/** Unregister a component */
-declare function unregisterComponent(name: string): boolean;
-
-/** Get registered component */
-declare function getComponent(name: string): ComponentRegistryEntry | undefined;
-
-/** Get all registered components */
-declare function getAllComponents(): ComponentRegistryEntry[];
-
-/** Create a client component */
-declare function createClientComponent(
-  element: HTMLElement,
-  initialState?: SerializableState
-): ClientComponent;
-
-/** Wait for DOM to be ready */
-declare function ready(callback: ReadyCallback): Promise<void>;
-
-/** DOM query utilities */
-declare function $(selector: Selector): HTMLElement[];
-declare function $$(selector: string): HTMLElement | null;
-
-/** Event utilities */
-declare function on(
-  element: HTMLElement | string,
-  event: string,
-  handler: EventHandler,
-  options?: EventListenerOptions | boolean
-): void;
-
-declare function off(
-  element: HTMLElement | string,
-  event?: string,
-  handler?: EventHandler
-): void;
-
-declare function trigger(
-  element: HTMLElement,
-  event: string,
-  data?: CustomEventData
-): boolean;
-
-declare function delegate(
-  container: HTMLElement,
-  selector: string,
-  event: string,
-  handler: EventHandler
-): void;
-
-/** Animation utilities */
-declare function requestAnimationFrame(callback: AnimationCallback): number;
-declare function cancelAnimationFrame(id: number): void;
-
-/** Debounce and throttle utilities */
-declare function debounce<T extends (...args: any[]) => any>(
-  func: T,
-  delay: number
-): (...args: Parameters<T>) => void;
-
-declare function throttle<T extends (...args: any[]) => any>(
-  func: T,
-  limit: number
-): (...args: Parameters<T>) => void;
-
-/** State management utilities */
-declare function createStateManager(): ClientStateManager;
-declare function syncState(options: StateSyncOptions): void;
-
-/** Performance utilities */
-declare function createPerformanceMonitor(): PerformanceMonitor;
-
-/** HMR utilities */
-declare function createHMRClient(config?: Partial<HMRConfig>): HMRClient;
-declare function enableHMR(config?: Partial<HMRConfig>): Promise<void>;
-export function createHotContext(moduleId: string): HotContext;
-
-/** Intersection observer utilities */
-declare function observeVisibility(
-  elements: HTMLElement | HTMLElement[],
-  callback: (entries: ExtendedIntersectionObserverEntry[]) => void,
-  options?: IntersectionObserverInit
-): IntersectionObserver;
-
-/** Lazy loading utilities */
-declare function lazyLoad(
-  elements: HTMLElement | HTMLElement[],
-  options?: {
-    threshold?: number;
-    rootMargin?: string;
-    attribute?: string;
-    placeholder?: string;
-  }
-): IntersectionObserver;
-
 // ============================================================================
-// State Serialization Functions (Plan 02-02)
+// State Serialization
 // ============================================================================
 
-/** Serialize state to base64-encoded JSON */
-export function serializeState(state: SerializableState): string;
+/** Serialize state to base64-encoded JSON; `null` when nothing is serializable */
+export function serializeState(state: SerializableState): string | null;
 
-/** Deserialize state from base64-encoded JSON */
-export function deserializeState(encoded: string): SerializableState;
+/** Deserialize state from base64-encoded JSON; `null` when invalid */
+export function deserializeState(encoded: string | null | undefined): SerializableState | null;
 
 /** Extract state from DOM element's data-state attribute */
 export function extractState(element: HTMLElement): SerializableState | null;
 
 /** Serialize state with size warning (10KB threshold) */
-export function serializeStateWithWarning(state: SerializableState, componentName?: string): string;
+export function serializeStateWithWarning(state: SerializableState, componentName?: string): string | null;
 
 // ============================================================================
-// Mismatch Detection Functions (Plan 02-03)
+// Mismatch Detection
 // ============================================================================
 
-/** Detect mismatches between DOM and virtual DOM */
+/**
+ * Detect mismatches between DOM and virtual DOM. An array `vNode` is compared
+ * with the element's children.
+ */
 export function detectMismatch(element: HTMLElement, vNode: CoherentNode): HydrationMismatch[];
 
-/** Report mismatches with warnings or errors */
+/** Report mismatches with warnings, or throw with `strict` */
 export function reportMismatches(
   mismatches: HydrationMismatch[],
   options?: { componentName?: string; strict?: boolean }
 ): void;
 
 /** Format path for mismatch reporting */
-export function formatPath(path: (string | number)[]): string;
+export function formatPath(path: (string | number)[] | null | undefined): string;
 
 // ============================================================================
-// Event Delegation Exports (Plan 02-01)
+// Event Delegation
 // ============================================================================
 
 /** Event delegation singleton */
@@ -871,106 +508,26 @@ export const eventDelegation: EventDelegation;
 /** Handler registry singleton */
 export const handlerRegistry: HandlerRegistry;
 
-/** Wrap an event handler for use with event delegation */
+/**
+ * Wrap a native event for a delegated handler: `target` is the element the
+ * handler is registered on, `componentRef` supplies state/setState/props.
+ */
 export function wrapEvent<S = any, E extends Event = Event>(
-  eventType: string,
-  handler: StateAwareHandler<S, E>,
-  handlerId?: string
-): { handlerId: string; dataAttribute: string };
+  originalEvent: E,
+  target: Element,
+  componentRef?: HandlerComponentRef | null
+): CoherentEvent<S, E>;
 
 // ============================================================================
-// HMR Exports (Phase 4)
+// HMR
 // ============================================================================
 
-export const HMRClient: new (config?: Partial<HMRConfig>) => HMRClient;
 export const hmrClient: HMRClient;
-export const ModuleTracker: new () => ModuleTracker;
 export const moduleTracker: ModuleTracker;
-export const CleanupTracker: new () => CleanupTracker;
 export const cleanupTracker: CleanupTracker;
-export const StateCapturer: new () => StateCapturer;
 export const stateCapturer: StateCapturer;
-export const ErrorOverlay: new () => ErrorOverlay;
 export const errorOverlay: ErrorOverlay;
-export const ConnectionIndicator: new () => ConnectionIndicator;
 export const connectionIndicator: ConnectionIndicator;
 
-// ============================================================================
-// Global Constants
-// ============================================================================
-
-/** Default hydration selector */
-declare const DEFAULT_HYDRATION_SELECTOR: string;
-
-/** Component registry */
-declare const componentRegistry: Map<string, ComponentRegistryEntry>;
-
-/** Global state manager instance */
-declare const globalStateManager: ClientStateManager;
-
-/** Global event manager instance */
-declare const globalEventManager: EventManager;
-
-/** Global performance monitor instance */
-declare const globalPerformanceMonitor: PerformanceMonitor;
-
-// ============================================================================
-// Default Export
-// ============================================================================
-
-declare const coherentClient: {
-  // Hydration
-  extractInitialState: typeof extractInitialState;
-  hydrate: typeof hydrate;
-
-  // Component registration
-  registerComponent: typeof registerComponent;
-  unregisterComponent: typeof unregisterComponent;
-  getComponent: typeof getComponent;
-  getAllComponents: typeof getAllComponents;
-  createClientComponent: typeof createClientComponent;
-
-  // DOM utilities
-  ready: typeof ready;
-  $: typeof $;
-  $$: typeof $$;
-
-  // Event utilities
-  on: typeof on;
-  off: typeof off;
-  trigger: typeof trigger;
-  delegate: typeof delegate;
-
-  // Animation utilities
-  requestAnimationFrame: typeof requestAnimationFrame;
-  cancelAnimationFrame: typeof cancelAnimationFrame;
-
-  // Utility functions
-  debounce: typeof debounce;
-  throttle: typeof throttle;
-
-  // State management
-  createStateManager: typeof createStateManager;
-  syncState: typeof syncState;
-  globalStateManager: typeof globalStateManager;
-
-  // Performance
-  createPerformanceMonitor: typeof createPerformanceMonitor;
-  globalPerformanceMonitor: typeof globalPerformanceMonitor;
-
-  // HMR
-  createHMRClient: typeof createHMRClient;
-  enableHMR: typeof enableHMR;
-  createHotContext: typeof createHotContext;
-
-  // Intersection Observer
-  observeVisibility: typeof observeVisibility;
-  lazyLoad: typeof lazyLoad;
-
-  // Constants
-  DEFAULT_HYDRATION_SELECTOR: typeof DEFAULT_HYDRATION_SELECTOR;
-  componentRegistry: typeof componentRegistry;
-  globalEventManager: typeof globalEventManager;
-};
-
-declare const _unused: typeof coherentClient;
+/** Hot context for a module: `createHotContext(import.meta.url)` */
+export function createHotContext(moduleId: string): HotContext;