@hyperfrontend/features 0.1.0 → 0.2.0

package/host/index.esm.js

@@ -1,15 +1,50 @@
-import { freeze } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
+import { freeze, values } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
 import { DEFAULT_CONTRACT, createBroker } from '../_dependencies/@hyperfrontend/nexus/index.esm.js';
+import { parse, stringify } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
 import { createElement, div, button } from '../_dependencies/@hyperfrontend/ui-utils/element/index.esm.js';
 import { createError } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
 import { round } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
 import { dateNow } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.esm.js';
-import { setInterval, clearInterval } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.esm.js';
+import { setInterval, clearInterval, clearTimeout, setTimeout } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.esm.js';
+import { createPromise, promiseResolve, promiseReject } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
 import { createProtocol } from '../_dependencies/@hyperfrontend/network-protocol/browser/v1/index.esm.js';
 import { createProtocol as createProtocol$1 } from '../_dependencies/@hyperfrontend/network-protocol/browser/v2/index.esm.js';
 import { DisplayMode } from '../_shared/shared/types/index.esm.js';
 import { ControlType, isControlType, withControlContract } from '../_shared/shared/control/index.esm.js';
 import { createEventEmitter } from '../_shared/shared/event-emitter/index.esm.js';
+import { createRequestPeer } from '../_shared/shared/request/index.esm.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) => parse(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.
 /**
@@ -107,7 +142,7 @@ const dialogDefaults = 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
@@ -151,6 +186,7 @@ const mountDialog = ({ options, requestClose }) => {
     document.addEventListener('keydown', onKeydown);
     return {
         target: iframe.contentWindow,
+        element: container.ref,
         cleanup: () => {
             document.removeEventListener('keydown', onKeydown);
             container.ref.remove();
@@ -163,7 +199,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
@@ -176,6 +212,7 @@ const mountEmbedded = ({ options }) => {
     container.appendChild(iframe);
     return {
         target: iframe.contentWindow,
+        element: iframe,
         frame: iframe,
         cleanup: () => iframe.remove(),
     };
@@ -348,6 +385,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();
@@ -360,8 +403,45 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
             monitor = null;
         }
     };
-    const destroy = () => {
-        stopMonitor();
+    const mountPlugins = (registered, element, displayMode) => {
+        const context = 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 = 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;
@@ -369,6 +449,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();
@@ -389,13 +483,21 @@ function createShellHandle(broker, baseOptions, emitter, wiring) {
     };
     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', 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));
@@ -409,6 +511,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));
@@ -421,6 +532,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);
@@ -432,6 +546,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) : promiseReject(createError(`Cannot send request '${type}': the shell is not open.`)),
+        handle: requests.handle,
         on: emitter.on,
         get isOpen() {
             return opened;
@@ -556,7 +672,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`.
@@ -570,7 +689,8 @@ function deriveShellName(options, sequence) {
  */
 function createShell(options) {
     const emitter = createEventEmitter();
-    const contract = withControlContract((options.contract ?? DEFAULT_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) : DEFAULT_CONTRACT);
     const broker = createBroker({ name: deriveShellName(options, (shellCount += 1)), contract });
     return createShellHandle(broker, options, emitter, { selectMount, registerSecurity, createHeartbeatMonitor });
 }

package/host/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA2B,MAAM,sBAAsB,CAAA;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAI5D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAO7C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,gBAAgB,CAAA;IAChD;;;;;;;OAOG;IACH,gBAAgB,CACd,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACtC;;;;;OAKG;IACH,sBAAsB,CAAC,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,gBAAgB,CAAA;CACnH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,YAAY,EACzB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,WAAW,GAClB,WAAW,CAyGb"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA2B,MAAM,sBAAsB,CAAA;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D,OAAO,KAAK,EAA6C,gBAAgB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAChH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAM5D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAO7C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,gBAAgB,CAAA;IAChD;;;;;;;OAOG;IACH,gBAAgB,CACd,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACtC;;;;;OAKG;IACH,sBAAsB,CAAC,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,gBAAgB,CAAA;CACnH;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,YAAY,EACzB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,WAAW,GAClB,WAAW,CA0Lb"}

package/host/plugins.d.ts

@@ -1,35 +1,2 @@
-import type { DisplayMode } from '../shared/types';
-/**
- * Context handed to an {@link ExperiencePlugin} around a feature's mount lifecycle.
- */
-export 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.
- */
-export 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>;
-}
+export type { ExperiencePlugin, ExperiencePluginContext } from '../shared/types';
 //# sourceMappingURL=plugins.d.ts.map

package/host/plugins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/plugins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAIlD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,sFAAsF;IACtF,OAAO,EAAE,WAAW,CAAA;IACpB,oDAAoD;IACpD,WAAW,EAAE,WAAW,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAA;IAC/D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnE"}
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/plugins.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA"}

package/host/types.d.ts

@@ -1,4 +1,5 @@
 import type { EventHandler } from '../shared/event-emitter';
+import type { RequestHandler, RequestOptions } from '../shared/request';
 import type { ShellOptions } from '../shared/types';
 /**
  * Public handle returned by {@link createShell}.
@@ -7,6 +8,9 @@ export 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;
@@ -16,6 +20,10 @@ export 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;
     /**
@@ -25,6 +33,45 @@ export 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`).
      *
@@ -44,6 +91,8 @@ export interface ShellHandle {
 export interface MountResult {
     /** Window the host messages, or `null` when a popup/standalone was blocked. */
     target: Window | null;
+    /** In-document root the mode mounted (embedded iframe or dialog container); unset when the feature opens in a separate window. */
+    element?: HTMLElement;
     /** Resizable element for content-driven sizing, when the mode embeds an iframe inline. */
     frame?: HTMLElement;
     /** Removes any DOM or closes any window created by the mount. */

package/host/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAAA;IAC3C;;OAEG;IACH,KAAK,IAAI,IAAI,CAAA;IACb;;OAEG;IACH,OAAO,IAAI,IAAI,CAAA;IACf;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACxC;;;;;;OAMG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI,CAAA;IACpD;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,iEAAiE;IACjE,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,OAAO,EAAE,YAAY,CAAA;IACrB,6EAA6E;IAC7E,YAAY,IAAI,IAAI,CAAA;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,WAAW,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/host/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAAA;IAC3C;;OAEG;IACH,KAAK,IAAI,IAAI,CAAA;IACb;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAAA;IACf;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACxC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACjF;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,IAAI,CAAA;IACzD;;;;;;OAMG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI,CAAA;IACpD;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,kIAAkI;IAClI,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,iEAAiE;IACjE,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,OAAO,EAAE,YAAY,CAAA;IACrB,6EAA6E;IAC7E,YAAY,IAAI,IAAI,CAAA;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,WAAW,CAAA"}

package/hostee/index.cjs.js

@@ -3,14 +3,15 @@
 const index_cjs_js$7 = require('../_dependencies/@hyperfrontend/nexus/index.cjs.js');
 const index_cjs_js$1 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
 const index_cjs_js = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
-const { ControlType, withControlContract } = require('../_shared/shared/control/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');
 require('../_dependencies/@hyperfrontend/json-utils/index.cjs.js');
 const index_cjs_js$2 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
-const index_cjs_js$6 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
+const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
 const index_cjs_js$3 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.cjs.js');
-const index_cjs_js$5 = require('../_dependencies/@hyperfrontend/ui-utils/element/index.cjs.js');
-const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/ui-utils/style/index.cjs.js');
+const index_cjs_js$6 = require('../_dependencies/@hyperfrontend/ui-utils/element/index.cjs.js');
+const index_cjs_js$5 = require('../_dependencies/@hyperfrontend/ui-utils/style/index.cjs.js');
 
 // note: Runtime validation shared by the host/hostee factories and the config loader.
 /**
@@ -45,6 +46,31 @@ function collectActionListIssues(actions, field, issues) {
         if (typeof action['type'] !== 'string' || action['type'].length === 0) {
             issues.push(`"${field}[${index}]" must have a non-empty string "type".`);
         }
+        if (action['respondsWith'] !== undefined && (typeof action['respondsWith'] !== 'string' || action['respondsWith'].length === 0)) {
+            issues.push(`"${field}[${index}]" has a "respondsWith" that must be a non-empty string.`);
+        }
+    });
+}
+/**
+ * Collects every `respondsWith` reference that does not name an action in the other direction.
+ *
+ * A request emitted by one side is answered by an action the same side accepts (and
+ * vice versa), so each `respondsWith` must resolve across the contract's directions.
+ *
+ * @param actions - The already well-formed action list to check.
+ * @param field - The field name of `actions`, used to locate problems in messages.
+ * @param other - The action list of the opposite direction.
+ * @param otherField - The field name of `other`, used in messages.
+ * @param issues - The running list of human-readable problems, appended to in place.
+ */
+function collectRespondsWithIssues(actions, field, other, otherField, issues) {
+    actions.forEach((action, index) => {
+        if (action.respondsWith === undefined) {
+            return;
+        }
+        if (!other.some((candidate) => candidate.type === action.respondsWith)) {
+            issues.push(`"${field}[${index}]" responds with "${action.respondsWith}", but "${otherField}" has no action of that type.`);
+        }
     });
 }
 /**
@@ -70,7 +96,7 @@ function describeType(value) {
  *
  * @param contract - The candidate contract, typically parsed from disk.
  * @returns The validated contract, typed.
- * @throws {Error} When the value is not an object, or any action is malformed.
+ * @throws {Error} When the value is not an object, any action is malformed, or a `respondsWith` names no action in the other direction.
  *
  * @example Validating a parsed contract file
  * ```typescript
@@ -85,6 +111,12 @@ function validateContract(contract) {
     const issues = [];
     collectActionListIssues(contract['emitted'], 'emitted', issues);
     collectActionListIssues(contract['accepted'], 'accepted', issues);
+    if (issues.length === 0) {
+        const emitted = contract['emitted'];
+        const accepted = contract['accepted'];
+        collectRespondsWithIssues(emitted, 'emitted', accepted, 'accepted', issues);
+        collectRespondsWithIssues(accepted, 'accepted', emitted, 'emitted', issues);
+    }
     if (issues.length > 0) {
         throw index_cjs_js.createError(`Invalid contract:\n${issues.map((issue) => `  - ${issue}`).join('\n')}`);
     }
@@ -135,7 +167,7 @@ const BODY_RESET_CSS = 'html,body{margin:0;padding:0;background:transparent}';
  * ```
  */
 function applyBodyReset() {
-    index_cjs_js$4.addStylesheet(BODY_RESET_CSS);
+    index_cjs_js$5.addStylesheet(BODY_RESET_CSS);
 }
 /**
  * Creates the hostee-side content-size announcer.
@@ -158,7 +190,7 @@ function createSizeAnnouncer(send) {
                 return;
             }
             announce();
-            cleanup = index_cjs_js$5.onElementResize(document.body, announce);
+            cleanup = index_cjs_js$6.onElementResize(document.body, announce);
         },
         stop() {
             if (cleanup) {
@@ -207,6 +239,7 @@ function resolveHostWindow(win) {
 function createFeatureHandle(broker, hostWindow, emitter) {
     let channel = null;
     let opened = false;
+    const requests = createRequestPeer('feature', (type, data) => channel?.send(type, data));
     if (hostWindow) {
         const activeChannel = broker.addChannel('host', hostWindow);
         channel = activeChannel;
@@ -223,16 +256,28 @@ function createFeatureHandle(broker, hostWindow, emitter) {
             emitter.emit('close');
             heartbeat.stop();
             announcer.stop();
+            requests.rejectAll('The host channel closed before the host responded.');
         });
         activeChannel.on('deny', (data) => emitter.emit('error', data));
         activeChannel.on('invalid', (data) => emitter.emit('error', data));
-        activeChannel.onMessage((message) => emitter.emit(message.type, message.data));
+        activeChannel.onMessage((message) => {
+            // why: Control traffic (heartbeat/size echoes, request/response envelopes) is SDK-internal; forwarding it would leak reserved __hf: types into consumer handlers.
+            if (isControlType(message.type)) {
+                requests.dispatch(message.type, message.data);
+                return;
+            }
+            emitter.emit(message.type, message.data);
+        });
         activeChannel.connect();
     }
     return index_cjs_js$2.freeze({
         send: (type, data) => channel?.send(type, data),
+        request: (type, data, options) => channel
+            ? requests.request(type, data, options)
+            : index_cjs_js$4.promiseReject(index_cjs_js.createError(`Cannot send request '${type}': the feature is not connected to a host.`)),
+        handle: requests.handle,
         on: emitter.on,
-        ready: () => index_cjs_js$6.createPromise((resolve) => {
+        ready: () => index_cjs_js$4.createPromise((resolve) => {
             if (opened) {
                 resolve();
                 return;

package/hostee/index.d.ts

@@ -1,4 +1,5 @@
-import { EventHandler, FeatureOptions } from '..';
+import { RequestOptions, RequestHandler, EventHandler, FeatureOptions } from '..';
+export { ActionDescription, FeatureContract, FeatureOptions, RequestHandler, RequestOptions } from '..';
 
 /**
  * Public handle returned by the hostee-side feature factory.
@@ -11,6 +12,45 @@ interface FeatureHandle {
      * @param data - Optional payload for the action.
      */
     send(type: string, data?: unknown): void;
+    /**
+     * Sends a request to the host and resolves with its response.
+     *
+     * The host answers through a handler it registered with its own
+     * `handle(type, handler)`. The promise rejects when the host's handler
+     * throws, when the host has no handler for the type, when no response
+     * arrives within the timeout (30 seconds by default), when the feature is
+     * not connected to a host, or when the host channel closes 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 host's response payload.
+     *
+     * @example Asking the host for its settings
+     * ```typescript
+     * const settings = await feature.request('getSettings', undefined, { timeoutMs: 5000 })
+     * ```
+     */
+    request(type: string, data?: unknown, options?: RequestOptions): Promise<unknown>;
+    /**
+     * Registers the handler that answers host 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 host 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 the host's request for the feature's state
+     * ```typescript
+     * feature.handle('getTime', (data) => formatTime(data))
+     * ```
+     */
+    handle(type: string, handler: RequestHandler): () => void;
     /**
      * Subscribes to host messages or lifecycle events (`open`, `close`, `error`).
      *

package/hostee/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/hostee/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/hostee/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACzF,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}