@zoijs/core 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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
+- **DOM-free template compiler + a `@zoijs/core/server` subpath.** `html\`…\`` now
+  compiles to a static HTML string + part descriptors **without touching the DOM**;
+  the `<template>` element is built lazily on first client render. This means a
+  component can be evaluated on a server (no DOM) so [`@zoijs/ssr`](https://www.npmjs.com/package/@zoijs/ssr)
+  can render it to a string. The new subpath exposes the building blocks a server
+  renderer needs — the static HTML/parts of a result, template/list markers, and the
+  **same** security predicates the client uses (`escapeText`, `escapeAttr`,
+  `isSafeUrl`, `isSafeAttributeName`, `URL_ATTRS`) so server and client make
+  identical safety decisions. Client rendering is byte-for-byte unchanged; the
+  learnable nine-function main surface is unchanged. See
+  [RFC 0008](docs/rfcs/0008-ssr.md).
+
 ## [1.4.0] — 2026-06-26
 
 ### Added

package/README.md

@@ -97,19 +97,36 @@ Relies on baseline-modern platform APIs: ES modules, `<template>`, `TreeWalker`,
 
 ## Public API
 
+The whole framework is **nine functions** — learnable in one sitting and frozen for 1.x:
+
 ```js
-import { html, mount, createState, computed, each, configure, onCleanup } from "@zoijs/core";
+import {
+  html, mount, each, boundary,
+  createState, computed, effect,
+  configure, onCleanup,
+} from "@zoijs/core";
 ```
 
 - `html` — tagged template; parsed once, cached.
 - `mount(component, target)` — render a component; returns `unmount()`.
+- `each(itemsFn, keyFn, renderFn)` — keyed list rendering (reuse / move / remove nodes).
+- `boundary(child, fallback)` — render-time error boundary: if `child` throws while building its markup, dispose the partial work and render `fallback`.
 - `createState(value)` — a reactive value (`get` / `set` / `peek`).
 - `computed(fn)` — a lazy, cached, **value-gated** derived value (`get` / `peek`).
-- `each(itemsFn, keyFn, renderFn)` — keyed list rendering (reuse / move / remove nodes).
+- `effect(fn)` — a side effect that re-runs when a value it reads changes; returns `{ dispose }` and may return a per-run cleanup.
 - `configure({ dev })` — toggle development warnings (default `dev: true`).
 - `onCleanup(fn)` — register teardown for a component or list item (timers, subscriptions).
 
-See the [Documentation site](docs/README.md) for the full guide, tutorials, and API reference.
+Plus the **`ref`** binding (`html\`<input ref=${(el) => el.focus()} />\``) — no export; it's a template
+attribute that hands you the rendered element.
+
+**Devtools (dev-only).** A separate subpath, `@zoijs/core/devtools`, exposes a read-only inspection
+hook — `attachInspector(inspector)` and `inspecting()` — that [`@zoijs/devtools`](https://www.npmjs.com/package/@zoijs/devtools)
+(or a browser extension) uses to observe the reactive graph. It's off by default, never instruments
+the hot read path, and is a no-op under `configure({ dev: false })`, so it costs production nothing and
+leaves the nine-function main surface unchanged.
+
+See the [Documentation site](https://zoijs.dev) for the full guide, tutorials, and API reference.
 
 **TypeScript:** ships type definitions ([`src/index.d.ts`](src/index.d.ts)) for autocomplete and optional type-checking — JS-first, no build step required. `createState<T>`, `computed<T>`, and `each<T>` are generic. Type-check with `npm run test:types`.
 
@@ -118,7 +135,9 @@ See the [Documentation site](docs/README.md) for the full guide, tutorials, and
 - Fine-grained text/attribute bindings — `${() => state.get()}` updates one node in place; setup runs once (no re-render).
 - Native events, secure-by-default rendering (inert text, URL-scheme guards, no `eval`).
 - `computed()` derived values — lazy, cached, nestable, and **value-gated** (unchanged results don't wake downstream).
-- `each()` keyed list reconciliation — preserves focus / input / scroll on reorder.
+- `effect()` side effects — re-run on change, with owner-scoped auto-disposal and a per-run cleanup.
+- `boundary()` render-time error boundary — a failing subtree shows a fallback instead of breaking `mount`.
+- `each()` keyed list reconciliation — minimal DOM moves; preserves focus / input / scroll on reorder.
 - Microtask batching, push-pull dependency tracking, **owner-scoped cleanup** (unmount and removed items dispose their subscriptions).
 - Production mode via `configure({ dev: false })` — no build step.
 - Safety: self-triggering effects are warned + stopped; a throwing binding doesn't break others.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoijs/core",
-  "version": "1.4.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",
@@ -13,6 +13,10 @@
     "./devtools": {
       "types": "./src/devtools.d.ts",
       "default": "./src/reactivity/devtools.js"
+    },
+    "./server": {
+      "types": "./src/server.d.ts",
+      "default": "./src/server.js"
     }
   },
   "files": [

package/src/core/html.js

@@ -7,8 +7,10 @@
 // attribute value, an event, etc. Dynamic values are kept in a separate channel
 // from the static HTML; a value can never change the template's structure.
 //
-// Output of the parse (cached per `strings`):
-//   template : a <template> element with unique markers
+// Output of the parse (cached per `strings`) is DOM-free — a static HTML string
+// plus part descriptors. The <template> element is built lazily on first client
+// render; on a server, @zoijs/ssr reads the static HTML + parts directly.
+//   html     : the static HTML string, with unique markers (no DOM)
 //   parts    : ordered list of binding descriptors
 //      { type: "child" }                          ← a comment-marker anchor
 //      { type: "element", attrs: [AttrPart] }     ← element carrying data-zoijs-bind
@@ -29,10 +31,24 @@ const cache = new WeakMap();
 export function html(strings, ...values) {
   let compiled = cache.get(strings);
   if (!compiled) {
-    compiled = compile(strings);
+    compiled = compile(strings); // pure: a static HTML string + parts, NO DOM
     cache.set(strings, compiled);
   }
-  return { template: compiled.template, parts: compiled.parts, hasElements: compiled.hasElements, values };
+  // The <template> element is created lazily, on first client render — so html()
+  // itself touches no DOM and works on a server (where @zoijs/ssr reads the static
+  // HTML + parts instead). The brand lets consumers detect a result without
+  // tripping the getter.
+  return {
+    __zoijsTemplate: true,
+    parts: compiled.parts,
+    hasElements: compiled.hasElements,
+    __staticHTML: compiled.html,
+    get template() {
+      if (!compiled.template) compiled.template = createTemplate(compiled.html);
+      return compiled.template;
+    },
+    values,
+  };
 }
 
 // ---- scanner ----------------------------------------------------------------
@@ -239,5 +255,8 @@ function compile(strings) {
   }
 
   const hasElements = parts.some((p) => p.type === "element");
-  return { template: createTemplate(out), parts, hasElements };
+  // Pure output: the static HTML string and the part descriptors. The DOM
+  // <template> is built later, lazily (see html()), so compile() needs no DOM and
+  // its result can be serialized on a server.
+  return { html: out, parts, hasElements, template: null };
 }

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

@@ -17,23 +17,28 @@ import { labelNext } from "../reactivity/devtools.js";
 import { createState } from "../reactivity/state.js";
 import { createOwner, runWithOwner, disposeOwner, onCleanup } from "../reactivity/owner.js";
 import { isDev } from "../reactivity/env.js";
-import { toText, isSafeUrl, isSafeAttributeName } from "../utils/security.js";
+import { toText, isSafeUrl, isSafeAttributeName, URL_ATTRS } from "../utils/security.js";
 
 const XLINK_NS = "http://www.w3.org/1999/xlink";
-const URL_ATTRS = new Set(["href", "src", "action", "formaction", "poster", "ping", "xlink:href"]);
 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, () => {
@@ -43,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");
@@ -54,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.
@@ -469,5 +489,5 @@ function applyAttribute(el, name, value) {
 // ---- helpers -----------------------------------------------------------------
 
 function isHtmlResult(v) {
-  return v && typeof v === "object" && v.template && Array.isArray(v.parts);
+  return v && v.__zoijsTemplate === true;
 }

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.

package/src/server.d.ts

@@ -0,0 +1,53 @@
+// Type surface for `@zoijs/core/server` — DOM-free building blocks for server
+// rendering (@zoijs/ssr). Server tooling, not part of the stable nine-function API.
+
+/** Coerce a value to a string (null/undefined → ""). */
+export function toText(value: unknown): string;
+/** Escape a value for insertion as HTML text content. */
+export function escapeText(value: unknown): string;
+/** Escape a value for inside a double-quoted attribute value. */
+export function escapeAttr(value: unknown): string;
+/** Is this URL safe for a URL-bearing attribute (scheme allowlist)? */
+export function isSafeUrl(url: string): boolean;
+/** Is this attribute name allowed to be bound from data (blocks on*, srcdoc)? */
+export function isSafeAttributeName(name: string): boolean;
+/** Attribute names whose values carry a URL (scheme-checked). */
+export const URL_ATTRS: ReadonlySet<string>;
+
+/** A part descriptor: a child slot, or a dynamic element with attribute parts. */
+export type Part =
+  | { type: "child"; hole: number }
+  | { type: "element"; attrs: AttrPart[] };
+
+/** A dynamic attribute descriptor. */
+export interface AttrPart {
+  name: string;
+  strings: string[];
+  holes: number[];
+  event: boolean;
+  whole: boolean;
+}
+
+/** An `html\`…\`` result, viewed without its DOM template. */
+export interface TemplateResult {
+  __zoijsTemplate: true;
+  __staticHTML: string;
+  parts: Part[];
+  values: unknown[];
+  hasElements: boolean;
+}
+
+/** An `each(...)` list marker. */
+export interface EachMarker {
+  __zoijsEach: true;
+  items: unknown;
+  keyFn: (item: unknown) => unknown;
+  renderFn: (item: unknown) => unknown;
+}
+
+/** True for an `html\`…\`` result (does not build the DOM template). */
+export function isTemplateResult(value: unknown): value is TemplateResult;
+/** True for an `each(...)` list marker. */
+export function isEachMarker(value: unknown): value is EachMarker;
+/** The static HTML skeleton of a template result. */
+export function templateHTML(result: TemplateResult): string;

package/src/server.js

@@ -0,0 +1,42 @@
+// server.js — DOM-free building blocks for server rendering (@zoijs/ssr).
+//
+// Reached via the subpath `@zoijs/core/server`. It exposes exactly what a string
+// renderer needs to walk an html() result and emit safe HTML WITHOUT a DOM:
+//
+//   - the static HTML skeleton + part descriptors of a template result,
+//   - markers for the two value kinds (a template result, an each() list),
+//   - and the SAME security predicates the client renderer uses, so server output
+//     and client output make identical safety decisions (escaping, URL schemes,
+//     unsafe attribute names).
+//
+// Nothing here touches the DOM, and the main nine-function surface is unchanged —
+// this is server tooling behind its own subpath, like `@zoijs/core/devtools`.
+
+export {
+  toText,
+  escapeText,
+  escapeAttr,
+  isSafeUrl,
+  isSafeAttributeName,
+  URL_ATTRS,
+} from "./utils/security.js";
+
+/** True for an `html\`…\`` result (brand check — does not build the DOM template). */
+export function isTemplateResult(value) {
+  return !!(value && value.__zoijsTemplate === true);
+}
+
+/** True for an `each(...)` list marker. */
+export function isEachMarker(value) {
+  return !!(value && value.__zoijsEach === true);
+}
+
+/**
+ * The static HTML skeleton of a template result — the author's HTML with unique
+ * markers (`<!--zoijs-->` for a child slot, ` data-zoijs-bind` on a dynamic
+ * element). A server renderer injects values at those markers. The result's
+ * `parts` (document-ordered descriptors) and `values` are read directly.
+ */
+export function templateHTML(result) {
+  return result.__staticHTML;
+}

package/src/utils/security.js

@@ -14,6 +14,27 @@ export function toText(value) {
   return value === null || value === undefined ? "" : String(value);
 }
 
+// HTML-escaping for SERVER string rendering (@zoijs/ssr). The client renderer
+// never needs these — it writes text via Text nodes and values via setAttribute,
+// both of which are inert/escaped by the platform. On a server there is no DOM, so
+// the same safety must be applied by escaping into the HTML string. Kept here so
+// escaping lives in one place alongside the other security predicates.
+
+/** Escape a value for insertion as HTML TEXT content. */
+export function escapeText(value) {
+  return toText(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Escape a value for insertion inside a double-quoted attribute value. */
+export function escapeAttr(value) {
+  return toText(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+
+// Attribute names that carry a URL — their values are scheme-checked (isSafeUrl).
+// Shared by the client renderer (DOM) and @zoijs/ssr (string) so both make the
+// exact same safety decision.
+export const URL_ATTRS = new Set(["href", "src", "action", "formaction", "poster", "ping", "xlink:href"]);
+
 // Allowlisted URL schemes for URL-bearing attributes (href, src, ...).
 const SAFE_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
 // data: is allowed only for raster image MIME types (never text/html, never SVG,