Documentation
    Preparing search index...

    Module @kehto/paja

    @kehto/paja

    Development runtime for local napplet authoring and static pointer-loaded napplet testing.

    Scoped relay and OUTBOX hints use the runtime's destination approvals. Paja's host policy rejects unconfigured local/private relay names, including trailing-dot spellings such as localhost.. Explicitly configured development relays remain available. Its default relay pool has no automatic NIP-42 signer. Network grants do not authorize relay authentication; keep signer-enabled third-party pools separate from napplet-directed traffic. See relay destination policy.

    The runtime is designed to be used from a napplet package script:

    {
    "scripts": {
    "dev": "kehto paja --target-url http://127.0.0.1:5173 -- pnpm vite --host 127.0.0.1"
    }
    }

    The target URL is explicit on purpose. Kehto can spawn any framework command and wait for that URL, but it does not guess which URL the framework chose. Loading that URL through Paja as injected srcdoc lets Kehto install mandatory window.napplet.shell plus enabled optional domains before app code runs. The Kehto host-owned shell prelude completes shell.ready / shell.init and caches capability queries, while a <base> tag keeps the app's own assets and HMR pointed at the target dev server without Vite, Svelte, React, or any other framework lock-in.

    The package provides the typed option model, CLI parser, runtime server, host page, and host config surface. Local target-url mode keeps one target iframe with a reload loop and a development console wired through a real ShellBridge, @kehto/runtime, and service adapters for the current web NAP surface: relay/outbox, storage, identity, keys, config, resource, theme, notify, media, upload, intent, count, link, common, lists, serial, BLE, WebRTC, DM, FS, CVM, and inc. Relay/outbox defaults to live public relays and uses NIP-65 relay-list bootstrap plus kind 3 contact-list reads for identity flows; background kind-0 profile warming runs only for a connected signer account, so a signer-less session with a fixed simulation identity stays read-only. --relay-mode memory is the explicit deterministic fixture mode and does not advertise relay, outbox, count, or DM. shell is the mandatory, non-toggleable handshake domain; the deprecated legacy package path remains an upstream compatibility alias to inc.

    The target iframe is sandboxed without allow-same-origin, so the napplet document has an opaque origin and requests its own assets with Origin: null. <script type="module"> is always fetched in CORS mode, so a dev server that does not allow that origin blocks the napplet's entry module and the frame renders blank. Vite's default server.cors allowlist covers only localhost, 127.0.0.1, and [::1] origins, so it rejects null:

    // vite.config.js
    export default {
    server: { cors: { origin: '*' } },
    };

    Any dev server works as long as it answers Origin: null with Access-Control-Allow-Origin: * or null. Paja probes the target on startup and logs a paja.target.cors.error entry in the message log, plus a console warning, when the target would block the sandboxed frame.

    NAP-RESOURCE exposes window.napplet.resource only to a frame the browser denies all direct network: fetch, XHR, WebSocket, EventSource, beacon, and external subresource loads. A live dev-server frame loads its scripts and HMR socket from the dev origin, so the two cannot be combined.

    When the target's index.html lists resource under napplet-requires, Paja loads it as a network-isolated snapshot: the Paja server fetches the document, and the frame runs those bytes under the same closed CSP as a local single-file target. Nothing is requested from the dev server by the frame, there is no <base> URL, and there is no hot reload; reload Paja after a rebuild. Inline scripts and styles and data: assets work. Anything referenced by URL does not, so serve a self-contained single-file build.

    Paja says so up front. The CLI prints a Target network: isolated snapshot notice with the references that will not load, GET /__kehto/target-network.json returns the same plan, and the browser host logs paja.target.network.isolated in the message log and warns on the console. planTargetNetwork and findExternalAssetReferences are exported for reuse.

    To keep live dev-server loading, declare resource under napplet-optional. The frame then loads live without window.napplet.resource, and Paja logs paja.target.resource.omitted.

    Every drawer section is a flush, independent native accordion: Pointer (in runtime-pointer mode), Interfaces, ACL, Signer, Resource servers, Language models, Messages, then Events last. Headers support Enter/Space, visible keyboard focus and state chevrons; bodies keep their padding and live controls when hidden. Sections start expanded unless a validated origin-local boolean preference says otherwise. The collapsed map uses kehto:paja:sidebar-sections:v1, separately from whole-drawer visibility and resource server values. Storage failures leave session-only toggles usable; collapsing never reloads the running app or discards unsaved drafts.

    The console shows supported interfaces with per-domain injection toggles (green when ready, yellow ⚠ when advertised but unconfigured, red when disabled), runtime ACL controls, Firewall permissions, signer controls, and a filterable message log with visible error details. The log highlights every shell reply that failed: a *.error, a result with error or ok: false, or a *.closed with a reason. A refusal (policy denied, policy-denied, publish denied, denied: <capability>) is badged denied. Everything else, such as relay list unavailable, relay timeout, or count-unavailable, is badged failed, not a denial, so a relay outage is never shown as a firewall block. It starts expanded and collapses to the left with the chevron button in the top bar; the same button brings the whole panel back. The toolbar stays onscreen after restoring a saved collapsed preference, including when no runtime tab is open. Paja allows every interface and operation by default and asks before each link.open; the Firewall panel edits those default rules for every napplet or one. Firewall approval prompts stay visible outside the sidebar, so new napplets can still receive consent before executing. Grant management stays in the sidebar. Collapsing is presentation-only — the target iframe keeps its identity and the loaded napplet keeps running — and Paja remembers the choice per browser origin. In runtime-pointer mode, ACL controls always display and mutate the active tab's resolver-verified d-tag and aggregate hash; a grant or revoke rerenders that same identity immediately. Paja starts with None selected and never asks an available browser extension for its public key on first startup. Choose Dev, NIP-07, or Bunker explicitly; None disconnects and cancels pending connections. The selected method (including None) is remembered per browser origin under kehto:paja:signer-method:v1. Reload restores Dev or reconnects an explicitly selected NIP-07 extension. Bunker restores selected but disconnected: enter its URI again. Only the method is stored, never credentials, keys, URIs, or approvals. Invalid or unreadable storage defaults to None; failed writes still allow selection for the current session. An unavailable extension stays selected with an error, without falling back to another signer. Fixed simulation identity is independent of signing authority. A signer change keeps loaded napplets running and pushes NAP-IDENTITY identity.changed (pubkey: "" on disconnect). Paja reloads the active frame only when the change adds a signer-dependent domain (webrtc, dm, upload) that the napplet declared, or removes one it was admitted. NIP-5D needs a fresh injection for that. Sign, publish, DM send, filesystem picker, Blossom upload, and external-link requests use one serialized in-page confirmation dialog. Deny has initial focus and Escape denies. A napplet-scoped serial or BLE chooser receives runtime approval first; Paja then keeps the selected device host-private until a second approval permits opening the port or GATT connection. Source-owned device sessions close and stop delivery when that authority is revoked. A napplet-scoped sign or publish request defaults to one-time approval. The modal can remember one event kind, all events for the current action, or all signing and publishing from this napplet version. Signing-only permission never implies publication; the combined choice explicitly grants both. The dialog shows the napplet, artifact/version, source scope and signer, with a warning about future effects. Grants bind the active account to the host's verified manifest identity (including publisher) and artifact hash. Signed versions can reuse approval after reload; another manifest, version or account asks again. Local single-file targets use their content hash in a separate local scope. Direct development URLs are mutable, so approvals last only for the current document/frame load and must be renewed after reload; HMR can still change that development session's running code. CVM without a user signer uses a separate, document-scoped host-generated principal; its approvals never transfer to a user account or another host session. Otherwise, unknown identity/account/kind remains one-shot. Denials are never remembered. Signer controls revoke every remembered signing/publication approval; failed durable deletion is reported instead of claiming revocation. Missing browser storage makes new choices memory-only. An ephemeral Dev account changes on a full host reload and therefore asks again. Older signing-only records are retained without gaining publication and emit KEHTO-PAJA-SIGNER-CONSENT-V1 once per host module lifetime; current records stay quiet. Removing a window or changing the signer denies pending signing/publication. Link requests always use the modal, and the external browser handoff runs directly from its approval click with noopener,noreferrer. Other operation permissions remain separate. The remembered choices are a legacy confirmation preference only: every sign request must first pass the runtime Firewall operation approval for its current verified source and exact scope. Actual legacy use warns once per page with FW-PAJA-SIGNER-CONSENT-LEGACY-001; use Firewall grants instead. The Firewall permissions panel shows live grants, revocation, clear, and storage retry. Without browser storage only session/once decisions are offered; failed durable saves block new grants. This is Paja host policy under NAP-RELAY PR #2 at 9f30b350, NAP-OUTBOX PR #32 at 8865f73d and NAP-LINK PR #53 at 50a2cd45, rather than a Kehto kernel default. Upload consent identifies the requesting napplet, file, MIME type, size, selected server, and durable public effect before bytes leave the browser. A denial or a live publish with no accepting relay returns a canonical failure and is not added to Paja's in-memory relay view. Paja's scoped-relay hook likewise waits for the backend result and returns false after denial or transport failure.

    By default, WebRTC needs the browser WebRTC API, live relays, and a connected NIP-44 signer. An explicitly configured multiplayer profile instead uses an isolated temporary key shared with that window’s CVM transport. Paja owns the RTCPeerConnection and data channels, uses signed kind-25050 Nostr events for encrypted offer/answer signaling, and asks for explicit session consent with a network-metadata warning. Napplets receive only NAP session/events and data channel payloads: JSON send payloads as message events and sendBytes payloads, sent as one binary data-channel message, as bytes events. Sessions report maxPayloadBytes from the webrtc.maxPayloadBytes setting (default 64 KiB). The soy-rtc/1 multiplayer profile stays JSON-only and answers sendBytes with unsupported. Napplets never see SDP, ICE state, relay sockets, or peer-connection objects. Connecting or disconnecting a signer updates the runtime's service registration before the replacement iframe loads, so an advertised WebRTC domain can answer requests. The default signaling implementation tracks pinned NAP-WEBRTC 5fae95dd2c8e59bd06c654e0845656add077dcda and the kind/tag conventions in NIP-100 PR #363 at ead1cd6.

    DM is advertised only with live relays and Paja's selected Dev signer, whose runtime-owned secret key can create and unwrap real NIP-17 gift wraps. Sends receive one explicit plaintext/recipient confirmation, publish only verified kind-1059 envelopes through the authorized relay path, and reload encrypted history from relays rather than treating a memory fixture as persistence. Napplets receive normalized NAP-DM messages, never secret keys, seals, rumors, or relay sockets. This implementation follows draft NAP-DM a0a48588.

    FS is advertised only after Paja successfully opens the browser's real origin-private filesystem. Each verified napplet identity gets a durable OPFS /workspace; browser file/directory pickers add session-only opaque virtual mounts after host approval. The backend implements metadata, directory lists, bounded range reads, canonical padded-base64 writes, replace/append/patch, revisions and preconditions, recursive mkdir/remove, atomic handle moves when the browser supports them, and advisory watches over actual storage. Host paths and handles never cross the NIP-5D boundary. This implementation follows draft NAP-FS bd1b9e91.

    Workspace storage and native pickers have separate browser requirements. Firefox can provide OPFS while lacking showOpenFilePicker, showSaveFilePicker, and showDirectoryPicker. In that environment, workspace operations remain usable and the corresponding picker requests return the canonical unsupported result. The Interfaces panel shows workspace and open/save/directory picker availability separately; the message log names a missing picker API when one caused that result. Green fs:read and fs:write ACL controls indicate permission, not browser API support. See the picker compatibility reference.

    The focused host regression runs in Chromium and Firefox after pnpm build: pnpm exec playwright install firefox, then pnpm exec playwright test --config playwright.paja-fs.config.ts.

    Language models configures draft NAP-LLM connections: pick a provider preset (OpenAI over Chat Completions or the Responses API, Anthropic, Google Gemini, OpenRouter, Groq, Mistral, DeepSeek, xAI, Together, Fireworks, Perplexity, Azure OpenAI, or local Ollama, LM Studio, llama.cpp and vLLM servers), enter the model and an optional API key, tick the capabilities the model supports (images, JSON output, and Tool calling with optional Required tool choice and Named tool choice) and choose whether to remember the key. Remembered keys are encrypted with AES-GCM under a PBKDF2-SHA-256 key derived from a vault password you create (at least vault.minPasswordLength characters, default 12); otherwise the key lasts for the page session only. Keys are sent solely to the connection's base URL (HTTPS, or HTTP on loopback) and never to napplets or the message log. The llm interface is advertised whenever the panel is present; it shows ⚠ llm until a connection exists. A napplet's select() then offers to open the panel and answers unsupported until you add one; with connections, a chooser lists the compatible ones. Every generate() shows a consent dialog naming the napplet, route, model, disclosed counts, any tool definitions offered and the number of tool results being sent before any prompt text leaves the browser. Paja relays tool calls to the napplet and never runs one. See Language models.

    Other domains are equally capability-bound. Relay, outbox, and count require live relays; count uses NIP-45 COUNT without downloading events. Storage requires writable localStorage; the memory setting is an unadvertised fixture. Keys requires a document listener, media requires a browser document and uses audio/video elements (OS Media Session integration is optional), notifications require Paja's host renderer, links require browser navigation, and intent requires the installed-catalog/runtime-tab host controller. DM also requires the Dev signer and live relays; FS requires a successful OPFS probe, while picker calls additionally require the corresponding browser API and a host-owned approval click. Missing host boundaries remove those domains from shell.init. For notify, Paja renders attributed text without fetching icons. The shared Firewall approves the exact notification operation/channel before the browser effect; Paja's own permission cache is tied to the current verified app artifact. Window teardown or revocation clears the UI and invalidates pending answers. For link.open, Paja approves the exact HTTP(S) URL and opens it from the click that approved it. When no click is live, such as a link allowed by a standing rule, a host confirmation supplies one; Paja rechecks the approval signal and verified artifact before navigation. It opens external links with noopener,noreferrer. Live relay URLs are validated before advertisement, fixture events and local publish echoes never enter live reads, and relay event sidecars disclose only sources that the relay pool actually observed.

    A signed-in napplet reads Paja identity and social data only through existing identity.getPublicKey, identity.getFollows, and ordinary kind-0 outbox.query messages. Paja exposes no social namespace, direct networking, or signer/key capability for this behavior.

    Paja privately validates the active account's replacement kind-3 contact list, then warms followed kind-0 profile records through its established outbox router. The resulting snapshot is active-account-scoped and memory-only. It is distinct from generic simulation cache mode; it is not napplet-owned storage and has no durable-cache controls. Captured-key request correlation keeps a follows request bound to the account that started it, while generation-safe background writes prevent stale-account data from becoming the active snapshot.

    A normal query can include matching cached RelayEventResult values, but Paja retains the base router's query-wide incomplete and error fields. A cache hit does not make a degraded query complete. Profile winner selection, pagination, follow mutation, durable-cache management, and per-author completeness are outside this behavior.

    NAP-IDENTITY at 6461e4b37c29dc09a20dff35d9515889c4433874 is byte-identical to the recorded napplet/naps master document for this phase. Pinned NAP-OUTBOX at 4589a8f9a16d8aa29b3740e2b3b0cdca11e0976e together with the installed @napplet/nap NAP-OUTBOX types (0.45.0 for host packages) is the PoC contract because current master has no NAP-OUTBOX path. Paja therefore makes no current-master OUTBOX conformance claim. Blossom upload behavior targets pinned NAP-UPLOAD at a7cc17463cbf5d9cb87884b31071bc4fc826034c.

    The static Paja Runtime build is served at /web/paja/ in the GitHub Pages artifact. It uses the same browser host and service adapters, but loads verified napplet HTML from pasted naddr or nevent pointers with hmr: none. Each loaded pointer becomes a closeable header tab; loading an already-running napplet opens a choice to load another instance, switch to the existing tab, or cancel. Each verified tab's Share control opens a dialog with its selectable /web/paja/?naddr=... or /web/paja/?nevent=... app link. Copy app link shows a confirmation on success; blocked or unavailable clipboard access selects the link for manual copying. Apps with advertised intents also offer Create intent link. Share keeps focus and pointer input in the host overlay while the apps remain loaded. The browser remembers open runtime tabs in local storage so returning to /web/paja/ restores the previous pointer set. An explicit pointer in the URL still takes precedence over restored tabs.

    The browser page title follows the active napplet tab name, including when switching or closing tabs. With no active napplet, the title is @kehto/paja.

    The static artifact has no server proxy, so it reads https and blossom resources directly from the browser, with no cookies and no referrer. It drops destinations it can tell are private from the URL: localhost, .local, .internal, .home.arpa and similar names, names without a dot, and private, loopback or reserved IP literals. Blossom bytes are still hash-checked. NAP-RESOURCE asks for DNS-time private-IP checks, which a browser can't make for its own fetches: a public-looking name that resolves to a private address gets through. That is a recorded spec gap. Hosts without CORS headers can't be read this way at all. Configure an optional resource proxy to add those DNS-time checks.

    The static artifact defaults to Paja's standard live relays and memory uploads. To point it at specific live relays or Blossom upload servers, pass comma-separated host lists when generating the artifact:

    PAJA_RELAY_URLS="wss://relay.example,wss://relay.example.net" \
    PAJA_UPLOAD_SERVERS="https://blossom.example" \
    node scripts/build-paja-pages.mjs

    When PAJA_UPLOAD_SERVERS is set, the runtime enables the Blossom upload rail and also makes those servers explicit NAP-RESOURCE fallbacks. It is not needed for read-side discovery: resources learned through OUTBOX use their event hints and hinted-author/publisher server lists first, then the active shell user's published list, the current window's verified pointer-manifest servers, and finally configured runtime fallbacks.

    In runtime-pointer mode, Paja can also open a napplet straight from disk. Use Open file… next to Load, or drop an index.html anywhere on the Paja page (not onto a running napplet frame, which receives its own drag events). The file opens in a new runtime tab named after the file.

    • Identity comes from the bytes. Paja hashes the exact file bytes (sha256) and derives aggregateHash as the NIP-5A aggregate over the single /index.html path entry. That is the same derivation the resolver checks for a published single-file napplet, so editing the file gives it a new identity. The dTag comes from the NIP-5D publishing metadata <meta name="napplet-id" content="…">. Without it, Paja uses local-<file-stem>.
    • Same loading path as verified pointers. Paja registers the identity before the frame runs. It injects the Class-1 CSP (with connect-src 'none', since a local file has no relay or Blossom hints) and then the runtime-owned window.napplet prelude, including enabled optional domains. The bytes go in through srcdoc under the same allow-scripts sandbox.
    • Development only and unverified. A local file has no signed manifest. It never enters the installed napplet catalog, never becomes an intent delivery target, has no share link, and is not restored after a page reload.
    • Self-contained single-file HTML only. A srcdoc document has no base URL, and the CSP denies network loads, so relative <script src>, stylesheets, and images do not load. Paja lists relative references it finds in the status line and the message log. Build with an inlining bundler (for example vite-plugin-singlefile). Opening a folder or zip of assets is not supported.

    Paja stores immutable resolver-verified manifest facts separately from live tabs. Closing a frame leaves its catalog record available for cold starts; explicit artifact removal deletes it. Restored pointers are reverified before entering the catalog. Entries preserve exact conventions and ordered parameter names under publisher/kind-safe opaque IDs, including nameless root and snapshot artifacts. The target's resolved intent domain must be available; INC is not required.

    Catalog installs, replacements, removals, and user default-handler updates emit intent.changed to eligible open napplets (napplet.intent.onChanged(...)). Replacements notify both removed and added archetypes, once per slug, using the current filtered catalog. A no handler rejection remains terminal: callers must retry explicitly; installing a handler does not replay the failed invocation. This follows napplet/naps NAP-INTENT on master (last changed at e5308ac), whose runtime behavior recommends notifications on catalog/default changes.

    Selection uses exact contracts and user-owned default, chooser, recommendation, and explicit-authorization policy. Explicit handler IDs require sender-aware authorization and cannot address an arbitrary running frame.

    When no installed handler is compatible with an invoke, Paja doesn't reject straight away. It opens No installed app opens this, which names the archetype, action, and convention. Nothing touches the network until the user presses Search for apps. Paja then asks the configured relays for manifests of every NIP-5D manifest kind whose i tag is the exact convention. If the request carried a handlerHint, the same search also looks up that coordinate, and a result for exactly that coordinate is listed first as suggested by the app. The hint's relays come from the napplet, so they go through the same relay policy as other napplet-supplied relays: public wss: or explicitly configured. Each result must have a valid signature and must advertise the same archetype (z) and exact convention (i). Results already installed are skipped. The list appears under Not installed yet and is capped by intent.discoveryLimit. When no relay can be reached, Paja says the search failed. It doesn't say that no app exists, and it never reports a denial.

    Picking a result runs the ordinary verified pointer load: event signature, exact coordinate, and NIP-5A artifact hash. Paja then installs the result and delivers to it, and Always use this app makes it the default. Search results are never added to available() or handlers() and are never shown to napplets. The resolver uses a pick only when the reloaded, verified catalog entry supports the convention. An explicit catalog handler never triggers a search. Cancelling, finding nothing, or a failed install keeps the original rejection (no handler, unsupported action, or unsupported convention). This uses the MAY in NAP-INTENT's "Recommended handler resolution" on napplet/naps master at 377bf939.

    The App handlers sidebar section lists every archetype that has an installed handler. For each one it shows the user's default, the other candidates, and their conventions. Make default and Forget default change the per-archetype default. Uninstall removes the handler from the catalog and from the saved catalog pointers, and also forgets any default that pointed at it. Every change emits intent.changed. Napplets can't reach this panel and can't change defaults. A tab still open on an uninstalled handler reinstalls it the next time that tab is restored.

    The controller retains work before returning acceptance. It then opens or reuses a verified target, waits for its registered source and real shell.ready, checks that the generation is current, and sends one target-only intent.deliver. Replacement, readiness failure, and terminal send failure remain host-observable controller outcomes; they do not produce a second source result. Accepted work survives source teardown and is never replayed by tab restoration.

    Paja activates delivered handler tabs because its stage shows one tab at a time. behavior.focus is advisory; reuse: false creates a new surface. Existing caller tabs remain open. Installed contracts and domains appear in pointer diagnostics.

    The Paja CLI starts the package server, which renders the same host page used by the static runtime. Both load browser-host.js; its single-window, tab, local file, and verified-pointer routes all pass executable HTML through admitBrowserDocument. There is no separate bench app or second executable iframe loader in this repository.

    Kehto provides the optional window.napplet.shell interface for environment information. Other domains route through trusted iframe creation identity independently of readiness. supports(domain) queries namespace presence locally. See the living NAP-SHELL.

    Before Paja assigns verified pointer or development bytes to srcdoc, it uses admitBrowserDocument to approve the declared interfaces and any explicit direct browser origins. Required denial blocks launch; optional denial narrows the injected namespace and later shell environment. The host registers the trusted source before the approved document executes. The injected CSP defaults to closed remote source lists. Relay and Blossom discovery hints select mediated services only and never grant the iframe direct browser traffic.

    Unsigned development HTML can request interfaces with space-separated <meta name="napplet-requires" content="shell relay"> and <meta name="napplet-optional" content="media"> declarations. They request approval; they do not grant it. Paja binds each development grant to the exact target URL and fetched HTML hash, so editing the document requires a new approval. A live dev server uses directive-specific browser source approval for its script, style, image, font, worker, media, and connection sources. That live frame cannot receive resource: NAP-RESOURCE allows it only in a frame with no direct network. A target that lists resource under napplet-requires is loaded as a network-isolated snapshot instead (see Targets that require resource). When no development declarations exist, Paja offers available interfaces as optional for the current session.

    Hosts can pass csp to createPajaRuntimeHostConfig:

    const config = createPajaRuntimeHostConfig({
    pointer,
    csp: {
    connectOrigins: ['https://api.example'],
    },
    });

    Each explicit origin is a separate network approval. Supported csp.directives entries are reduced to exact origins for their named source directive and require the same approval; unsupported directives and broad source expressions fail closed. Browser sources follow CSP scheme/port matching, including HTTP to HTTPS upgrades; they are not literal origin-equality checks. The approval UI discloses this when relevant. The shared CSP still denies frames, objects, manifests, and unlisted sources. Set frame-ancestors on the host HTTP response, not in a meta policy. See the shared policy contract.

    The Paja host page carries Content-Security-Policy: frame-src 'none' in its <head> (renderNappletFramePolicyMeta() from @kehto/shell), so a napplet cannot navigate its frame away from the verified srcdoc at any time, including before its first load, which NIP-5D's replacement evidence cannot observe. Paja refuses to load a napplet into a frame whose host page lacks it.

    The host page also carries <meta name="referrer" content="no-referrer"> and <base href="./">, and every napplet frame gets referrerpolicy="no-referrer" (@kehto/shell's renderNappletReferrerPolicyMeta(), renderNappletHostBase() and denyNappletReferrer()), so a napplet reads neither Paja's URL from document.referrer nor its query (opened pointers, intent links) from document.baseURI. When the experimental nested-context lock resolves on, Paja also applies the resource-hint lock and refuses static dns-prefetch, preconnect and prerender links. See the NIP-5D conformance policy.

    Environment simulation can be supplied through CLI flags or a JSON config file:

    The old --firewall-mode and simulation.firewall settings are rejected because they never granted a scoped permission. Use the Firewall approvals panel for interface, resource, and network decisions. Simulation settings can still restrict availability or select test backends, but cannot approve a target.

    kehto paja \
    --target-url http://127.0.0.1:5173 \
    --identity-mode fixed \
    --identity-pubkey 4444444444444444444444444444444444444444444444444444444444444444 \
    --relay-mode disabled \
    --capability relay:off \
    --capability outbox:off \
    --theme light \
    --config-value 'density="compact"'
    {
    "targetUrl": "http://127.0.0.1:5173",
    "simulation": {
    "identity": {
    "mode": "fixed",
    "pubkey": "4444444444444444444444444444444444444444444444444444444444444444"
    },
    "relay": { "mode": "disabled" },
    "capabilities": { "domains": { "relay": false, "outbox": false } },
    "theme": { "mode": "light" },
    "config": { "values": { "density": "compact" } }
    }
    }

    Configured config.values are only a seed for identities with no saved settings. A napplet must register a valid NAP-CONFIG schema before any values are delivered. Paja then validates/defaults the seed, persists commits under the host-resolved (dTag, aggregateHash), and exposes a shell-owned settings dialog; napplets remain read-only. If durable browser storage or that host UI is unavailable, Paja does not advertise config.

    Every Paja timeout, interval, cap and abuse bound is a user-changeable default. Open Settings in the top bar to edit them. The dialog has one tab per group below (arrow keys, Home and End move between tabs) and is generated from the settings registry, so it lists every key. On a failed save, every tab holding an invalid value is marked "needs fixing" and the first one opens with focus on the field. All defaults are defined in one file, packages/paja/src/settings-registry.ts. Saved values persist per host origin under kehto:paja:settings.v1 (overrides only) and are restored on every visit. Corrupt, retired or out-of-range stored entries are dropped rather than clamped; if storage is unavailable, changes apply for the session only. Most changes take effect on the next operation; anything a running napplet or service already captured applies after Save and reload. Napplets cannot read or write these settings.

    A config file can seed the same keys under settings. Browser-scope keys become the host page's defaults (a saved GUI override still wins); server-scope keys apply to the CLI and server process and are shown read-only in the dialog. Unknown keys and out-of-range values in a config file are an error, not a silent clamp.

    {
    "targetUrl": "http://127.0.0.1:5173",
    "settings": {
    "relay.liveQueryWaitMs": 8000,
    "server.resourceTimeoutMs": 60000
    }
    }

    Bounds keep abuse guards from being disabled (no zero, negative or unbounded caps), and security floors can only be raised: vault.minPasswordLength, vault.minDistinctChars, vault.pbkdf2Iterations (new vaults only; an existing vault keeps the iterations it was created with) and webrtc.roomMinChars. --port and --ready-timeout stay CLI/config options.

    Numbers that are not settings, because changing them would break a wire contract or a persisted format: Nostr event kinds (named in nostr-kinds.ts), crypto sizes, HTTP status codes, reserved address ranges, MIME magic bytes, unit conversions, and presentation values such as CSS sizes. settings-guard.test.ts fails on any new bare number that is neither registered nor listed there with its reason.

    NAP-FS limits, NAP-WEBRTC maxPayloadBytes and NAP-RESOURCE caps are shell policy in their drafts (NAP-FS bd1b9e9, NAP-WEBRTC fb4dd6f, NAP-RESOURCE ae5b9c6), so Paja advertises and enforces the effective setting.

    Key Setting Default Range
    Relays and queries
    relay.liveQueryWaitMs Live relay query and connect wait 4000 ms 250–120000
    relay.hostQueryTimeoutMs Host-owned relay query timeout 5000 ms 250–120000
    relay.contactListCandidateLimit Contact-list candidates per lookup 64 1–1024
    relay.profileQueryLimit Events per profile or list query 16 1–500
    relay.eventLookupLimit Events per id lookup 8 1–500
    relay.replaceableLookupLimit Events per relay-list lookup 2 1–100
    relay.missingProfileQueryMinimum Minimum batch size for missing profiles 10 1–500
    social.followParseYieldEvery Follow tags parsed before yielding 64 1–10000
    social.profileWarmYieldEvery Profiles warmed before yielding 64 1–10000
    Resources and Blossom
    resource.maxBytes Maximum resource size 10485760 bytes 1024–536870912
    resource.maxUrls URLs per bulk request 100 1–1000
    resource.maxServers Blossom servers tried per blob 8 1–64
    resource.maxRedirects Redirects followed per fetch 5 0–20
    blossom.serverListTtlMs Server-list cache lifetime 300000 ms 0–86400000
    blossom.maxResourcesPerWindow Tracked resources per napplet 256 1–10000
    blossom.maxContextsPerResource Contexts kept per resource 8 1–256
    blossom.maxServerListChars Maximum server-list event size 262144 chars 1024–16777216
    blossom.maxUriHints Server hints per blossom: URI 8 0–64
    blossom.maxUriChars Maximum blossom: URI length 8192 chars 256–65536
    Filesystem
    fs.maxReadBytes Maximum bytes per read 1048576 bytes 1–268435456
    fs.maxWriteBytes Maximum bytes per write 1048576 bytes 1–268435456
    fs.maxRevisionBytes Maximum file size for revision hashing 16777216 bytes 1–1073741824
    fs.maxWatchCount Active watches per napplet 16 1–256
    fs.watchIntervalMs Watch polling interval 1000 ms 100–60000
    fs.encodeChunkBytes Base64 encode chunk size 32768 bytes 1024–65536
    WebRTC
    webrtc.maxPayloadBytes Maximum payload per send 65536 bytes 1024–1048576
    webrtc.maxSessionsPerWindow Sessions per napplet 4 1–64
    webrtc.maxPeers Peers per session 8 1–64
    webrtc.signalMaxAgeSeconds Maximum signal age 300 s 10–3600
    webrtc.signalLookbackSeconds Signal subscription lookback 60 s 0–3600
    webrtc.iceGatherTimeoutMs ICE gathering timeout 8000 ms 500–120000
    webrtc.bufferedAmountLimitBytes Data-channel buffer limit 1048576 bytes 16384–67108864
    webrtc.seenSignalCache Remembered signal ids 256 16–65536
    webrtc.roomMinChars Minimum room length 8 chars 8–128
    webrtc.roomMaxChars Maximum room length 128 chars 8–1024
    webrtc.channelMaxChars Maximum channel label length 64 chars 1–1024
    webrtc.protocolMaxChars Maximum protocol length 64 chars 1–1024
    Multiplayer WebRTC profile
    mp.maxMessageBytes Maximum message size 16384 bytes 1024–1048576
    mp.roomMaxChars Maximum room length 256 chars 1–4096
    mp.maxPeers Peers per room 8 1–64
    mp.channelMaxChars Maximum channel length 64 chars 1–1024
    mp.protocolMaxChars Maximum protocol length 128 chars 1–1024
    mp.maxSessions Rooms per napplet 4 1–64
    mp.iceGatherTimeoutMs ICE gathering timeout 8000 ms 500–120000
    mp.signalExpirationSeconds Signal expiration 60 s 5–3600
    mp.signalMaxAgeSeconds Maximum signal age 60 s 5–3600
    mp.signalLookbackSeconds Signal subscription lookback 10 s 0–3600
    mp.rateWindowMs Rate-limit window 1000 ms 100–60000
    mp.maxMessagesPerWindow Messages per window 240 1–100000
    mp.maxBytesPerWindow Bytes per window 524288 bytes 1024–67108864
    mp.maxSignalsPerWindow Signals per window 32 1–10000
    mp.maxQueuedPerPeer Queued messages per peer 4 1–1024
    mp.maxSignalChars Maximum signal size 64000 chars 1024–1048576
    mp.sdpMaxChars Maximum SDP size 32000 chars 1024–1048576
    mp.nonceMaxChars Maximum nonce length 64 chars 8–1024
    mp.seenSignalCache Remembered signal ids 2048 16–65536
    mp.maxRetiredPeers Retired peer incarnations per room 256 1–65536
    mp.joinTimeoutMs Peer join timeout 45000 ms 1000–600000
    mp.tickIntervalMs Room maintenance interval 2000 ms 100–60000
    mp.bufferedAmountLimitBytes Data-channel buffer limit 262144 bytes 16384–67108864
    Intents and links
    intent.maxDeliveryAttempts Delivery attempts ceiling 10 1–100
    intent.launcherReadyTimeoutMs Launcher ready timeout 10000 ms 1000–600000
    intent.launcherOutcomeTimeoutMs Launcher outcome timeout 10000 ms 1000–600000
    intent.linkMaxBytes Maximum app-link size 16384 bytes 1024–1048576
    intent.discoveryLimit Not-installed intent handlers offered per search 20 1–200
    link.approvalClickWindowMs Link approval click window 1000 ms 100–10000
    link.labelMaxChars Maximum link label length 256 chars 1–4096
    Firewall
    firewall.maxRequirements Requirements per approval request 128 2–1024
    firewall.maxGrants Grants in the permission table 2048 64–16384
    firewall.maxGrantsPerNapplet Grants one napplet may hold 512 16–16384
    firewall.promptOpenOrigins Relay origins listed open in a prompt 5 0–1023
    Signer
    signer.nip46TimeoutMs Remote signer request timeout 30000 ms 1000–600000
    signer.previewChars Content shown in signing prompts 240 chars 16–10000
    signer.consentMaxSubjects Remembered consent subjects 128 1–10000
    signer.consentMaxKindsPerSubject Remembered kinds per subject 128 1–10000
    signer.consentMaxIdentityChars Maximum consent identity length 512 chars 64–8192
    Language models
    llm.modelsTimeoutMs Model list timeout 8000 ms 500–120000
    llm.maxConnections Saved connections 32 1–256
    llm.connectionNameMaxChars Maximum connection name length 64 chars 1–1024
    llm.presetIdMaxChars Maximum preset id length 64 chars 1–1024
    llm.modelIdMaxChars Maximum model id length 200 chars 1–4096
    vault.minPasswordLength Minimum vault password length 12 chars 12–256
    vault.minDistinctChars Minimum distinct password characters 4 chars 4–64
    vault.pbkdf2Iterations PBKDF2 iterations for new vaults 600000 600000–10000000
    Multiplayer providers
    cvm.discoveryTimeoutMs Provider discovery timeout 15000 ms 1000–300000
    cvm.serverRequestTimeoutMs Server request answer window 30000 ms 1000–300000
    cvm.discoveryMaxBytes Maximum discovery document size 1000000 bytes 1024–67108864
    cvm.discoveryEventLimit Events per discovery query 64 1–1000
    cvm.referenceMaxChars Maximum discovery input length 2048 chars 64–65536
    cvm.toolNameMaxChars Maximum tool name length 256 chars 1–4096
    cvm.maxSavedFamilies Saved provider families 16 1–256
    cvm.familySourceMaxChars Maximum saved family source length 4096 chars 64–65536
    multiplayer.textMaxChars Maximum configuration text length 256 chars 1–4096
    multiplayer.maxRelays Relays per configuration 16 1–256
    multiplayer.maxTools Tools per family 64 1–1024
    multiplayer.maxRegistryFamilies Registry families 16 1–256
    multiplayer.maxIceServers ICE servers 8 1–64
    multiplayer.maxIceUrls URLs per ICE server 8 1–64
    Development target
    target.maxDTagChars Maximum development d tag length 128 chars 1–1024
    target.maxNapDeclarations Development NAP declarations 64 1–1024
    target.maxReportedAssets Relative assets listed in diagnostics 8 1–1000
    target.maxReportedReferences Network references listed in diagnostics 8 1–1000
    target.runtimeWaitMs Pointer resolution relay deadline 5000 ms 250–300000
    target.failureReasonChars Characters per relay failure reason 160 chars 16–4096
    target.failureReasonCount Relay failure reasons shown 3 1–50
    target.pointerReplacementLimit Replacement manifests offered for a gone nevent 50 1–500
    Console and indicators
    console.messageLogLimit Messages kept in the log 500 10–100000
    console.messageLogVisibleRows Messages rendered in the log 120 10–10000
    notify.badgeMaxCount Largest badge count shown 9999 9–1000000
    notify.maxActions Actions per notification 3 0–3
    gamepad.axisDeadzone Stick deadzone 0.12 0–1
    gamepad.buttonThreshold Button press threshold 0.05 0–1
    gamepad.activityHoldMs Controller activity highlight 420 ms 0–10000
    Server (config file only)
    server.readinessPollIntervalMs Target readiness poll interval 250 ms 50–60000
    server.shutdownGraceMs Shutdown grace before force close 500 ms 0–60000
    server.requestBodyTimeoutMs Request body timeout 10000 ms 1000–300000
    server.requestBodyMaxBytes Maximum request body 4096 bytes 256–1048576
    server.resourceMaxBytes Maximum proxied resource size 10485760 bytes 1024–536870912
    server.resourceTimeoutMs Proxied resource timeout 30000 ms 1000–600000
    server.resourceProxyPreflightMaxAgeSeconds Standalone resource proxy preflight cache 600 s 0–86400
    server.targetNoticeTimeoutMs Target network notice timeout 2000 ms 100–60000
    server.discoveryGraceMs Managed command URL discovery grace 1000 ms 0–60000

    Paja keeps memory as the default unadvertised upload fixture. It does not register window.napplet.upload, return success, or store bytes. Opt into real Blossom storage with a shell-owned server and an active Dev, NIP-07, or NIP-46 signer:

    kehto paja \
    --target-url http://127.0.0.1:5173 \
    --upload-mode blossom \
    --upload-server https://blossom.example \
    -- pnpm vite --host 127.0.0.1

    Paja prompts with the napplet identity, file details, selected server, and a public/durable warning before it signs or sends bytes. Production servers must use HTTPS; plain HTTP is accepted only for loopback development hosts. The server must allow Paja's browser origin, PUT and OPTIONS, plus the Authorization and Content-Type CORS headers.

    With runtime permissions enabled, Paja first prepares the selected Blossom /upload endpoint and signer identity without prompting, signing, or sending bytes. Firewall then approves the exact upload resource (including byte digest, size and media details) together with the selected network origin. Paja's confirmation and Blossom signing run only inside that approved lifetime. Revocation or signer replacement aborts the upload and suppresses later status updates. A returned public CDN URL is result metadata; it does not grant the napplet direct network access to that URL.

    Explicit servers win. With no explicit server, Paja may use an independently warmed snapshot of the active signer's newest BUD-03 kind 10063 server tags. upload.info and upload.upload never initiate that discovery. Pointer loader Blossom hints are artifact sources, not upload policy. The current path uses the first server only, returns its direct HTTP(S) URL, and does not mirror or construct BUD-10 URLs.

    Completion requires the server descriptor to confirm the exact local SHA-256 and byte size as a non-negative safe integer. Missing or mismatched proof is a failed result even after an HTTP success. The configured identity, provider, signer, discovery author, and signed authorization pubkeys must agree; a fixed pubkey without signEvent is read-only. This implements the draft NAP-UPLOAD at a7cc174.

    The development sidebar's Resource servers textarea adds read-only Blossom lookup origins in both target-URL and runtime-pointer modes. Enter one public HTTPS origin per line (cdn.example is shorthand for https://cdn.example) and press Save. Blanks are ignored and equivalent origins are deduplicated in first-seen order. A bad line rejects the whole save without changing the active or saved list; credentials, paths, queries, fragments, HTTP and obvious local/private hosts are rejected. Saving blank clears only these extras.

    Valid saves apply to subsequent Blossom requests across all running tabs, without reloading their frames. The list persists in the host origin's localStorage; if storage fails, it remains usable session-only, and the status warns that an older saved list may return after reload. Extras are appended after existing URI/event/user/window/configured defaults. The combined eight-server cap remains: extras may not be reached if earlier candidates fill it. This setting does not change upload destinations, per-napplet NAP-CONFIG, initial pointer/artifact loading, direct HTTP(S) resource URLs, or napplet CSP/network grants. Each actual HTTP(S) destination still requires authorization and must pass the proxy address policy below.

    Paja redirects HTML requests using an alias hostname to its configured host origin before issuing the proxy capability cookie. Resource proxy requests remain restricted to that canonical origin.

    Paja resolves HTTP(S) resources through its protected, same-origin POST /__kehto/resource endpoint. The resource request and each actual network destination have separate authorization requirements; an interface grant or Blossom server hint grants neither. The resolver requires the request-bound network authorization callback and refuses network access when it is absent. The proxy validates its host, main-frame Origin, JSON POST, and server-instance HttpOnly cookie before DNS. It pins a permitted public address to the connection, preserves TLS hostname checks, omits upstream credentials/referrer, and bounds responses to server.resourceMaxBytes and server.resourceTimeoutMs (default 10 MiB and 30 seconds). Private, loopback, and other blocked special-purpose addresses are rejected, including development loopback targets.

    A resource proxy is optional. Without one, the static /web/paja/ build reads https and blossom resources directly and drops private destinations it can see in the URL. A proxy adds what the browser can't do: DNS-time checks that catch public-looking names resolving to private addresses, hop-by-hop approval of every redirect, and reads from hosts that don't send CORS headers. To use one, run the standalone proxy and point the static build at it:

    kehto paja resource-proxy --allow-origin https://kehto.github.io --port 8787
    

    There are two ways to point the build at it. Set PAJA_RESOURCE_PROXY_URL when running node scripts/build-paja-pages.mjs (or pass resourceProxyUrl to createPajaRuntimeHostConfig), or enter the URL in the Resource proxy field under Resource servers, which is saved for that host origin. The URL must be HTTPS, or HTTP on localhost/127.0.0.1, and a napplet can't set it.

    The standalone proxy uses the same DNS-pinned transport, caps and redirect hand-back as the local endpoint, so NAP-RESOURCE's DNS-time private-IP checks (napplet/naps#80 @ ae5b9c6) still apply. It answers only --allow-origin origins over CORS, including the preflight, and refuses to start without one. It doesn't authenticate callers, because a non-browser client can send any Origin. Think of it as an open fetch proxy limited to public addresses, server.resourceMaxBytes and server.resourceTimeoutMs, so rate-limit it if you expose it. The proxy sees every resource URL it fetches and could alter plain HTTPS bytes. Blossom bytes are still hash-checked in the browser. The browser sends no cookies to a remote proxy, and it treats a 404 as not-found only when the proxy marks it as the upstream reply. server.resourceProxyPreflightMaxAgeSeconds (default 600) sets the preflight cache.

    Redirects return metadata to the trusted resolver instead of redirecting the browser. The resolver permits at most five hops, authorizes each destination, and repeats the proxy's DNS/address checks. Cancelling the host request aborts upstream work. Remote resource responses no longer depend on allowing the opaque iframe origin through upstream CORS. See the resource proxy policy for caller checks, address policy, deadlines, and regression coverage.

    Paja classifies returned bytes itself. Its classifier recognizes checksum-valid Game Boy ROM headers as application/vnd.nintendo.gb-rom; upstream media types never establish the result MIME. HTTP(S) and locally decoded data: bytes must have a recognized type; opaque invalid-UTF-8 or NUL-bearing binary remains rejected. Only capped, SHA-256-verified canonical Blossom resources may return unknown opaque bytes as application/octet-stream. Recognized formats retain their sniffed MIME. SVG, HTML, XML and script prefixes remain blocked, even with NUL or invalid-UTF-8 suffixes; upstream headers never override classification. Byte-identifiable UTF-16 markup is checked by decoding the complete capped buffer; identifiable UTF-32 document signatures are conservatively rejected. This encoding guard is not a general markup parser.

    data: remains locally decoded. blossom: is a separate, content-addressed boundary and is advertised because each request may provide server locations without a host default. For example, reads accept blossom:<hash>.gbc?xs=cdn.example&as=<pubkey>&sz=32768 and blossom:sha256:<hash>.gbc?xs=cdn.example&sz=32768. Internal event-reference keys and synthesized references use blossom:<hash>. Napplet-supplied resource cache keys remain unchanged, as NAP-RESOURCE does not require URL canonicalization. Actual sha256: alias reads/server-resolution requests emit KEHTO_COMPAT_BLOSSOM_SHA256 once per host module lifetime, with replacement guidance and no URL/hash payload. Canonical requests stay quiet. Repeated xs and as are supported without an observed event. Paja accepts only public-looking HTTPS origin hints (scheme-less domains use HTTPS), discards invalid/private literals, and deduplicates them. Unlike BUD-10's suggested HTTP retry, URI hints never enable public HTTP. For a Blossom URL previously returned to the same napplet window by outbox.getEvent, outbox.query, or outbox.subscribe, Paja retains bounded event context without prefetching bytes. Resolution tries URI xs and event-local server hints first, then lazily queries URI as, event-hinted authors' and the event publisher's newest BUD-03 kind 10063 lists through host-configured NIP-65 bootstrap relays and the selected author relay, then queries the active shell user's BUD-03 list through the same approval-bound relay path, then uses the current window's verified pointer-manifest servers, followed by upload-runtime fallbacks and saved extra resource servers. Every bootstrap and author relay is authorized as its exact ws:/wss: destination before its socket opens. The host uses only configured discovery/super relays for bootstrap discovery, including contact-list and followed-author warming. Paja neither reads nor calls the obsolete NIP-07 getRelays() extension property, including during signer initialization and account changes; there is no signer-bootstrap cache. The retained NAP identity.getRelays operation returns an empty relay map for unsupported external-user metadata, not host URLs presented as user NIP-65 preferences. This follows current NIP-07 (checked 2026-11-12) and NAP-IDENTITY at 43cb3a4, which permits empty unsupported results. The user-list lookup works independently of upload mode; an upload runtime may reuse the same servers when present. ROM-specific event and publisher locations retain priority over the user/runtime fallbacks. URI length is capped at blossom.maxUriChars (default 8192 characters); retained unique xs, the complete author lookup list, and combined server candidates are each capped at eight by default (blossom.maxUriHints, resource.maxServers). Both prefixes require exactly 64 hex characters, with an optional single ASCII-alphanumeric extension preserved in GET /<hash>.<ext>; no query hints reach the blob server. Extensions and upstream headers never establish MIME. Fragments, path injection, malformed escapes/authors, and invalid or repeated sz fail with invalid-request before discovery. sz must be a positive decimal safe integer; sizes above resource.maxBytes (default 10 MiB) fail too-large. Paja checks a numeric Content-Length before reading and always checks actual bytes against sz; a size or hash mismatch is decode-failed unless fallback succeeds. Hash-only event context stays window-scoped, without transferring extension/size or retaining request hints. Byte caches retain the original URL and identity scope; public author lists reuse five-minute cache/single-flight lookups, with incomplete misses retryable.

    BUD-10 at b5bd280 requires lowercase hashes and an extension (default .bin) for emitted references. Extensionless reads, mixed-case hashes, and the sha256: alias are deliberately retained local compatibility, not a full BUD-10 conformance claim. Upload URI generation is unchanged. Paja verifies SHA-256 and byte MIME after authorized proxy retrieval. The checked NAP-RESOURCE draft at ae5b9c6 uses canonical id correlation, a single url or ordered urls list, and padded RFC 4648 base64 wire bytes. The injected web API converts verified wire bytes to Blob values; a JavaScript Blob is not the wire payload. Per-item bulk outcomes preserve input order. The old requestId input, object-form requests list, and wire-level servers hint have been retired from this contract. Use URI hints or host-owned resolver configuration for Blossom discovery. See RESOURCE_FIELDS in the compatibility register.

    Verified manifest servers remain source-scoped Paja host policy under the NIP-5D draft at 5560820. Neither those hints nor stored extra servers grant iframe network authority.

    The shared launch admission and CSP isolate mediated resource frames from direct browser traffic. NAP-RESOURCE requires direct-network denial before exposing resource, including remote script, image, style, font, and worker paths as well as connect-src. The proxy and service approval checks alone do not stop a frame with permissive CSP from contacting remote servers. Explicit direct-network frames use the compatible interface set defined by that host policy; required interfaces cannot be silently dropped. Paja's host-injected base URL is limited to the exact approved development origin so relative assets resolve. SVG rejection rather than rasterization and the retained Blossom URI aliases are also bounded host behavior, not a claim of complete draft conformance. Publisher discovery follows Blossom BUD-03 at b5bd280.

    Full package docs: docs/packages/paja.md. Getting started: docs/how-tos/paja-getting-started.md. Local authoring how-to: docs/how-tos/paja-local-authoring.md. Generated API module: docs/api/modules/_kehto_paja.html (run pnpm docs:api).

    Current manifests use a direct artifact x hash, plain-text content, role-matched z/i intent declarations, and required R / optional O domains. Kehto also accepts legacy aggregate events through an isolated compatibility adapter. Existing aggregateHash host/cache/ACL fields carry the verified artifact hash for current events; legacy identities keep their original aggregate. Both paths verify signatures and bytes before runtime injection and srcdoc execution. For the schema and removal boundary, see event migration.

    Paja loads napplets that declare unknown or unavailable domains. Optional O integrations load quietly so the napplet can gracefully degrade. For unavailable required R domains (or legacy requires declarations), Paja logs a warning per frame navigation that full functionality may be unavailable, then continues. Declarations never grant capabilities: unsupported or disabled domain objects remain absent from window.napplet. Check namespace presence before using an experimental integration. Paja does not implement an experimental protocol merely because a manifest names it.

    This follows NAP-INTENT PR #106 at fc121fc264615482143eda86125863d2e1f741a2 and NIP-5D PR #2303 at 020cb8b33a9e4c6b8ca4b2f9d0ed0a67843b68f7.

    For a verified app with advertised intents, choose Share → Create intent link. Select its convention, include the text parameters you want, or switch to JSON. Parameters start omitted; selecting Include with an empty field sends an explicit empty string. Names stay in advertised order and extra named fields are allowed. No parameter type or requiredness is inferred. An empty advertised list still permits a payload. Opening or editing the builder never invokes an intent. Use Copy link to share it, or Test intent to open the shared content.

    The outer URL carries a complete percent-encoded convention URI in intent. For example, ?intent=napplet%3Aprofile%2Fopen%3Fpubkey%3Dabc%252B123 contains napplet:profile/open?pubkey=abc%2B123 and delivers text abc+123. Outer and inner layers decode once each; literal + stays plus. Optional outer payload contains JSON, including null, primitives, arrays, or objects, and cannot accompany an inner query. URLs are limited to intent.linkMaxBytes (default 16 KiB) UTF-8. Duplicate keys, malformed encoding, and conflicting target instructions are rejected. Ordinary pointer-only app links retain their existing behavior.

    New links recommend the app using a named-35129 #naddr when available; snapshot or unnamed apps use an exact outer pointer. The builder also offers recipient-default routing. Explicit pointers must verify and advertise the exact contract; failure never silently falls back. Recommendation relay hints remain untrusted discovery inputs. Invalid, incompatible, or disallowed recommendations do not override an applicable saved default.

    Opening a shared link opens its verified app and delivers the content directly, following Paja's ordinary pointer navigation and capability policy. No URI or payload review is shown. If an applicable saved default conflicts with the link's app, Paja names both apps and asks which to use. A one-time choice leaves the default unchanged; Always use this app explicitly saves the chosen app. Without a usable hint or default, ordinary installed-handler selection applies. Installed app pointers are saved separately from open tabs and reverified when loaded; cached pointers never authorize execution or supply trusted metadata.

    Progress and failures use a small notice. Successful delivery dismisses it. Closing the notice or cancelling an app choice before dispatch sends nothing. After acceptance, the incoming intent is removed from the current URL so reload restores the app without delivering the shared content again. Accepted work is retained until the verified target is ready.

    Paja invokes through a separate signed launcher napplet with a verified artifact and authenticated iframe endpoint. Its source supplies the opaque sender; the URL cannot supply one. The hidden launcher is removed after acceptance and is never persisted or restored. Verification precedes srcdoc, and host bootstrap injection stays outside signed bytes. Native external-origin sender semantics remain a documented upstream spec gap; no host sender identity is invented.

    This non-normative guidance defers to NAP-GAMEPAD at napplet/naps@19de5ce1. Services export createGamepadService and browserGamepadOptions; shell exports denyNappletControllerAccess. Paja registers one host reader and denies native gamepad/HID/USB paths before frame execution. A subscription must approve the host-private gamepad:input resource before the reader starts; denial emits reason: "blocked". Only the visible host's input owner receives live controls. Focus loss supplies neutral controls and timestamp zero; unsubscribe, revocation, window destruction, and service removal release polling. See Controller input.

    This non-normative guidance defers to the living NAP-LLM (checked at 5e93bdf). Services export createLlmService, LlmServiceError, the provider mappers (OpenAI Chat Completions, OpenAI Responses, Anthropic Messages and Gemini generateContent dialects) and LLM_PROVIDER_PRESETS; shell exports getShellDomainState and the LlmHooks adapter field; acl exports llm:generate. The runtime routes llm.* to one registered service and answers every sanctioned request with exactly one llm.<op>.result, shaping missing-service and ACL failures as { code: 'unsupported' }. Hosts implement LlmConnectionHost; the service enforces schema, handle ownership, a per-window live-handle bound (maxHandlesPerWindow), consent before submission, duplicate ids, cancellation and deadline races, ordered deltas and safe errors, and passes select/authorize a { signal } that withdraws stale prompts. createHttpLlmProvider({ stream: true }) streams provider output into llm.delta as block start/delta/end events. Results carry content parts (text, thinking and tool calls); tool calls and results are validated and relayed, and Kehto never executes one. Advertisement stays binary on the wire while hosts report a third unconfigured state until the user adds a connection. See Language models.

    Paja MUST load all three NIP-5D manifest kinds: root 15129, named 35129, and snapshot 5129. Use an naddr with an empty identifier for the latest root, an naddr with the literal d identifier for the latest named napplet, or a nevent to pin a signed event of any of the three kinds. Snapshots require nevent because they are immutable events without replaceable coordinates. All paths verify the signed manifest and artifact hash before injecting srcdoc. Distinct snapshots retain separate tabs and catalog identities even when their artifact bytes match.

    Pointer resolution tracks each relay's connection outcome, not just whether events arrived. When zero relays open a WebSocket, the resolver throws PajaRelayUnreachableError (code: 'relay-unreachable', with a PajaRelayConnectionSummary of connected/failed/pending relays) instead of the generic timeout, and the pointer status reads No relay connection could be opened … 0 of N relays connected … with the likely causes: the browser is offline, the relays are blocked, or the browser reached its WebSocket connection limit (for example many open tabs each holding relay connections). Paja logs a paja.relay.unreachable entry with the per-relay detail. A deadline expiry with at least one live relay keeps the timeout message and now states how many relays connected. Pools without ensureRelay keep the previous timeout and relay query failure messages.

    Relays fail now and then; one down relay does not turn a clean miss into a failure. When at least one relay answered EOSE without the manifest, the resolver throws PajaPointerNotFoundError (code: 'pointer-not-found', with answered, failed, and the queried relays), and the status reads Napplet manifest not found (4 answered, 1 failed): … followed by the relays that could not be asked. Paja logs paja.pointer.not-found with the counts. The no-connection message and its WebSocket-limit hint stay reserved for zero opened sockets, and a query no relay answered (every relay failed or sent CLOSED) stays a relay query failure.

    A nevent pins one event. When it names an addressable napplet (35129, with author and kind) whose event is gone, the author has most likely republished it and relays replaced the old event. A nevent carries no d tag, so Paja cannot tell which coordinate it belonged to. findPajaPointerReplacements asks the relays that answered for the author's current 35129 manifests and lists each d tag (up to 50). One candidate shows as an Open … button; several show as a picker with nothing preselected, because Paja picks none. Nothing is fetched from Blossom, verified, installed, or framed until the user clicks one. The click starts an ordinary naddr load, so the manifest signature, artifact hash, (dTag, artifactHash) identity, and version consent all run again for the new bytes. Paja never swaps bytes under the old verified identity. Replaceable root (15129) nevents are not offered a replacement yet.

    Paja shows a numbered controller icon directly beside the console arrow for each controller the browser detects. Each slot has its own color and input animation; hover for the controller model and activity state. Buttons and stick movement light up only that controller (stick movement below 0.12 is ignored). Quick taps retain the highlight briefly so they are easy to spot. Reduced-motion settings keep the activity highlight without animation. Disconnecting removes the icon. Browsers may require a button press before exposing a newly connected controller. These host diagnostics work without a napplet gamepad subscription and do not change focus-scoped input delivery.

    Paja provides shell-owned audio/video playback through its resource resolver and a collapsible player with transport, seek, volume, and close controls. It also streams live HTTPS MP3/AAC radio without awaiting EOF and displays napplet-owned sessions. See Media playback for source support, lifecycle rules, and canonical API examples.

    Paja explicitly installs operation and prompt limiters from @kehto/rate-limit in createPajaPermissionAdapter. These are Paja host choices; runtime and Firewall do not impose them on other hosts. Limiter configuration and counters are separate from approval grants.

    The Multiplayer providers sidebar accepts explicit JSON settings, also available as simulation.multiplayer in a Paja config file. Select soy-rtc/1, signaling relays, and CVM families with pinned tool schemas. Optional static STUN/TURN settings receive separate endpoint approval. No provider is selected from an app URL. See configuration and interoperability.

    The same sidebar discovers CVM tool inventories from a nevent, a CEP-15 tool schema hash, or an HTTPS website's /.well-known/napplet.json. Choose a provider, local family label, and tools; generated JSON is read-only and shows its source. Manual JSON remains editable. Saved families persist per host origin and coexist in the registry, including without a multiplayer signaling profile. Saves and removals reload the host. ContextVM doesn't define named-family manifests or naddr discovery; labels and membership are local choices.

    Modules

    cli