@luzmo/analytics-components-kit 1.0.3-beta.5 → 1.0.3-beta.6

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

@@ -0,0 +1,11 @@
+import type { LuzmoChart } from '../../types';
+import type { AiPromptAgent, AiPromptCreateBody, AiPromptDeleteBody, AiPromptProperties, BuildAiPromptRequestContext } from './ai-prompt-types';
+export type { AiPromptAgent, AiPromptCreateBody, AiPromptDeleteBody, AiPromptInput, AiPromptItemTask, AiPromptProperties, AiPromptScreenMode, BuildAiPromptRequestContext, DashboardStatePayload, LuzmoDashboardGeneratedEventDetail, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from './ai-prompt-types';
+export declare function getAiPromptUrl(apiUrl: string, apiVersion: string): string;
+export declare function chartToItemAsset(chart: LuzmoChart): Record<string, unknown> | null;
+export declare function buildItemAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
+export declare function buildDashboardAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
+export declare function buildAnalystAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
+export declare function buildAiPromptProperties(agent: AiPromptAgent, ctx: BuildAiPromptRequestContext): AiPromptProperties;
+export declare function buildAiPromptRequest(agent: AiPromptAgent, ctx: BuildAiPromptRequestContext): AiPromptCreateBody;
+export declare function buildAiPromptDeleteRequest(restoreToMessageId: string, authKey: string, authToken: string, apiVersion?: string, conversationId?: string | null): AiPromptDeleteBody;

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

@@ -2,19 +2,24 @@ import '@luzmo/lucero/chat-message';
 import '@luzmo/lucero/overlay';
 import '@luzmo/lucero/popover';
 import '@luzmo/lucero/progress-steps';
-import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
 import { LuzmoElement } from '@utils/base';
 import { TemplateResult } from 'lit';
 import type { ChatMessage, Dataset, LuzmoChart } from '../../types';
 import '../ai-interaction-textarea';
+import type { AiChatSession } from './session/ai-chat-session';
+import type { AiPromptAgent, AiPromptItemTask, AiPromptScreenMode, DashboardStatePayload } from './ai-prompt-types';
 /**
  * @customElement luzmo-ai-chat
- * @summary A complete AI chat interface combining messages display and input
+ * @summary AI chat UI backed by AiChatSession for transcript, datasets, and streaming.
+ * @description Chat state lives in an AiChatSession. By default the element creates an internal
+ * 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 luzmo-message-sent - Fired when a user sends a message
- * @fires luzmo-prompt-submitted - Fired when request-mode is set to external so the host can execute the API request lifecycle.
  * @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 the AI generates a chart (includes generatedChart in response)
- * @fires luzmo-restore-requested - Fired when a restore action is triggered in external mode
+ * @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-conversation-id-changed - Fired when the conversation ID is updated from the API
  *
  * @property {string} --luzmo-ai-chat-background - Background of the chat container
  * @property {string} --luzmo-ai-chat-border-radius - Border radius of the chat container
@@ -46,11 +51,11 @@ export declare class LuzmoAiChat extends LuzmoElement {
     static styles: import("lit").CSSResult;
     static tagName: string;
     /**
-     * Array of chat messages to display
+     * Live transcript is {@link AiChatSession.state.messages}. This prop optionally seeds the session on first connect.
      */
     messages: ChatMessage[];
     /**
-     * Array of selected datasets for the input
+     * Live selection is in the session. This prop optionally seeds on first connect.
      */
     selectedDatasets: Dataset[];
     /**
@@ -112,30 +117,52 @@ export declare class LuzmoAiChat extends LuzmoElement {
      */
     requireDataset: boolean;
     /**
-     * AI model preference for chart generation
-     * @default 'performance'
+     * Which aiprompt agent to use. Determines request payload and stream handling.
+     * @default 'item'
      */
-    modelPreference: 'performance' | 'quality';
+    agent: AiPromptAgent;
     /**
-     * Controls if API calls are handled internally or by the host application.
-     * @default 'internal'
+     * Task for the item agent (`generate`, `suggest`, `describe`).
+     * @default 'generate'
+     */
+    task: AiPromptItemTask;
+    /**
+     * AI model preference for item agent chart generation
+     * @default 'performance'
      */
-    requestMode: 'internal' | 'external';
+    modelPreference: 'performance' | 'quality';
     /**
-     * Used only in external request mode to reflect request lifecycle in the UI.
-     * @default false
+     * Host-owned {@link AiChatSession}. The component subscribes and renders; does not abort on disconnect.
      */
-    isGenerating: boolean;
+    chatSession: AiChatSession | null;
     /**
-     * Conversation ID
+     * Conversation ID (synced into the session; updated when the API returns a new id).
      * @default null
      */
     conversationId: string | null;
     /**
-     * vizItem
+     * Chart context for `agent="item"`.
      * @default null
      */
     chart: LuzmoChart | null;
+    /**
+     * Dashboard context for `agent="dashboard"`.
+     * @default null
+     */
+    dashboard: DashboardStatePayload | null;
+    /**
+     * Current screen mode when editing a dashboard.
+     */
+    currentScreenMode?: AiPromptScreenMode;
+    /**
+     * Locale ID sent to the aiprompt API.
+     */
+    localeId?: string;
+    /**
+     * Timezone ID for dashboard agent requests.
+     * @default 'UTC'
+     */
+    timezoneId: string;
     /**
      * API version
      * @default '0.1.0'
@@ -149,59 +176,37 @@ export declare class LuzmoAiChat extends LuzmoElement {
     stream: boolean;
     /**
      * Loading message shown while generating and before progress steps are available.
-     * Only effective in external request mode; in internal mode, progress steps
-     * are initialized immediately.
      * @default null
      */
     loadingMessage: string | null;
     /**
-     * When set, the component auto-submits this prompt via the streaming API
-     * without adding a duplicate user message (assumes it is already in `messages`).
-     * Useful when the prompt originates from an external source (e.g. a dropdown).
+     * When set, auto-submits via the session without adding a duplicate user message
+     * (assumes the prompt is already in the transcript).
      * @default null
      */
     initialPrompt: string | null;
-    /**
-     * Progress tree for external request mode. Ignored in internal mode.
-     * @default null
-     */
-    progress: ProgressTreeNode | null;
-    /**
-     * Whether progress steps should be shown collapsed.
-     * Only used in external request mode. Ignored in internal mode.
-     * @default false
-     */
-    progressCollapsed: boolean;
-    private _progress;
-    private _progressCollapsed;
-    private _isGeneratingInternal;
     private _textareaValue;
-    private _abortController;
-    private _inflightAiMessage;
     private _lastProcessedInitialPrompt;
-    private _receivedProgress;
-    private _generateMessageId;
-    private _buildRequestBody;
-    private _buildDeleteRequestBody;
-    private _finalizeInflightMessage;
-    private _sendStreamingMessage;
-    private _processStreamChunk;
-    private _addUserMessage;
-    private _updateMessage;
-    private _truncateMessagesAfterRestore;
-    private _restoreInternal;
+    private readonly _session;
+    /** Active {@link AiChatSession} (host or auto-created). Null until first bind or action. */
+    get session(): AiChatSession | null;
+    private _getRenderState;
+    private _createDomBridgeCallbacks;
+    private _buildSessionConfig;
+    private _emitConversationIdChanged;
+    private _restoreViaSession;
     private _handleRestoreState;
-    private _prepareForAIResponse;
-    private _handleAPIError;
     private _handleDatasetSelected;
     private _handleDatasetRemoved;
-    private _emitDatasetsChanged;
-    private _isDatasetRequirementMet;
+    private _submitViaSession;
     private _handlePromptSubmitted;
     private _processInitialPrompt;
+    connectedCallback(): void;
     disconnectedCallback(): void;
     private _scrollToBottom;
     protected updated(changedProperties: Map<string, unknown>): void;
+    private _syncSession;
+    private _handleInitialPromptChange;
     /**
      * Sanitizes HTML content to prevent XSS attacks while preserving safe formatting
      * @param htmlContent - The HTML string to sanitize

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

@@ -0,0 +1,93 @@
+import type { Dataset, LuzmoChart } from '../../types';
+export type AiPromptAgent = 'item' | 'dashboard' | 'analyst';
+export type AiPromptItemTask = 'generate' | 'suggest' | 'describe';
+export type AiPromptScreenMode = 'desktop' | 'tablet' | 'mobile';
+/** Dashboard payload for `agent: 'dashboard'` input (views, syncScreenModes, optional theme). */
+export interface DashboardStatePayload {
+    views: unknown[];
+    syncScreenModes?: boolean;
+    theme?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface AiPromptTextInput {
+    type: 'text';
+    text: string;
+}
+export interface AiPromptDatasetInput {
+    type: 'dataset';
+    id: string;
+}
+export interface AiPromptItemInput {
+    type: 'item';
+    value: Record<string, unknown>;
+}
+export interface AiPromptDashboardInput {
+    type: 'dashboard';
+    value: DashboardStatePayload;
+    current_screen_mode?: AiPromptScreenMode;
+}
+export type AiPromptInput = AiPromptTextInput | AiPromptDatasetInput | AiPromptItemInput | AiPromptDashboardInput;
+export interface AiPromptProperties {
+    agent: AiPromptAgent;
+    task: AiPromptItemTask | 'generate';
+    conversation_id?: string;
+    locale_id?: string;
+    timezone_id?: string;
+    stream: boolean;
+    response_mode: 'mixed';
+    input: AiPromptInput[];
+}
+export interface AiPromptCreateBody {
+    key: string;
+    token: string;
+    action: 'create';
+    version: string;
+    properties: AiPromptProperties;
+}
+export interface AiPromptDeleteBody {
+    key: string;
+    token: string;
+    action: 'delete';
+    version: string;
+    properties: {
+        agent: 'item';
+        restore_to_message_id: string;
+        conversation_id?: string;
+    };
+}
+export interface BuildAiPromptRequestContext {
+    prompt: string;
+    datasetIds: string[];
+    authKey: string;
+    authToken: string;
+    conversationId: string | null;
+    apiVersion?: string;
+    stream?: boolean;
+    localeId?: string;
+    timezoneId?: string;
+    /** Session/UI preference only; not serialized on aiprompt create until the backend supports it. */
+    modelPreference?: 'performance' | 'quality';
+    chart?: LuzmoChart | null;
+    dashboard?: DashboardStatePayload | null;
+    currentScreenMode?: AiPromptScreenMode;
+    task?: AiPromptItemTask;
+}
+export interface LuzmoPromptSubmittedEventDetail {
+    prompt: string;
+    selectedDatasets: Dataset[];
+    datasetIds: string[];
+    agent: AiPromptAgent;
+    request: AiPromptCreateBody;
+    url: string;
+}
+export interface LuzmoRestoreRequestedEventDetail {
+    apiMessageId: string;
+    messageIndex: number;
+    request: AiPromptDeleteBody;
+    url: string;
+}
+export interface LuzmoDashboardGeneratedEventDetail {
+    dashboard: DashboardStatePayload;
+    conversationId: string | null;
+    name?: Record<string, 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-D9yB7Sw_.cjs`);exports.LuzmoAiChat=e.t,exports.buildAiMessageDeleteRequest=e.n,exports.buildAiMessageRequest=e.r,exports.createInitialProgress=e.i,exports.fetchStreamingResponse=e.a,exports.hasProgressChunk=e.o,exports.readNdjsonStream=e.s;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../ai-chat-CY73iYCg.cjs`);exports.AiChatSession=e.r,exports.AiChatSessionController=e.n,exports.LuzmoAiChat=e.t,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;

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

@@ -4,8 +4,13 @@ declare global {
         'luzmo-ai-chat': LuzmoAiChat;
     }
 }
-export { LuzmoAiChat } from './ai-chat';
 export type { ProgressTreeNode } from '../../types/ai-chat.types';
-export * from './request-contract';
-export { createInitialProgress, fetchStreamingResponse, hasProgressChunk, readNdjsonStream } from './ai-chat-streaming';
-export type { StreamingRequestOptions, StreamingResponse } from './ai-chat-streaming';
+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 * 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';

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 { a as e, i as t, n, o as r, r as i, s as a, t as o } from "../ai-chat-DkfD3BDG.js";
-export { o as LuzmoAiChat, n as buildAiMessageDeleteRequest, i as buildAiMessageRequest, t as createInitialProgress, e as fetchStreamingResponse, r as hasProgressChunk, a as readNdjsonStream };
+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, y } from "../ai-chat-DVU9XiA2.js";
+export { m as AiChatSession, d as AiChatSessionController, g as LuzmoAiChat, p as buildAiPromptDeleteRequest, u as buildAiPromptProperties, s as buildAiPromptRequest, o as buildAnalystAiPromptProperties, e as buildDashboardAiPromptProperties, v as buildItemAiPromptProperties, y 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 };

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

@@ -0,0 +1,51 @@
+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;
+    /** 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;
+    /** 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,86 @@
+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';
+export interface AiChatSessionConfig {
+    agent: AiPromptAgent;
+    authKey: string;
+    authToken: string;
+    apiUrl?: string;
+    apiVersion?: string;
+    stream?: boolean;
+    conversationId?: string | null;
+    chart?: LuzmoChart | null;
+    dashboard?: DashboardStatePayload | 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. */
+    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 kit's {@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;
+    onChartGenerated?: (detail: AiSampleChart) => void;
+    onDashboardGenerated?: (detail: LuzmoDashboardGeneratedEventDetail) => void;
+    onResponseReceived?: (message: ChatMessage, done: boolean, error?: unknown) => 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.
+     */
+    onPromptSubmitted?: (detail: LuzmoPromptSubmittedEventDetail) => 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;
+    /** 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;
+}
+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,81 @@
+import type { Dataset } from '../../../types';
+import type { AiPromptCreateBody, AiPromptDeleteBody, LuzmoPromptSubmittedEventDetail } from '../ai-prompt-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 },
+ *   {
+ *     onDashboardGenerated: (d) => applyToEditor(d),
+ *     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;
+    /**
+     * 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(): boolean;
+    getAiPromptUrl(): string;
+    buildRequestBody(prompt: string, datasetIds: string[]): AiPromptCreateBody;
+    /** Same payload passed to {@link AiChatSessionCallbacks.onPromptSubmitted}. */
+    buildPromptSubmittedDetail(prompt: string, selectedDatasets: Dataset[], datasetIds: string[]): LuzmoPromptSubmittedEventDetail;
+    /**
+     * Append the user prompt (unless `skipUserMessage`), start streaming, and update {@link state}.
+     */
+    submit(params: AiChatSessionSubmitParams): Promise<void>;
+    /** 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;
+    private _createStreamCallbacks;
+    private _setConversationId;
+    private _upsertMessage;
+    private _finalizeInflightMessage;
+    private _removeInflightFromMessages;
+    private _removeEmptyInflightFromMessages;
+    private _handleSubmitError;
+    private _hasCallback;
+    private _emit;
+    private _invokeCallback;
+    private _patchState;
+    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/{ai-chat-streaming.d.ts → stream/ai-chat-streaming.d.ts}

@@ -11,4 +11,10 @@ export interface StreamingResponse {
     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/analyst-handler.d.ts

@@ -0,0 +1,3 @@
+import type { StreamHandlerContext } from './types';
+/** Minimal analyst stream handling: text, progress, and errors. */
+export declare function processAnalystStreamChunk(chunk: Record<string, unknown>, ctx: StreamHandlerContext): void;

package/components/ai-chat/stream/dashboard-handler.d.ts

@@ -0,0 +1,4 @@
+import type { DashboardStatePayload } from '../ai-prompt-types';
+import type { StreamHandlerContext } from './types';
+export declare function processDashboardStreamChunk(chunk: Record<string, unknown>, ctx: StreamHandlerContext): void;
+export declare function getDashboardSnapshot(state: StreamHandlerContext['state']): DashboardStatePayload | null;

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

@@ -0,0 +1,8 @@
+export { createInitialProgress, fetchStreamingResponse, hasProgressChunk, parseStreamLine, readNdjsonStream } from './ai-chat-streaming';
+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';

package/components/ai-chat/stream/item-handler.d.ts

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

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

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

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

@@ -0,0 +1,10 @@
+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 handleSharedProgress(chunk: Record<string, unknown>, ctx: StreamHandlerContext): boolean;
+export declare function handleSharedError(chunk: Record<string, unknown>, ctx: StreamHandlerContext): boolean;
+export declare function appendStreamText(ctx: StreamHandlerContext, textContent: string): void;
+export declare function finalizeTextResponse(ctx: StreamHandlerContext, isDone: boolean, hadTextInChunk?: boolean): void;
+export declare function extractChartFromChunk(chunk: Record<string, unknown>): Record<string, unknown> | null;

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

@@ -0,0 +1,26 @@
+import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
+import type { AiSampleChart, ChatMessage } from '../../../types';
+import type { DashboardStatePayload, LuzmoDashboardGeneratedEventDetail } 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;
+}
+export interface StreamHandlerState {
+    progressCollapsed: boolean;
+    dashboardSnapshot: DashboardStatePayload | null;
+    dashboardName: Record<string, string> | undefined;
+    interruptQuestion: string | null;
+    /** Latest item chart payload from streaming `asset_delta` events (aiprompt item agent). */
+    itemSnapshot: Record<string, unknown> | null;
+}
+export interface StreamHandlerContext {
+    aiMessage: ChatMessage;
+    callbacks: StreamHandlerCallbacks;
+    state: StreamHandlerState;
+}