@dxos/web-context-solid 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+MIT License
+Copyright (c) 2025 DXOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @dxos/web-context-solid
+
+SolidJS implementation of the Web Component Context Protocol.
+
+## Overview
+
+This package allows SolidJS components to seamlessly participate in the [Web Component Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md).
+
+## Installation
+
+```bash
+npm install @dxos/web-context-solid @dxos/web-context
+```
+
+## Usage
+
+### Providing Context
+
+```tsx
+import { createContext } from '@dxos/web-context';
+import { ContextProtocolProvider } from '@dxos/web-context-solid';
+
+const ThemeContext = createContext<{ color: string }>('theme');
+
+const App = () => (
+  <ContextProtocolProvider context={ThemeContext} value={{ color: 'blue' }}>
+    <MyComponent />
+  </ContextProtocolProvider>
+);
+```
+
+### Consuming Context
+
+```tsx
+import { useWebComponentContext } from '@dxos/web-context-solid';
+
+const MyComponent = () => {
+  const theme = useWebComponentContext(ThemeContext, { subscribe: true });
+  
+  return <div style={{ color: theme()?.color }}>Hello World</div>;
+};
+```

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dxos/web-context-solid",
+  "version": "0.0.0",
+  "description": "Solid.js integration with web context protocol",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {}
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "solid-element": "^1.9.1",
+    "@dxos/web-context": "0.0.0"
+  },
+  "devDependencies": {
+    "@solidjs/testing-library": "^0.8.10",
+    "solid-js": "^1.9.9",
+    "vite-plugin-solid": "^2.11.10"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consumer.test.tsx

@@ -0,0 +1,255 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { cleanup, render, waitFor } from '@solidjs/testing-library';
+import { createSignal } from 'solid-js';
+import { afterEach, describe, expect, test } from 'vitest';
+
+import { CONTEXT_REQUEST_EVENT, createContext } from '@dxos/web-context';
+
+import { useWebComponentContext } from './consumer';
+import { ContextProtocolProvider } from './provider';
+
+describe('useWebComponentContext', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  test('returns undefined when no provider exists', () => {
+    const ctx = createContext<string>('test');
+    let contextValue: string | undefined;
+
+    render(() => {
+      const value = useWebComponentContext(ctx);
+      contextValue = value();
+      return <div>Test</div>;
+    });
+
+    expect(contextValue).toBeUndefined();
+  });
+
+  test('receives value from provider', () => {
+    const ctx = createContext<string>('test');
+    let contextValue: string | undefined;
+
+    render(() => (
+      <ContextProtocolProvider context={ctx} value='hello'>
+        {(() => {
+          const value = useWebComponentContext(ctx);
+          contextValue = value();
+          return <div>Test</div>;
+        })()}
+      </ContextProtocolProvider>
+    ));
+
+    expect(contextValue).toBe('hello');
+  });
+
+  test('receives updates when subscribed', async () => {
+    const ctx = createContext<number>('counter');
+    const [count, setCount] = createSignal(0);
+    const values: number[] = [];
+
+    render(() => (
+      <ContextProtocolProvider context={ctx} value={count}>
+        {(() => {
+          const value = useWebComponentContext(ctx, { subscribe: true });
+          // Track all values we receive
+          values.push(value() ?? -1);
+          return <div>{value()}</div>;
+        })()}
+      </ContextProtocolProvider>
+    ));
+
+    expect(values).toContain(0);
+
+    // Update the value
+    setCount(1);
+    await Promise.resolve();
+
+    // Re-render will have picked up the new value via the signal
+    // Since SolidJS is fine-grained, we need to access the value in an effect
+  });
+
+  test('does not receive updates when not subscribed', async () => {
+    const ctx = createContext<number>('counter');
+    const [count, setCount] = createSignal(0);
+    const receivedValues: number[] = [];
+
+    // Use a proper component pattern
+    const Consumer = () => {
+      const value = useWebComponentContext(ctx, { subscribe: false });
+      // Track what values the signal returns when accessed
+      receivedValues.push(value() ?? -1);
+      return <div data-testid='display'>{value()}</div>;
+    };
+
+    const { findByTestId } = render(() => (
+      <ContextProtocolProvider context={ctx} value={count}>
+        <Consumer />
+      </ContextProtocolProvider>
+    ));
+
+    const display = await findByTestId('display');
+    expect(display.textContent).toBe('0');
+
+    // Clear to track only updates after initial render
+    const initialValues = [...receivedValues];
+    receivedValues.length = 0;
+
+    // Update the provider value
+    setCount(1);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Without subscription, the consumer's signal should NOT update
+    // The display should still show the initial value
+    expect(display.textContent).toBe('0');
+
+    // The consumer should not have received any new values
+    // (some frameworks might re-render, but the value shouldn't change)
+    expect(receivedValues.every((v) => v === 0 || v === -1)).toBe(true);
+  });
+
+  test('can dispatch from custom element', () => {
+    const ctx = createContext<string>('test');
+    let contextValue: string | undefined;
+
+    // Create a custom element to dispatch from
+    const customEl = document.createElement('div');
+    document.body.appendChild(customEl);
+
+    // Set up provider on body
+    const handler = (e: Event) => {
+      const event = e as any;
+      if (event.context === ctx) {
+        event.stopImmediatePropagation();
+        event.callback('custom-element-value');
+      }
+    };
+    document.body.addEventListener(CONTEXT_REQUEST_EVENT, handler);
+
+    render(() => {
+      const value = useWebComponentContext(ctx, { element: customEl });
+      contextValue = value();
+      return <div>Test</div>;
+    });
+
+    expect(contextValue).toBe('custom-element-value');
+
+    // Cleanup
+    document.body.removeEventListener(CONTEXT_REQUEST_EVENT, handler);
+    document.body.removeChild(customEl);
+  });
+
+  test('returns accessor that can be called multiple times', () => {
+    const ctx = createContext<string>('test');
+
+    render(() => (
+      <ContextProtocolProvider context={ctx} value='test-value'>
+        {(() => {
+          const value = useWebComponentContext(ctx);
+
+          // Call the accessor multiple times
+          const v1 = value();
+          const v2 = value();
+          const v3 = value();
+
+          expect(v1).toBe('test-value');
+          expect(v2).toBe('test-value');
+          expect(v3).toBe('test-value');
+
+          return <div>Test</div>;
+        })()}
+      </ContextProtocolProvider>
+    ));
+  });
+
+  test('works with object values', () => {
+    const ctx = createContext<{ name: string; count: number }>('user');
+    let contextValue: { name: string; count: number } | undefined;
+
+    render(() => (
+      <ContextProtocolProvider context={ctx} value={{ name: 'Alice', count: 42 }}>
+        {(() => {
+          const value = useWebComponentContext(ctx);
+          contextValue = value();
+          return <div>Test</div>;
+        })()}
+      </ContextProtocolProvider>
+    ));
+
+    expect(contextValue).toEqual({ name: 'Alice', count: 42 });
+  });
+
+  test('works with nested providers (gets nearest)', () => {
+    const ctx = createContext<string>('test');
+    let contextValue: string | undefined;
+
+    render(() => (
+      <ContextProtocolProvider context={ctx} value='outer'>
+        <ContextProtocolProvider context={ctx} value='inner'>
+          {(() => {
+            const value = useWebComponentContext(ctx);
+            contextValue = value();
+            return <div>Test</div>;
+          })()}
+        </ContextProtocolProvider>
+      </ContextProtocolProvider>
+    ));
+
+    expect(contextValue).toBe('inner');
+  });
+
+  test('different contexts do not interfere', () => {
+    const ctx1 = createContext<string>('ctx1');
+    const ctx2 = createContext<number>('ctx2');
+    let value1: string | undefined;
+    let value2: number | undefined;
+
+    render(() => (
+      <ContextProtocolProvider context={ctx1} value='string-value'>
+        <ContextProtocolProvider context={ctx2} value={123}>
+          {(() => {
+            const v1 = useWebComponentContext(ctx1);
+            const v2 = useWebComponentContext(ctx2);
+            value1 = v1();
+            value2 = v2();
+            return <div>Test</div>;
+          })()}
+        </ContextProtocolProvider>
+      </ContextProtocolProvider>
+    ));
+
+    expect(value1).toBe('string-value');
+    expect(value2).toBe(123);
+  });
+
+  test('signal updates reactively in JSX', async () => {
+    const ctx = createContext<number>('counter');
+    const [count, setCount] = createSignal(0);
+
+    // Use a proper component pattern instead of IIFE
+    const Consumer = () => {
+      const value = useWebComponentContext(ctx, { subscribe: true });
+      return <div data-testid='display'>{value()}</div>;
+    };
+
+    const { findByTestId } = render(() => (
+      <ContextProtocolProvider context={ctx} value={count}>
+        <Consumer />
+      </ContextProtocolProvider>
+    ));
+
+    const display = await findByTestId('display');
+    expect(display.textContent).toBe('0');
+
+    // Update the value
+    setCount(42);
+
+    // Wait for the DOM to update
+    await waitFor(() => {
+      expect(display.textContent).toBe('42');
+    });
+  });
+});

package/src/consumer.ts

@@ -0,0 +1,102 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Accessor, createSignal, onCleanup } from 'solid-js';
+
+import { ContextRequestEvent, type ContextType, type UnknownContext } from '@dxos/web-context';
+
+import { getHostElement } from './internal';
+import { getContextRequestHandler } from './provider';
+
+/**
+ * Options for useWebComponentContext hook
+ */
+export interface UseWebComponentContextOptions {
+  /**
+   * Whether to subscribe to context updates.
+   * If true, the returned signal will update when the provider's value changes.
+   * Default: false
+   */
+  subscribe?: boolean;
+
+  /**
+   * The element to dispatch the context-request event from.
+   * This is only used when there's no SolidJS provider in the tree.
+   * Default: document.body
+   */
+  element?: HTMLElement;
+}
+
+/**
+ * A SolidJS hook that requests context using the Web Component Context Protocol.
+ *
+ * This first tries to use the SolidJS context chain (for providers in the same
+ * SolidJS tree), then falls back to dispatching a DOM event (for web component
+ * providers).
+ *
+ * @param context - The context key to request
+ * @param options - Optional configuration
+ * @returns An accessor that returns the context value or undefined
+ *
+ * @example
+ * ```tsx
+ * const theme = useWebComponentContext(themeContext);
+ * return <div style={{ color: theme()?.primary }}>Hello</div>;
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Subscribe to updates
+ * const theme = useWebComponentContext(themeContext, { subscribe: true });
+ * return <div style={{ color: theme()?.primary }}>Hello</div>;
+ * ```
+ */
+export function useWebComponentContext<T extends UnknownContext>(
+  context: T,
+  options?: UseWebComponentContextOptions,
+): Accessor<ContextType<T> | undefined> {
+  const [value, setValue] = createSignal<ContextType<T> | undefined>(undefined);
+  let unsubscribeFn: (() => void) | undefined;
+
+  // Create callback that updates our signal
+  const callback = (newValue: ContextType<T>, unsubscribe?: () => void): void => {
+    setValue(() => newValue);
+    // Store the latest unsubscribe function
+    if (unsubscribe) {
+      unsubscribeFn = unsubscribe;
+    }
+  };
+
+  // Determine the target element for the context request
+  // Use: 1) explicit element option, 2) host element from custom element context, 3) document.body
+  const hostElement = getHostElement();
+  const targetElement = options?.element ?? hostElement ?? document.body;
+
+  // Create the context request event with contextTarget for proper re-parenting support
+  const event = new ContextRequestEvent(context, callback, {
+    subscribe: options?.subscribe,
+    target: targetElement,
+  });
+
+  // First, try to handle via SolidJS context chain (synchronous)
+  const handler = getContextRequestHandler();
+  let handled = false;
+
+  if (handler) {
+    handled = handler(event);
+  }
+
+  // If not handled by SolidJS providers, try DOM event dispatch
+  if (!handled) {
+    targetElement.dispatchEvent(event);
+  }
+
+  // Cleanup: unsubscribe when component unmounts
+  // Cleanup: unsubscribe when component unmounts
+  onCleanup(() => {
+    unsubscribeFn?.();
+  });
+
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from '@dxos/web-context';
+
+export * from './consumer';
+export * from './provider';
+export * from './solid-element';

package/src/internal.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext as createSolidContext, useContext } from 'solid-js';
+
+/**
+ * Internal SolidJS context for passing the host element to nested components.
+ * This allows useWebComponentContext to dispatch events from the custom element.
+ */
+export const HostElementContext = createSolidContext<HTMLElement | undefined>();
+
+/**
+ * Get the host custom element from SolidJS context.
+ * Used internally by useWebComponentContext when called from a custom element.
+ */
+export function getHostElement(): HTMLElement | undefined {
+  return useContext(HostElementContext);
+}

package/src/provider.test.tsx

@@ -0,0 +1,254 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { cleanup, render } from '@solidjs/testing-library';
+import { createSignal } from 'solid-js';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import { CONTEXT_REQUEST_EVENT, ContextRequestEvent, createContext } from '@dxos/web-context';
+
+import { ContextProtocolProvider } from './provider';
+
+describe('ContextProtocolProvider', () => {
+  // Clean up after each test
+  afterEach(() => {
+    cleanup();
+  });
+
+  test('renders children', () => {
+    const ctx = createContext<string>('test');
+
+    const { getByText } = render(() => (
+      <ContextProtocolProvider context={ctx} value='hello'>
+        <span>Child Content</span>
+      </ContextProtocolProvider>
+    ));
+
+    expect(getByText('Child Content')).toBeInTheDocument();
+  });
+
+  test('responds to context-request events with matching context', async () => {
+    const ctx = createContext<string>('test');
+    const callback = vi.fn();
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={ctx} value='provided-value'>
+        <div data-testid='child'>Child</div>
+      </ContextProtocolProvider>
+    ));
+
+    const child = container.querySelector('[data-testid="child"]')!;
+    const event = new ContextRequestEvent(ctx, callback, { target: child });
+    child.dispatchEvent(event);
+
+    expect(callback).toHaveBeenCalledWith('provided-value');
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  test('ignores context-request events with non-matching context', () => {
+    const ctx1 = createContext<string>('ctx1');
+    const ctx2 = createContext<string>('ctx2');
+    const callback = vi.fn();
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={ctx1} value='value1'>
+        <div data-testid='child'>Child</div>
+      </ContextProtocolProvider>
+    ));
+
+    const child = container.querySelector('[data-testid="child"]')!;
+    const event = new ContextRequestEvent(ctx2, callback, { target: child });
+    child.dispatchEvent(event);
+
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  test('stops immediate propagation when handling request', () => {
+    const ctx = createContext<string>('test');
+    const callback = vi.fn();
+    const outerHandler = vi.fn();
+
+    const { container } = render(() => (
+      <div>
+        <ContextProtocolProvider context={ctx} value='inner-value'>
+          <div data-testid='child'>Child</div>
+        </ContextProtocolProvider>
+      </div>
+    ));
+
+    // Add outer listener
+    container.addEventListener(CONTEXT_REQUEST_EVENT, outerHandler);
+
+    const child = container.querySelector('[data-testid="child"]')!;
+    const event = new ContextRequestEvent(ctx, callback, { target: child });
+    child.dispatchEvent(event);
+
+    expect(callback).toHaveBeenCalledWith('inner-value');
+    expect(outerHandler).not.toHaveBeenCalled();
+
+    container.removeEventListener(CONTEXT_REQUEST_EVENT, outerHandler);
+  });
+
+  test('provides unsubscribe callback for subscriptions', () => {
+    const ctx = createContext<number>('counter');
+    const callback = vi.fn();
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={ctx} value={42}>
+        <div data-testid='child'>Child</div>
+      </ContextProtocolProvider>
+    ));
+
+    const child = container.querySelector('[data-testid="child"]')!;
+    const event = new ContextRequestEvent(ctx, callback, { subscribe: true, target: child });
+    child.dispatchEvent(event);
+
+    expect(callback).toHaveBeenCalledWith(42, expect.any(Function));
+  });
+
+  test('does not provide unsubscribe for non-subscription requests', () => {
+    const ctx = createContext<number>('counter');
+    const callback = vi.fn();
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={ctx} value={42}>
+        <div data-testid='child'>Child</div>
+      </ContextProtocolProvider>
+    ));
+
+    const child = container.querySelector('[data-testid="child"]')!;
+    const event = new ContextRequestEvent(ctx, callback, { subscribe: false, target: child });
+    child.dispatchEvent(event);
+
+    // Should be called with just the value (no unsubscribe)
+    expect(callback).toHaveBeenCalledWith(42);
+    expect(callback.mock.calls[0].length).toBe(1);
+  });
+
+  test('notifies subscribers when value changes (reactive accessor)', async () => {
+    const ctx = createContext<number>('counter');
+    const callback = vi.fn();
+    const [count, setCount] = createSignal(0);
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={ctx} value={count}>
+        <div data-testid='child'>Child</div>
+      </ContextProtocolProvider>
+    ));
+
+    const child = container.querySelector('[data-testid="child"]')!;
+    const event = new ContextRequestEvent(ctx, callback, { subscribe: true, target: child });
+    child.dispatchEvent(event);
+
+    expect(callback).toHaveBeenCalledWith(0, expect.any(Function));
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    // Update the value
+    setCount(1);
+
+    // Wait for effect to run
+    await Promise.resolve();
+
+    expect(callback).toHaveBeenCalledWith(1, expect.any(Function));
+    expect(callback).toHaveBeenCalledTimes(2);
+
+    // Update again
+    setCount(2);
+    await Promise.resolve();
+
+    expect(callback).toHaveBeenCalledWith(2, expect.any(Function));
+    expect(callback).toHaveBeenCalledTimes(3);
+  });
+
+  test('unsubscribe stops updates', async () => {
+    const ctx = createContext<number>('counter');
+    const callback = vi.fn();
+    const [count, setCount] = createSignal(0);
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={ctx} value={count}>
+        <div data-testid='child'>Child</div>
+      </ContextProtocolProvider>
+    ));
+
+    const child = container.querySelector('[data-testid="child"]')!;
+
+    let unsubscribeFn: (() => void) | undefined;
+    const wrappedCallback = (value: number, unsubscribe?: () => void) => {
+      callback(value, unsubscribe);
+      unsubscribeFn = unsubscribe;
+    };
+
+    const event = new ContextRequestEvent(ctx, wrappedCallback, { subscribe: true, target: child });
+    child.dispatchEvent(event);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    // Unsubscribe
+    unsubscribeFn!();
+
+    // Update the value
+    setCount(1);
+    await Promise.resolve();
+
+    // Should not have received update
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  test('nested providers - inner provider handles matching context', () => {
+    const ctx = createContext<string>('test');
+    const callback = vi.fn();
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={ctx} value='outer'>
+        <ContextProtocolProvider context={ctx} value='inner'>
+          <div data-testid='child'>Child</div>
+        </ContextProtocolProvider>
+      </ContextProtocolProvider>
+    ));
+
+    const child = container.querySelector('[data-testid="child"]')!;
+    const event = new ContextRequestEvent(ctx, callback, { target: child });
+    child.dispatchEvent(event);
+
+    expect(callback).toHaveBeenCalledWith('inner');
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  test('multiple contexts can be provided simultaneously', () => {
+    const themeCtx = createContext<string>('theme');
+    const userCtx = createContext<{ name: string }>('user');
+    const themeCallback = vi.fn();
+    const userCallback = vi.fn();
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={themeCtx} value='dark'>
+        <ContextProtocolProvider context={userCtx} value={{ name: 'Alice' }}>
+          <div data-testid='child'>Child</div>
+        </ContextProtocolProvider>
+      </ContextProtocolProvider>
+    ));
+
+    const child = container.querySelector('[data-testid="child"]')!;
+
+    child.dispatchEvent(new ContextRequestEvent(themeCtx, themeCallback, { target: child }));
+    child.dispatchEvent(new ContextRequestEvent(userCtx, userCallback, { target: child }));
+
+    expect(themeCallback).toHaveBeenCalledWith('dark');
+    expect(userCallback).toHaveBeenCalledWith({ name: 'Alice' });
+  });
+
+  test('wrapper div uses display: contents', () => {
+    const ctx = createContext<string>('test');
+
+    const { container } = render(() => (
+      <ContextProtocolProvider context={ctx} value='value'>
+        <span>Child</span>
+      </ContextProtocolProvider>
+    ));
+
+    const wrapperDiv = container.querySelector('div');
+    expect(wrapperDiv).toHaveStyle({ display: 'contents' });
+  });
+});

package/src/provider.tsx

@@ -0,0 +1,272 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import {
+  type Accessor,
+  type JSX,
+  createEffect,
+  createContext as createSolidContext,
+  onCleanup,
+  onMount,
+  useContext,
+} from 'solid-js';
+
+import {
+  CONTEXT_PROVIDER_EVENT,
+  CONTEXT_REQUEST_EVENT,
+  type ContextCallback,
+  ContextProviderEvent,
+  ContextRequestEvent,
+  type ContextType,
+  type UnknownContext,
+} from '@dxos/web-context';
+
+/**
+ * Handler function type for context requests passed via SolidJS context
+ */
+type ContextRequestHandler = (event: ContextRequestEvent<UnknownContext>) => boolean;
+
+/**
+ * Internal SolidJS context for passing context request handlers down the tree.
+ * This allows useWebComponentContext to work synchronously in SolidJS.
+ */
+const ContextRequestHandlerContext = createSolidContext<ContextRequestHandler | undefined>();
+
+/**
+ * Try to handle a context request using the SolidJS context chain.
+ * Returns true if handled, false otherwise.
+ * Used internally by useWebComponentContext.
+ */
+export function tryHandleContextRequest(event: ContextRequestEvent<UnknownContext>): boolean {
+  const handler = useContext(ContextRequestHandlerContext);
+  if (handler) {
+    return handler(event);
+  }
+  return false;
+}
+
+/**
+ * Get the context request handler from SolidJS context.
+ * Used internally by useWebComponentContext.
+ */
+export function getContextRequestHandler(): ContextRequestHandler | undefined {
+  return useContext(ContextRequestHandlerContext);
+}
+
+/**
+ * Props for the ContextProtocolProvider component
+ */
+export interface ContextProtocolProviderProps<T extends UnknownContext> {
+  /** The context key to provide */
+  context: T;
+  /** The value to provide - can be a static value or an accessor for reactive updates */
+  value: ContextType<T> | Accessor<ContextType<T>>;
+  /** Child elements */
+  children: JSX.Element;
+}
+
+/**
+ * A provider component that:
+ * 1. Handles context-request events from web components (via DOM events)
+ * 2. Handles context requests from SolidJS consumers (via SolidJS context)
+ * 3. Supports subscriptions for reactive updates
+ * 4. Uses WeakRef for subscriptions to prevent memory leaks
+ */
+export function ContextProtocolProvider<T extends UnknownContext>(props: ContextProtocolProviderProps<T>): JSX.Element {
+  // Get parent handler if one exists (for nested providers)
+  const parentHandler = useContext(ContextRequestHandlerContext);
+
+  // Track subscriptions with their stable unsubscribe functions and consumer host elements
+  // We use WeakMap to hold callbacks weakly. This ensures that if a consumer
+  // drops the callback, we don't leak memory.
+  //
+  // NOTE: This means consumers MUST retain the callback reference as long as they
+  // want to receive updates (e.g. implicitly via closure in a retained component).
+  interface SubscriptionInfo {
+    unsubscribe: () => void;
+    consumerHost: Element;
+    // Store ref to allow cleaning up the Set when unsubscribing
+    ref: WeakRef<ContextCallback<ContextType<T>>>;
+  }
+  const subscriptions = new WeakMap<ContextCallback<ContextType<T>>, SubscriptionInfo>();
+  const subscriptionRefs = new Set<WeakRef<ContextCallback<ContextType<T>>>>();
+
+  // Helper to get current value (handles both static and accessor)
+  const getValue = (): ContextType<T> => {
+    const v = props.value;
+    return typeof v === 'function' ? (v as Accessor<ContextType<T>>)() : v;
+  };
+
+  // Core handler logic - used by both DOM events and SolidJS context
+  const handleRequest = (event: ContextRequestEvent<UnknownContext>): boolean => {
+    // Check if this provider handles this context (strict equality per spec)
+    if (event.context !== props.context) {
+      // Pass to parent handler if we don't handle this context
+      if (parentHandler) {
+        return parentHandler(event);
+      }
+      return false;
+    }
+
+    const currentValue = getValue();
+
+    if (event.subscribe) {
+      // Store the callback for future updates
+      const callback = event.callback as ContextCallback<ContextType<T>>;
+
+      // Get the consumer host element from the event
+      // Fallback to composedPath()[0] if contextTarget is missing (standard compliance)
+      const consumerHost = event.contextTarget || (event.composedPath()[0] as Element);
+
+      // Create a stable unsubscribe function for this callback
+      // IMPORTANT: We must pass the SAME unsubscribe function each time we call the callback
+      // Lit's ContextConsumer compares unsubscribe functions and calls the old one if different
+      const unsubscribe = () => {
+        const info = subscriptions.get(callback);
+        if (info) {
+          subscriptionRefs.delete(info.ref);
+          subscriptions.delete(callback);
+        }
+      };
+
+      const ref = new WeakRef(callback);
+      subscriptions.set(callback, { unsubscribe, consumerHost, ref });
+      subscriptionRefs.add(ref);
+
+      // Invoke callback with current value and unsubscribe function
+      event.callback(currentValue, unsubscribe);
+    } else {
+      // One-time request - just provide the value
+      event.callback(currentValue);
+    }
+
+    return true;
+  };
+
+  // Handle DOM context-request events (for web components)
+  const handleContextRequestEvent = (e: Event) => {
+    const event = e as ContextRequestEvent<UnknownContext>;
+    if (handleRequest(event)) {
+      // Stop propagation per spec recommendation
+      event.stopImmediatePropagation();
+    }
+  };
+
+  // Handle context-provider events from child providers
+  // When a new provider appears below us, we re-dispatch our subscriptions
+  // so consumers can re-parent to the closer provider
+  const handleContextProviderEvent = (e: Event) => {
+    const event = e as ContextProviderEvent<UnknownContext>;
+
+    // Only handle events for our context
+    if (event.context !== props.context) {
+      return;
+    }
+
+    // Don't handle our own event
+    if (containerRef && event.contextTarget === containerRef) {
+      return;
+    }
+
+    // Re-dispatch context requests from our subscribers
+    // They may now have a closer provider
+    // Iterate over weak refs to re-dispatch
+    // We use a separate Set of WeakRefs because WeakMap is not iterable.
+    // This allows us to re-parent subscriptions when a new provider appears.
+    const seen = new Set<ContextCallback<ContextType<T>>>();
+    for (const ref of subscriptionRefs) {
+      const callback = ref.deref();
+      if (!callback) {
+        subscriptionRefs.delete(ref);
+        continue;
+      }
+
+      const info = subscriptions.get(callback);
+      if (!info) continue;
+
+      const { consumerHost } = info;
+
+      // Prevent infinite loops with duplicate callbacks
+      if (seen.has(callback)) {
+        continue;
+      }
+      seen.add(callback);
+
+      // Re-dispatch the context request from the consumer
+      // We explicitly pass the original consumerHost as the target to preserve the causal chain
+      consumerHost.dispatchEvent(
+        new ContextRequestEvent(props.context, callback, { subscribe: true, target: consumerHost }),
+      );
+    }
+
+    // Stop propagation - we've handled the re-parenting
+    event.stopPropagation();
+  };
+
+  // Set up effect to notify subscribers when value changes
+  let isFirstRun = true;
+  createEffect(() => {
+    // IMPORTANT: We must call the accessor DIRECTLY inside the effect to establish tracking
+    // Reading props.value gives us the accessor, then we must call it to track the signal
+    const v = props.value;
+    const newValue = typeof v === 'function' ? (v as Accessor<ContextType<T>>)() : v;
+
+    // Skip first run - only notify on changes after initial subscription
+    if (isFirstRun) {
+      isFirstRun = false;
+      return;
+    }
+
+    // Notify all subscribers with their stable unsubscribe functions
+    for (const ref of subscriptionRefs) {
+      const callback = ref.deref();
+      if (!callback) {
+        subscriptionRefs.delete(ref);
+        continue;
+      }
+
+      const info = subscriptions.get(callback);
+      if (info) {
+        callback(newValue, info.unsubscribe);
+      }
+    }
+  });
+
+  // Reference to container element for event listener
+  let containerRef: HTMLDivElement | undefined;
+
+  // Set up event listeners when element is created
+  const setupListeners = (el: HTMLDivElement) => {
+    containerRef = el;
+    el.addEventListener(CONTEXT_REQUEST_EVENT, handleContextRequestEvent);
+    el.addEventListener(CONTEXT_PROVIDER_EVENT, handleContextProviderEvent);
+  };
+
+  // Announce this provider when mounted
+  // This allows ContextRoot implementations to replay pending requests
+  // and allows parent providers to re-parent their subscriptions
+  onMount(() => {
+    if (containerRef) {
+      containerRef.dispatchEvent(new ContextProviderEvent(props.context, containerRef));
+    }
+  });
+
+  // Cleanup on unmount
+  onCleanup(() => {
+    if (containerRef) {
+      containerRef.removeEventListener(CONTEXT_REQUEST_EVENT, handleContextRequestEvent);
+      containerRef.removeEventListener(CONTEXT_PROVIDER_EVENT, handleContextProviderEvent);
+    }
+    // WeakMap clears itself, but we should clear the Set of refs
+    subscriptionRefs.clear();
+  });
+
+  return (
+    <ContextRequestHandlerContext.Provider value={handleRequest}>
+      <div ref={setupListeners} style={{ display: 'contents' }}>
+        {props.children}
+      </div>
+    </ContextRequestHandlerContext.Provider>
+  );
+}

package/src/solid-element.tsx

@@ -0,0 +1,84 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { ComponentType } from 'solid-element';
+import type { JSX } from 'solid-js';
+
+import { HostElementContext } from './internal';
+
+/**
+ * Integration utilities for using Web Component Context Protocol with solid-element.
+ *
+ * This module provides utilities to integrate our context protocol implementation
+ * with the solid-element library for creating web components.
+ *
+ * @example
+ * ```tsx
+ * import { customElement } from 'solid-element';
+ * import { withContextProvider } from './context/solid-element';
+ *
+ * customElement('my-button', {}, withContextProvider((props, { element }) => {
+ *   const theme = useWebComponentContext(themeContext, { subscribe: true });
+ *   return <button style={{ background: theme()?.primary }}>Click me</button>;
+ * }));
+ * ```
+ */
+
+/**
+ * Options passed by solid-element to component functions.
+ * The element extends HTMLElement with additional custom element methods.
+ */
+export interface SolidElementOptions {
+  element: HTMLElement & {
+    renderRoot: Element | Document | ShadowRoot | DocumentFragment;
+    addReleaseCallback(fn: () => void): void;
+    addPropertyChangedCallback(fn: (name: string, value: unknown) => void): void;
+  };
+}
+
+/**
+ * Function component type for solid-element.
+ * Receives props and an options object containing the host element.
+ */
+export type SolidElementComponent<P extends object = object> = (props: P, options: SolidElementOptions) => JSX.Element;
+
+/**
+ * Wraps a solid-element component to provide the host element context.
+ * This enables useWebComponentContext to dispatch events from the custom element
+ * rather than document.body.
+ *
+ * @param component - The solid-element component function
+ * @returns A wrapped component that provides HostElementContext
+ *
+ * @example
+ * ```tsx
+ * import { customElement } from 'solid-element';
+ * import { withContextProvider, useWebComponentContext } from './context';
+ *
+ * customElement('themed-button', {}, withContextProvider((props, { element }) => {
+ *   const theme = useWebComponentContext(themeContext, { subscribe: true });
+ *   return (
+ *     <button style={{ background: theme()?.primary }}>
+ *       Themed Button
+ *     </button>
+ *   );
+ * }));
+ * ```
+ */
+export function withContextProvider<P extends object>(component: SolidElementComponent<P>): ComponentType<P> {
+  // Return a new component function that wraps the original with HostElementContext
+  // This enables useWebComponentContext to dispatch events from the custom element
+  const wrappedComponent = (props: P, options: SolidElementOptions) => {
+    // Create a child component that renders within the context
+    const WrappedContent = () => component(props, options);
+
+    return (
+      <HostElementContext.Provider value={options.element}>
+        <WrappedContent />
+      </HostElementContext.Provider>
+    );
+  };
+
+  return wrappedComponent as unknown as ComponentType<P>;
+}