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

package/angular/utils/transformations/convert-datasets-to-data-fields.d.ts

@@ -0,0 +1,30 @@
+import type { DatasetDataField } from '../../types/dataset-data-field.types';
+import type { DatasetColumnMetadata, DatasetFormulaMetadata, DatasetMetadata } from '../data-broker/index';
+export declare const mapDatasetColumnToDatasetDataField: (datasetId: string, column: DatasetColumnMetadata, options?: {
+    includeHidden?: boolean;
+}) => Extract<DatasetDataField, {
+    columnId: string;
+}> | null;
+export declare const mapDatasetFormulaToDatasetDataField: (datasetId: string, formula: DatasetFormulaMetadata, options?: {
+    includeHidden?: boolean;
+}) => Extract<DatasetDataField, {
+    formulaId: string;
+}> | null;
+export declare const mapDatasetToDataFields: (dataset: DatasetMetadata, options?: {
+    includeHidden?: boolean;
+}) => DatasetDataField[];
+export interface DatasetWithDataFields {
+    id: string;
+    name: Record<string, string>;
+    description?: Record<string, string>;
+    dataFields: DatasetDataField[];
+}
+/**
+ * Converts DataBroker dataset metadata to datasets with data fields.
+ * @param datasets Array of datasets to convert.
+ * @param options Mapping options to control visibility and field types.
+ * @returns Array of datasets, each containing its metadata and data fields.
+ */
+export declare const convertDatasetsToDataFields: (datasets: DatasetMetadata[], options?: {
+    includeHidden?: boolean;
+}) => DatasetWithDataFields[];

package/angular/utils/transformations/tests/convert-data-field-to-slot-content.test.d.ts

@@ -0,0 +1 @@
+export {};

package/angular/utils/transformations/tests/convert-datasets-to-data-fields.test.d.ts

@@ -0,0 +1 @@
+export {};

package/angular/utils/types/tests/type-check.test.d.ts

@@ -0,0 +1 @@
+export {};

package/angular/utils/types/type-check.d.ts

@@ -0,0 +1,28 @@
+export declare function isEmpty(value: any): boolean;
+export declare function isString(value: any): value is string;
+export declare function isNumeric(value: any): value is number;
+export declare function isBoolean(value: any): value is boolean;
+export declare function isObject(value: any): boolean;
+export declare function isDate(value: any): value is Date;
+export declare function isEmptyObject(value: any): boolean;
+/**
+ * Validates if a string is a valid UUID v4 format
+ * @param value - The string to validate
+ * @returns true if the string is a valid UUID, false otherwise
+ */
+export declare function isValidUuid(value: unknown): boolean;
+/**
+ * Filters an array of strings to only include valid UUIDs
+ * @param ids - Array of strings to filter
+ * @returns Array containing only valid UUIDs
+ */
+export declare function filterValidUuids(ids: string[]): string[];
+/**
+ * Validates an array of IDs and returns info about invalid ones
+ * @param ids - Array of IDs to validate
+ * @returns Object with valid IDs array and invalid IDs array
+ */
+export declare function validateUuids(ids: string[]): {
+    valid: string[];
+    invalid: string[];
+};

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

@@ -1,11 +1,11 @@
 import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
 import type { AiSampleChart, ChatMessage } from '../../types';
-import type { AiPromptAgent, DashboardStatePayload } from './ai-prompt-types';
+import type { AiPromptAgent, AiPromptCustomItemInput, 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`). */
+    /** The aiprompt agent that produced this step (`item`, `dashboard`, `analyst`, `custom-item`). */
     agent: AiPromptAgent;
     /** Current conversation id, or `null` before the backend assigns one. */
     conversationId: string | null;
@@ -15,7 +15,7 @@ export interface AiChatStepBase {
     raw: Record<string, unknown>;
 }
 /** Recognized stream-step type discriminants. */
-export type AiChatRecognizedStepType = 'decision' | 'text' | 'progress' | 'dashboard-title' | 'dashboard-layout' | 'dashboard-item' | 'chart' | 'interrupt';
+export type AiChatRecognizedStepType = 'decision' | 'text' | 'progress' | 'dashboard-title' | 'dashboard-layout' | 'dashboard-item' | 'chart' | 'custom-item' | 'elicitation' | 'interrupt';
 /**
  * Stream steps assembled into a typed `data` payload.
  * Discriminated by `type` (when `recognized` is `true`).
@@ -58,6 +58,17 @@ export type RecognizedStepEvent = (AiChatStepBase & {
     recognized: true;
     type: 'chart';
     data: Record<string, unknown>;
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'custom-item';
+    data: AiPromptCustomItemInput['value'];
+}) | (AiChatStepBase & {
+    recognized: true;
+    type: 'elicitation';
+    data: {
+        question: string;
+        options: string[];
+    };
 }) | (AiChatStepBase & {
     recognized: true;
     type: 'interrupt';
@@ -95,6 +106,11 @@ export interface AiChatCompleteEvent {
     dashboard?: DashboardStatePayload;
     /** Authoritative chart payload (item agent). */
     chart?: AiSampleChart;
+    /**
+     * Updated custom item draft (custom-item agent), present only when the agent changed it.
+     * Carries the chart document under `document` plus validation results such as `ok`.
+     */
+    customItem?: AiPromptCustomItemInput['value'];
     /** Dashboard name keyed by locale (dashboard agent). */
     name?: Record<string, string>;
     /** Forward-compat: any final assets not modeled explicitly. */

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

@@ -7,6 +7,11 @@ export declare function chartToItemAsset(chart: LuzmoChart): Record<string, unkn
 export declare function buildItemAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
 export declare function buildDashboardAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
 export declare function buildAnalystAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
+/**
+ * Properties for the custom-item agent, which authors custom chart code. It reads no datasets
+ * and replies in markdown, which the chat renders.
+ */
+export declare function buildCustomItemAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
 /**
  * Properties for a saved Agent run. The agent id resolves datasets, capabilities and theme
  * server-side, so `agent` and `task` are deliberately absent: sending either alongside

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

@@ -8,7 +8,8 @@ import { LuzmoElement } from '../../utils/base';
 import { type PropertyValues, TemplateResult } from 'lit';
 import type { ChatMessage, Dataset, LuzmoChart } from '../../types';
 import '../ai-interaction-textarea';
-import type { AiPromptAgent, AiPromptItemTask, AiPromptScreenMode, DashboardStatePayload } from './ai-prompt-types';
+import type { AiPromptAgent, AiPromptCustomItemInput, AiPromptItemTask, AiPromptScreenMode, DashboardStatePayload } from './ai-prompt-types';
+import type { AiChatAgentConfig } from './types';
 import './empty-state';
 import type { AiChatEmptyStateSuggestion } from './empty-state';
 import type { AiChatSession } from './session/ai-chat-session';
@@ -19,8 +20,8 @@ import type { AiChatSession } from './session/ai-chat-session';
  * 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 {CustomEvent<AiChatStepEvent>} luzmo-step - Fired for every incremental, kit-assembled event during a streamed response (decision, text, progress, dashboard-title/layout/item, chart, custom-item, elicitation, 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/customItem) or an `error`.
  * @fires {CustomEvent<AiChatMessageSentEventDetail>} luzmo-message-sent - Fired when a user sends a message
  * @fires {CustomEvent<AiChatDatasetsChangedEventDetail>} luzmo-datasets-changed - Fired when the selected datasets change
  * @fires {CustomEvent<AiChatConversationIdChangedEventDetail>} luzmo-conversation-id-changed - Fired when the conversation ID is updated from the API
@@ -168,11 +169,19 @@ export declare class LuzmoAiChat extends LuzmoElement {
         signal?: AbortSignal;
     }) => Promise<string[]>;
     /**
-     * Which aiprompt agent to use. Determines request payload and stream handling.
-     * With `agent-id` set it no longer shapes the request payload, only stream handling.
+     * Which aiprompt agent to use (`item`, `dashboard`, `analyst` or `custom-item`). Determines request
+     * payload and stream handling. With `agent-id` set it no longer shapes the request payload, only stream handling.
+     * Custom-item hosts must set `hide-agents` and leave `agent-id` unset to preserve draft context
+     * and internal repair prompts.
      * @default 'item'
      */
     agent: AiPromptAgent;
+    /**
+     * Typed agent selection and context. Takes precedence over legacy agent, task and context properties.
+     * Omit context to preserve the same agent's session context; use null to clear it.
+     * Undefined leaves a host session's typed configuration intact and uses legacy properties for an internal session.
+     */
+    agentConfig?: AiChatAgentConfig;
     /**
      * Saved Agent id (UUID) to run the prompt as. An agent picked in the prompt box takes precedence for that prompt.
      */
@@ -206,6 +215,14 @@ export declare class LuzmoAiChat extends LuzmoElement {
      * @default null
      */
     dashboard: DashboardStatePayload | null;
+    /**
+     * Draft context for `agent="custom-item"`, sent as its `custom-item` input. The host owns the
+     * shape: the chart document under `document`, plus fields such as `chartId`.
+     * With a host `chatSession`, the default null preserves its draft. Once this element supplies
+     * a draft, setting this property to null clears the session's custom item context.
+     * @default null
+     */
+    customItem: AiPromptCustomItemInput['value'] | null;
     /**
      * Current screen mode when editing a dashboard.
      */
@@ -273,6 +290,7 @@ export declare class LuzmoAiChat extends LuzmoElement {
     private get _pickedAgentId();
     private get _resolvedAcceptedFileTypes();
     private _buildSessionConfig;
+    private _getAgentConfig;
     private _emitConversationIdChanged;
     private _restoreViaSession;
     private _handleRestoreState;
@@ -321,6 +339,7 @@ export declare class LuzmoAiChat extends LuzmoElement {
     private _renderAssistantMessageActions;
     private _renderRestoreMenu;
     private _renderMessages;
+    private _handleElicitationSubmit;
     private _renderStreamingResponse;
     private _renderLoadingMessage;
     private _renderEmptyState;

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

@@ -1,6 +1,6 @@
 import type { PromptBoxAttachment } from '@luzmo/lucero';
 import type { Dataset, LuzmoChart } from '../../types';
-export type AiPromptAgent = 'item' | 'dashboard' | 'analyst';
+export type AiPromptAgent = 'item' | 'dashboard' | 'analyst' | 'custom-item';
 export type AiPromptItemTask = 'generate' | 'suggest' | 'describe';
 export type AiPromptScreenMode = 'desktop' | 'tablet' | 'mobile';
 /** Dashboard payload for `agent: 'dashboard'` input (views, syncScreenModes, optional theme). */
@@ -27,16 +27,25 @@ export interface AiPromptDashboardInput {
     value: DashboardStatePayload;
     current_screen_mode?: AiPromptScreenMode;
 }
+/**
+ * Draft context for `agent: 'custom-item'`. The host owns its shape: the chart document under
+ * `document`, plus optional fields such as `chartId`, `isExample`, `hostTheme` and `previewFrame`.
+ */
+export interface AiPromptCustomItemInput {
+    type: 'custom-item';
+    value: Record<string, unknown>;
+}
 export interface AiPromptImageInput {
     type: 'image';
     url: string;
 }
-export type AiPromptInput = AiPromptTextInput | AiPromptDatasetInput | AiPromptItemInput | AiPromptDashboardInput | AiPromptImageInput;
+export type AiPromptInput = AiPromptTextInput | AiPromptDatasetInput | AiPromptItemInput | AiPromptDashboardInput | AiPromptCustomItemInput | AiPromptImageInput;
 /** Fields both aiprompt create shapes share, whichever agent selector is used. */
 export interface AiPromptPropertiesBase {
     conversation_id?: string;
     locale_id?: string;
     timezone_id?: string;
+    text_format?: 'plain' | 'markdown';
     stream: boolean;
     response_mode: 'mixed';
     input: AiPromptInput[];
@@ -45,6 +54,8 @@ export interface AiPromptPropertiesBase {
 export interface AiPromptBuiltInAgentProperties extends AiPromptPropertiesBase {
     agent: AiPromptAgent;
     task: AiPromptItemTask | 'generate';
+    /** Hides the prompt from the restored transcript. Custom-item agent only. */
+    internal?: boolean;
     agent_id?: never;
 }
 /**
@@ -90,9 +101,13 @@ export interface BuildAiPromptRequestContext {
     modelPreference?: 'performance' | 'quality';
     chart?: LuzmoChart | null;
     dashboard?: DashboardStatePayload | null;
+    /** Draft context for `agent: 'custom-item'`. */
+    customItem?: AiPromptCustomItemInput['value'] | null;
     currentScreenMode?: AiPromptScreenMode;
     task?: AiPromptItemTask;
     attachmentUrls?: string[];
+    /** Sends `internal: true` so the prompt stays out of the restored transcript (custom-item agent only). */
+    internal?: boolean;
 }
 export interface LuzmoPromptSubmittedEventDetail {
     prompt: string;

package/components/ai-chat/helpers/agent-config.d.ts

@@ -0,0 +1,12 @@
+import type { AiPromptAgent, BuildAiPromptRequestContext } from '../ai-prompt-types';
+import type { AiChatAgentConfig } from '../types';
+type LegacyAgentContext = Pick<BuildAiPromptRequestContext, 'chart' | 'dashboard' | 'customItem' | 'currentScreenMode' | 'task'>;
+type AgentConfigSource = LegacyAgentContext & {
+    agent?: AiPromptAgent;
+    agentConfig?: AiChatAgentConfig;
+};
+/** Adapt existing flat inputs, or inherit omitted typed context only when the agent type matches. */
+export declare function resolveAiChatAgentConfig(source: AgentConfigSource, previous?: AiChatAgentConfig): AiChatAgentConfig;
+/** Clear inactive legacy fields so a typed configuration cannot leak another agent's context. */
+export declare function agentRequestContext(config: AiChatAgentConfig): LegacyAgentContext;
+export {};

package/components/ai-chat/helpers/elicitation-template.d.ts

@@ -0,0 +1,18 @@
+import '@luzmo/lucero/question-box';
+import type { QuestionBoxResultDetail } from '@luzmo/lucero/question-box';
+import type { ChatMessage } from '../../../types';
+/**
+ * - `open`: the latest question, waiting for an answer.
+ * - `answered`: an answer was sent; shown read-only.
+ * - `closed`: not answerable, because the conversation moved on, a response is generating or the chat is disabled.
+ */
+export type ElicitationState = 'open' | 'answered' | 'closed';
+export interface ElicitationMarkupArgs {
+    message: ChatMessage;
+    state: ElicitationState;
+    onSubmit: (event: CustomEvent<QuestionBoxResultDetail>) => void;
+}
+/** Reads the chosen option from a question box `luzmo-submit` event. */
+export declare function readElicitationAnswer(detail: QuestionBoxResultDetail): string | undefined;
+/** Renders the agent question on an assistant message as a single-choice question box. */
+export declare function elicitationMarkup({ message, state, onSubmit }: ElicitationMarkupArgs): unknown;

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-interaction-textarea-Crcz4rCV.cjs"),t=require("../ai-chat-7kHoMVeu.cjs");exports.AI_PROMPT_ACCEPTED_IMAGE_MIME_TYPES=e.c,exports.AI_PROMPT_MAX_ATTACHMENTS=e.l,exports.AiChatSession=t.i,exports.AiChatSessionController=t.r,exports.LuzmoAiChat=t.n,exports.LuzmoAiChatEmptyState=t.E,exports.assertValidAiPromptAttachmentFiles=e.u,exports.assertValidAiPromptAttachmentUrls=e.d,exports.blobToBase64=e.n,exports.buildAiDictationRequest=e.r,exports.buildAiPromptDeleteRequest=t._,exports.buildAiPromptProperties=t.v,exports.buildAiPromptRequest=t.y,exports.buildAnalystAiPromptProperties=t.b,exports.buildDashboardAiPromptProperties=t.x,exports.buildItemAiPromptProperties=t.S,exports.buildSavedAgentAiPromptProperties=t.C,exports.chartToItemAsset=t.w,exports.createAiChatSession=t.a,exports.createInitialProgress=t.f,exports.createInitialStreamState=t.o,exports.createStreamHandler=t.s,exports.extractChartFromChunk=t.u,exports.extractDashboardFromChunk=t.d,exports.fetchStreamingResponse=t.m,exports.getAgentStreamDefinition=t.c,exports.getAiDictationUrl=e.i,exports.getAiPromptUrl=t.T,exports.getUploadUrl=e.o,exports.hasProgressChunk=t.p,exports.isAiPromptAcceptedImageFile=e.f,exports.isAiPromptAcceptedImageMimeType=e.p,exports.isAiPromptAcceptedImageUrl=e.m,exports.isRecognizedStep=t.t,exports.parseStreamLine=t.h,exports.processStreamChunk=t.l,exports.readNdjsonStream=t.g,exports.streamAiDictation=e.a,exports.uploadAiPromptImages=e.s;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../ai-interaction-textarea-B6tZgh5k.cjs"),t=require("../ai-chat-CG-eIiBr.cjs");exports.AI_PROMPT_ACCEPTED_IMAGE_MIME_TYPES=e.c,exports.AI_PROMPT_MAX_ATTACHMENTS=e.l,exports.AiChatSession=t.i,exports.AiChatSessionController=t.r,exports.LuzmoAiChat=t.n,exports.LuzmoAiChatEmptyState=t.D,exports.assertValidAiPromptAttachmentFiles=e.u,exports.assertValidAiPromptAttachmentUrls=e.d,exports.blobToBase64=e.n,exports.buildAiDictationRequest=e.r,exports.buildAiPromptDeleteRequest=t._,exports.buildAiPromptProperties=t.v,exports.buildAiPromptRequest=t.y,exports.buildAnalystAiPromptProperties=t.b,exports.buildCustomItemAiPromptProperties=t.x,exports.buildDashboardAiPromptProperties=t.S,exports.buildItemAiPromptProperties=t.C,exports.buildSavedAgentAiPromptProperties=t.w,exports.chartToItemAsset=t.T,exports.createAiChatSession=t.a,exports.createInitialProgress=t.f,exports.createInitialStreamState=t.o,exports.createStreamHandler=t.s,exports.extractChartFromChunk=t.u,exports.extractDashboardFromChunk=t.d,exports.fetchStreamingResponse=t.m,exports.getAgentStreamDefinition=t.c,exports.getAiDictationUrl=e.i,exports.getAiPromptUrl=t.E,exports.getUploadUrl=e.o,exports.hasProgressChunk=t.p,exports.isAiPromptAcceptedImageFile=e.f,exports.isAiPromptAcceptedImageMimeType=e.p,exports.isAiPromptAcceptedImageUrl=e.m,exports.isRecognizedStep=t.t,exports.parseStreamLine=t.h,exports.processStreamChunk=t.l,exports.readNdjsonStream=t.g,exports.streamAiDictation=e.a,exports.uploadAiPromptImages=e.s;

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

@@ -4,7 +4,7 @@ declare global {
         'luzmo-ai-chat': LuzmoAiChat;
     }
 }
-export type { ProgressTreeNode, AssistantMessageAction, AssistantMessageActionConfirmVariant, AssistantMessageActionEventDetail, AiChatMessageSentEventDetail, AiChatDatasetsChangedEventDetail, AiChatConversationIdChangedEventDetail } from '../../types/ai-chat.types';
+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';
@@ -12,6 +12,7 @@ export { AiChatSession, AiChatSessionController, createAiChatSession } from './s
 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';

package/components/ai-chat/index.js

@@ -24,6 +24,6 @@
 		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: color-mix(in oklch, var(--luzmo-border-color-full), black 25%);--luzmo-border-color-full-down: color-mix(in oklch, var(--luzmo-border-color-full), black 45%);--luzmo-border-color-full-focus: color-mix(in oklch, var(--luzmo-border-color-full), black 25%);--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: color-mix( in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 5%), black 1.5% );--luzmo-background-color-down: color-mix(in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 7%), black 1%);--luzmo-background-color-focus: color-mix( in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 5%), black 1.5% );--luzmo-background-color-highlight: rgb(240, 240, 240);--luzmo-background-color-highlight-disabled: rgb(245, 245, 245);--luzmo-background-color-highlight-hover: color-mix(in oklch, var(--luzmo-background-color-highlight), black 10%);--luzmo-background-color-highlight-down: color-mix(in oklch, var(--luzmo-background-color-highlight), black 20%);--luzmo-background-color-highlight-focus: color-mix(in oklch, var(--luzmo-background-color-highlight), black 10%);--luzmo-background-color-alt-1: rgb(250, 250, 250);--luzmo-background-color-alt-2: rgb(239, 239, 239);--luzmo-border-width: 1px;--luzmo-shadow-color-rgb: 0, 0, 0;--luzmo-shadow-opacity: 0.1;--luzmo-shadow-color: rgba(var(--luzmo-shadow-color-rgb), var(--luzmo-shadow-opacity));--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: color-mix(in oklch, var(--luzmo-font-color), black 8%);--luzmo-font-color-down: color-mix(in oklch, var(--luzmo-font-color), black 20%);--luzmo-font-color-focus: color-mix(in oklch, var(--luzmo-font-color), black 8%);--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: color-mix(in oklch, var(--luzmo-primary), black 8%);--luzmo-primary-down: color-mix(in oklch, var(--luzmo-primary), black 20%);--luzmo-primary-focus: color-mix(in oklch, var(--luzmo-primary), black 8%);--luzmo-primary-inverse-color: #ffffff;--luzmo-primary-rgb: 68, 52, 255;--luzmo-secondary: #ff00ff;--luzmo-secondary-hover: color-mix(in oklch, var(--luzmo-secondary), black 8%);--luzmo-secondary-down: color-mix(in oklch, var(--luzmo-secondary), black 20%);--luzmo-secondary-focus: color-mix(in oklch, var(--luzmo-secondary), black 8%);--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: color-mix(in oklch, var(--luzmo-negative-color), black 8%);--luzmo-negative-color-down: color-mix(in oklch, var(--luzmo-negative-color), black 20%);--luzmo-negative-color-focus: color-mix(in oklch, var(--luzmo-negative-color), black 8%);--luzmo-negative-color-rgb: 202, 34, 28;--luzmo-positive-color: rgb(20, 150, 101);--luzmo-positive-color-hover: color-mix(in oklch, var(--luzmo-positive-color), black 8%);--luzmo-positive-color-down: color-mix(in oklch, var(--luzmo-positive-color), black 20%);--luzmo-positive-color-focus: color-mix(in oklch, var(--luzmo-positive-color), black 8%);--luzmo-positive-color-rgb: 20, 150, 101;--luzmo-selected-color: rgb(110, 110, 110);--luzmo-selected-color-hover: color-mix(in oklch, var(--luzmo-selected-color), black 25%);--luzmo-selected-color-down: color-mix(in oklch, var(--luzmo-selected-color), black 45%);--luzmo-selected-color-focus: color-mix(in oklch, var(--luzmo-selected-color), black 25%);--luzmo-selected-color-hard: #1e1e1e;--luzmo-selected-color-hard-hover: color-mix(in oklch, var(--luzmo-selected-color-hard), black 25%);--luzmo-selected-color-hard-down: color-mix(in oklch, var(--luzmo-selected-color-hard), black 45%);--luzmo-selected-color-hard-focus: color-mix(in oklch, var(--luzmo-selected-color-hard), black 25%);--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, 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-BbVH-aF4.js";
-import { C as p, E as m, S as h, T as g, _, a as v, b as y, c as b, d as x, f as S, g as C, h as w, i as T, l as E, m as D, n as O, o as k, p as A, r as j, s as M, t as N, u as P, v as F, w as I, x as L, y as R } from "../ai-chat-CI9l8ZOE.js";
-export { t as AI_PROMPT_ACCEPTED_IMAGE_MIME_TYPES, a as AI_PROMPT_MAX_ATTACHMENTS, T as AiChatSession, j as AiChatSessionController, O as LuzmoAiChat, m as LuzmoAiChatEmptyState, f as assertValidAiPromptAttachmentFiles, n as assertValidAiPromptAttachmentUrls, s as blobToBase64, u as buildAiDictationRequest, _ as buildAiPromptDeleteRequest, F as buildAiPromptProperties, R as buildAiPromptRequest, y as buildAnalystAiPromptProperties, L as buildDashboardAiPromptProperties, h as buildItemAiPromptProperties, p as buildSavedAgentAiPromptProperties, I as chartToItemAsset, v as createAiChatSession, S as createInitialProgress, k as createInitialStreamState, M as createStreamHandler, P as extractChartFromChunk, x as extractDashboardFromChunk, D as fetchStreamingResponse, b as getAgentStreamDefinition, i as getAiDictationUrl, g as getAiPromptUrl, c as getUploadUrl, A as hasProgressChunk, r as isAiPromptAcceptedImageFile, l as isAiPromptAcceptedImageMimeType, o as isAiPromptAcceptedImageUrl, N as isRecognizedStep, w as parseStreamLine, E as processStreamChunk, C as readNdjsonStream, e as streamAiDictation, d as uploadAiPromptImages };
+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-D9g9G0T1.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-CMc_9Oo2.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

@@ -22,6 +22,8 @@ export declare class AiChatSessionController {
     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;
@@ -43,6 +45,7 @@ export declare class AiChatSessionController {
     /**
      * 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;

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

@@ -2,10 +2,15 @@ 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, AiPromptCreateBody, AiPromptDeleteBody, AiPromptItemTask, AiPromptScreenMode, BuildAiPromptRequestContext, DashboardStatePayload, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from '../ai-prompt-types';
+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 {
-    agent: AiPromptAgent;
+    /** 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;
@@ -15,6 +20,8 @@ export interface AiChatSessionConfig {
     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;
@@ -88,8 +95,17 @@ export interface AiChatSessionSubmitParams {
     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}. */
+    /**
+     * 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;

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

@@ -1,6 +1,7 @@
 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.
@@ -36,6 +37,8 @@ export declare class AiChatSession {
     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.
@@ -54,7 +57,9 @@ export declare class AiChatSession {
     removeDataset(datasetId: string): void;
     isDatasetRequirementMet(agentId?: string): boolean;
     getAiPromptUrl(): string;
-    buildRequestBody(prompt: string, datasetIds: string[], attachmentUrls?: string[], agentId?: string | undefined): AiPromptCreateBody;
+    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;
@@ -64,6 +69,7 @@ export declare class AiChatSession {
         attachments?: PromptBoxAttachment[];
         attachmentUrls?: string[];
         agentId?: string;
+        internal?: boolean;
     }): LuzmoPromptSubmittedEventDetail;
     /** Prefer provided URLs; otherwise upload via host callback or built-in `/upload`. */
     private _resolveAttachmentUrls;
@@ -72,6 +78,15 @@ export declare class AiChatSession {
      * 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;
@@ -97,6 +112,7 @@ export declare class AiChatSession {
     private _emit;
     private _invokeCallback;
     private _patchState;
+    private _notifySubscribers;
     private _areSelectedDatasetsEqual;
     private _areChatMessagesEqual;
 }

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

@@ -6,7 +6,7 @@
  * 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 { 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;
@@ -25,3 +25,5 @@ export declare function extractDashboardName(assets: unknown[]): Record<string,
 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

@@ -32,6 +32,7 @@
  *
  * - **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`)

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

@@ -1,7 +1,7 @@
 import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
 import type { ChatMessage } from '../../../types';
 import type { AiChatCompleteEvent, AiChatStepEvent } from '../ai-chat-events';
-import type { AiPromptAgent, DashboardStatePayload } from '../ai-prompt-types';
+import type { AiPromptAgent, AiPromptCustomItemInput, DashboardStatePayload } from '../ai-prompt-types';
 export interface StreamHandlerCallbacks {
     onConversationIdChange: (conversationId: string) => void;
     onProgress: (progress: ProgressTreeNode) => void;
@@ -32,6 +32,8 @@ export interface StreamHandlerState {
     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. */
@@ -52,4 +54,6 @@ export interface AgentStreamDefinition {
     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;
+};