@lwc/engine-core 4.0.0-alpha.0 → 4.0.0

package/dist/index.cjs.js

@@ -6,7 +6,6 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var shared = require('@lwc/shared');
-var ariaReflection = require('@lwc/aria-reflection');
 var features = require('@lwc/features');
 
 /*
@@ -392,20 +391,6 @@ function flattenStylesheets(stylesheets) {
     }
     return list;
 }
-// Set a ref (lwc:ref) on a VM, from a template API
-function setRefVNode(vm, ref, vnode) {
-    if (process.env.NODE_ENV !== 'production' && shared.isUndefined(vm.refVNodes)) {
-        throw new Error('refVNodes must be defined when setting a ref');
-    }
-    // If this method is called, then vm.refVNodes is set as the template has refs.
-    // If not, then something went wrong and we threw an error above.
-    const refVNodes = vm.refVNodes;
-    // In cases of conflict (two elements with the same ref), prefer, the last one,
-    // in depth-first traversal order.
-    if (!(ref in refVNodes) || refVNodes[ref].key < vnode.key) {
-        refVNodes[ref] = vnode;
-    }
-}
 // Throw an error if we're running in prod mode. Ensures code is truly removed from prod mode.
 function assertNotProd() {
     /* istanbul ignore if */
@@ -433,6 +418,45 @@ var _a, _b;
 const instrumentDef = (_a = shared.globalThis.__lwc_instrument_cmp_def) !== null && _a !== void 0 ? _a : shared.noop;
 const instrumentInstance = (_b = shared.globalThis.__lwc_instrument_cmp_instance) !== null && _b !== void 0 ? _b : shared.noop;
 
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+// Apply ARIA string reflection behavior to a prototype.
+// This is deliberately kept separate from @lwc/aria-reflection. @lwc/aria-reflection is a global polyfill that is
+// needed for backwards compatibility in LEX, whereas `applyAriaReflection` is designed to only apply to our own
+// LightningElement/BaseBridgeElement prototypes.
+function applyAriaReflection(prototype) {
+    for (const propName of shared.keys(shared.AriaPropNameToAttrNameMap)) {
+        const attrName = shared.AriaPropNameToAttrNameMap[propName];
+        if (shared.isUndefined(shared.getOwnPropertyDescriptor(prototype, propName))) {
+            // Note that we need to call this.{get,set,has,remove}Attribute rather than dereferencing
+            // from Element.prototype, because these methods are overridden in LightningElement.
+            shared.defineProperty(prototype, propName, {
+                get() {
+                    return this.getAttribute(attrName);
+                },
+                set(newValue) {
+                    // TODO [#3284]: there is disagreement between browsers and the spec on how to treat undefined
+                    // Our historical behavior is to only treat null as removing the attribute
+                    // See also https://github.com/w3c/aria/issues/1858
+                    if (shared.isNull(newValue)) {
+                        this.removeAttribute(attrName);
+                    }
+                    else {
+                        this.setAttribute(attrName, newValue);
+                    }
+                },
+                // configurable and enumerable to allow it to be overridden – this mimics Safari's/Chrome's behavior
+                configurable: true,
+                enumerable: true,
+            });
+        }
+    }
+}
+
 /*
  * Copyright (c) 2018, salesforce.com, inc.
  * All rights reserved.
@@ -523,8 +547,8 @@ function lockDomMutation() {
     assertNotProd(); // this method should never leak to prod
     isDomMutationAllowed = false;
 }
-function logMissingPortalError(name, type) {
-    return logError(`The \`${name}\` ${type} is available only on elements that use the \`lwc:dom="manual"\` directive.`);
+function logMissingPortalWarn(name, type) {
+    return logWarn(`The \`${name}\` ${type} is available only on elements that use the \`lwc:dom="manual"\` directive.`);
 }
 function patchElementWithRestrictions(elm, options) {
     assertNotProd(); // this method should never leak to prod
@@ -549,14 +573,14 @@ function patchElementWithRestrictions(elm, options) {
         shared.assign(descriptors, {
             appendChild: generateDataDescriptor({
                 value(aChild) {
-                    logMissingPortalError('appendChild', 'method');
+                    logMissingPortalWarn('appendChild', 'method');
                     return appendChild.call(this, aChild);
                 },
             }),
             insertBefore: generateDataDescriptor({
                 value(newNode, referenceNode) {
                     if (!isDomMutationAllowed) {
-                        logMissingPortalError('insertBefore', 'method');
+                        logMissingPortalWarn('insertBefore', 'method');
                     }
                     return insertBefore.call(this, newNode, referenceNode);
                 },
@@ -564,14 +588,14 @@ function patchElementWithRestrictions(elm, options) {
             removeChild: generateDataDescriptor({
                 value(aChild) {
                     if (!isDomMutationAllowed) {
-                        logMissingPortalError('removeChild', 'method');
+                        logMissingPortalWarn('removeChild', 'method');
                     }
                     return removeChild.call(this, aChild);
                 },
             }),
             replaceChild: generateDataDescriptor({
                 value(newChild, oldChild) {
-                    logMissingPortalError('replaceChild', 'method');
+                    logMissingPortalWarn('replaceChild', 'method');
                     return replaceChild.call(this, newChild, oldChild);
                 },
             }),
@@ -581,7 +605,7 @@ function patchElementWithRestrictions(elm, options) {
                 },
                 set(value) {
                     if (!isDomMutationAllowed) {
-                        logMissingPortalError('nodeValue', 'property');
+                        logMissingPortalWarn('nodeValue', 'property');
                     }
                     originalNodeValueDescriptor.set.call(this, value);
                 },
@@ -591,7 +615,7 @@ function patchElementWithRestrictions(elm, options) {
                     return originalTextContentDescriptor.get.call(this);
                 },
                 set(value) {
-                    logMissingPortalError('textContent', 'property');
+                    logMissingPortalWarn('textContent', 'property');
                     originalTextContentDescriptor.set.call(this, value);
                 },
             }),
@@ -600,7 +624,7 @@ function patchElementWithRestrictions(elm, options) {
                     return originalInnerHTMLDescriptor.get.call(this);
                 },
                 set(value) {
-                    logMissingPortalError('innerHTML', 'property');
+                    logMissingPortalWarn('innerHTML', 'property');
                     return originalInnerHTMLDescriptor.set.call(this, value);
                 },
             }),
@@ -1458,6 +1482,79 @@ function warnIfInvokedDuringConstruction(vm, methodOrPropName) {
         logError(`this.${methodOrPropName} should not be called during the construction of the custom element for ${getComponentTag(vm)} because the element is not yet in the DOM or has no children yet.`);
     }
 }
+// List of properties on ElementInternals that are formAssociated can be found in the spec:
+// https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements
+const formAssociatedProps = new Set([
+    'setFormValue',
+    'form',
+    'setValidity',
+    'willValidate',
+    'validity',
+    'validationMessage',
+    'checkValidity',
+    'reportValidity',
+    'labels',
+]);
+// Verify that access to a form-associated property of the ElementInternals proxy has formAssociated set in the LWC.
+function verifyPropForFormAssociation(propertyKey, isFormAssociated) {
+    if (shared.isString(propertyKey) && formAssociatedProps.has(propertyKey) && !isFormAssociated) {
+        //Note this error message mirrors Chrome and Firefox error messages, in Safari the error is slightly different.
+        throw new DOMException(`Failed to execute '${propertyKey}' on 'ElementInternals': The target element is not a form-associated custom element.`);
+    }
+}
+const elementInternalsAccessorAllowList = new Set(['shadowRoot', 'role', ...formAssociatedProps]);
+// Prevent access to properties not defined in the HTML spec in case browsers decide to
+// provide new APIs that provide access to form associated properties.
+// This can be removed along with UpgradeableConstructor.
+function isAllowedElementInternalAccessor(propertyKey) {
+    let isAllowedAccessor = false;
+    // As of this writing all ElementInternal property keys as described in the spec are implemented with strings
+    // in Chrome, Firefox, and Safari
+    if (shared.isString(propertyKey)) {
+        // Allow list is based on HTML spec:
+        // https://html.spec.whatwg.org/multipage/custom-elements.html#the-elementinternals-interface
+        isAllowedAccessor =
+            elementInternalsAccessorAllowList.has(propertyKey) || /^aria/.test(propertyKey);
+        if (!isAllowedAccessor && process.env.NODE_ENV !== 'production') {
+            logWarn('Only properties defined in the ElementInternals HTML spec are available.');
+        }
+    }
+    return isAllowedAccessor;
+}
+// Wrap all ElementInternal objects in a proxy to prevent form association when `formAssociated` is not set on an LWC.
+// This is needed because the 1UpgradeableConstructor1 always sets `formAssociated=true`, which means all
+// ElementInternal objects will have form-associated properties set when an LWC is placed in a form.
+// We are doing this to guard against customers taking a dependency on form elements being associated to ElementInternals
+// when 'formAssociated' has not been set on the LWC.
+function createElementInternalsProxy(elementInternals, isFormAssociated) {
+    const elementInternalsProxy = new Proxy(elementInternals, {
+        set(target, propertyKey, newValue) {
+            if (isAllowedElementInternalAccessor(propertyKey)) {
+                // Verify that formAssociated is set for form associated properties
+                verifyPropForFormAssociation(propertyKey, isFormAssociated);
+                return Reflect.set(target, propertyKey, newValue);
+            }
+            // As of this writing ElementInternals do not have non-string properties that can be set.
+            return false;
+        },
+        get(target, propertyKey) {
+            if (
+            // Pass through Object.prototype methods such as toString()
+            shared.hasOwnProperty.call(Object.prototype, propertyKey) ||
+                // As of this writing, ElementInternals only uses Symbol.toStringTag which is called
+                // on Object.hasOwnProperty invocations
+                Symbol.for('Symbol.toStringTag') === propertyKey ||
+                // ElementInternals allow listed properties
+                isAllowedElementInternalAccessor(propertyKey)) {
+                // Verify that formAssociated is set for form associated properties
+                verifyPropForFormAssociation(propertyKey, isFormAssociated);
+                const propertyValue = Reflect.get(target, propertyKey);
+                return shared.isFunction(propertyValue) ? propertyValue.bind(target) : propertyValue;
+            }
+        },
+    });
+    return elementInternalsProxy;
+}
 // @ts-ignore
 LightningElement.prototype = {
     constructor: LightningElement,
@@ -1549,6 +1646,16 @@ LightningElement.prototype = {
         }
         return getBoundingClientRect(elm);
     },
+    attachInternals() {
+        const vm = getAssociatedVM(this);
+        const { elm, def: { formAssociated }, renderer: { attachInternals }, } = vm;
+        if (vm.shadowMode === 1 /* ShadowMode.Synthetic */) {
+            throw new Error('attachInternals API is not supported in light DOM or synthetic shadow.');
+        }
+        const internals = attachInternals(elm);
+        // #TODO[2970]: remove proxy once `UpgradeableConstructor` has been removed
+        return createElementInternalsProxy(internals, Boolean(formAssociated));
+    },
     get isConnected() {
         const vm = getAssociatedVM(this);
         const { elm, renderer: { isConnected }, } = vm;
@@ -1737,7 +1844,7 @@ shared.defineProperties(LightningElement.prototype, lightningBasedDescriptors);
 // Apply ARIA reflection to LightningElement.prototype, on both the browser and server.
 // This allows `this.aria*` property accessors to work from inside a component, and to reflect `aria-*` attrs.
 // Note this works regardless of whether the global ARIA reflection polyfill is applied or not.
-ariaReflection.applyAriaReflection(LightningElement.prototype);
+applyAriaReflection(LightningElement.prototype);
 shared.defineProperty(LightningElement, 'CustomElementConstructor', {
     get() {
         // If required, a runtime-specific implementation must be defined.
@@ -2549,7 +2656,22 @@ function createAttributeChangedCallback(attributeToPropMap, superAttributeChange
         this[propName] = newValue;
     };
 }
-function HTMLBridgeElementFactory(SuperClass, props, methods) {
+function createAccessorThatWarns(propName) {
+    let prop;
+    return {
+        get() {
+            logWarn(`The property "${propName}" is not publicly accessible. Add the @api annotation to the property declaration or getter/setter in the component to make it accessible.`);
+            return prop;
+        },
+        set(value) {
+            logWarn(`The property "${propName}" is not publicly accessible. Add the @api annotation to the property declaration or getter/setter in the component to make it accessible.`);
+            prop = value;
+        },
+        enumerable: true,
+        configurable: true,
+    };
+}
+function HTMLBridgeElementFactory(SuperClass, publicProperties, methods, observedFields, proto, hasCustomSuperClass) {
     const HTMLBridgeElement = class extends SuperClass {
     };
     // generating the hash table for attributes to avoid duplicate fields and facilitate validation
@@ -2558,9 +2680,31 @@ function HTMLBridgeElementFactory(SuperClass, props, methods) {
     const { attributeChangedCallback: superAttributeChangedCallback } = SuperClass.prototype;
     const { observedAttributes: superObservedAttributes = [] } = SuperClass;
     const descriptors = shared.create(null);
+    // present a hint message so that developers are aware that they have not decorated property with @api
+    if (process.env.NODE_ENV !== 'production') {
+        // TODO [#3761]: enable for components that don't extend from LightningElement
+        if (!shared.isUndefined(proto) && !shared.isNull(proto) && !hasCustomSuperClass) {
+            const nonPublicPropertiesToWarnOn = new Set([
+                // getters, setters, and methods
+                ...shared.keys(shared.getOwnPropertyDescriptors(proto)),
+                // class properties
+                ...observedFields,
+            ]
+                // we don't want to override HTMLElement props because these are meaningful in other ways,
+                // and can break tooling that expects it to be iterable or defined, e.g. Jest:
+                // https://github.com/jestjs/jest/blob/b4c9587/packages/pretty-format/src/plugins/DOMElement.ts#L95
+                // It also doesn't make sense to override e.g. "constructor".
+                .filter((propName) => !(propName in HTMLElementPrototype)));
+            for (const propName of nonPublicPropertiesToWarnOn) {
+                if (shared.ArrayIndexOf.call(publicProperties, propName) === -1) {
+                    descriptors[propName] = createAccessorThatWarns(propName);
+                }
+            }
+        }
+    }
     // expose getters and setters for each public props on the new Element Bridge
-    for (let i = 0, len = props.length; i < len; i += 1) {
-        const propName = props[i];
+    for (let i = 0, len = publicProperties.length; i < len; i += 1) {
+        const propName = publicProperties[i];
         attributeToPropMap[shared.htmlPropertyToAttribute(propName)] = propName;
         descriptors[propName] = {
             get: createGetter(propName),
@@ -2585,6 +2729,31 @@ function HTMLBridgeElementFactory(SuperClass, props, methods) {
     descriptors.attributeChangedCallback = {
         value: createAttributeChangedCallback(attributeToPropMap, superAttributeChangedCallback),
     };
+    // To avoid leaking private component details, accessing internals from outside a component is not allowed.
+    descriptors.attachInternals = {
+        set() {
+            if (process.env.NODE_ENV !== 'production') {
+                logWarn('attachInternals cannot be accessed outside of a component. Use this.attachInternals instead.');
+            }
+        },
+        get() {
+            if (process.env.NODE_ENV !== 'production') {
+                logWarn('attachInternals cannot be accessed outside of a component. Use this.attachInternals instead.');
+            }
+        },
+    };
+    descriptors.formAssociated = {
+        set() {
+            if (process.env.NODE_ENV !== 'production') {
+                logWarn('formAssociated cannot be accessed outside of a component. Set the value within the component class.');
+            }
+        },
+        get() {
+            if (process.env.NODE_ENV !== 'production') {
+                logWarn('formAssociated cannot be accessed outside of a component. Set the value within the component class.');
+            }
+        },
+    };
     // Specify attributes for which we want to reflect changes back to their corresponding
     // properties via attributeChangedCallback.
     shared.defineProperty(HTMLBridgeElement, 'observedAttributes', {
@@ -2595,7 +2764,7 @@ function HTMLBridgeElementFactory(SuperClass, props, methods) {
     shared.defineProperties(HTMLBridgeElement.prototype, descriptors);
     return HTMLBridgeElement;
 }
-const BaseBridgeElement = HTMLBridgeElementFactory(HTMLElementConstructor, shared.getOwnPropertyNames(HTMLElementOriginalDescriptors), []);
+const BaseBridgeElement = HTMLBridgeElementFactory(HTMLElementConstructor, shared.getOwnPropertyNames(HTMLElementOriginalDescriptors), [], [], null, false);
 if (process.env.IS_BROWSER) {
     // This ARIA reflection only really makes sense in the browser. On the server, there is no `renderedCallback()`,
     // so you cannot do e.g. `this.template.querySelector('x-child').ariaBusy = 'true'`. So we don't need to expose
@@ -2608,7 +2777,7 @@ if (process.env.IS_BROWSER) {
     //
     // Also note that we apply this to BaseBridgeElement.prototype to avoid excessively redefining property
     // accessors inside the HTMLBridgeElementFactory.
-    ariaReflection.applyAriaReflection(BaseBridgeElement.prototype);
+    applyAriaReflection(BaseBridgeElement.prototype);
 }
 shared.freeze(BaseBridgeElement);
 shared.seal(BaseBridgeElement.prototype);
@@ -2893,7 +3062,7 @@ function getCtorProto(Ctor) {
     return proto;
 }
 function createComponentDef(Ctor) {
-    const { shadowSupportMode: ctorShadowSupportMode, renderMode: ctorRenderMode } = Ctor;
+    const { shadowSupportMode: ctorShadowSupportMode, renderMode: ctorRenderMode, formAssociated: ctorFormAssociated, } = Ctor;
     if (process.env.NODE_ENV !== 'production') {
         const ctorName = Ctor.name;
         // Removing the following assert until https://bugs.webkit.org/show_bug.cgi?id=190140 is fixed.
@@ -2905,7 +3074,8 @@ function createComponentDef(Ctor) {
         }
         if (!shared.isUndefined(ctorShadowSupportMode) &&
             ctorShadowSupportMode !== "any" /* ShadowSupportMode.Any */ &&
-            ctorShadowSupportMode !== "reset" /* ShadowSupportMode.Default */) {
+            ctorShadowSupportMode !== "reset" /* ShadowSupportMode.Default */ &&
+            ctorShadowSupportMode !== "native" /* ShadowSupportMode.Native */) {
             logError(`Invalid value for static property shadowSupportMode: '${ctorShadowSupportMode}'`);
         }
         if (!shared.isUndefined(ctorRenderMode) &&
@@ -2917,10 +3087,11 @@ function createComponentDef(Ctor) {
     const decoratorsMeta = getDecoratorsMeta(Ctor);
     const { apiFields, apiFieldsConfig, apiMethods, wiredFields, wiredMethods, observedFields } = decoratorsMeta;
     const proto = Ctor.prototype;
-    let { connectedCallback, disconnectedCallback, renderedCallback, errorCallback, render } = proto;
+    let { connectedCallback, disconnectedCallback, renderedCallback, errorCallback, formAssociatedCallback, formResetCallback, formDisabledCallback, formStateRestoreCallback, render, } = proto;
     const superProto = getCtorProto(Ctor);
-    const superDef = superProto !== LightningElement ? getComponentInternalDef(superProto) : lightingElementDef;
-    const bridge = HTMLBridgeElementFactory(superDef.bridge, shared.keys(apiFields), shared.keys(apiMethods));
+    const hasCustomSuperClass = superProto !== LightningElement;
+    const superDef = hasCustomSuperClass ? getComponentInternalDef(superProto) : lightingElementDef;
+    const bridge = HTMLBridgeElementFactory(superDef.bridge, shared.keys(apiFields), shared.keys(apiMethods), shared.keys(observedFields), proto, hasCustomSuperClass);
     const props = shared.assign(shared.create(null), superDef.props, apiFields);
     const propsConfig = shared.assign(shared.create(null), superDef.propsConfig, apiFieldsConfig);
     const methods = shared.assign(shared.create(null), superDef.methods, apiMethods);
@@ -2929,6 +3100,10 @@ function createComponentDef(Ctor) {
     disconnectedCallback = disconnectedCallback || superDef.disconnectedCallback;
     renderedCallback = renderedCallback || superDef.renderedCallback;
     errorCallback = errorCallback || superDef.errorCallback;
+    formAssociatedCallback = formAssociatedCallback || superDef.formAssociatedCallback;
+    formResetCallback = formResetCallback || superDef.formResetCallback;
+    formDisabledCallback = formDisabledCallback || superDef.formDisabledCallback;
+    formStateRestoreCallback = formStateRestoreCallback || superDef.formStateRestoreCallback;
     render = render || superDef.render;
     let shadowSupportMode = superDef.shadowSupportMode;
     if (!shared.isUndefined(ctorShadowSupportMode)) {
@@ -2938,6 +3113,10 @@ function createComponentDef(Ctor) {
     if (!shared.isUndefined(ctorRenderMode)) {
         renderMode = ctorRenderMode === 'light' ? 0 /* RenderMode.Light */ : 1 /* RenderMode.Shadow */;
     }
+    let formAssociated = superDef.formAssociated;
+    if (!shared.isUndefined(ctorFormAssociated)) {
+        formAssociated = ctorFormAssociated;
+    }
     const template = getComponentRegisteredTemplate(Ctor) || superDef.template;
     const name = Ctor.name || superDef.name;
     // installing observed fields into the prototype.
@@ -2953,10 +3132,15 @@ function createComponentDef(Ctor) {
         template,
         renderMode,
         shadowSupportMode,
+        formAssociated,
         connectedCallback,
         disconnectedCallback,
-        renderedCallback,
         errorCallback,
+        formAssociatedCallback,
+        formDisabledCallback,
+        formResetCallback,
+        formStateRestoreCallback,
+        renderedCallback,
         render,
     };
     // This is a no-op unless Lightning DevTools are enabled.
@@ -3033,6 +3217,7 @@ const lightingElementDef = {
     methods: EmptyObject,
     renderMode: 1 /* RenderMode.Shadow */,
     shadowSupportMode: "reset" /* ShadowSupportMode.Default */,
+    formAssociated: undefined,
     wire: EmptyObject,
     bridge: BaseBridgeElement,
     template: defaultEmptyTemplate,
@@ -3089,9 +3274,11 @@ function createInlineStyleVNode(content) {
         },
     }, [api.t(content)]);
 }
-function updateStylesheetToken(vm, template) {
+// TODO [#3733]: remove support for legacy scope tokens
+function updateStylesheetToken(vm, template, legacy) {
     const { elm, context, renderMode, shadowMode, renderer: { getClassList, removeAttribute, setAttribute }, } = vm;
-    const { stylesheets: newStylesheets, stylesheetToken: newStylesheetToken } = template;
+    const { stylesheets: newStylesheets } = template;
+    const newStylesheetToken = legacy ? template.legacyStylesheetToken : template.stylesheetToken;
     const { stylesheets: newVmStylesheets } = vm;
     const isSyntheticShadow = renderMode === 1 /* RenderMode.Shadow */ && shadowMode === 1 /* ShadowMode.Synthetic */;
     const { hasScopedStyles } = context;
@@ -3099,7 +3286,19 @@ function updateStylesheetToken(vm, template) {
     let newHasTokenInClass;
     let newHasTokenInAttribute;
     // Reset the styling token applied to the host element.
-    const { stylesheetToken: oldToken, hasTokenInClass: oldHasTokenInClass, hasTokenInAttribute: oldHasTokenInAttribute, } = context;
+    let oldToken;
+    let oldHasTokenInClass;
+    let oldHasTokenInAttribute;
+    if (legacy) {
+        oldToken = context.legacyStylesheetToken;
+        oldHasTokenInClass = context.hasLegacyTokenInClass;
+        oldHasTokenInAttribute = context.hasLegacyTokenInAttribute;
+    }
+    else {
+        oldToken = context.stylesheetToken;
+        oldHasTokenInClass = context.hasTokenInClass;
+        oldHasTokenInAttribute = context.hasTokenInAttribute;
+    }
     if (!shared.isUndefined(oldToken)) {
         if (oldHasTokenInClass) {
             getClassList(elm).remove(makeHostToken(oldToken));
@@ -3127,9 +3326,16 @@ function updateStylesheetToken(vm, template) {
         }
     }
     // Update the styling tokens present on the context object.
-    context.stylesheetToken = newToken;
-    context.hasTokenInClass = newHasTokenInClass;
-    context.hasTokenInAttribute = newHasTokenInAttribute;
+    if (legacy) {
+        context.legacyStylesheetToken = newToken;
+        context.hasLegacyTokenInClass = newHasTokenInClass;
+        context.hasLegacyTokenInAttribute = newHasTokenInAttribute;
+    }
+    else {
+        context.stylesheetToken = newToken;
+        context.hasTokenInClass = newHasTokenInClass;
+        context.hasTokenInAttribute = newHasTokenInAttribute;
+    }
 }
 function evaluateStylesheetsContent(stylesheets, stylesheetToken, vm) {
     const content = [];
@@ -3217,9 +3423,12 @@ function getNearestShadowComponent(vm) {
  * this returns the unique token for that scoped stylesheet. Otherwise
  * it returns null.
  */
-function getScopeTokenClass(owner) {
+// TODO [#3733]: remove support for legacy scope tokens
+function getScopeTokenClass(owner, legacy) {
     const { cmpTemplate, context } = owner;
-    return (context.hasScopedStyles && (cmpTemplate === null || cmpTemplate === void 0 ? void 0 : cmpTemplate.stylesheetToken)) || null;
+    return ((context.hasScopedStyles &&
+        (legacy ? cmpTemplate === null || cmpTemplate === void 0 ? void 0 : cmpTemplate.legacyStylesheetToken : cmpTemplate === null || cmpTemplate === void 0 ? void 0 : cmpTemplate.stylesheetToken)) ||
+        null);
 }
 /**
  * This function returns the host style token for a custom element if it
@@ -3353,28 +3562,20 @@ function isLiveBindingProp(sel, key) {
     return sel === 'input' && (key === 'value' || key === 'checked');
 }
 function patchProps(oldVnode, vnode, renderer) {
-    let { props } = vnode.data;
-    const { spread } = vnode.data;
-    if (shared.isUndefined(props) && shared.isUndefined(spread)) {
+    const { props } = vnode.data;
+    if (shared.isUndefined(props)) {
         return;
     }
     let oldProps;
     if (!shared.isNull(oldVnode)) {
         oldProps = oldVnode.data.props;
-        const oldSpread = oldVnode.data.spread;
         // Props may be the same due to the static content optimization, so we can skip diffing
-        if (oldProps === props && oldSpread === spread) {
+        if (oldProps === props) {
             return;
         }
         if (shared.isUndefined(oldProps)) {
             oldProps = EmptyObject;
         }
-        if (!shared.isUndefined(oldSpread)) {
-            oldProps = shared.assign({}, oldProps, oldSpread);
-        }
-    }
-    if (!shared.isUndefined(spread)) {
-        props = shared.assign({}, props, spread);
     }
     const isFirstPatch = shared.isNull(oldVnode);
     const { elm, sel } = vnode;
@@ -3548,6 +3749,113 @@ function applyStaticStyleAttribute(vnode, renderer) {
     }
 }
 
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+// Set a ref (lwc:ref) on a VM, from a template API
+function applyRefs(vnode, owner) {
+    const { data } = vnode;
+    const { ref } = data;
+    if (shared.isUndefined(ref)) {
+        return;
+    }
+    if (process.env.NODE_ENV !== 'production' && shared.isUndefined(owner.refVNodes)) {
+        throw new Error('refVNodes must be defined when setting a ref');
+    }
+    // If this method is called, then vm.refVNodes is set as the template has refs.
+    // If not, then something went wrong and we threw an error above.
+    const refVNodes = owner.refVNodes;
+    // In cases of conflict (two elements with the same ref), prefer the last one,
+    // in depth-first traversal order. This happens automatically due to how we render
+    refVNodes[ref] = vnode;
+}
+
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+function traverseAndSetElements(root, parts, renderer) {
+    const numParts = parts.length;
+    // Optimization given that, in most cases, there will be one part, and it's just the root
+    if (numParts === 1) {
+        const firstPart = parts[0];
+        if (firstPart.partId === 0) {
+            // 0 means the root node
+            firstPart.elm = root;
+            return;
+        }
+    }
+    const partIdsToParts = new Map();
+    for (const staticPart of parts) {
+        partIdsToParts.set(staticPart.partId, staticPart);
+    }
+    let numFoundParts = 0;
+    const { previousSibling, getLastChild } = renderer;
+    const stack = [root];
+    let partId = -1;
+    // Depth-first traversal. We assign a partId to each element, which is an integer based on traversal order.
+    while (stack.length > 0) {
+        const elm = shared.ArrayShift.call(stack);
+        partId++;
+        const part = partIdsToParts.get(partId);
+        if (!shared.isUndefined(part)) {
+            part.elm = elm;
+            if (++numFoundParts === numParts) {
+                return; // perf optimization - stop traversing once we've found everything we need
+            }
+        }
+        // For depth-first traversal, prepend to the stack in reverse order
+        // Note that we traverse using `*Child`/`*Sibling` rather than `children` because the browser uses a linked
+        // list under the hood to represent the DOM tree, so it's faster to do this than to create an underlying array
+        // by calling `children`.
+        let child = getLastChild(elm);
+        while (!shared.isNull(child)) {
+            shared.ArrayUnshift.call(stack, child);
+            child = previousSibling(child);
+        }
+    }
+    if (process.env.NODE_ENV !== 'production') {
+        shared.assert.isTrue(numFoundParts === numParts, `Should have found all parts by now. Found ${numFoundParts}, needed ${numParts}.`);
+    }
+}
+/**
+ * Given an array of static parts, do all the mounting required for these parts.
+ *
+ * @param root - the root element
+ * @param vnode - the parent VStatic
+ * @param renderer - the renderer to use
+ * @param mount - true this is a first (mount) render as opposed to a subsequent (patch) render
+ */
+function applyStaticParts(root, vnode, renderer, mount) {
+    // On the server, we don't support ref (because it relies on renderedCallback), nor do we
+    // support event listeners (no interactivity), so traversing parts makes no sense
+    if (!process.env.IS_BROWSER) {
+        return;
+    }
+    const { parts, owner } = vnode;
+    if (shared.isUndefined(parts)) {
+        return;
+    }
+    // This adds `part.elm` to each `part`. We have to do this on every mount/patch because the `parts`
+    // array is recreated from scratch every time, so each `part.elm` is now undefined.
+    // TODO [#3800]: avoid calling traverseAndSetElements on every re-render
+    traverseAndSetElements(root, parts, renderer);
+    // Currently only event listeners and refs are supported for static vnodes
+    for (const part of parts) {
+        if (mount) {
+            // Event listeners only need to be applied once when mounting
+            applyEventListeners(part, renderer);
+        }
+        // Refs must be updated after every render due to refVNodes getting reset before every render
+        applyRefs(part, owner);
+    }
+}
+
 /*
  * Copyright (c) 2018, salesforce.com, inc.
  * All rights reserved.
@@ -3590,7 +3898,7 @@ function patch(n1, n2, parent, renderer) {
             patchComment(n1, n2, renderer);
             break;
         case 4 /* VNodeType.Static */:
-            n2.elm = n1.elm;
+            patchStatic(n1, n2, renderer);
             break;
         case 5 /* VNodeType.Fragment */:
             patchFragment(n1, n2, parent, renderer);
@@ -3684,13 +3992,18 @@ function mountElement(vnode, parent, anchor, renderer) {
     applyStyleScoping(elm, owner, renderer);
     applyDomManual(elm, vnode);
     applyElementRestrictions(elm, vnode);
-    patchElementPropsAndAttrs$1(null, vnode, renderer);
+    patchElementPropsAndAttrsAndRefs$1(null, vnode, renderer);
     insertNode(elm, parent, anchor, renderer);
     mountVNodes(vnode.children, elm, renderer, null);
 }
+function patchStatic(n1, n2, renderer) {
+    const elm = (n2.elm = n1.elm);
+    // The `refs` object is blown away in every re-render, so we always need to re-apply them
+    applyStaticParts(elm, n2, renderer, false);
+}
 function patchElement(n1, n2, renderer) {
     const elm = (n2.elm = n1.elm);
-    patchElementPropsAndAttrs$1(n1, n2, renderer);
+    patchElementPropsAndAttrsAndRefs$1(n1, n2, renderer);
     patchChildren(n1.children, n2.children, elm, renderer);
 }
 function mountStatic(vnode, parent, anchor, renderer) {
@@ -3707,8 +4020,7 @@ function mountStatic(vnode, parent, anchor, renderer) {
         }
     }
     insertNode(elm, parent, anchor, renderer);
-    // Event listeners are only applied once when mounting, so they are allowed for static vnodes
-    applyEventListeners(vnode, renderer);
+    applyStaticParts(elm, vnode, renderer, true);
 }
 function mountCustomElement(vnode, parent, anchor, renderer) {
     const { sel, owner } = vnode;
@@ -3724,22 +4036,38 @@ function mountCustomElement(vnode, parent, anchor, renderer) {
         // the custom element from the registry is expecting an upgrade callback
         vm = createViewModelHook(elm, vnode, renderer);
     };
-    const connectedCallback = (elm) => {
-        if (shouldUseNativeCustomElementLifecycle(vm)) {
+    let connectedCallback;
+    let disconnectedCallback;
+    let formAssociatedCallback;
+    let formDisabledCallback;
+    let formResetCallback;
+    let formStateRestoreCallback;
+    if (lwcRuntimeFlags.ENABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE) {
+        connectedCallback = (elm) => {
             connectRootElement(elm);
-        }
-    };
-    const disconnectedCallback = (elm) => {
-        if (shouldUseNativeCustomElementLifecycle(vm)) {
+        };
+        disconnectedCallback = (elm) => {
             disconnectRootElement(elm);
-        }
-    };
+        };
+        formAssociatedCallback = (elm) => {
+            runFormAssociatedCallback(elm);
+        };
+        formDisabledCallback = (elm) => {
+            runFormDisabledCallback(elm);
+        };
+        formResetCallback = (elm) => {
+            runFormResetCallback(elm);
+        };
+        formStateRestoreCallback = (elm) => {
+            runFormStateRestoreCallback(elm);
+        };
+    }
     // Should never get a tag with upper case letter at this point; the compiler
     // should produce only tags with lowercase letters. However, the Java
     // compiler may generate tagnames with uppercase letters so - for backwards
     // compatibility, we lower case the tagname here.
     const normalizedTagname = sel.toLowerCase();
-    const elm = createCustomElement(normalizedTagname, upgradeCallback, connectedCallback, disconnectedCallback);
+    const elm = createCustomElement(normalizedTagname, upgradeCallback, connectedCallback, disconnectedCallback, formAssociatedCallback, formDisabledCallback, formResetCallback, formStateRestoreCallback);
     vnode.elm = elm;
     vnode.vm = vm;
     linkNodeToShadow(elm, owner, renderer);
@@ -3747,11 +4075,11 @@ function mountCustomElement(vnode, parent, anchor, renderer) {
     if (vm) {
         allocateChildren(vnode, vm);
     }
-    patchElementPropsAndAttrs$1(null, vnode, renderer);
+    patchElementPropsAndAttrsAndRefs$1(null, vnode, renderer);
     insertNode(elm, parent, anchor, renderer);
     if (vm) {
         if (process.env.IS_BROWSER) {
-            if (!shouldUseNativeCustomElementLifecycle(vm)) {
+            if (!lwcRuntimeFlags.ENABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE) {
                 if (process.env.NODE_ENV !== 'production') {
                     // With synthetic lifecycle callbacks, it's possible for elements to be removed without the engine
                     // noticing it (e.g. `appendChild` the same host element twice). This test ensures we don't regress.
@@ -3784,7 +4112,7 @@ function patchCustomElement(n1, n2, parent, renderer) {
         // Otherwise patch the existing component with new props/attrs/etc.
         const elm = (n2.elm = n1.elm);
         const vm = (n2.vm = n1.vm);
-        patchElementPropsAndAttrs$1(n1, n2, renderer);
+        patchElementPropsAndAttrsAndRefs$1(n1, n2, renderer);
         if (!shared.isUndefined(vm)) {
             // in fallback mode, the allocation will always set children to
             // empty and delegate the real allocation to the slot elements
@@ -3931,7 +4259,7 @@ function removeNode(node, parent, renderer) {
         lockDomMutation();
     }
 }
-function patchElementPropsAndAttrs$1(oldVnode, vnode, renderer) {
+function patchElementPropsAndAttrsAndRefs$1(oldVnode, vnode, renderer) {
     if (shared.isNull(oldVnode)) {
         applyEventListeners(vnode, renderer);
         applyStaticClassAttribute(vnode, renderer);
@@ -3943,20 +4271,39 @@ function patchElementPropsAndAttrs$1(oldVnode, vnode, renderer) {
     patchStyleAttribute(oldVnode, vnode, renderer);
     patchAttributes(oldVnode, vnode, renderer);
     patchProps(oldVnode, vnode, renderer);
+    // The `refs` object is blown away in every re-render, so we always need to re-apply them
+    applyRefs(vnode, vnode.owner);
 }
 function applyStyleScoping(elm, owner, renderer) {
+    const { getClassList } = renderer;
     // Set the class name for `*.scoped.css` style scoping.
-    const scopeToken = getScopeTokenClass(owner);
+    const scopeToken = getScopeTokenClass(owner, /* legacy */ false);
     if (!shared.isNull(scopeToken)) {
-        const { getClassList } = renderer;
         // TODO [#2762]: this dot notation with add is probably problematic
         // probably we should have a renderer api for just the add operation
         getClassList(elm).add(scopeToken);
     }
+    // TODO [#3733]: remove support for legacy scope tokens
+    if (lwcRuntimeFlags.ENABLE_LEGACY_SCOPE_TOKENS) {
+        const legacyScopeToken = getScopeTokenClass(owner, /* legacy */ true);
+        if (!shared.isNull(legacyScopeToken)) {
+            // TODO [#2762]: this dot notation with add is probably problematic
+            // probably we should have a renderer api for just the add operation
+            getClassList(elm).add(legacyScopeToken);
+        }
+    }
     // Set property element for synthetic shadow DOM style scoping.
     const { stylesheetToken: syntheticToken } = owner.context;
-    if (owner.shadowMode === 1 /* ShadowMode.Synthetic */ && !shared.isUndefined(syntheticToken)) {
-        elm.$shadowToken$ = syntheticToken;
+    if (owner.shadowMode === 1 /* ShadowMode.Synthetic */) {
+        if (!shared.isUndefined(syntheticToken)) {
+            elm.$shadowToken$ = syntheticToken;
+        }
+        if (lwcRuntimeFlags.ENABLE_LEGACY_SCOPE_TOKENS) {
+            const legacyToken = owner.context.legacyStylesheetToken;
+            if (!shared.isUndefined(legacyToken)) {
+                elm.$legacyShadowToken$ = legacyToken;
+            }
+        }
     }
 }
 function applyDomManual(elm, vnode) {
@@ -4316,14 +4663,6 @@ function updateStaticChildren(c1, c2, parent, renderer) {
         }
     }
 }
-function shouldUseNativeCustomElementLifecycle(vm) {
-    if (lwcRuntimeFlags.DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE) {
-        // temporary "kill switch"
-        return false;
-    }
-    const apiVersion = getComponentAPIVersion(vm.component.constructor);
-    return shared.isAPIFeatureEnabled(5 /* APIFeature.ENABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE */, apiVersion);
-}
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -4335,6 +4674,14 @@ const SymbolIterator = Symbol.iterator;
 function addVNodeToChildLWC(vnode) {
     shared.ArrayPush.call(getVMBeingRendered().velements, vnode);
 }
+// [s]tatic [p]art
+function sp(partId, data) {
+    return {
+        partId,
+        data,
+        elm: undefined, // elm is defined later
+    };
+}
 // [s]coped [s]lot [f]actory
 function ssf(slotName, factory) {
     return {
@@ -4348,7 +4695,7 @@ function ssf(slotName, factory) {
     };
 }
 // [st]atic node
-function st(fragment, key, data) {
+function st(fragment, key, parts) {
     const owner = getVMBeingRendered();
     const vnode = {
         type: 4 /* VNodeType.Static */,
@@ -4357,12 +4704,8 @@ function st(fragment, key, data) {
         elm: undefined,
         fragment,
         owner,
-        data,
+        parts,
     };
-    const ref = data === null || data === void 0 ? void 0 : data.ref;
-    if (!shared.isUndefined(ref)) {
-        setRefVNode(owner, ref, vnode);
-    }
     return vnode;
 }
 // [fr]agment node
@@ -4404,7 +4747,7 @@ function h(sel, data, children = EmptyArray) {
             }
         });
     }
-    const { key, ref } = data;
+    const { key } = data;
     const vnode = {
         type: 2 /* VNodeType.Element */,
         sel,
@@ -4414,9 +4757,6 @@ function h(sel, data, children = EmptyArray) {
         key,
         owner: vmBeingRendered,
     };
-    if (!shared.isUndefined(ref)) {
-        setRefVNode(vmBeingRendered, ref, vnode);
-    }
     return vnode;
 }
 // [t]ab[i]ndex function
@@ -4531,7 +4871,7 @@ function c(sel, Ctor, data, children = EmptyArray) {
             });
         }
     }
-    const { key, ref } = data;
+    const { key } = data;
     let elm, aChildren, vm;
     const vnode = {
         type: 3 /* VNodeType.CustomElement */,
@@ -4547,9 +4887,6 @@ function c(sel, Ctor, data, children = EmptyArray) {
         vm,
     };
     addVNodeToChildLWC(vnode);
-    if (!shared.isUndefined(ref)) {
-        setRefVNode(vmBeingRendered, ref, vnode);
-    }
     return vnode;
 }
 // [i]terable node
@@ -4840,6 +5177,7 @@ const api = shared.freeze({
     shc,
     ssf,
     ddc,
+    sp,
 });
 
 /*
@@ -4997,9 +5335,10 @@ function buildParseFragmentFn(createFragmentFn) {
     return (strings, ...keys) => {
         const cache = shared.create(null);
         return function () {
-            const { context: { hasScopedStyles, stylesheetToken }, shadowMode, renderer, } = getVMBeingRendered();
+            const { context: { hasScopedStyles, stylesheetToken, legacyStylesheetToken }, shadowMode, renderer, } = getVMBeingRendered();
             const hasStyleToken = !shared.isUndefined(stylesheetToken);
             const isSyntheticShadow = shadowMode === 1 /* ShadowMode.Synthetic */;
+            const hasLegacyToken = lwcRuntimeFlags.ENABLE_LEGACY_SCOPE_TOKENS && !shared.isUndefined(legacyStylesheetToken);
             let cacheKey = 0;
             if (hasStyleToken && hasScopedStyles) {
                 cacheKey |= 1 /* FragmentCache.HAS_SCOPED_STYLE */;
@@ -5007,12 +5346,19 @@ function buildParseFragmentFn(createFragmentFn) {
             if (hasStyleToken && isSyntheticShadow) {
                 cacheKey |= 2 /* FragmentCache.SHADOW_MODE_SYNTHETIC */;
             }
+            if (hasLegacyToken) {
+                // This isn't strictly required for prod, but it's required for our karma tests
+                // since the lwcRuntimeFlag may change over time
+                cacheKey |= 4 /* FragmentCache.HAS_LEGACY_SCOPE_TOKEN */;
+            }
             if (!shared.isUndefined(cache[cacheKey])) {
                 return cache[cacheKey];
             }
-            const classToken = hasScopedStyles && hasStyleToken ? ' ' + stylesheetToken : '';
-            const classAttrToken = hasScopedStyles && hasStyleToken ? ` class="${stylesheetToken}"` : '';
-            const attrToken = hasStyleToken && isSyntheticShadow ? ' ' + stylesheetToken : '';
+            // If legacy stylesheet tokens are required, then add them to the rendered string
+            const stylesheetTokenToRender = stylesheetToken + (hasLegacyToken ? ` ${legacyStylesheetToken}` : '');
+            const classToken = hasScopedStyles && hasStyleToken ? ' ' + stylesheetTokenToRender : '';
+            const classAttrToken = hasScopedStyles && hasStyleToken ? ` class="${stylesheetTokenToRender}"` : '';
+            const attrToken = hasStyleToken && isSyntheticShadow ? ' ' + stylesheetTokenToRender : '';
             let htmlFragment = '';
             for (let i = 0, n = keys.length; i < n; i++) {
                 switch (keys[i]) {
@@ -5088,7 +5434,10 @@ function evaluateTemplate(vm, html) {
                 // Set the computeHasScopedStyles property in the context, to avoid recomputing it repeatedly.
                 context.hasScopedStyles = computeHasScopedStyles(html, vm);
                 // Update the scoping token on the host element.
-                updateStylesheetToken(vm, html);
+                updateStylesheetToken(vm, html, /* legacy */ false);
+                if (lwcRuntimeFlags.ENABLE_LEGACY_SCOPE_TOKENS) {
+                    updateStylesheetToken(vm, html, /* legacy */ true);
+                }
                 // Evaluate, create stylesheet and cache the produced VNode for future
                 // re-rendering.
                 const stylesheetsContent = getStylesheetsContent(vm, html);
@@ -5103,8 +5452,6 @@ function evaluateTemplate(vm, html) {
                 // add the VM to the list of host VMs that can be re-rendered if html is swapped
                 setActiveVM(vm);
             }
-            // reset the refs; they will be set during the tmpl() instantiation
-            vm.refVNodes = html.hasRefs ? shared.create(null) : null;
             // right before producing the vnodes, we clear up all internal references
             // to custom elements from the template.
             vm.velements = [];
@@ -5274,8 +5621,9 @@ function getComponentAPIVersion(Ctor) {
     const metadata = registeredComponentMap.get(Ctor);
     const apiVersion = metadata === null || metadata === void 0 ? void 0 : metadata.apiVersion;
     if (shared.isUndefined(apiVersion)) {
-        // This should only occur in two places: 1) our Karma tests, with unregistered components, and
-        // 2) the ACT compiler. To be safe, return the lowest possible API version.
+        // This should only occur in our Karma tests; in practice every component
+        // is registered, and so this code path should not get hit. But to be safe,
+        // return the lowest possible version.
         return shared.LOWEST_API_VERSION;
     }
     return apiVersion;
@@ -5323,44 +5671,6 @@ function getWrappedComponentsListener(vm, listener) {
     return wrappedListener;
 }
 
-/*
- * Copyright (c) 2018, salesforce.com, inc.
- * All rights reserved.
- * SPDX-License-Identifier: MIT
- * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
- */
-const Services = shared.create(null);
-const hooks = ['rendered', 'connected', 'disconnected'];
-/**
- * EXPERIMENTAL: This function allows for the registration of "services"
- * in LWC by exposing hooks into the component life-cycle. This API is
- * subject to change or being removed.
- */
-function register(service) {
-    if (process.env.NODE_ENV !== 'production') {
-        shared.assert.isTrue(shared.isObject(service), `Invalid service declaration, ${service}: service must be an object`);
-    }
-    for (let i = 0; i < hooks.length; ++i) {
-        const hookName = hooks[i];
-        if (hookName in service) {
-            let l = Services[hookName];
-            if (shared.isUndefined(l)) {
-                Services[hookName] = l = [];
-            }
-            shared.ArrayPush.call(l, service[hookName]);
-        }
-    }
-}
-function invokeServiceHook(vm, cbs) {
-    if (process.env.NODE_ENV !== 'production') {
-        shared.assert.isTrue(shared.isArray(cbs) && cbs.length > 0, `Optimize invokeServiceHook() to be invoked only when needed`);
-    }
-    const { component, def, context } = vm;
-    for (let i = 0, len = cbs.length; i < len; ++i) {
-        cbs[i].call(undefined, component, {}, def, context);
-    }
-}
-
 /*
  * Copyright (c) 2023, Salesforce.com, inc.
  * All rights reserved.
@@ -5419,12 +5729,18 @@ function resetComponentStateWhenRemoved(vm) {
 // old vnode.children is removed from the DOM.
 function removeVM(vm) {
     if (process.env.NODE_ENV !== 'production') {
-        shared.assert.isTrue(vm.state === 1 /* VMState.connected */ || vm.state === 2 /* VMState.disconnected */, `${vm} must have been connected.`);
+        if (!lwcRuntimeFlags.ENABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE) {
+            // With native lifecycle, we cannot be certain that connectedCallback was called before a component
+            // was removed from the VDOM. If the component is disconnected, then connectedCallback will not fire
+            // in native mode, although it will fire in synthetic mode due to appendChild triggering it.
+            // See: W-14037619 for details
+            shared.assert.isTrue(vm.state === 1 /* VMState.connected */ || vm.state === 2 /* VMState.disconnected */, `${vm} must have been connected.`);
+        }
     }
     resetComponentStateWhenRemoved(vm);
 }
-function getNearestShadowAncestor(vm) {
-    let ancestor = vm.owner;
+function getNearestShadowAncestor(owner) {
+    let ancestor = owner;
     while (!shared.isNull(ancestor) && ancestor.renderMode === 0 /* RenderMode.Light */) {
         ancestor = ancestor.owner;
     }
@@ -5458,6 +5774,9 @@ function createVM(elm, ctor, renderer, options) {
             stylesheetToken: undefined,
             hasTokenInClass: undefined,
             hasTokenInAttribute: undefined,
+            legacyStylesheetToken: undefined,
+            hasLegacyTokenInClass: undefined,
+            hasLegacyTokenInAttribute: undefined,
             hasScopedStyles: undefined,
             styleVNodes: null,
             tplCache: EmptyObject,
@@ -5482,15 +5801,12 @@ function createVM(elm, ctor, renderer, options) {
         vm.debugInfo = shared.create(null);
     }
     vm.stylesheets = computeStylesheets(vm, def.ctor);
-    vm.shadowMode = computeShadowMode(vm, renderer);
+    vm.shadowMode = computeShadowMode(def, vm.owner, renderer);
     vm.tro = getTemplateReactiveObserver(vm);
     if (process.env.NODE_ENV !== 'production') {
         vm.toString = () => {
             return `[object:vm ${def.name} (${vm.idx})]`;
         };
-        if (lwcRuntimeFlags.ENABLE_FORCE_NATIVE_SHADOW_MODE_FOR_TEST) {
-            vm.shadowMode = 0 /* ShadowMode.Native */;
-        }
     }
     // Create component instance associated to the vm and the element.
     invokeComponentConstructor(vm, def.ctor);
@@ -5553,8 +5869,21 @@ function warnOnStylesheetsMutation(ctor) {
         });
     }
 }
-function computeShadowMode(vm, renderer) {
-    const { def } = vm;
+// Compute the shadowMode/renderMode without creating a VM. This is used in some scenarios like hydration.
+function computeShadowAndRenderMode(Ctor, renderer) {
+    const def = getComponentInternalDef(Ctor);
+    const { renderMode } = def;
+    // Assume null `owner` - this is what happens in hydration cases anyway
+    const shadowMode = computeShadowMode(def, /* owner */ null, renderer);
+    return { renderMode, shadowMode };
+}
+function computeShadowMode(def, owner, renderer) {
+    // Force the shadow mode to always be native. Used for running tests with synthetic shadow patches
+    // on, but components running in actual native shadow mode
+    if (process.env.NODE_ENV !== 'production' &&
+        lwcRuntimeFlags.ENABLE_FORCE_NATIVE_SHADOW_MODE_FOR_TEST) {
+        return 0 /* ShadowMode.Native */;
+    }
     const { isSyntheticShadowDefined } = renderer;
     let shadowMode;
     if (isSyntheticShadowDefined) {
@@ -5563,12 +5892,14 @@ function computeShadowMode(vm, renderer) {
             // everything defaults to native when the synthetic shadow polyfill is unavailable.
             shadowMode = 0 /* ShadowMode.Native */;
         }
-        else if (lwcRuntimeFlags.ENABLE_MIXED_SHADOW_MODE) {
-            if (def.shadowSupportMode === "any" /* ShadowSupportMode.Any */) {
+        else if (lwcRuntimeFlags.ENABLE_MIXED_SHADOW_MODE ||
+            def.shadowSupportMode === "native" /* ShadowSupportMode.Native */) {
+            if (def.shadowSupportMode === "any" /* ShadowSupportMode.Any */ ||
+                def.shadowSupportMode === "native" /* ShadowSupportMode.Native */) {
                 shadowMode = 0 /* ShadowMode.Native */;
             }
             else {
-                const shadowAncestor = getNearestShadowAncestor(vm);
+                const shadowAncestor = getNearestShadowAncestor(owner);
                 if (!shared.isNull(shadowAncestor) && shadowAncestor.shadowMode === 0 /* ShadowMode.Native */) {
                     // Transitive support for native Shadow DOM. A component in native mode
                     // transitively opts all of its descendants into native.
@@ -5623,6 +5954,8 @@ function rehydrate(vm) {
 }
 function patchShadowRoot(vm, newCh) {
     const { renderRoot, children: oldCh, renderer } = vm;
+    // reset the refs; they will be set during `patchChildren`
+    resetRefVNodes(vm);
     // caching the new children collection
     vm.children = newCh;
     if (newCh.length > 0 || oldCh.length > 0) {
@@ -5654,10 +5987,6 @@ function runRenderedCallback(vm) {
     if (!process.env.IS_BROWSER) {
         return;
     }
-    const { rendered } = Services;
-    if (rendered) {
-        invokeServiceHook(vm, rendered);
-    }
     if (!shared.isUndefined(renderedCallback)) {
         logOperationStart(4 /* OperationId.RenderedCallback */, vm);
         invokeComponentCallback(vm, renderedCallback);
@@ -5700,11 +6029,6 @@ function runConnectedCallback(vm) {
         return; // nothing to do since it was already connected
     }
     vm.state = 1 /* VMState.connected */;
-    // reporting connection
-    const { connected } = Services;
-    if (connected) {
-        invokeServiceHook(vm, connected);
-    }
     if (hasWireAdapters(vm)) {
         connectWireAdapters(vm);
     }
@@ -5730,11 +6054,6 @@ function runDisconnectedCallback(vm) {
         vm.isDirty = true;
     }
     vm.state = 2 /* VMState.disconnected */;
-    // reporting disconnection
-    const { disconnected } = Services;
-    if (disconnected) {
-        invokeServiceHook(vm, disconnected);
-    }
     if (hasWireAdapters(vm)) {
         disconnectWireAdapters(vm);
     }
@@ -5859,7 +6178,12 @@ function runWithBoundaryProtection(vm, owner, pre, job, post) {
         if (!shared.isUndefined(error)) {
             addErrorComponentStack(vm, error);
             const errorBoundaryVm = shared.isNull(owner) ? undefined : getErrorBoundaryVM(owner);
-            if (shared.isUndefined(errorBoundaryVm)) {
+            // Error boundaries are not in effect when server-side rendering. `errorCallback`
+            // is intended to allow recovery from errors - changing the state of a component
+            // and instigating a re-render. That is at odds with the single-pass, synchronous
+            // nature of SSR. For that reason, all errors bubble up to the `renderComponent`
+            // call site.
+            if (!process.env.IS_BROWSER || shared.isUndefined(errorBoundaryVm)) {
                 throw error; // eslint-disable-line no-unsafe-finally
             }
             resetComponentRoot(vm); // remove offenders
@@ -5887,6 +6211,52 @@ function forceRehydration(vm) {
         scheduleRehydration(vm);
     }
 }
+function runFormAssociatedCustomElementCallback(vm, faceCb) {
+    const { renderMode, shadowMode, def: { formAssociated }, } = vm;
+    // Technically the UpgradableConstructor always sets `static formAssociated = true` but silently fail here to match browser behavior.
+    if (shared.isUndefined(formAssociated) || shared.isFalse(formAssociated)) {
+        if (process.env.NODE_ENV !== 'production') {
+            logWarn(`Form associated lifecycle methods must have the 'static formAssociated' value set in the component's prototype chain.`);
+        }
+        return;
+    }
+    if (shadowMode === 1 /* ShadowMode.Synthetic */ && renderMode !== 0 /* RenderMode.Light */) {
+        throw new Error('Form associated lifecycle methods are not available in synthetic shadow. Please use native shadow or light DOM.');
+    }
+    invokeComponentCallback(vm, faceCb);
+}
+function runFormAssociatedCallback(elm) {
+    const vm = getAssociatedVM(elm);
+    const { formAssociatedCallback } = vm.def;
+    if (!shared.isUndefined(formAssociatedCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formAssociatedCallback);
+    }
+}
+function runFormDisabledCallback(elm) {
+    const vm = getAssociatedVM(elm);
+    const { formDisabledCallback } = vm.def;
+    if (!shared.isUndefined(formDisabledCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formDisabledCallback);
+    }
+}
+function runFormResetCallback(elm) {
+    const vm = getAssociatedVM(elm);
+    const { formResetCallback } = vm.def;
+    if (!shared.isUndefined(formResetCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formResetCallback);
+    }
+}
+function runFormStateRestoreCallback(elm) {
+    const vm = getAssociatedVM(elm);
+    const { formStateRestoreCallback } = vm.def;
+    if (!shared.isUndefined(formStateRestoreCallback)) {
+        runFormAssociatedCustomElementCallback(vm, formStateRestoreCallback);
+    }
+}
+function resetRefVNodes(vm) {
+    const { cmpTemplate } = vm;
+    vm.refVNodes = !shared.isNull(cmpTemplate) && cmpTemplate.hasRefs ? shared.create(null) : null;
+}
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -6061,6 +6431,12 @@ const NON_STANDARD_ARIA_PROPS = [
     'ariaLabelledBy',
     'ariaOwns',
 ];
+function isGlobalAriaPolyfillLoaded() {
+    // Sniff for the legacy polyfill being loaded. The reason this works is because ariaActiveDescendant is a
+    // non-standard ARIA property reflection that is only supported in our legacy polyfill. See
+    // @lwc/aria-reflection/README.md for details.
+    return !shared.isUndefined(shared.getOwnPropertyDescriptor(Element.prototype, 'ariaActiveDescendant'));
+}
 function findVM(elm) {
     // If it's a shadow DOM component, then it has a host
     const { host } = elm.getRootNode();
@@ -6120,6 +6496,9 @@ function enableDetection() {
         }
         // @ts-ignore
         const { get, set } = descriptor;
+        // It's important for this defineProperty call to happen _after_ ARIA accessors are applied to the
+        // BaseBridgeElement and LightningElement prototypes. Otherwise, we will log/report for access of non-standard
+        // props on these prototypes, which we actually don't want. We only care about access on generic HTMLElements.
         shared.defineProperty(prototype, prop, {
             get() {
                 checkAndReportViolation(this, prop, false, undefined);
@@ -6135,16 +6514,14 @@ function enableDetection() {
     }
 }
 // No point in running this code if we're not in a browser, or if the global polyfill is not loaded
-if (process.env.IS_BROWSER) {
-    if (lwcRuntimeFlags.ENABLE_ARIA_REFLECTION_GLOBAL_POLYFILL) {
-        // Always run detection in dev mode, so we can at least print to the console
-        if (process.env.NODE_ENV !== 'production') {
-            enableDetection();
-        }
-        else {
-            // In prod mode, only enable detection if reporting is enabled
-            onReportingEnabled(enableDetection);
-        }
+if (process.env.IS_BROWSER && isGlobalAriaPolyfillLoaded()) {
+    // Always run detection in dev mode, so we can at least print to the console
+    if (process.env.NODE_ENV !== 'production') {
+        enableDetection();
+    }
+    else {
+        // In prod mode, only enable detection if reporting is enabled
+        onReportingEnabled(enableDetection);
     }
 }
 
@@ -6167,6 +6544,8 @@ function hydrateRoot(vm) {
 function hydrateVM(vm) {
     const children = renderComponent(vm);
     vm.children = children;
+    // reset the refs; they will be set during `hydrateChildren`
+    resetRefVNodes(vm);
     const { renderRoot: parentNode, renderer: { getFirstChild }, } = vm;
     hydrateChildren(getFirstChild(parentNode), children, parentNode, vm);
     runRenderedCallback(vm);
@@ -6275,7 +6654,7 @@ function hydrateStaticElement(elm, vnode, renderer) {
         return handleMismatch(elm, vnode, renderer);
     }
     vnode.elm = elm;
-    applyEventListeners(vnode, renderer);
+    applyStaticParts(elm, vnode, renderer, true);
     return elm;
 }
 function hydrateFragment(elm, vnode, renderer) {
@@ -6309,7 +6688,7 @@ function hydrateElement(elm, vnode, renderer) {
             }
         }
     }
-    patchElementPropsAndAttrs(vnode, renderer);
+    patchElementPropsAndAttrsAndRefs(vnode, renderer);
     if (!isDomManual) {
         const { getFirstChild } = renderer;
         hydrateChildren(getFirstChild(elm), vnode.children, elm, owner);
@@ -6333,6 +6712,8 @@ function hydrateCustomElement(elm, vnode, renderer) {
         return handleMismatch(elm, vnode, renderer);
     }
     const { sel, mode, ctor, owner } = vnode;
+    const { defineCustomElement, getTagName } = renderer;
+    defineCustomElement(shared.StringToLowerCase.call(getTagName(elm)));
     const vm = createVM(elm, ctor, renderer, {
         mode,
         owner,
@@ -6342,7 +6723,7 @@ function hydrateCustomElement(elm, vnode, renderer) {
     vnode.elm = elm;
     vnode.vm = vm;
     allocateChildren(vnode, vm);
-    patchElementPropsAndAttrs(vnode, renderer);
+    patchElementPropsAndAttrsAndRefs(vnode, renderer);
     // Insert hook section:
     if (process.env.NODE_ENV !== 'production') {
         shared.assert.isTrue(vm.state === 0 /* VMState.created */, `${vm} cannot be recycled.`);
@@ -6407,9 +6788,11 @@ function handleMismatch(node, vnode, renderer) {
     removeNode(node, parentNode, renderer);
     return vnode.elm;
 }
-function patchElementPropsAndAttrs(vnode, renderer) {
+function patchElementPropsAndAttrsAndRefs(vnode, renderer) {
     applyEventListeners(vnode, renderer);
     patchProps(null, vnode, renderer);
+    // The `refs` object is blown away in every re-render, so we always need to re-apply them
+    applyRefs(vnode, vnode.owner);
 }
 function hasCorrectNodeType(vnode, node, nodeType, renderer) {
     const { getProperty } = renderer;
@@ -6477,7 +6860,8 @@ function validateClassAttr(vnode, elm, renderer) {
     const { data, owner } = vnode;
     let { className, classMap } = data;
     const { getProperty, getClassList, getAttribute } = renderer;
-    const scopedToken = getScopeTokenClass(owner);
+    // we don't care about legacy for hydration. it's a new use case
+    const scopedToken = getScopeTokenClass(owner, /* legacy */ false);
     const stylesheetTokenHost = isVCustomElement(vnode) ? getStylesheetTokenHost(vnode) : null;
     // Classnames for scoped CSS are added directly to the DOM during rendering,
     // or to the VDOM on the server in the case of SSR. As such, these classnames
@@ -6792,7 +7176,7 @@ function trackMutations(tmpl) {
 }
 function addLegacyStylesheetTokensShim(tmpl) {
     // When ENABLE_FROZEN_TEMPLATE is false, then we shim stylesheetTokens on top of stylesheetToken for anyone who
-    // is accessing the old internal API (backwards compat). Details: https://salesforce.quip.com/v1rmAFu2cKAr
+    // is accessing the old internal API (backwards compat). Details: W-14210169
     shared.defineProperty(tmpl, 'stylesheetTokens', {
         enumerable: true,
         configurable: true,
@@ -6898,6 +7282,7 @@ exports.LightningElement = LightningElement;
 exports.__unstable__ProfilerControl = profilerControl;
 exports.__unstable__ReportingControl = reportingControl;
 exports.api = api$1;
+exports.computeShadowAndRenderMode = computeShadowAndRenderMode;
 exports.connectRootElement = connectRootElement;
 exports.createContextProviderWithRegister = createContextProviderWithRegister;
 exports.createVM = createVM;
@@ -6913,10 +7298,13 @@ exports.isComponentConstructor = isComponentConstructor;
 exports.parseFragment = parseFragment;
 exports.parseSVGFragment = parseSVGFragment;
 exports.readonly = readonly;
-exports.register = register;
 exports.registerComponent = registerComponent;
 exports.registerDecorators = registerDecorators;
 exports.registerTemplate = registerTemplate;
+exports.runFormAssociatedCallback = runFormAssociatedCallback;
+exports.runFormDisabledCallback = runFormDisabledCallback;
+exports.runFormResetCallback = runFormResetCallback;
+exports.runFormStateRestoreCallback = runFormStateRestoreCallback;
 exports.sanitizeAttribute = sanitizeAttribute;
 exports.setHooks = setHooks;
 exports.swapComponent = swapComponent;
@@ -6925,5 +7313,5 @@ exports.swapTemplate = swapTemplate;
 exports.track = track;
 exports.unwrap = unwrap;
 exports.wire = wire;
-/** version: 4.0.0-alpha.0 */
+/** version: 4.0.0 */
 //# sourceMappingURL=index.cjs.js.map