@frockbot/plugin-shell 0.3.1 → 0.3.3

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>

package/src/client/PackageSurfacePage.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+/**
+ * A Package page hosted as a surface.
+ *
+ * The surface's chrome — its title and the way out of it — belongs to the
+ * shell; the page fills the body and is attributed to the Package that ships
+ * it, so a User always knows whose screen they are looking at.
+ */
+import { computed, inject } from "vue";
+import { frockBotWebDataKey } from "../shared.js";
+import { appletsBridgeStateV2 } from "./applets-state.js";
+import PackageIframeHost from "./PackageIframeHost.vue";
+import type { PackageIframeEntryV1 } from "./package-iframe-entries.js";
+
+const props = defineProps<{ entry: PackageIframeEntryV1 }>();
+const providedWeb = inject(frockBotWebDataKey);
+if (!providedWeb) throw new Error("Package surface data was not provided");
+const web = providedWeb;
+const states = computed(() => ({ applets: appletsBridgeStateV2(web.value) }));
+</script>
+
+<template>
+  <div class="package-surface-page">
+    <PackageIframeHost
+      :contribution="props.entry.contribution"
+      :page="props.entry.page"
+      :slot="props.entry.slot"
+      :states="states"
+    />
+  </div>
+</template>
+
+<style scoped>
+.package-surface-page {
+  display: grid;
+  min-width: 0;
+  gap: 16px;
+}
+</style>

package/src/client/applets-client.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from "bun:test";
+import {
+  mostRecentlyChangedFileV1,
+  readAppletList,
+  readAppletSource,
+  readFocusedAppletId,
+  writeFocusedAppletId,
+  type AppletsHostedRequest,
+} from "./applets-client.js";
+import { appletsAvailableV1, appletsBridgeStateV2 } from "./applets-state.js";
+import type { FrockBotWebData } from "../shared.js";
+
+const summary = {
+  appletId: "u1abc.todo",
+  displayName: "Todo",
+  status: "published" as const,
+  currentGenerationId: "generation-2",
+  tools: ["add_todo"],
+  createdAt: "2026-09-03T00:00:00.000Z",
+};
+
+/** A fake transport, so the client is proven without a backend on the branch. */
+function transportOf(
+  answers: Record<string, unknown>,
+  recorded: Array<{ path: string; method?: string; body?: string }> = [],
+): AppletsHostedRequest {
+  return (path, method, body) => {
+    recorded.push({
+      path,
+      ...(method ? { method } : {}),
+      ...(body ? { body } : {}),
+    });
+    if (!(path in answers))
+      return Promise.reject(new Error(`no route ${path}`));
+    return Promise.resolve(answers[path]);
+  };
+}
+
+describe("Applet routes", () => {
+  test("reads the User's Applets through the strict decoder", async () => {
+    const request = transportOf({
+      "/api/applets": { schemaVersion: 1, applets: [summary] },
+    });
+    expect(await readAppletList(request)).toEqual([summary]);
+  });
+
+  test("refuses a list the decoder does not accept", () => {
+    const request = transportOf({ "/api/applets": { applets: [summary] } });
+    expect(readAppletList(request)).rejects.toThrow();
+  });
+
+  test("the focus write reads back what the backend recorded", async () => {
+    const recorded: Array<{ path: string; method?: string; body?: string }> =
+      [];
+    const request = transportOf(
+      { "/api/bots/bot-1/applets/focus": { appletId: "u1abc.todo" } },
+      recorded,
+    );
+    // The click asked for one Applet; the answer is the one that was recorded.
+    expect(await writeFocusedAppletId(request, "bot-1", "u1abc.other")).toBe(
+      "u1abc.todo",
+    );
+    expect(recorded[0]).toEqual({
+      path: "/api/bots/bot-1/applets/focus",
+      method: "POST",
+      body: JSON.stringify({ schemaVersion: 1, appletId: "u1abc.other" }),
+    });
+    expect(await readFocusedAppletId(request, "bot-1")).toBe("u1abc.todo");
+  });
+
+  test("no focus is a value, not a missing read", async () => {
+    const request = transportOf({
+      "/api/bots/bot-1/applets/focus": { appletId: null },
+    });
+    expect(await readFocusedAppletId(request, "bot-1")).toBeNull();
+  });
+
+  test("the source read is bot-scoped and decoded", async () => {
+    const view = {
+      appletId: "u1abc.todo",
+      files: [
+        {
+          path: "server.ts",
+          text: "export class A {}",
+          generationId: "w-1",
+          changedAt: "2026-09-03T00:01:00.000Z",
+        },
+      ],
+      truncated: false,
+    };
+    const request = transportOf({
+      "/api/bots/bot-1/applets/u1abc.todo/source": view,
+    });
+    expect(await readAppletSource(request, "bot-1", "u1abc.todo")).toEqual(
+      view,
+    );
+  });
+
+  test("the code view follows the most recently changed file", () => {
+    expect(mostRecentlyChangedFileV1(undefined)).toBeUndefined();
+    expect(
+      mostRecentlyChangedFileV1({
+        appletId: "u1abc.todo",
+        truncated: false,
+        files: [
+          {
+            path: "server.ts",
+            text: "",
+            generationId: "w-1",
+            changedAt: "2026-09-03T00:01:00.000Z",
+          },
+          {
+            path: "ui.tsx",
+            text: "",
+            generationId: "w-2",
+            changedAt: "2026-09-03T00:05:00.000Z",
+          },
+        ],
+      }),
+    ).toBe("ui.tsx");
+  });
+});
+
+describe("the applets feed a page receives", () => {
+  const web = {
+    applets: [summary],
+    focusedAppletId: "u1abc.todo",
+    appletViewer: {
+      appletId: "u1abc.todo",
+      token: "signed",
+      expiresAt: "2026-09-03T00:15:00.000Z",
+      socketUrl: "wss://bot.example.com/api/applets/u1abc.todo/socket",
+      uiUrl: "https://ui.example.com/packages/aa.html",
+      generationId: "generation-2",
+    },
+    appletSource: undefined,
+    appletBuild: undefined,
+  } satisfies Pick<
+    FrockBotWebData,
+    | "applets"
+    | "focusedAppletId"
+    | "appletViewer"
+    | "appletSource"
+    | "appletBuild"
+  >;
+
+  test("carries the focused Applet, the list, and the viewer", () => {
+    const state = appletsBridgeStateV2(web);
+    expect(state.focused).toEqual(summary);
+    expect(state.list).toEqual([summary]);
+    expect(state.viewer?.generationId).toBe("generation-2");
+    expect(state.viewer).not.toHaveProperty("expiresAt");
+  });
+
+  test("a viewer credential minted for another Applet is not handed over", () => {
+    const state = appletsBridgeStateV2({
+      ...web,
+      focusedAppletId: "u1abc.other",
+    });
+    expect(state.viewer).toBeNull();
+    expect(state.focused).toBeNull();
+  });
+
+  test("Applets are available only when a Package declares the focus tool", () => {
+    const page = {
+      id: "canvas",
+      artifact: {
+        contentHash: "a".repeat(64),
+        size: 1,
+        mediaType: "text/html" as const,
+        bundlerVersion: "frockbot-inline-html@1",
+      },
+      mounts: [{ slot: "frockbot.right-panel" }],
+    };
+    const catalog = (declaredTools: string[]) => ({
+      schemaVersion: 1 as const,
+      botId: "bot-1",
+      generationId: "generation-1",
+      artifactOrigin: "https://ui.example.com",
+      contributions: [
+        {
+          packageId: "applets",
+          displayName: "Applets",
+          provenance: "Bot-authored" as const,
+          pages: [page],
+          entries: [],
+          declaredTools,
+        },
+      ],
+    });
+    // Derived from a manifest fact, never from a Package id: a deployment
+    // without Applets asks for no Applet route at all.
+    expect(appletsAvailableV1(catalog(["applet_focus"]))).toBe(true);
+    expect(appletsAvailableV1(catalog(["weather_lookup"]))).toBe(false);
+    expect(appletsAvailableV1(undefined)).toBe(false);
+  });
+
+  test("no focus is null rather than an absent field", () => {
+    const state = appletsBridgeStateV2({ ...web, focusedAppletId: null });
+    expect(state.focused).toBeNull();
+    expect(state.viewer).toBeNull();
+    expect(state.list).toEqual([summary]);
+  });
+});