@frockbot/plugin-shell 0.3.1 → 0.3.2

package/src/client/FrockBotApp.vue

@@ -27,6 +27,7 @@ import {
 } from "../shared.js";
 import { ComposerDraftStore } from "./composer-draft.js";
 import SendPayloadView from "./SendPayloadView.vue";
+import AppletCanvas from "./AppletCanvas.vue";
 import PackageIframeHost from "./PackageIframeHost.vue";
 import type { ClientSkillCatalogEntryV1 } from "../skill-protocol.js";
 import {
@@ -127,11 +128,113 @@ function closeDrawers(): void {
   if (!panelSurface.value) rightPanelOpen.value = false;
 }
 
+/*
+ * Escape, wherever the focus is.
+ *
+ * A drawer's own trigger disappears when the drawer opens, so focus can land
+ * back on the document body — outside this component's element — and a handler
+ * bound to the root would never see the key. The window is where "give the
+ * conversation back" has to be heard.
+ */
 function onRootKeydown(event: KeyboardEvent): void {
-  if (event.key !== "Escape" || !navOpen.value) return;
+  if (event.key !== "Escape" || event.defaultPrevented) return;
+  if (navOpen.value) {
+    event.preventDefault();
+    closeNav();
+    return;
+  }
+  // An open overlay owns Escape; closing the panel underneath it would be a
+  // second dismissal the User did not ask for.
+  if (overlaySurface.value) return;
+  // On a phone the right panel covers the conversation, so Escape gives the
+  // conversation back — the same thing tapping the scrim does.
+  if (phoneLayout.value && rightPanelOpen.value && !panelSurface.value) {
+    event.preventDefault();
+    rightPanelOpen.value = false;
+  }
+}
+
+/*
+ * The Applet canvas.
+ *
+ * A Session with a focused Applet gives the right panel to the canvas; without
+ * one the panel keeps the content its plugins put there. The canvas is wider
+ * than a summary column, and how much wider is the User's: the width they drag
+ * is theirs and is remembered per browser, which is a per-viewer convenience
+ * rather than durable state and belongs in local storage.
+ */
+const APPLET_PANEL_WIDTH_KEY = "frockbot.applet-panel-width";
+const APPLET_PANEL_MIN = 320;
+const APPLET_PANEL_MAX = 900;
+const APPLET_PANEL_DEFAULT = 480;
+
+function readStoredPanelWidth(): number {
+  try {
+    const stored = Number(window.localStorage.getItem(APPLET_PANEL_WIDTH_KEY));
+    if (!Number.isFinite(stored) || stored <= 0) return APPLET_PANEL_DEFAULT;
+    return Math.min(APPLET_PANEL_MAX, Math.max(APPLET_PANEL_MIN, stored));
+  } catch {
+    return APPLET_PANEL_DEFAULT;
+  }
+}
+
+const appletPanelWidth = ref(
+  typeof window === "undefined" ? APPLET_PANEL_DEFAULT : readStoredPanelWidth(),
+);
+const appletCanvasOpen = computed(() =>
+  Boolean(state.value.focusedAppletId && !panelSurface.value),
+);
+
+function storePanelWidth(width: number): void {
+  try {
+    window.localStorage.setItem(APPLET_PANEL_WIDTH_KEY, String(width));
+  } catch {
+    // A browser that refuses storage still resizes; it just forgets.
+  }
+}
+
+function setPanelWidth(width: number): void {
+  appletPanelWidth.value = Math.min(
+    APPLET_PANEL_MAX,
+    Math.max(APPLET_PANEL_MIN, Math.round(width)),
+  );
+}
+
+function onPanelHandlePointerDown(event: PointerEvent): void {
+  if (phoneLayout.value) return;
+  const target = event.currentTarget as HTMLElement;
+  target.setPointerCapture(event.pointerId);
+  const move = (moveEvent: PointerEvent) => {
+    setPanelWidth(window.innerWidth - moveEvent.clientX);
+  };
+  const stop = () => {
+    target.removeEventListener("pointermove", move);
+    target.removeEventListener("pointerup", stop);
+    target.removeEventListener("pointercancel", stop);
+    storePanelWidth(appletPanelWidth.value);
+  };
+  target.addEventListener("pointermove", move);
+  target.addEventListener("pointerup", stop);
+  target.addEventListener("pointercancel", stop);
+}
+
+/** The keyboard's way to do what the drag does. */
+function onPanelHandleKeydown(event: KeyboardEvent): void {
+  const step = event.shiftKey ? 64 : 16;
+  if (event.key === "ArrowLeft") setPanelWidth(appletPanelWidth.value + step);
+  else if (event.key === "ArrowRight")
+    setPanelWidth(appletPanelWidth.value - step);
+  else return;
   event.preventDefault();
-  closeNav();
+  storePanelWidth(appletPanelWidth.value);
 }
+
+/** The phone's way into a focused Applet while the panel is closed. */
+const appletChip = computed(() =>
+  phoneLayout.value && !rightPanelOpen.value && state.value.focusedAppletId
+    ? (state.value.focusedApplet?.displayName ?? "Applet")
+    : undefined,
+);
 /*
  * Skill invocation. `/` or `@` at a word boundary opens a popover over the
  * Bot's catalog; choosing one attaches a ref chip and removes the trigger from
@@ -195,9 +298,16 @@ function iframeEntriesFor(tool: WebToolActivity) {
   const slot = `frockbot.tool-result:${tool.name}`;
   return (state.value.packageUi?.contributions ?? [])
     .flatMap((contribution) =>
-      contribution.mounts
-        .filter((mount) => mount.slot === slot)
-        .map((mount) => ({ contribution, slot, order: mount.order ?? 0 })),
+      contribution.pages.flatMap((page) =>
+        page.mounts
+          .filter((mount) => mount.slot === slot)
+          .map((mount) => ({
+            contribution,
+            page,
+            slot,
+            order: mount.order ?? 0,
+          })),
+      ),
     )
     .sort(
       (left, right) =>
@@ -387,12 +497,14 @@ onMounted(() => {
   window.addEventListener("popstate", applySettingsDeepLink);
   window.addEventListener("hashchange", applySettingsDeepLink);
   phoneLayoutMedia?.addEventListener("change", onPhoneLayoutChange);
+  window.addEventListener("keydown", onRootKeydown);
 });
 
 onBeforeUnmount(() => {
   window.removeEventListener("popstate", applySettingsDeepLink);
   window.removeEventListener("hashchange", applySettingsDeepLink);
   phoneLayoutMedia?.removeEventListener("change", onPhoneLayoutChange);
+  window.removeEventListener("keydown", onRootKeydown);
 });
 
 watch(
@@ -584,16 +696,18 @@ function handleComposerKeydown(event: KeyboardEvent): void {
 </script>
 
 <template>
-  <div class="frockbot-root" @keydown="onRootKeydown">
+  <div class="frockbot-root">
     <div
       class="app-shell"
       :class="{
         'panel-open': rightPanelOpen,
         'panel-surface': Boolean(panelSurface),
+        'panel-applet': appletCanvasOpen,
         'mac-desktop': macDesktop,
         'phone-layout': phoneLayout,
         'nav-open': navOpen,
       }"
+      :style="{ '--applet-panel-width': `${appletPanelWidth}px` }"
     >
       <aside
         class="sidebar"
@@ -713,12 +827,12 @@ function handleComposerKeydown(event: KeyboardEvent): void {
               <template v-for="tool in message.tools" :key="tool.id">
                 <PackageIframeHost
                   v-for="entry in iframeEntriesFor(tool)"
-                  :key="`${tool.id}:${entry.contribution.packageId}`"
+                  :key="`${tool.id}:${entry.contribution.packageId}:${entry.page.id}`"
                   class="message-package-iframe"
                   :contribution="entry.contribution"
+                  :page="entry.page"
                   :slot="entry.slot"
-                  :state-name="`tool:${tool.name}`"
-                  :state-value="toolResultState(tool)"
+                  :states="{ [`tool:${tool.name}`]: toolResultState(tool) }"
                 />
               </template>
               <!--
@@ -870,6 +984,21 @@ function handleComposerKeydown(event: KeyboardEvent): void {
               </span>
             </li>
           </ul>
+          <!--
+            The phone's way back to a focused Applet. The panel is a drawer
+            here, so with it closed there is nothing on screen that says an
+            Applet is in play; this chip both says so and opens it.
+          -->
+          <button
+            v-if="appletChip"
+            type="button"
+            class="applet-chip"
+            @click="toggleRightPanel"
+          >
+            <UiIcon name="applets" size="sm" />
+            <span class="applet-chip-name">Applet: {{ appletChip }}</span>
+            <span class="applet-chip-action">Open</span>
+          </button>
           <div class="composer-body">
             <ul v-if="attachedSkills.length > 0" class="skill-chips">
               <li v-for="entry in attachedSkills" :key="entry.ref">
@@ -936,15 +1065,40 @@ function handleComposerKeydown(event: KeyboardEvent): void {
           Both layers live in one stack so panel plugins keep their state
           while a surface holds their place.
         -->
+        <!--
+          The edge the User drags to make room for an Applet. It is a real
+          control, not a hairline: it takes focus and the arrow keys do what
+          the drag does.
+        -->
+        <div
+          v-if="appletCanvasOpen && !phoneLayout"
+          class="applet-panel-handle"
+          role="separator"
+          tabindex="0"
+          aria-orientation="vertical"
+          aria-label="Resize the Applet panel"
+          :aria-valuenow="appletPanelWidth"
+          :aria-valuemin="320"
+          :aria-valuemax="900"
+          @pointerdown="onPanelHandlePointerDown"
+          @keydown="onPanelHandleKeydown"
+        />
         <div class="right-panel-stack">
           <Transition name="panel-swap">
             <div v-show="!panelSurface" class="right-panel-content">
-              <header class="right-panel-header">
-                <k-slot name="frockbot.bot-actions" />
-              </header>
-              <div class="right-panel-body">
-                <k-slot name="frockbot.right-panel" />
-              </div>
+              <!--
+                A focused Applet takes the panel; with none, the panel is the
+                one its plugins have always drawn.
+              -->
+              <AppletCanvas v-if="appletCanvasOpen" />
+              <template v-else>
+                <header class="right-panel-header">
+                  <k-slot name="frockbot.bot-actions" />
+                </header>
+                <div class="right-panel-body">
+                  <k-slot name="frockbot.right-panel" />
+                </div>
+              </template>
             </div>
           </Transition>
           <Transition name="panel-swap">

package/src/client/PackageEntryTrigger.vue

@@ -0,0 +1,77 @@
+<script setup lang="ts">
+/**
+ * One declarative Package entry in the sidebar.
+ *
+ * Everything drawn here is manifest data — the label, the icon name, and the
+ * page the entry opens — so a Package reaches the sidebar without running any
+ * code in the app origin. The icon is looked up in the shared set; a Package
+ * naming an icon this client does not have falls back to the generic one
+ * rather than drawing nothing.
+ */
+import { clientSurfaceRegistryKey } from "@frockbot/client-core";
+import { UiIcon, uiIconPaths, type UiIconName } from "@frockbot/client-ui";
+import { computed, inject } from "vue";
+import type { PackageIframeEntryV1 } from "./package-iframe-entries.js";
+
+const props = defineProps<{ entry: PackageIframeEntryV1 }>();
+const surfaces = inject(clientSurfaceRegistryKey);
+if (!surfaces) throw new Error("client surface registry was not provided");
+
+const icon = computed<UiIconName>(() =>
+  Object.hasOwn(uiIconPaths, props.entry.entry.icon)
+    ? (props.entry.entry.icon as UiIconName)
+    : "plugins",
+);
+
+function open(): void {
+  if (surfaces?.has(props.entry.surfaceId))
+    surfaces.open(props.entry.surfaceId);
+}
+</script>
+
+<template>
+  <button class="package-entry-trigger" type="button" @click="open">
+    <span class="package-entry-trigger__icon"><UiIcon :name="icon" /></span>
+    {{ entry.entry.label }}
+  </button>
+</template>
+
+<style scoped>
+.package-entry-trigger {
+  display: flex;
+  width: 100%;
+  height: 40px;
+  align-items: center;
+  gap: 10px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: var(--frock-radius-control);
+  color: var(--frock-text);
+  background: transparent;
+  font-size: var(--frock-text-md);
+  font-weight: 500;
+  text-align: left;
+  cursor: pointer;
+  transition: background-color var(--frock-motion-fast);
+}
+
+.package-entry-trigger:hover {
+  background: var(--frock-fill-hover);
+}
+
+.package-entry-trigger:active {
+  background: var(--frock-fill-pressed);
+}
+
+.package-entry-trigger__icon {
+  display: grid;
+  width: var(--frock-avatar-sm);
+  height: var(--frock-avatar-sm);
+  flex: 0 0 auto;
+  place-items: center;
+  border-radius: 8px;
+  color: var(--frock-action-primary);
+  background: var(--frock-surface);
+  box-shadow: inset 0 0 0 1px var(--frock-border);
+}
+</style>

package/src/client/PackageIframeHost.vue

@@ -1,20 +1,35 @@
 <script setup lang="ts">
 import {
-  decodePackageIframePageMessageV1,
+  decodePackageIframePageMessageV2,
+  packageIframeExternalUrlAllowedV2,
+  packageIframeFocusAllowedV2,
   packageIframeToolAllowedV1,
+  type PackageIframeBridgeVersionV2,
   type PackageIframeContributionViewV1,
-  type PackageIframeHostMessageV1,
+  type PackageIframeHostMessageV2,
+  type PackageIframePageViewV1,
 } from "@frockbot/kernel-contracts";
 import { computed, inject, onBeforeUnmount, onMounted, ref, watch } from "vue";
 import { frockBotWebDataKey } from "../shared.js";
 import { postPackageIframeHostMessage } from "./package-iframe-host-message.js";
 
-const props = defineProps<{
-  contribution: PackageIframeContributionViewV1;
-  slot: string;
-  stateName: string;
-  stateValue: unknown;
-}>();
+const props = withDefaults(
+  defineProps<{
+    contribution: PackageIframeContributionViewV1;
+    page: PackageIframePageViewV1;
+    slot: string;
+    /** The named state feeds this frame receives, by state name. */
+    states: Record<string, unknown>;
+    /**
+     * `flow` gives the frame the height the page asks for; `fill` gives it the
+     * height of its container, for a page that owns a whole panel.
+     */
+    layout?: "flow" | "fill";
+    /** A page hosted in a surface has its attribution drawn by the surface. */
+    attribution?: boolean;
+  }>(),
+  { layout: "flow", attribution: true },
+);
 const providedWeb = inject(frockBotWebDataKey);
 if (!providedWeb) throw new Error("Package iframe host data was not provided");
 const web = providedWeb;
@@ -22,37 +37,86 @@ const frame = ref<HTMLIFrameElement>();
 const height = ref(240);
 const failure = ref<string>();
 const lastStateWireByName = new Map<string, string>();
+/*
+ * Which bridge this page reads. A page announces version 2 with `hello`; one
+ * that never announces is a version 1 page and is only ever sent version 1
+ * messages, so a page published before the bump keeps working unchanged.
+ */
+const bridgeVersion = ref<PackageIframeBridgeVersionV2>(1);
 const catalog = computed(() => web.value.packageUi);
 const source = computed(() => {
   const origin = catalog.value?.artifactOrigin;
   return origin
-    ? `${origin}/packages/${props.contribution.artifact.contentHash}.html`
+    ? `${origin}/packages/${props.page.artifact.contentHash}.html`
     : "about:blank";
 });
 
-const THEME_TOKEN_NAMES = [
-  "surface",
-  "surface-raised",
-  "surface-subtle",
-  "text",
-  "text-muted",
-  "border",
-  "accent-surface",
-  "accent-text",
-  "radius-card",
+/*
+ * The theme a page is given.
+ *
+ * Design tokens are the contract between the shell and a Package's page (ADR
+ * 0007): a page is handed semantic names, never the shell's stylesheet, and
+ * never a colour to hard-code. The list is what an Applet kit needs to build a
+ * whole screen — surfaces, text, borders, the accent, the three status
+ * colours, the focus ring, geometry, and the type scale — under names that say
+ * what a value is for rather than which shell control it came from.
+ */
+const THEME_TOKENS: ReadonlyArray<readonly [string, string]> = [
+  ["surface", "surface"],
+  ["surface-raised", "surface-raised"],
+  ["surface-subtle", "surface-subtle"],
+  ["surface-window", "surface-window"],
+  ["text", "text"],
+  ["text-muted", "text-muted"],
+  ["text-subtle", "text-subtle"],
+  ["border", "border"],
+  ["border-strong", "border-strong"],
+  ["accent", "action-primary"],
+  ["accent-hover", "action-primary-hover"],
+  ["accent-pressed", "action-primary-pressed"],
+  ["accent-surface", "accent-surface"],
+  ["accent-text", "accent-text"],
+  ["on-accent", "on-accent"],
+  ["danger", "danger-text"],
+  ["danger-surface", "danger-surface"],
+  ["danger-border", "danger-border"],
+  ["success", "success"],
+  ["success-surface", "success-surface"],
+  ["success-border", "success-border"],
+  ["warning", "warning"],
+  ["warning-surface", "warning-surface"],
+  ["warning-border", "warning-border"],
+  ["focus-ring", "focus-ring"],
+  ["fill-hover", "fill-hover"],
+  ["fill-pressed", "fill-pressed"],
+  ["radius-control", "radius-control"],
+  ["radius-card", "radius-card"],
+  ["control-sm", "control-sm"],
+  ["control-md", "control-md"],
+  ["control-lg", "control-lg"],
+  ["font-sans", "font-sans"],
+  ["font-mono", "font-mono"],
+  ["text-xs", "text-xs"],
+  ["text-sm", "text-sm"],
+  ["text-base", "text-base"],
+  ["text-md", "text-md"],
+  ["text-lg", "text-lg"],
+  ["text-xl", "text-xl"],
+  ["leading-normal", "leading-normal"],
+  ["motion-fast", "motion-fast"],
 ] as const;
 
 function themeTokens(): Record<string, string> {
   const styles = getComputedStyle(document.documentElement);
   return Object.fromEntries(
-    THEME_TOKEN_NAMES.map((name) => [
+    THEME_TOKENS.map(([name, token]) => [
       name,
-      styles.getPropertyValue(`--frock-${name}`).trim(),
-    ]),
+      styles.getPropertyValue(`--frock-${token}`).trim(),
+    ]).filter(([, value]) => value !== ""),
   );
 }
 
-function post(message: PackageIframeHostMessageV1): void {
+function post(message: PackageIframeHostMessageV2): void {
   const target = frame.value?.contentWindow;
   if (!target) return;
   try {
@@ -63,51 +127,75 @@ function post(message: PackageIframeHostMessageV1): void {
   }
 }
 
+function postStates(): void {
+  for (const [name, value] of Object.entries(props.states)) {
+    post({
+      schemaVersion: bridgeVersion.value,
+      type: "state",
+      name,
+      value,
+    });
+  }
+}
+
 function initialize(): void {
   const botId = web.value.activeBotId;
   if (!botId) return;
   lastStateWireByName.clear();
   post({
-    schemaVersion: 1,
+    schemaVersion: bridgeVersion.value,
     type: "init",
     themeTokens: themeTokens(),
     packageId: props.contribution.packageId,
     botId,
     slot: props.slot,
+    pageId: props.page.id,
   });
-  post({
-    schemaVersion: 1,
-    type: "state",
-    name: props.stateName,
-    value: props.stateValue,
-  });
+  postStates();
 }
 
-watch(
-  () => [props.stateName, props.stateValue] as const,
-  () =>
-    post({
-      schemaVersion: 1,
-      type: "state",
-      name: props.stateName,
-      value: props.stateValue,
-    }),
-  { deep: true },
-);
+watch(() => props.states, postStates, { deep: true });
 
 async function onMessage(event: MessageEvent): Promise<void> {
   if (!frame.value?.contentWindow || event.source !== frame.value.contentWindow)
     return;
   let message;
   try {
-    message = decodePackageIframePageMessageV1(event.data);
+    message = decodePackageIframePageMessageV2(event.data);
   } catch {
     return;
   }
+  if (message.type === "hello") {
+    // The announcement can land before or after the frame's load event, so the
+    // handshake is re-sent at the announced version either way.
+    if (bridgeVersion.value === message.bridgeVersion) return;
+    bridgeVersion.value = message.bridgeVersion;
+    initialize();
+    return;
+  }
   if (message.type === "resize") {
     height.value = Math.min(1_200, Math.max(96, Math.round(message.height)));
     return;
   }
+  if (message.type === "focus") {
+    if (!packageIframeFocusAllowedV2(props.contribution)) {
+      failure.value = "This Package cannot change the focused Applet.";
+      return;
+    }
+    failure.value = undefined;
+    await web.value.setFocusedApplet(message.appletId);
+    return;
+  }
+  if (message.type === "openExternal") {
+    const origin = catalog.value?.artifactOrigin;
+    if (!origin || !packageIframeExternalUrlAllowedV2(message.url, origin)) {
+      failure.value = "This Package page can only open its own pages.";
+      return;
+    }
+    failure.value = undefined;
+    window.open(message.url, "_blank", "noopener,noreferrer");
+    return;
+  }
   if (!packageIframeToolAllowedV1(props.contribution, message.name)) {
     failure.value = `This Package did not declare ${message.name}.`;
     return;
@@ -120,7 +208,7 @@ async function onMessage(event: MessageEvent): Promise<void> {
       message.input,
     );
     post({
-      schemaVersion: 1,
+      schemaVersion: bridgeVersion.value,
       type: "state",
       name: `tool:${message.name}`,
       value: result,
@@ -128,7 +216,7 @@ async function onMessage(event: MessageEvent): Promise<void> {
   } catch (error) {
     failure.value = error instanceof Error ? error.message : "Tool call failed";
     post({
-      schemaVersion: 1,
+      schemaVersion: bridgeVersion.value,
       type: "state",
       name: `tool:${message.name}`,
       value: { isError: true, content: failure.value },
@@ -141,8 +229,8 @@ onBeforeUnmount(() => window.removeEventListener("message", onMessage));
 </script>
 
 <template>
-  <section class="package-iframe-frame">
-    <header class="package-iframe-attribution">
+  <section class="package-iframe-frame" :class="`package-iframe-${layout}`">
+    <header v-if="attribution" class="package-iframe-attribution">
       <strong>{{ contribution.displayName }}</strong>
       <span>{{ contribution.provenance }} Package</span>
     </header>
@@ -151,7 +239,7 @@ onBeforeUnmount(() => window.removeEventListener("message", onMessage));
       ref="frame"
       :title="`${contribution.displayName} Package page`"
       :src="source"
-      :style="{ height: `${height}px` }"
+      :style="layout === 'fill' ? undefined : { height: `${height}px` }"
       sandbox="allow-scripts"
       credentialless
       referrerpolicy="no-referrer"
@@ -172,6 +260,19 @@ onBeforeUnmount(() => window.removeEventListener("message", onMessage));
   background: var(--frock-surface);
 }
 
+.package-iframe-fill {
+  display: flex;
+  height: 100%;
+  flex-direction: column;
+  border: 0;
+  border-radius: 0;
+}
+
+.package-iframe-fill iframe {
+  min-height: 0;
+  flex: 1;
+}
+
 .package-iframe-attribution {
   position: relative;
   z-index: 1;

package/src/client/PackageIframeSettings.vue

@@ -11,9 +11,11 @@ const slot = "frockbot.bot-settings-sections";
 const contributions = computed(() =>
   (web.value.packageUi?.contributions ?? [])
     .flatMap((contribution) =>
-      contribution.mounts
-        .filter((mount) => mount.slot === slot)
-        .map((mount) => ({ contribution, order: mount.order ?? 0 })),
+      contribution.pages.flatMap((page) =>
+        page.mounts
+          .filter((mount) => mount.slot === slot)
+          .map((mount) => ({ contribution, page, order: mount.order ?? 0 })),
+      ),
     )
     .sort(
       (left, right) =>
@@ -34,11 +36,11 @@ function settingsFor(packageId: string): Record<string, unknown> {
   <div v-if="contributions.length > 0" class="package-iframe-settings">
     <PackageIframeHost
       v-for="entry in contributions"
-      :key="entry.contribution.packageId"
+      :key="`${entry.contribution.packageId}:${entry.page.id}`"
       :contribution="entry.contribution"
+      :page="entry.page"
       :slot="slot"
-      state-name="settings"
-      :state-value="settingsFor(entry.contribution.packageId)"
+      :states="{ settings: settingsFor(entry.contribution.packageId) }"
     />
   </div>
 </template>