@praxisjs/runtime 0.5.5 → 0.7.0

package/src/dom/remove.ts

@@ -0,0 +1,22 @@
+// Replaces Range.deleteContents(): creating a Range per removal is several times slower than
+// walking the siblings, and unreachable Ranges stay registered with the document until collected.
+// Walking first → last (rather than only the tracked nodes) also removes anything a nested reactive
+// child inserted between them after mount, which is what the Range used to cover.
+export function removeNodes(nodes: Node[]): void {
+  const first = nodes[0];
+  const last = nodes[nodes.length - 1];
+  const parent = first.parentNode;
+
+  if (parent === null || last.parentNode !== parent) {
+    for (const node of nodes) node.parentNode?.removeChild(node);
+    return;
+  }
+
+  let node: Node | null = first;
+  while (node) {
+    const next: Node | null = node.nextSibling;
+    parent.removeChild(node);
+    if (node === last) return;
+    node = next;
+  }
+}

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,7 +1,9 @@
 import { StatelessComponent } from "@praxisjs/core";
+import { isServerRenderPass } from "@praxisjs/core/internal";
 
 import { mountChildren } from "./children";
 import { getCurrentScope } from "./context";
+import { removeNodes } from "./dom/remove";
 
 export interface PortalProps {
   to?: Element | string | null;
@@ -12,6 +14,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;
@@ -19,16 +28,16 @@ export class Portal extends StatelessComponent<PortalProps> {
     const start = document.createComment("");
     const end = document.createComment("");
 
-    target.appendChild(start);
-    mountChildren(target, this.props.children, scope);
-    target.appendChild(end);
+    // Built off-document and attached once, so the target never sees a half-built subtree.
+    const fragment = document.createDocumentFragment();
+    fragment.appendChild(start);
+    mountChildren(fragment, this.props.children, scope);
+    fragment.appendChild(end);
+    target.appendChild(fragment);
 
     scope.add(() => {
       if (!start.parentNode || start.parentNode !== end.parentNode) return;
-      const range = document.createRange();
-      range.setStartBefore(start);
-      range.setEndAfter(end);
-      range.deleteContents();
+      removeNodes([start, end]);
     });
 
     return document.createComment("portal");

package/src/reactive.ts

@@ -1,4 +1,6 @@
 import { runInScope } from "./context";
+import { removeNodes } from "./dom/remove";
+import { isRecording, registerReactiveNode } from "./hydration-context";
 import { Scope } from "./scope";
 
 function collectNodes(value: unknown, out: Node[]): void {
@@ -37,17 +39,21 @@ 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) {
-      if (currentNodes.length === 1) {
-        (anchor as Element).removeChild(currentNodes[0]);
-      } else {
-        const range = document.createRange();
-        range.setStartBefore(currentNodes[0]);
-        range.setEndAfter(currentNodes[currentNodes.length - 1]);
-        range.deleteContents();
-      }
+    if (currentNodes.length === 1) {
+      (anchor as Element).removeChild(currentNodes[0]);
+    } else if (currentNodes.length > 1) {
+      removeNodes(currentNodes);
     }
 
     if (newNodes.length > 0) {