@kehto/shell 0.18.0 → 0.19.1

package/README.md

@@ -15,9 +15,9 @@ pnpm add @kehto/shell
 ## Published Napplet Compatibility
 
 `@kehto/shell` publishes against `@napplet/core` and `@napplet/nap`
-`>=0.29.0 <0.30.0`. The installed core/nap 0.29.0 contracts are from source
-`dd7b3a728eb9c838b7218fcec7bb7bb00e7cc88b` and release
-`60889f1c2476e063500c7ab6624af6abe0dbcbe5`.
+`>=0.31.0 <0.32.0`. The installed core/nap 0.31.0 contracts are from source
+`7b675622e13870628ce174833d7b2a33cf32a0ab` and release
+`03ad65b66413e5798536ef48695ffc4c2508f2c3`.
 
 ## Overview
 
@@ -28,7 +28,7 @@ The primary entry point is `createShellBridge()` — it owns the postMessage lis
 Current draft behaviors this package enforces:
 
 - The shell does not inject a host-provided nostr object into napplets — NIP-5D explicitly forbids napplet-visible signing. Napplets call `relay.publish` / `relay.publishEncrypted` and the shell mediates the signing flow internally (NIP-44 default, NIP-04 opt-in for encrypted envelopes).
-- `injectNappletNamespacePrelude()` implements the NIP-5D injected-domain bootstrap and mandatory NAP-SHELL shim: hosts prepend it to `srcdoc` outside verified artifact bytes, install the parent-bound `shell.init` receiver, emit one `shell.ready`, and expose callable NAP interfaces before authored scripts run. Optional namespaces are filtered to the bare-domain allowlist; `shell` is always retained. Published core 0.29.0 and shim 0.27.0 omit generic mandatory shell, so Kehto retains this host-owned prelude under NAP-SHELL `5ac0490461ca6fec2f0d2e45b4835cf9bc08de24` until an upstream correction is reviewed.
+- `injectNappletNamespacePrelude()` implements the NIP-5D injected-domain bootstrap and mandatory NAP-SHELL shim: hosts prepend it to `srcdoc` outside verified artifact bytes, install the parent-bound `shell.init` receiver, emit one `shell.ready`, and expose callable NAP interfaces before authored scripts run. Optional namespaces are filtered to the bare-domain allowlist; `shell` is always retained. Published core 0.31.0 and shim 0.29.0 omit generic mandatory shell, so Kehto retains this host-owned prelude under NAP-SHELL `5ac0490461ca6fec2f0d2e45b4835cf9bc08de24` until an upstream correction is reviewed.
 - `window.napplet.shell.supports(domain)` answers synchronously and locally from the cached first `shell.init` environment. It returns `false` before `shell.init`, for unknown values, and for domains that are not live and granted to that napplet; it never sends a support-query message.
 - Five optional per-domain proxies — `createIdentityProxy`, `createThemeProxy`, `createKeysProxy`, `createMediaProxy`, `createNotifyProxy` — can be composed between napplet and runtime to intercept request traffic per NAP. They are NOT wired by default. Identity/theme proxy `emit()` compatibility members fail closed; hosts must deliver automatic changes through `ShellBridge.publishIdentityChanged()` / `publishTheme()`, which enforce live session, granted domain, and current ACL.
 - `keys.forward` is napplet-to-shell only. Active napplets suppress locally-bound keys from `keys.bindings` before forwarding; shell-initiated action triggers use `keys.action`.
@@ -37,25 +37,25 @@ Current draft behaviors this package enforces:
 ### NAP-INC binding and channel contract
 
 The injected INC binding follows merged
-[`naps/NAP-INC.md`](https://github.com/napplet/naps/blob/6461e4b37c29dc09a20dff35d9515889c4433874/naps/NAP-INC.md)
+[`naps/NAP-INC.md`](https://github.com/napplet/naps/blob/5ac0490461ca6fec2f0d2e45b4835cf9bc08de24/naps/NAP-INC.md)
 on `napplet/naps` master
-`6461e4b37c29dc09a20dff35d9515889c4433874`. The specification remains marked
+`5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`. The specification remains marked
 draft, but its merged path is the protocol authority.
 
 The released package projection and `window.napplet.inc` binding own
 query-to-text-payload
 transposition: it converts a convention URI query before emitting a stable,
-exact queryless topic identity. Subscriptions reject query-bearing identities.
-The binding never creates a normalized query-bearing wire/discovery identity,
+exact stable convention topic identity. Subscriptions reject query- or fragment-bearing
+**convention** identities; arbitrary opaque topics remain byte-for-byte exact,
+including `?` and `#`. The binding never creates a normalized query-bearing
+wire/discovery identity,
 does not do prefix/wildcard/query-aware matching or service-over-INC prefix
 dispatch, and does not infer payload kinds. Runtime delivery supplies the
 **runtime-attested dTag**; no caller sender is accepted, topic source exclusion
 is runtime-owned, and IDs and payloads are opaque.
 
-Merged NAP-INC delivers one `IncEvent` to `on(topic, callback)`. Released
-`@napplet/nap@0.29.0` instead declares and implements a
-`(payload, NostrEvent)` callback. The protected binding follows the NAP;
-package-based consumers must bridge that upstream callback drift.
+Merged NAP-INC and released `@napplet/nap@0.31.0` both deliver one `IncEvent`
+to `on(topic, callback)`.
 
 For channels, runtime ACL checks are open-only rather than per-message. The
 target `inc.channel.opened` before the opener result creates an equivalent target
@@ -69,18 +69,18 @@ the prior opener-only interpretation is obsolete.
 
 ### NAP-INTENT binding and delivery
 
-Phase 104 implements the draft [NAP-INTENT PR #91 at
-`a718915ddefa2f03a0126579601f59d8bd86f7c4`](https://github.com/napplet/naps/pull/91).
-The protected `window.napplet.intent` binding normalizes URI invocation into
-exact `archetype`, `action`, queryless `convention`, and optional payload
-fields. It rejects fragments, malformed/repeated queries, query plus explicit
-payload, mismatched normalized fields, and caller-supplied sender data.
-
-Only parent-originated result, change, and delivery envelopes settle the
-binding. Incoming no-ID `intent.deliver` values are retained until an
-`onDelivery` handler is registered. The runtime, not the source, attests the
-sender dTag; an accepted result records retained responsibility and does not
-expose target window, handled, protocol, retry, or lifecycle state.
+Kehto implements merged [NAP-INTENT at
+`5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`](https://github.com/napplet/naps/blob/5ac0490461ca6fec2f0d2e45b4835cf9bc08de24/naps/NAP-INTENT.md).
+The protected `window.napplet.intent` binding accepts structured
+`invoke(request)` calls and `open(archetype, payload?, opts?)`. It defaults
+`action` to `open`, preserves an optional queryless convention, rejects
+unsupported fields and caller-supplied sender data, and resolves only
+parent-originated correlated results.
+
+Successful results include `handled`, `handler`, `windowId`, and `convention`
+after target dispatch completes. There is no `intent.deliver` or `onDelivery`;
+selected targets consume their convention through the ordinary
+runtime-attested INC binding.
 
 Phase 105 completed released `@napplet/*` package adoption and persistent live
 Paja/playground catalogs and target controllers. The Phase 104 Paja simulator

package/dist/index.js

@@ -1334,9 +1334,14 @@ function nappletNamespacePrelude(domains) {
   function fire(message) {
     post(message);
   }
+  function isConventionTopic(topic) {
+    const pathEnd = topic.search(/[?#]/);
+    const path = pathEnd === -1 ? topic : topic.slice(0, pathEnd);
+    return /^napplet:[^/?#]+\/[^/?#]+$/.test(path);
+  }
   function normalizeConventionUri(topic, hasExplicitPayload) {
     if (typeof topic !== "string") throw new TypeError("INC topic must be text");
-    if (!topic.startsWith("napplet:")) return { topic };
+    if (!isConventionTopic(topic)) return { topic };
     if (topic.includes("#")) throw new TypeError("Convention topics cannot contain fragments");
     const queryStart = topic.indexOf("?");
     if (queryStart === -1) {
@@ -1345,7 +1350,7 @@ function nappletNamespacePrelude(domains) {
     if (hasExplicitPayload) {
       throw new TypeError("Convention queries cannot be combined with an explicit payload");
     }
-    const values = {};
+    const entries = [];
     const names = /* @__PURE__ */ new Set();
     const query = topic.slice(queryStart + 1);
     if (query) {
@@ -1364,10 +1369,10 @@ function nappletNamespacePrelude(domains) {
         }
         if (names.has(name)) throw new TypeError("Convention query names must be unique");
         names.add(name);
-        values[name] = value;
+        entries.push([name, value]);
       }
     }
-    return { topic: topic.slice(0, queryStart), payload: values };
+    return { topic: topic.slice(0, queryStart), payload: Object.fromEntries(entries) };
   }
   function resultOrError(msg) {
     return msg;
@@ -1526,7 +1531,7 @@ function nappletNamespacePrelude(domains) {
     const unopenedClosed = /* @__PURE__ */ new Map();
     function stableSubscriptionTopic(topic) {
       if (typeof topic !== "string") throw new TypeError("INC topic must be text");
-      if (topic.includes("?") || topic.includes("#")) {
+      if (isConventionTopic(topic) && (topic.includes("?") || topic.includes("#"))) {
         throw new TypeError("INC subscriptions require a queryless topic identity");
       }
       return topic;
@@ -1547,7 +1552,6 @@ function nappletNamespacePrelude(domains) {
         },
         on(handler) {
           if (typeof handler !== "function") throw new TypeError("INC channel event handler must be a function");
-          if (state.closed) return subscriptionHandle(() => void 0);
           state.eventHandlers.add(handler);
           const pending = state.pendingEvents.splice(0);
           for (const event of pending) handler(event);
@@ -2217,77 +2221,57 @@ function nappletNamespacePrelude(domains) {
     };
   }
   function makeIntent() {
-    const deliveryHandlers = /* @__PURE__ */ new Set();
-    const pendingDeliveries = [];
     const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
-    const normalizeDelivery = (value) => {
-      if (!value || typeof value !== "object" || typeof value.sender !== "string" || typeof value.archetype !== "string" || typeof value.action !== "string" || typeof value.convention !== "string") {
-        return void 0;
+    const normalizeRequest = (value) => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("Intent request must be an object");
       }
-      const delivery = value;
-      return {
-        sender: delivery.sender,
-        archetype: delivery.archetype,
-        action: delivery.action,
-        convention: delivery.convention,
-        ...hasOwn(delivery, "payload") ? { payload: delivery.payload } : {}
-      };
-    };
-    listen((event) => {
-      if (!isParentMessage(event)) return;
-      const msg = event.data;
-      if (typeof msg !== "object" || msg === null || msg.type !== "intent.deliver") return;
-      const delivery = normalizeDelivery(msg.delivery);
-      if (!delivery) return;
-      if (deliveryHandlers.size === 0) pendingDeliveries.push(delivery);
-      else for (const handler of deliveryHandlers) handler(delivery);
-    });
-    function normalizeIntentUri(uri, explicitPayload, actionMustBe) {
-      if (typeof uri !== "string" || !uri.startsWith("napplet:")) {
-        throw new TypeError("Intent convention URI must start with napplet:");
+      const supplied = value;
+      if (hasOwn(supplied, "sender")) {
+        throw new TypeError("Intent callers cannot supply sender");
       }
-      if (uri.includes("#")) throw new TypeError("Intent convention URI cannot contain fragments");
-      const normalized = normalizeConventionUri(uri, explicitPayload);
-      const match = /^napplet:([^/?#]+)\/([^/?#]+)$/.exec(normalized.topic);
-      if (!match) throw new TypeError("Intent convention URI must be napplet:<archetype>/<intent>");
-      if (actionMustBe !== void 0 && match[2] !== actionMustBe) {
-        throw new TypeError(`Intent convention URI must use the ${actionMustBe} intent`);
+      const allowed2 = ["archetype", "action", "convention", "payload", "handler", "behavior"];
+      if (Object.keys(supplied).some((field) => !allowed2.includes(field))) {
+        throw new TypeError("Intent request contains unsupported fields");
       }
-      return {
-        archetype: match[1],
-        action: match[2],
-        convention: normalized.topic,
-        ...normalized.payload === void 0 ? {} : { payload: normalized.payload }
-      };
-    }
-    const invoke = (uri, opts, actionMustBe) => {
-      const supplied = opts && typeof opts === "object" ? opts : void 0;
-      const explicitPayload = supplied?.payload !== void 0;
-      const normalized = normalizeIntentUri(uri, explicitPayload, actionMustBe);
-      if (supplied && hasOwn(supplied, "sender")) {
-        throw new TypeError("Intent callers cannot supply sender");
+      if (typeof supplied.archetype !== "string" || supplied.archetype.length === 0) {
+        throw new TypeError("Intent request requires an archetype");
       }
-      for (const field of ["archetype", "action", "convention"]) {
-        if (supplied && hasOwn(supplied, field) && supplied[field] !== normalized[field]) {
-          throw new TypeError(`Intent options cannot override URI-derived ${field}`);
-        }
+      const action = supplied.action === void 0 ? "open" : supplied.action;
+      if (typeof action !== "string" || action.length === 0) {
+        throw new TypeError("Intent action must be a non-empty string");
+      }
+      if (supplied.convention !== void 0 && (typeof supplied.convention !== "string" || !/^napplet:[^/?#\s]+\/[^/?#\s]+$/.test(supplied.convention))) {
+        throw new TypeError("Intent convention must be queryless");
+      }
+      if (supplied.handler !== void 0 && (typeof supplied.handler !== "string" || supplied.handler.length === 0)) {
+        throw new TypeError("Intent handler must be a non-empty string");
       }
       const behaviorValue = supplied?.behavior;
       const behavior = behaviorValue && typeof behaviorValue === "object" ? behaviorValue : void 0;
+      if (behaviorValue !== void 0 && (!behavior || Array.isArray(behaviorValue) || Object.keys(behavior).some((field) => field !== "focus" && field !== "newWindow" && field !== "reuse") || hasOwn(behavior, "focus") && typeof behavior.focus !== "boolean" || hasOwn(behavior, "newWindow") && typeof behavior.newWindow !== "boolean" || hasOwn(behavior, "reuse") && typeof behavior.reuse !== "boolean")) {
+        throw new TypeError("Intent behavior contains unsupported fields");
+      }
       const sanitizedBehavior = {
         ...typeof behavior?.focus === "boolean" ? { focus: behavior.focus } : {},
+        ...typeof behavior?.newWindow === "boolean" ? { newWindow: behavior.newWindow } : {},
         ...typeof behavior?.reuse === "boolean" ? { reuse: behavior.reuse } : {}
       };
-      const handler = typeof supplied?.handler === "string" ? supplied.handler : void 0;
+      return {
+        archetype: supplied.archetype,
+        action,
+        ...typeof supplied.convention === "string" ? { convention: supplied.convention } : {},
+        ...hasOwn(supplied, "payload") ? { payload: supplied.payload } : {},
+        ...typeof supplied.handler === "string" ? { handler: supplied.handler } : {},
+        ...Object.keys(sanitizedBehavior).length === 0 ? {} : { behavior: sanitizedBehavior }
+      };
+    };
+    const invoke = (value) => {
+      const normalized = normalizeRequest(value);
       return request(
         {
           type: "intent.invoke",
-          request: {
-            ...normalized,
-            ...explicitPayload ? { payload: supplied?.payload } : {},
-            ...handler === void 0 ? {} : { handler },
-            ...Object.keys(sanitizedBehavior).length === 0 ? {} : { behavior: sanitizedBehavior }
-          }
+          request: normalized
         },
         "intent.invoke.result",
         (msg) => fieldOrThrow(msg, "result", "intent.invoke.result missing result")
@@ -2295,7 +2279,12 @@ function nappletNamespacePrelude(domains) {
     };
     return {
       invoke,
-      open: (uri, opts) => invoke(uri, opts, "open"),
+      open: (archetype, payload, opts) => invoke({
+        archetype,
+        action: "open",
+        ...payload === void 0 ? {} : { payload },
+        ...opts
+      }),
       available: (archetype) => request(
         { type: "intent.available", archetype },
         "intent.available.result",
@@ -2310,14 +2299,7 @@ function nappletNamespacePrelude(domains) {
         "intent.changed",
         callback,
         (msg) => msg.availability
-      ),
-      onDelivery: (callback) => {
-        if (typeof callback !== "function") throw new TypeError("Intent delivery handler must be a function");
-        deliveryHandlers.add(callback);
-        const pending = pendingDeliveries.splice(0);
-        for (const delivery of pending) callback(delivery);
-        return subscriptionHandle(() => deliveryHandlers.delete(callback));
-      }
+      )
     };
   }
   function makeWebrtc() {