feat: CSR/SSRv1 context (#5356)

* chore: add tests, centralize coverage
* chore: add stubs for unimplemented v2 exports
* chore: simplified shadow test
* fix: gate protection, review comments, malformed context handling
* fix: doc review

Author: jhefferman-sfdc

packages/@lwc/engine-core/README.md

@@ -121,3 +121,18 @@ This experimental API enables the removal of an object's observable membrane pro
 This experimental API enables the addition of a signal as a trusted signal. If the [ENABLE_EXPERIMENTAL_SIGNALS](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/features/README.md#lwcfeatures) feature is enabled, any signal value change will trigger a re-render.
 
 If `setTrustedSignalSet` is called more than once, it will throw an error. If it is never called, then no trusted signal validation will be performed. The same `setTrustedSignalSet` API must be called on both `@lwc/engine-dom` and `@lwc/signals`.
+
+### setContextKeys
+
+Not intended for external use. Enables another library to establish contextful relationships via the LWC component tree. The `connectContext` and `disconnectContext` symbols that are provided are later used to identify methods that facilitate the establishment and dissolution of these contextful relationships.
+
+### setTrustedContextSet()
+
+Not intended for external use. This experimental API enables the addition of context as trusted context. If the [ENABLE_EXPERIMENTAL_SIGNALS](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/features/README.md#lwcfeatures) feature is enabled.
+
+If `setTrustedContextSet` is called more than once, it will throw an error. If it is never called, then context will not be connected.
+
+### ContextBinding
+
+The context object's `connectContext` and `disconnectContext` methods are called with this object when contextful components are connected and disconnected. The ContextBinding exposes `provideContext` and `consumeContext`,
+enabling the provision/consumption of a contextful Signal of a specified variety for the associated component.

packages/@lwc/engine-core/src/framework/main.ts

@@ -73,5 +73,5 @@ export { default as wire } from './decorators/wire';
 export { readonly } from './readonly';
 
 export { setFeatureFlag, setFeatureFlagForTest } from '@lwc/features';
-export { setTrustedSignalSet } from '@lwc/shared';
+export { setContextKeys, setTrustedSignalSet, setTrustedContextSet } from '@lwc/shared';
 export type { Stylesheet, Stylesheets } from '@lwc/shared';

packages/@lwc/engine-core/src/framework/modules/context.ts

@@ -0,0 +1,149 @@
+/*
+ * Copyright (c) 2025, 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
+ */
+import {
+    isUndefined,
+    getPrototypeOf,
+    keys,
+    getContextKeys,
+    ArrayFilter,
+    ContextEventName,
+    isTrustedContext,
+    type ContextProvidedCallback,
+    type ContextBinding as IContextBinding,
+} from '@lwc/shared';
+import { type VM } from '../vm';
+import { logWarnOnce } from '../../shared/logger';
+import type { Signal } from '@lwc/signals';
+import type { RendererAPI } from '../renderer';
+import type { ShouldContinueBubbling } from '../wiring/types';
+
+type ContextVarieties = Map<unknown, Signal<unknown>>;
+
+class ContextBinding<C extends object> implements IContextBinding<C> {
+    component: C;
+    #renderer: RendererAPI;
+    #providedContextVarieties: ContextVarieties;
+    #elm: HTMLElement;
+
+    constructor(vm: VM, component: C, providedContextVarieties: ContextVarieties) {
+        this.component = component;
+        this.#renderer = vm.renderer;
+        this.#elm = vm.elm;
+        this.#providedContextVarieties = providedContextVarieties;
+
+        // Register the component as a context provider.
+        this.#renderer.registerContextProvider(
+            this.#elm,
+            ContextEventName,
+            (contextConsumer): ShouldContinueBubbling => {
+                // This callback is invoked when the provided context is consumed somewhere down
+                // in the component's subtree.
+                return contextConsumer.setNewContext(this.#providedContextVarieties);
+            }
+        );
+    }
+
+    provideContext<V extends object>(
+        contextVariety: V,
+        providedContextSignal: Signal<unknown>
+    ): void {
+        if (this.#providedContextVarieties.has(contextVariety)) {
+            logWarnOnce(
+                'Multiple contexts of the same variety were provided. Only the first context will be used.'
+            );
+            return;
+        }
+        this.#providedContextVarieties.set(contextVariety, providedContextSignal);
+    }
+
+    consumeContext<V extends object>(
+        contextVariety: V,
+        contextProvidedCallback: ContextProvidedCallback
+    ): void {
+        this.#renderer.registerContextConsumer(this.#elm, ContextEventName, {
+            setNewContext: (providerContextVarieties: ContextVarieties): ShouldContinueBubbling => {
+                // If the provider has the specified context variety, then it is consumed
+                // and true is returned to stop bubbling.
+                if (providerContextVarieties.has(contextVariety)) {
+                    contextProvidedCallback(providerContextVarieties.get(contextVariety));
+                    return true;
+                }
+                // Return false as context has not been found/consumed
+                // and the consumer should continue traversing the context tree
+                return false;
+            },
+        });
+    }
+}
+
+export function connectContext(vm: VM) {
+    const contextKeys = getContextKeys();
+
+    if (isUndefined(contextKeys)) {
+        return;
+    }
+
+    const { connectContext } = contextKeys;
+    const { component } = vm;
+
+    const enumerableKeys = keys(getPrototypeOf(component));
+    const contextfulKeys = ArrayFilter.call(enumerableKeys, (enumerableKey) =>
+        isTrustedContext((component as any)[enumerableKey])
+    );
+
+    if (contextfulKeys.length === 0) {
+        return;
+    }
+
+    const providedContextVarieties: ContextVarieties = new Map();
+
+    try {
+        for (let i = 0; i < contextfulKeys.length; i++) {
+            (component as any)[contextfulKeys[i]][connectContext](
+                new ContextBinding(vm, component, providedContextVarieties)
+            );
+        }
+    } catch (err: any) {
+        logWarnOnce(
+            `Attempted to connect to trusted context but received the following error: ${
+                err.message
+            }`
+        );
+    }
+}
+
+export function disconnectContext(vm: VM) {
+    const contextKeys = getContextKeys();
+
+    if (!contextKeys) {
+        return;
+    }
+
+    const { disconnectContext } = contextKeys;
+    const { component } = vm;
+
+    const enumerableKeys = keys(getPrototypeOf(component));
+    const contextfulKeys = ArrayFilter.call(enumerableKeys, (enumerableKey) =>
+        isTrustedContext((component as any)[enumerableKey])
+    );
+
+    if (contextfulKeys.length === 0) {
+        return;
+    }
+
+    try {
+        for (let i = 0; i < contextfulKeys.length; i++) {
+            (component as any)[contextfulKeys[i]][disconnectContext](component);
+        }
+    } catch (err: any) {
+        logWarnOnce(
+            `Attempted to disconnect from trusted context but received the following error: ${
+                err.message
+            }`
+        );
+    }
+}

packages/@lwc/engine-core/src/framework/mutation-tracker.ts

@@ -42,6 +42,7 @@ export function componentValueObserved(vm: VM, key: PropertyKey, target: any = {
         isObject(target) &&
         !isNull(target) &&
         isTrustedSignal(target) &&
+        process.env.IS_BROWSER &&
         // Only subscribe if a template is being rendered by the engine
         tro.isObserving()
     ) {

packages/@lwc/engine-core/src/framework/renderer.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
-import type { WireContextSubscriptionPayload } from './wiring';
+import type { WireContextSubscriptionCallback, WireContextSubscriptionPayload } from './wiring';
 
 export type HostNode = any;
 export type HostElement = any;
@@ -76,6 +76,11 @@ export interface RendererAPI {
     ) => E;
     defineCustomElement: (tagName: string, isFormAssociated: boolean) => void;
     ownerDocument(elm: E): Document;
+    registerContextProvider: (
+        element: E,
+        adapterContextToken: string,
+        onContextSubscription: WireContextSubscriptionCallback
+    ) => void;
     registerContextConsumer: (
         element: E,
         adapterContextToken: string,

packages/@lwc/engine-core/src/framework/vm.ts

@@ -49,6 +49,7 @@ import { flushMutationLogsForVM, getAndFlushMutationLogs } from './mutation-logg
 import { connectWireAdapters, disconnectWireAdapters, installWireAdapters } from './wiring';
 import { VNodeType, isVFragment } from './vnodes';
 import { isReportingEnabled, report, ReportingEventId } from './reporting';
+import { connectContext, disconnectContext } from './modules/context';
 import type { VNodes, VCustomElement, VNode, VBaseElement, VStaticPartElement } from './vnodes';
 import type { ReactiveObserver } from './mutation-tracker';
 import type {
@@ -702,6 +703,12 @@ export function runConnectedCallback(vm: VM) {
     if (hasWireAdapters(vm)) {
         connectWireAdapters(vm);
     }
+
+    if (lwcRuntimeFlags.ENABLE_EXPERIMENTAL_SIGNALS) {
+        // Setup context before connected callback is executed
+        connectContext(vm);
+    }
+
     const { connectedCallback } = vm.def;
     if (!isUndefined(connectedCallback)) {
         logOperationStart(OperationId.ConnectedCallback, vm);
@@ -751,6 +758,11 @@ function runDisconnectedCallback(vm: VM) {
     if (process.env.NODE_ENV !== 'production') {
         assert.isTrue(vm.state !== VMState.disconnected, `${vm} must be inserted.`);
     }
+
+    if (lwcRuntimeFlags.ENABLE_EXPERIMENTAL_SIGNALS) {
+        disconnectContext(vm);
+    }
+
     if (isFalse(vm.isDirty)) {
         // this guarantees that if the component is reused/reinserted,
         // it will be re-rendered because we are disconnecting the reactivity

packages/@lwc/engine-core/src/framework/wiring/context.ts

@@ -54,9 +54,12 @@ export function createContextProviderWithRegister(
                         consumerDisconnectedCallback(consumer);
                     }
                 };
-                setDisconnectedCallback(disconnectCallback);
+                setDisconnectedCallback?.(disconnectCallback);
 
                 consumerConnectedCallback(consumer);
+                // Return true as the context is always consumed here and the consumer should
+                // stop bubbling.
+                return true;
             }
         );
     };
@@ -91,6 +94,9 @@ export function createContextWatcher(
                 // eslint-disable-next-line @lwc/lwc-internal/no-invalid-todo
                 // TODO: dev-mode validation of config based on the adapter.contextSchema
                 callbackWhenContextIsReady(newContext);
+                // Return true as the context is always consumed here and the consumer should
+                // stop bubbling.
+                return true;
             },
             setDisconnectedCallback(disconnectCallback: () => void) {
                 // adds this callback into the disconnect bucket so it gets disconnected from parent

packages/@lwc/engine-core/src/framework/wiring/types.ts

@@ -59,13 +59,15 @@ export interface WireDebugInfo {
     wasDataProvisionedForConfig: boolean;
 }
 
+export type ShouldContinueBubbling = boolean;
+
 export type WireContextSubscriptionCallback = (
     subscriptionPayload: WireContextSubscriptionPayload
-) => void;
+) => ShouldContinueBubbling;
 
 export interface WireContextSubscriptionPayload {
-    setNewContext(newContext: ContextValue): void;
-    setDisconnectedCallback(disconnectCallback: () => void): void;
+    setNewContext(newContext: ContextValue): ShouldContinueBubbling;
+    setDisconnectedCallback?(disconnectCallback: () => void): void;
 }
 
 export interface ContextConsumer {

packages/@lwc/engine-core/src/shared/logger.ts

@@ -51,6 +51,10 @@ export function logError(message: string, vm?: VM) {
     log('error', message, vm, false);
 }
 
+export function logErrorOnce(message: string, vm?: VM) {
+    log('error', message, vm, true);
+}
+
 export function logWarn(message: string, vm?: VM) {
     log('warn', message, vm, false);
 }

packages/@lwc/engine-dom/src/index.ts

@@ -30,7 +30,9 @@ export {
     isComponentConstructor,
     parseFragment,
     parseSVGFragment,
+    setContextKeys,
     setTrustedSignalSet,
+    setTrustedContextSet,
     swapComponent,
     swapStyle,
     swapTemplate,

packages/@lwc/engine-dom/src/renderer/context.ts

@@ -16,8 +16,8 @@ import type {
 
 export class WireContextSubscriptionEvent extends CustomEvent<undefined> {
     // These are initialized on the constructor via defineProperties.
-    public readonly setNewContext!: (newContext: WireContextValue) => void;
-    public readonly setDisconnectedCallback!: (disconnectCallback: () => void) => void;
+    public readonly setNewContext!: (newContext: WireContextValue) => boolean;
+    public readonly setDisconnectedCallback?: (disconnectCallback: () => void) => void;
 
     constructor(
         adapterToken: string,
@@ -56,11 +56,15 @@ export function registerContextProvider(
     onContextSubscription: WireContextSubscriptionCallback
 ) {
     addEventListener(elm, adapterContextToken, ((evt: WireContextSubscriptionEvent) => {
-        evt.stopImmediatePropagation();
         const { setNewContext, setDisconnectedCallback } = evt;
-        onContextSubscription({
-            setNewContext,
-            setDisconnectedCallback,
-        });
+        // If context subscription is successful, stop event propagation
+        if (
+            onContextSubscription({
+                setNewContext,
+                setDisconnectedCallback,
+            })
+        ) {
+            evt.stopImmediatePropagation();
+        }
     }) as EventListener);
 }

packages/@lwc/engine-server/src/context.ts

@@ -26,7 +26,7 @@ export function createContextProvider(adapter: WireAdapterConstructor) {
     return createContextProviderWithRegister(adapter, registerContextProvider);
 }
 
-function registerContextProvider(
+export function registerContextProvider(
     elm: HostElement | LightningElement,
     adapterContextToken: string,
     onContextSubscription: WireContextSubscriptionCallback
@@ -57,10 +57,10 @@ export function registerContextConsumer(
             const subscribeToProvider =
                 currentNode[HostContextProvidersKey].get(adapterContextToken);
             if (!isUndefined(subscribeToProvider)) {
-                subscribeToProvider(subscriptionPayload);
-                // If we find a provider, we shouldn't continue traversing
-                // looking for another provider.
-                break;
+                // If context subscription is successful, stop traversing to locate a provider
+                if (subscribeToProvider(subscriptionPayload)) {
+                    break;
+                }
             }
         }
 

packages/@lwc/engine-server/src/index.ts

@@ -29,6 +29,8 @@ export {
     isComponentConstructor,
     parseFragment,
     parseFragment as parseSVGFragment,
+    setTrustedContextSet,
+    setContextKeys,
 } from '@lwc/engine-core';
 
 // Engine-server public APIs -----------------------------------------------------------------------

packages/@lwc/engine-server/src/renderer.ts

@@ -35,7 +35,7 @@ import {
     startTrackingMutations,
     stopTrackingMutations,
 } from './utils/mutation-tracking';
-import { registerContextConsumer } from './context';
+import { registerContextConsumer, registerContextProvider } from './context';
 import type { HostNode, HostElement, HostAttribute, HostChildNode } from './types';
 import type { LifecycleCallback } from '@lwc/engine-core';
 
@@ -509,6 +509,7 @@ export const renderer = {
     insertStylesheet,
     assertInstanceOfHTMLElement,
     ownerDocument,
+    registerContextProvider,
     registerContextConsumer,
     attachInternals,
     defineCustomElement: getUpgradableElement,