@zoijs/core 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to Zoijs are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and Zoijs follows
 [Semantic Versioning](https://semver.org/) (see `VERSIONING.md`).
 
+## [1.6.0] — 2026-06-27
+
+### Added
+- **Hydration — `mount(component, target, { hydrate: true })`.** The client now
+  **adopts** server-rendered DOM in place instead of re-creating it: with `hydrate`,
+  `mount` reuses the existing elements inside `target` exactly — never cloning or
+  replacing them — and attaches event handlers and reactive attribute bindings to
+  those live nodes. Each dynamic child slot's server content is cleared (back to the
+  `<!--zoijs:[-->` start marker that [`@zoijs/ssr`](https://www.npmjs.com/package/@zoijs/ssr)
+  emits) and re-rendered in place; since the values match the server, there is no
+  visible change and no flash. This is the client half of full SSR — pair it with
+  `renderToString(component, { hydratable: true })`. The default `mount` path is
+  byte-for-byte unchanged (the option is additive), and the nine-function main surface
+  is the same. `@zoijs/ssr` re-exports this as `hydrate()`. See
+  [RFC 0008](docs/rfcs/0008-ssr.md).
+
 ## [1.5.0] — 2026-06-26
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoijs/core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Zoijs — a beginner-friendly, no-build, no-Virtual-DOM frontend framework. Plain HTML, CSS, and JavaScript.",
   "type": "module",
   "main": "src/index.js",

package/src/core/mount.js

@@ -11,18 +11,25 @@ import { createOwner, runWithOwner, disposeOwner } from "../reactivity/owner.js"
 /**
  * @param {Function|object} component  a component function, or an html() result
  * @param {Element|string}  target     a DOM element or a CSS selector
+ * @param {{ hydrate?: boolean }} [options]  with `hydrate: true`, adopt the
+ *   server-rendered DOM already inside `target` instead of replacing it — the
+ *   elements/attributes/events are reused in place (used by @zoijs/ssr's
+ *   `hydrate()`). The returned unmount() disposes everything either way.
  * @returns {Function} unmount
  */
-export function mount(component, target) {
+export function mount(component, target, options) {
   const el = resolveTarget(target);
   const owner = createOwner();
+  const hydrate = !!(options && options.hydrate);
 
   let node;
   runWithOwner(owner, () => {
     const result = typeof component === "function" ? component() : component;
-    node = render(result).node;
+    // Hydration binds to el's existing children in place; a fresh mount builds a
+    // detached fragment we then swap in.
+    node = render(result, hydrate ? el : undefined).node;
   });
-  el.replaceChildren(node);
+  if (!hydrate) el.replaceChildren(node);
 
   return () => {
     disposeOwner(owner);

package/src/core/renderer.js

@@ -24,15 +24,21 @@ const noop = () => {};
 
 /**
  * @param {{ template: HTMLTemplateElement, parts: object[], values: any[] }} result
- * @returns {{ node: DocumentFragment, dispose: Function }}
+ * @param {Element} [hydrateRoot]  when given, bind to this EXISTING server-rendered
+ *   subtree in place (no clone) instead of building fresh DOM — see hydration below.
+ * @returns {{ node: Node, dispose: Function }}
  */
-export function render(result) {
+export function render(result, hydrateRoot) {
   const owner = createOwner(); // nested under the active owner
-  const fragment = result.template.content.cloneNode(true);
+  // Hydration adopts the server DOM in place — elements, attributes, and events are
+  // reused, never re-created; each dynamic slot is cleared + re-rendered (same
+  // values → no visible change). Otherwise build a fresh clone.
+  const hydrating = hydrateRoot != null;
+  const fragment = hydrating ? hydrateRoot : result.template.content.cloneNode(true);
   const { parts, values } = result;
 
-  // Collect every part's target node on the PRISTINE clone first (document
-  // order), so a binding that inserts children can't shadow a later part.
+  // Collect every part's target node first (document order), so a binding that
+  // inserts children can't shadow a later part.
   const nodes = collectNodes(fragment, parts, result.hasElements);
 
   runWithOwner(owner, () => {
@@ -42,6 +48,7 @@ export function render(result) {
       if (!node) continue;
 
       if (part.type === "child") {
+        if (hydrating) clearHydratedSlot(node); // drop this slot's server content
         bindChild(node, values[part.hole]);
       } else {
         node.removeAttribute("data-zoijs-bind");
@@ -53,6 +60,20 @@ export function render(result) {
   return { node: fragment, dispose: () => disposeOwner(owner) };
 }
 
+// Remove a hydrated slot's server content: the nodes before its anchor, back
+// through the slot's `<!--zoijs:[-->` start marker (emitted by @zoijs/ssr). Static
+// text outside the slot is preserved; the normal binding then renders fresh content
+// in the same place. No start marker → leave the DOM as-is (not a hydratable slot).
+const isSlotStart = (n) => n && n.nodeType === 8 && n.data === "zoijs:[";
+function clearHydratedSlot(anchor) {
+  let start = anchor.previousSibling;
+  while (start && !isSlotStart(start)) start = start.previousSibling;
+  if (!start) return;
+  let n;
+  while ((n = anchor.previousSibling) !== start) n.remove();
+  start.remove();
+}
+
 // Match parts to nodes by document order: a child part ↔ the next marker comment,
 // an element part ↔ the next element carrying data-zoijs-bind. Unique markers make
 // this collision-proof across nested templates and list items.

package/src/index.d.ts

@@ -66,11 +66,26 @@ export type Ref<E extends Element = Element> = (element: E) => void | (() => voi
  */
 export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
 
+/** Options for {@link mount}. */
+export interface MountOptions {
+  /**
+   * Adopt the server-rendered DOM already inside `target` (from `@zoijs/ssr`'s
+   * `renderToString(..., { hydratable: true })`) instead of replacing it: elements,
+   * attributes, and events are reused in place. Used by `@zoijs/ssr`'s `hydrate()`.
+   */
+  hydrate?: boolean;
+}
+
 /**
  * Render a component (or a template) into a DOM element or CSS selector.
  * Returns an `unmount()` that detaches the DOM and disposes all reactivity.
+ * With `{ hydrate: true }`, binds to the existing server-rendered DOM in place.
  */
-export function mount(component: Component | TemplateResult, target: Element | string): () => void;
+export function mount(
+  component: Component | TemplateResult,
+  target: Element | string,
+  options?: MountOptions
+): () => void;
 
 /**
  * Create a reactive value.