feat(runtime): popcraft.setPanelIcon for a plugin's sidebar panel icon

src/runtime/main.ts

@@ -5,7 +5,7 @@
 import { createRpcClient, type RpcClient } from './rpc.js'
 import type {
   PopCraftEvents, PopCraftExportOptions, PopCraftFindQuery, PopCraftNode, PopCraftNodeType,
-  PopCraftPage, PopCraftPaint, PopCraftShowUIOptions, PopCraftUploadOptions, PopCraftUploadResult,
+  PopCraftPage, PopCraftPaint, PopCraftPanelIconOptions, PopCraftShowUIOptions, PopCraftUploadOptions, PopCraftUploadResult,
   PopCraftVariables,
 } from '../types.js'
 import type {
@@ -301,6 +301,11 @@ export function createMainApi(rpc: RpcClient = createRpcClient()) {
 
     showUI: (options?: PopCraftShowUIOptions) => rpc.call<void>('showUI', options || {}),
     hideUI: () => rpc.call<void>('hideUI'),
+    /**
+     * Change the rail icon of one of this plugin's panels while it runs, e.g. to show a connection's state. Reset when
+     * the plugin stops.
+     */
+    setPanelIcon: (options: PopCraftPanelIconOptions) => rpc.call<void>('setPanelIcon', options || {}),
     /** Ends the run. The optional message is shown as a notification. */
     closePlugin: (message?: string) => rpc.call<void>('closePlugin', { message }),
 

src/types.ts

@@ -179,6 +179,16 @@ export interface PopCraftShowUIOptions {
   visible?: boolean
 }
 
+/** `popcraft.setPanelIcon`: the rail icon of one of the plugin's sidebar panels (`contributes.panels`). */
+export interface PopCraftPanelIconOptions {
+  /** The panel's id; defaults to the plugin's first panel. */
+  panel?: string
+  /** A `data:image/svg+xml`, png or webp URL (at most 64 KB). Omit or pass null to go back to the manifest icon. */
+  icon?: string | null
+  /** Draw the image in its own colours. Default false: its shape is filled with the rail's text colour, like the built-in icons. */
+  color?: boolean
+}
+
 /** Events a plugin can subscribe to with `popcraft.on`. */
 export interface PopCraftEvents {
   selectionchange: { ids: string[] }