@kehto/shell 0.17.2 → 0.18.0

package/dist/index.js

@@ -35,7 +35,7 @@ function createRelayPoolAdapter(shellHooks, originRegistry2) {
       const pool = shellHooks.relayPool.getRelayPool();
       if (!pool) return;
       const relayUrls = shellHooks.relayPool.selectRelayTier([]);
-      pool.publish(relayUrls, event);
+      return pool.publish(relayUrls, event);
     },
     selectRelayTier(filters) {
       return shellHooks.relayPool.selectRelayTier(filters);
@@ -392,6 +392,19 @@ var originRegistry = {
     if (!entry?.dTag || !entry?.aggregateHash) return void 0;
     return { dTag: entry.dTag, aggregateHash: entry.aggregateHash };
   },
+  /** Store the immutable environment captured for this exact frame registration. */
+  setEnvironment(win, environment) {
+    const entry = registry.get(win);
+    if (!entry) return;
+    entry.environment = Object.freeze({
+      capabilities: Object.freeze({ domains: Object.freeze([...environment.capabilities.domains]) }),
+      services: Object.freeze([...environment.services])
+    });
+  },
+  /** Return the immutable environment captured before this frame executes. */
+  getEnvironment(win) {
+    return registry.get(win)?.environment;
+  },
   /**
    * Look up the monotonically increasing registration id for a Window.
    *
@@ -962,113 +975,153 @@ var audioManager = {
 };
 
 // src/shell-init.ts
-var NAP_DOMAINS = [
+var RUNTIME_NATIVE_DOMAINS = [
+  "relay",
   "identity",
   "storage",
   "inc",
   "theme",
   "keys",
   "media",
-  "notify",
+  "notify"
+];
+var SERVICE_ONLY_DOMAINS = [
+  "outbox",
   "config",
   "resource",
-  "cvm"
-];
-var NAP_INC_PROTOCOLS = [
-  "inc:NAP-01",
-  "inc:NAP-02",
-  "inc:NAP-03",
-  "inc:NAP-04",
-  "inc:NAP-05",
-  "inc:NAP-06"
+  "cvm",
+  "upload",
+  "intent",
+  "link",
+  "common",
+  "lists",
+  "serial",
+  "ble",
+  "webrtc",
+  "dm",
+  "count"
 ];
 function buildShellCapabilities(hooks) {
-  const domains = hooks.relayPool ? ["relay", "outbox", ...NAP_DOMAINS] : [...NAP_DOMAINS];
-  if (hooks.upload) domains.push("upload");
-  if (hooks.intent?.isAvailable()) domains.push("intent");
-  if (hooks.services?.count) domains.push("count");
-  if (hooks.link?.isAvailable()) domains.push("link");
-  if (hooks.common?.isAvailable()) domains.push("common");
-  if (hooks.lists?.isAvailable()) domains.push("lists");
-  if (hooks.serial?.isAvailable()) domains.push("serial");
-  if (hooks.ble?.isAvailable()) domains.push("ble");
-  if (hooks.webrtc?.isAvailable()) domains.push("webrtc");
-  if (hooks.dm) domains.push("dm");
-  const sandbox = [];
-  const protocols = {};
-  for (const entry of NAP_INC_PROTOCOLS) {
-    const [domain, protocol] = entry.split(":");
-    (protocols[domain] ??= []).push(protocol);
-  }
-  const naps = hooks.relayPool ? ["relay", "outbox", ...NAP_DOMAINS, ...NAP_INC_PROTOCOLS] : [...NAP_DOMAINS, ...NAP_INC_PROTOCOLS];
-  if (hooks.upload) naps.push("upload");
-  if (hooks.intent?.isAvailable()) naps.push("intent");
-  if (hooks.services?.count) naps.push("count");
-  if (hooks.link?.isAvailable()) naps.push("link");
-  if (hooks.common?.isAvailable()) naps.push("common");
-  if (hooks.lists?.isAvailable()) naps.push("lists");
-  if (hooks.serial?.isAvailable()) naps.push("serial");
-  if (hooks.ble?.isAvailable()) naps.push("ble");
-  if (hooks.webrtc?.isAvailable()) naps.push("webrtc");
-  if (hooks.dm) naps.push("dm");
-  return applyCapabilityOverrides(
-    { domains, protocols, naps, sandbox },
-    hooks.capabilities?.disabledDomains ?? []
-  );
+  const disabled = new Set(hooks.capabilities?.disabledDomains ?? []);
+  const domains = RUNTIME_NATIVE_DOMAINS.filter((domain) => !disabled.has(domain));
+  for (const domain of SERVICE_ONLY_DOMAINS) {
+    if (!disabled.has(domain) && isServiceDomainLive(hooks, domain)) domains.push(domain);
+  }
+  return Object.freeze({ domains: freezeList(domains) });
 }
-function applyCapabilityOverrides(capabilities, disabledDomains) {
-  if (disabledDomains.length === 0) return capabilities;
-  const disabled = new Set(disabledDomains);
-  const protocols = {};
-  for (const [domain, supportedProtocols] of Object.entries(capabilities.protocols)) {
-    if (!disabled.has(domain)) protocols[domain] = supportedProtocols;
+function resolveShellEnvironment(hooks, identity) {
+  const capabilities = buildShellCapabilities(hooks);
+  const disabled = new Set(hooks.capabilities?.disabledDomains ?? []);
+  const services = getLiveServices(hooks, capabilities.domains, disabled);
+  const available = Object.freeze({
+    domains: freezeList(capabilities.domains),
+    services: freezeList(services)
+  });
+  const granted = hooks.capabilities?.resolveEnvironment?.(identity, available) ?? available;
+  return Object.freeze({
+    capabilities: Object.freeze({
+      domains: freezeList(intersectInOrder(available.domains, granted.domains))
+    }),
+    services: freezeList(intersectInOrder(available.services, granted.services))
+  });
+}
+function isServiceDomainLive(hooks, domain) {
+  if (!hooks.services?.[domain]) return false;
+  switch (domain) {
+    case "outbox":
+      return Boolean(hooks.relayPool);
+    case "upload":
+      return hooks.upload?.getUploader() !== null && hooks.upload?.getUploader() !== void 0;
+    case "intent":
+      return hooks.intent?.isAvailable() === true;
+    case "link":
+      return hooks.link?.isAvailable() === true;
+    case "common":
+      return hooks.common?.isAvailable() === true;
+    case "lists":
+      return hooks.lists?.isAvailable() === true;
+    case "serial":
+      return hooks.serial?.isAvailable() === true;
+    case "ble":
+      return hooks.ble?.isAvailable() === true;
+    case "webrtc":
+      return hooks.webrtc?.isAvailable() === true;
+    case "dm":
+      return hooks.dm !== void 0;
+    default:
+      return true;
   }
-  return {
-    domains: capabilities.domains.filter((entry) => !disabled.has(entry)),
-    protocols,
-    naps: capabilities.naps.filter((entry) => !disabled.has(entry.split(":")[0] ?? entry)),
-    sandbox: capabilities.sandbox
-  };
+}
+function getLiveServices(hooks, domains, disabled) {
+  const liveDomains = new Set(domains);
+  return Object.keys(hooks.services ?? {}).filter((name) => {
+    if (disabled.has(name)) return false;
+    return !SERVICE_ONLY_DOMAINS.includes(name) || liveDomains.has(name);
+  });
+}
+function intersectInOrder(available, requested) {
+  const requestedSet = new Set(requested);
+  return available.filter((entry) => requestedSet.has(entry));
+}
+function freezeList(values) {
+  return Object.freeze([...values]);
 }
 
 // src/shell-ready.ts
-var initSent = /* @__PURE__ */ new WeakMap();
+function createShellReadyState() {
+  const initSent = /* @__PURE__ */ new WeakMap();
+  const sessionRegistration = /* @__PURE__ */ new Map();
+  const environments = /* @__PURE__ */ new Map();
+  return {
+    initSent,
+    sessionRegistration,
+    environments,
+    isDomainAllowed(windowId, domain) {
+      return environments.get(windowId)?.capabilities.domains.includes(domain) ?? false;
+    },
+    clear() {
+      sessionRegistration.clear();
+      environments.clear();
+    }
+  };
+}
 function handleShellReady({
   hooks,
   origin,
   runtime,
+  state,
   sourceRegistrationId,
   sourceWindow,
   windowId
 }) {
-  registerNip5dSessionIfNeeded({
-    hooks,
-    origin,
-    runtime,
-    sourceRegistrationId,
-    sourceWindow,
-    windowId
-  });
-  if (initSent.get(sourceWindow) === sourceRegistrationId) {
+  if (state.initSent.get(sourceWindow) === sourceRegistrationId) {
     return;
   }
-  const capabilities = buildShellCapabilities(hooks);
-  postShellInit(sourceWindow, capabilities, Object.keys(hooks.services ?? {}));
-  initSent.set(sourceWindow, sourceRegistrationId);
+  const identity = resolveNip5dIdentity(hooks, windowId, sourceWindow);
+  if (!identity) return;
+  registerNip5dSessionIfNeeded({ origin, runtime, state, sourceRegistrationId, windowId, identity });
+  const environment = originRegistry.getEnvironment(sourceWindow) ?? resolveShellEnvironment(hooks, identity);
+  state.environments.set(windowId, environment);
+  postShellInit(sourceWindow, environment);
+  state.initSent.set(sourceWindow, sourceRegistrationId);
 }
 function registerNip5dSessionIfNeeded({
-  hooks,
   origin,
   runtime,
-  windowId
+  state,
+  sourceRegistrationId,
+  windowId,
+  identity
 }) {
-  if (runtime.sessionRegistry.getEntryByWindowId(windowId)) {
+  const existing = runtime.sessionRegistry.getEntryByWindowId(windowId);
+  const previousRegistration = state.sessionRegistration.get(windowId);
+  if (existing && previousRegistration === sourceRegistrationId) {
     return;
   }
-  const identity = resolveNip5dIdentity(hooks, windowId);
-  if (!identity) {
-    return;
+  if (existing && previousRegistration !== void 0) {
+    runtime.sessionRegistry.unregister(windowId);
   }
+  if (existing && previousRegistration === void 0) return;
   const entry = {
     pubkey: "",
     windowId,
@@ -1081,33 +1134,30 @@ function registerNip5dSessionIfNeeded({
     provenance: "nip-5d"
   };
   runtime.sessionRegistry.register(windowId, entry);
+  state.sessionRegistration.set(windowId, sourceRegistrationId);
 }
-function resolveNip5dIdentity(hooks, windowId) {
+function resolveNip5dIdentity(hooks, windowId, sourceWindow) {
   const hookIdentity = hooks.onNip5dIframeCreate?.(windowId);
   if (hookIdentity !== null && hookIdentity !== void 0) {
-    return {
+    return Object.freeze({
       dTag: hookIdentity.dTag,
       aggregateHash: hookIdentity.aggregateHash
-    };
-  }
-  const win = originRegistry.getIframeWindow(windowId);
-  if (!win) {
-    return null;
+    });
   }
-  const originIdentity = originRegistry.getIdentity(win);
+  const originIdentity = originRegistry.getIdentity(sourceWindow);
   if (!originIdentity) {
     return null;
   }
-  return {
+  return Object.freeze({
     dTag: originIdentity.dTag,
     aggregateHash: originIdentity.aggregateHash
-  };
+  });
 }
-function postShellInit(win, capabilities, services) {
+function postShellInit(win, environment) {
   const initMsg = {
     type: "shell.init",
-    capabilities,
-    services
+    capabilities: environment.capabilities,
+    services: environment.services
   };
   win.postMessage(initMsg, "*");
 }
@@ -1123,6 +1173,7 @@ function reportUnrouted(hooks, event, reason) {
   }
 }
 function createShellBridge(hooks) {
+  const shellReadyState = createShellReadyState();
   const runtimeHooks = adaptHooks(hooks, {
     originRegistry,
     manifestCache,
@@ -1130,11 +1181,16 @@ function createShellBridge(hooks) {
     audioManager,
     nappKeyRegistry
   });
-  const runtime = createRuntime(runtimeHooks);
-  function broadcastToNapplets(envelope) {
-    const windowIds = originRegistry.getAllWindowIds();
-    for (const windowId of windowIds) {
-      const win = originRegistry.getIframeWindow(windowId);
+  const runtime = createRuntime({
+    ...runtimeHooks,
+    isDomainAllowed: shellReadyState.isDomainAllowed
+  });
+  function publishToEligibleNapplets(envelope, domain, capability) {
+    for (const entry of runtime.sessionRegistry.getAllEntries()) {
+      const environment = shellReadyState.environments.get(entry.windowId);
+      if (!environment?.capabilities.domains.includes(domain)) continue;
+      if (!runtime.aclState.check(entry.pubkey, entry.dTag, entry.aggregateHash, capability)) continue;
+      const win = originRegistry.getIframeWindow(entry.windowId);
       if (!win) continue;
       win.postMessage(envelope, "*");
     }
@@ -1158,6 +1214,7 @@ function createShellBridge(hooks) {
           hooks,
           origin: event.origin,
           runtime,
+          state: shellReadyState,
           sourceRegistrationId: originRegistry.getRegistrationId(sourceWindow) ?? 0,
           sourceWindow,
           windowId
@@ -1171,17 +1228,18 @@ function createShellBridge(hooks) {
     },
     destroy() {
       runtime.destroy();
+      shellReadyState.clear();
     },
     registerConsentHandler(handler) {
       runtime.registerConsentHandler(handler);
     },
     publishTheme(theme) {
       const envelope = { type: "theme.changed", theme };
-      broadcastToNapplets(envelope);
+      publishToEligibleNapplets(envelope, "theme", "theme:read");
     },
     publishIdentityChanged(pubkey) {
       const envelope = { type: "identity.changed", pubkey };
-      broadcastToNapplets(envelope);
+      publishToEligibleNapplets(envelope, "identity", "identity:read");
     },
     get runtime() {
       return runtime;
@@ -1276,6 +1334,41 @@ function nappletNamespacePrelude(domains) {
   function fire(message) {
     post(message);
   }
+  function normalizeConventionUri(topic, hasExplicitPayload) {
+    if (typeof topic !== "string") throw new TypeError("INC topic must be text");
+    if (!topic.startsWith("napplet:")) return { topic };
+    if (topic.includes("#")) throw new TypeError("Convention topics cannot contain fragments");
+    const queryStart = topic.indexOf("?");
+    if (queryStart === -1) {
+      return { topic };
+    }
+    if (hasExplicitPayload) {
+      throw new TypeError("Convention queries cannot be combined with an explicit payload");
+    }
+    const values = {};
+    const names = /* @__PURE__ */ new Set();
+    const query = topic.slice(queryStart + 1);
+    if (query) {
+      for (const pair of query.split("&")) {
+        const separator = pair.indexOf("=");
+        if (separator < 0) {
+          throw new TypeError("Convention query parameters must use name=value form");
+        }
+        let name;
+        let value;
+        try {
+          name = decodeURIComponent(pair.slice(0, separator));
+          value = decodeURIComponent(pair.slice(separator + 1));
+        } catch {
+          throw new TypeError("Convention query contains malformed percent encoding");
+        }
+        if (names.has(name)) throw new TypeError("Convention query names must be unique");
+        names.add(name);
+        values[name] = value;
+      }
+    }
+    return { topic: topic.slice(0, queryStart), payload: values };
+  }
   function resultOrError(msg) {
     return msg;
   }
@@ -1315,11 +1408,13 @@ function nappletNamespacePrelude(domains) {
       if (typeof incoming !== "object" || incoming === null) return;
       const message = incoming;
       if (message.type !== "shell.init") return;
-      const services = Object.freeze(
-        Array.isArray(message.services) ? message.services.filter((service) => typeof service === "string") : []
-      );
+      const rawCapabilities = message.capabilities;
+      const rawDomains = typeof rawCapabilities === "object" && rawCapabilities !== null ? rawCapabilities.domains : void 0;
+      if (!Array.isArray(rawDomains)) return;
+      const domains2 = freezeStrings(rawDomains);
+      const services = freezeStrings(Array.isArray(message.services) ? message.services : []);
       environment = Object.freeze({
-        capabilities: message.capabilities ?? {},
+        capabilities: Object.freeze({ domains: domains2 }),
         services
       });
       off();
@@ -1327,20 +1422,18 @@ function nappletNamespacePrelude(domains) {
       for (const handler of readyHandlers) handler(environment);
       readyHandlers.clear();
     });
-    function supports(domain, protocol) {
-      if (!environment || typeof environment.capabilities !== "object" || environment.capabilities === null) {
-        return false;
+    function freezeStrings(values) {
+      const seen = /* @__PURE__ */ new Set();
+      const strings = [];
+      for (const value of values) {
+        if (typeof value !== "string" || value.length === 0 || seen.has(value)) continue;
+        seen.add(value);
+        strings.push(value);
       }
-      const capabilities = environment.capabilities;
-      if (protocol !== void 0) {
-        const protocols = capabilities.protocols;
-        if (typeof protocols === "object" && protocols !== null) {
-          const supported = protocols[domain];
-          if (Array.isArray(supported) && supported.includes(protocol)) return true;
-        }
-        return Array.isArray(capabilities.naps) && capabilities.naps.includes(`${domain}:${protocol}`);
-      }
-      return Array.isArray(capabilities.domains) && capabilities.domains.includes(domain) || Array.isArray(capabilities.naps) && capabilities.naps.includes(domain);
+      return Object.freeze(strings);
+    }
+    function supports(domain) {
+      return typeof domain === "string" && environment?.capabilities.domains.includes(domain) === true;
     }
     const shell2 = {
       ready: () => ready,
@@ -1424,38 +1517,205 @@ function nappletNamespacePrelude(domains) {
     };
   }
   function makeInc() {
-    return {
-      emit(topic, _extraTags, content) {
-        let payload = content;
-        if (typeof content === "string" && content.length > 0) {
-          try {
-            payload = JSON.parse(content);
-          } catch {
-            payload = content;
-          }
+    const topicStates = /* @__PURE__ */ new Map();
+    const maxRetainedEvents = 32;
+    const channelStates = /* @__PURE__ */ new Map();
+    const openedHandlers = /* @__PURE__ */ new Set();
+    const pendingOpened = [];
+    const unopenedEvents = /* @__PURE__ */ new Map();
+    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("#")) {
+        throw new TypeError("INC subscriptions require a queryless topic identity");
+      }
+      return topic;
+    }
+    function closeChannelState(state, closed, notifyShell) {
+      if (state.closed) return;
+      state.closed = closed;
+      if (notifyShell) fire({ type: "inc.channel.close", channelId: state.channelId });
+      for (const handler of state.closedHandlers) handler(closed);
+    }
+    function makeChannelHandle(state) {
+      return {
+        id: state.channelId,
+        peer: state.peer,
+        emit(payload) {
+          if (state.closed) return;
+          fire({ type: "inc.channel.emit", channelId: state.channelId, ...payload === void 0 ? {} : { payload } });
+        },
+        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);
+          return subscriptionHandle(() => state.eventHandlers.delete(handler));
+        },
+        onClosed(handler) {
+          if (typeof handler !== "function") throw new TypeError("INC channel close handler must be a function");
+          state.closedHandlers.add(handler);
+          if (state.closed) handler(state.closed);
+          return subscriptionHandle(() => state.closedHandlers.delete(handler));
+        },
+        close() {
+          closeChannelState(state, { channelId: state.channelId }, true);
+        }
+      };
+    }
+    function materializeChannel(channelId, peer) {
+      const existing = channelStates.get(channelId);
+      if (existing) return existing;
+      const state = {
+        channelId,
+        peer,
+        eventHandlers: /* @__PURE__ */ new Set(),
+        closedHandlers: /* @__PURE__ */ new Set(),
+        pendingEvents: unopenedEvents.get(channelId) ?? []
+      };
+      unopenedEvents.delete(channelId);
+      channelStates.set(channelId, state);
+      const closed = unopenedClosed.get(channelId);
+      unopenedClosed.delete(channelId);
+      if (closed) closeChannelState(state, closed, false);
+      return state;
+    }
+    function deliverOpened(state) {
+      const handle = makeChannelHandle(state);
+      if (openedHandlers.size > 0) {
+        for (const handler of openedHandlers) handler(handle);
+        return;
+      }
+      pendingOpened.push(state);
+    }
+    function receiveChannelEvent(channelId, sender, payloadPresent, payload) {
+      const event = payloadPresent ? { channelId, sender, payload } : { channelId, sender };
+      const state = channelStates.get(channelId);
+      if (!state) {
+        const pending = unopenedEvents.get(channelId) ?? [];
+        if (pending.length >= maxRetainedEvents) {
+          unopenedEvents.delete(channelId);
+          unopenedClosed.set(channelId, { channelId, reason: "buffer overflow" });
+          fire({ type: "inc.channel.close", channelId });
+          return;
         }
-        fire({ type: "inc.emit", topic, ...payload === void 0 || payload === "" ? {} : { payload } });
+        pending.push(event);
+        unopenedEvents.set(channelId, pending);
+        return;
+      }
+      if (state.closed) return;
+      if (state.eventHandlers.size > 0) {
+        for (const handler of state.eventHandlers) handler(event);
+        return;
+      }
+      if (state.pendingEvents.length >= maxRetainedEvents) {
+        closeChannelState(state, { channelId, reason: "buffer overflow" }, true);
+        return;
+      }
+      state.pendingEvents.push(event);
+    }
+    listen((event) => {
+      if (!isParentMessage(event)) return;
+      const msg = event.data;
+      if (typeof msg !== "object" || msg === null || typeof msg.type !== "string") return;
+      if (msg.type === "inc.channel.opened" && typeof msg.channelId === "string" && typeof msg.peer === "string") {
+        deliverOpened(materializeChannel(msg.channelId, msg.peer));
+        return;
+      }
+      if (msg.type === "inc.channel.event" && typeof msg.channelId === "string" && typeof msg.sender === "string") {
+        receiveChannelEvent(msg.channelId, msg.sender, Object.prototype.hasOwnProperty.call(msg, "payload"), msg.payload);
+        return;
+      }
+      if (msg.type === "inc.channel.closed" && typeof msg.channelId === "string") {
+        const closed = typeof msg.reason === "string" ? { channelId: msg.channelId, reason: msg.reason } : { channelId: msg.channelId };
+        const state = channelStates.get(msg.channelId);
+        if (state) closeChannelState(state, closed, false);
+        else unopenedClosed.set(msg.channelId, closed);
+      }
+    });
+    return {
+      emit(topic, payload) {
+        const transposed = normalizeConventionUri(topic, arguments.length > 1);
+        fire({
+          type: "inc.emit",
+          topic: transposed.topic,
+          ...transposed.payload === void 0 && payload === void 0 ? {} : { payload: transposed.payload ?? payload }
+        });
       },
       on(topic, callback) {
-        const off = listen((event) => {
-          if (!isParentMessage(event)) return;
-          const msg = event.data;
-          if (typeof msg !== "object" || msg === null || msg.type !== "inc.event" || msg.topic !== topic) return;
-          callback(msg.payload ?? {}, {
-            id: "",
-            pubkey: typeof msg.sender === "string" ? msg.sender : "",
-            created_at: Math.floor(Date.now() / 1e3),
-            kind: 0,
-            tags: [["t", topic]],
-            content: typeof msg.payload === "string" ? msg.payload : JSON.stringify(msg.payload ?? {}),
-            sig: ""
+        const stableTopic = stableSubscriptionTopic(topic);
+        if (typeof callback !== "function") throw new TypeError("INC subscription handler must be a function");
+        let state = topicStates.get(stableTopic);
+        if (!state) {
+          const handlers = /* @__PURE__ */ new Set();
+          const subscriptionId = id();
+          const offEvent = listen((event) => {
+            if (!isParentMessage(event)) return;
+            const msg = event.data;
+            if (typeof msg !== "object" || msg === null || msg.type !== "inc.event" || msg.topic !== stableTopic || typeof msg.sender !== "string") return;
+            const delivered = Object.prototype.hasOwnProperty.call(msg, "payload") ? { topic: stableTopic, sender: msg.sender, payload: msg.payload } : { topic: stableTopic, sender: msg.sender };
+            for (const handler of handlers) handler(delivered);
           });
-        });
-        fire({ type: "inc.subscribe", id: id(), topic });
+          const offResult = listen((event) => {
+            if (!isParentMessage(event)) return;
+            const msg = event.data;
+            if (typeof msg !== "object" || msg === null || msg.type !== "inc.subscribe.result" || msg.id !== subscriptionId) return;
+            offResult();
+            if (typeof msg.error === "string" && msg.error) {
+              offEvent();
+              topicStates.delete(stableTopic);
+            }
+          });
+          state = { handlers, offEvent, offResult };
+          topicStates.set(stableTopic, state);
+          fire({ type: "inc.subscribe", id: subscriptionId, topic: stableTopic });
+        }
+        state.handlers.add(callback);
         return subscriptionHandle(() => {
-          fire({ type: "inc.unsubscribe", topic });
-          off();
+          const current = topicStates.get(stableTopic);
+          if (!current) return;
+          current.handlers.delete(callback);
+          if (current.handlers.size !== 0) return;
+          current.offEvent();
+          current.offResult();
+          topicStates.delete(stableTopic);
+          fire({ type: "inc.unsubscribe", topic: stableTopic });
         });
+      },
+      channel: {
+        open(targetDTag) {
+          return request(
+            { type: "inc.channel.open", target: targetDTag },
+            "inc.channel.open.result",
+            (msg) => {
+              if (typeof msg.channelId !== "string" || typeof msg.peer !== "string") {
+                throw new Error("inc.channel.open.result missing channel identity");
+              }
+              return makeChannelHandle(materializeChannel(msg.channelId, msg.peer));
+            }
+          );
+        },
+        onOpened(handler) {
+          if (typeof handler !== "function") throw new TypeError("INC opened handler must be a function");
+          openedHandlers.add(handler);
+          const pending = pendingOpened.splice(0);
+          for (const state of pending) handler(makeChannelHandle(state));
+          return subscriptionHandle(() => openedHandlers.delete(handler));
+        },
+        list() {
+          return request(
+            { type: "inc.channel.list" },
+            "inc.channel.list.result",
+            (msg) => Object.freeze((Array.isArray(msg.channels) ? msg.channels : []).flatMap((channel) => channel && typeof channel === "object" && typeof channel.id === "string" && typeof channel.peer === "string" ? [Object.freeze({
+              id: channel.id,
+              peer: channel.peer
+            })] : []))
+          );
+        },
+        broadcast(payload) {
+          fire({ type: "inc.channel.broadcast", ...payload === void 0 ? {} : { payload } });
+        }
       }
     };
   }
@@ -1493,14 +1753,22 @@ function nappletNamespacePrelude(domains) {
     return { ...makeScope(), instance: makeScope("instance") };
   }
   function makeIdentity() {
-    const read = (type, field, fallback) => request(
-      { type },
+    const read = (type, field, fallback, payload = {}) => request(
+      { type, ...payload },
       `${type}.result`,
       (msg) => Object.prototype.hasOwnProperty.call(msg, field) ? msg[field] : fallback,
       { rejectOnError: type !== "identity.getPublicKey" }
     );
-    return {
+    return Object.freeze({
       getPublicKey: () => read("identity.getPublicKey", "pubkey", ""),
+      getRelays: () => read("identity.getRelays", "relays", {}),
+      getProfile: () => read("identity.getProfile", "profile", null),
+      getFollows: () => read("identity.getFollows", "pubkeys", []),
+      getList: (listType) => read("identity.getList", "entries", [], { listType }),
+      getZaps: () => read("identity.getZaps", "zaps", []),
+      getMutes: () => read("identity.getMutes", "pubkeys", []),
+      getBlocked: () => read("identity.getBlocked", "pubkeys", []),
+      getBadges: () => read("identity.getBadges", "badges", []),
       onChanged(handler) {
         const off = listen((event) => {
           if (!isParentMessage(event)) return;
@@ -1509,20 +1777,8 @@ function nappletNamespacePrelude(domains) {
           if (typeof msg.pubkey === "string") handler(msg.pubkey);
         });
         return subscriptionHandle(off);
-      },
-      getRelays: () => read("identity.getRelays", "relays", {}),
-      getProfile: () => read("identity.getProfile", "profile", null),
-      getFollows: () => read("identity.getFollows", "pubkeys", []),
-      getList: (listType) => request(
-        { type: "identity.getList", listType },
-        "identity.getList.result",
-        (msg) => Array.isArray(msg.entries) ? msg.entries : []
-      ),
-      getZaps: () => read("identity.getZaps", "zaps", []),
-      getMutes: () => read("identity.getMutes", "pubkeys", []),
-      getBlocked: () => read("identity.getBlocked", "pubkeys", []),
-      getBadges: () => read("identity.getBadges", "badges", [])
-    };
+      }
+    });
   }
   function makeTheme() {
     return {
@@ -1961,19 +2217,85 @@ function nappletNamespacePrelude(domains) {
     };
   }
   function makeIntent() {
-    const invoke = (requestPayload) => request(
-      { type: "intent.invoke", request: requestPayload },
-      "intent.invoke.result",
-      (msg) => fieldOrThrow(msg, "result", "intent.invoke.result missing result")
-    );
+    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 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:");
+      }
+      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`);
+      }
+      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");
+      }
+      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 behaviorValue = supplied?.behavior;
+      const behavior = behaviorValue && typeof behaviorValue === "object" ? behaviorValue : void 0;
+      const sanitizedBehavior = {
+        ...typeof behavior?.focus === "boolean" ? { focus: behavior.focus } : {},
+        ...typeof behavior?.reuse === "boolean" ? { reuse: behavior.reuse } : {}
+      };
+      const handler = typeof supplied?.handler === "string" ? supplied.handler : void 0;
+      return request(
+        {
+          type: "intent.invoke",
+          request: {
+            ...normalized,
+            ...explicitPayload ? { payload: supplied?.payload } : {},
+            ...handler === void 0 ? {} : { handler },
+            ...Object.keys(sanitizedBehavior).length === 0 ? {} : { behavior: sanitizedBehavior }
+          }
+        },
+        "intent.invoke.result",
+        (msg) => fieldOrThrow(msg, "result", "intent.invoke.result missing result")
+      );
+    };
     return {
       invoke,
-      open: (archetype, payload, opts) => invoke({
-        archetype,
-        action: "open",
-        payload,
-        ...opts && typeof opts === "object" ? opts : {}
-      }),
+      open: (uri, opts) => invoke(uri, opts, "open"),
       available: (archetype) => request(
         { type: "intent.available", archetype },
         "intent.available.result",
@@ -1988,7 +2310,14 @@ 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() {
@@ -2123,14 +2452,40 @@ function nappletNamespacePrelude(domains) {
     };
   }
   const shell = makeShell();
+  let inc;
+  let identity;
+  let theme;
+  let intent;
+  function makeProtectedInc(existing) {
+    const extensions = existing && typeof existing === "object" ? existing : {};
+    inc ??= makeInc();
+    return { ...extensions, ...inc };
+  }
+  function makeProtectedIdentity() {
+    identity ??= makeIdentity();
+    return identity;
+  }
+  function makeProtectedTheme() {
+    theme ??= Object.freeze(makeTheme());
+    return theme;
+  }
+  function makeProtectedIntent() {
+    intent ??= Object.freeze(makeIntent());
+    return intent;
+  }
+  function isProtectedDomain(domain) {
+    return domain === "shell" || domain === "inc" || domain === "identity" || domain === "theme" || domain === "intent";
+  }
   function makeDomain(domain, existing) {
     if (domain === "shell") return shell;
+    if (domain === "inc") return makeProtectedInc(existing);
+    if (domain === "identity") return makeProtectedIdentity();
+    if (domain === "theme") return makeProtectedTheme();
+    if (domain === "intent") return makeProtectedIntent();
     if (existing && typeof existing === "object" && Object.keys(existing).length > 0) return existing;
     switch (domain) {
       case "relay":
         return makeRelay();
-      case "inc":
-        return makeInc();
       case "storage":
         return makeStorage();
       case "keys":
@@ -2139,10 +2494,6 @@ function nappletNamespacePrelude(domains) {
         return makeMedia();
       case "notify":
         return makeNotify();
-      case "identity":
-        return makeIdentity();
-      case "theme":
-        return makeTheme();
       case "config":
         return makeConfig();
       case "resource":
@@ -2153,8 +2504,6 @@ function nappletNamespacePrelude(domains) {
         return makeOutbox();
       case "upload":
         return makeUpload();
-      case "intent":
-        return makeIntent();
       case "webrtc":
         return makeWebrtc();
       case "ble":
@@ -2184,10 +2533,22 @@ function nappletNamespacePrelude(domains) {
       },
       defineProperty(obj, prop, descriptor) {
         if (typeof prop !== "string" || !allowed.has(prop)) return true;
+        if (isProtectedDomain(prop)) {
+          return Reflect.defineProperty(obj, prop, {
+            value: makeDomain(prop, descriptor.value),
+            enumerable: true,
+            configurable: true,
+            writable: true
+          });
+        }
         return Reflect.defineProperty(obj, prop, {
           ...descriptor,
           value: makeDomain(prop, descriptor.value)
         });
+      },
+      deleteProperty(obj, prop) {
+        if (typeof prop === "string" && allowed.has(prop) && isProtectedDomain(prop)) return true;
+        return Reflect.deleteProperty(obj, prop);
       }
     });
   }
@@ -2217,7 +2578,7 @@ function nappletNamespacePrelude(domains) {
       root = buildNappletNamespace(value);
     },
     enumerable: false,
-    configurable: true
+    configurable: false
   });
 }
 
@@ -2234,9 +2595,10 @@ function createIdentityProxy(deps) {
     dispatch(windowId, envelope) {
       deps.runtime.handleMessage(windowId, envelope);
     },
-    emit(windowId, envelope) {
-      const win = deps.originRegistry.getIframeWindow(windowId);
-      if (win) win.postMessage(envelope, "*");
+    emit(_windowId, _envelope) {
+      throw new Error(
+        "Direct identity proxy emit is prohibited; use ShellBridge.publishIdentityChanged()"
+      );
     }
   };
 }
@@ -2247,9 +2609,10 @@ function createThemeProxy(deps) {
     dispatch(windowId, envelope) {
       deps.runtime.handleMessage(windowId, envelope);
     },
-    emit(windowId, envelope) {
-      const win = deps.originRegistry.getIframeWindow(windowId);
-      if (win) win.postMessage(envelope, "*");
+    emit(_windowId, _envelope) {
+      throw new Error(
+        "Direct theme proxy emit is prohibited; use ShellBridge.publishTheme()"
+      );
     }
   };
 }
@@ -2312,6 +2675,7 @@ export {
   nappKeyRegistry,
   originRegistry,
   renderNappletNamespacePrelude,
+  resolveShellEnvironment,
   sessionRegistry
 };
 //# sourceMappingURL=index.js.map