@hyperfrontend/features/host

Host

Host-side SDK for embedding hyperfrontend features — shell factory, display modes, iframe utilities, and lifecycle.

import { createShell, DisplayMode } from '@hyperfrontend/features/host'

const shell = createShell({
  url: 'https://features.example.com/clock',
  container: '#clock-slot',
  displayMode: DisplayMode.Embedded,
})

shell.on('open', () => console.log('feature connected'))
shell.on('tick', (time) => console.log('feature said', time))

shell.open()
shell.send('set-timezone', { tz: 'UTC' })

API

Export	Purpose
`createShell`	Build a shell handle for a feature; returns `open`/`close`/`send`/`on`/`isOpen`.
`DisplayMode`	The four built-in modes: `Embedded`, `Dialog`, `Popup`, `Standalone`.
`ShellHandle`	Type of the handle returned by `createShell`.
`ShellOptions`	Options accepted by `createShell` and per-`open` overrides.
`ExperiencePlugin`	Opt-in extension point for layering transitions/animations onto display modes.

The shell wraps a @hyperfrontend/nexus broker: send emits a contract action to the feature, and on subscribes to feature messages and the open/close/error lifecycle events. close disconnects the channel; destroy also releases the DOM.

API Reference

ƒ Functions

§function

createShell(options: ShellOptions): 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.

Parameters

Name	Type	Description
§options	`ShellOptions`	Create-time shell options, overridable per `open` call.

Returns

ShellHandle

A handle exposing open, close, destroy, send, on, and isOpen.

Example

Embedding a clock feature

const clock = createShell({ container: '#clock', url: 'https://clock.example.com' })
clock.open({ displayMode: DisplayMode.Dialog, dialogWidth: 530 })
clock.on('timeUpdated', (data) => console.log(data))

◈ Interfaces

§interface

ExperiencePlugin

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.

Properties

§name:string—

Unique plugin name, surfaced in debug logs.

§interface

ExperiencePluginContext

Context handed to an ExperiencePlugin around a feature's mount lifecycle.

Properties

§displayMode:DisplayMode—

The display mode the feature was surfaced in.

§element:HTMLElement—

The root element the display mode mounted (dialog container or embedded frame).

§interface

ShellHandle

Public handle returned by createShell.

Properties

§readonly isOpen:boolean—

Whether the feature channel is currently open (true while connected).

§interface

ShellOptions

Options accepted by the host-side FeatureContract consumer when creating or opening a shell.

Properties

§closeOnEscape?:boolean—

Whether pressing Escape closes the shell; defaults to true.

§container:string | HTMLElement—

Target element (or CSS selector) the embedded feature mounts into.

§contract?:FeatureContract—

Contract describing the feature's actions; replaces the generic default when provided.

§dialogHeight?:number—

Dialog height in pixels (dialog mode only).

§dialogOverlay?:boolean—

Whether the dialog renders a dimmed backdrop; defaults to true.

§dialogWidth?:number—

Dialog width in pixels (dialog mode only).

§displayMode?:DisplayMode—

How the feature should be surfaced; defaults to DisplayMode.Embedded.

§embedSizing?:EmbedSizing—

How an embedded feature is sized; defaults to fill (the iframe fills its container).

§name?:string—

Stable identifier for the feature; seeds the broker name surfaced in debug logs.

§onUnresponsive?:UnresponsivePolicy—

How the host reacts when the feature stops responding; defaults to emit.

§protocol?:SecurityProtocol—

Security envelope to negotiate; defaults to none.

§sharedKey?:string—

Pre-shared key used by the v2 protocol.

§url?:string—

URL of the feature app to load.

§interface

UnresponsiveInfo

Context passed to an UnresponsivePolicy callback when a feature stops beating.

Properties

§displayMode:DisplayMode—

The display mode the unresponsive feature was using.

§lastBeatAt:number—

Timestamp (ms) of the last beat received, or null if none ever arrived.

§missedBeats:number—

Consecutive missed beats that tripped the watchdog.

◆ Types

§type

EmbedSizing

How the feature is laid out when the host surfaces it.

type EmbedSizing = "fill" | "content"

§type

UnresponsivePolicy

What the host does when a feature misses too many heartbeats.
emit (the default) emits an error; unmount also tears the feature down; a callback takes over handling entirely with the UnresponsiveInfo.

type UnresponsivePolicy = "emit" | "unmount" | (info: UnresponsiveInfo) => void

● Variables

§type

DisplayMode

Supported ways a host can surface an embedded feature.
All four modes are built into the SDK.