fix(genui): swallow the closing stream_done event instead of materializing it

docs/genui/streaming.md

@@ -8,7 +8,7 @@ A connector advertises GenUI support by implementing `onGenUIChunk(callback)`. T
 type AIChunk =
   | { type: "text";  content: string;       id: number; }
   | { type: "ui";    component: string;     props: Record<string, unknown>; id: number; }
-  | { type: "event"; name: string;          payload: unknown; id: number; for?: number; };
+  | { type: "event"; name: string;          payload?: unknown; id: number; for?: number; };
 ```
 
 Schema: [`schemas/genui/ai-chunk.schema.json`](../../schemas/genui/ai-chunk.schema.json).

packages/core/src/application/ChatEngine.ts

@@ -262,6 +262,13 @@ export class ChatEngine {
   }
 
   private _handleGenUIChunk(streamId: string, chunk: AIChunk, done: boolean): void {
+    // The closing `stream_done` event (mekik PROTOCOL.md §4.1) is stream
+    // lifecycle, not content — materializing it would add a phantom empty
+    // message (a text-only stream has no genui host for it to live in).
+    if (chunk.type === "event" && chunk.name === "stream_done") {
+      if (done) this._finishStream(streamId);
+      return;
+    }
     const firstChunk = !this._streamHosts.has(streamId);
 
     // Text deltas render as a normal, growing bot bubble (default-text-message);

packages/core/src/application/__tests__/ChatEngine.test.ts

@@ -646,6 +646,34 @@ describe("ChatEngine", () => {
     expect(data.chunks[1].type).toBe("event");
   });
 
+  it("does not open a phantom bubble for the closing stream_done event of a text-only stream", async () => {
+    const connector = createMockConnector();
+    const engine = new ChatEngine(connector);
+    await engine.init();
+    connector.simulateGenUIChunk("s-done", { type: "text", content: "Hi", id: 1 }, false);
+    connector.simulateGenUIChunk("s-done", { type: "event", name: "stream_done", id: 2 }, true);
+    const msgs = messageStore.getState().messages;
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0].data.text).toBe("Hi");
+    expect(msgs[0].data.streaming).toBe(false);
+  });
+
+  it("does not append the closing stream_done event into a genui message", async () => {
+    const handler = vi.fn();
+    EventBus.on("genui_stream_completed", handler);
+    const connector = createMockConnector();
+    const engine = new ChatEngine(connector);
+    await engine.init();
+    connector.simulateGenUIChunk("s-done2", { type: "ui", component: "card", props: {}, id: 1 }, false);
+    connector.simulateGenUIChunk("s-done2", { type: "event", name: "stream_done", id: 2 }, true);
+    const msgs = messageStore.getState().messages;
+    expect(msgs).toHaveLength(1);
+    const data = msgs[0].data as { chunks: AIChunk[]; streamingComplete: boolean };
+    expect(data.chunks).toHaveLength(1);
+    expect(data.streamingComplete).toBe(true);
+    expect(handler).toHaveBeenCalledWith({ streamId: "s-done2" });
+  });
+
   // ── receiveComponentEvent ──────────────────────────────────────────
 
   it("routes component events to connector by stream id", async () => {

packages/core/src/domain/entities/GenUI.ts

@@ -32,8 +32,8 @@ export interface AIChunkEvent {
   type: "event";
   /** Event name (e.g. "form_success"). */
   name: string;
-  /** Arbitrary payload delivered to listeners. */
-  payload: unknown;
+  /** Arbitrary payload delivered to listeners. Omitted for signal-only events. */
+  payload?: unknown;
   /** Unique id of this chunk (for deduplication). */
   id: number;
   /**

website/docs/genui/streaming.md

@@ -14,7 +14,7 @@ A connector advertises GenUI support by implementing `onGenUIChunk(callback)`. T
 type AIChunk =
   | { type: "text";  content: string;       id: number; }
   | { type: "ui";    component: string;     props: Record<string, unknown>; id: number; }
-  | { type: "event"; name: string;          payload: unknown; id: number; for?: number; };
+  | { type: "event"; name: string;          payload?: unknown; id: number; for?: number; };
 ```
 
 Schema: [`schemas/genui/ai-chunk.schema.json`](https://github.com/AimTune/chativa/blob/main/schemas/genui/ai-chunk.schema.json).