Napplets
A napplet is a sandboxed application published as a Nostr manifest and a single HTML artifact on Blossom (NIP-5D). It requests data and actions from its host through NAP services. Applesauce connects those requests to your app's existing event store, relay pool, and active account.
This section is for developers and agents adding napplet support to an Applesauce app. Guest napplets use @napplet/core and window.napplet; the APIs here belong to the host application.
Kehto is a host-side toolkit and protocol kernel. Applesauce supplies the integration with your app's data and signer; Paja is Kehto's separate reference developer runtime. NIP-5D and NAP contracts are still evolving, so use the compatible package versions listed in Hosting. See Kehto's architecture and protocol status for the wider ecosystem context.
Choose an integration level
You can use manifest and handler support without running napplets. To embed them, start with the browser host; use services and adapters directly when your app already manages a Kehto shell.
| Your app needs to… | Start with | Package entry point |
|---|---|---|
| Browse, inspect, or publish manifests | Manifests & Discovery | applesauce-common |
| Save preferred apps and route intents | Handlers & Intents | applesauce-common helpers, casts, and models; applesauce-actions/actions |
| Resolve and run sandboxed apps | Hosting | applesauce-extra/kehto/host |
| Connect an existing shell or replace individual services | Services & Adapters | applesauce-extra/kehto |
| Configure DM transports and send routing | Messaging | applesauce-extra/kehto |
How the layers fit together
Manifests describe the app. Helpers validate metadata, casts expose it, models find manifests, and factories build updates and snapshots. A manifest points to the artifact and advertises supported conventions and required domains.
Handlers describe the user's choices. Preferences rank apps for an archetype or intent. Your app checks compatibility, chooses a handler, and delivers its payload. Recommendations can inform a picker.
The browser host runs the app. createKehtoHost resolves and verifies the artifact, mounts it in an application-owned iframe, and manages its Kehto session. It creates the service registry and shell adapter for you.
Services connect the app to Applesauce. Kehto handles the protocol and runtime permissions. Applesauce services answer requests using your store, pool, and signer. Lower-level option builders let you reuse individual adapters with Kehto's service factories.
Your application owns product policy. It provides the surrounding UI, handler selection, consent prompts, signing approval, and any extra services such as theme, notifications, or intent routing.
Kehto library details
Use these references when you need the contracts beneath the Applesauce adapters:
| Library | Responsibility | Reference |
|---|---|---|
@kehto/runtime | Protocol dispatch, capability checks, and service lifecycle | Runtime package |
@kehto/shell | Browser message bridge, source sessions, and injected domains | Shell package |
@kehto/services | Service factories and adapter contracts | Services package |
@kehto/nip | Manifest verification, artifact resolution, and caching | NIP utilities |
Kehto's API reference describes its current library APIs; the Applesauce guides describe the integration supported by this release.
Add support to an existing app
- Set up the browser host with your shared store, loader, pool, and reactive account.
- Add permission and signing UI, then resolve, mount, and await a napplet instance.
- Discover manifests if users need a catalog, and save handler preferences if they need app choices or intent routing.
- Customize services and messaging as your application requires.
For a complete implementation, see the Napplet Loader example. The Browser and Handler Preferences examples cover discovery and selection separately.