@hyperfrontend/features 0.1.0 → 0.2.0

package/generators/shell/schema-type.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Projects a JSON-schema-like payload description into TypeScript type source.
+ *
+ * Bounded mapping: scalar `type`s, `object` with `properties`/`required`,
+ * `array` with a single `items` schema, `enum`, and `const` are projected;
+ * anything else (including a missing schema) falls back to `unknown`, so a
+ * generated type is never wrong — at worst it is loose.
+ *
+ * @param schema - The schema value to project.
+ * @param indent - Indentation prefix applied to nested object members.
+ * @returns The TypeScript type as source text.
+ *
+ * @example Projecting an action payload schema
+ * ```typescript
+ * schemaToType({ type: 'object', properties: { tz: { type: 'string' } }, required: ['tz'] })
+ * // => '{\n  tz: string\n}'
+ * ```
+ */
+export declare function schemaToType(schema: unknown, indent?: string): string;
+//# sourceMappingURL=schema-type.d.ts.map

package/generators/shell/schema-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-type.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/generators/shell/schema-type.ts"],"names":[],"mappings":"AA2FA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,MAAM,CA0BjE"}

package/generators/shell/source-literal.d.ts

@@ -1,3 +1,31 @@
+/**
+ * Renders a string as a single-quoted TypeScript string literal.
+ *
+ * Embedded double quotes are left bare (legal inside single quotes); single
+ * quotes and backslashes are escaped; control characters keep their JSON escape.
+ *
+ * @param value - The string to render.
+ * @returns A single-quoted, safely escaped string literal.
+ *
+ * @example Quoting a string containing a single quote
+ * ```typescript
+ * quoteString("it's") // => "'it\\'s'"
+ * ```
+ */
+export declare function quoteString(value: string): string;
+/**
+ * Renders an object key, leaving valid identifiers bare and quoting the rest.
+ *
+ * @param key - The property name.
+ * @returns The key as written in an object literal.
+ *
+ * @example Formatting identifier and non-identifier keys
+ * ```typescript
+ * formatKey('url') // => 'url'
+ * formatKey('time-zone') // => "'time-zone'"
+ * ```
+ */
+export declare function formatKey(key: string): string;
 /**
  * Renders a JSON-compatible value as formatted TypeScript source.
  *

package/generators/shell/source-literal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-literal.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/generators/shell/source-literal.ts"],"names":[],"mappings":"AAgFA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,MAAM,CAwBnE"}
+{"version":3,"file":"source-literal.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/generators/shell/source-literal.ts"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,MAAM,CAwBnE"}

package/host/create-shell.d.ts

@@ -21,7 +21,10 @@ export declare function deriveShellName(options: ShellOptions, sequence: number)
  * Creates a host-side shell for embedding a feature.
  *
  * Provisions a nexus broker and returns a handle whose `open` mounts the feature
- * in the requested display mode.
+ * in the requested display mode. The `contract` option takes the feature's
+ * contract exactly as the feature authored it; the shell derives the host-side
+ * orientation itself, so the handle sends what the feature accepts and receives
+ * what the feature emits.
  *
  * @param options - Create-time shell options, overridable per `open` call.
  * @returns A handle exposing `open`, `close`, `destroy`, `send`, `on`, and `isOpen`.

package/host/create-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-shell.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/create-shell.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AA6E1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI/E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CAK9D"}
+{"version":3,"file":"create-shell.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/create-shell.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AA8E1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI/E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CAM9D"}

package/host/display-modes/dialog.d.ts

@@ -5,7 +5,7 @@ import type { DisplayModeMount } from '../types';
  * @param context - Inputs the shell passes to this display mode.
  * @param context.options - The merged shell options.
  * @param context.requestClose - Requests the shell close itself.
- * @returns The iframe content window and a teardown that unmounts the dialog.
+ * @returns The iframe content window, the dialog container as the mounted element, and a teardown that unmounts the dialog.
  *
  * @example Mounting a dialog
  * ```typescript

package/host/display-modes/dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/host/display-modes/dialog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAOhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,EAAE,gBAgDzB,CAAA"}
+{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/host/display-modes/dialog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAOhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,EAAE,gBAiDzB,CAAA"}

package/host/display-modes/embedded.d.ts

@@ -4,7 +4,7 @@ import type { DisplayModeMount } from '../types';
  *
  * @param context - Inputs the shell passes to this display mode.
  * @param context.options - The merged shell options.
- * @returns The iframe content window and a teardown that removes the iframe.
+ * @returns The iframe content window, the iframe as the mounted element, and a teardown that removes the iframe.
  *
  * @example Mounting embedded
  * ```typescript

package/host/display-modes/embedded.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedded.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/host/display-modes/embedded.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAGhD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,gBAS3B,CAAA"}
+{"version":3,"file":"embedded.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/host/display-modes/embedded.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAGhD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,gBAU3B,CAAA"}

package/host/index.cjs.js

@@ -1,17 +1,52 @@
 'use strict';
 
 const index_cjs_js = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
-const index_cjs_js$8 = require('../_dependencies/@hyperfrontend/nexus/index.cjs.js');
-const index_cjs_js$1 = require('../_dependencies/@hyperfrontend/ui-utils/element/index.cjs.js');
-const index_cjs_js$2 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
-const index_cjs_js$3 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js');
-const index_cjs_js$5 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.cjs.js');
-const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.cjs.js');
-const index_cjs_js$6 = require('../_dependencies/@hyperfrontend/network-protocol/browser/v1/index.cjs.js');
-const index_cjs_js$7 = require('../_dependencies/@hyperfrontend/network-protocol/browser/v2/index.cjs.js');
+const index_cjs_js$a = require('../_dependencies/@hyperfrontend/nexus/index.cjs.js');
+const index_cjs_js$1 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
+const index_cjs_js$2 = require('../_dependencies/@hyperfrontend/ui-utils/element/index.cjs.js');
+const index_cjs_js$3 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js');
+const index_cjs_js$6 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.cjs.js');
+const index_cjs_js$5 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.cjs.js');
+const index_cjs_js$7 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
+const index_cjs_js$8 = require('../_dependencies/@hyperfrontend/network-protocol/browser/v1/index.cjs.js');
+const index_cjs_js$9 = require('../_dependencies/@hyperfrontend/network-protocol/browser/v2/index.cjs.js');
 const { DisplayMode } = require('../_shared/shared/types/index.cjs.js');
 const { ControlType, isControlType, withControlContract } = require('../_shared/shared/control/index.cjs.js');
 const { createEventEmitter } = require('../_shared/shared/event-emitter/index.cjs.js');
+const { createRequestPeer } = require('../_shared/shared/request/index.cjs.js');
+
+/**
+ * Deep-copies an action list so the returned contract shares no object
+ * references with its source.
+ *
+ * @param actions - The action descriptions to copy.
+ * @returns Fresh action objects with identical contents.
+ */
+function copyActions(actions) {
+    // why: The messaging layer rejects configs containing repeated object references, so the inverted contract must be built from fresh literals rather than aliasing the caller's action objects.
+    return actions.map((action) => index_cjs_js$1.parse(index_cjs_js$1.stringify(action)));
+}
+/**
+ * Inverts a feature-authored contract into the host's perspective.
+ *
+ * A feature contract is written from the feature's point of view: `emitted` is
+ * what the feature sends, `accepted` is what the feature handles. The host
+ * channel needs the mirror image — it sends what the feature accepts and
+ * accepts what the feature emits — so the two lists are swapped.
+ *
+ * @param contract - The contract as authored by the feature.
+ * @returns A fresh contract oriented to the host side.
+ *
+ * @example Deriving the host-side contract
+ * ```typescript
+ * const host = invertFeatureContract({ emitted: [{ type: 'tick' }], accepted: [{ type: 'setTimezone' }] })
+ * // => { emitted: [{ type: 'setTimezone' }], accepted: [{ type: 'tick' }] }
+ * ```
+ */
+function invertFeatureContract(contract) {
+    return { emitted: copyActions(contract.accepted), accepted: copyActions(contract.emitted) };
+}
 
 // note: Borderless and transparent so the embedded feature blends into the host page.
 /**
@@ -31,7 +66,7 @@ function resolveContainer(container) {
     }
     const found = document.querySelector(container);
     if (found === null) {
-        throw index_cjs_js$2.createError(`Shell container not found for selector "${container}".`);
+        throw index_cjs_js$3.createError(`Shell container not found for selector "${container}".`);
     }
     return found;
 }
@@ -48,7 +83,7 @@ function resolveContainer(container) {
  * ```
  */
 function createFeatureIframe(url) {
-    const iframe = index_cjs_js$1.createElement('iframe', {
+    const iframe = index_cjs_js$2.createElement('iframe', {
         inlineStyle: { border: 'none', width: '100%', height: '100%' },
     }).ref;
     iframe.src = url;
@@ -87,7 +122,7 @@ function resolveDialogSize() {
         width = maxWidth;
         height = width / SIZE_CONFIG.aspectRatio;
     }
-    return { width: index_cjs_js$3.round(width), height: index_cjs_js$3.round(height) };
+    return { width: index_cjs_js$4.round(width), height: index_cjs_js$4.round(height) };
 }
 /**
  * Dynamic default size for dialog and popup modes, recomputed on each access
@@ -109,7 +144,7 @@ const dialogDefaults = index_cjs_js.freeze({
  * @param context - Inputs the shell passes to this display mode.
  * @param context.options - The merged shell options.
  * @param context.requestClose - Requests the shell close itself.
- * @returns The iframe content window and a teardown that unmounts the dialog.
+ * @returns The iframe content window, the dialog container as the mounted element, and a teardown that unmounts the dialog.
  *
  * @example Mounting a dialog
  * ```typescript
@@ -117,13 +152,13 @@ const dialogDefaults = index_cjs_js.freeze({
  * ```
  */
 const mountDialog = ({ options, requestClose }) => {
-    const container = index_cjs_js$1.div({ inlineStyle: { position: 'fixed', inset: '0', zIndex: '2147483647' } });
+    const container = index_cjs_js$2.div({ inlineStyle: { position: 'fixed', inset: '0', zIndex: '2147483647' } });
     if (options.dialogOverlay ?? true) {
-        const backdrop = index_cjs_js$1.div({ inlineStyle: { position: 'absolute', inset: '0', background: 'rgba(0, 0, 0, 0.5)' } });
+        const backdrop = index_cjs_js$2.div({ inlineStyle: { position: 'absolute', inset: '0', background: 'rgba(0, 0, 0, 0.5)' } });
         backdrop.ref.addEventListener('click', () => requestClose());
         container.addChild(backdrop);
     }
-    const dialog = index_cjs_js$1.div({
+    const dialog = index_cjs_js$2.div({
         inlineStyle: {
             position: 'absolute',
             top: '50%',
@@ -134,7 +169,7 @@ const mountDialog = ({ options, requestClose }) => {
             background: '#fff',
         },
     });
-    const closeButton = index_cjs_js$1.button();
+    const closeButton = index_cjs_js$2.button();
     closeButton.ref.type = 'button';
     closeButton.ref.textContent = '×';
     closeButton.ref.setAttribute('aria-label', 'Close');
@@ -153,6 +188,7 @@ const mountDialog = ({ options, requestClose }) => {
     document.addEventListener('keydown', onKeydown);
     return {
         target: iframe.contentWindow,
+        element: container.ref,
         cleanup: () => {
             document.removeEventListener('keydown', onKeydown);
             container.ref.remove();
@@ -165,7 +201,7 @@ const mountDialog = ({ options, requestClose }) => {
  *
  * @param context - Inputs the shell passes to this display mode.
  * @param context.options - The merged shell options.
- * @returns The iframe content window and a teardown that removes the iframe.
+ * @returns The iframe content window, the iframe as the mounted element, and a teardown that removes the iframe.
  *
  * @example Mounting embedded
  * ```typescript
@@ -178,6 +214,7 @@ const mountEmbedded = ({ options }) => {
     container.appendChild(iframe);
     return {
         target: iframe.contentWindow,
+        element: iframe,
         frame: iframe,
         cleanup: () => iframe.remove(),
     };
@@ -285,20 +322,20 @@ function createHeartbeatMonitor(onUnresponsive) {
     let lastBeatAt = null;
     let timer;
     const stop = () => {
-        index_cjs_js$4.clearInterval(timer);
+        index_cjs_js$5.clearInterval(timer);
         timer = undefined;
     };
     return {
         beat() {
             missed = 0;
-            lastBeatAt = index_cjs_js$5.dateNow();
+            lastBeatAt = index_cjs_js$6.dateNow();
         },
         start() {
             if (timer !== undefined) {
                 return;
             }
             missed = 0;
-            timer = index_cjs_js$4.setInterval(() => {
+            timer = index_cjs_js$5.setInterval(() => {
                 missed += 1;
                 if (missed >= MISS_THRESHOLD) {
                     stop();
@@ -350,6 +387,12 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
     let opened = false;
     let openCount = 0;
     let monitor = null;
+    let plugins = null;
+    let pendingUnmount = null;
+    let queuedOpen = null;
+    // why: One peer outlives every open/close cycle so handlers registered before the first open (or across reopens) keep answering feature requests.
+    const requests = createRequestPeer('host', (type, data) => channel?.send(type, data));
+    const emitError = (error) => emitter.emit('error', error);
     const runCleanup = () => {
         if (cleanup) {
             cleanup();
@@ -362,8 +405,45 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
             monitor = null;
         }
     };
-    const destroy = () => {
-        stopMonitor();
+    const mountPlugins = (registered, element, displayMode) => {
+        const context = index_cjs_js.freeze({ element, displayMode });
+        const teardowns = [];
+        for (const plugin of registered) {
+            try {
+                const teardown = plugin.onMount?.(context);
+                if (teardown) {
+                    teardowns.push(teardown);
+                }
+            }
+            catch (error) {
+                emitError(error);
+            }
+        }
+        plugins = { registered, context, teardowns };
+    };
+    const startUnmount = (state, finish) => {
+        plugins = null;
+        let chain = index_cjs_js$7.promiseResolve();
+        for (const plugin of [...state.registered].reverse()) {
+            chain = chain.then(() => plugin.onUnmount?.(state.context)).catch(emitError);
+        }
+        pendingUnmount = chain.then(() => {
+            for (const teardown of [...state.teardowns].reverse()) {
+                try {
+                    teardown();
+                }
+                catch (error) {
+                    emitError(error);
+                }
+            }
+            finish();
+            pendingUnmount = null;
+            const reopen = queuedOpen;
+            queuedOpen = null;
+            reopen?.();
+        });
+    };
+    const releaseChannelAndCleanup = () => {
         if (channel) {
             channel.destroy();
             channel = null;
@@ -371,6 +451,20 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
         opened = false;
         runCleanup();
     };
+    const destroy = () => {
+        requests.rejectAll('The shell was destroyed before the feature responded.');
+        queuedOpen = null;
+        if (pendingUnmount) {
+            return;
+        }
+        stopMonitor();
+        const state = plugins;
+        if (state) {
+            startUnmount(state, releaseChannelAndCleanup);
+            return;
+        }
+        releaseChannelAndCleanup();
+    };
     const close = () => {
         if (channel) {
             channel.disconnect();
@@ -384,20 +478,28 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
             policy({ missedBeats, lastBeatAt, displayMode: options.displayMode ?? DisplayMode.Embedded, close, destroy });
             return;
         }
-        emitter.emit('error', index_cjs_js$2.createError('Feature became unresponsive.'));
+        emitter.emit('error', index_cjs_js$3.createError('Feature became unresponsive.'));
         if (policy === 'unmount') {
             destroy();
         }
     };
     const open = (overrides) => {
         destroy();
+        if (pendingUnmount) {
+            queuedOpen = () => open(overrides);
+            return;
+        }
         const options = { ...baseOptions, ...overrides };
-        const result = wiring.selectMount(options.displayMode ?? DisplayMode.Embedded)({ options, requestClose: close });
+        const displayMode = options.displayMode ?? DisplayMode.Embedded;
+        const result = wiring.selectMount(displayMode)({ options, requestClose: close });
         cleanup = result.cleanup;
         if (result.target === null) {
-            emitter.emit('error', index_cjs_js$2.createError('Feature window could not be opened.'));
+            emitter.emit('error', index_cjs_js$3.createError('Feature window could not be opened.'));
             return;
         }
+        if (options.plugins && options.plugins.length > 0) {
+            mountPlugins(options.plugins, result.element ?? null, displayMode);
+        }
         channel = broker.addChannel(`feature-${(openCount += 1)}`, result.target, wiring.registerSecurity(broker, options.protocol, options.sharedKey));
         const sizeFrame = options.embedSizing === 'content' ? result.frame : undefined;
         const activeMonitor = wiring.createHeartbeatMonitor((missedBeats, lastBeatAt) => applyUnresponsive(options, missedBeats, lastBeatAt));
@@ -411,6 +513,15 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
             opened = false;
             emitter.emit('close');
             stopMonitor();
+            requests.rejectAll('The feature channel closed before the feature responded.');
+            if (pendingUnmount) {
+                return;
+            }
+            const state = plugins;
+            if (state) {
+                startUnmount(state, runCleanup);
+                return;
+            }
             runCleanup();
         });
         channel.on('deny', (data) => emitter.emit('error', data));
@@ -423,6 +534,9 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
                 else if (message.type === ControlType.Size && sizeFrame) {
                     applyContentSize(sizeFrame, message.data);
                 }
+                else {
+                    requests.dispatch(message.type, message.data);
+                }
                 return;
             }
             emitter.emit(message.type, message.data);
@@ -434,6 +548,8 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
         close,
         destroy,
         send: (type, data) => channel?.send(type, data),
+        request: (type, data, options) => channel ? requests.request(type, data, options) : index_cjs_js$7.promiseReject(index_cjs_js$3.createError(`Cannot send request '${type}': the shell is not open.`)),
+        handle: requests.handle,
         on: emitter.on,
         get isOpen() {
             return opened;
@@ -458,11 +574,11 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
  */
 function registerSecurity(broker, protocol, sharedKey) {
     if (protocol === 'v1') {
-        broker.registerProtocol('v1', index_cjs_js$6.createProtocol(broker.logger));
+        broker.registerProtocol('v1', index_cjs_js$8.createProtocol(broker.logger));
         return { security: { protocol: 'v1' } };
     }
     if (protocol === 'v2') {
-        broker.registerProtocol('v2', index_cjs_js$7.createProtocol(broker.logger, sharedKey ?? ''));
+        broker.registerProtocol('v2', index_cjs_js$9.createProtocol(broker.logger, sharedKey ?? ''));
         return { security: { protocol: 'v2', sharedKey } };
     }
     return undefined;
@@ -558,7 +674,10 @@ function deriveShellName(options, sequence) {
  * Creates a host-side shell for embedding a feature.
  *
  * Provisions a nexus broker and returns a handle whose `open` mounts the feature
- * in the requested display mode.
+ * in the requested display mode. The `contract` option takes the feature's
+ * contract exactly as the feature authored it; the shell derives the host-side
+ * orientation itself, so the handle sends what the feature accepts and receives
+ * what the feature emits.
  *
  * @param options - Create-time shell options, overridable per `open` call.
  * @returns A handle exposing `open`, `close`, `destroy`, `send`, `on`, and `isOpen`.
@@ -572,8 +691,9 @@ function deriveShellName(options, sequence) {
  */
 function createShell(options) {
     const emitter = createEventEmitter();
-    const contract = withControlContract((options.contract ?? index_cjs_js$8.DEFAULT_CONTRACT));
-    const broker = index_cjs_js$8.createBroker({ name: deriveShellName(options, (shellCount += 1)), contract });
+    // how: A feature-authored contract is inverted into the host's perspective; the generic default contract is already channel-oriented and is used as-is.
+    const contract = withControlContract(options.contract ? invertFeatureContract(options.contract) : index_cjs_js$a.DEFAULT_CONTRACT);
+    const broker = index_cjs_js$a.createBroker({ name: deriveShellName(options, (shellCount += 1)), contract });
     return createShellHandle(broker, options, emitter, { selectMount, registerSecurity, createHeartbeatMonitor });
 }
 

package/host/index.d.ts

@@ -1,39 +1,5 @@
-import { DisplayMode, ShellOptions, EventHandler } from '..';
-export { DisplayMode, EmbedSizing, ShellOptions, UnresponsiveInfo, UnresponsivePolicy } from '..';
-
-/**
- * Context handed to an {@link ExperiencePlugin} around a feature's mount lifecycle.
- */
-interface ExperiencePluginContext {
-    /** The root element the display mode mounted (dialog container or embedded frame). */
-    element: HTMLElement;
-    /** The display mode the feature was surfaced in. */
-    displayMode: DisplayMode;
-}
-/**
- * Opt-in extension that decorates a feature's mount lifecycle (e.g. transitions, animations).
- *
- * Implement this interface to layer experiences onto the built-in display modes,
- * then pass the plugin to the host shell. The SDK ships no built-in plugins.
- */
-interface ExperiencePlugin {
-    /** Unique plugin name, surfaced in debug logs. */
-    name: string;
-    /**
-     * Runs after the feature mounts; may animate it in and return a teardown.
-     *
-     * @param context - The mounted element and its display mode.
-     * @returns An optional teardown invoked on unmount.
-     */
-    onMount?(context: ExperiencePluginContext): void | (() => void);
-    /**
-     * Runs before the feature unmounts; may return a promise to defer teardown until an exit animation finishes.
-     *
-     * @param context - The mounted element and its display mode.
-     * @returns Optionally a promise the shell awaits before tearing down.
-     */
-    onUnmount?(context: ExperiencePluginContext): void | Promise<void>;
-}
+import { ShellOptions, RequestOptions, RequestHandler, EventHandler } from '..';
+export { ActionDescription, DisplayMode, EmbedSizing, ExperiencePlugin, ExperiencePluginContext, FeatureContract, RequestHandler, RequestOptions, SecurityProtocol, ShellOptions, UnresponsiveInfo, UnresponsivePolicy } from '..';
 
 /**
  * Public handle returned by {@link createShell}.
@@ -42,6 +8,9 @@ interface ShellHandle {
     /**
      * Mounts the feature using the merged create-time and call-time options.
      *
+     * When a plugin teardown from the previous mount is still in flight, the
+     * remount is queued until it settles; the latest `open` call wins.
+     *
      * @param options - Per-open overrides layered over the create-time options.
      */
     open(options?: Partial<ShellOptions>): void;
@@ -51,6 +20,10 @@ interface ShellHandle {
     close(): void;
     /**
      * Closes the feature and releases all resources (channel and DOM).
+     *
+     * When experience plugins are registered, their `onUnmount` hooks are
+     * awaited before the channel and DOM are released; calling `destroy` again
+     * while that teardown is in flight is a no-op.
      */
     destroy(): void;
     /**
@@ -60,6 +33,45 @@ interface ShellHandle {
      * @param data - Optional payload for the action.
      */
     send(type: string, data?: unknown): void;
+    /**
+     * Sends a request to the feature and resolves with its response.
+     *
+     * The feature answers through a handler it registered with its own
+     * `handle(type, handler)`. The promise rejects when the feature's handler
+     * throws, when the feature has no handler for the type, when no response
+     * arrives within the timeout (30 seconds by default), when the shell is not
+     * open, or when the channel closes or the shell is destroyed while the
+     * request is pending.
+     *
+     * @param type - Request action type, drawn from the feature contract.
+     * @param data - Optional payload for the request.
+     * @param options - Per-request settings such as `timeoutMs`.
+     * @returns A promise settling with the feature's response payload.
+     *
+     * @example Querying the feature for its current state
+     * ```typescript
+     * const time = await shell.request('getTime', { timezone: 'UTC' }, { timeoutMs: 5000 })
+     * ```
+     */
+    request(type: string, data?: unknown, options?: RequestOptions): Promise<unknown>;
+    /**
+     * Registers the handler that answers feature requests of a given type.
+     *
+     * One handler per type: registering a second handler for a type that already
+     * has one throws. The handler may return the response value directly or a
+     * promise of it; a thrown error or rejected promise reaches the feature as a
+     * failed response carrying the error's message.
+     *
+     * @param type - Request type to answer.
+     * @param handler - Receives the request payload and returns the response.
+     * @returns A function that unregisters this handler.
+     *
+     * @example Answering a feature's request for host settings
+     * ```typescript
+     * shell.handle('getSettings', () => ({ locale: 'en-US' }))
+     * ```
+     */
+    handle(type: string, handler: RequestHandler): () => void;
     /**
      * Subscribes to feature messages or lifecycle events (`open`, `close`, `error`).
      *
@@ -78,7 +90,10 @@ interface ShellHandle {
  * Creates a host-side shell for embedding a feature.
  *
  * Provisions a nexus broker and returns a handle whose `open` mounts the feature
- * in the requested display mode.
+ * in the requested display mode. The `contract` option takes the feature's
+ * contract exactly as the feature authored it; the shell derives the host-side
+ * orientation itself, so the handle sends what the feature accepts and receives
+ * what the feature emits.
  *
  * @param options - Create-time shell options, overridable per `open` call.
  * @returns A handle exposing `open`, `close`, `destroy`, `send`, `on`, and `isOpen`.
@@ -93,4 +108,4 @@ interface ShellHandle {
 declare function createShell(options: ShellOptions): ShellHandle;
 
 export { createShell };
-export type { ExperiencePlugin, ExperiencePluginContext, ShellHandle };
+export type { ShellHandle };

package/host/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACtG,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAC1E,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvE,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAC1E,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA"}