docs / Runtime
Hydration
How Vesk attaches client behavior to server-rendered HTML: vsk markers, claim walkers, and the hydration entry points.
Hydration attaches client behavior (event handlers, effects, tracked bindings) to server-rendered HTML. The server marks the parts of the DOM that need client JS; the client hydrator walks those markers and claims the existing DOM instead of rebuilding it.
Server side
server-jsgen.ts
subtreeNeedsJS = __vskHydrate && (forceClaim || !isStaticIR(node.children))
- Fully static subtrees get no marker and no client-side reconstruction.
- Reactive subtrees get a `<!--vsk-->` marker; the hydrator claims them in place.
- Event-handler attributes are excluded from the SSR HTML entirely — the client bundle attaches them.
Client entry points
| Entry | Behavior |
|---|---|
| hydrate(container, fn, props) | Hydrate everything immediately |
| hydrateViewport(container, fn, props, rootMargin) | Hydrate visible markers now; hydrate the rest via IntersectionObserver |
| hydrateIdle(container, fn, props, {chunkSize, timeout}) | Hydrate in chunks via requestIdleCallback; returns { cancel() } |
| hydrateOnInteraction(container, fn, props, {events}) | Hydrate on the first click/touchstart/focus/mouseenter |
| hydrateInitial(container, fn, props) | Hydrate with a fresh walker (no marker list) |
| needsHydration / hydrationCount(container) | Whether the container still contains unhydrated vsk markers |
Automated hydration uses `hydrateViewport` by default; `createHydrateWalker(container, markerList?)` walks from markers or from the container, and `reactiveProps(props)` makes server-rendered prop values reactive on the client.