@frockbot/plugin-shell 0.3.1 → 0.3.2

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]);
+  });
+});

package/src/client/applets-client.ts

@@ -0,0 +1,139 @@
+/**
+ * The client half of the Applet routes.
+ *
+ * The backend is the authority for every one of these reads; this module is
+ * only the typed seam between the hosted transport and the shell's projection,
+ * so a route that is absent from a deployment reads as "no Applets" rather
+ * than as an error over the User's conversation. Every response crosses a
+ * strict decoder before it reaches the shell.
+ */
+import {
+  decodeAppletBuildViewV1,
+  decodeAppletFocusViewV1,
+  decodeAppletListViewV1,
+  decodeAppletSourceViewV1,
+  decodeAppletUiViewV1,
+  decodeAppletViewerTokenV1,
+  type AppletBuildViewV1,
+  type AppletSourceViewV1,
+  type AppletSummaryV1,
+  type AppletUiViewV1,
+  type AppletViewerTokenV1,
+} from "@frockbot/kernel-contracts";
+
+/** Exactly what the shell's hosted transport offers, and nothing more. */
+export type AppletsHostedRequest = (
+  path: string,
+  method?: "GET" | "POST",
+  body?: string,
+) => Promise<unknown>;
+
+const applet = (appletId: string) => encodeURIComponent(appletId);
+
+export async function readAppletList(
+  request: AppletsHostedRequest,
+): Promise<AppletSummaryV1[]> {
+  return decodeAppletListViewV1(await request("/api/applets")).applets;
+}
+
+export async function readAppletViewerToken(
+  request: AppletsHostedRequest,
+  appletId: string,
+): Promise<AppletViewerTokenV1> {
+  return decodeAppletViewerTokenV1(
+    await request(`/api/applets/${applet(appletId)}/token`),
+  );
+}
+
+export async function readAppletUi(
+  request: AppletsHostedRequest,
+  appletId: string,
+): Promise<AppletUiViewV1> {
+  return decodeAppletUiViewV1(
+    await request(`/api/applets/${applet(appletId)}/ui`),
+  );
+}
+
+/*
+ * The canvas's two Workspace-backed reads are Bot-scoped in the URL and
+ * User-scoped in what they answer: the Applets root belongs to the User, and
+ * the Bot in the path only names the Durable Object that holds the Workspace
+ * binding. Reading them wakes no Computer.
+ */
+export async function readAppletSource(
+  request: AppletsHostedRequest,
+  botId: string,
+  appletId: string,
+): Promise<AppletSourceViewV1> {
+  return decodeAppletSourceViewV1(
+    await request(
+      `/api/bots/${encodeURIComponent(botId)}/applets/${applet(appletId)}/source`,
+    ),
+  );
+}
+
+export async function readAppletBuild(
+  request: AppletsHostedRequest,
+  botId: string,
+  appletId: string,
+): Promise<AppletBuildViewV1> {
+  return decodeAppletBuildViewV1(
+    await request(
+      `/api/bots/${encodeURIComponent(botId)}/applets/${applet(appletId)}/build`,
+    ),
+  );
+}
+
+export async function readFocusedAppletId(
+  request: AppletsHostedRequest,
+  botId: string,
+): Promise<string | null> {
+  return decodeAppletFocusViewV1(
+    await request(`/api/bots/${encodeURIComponent(botId)}/applets/focus`),
+  ).appletId;
+}
+
+/**
+ * Records the Session's focused Applet and returns what the backend recorded,
+ * never what the click asked for: a focus the backend refused reads back as
+ * the focus it kept.
+ */
+export async function writeFocusedAppletId(
+  request: AppletsHostedRequest,
+  botId: string,
+  appletId: string | null,
+): Promise<string | null> {
+  return decodeAppletFocusViewV1(
+    await request(
+      `/api/bots/${encodeURIComponent(botId)}/applets/focus`,
+      "POST",
+      JSON.stringify({ schemaVersion: 1, appletId }),
+    ),
+  ).appletId;
+}
+
+/**
+ * The file the canvas shows while a Bot is writing an Applet: the one that
+ * changed most recently, falling back to the first path in sorted order so a
+ * store with no timestamps still opens on something.
+ */
+export function mostRecentlyChangedFileV1(
+  source: AppletSourceViewV1 | undefined,
+): string | undefined {
+  if (!source || source.files.length === 0) return undefined;
+  // A tie on time — a fresh scaffold, one sync — opens on the file a Bot edits
+  // first, not on the README the alphabet would pick.
+  const preferred = ["server.ts", "ui.tsx"];
+  const ordered = source.files.toSorted((left, right) => {
+    const leftAt = left.changedAt ?? "";
+    const rightAt = right.changedAt ?? "";
+    if (leftAt !== rightAt) return rightAt.localeCompare(leftAt);
+    const leftRank = preferred.indexOf(left.path);
+    const rightRank = preferred.indexOf(right.path);
+    const rank = (value: number) => (value < 0 ? preferred.length : value);
+    return (
+      rank(leftRank) - rank(rightRank) || left.path.localeCompare(right.path)
+    );
+  });
+  return ordered[0]?.path;
+}

package/src/client/applets-state.ts

@@ -0,0 +1,64 @@
+/**
+ * The `applets` feed a bridge v2 page receives.
+ *
+ * This is a projection of what the shell has already read, never a second
+ * source of truth: the backend is the authority for the list, the focus, and
+ * the viewer credential, and a page that is handed a stale generation simply
+ * reconnects when the next feed arrives.
+ */
+import {
+  PACKAGE_IFRAME_FOCUS_TOOL_V2,
+  type PackageIframeAppletsStateV2,
+  type PackageIframeCatalogV1,
+  type AppletSummaryV1,
+} from "@frockbot/kernel-contracts";
+import type { FrockBotWebData } from "../shared.js";
+
+/**
+ * Whether this Bot's Composition has Applets in it at all.
+ *
+ * Derived from manifest facts — a Package declaring the Applet focus tool —
+ * never from a Package id. A deployment or a User without the Applets Package
+ * has no Applet routes, and the shell must not ask for them: an absent
+ * capability is silence, not a failed request.
+ */
+export function appletsAvailableV1(
+  catalog: PackageIframeCatalogV1 | undefined,
+): boolean {
+  return (catalog?.contributions ?? []).some((contribution) =>
+    contribution.declaredTools.includes(PACKAGE_IFRAME_FOCUS_TOOL_V2),
+  );
+}
+
+export function focusedAppletSummaryV1(
+  web: Pick<FrockBotWebData, "applets" | "focusedAppletId">,
+): AppletSummaryV1 | null {
+  const appletId = web.focusedAppletId;
+  if (!appletId) return null;
+  return web.applets.find((applet) => applet.appletId === appletId) ?? null;
+}
+
+export function appletsBridgeStateV2(
+  web: Pick<
+    FrockBotWebData,
+    "applets" | "focusedAppletId" | "appletViewer" | "appletBuild"
+  >,
+): PackageIframeAppletsStateV2 {
+  const viewer = web.appletViewer;
+  return {
+    focused: focusedAppletSummaryV1(web),
+    list: web.applets,
+    viewer:
+      viewer && viewer.appletId === web.focusedAppletId
+        ? {
+            token: viewer.token,
+            socketUrl: viewer.socketUrl,
+            uiUrl: viewer.uiUrl,
+            generationId: viewer.generationId,
+          }
+        : null,
+    // The source stays out of the feed: the shell draws the code view itself,
+    // and a source tree would overflow the bridge's 64 KB message bound.
+    ...(web.appletBuild === undefined ? {} : { build: web.appletBuild }),
+  };
+}

package/src/client/index.test.ts

@@ -408,13 +408,19 @@ describe("Bot selection", () => {
       packageId: "weather-page",
       displayName: "Sydney Weather",
       provenance: "Bot-authored" as const,
-      artifact: {
-        contentHash: "a".repeat(64),
-        size: 1,
-        mediaType: "text/html" as const,
-        bundlerVersion: "frockbot-inline-html@1",
-      },
-      mounts: [{ slot: "frockbot.bot-settings-sections", order: 20 }],
+      pages: [
+        {
+          id: "main",
+          artifact: {
+            contentHash: "a".repeat(64),
+            size: 1,
+            mediaType: "text/html" as const,
+            bundlerVersion: "frockbot-inline-html@1",
+          },
+          mounts: [{ slot: "frockbot.bot-settings-sections", order: 20 }],
+        },
+      ],
+      entries: [],
       declaredTools: ["weather_lookup"],
     };
     const requests: Array<{