@luzmo/analytics-components-kit 1.0.9-beta.7 → 1.0.9-beta.9

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

@@ -0,0 +1,24 @@
+import { LuzmoAiChat } from './ai-chat';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-ai-chat': LuzmoAiChat;
+    }
+}
+export type { ProgressTreeNode, AssistantMessageAction, AssistantMessageActionConfirmVariant, AssistantMessageActionEventDetail, ChatMessageElicitation, AiChatMessageSentEventDetail, AiChatDatasetsChangedEventDetail, AiChatConversationIdChangedEventDetail } from '../../types/ai-chat.types';
+export type { PromptBoxAttachment, PromptBoxFileIcons } from '../ai-interaction-textarea';
+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';
+export { LuzmoAiChat } from './ai-chat';
+export type { AiChatAgentConfig } from './types';
+export { LuzmoAiChatEmptyState } from './empty-state';
+export type { AiChatEmptyStateSuggestion, AiChatEmptyStateSuggestionSelectedDetail } from './empty-state';
+export * from './ai-prompt-types';
+export * from './ai-chat-request';
+export { getUploadUrl, uploadAiPromptImages, getAiDictationUrl, streamAiDictation, buildAiDictationRequest, blobToBase64 } from '../../utils/ai-prompt';
+export type { UploadAiPromptImagesOptions, AiDictationCreateBody, AiDictationProperties, BuildAiDictationRequestOptions, StreamAiDictationOptions } from '../../utils/ai-prompt';
+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

@@ -1,22 +1,22 @@
-/*! * A kit of modern Luzmo Web Components for analytics in your web application.
- * 
- * Copyright © 2026 Luzmo
- * All rights reserved.
- * Luzmo web components (“Luzmo Web Components”)
- * must be used according to the Luzmo Terms of Service.
- * This license allows users with a current active Luzmo account
- * to use the Luzmo Web Components. This license terminates
- * automatically if a user no longer has an active Luzmo account.
- * Please view the Luzmo Terms of Service at: https://www.luzmo.com/information-pages/terms-of-use.
- * 
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
+/*! * A kit of modern Luzmo Web Components for analytics in your web application.
+ * 
+ * Copyright © 2026 Luzmo
+ * All rights reserved.
+ * Luzmo web components (“Luzmo Web Components”)
+ * must be used according to the Luzmo Terms of Service.
+ * This license allows users with a current active Luzmo account
+ * to use the Luzmo Web Components. This license terminates
+ * automatically if a user no longer has an active Luzmo account.
+ * Please view the Luzmo Terms of Service at: https://www.luzmo.com/information-pages/terms-of-use.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  * */
-import { a as e, c as t, d as n, f as r, i, l as a, m as o, n as s, o as c, p as l, r as u, s as d, u as f } from "../ai-interaction-textarea-Bths0__L.js";
-import { C as p, D as m, E as h, S as g, T as _, _ as v, a as y, b, c as x, d as S, f as C, g as w, h as T, i as E, l as D, m as O, n as k, o as A, p as j, r as M, s as N, t as P, u as F, v as I, w as L, x as R, y as z } from "../ai-chat-kH4xkt7a.js";
+import { a as e, c as t, d as n, f as r, i, l as a, m as o, n as s, o as c, p as l, r as u, s as d, u as f } from "../ai-interaction-textarea-CAb6g6dq.js";
+import { C as p, D as m, E as h, S as g, T as _, _ as v, a as y, b, c as x, d as S, f as C, g as w, h as T, i as E, l as D, m as O, n as k, o as A, p as j, r as M, s as N, t as P, u as F, v as I, w as L, x as R, y as z } from "../ai-chat-D0d30We9.js";
 export { t as AI_PROMPT_ACCEPTED_IMAGE_MIME_TYPES, a as AI_PROMPT_MAX_ATTACHMENTS, E as AiChatSession, M as AiChatSessionController, k as LuzmoAiChat, m as LuzmoAiChatEmptyState, f as assertValidAiPromptAttachmentFiles, n as assertValidAiPromptAttachmentUrls, s as blobToBase64, u as buildAiDictationRequest, v as buildAiPromptDeleteRequest, I as buildAiPromptProperties, z as buildAiPromptRequest, b as buildAnalystAiPromptProperties, R as buildCustomItemAiPromptProperties, g as buildDashboardAiPromptProperties, p as buildItemAiPromptProperties, L as buildSavedAgentAiPromptProperties, _ as chartToItemAsset, y as createAiChatSession, C as createInitialProgress, A as createInitialStreamState, N as createStreamHandler, F as extractChartFromChunk, S as extractDashboardFromChunk, O as fetchStreamingResponse, x as getAgentStreamDefinition, i as getAiDictationUrl, h as getAiPromptUrl, c as getUploadUrl, j as hasProgressChunk, r as isAiPromptAcceptedImageFile, l as isAiPromptAcceptedImageMimeType, o as isAiPromptAcceptedImageUrl, P as isRecognizedStep, T as parseStreamLine, D as processStreamChunk, w as readNdjsonStream, e as streamAiDictation, d as uploadAiPromptImages };

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

@@ -0,0 +1,60 @@
+import type { ChatMessage, Dataset } from '../../../types';
+import { type AiChatSession } from './ai-chat-session';
+import type { AiChatSessionCallbacks, AiChatSessionConfig, AiChatSessionState } from './ai-chat-session-types';
+export type AiChatSessionSeed = {
+    messages: ChatMessage[];
+    selectedDatasets: Dataset[];
+    conversationId: string | null;
+};
+export type AiChatSessionControllerOptions = {
+    getConfig: () => AiChatSessionConfig;
+    getSeed: () => AiChatSessionSeed;
+    createDomBridge: () => AiChatSessionCallbacks;
+    onRenderNeeded: () => void;
+};
+/**
+ * Single {@link AiChatSession} slot for `luzmo-ai-chat`.
+ * The chat component uses {@link current}, {@link state}, and {@link requireSession} only.
+ */
+export declare class AiChatSessionController {
+    private readonly options;
+    /** The active {@link AiChatSession}. Null until first bind or action. */
+    private _session;
+    /** When true, {@link teardown} aborts and clears the session. */
+    private _ownsSession;
+    /** Once the element supplies a custom item, its null value also overrides a host session. */
+    private _customItemFromProps;
+    /** Whether the session has been seeded from props. Used to avoid unnecessary updates. */
+    private _seededFromProps;
+    private _unsubscribe;
+    constructor(options: AiChatSessionControllerOptions);
+    get current(): AiChatSession | null;
+    get state(): Readonly<AiChatSessionState>;
+    get ownsCurrentSession(): boolean;
+    /**
+     * Use an app-provided session (e.g. from `.chatSession`).
+     * Pass `null` to clear it; an owned session may be created later via {@link requireSession}.
+     */
+    setSession(session: AiChatSession | null): void;
+    /**
+     * Sync config / seed props after Lit `updated`.
+     * Call after handling `chatSession` via {@link setSession}.
+     */
+    syncProperties(changedProperties: Map<string, unknown>): void;
+    requireSession(): AiChatSession;
+    /**
+     * Auth/API props from the element for host-owned sessions.
+     * Skips nullish chart/dashboard/screen mode so host-owned values are not wiped.
+     * Preserves a host custom item until the element supplies one; later null clears it.
+     * Never touches host `fetchStreaming`.
+     */
+    private _mergeHostElementConfig;
+    /** Re-attach UI bridge and state subscription after {@link teardown} on reconnect. */
+    connect(): void;
+    teardown(): void;
+    private _createSessionIfMissing;
+    private _clearSession;
+    private _seedFromPropsOnce;
+    private _wire;
+    private _unwire;
+}

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

@@ -0,0 +1,119 @@
+import type { PromptBoxAttachment } from '@luzmo/lucero';
+import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
+import type { AiSampleChart, ChatMessage, Dataset, LuzmoChart } from '../../../types';
+import type { AiChatCompleteEvent, AiChatStepEvent } from '../ai-chat-events';
+import type { AiPromptAgent, AiPromptCustomItemInput, AiPromptCreateBody, AiPromptDeleteBody, AiPromptItemTask, AiPromptScreenMode, BuildAiPromptRequestContext, DashboardStatePayload, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from '../ai-prompt-types';
+import type { StreamingRequestOptions, StreamingResponse } from '../stream/transport';
+import type { AiChatAgentConfig } from '../types';
+export interface AiChatSessionConfig {
+    /** Legacy agent selector. Defaults to item; agentConfig takes precedence. */
+    agent?: AiPromptAgent;
+    /** Typed agent selection and context. Omitted context preserves the same agent's context; null clears it. */
+    agentConfig?: AiChatAgentConfig;
+    /** Saved Agent override. Leave unset for custom-item sessions to preserve draft context and internal prompts. */
+    agentId?: string;
+    authKey: string;
+    authToken: string;
+    apiUrl?: string;
+    apiVersion?: string;
+    stream?: boolean;
+    conversationId?: string | null;
+    chart?: LuzmoChart | null;
+    dashboard?: DashboardStatePayload | null;
+    /** Draft context for `agent: 'custom-item'`, sent as its `custom-item` input. */
+    customItem?: AiPromptCustomItemInput['value'] | null;
+    currentScreenMode?: AiPromptScreenMode;
+    localeId?: string;
+    timezoneId?: string;
+    task?: AiPromptItemTask;
+    modelPreference?: 'performance' | 'quality';
+    /** Initial transcript when hydrating a saved conversation. */
+    messages?: ChatMessage[];
+    /** Datasets attached to the prompt input. */
+    selectedDatasets?: Dataset[];
+    /** When true, {@link AiChatSession.submit} requires at least one selected dataset or an `agentId` passed to it. */
+    requireDataset?: boolean;
+    /** Initial loading flag (e.g. Storybook or restored UI state). */
+    isGenerating?: boolean;
+    /** Initial progress tree. */
+    progress?: ProgressTreeNode | null;
+    /** Initial progress collapsed flag. */
+    progressCollapsed?: boolean;
+    /**
+     * 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>;
+}
+export interface AiChatSessionState {
+    messages: ChatMessage[];
+    selectedDatasets: Dataset[];
+    isGenerating: boolean;
+    progress: ProgressTreeNode | null;
+    progressCollapsed: boolean;
+    conversationId: string | null;
+    /** In-flight assistant message (streaming). Also present in `messages` while streaming. */
+    inflightMessage: ChatMessage | null;
+}
+export interface AiChatSessionCallbacks {
+    onStateChange?: (state: AiChatSessionState) => void;
+    onConversationIdChange?: (conversationId: string) => 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 plus an abort signal. No built-in fetch.
+     */
+    onPromptSubmitted?: (detail: LuzmoPromptSubmittedEventDetail) => void | Promise<void>;
+    /**
+     * Optional image upload override. When omitted, images upload via `POST /upload`.
+     * Return one signed URL per file (same order).
+     */
+    uploadAttachments?: (files: File[], options?: {
+        signal?: AbortSignal;
+    }) => Promise<string[]>;
+    /** 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>;
+}
+export interface AiChatSessionSubmitParams {
+    prompt: string;
+    /** Defaults to ids from {@link AiChatSessionState.selectedDatasets}. */
+    datasetIds?: string[];
+    /** Optional stable id for the in-flight AI message. */
+    aiMessageId?: string;
+    /** When true, does not append a user message (e.g. `initial-prompt` already in the transcript). */
+    skipUserMessage?: boolean;
+    /** Local prompt-box files; uploaded unless `attachmentUrls` is set. */
+    attachments?: PromptBoxAttachment[];
+    /** Signed image URLs already uploaded (`{ type: 'image', url }` inputs). Skips upload. */
+    attachmentUrls?: string[];
+    /**
+     * Saved Agent id for this prompt. Defaults to {@link AiChatSessionConfig.agentId}.
+     * Leave unset for custom-item sessions to preserve draft context and internal prompts.
+     */
+    agentId?: string;
+    /**
+     * Sends the prompt as `internal: true`, which keeps it out of the restored transcript.
+     * Only the custom-item agent supports it. Combine with `skipUserMessage` for a turn the
+     * host starts itself, such as an automatic fix.
+     */
+    internal?: boolean;
+}
+export interface AiChatSessionRestoreParams {
+    restoreToMessageId: string;
+    messageIndex: number;
+}
+export type AiChatSessionBuildContext = Omit<BuildAiPromptRequestContext, 'prompt' | 'datasetIds'>;
+export interface AiChatSessionRestoreResult {
+    chart?: AiSampleChart;
+    message?: string;
+}
+export type { AiPromptCreateBody, AiPromptDeleteBody, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail };

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

@@ -0,0 +1,119 @@
+import type { PromptBoxAttachment } from '@luzmo/lucero';
+import type { Dataset } from '../../../types';
+import type { AiPromptCreateBody, AiPromptDeleteBody, LuzmoPromptSubmittedEventDetail } from '../ai-prompt-types';
+import type { AiChatAgentConfig } from '../types';
+import type { AiChatSessionCallbacks, AiChatSessionConfig, AiChatSessionRestoreParams, AiChatSessionRestoreResult, AiChatSessionState, AiChatSessionSubmitParams } from './ai-chat-session-types';
+/**
+ * Headless chat controller: transcript, datasets, streaming, and API calls without a DOM host.
+ * Use with `luzmo-ai-chat` via `.chatSession` for the same simplicity as internal mode,
+ * while keeping the session alive when the panel unmounts.
+ *
+ * @example
+ * ```ts
+ * const session = createAiChatSession(
+ *   { agent: 'dashboard', authKey, authToken, dashboard, currentScreenMode },
+ *   {
+ *     onComplete: (e) => {
+ *       if (e.dashboard) applyToEditor(e.dashboard, e.name);
+ *     },
+ *     onStateChange: (s) => persistConversation(s.messages),
+ *   }
+ * );
+ *
+ * html`<luzmo-ai-chat .chatSession=${session}></luzmo-ai-chat>`;
+ * ```
+ */
+export declare class AiChatSession {
+    private _config;
+    /** Callbacks passed to {@link createAiChatSession} (host application). */
+    private _hostCallbacks;
+    /** Optional bridge from `luzmo-ai-chat` (DOM events). Replaced on each bind, not chained. */
+    private _uiBridgeCallbacks;
+    private readonly _subscribers;
+    private _state;
+    private _abortController;
+    private _inflightMessage;
+    private _receivedProgress;
+    constructor(config: AiChatSessionConfig, callbacks?: AiChatSessionCallbacks);
+    get state(): Readonly<AiChatSessionState>;
+    get isGenerating(): boolean;
+    /** Effective built-in agent and context after applying typed configuration or legacy compatibility inputs. */
+    get agentConfig(): AiChatAgentConfig;
+    /**
+     * Subscribe to full session state (for `luzmo-ai-chat` rendering). Returns an unsubscribe function.
+     * The listener is invoked immediately with the current state.
+     */
+    subscribe(listener: (state: AiChatSessionState) => void): () => void;
+    /**
+     * Wire `luzmo-ai-chat` DOM event bridging. Safe to call again when hot-swapping the same
+     * session back onto the component — replaces the previous bridge instead of stacking it.
+     */
+    setUiBridge(bridge: AiChatSessionCallbacks): void;
+    /** Merge config (chart, conversationId, agent, …) without aborting an in-flight request. */
+    updateConfig(partial: Partial<AiChatSessionConfig>): void;
+    /** Replace the full dataset selection (e.g. when the dashboard context changes). */
+    setSelectedDatasets(datasets: Dataset[]): void;
+    addDataset(dataset: Dataset): void;
+    removeDataset(datasetId: string): void;
+    isDatasetRequirementMet(agentId?: string): boolean;
+    getAiPromptUrl(): string;
+    buildRequestBody(prompt: string, datasetIds: string[], attachmentUrls?: string[], agentId?: string | undefined, options?: {
+        internal?: boolean;
+    }): AiPromptCreateBody;
+    /** Same payload passed to {@link AiChatSessionCallbacks.onPromptSubmitted}. */
+    buildPromptSubmittedDetail(params: {
+        prompt: string;
+        selectedDatasets: Dataset[];
+        datasetIds: string[];
+        signal?: AbortSignal;
+        attachments?: PromptBoxAttachment[];
+        attachmentUrls?: string[];
+        agentId?: string;
+        internal?: boolean;
+    }): LuzmoPromptSubmittedEventDetail;
+    /** Prefer provided URLs; otherwise upload via host callback or built-in `/upload`. */
+    private _resolveAttachmentUrls;
+    private _normalizeUploadedUrls;
+    /**
+     * Append the user prompt (unless `skipUserMessage`), start streaming, and update {@link state}.
+     */
+    submit(params: AiChatSessionSubmitParams): Promise<void>;
+    /** {@link submit}, resolving to whether the request was sent (`false` when declined, aborted or superseded first). */
+    private _submit;
+    /**
+     * Answer the clarifying question on the last message and send the answer as the next prompt.
+     * Resolves to `false` without sending while a response is generating, when that message has no open
+     * question or another message follows it, when `answer` is not one of its options, when the dataset requirement is not met, or when
+     * the send is aborted or superseded before the request goes out; the answer is cleared again then.
+     */
+    answerElicitation(messageId: string, answer: string, params?: Omit<AiChatSessionSubmitParams, 'prompt'>): Promise<boolean>;
+    /** Item agent only — restore conversation to a prior API message. */
+    restore(params: AiChatSessionRestoreParams): Promise<AiChatSessionRestoreResult>;
+    buildRestoreRequest(restoreToMessageId: string): AiPromptDeleteBody;
+    /**
+     * Cancel the in-flight prompt.
+     * User-initiated stops (`notify`) leave a "response cancelled" placeholder where the assistant
+     * reply would have been; internal aborts discard any partial assistant output.
+     */
+    abort(options?: {
+        notify?: boolean;
+        cancelledMessage?: string;
+    }): void;
+    private _abortInflight;
+    private _createStreamCallbacks;
+    private _setConversationId;
+    private _upsertMessage;
+    private _finalizeInflightMessage;
+    private _removeInflightFromMessages;
+    private _markInflightCancelled;
+    private _discardInflightMessage;
+    private _handleSubmitError;
+    private _hasCallback;
+    private _emit;
+    private _invokeCallback;
+    private _patchState;
+    private _notifySubscribers;
+    private _areSelectedDatasetsEqual;
+    private _areChatMessagesEqual;
+}
+export declare function createAiChatSession(config: AiChatSessionConfig, callbacks?: AiChatSessionCallbacks): AiChatSession;

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

@@ -0,0 +1,2 @@
+export { AiChatSession, createAiChatSession } from './ai-chat-session';
+export { AiChatSessionController } from './ai-chat-session-controller';

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

@@ -0,0 +1,29 @@
+/**
+ * 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 { AiPromptCustomItemInput, 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;
+/**
+ * Authoritative assistant text from a terminal chunk's `result.assistant_message`.
+ *
+ * Unlike {@link extractStreamText}, this never falls back to inline delta fields, so
+ * it is safe to use when finalizing the message: it yields the full answer to *set*
+ * (not append), avoiding duplication when the same text was already streamed as deltas.
+ */
+export declare function extractResultAssistantText(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;
+/** Reads custom-item drafts from top-level or terminal assistant-message assets. */
+export declare function extractCustomItemFromChunk(chunk: Record<string, unknown>): AiPromptCustomItemInput['value'] | null;

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

@@ -0,0 +1,53 @@
+/**
+ * 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`.
+ * - **custom-item** — `customItemAssetType: 'custom-item'`; updated draft 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, getAgentStreamDefinition } from './registry';
+export type { AgentStreamDefinition, StreamHandlerCallbacks, StreamHandlerContext, StreamHandlerState } from './types';
+export { applyConversationId, extractChartFromChunk, extractDashboardFromChunk, extractDashboardName, extractDashboardNameFromChunk, extractInlineStreamText, extractResultAssistantText, 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

@@ -0,0 +1,6 @@
+import type { AiPromptAgent } from '../ai-prompt-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/transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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>;
+    signal?: AbortSignal;
+}
+export interface StreamingResponse {
+    body: ReadableStream<Uint8Array>;
+    conversationId: string | null;
+}
+export declare function fetchStreamingResponse(options: StreamingRequestOptions): Promise<StreamingResponse>;
+/**
+ * Parse one line from an aiprompt response stream.
+ * Supports plain NDJSON (`{"type":"progress",...}`) and SSE (`data: {...}`).
+ */
+export declare function parseStreamLine(line: string): Record<string, unknown> | null;
+/** Read NDJSON or SSE (`data:`) chunks from a streaming aiprompt response body. */
+export declare function readNdjsonStream(body: ReadableStream<Uint8Array>, onChunk: (chunk: Record<string, unknown>) => void): Promise<void>;

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

@@ -0,0 +1,59 @@
+import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
+import type { ChatMessage } from '../../../types';
+import type { AiChatCompleteEvent, AiChatStepEvent } from '../ai-chat-events';
+import type { AiPromptAgent, AiPromptCustomItemInput, DashboardStatePayload } from '../ai-prompt-types';
+export interface StreamHandlerCallbacks {
+    onConversationIdChange: (conversationId: string) => void;
+    onProgress: (progress: ProgressTreeNode) => void;
+    onProgressCollapsed: (collapsed: boolean) => void;
+    onMessageUpdate: (message: ChatMessage) => 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;
+    /** Authoritative custom item draft (custom-item agent). */
+    customItemSnapshot: AiPromptCustomItemInput['value'] | null;
+    /** Pending clarification question, when the agent interrupted. */
+    interruptQuestion: string | 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;
+    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.customItem}. */
+    customItemAssetType?: string;
+}

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

@@ -0,0 +1,24 @@
+import type { LuzmoChart } from '../../types';
+import type { AiPromptCustomItemInput, AiPromptItemTask, AiPromptScreenMode, DashboardStatePayload } from './ai-prompt-types';
+/** Configuration for one built-in agent. Omitted context preserves the same agent's context; null clears it. */
+export type AiChatAgentConfig = {
+    type: 'item';
+    context?: {
+        chart?: LuzmoChart | null;
+        task?: AiPromptItemTask;
+    } | null;
+} | {
+    type: 'dashboard';
+    context?: {
+        dashboard?: DashboardStatePayload | null;
+        currentScreenMode?: AiPromptScreenMode;
+    } | null;
+} | {
+    type: 'custom-item';
+    context?: {
+        customItem?: AiPromptCustomItemInput['value'] | null;
+    } | null;
+} | {
+    type: 'analyst';
+    context?: null;
+};