@k2b/cloud 0.38.0 → 0.39.0

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

@@ -0,0 +1,31 @@
+import { i18n } from "@k2b/stdlib";
+
+export const composerInsertMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      insertFromCloud: "Insert from Cloud",
+      insertFromCloudHint: "Find something in your apps and insert it",
+      insertTag: ({ tag }: { tag: string }) => `Insert ${tag}`,
+      chooseFrom: ({ app }: { app: string }) => `Choose from ${app}`,
+      tagFromApp: ({ tag, app }: { tag: string; app: string }) => `${tag} from ${app}`,
+      searchTagFor: ({ tag, query }: { tag: string; query: string }) => `Search ${tag} for “${query}”`,
+      searchTag: ({ tag }: { tag: string }) => `Search ${tag}`,
+      fromAppWithPreview: ({ app }: { app: string }) => `From ${app}, with preview`,
+      searchCloudFor: ({ query }: { query: string }) => `Search Cloud for “${query}”`,
+      searchAllApps: "Search all apps for content",
+    },
+    de: {
+      insertFromCloud: "Aus Cloud einfügen",
+      insertFromCloudHint: "Etwas aus deinen Apps suchen und einfügen",
+      insertTag: ({ tag }) => `${tag} einfügen`,
+      chooseFrom: ({ app }) => `Aus ${app} wählen`,
+      tagFromApp: ({ tag, app }) => `${tag} aus ${app}`,
+      searchTagFor: ({ tag, query }) => `„${query}“ in ${tag} suchen`,
+      searchTag: ({ tag }) => `${tag} durchsuchen`,
+      fromAppWithPreview: ({ app }) => `Aus ${app}, mit Vorschau`,
+      searchCloudFor: ({ query }) => `„${query}“ in Cloud suchen`,
+      searchAllApps: "In allen Apps nach Inhalten suchen",
+    },
+  },
+});

package/src/browser/composer-insert.ts

@@ -0,0 +1,150 @@
+import type { ChatAttachment, ChatCommand, ChatCommandResult, ChatCommandScope } from "@k2b/ui";
+import type { CloudResourceRef } from "../contracts";
+import type { CloudSearchTag } from "./composer-catalog";
+import { composerInsertMessages } from "./composer-insert-messages";
+import { type CloudResourcePickerItem, openCloudResourcePicker } from "./resource-picker";
+
+export {
+  type CloudComposerCatalog,
+  type CloudSearchTag,
+  createCloudComposerCatalog,
+  loadCloudComposerCatalog,
+} from "./composer-catalog";
+
+export type CloudInsertMenuOptions = {
+  locale: string;
+  /** Every app's search tags, from `loadCloudComposerCatalog`. */
+  tags: readonly CloudSearchTag[];
+  /** Section of the rows in the composer's slash list. */
+  section?: string;
+  /** Turns the chosen resource into the reference the composer puts where `/…` was. */
+  mention: (item: CloudResourcePickerItem) => ChatAttachment;
+  /** References the draft already holds; the picker leaves them out. Read when the picker opens. */
+  excludeRefs?: () => readonly CloudResourceRef[];
+  /** Why nothing can be inserted now, such as a full message; it replaces each row's description. */
+  reason?: string;
+  /** First words of the composer's own scopes. A tag never claims them, so they keep narrowing as before. */
+  reservedWords?: readonly string[];
+  /** More first words for one tag, keyed `appId:tag`, such as a short word an app uses for its own tag. */
+  scopeWords?: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Tags, keyed `appId:tag`, whose resources of one type this composer reads itself, such as
+   * `{ "assistant:studio-app": "assistant.app" }`. Their picker lists only that type, also without a Cloud reader, even
+   * after the person removes the scope chip. Every other picker lists only resources with a reader (`requireReader`).
+   */
+  ownReaders?: Readonly<Record<string, string>>;
+};
+
+export type CloudInsertMenu = {
+  /** "Insert from Cloud": the picker across all apps. */
+  insert: ChatCommand;
+  /** One row per search tag, only while searching. Enter opens the picker narrowed to the tag; Tab narrows the list. */
+  tags: ChatCommand[];
+  /** One scope per tag that keeps a first word of its own, titled like "Notes from Notebooks". */
+  scopes: ChatCommandScope[];
+  /** For the composer's `commandFallback`: "Search Notes for “q3”" in a tag scope, "Search Cloud for “q3”" otherwise. */
+  fallback: (search: { query: string; scope?: string }) => ChatCommand | undefined;
+};
+
+const fold = (text: string) => text.toLowerCase().normalize("NFD").replace(/\p{M}/gu, "").replace(/ß/g, "ss");
+const tagKey = (tag: Pick<CloudSearchTag, "appId" | "tag">) => `${tag.appId}:${tag.tag}`;
+const scopeId = (tag: Pick<CloudSearchTag, "appId" | "tag">) => `cloud-tag:${tagKey(tag)}`;
+
+/**
+ * Slash-list rows that insert Cloud content the person can read. Every row opens the resource picker, narrowed on the
+ * server to an app and tag when it has one, and hands the chosen item back as a `mention` for the token's place.
+ */
+export const cloudInsertMenu = (options: CloudInsertMenuOptions): CloudInsertMenu => {
+  const t = composerInsertMessages.resolve([options.locale]).t;
+  const pick = async (tag: CloudSearchTag | undefined, query: string): Promise<ChatCommandResult> => {
+    const ownType = tag ? options.ownReaders?.[tagKey(tag)] : undefined;
+    const item = await openCloudResourcePicker({
+      title: tag ? t.insertTag({ tag: tag.title }) : t.insertFromCloud,
+      scope: tag ? { appId: tag.appId, tag: tag.tag, label: `${tag.title} · ${tag.appName}`, icon: tag.appIcon } : undefined,
+      query: query || undefined,
+      ...(ownType ? { resourceType: ownType } : { requireReader: true }),
+      excludeRefs: options.excludeRefs?.(),
+    });
+    return item ? { mention: options.mention(item) } : "cancelled";
+  };
+
+  const reserved = new Set((options.reservedWords ?? []).map(fold));
+  // The title comes first, so Tab writes the word the person reads ("notizen ").
+  const candidates = options.tags.map((tag) => {
+    const title = fold(tag.title);
+    return [
+      ...new Set(
+        [...(/\s/.test(title) ? [] : [title]), tag.tag, ...tag.aliases, ...(options.scopeWords?.[tagKey(tag)] ?? [])]
+          .map(fold)
+          .filter((word) => word && !/\s/.test(word) && !reserved.has(word)),
+      ),
+    ];
+  });
+  // A word two tags share narrows to neither, so Tab on either row would leave the list unscoped; neither keeps it.
+  const uses = new Map<string, number>();
+  for (const word of candidates.flat()) uses.set(word, (uses.get(word) ?? 0) + 1);
+  const scoped = new Map<string, CloudSearchTag>();
+  const scopes: ChatCommandScope[] = [];
+  const tags = options.tags.map((tag, index): ChatCommand => {
+    const words = candidates[index]!.filter((word) => uses.get(word) === 1);
+    if (words.length) {
+      scoped.set(scopeId(tag), tag);
+      scopes.push({ id: scopeId(tag), title: t.tagFromApp({ tag: tag.title, app: tag.appName }), words });
+    }
+    return {
+      id: scopeId(tag),
+      section: options.section,
+      name: tag.tag,
+      label: tag.title,
+      description: t.chooseFrom({ app: tag.appName }),
+      icon: tag.appIcon,
+      keywords: [tag.title, tag.appName, tag.tag, ...tag.aliases, ...(options.scopeWords?.[tagKey(tag)] ?? [])],
+      app: tag.appName,
+      scope: words.length ? scopeId(tag) : undefined,
+      hiddenUntilSearch: true,
+      reason: options.reason,
+      action: () => pick(tag, ""),
+    };
+  });
+
+  return {
+    insert: {
+      id: "cloud-insert",
+      section: options.section,
+      name: "cloud",
+      label: t.insertFromCloud,
+      description: t.insertFromCloudHint,
+      icon: "ti ti-cloud-search",
+      keywords: ["cloud", "insert", "einfügen", "inhalt", "content", "ressource", "resource", "verweis", "reference", "link"],
+      reason: options.reason,
+      action: () => pick(undefined, ""),
+    },
+    tags,
+    scopes,
+    fallback: ({ query, scope }) => {
+      if (scope !== undefined) {
+        const tag = scoped.get(scope);
+        if (!tag) return undefined;
+        return {
+          id: `cloud-search:${tagKey(tag)}`,
+          name: `cloud-search:${tagKey(tag)}`,
+          label: query ? t.searchTagFor({ tag: tag.title, query }) : t.searchTag({ tag: tag.title }),
+          description: t.fromAppWithPreview({ app: tag.appName }),
+          icon: "ti ti-search",
+          reason: options.reason,
+          action: () => pick(tag, query),
+        };
+      }
+      if (!query) return undefined;
+      return {
+        id: "cloud-search",
+        name: "cloud-search",
+        label: t.searchCloudFor({ query }),
+        description: t.searchAllApps,
+        icon: "ti ti-search",
+        reason: options.reason,
+        action: () => pick(undefined, query),
+      };
+    },
+  };
+};

package/src/browser/panel-messages.ts

@@ -0,0 +1,24 @@
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+export function isPanelReadyMessage(value: unknown, provider: string): value is { type: "cloud.panel.ready"; v: 1; provider: string } {
+  return (
+    isRecord(value) &&
+    Reflect.ownKeys(value).length === 3 &&
+    Object.hasOwn(value, "type") &&
+    Object.hasOwn(value, "v") &&
+    Object.hasOwn(value, "provider") &&
+    value.type === "cloud.panel.ready" &&
+    value.v === 1 &&
+    typeof value.provider === "string" &&
+    value.provider === provider
+  );
+}
+
+export function isPanelCloseMessage(value: unknown): value is { type: "cloud.panel.close"; v?: 1 } {
+  return (
+    isRecord(value) &&
+    Object.hasOwn(value, "type") &&
+    value.type === "cloud.panel.close" &&
+    (Reflect.ownKeys(value).length === 1 || (Reflect.ownKeys(value).length === 2 && Object.hasOwn(value, "v") && value.v === 1))
+  );
+}

package/src/browser/panel-slot.ts

@@ -0,0 +1,354 @@
+import { attachResizeSeparator, parkWorkspaceDetailDrawers } from "@k2b/ui";
+import { PANEL_MAX_WIDTH_REM, PANEL_MIN_WIDTH_REM, readPanelCookie, serializePanelCookie } from "../_internal/panel-cookie";
+import { platformMessages } from "../ssr/platform-messages";
+import { readShellData } from "../ssr/shell-data";
+import type { PanelRequest } from "./panel";
+import { isPanelCloseMessage, isPanelReadyMessage } from "./panel-messages";
+
+export const PANEL_READY_TIMEOUT_MS = 10_000;
+let installed: { dispose: () => void; request: (request: PanelRequest) => void } | undefined;
+
+export function handlePanelRequest(request: PanelRequest): void {
+  installed?.request(request);
+}
+
+/** Owns the slot's single iframe, independently persisted desktop and transient phone state. */
+export function installPanelSlot(): () => void {
+  if (installed) return installed.dispose;
+  const canvas = document.querySelector<HTMLElement>(".cloud-app-canvas");
+  const slot = document.getElementById("cloud-panel");
+  const body = slot?.querySelector<HTMLElement>(".cloud-panel__body");
+  const panel = readShellData()?.panel;
+  if (!canvas || !slot || !body || !panel?.providers.length) return () => {};
+  const t = platformMessages.resolve([document.documentElement.lang || "en"]).t;
+  // The mode uses the same px breakpoint as panel.css and the shell, read fresh, so CSS and the controller always
+  // agree; `phoneChange` only tells when to look again.
+  const isPhone = () => !window.matchMedia("(min-width: 768px)").matches;
+  const phoneChange = window.matchMedia("(max-width: 767.98px)");
+  const column = window.matchMedia("(min-width: 1024px)");
+  const attribute = () => (isPhone() ? "data-panel-sheet" : "data-panel");
+  const isOpen = () => canvas.getAttribute(attribute()) === "open";
+  const status = slot.querySelector<HTMLElement>("[data-cloud-panel-status]");
+  const separator = slot.querySelector<HTMLElement>(".cloud-panel__resize");
+  const tabs = [...slot.querySelectorAll<HTMLButtonElement>("[data-cloud-panel-provider]")];
+  const grow = slot.querySelector<HTMLButtonElement>("[data-cloud-panel-grow]");
+  let provider = panel.providers.find((item) => item.id === slot.dataset.provider) ?? panel.providers[0]!;
+  let frame = slot.querySelector<HTMLIFrameElement>("[data-cloud-panel-frame]");
+  let search: string | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let opener: HTMLElement | undefined;
+  const rem = () => parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+  const storedWidth = parseFloat(canvas.style.getPropertyValue("--cloud-panel-width-set"));
+  let committedWidth = Number.isFinite(storedWidth) ? storedWidth : undefined;
+  let width = committedWidth ?? PANEL_MIN_WIDTH_REM;
+  const setWidth = (value: number) => {
+    width = value;
+    canvas.style.setProperty("--cloud-panel-width-set", `${value}rem`);
+    separator?.setAttribute("aria-valuenow", String(Math.round(value * 100) / 100));
+  };
+  const seedWidth = () => {
+    if (committedWidth !== undefined || !column.matches || !isOpen()) return;
+    const measured = slot.getBoundingClientRect().width / rem();
+    if (measured > 0) width = Math.min(PANEL_MAX_WIDTH_REM, Math.max(PANEL_MIN_WIDTH_REM, measured));
+    separator?.setAttribute("aria-valuenow", String(Math.round(width * 100) / 100));
+  };
+  // Another tab may have saved a newer width; opening or closing keeps it instead of writing back an old one.
+  const adoptStoredWidth = (apply: boolean) => {
+    const stored = readPanelCookie(
+      document.cookie,
+      panel.providers.map((item) => item.id),
+    ).widthRem;
+    if (stored === undefined) return;
+    committedWidth = stored;
+    if (apply && stored !== width) setWidth(stored);
+  };
+  const writeCookie = () => {
+    if (isPhone() || canvas.hasAttribute("data-panel-transient")) return;
+    document.cookie = serializePanelCookie(
+      { open: canvas.dataset.panel === "open", provider: provider.id, widthRem: committedWidth },
+      location.protocol === "https:",
+    );
+  };
+  const update = () => {
+    for (const button of document.querySelectorAll("[data-cloud-panel-toggle]")) button.setAttribute("aria-expanded", String(isOpen()));
+    for (const tab of tabs) {
+      const selected = tab.dataset.cloudPanelProvider === provider.id;
+      tab.setAttribute("aria-selected", String(selected));
+      tab.tabIndex = selected ? 0 : -1;
+    }
+    const description = slot.querySelector<HTMLElement>(".k2b-placeholder__description");
+    if (description) description.textContent = t.panelNotResponding({ label: provider.label });
+  };
+  const clearTimer = () => {
+    clearTimeout(timer);
+    timer = undefined;
+  };
+  const loading = () => {
+    clearTimer();
+    slot.dataset.state = "loading";
+    if (status) status.textContent = t.panelLoading({ label: provider.label });
+    timer = setTimeout(() => {
+      slot.dataset.state = "failed";
+      if (status) status.textContent = `${t.panelLoadFailed}. ${t.panelNotResponding({ label: provider.label })}`;
+    }, PANEL_READY_TIMEOUT_MS);
+  };
+  const markReady = () => {
+    clearTimer();
+    slot.dataset.state = "ready";
+    if (status) status.textContent = "";
+  };
+  const unload = () => {
+    clearTimer();
+    frame?.remove();
+    frame = null;
+    slot.dataset.state = "closed";
+    if (status) status.textContent = "";
+  };
+  const target = () => {
+    const url = new URL(provider.href, location.origin);
+    if (search !== undefined) url.search = search;
+    return url;
+  };
+  // The page the iframe shows now; a reader may have moved on inside the panel since it loaded.
+  const shownHref = () => {
+    try {
+      return frame?.contentWindow?.location.href;
+    } catch {
+      return undefined;
+    }
+  };
+  const load = (replace = false) => {
+    const url = target();
+    if (!replace && frame?.src === url.href) return;
+    frame?.remove();
+    // The server validates every provider path; the iframe still never leaves this origin.
+    if (url.origin !== location.origin) {
+      frame = null;
+      clearTimer();
+      slot.dataset.state = "failed";
+      return;
+    }
+    frame = document.createElement("iframe");
+    frame.className = "cloud-panel__frame";
+    frame.title = provider.label;
+    frame.dataset.cloudPanelFrame = provider.id;
+    frame.src = url.href;
+    loading();
+    body.append(frame);
+  };
+  let removeFallbackFocus = () => {};
+  const returnFocus = () => {
+    if (opener?.isConnected && opener.getClientRects().length && !opener.closest("[inert]")) {
+      opener.focus();
+      if (document.activeElement === opener) return;
+    }
+    const main = canvas.querySelector<HTMLElement>("[data-cloud-app-area] main.layout-content-main, main[data-cloud-app-area]");
+    if (!main) return;
+    removeFallbackFocus();
+    if (!main.hasAttribute("tabindex")) {
+      main.tabIndex = -1;
+      removeFallbackFocus = () => {
+        main.removeAttribute("tabindex");
+        main.removeEventListener("blur", removeFallbackFocus);
+      };
+      main.addEventListener("blur", removeFallbackFocus, { once: true });
+    }
+    main.focus();
+  };
+  const close = () => {
+    if (!isOpen()) return;
+    canvas.removeAttribute(attribute());
+    disposeResize();
+    disposeResize = attachResize();
+    unload();
+    adoptStoredWidth(false);
+    writeCookie();
+    update();
+    returnFocus();
+  };
+  const open = (id: string, nextSearch?: string) => {
+    const next = panel.providers.find((item) => item.id === id);
+    if (!next) return;
+    parkWorkspaceDetailDrawers(document);
+    const active = document.activeElement;
+    if (active instanceof HTMLElement && active !== document.body && !slot.contains(active)) opener = active;
+    provider = next;
+    search = typeof nextSearch === "string" && nextSearch.length <= 2048 ? nextSearch : undefined;
+    canvas.setAttribute(attribute(), "open");
+    slot.dataset.provider = provider.id;
+    adoptStoredWidth(true);
+    seedWidth();
+    // A requested search is a destination: it replaces a page reached inside the panel.
+    const shown = shownHref();
+    load(search !== undefined && shown !== undefined && shown !== "about:blank" && shown !== target().href);
+    writeCookie();
+    update();
+    frame?.focus();
+  };
+  const request = (request: PanelRequest) => {
+    if (request.action === "open") open(request.provider, request.search);
+    else if (request.action === "close" || isOpen()) close();
+    else open(provider.id, search);
+  };
+  const message = (event: MessageEvent<unknown>) => {
+    if (!frame || event.source !== frame.contentWindow || event.origin !== location.origin) return;
+    if (isPanelReadyMessage(event.data, provider.id)) markReady();
+    else if (isPanelCloseMessage(event.data)) close();
+  };
+  const click = (event: MouseEvent) => {
+    if (!(event.target instanceof Element)) return;
+    if (event.target.closest("[data-cloud-panel-close]")) close();
+    else if (event.target.closest("[data-cloud-panel-retry]") && isOpen()) {
+      load(true);
+      frame?.focus();
+    } else if (event.target.closest("[data-cloud-panel-grow]") && isPhone()) {
+      const full = slot.dataset.panelSize !== "full";
+      if (full) slot.dataset.panelSize = "full";
+      else delete slot.dataset.panelSize;
+      grow?.setAttribute("aria-label", full ? t.shrinkPanel : t.enlargePanel);
+    } else {
+      const tab = event.target.closest<HTMLElement>("[data-cloud-panel-provider]");
+      if (tab?.dataset.cloudPanelProvider) open(tab.dataset.cloudPanelProvider);
+    }
+  };
+  const key = (event: KeyboardEvent) => {
+    if (event.defaultPrevented || event.isComposing || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+    if (!(event.target instanceof Element) || !slot.contains(event.target)) return;
+    if (event.key === "Escape") {
+      event.preventDefault();
+      close();
+      return;
+    }
+    const index = tabs.findIndex((tab) => tab === event.target);
+    if (index < 0) return;
+    let next: number;
+    if (event.key === "ArrowRight") next = (index + 1) % tabs.length;
+    else if (event.key === "ArrowLeft") next = (index + tabs.length - 1) % tabs.length;
+    else if (event.key === "Home") next = 0;
+    else if (event.key === "End") next = tabs.length - 1;
+    else return; // Buttons activate with native Enter/Space clicks.
+    event.preventDefault();
+    for (const [index, tab] of tabs.entries()) tab.tabIndex = index === next ? 0 : -1;
+    tabs[next]?.focus();
+  };
+  const modeChange = () => {
+    disposeResize();
+    if (isOpen()) {
+      seedWidth();
+      load();
+    } else unload();
+    disposeResize = attachResize();
+    update();
+  };
+  const closeSheet = () => {
+    const wasOpen = canvas.dataset.panelSheet === "open";
+    canvas.removeAttribute("data-panel-sheet");
+    if (wasOpen && isPhone()) {
+      unload();
+      update();
+    }
+  };
+  const pageShow = (event: PageTransitionEvent) => {
+    if (event.persisted) closeSheet();
+  };
+  const entryChange = (event: NavigationCurrentEntryChangeEvent) => {
+    if (event.navigationType === "push") closeSheet();
+  };
+  let dragWidth = width;
+  let dragStoredWidth = committedWidth;
+  let dragInlineWidth = "";
+  const restoreDragWidth = () => {
+    width = dragWidth;
+    committedWidth = dragStoredWidth;
+    if (dragInlineWidth) canvas.style.setProperty("--cloud-panel-width-set", dragInlineWidth);
+    else canvas.style.removeProperty("--cloud-panel-width-set");
+    separator?.setAttribute("aria-valuenow", String(Math.round(width * 100) / 100));
+  };
+  let endingDrag = false;
+  seedWidth();
+  const attachResize = () =>
+    separator && column.matches
+      ? attachResizeSeparator(separator, {
+          min: PANEL_MIN_WIDTH_REM,
+          max: PANEL_MAX_WIDTH_REM,
+          value: () => width,
+          get unit() {
+            return rem();
+          },
+          step: 1,
+          largeStep: 4,
+          grow: "start",
+          collapseBelow: 16,
+          onResize: (value) => {
+            if (endingDrag) {
+              endingDrag = false;
+              restoreDragWidth();
+            } else setWidth(value);
+          },
+          onResizeEnd: (value) => {
+            endingDrag = false;
+            committedWidth = value;
+            writeCookie();
+          },
+          onCollapseIntent: (armed) => {
+            if (armed) slot.dataset.closing = "true";
+            else delete slot.dataset.closing;
+          },
+          onCollapse: () => {
+            endingDrag = false;
+            restoreDragWidth();
+            close();
+          },
+          onDragChange: (dragging) => {
+            if (dragging) {
+              dragWidth = width;
+              dragStoredWidth = committedWidth;
+              dragInlineWidth = canvas.style.getPropertyValue("--cloud-panel-width-set");
+              slot.dataset.resizing = "true";
+            } else {
+              delete slot.dataset.resizing;
+              endingDrag = true;
+            }
+          },
+        })
+      : () => {};
+  let disposeResize = attachResize();
+  window.addEventListener("message", message);
+  window.addEventListener("keydown", key);
+  slot.addEventListener("click", click);
+  phoneChange.addEventListener("change", modeChange);
+  column.addEventListener("change", modeChange);
+  window.addEventListener("pageshow", pageShow);
+  window.addEventListener("popstate", closeSheet);
+  window.navigation?.addEventListener("currententrychange", entryChange);
+  window.addEventListener("resize", seedWidth);
+  // An SSR iframe can have posted its one-shot ready before this lazy module
+  // arrived. Its runtime also marks its own same-origin document, so read that
+  // once the listener is in place instead of loading the provider again.
+  if (isOpen() && frame) {
+    if (frame.contentDocument?.documentElement.dataset.cloudPanelReady === provider.id) markReady();
+    else loading();
+  } else if (isOpen()) load();
+  else unload();
+  update();
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    clearTimer();
+    disposeResize();
+    removeFallbackFocus();
+    window.removeEventListener("message", message);
+    window.removeEventListener("keydown", key);
+    slot.removeEventListener("click", click);
+    phoneChange.removeEventListener("change", modeChange);
+    column.removeEventListener("change", modeChange);
+    window.removeEventListener("pageshow", pageShow);
+    window.removeEventListener("popstate", closeSheet);
+    window.navigation?.removeEventListener("currententrychange", entryChange);
+    window.removeEventListener("resize", seedWidth);
+    installed = undefined;
+  };
+  installed = { dispose, request };
+  return dispose;
+}

package/src/browser/panel.ts

@@ -0,0 +1,28 @@
+export type PanelRequest = { action: "open"; provider: string; search?: string; accepted: boolean } | { action: "close" | "toggle" };
+
+declare global {
+  interface WindowEventMap {
+    "cloud.panel.request": CustomEvent<PanelRequest>;
+  }
+}
+
+/** Opens a visible provider. False leaves navigation with the caller when this page has no matching slot. */
+export function openPanel(provider: string, options?: { search?: string }): boolean {
+  const detail: PanelRequest = {
+    action: "open",
+    provider,
+    search: typeof options?.search === "string" && options.search.length <= 2048 ? options.search : undefined,
+    accepted: false,
+  };
+  window.dispatchEvent(new CustomEvent("cloud.panel.request", { detail }));
+  return detail.accepted;
+}
+
+/** Closes the panel when it is open. */
+export function closePanel(): void {
+  if (window.parent !== window && document.querySelector("[data-cloud-panel-page]")) {
+    window.parent.postMessage({ type: "cloud.panel.close" }, location.origin);
+    return;
+  }
+  window.dispatchEvent(new CustomEvent<PanelRequest>("cloud.panel.request", { detail: { action: "close" } }));
+}

package/src/browser/resource-picker.tsx

@@ -6,10 +6,14 @@ import { resourceSearchDialogOptions } from "./resource-search-dialog";
 import { resourceSearchMessages } from "./resource-search-messages";
 
 export type CloudResourcePickerItem = SearchItem;
+/** Narrows the search on the server to one app and, optionally, one of its search tags; shown as the removable chip. */
+export type CloudResourcePickerScope = { appId: string; tag?: string; label: string; icon?: string };
 export type CloudResourcePickerOptions = {
   title?: string;
   placeholder?: string;
   initialAppId?: string;
+  scope?: CloudResourcePickerScope;
+  query?: string;
   excludeRefs?: readonly CloudResourceRef[];
   requireReader?: boolean;
   resourceType?: string;
@@ -20,7 +24,14 @@ export const openCloudResourcePicker = (options: CloudResourcePickerOptions = {}
   const t = resourceSearchMessages.resolve([locale]).t;
   return dialogCore.open<CloudResourcePickerItem>(
     (close) => (
-      <CloudResourceSearch {...options} title={options.title ?? t.chooseResource} selectionMode onSelect={close} onClose={() => close()} />
+      <CloudResourceSearch
+        {...options}
+        request={options.scope !== undefined || options.query !== undefined ? { scope: options.scope, query: options.query } : undefined}
+        title={options.title ?? t.chooseResource}
+        selectionMode
+        onSelect={close}
+        onClose={() => close()}
+      />
     ),
     // A phone shows the picker as a full-screen sheet; global search keeps its floating card.
     {