@lwc/engine-core 2.5.1 → 2.5.2-canary1

package/dist/engine-core.cjs.js

@@ -4012,7 +4012,6 @@ function setScopeTokenClassIfNecessary(elm, owner) {
     owner.renderer.getClassList(elm).add(token);
   }
 }
-
 function updateNodeHook(oldVnode, vnode) {
   const {
     elm,
@@ -4076,6 +4075,16 @@ function createElmHook(vnode) {
   modComputedClassName.create(vnode);
   modComputedStyle.create(vnode);
 }
+function hydrateElmHook(vnode) {
+  modEvents.create(vnode); // Attrs are already on the element.
+  // modAttrs.create(vnode);
+
+  modProps.create(vnode); // Already set.
+  // modStaticClassName.create(vnode);
+  // modStaticStyle.create(vnode);
+  // modComputedClassName.create(vnode);
+  // modComputedStyle.create(vnode);
+}
 function fallbackElmHook(elm, vnode) {
   const {
     owner
@@ -4240,6 +4249,172 @@ function createChildrenHook(vnode) {
     }
   }
 }
+
+function isElementNode(node) {
+  // @todo: should the hydrate be part of engine-dom? can we move hydrate out of the hooks?
+  // eslint-disable-next-line lwc-internal/no-global-node
+  return node.nodeType === Node.ELEMENT_NODE;
+}
+
+function vnodesAndElementHaveCompatibleAttrs(vnode, elm) {
+  const {
+    data: {
+      attrs = {}
+    },
+    owner: {
+      renderer
+    }
+  } = vnode;
+  let nodesAreCompatible = true; // Validate attributes, though we could always recovery from those by running the update mods.
+  // Note: intentionally ONLY matching vnodes.attrs to elm.attrs, in case SSR is adding extra attributes.
+
+  for (const [attrName, attrValue] of Object.entries(attrs)) {
+    const elmAttrValue = renderer.getAttribute(elm, attrName);
+
+    if (attrValue !== elmAttrValue) {
+      logError(`Error hydrating element: attribute "${attrName}" has different values, expected "${attrValue}" but found "${elmAttrValue}"`, vnode.owner);
+      nodesAreCompatible = false;
+    }
+  }
+
+  return nodesAreCompatible;
+}
+
+function vnodesAndElementHaveCompatibleClass(vnode, elm) {
+  const {
+    data: {
+      className,
+      classMap
+    },
+    owner: {
+      renderer
+    }
+  } = vnode;
+  let nodesAreCompatible = true;
+
+  if (!shared.isUndefined(className) && className !== elm.className) {
+    // @todo: not sure if the above comparison is correct, maybe we should normalize to classlist
+    // className is used when class is bound to an expr.
+    logError(`Mismatch hydrating element: attribute "class" has different values, expected "${className}" but found "${elm.className}"`, vnode.owner);
+    nodesAreCompatible = false;
+  } else if (!shared.isUndefined(classMap)) {
+    // classMap is used when class is set to static value.
+    // @todo: there might be a simpler method to do this.
+    const classList = renderer.getClassList(elm);
+    let hasClassMismatch = false;
+    let computedClassName = ''; // all classes from the vnode should be in the element.classList
+
+    for (const name in classMap) {
+      computedClassName += ' ' + name;
+
+      if (!classList.contains(name)) {
+        nodesAreCompatible = false;
+        hasClassMismatch = true;
+      }
+    } // all classes from element.classList should be in the vnode classMap
+
+
+    classList.forEach(name => {
+      if (!classMap[name]) {
+        nodesAreCompatible = false;
+        hasClassMismatch = true;
+      }
+    });
+
+    if (hasClassMismatch) {
+      logError(`Mismatch hydrating element: attribute "class" has different values, expected "${computedClassName.trim()}" but found "${elm.className}"`, vnode.owner);
+    }
+  }
+
+  return nodesAreCompatible;
+}
+
+function vnodesAndElementHaveCompatibleStyle(vnode, elm) {
+  const {
+    data: {
+      style,
+      styleDecls
+    },
+    owner: {
+      renderer
+    }
+  } = vnode;
+  const elmStyle = renderer.getAttribute(elm, 'style');
+  let nodesAreCompatible = true; // @todo: question: would it be the same or is there a chance that the browser tweak the result of elm.setAttribute('style', ...)?
+  //        ex: such "str" exist that after elm.setAttribute('style', str), elm.getAttribute('style') !== str.
+
+  if (!shared.isUndefined(style) && style !== elmStyle) {
+    // style is used when class is bound to an expr.
+    logError(`Mismatch hydrating element: attribute "style" has different values, expected "${style}" but found "${elmStyle}".`, vnode.owner);
+    nodesAreCompatible = false;
+  } else if (!shared.isUndefined(styleDecls)) {
+    // styleMap is used when class is set to static value.
+    for (let i = 0; i < styleDecls.length; i++) {
+      const [prop, value, important] = styleDecls[i];
+      const elmPropValue = elm.style.getPropertyValue(prop);
+      const elmPropPriority = elm.style.getPropertyPriority(prop);
+
+      if (value !== elmPropValue || important !== (elmPropPriority === 'important')) {
+        nodesAreCompatible = false;
+      }
+    } // questions: is there a way to check that only those props in styleMap are set in the element?
+    //            how to generate the style?
+
+
+    logError('Error hydrating element: attribute "style" has different values.', vnode.owner);
+  }
+
+  return nodesAreCompatible;
+}
+
+function throwHydrationError() {
+  // @todo: maybe create a type for these type of hydration errors
+  shared.assert.fail('Server rendered elements do not match client side generated elements');
+}
+
+function hydrateChildrenHook(elmChildren, children, vm) {
+  var _a;
+
+  if (process.env.NODE_ENV !== 'production') {
+    const filteredVNodes = shared.ArrayFilter.call(children, vnode => !!vnode);
+
+    if (elmChildren.length !== filteredVNodes.length) {
+      logError(`Hydration mismatch: incorrect number of rendered elements, expected ${filteredVNodes.length} but found ${elmChildren.length}.`, vm);
+      throwHydrationError();
+    }
+  }
+
+  let elmCurrentChildIdx = 0;
+
+  for (let j = 0, n = children.length; j < n; j++) {
+    const ch = children[j];
+
+    if (ch != null) {
+      const childNode = elmChildren[elmCurrentChildIdx];
+
+      if (process.env.NODE_ENV !== 'production') {
+        // VComments and VTexts validation is handled in their hooks
+        if (isElementNode(childNode)) {
+          if (((_a = ch.sel) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== childNode.tagName.toLowerCase()) {
+            logError(`Hydration mismatch: expecting element with tag "${ch.sel}" but found "${childNode.tagName}".`, vm);
+            throwHydrationError();
+          } // Note: props are not yet set
+
+
+          const isVNodeAndElementCompatible = vnodesAndElementHaveCompatibleAttrs(ch, childNode) && vnodesAndElementHaveCompatibleClass(ch, childNode) && vnodesAndElementHaveCompatibleStyle(ch, childNode);
+
+          if (!isVNodeAndElementCompatible) {
+            logError(`Hydration mismatch: incompatible attributes for element with tag "${childNode.tagName}".`, vm);
+            throwHydrationError();
+          }
+        }
+      }
+
+      ch.hook.hydrate(ch, childNode);
+      elmCurrentChildIdx++;
+    }
+  }
+}
 function updateCustomElmHook(oldVnode, vnode) {
   // Attrs need to be applied to element before props
   // IE11 will wipe out value on radio inputs if value
@@ -4336,7 +4511,27 @@ const TextHook = {
   update: updateNodeHook,
   insert: insertNodeHook,
   move: insertNodeHook,
-  remove: removeNodeHook
+  remove: removeNodeHook,
+  hydrate: (vNode, node) => {
+    var _a; // @todo tests.
+
+
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line lwc-internal/no-global-node
+      if (node.nodeType !== Node.TEXT_NODE) {
+        logError('Hydration mismatch: incorrect node type received', vNode.owner);
+        shared.assert.fail('Hydration mismatch: incorrect node type received.');
+      }
+
+      if (node.nodeValue !== vNode.text) {
+        logError('Hydration mismatch: text values do not match, will recover from the difference', vNode.owner);
+      }
+    } // always set the text value to the one from the vnode.
+
+
+    node.nodeValue = (_a = vNode.text) !== null && _a !== void 0 ? _a : null;
+    vNode.elm = node;
+  }
 };
 const CommentHook = {
   create: vnode => {
@@ -4354,7 +4549,23 @@ const CommentHook = {
   update: updateNodeHook,
   insert: insertNodeHook,
   move: insertNodeHook,
-  remove: removeNodeHook
+  remove: removeNodeHook,
+  hydrate: (vNode, node) => {
+    var _a; // @todo tests.
+
+
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line lwc-internal/no-global-node
+      if (node.nodeType !== Node.COMMENT_NODE) {
+        logError('Hydration mismatch: incorrect node type received', vNode.owner);
+        shared.assert.fail('Hydration mismatch: incorrect node type received.');
+      }
+    } // always set the text value to the one from the vnode.
+
+
+    node.nodeValue = (_a = vNode.text) !== null && _a !== void 0 ? _a : null;
+    vNode.elm = node;
+  }
 }; // insert is called after update, which is used somewhere else (via a module)
 // to mark the vm as inserted, that means we cannot use update as the main channel
 // to rehydrate when dirty, because sometimes the element is not inserted just yet,
@@ -4394,6 +4605,12 @@ const ElementHook = {
   remove: (vnode, parentNode) => {
     removeNodeHook(vnode, parentNode);
     removeElmHook(vnode);
+  },
+  hydrate: (vnode, node) => {
+    vnode.elm = node;
+    hydrateElmHook(vnode); // hydrate children hook
+
+    hydrateChildrenHook(vnode.elm.childNodes, vnode.children, vnode.owner);
   }
 };
 const CustomElementHook = {
@@ -4485,6 +4702,52 @@ const CustomElementHook = {
       // will take care of disconnecting any child VM attached to its shadow as well.
       removeVM(vm);
     }
+  },
+  hydrate: (vnode, elm) => {
+    // the element is created, but the vm is not
+    const {
+      sel,
+      mode,
+      ctor,
+      owner
+    } = vnode;
+    const def = getComponentInternalDef(ctor);
+    createVM(elm, def, {
+      mode,
+      owner,
+      tagName: sel,
+      renderer: owner.renderer
+    });
+    vnode.elm = elm;
+    const vm = getAssociatedVMIfPresent(elm);
+
+    if (vm) {
+      allocateChildrenHook(vnode, vm);
+    }
+
+    hydrateElmHook(vnode); // Insert hook section:
+
+    if (vm) {
+      if (process.env.NODE_ENV !== 'production') {
+        shared.assert.isTrue(vm.state === 0
+        /* created */
+        , `${vm} cannot be recycled.`);
+      }
+
+      runConnectedCallback(vm);
+    }
+
+    if (!(vm && vm.renderMode === 0
+    /* Light */
+    )) {
+      // VM is not rendering in Light DOM, we can proceed and hydrate the slotted content.
+      // Note: for Light DOM, this is handled while hydrating the VM
+      hydrateChildrenHook(vnode.elm.childNodes, vnode.children, vm);
+    }
+
+    if (vm) {
+      hydrateVM(vm);
+    }
   }
 };
 
@@ -5135,7 +5398,7 @@ function createStylesheet(vm, stylesheets) {
     for (let i = 0; i < stylesheets.length; i++) {
       renderer.insertGlobalStylesheet(stylesheets[i]);
     }
-  } else if (renderer.ssr) {
+  } else if (renderer.ssr || renderer.isHydrating) {
     // native shadow or light DOM, SSR
     const combinedStylesheetContent = shared.ArrayJoin.call(stylesheets, '\n');
     return createInlineStyleVNode(combinedStylesheetContent);
@@ -5321,9 +5584,9 @@ function validateLightDomTemplate(template, vm) {
   if (vm.renderMode === 0
   /* Light */
   ) {
-    shared.assert.isTrue(template.renderMode === 'light', `Light DOM components can't render shadow DOM templates. Add an 'lwc:render-mode="light"' directive on the root template tag.`);
+    shared.assert.isTrue(template.renderMode === 'light', `Light DOM components can't render shadow DOM templates. Add an 'lwc:render-mode="light"' directive to the root template tag of ${getComponentTag(vm)}.`);
   } else {
-    shared.assert.isTrue(shared.isUndefined(template.renderMode), `Shadow DOM components template can't render light DOM templates. Either remove the 'lwc:render-mode' directive or set it to 'lwc:render-mode="shadow"`);
+    shared.assert.isTrue(shared.isUndefined(template.renderMode), `Shadow DOM components template can't render light DOM templates. Either remove the 'lwc:render-mode' directive from ${getComponentTag(vm)} or set it to 'lwc:render-mode="shadow"`);
   }
 }
 
@@ -5732,12 +5995,28 @@ function connectRootElement(elm) {
   /* GlobalHydrate */
   , vm);
 }
+function hydrateRootElement(elm) {
+  const vm = getAssociatedVM(elm); // Usually means moving the element from one place to another, which is observable via
+  // life-cycle hooks.
+
+  if (vm.state === 1
+  /* connected */
+  ) {
+    disconnectRootElement(elm);
+  }
+
+  runConnectedCallback(vm);
+  hydrateVM(vm); // should we hydrate the root children? light dom case.
+}
 function disconnectRootElement(elm) {
   const vm = getAssociatedVM(elm);
   resetComponentStateWhenRemoved(vm);
 }
 function appendVM(vm) {
   rehydrate(vm);
+}
+function hydrateVM(vm) {
+  hydrate(vm);
 } // just in case the component comes back, with this we guarantee re-rendering it
 // while preventing any attempt to rehydration until after reinsertion.
 
@@ -5962,6 +6241,22 @@ function rehydrate(vm) {
   }
 }
 
+function hydrate(vm) {
+  if (shared.isTrue(vm.isDirty)) {
+    // manually diffing/patching here.
+    // This routine is:
+    // patchShadowRoot(vm, children);
+    //  -> addVnodes.
+    const children = renderComponent(vm);
+    vm.children = children;
+    const vmChildren = vm.renderMode === 0
+    /* Light */
+    ? vm.elm.childNodes : vm.elm.shadowRoot.childNodes;
+    hydrateChildrenHook(vmChildren, children, vm);
+    runRenderedCallback(vm);
+  }
+}
+
 function patchShadowRoot(vm, newCh) {
   const {
     children: oldCh
@@ -6788,6 +7083,7 @@ exports.getAssociatedVMIfPresent = getAssociatedVMIfPresent;
 exports.getComponentDef = getComponentDef;
 exports.getComponentInternalDef = getComponentInternalDef;
 exports.getUpgradableConstructor = getUpgradableConstructor;
+exports.hydrateRootElement = hydrateRootElement;
 exports.isComponentConstructor = isComponentConstructor;
 exports.readonly = readonly;
 exports.register = register;
@@ -6801,4 +7097,4 @@ exports.swapTemplate = swapTemplate;
 exports.track = track;
 exports.unwrap = unwrap;
 exports.wire = wire;
-/* version: 2.5.1 */
+/* version: 2.5.2-canary1 */

package/dist/engine-core.js

@@ -1,5 +1,5 @@
 /* proxy-compat-disable */
-import { seal, create, isFunction as isFunction$1, ArrayPush as ArrayPush$1, isUndefined as isUndefined$1, ArrayIndexOf, ArraySplice, StringToLowerCase, ArrayJoin, isNull, assign, assert, keys, StringCharCodeAt, isString, StringSlice, freeze, defineProperties, forEach, getOwnPropertyNames as getOwnPropertyNames$1, getPrototypeOf as getPrototypeOf$1, setPrototypeOf, getPropertyDescriptor, isObject, AriaPropNameToAttrNameMap, defineProperty, KEY__SYNTHETIC_MODE, toString as toString$1, isFalse, isTrue, getOwnPropertyDescriptor as getOwnPropertyDescriptor$1, htmlPropertyToAttribute, ArraySlice, hasOwnProperty as hasOwnProperty$1, noop, isArray as isArray$1, isNumber, StringReplace, KEY__SHADOW_RESOLVER, KEY__SCOPED_CSS, ArrayUnshift, isFrozen } from '@lwc/shared';
+import { seal, create, isFunction as isFunction$1, ArrayPush as ArrayPush$1, isUndefined as isUndefined$1, ArrayIndexOf, ArraySplice, StringToLowerCase, ArrayJoin, isNull, assign, assert, keys, StringCharCodeAt, isString, StringSlice, freeze, defineProperties, forEach, getOwnPropertyNames as getOwnPropertyNames$1, getPrototypeOf as getPrototypeOf$1, setPrototypeOf, getPropertyDescriptor, isObject, AriaPropNameToAttrNameMap, defineProperty, KEY__SYNTHETIC_MODE, toString as toString$1, isFalse, isTrue, getOwnPropertyDescriptor as getOwnPropertyDescriptor$1, htmlPropertyToAttribute, ArraySlice, hasOwnProperty as hasOwnProperty$1, ArrayFilter, noop, isArray as isArray$1, isNumber, StringReplace, KEY__SHADOW_RESOLVER, KEY__SCOPED_CSS, ArrayUnshift, isFrozen } from '@lwc/shared';
 import { runtimeFlags } from '@lwc/features';
 export { setFeatureFlag, setFeatureFlagForTest } from '@lwc/features';
 
@@ -4009,7 +4009,6 @@ function setScopeTokenClassIfNecessary(elm, owner) {
     owner.renderer.getClassList(elm).add(token);
   }
 }
-
 function updateNodeHook(oldVnode, vnode) {
   const {
     elm,
@@ -4073,6 +4072,16 @@ function createElmHook(vnode) {
   modComputedClassName.create(vnode);
   modComputedStyle.create(vnode);
 }
+function hydrateElmHook(vnode) {
+  modEvents.create(vnode); // Attrs are already on the element.
+  // modAttrs.create(vnode);
+
+  modProps.create(vnode); // Already set.
+  // modStaticClassName.create(vnode);
+  // modStaticStyle.create(vnode);
+  // modComputedClassName.create(vnode);
+  // modComputedStyle.create(vnode);
+}
 function fallbackElmHook(elm, vnode) {
   const {
     owner
@@ -4237,6 +4246,172 @@ function createChildrenHook(vnode) {
     }
   }
 }
+
+function isElementNode(node) {
+  // @todo: should the hydrate be part of engine-dom? can we move hydrate out of the hooks?
+  // eslint-disable-next-line lwc-internal/no-global-node
+  return node.nodeType === Node.ELEMENT_NODE;
+}
+
+function vnodesAndElementHaveCompatibleAttrs(vnode, elm) {
+  const {
+    data: {
+      attrs = {}
+    },
+    owner: {
+      renderer
+    }
+  } = vnode;
+  let nodesAreCompatible = true; // Validate attributes, though we could always recovery from those by running the update mods.
+  // Note: intentionally ONLY matching vnodes.attrs to elm.attrs, in case SSR is adding extra attributes.
+
+  for (const [attrName, attrValue] of Object.entries(attrs)) {
+    const elmAttrValue = renderer.getAttribute(elm, attrName);
+
+    if (attrValue !== elmAttrValue) {
+      logError(`Error hydrating element: attribute "${attrName}" has different values, expected "${attrValue}" but found "${elmAttrValue}"`, vnode.owner);
+      nodesAreCompatible = false;
+    }
+  }
+
+  return nodesAreCompatible;
+}
+
+function vnodesAndElementHaveCompatibleClass(vnode, elm) {
+  const {
+    data: {
+      className,
+      classMap
+    },
+    owner: {
+      renderer
+    }
+  } = vnode;
+  let nodesAreCompatible = true;
+
+  if (!isUndefined$1(className) && className !== elm.className) {
+    // @todo: not sure if the above comparison is correct, maybe we should normalize to classlist
+    // className is used when class is bound to an expr.
+    logError(`Mismatch hydrating element: attribute "class" has different values, expected "${className}" but found "${elm.className}"`, vnode.owner);
+    nodesAreCompatible = false;
+  } else if (!isUndefined$1(classMap)) {
+    // classMap is used when class is set to static value.
+    // @todo: there might be a simpler method to do this.
+    const classList = renderer.getClassList(elm);
+    let hasClassMismatch = false;
+    let computedClassName = ''; // all classes from the vnode should be in the element.classList
+
+    for (const name in classMap) {
+      computedClassName += ' ' + name;
+
+      if (!classList.contains(name)) {
+        nodesAreCompatible = false;
+        hasClassMismatch = true;
+      }
+    } // all classes from element.classList should be in the vnode classMap
+
+
+    classList.forEach(name => {
+      if (!classMap[name]) {
+        nodesAreCompatible = false;
+        hasClassMismatch = true;
+      }
+    });
+
+    if (hasClassMismatch) {
+      logError(`Mismatch hydrating element: attribute "class" has different values, expected "${computedClassName.trim()}" but found "${elm.className}"`, vnode.owner);
+    }
+  }
+
+  return nodesAreCompatible;
+}
+
+function vnodesAndElementHaveCompatibleStyle(vnode, elm) {
+  const {
+    data: {
+      style,
+      styleDecls
+    },
+    owner: {
+      renderer
+    }
+  } = vnode;
+  const elmStyle = renderer.getAttribute(elm, 'style');
+  let nodesAreCompatible = true; // @todo: question: would it be the same or is there a chance that the browser tweak the result of elm.setAttribute('style', ...)?
+  //        ex: such "str" exist that after elm.setAttribute('style', str), elm.getAttribute('style') !== str.
+
+  if (!isUndefined$1(style) && style !== elmStyle) {
+    // style is used when class is bound to an expr.
+    logError(`Mismatch hydrating element: attribute "style" has different values, expected "${style}" but found "${elmStyle}".`, vnode.owner);
+    nodesAreCompatible = false;
+  } else if (!isUndefined$1(styleDecls)) {
+    // styleMap is used when class is set to static value.
+    for (let i = 0; i < styleDecls.length; i++) {
+      const [prop, value, important] = styleDecls[i];
+      const elmPropValue = elm.style.getPropertyValue(prop);
+      const elmPropPriority = elm.style.getPropertyPriority(prop);
+
+      if (value !== elmPropValue || important !== (elmPropPriority === 'important')) {
+        nodesAreCompatible = false;
+      }
+    } // questions: is there a way to check that only those props in styleMap are set in the element?
+    //            how to generate the style?
+
+
+    logError('Error hydrating element: attribute "style" has different values.', vnode.owner);
+  }
+
+  return nodesAreCompatible;
+}
+
+function throwHydrationError() {
+  // @todo: maybe create a type for these type of hydration errors
+  assert.fail('Server rendered elements do not match client side generated elements');
+}
+
+function hydrateChildrenHook(elmChildren, children, vm) {
+  var _a;
+
+  if (process.env.NODE_ENV !== 'production') {
+    const filteredVNodes = ArrayFilter.call(children, vnode => !!vnode);
+
+    if (elmChildren.length !== filteredVNodes.length) {
+      logError(`Hydration mismatch: incorrect number of rendered elements, expected ${filteredVNodes.length} but found ${elmChildren.length}.`, vm);
+      throwHydrationError();
+    }
+  }
+
+  let elmCurrentChildIdx = 0;
+
+  for (let j = 0, n = children.length; j < n; j++) {
+    const ch = children[j];
+
+    if (ch != null) {
+      const childNode = elmChildren[elmCurrentChildIdx];
+
+      if (process.env.NODE_ENV !== 'production') {
+        // VComments and VTexts validation is handled in their hooks
+        if (isElementNode(childNode)) {
+          if (((_a = ch.sel) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== childNode.tagName.toLowerCase()) {
+            logError(`Hydration mismatch: expecting element with tag "${ch.sel}" but found "${childNode.tagName}".`, vm);
+            throwHydrationError();
+          } // Note: props are not yet set
+
+
+          const isVNodeAndElementCompatible = vnodesAndElementHaveCompatibleAttrs(ch, childNode) && vnodesAndElementHaveCompatibleClass(ch, childNode) && vnodesAndElementHaveCompatibleStyle(ch, childNode);
+
+          if (!isVNodeAndElementCompatible) {
+            logError(`Hydration mismatch: incompatible attributes for element with tag "${childNode.tagName}".`, vm);
+            throwHydrationError();
+          }
+        }
+      }
+
+      ch.hook.hydrate(ch, childNode);
+      elmCurrentChildIdx++;
+    }
+  }
+}
 function updateCustomElmHook(oldVnode, vnode) {
   // Attrs need to be applied to element before props
   // IE11 will wipe out value on radio inputs if value
@@ -4333,7 +4508,27 @@ const TextHook = {
   update: updateNodeHook,
   insert: insertNodeHook,
   move: insertNodeHook,
-  remove: removeNodeHook
+  remove: removeNodeHook,
+  hydrate: (vNode, node) => {
+    var _a; // @todo tests.
+
+
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line lwc-internal/no-global-node
+      if (node.nodeType !== Node.TEXT_NODE) {
+        logError('Hydration mismatch: incorrect node type received', vNode.owner);
+        assert.fail('Hydration mismatch: incorrect node type received.');
+      }
+
+      if (node.nodeValue !== vNode.text) {
+        logError('Hydration mismatch: text values do not match, will recover from the difference', vNode.owner);
+      }
+    } // always set the text value to the one from the vnode.
+
+
+    node.nodeValue = (_a = vNode.text) !== null && _a !== void 0 ? _a : null;
+    vNode.elm = node;
+  }
 };
 const CommentHook = {
   create: vnode => {
@@ -4351,7 +4546,23 @@ const CommentHook = {
   update: updateNodeHook,
   insert: insertNodeHook,
   move: insertNodeHook,
-  remove: removeNodeHook
+  remove: removeNodeHook,
+  hydrate: (vNode, node) => {
+    var _a; // @todo tests.
+
+
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line lwc-internal/no-global-node
+      if (node.nodeType !== Node.COMMENT_NODE) {
+        logError('Hydration mismatch: incorrect node type received', vNode.owner);
+        assert.fail('Hydration mismatch: incorrect node type received.');
+      }
+    } // always set the text value to the one from the vnode.
+
+
+    node.nodeValue = (_a = vNode.text) !== null && _a !== void 0 ? _a : null;
+    vNode.elm = node;
+  }
 }; // insert is called after update, which is used somewhere else (via a module)
 // to mark the vm as inserted, that means we cannot use update as the main channel
 // to rehydrate when dirty, because sometimes the element is not inserted just yet,
@@ -4391,6 +4602,12 @@ const ElementHook = {
   remove: (vnode, parentNode) => {
     removeNodeHook(vnode, parentNode);
     removeElmHook(vnode);
+  },
+  hydrate: (vnode, node) => {
+    vnode.elm = node;
+    hydrateElmHook(vnode); // hydrate children hook
+
+    hydrateChildrenHook(vnode.elm.childNodes, vnode.children, vnode.owner);
   }
 };
 const CustomElementHook = {
@@ -4482,6 +4699,52 @@ const CustomElementHook = {
       // will take care of disconnecting any child VM attached to its shadow as well.
       removeVM(vm);
     }
+  },
+  hydrate: (vnode, elm) => {
+    // the element is created, but the vm is not
+    const {
+      sel,
+      mode,
+      ctor,
+      owner
+    } = vnode;
+    const def = getComponentInternalDef(ctor);
+    createVM(elm, def, {
+      mode,
+      owner,
+      tagName: sel,
+      renderer: owner.renderer
+    });
+    vnode.elm = elm;
+    const vm = getAssociatedVMIfPresent(elm);
+
+    if (vm) {
+      allocateChildrenHook(vnode, vm);
+    }
+
+    hydrateElmHook(vnode); // Insert hook section:
+
+    if (vm) {
+      if (process.env.NODE_ENV !== 'production') {
+        assert.isTrue(vm.state === 0
+        /* created */
+        , `${vm} cannot be recycled.`);
+      }
+
+      runConnectedCallback(vm);
+    }
+
+    if (!(vm && vm.renderMode === 0
+    /* Light */
+    )) {
+      // VM is not rendering in Light DOM, we can proceed and hydrate the slotted content.
+      // Note: for Light DOM, this is handled while hydrating the VM
+      hydrateChildrenHook(vnode.elm.childNodes, vnode.children, vm);
+    }
+
+    if (vm) {
+      hydrateVM(vm);
+    }
   }
 };
 
@@ -5132,7 +5395,7 @@ function createStylesheet(vm, stylesheets) {
     for (let i = 0; i < stylesheets.length; i++) {
       renderer.insertGlobalStylesheet(stylesheets[i]);
     }
-  } else if (renderer.ssr) {
+  } else if (renderer.ssr || renderer.isHydrating) {
     // native shadow or light DOM, SSR
     const combinedStylesheetContent = ArrayJoin.call(stylesheets, '\n');
     return createInlineStyleVNode(combinedStylesheetContent);
@@ -5318,9 +5581,9 @@ function validateLightDomTemplate(template, vm) {
   if (vm.renderMode === 0
   /* Light */
   ) {
-    assert.isTrue(template.renderMode === 'light', `Light DOM components can't render shadow DOM templates. Add an 'lwc:render-mode="light"' directive on the root template tag.`);
+    assert.isTrue(template.renderMode === 'light', `Light DOM components can't render shadow DOM templates. Add an 'lwc:render-mode="light"' directive to the root template tag of ${getComponentTag(vm)}.`);
   } else {
-    assert.isTrue(isUndefined$1(template.renderMode), `Shadow DOM components template can't render light DOM templates. Either remove the 'lwc:render-mode' directive or set it to 'lwc:render-mode="shadow"`);
+    assert.isTrue(isUndefined$1(template.renderMode), `Shadow DOM components template can't render light DOM templates. Either remove the 'lwc:render-mode' directive from ${getComponentTag(vm)} or set it to 'lwc:render-mode="shadow"`);
   }
 }
 
@@ -5729,12 +5992,28 @@ function connectRootElement(elm) {
   /* GlobalHydrate */
   , vm);
 }
+function hydrateRootElement(elm) {
+  const vm = getAssociatedVM(elm); // Usually means moving the element from one place to another, which is observable via
+  // life-cycle hooks.
+
+  if (vm.state === 1
+  /* connected */
+  ) {
+    disconnectRootElement(elm);
+  }
+
+  runConnectedCallback(vm);
+  hydrateVM(vm); // should we hydrate the root children? light dom case.
+}
 function disconnectRootElement(elm) {
   const vm = getAssociatedVM(elm);
   resetComponentStateWhenRemoved(vm);
 }
 function appendVM(vm) {
   rehydrate(vm);
+}
+function hydrateVM(vm) {
+  hydrate(vm);
 } // just in case the component comes back, with this we guarantee re-rendering it
 // while preventing any attempt to rehydration until after reinsertion.
 
@@ -5959,6 +6238,22 @@ function rehydrate(vm) {
   }
 }
 
+function hydrate(vm) {
+  if (isTrue(vm.isDirty)) {
+    // manually diffing/patching here.
+    // This routine is:
+    // patchShadowRoot(vm, children);
+    //  -> addVnodes.
+    const children = renderComponent(vm);
+    vm.children = children;
+    const vmChildren = vm.renderMode === 0
+    /* Light */
+    ? vm.elm.childNodes : vm.elm.shadowRoot.childNodes;
+    hydrateChildrenHook(vmChildren, children, vm);
+    runRenderedCallback(vm);
+  }
+}
+
 function patchShadowRoot(vm, newCh) {
   const {
     children: oldCh
@@ -6762,5 +7057,5 @@ function readonly(obj) {
   return reactiveMembrane.getReadOnlyProxy(obj);
 }
 
-export { LightningElement, profilerControl as __unstable__ProfilerControl, api$1 as api, connectRootElement, createContextProvider, createVM, disconnectRootElement, getAssociatedVMIfPresent, getComponentDef, getComponentInternalDef, getUpgradableConstructor, isComponentConstructor, readonly, register, registerComponent, registerDecorators, registerTemplate, sanitizeAttribute, swapComponent, swapStyle, swapTemplate, track, unwrap, wire };
-/* version: 2.5.1 */
+export { LightningElement, profilerControl as __unstable__ProfilerControl, api$1 as api, connectRootElement, createContextProvider, createVM, disconnectRootElement, getAssociatedVMIfPresent, getComponentDef, getComponentInternalDef, getUpgradableConstructor, hydrateRootElement, isComponentConstructor, readonly, register, registerComponent, registerDecorators, registerTemplate, sanitizeAttribute, swapComponent, swapStyle, swapTemplate, track, unwrap, wire };
+/* version: 2.5.2-canary1 */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lwc/engine-core",
-    "version": "2.5.1",
+    "version": "2.5.2-canary1",
     "description": "Core LWC engine APIs.",
     "homepage": "https://lwc.dev/",
     "repository": {
@@ -24,8 +24,8 @@
         "types/"
     ],
     "dependencies": {
-        "@lwc/features": "2.5.1",
-        "@lwc/shared": "2.5.1"
+        "@lwc/features": "2.5.2-canary1",
+        "@lwc/shared": "2.5.2-canary1"
     },
     "devDependencies": {
         "observable-membrane": "1.0.1"
@@ -33,5 +33,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "443fa2e0a54c8940814292aac84d40e7eb69b22f"
+    "gitHead": "9704f323be88e79bbffb964e4805e6cbf18556ec"
 }

package/types/3rdparty/snabbdom/types.d.ts

@@ -70,6 +70,7 @@ export interface Hooks<N extends VNode> {
     move: (vNode: N, parentNode: Node, referenceNode: Node | null) => void;
     update: (oldVNode: N, vNode: N) => void;
     remove: (vNode: N, parentNode: Node) => void;
+    hydrate: (vNode: N, node: Node) => void;
 }
 export interface Module<N extends VNode> {
     create?: (vNode: N) => void;

package/types/framework/hooks.d.ts

@@ -1,9 +1,11 @@
 import { VM } from './vm';
 import { VNode, VCustomElement, VElement, VNodes } from '../3rdparty/snabbdom/types';
+export declare function hydrateNodeHook(vNode: VNode, node: Node): void;
 export declare function updateNodeHook(oldVnode: VNode, vnode: VNode): void;
 export declare function insertNodeHook(vnode: VNode, parentNode: Node, referenceNode: Node | null): void;
 export declare function removeNodeHook(vnode: VNode, parentNode: Node): void;
 export declare function createElmHook(vnode: VElement): void;
+export declare function hydrateElmHook(vnode: VElement): void;
 export declare function fallbackElmHook(elm: Element, vnode: VElement): void;
 export declare function updateElmHook(oldVnode: VElement, vnode: VElement): void;
 export declare function updateChildrenHook(oldVnode: VElement, vnode: VElement): void;
@@ -11,6 +13,7 @@ export declare function allocateChildrenHook(vnode: VCustomElement, vm: VM): voi
 export declare function createViewModelHook(elm: HTMLElement, vnode: VCustomElement): void;
 export declare function createCustomElmHook(vnode: VCustomElement): void;
 export declare function createChildrenHook(vnode: VElement): void;
+export declare function hydrateChildrenHook(elmChildren: NodeListOf<ChildNode>, children: VNodes, vm?: VM): void;
 export declare function updateCustomElmHook(oldVnode: VCustomElement, vnode: VCustomElement): void;
 export declare function removeElmHook(vnode: VElement): void;
 export declare function markAsDynamicChildren(children: VNodes): void;

package/types/framework/main.d.ts

@@ -7,7 +7,7 @@ export { default as wire } from './decorators/wire';
 export { readonly } from './readonly';
 export { setFeatureFlag, setFeatureFlagForTest } from '@lwc/features';
 export { getComponentInternalDef } from './def';
-export { createVM, connectRootElement, disconnectRootElement, getAssociatedVMIfPresent, } from './vm';
+export { createVM, connectRootElement, disconnectRootElement, getAssociatedVMIfPresent, hydrateRootElement, } from './vm';
 export { registerComponent } from './component';
 export { registerTemplate } from './secure-template';
 export { registerDecorators } from './decorators/register';

package/types/framework/renderer.d.ts

@@ -2,6 +2,7 @@ export declare type HostNode = any;
 export declare type HostElement = any;
 export interface Renderer<N = HostNode, E = HostElement> {
     ssr: boolean;
+    readonly isHydrating: boolean;
     isNativeShadowDefined: boolean;
     isSyntheticShadowDefined: boolean;
     insert(node: N, parent: E, anchor: N | null): void;

package/types/framework/vm.d.ts

@@ -118,8 +118,10 @@ export interface VM<N = HostNode, E = HostElement> {
 declare type VMAssociable = HostNode | LightningElement;
 export declare function rerenderVM(vm: VM): void;
 export declare function connectRootElement(elm: any): void;
+export declare function hydrateRootElement(elm: any): void;
 export declare function disconnectRootElement(elm: any): void;
 export declare function appendVM(vm: VM): void;
+export declare function hydrateVM(vm: VM): void;
 export declare function removeVM(vm: VM): void;
 export declare function createVM<HostNode, HostElement>(elm: HostElement, def: ComponentDef, options: {
     mode: ShadowRootMode;