@hyperfrontend/features 0.1.0 → 0.2.0

package/server/index.esm.js

@@ -3,7 +3,7 @@ import { isArray } from '../_dependencies/@hyperfrontend/immutable-api-utils/bui
 import { createError } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
 import { isInteger } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js';
 import { exists, readJsonFile, readFileBuffer, isFile } from '../_dependencies/@hyperfrontend/project-scope/core/fs/index.esm.js';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { createServer } from 'node:http';
 import { stringify } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
 import { promiseAll, createPromise } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
@@ -185,6 +185,29 @@ async function resolveDevConfig(options) {
     };
 }
 
+/**
+ * Directory of the currently-running module under either module system.
+ *
+ * The CommonJS build (and any CommonJS host) exposes `__dirname`; the
+ * ES-module build derives the directory from `import.meta.url`. Both formats
+ * ship beside the `debug-ui` assets, so the result anchors asset
+ * self-location wherever the package is installed or embedded.
+ *
+ * @returns Absolute directory path of the running module.
+ *
+ * @example Anchoring an asset lookup beside the running module
+ * ```typescript
+ * const assetDir = join(currentModuleDir(), 'debug-ui')
+ * ```
+ */
+function currentModuleDir() {
+    // why: `typeof` guards the CommonJS-only global so the ES-module build falls through to `import.meta.url` instead of crashing on an undefined identifier.
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    return dirname(fileURLToPath(import.meta.url));
+}
+
 // note: Minimal MIME table for the asset types a compiled feature/debug-UI bundle ships; anything else falls back to octet-stream.
 const CONTENT_TYPES = freeze({
     '.html': 'text/html; charset=utf-8',
@@ -293,23 +316,66 @@ function createStaticHandler(root, deps = {}) {
     return (req, res) => serveFile(root, req.url ?? '/', res, deps);
 }
 
-// note: Path prefix the control server serves the compiled debug-UI assets under; the page loads `/__debug/bootstrap.js`.
+// note: Path prefix the control server serves the compiled debug-UI assets under; the page loads `/__debug/index.iife.min.js`.
 const DEBUG_PREFIX = '/__debug';
 // note: Placeholder the debug-UI HTML embeds; the control server swaps it for the live JSON manifest at request time.
 const MANIFEST_TOKEN = 'HF_MANIFEST_PLACEHOLDER';
 /**
- * Resolves the directory the compiled debug-UI assets ship in, located beside
- * this module via `__dirname` so the server finds them wherever the package is
- * installed.
+ * Probes a single directory for the shipped debug-UI assets, checking both a
+ * sibling `debug-ui` folder (running from the `server/` output) and a nested
+ * `server/debug-ui` folder (running from another package entry, such as the
+ * CLI bin at the package root).
+ *
+ * @param dir - Candidate directory expected to hold the assets.
+ * @param isFile - File probe used to confirm the assets exist.
+ * @returns The `debug-ui` asset directory, or `undefined` when it is not here.
+ */
+function probeAssetDir(dir, isFile) {
+    const sibling = join(dir, 'debug-ui');
+    if (isFile(join(sibling, 'index.html'))) {
+        return sibling;
+    }
+    const nested = join(dir, 'server', 'debug-ui');
+    return isFile(join(nested, 'index.html')) ? nested : undefined;
+}
+/**
+ * Locates the debug-UI assets by ascending from a start directory toward the
+ * filesystem root, returning the first ancestor holding a `debug-ui` folder.
+ *
+ * @param startDir - Directory the ascent begins from.
+ * @param isFile - File probe used to confirm the assets exist.
+ * @returns The `debug-ui` asset directory, or `undefined` when no ancestor holds one.
+ */
+function ascendForAssets(startDir, isFile) {
+    let dir = startDir;
+    let parent = dirname(dir);
+    // how: probe each level then step up; the final probe covers the filesystem root, where parent === dir
+    while (parent !== dir) {
+        const found = probeAssetDir(dir, isFile);
+        if (found !== undefined) {
+            return found;
+        }
+        dir = parent;
+        parent = dirname(dir);
+    }
+    return probeAssetDir(dir, isFile);
+}
+/**
+ * Resolves the directory the compiled debug-UI assets ship in by ascending
+ * from the running module (located via `__dirname` in CommonJS or
+ * `import.meta.url` in ESM). The ascent finds the assets wherever the package
+ * lives — the built dist, an installed `node_modules` copy, or embedded
+ * inside a consumer's bundle output.
  *
+ * @param isFile - File probe used to confirm the assets exist.
  * @returns The absolute debug-UI asset directory.
  */
-function defaultAssetRoot() {
-    /* istanbul ignore if -- @preserve the ESM build has no __dirname; the shipped CommonJS build and the test runner always define it */
-    if (typeof __dirname === 'undefined') {
-        throw createError('@hyperfrontend/features dev server self-location requires the CommonJS build; inject `assetRoot` otherwise.');
+function defaultAssetRoot(isFile) {
+    const located = ascendForAssets(currentModuleDir(), isFile);
+    if (located === undefined) {
+        throw createError('@hyperfrontend/features dev server could not locate the bundled debug-UI assets beside the running module; inject `assetRoot` to point at a directory containing the debug-UI `index.html`.');
     }
-    return join(__dirname, 'debug-ui');
+    return located;
 }
 /**
  * Reads the listening port from a server, throwing if the address is unexpectedly absent.
@@ -420,7 +486,6 @@ function controlHandler(manifest, assetRoot, deps) {
  */
 async function startDevServer(config, deps = {}) {
     const createServer$1 = deps.createServer ?? createServer;
-    const assetRoot = deps.assetRoot ?? defaultAssetRoot();
     const servers = [];
     const apps = [];
     for (const app of config.apps) {
@@ -432,6 +497,8 @@ async function startDevServer(config, deps = {}) {
     const manifest = { apps: apps.map((app) => ({ name: app.name, url: app.url })), debug: config.debug };
     let debugUrl;
     if (config.debug.enabled) {
+        // why: resolved only when the debug UI is enabled so consumers with it disabled never pay for (or fail on) asset self-location.
+        const assetRoot = deps.assetRoot ?? defaultAssetRoot(deps.isFile ?? isFile);
         const control = createServer$1(controlHandler(manifest, assetRoot, deps));
         const port = await listen(control, config.debugPort);
         servers.push(control);

package/server/module-dir.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Directory of the currently-running module under either module system.
+ *
+ * The CommonJS build (and any CommonJS host) exposes `__dirname`; the
+ * ES-module build derives the directory from `import.meta.url`. Both formats
+ * ship beside the `debug-ui` assets, so the result anchors asset
+ * self-location wherever the package is installed or embedded.
+ *
+ * @returns Absolute directory path of the running module.
+ *
+ * @example Anchoring an asset lookup beside the running module
+ * ```typescript
+ * const assetDir = join(currentModuleDir(), 'debug-ui')
+ * ```
+ */
+export declare function currentModuleDir(): string;
+//# sourceMappingURL=module-dir.d.ts.map

package/server/module-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-dir.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/server/module-dir.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC"}

package/server/module-dir.stub.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CommonJS stand-in for the module locator: runtimes that execute this source
+ * tree as CommonJS cannot parse the `import.meta` token in `module-dir.ts`,
+ * and always define `__dirname`, which resolves to the same source directory
+ * here.
+ *
+ * @returns Absolute directory path of the running module.
+ *
+ * @example Anchoring an asset lookup beside the running module
+ * ```typescript
+ * const assetDir = join(currentModuleDir(), 'debug-ui')
+ * ```
+ */
+export declare function currentModuleDir(): string;
+//# sourceMappingURL=module-dir.stub.d.ts.map

package/server/module-dir.stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-dir.stub.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/server/module-dir.stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}

package/shared/contract.d.ts

@@ -8,7 +8,7 @@ import type { ActionDescription, FeatureConfig, FeatureContract } from './types'
  *
  * @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

package/shared/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AA2DhF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,eAAe,CAcnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,CAWpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAK7F"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AA2FhF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,eAAe,CAoBnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,CAWpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAK7F"}

package/shared/control.d.ts

@@ -7,6 +7,10 @@ export declare const ControlType: Readonly<{
     readonly Beat: "__hf:beat";
     /** Hostee-to-host content-size announcement. */
     readonly Size: "__hf:size";
+    /** Correlated request envelope carrying a consumer request in either direction. */
+    readonly Request: "__hf:request";
+    /** Correlated response envelope answering a request. */
+    readonly Response: "__hf:response";
 }>;
 /**
  * Union of the reserved control message types.

package/shared/control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAM9C;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB,oCAAoC;;IAEpC,gDAAgD;;EAEhD,CAAA;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAExE;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAM9E"}
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAM9C;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB,oCAAoC;;IAEpC,gDAAgD;;IAEhD,mFAAmF;;IAEnF,wDAAwD;;EAExD,CAAA;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAExE;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAY9E"}

package/shared/invert-contract.d.ts

@@ -0,0 +1,20 @@
+import type { FeatureContract } from './types';
+/**
+ * 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' }] }
+ * ```
+ */
+export declare function invertFeatureContract(contract: FeatureContract): FeatureContract;
+//# sourceMappingURL=invert-contract.d.ts.map

package/shared/invert-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invert-contract.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/invert-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAqB,eAAe,EAAE,MAAM,SAAS,CAAA;AAejE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAEhF"}

package/shared/request.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Which side of the feature channel a peer speaks for.
+ */
+export type PeerOrigin = 'host' | 'feature';
+/**
+ * Per-request settings accepted by `request`.
+ */
+export interface RequestOptions {
+    /** Milliseconds to wait for the response before rejecting; defaults to 30000. */
+    timeoutMs?: number;
+}
+/**
+ * Answers one request type; may return the response value directly or a promise of it.
+ *
+ * @param data - The request payload sent by the other side.
+ * @returns The response value, or a promise that resolves to it.
+ */
+export type RequestHandler = (data: unknown) => unknown;
+/**
+ * One side of the correlated request/response protocol layered on the control plane.
+ */
+export interface RequestPeer {
+    /**
+     * Sends a request to the other side and resolves with its response.
+     *
+     * @param type - Request type the other side answers.
+     * @param data - Optional payload for the request.
+     * @param options - Per-request settings such as `timeoutMs`.
+     * @returns A promise settling with the other side's response.
+     */
+    request(type: string, data?: unknown, options?: RequestOptions): Promise<unknown>;
+    /**
+     * Registers the single handler answering requests of a type; a second registration for the same type throws.
+     *
+     * @param type - Request type to answer.
+     * @param handler - Receives the request payload and returns the response.
+     * @returns A function that unregisters this handler.
+     */
+    handle(type: string, handler: RequestHandler): () => void;
+    /**
+     * Routes an incoming control-plane message into the protocol; non-envelope data and self-originated echoes are ignored.
+     *
+     * @param type - The wire message type.
+     * @param data - The wire message payload.
+     */
+    dispatch(type: string, data: unknown): void;
+    /**
+     * Rejects every pending request, e.g. when the channel closes.
+     *
+     * @param reason - Human-readable reason placed on each rejection error.
+     */
+    rejectAll(reason: string): void;
+}
+/**
+ * Creates one side of the request/response protocol around a channel send function.
+ *
+ * @param origin - Which side of the channel this peer speaks for.
+ * @param send - Sends a control message through the underlying channel.
+ * @returns The frozen peer.
+ *
+ * @example Wiring a peer into a channel's control-message intercept
+ * ```typescript
+ * const peer = createRequestPeer('host', (type, data) => channel?.send(type, data))
+ * channel.onMessage((message) => isControlType(message.type) && peer.dispatch(message.type, message.data))
+ * ```
+ */
+export declare function createRequestPeer(origin: PeerOrigin, send: (type: string, data: unknown) => void): RequestPeer;
+//# sourceMappingURL=request.d.ts.map

package/shared/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/request.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAA;AAEvD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACjF;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,IAAI,CAAA;IACzD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IAC3C;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC;AA4CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,WAAW,CA4F9G"}

package/{nx/shared → shared}/shutdown.d.ts

@@ -1,8 +1,9 @@
 /**
  * Resolve once the process receives an interrupt or terminate signal.
  *
- * Used by long-running executors to stay alive after startup and tear down
- * gracefully when Nx (or the user) stops the target.
+ * Used by the dev command and long-running executors to stay alive after
+ * startup and tear down gracefully when the user (or the task runner) stops
+ * them.
  *
  * @returns A promise that settles when `SIGINT` or `SIGTERM` is received.
  *

package/shared/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/shutdown.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAM/C"}

package/shared/types.d.ts

@@ -63,6 +63,8 @@ export interface ActionDescription {
     description?: string;
     /** Optional JSON-schema-like shape describing the action payload. */
     schema?: object;
+    /** When this action is used as a request, the type of the action in the other direction that answers it. */
+    respondsWith?: string;
 }
 /**
  * The set of actions a feature emits to, and accepts from, its counterpart.
@@ -76,6 +78,66 @@ export interface FeatureContract {
     /** Actions this side handles from the other side. */
     accepted: ActionDescription[];
 }
+/**
+ * Context handed to an {@link ExperiencePlugin} around a feature's mount lifecycle.
+ */
+export interface ExperiencePluginContext {
+    /**
+     * The in-document root the display mode mounted: the iframe for `embedded`,
+     * the dialog container for `dialog`, and `null` for `popup` and
+     * `standalone`, which open a separate window with no in-document element.
+     */
+    element: HTMLElement | null;
+    /** The display mode the feature was surfaced in. */
+    displayMode: DisplayMode;
+}
+/**
+ * Opt-in extension that decorates a feature's mount lifecycle (e.g. transitions, animations).
+ *
+ * Register plugins through {@link ShellOptions.plugins}. After each successful
+ * mount the shell calls `onMount` on every plugin in registration order; before
+ * each unmount it calls `onUnmount` one plugin at a time in reverse
+ * registration order, awaiting any returned promise, then runs the teardowns
+ * returned by `onMount` (also in reverse registration order) and finally
+ * removes the feature. The SDK ships no built-in plugins.
+ *
+ * @example Registering a fade-out plugin on a shell
+ * ```typescript
+ * const shell = createShell({
+ *   container: '#shell',
+ *   plugins: [
+ *     {
+ *       name: 'fade',
+ *       onUnmount: ({ element }) => (element ? animateFadeOut(element) : undefined),
+ *     },
+ *   ],
+ * })
+ * ```
+ */
+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.
+     *
+     * A thrown error surfaces as an `error` event on the shell and does not
+     * stop the remaining plugins from mounting.
+     *
+     * @param context - The mounted element and its display mode.
+     * @returns An optional teardown invoked on unmount, after every `onUnmount` has settled.
+     */
+    onMount?(context: ExperiencePluginContext): void | (() => void);
+    /**
+     * Runs before the feature unmounts; may return a promise to defer teardown until an exit animation finishes.
+     *
+     * A rejected promise (or thrown error) surfaces as an `error` event on the
+     * shell and teardown continues with the remaining plugins.
+     *
+     * @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>;
+}
 /**
  * Options accepted by the host-side {@link FeatureContract} consumer when
  * creating or opening a shell.
@@ -85,7 +147,12 @@ export interface ShellOptions {
     container: string | HTMLElement;
     /** Stable identifier for the feature; seeds the broker name surfaced in debug logs. */
     name?: string;
-    /** Contract describing the feature's actions; replaces the generic default when provided. */
+    /**
+     * The feature's contract exactly as the feature authored it (`emitted` = what
+     * the feature sends, `accepted` = what the feature handles). The shell
+     * derives the host-side orientation itself — hand it the feature's contract,
+     * never a pre-swapped copy. Replaces the generic default when provided.
+     */
     contract?: FeatureContract;
     /** How the feature should be surfaced; defaults to {@link DisplayMode.Embedded}. */
     displayMode?: DisplayMode;
@@ -107,6 +174,8 @@ export interface ShellOptions {
     protocol?: SecurityProtocol;
     /** Pre-shared key used by the `v2` protocol. */
     sharedKey?: string;
+    /** Experience plugins wrapped around each mount/unmount; `onMount` runs in registration order, `onUnmount` in reverse. */
+    plugins?: readonly ExperiencePlugin[];
 }
 /**
  * Options accepted by the hostee-side feature factory.
@@ -161,6 +230,8 @@ export interface ResolvedFeatureConfig extends FeatureConfig {
     url: string;
     /** Default display options baked into the connector as the feature's defaults. */
     display?: DisplayDefaults;
+    /** Security envelope the build resolved; baked into the generated connector as its default. */
+    protocol?: SecurityProtocol;
 }
 /**
  * A single feature app entry served by the dev server.

package/shared/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../../libs/features/src/shared/types.ts"],"names":[],"mappings":"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"}

package/_shared/nx/shared/context/index.cjs.js

@@ -1,18 +0,0 @@
-'use strict';
-
-const error = require('@hyperfrontend/immutable-api-utils/built-in-copy/error');
-const node_path = require('node:path');
-
-function resolveProjectCwd(context) {
-    const { projectName } = context;
-    if (projectName === undefined) {
-        throw error.createError('An executing project name is required.');
-    }
-    const projectConfig = context.projectsConfigurations?.projects[projectName];
-    if (projectConfig === undefined) {
-        throw error.createError(`Could not find project configuration for ${projectName}.`);
-    }
-    return node_path.join(context.root, projectConfig.root);
-}
-
-exports.resolveProjectCwd = resolveProjectCwd;

package/_shared/nx/shared/context/index.esm.js

@@ -1,16 +0,0 @@
-import { createError as createError$1 } from '@hyperfrontend/immutable-api-utils/built-in-copy/error';
-import { join } from 'node:path';
-
-function resolveProjectCwd(context) {
-    const { projectName } = context;
-    if (projectName === undefined) {
-        throw createError$1('An executing project name is required.');
-    }
-    const projectConfig = context.projectsConfigurations?.projects[projectName];
-    if (projectConfig === undefined) {
-        throw createError$1(`Could not find project configuration for ${projectName}.`);
-    }
-    return join(context.root, projectConfig.root);
-}
-
-export { resolveProjectCwd };

package/nx/shared/shutdown.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/nx/shared/shutdown.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAM/C"}

package/server/debug-ui/bootstrap.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=bootstrap.d.ts.map

package/server/debug-ui/bootstrap.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/features/src/server/debug-ui/bootstrap.ts"],"names":[],"mappings":""}