@k2b/cloud 0.39.0 → 0.40.0

package/src/browser/app-approval.ts

@@ -7,11 +7,19 @@ import {
   APP_ACTION_LIMITS,
   APP_APPROVAL_LIMITS,
   APP_APPROVAL_PATH,
+  APP_APPROVAL_PENDING_ACCEPT,
   APP_APPROVAL_PROTOCOL,
   type AppActionView,
   AppActionViewSchema,
   type AppApprovalAccept,
+  type AppApprovalPendingAccept,
+  type AppDeviceChange,
+  AppDeviceChangeSchema,
   AppDeviceCommandSchema,
+  type AppDeviceInbox,
+  AppDeviceInboxSchema,
+  type AppDeviceInboxWithChanges,
+  AppDeviceInboxWithChangesSchema,
   AppDeviceProofSchema,
   type AppDevicePublicKey,
   AppDevicePublicKeySchema,
@@ -197,7 +205,8 @@ const connect = async (options: {
       );
     },
     pairingResult: (payload: AppPairingPayload, key: AppApprovalKey, signal?: AbortSignal) => {
-      const p = pairing(payload);
+      const p = AppPairingPayloadSchema.parse(payload);
+      if (p.issuer !== issuer) throw new AppApprovalClientError("INVALID_INPUT");
       return request(
         "/pairings/result",
         AppPairingResultSchema,
@@ -205,8 +214,10 @@ const connect = async (options: {
         signal,
       );
     },
-    pending: async (device: AppApprovalDevice, signal?: AbortSignal) => {
-      const result = await command(device, { operation: "pending" }, signal);
+    pending: async (device: AppApprovalDevice, signal?: AbortSignal, options?: { accept?: AppApprovalPendingAccept[] }) => {
+      // Untyped callers may reuse their inbox list; drop what pending does not serve instead of failing every poll.
+      const accept = options?.accept?.filter((entry) => APP_APPROVAL_PENDING_ACCEPT.includes(entry) && info.features?.includes(entry));
+      const result = await command(device, { operation: "pending", ...(accept?.length ? { accept } : {}) }, signal);
       if (!("requests" in result)) throw new AppApprovalClientError("INVALID_RESPONSE");
       return result;
     },
@@ -226,12 +237,46 @@ const connect = async (options: {
     actions: info.features?.includes("actions") === true,
     /** Whether this Cloud can include terminal consent in an explicitly opted-in inbox. */
     terminalLogins: info.features?.includes("terminal-logins") === true,
+    /** Whether this Cloud serves sign-in context through a signed opt-in. */
+    loginContext: info.features?.includes("login-context") === true,
+    /** Whether this Cloud lists requests to pair or remove a device in an inbox that accepts `device-changes`. */
+    deviceChanges: info.features?.includes("device-changes") === true,
     /** Pending sign-ins and the newest open Action approvals in one call; use it instead of `pending` where `actions` is true. */
-    inbox: async (device: AppApprovalDevice, signal?: AbortSignal, options?: { accept?: AppApprovalAccept[] }) => {
+    inbox: async (
+      device: AppApprovalDevice,
+      signal?: AbortSignal,
+      options?: { accept?: AppApprovalAccept[] },
+    ): Promise<AppDeviceInbox | AppDeviceInboxWithChanges> => {
       // SDK upgrades alone must not expose consent the app cannot show. Old Clouds never see the new key.
       const accept = options?.accept?.filter((entry) => info.features?.includes(entry));
       const result = await command(device, { operation: "inbox", ...(accept?.length ? { accept } : {}) }, signal);
-      if (!("actions" in result)) throw new AppApprovalClientError("INVALID_RESPONSE");
+      if (!("actions" in result) || (accept?.includes("device-changes") && (!("changes" in result) || !("moreChanges" in result))))
+        throw new AppApprovalClientError("INVALID_RESPONSE");
+      return "changes" in result ? AppDeviceInboxWithChangesSchema.parse(result) : AppDeviceInboxSchema.parse(result);
+    },
+    /**
+     * Signs a decision on one entry of `changes`, a request to pair or remove a device of this account. Only call it on an
+     * explicit choice of the person. The device being removed can approve its own removal; its `deny` throws
+     * `AppApprovalClientError` with code `HTTP` and status 409.
+     */
+    decideChange: async (device: AppApprovalDevice, change: AppDeviceChange, decision: "approve" | "deny", signal?: AbortSignal) => {
+      const parsed = AppDeviceChangeSchema.safeParse(change);
+      if (!parsed.success || Date.parse(parsed.data.expiresAt) <= Date.now()) throw new AppApprovalClientError("INVALID_INPUT");
+      change = parsed.data;
+      const result = await command(
+        device,
+        {
+          operation: "change",
+          changeId: change.changeId,
+          kind: change.kind,
+          targetId: change.device.id,
+          endSessions: change.endSessions,
+          decision,
+        },
+        signal,
+      );
+      if (!("state" in result) || result.state !== (decision === "approve" ? "approved" : "denied"))
+        throw new AppApprovalClientError("INVALID_RESPONSE");
       return result;
     },
     /** One open Action approval. The digest is recomputed here, so a view that does not match it is never returned. */
@@ -263,6 +308,10 @@ const connect = async (options: {
       if (!("state" in result) || result.state !== "updated") throw new AppApprovalClientError("INVALID_RESPONSE");
       return result;
     },
+    /**
+     * Removes this device itself at once, without approval from a paired device. Sign-ins it approved stay signed in.
+     * Removing a device from Cloud in the browser waits for a paired device to approve instead.
+     */
     revoke: async (device: AppApprovalDevice, signal?: AbortSignal) => {
       const result = await command(device, { operation: "revoke" }, signal);
       if (!("state" in result) || result.state !== "revoked") throw new AppApprovalClientError("INVALID_RESPONSE");

package/src/browser/commands.ts

@@ -14,17 +14,33 @@ export type { CommandOptions } from "../contracts/commands";
 export type { CommandTarget, ContextAwareCommand } from "./command-bridge";
 export { registerCommandHandler, registerContextAwareCommand } from "./command-bridge";
 
-/** Opens locally only when a mounted owner explicitly accepts; otherwise follows the app's URL. */
-export const openCommand = async (command: string, input: unknown = {}, options: CommandOptions = {}): Promise<void> => {
+/**
+ * Opens locally only when a mounted owner accepts; otherwise follows the app's URL.
+ * Resolves true after the owner's handler resolves or navigation starts.
+ * Resolves false if code cannot load (with a reload notice) or `signal` aborts before handling or while resolving the link.
+ * An accepting owner takes over without the signal. Handler rejections and link resolution failures still reject.
+ */
+export const openCommand = async (
+  command: string,
+  input: unknown = {},
+  options: CommandOptions = {},
+  signal?: AbortSignal,
+): Promise<boolean> => {
   const modules = await importOnDemand(() => Promise.all([import("../contracts/commands"), import("../capabilities/client")]));
-  if (!modules) return;
+  if (!modules || signal?.aborted) return false;
   const [contracts, capabilities] = modules;
   const parsedOptions = contracts.CommandOptionsSchema.parse(options);
   const handled = requestCommandHandling({ command, input, options: parsedOptions });
-  if (handled) return handled;
-  const result = await capabilities.resolveCommand(command, input, parsedOptions);
-  if (!result.ok) throw new Error(result.error.message);
+  if (handled) {
+    await handled;
+    return true;
+  }
+  // An abort also ends the request, so a cancelled opening does not wait for its answer.
+  const result = await capabilities.resolveCommand(command, input, parsedOptions, { signal });
+  if (signal?.aborted) return false;
+  if (!result.ok) throw new Error(result.error.message, { cause: result.error });
   window.location.assign(result.data.href);
+  return true;
 };
 
 /** Call after this page's handlers have mounted. Each entry is consumed, including invalid links. */

package/src/browser/composer-catalog.ts

@@ -2,6 +2,8 @@ import type { ChatCommandSearch } from "@k2b/ui";
 import { createSignal } from "solid-js";
 import { listCapabilityCatalog } from "../capabilities/client";
 import { LOCALE_HEADER } from "../shared/locale";
+import { discoverableCommandInput } from "./discoverable-command";
+import { navigationApps } from "./navigation-apps";
 
 export type CloudSearchTag = {
   appId: string;
@@ -13,12 +15,25 @@ export type CloudSearchTag = {
   aliases: readonly string[];
 };
 
+export type CloudComposerCommand = {
+  id: string;
+  appId: string;
+  appName: string;
+  appIcon: string;
+  title: string;
+  description: string;
+  icon: string;
+  keywords: readonly string[];
+  input: unknown;
+};
+
 /**
  * What composers read from the page's one Capability catalog load. It leaves out the tags of apps without a resource
  * reader: a picker that requires one can show none of their results. A composer that reads such a type itself adds its
  * tag on its own and names the type in `cloudInsertMenu`'s `ownReaders`.
  */
-export type CloudComposerCatalog = { tags: readonly CloudSearchTag[] };
+export type CloudComposerCatalog = { tags: readonly CloudSearchTag[]; commands: readonly CloudComposerCommand[] };
+export type CloudComposerCatalogState = "loading" | "ready" | "failed";
 
 /** The budget of one Capability query (and of resolving a Command), applied to each catalog page. */
 const CATALOG_PAGE_TIMEOUT_MS = 15_000;
@@ -27,6 +42,8 @@ const catalogs = new Map<string, Promise<CloudComposerCatalog>>();
 
 const loadCatalog = async (locale: string): Promise<CloudComposerCatalog> => {
   const tags: CloudSearchTag[] = [];
+  const commands: CloudComposerCommand[] = [];
+  const { appIds, currentAppId } = navigationApps();
   const seen = new Set<string>();
   let cursor: string | undefined;
   do {
@@ -39,6 +56,23 @@ const loadCatalog = async (locale: string): Promise<CloudComposerCatalog> => {
     });
     if (!result.ok) throw new Error(result.error.message);
     for (const app of result.data.apps) {
+      if (app.appId !== currentAppId) {
+        for (const command of app.manifest.commands) {
+          const input = discoverableCommandInput(command, app.appId, appIds);
+          if (!input?.success) continue;
+          commands.push({
+            id: `${app.appId}.${command.localId}`,
+            appId: app.appId,
+            appName: app.appName,
+            appIcon: app.appIcon,
+            title: command.title,
+            description: command.description,
+            icon: command.icon ?? app.appIcon,
+            keywords: command.keywords,
+            input: input.data,
+          });
+        }
+      }
       if (!app.manifest.types.some((type) => type.reader)) continue;
       for (const query of app.manifest.queries) {
         for (const tag of query.universalSearch?.tags ?? []) {
@@ -53,7 +87,7 @@ const loadCatalog = async (locale: string): Promise<CloudComposerCatalog> => {
     if (next && cursor && next <= cursor) throw new Error("Invalid Composer catalog cursor");
     cursor = next;
   } while (cursor);
-  return { tags };
+  return { tags, commands };
 };
 
 /**
@@ -72,7 +106,7 @@ export const loadCloudComposerCatalog = (locale: string): Promise<CloudComposerC
 };
 
 /**
- * The search tags of one composer. Call `ready` at the start of every `searchCommands` run: each menu opening starts
+ * The search tags, Commands, and load state of one composer. Call `ready` at the start of every `searchCommands` run: each menu opening starts
  * the shared load once, so only the first opening, or one after a failure, sends a request, and no keystroke does.
  * A search with typed text and no scope waits for that answer, so "/notiz" never settles as "nothing found" before its
  * tag arrives. The overview and scoped searches do not wait, and after a failed load no search waits again; a later
@@ -80,20 +114,28 @@ export const loadCloudComposerCatalog = (locale: string): Promise<CloudComposerC
  */
 export function createCloudComposerCatalog(load: (locale: string) => Promise<CloudComposerCatalog> = loadCloudComposerCatalog) {
   const [tags, setTags] = createSignal<readonly CloudSearchTag[]>([]);
+  const [commands, setCommands] = createSignal<readonly CloudComposerCommand[]>([]);
+  const [state, setState] = createSignal<CloudComposerCatalogState>("loading");
   let opening: number | undefined;
   let settled: Promise<void> = Promise.resolve();
   let failed = false;
   return {
     tags,
+    commands,
+    state,
     ready(query: string, search: ChatCommandSearch, locale: string): Promise<void> {
       if (opening !== search.opening) {
         opening = search.opening;
+        if (state() === "failed") setState("loading");
         settled = load(locale).then(
           (catalog) => {
             setTags(catalog.tags);
+            setCommands(catalog.commands);
+            setState("ready");
           },
           () => {
             failed = true;
+            setState("failed");
           },
         );
       }

package/src/browser/composer-insert.ts

@@ -6,11 +6,21 @@ import { type CloudResourcePickerItem, openCloudResourcePicker } from "./resourc
 
 export {
   type CloudComposerCatalog,
+  type CloudComposerCatalogState,
+  type CloudComposerCommand,
   type CloudSearchTag,
   createCloudComposerCatalog,
   loadCloudComposerCatalog,
 } from "./composer-catalog";
 
+export {
+  type CloudCommandMenu,
+  type CloudCommandMenuOptions,
+  cloudCommandMenu,
+  type OpenComposerCommandOptions,
+  openComposerCommand,
+} from "./composer-open";
+
 export type CloudInsertMenuOptions = {
   locale: string;
   /** Every app's search tags, from `loadCloudComposerCatalog`. */

package/src/browser/composer-open-messages.ts

@@ -0,0 +1,17 @@
+import { i18n } from "@k2b/stdlib";
+
+export const composerOpenMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      appUnavailable: ({ app }: { app: string }) => `${app} is not reachable right now. Choose it again to try once more.`,
+      commandsFailed: "Commands from apps could not be loaded",
+      tryAgain: "Try again",
+    },
+    de: {
+      appUnavailable: ({ app }) => `${app} ist gerade nicht erreichbar. Erneut wählen versucht es nochmal.`,
+      commandsFailed: "Befehle aus Apps konnten nicht geladen werden",
+      tryAgain: "Erneut versuchen",
+    },
+  },
+});

package/src/browser/composer-open.ts

@@ -0,0 +1,110 @@
+import type { ChatCommand, ChatCommandDraft, ChatCommandOpenResult } from "@k2b/ui";
+import { CAPABILITY_FRAMEWORK_ERROR_CODES } from "../contracts/capabilities";
+import { isCommandPath } from "../contracts/command-path";
+import { openCommand } from "./commands";
+import type { CloudComposerCatalogState, CloudComposerCommand } from "./composer-catalog";
+import { composerOpenMessages } from "./composer-open-messages";
+
+export type OpenComposerCommandOptions = {
+  before: () => Promise<void>;
+  returnTo: () => string | undefined;
+  /** Read after `before`; once it aborts, for example because the person left the chat, nothing opens. */
+  signal?: () => AbortSignal | undefined;
+  locale: string;
+};
+
+/**
+ * Save first, then resolve and open. If nothing opens, cancel so the composer keeps its token and restores the live draft.
+ * Save errors reach the status line; resolution errors stay on the retryable row.
+ */
+export const openComposerCommand = async (
+  command: CloudComposerCommand,
+  options: OpenComposerCommandOptions,
+): Promise<ChatCommandOpenResult> => {
+  await options.before();
+  const signal = options.signal?.();
+  if (signal?.aborted) return "cancelled";
+  const returnTo = options.returnTo();
+  if (returnTo !== undefined && !isCommandPath(returnTo)) throw new Error("Invalid Command return path");
+  try {
+    if (!(await openCommand(command.id, command.input, { returnTo }, signal))) return "cancelled";
+  } catch (error) {
+    if (signal?.aborted) return "cancelled";
+    const cause = error instanceof Error ? error.cause : undefined;
+    if (
+      typeof cause === "object" &&
+      cause !== null &&
+      "code" in cause &&
+      typeof cause.code === "string" &&
+      "status" in cause &&
+      typeof cause.status === "number" &&
+      "message" in cause &&
+      typeof cause.message === "string" &&
+      cause.code !== CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable &&
+      ![502, 503, 504].includes(cause.status) &&
+      cause.message
+    ) {
+      return { failed: cause.message };
+    }
+    return { failed: composerOpenMessages.resolve([options.locale]).t.appUnavailable({ app: command.appName }) };
+  }
+  if (signal?.aborted) return "cancelled";
+};
+
+export type CloudCommandMenuOptions = {
+  locale: string;
+  commands: readonly CloudComposerCommand[];
+  state: CloudComposerCatalogState;
+  section?: string;
+  before: (draft: ChatCommandDraft, signal: AbortSignal, follow: () => void) => Promise<void>;
+  returnTo: () => string | undefined;
+  /** See `OpenComposerCommandOptions.signal`. */
+  signal?: () => AbortSignal | undefined;
+};
+export type CloudCommandMenu = { commands: ChatCommand[]; pending: boolean };
+
+/** Put this section last. Pending placeholders reserve its end; a failed catalog offers one explicit reload. */
+export const cloudCommandMenu = (options: CloudCommandMenuOptions): CloudCommandMenu => {
+  const t = composerOpenMessages.resolve([options.locale]).t;
+  if (options.state === "loading") return { commands: [], pending: true };
+  if (options.state === "failed")
+    return {
+      commands: [
+        {
+          id: "cloud-commands-retry",
+          name: "cloud-commands-retry",
+          label: t.commandsFailed,
+          description: t.tryAgain,
+          icon: "ti ti-alert-circle",
+          searchAgain: true,
+          persistent: true,
+          section: options.section,
+        },
+      ],
+      pending: false,
+    };
+  return {
+    commands: options.commands.map((command) => ({
+      id: `cloud-command:${command.id}`,
+      name: command.id,
+      label: command.title,
+      description: `${command.appName} · ${command.description}`,
+      icon: command.icon,
+      keywords: [command.title, ...command.keywords, command.appName, command.description],
+      app: command.appName,
+      section: options.section,
+      // The composer's signal aborts when the person closes the list; the opener's, when it leaves the chat.
+      open: (draft, closed, follow) =>
+        openComposerCommand(command, {
+          before: () => options.before(draft, closed, follow),
+          returnTo: options.returnTo,
+          signal: () => {
+            const left = options.signal?.();
+            return left ? AbortSignal.any([closed, left]) : closed;
+          },
+          locale: options.locale,
+        }),
+    })),
+    pending: false,
+  };
+};

package/src/browser/discoverable-command.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+import type { CapabilityCommandManifest } from "../contracts/capabilities";
+
+/** Shared discovery rule for the palette and composers; it grants no access to the destination. */
+export const discoverableCommandInput = (command: CapabilityCommandManifest, appId: string, appIds: ReadonlySet<string>) =>
+  appIds.has(appId) ? z.fromJSONSchema(structuredClone(command.inputSchema)).safeParse({}) : undefined;

package/src/browser/hints.ts

@@ -0,0 +1,6 @@
+import { mergeSeenHints, parseSeenHintsCookieHeader, seenHintsSetCookie } from "../contracts/seen-hints";
+
+/** Persist dismissal before navigating or closing the hint. */
+export const markHintSeen = (id: string): void => {
+  document.cookie = seenHintsSetCookie(mergeSeenHints(parseSeenHintsCookieHeader(document.cookie), id), location.protocol === "https:");
+};

package/src/browser/live-connection.ts

@@ -10,6 +10,8 @@ export type LiveSubscriptionHandlers<T> = {
   apply: (events: { data: T; cursor: string }[]) => Promise<void>;
   /** Loads the canonical state again; events after it follow. */
   resync: () => Promise<void>;
+  /** Reports changes in whether the subscription is confirmed and has no pending work. Never called after `close()`. */
+  caughtUp?: (caughtUp: boolean) => void;
   /** The subscription ended because its resource is gone or no longer readable. */
   revoked?: (code: "not_found" | "access_denied") => void;
   /** Live updates stopped: the session ended, or `apply` or `resync` kept failing. Never called after `close()`. */
@@ -25,6 +27,7 @@ export type LiveConnection = {
 type Subscriber = {
   frame: () => unknown;
   confirmed: boolean;
+  report: () => void;
   receive: (message: LiveServerMessage) => void;
   end: () => void;
 };
@@ -56,9 +59,17 @@ const connect = (url: string, activity: "visible" | "always"): Shared => {
     onOpen: (controls) => {
       for (const subscriber of subscribers.values()) {
         subscriber.confirmed = false;
+        subscriber.report();
         controls.send(subscriber.frame());
       }
     },
+    onStatus: (status) => {
+      if (status === "open") return;
+      for (const subscriber of subscribers.values()) {
+        subscriber.confirmed = false;
+        subscriber.report();
+      }
+    },
     onMessage: (message) => {
       if (message.t === "progress") {
         for (const subscriber of subscribers.values()) if (subscriber.confirmed) subscriber.receive(message);
@@ -96,8 +107,16 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
     let resyncAt: string | null = null;
     let ended = false;
     let running = false;
+    let caughtUp = false;
     const work: Work<T>[] = [];
 
+    const report = () => {
+      const next = !ended && subscriber.confirmed && !running && work.length === 0;
+      if (next === caughtUp) return;
+      caughtUp = next;
+      handlers.caughtUp?.(next);
+    };
+
     const attempt = async (run: () => Promise<void>): Promise<boolean> => {
       for (let tries = 0; ; tries++) {
         try {
@@ -122,6 +141,7 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
             cursor = item.cursor;
             continue;
           }
+          report();
           const applied = item.kind === "events" ? await attempt(() => handlers.apply(item.events)) : await attempt(handlers.resync);
           if (!applied) {
             // A closed subscription reports nothing: its owner ended it.
@@ -135,6 +155,7 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
         }
       } finally {
         running = false;
+        report();
       }
     };
 
@@ -153,6 +174,7 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
         return { t: "sub", id, channel, scope, ...(after ? { after } : {}) };
       },
       confirmed: false,
+      report,
       receive: (message) => {
         if (ended) return;
         if (message.t === "revoked") {
@@ -189,10 +211,12 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
       },
     };
 
-    const stop = () => {
+    const stop = (notify = true) => {
       if (ended) return;
       ended = true;
       work.length = 0;
+      if (notify) report();
+      else caughtUp = false;
       if (subscribers.get(id) !== subscriber) return;
       subscribers.delete(id);
       socket.send({ t: "unsub", id });
@@ -205,6 +229,6 @@ export const liveConnection = (url: string, options: { activity?: "visible" | "a
     subscribers.set(id, subscriber);
     if (subscribers.size === 1) socket.connect();
     else socket.send(subscriber.frame());
-    return { close: stop };
+    return { close: () => stop(false) };
   },
 });

package/src/browser/navigation-apps.ts

@@ -0,0 +1,7 @@
+import { readShellData } from "../ssr/shell-data";
+
+/** Navigation controls discoverability, never authorization; the target application still checks access. */
+export const navigationApps = (): { appIds: ReadonlySet<string>; currentAppId?: string } => {
+  const shell = readShellData();
+  return { appIds: new Set(shell?.apps.map((app) => app.id) ?? []), currentAppId: shell?.appId };
+};

package/src/browser/panel-context-bridge.ts

@@ -0,0 +1,30 @@
+import type { CloudResourceRef } from "../contracts/capabilities";
+import type { PanelPageContext } from "../contracts/panel-context";
+
+export const PAGE_CONTEXT_COLLECT = "cloud.page-context.collect";
+export const PAGE_CONTEXT_CHANGED = "cloud.page-context.changed";
+export const PANEL_CONTEXT_CHANGED = "cloud.panel.context.changed";
+export const PANEL_CONTEXT_ELEMENT = "cloud-panel-context";
+export const PANEL_SHORTCUTS_ELEMENT = "cloud-panel-shortcuts";
+export const PANEL_SHORTCUTS_CHANGED = "cloud.panel.shortcuts.changed";
+export type PageContextSource = { scope?: CloudResourceRef };
+export type PageContextCollection = { sources: PageContextSource[] };
+export type PanelConsentRequest = { provider: string; allowed: boolean };
+export type PanelState = { provider: string; appName: string; consent: boolean; allowed: boolean; saving: boolean; open: boolean };
+
+declare global {
+  interface WindowEventMap {
+    "cloud.panel.consent": CustomEvent<PanelConsentRequest>;
+    "cloud.panel.state": CustomEvent<PanelState>;
+  }
+}
+
+/** Framework-validated SSR data, then receiver-validated messages. Shared DOM state survives independent bundles. */
+export function readProviderContext(): PanelPageContext | null {
+  if (typeof document === "undefined") return null;
+  try {
+    return JSON.parse(document.getElementById(PANEL_CONTEXT_ELEMENT)?.textContent ?? "null");
+  } catch {
+    return null;
+  }
+}

package/src/browser/panel-context-receiver.ts

@@ -0,0 +1,53 @@
+import { isPanelContextMessage } from "../contracts/panel-context-plain";
+import {
+  PANEL_CONTEXT_CHANGED,
+  PANEL_CONTEXT_ELEMENT,
+  PANEL_SHORTCUTS_CHANGED,
+  PANEL_SHORTCUTS_ELEMENT,
+  readProviderContext,
+} from "./panel-context-bridge";
+
+/** Installed only by an embedded PanelRuntime; the public page publisher never imports validation. */
+export function installPanelContextReceiver(): () => void {
+  let element = document.getElementById(PANEL_CONTEXT_ELEMENT);
+  if (!element) {
+    element = document.createElement("script");
+    element.id = PANEL_CONTEXT_ELEMENT;
+    element.setAttribute("type", "application/json");
+    element.textContent = "null";
+    document.body.append(element);
+  }
+  let shortcutsElement = document.getElementById(PANEL_SHORTCUTS_ELEMENT);
+  if (!shortcutsElement) {
+    shortcutsElement = document.createElement("script");
+    shortcutsElement.id = PANEL_SHORTCUTS_ELEMENT;
+    shortcutsElement.setAttribute("type", "application/json");
+    shortcutsElement.textContent = "[]";
+    document.body.append(shortcutsElement);
+  }
+  const first = readProviderContext();
+  let pageId = first?.pageId;
+  let seq = first?.seq ?? 0;
+  const receive = (event: MessageEvent<unknown>) => {
+    if (event.source !== window.parent || event.origin !== location.origin || !isPanelContextMessage(event.data)) return;
+    const context = event.data.context;
+    if (context) {
+      if ((pageId !== undefined && context.pageId !== pageId) || context.seq < seq) return;
+      pageId = context.pageId;
+      seq = context.seq;
+    }
+    // Null revokes the current context without forgetting document identity or ordering.
+    const contextJson = JSON.stringify(context);
+    const contextChanged = element.textContent !== contextJson;
+    element.textContent = contextJson;
+    const shortcuts = JSON.stringify(context ? (event.data.shortcuts ?? []) : []);
+    const shortcutsChanged = shortcutsElement.textContent !== shortcuts;
+    shortcutsElement.textContent = shortcuts;
+    // Remember accepted snapshots, including empty ones, across Help remounts.
+    shortcutsElement.setAttribute("data-received", "");
+    if (shortcutsChanged) window.dispatchEvent(new Event(PANEL_SHORTCUTS_CHANGED));
+    if (contextChanged || !shortcutsChanged) window.dispatchEvent(new Event(PANEL_CONTEXT_CHANGED));
+  };
+  window.addEventListener("message", receive);
+  return () => window.removeEventListener("message", receive);
+}

package/src/browser/panel-menu.tsx

@@ -0,0 +1,56 @@
+import { Dropdown } from "@k2b/ui";
+import { createSignal, onCleanup, onMount } from "solid-js";
+import { platformMessages } from "../ssr/platform-messages";
+import type { PanelState } from "./panel-context-bridge";
+
+/**
+ * The slot head's ⋯ menu for providers that need consent. The lazy slot controller mounts it over the server's
+ * placeholder button, so it costs no island and can never change an answer before the controller listens. Only
+ * document events cross the menu/controller boundary.
+ */
+export default function PanelMenu(props: { initial: PanelState; locale: string }) {
+  const t = () => platformMessages.resolve([props.locale]).t;
+  const [state, setState] = createSignal(props.initial);
+  const [open, setOpen] = createSignal(false);
+  onMount(() => {
+    const changed = (event: CustomEvent<PanelState>) => {
+      // A closed slot, another provider or one without consent leaves no reason for the menu to stay expanded.
+      if (!event.detail.open || event.detail.provider !== state().provider || !event.detail.consent) setOpen(false);
+      setState(event.detail);
+    };
+    window.addEventListener("cloud.panel.state", changed);
+    onCleanup(() => window.removeEventListener("cloud.panel.state", changed));
+  });
+  return (
+    <Dropdown.Root
+      open={open()}
+      onOpenChange={setOpen}
+      label={t().panelMenu}
+      position="bottom-left"
+      items={[
+        {
+          sectionLabel: t().panelFrom({ app: state().appName }),
+          items: [
+            {
+              label: t().panelShareContext,
+              choice: "checkbox",
+              // A getter: the menu keeps its rows, so a plain value would show the answer from when it opened.
+              checked: () => state().allowed,
+              disabled: state().saving,
+              action: () =>
+                window.dispatchEvent(
+                  new CustomEvent("cloud.panel.consent", {
+                    detail: { provider: state().provider, allowed: !state().allowed },
+                  }),
+                ),
+            },
+          ],
+        },
+      ]}
+    >
+      <Dropdown.Trigger iconOnly label={t().panelMenu} disabled={!state().consent}>
+        <i class="ti ti-dots" aria-hidden="true" />
+      </Dropdown.Trigger>
+    </Dropdown.Root>
+  );
+}