@stackable-labs/sdk-extension-host 1.0.0

package/LICENSE

@@ -0,0 +1,29 @@
+LICENSE
+
+Copyright (c) 2026-present UNIQUELY PARTICULAR LLC, STACKABLE LABS, LLC, agnoStack, Inc., and Adam Grohs ("Author" herein)
+
+Permission is hereby granted to use, copy, and modify this software
+(the "Software") solely for the purpose of developing, testing,
+or maintaining integration with Author's products and services.
+
+The Software may not be used:
+- as a standalone product or service,
+- to integrate with any platform or service other than Author's,
+- to build or enhance a competing product or service,
+- or for any purpose unrelated to integrations with Author.
+
+Redistribution of the Software, in whole or in part, is permitted
+only as part of an application or service that integrates with Author
+and does not expose the Software as a general-purpose library.
+
+This 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.
+
+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
+PUBLISHER, AUTHORS, ANY CONTRIBUTOR 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,53 @@
+# @stackable-labs/sdk-extension-host
+
+Host-side SDK for creating an app that allows embeddable slots via Stackable extensions.
+
+## Installation
+
+```bash
+npm install @stackable-labs/sdk-extension-host
+```
+
+## Peer dependencies
+
+```
+react >= 18.0.0 < 19.0.0
+react-dom >= 18.0.0 < 19.0.0
+```
+
+## Usage
+
+Wrap your app with `ExtensionProvider` and place `ExtensionSlot` wherever extension UI should appear:
+
+```tsx
+import { ExtensionProvider, ExtensionSlot, registerComponents } from '@stackable-labs/sdk-extension-host';
+
+// Register host components once at app startup (before any ExtensionSlot renders)
+registerComponents({ 'ui-button': Button, 'ui-text': Text });
+
+function App() {
+  return (
+    <ExtensionProvider extensions={extensions} capabilityHandlers={handlers}>
+      <ExtensionSlot target="slot.header" />
+      <MainContent />
+      <ExtensionSlot target="slot.content" />
+    </ExtensionProvider>
+  );
+}
+```
+
+## Key exports
+
+- **`ExtensionProvider`** — React context provider; manages extension sandboxes
+- **`ExtensionSlot`** — renders extension-produced UI into a named host slot
+- **`registerComponents`** — register allowed host components extensions may render
+- **`CapabilityRPCHandler`** — handles capability requests from extension sandboxes
+- **`SandboxManager`** — creates and destroys hidden iframe sandboxes per extension
+
+## Changelog
+
+See [npm version history](https://www.npmjs.com/package/@stackable-labs/sdk-extension-host?activeTab=versions).
+
+## License
+
+SEE LICENSE IN [LICENSE](./LICENSE)

package/dist/CapabilityRPCHandler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CapabilityRPCHandler — receives capability calls from sandbox,
+ * enforces permissions, and executes them on the host side.
+ */
+import type { ApiRequest, ToastPayload, ActionInvokePayload } from '@stackable-labs/sdk-extension-contracts';
+export interface CapabilityHandlers {
+    'data.query': (payload: ApiRequest) => Promise<unknown>;
+    'actions.toast': (payload: ToastPayload) => Promise<void>;
+    'actions.invoke': (payload: ActionInvokePayload) => Promise<unknown>;
+    'context.read': () => Promise<Record<string, unknown>>;
+}
+/**
+ * Create an RPC handler that listens for capability requests from sandboxes.
+ */
+export declare const createCapabilityRPCHandler: (handlers: CapabilityHandlers) => () => void;

package/dist/CapabilityRPCHandler.js

@@ -0,0 +1,85 @@
+/**
+ * CapabilityRPCHandler — receives capability calls from sandbox,
+ * enforces permissions, and executes them on the host side.
+ */
+import { CAPABILITY_PERMISSION_MAP } from '@stackable-labs/sdk-extension-contracts';
+import { getAllSandboxes, getSandbox, postToSandbox } from './SandboxManager';
+/**
+ * Create an RPC handler that listens for capability requests from sandboxes.
+ */
+export const createCapabilityRPCHandler = (handlers) => {
+    const handleMessage = async (event) => {
+        const msg = event.data;
+        if (msg?.type !== 'capability-request')
+            return;
+        const request = msg;
+        // Find which sandbox sent this request
+        let extensionId = null;
+        for (const [id, sandbox] of getAllSandboxes()) {
+            if (event.source === sandbox.iframe.contentWindow) {
+                extensionId = id;
+                break;
+            }
+        }
+        if (!extensionId) {
+            console.warn('Received capability request from unknown source');
+            return;
+        }
+        const sandbox = getSandbox(extensionId);
+        if (!sandbox)
+            return;
+        // Check permissions
+        const requiredPermission = CAPABILITY_PERMISSION_MAP[request.capability];
+        if (requiredPermission && !sandbox.manifest.permissions.includes(requiredPermission)) {
+            const response = {
+                type: 'capability-response',
+                id: request.id,
+                success: false,
+                error: `Permission denied: '${requiredPermission}' not granted for extension '${extensionId}'`,
+            };
+            postToSandbox(extensionId, response);
+            return;
+        }
+        // Execute the capability
+        try {
+            let result;
+            switch (request.capability) {
+                case 'data.query':
+                    result = await handlers['data.query'](request.payload);
+                    break;
+                case 'actions.toast':
+                    result = await handlers['actions.toast'](request.payload);
+                    break;
+                case 'actions.invoke':
+                    result = await handlers['actions.invoke'](request.payload);
+                    break;
+                case 'context.read':
+                    result = await handlers['context.read']();
+                    break;
+                default:
+                    throw new Error(`Unknown capability: ${request.capability}`);
+            }
+            const response = {
+                type: 'capability-response',
+                id: request.id,
+                success: true,
+                data: result,
+            };
+            postToSandbox(extensionId, response);
+        }
+        catch (err) {
+            const response = {
+                type: 'capability-response',
+                id: request.id,
+                success: false,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            };
+            postToSandbox(extensionId, response);
+        }
+    };
+    window.addEventListener('message', handleMessage);
+    return () => {
+        window.removeEventListener('message', handleMessage);
+    };
+};
+//# sourceMappingURL=CapabilityRPCHandler.js.map

package/dist/CapabilityRPCHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityRPCHandler.js","sourceRoot":"","sources":["../src/CapabilityRPCHandler.ts"],"names":[],"mappings":"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"}

package/dist/ComponentRegistry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ComponentRegistry — maps Remote DOM custom element tags to host React components.
+ * Unknown tags are rejected (dropped or replaced with a warning stub).
+ */
+import type { UITag } from '@stackable-labs/sdk-extension-contracts';
+type ComponentMap = Map<string, React.ComponentType<Record<string, unknown>>>;
+/**
+ * Register a host React component for a UI tag.
+ */
+export declare const registerComponent: (tag: UITag, component: React.ComponentType<Record<string, unknown>>) => void;
+/**
+ * Register multiple components at once.
+ */
+export declare const registerComponents: (components: Partial<Record<UITag, React.ComponentType<Record<string, unknown>>>>) => void;
+/**
+ * Check if a tag is in the UI contract.
+ */
+export declare const isValidTag: (tag: string) => tag is UITag;
+/**
+ * Look up the host component for a given tag.
+ * Returns undefined if the tag is not in the contract (unknown tag → rejected).
+ */
+export declare const getComponent: (tag: string) => React.ComponentType<Record<string, unknown>> | undefined;
+/**
+ * Get all registered components.
+ */
+export declare const getRegistry: () => ComponentMap;
+export {};

package/dist/ComponentRegistry.js

@@ -0,0 +1,43 @@
+/**
+ * ComponentRegistry — maps Remote DOM custom element tags to host React components.
+ * Unknown tags are rejected (dropped or replaced with a warning stub).
+ */
+import { UI_TAGS } from '@stackable-labs/sdk-extension-contracts';
+const registry = new Map();
+/**
+ * Register a host React component for a UI tag.
+ */
+export const registerComponent = (tag, component) => {
+    registry.set(tag, component);
+};
+/**
+ * Register multiple components at once.
+ */
+export const registerComponents = (components) => {
+    for (const [tag, component] of Object.entries(components)) {
+        if (component) {
+            registry.set(tag, component);
+        }
+    }
+};
+/**
+ * Check if a tag is in the UI contract.
+ */
+export const isValidTag = (tag) => UI_TAGS.includes(tag);
+/**
+ * Look up the host component for a given tag.
+ * Returns undefined if the tag is not in the contract (unknown tag → rejected).
+ */
+export const getComponent = (tag) => {
+    // Only allow tags that are in the contract
+    if (!isValidTag(tag)) {
+        console.warn(`[ExtensionHost] Unknown UI tag rejected: <${tag}>`);
+        return undefined;
+    }
+    return registry.get(tag);
+};
+/**
+ * Get all registered components.
+ */
+export const getRegistry = () => registry;
+//# sourceMappingURL=ComponentRegistry.js.map

package/dist/ComponentRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentRegistry.js","sourceRoot":"","sources":["../src/ComponentRegistry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAA;AAIjE,MAAM,QAAQ,GAAiB,IAAI,GAAG,EAAE,CAAA;AAExC;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAU,EAAE,SAAuD,EAAQ,EAAE;IAC7G,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;AAC9B,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,UAAgF,EAAQ,EAAE;IAC3H,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1D,IAAI,SAAS,EAAE,CAAC;YACd,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;QAC9B,CAAC;IACH,CAAC;AACH,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAW,EAAgB,EAAE,CAAE,OAA6B,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;AAErG;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAW,EAA4D,EAAE;IACpG,2CAA2C;IAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,6CAA6C,GAAG,GAAG,CAAC,CAAA;QACjE,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAC1B,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAiB,EAAE,CAAC,QAAQ,CAAA"}

package/dist/ExtensionProvider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ExtensionProvider — React context provider that manages extension sandboxes.
+ * Place at the app root so runtimes persist across navigation.
+ */
+import React from 'react';
+import type { ExtensionRegistryEntry } from '@stackable-labs/sdk-extension-contracts';
+import type { CapabilityHandlers } from './CapabilityRPCHandler';
+interface ExtensionProviderContextValue {
+    extensions: ExtensionRegistryEntry[];
+    ready: boolean;
+}
+interface ExtensionProviderProps {
+    extensions: ExtensionRegistryEntry[];
+    capabilityHandlers: CapabilityHandlers;
+    children: React.ReactNode;
+}
+export declare const ExtensionProvider: ({ extensions, capabilityHandlers, children, }: ExtensionProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const useExtensionProvider: () => ExtensionProviderContextValue;
+export {};

package/dist/ExtensionProvider.js

@@ -0,0 +1,55 @@
+/**
+ * ExtensionProvider — React context provider that manages extension sandboxes.
+ * Place at the app root so runtimes persist across navigation.
+ */
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useRef, useState } from 'react';
+import { createSandbox, destroySandbox } from './SandboxManager';
+import { createCapabilityRPCHandler } from './CapabilityRPCHandler';
+const ExtensionProviderContext = createContext({
+    extensions: [],
+    ready: false,
+});
+export const ExtensionProvider = ({ extensions, capabilityHandlers, children, }) => {
+    const [ready, setReady] = useState(false);
+    const sandboxContainerRef = useRef(null);
+    const cleanupRef = useRef(null);
+    useEffect(() => {
+        if (!sandboxContainerRef.current)
+            return;
+        let cancelled = false;
+        const init = async () => {
+            const container = sandboxContainerRef.current;
+            if (!container)
+                return;
+            console.log('[ExtensionProvider] Initializing with', extensions.length, 'extensions');
+            // Create sandboxes for each enabled extension
+            for (const ext of extensions) {
+                if (ext.enabled && !cancelled) {
+                    console.log('[ExtensionProvider] Creating sandbox for', ext.id, 'bundleUrl:', ext.bundleUrl);
+                    await createSandbox(ext, container);
+                    console.log('[ExtensionProvider] Sandbox created for', ext.id);
+                }
+            }
+            // Set up the capability RPC handler
+            cleanupRef.current = createCapabilityRPCHandler(capabilityHandlers);
+            if (!cancelled) {
+                console.log('[ExtensionProvider] Ready');
+                setReady(true);
+            }
+        };
+        init();
+        return () => {
+            cancelled = true;
+            // Clean up sandboxes and RPC handler
+            for (const ext of extensions) {
+                destroySandbox(ext.id);
+            }
+            cleanupRef.current?.();
+        };
+    }, [extensions, capabilityHandlers]);
+    return (_jsxs(ExtensionProviderContext.Provider, { value: { extensions, ready }, children: [_jsx("div", { ref: sandboxContainerRef, style: { display: 'none' } }), children] }));
+};
+export const useExtensionProvider = () => useContext(ExtensionProviderContext);
+//# sourceMappingURL=ExtensionProvider.js.map

package/dist/ExtensionProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExtensionProvider.js","sourceRoot":"","sources":["../src/ExtensionProvider.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,CAAA;;AAEZ,OAAc,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAErF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAQnE,MAAM,wBAAwB,GAAG,aAAa,CAAgC;IAC5E,UAAU,EAAE,EAAE;IACd,KAAK,EAAE,KAAK;CACb,CAAC,CAAA;AAQF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,EAChC,UAAU,EACV,kBAAkB,EAClB,QAAQ,GACe,EAAE,EAAE;IAC3B,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAU,KAAK,CAAC,CAAA;IAClD,MAAM,mBAAmB,GAAG,MAAM,CAAiB,IAAI,CAAC,CAAA;IACxD,MAAM,UAAU,GAAG,MAAM,CAAsB,IAAI,CAAC,CAAA;IAEpD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,mBAAmB,CAAC,OAAO;YAAE,OAAM;QAExC,IAAI,SAAS,GAAG,KAAK,CAAA;QAErB,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE;YACtB,MAAM,SAAS,GAAG,mBAAmB,CAAC,OAAO,CAAA;YAC7C,IAAI,CAAC,SAAS;gBAAE,OAAM;YAEtB,OAAO,CAAC,GAAG,CAAC,uCAAuC,EAAE,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;YAErF,8CAA8C;YAC9C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;gBAC7B,IAAI,GAAG,CAAC,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;oBAC9B,OAAO,CAAC,GAAG,CAAC,0CAA0C,EAAE,GAAG,CAAC,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;oBAC5F,MAAM,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;oBACnC,OAAO,CAAC,GAAG,CAAC,yCAAyC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;gBAChE,CAAC;YACH,CAAC;YAED,oCAAoC;YACpC,UAAU,CAAC,OAAO,GAAG,0BAA0B,CAAC,kBAAkB,CAAC,CAAA;YAEnE,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;gBACxC,QAAQ,CAAC,IAAI,CAAC,CAAA;YAChB,CAAC;QACH,CAAC,CAAA;QAED,IAAI,EAAE,CAAA;QAEN,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAA;YAChB,qCAAqC;YACrC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;gBAC7B,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YACxB,CAAC;YACD,UAAU,CAAC,OAAO,EAAE,EAAE,CAAA;QACxB,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAA;IAEpC,OAAO,CACL,MAAC,wBAAwB,CAAC,QAAQ,IAAC,KAAK,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,aAE7D,cAAK,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAI,EAC5D,QAAQ,IACyB,CACrC,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,wBAAwB,CAAC,CAAA"}

package/dist/ExtensionSlot.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ExtensionSlot — renders the output of an extension surface at a specific target.
+ * The host places these in its layout where extension UI should appear.
+ *
+ * Receives serialized DOM trees from the extension via postMessage (cross-origin safe)
+ * and renders them using the host component registry.
+ */
+import React from 'react';
+interface ExtensionSlotProps {
+    /** The extension point target (e.g., "slot.header") */
+    target: string;
+    /** Optional context to pass to the surface */
+    context?: Record<string, unknown>;
+    /** Optional className for the slot container */
+    className?: string;
+    /** Optional fallback content when no extension output is available */
+    fallback?: React.ReactNode;
+    /** Optional wrapper for each extension's rendered content */
+    render?: (params: {
+        extensionId: string;
+        children: React.ReactNode;
+        index: number;
+        total: number;
+    }) => React.ReactNode;
+    /** Optional separator rendered between extension outputs */
+    separator?: React.ReactNode | ((params: {
+        index: number;
+        total: number;
+        previousExtensionId: string;
+        extensionId: string;
+    }) => React.ReactNode);
+}
+/**
+ * Renders extension UI for a given target.
+ * Listens for serialized DOM trees from the extension sandbox via postMessage.
+ */
+export declare const ExtensionSlot: ({ target, context, className, separator, fallback, render, }: ExtensionSlotProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/ExtensionSlot.js

@@ -0,0 +1,164 @@
+/**
+ * ExtensionSlot — renders the output of an extension surface at a specific target.
+ * The host places these in its layout where extension UI should appear.
+ *
+ * Receives serialized DOM trees from the extension via postMessage (cross-origin safe)
+ * and renders them using the host component registry.
+ */
+'use client';
+import { createElement as _createElement } from "react";
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { useEffect, useState, useCallback, useMemo, useRef } from 'react';
+import { useExtensionProvider } from './ExtensionProvider';
+import { getSandbox } from './SandboxManager';
+import { getComponent } from './ComponentRegistry';
+/**
+ * Renders extension UI for a given target.
+ * Listens for serialized DOM trees from the extension sandbox via postMessage.
+ */
+export const ExtensionSlot = ({ target, context, className, separator, fallback = null, render, }) => {
+    const { extensions, ready } = useExtensionProvider();
+    const [surfaceContentByExtension, setSurfaceContentByExtension] = useState({});
+    const previousMatchingIdsRef = useRef('');
+    // Find extensions that target this slot — stabilize reference by ID list
+    const matchingExtensions = useMemo(() => extensions.filter((ext) => ext.enabled && ext.manifest.targets.includes(target)), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [extensions.map((e) => e.id).join(','), target]);
+    const renderSerializedNode = useCallback((node, sourceWindow, key = 0) => {
+        if (node.type === 'text') {
+            return node.text || null;
+        }
+        if (!node.tag)
+            return null;
+        // Fragment wrapper from Surface serialization
+        if (node.tag === '__fragment') {
+            return (_jsx(React.Fragment, { children: node.children?.map((child, i) => renderSerializedNode(child, sourceWindow, i)) }, key));
+        }
+        const HostComponent = getComponent(node.tag);
+        if (!HostComponent) {
+            // Unknown tag — rejected by contract
+            if (node.tag.startsWith('ui-')) {
+                console.warn(`[ExtensionSlot] Unknown UI tag rejected: <${node.tag}>`);
+                return null;
+            }
+            // For non-ui tags, just render children
+            return (_jsx(React.Fragment, { children: node.children?.map((child, i) => renderSerializedNode(child, sourceWindow, i)) }, key));
+        }
+        const props = { ...node.attrs };
+        // Wire up click handler proxy if the node has an actionId
+        if (node.actionId) {
+            const actionId = node.actionId;
+            props.onClick = () => {
+                const postTarget = sourceWindow;
+                postTarget?.postMessage({ type: 'action-invoke', surfaceId: target, actionId }, '*');
+            };
+        }
+        // Wire up onChange handler proxy if the node has a data-onchange-id
+        if (props['data-onchange-id']) {
+            const onchangeId = props['data-onchange-id'];
+            delete props['data-onchange-id'];
+            props.onChange = (e) => {
+                const postTarget = sourceWindow;
+                postTarget?.postMessage({ type: 'action-invoke', surfaceId: target, actionId: onchangeId, value: e.target.value }, '*');
+            };
+        }
+        const children = node.children?.map((child, i) => renderSerializedNode(child, sourceWindow, i));
+        return (_createElement(HostComponent, { ...props, key: key }, children && children.length > 0 ? children : undefined));
+    }, [target]);
+    useEffect(() => {
+        const matchingIds = matchingExtensions.map((ext) => ext.id).join(',');
+        if (previousMatchingIdsRef.current !== matchingIds) {
+            previousMatchingIdsRef.current = matchingIds;
+            setSurfaceContentByExtension({});
+        }
+        if (!ready || matchingExtensions.length === 0)
+            return;
+        // Listen for surface-update messages from extension sandboxes
+        const handleMessage = (event) => {
+            const msg = event.data;
+            if (!msg || typeof msg !== 'object')
+                return;
+            // Verify the message comes from one of our sandboxes
+            const isFromSandbox = matchingExtensions.some((ext) => {
+                const sandbox = getSandbox(ext.id);
+                return sandbox && event.source === sandbox.iframe.contentWindow;
+            });
+            if (!isFromSandbox)
+                return;
+            if (msg.type === 'surface-update' && msg.surfaceId === target) {
+                const senderExtension = matchingExtensions.find((ext) => {
+                    const sandbox = getSandbox(ext.id);
+                    return sandbox && event.source === sandbox.iframe.contentWindow;
+                });
+                if (!senderExtension)
+                    return;
+                const rendered = renderSerializedNode(msg.tree, event.source ?? null);
+                setSurfaceContentByExtension((prev) => ({
+                    ...prev,
+                    [senderExtension.id]: rendered,
+                }));
+            }
+            if (msg.type === 'surface-ready' && msg.surfaceId === target) {
+                // Surface is ready, send initial context
+                if (context) {
+                    matchingExtensions.forEach((ext) => {
+                        const sandbox = getSandbox(ext.id);
+                        sandbox?.iframe.contentWindow?.postMessage({ type: 'context-update', surfaceId: target, context }, '*');
+                    });
+                }
+            }
+        };
+        window.addEventListener('message', handleMessage);
+        // Request the extension to re-send its current surface tree.
+        // This handles the case where the slot mounts after the extension
+        // has already sent its initial surface-update (e.g. widget popup).
+        // console.log(`[ExtensionSlot] Mounted for target="${target}", requesting re-send from ${matchingExtensions.length} extension(s)`);
+        matchingExtensions.forEach((ext) => {
+            const sandbox = getSandbox(ext.id);
+            sandbox?.iframe.contentWindow?.postMessage({ type: 'surface-render', surfaceId: target, context }, '*');
+        });
+        return () => {
+            window.removeEventListener('message', handleMessage);
+        };
+    }, [ready, matchingExtensions, target, context, renderSerializedNode]);
+    if (!ready) {
+        return null;
+    }
+    if (matchingExtensions.length === 0) {
+        return fallback ? (_jsx("div", { "data-extension-slot": target, title: target, className: className, children: fallback })) : null;
+    }
+    const extensionContent = matchingExtensions
+        .map((ext) => ({ id: ext.id, children: surfaceContentByExtension[ext.id] }))
+        .filter((entry) => Boolean(entry.children));
+    const content = extensionContent.length > 0
+        ? extensionContent.flatMap((entry, index, entries) => {
+            const renderedItem = render
+                ? render({
+                    extensionId: entry.id,
+                    children: entry.children,
+                    index,
+                    total: entries.length,
+                })
+                : _jsx(React.Fragment, { children: entry.children }, entry.id);
+            const item = _jsx(React.Fragment, { children: renderedItem }, `extension:${entry.id}`);
+            if (index === 0 || !separator) {
+                return [item];
+            }
+            const previous = entries[index - 1];
+            const separatorNode = typeof separator === 'function'
+                ? separator({
+                    index,
+                    total: entries.length,
+                    previousExtensionId: previous.id,
+                    extensionId: entry.id,
+                })
+                : separator;
+            return [
+                _jsx(React.Fragment, { children: separatorNode }, `separator:${previous.id}:${entry.id}:${index}`),
+                item
+            ];
+        })
+        : fallback;
+    return (_jsx("div", { "data-extension-slot": target, title: target, className: className, children: content }));
+};
+//# sourceMappingURL=ExtensionSlot.js.map

package/dist/ExtensionSlot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExtensionSlot.js","sourceRoot":"","sources":["../src/ExtensionSlot.tsx"],"names":[],"mappings":"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"}

package/dist/SandboxManager.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SandboxManager — creates and manages one iframe per extension per tab.
+ */
+import type { ExtensionRegistryEntry, HostToSandboxMessage, SandboxToHostMessage } from '@stackable-labs/sdk-extension-contracts';
+export interface SandboxInstance {
+    extensionId: string;
+    iframe: HTMLIFrameElement;
+    manifest: ExtensionRegistryEntry['manifest'];
+    ready: boolean;
+    messageHandlers: Set<(msg: SandboxToHostMessage) => void>;
+}
+/**
+ * Create a sandbox iframe for an extension and load its bundle.
+ *
+ * If bundleUrl is a full URL (http://...), uses iframe.src pointing to
+ * a sandbox HTML page on that origin (dev mode with Vite).
+ * If bundleUrl is a relative path, fetches the bundle and inlines it in srcdoc.
+ */
+export declare const createSandbox: (entry: ExtensionRegistryEntry, container: HTMLElement) => Promise<SandboxInstance>;
+/**
+ * Send a message to a sandbox.
+ */
+export declare const postToSandbox: (extensionId: string, message: HostToSandboxMessage) => void;
+/**
+ * Get a sandbox instance by extension ID.
+ */
+export declare const getSandbox: (extensionId: string) => SandboxInstance | undefined;
+/**
+ * Destroy a sandbox and clean up.
+ */
+export declare const destroySandbox: (extensionId: string) => void;
+/**
+ * Get all active sandbox instances.
+ */
+export declare const getAllSandboxes: () => Map<string, SandboxInstance>;

package/dist/SandboxManager.js

@@ -0,0 +1,102 @@
+/**
+ * SandboxManager — creates and manages one iframe per extension per tab.
+ */
+const sandboxes = new Map();
+/**
+ * Create a sandbox iframe for an extension and load its bundle.
+ *
+ * If bundleUrl is a full URL (http://...), uses iframe.src pointing to
+ * a sandbox HTML page on that origin (dev mode with Vite).
+ * If bundleUrl is a relative path, fetches the bundle and inlines it in srcdoc.
+ */
+export const createSandbox = async (entry, container) => {
+    const existing = sandboxes.get(entry.id);
+    if (existing)
+        return existing;
+    const iframe = document.createElement('iframe');
+    iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin');
+    iframe.style.display = 'none';
+    iframe.style.width = '0';
+    iframe.style.height = '0';
+    iframe.style.border = 'none';
+    const isAbsoluteUrl = entry.bundleUrl.startsWith('http');
+    if (isAbsoluteUrl) {
+        // Dev mode: point iframe.src to a sandbox page served by the extension's dev server
+        iframe.src = entry.bundleUrl;
+    }
+    else {
+        // Production mode: fetch bundle and inline it
+        let bundleCode = '';
+        try {
+            const res = await fetch(entry.bundleUrl);
+            bundleCode = await res.text();
+        }
+        catch (err) {
+            console.error(`[SandboxManager] Failed to fetch bundle for ${entry.id}:`, err);
+        }
+        const sandboxHtml = `
+      <!DOCTYPE html>
+      <html>
+        <head><meta charset="utf-8"></head>
+        <body>
+          <div id="extension-root"></div>
+          <script type="module">${bundleCode}</script>
+        </body>
+      </html>
+    `;
+        iframe.srcdoc = sandboxHtml;
+    }
+    container.appendChild(iframe);
+    const instance = {
+        extensionId: entry.id,
+        iframe,
+        manifest: entry.manifest,
+        ready: false,
+        messageHandlers: new Set(),
+    };
+    // Listen for messages from this sandbox
+    const handleMessage = (event) => {
+        // Only accept messages from this iframe
+        if (event.source !== iframe.contentWindow)
+            return;
+        const msg = event.data;
+        if (msg?.type === 'extension-ready') {
+            instance.ready = true;
+        }
+        instance.messageHandlers.forEach((handler) => handler(msg));
+    };
+    window.addEventListener('message', handleMessage);
+    sandboxes.set(entry.id, instance);
+    return instance;
+};
+/**
+ * Send a message to a sandbox.
+ */
+export const postToSandbox = (extensionId, message) => {
+    const instance = sandboxes.get(extensionId);
+    if (!instance?.iframe.contentWindow) {
+        console.warn(`Sandbox not found for extension: ${extensionId}`);
+        return;
+    }
+    instance.iframe.contentWindow.postMessage(message, '*');
+};
+/**
+ * Get a sandbox instance by extension ID.
+ */
+export const getSandbox = (extensionId) => sandboxes.get(extensionId);
+/**
+ * Destroy a sandbox and clean up.
+ */
+export const destroySandbox = (extensionId) => {
+    const instance = sandboxes.get(extensionId);
+    if (instance) {
+        instance.iframe.remove();
+        instance.messageHandlers.clear();
+        sandboxes.delete(extensionId);
+    }
+};
+/**
+ * Get all active sandbox instances.
+ */
+export const getAllSandboxes = () => sandboxes;
+//# sourceMappingURL=SandboxManager.js.map

package/dist/SandboxManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxManager.js","sourceRoot":"","sources":["../src/SandboxManager.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ExtensionProvider, useExtensionProvider } from './ExtensionProvider';
+export { ExtensionSlot } from './ExtensionSlot';
+export { createSandbox, getSandbox, destroySandbox, postToSandbox, } from './SandboxManager';
+export { createCapabilityRPCHandler, type CapabilityHandlers, } from './CapabilityRPCHandler';
+export { registerComponent, registerComponents, getComponent, isValidTag, } from './ComponentRegistry';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { ExtensionProvider, useExtensionProvider } from './ExtensionProvider';
+export { ExtensionSlot } from './ExtensionSlot';
+export { createSandbox, getSandbox, destroySandbox, postToSandbox, } from './SandboxManager';
+export { createCapabilityRPCHandler, } from './CapabilityRPCHandler';
+export { registerComponent, registerComponents, getComponent, isValidTag, } from './ComponentRegistry';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,aAAa,GACd,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,0BAA0B,GAE3B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,UAAU,GACX,MAAM,qBAAqB,CAAA"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@stackable-labs/sdk-extension-host",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@stackable-labs/sdk-extension-contracts": "1.0.0",
+    "@remote-dom/core": "1.x",
+    "@remote-dom/react": "1.x"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 <19.0.0",
+    "react-dom": ">=18.0.0 <19.0.0"
+  },
+  "description": "Host-side SDK for embedding Stackable extensions.",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://www.npmjs.com/package/@stackable-labs/sdk-extension-host",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ]
+}