@embeddr/zen-shell

The plugin host and windowing runtime for Embeddr.

Zen Shell provides the infrastructure that lets Embeddr load, render, and manage plugins as floating panels — including UMD bundle loading, a draggable window manager, a tiling layout engine, WebSocket connectivity, and a global event bus.

What's in here

| Area | Path | Purpose | | -------------- | ------------------------------ | ----------------------------------------------------------------------------- | | Shell | src/shell/ZenShell.tsx | Root shell component — mounts providers, plugin runtime, panel manager | | Panels | src/panels/ | Draggable floating panels, panel manager, UMD panel host | | Plugin runtime | src/runtime/, src/plugins/ | UMD bundle loading, manifest parsing, plugin registry, error boundaries | | Tiling layout | src/layouts/tiling.tsx | TilingLayout component for grid-based panel arrangement | | Event bus | src/events/event-bus.ts | Global typed event bus; core-ui-event-bridge bridges to embeddr-core events | | Providers | src/providers/ | WebSocket, theme, toast, and shell context providers | | Stores | src/stores/ | Zustand stores for panel state and global shell state | | Hooks | src/hooks/ | useTheme, useLocalStorage, useScreenSafeArea | | Client | src/client/ | Plugin-scoped API factory and adapter (sandboxes plugin API calls) |

Usage

Zen Shell is a source-only package — it has no build step and is consumed by packages that do their own bundling (currently embeddr-frontend).

import { ZenShell } from "@embeddr/zen-shell";
import { globalEventBus } from "@embeddr/zen-shell";
import { TilingLayout } from "@embeddr/zen-shell";

The ZenShell component is the top-level host. Mount it inside your app's providers:

<ZenShell pluginManifestUrl="/api/v1/plugins/manifest" />

Plugin system

Plugins are loaded as UMD bundles at runtime. Each plugin declares a manifest that describes its panels, capabilities, and required permissions. The runtime:

1. Fetches the plugin manifest from the embeddr-cli API
2. Loads UMD bundles via dynamic <script> injection (umd-loader.ts)
3. Registers panel types in the plugin registry (registry.ts)
4. Renders panels inside UmdPanelHost with a scoped API surface (api-factory.ts)

Plugins receive a sandboxed EmbeddrPluginApi object — they cannot access the broader app directly.

Event bus

A global typed event bus decouples plugin panels from the shell and from each other:

import { globalEventBus } from "@embeddr/zen-shell";

// Emit
globalEventBus.emit("artifact:selected", { id: "..." });

// Subscribe
const off = globalEventBus.on("artifact:selected", ({ id }) => {
  console.log("artifact selected:", id);
});

// Cleanup
off();

The CoreUiEventBridge component wires embeddr-core WebSocket events into the event bus automatically when mounted inside ZenShell.

Tiling layout

TilingLayout arranges children in a responsive grid. Panels registered as "tiling" panels are managed through this layout rather than the floating panel manager:

import { TilingLayout } from "@embeddr/zen-shell";

<TilingLayout columns={2}>
  <MyPanel />
  <AnotherPanel />
</TilingLayout>;

WebSocket

WebSocketProvider maintains a persistent WebSocket connection to the embeddr-cli server and reconnects automatically. Components and plugins can subscribe to real-time events (execution progress, artifact updates) via the event bus bridge.

Relation to other packages

embeddr-core          (domain models, plugin interfaces)
    ↓
embeddr-plugins       (21+ bundled plugins, UMD bundles)
    ↓
embeddr-cli           (FastAPI server, serves plugin manifests + UMD bundles)
    ↓
@embeddr/react-ui     (shared component library)
    ↓
@embeddr/zen-shell    (plugin host, windowing runtime)  ← you are here
    ↓
embeddr-frontend      (main React app, mounts ZenShell)

License

Copyright 2026 Embeddr Labs and Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0