repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

Add ui widget lifecycle state

52da921d9206485afb5591dc4f6a07b70f4c7403

Oliver Krylow <o.krylow@isp-insoft.de> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

extensions/ui/__tests__/widget-state.test.ts

Added
new file mode 100644
1 +import { describe, expect, it } from "vitest";
2 +import { WidgetStore } from "../widget-state";
4 +describe("ui widget state", () => {
5 + it("creates stable widget ids from tool call ids", () => {
6 + const store = new WidgetStore({ now: () => 100 });
7 + const first = store.mount({
8 + toolCallId: "call-1",
9 + title: "Card",
10 + fallback: "fallback",
11 + html: "<p>hi</p>",
12 + });
13 + const second = store.mount({
14 + toolCallId: "call-1",
15 + title: "Card",
16 + fallback: "fallback",
17 + html: "<p>hi</p>",
18 + });
20 + expect(first.widgetId).toBe("widget-call-1");
21 + expect(second.widgetId).toBe(first.widgetId);
22 + expect(store.get(first.widgetId)?.status).toBe("mounted");
23 + });
25 + it("records mount update action and error lifecycle", () => {
26 + const store = new WidgetStore({ now: () => 200 });
27 + const mount = store.mount({
28 + toolCallId: "call-2",
29 + title: "Form",
30 + fallback: "fallback",
31 + html: "<button>go</button>",
32 + });
33 + const update = store.update(mount.widgetId, { html: "<button>stop</button>" });
34 + const action = store.action(mount.widgetId, {
35 + toolCallId: "call-2",
36 + label: "Approve",
37 + payload: { ok: true },
38 + });
39 + const error = store.error(mount.widgetId, "boom");
41 + expect(update).toMatchObject({ type: "widget_update", widgetId: mount.widgetId });
42 + expect(action).toMatchObject({
43 + type: "widget_action",
44 + widgetId: mount.widgetId,
45 + toolCallId: "call-2",
46 + label: "Approve",
47 + actionId: "action-1",
48 + at: 200,
49 + });
50 + expect(error).toMatchObject({
51 + type: "widget_error",
52 + widgetId: mount.widgetId,
53 + message: "boom",
54 + });
55 + expect(store.get(mount.widgetId)?.audit).toHaveLength(4);
56 + });
57 +});

extensions/ui/protocol.ts

Modified
73 73 [key: string]: unknown;
76 +export type UiWidgetEvent = UiEventBase & {
77 + type: "widget_mount" | "widget_update" | "widget_action" | "widget_error";
78 + widgetId: string;
79 + toolCallId?: string;
80 + title?: string;
81 + fallback?: string;
82 + html?: string;
83 + status?: "mounted" | "updated" | "action" | "error";
84 + actionId?: string;
85 + label?: string;
86 + payload?: unknown;
87 + message?: string;
88 +};
76 90 export type UiEvent =
77 91 | UiStateEvent
78 92 | UiLogEvent
81 95 | UiErrorEvent
82 96 | UiRequestEvent
83 97 | UiNotifyEvent
84 - | UiStatusEvent;
98 + | UiStatusEvent
99 + | UiWidgetEvent;
86 101 export type UiEventInput = Omit<UiEvent, keyof UiEventBase>;

extensions/ui/widget-state.ts

Added
new file mode 100644
1 +import type { UiWidgetEvent } from "./protocol";
3 +export type WidgetRecord = {
4 + widgetId: string;
5 + toolCallId: string;
6 + title: string;
7 + fallback: string;
8 + html: string;
9 + status: "mounted" | "updated" | "action" | "error";
10 + audit: UiWidgetEvent[];
11 +};
13 +export type WidgetStoreOptions = {
14 + now?: () => number;
15 +};
17 +export type MountWidgetInput = {
18 + toolCallId: string;
19 + title: string;
20 + fallback: string;
21 + html: string;
22 +};
24 +export type WidgetActionInput = {
25 + toolCallId: string;
26 + label: string;
27 + payload?: unknown;
28 +};
30 +export class WidgetStore {
31 + readonly #now: () => number;
32 + #actions = 0;
33 + #widgets = new Map<string, WidgetRecord>();
35 + constructor(options: WidgetStoreOptions = {}) {
36 + this.#now = options.now ?? Date.now;
37 + }
39 + mount(input: MountWidgetInput): UiWidgetEvent {
40 + const widgetId = widgetIdForToolCall(input.toolCallId);
41 + const event: UiWidgetEvent = {
42 + id: 0,
43 + at: this.#now(),
44 + type: "widget_mount",
45 + widgetId,
46 + toolCallId: input.toolCallId,
47 + title: input.title,
48 + fallback: input.fallback,
49 + html: input.html,
50 + status: "mounted",
51 + };
52 + this.#widgets.set(widgetId, {
53 + widgetId,
54 + toolCallId: input.toolCallId,
55 + title: input.title,
56 + fallback: input.fallback,
57 + html: input.html,
58 + status: "mounted",
59 + audit: [event],
60 + });
61 + return event;
62 + }
64 + update(widgetId: string, patch: { html: string }): UiWidgetEvent {
65 + const record = this.#require(widgetId);
66 + record.html = patch.html;
67 + record.status = "updated";
68 + return this.#audit(record, {
69 + type: "widget_update",
70 + widgetId,
71 + toolCallId: record.toolCallId,
72 + html: patch.html,
73 + status: "updated",
74 + });
75 + }
77 + action(widgetId: string, input: WidgetActionInput): UiWidgetEvent {
78 + const record = this.#require(widgetId);
79 + record.status = "action";
80 + return this.#audit(record, {
81 + type: "widget_action",
82 + widgetId,
83 + toolCallId: input.toolCallId,
84 + actionId: `action-${++this.#actions}`,
85 + label: input.label,
86 + payload: input.payload,
87 + status: "action",
88 + });
89 + }
91 + error(widgetId: string, message: string): UiWidgetEvent {
92 + const record = this.#require(widgetId);
93 + record.status = "error";
94 + return this.#audit(record, {
95 + type: "widget_error",
96 + widgetId,
97 + toolCallId: record.toolCallId,
98 + message,
99 + status: "error",
100 + });
103 + get(widgetId: string): WidgetRecord | undefined {
104 + return this.#widgets.get(widgetId);
107 + #audit(record: WidgetRecord, event: Omit<UiWidgetEvent, "id" | "at">): UiWidgetEvent {
108 + const full = { id: 0, at: this.#now(), ...event };
109 + record.audit.push(full);
110 + return full;
113 + #require(widgetId: string): WidgetRecord {
114 + const record = this.#widgets.get(widgetId);
115 + if (!record) throw new Error(`Unknown widget: ${widgetId}`);
116 + return record;
120 +export function widgetIdForToolCall(toolCallId: string): string {
121 + return `widget-${toolCallId.replaceAll(/[^a-zA-Z0-9_-]/g, "-")}`;