@frockbot/applet-sdk 0.7.40 → 0.7.41

package/README.md

@@ -44,7 +44,7 @@ which `applet_create` writes through the Workspace.
 
 A Plugin (ADR 0026) is written against `@frockbot/applet-sdk/plugin`, which
 is declarations only: `plugin.ts` exports `tools` and `execute`, and may
-export `hooks`, `services` and `triggers`, beside a `plugin.json` descriptor.
+export `hooks`, `services`, `triggers` and `views`, beside a `plugin.json` descriptor.
 `tools` may be empty — a Plugin that only serves hooks is admissible, because
 the kernel's own descriptor contract admits one.
 `runPluginBuildV1(directory, { mode, id })` is four stages — `descriptor`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.40",
+  "version": "0.7.41",
   "private": false,
   "type": "module",
   "description": "Authoring SDK for FrockBot Applets: schema-first Durable Object server, TanStack DB client, component kit, linter, and the build pipeline.",

package/plugin/index.d.ts

@@ -379,6 +379,56 @@ export type PluginTrigger = (
 /** Every trigger the module exports, by the name `plugin.json` declares. */
 export type PluginTriggers = Record<string, PluginTrigger>;
 
+/**
+ * One node of a section a Plugin renders on its card. The host draws it with
+ * its own widgets; a Plugin ships no markup. `field` and `embed` nodes are
+ * not accepted from a Plugin and are left out when the card is drawn.
+ */
+export type PluginViewNode =
+  | {
+      type: "text";
+      text: string;
+      style?: "body" | "heading" | "label" | "status";
+    }
+  | {
+      type: "group";
+      orientation: "row" | "column";
+      title?: string;
+      collapsed?: boolean;
+      children: PluginViewNode[];
+    }
+  | {
+      /**
+       * A control. `actionId` names one of this Plugin's tools; pressing it
+       * runs that tool with `input`, outside any Turn, and the section is
+       * rendered again.
+       */
+      type: "action";
+      actionId: string;
+      label: string;
+      style?: "primary" | "secondary" | "danger";
+      input?: { [key: string]: unknown };
+    }
+  | {
+      type: "list";
+      empty?: string;
+      rows: { id: string; node: PluginViewNode; selected?: boolean }[];
+    };
+
+/** What a view returns: the section's tree. Return nothing to show no section. */
+export interface PluginViewDocument {
+  root: PluginViewNode;
+}
+
+/** A view: renders one declared surface with the same `ctx` a tool call gets. */
+export type PluginView = (
+  ctx: PluginContext,
+) =>
+  | Promise<PluginViewDocument | undefined | void>
+  | PluginViewDocument
+  | undefined
+  | void;
+
 /**
  * A tool call's answer. A string is handed to the Bot as it is; anything else
  * is JSON-serialized. Throw to answer with an error the Bot can read — the
@@ -409,4 +459,9 @@ export interface PluginModule {
   /** Values other Plugins that `consume` a service of the same name receive. */
   services?: Record<string, unknown>;
   triggers?: PluginTriggers;
+  /**
+   * One view per surface id declared under `views` in `plugin.json`, each
+   * with slot `settings.sections`: a section drawn on this Plugin's card.
+   */
+  views?: Record<string, PluginView>;
 }

package/src/build/plugin.ts

@@ -51,6 +51,7 @@ export interface PluginDescriptionV1 {
   hooks: string[];
   services: string[];
   triggers: string[];
+  views: string[];
 }
 
 export interface PluginBuildManifestV1 extends PluginDescriptionV1 {
@@ -301,6 +302,7 @@ function describe() {
     hooks: names(plugin.hooks, "hooks"),
     services: names(plugin.services, "services"),
     triggers: names(plugin.triggers, "triggers"),
+    views: names(plugin.views, "views"),
   };
 }
 
@@ -393,6 +395,7 @@ function validateDescription(input: PluginDescriptionV1): PluginDescriptionV1 {
     hooks: [...input.hooks],
     services: [...input.services],
     triggers: [...input.triggers],
+    views: [...input.views],
   };
 }