@praxisjs/runtime 0.5.4 → 0.6.0

package/src/__tests__/hydration.test.ts

@@ -0,0 +1,360 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, afterEach } from "vitest";
+
+import { StatefulComponent } from "@praxisjs/core";
+import { isServerRenderPass, setServerRenderPass, signal } from "@praxisjs/core/internal";
+
+import { mountComponent } from "../component";
+import { getCurrentScope } from "../context";
+import { mountElement } from "../element";
+import { reconcile } from "../hydration";
+import { registerReactiveNode } from "../hydration-context";
+import { render, Portal } from "../index";
+import { Scope } from "../scope";
+
+const SSG_MARKER = "data-praxis-ssg";
+
+/** Renders `factory` into a throwaway container and returns the resulting markup, simulating SSR output. */
+function ssrHTML(factory: () => Node | Node[] | null): string {
+  const serverContainer = document.createElement("div");
+  const unmount = render(factory, serverContainer);
+  const html = serverContainer.innerHTML;
+  unmount();
+  return html;
+}
+
+function hydratable(factory: () => Node | Node[] | null): HTMLElement {
+  const container = document.createElement("div");
+  container.innerHTML = ssrHTML(factory);
+  container.setAttribute(SSG_MARKER, "1");
+  document.body.appendChild(container);
+  return container;
+}
+
+afterEach(() => { setServerRenderPass(false); });
+
+describe("render() — hydration (build + reconcile)", () => {
+  it("adopts a flat element instead of recreating it", () => {
+    const factory = () => mountElement("p", { id: "greet", children: "hello" }, new Scope());
+    const container = hydratable(factory);
+    const serverEl = container.querySelector("#greet");
+    expect(serverEl).not.toBeNull();
+
+    render(factory, container);
+
+    expect(container.querySelector("#greet")).toBe(serverEl);
+    document.body.removeChild(container);
+  });
+
+  it("adopts nested elements at every level — the case that broke the ambient-cursor attempt", () => {
+    const factory = () => mountElement("div", {
+      id: "outer",
+      children: mountElement("span", { id: "inner", children: "text" }, new Scope()),
+    }, new Scope());
+    const container = hydratable(factory);
+    const outerBefore = container.querySelector("#outer");
+    const innerBefore = container.querySelector("#inner");
+
+    render(factory, container);
+
+    expect(container.querySelector("#outer")).toBe(outerBefore);
+    expect(container.querySelector("#inner")).toBe(innerBefore);
+    expect(container.textContent).toBe("text");
+    document.body.removeChild(container);
+  });
+
+  it("adopts three levels deep with siblings at each level", () => {
+    const factory = () => mountElement("ul", {
+      id: "list",
+      children: [
+        mountElement("li", { id: "a", children: mountElement("b", { children: "1" }, new Scope()) }, new Scope()),
+        mountElement("li", { id: "b", children: "2" }, new Scope()),
+      ],
+    }, new Scope());
+    const container = hydratable(factory);
+    const before = {
+      list: container.querySelector("#list"),
+      a: container.querySelector("#a"),
+      b: container.querySelector("#b"),
+      bold: container.querySelector("b"),
+    };
+
+    render(factory, container);
+
+    expect(container.querySelector("#list")).toBe(before.list);
+    expect(container.querySelector("#a")).toBe(before.a);
+    expect(container.querySelector("#b")).toBe(before.b);
+    expect(container.querySelector("b")).toBe(before.bold);
+    document.body.removeChild(container);
+  });
+
+  it("wires event listeners onto the adopted (real) element via replay", () => {
+    let clicks = 0;
+    const factory = () => mountElement("div", {
+      children: mountElement("button", { onClick: () => { clicks++; }, children: "Click" }, new Scope()),
+    }, new Scope());
+    const container = hydratable(factory);
+    const buttonBefore = container.querySelector("button");
+
+    render(factory, container);
+
+    expect(container.querySelector("button")).toBe(buttonBefore);
+    container.querySelector("button")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(clicks).toBe(1);
+    document.body.removeChild(container);
+  });
+
+  it("hydrates reactive text and keeps reacting to signal changes afterwards", () => {
+    const text = signal("initial");
+    const factory = () => mountElement("span", { children: () => text() }, new Scope());
+    const container = hydratable(factory);
+    expect(container.textContent).toBe("initial");
+
+    render(factory, container);
+
+    text.set("updated");
+    expect(container.textContent).toBe("updated");
+    text.set("initial");
+    document.body.removeChild(container);
+  });
+
+  it("hydrates a reactive list of elements, keeping real nodes, and stays correct after a later update", () => {
+    const items = signal(["a", "b", "c"]);
+    const factory = () => mountElement("ul", {
+      id: "list",
+      children: () => items().map((item) => mountElement("li", { children: item }, new Scope())),
+    }, new Scope());
+    const container = hydratable(factory);
+    const list = container.querySelector("#list") as HTMLElement;
+    const firstLiBefore = list.querySelector("li");
+    expect(container.textContent).toBe("abc");
+
+    render(factory, container);
+
+    expect(container.querySelector("#list")?.querySelector("li")).toBe(firstLiBefore);
+    expect(container.textContent).toBe("abc");
+
+    // A subsequent reactive update must diff correctly — this only works if
+    // reconcile() rewrote mountReactive's `currentNodes` bookkeeping in place
+    // when it kept the real <li> elements instead of the fresh ones.
+    items.set(["x", "y"]);
+    expect(container.textContent).toBe("xy");
+    items.set(["z"]);
+    expect(container.textContent).toBe("z");
+    document.body.removeChild(container);
+  });
+
+  it("hydrates a component nested inside another component, firing onMount/onUnmount correctly", async () => {
+    class Inner extends StatefulComponent {
+      static __isComponent = true as const;
+      static __isStateless = false;
+      onMount() {}
+      onUnmount() {}
+      render() { return mountElement("em", { children: "inner" }, getCurrentScope()); }
+    }
+    class Outer extends StatefulComponent {
+      static __isComponent = true as const;
+      static __isStateless = false;
+      onMount() {}
+      render() {
+        return mountElement("section", {
+          children: mountComponent(Inner, {}, getCurrentScope()),
+        }, getCurrentScope());
+      }
+    }
+
+    const factory = () => mountComponent(Outer, {}, getCurrentScope());
+    const container = hydratable(factory);
+    const emBefore = container.querySelector("em");
+
+    const outerMount = vi.spyOn(Outer.prototype, "onMount");
+    const innerMount = vi.spyOn(Inner.prototype, "onMount");
+    const innerUnmount = vi.spyOn(Inner.prototype, "onUnmount");
+    const dispose = render(factory, container);
+    await Promise.resolve();
+
+    expect(outerMount).toHaveBeenCalledOnce();
+    expect(innerMount).toHaveBeenCalledOnce();
+    expect(container.querySelector("em")).toBe(emBefore);
+    expect(container.textContent).toBe("inner");
+
+    dispose();
+    expect(innerUnmount).toHaveBeenCalledOnce();
+
+    outerMount.mockRestore();
+    innerMount.mockRestore();
+    innerUnmount.mockRestore();
+    document.body.removeChild(container);
+  });
+
+  it("a tag mismatch at one node replaces only that node — siblings stay adopted", () => {
+    const factory = () => mountElement("div", {
+      id: "wrap",
+      children: [
+        mountElement("p", { id: "before", children: "before" }, new Scope()),
+        mountElement("span", { id: "target", children: "new" }, new Scope()),
+        mountElement("p", { id: "after", children: "after" }, new Scope()),
+      ],
+    }, new Scope());
+
+    const container = document.createElement("div");
+    container.innerHTML =
+      '<div id="wrap"><p id="before">before</p><strong id="target">old</strong><p id="after">after</p></div>';
+    container.setAttribute(SSG_MARKER, "1");
+    document.body.appendChild(container);
+
+    const beforeEl = container.querySelector("#before");
+    const afterEl = container.querySelector("#after");
+
+    render(factory, container);
+
+    expect(container.querySelector("#before")).toBe(beforeEl);
+    expect(container.querySelector("#after")).toBe(afterEl);
+    expect(container.querySelector("#target")?.tagName.toLowerCase()).toBe("span");
+    expect(container.textContent).toBe("beforenewafter");
+    document.body.removeChild(container);
+  });
+
+  it("appends extra fresh nodes when the real DOM has fewer children than the fresh tree", () => {
+    // Client factory produces three items; the server only rendered two —
+    // exercises reconcile()'s mismatch branch once realCursor has run out.
+    const factory = () => mountElement("ul", {
+      id: "list",
+      children: [
+        mountElement("li", { id: "a", children: "a" }, new Scope()),
+        mountElement("li", { id: "b", children: "b" }, new Scope()),
+        mountElement("li", { id: "c", children: "c" }, new Scope()),
+      ],
+    }, new Scope());
+
+    const container = document.createElement("div");
+    container.innerHTML = '<ul id="list"><li id="a">a</li><li id="b">b</li></ul>';
+    container.setAttribute(SSG_MARKER, "1");
+    document.body.appendChild(container);
+
+    const aBefore = container.querySelector("#a");
+    const bBefore = container.querySelector("#b");
+
+    render(factory, container);
+
+    expect(container.querySelector("#a")).toBe(aBefore);
+    expect(container.querySelector("#b")).toBe(bBefore);
+    expect(container.querySelector("#c")?.textContent).toBe("c");
+    expect(container.querySelectorAll("#list > li")).toHaveLength(3);
+    document.body.removeChild(container);
+  });
+
+  it("keeps the real element even when its fresh counterpart bypassed mountElement (nothing recorded to replay)", () => {
+    class RawComp extends StatefulComponent {
+      static __isComponent = true as const;
+      static __isStateless = false;
+      render() {
+        const el = document.createElement("mark");
+        el.id = "raw";
+        el.textContent = "raw content";
+        return el;
+      }
+    }
+
+    const factory = () => mountComponent(RawComp, {}, getCurrentScope());
+    const container = hydratable(factory);
+    const markBefore = container.querySelector("#raw");
+
+    render(factory, container);
+
+    expect(container.querySelector("#raw")).toBe(markBefore);
+    expect(container.textContent).toBe("raw content");
+    document.body.removeChild(container);
+  });
+
+  it("removes trailing real nodes the fresh tree no longer produces", () => {
+    // Server rendered three items; the client factory only produces two —
+    // exercises reconcile()'s cleanup loop for leftover real siblings past
+    // the end of freshChildren.
+    const factory = () => mountElement("ul", {
+      id: "list",
+      children: [
+        mountElement("li", { id: "a", children: "a" }, new Scope()),
+        mountElement("li", { id: "b", children: "b" }, new Scope()),
+      ],
+    }, new Scope());
+
+    const container = document.createElement("div");
+    container.innerHTML =
+      '<ul id="list"><li id="a">a</li><li id="b">b</li><li id="c">c</li></ul>';
+    container.setAttribute(SSG_MARKER, "1");
+    document.body.appendChild(container);
+
+    const aBefore = container.querySelector("#a");
+    const bBefore = container.querySelector("#b");
+
+    render(factory, container);
+
+    expect(container.querySelector("#a")).toBe(aBefore);
+    expect(container.querySelector("#b")).toBe(bBefore);
+    expect(container.querySelector("#c")).toBeNull();
+    expect(container.querySelectorAll("#list > li")).toHaveLength(2);
+    document.body.removeChild(container);
+  });
+
+  it("reconcile() is a safe no-op when a fresh node's registered reactive owner doesn't actually contain it", () => {
+    // Defensive guard in notifyReplacement(): registerReactiveNode() always
+    // registers a node into the exact array collectNodes() just built it
+    // into, so indexOf() finding nothing shouldn't happen through normal
+    // mounting — this exercises that branch directly, at the unit level, to
+    // confirm the guard degrades safely (no throw, no corruption) rather
+    // than silently trusting it can never occur.
+    const fresh = document.createElement("span");
+    const bogusOwner: Node[] = [];
+    registerReactiveNode(fresh, bogusOwner);
+
+    const container = document.createElement("div");
+    const real = document.createElement("span");
+    container.appendChild(real);
+
+    expect(() => { reconcile(container, [fresh]); }).not.toThrow();
+    expect(bogusOwner).toEqual([]);
+    expect(container.firstChild).toBe(real);
+  });
+
+  it("plain client render (no SSG marker) is completely unaffected", () => {
+    const factory = () => mountElement("p", { children: "hello" }, new Scope());
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+
+    render(factory, container);
+
+    expect(container.textContent).toBe("hello");
+    document.body.removeChild(container);
+  });
+});
+
+describe("Portal — server render pass", () => {
+  it("renders nothing into the target during a server render pass", () => {
+    setServerRenderPass(true);
+    expect(isServerRenderPass()).toBe(true);
+
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+    const scope = new Scope();
+    const nodes = mountComponent(Portal, { to: target, children: document.createTextNode("hi") }, scope);
+
+    expect(target.textContent).toBe("");
+    expect(nodes.every((n) => n.nodeType === Node.COMMENT_NODE)).toBe(true);
+    scope.dispose();
+    document.body.removeChild(target);
+  });
+
+  it("mounts normally on the client once the server pass is over", () => {
+    setServerRenderPass(false);
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+    const scope = new Scope();
+
+    mountComponent(Portal, { to: target, children: document.createTextNode("hi") }, scope);
+
+    expect(target.textContent).toBe("hi");
+    scope.dispose();
+    document.body.removeChild(target);
+  });
+});

package/src/element.ts

@@ -1,6 +1,7 @@
 import { mountChildren } from "./children";
 import { createElement } from "./dom/create";
 import { applyProp } from "./dom/props";
+import { isRecording, recordProps } from "./hydration-context";
 
 import type { Scope } from "./scope";
 
@@ -11,6 +12,10 @@ export function mountElement(
 ): HTMLElement | SVGElement {
   const el = createElement(tag);
 
+  // During a hydration build pass, retain (props, scope) so reconcile() can
+  // replay them onto whichever real element it ends up keeping instead.
+  if (isRecording()) recordProps(el, props, scope);
+
   for (const key in props) {
     if (key === "children") continue;
     applyProp(el, key, props[key], scope);

package/src/hydration-context.ts

@@ -0,0 +1,53 @@
+import type { Scope } from "./scope";
+
+let _recording = false;
+
+/**
+ * Marks the synchronous "build" pass of a hydration attempt: `factory()` runs
+ * completely normally (same create-mode code as a plain client render), but
+ * every element additionally records its (props, scope) for reconcile()'s
+ * replay step, and every mountReactive() region records which of its output
+ * nodes may need to be swapped in-place if reconcile() decides to keep a real
+ * element instead of the fresh one. No-op / zero cost outside a build pass.
+ */
+export function runInRecording<T>(fn: () => T): T {
+  const prev = _recording;
+  _recording = true;
+  try {
+    return fn();
+  } finally {
+    _recording = prev;
+  }
+}
+
+export function isRecording(): boolean {
+  return _recording;
+}
+
+interface PropRecord {
+  props: Record<string, unknown>;
+  scope: Scope;
+}
+
+const _propRecords = new WeakMap<Element, PropRecord>();
+
+export function recordProps(el: Element, props: Record<string, unknown>, scope: Scope): void {
+  _propRecords.set(el, { props, scope });
+}
+
+export function getRecordedProps(el: Element): PropRecord | undefined {
+  return _propRecords.get(el);
+}
+
+// mountReactive() keeps a `currentNodes` array (by reference) for diffing its
+// *next* update. If reconcile() replaces one of those fresh nodes with a real
+// one, it needs to overwrite that array in place so the closure sees the swap.
+const _reactiveOwners = new WeakMap<Node, Node[]>();
+
+export function registerReactiveNode(node: Node, owner: Node[]): void {
+  _reactiveOwners.set(node, owner);
+}
+
+export function getReactiveOwner(node: Node): Node[] | undefined {
+  return _reactiveOwners.get(node);
+}

package/src/hydration.ts

@@ -0,0 +1,70 @@
+import { applyProp } from "./dom/props";
+import { getReactiveOwner, getRecordedProps } from "./hydration-context";
+
+function replayProps(real: Element, fresh: Element): void {
+  const record = getRecordedProps(fresh);
+  if (!record) return;
+  for (const key in record.props) {
+    if (key === "children") continue;
+    applyProp(real, key, record.props[key], record.scope);
+  }
+}
+
+// mountReactive()'s `currentNodes` array holds fresh node references for its
+// *next* diff. If we're keeping `real` instead of `fresh` here, that array
+// needs to see the swap too — it's registered by reference, so this mutation
+// is visible to whichever effect closure owns it.
+function notifyReplacement(fresh: Node, real: Node): void {
+  const owner = getReactiveOwner(fresh);
+  if (!owner) return;
+  const idx = owner.indexOf(fresh);
+  if (idx !== -1) owner[idx] = real;
+}
+
+/**
+ * Walks `freshChildren` (the complete, correctly-nested output of a normal
+ * create-mode mount into a detached scratch node) against `realParent`'s
+ * existing children (the server-rendered DOM already attached to the page),
+ * in document order — safe now that both trees are fully built, unlike trying
+ * to adopt while `freshChildren` was still being constructed.
+ *
+ * Matching elements keep the real node (props/listeners replayed onto it,
+ * via `applyProp` — the same function normal mounting uses) and recurse.
+ * Text/comment nodes are always taken from the fresh side — they carry no
+ * listeners or state, so recreating them is free and avoids having to
+ * re-point mountComponent/mountReactive's anchor comments. Anything that
+ * doesn't line up (different tag, or one side ran out) is a local mismatch:
+ * the stale real node is dropped and the fresh one takes its place — no
+ * lookahead, no reordering, and no whole-page fallback.
+ */
+export function reconcile(realParent: Node, freshChildren: Node[]): void {
+  let realCursor: ChildNode | null = realParent.firstChild;
+
+  for (const fresh of freshChildren) {
+    if (
+      fresh.nodeType === Node.ELEMENT_NODE &&
+      realCursor?.nodeType === Node.ELEMENT_NODE &&
+      (realCursor as Element).localName === (fresh as Element).localName
+    ) {
+      const real = realCursor as Element;
+      realCursor = real.nextSibling;
+      replayProps(real, fresh as Element);
+      reconcile(real, Array.from((fresh as Element).childNodes));
+      notifyReplacement(fresh, real);
+      continue;
+    }
+
+    if (realCursor) {
+      const stale = realCursor;
+      realCursor = realCursor.nextSibling;
+      stale.remove();
+    }
+    realParent.insertBefore(fresh, realCursor);
+  }
+
+  while (realCursor) {
+    const stale = realCursor;
+    realCursor = realCursor.nextSibling;
+    stale.remove();
+  }
+}

package/src/index.ts

@@ -1,22 +1,17 @@
 import { mountChildren } from "./children";
 import { runInScope } from "./context";
+import { reconcile } from "./hydration";
+import { runInRecording } from "./hydration-context";
 import { Scope } from "./scope";
 
-/**
- * Renders a component tree into a container element.
- *
- * The factory function is called once inside the root scope,
- * so `jsx()` can access the current scope via `getCurrentScope()`.
- *
- * @example
- * render(() => <App />, document.getElementById('app'));
- */
-export function render(
+/** Written by `@praxisjs/ssg` onto the mount container in its prerendered HTML. */
+const SSG_MARKER = "data-praxis-ssg";
+
+function mountCreate(
   factory: () => Node | Node[] | null,
   container: HTMLElement,
 ): () => void {
   const rootScope = new Scope();
-
   container.innerHTML = "";
 
   runInScope(rootScope, () => {
@@ -30,6 +25,57 @@ export function render(
   };
 }
 
+function hydrate(
+  factory: () => Node | Node[] | null,
+  container: HTMLElement,
+): () => void {
+  const rootScope = new Scope();
+  const scratch = document.createDocumentFragment();
+
+  // Build normally — same code as mountCreate, just into a detached scratch
+  // node instead of the real container, so it can be walked in document
+  // order afterwards (its own construction order is bottom-up, not useful
+  // for matching against the server-rendered DOM directly).
+  runInRecording(() => {
+    runInScope(rootScope, () => {
+      const result = factory();
+      mountChildren(scratch, result, rootScope);
+    });
+  });
+
+  reconcile(container, Array.from(scratch.childNodes));
+
+  return () => {
+    rootScope.dispose();
+    container.innerHTML = "";
+  };
+}
+
+/**
+ * Renders a component tree into a container element.
+ *
+ * The factory function is called once inside the root scope,
+ * so `jsx()` can access the current scope via `getCurrentScope()`.
+ *
+ * If `container` carries the marker `@praxisjs/ssg` stamps onto prerendered
+ * HTML, the tree is built normally into a detached scratch node and then
+ * reconciled against the existing DOM (real elements are kept and have their
+ * props/listeners replayed onto them; text/comments and any mismatched nodes
+ * are recreated) instead of clearing the container and mounting fresh.
+ *
+ * @example
+ * render(() => <App />, document.getElementById('app'));
+ */
+export function render(
+  factory: () => Node | Node[] | null,
+  container: HTMLElement,
+): () => void {
+  if (container.hasAttribute(SSG_MARKER)) {
+    return hydrate(factory, container);
+  }
+  return mountCreate(factory, container);
+}
+
 export { Scope } from "./scope";
 export { runInScope, getCurrentScope } from "./context";
 export { mountElement } from "./element";

package/src/portal.ts

@@ -1,4 +1,5 @@
 import { StatelessComponent } from "@praxisjs/core";
+import { isServerRenderPass } from "@praxisjs/core/internal";
 
 import { mountChildren } from "./children";
 import { getCurrentScope } from "./context";
@@ -12,6 +13,13 @@ export class Portal extends StatelessComponent<PortalProps> {
   static readonly __isStateless = true;
 
   render() {
+    // Portals escape to an arbitrary external target (default document.body),
+    // which would need a hydration cursor shared across every portal mounted at
+    // that same target — out of scope for v1. Skip during the server render pass
+    // (target content isn't part of the static HTML); the client mounts normally,
+    // create-mode, right after hydration completes — no duplication.
+    if (isServerRenderPass()) return null;
+
     const scope = getCurrentScope();
     const target = resolvePortalTarget(this.props.to);
     if (!target) return null;

package/src/reactive.ts

@@ -1,4 +1,5 @@
 import { runInScope } from "./context";
+import { isRecording, registerReactiveNode } from "./hydration-context";
 import { Scope } from "./scope";
 
 function collectNodes(value: unknown, out: Node[]): void {
@@ -37,6 +38,15 @@ export function mountReactive(
     const newNodes: Node[] = [];
     collectNodes(result, newNodes);
 
+    // During a hydration build pass, remember that each of these fresh nodes
+    // belongs to *this* array — reconcile() mutates `newNodes` in place (by
+    // reference, same array `currentNodes` ends up pointing at) if it decides
+    // to keep a real element instead of one of them, so future diffs here
+    // stay correct.
+    if (isRecording()) {
+      for (const n of newNodes) registerReactiveNode(n, newNodes);
+    }
+
     const anchor = end.parentNode ?? parent;
 
     if (currentNodes.length > 0) {