Architecture

@hyperfrontend/features is the batteries-included layer on top of @hyperfrontend/nexus. Nexus owns the cross-window messaging protocol; this package owns the frontend glue around it — iframe management, display modes, lifecycle orchestration, shell generation, a CLI, and a dev server — so a feature app and a host app can be developed independently and composed at runtime.

System Overview

A feature app (the hostee) is a normal web app that declares a contract and connects through the hostee SDK. A host app builds a shell that mounts the feature in a display mode and exchanges contract-validated messages with it over a Nexus channel. The CLI turns a feature app into a self-contained shell package that any host installs; the dev server runs both sides locally with a debug UI.

The host never needs @hyperfrontend/features as a direct dependency: it installs the generated shell package, which inlines everything it needs. The two sides only agree on a contract (the actions each emits and accepts).

Design Principles

Standalone core, isolated Nx adapter. The package, CLI, and dev server have no build-tool dependency. The optional Nx generators and executors live in an isolated /nx/* adapter that the core never imports, so Nx integration can be added or ignored without touching the SDK.
```
// ✅ the core SDK
import { createShell } from '@hyperfrontend/features/host'
// ❌ the core never imports build-tool internals
// import { …} from '@nx/devkit'
```

Per-surface subpath isolation. Host, hostee, CLI, and server are independent entry points so a consumer pulls in only what it uses and bundlers tree-shake the rest.

// ✅ a feature app ships only the hostee surface
import { createFeature } from '@hyperfrontend/features/hostee'
// ❌ never re-export the host/CLI/server surface from the hostee barrel

Contract-validated messaging. Every action a side emits or accepts is declared in a FeatureContract; the contract drives validation, the shell type generator, and the debug UI. The contract is the only coupling between host and feature.
Self-contained generated shells. build emits a shell package with zero runtime dependencies — the contract is inlined and direct deps are bundled — so a host installs one package and inherits no transitive install burden.
Security is explicit. The envelope defaults to protocol: 'none' for local development; production builds must opt into v1 or v2 (@hyperfrontend/network-protocol).
```
// ✅ production picks an envelope explicitly
createShell({ url, container, protocol: 'v2', sharedKey })
// ⚠️ 'none' is a local-only default
```
Pure generators, I/O at the edges. Generators are pure (config, contract, tree) => void functions that write to a @hyperfrontend/project-scope VFS tree; all filesystem I/O, prompting, and commits live in the CLI — never in the generators or the SDK.

Module Composition

Module	Subpath	Responsibility
`shared`	`.`	Contract types, contract/config/payload validation, `DisplayMode`, `SecurityProtocol`, control messages, the event emitter, and the `defineConfig`/`defineDevConfig` helpers.
`host`	`/host`	`createShell` factory, the four display modes, iframe/sizing utilities, heartbeat watchdog, and the experience-plugin seam.
`hostee`	`/hostee`	`createFeature` factory, host-window resolution, feature lifecycle, and heartbeat emission.
`cli`	`/cli`	`init`/`build`/`dev` command runners, the tiered `feature.config.` / `hf-dev.config.` loader, and CLI/flag parity; backs the `hf` bin.
`generators`	`/generators`	Pure generators for the shell package, `metadata.json`, the write-once feature module, and contract `.d.ts` types.
`server`	`/server`	Static per-app hosting and the in-browser debug UI (display-mode, resize, message-log, security controls).
`nx`	`/nx/*`	Optional Nx adapter — a `feature` generator and `build`/`serve` executors that delegate to the SDK. Zero `@nx/devkit` dependency.

Data Flow

Mounting a feature and exchanging messages:

Core Interfaces

// Host: build a shell, mount a feature, exchange messages.
function createShell(options: ShellOptions): ShellHandle

interface ShellHandle {
  open(options?: Partial<ShellOptions>): void
  close(): void
  destroy(): void
  send(type: string, data?: unknown): void
  on(event: string, handler: (payload: unknown) => void): () => void
  readonly isOpen: boolean
}

// Hostee: connect a feature app to whatever host embeds it.
function createFeature(options: FeatureOptions): FeatureHandle

interface FeatureHandle {
  send(type: string, data?: unknown): void
  on(event: string, handler: (payload: unknown) => void): () => void
  ready(): Promise<void>
  close(): void
}

// The only coupling between the two sides.
interface FeatureContract {
  emitted: ActionDescription[]
  accepted: ActionDescription[]
}

type DisplayMode = 'embedded' | 'dialog' | 'popup' | 'standalone'
type SecurityProtocol = 'none' | 'v1' | 'v2'