# Modulon Popout SDK 0.5.0

> Production browser runtime for detachable windows, recoverable surface sessions, typed cross-window messaging, synchronized state, React integration, and support diagnostics.

Package: @modulonengine/sdk
Language: TypeScript / ESM
Runtime dependencies: none
React: optional peer dependency, >=18
Primary environment: modern desktop browsers

## Start here

- AI integration guide: ./docs/AI-GUIDE.md
- Five-minute quickstart: ./docs/quickstart.md
- Architecture and product boundaries: ./docs/architecture.md
- Public API index: ./docs/api.md
- Security and trust boundaries: ./docs/security.md
- Browser capability matrix: ./docs/browser-matrix.md
- React guide: ./docs/frameworks/react.md
- Testing guide: ./docs/testing.md
- Troubleshooting: ./docs/troubleshooting.md
- Migration from earlier versions: ./docs/migration.md

## Preferred API

Use createModulonHost() in the host page and createModulonPopout() in each popout route. Open windows through runtime.surfaces.open() and handle both the open result and session.ready. Define shared method/event types with defineModulonProtocol() and provide runtime validators at cross-window boundaries. Use createSyncedState()/connectToSyncedState() through the factory configuration for shared browser state.

Package entrypoints:
- @modulonengine/sdk
- @modulonengine/sdk/react
- @modulonengine/sdk/debug
- @modulonengine/sdk/testing

## Required constraints

- Popouts must be opened directly from a user gesture.
- Host and popout must share appId, namespace, protocol, and security policy.
- Serve public/modulon-shared-worker.js from the application origin.
- Auto transport order is opener, SharedWorker, then same-origin BroadcastChannel.
- BroadcastChannel supports RPC, events, and sync but not distributed locks or authority.
- Use exact allowedOrigins/targetOrigin values in production.
- Treat cross-window payloads as untrusted and validate them.
- Review redacted support bundles before sharing.
- Do not use undocumented dist/* imports.

## Scope boundaries

This SDK does not provide docking/window chrome, automatic monitor layouts, WebRTC/WebSocket remote sync, durable backend persistence, game-engine bindings, or native desktop runtimes.

Live documentation: https://modulonengine.com/docs/
Live Operations Console: https://modulonengine.com/operations-console/
Product page: https://modulon.dev/product.html?product=modulon-sdk