@luzmo/analytics-components-kit 1.0.3-beta.7 → 1.0.3-beta.8

package/components/ai-chat/ai-chat-events.d.ts

@@ -0,0 +1,123 @@
+import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
+import type { AiSampleChart, ChatMessage } from '../../types';
+import type { AiPromptAgent, DashboardStatePayload } from './ai-prompt-types';
+/**
+ * Common fields present on every streamed step event, recognized or not.
+ */
+export interface AiChatStepBase {
+    /** The aiprompt agent that produced this step (`item`, `dashboard`, `analyst`). */
+    agent: AiPromptAgent;
+    /** Current conversation id, or `null` before the backend assigns one. */
+    conversationId: string | null;
+    /** Backend message id, when the chunk carries one. */
+    messageId?: string;
+    /** Always present — the original stream chunk that produced this step. */
+    raw: Record<string, unknown>;
+}
+/** Recognized stream-step type discriminants. */
+export type AiChatRecognizedStepType = 'decision' | 'text' | 'progress' | 'dashboard-title' | 'dashboard-layout' | 'dashboard-item' | 'chart' | 'interrupt';
+/**
+ * Stream steps assembled into a typed `data` payload.
+ * Discriminated by `type` (when `recognized` is `true`).
+ */
+export type RecognizedStepEvent = (AiChatStepBase & {
+    recognized: true;
+    type: 'decision';
+    data: {
+        decision: 'create' | 'edit' | 'question';
+    };
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'text';
+    data: {
+        delta: string;
+        text: string;
+    };
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'progress';
+    data: ProgressTreeNode;
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'dashboard-title';
+    data: {
+        name: Record<string, string>;
+    };
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'dashboard-layout';
+    data: DashboardStatePayload;
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'dashboard-item';
+    data: {
+        slot: number;
+        chart: Record<string, unknown>;
+    };
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'chart';
+    data: Record<string, unknown>;
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'interrupt';
+    data: {
+        question: string;
+    };
+});
+/**
+ * Stream steps not (yet) modeled. Still delivered so consumers never
+ * silently lose data; `data` is a best-effort payload (often identical to `raw`).
+ */
+export type UnknownStepEvent = AiChatStepBase & {
+    recognized: false;
+    /** Raw chunk `type` / `asset_type`. */
+    type: string;
+    /** Best-effort payload (often `=== raw`). */
+    data: unknown;
+};
+/**
+ * Open union of streamed step events. Use {@link isRecognizedStep} to narrow to
+ * the typed {@link RecognizedStepEvent} set; otherwise inspect `raw`.
+ */
+export type AiChatStepEvent = RecognizedStepEvent | UnknownStepEvent;
+/**
+ * Authoritative final result of a streamed response, fired exactly once.
+ */
+export interface AiChatCompleteEvent {
+    /** The aiprompt agent that produced this result. */
+    agent: AiPromptAgent;
+    /** Conversation id for this response. */
+    conversationId: string | null;
+    /** Final assistant message (text + flags). */
+    message: ChatMessage;
+    /** Authoritative dashboard payload (dashboard agent). */
+    dashboard?: DashboardStatePayload;
+    /** Authoritative chart payload (item agent). */
+    chart?: AiSampleChart;
+    /** Dashboard name keyed by locale (dashboard agent). */
+    name?: Record<string, string>;
+    /** Forward-compat: any final assets not modeled explicitly. */
+    assets?: Record<string, unknown>;
+    /** Present when the response failed. */
+    error?: unknown;
+    /** Original terminal chunk. */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Type guard separating the typed, recognized step set from the open passthrough.
+ * Lets consumers `switch` exhaustively on `event.type` with fully narrowed `data`.
+ *
+ * @example
+ * ```ts
+ * onStep: (event) => {
+ *   if (!isRecognizedStep(event)) return; // forward-compatible: ignore or use event.raw
+ *   switch (event.type) {
+ *     case 'decision':
+ *       // event.data.decision is typed
+ *       break;
+ *   }
+ * };
+ * ```
+ */
+export declare function isRecognizedStep(event: AiChatStepEvent): event is RecognizedStepEvent;

package/components/ai-chat/ai-chat.d.ts

@@ -17,11 +17,12 @@ import type { AiPromptAgent, AiPromptItemTask, AiPromptScreenMode, DashboardStat
  * session from auth, agent, and chart or dashboard props; optional messages and selected-datasets
  * seed it once on connect. Pass .chatSession for a host-owned session (e.g. dashboard editor).
  * See {@link AiChatSession} / createAiChatSession for callbacks and external fetchStreaming.
+ * @fires {CustomEvent<AiChatStepEvent>} luzmo-step - Fired for every incremental, kit-assembled event during a streamed response (decision, text, progress, dashboard-title/layout/item, chart, interrupt, plus forward-by-default unrecognized chunks). Use `isRecognizedStep` to narrow.
+ * @fires {CustomEvent<AiChatCompleteEvent>} luzmo-complete - Fired exactly once per response with the authoritative final result (dashboard/chart/name) or an `error`.
  * @fires luzmo-message-sent - Fired when a user sends a message
- * @fires luzmo-response-received - Fired when an AI text response is received. For chart responses, this event is only fired if the response includes a `message` field. For error responses, this event is always fired with the error explanation.
- * @fires luzmo-chart-generated - Fired when agent is `item` and a chart asset is ready
- * @fires luzmo-dashboard-generated - Fired when agent is `dashboard` and a dashboard asset is ready
+ * @fires luzmo-datasets-changed - Fired when the selected datasets change
  * @fires luzmo-conversation-id-changed - Fired when the conversation ID is updated from the API
+ * @fires luzmo-stop - Fired when an in-flight prompt is stopped
  *
  * @property {string} --luzmo-ai-chat-background - Background of the chat container
  * @property {string} --luzmo-ai-chat-border-radius - Border radius of the chat container
@@ -215,6 +216,7 @@ export declare class LuzmoAiChat extends LuzmoElement {
     private _handleDatasetRemoved;
     private _submitViaSession;
     private _handlePromptSubmitted;
+    private _handlePromptStopped;
     private _handleEmptyStateSuggestionSelected;
     private _processInitialPrompt;
     connectedCallback(): void;

package/components/ai-chat/ai-prompt-types.d.ts

@@ -79,6 +79,7 @@ export interface LuzmoPromptSubmittedEventDetail {
     agent: AiPromptAgent;
     request: AiPromptCreateBody;
     url: string;
+    signal?: AbortSignal;
 }
 export interface LuzmoRestoreRequestedEventDetail {
     apiMessageId: string;

package/components/ai-chat/index.cjs

@@ -17,4 +17,4 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  * */
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../ai-chat-BITPlYbm.cjs`);exports.AiChatSession=e.r,exports.AiChatSessionController=e.n,exports.LuzmoAiChat=e.t,exports.LuzmoAiChatEmptyState=e.x,exports.buildAiPromptDeleteRequest=e.p,exports.buildAiPromptProperties=e.m,exports.buildAiPromptRequest=e.h,exports.buildAnalystAiPromptProperties=e.g,exports.buildDashboardAiPromptProperties=e._,exports.buildItemAiPromptProperties=e.v,exports.chartToItemAsset=e.y,exports.createAiChatSession=e.i,exports.createInitialProgress=e.c,exports.createInitialStreamState=e.a,exports.createStreamHandler=e.o,exports.extractChartFromChunk=e.s,exports.fetchStreamingResponse=e.l,exports.getAiPromptUrl=e.b,exports.hasProgressChunk=e.u,exports.parseStreamLine=e.d,exports.readNdjsonStream=e.f;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../ai-chat-45RQcnbP.cjs`);exports.AiChatSession=e.i,exports.AiChatSessionController=e.r,exports.LuzmoAiChat=e.n,exports.LuzmoAiChatEmptyState=e.T,exports.buildAiPromptDeleteRequest=e._,exports.buildAiPromptProperties=e.v,exports.buildAiPromptRequest=e.y,exports.buildAnalystAiPromptProperties=e.b,exports.buildDashboardAiPromptProperties=e.x,exports.buildItemAiPromptProperties=e.S,exports.chartToItemAsset=e.C,exports.createAiChatSession=e.a,exports.createInitialProgress=e.f,exports.createInitialStreamState=e.o,exports.createStreamHandler=e.s,exports.extractChartFromChunk=e.u,exports.extractDashboardFromChunk=e.d,exports.fetchStreamingResponse=e.m,exports.getAgentStreamDefinition=e.c,exports.getAiPromptUrl=e.w,exports.hasProgressChunk=e.p,exports.isRecognizedStep=e.t,exports.parseStreamLine=e.h,exports.processStreamChunk=e.l,exports.readNdjsonStream=e.g;

package/components/ai-chat/index.d.ts

@@ -5,6 +5,8 @@ declare global {
     }
 }
 export type { ProgressTreeNode } from '../../types/ai-chat.types';
+export { isRecognizedStep } from './ai-chat-events';
+export type { AiChatCompleteEvent, AiChatRecognizedStepType, AiChatStepBase, AiChatStepEvent, RecognizedStepEvent, UnknownStepEvent } from './ai-chat-events';
 export { AiChatSession, AiChatSessionController, createAiChatSession } from './session';
 export type { AiChatSessionControllerOptions, AiChatSessionSeed } from './session/ai-chat-session-controller';
 export type { AiChatSessionBuildContext, AiChatSessionCallbacks, AiChatSessionConfig, AiChatSessionRestoreParams, AiChatSessionRestoreResult, AiChatSessionState, AiChatSessionSubmitParams, AiPromptCreateBody, AiPromptDeleteBody, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from './session/ai-chat-session-types';
@@ -13,6 +15,6 @@ export { LuzmoAiChatEmptyState } from './empty-state';
 export type { AiChatEmptyStateSuggestion, AiChatEmptyStateSuggestionSelectedDetail } from './empty-state';
 export * from './ai-prompt-types';
 export * from './ai-chat-request';
-export { createInitialProgress, createInitialStreamState, createStreamHandler, extractChartFromChunk, fetchStreamingResponse, hasProgressChunk, parseStreamLine, readNdjsonStream } from './stream';
-export type { StreamingRequestOptions, StreamingResponse } from './stream/ai-chat-streaming';
-export type { StreamHandlerCallbacks, StreamHandlerContext } from './stream';
+export { createInitialProgress, createInitialStreamState, createStreamHandler, extractChartFromChunk, extractDashboardFromChunk, fetchStreamingResponse, getAgentStreamDefinition, hasProgressChunk, parseStreamLine, processStreamChunk, readNdjsonStream } from './stream';
+export type { StreamingRequestOptions, StreamingResponse } from './stream/transport';
+export type { AgentStreamDefinition, StreamHandlerCallbacks, StreamHandlerContext, StreamHandlerState } from './stream';

package/components/ai-chat/index.js

@@ -24,5 +24,5 @@
 		e.setAttribute("data-luzmo-vars", ""), e.textContent = "html{--luzmo-animation-duration: 0.15s;--luzmo-border-color: rgba(var(--luzmo-border-color-rgb), 0.1);--luzmo-border-color-hover: rgba(var(--luzmo-border-color-rgb), 0.15);--luzmo-border-color-down: rgba(var(--luzmo-border-color-rgb), 0.3);--luzmo-border-color-focus: rgba(var(--luzmo-border-color-rgb), 0.15);--luzmo-border-color-rgb: 0, 0, 0;--luzmo-border-color-full: rgb(180, 180, 180);--luzmo-border-color-full-hover: rgb(140, 140, 140);--luzmo-border-color-full-down: rgb(110, 110, 110);--luzmo-border-color-full-focus: rgb(140, 140, 140);--luzmo-border-color-disabled: #dddddd;--luzmo-border-radius: 6px;--luzmo-border-radius-s: 4px;--luzmo-border-radius-l: 8px;--luzmo-border-radius-xl: 12px;--luzmo-border-radius-full: 999rem;--luzmo-background-color: #ffffff;--luzmo-background-color-rgb: 255, 255, 255;--luzmo-background-color-disabled: #eeeeee;--luzmo-background-color-hover: #f0f0fc;--luzmo-background-color-down: #f1f1ff;--luzmo-background-color-focus: #f0f0fc;--luzmo-background-color-highlight: rgb(240, 240, 240);--luzmo-background-color-highlight-disabled: rgb(245, 245, 245);--luzmo-background-color-highlight-hover: rgb(225, 225, 225);--luzmo-background-color-highlight-down: rgb(215, 215, 215);--luzmo-background-color-highlight-focus: rgb(225, 225, 225);--luzmo-background-color-alt-1: rgb(250, 250, 250);--luzmo-background-color-alt-2: rgb(239, 239, 239);--luzmo-border-width: 1px;--luzmo-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', Helvetica, Arial, sans-serif;--luzmo-font-size-xs: 10px;--luzmo-font-size-s: 12px;--luzmo-font-size-m: 14px;--luzmo-font-size: 14px;--luzmo-font-size-l: 16px;--luzmo-font-size-xl: 18px;--luzmo-font-size-xxl: 20px;--luzmo-font-style: normal;--luzmo-line-height: normal;--luzmo-font-weight: 400;--luzmo-font-weight-semibold: 500;--luzmo-font-weight-bold: 600;--luzmo-font-color: #333;--luzmo-font-color-hard: #000;--luzmo-font-color-disabled: var(--luzmo-color-disabled);--luzmo-font-color-extra-dimmed: #888;--luzmo-font-color-hover: #333;--luzmo-font-color-down: #111;--luzmo-font-color-focus: #333;--luzmo-scrollbar-size: 6px;--luzmo-scrollbar-width: thin;--luzmo-scrollbar-track-background: transparent;--luzmo-scrollbar-track-border-radius: var(--luzmo-border-radius-s);--luzmo-scrollbar-thumb-background: rgba(var(--luzmo-border-color-rgb), 0.3);--luzmo-scrollbar-thumb-border-radius: var(--luzmo-border-radius-s);--luzmo-scrollbar-thumb-hover-background: rgba(var(--luzmo-border-color-rgb), 0.4);--luzmo-primary: #4434ff;--luzmo-primary-hover: #4234e4;--luzmo-primary-down: #392cc7;--luzmo-primary-focus: #4234e4;--luzmo-primary-inverse-color: #ffffff;--luzmo-primary-rgb: 68, 52, 255;--luzmo-secondary: #ff00ff;--luzmo-secondary-hover: #e309e3;--luzmo-secondary-down: #c711c7;--luzmo-secondary-focus: #e309e3;--luzmo-secondary-inverse-color: #ffffff;--luzmo-secondary-rgb: 255, 0, 255;--luzmo-secondary-outline: rgba(255, 0, 255, 0.2);--luzmo-negative-color: #ca221c;--luzmo-negative-color-hover: #b3241f;--luzmo-negative-color-down: #9f231f;--luzmo-negative-color-focus: #b3241f;--luzmo-negative-color-rgb: 202, 34, 28;--luzmo-positive-color: rgb(20, 150, 101);--luzmo-positive-color-hover: rgb(17, 128, 86);--luzmo-positive-color-down: rgb(16, 105, 71);--luzmo-positive-color-focus: rgb(17, 128, 86);--luzmo-positive-color-rgb: 20, 150, 101;--luzmo-selected-color: rgb(110, 110, 110);--luzmo-selected-color-hover: rgb(70, 70, 70);--luzmo-selected-color-down: rgb(40, 40, 40);--luzmo-selected-color-focus: rgb(70, 70, 70);--luzmo-selected-color-hard: #1e1e1e;--luzmo-selected-color-hard-hover: rgb(0, 0, 0);--luzmo-selected-color-hard-down: rgb(0, 0, 0);--luzmo-selected-color-hard-focus: rgb(0, 0, 0);--luzmo-color-informative: #1a77e9;--luzmo-color-informative-rgb: 26, 119, 233;--luzmo-color-disabled: #aaaaaa;--luzmo-spacing-1: 2px;--luzmo-spacing-2: 4px;--luzmo-spacing-3: 8px;--luzmo-spacing-4: 12px;--luzmo-spacing-5: 16px;--luzmo-indicator-gap: 2px;--luzmo-indicator-width: 1px;--luzmo-indicator-color: var(--luzmo-primary);--luzmo-component-height-xxs: 20px;--luzmo-component-height-xs: 24px;--luzmo-component-height-s: 28px;--luzmo-component-height: 32px;--luzmo-component-height-l: 40px;--luzmo-component-height-xl: 48px;--luzmo-component-height-xxl: 64px;--luzmo-icon-size-xxs: 12px;--luzmo-icon-size-xs: 14px;--luzmo-icon-size-s: 16px;--luzmo-icon-size-m: 18px;--luzmo-icon-size-l: 20px;--luzmo-icon-size-xl: 22px;--luzmo-icon-size-xxl: 32px}", document.head.appendChild(e);
 	}
 })();
-import { _ as e, a as t, b as n, c as r, d as i, f as a, g as o, h as s, i as c, l, m as u, n as d, o as f, p, r as m, s as h, t as g, u as _, v, x as y, y as b } from "../ai-chat-D6fgbjA2.js";
-export { m as AiChatSession, d as AiChatSessionController, g as LuzmoAiChat, y as LuzmoAiChatEmptyState, p as buildAiPromptDeleteRequest, u as buildAiPromptProperties, s as buildAiPromptRequest, o as buildAnalystAiPromptProperties, e as buildDashboardAiPromptProperties, v as buildItemAiPromptProperties, b as chartToItemAsset, c as createAiChatSession, r as createInitialProgress, t as createInitialStreamState, f as createStreamHandler, h as extractChartFromChunk, l as fetchStreamingResponse, n as getAiPromptUrl, _ as hasProgressChunk, i as parseStreamLine, a as readNdjsonStream };
+import { C as e, S as t, T as n, _ as r, a as i, b as a, c as o, d as s, f as c, g as l, h as u, i as d, l as f, m as p, n as m, o as h, p as g, r as _, s as v, t as y, u as b, v as x, w as S, x as C, y as w } from "../ai-chat-07oftyCS.js";
+export { d as AiChatSession, _ as AiChatSessionController, m as LuzmoAiChat, n as LuzmoAiChatEmptyState, r as buildAiPromptDeleteRequest, x as buildAiPromptProperties, w as buildAiPromptRequest, a as buildAnalystAiPromptProperties, C as buildDashboardAiPromptProperties, t as buildItemAiPromptProperties, e as chartToItemAsset, i as createAiChatSession, c as createInitialProgress, h as createInitialStreamState, v as createStreamHandler, b as extractChartFromChunk, s as extractDashboardFromChunk, p as fetchStreamingResponse, o as getAgentStreamDefinition, S as getAiPromptUrl, g as hasProgressChunk, y as isRecognizedStep, u as parseStreamLine, f as processStreamChunk, l as readNdjsonStream };

package/components/ai-chat/session/ai-chat-session-types.d.ts

@@ -1,7 +1,8 @@
 import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
 import type { AiSampleChart, ChatMessage, Dataset, LuzmoChart } from '../../../types';
-import type { AiPromptAgent, AiPromptCreateBody, AiPromptDeleteBody, AiPromptItemTask, AiPromptScreenMode, BuildAiPromptRequestContext, DashboardStatePayload, LuzmoDashboardGeneratedEventDetail, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from '../ai-prompt-types';
-import type { StreamingRequestOptions, StreamingResponse } from '../stream/ai-chat-streaming';
+import type { AiChatCompleteEvent, AiChatStepEvent } from '../ai-chat-events';
+import type { AiPromptAgent, AiPromptCreateBody, AiPromptDeleteBody, AiPromptItemTask, AiPromptScreenMode, BuildAiPromptRequestContext, DashboardStatePayload, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from '../ai-prompt-types';
+import type { StreamingRequestOptions, StreamingResponse } from '../stream/transport';
 export interface AiChatSessionConfig {
     agent: AiPromptAgent;
     authKey: string;
@@ -30,7 +31,7 @@ export interface AiChatSessionConfig {
     /** Initial progress collapsed flag. */
     progressCollapsed?: boolean;
     /**
-     * Custom streaming HTTP client. Defaults to the kit's {@link fetchStreamingResponse}.
+     * Custom streaming HTTP client. Defaults to the built-in {@link fetchStreamingResponse}.
      * Use for proxies, mocks, or alternate auth transport while keeping session state handling.
      */
     fetchStreaming?: (options: StreamingRequestOptions) => Promise<StreamingResponse>;
@@ -48,22 +49,23 @@ export interface AiChatSessionState {
 export interface AiChatSessionCallbacks {
     onStateChange?: (state: AiChatSessionState) => void;
     onConversationIdChange?: (conversationId: string) => void;
-    onChartGenerated?: (detail: AiSampleChart) => void;
-    onDashboardGenerated?: (detail: LuzmoDashboardGeneratedEventDetail) => void;
-    onResponseReceived?: (message: ChatMessage, done: boolean, error?: unknown) => void;
+    /** Fired for every incremental, kit-assembled event during a streamed response. */
+    onStep?: (event: AiChatStepEvent) => void;
+    /** Fired exactly once per response with the authoritative final result (or error). */
+    onComplete?: (event: AiChatCompleteEvent) => void;
     onMessageSent?: (message: ChatMessage, selectedDatasets: Dataset[]) => void;
     onDatasetsChanged?: (selectedDatasets: Dataset[]) => void;
     /**
      * Host-owned submit: session updates transcript and loading state, then invokes this
-     * with the same payload shape as the former `luzmo-prompt-submitted` event. No built-in fetch.
+     * with the same payload shape as the former `luzmo-prompt-submitted` event plus an abort signal. No built-in fetch.
      */
     onPromptSubmitted?: (detail: LuzmoPromptSubmittedEventDetail) => void | Promise<void>;
+    /** Host-owned cleanup hook invoked for user-initiated prompt stops. */
+    onPromptStopped?: () => void | Promise<void>;
     /**
      * Host-owned restore (item agent): session invokes this with delete request + URL; no built-in fetch.
      */
     onRestoreRequested?: (detail: LuzmoRestoreRequestedEventDetail) => void | Promise<void>;
-    /** @deprecated Use `onResponseReceived` with the optional `error` argument. */
-    onError?: (error: unknown, message: ChatMessage) => void;
 }
 export interface AiChatSessionSubmitParams {
     prompt: string;

package/components/ai-chat/session/ai-chat-session.d.ts

@@ -11,7 +11,9 @@ import type { AiChatSessionCallbacks, AiChatSessionConfig, AiChatSessionRestoreP
  * const session = createAiChatSession(
  *   { agent: 'dashboard', authKey, authToken, dashboard, currentScreenMode },
  *   {
- *     onDashboardGenerated: (d) => applyToEditor(d),
+ *     onComplete: (e) => {
+ *       if (e.dashboard) applyToEditor(e.dashboard, e.name);
+ *     },
  *     onStateChange: (s) => persistConversation(s.messages),
  *   }
  * );
@@ -53,7 +55,7 @@ export declare class AiChatSession {
     getAiPromptUrl(): string;
     buildRequestBody(prompt: string, datasetIds: string[]): AiPromptCreateBody;
     /** Same payload passed to {@link AiChatSessionCallbacks.onPromptSubmitted}. */
-    buildPromptSubmittedDetail(prompt: string, selectedDatasets: Dataset[], datasetIds: string[]): LuzmoPromptSubmittedEventDetail;
+    buildPromptSubmittedDetail(prompt: string, selectedDatasets: Dataset[], datasetIds: string[], signal?: AbortSignal): LuzmoPromptSubmittedEventDetail;
     /**
      * Append the user prompt (unless `skipUserMessage`), start streaming, and update {@link state}.
      */
@@ -61,15 +63,17 @@ export declare class AiChatSession {
     /** Item agent only — restore conversation to a prior API message. */
     restore(params: AiChatSessionRestoreParams): Promise<AiChatSessionRestoreResult>;
     buildRestoreRequest(restoreToMessageId: string): AiPromptDeleteBody;
-    /** Cancel the in-flight fetch. Does not clear conversation state. */
-    abort(): void;
-    private abortInflight;
+    /** Cancel the in-flight prompt and discard any partial assistant output. */
+    abort(options?: {
+        notify?: boolean;
+    }): void;
+    private _abortInflight;
     private _createStreamCallbacks;
     private _setConversationId;
     private _upsertMessage;
     private _finalizeInflightMessage;
     private _removeInflightFromMessages;
-    private _removeEmptyInflightFromMessages;
+    private _discardInflightMessage;
     private _handleSubmitError;
     private _hasCallback;
     private _emit;

package/components/ai-chat/stream/chunk-extractors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure field extractors for raw stream chunks.
+ *
+ * These read assistant text, chart, dashboard, and conversation-id values out of
+ * the various shapes a chunk can take (inline fields, `aiMessageAssets`, or a
+ * nested `result.assistant_message`). They are side-effect free, except
+ * `applyConversationId`, which forwards the id through a callback.
+ */
+import type { DashboardStatePayload } from '../ai-prompt-types';
+import type { StreamHandlerContext } from './types';
+export declare function extractInlineStreamText(chunk: Record<string, unknown>): string;
+export declare function extractStreamText(chunk: Record<string, unknown>): string;
+export declare function isStreamDone(chunk: Record<string, unknown>): boolean;
+export declare function applyConversationId(chunk: Record<string, unknown>, ctx: StreamHandlerContext): void;
+export declare function extractChartFromChunk(chunk: Record<string, unknown>): Record<string, unknown> | null;
+export declare function extractDashboardName(assets: unknown[]): Record<string, string> | undefined;
+export declare function extractDashboardFromChunk(chunk: Record<string, unknown>): DashboardStatePayload | null;
+/** Collect dashboard name from whichever asset array the chunk exposes. */
+export declare function extractDashboardNameFromChunk(chunk: Record<string, unknown>): Record<string, string> | undefined;

package/components/ai-chat/stream/index.d.ts

@@ -1,8 +1,52 @@
-export { createInitialProgress, fetchStreamingResponse, hasProgressChunk, parseStreamLine, readNdjsonStream } from './ai-chat-streaming';
+/**
+ * AI chat streaming — public barrel for the stream pipeline.
+ *
+ * Orchestrated by `ai-chat-session.ts` when a prompt is submitted. The pipeline
+ * has three layers: transport (HTTP + line parsing), processing (chunk → state +
+ * events), and shared helpers (field extraction).
+ *
+ * ## End-to-end flow
+ *
+ * ```
+ * submit prompt
+ *   → createInitialProgress()              // "Thinking" progress tree in the UI
+ *   → fetchStreamingResponse()             // POST to aiprompt API (or custom fetchStreaming)
+ *   → readNdjsonStream(body, onChunk)      // decode NDJSON / SSE lines into JSON objects
+ *        → createStreamHandler(agent)      // bound processStreamChunk per agent
+ *             → processStreamChunk()       // map chunk → callbacks (onStep, onComplete, …)
+ *   → session applies callbacks            // updates messages, progress, chart/dashboard
+ * ```
+ *
+ * ## Modules
+ *
+ * | File                 | Responsibility                                              |
+ * | -------------------- | ----------------------------------------------------------- |
+ * | `transport`          | HTTP fetch + NDJSON/SSE line parsing                        |
+ * | `progress`           | Initial progress tree + progress-chunk detection           |
+ * | `registry`           | Agent wiring: `createStreamHandler`, initial stream state   |
+ * | `stream-processor`   | Chunk routing, asset buffering, step/complete event emission  |
+ * | `chunk-extractors`   | Chunk field extraction (text, chart, dashboard, conversation) |
+ * | `types`              | `StreamHandlerContext`, callbacks, per-chunk state            |
+ *
+ * ## Agent mapping (`registry.ts`)
+ *
+ * - **dashboard** — `dashboardAssetType: 'dashboard'`; emits layout/title/item steps.
+ * - **item** — `chartAssetType: 'item'`; final chart on `onComplete`.
+ * - **analyst** — text and progress only.
+ *
+ * ## Callbacks (`StreamHandlerCallbacks`)
+ *
+ * Each chunk drives incremental UI via `onStep` (typed stream events), `onProgress`,
+ * `onMessageUpdate`, and `onProgressCollapsed`. The stream ends with a single
+ * `onComplete` carrying the final message and optional chart/dashboard payload.
+ *
+ * See `stream-processor.ts` for the full chunk-handler priority order and mapping table.
+ */
+export type { StreamingRequestOptions, StreamingResponse } from './transport';
+export { fetchStreamingResponse, parseStreamLine, readNdjsonStream } from './transport';
+export { createInitialProgress, hasProgressChunk } from './progress';
 export type { StreamChunkProcessor } from './registry';
-export { createInitialStreamState, createStreamHandler } from './registry';
-export type { StreamHandlerCallbacks, StreamHandlerContext, StreamHandlerState } from './types';
-export { appendStreamText, applyConversationId, extractChartFromChunk, extractStreamText, finalizeTextResponse, handleSharedError, handleSharedProgress, isStreamDone } from './shared';
-export { processItemStreamChunk } from './item-handler';
-export { getDashboardSnapshot, processDashboardStreamChunk } from './dashboard-handler';
-export { processAnalystStreamChunk } from './analyst-handler';
+export { createInitialStreamState, createStreamHandler, getAgentStreamDefinition } from './registry';
+export type { AgentStreamDefinition, StreamHandlerCallbacks, StreamHandlerContext, StreamHandlerState } from './types';
+export { applyConversationId, extractChartFromChunk, extractDashboardFromChunk, extractDashboardName, extractDashboardNameFromChunk, extractInlineStreamText, extractStreamText, isStreamDone } from './chunk-extractors';
+export { processStreamChunk } from './stream-processor';

package/components/ai-chat/stream/progress.d.ts

@@ -0,0 +1,3 @@
+import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
+export declare function createInitialProgress(): ProgressTreeNode;
+export declare function hasProgressChunk(value: Record<string, unknown>): boolean;

package/components/ai-chat/stream/registry.d.ts

@@ -1,5 +1,6 @@
 import type { AiPromptAgent } from '../ai-prompt-types';
-import type { StreamHandlerContext } from './types';
+import type { AgentStreamDefinition, StreamHandlerContext } from './types';
 export type StreamChunkProcessor = (chunk: Record<string, unknown>, ctx: StreamHandlerContext) => void;
+export declare function getAgentStreamDefinition(agent: AiPromptAgent): AgentStreamDefinition;
 export declare function createStreamHandler(agent: AiPromptAgent): StreamChunkProcessor;
 export declare function createInitialStreamState(): StreamHandlerContext['state'];

package/components/ai-chat/stream/stream-processor.d.ts

@@ -0,0 +1,2 @@
+import type { AgentStreamDefinition, StreamHandlerContext } from './types';
+export declare function processStreamChunk(chunk: Record<string, unknown>, ctx: StreamHandlerContext, def: AgentStreamDefinition): void;

package/components/ai-chat/stream/{ai-chat-streaming.d.ts → transport.d.ts}

@@ -1,6 +1,12 @@
-import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
-export declare function createInitialProgress(): ProgressTreeNode;
-export declare function hasProgressChunk(value: Record<string, unknown>): boolean;
+/**
+ * Transport layer for AI chat streaming.
+ *
+ * Owns the HTTP request to the aiprompt API and the wire-format decoding of the
+ * response body. Knows nothing about chunk semantics — it produces raw JSON
+ * objects that `stream-processor.ts` interprets.
+ *
+ * Supports both plain NDJSON (`{"type":"progress",...}`) and SSE (`data: {...}`).
+ */
 export interface StreamingRequestOptions {
     url: string;
     body: Record<string, unknown>;

package/components/ai-chat/stream/types.d.ts

@@ -1,26 +1,55 @@
 import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
-import type { AiSampleChart, ChatMessage } from '../../../types';
-import type { DashboardStatePayload, LuzmoDashboardGeneratedEventDetail } from '../ai-prompt-types';
+import type { ChatMessage } from '../../../types';
+import type { AiChatCompleteEvent, AiChatStepEvent } from '../ai-chat-events';
+import type { AiPromptAgent, DashboardStatePayload } from '../ai-prompt-types';
 export interface StreamHandlerCallbacks {
     onConversationIdChange: (conversationId: string) => void;
     onProgress: (progress: ProgressTreeNode) => void;
     onProgressCollapsed: (collapsed: boolean) => void;
     onMessageUpdate: (message: ChatMessage) => void;
-    dispatchChartGenerated: (detail: AiSampleChart) => void;
-    dispatchDashboardGenerated: (detail: LuzmoDashboardGeneratedEventDetail) => void;
-    dispatchResponseReceived: (message: ChatMessage, done: boolean) => void;
     getConversationId: () => string | null;
+    /** Fired for every incremental, assembled stream event. */
+    onStep: (event: AiChatStepEvent) => void;
+    /** Fired exactly once with the authoritative final result (or error). */
+    onComplete: (event: AiChatCompleteEvent) => void;
+}
+/** Per-asset accumulation buffer for the ASSET_START/DELTA/END channel. */
+export interface StreamAssetBuffer {
+    assetType: string;
+    snapshot: Record<string, unknown>;
 }
 export interface StreamHandlerState {
     progressCollapsed: boolean;
+    /** Accumulated assistant text streamed so far. */
+    accumulatedText: string;
+    /** Latest classifier decision routed from the progress root node. */
+    decision: 'create' | 'edit' | 'question' | null;
+    /** In-flight asset buffers keyed by asset id (or asset type as fallback). */
+    assets: Record<string, StreamAssetBuffer>;
+    /** Authoritative dashboard snapshot (dashboard agent). */
     dashboardSnapshot: DashboardStatePayload | null;
+    /** Dashboard name keyed by locale (dashboard agent). */
     dashboardName: Record<string, string> | undefined;
+    /** Authoritative chart snapshot (item agent). */
+    chartSnapshot: Record<string, unknown> | null;
+    /** Pending clarification question, when the agent interrupted. */
     interruptQuestion: string | null;
-    /** Latest item chart payload from streaming `asset_delta` events (aiprompt item agent). */
-    itemSnapshot: Record<string, unknown> | null;
+    /** Guards against firing {@link StreamHandlerCallbacks.onComplete} more than once. */
+    completed: boolean;
 }
 export interface StreamHandlerContext {
     aiMessage: ChatMessage;
     callbacks: StreamHandlerCallbacks;
     state: StreamHandlerState;
 }
+/**
+ * Per-agent stream definition. The shared processor owns the envelope/emit logic;
+ * the agent only declares which final `asset_type`s map to its authoritative result.
+ */
+export interface AgentStreamDefinition {
+    agent: AiPromptAgent;
+    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.chart}. */
+    chartAssetType?: string;
+    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.dashboard}. */
+    dashboardAssetType?: string;
+}