@frockbot/plugin-shell 0.3.1 → 0.3.3

package/src/client/package-iframe-entries.ts

@@ -0,0 +1,112 @@
+/**
+ * Declarative Package entries.
+ *
+ * An entry is manifest data — an id, a label, an icon name, and the page it
+ * opens — so a Package puts a control in the shell's sidebar without shipping
+ * a line of JavaScript into the app origin. This module turns the catalog into
+ * the ordered list the shell registers, and nothing here executes Package
+ * code.
+ */
+import type {
+  PackageIframeCatalogV1,
+  PackageIframeContributionViewV1,
+  PackageIframeEntryViewV1,
+  PackageIframePageViewV1,
+} from "@frockbot/kernel-contracts";
+
+export interface PackageIframeEntryV1 {
+  contribution: PackageIframeContributionViewV1;
+  entry: PackageIframeEntryViewV1;
+  page: PackageIframePageViewV1;
+  /** The slot the page is mounted in when the entry opens it. */
+  slot: string;
+  /** The shell surface id this entry opens. Stable for one Package page. */
+  surfaceId: string;
+  /** Where the entry sits among the slot's other fillers. */
+  order: number;
+}
+
+/** The order a Package entry takes when its manifest names none. */
+export const PACKAGE_IFRAME_ENTRY_DEFAULT_ORDER_V1 = 50;
+
+export function packageIframeSurfaceIdV1(
+  packageId: string,
+  pageId: string,
+): string {
+  return `package-page:${packageId}:${pageId}`;
+}
+
+export function packageIframePageSlotV1(pageId: string): string {
+  return `frockbot.surface:${pageId}`;
+}
+
+/**
+ * Every entry the Bot's active Composition declares, in the order the sidebar
+ * draws them. Ties break on Package id so two Packages asking for the same
+ * order draw in a stable sequence rather than in catalog order.
+ */
+export function packageIframeEntriesV1(
+  catalog: PackageIframeCatalogV1 | undefined,
+): PackageIframeEntryV1[] {
+  return (catalog?.contributions ?? [])
+    .flatMap((contribution) =>
+      contribution.entries.flatMap((entry) => {
+        const page = contribution.pages.find(
+          (candidate) => candidate.id === entry.opens.page,
+        );
+        // The catalog decoder already refuses an entry whose page does not
+        // mount its own surface slot; this keeps the projection total anyway,
+        // because a shell that renders half an entry is worse than one that
+        // renders none.
+        if (!page) return [];
+        return [
+          {
+            contribution,
+            entry,
+            page,
+            slot: packageIframePageSlotV1(page.id),
+            surfaceId: packageIframeSurfaceIdV1(
+              contribution.packageId,
+              page.id,
+            ),
+            order: entry.order ?? PACKAGE_IFRAME_ENTRY_DEFAULT_ORDER_V1,
+          },
+        ];
+      }),
+    )
+    .toSorted(
+      (left, right) =>
+        left.order - right.order ||
+        left.contribution.packageId.localeCompare(
+          right.contribution.packageId,
+        ) ||
+        left.entry.id.localeCompare(right.entry.id),
+    );
+}
+
+/**
+ * The pages mounted in one slot, in mount order. The right panel and the
+ * settings screen both read their pages this way.
+ */
+export function packageIframePagesForSlotV1(
+  catalog: PackageIframeCatalogV1 | undefined,
+  slot: string,
+): Array<{
+  contribution: PackageIframeContributionViewV1;
+  page: PackageIframePageViewV1;
+  order: number;
+}> {
+  return (catalog?.contributions ?? [])
+    .flatMap((contribution) =>
+      contribution.pages.flatMap((page) =>
+        page.mounts
+          .filter((mount) => mount.slot === slot)
+          .map((mount) => ({ contribution, page, order: mount.order ?? 0 })),
+      ),
+    )
+    .toSorted(
+      (left, right) =>
+        left.order - right.order ||
+        left.contribution.packageId.localeCompare(right.contribution.packageId),
+    );
+}

package/src/client/package-iframe-host-message.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import type { PackageIframeHostMessageV1 } from "@frockbot/kernel-contracts";
+import type { PackageIframeHostMessageV2 } from "@frockbot/kernel-contracts";
 import { postPackageIframeHostMessage } from "./package-iframe-host-message.js";
 
 describe("Package iframe host messages", () => {
   test("posts unchanged state once and posts changed state again", () => {
-    const posted: PackageIframeHostMessageV1[] = [];
+    const posted: PackageIframeHostMessageV2[] = [];
     const target = {
-      postMessage(message: PackageIframeHostMessageV1): void {
+      postMessage(message: PackageIframeHostMessageV2): void {
         posted.push(message);
       },
     } as Pick<Window, "postMessage">;

package/src/client/package-iframe-host-message.ts

@@ -1,10 +1,10 @@
-import type { PackageIframeHostMessageV1 } from "@frockbot/kernel-contracts";
+import type { PackageIframeHostMessageV2 } from "@frockbot/kernel-contracts";
 
 type MessageTarget = Pick<Window, "postMessage">;
 
 export function postPackageIframeHostMessage(
   target: MessageTarget,
-  message: PackageIframeHostMessageV1,
+  message: PackageIframeHostMessageV2,
   lastStateWireByName: Map<string, string>,
 ): void {
   const wire = JSON.stringify(message);
@@ -20,7 +20,7 @@ export function postPackageIframeHostMessage(
 
   // Vue settings values may be reactive proxies, which structured clone
   // rejects. JSON is also the bridge's declared value domain.
-  target.postMessage(JSON.parse(wire) as PackageIframeHostMessageV1, "*");
+  target.postMessage(JSON.parse(wire) as PackageIframeHostMessageV2, "*");
   if (message.type === "state") {
     lastStateWireByName.set(message.name, wire);
   }

package/src/client/styles.css

@@ -49,6 +49,15 @@
   --panel-current: var(--panel-surface-width);
 }
 
+/*
+ * An Applet needs room a summary column does not have, and how much is the
+ * User's: `--applet-panel-width` is the width they last dragged, written by
+ * the component and remembered per browser.
+ */
+.app-shell.panel-open.panel-applet {
+  --panel-current: var(--applet-panel-width, 480px);
+}
+
 /* Sidebar */
 
 .sidebar {
@@ -254,6 +263,17 @@
   margin-top: 18px;
 }
 
+/*
+ * A message the User sent while the Bot was still working. It is an ordinary
+ * message the Bot has not reached yet, so it is drawn as one and simply held
+ * back — no label, no icon, no word for the User to learn. It goes to full
+ * strength the moment its own Turn starts.
+ */
+.message-pending {
+  opacity: 0.55;
+  transition: opacity var(--frock-motion-enter);
+}
+
 /* A Session announcement: the conversation narrating itself, not a party. */
 .message-system {
   align-items: center;
@@ -577,6 +597,44 @@
  * message being composed, not a separate control.
  */
 
+/*
+ * The focused Applet, on a phone, while its panel is closed.
+ *
+ * It sits above the composer rather than inside it: the composer's row is the
+ * message and the send control, and squeezing a third thing into it is what
+ * makes a phone composer unusable.
+ */
+.applet-chip {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  left: 0;
+  display: inline-flex;
+  max-width: 100%;
+  height: var(--frock-control-md);
+  align-items: center;
+  gap: 6px;
+  padding: 0 10px;
+  border: 1px solid var(--frock-border-strong);
+  border-radius: 999px;
+  color: var(--frock-text);
+  background: var(--frock-surface-raised);
+  box-shadow: var(--frock-shadow-control);
+  font-size: var(--frock-text-sm);
+  cursor: pointer;
+}
+
+.applet-chip-name {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.applet-chip-action {
+  flex: 0 0 auto;
+  color: var(--frock-action-primary);
+  font-weight: 600;
+}
+
 .composer-body {
   display: flex;
   width: 100%;
@@ -702,6 +760,50 @@
   flex-direction: column;
 }
 
+.panel-applet .right-panel-content {
+  width: var(--applet-panel-width, 480px);
+}
+
+/*
+ * The Applet panel's drag edge. It is 8px of grab area over a 1px seam, it
+ * takes focus, and the arrow keys resize by the same amounts the drag does, so
+ * the width is not a mouse-only setting.
+ */
+.applet-panel-handle {
+  position: absolute;
+  z-index: 16;
+  top: 0;
+  bottom: 0;
+  left: -4px;
+  width: 8px;
+  border: 0;
+  padding: 0;
+  background: transparent;
+  cursor: col-resize;
+  touch-action: none;
+}
+
+.applet-panel-handle::after {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 3px;
+  width: 2px;
+  background: transparent;
+  content: "";
+  transition: background-color var(--frock-motion-fast);
+}
+
+.applet-panel-handle:hover::after,
+.applet-panel-handle:focus-visible::after {
+  background: var(--frock-action-primary);
+}
+
+.applet-panel-handle:focus-visible {
+  outline: 2px solid var(--frock-border-focus);
+  outline-offset: -2px;
+}
+
 .right-panel-header {
   display: flex;
   height: var(--frock-titlebar-height);
@@ -788,6 +890,11 @@
     width: var(--panel-surface-width);
   }
 
+  .app-shell.panel-applet .right-panel {
+    width: var(--applet-panel-width, 480px);
+    max-width: 100%;
+  }
+
   /*
    * A parked panel is hidden as well as off-canvas: it is not something to
    * tab into, read out, or hit-test, and `visibility` is the one property that
@@ -894,15 +1001,25 @@
 
   /* The right panel is a drawer too, and on a phone it takes the whole width. */
   .right-panel,
-  .app-shell.panel-surface .right-panel {
+  .app-shell.panel-surface .right-panel,
+  .app-shell.panel-applet .right-panel {
     width: 100%;
   }
 
   .right-panel-content,
+  .panel-applet .right-panel-content,
   .panel-surface-view {
     width: 100%;
   }
 
+  /*
+   * A focused Applet on a phone is a full-height sheet, not a wider column:
+   * there is one column, so the canvas is the whole of it while it is open.
+   */
+  .app-shell.panel-open.panel-applet {
+    --applet-panel-width: 100%;
+  }
+
   /* There is no window chrome to drag and no traffic lights to clear. */
   .brand {
     padding-left: 0;

package/src/composition-views.ts

@@ -39,7 +39,26 @@ export type CompositionMemberManifestReaderV1 = (
   member: CompositionMemberV1,
 ) => Promise<FrockBotManifest | undefined>;
 
-/** Project iframe Contributions from either Bot or Catalog provenance. */
+/** What the shell attributes an iframe page to, by where its code came from. */
+function iframeProvenanceV1(
+  member: CompositionMemberV1,
+): PackageIframeCompositionV1["contributions"][number]["provenance"] {
+  if (member.provenance.kind === "bot") return "Bot-authored";
+  if (member.provenance.kind === "first-party") return "FrockBot";
+  return "User-installed";
+}
+
+/**
+ * Project iframe Contributions from every artifact-backed member.
+ *
+ * The test is the artifact, not the provenance. "Every Contribution kind is
+ * resolved from the manifest and an artifact, never from a switch over Package
+ * identity" — a first-party Package that ships as an artifact-backed member
+ * (ADR 0022 decision 8) has a manifest the Bot object holds and pages the
+ * anonymous origin can serve, so there is nothing left for a provenance test
+ * to decide. A first-party member with no artifact is in-process code whose
+ * client Contribution is a compiled module, and it has no iframe page to show.
+ */
 export async function projectPackageIframeCompositionV1(input: {
   botId: string;
   generation: CompositionGenerationV1;
@@ -47,7 +66,7 @@ export async function projectPackageIframeCompositionV1(input: {
 }): Promise<PackageIframeCompositionV1> {
   const contributions: PackageIframeCompositionV1["contributions"] = [];
   for (const member of input.generation.members) {
-    if (member.provenance.kind === "first-party") continue;
+    if (member.artifact === undefined) continue;
     const manifest = await input.readMemberManifest(member);
     if (!manifest) continue;
     const client = manifest.contributions.client;
@@ -55,10 +74,16 @@ export async function projectPackageIframeCompositionV1(input: {
     contributions.push({
       packageId: member.packageId,
       displayName: manifest.displayName,
-      provenance:
-        member.provenance.kind === "bot" ? "Bot-authored" : "User-installed",
-      artifact: { ...client.artifact },
-      mounts: client.mounts.map((mount) => ({ ...mount })),
+      provenance: iframeProvenanceV1(member),
+      pages: client.pages.map((page) => ({
+        id: page.id,
+        artifact: { ...page.artifact },
+        mounts: page.mounts.map((mount) => ({ ...mount })),
+      })),
+      entries: (client.entries ?? []).map((entry) => ({
+        ...entry,
+        opens: { ...entry.opens },
+      })),
       declaredTools: (manifest.tools ?? []).map((tool) => tool.name),
     });
   }

package/src/run-protocol.test.ts

@@ -416,6 +416,46 @@ describe("client run protocol v1", () => {
       }),
     ).toThrow("turn command.schemaVersion is invalid");
 
+    // Supersede intent is carried by the field's presence. The composer sends
+    // it on every send, and names a run only when it observed one.
+    expect(
+      decodeClientTurnCommandV1({
+        schemaVersion: 1,
+        commandId: "command-1",
+        text: "hello",
+        supersedes: {},
+      }),
+    ).toEqual({
+      schemaVersion: 1,
+      commandId: "command-1",
+      text: "hello",
+      supersedes: {},
+    });
+    expect(
+      decodeClientTurnCommandV1({
+        schemaVersion: 1,
+        commandId: "command-1",
+        text: "hello",
+        supersedes: { runId: "run-1" },
+      }).supersedes,
+    ).toEqual({ runId: "run-1" });
+    expect(() =>
+      decodeClientTurnCommandV1({
+        schemaVersion: 1,
+        commandId: "command-1",
+        text: "hello",
+        supersedes: { runId: "not a run id" },
+      }),
+    ).toThrow("turn command.supersedes.runId is invalid");
+    expect(() =>
+      decodeClientTurnCommandV1({
+        schemaVersion: 1,
+        commandId: "command-1",
+        text: "hello",
+        supersedes: { runId: "run-1", extra: 1 },
+      }),
+    ).toThrow();
+
     expect(
       decodeClientNotificationAcknowledgementCommandV1({
         schemaVersion: 1,
@@ -571,6 +611,58 @@ describe("client run protocol v1", () => {
     }
   });
 
+  test("projects dynamic call identity so the client can show the inner tool", () => {
+    const projected = projectClientTurnV1({
+      runId: "run-dynamic-tool",
+      text: "",
+      events: [
+        event({
+          type: "tool/call",
+          seq: 0,
+          timestamp,
+          turn: 1,
+          step: 1,
+          occurrenceId: "tool:1:1:0",
+          name: "call_dynamic_tool",
+          input: {
+            namespace: "user-Github--acme",
+            toolName: "search_issues",
+            arguments: { query: "is:open" },
+            mcpDetails: { description: "Find open issues." },
+          },
+        }),
+        event({
+          type: "tool/result",
+          seq: 1,
+          timestamp,
+          turn: 1,
+          step: 1,
+          occurrenceId: "tool:1:1:0",
+          name: "call_dynamic_tool",
+          content: "[]",
+          isError: false,
+          status: "completed",
+        }),
+      ],
+    });
+
+    expect(projected.events[0]).toEqual({
+      type: "tool/call",
+      call: {
+        id: "tool-1",
+        name: "call_dynamic_tool",
+        input: {
+          namespace: "user-Github--acme",
+          toolName: "search_issues",
+          argumentsJson: '{"query":"is:open"}',
+        },
+      },
+    });
+    expect(decodeClientTurnV1(structuredClone(projected)).events[0]).toEqual(
+      projected.events[0],
+    );
+  });
+
   test("projects only bounded user-visible run state", () => {
     const stored = {
       runId: "run-1",