The application runtime for overlays. Turn an existing responsive web app into a polished in-page widget or browser extension without rebuilding the app.
Bring your app. Widget Shell makes it safely and convincingly present over another app.
Widget Shell supplies the difficult reusable layer between extension tooling and application UI: isolation, lifecycle, responsive viewport geometry, launchers, focus, accessibility, persistence, loading and recovery, and a capability-based page bridge.
Extension frameworks answer how to build and inject an extension component. Chat widgets provide a polished shell for one company's messenger. Positioning libraries decide where an element belongs.
Widget Shell answers a different question: how does an existing application become an excellent overlay product?
- Bring any owned, mobile-responsive, embeddable application.
- Use one guest application across a floating phone, compact widget, sheet, side panel, full screen, or Lucarne-injected surface.
- Default to a strongly isolated iframe with a stable responsive viewport.
- Grant page access through explicit, validated capabilities rather than unrestricted DOM access.
- Ship the default experience or replace its launcher, chrome, transport, persistence, styles, and framework adapters independently.
Widget Shell is in initial development. The 0.x public contracts are usable but may evolve between minor releases; changes are documented in the changelog.
import { createOverlay } from "@volter-ai-dev/widget-shell";
const overlay = createOverlay({
id: "acme-support",
content: {
kind: "iframe",
src: browser.runtime.getURL("/app.html"),
},
viewport: "mobile-sm",
placement: "bottom-end",
launcher: {
icon: "/icon.svg",
label: "Open Acme",
},
});
overlay.mount();The default preset gives the guest a stable 390 × 667 CSS-pixel viewport. Its collapsed launcher is transparent and unbranded; setting theme.accent opts into a filled treatment. It can be dragged, resized, snapped, and persisted while floating; smaller hosts progressively switch it into sheet and full-screen modes. See the API guide.
- Bring your own app. The guest owns its routing, authentication, data, and application state.
- Safe by default. iframe isolation, strict origins, narrow capabilities, and no evaluated remote code.
- Progressive adoption. Use the finished shell, a framework adapter, or only the framework-free primitives.
- Stable responsive geometry. The guest receives an application viewport, not content-height jitter.
- Exact cleanup. Unmounting restores the host page without leaked nodes, listeners, observers, timers, or URLs.
- Fast while closed. The collapsed launcher is tiny and the guest is lazy by default.
- Accessible as infrastructure. Focus, keyboard, motion, contrast, labels, and reading order are core behavior.
- Integrate; do not replace. WXT, Plasmo, Extension.js, Vite, and application frameworks remain first-class peers.
Widget Shell includes overlay lifecycle, geometry, iframe and Shadow DOM hosts, a guest bridge, default chrome, style tokens, and delivery adapters.
It is not an extension build system, application framework, backend, chat framework, page-scraping toolkit, or universal wrapper for third-party websites. See the product contract and architecture.
The project also publishes an enforced performance contract; the complete extension host currently ships at approximately 7 KiB gzip before the guest application.
Use the extension integration guide for raw Manifest V3, WXT, and Plasmo projects. The framework examples are built nightly with their real toolchains while the merge gate remains headless and fast.
We welcome bug reports, design feedback, documentation fixes, adapters, and focused implementation contributions. Start with CONTRIBUTING.md. Security issues must follow SECURITY.md, not the public issue tracker.
Explore every supported visual state in the live Storybook.
MIT © Volter AI.