udi-yac 0.1.1 → 0.1.2

package/README.md

@@ -80,6 +80,11 @@ import 'udi-yac/style.css';
 | `authToken`        | `string?`            | JWT bearer token for API auth                                                                                   |
 | `requireApiKey`    | `boolean?`           | Show API key input before chatting                                                                              |
 | `model`            | `string?`            | LLM model name override                                                                                         |
+| `downloadActions`  | `DownloadAction[]?`  | Extra items appended to the Download Data dropdown. See [Custom download actions](#custom-download-actions).    |
+| `entityIcons`      | `EntityIconMap?`     | Icon overrides for entity count chips. See [Custom entity icons](#custom-entity-icons).                         |
+| `mascot`           | `ReactNode \| null?` | Replace or hide the welcome mascot. See [Custom mascot](#custom-mascot).                                        |
+| `splashMessages`   | `readonly string[]?` | Override or hide the randomised prompt above the mascot. See [Custom splash messages](#custom-splash-messages). |
+| `onEvent`          | `TrackerFn?`         | Analytics callback invoked on key user actions. See [Analytics events](#analytics-events).                      |
 | `className`        | `string?`            | CSS class for the root element                                                                                  |
 | `style`            | `CSSProperties?`     | Inline styles for the root element                                                                              |
 
@@ -215,9 +220,166 @@ See [`src/data/hubmapRemote.ts`](src/data/hubmapRemote.ts) for the canonical inl
 ### Data Management
 
 - **Entity counts**: per-entity row counts with dynamic filtered counts
-- **Download**: filtered data as ZIP of CSVs, or manifest (hubmap_id extraction)
+- **Download**: filtered data as ZIP of CSVs, or manifest (hubmap_id extraction). Consumers can extend the dropdown with custom actions via the `downloadActions` prop — see [Custom download actions](#custom-download-actions).
 - Data package loading with domain computation (Arquero)
 
+### Custom download actions
+
+Pass `downloadActions` on `UDIChatConfig` to append consumer-specific entries to the Download Data dropdown. Each action's `onClick` receives a snapshot of the current filters and the per-source rows the built-in "Download Raw Data" would have used, so you can export to custom formats, post to an API, or route to another tool.
+
+```tsx
+import { UDIChat } from 'udi-yac';
+import type { DownloadAction } from 'udi-yac';
+
+const sendToWorkspaces: DownloadAction = {
+  label: 'Open in Workspaces',
+  disabled: (ctx) => ctx.rowsBySource.every((r) => r.rows.length === 0),
+  onClick: async ({ rowsBySource, filters }) => {
+    const ids = rowsBySource.flatMap(({ rows }) =>
+      rows.map((r) => String(r['hubmap_id'] ?? '')).filter(Boolean),
+    );
+    await fetch('/api/workspaces', {
+      method: 'POST',
+      body: JSON.stringify({ ids, filters }),
+    });
+  },
+};
+
+<UDIChat apiBaseUrl="http://localhost:8007" downloadActions={[sendToWorkspaces]} />;
+```
+
+The `DownloadActionContext` passed to each callback contains:
+
+| Field          | Type                                | Notes                                                              |
+| -------------- | ----------------------------------- | ------------------------------------------------------------------ |
+| `rowsBySource` | `{ source: string; rows: Row[] }[]` | Post-filter, post-brush rows — same data the built-in ZIP exports. |
+| `filters`      | `DataSelections`                    | Active filter selections keyed by filter id.                       |
+| `dataPackage`  | `DataPackage \| null`               | The loaded data package; null until first resolution completes.    |
+
+Custom actions render after the two built-in items, separated by a divider.
+
+### Custom entity icons
+
+Pass `entityIcons` on `UDIChatConfig` to change the icon rendered on each entity count chip in the dashboard header. Keys are entity names exactly as they appear in the data package (`resources[].name`). Any component that accepts a `className` prop works — lucide-react icons are typical.
+
+```tsx
+import { UDIChat } from 'udi-yac';
+import type { EntityIconMap } from 'udi-yac';
+import { Dna, FlaskConical } from 'lucide-react';
+
+const icons: EntityIconMap = {
+  // Override the default icon for an existing entity:
+  samples: FlaskConical,
+  // Add an icon for a custom entity:
+  sequencing_runs: Dna,
+};
+
+<UDIChat apiBaseUrl="http://localhost:8007" entityIcons={icons} />;
+```
+
+Consumer entries are merged on top of the built-in icons (`donors`, `samples`, `datasets`, …) — you only need to supply the names you want to override or add. Entities with no match fall back to a generic table icon.
+
+### Custom mascot
+
+The empty-dashboard welcome splash renders a YAC mascot by default. Consumers can replace it or hide it via the `mascot` prop on `UDIChatConfig`:
+
+| Value              | Result                                                                 |
+| ------------------ | ---------------------------------------------------------------------- |
+| `undefined` (omit) | Renders the built-in YAC mascot image.                                 |
+| `null`             | Hides the mascot entirely. The speech-bubble prompt above still shows. |
+| Any `ReactNode`    | Renders the provided node in place of the mascot image.                |
+
+```tsx
+import { UDIChat } from 'udi-yac';
+
+// Replace with a custom image:
+<UDIChat
+  apiBaseUrl="http://localhost:8007"
+  mascot={<img src="/my-mascot.svg" alt="" className="w-60 h-60 object-contain" />}
+/>
+
+// Hide entirely:
+<UDIChat apiBaseUrl="http://localhost:8007" mascot={null} />
+```
+
+### Custom splash messages
+
+One prompt is picked at random from a built-in pool (`"Ask me for a visualization!"`, `"What data would you like to explore?"`, etc.) and shown in the speech bubble above the mascot. Override via `splashMessages` on `UDIChatConfig`:
+
+| Value              | Result                                                 |
+| ------------------ | ------------------------------------------------------ |
+| `undefined` (omit) | Random pick from the built-in defaults.                |
+| Non-empty array    | Random pick from the provided strings exclusively.     |
+| `[]`               | Hides the speech bubble entirely (mascot still shows). |
+
+```tsx
+<UDIChat
+  apiBaseUrl="http://localhost:8007"
+  splashMessages={[
+    'Ask me about donors, samples, or datasets.',
+    'Try “average age by sex”.',
+  ]}
+/>
+
+// Hide the speech bubble:
+<UDIChat apiBaseUrl="http://localhost:8007" splashMessages={[]} />
+```
+
+The selection is made once per `UDIChat` mount, so the message doesn't flicker between renders.
+
+### Analytics events
+
+Pass an `onEvent` callback on `UDIChatConfig` to receive events for key user actions. The signature —
+
+```ts
+type TrackerFn = (name: string, properties?: Record<string, unknown>) => void;
+```
+
+— matches the call shape of every major analytics tool, so it can usually be forwarded directly:
+
+```tsx
+import { UDIChat } from 'udi-yac';
+import type { TrackerFn } from 'udi-yac';
+
+// Google Analytics 4 (via gtag):
+const track: TrackerFn = (name, props) => window.gtag?.('event', name, props);
+
+// Segment / Amplitude / PostHog:
+// const track: TrackerFn = (name, props) => window.analytics?.track(name, props);
+
+<UDIChat apiBaseUrl="http://localhost:8007" onEvent={track} />;
+```
+
+Event names are stable, snake_case strings. **Properties carry metadata only — never raw message content or OpenAI key material.** If the callback throws, the error is swallowed so an analytics failure never breaks the chat.
+
+**Correlation ids.** Every event carries a `sessionId` (minted once per `UDIChat` mount) so all events from one chat instance can be stitched together and two tabs can be told apart. A subset of events — the ones bound to a single send↔response round trip — also carries a shared `turnId`, making it trivial to match a `message_sent` to the `response_received`, `rebuff_received`, or `request_failed` it produced. A retry after entering an API key reuses the original `turnId` so the retry's response still pairs back to the originating send.
+
+| Event                      | Fired when                                                                                      | Properties                                                                                                                                                                                                                                                   |
+| -------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `message_sent`             | User submits a message through the chat input                                                   | `turnId: string`<br>`charCount: number` — length of the text, not the text itself<br>`conversationLength: number` — messages already in the conversation when this one was added<br>`hasUserApiKey: boolean` — whether the request will carry the user's key |
+| `response_received`        | Server completes a `/v1/yac/completions` call (including rebuffs)                               | `turnId: string` — matches the originating `message_sent`<br>`durationMs: number`<br>`toolCallNames: string[]` — e.g. `["RenderVisualization", "FreeTextExplain"]`<br>`toolCallCount: number`<br>`hadUserKey: boolean`<br>`hasRebuff: boolean`               |
+| `rebuff_received`          | The response contains a `Rebuff` tool_call                                                      | `turnId: string`<br>`reason?: string` — machine-readable discriminator; `"budget_exceeded"` for quota rebuffs, absent for ordinary rebuffs<br>`hadUserKey: boolean`                                                                                          |
+| `request_failed`           | `/v1/yac/completions` throws (network error, HTTP !ok)                                          | `turnId: string`<br>`durationMs: number`<br>`hadUserKey: boolean`                                                                                                                                                                                            |
+| `api_key_set`              | User submits a key through the `ApiKeyInput`                                                    | `inResponseToQuota: boolean` — true if a budget-exceeded rebuff had triggered the prompt (distinguishes first-time entry from quota-recovery entry)                                                                                                          |
+| `api_key_cleared`          | User clears their stored key via the header icon                                                | _(none)_                                                                                                                                                                                                                                                     |
+| `conversation_reset`       | User clicks the Reset button (clears messages, pinned viz, filters, memory bank)                | `conversationLength: number` — message count at the moment of reset                                                                                                                                                                                          |
+| `visualization_pinned`     | A new visualization is auto-pinned from an assistant response                                   | `hasTitle: boolean`<br>`toolCallIndex: number` — position within the assistant message's tool_calls                                                                                                                                                          |
+| `visualization_closed`     | User clicks the × on a pinned visualization card                                                | `hasTitle: boolean`                                                                                                                                                                                                                                          |
+| `download_raw_data`        | User clicks "Download Raw Data" in the Download Data dropdown                                   | `sources: number` — count of sources contributing rows<br>`rowsTotal: number`                                                                                                                                                                                |
+| `download_manifest`        | User clicks "Download Manifest"                                                                 | `idsTotal: number` — count of `hubmap_id` values in the exported manifest                                                                                                                                                                                    |
+| `download_<slug>`          | User clicks a custom `downloadActions` entry                                                    | `label: string` — the original menu label                                                                                                                                                                                                                    |
+| `filter_range_changed`     | User commits a new range on a quantitative (interval) filter slider, including the reset button | `entity: string`<br>`field: string`<br>`isReset: boolean` — true when triggered by the reset button<br>`isFullRange: boolean` — true when the new range covers the full domain                                                                               |
+| `filter_selection_changed` | User toggles a checkbox or clicks "Clear all" on a categorical (point) filter                   | `entity: string`<br>`field: string`<br>`action: 'toggle' \| 'clear_all'`<br>`checked?: boolean` — present only when `action === 'toggle'`<br>`selectionCount: number` — count of selected values after the change (no values themselves)                     |
+| `filter_entity_changed`    | User changes the target entity on a tweakable filter card                                       | `filterType: 'interval' \| 'point'`<br>`entity: string` — the newly selected entity<br>`field: string` — the field carried over to the new entity (may be empty)                                                                                             |
+| `filter_field_changed`     | User changes the target field on a tweakable filter card                                        | `filterType: 'interval' \| 'point'`<br>`entity: string`<br>`field: string` — the newly selected field                                                                                                                                                        |
+| `visualization_tweaked`    | User swaps the field bound to an encoding via a `VizTweakComponent` dropdown                    | `encoding: string` — the encoding channel (e.g. `"x"`, `"color"`)                                                                                                                                                                                            |
+
+Every row in the table above also includes `sessionId: string`; it's omitted from the per-event cells to keep the table scannable.
+
+**Custom download slug.** The suffix is derived from the action's `label`: a leading `"Download "` is stripped, the rest is lowercased and non-alphanumeric runs are replaced with `_`. So a `{ label: "Download All TSVs" }` action emits `download_all_tsvs`; `{ label: "Open in Workspaces" }` emits `download_open_in_workspaces`. The original label is always echoed back in `properties.label` so consumers can distinguish collisions.
+
+**Properties you will _not_ see.** By design, the following never cross the tracker boundary: raw message text, tool_call `arguments`, OpenAI API keys, data rows, filter values. Only counts, booleans, tool-call names, ids, and short slug strings are emitted.
+
 ### Debug Mode (type `!/admin` in chat)
 
 - System prompts toggle (show/hide system messages)

package/dist/app/UDIChatConfig.d.ts

@@ -1,4 +1,16 @@
+import { ReactNode } from 'react';
 import { DataPackage, DataFieldDomain } from '../types/dataPackage';
+import { DownloadAction, EntityIconMap } from '../features/dashboard';
+/**
+ * Signature for the optional analytics callback — deliberately untyped in
+ * the `properties` bag so consumers can forward directly to GA4, Segment,
+ * Amplitude, PostHog, or any other tool that accepts
+ * `(eventName, properties)`.
+ *
+ * Event names are stable, snake_case strings. Properties carry metadata
+ * only — never raw message content or API key material.
+ */
+export type TrackerFn = (name: string, properties?: Record<string, unknown>) => void;
 /**
  * Public configuration surface for the `UDIChat` root component. Extracted
  * from UDIChat.tsx so that `validateConfig` and other app-layer utilities
@@ -18,6 +30,51 @@ export interface UDIChatConfig {
     /** If true, prompt the user to enter an OpenAI API key before chatting. */
     requireApiKey?: boolean;
     model?: string;
+    /**
+     * Extra items to append to the Download Data dropdown. Each action's
+     * `onClick` receives a {@link DownloadActionContext} snapshot of the
+     * current filters and per-source rows, so consumers can export, route,
+     * or post-process that data in consumer-specific ways. Rendered after
+     * the built-in "Download Raw Data" and "Download Manifest" items,
+     * separated by a divider.
+     */
+    downloadActions?: readonly DownloadAction[];
+    /**
+     * Map from entity name (as it appears in the data package `resources[].name`)
+     * to an icon component. Merged on top of the built-in icons (donors,
+     * samples, datasets, …) with consumer entries winning, so you can supply
+     * icons for additional entities or override the defaults. Any component
+     * that accepts a `className` prop works — lucide-react icons are typical.
+     */
+    entityIcons?: EntityIconMap;
+    /**
+     * Controls the mascot rendered on the empty-dashboard splash:
+     * - `undefined` (prop omitted): the default YAC mascot image is rendered.
+     * - `null`: the mascot is hidden entirely.
+     * - any other ReactNode: the provided node is rendered in place of the mascot.
+     *
+     * The speech-bubble prompt above the mascot is not affected by this prop.
+     */
+    mascot?: ReactNode | null;
+    /**
+     * Override the randomised prompts shown in the speech bubble above the
+     * mascot on the empty-dashboard splash.
+     * - `undefined` (prop omitted): use the built-in defaults.
+     * - A non-empty array: pick one of the provided messages at random.
+     * - An empty array (`[]`): hide the speech bubble entirely.
+     */
+    splashMessages?: readonly string[];
+    /**
+     * Optional analytics callback. When provided, UDIChat emits events for
+     * key user actions (messages sent, responses received, rebuffs, API key
+     * changes, visualization pin/close, conversation reset, downloads).
+     *
+     * Callbacks carry metadata only — never raw message content or OpenAI
+     * key material — and thrown errors are swallowed so an analytics failure
+     * never breaks the chat. See the "Analytics events" section of the
+     * README for the full event catalog and the properties each one emits.
+     */
+    onEvent?: TrackerFn;
     className?: string;
     style?: React.CSSProperties;
 }

package/dist/app/UDIChatContext.d.ts

@@ -1,5 +1,7 @@
 import { ReactNode } from 'react';
 import { StoreApi } from 'zustand';
+import { DownloadAction, EntityIconMap } from '../features/dashboard';
+import { TrackerFn } from './UDIChatConfig';
 import { ConversationState } from '../features/chat/stores/conversationStore';
 import { DashboardState } from '../features/dashboard/stores/dashboardStore';
 import { DataPackageState } from '../features/data-package/stores/dataPackageStore';
@@ -24,3 +26,30 @@ export declare function useMemoryBank<T>(selector: (state: MemoryBankState) => T
 export declare function useMemoryBankStore(): StoreApi<MemoryBankState>;
 export declare function useGlobal<T>(selector: (state: GlobalState) => T): T;
 export declare function useGlobalStore(): StoreApi<GlobalState>;
+export declare function DownloadActionsProvider({ actions, children, }: {
+    actions: readonly DownloadAction[] | undefined;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useDownloadActions(): readonly DownloadAction[];
+export declare function EntityIconsProvider({ icons, children, }: {
+    icons: EntityIconMap | undefined;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useEntityIcons(): EntityIconMap;
+type MascotValue = ReactNode | null | undefined;
+export declare function MascotProvider({ mascot, children }: {
+    mascot: MascotValue;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useMascot(): MascotValue;
+export declare function SplashMessagesProvider({ messages, children, }: {
+    messages: readonly string[] | undefined;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useSplashMessages(): readonly string[] | undefined;
+export declare function TrackerProvider({ onEvent, children, }: {
+    onEvent: TrackerFn | undefined;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useTracker(): TrackerFn;
+export {};

package/dist/components/ui/badge.d.ts

@@ -1,7 +1,7 @@
 import { useRender } from '@base-ui/react/use-render';
 import { VariantProps } from 'class-variance-authority';
 declare const badgeVariants: (props?: ({
-    variant?: "default" | "link" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
+    variant?: "default" | "outline" | "secondary" | "ghost" | "destructive" | "link" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<'span'> & VariantProps<typeof badgeVariants>): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export { Badge, badgeVariants };

package/dist/components/ui/button.d.ts

@@ -1,8 +1,9 @@
 import { Button as ButtonPrimitive } from '@base-ui/react/button';
 import { VariantProps } from 'class-variance-authority';
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "link" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
+    variant?: "default" | "outline" | "secondary" | "ghost" | "destructive" | "link" | null | undefined;
     size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
-declare function Button({ className, variant, size, ...props }: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>): import("react/jsx-runtime").JSX.Element;
+type ButtonProps = ButtonPrimitive.Props & VariantProps<typeof buttonVariants>;
+declare const Button: import('react').ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
 export { Button, buttonVariants };

package/dist/features/chat/components/ChatPanel.d.ts

@@ -3,11 +3,16 @@ interface ChatPanelProps {
     config: QueryConfig;
     needsApiKey: boolean;
     hasApiKey: boolean;
+    userKeyQuotaExceeded: boolean;
+    pendingQuotaRetry: boolean;
     onSetApiKey: (key: string) => void;
     onClearApiKey: () => void;
+    onQuotaRebuff: (hadUserKey: boolean) => void;
+    onNormalResponse: () => void;
+    onConsumePendingRetry: () => void;
     showDrawerToggle?: boolean;
     drawerOpen?: boolean;
     onToggleDrawer?: () => void;
 }
-export declare function ChatPanel({ config, needsApiKey, hasApiKey, onSetApiKey, onClearApiKey, showDrawerToggle, onToggleDrawer, }: ChatPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatPanel({ config, needsApiKey, hasApiKey, userKeyQuotaExceeded, pendingQuotaRetry, onSetApiKey, onClearApiKey, onQuotaRebuff, onNormalResponse, onConsumePendingRetry, showDrawerToggle, onToggleDrawer, }: ChatPanelProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/features/chat/hooks/useApiKey.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Owns all state related to the user-supplied OpenAI API key: the key
+ * itself (persisted to localStorage), the two quota flags that react to
+ * budget-exceeded rebuffs from the server, and the one-shot retry signal
+ * that fires after the user submits a key in response to a quota event.
+ *
+ * The retry effect itself lives in `ChatPanel`, because it needs
+ * `retryLastUserMessage` from `useChatApi` — see `pendingQuotaRetry` /
+ * `consumePendingRetry` for the hand-off.
+ */
+export declare function useApiKey({ requireApiKey }: {
+    requireApiKey: boolean;
+}): {
+    openAiKey: string | null;
+    needsApiKey: boolean;
+    hasApiKey: boolean;
+    userKeyQuotaExceeded: boolean;
+    pendingQuotaRetry: boolean;
+    setApiKey: (key: string) => void;
+    clearApiKey: () => void;
+    onQuotaRebuff: (hadUserKey: boolean) => void;
+    onNormalResponse: () => void;
+    consumePendingRetry: () => void;
+};

package/dist/features/chat/hooks/useChatApi.d.ts

@@ -1,6 +1,24 @@
 import { QueryConfig } from '../api/completions';
-export declare function useChatApi(config: QueryConfig): {
+interface UseChatApiOptions {
+    /**
+     * Fired when the latest assistant response is a budget-exceeded rebuff
+     * (server returns a `Rebuff` tool_call with `arguments.reason ===
+     * "budget_exceeded"`). `hadUserKey` is true iff `config.openAiKey` was
+     * present on the request, which lets the parent distinguish the
+     * server-key-exhausted case from user-key-exhausted.
+     */
+    onQuotaRebuff?: (hadUserKey: boolean) => void;
+    /**
+     * Fired on any successful response that is NOT a budget-exceeded rebuff,
+     * so the parent can clear a stale quota flag — e.g. after an admin
+     * refills the server key, the prompt should go away on its own.
+     */
+    onNormalResponse?: () => void;
+}
+export declare function useChatApi(config: QueryConfig, options?: UseChatApiOptions): {
     sendMessage: (text: string) => Promise<void>;
+    retryLastUserMessage: () => Promise<void>;
     isLoading: boolean;
     error: string | null;
 };
+export {};

package/dist/features/dashboard/index.d.ts

@@ -8,3 +8,4 @@ export { createDashboardStore, extractAllUdiSpecsFromMessage, type DashboardStat
 export { createDataFiltersStore, extractFilterSpecFromMessage, messageFilterKeyWithToolCall, messageFilterKey, type DataFiltersState, type DataSelection, type DataSelections, } from './stores/dataFiltersStore';
 export { createSelectionsStore, type SelectionsState } from './stores/selectionsStore';
 export { createMemoryBankStore, type MemoryBankState } from './stores/memoryBankStore';
+export type { DownloadAction, DownloadActionContext, EntityIconComponent, EntityIconMap, } from './types';

package/dist/features/dashboard/types.d.ts

@@ -0,0 +1,50 @@
+import { ComponentType } from 'react';
+import { DataPackage, Row } from '../../types/dataPackage';
+import { DataSelections } from './stores/dataFiltersStore';
+/**
+ * An icon component suitable for the entity count chips. Any component that
+ * accepts a `className` prop and renders an icon works — lucide-react icons
+ * are the typical choice.
+ */
+export type EntityIconComponent = ComponentType<{
+    className?: string;
+}>;
+/**
+ * Consumer-provided mapping from entity name to icon. Merged on top of the
+ * built-in defaults (donors, samples, datasets, …) so consumers can supply
+ * icons for additional entities or override existing ones.
+ */
+export type EntityIconMap = Record<string, EntityIconComponent>;
+/**
+ * Snapshot of dashboard state passed to a {@link DownloadAction}'s callbacks.
+ * The consumer reads this to decide what to export / where to send it.
+ */
+export interface DownloadActionContext {
+    /**
+     * Per-source rows reflecting the currently applied filters and brush
+     * selections — the same data the built-in "Download Raw Data" action uses.
+     */
+    rowsBySource: {
+        source: string;
+        rows: Row[];
+    }[];
+    /** Active filter selections, keyed by filter id. */
+    filters: DataSelections;
+    /** The loaded data package, or null if it hasn't resolved yet. */
+    dataPackage: DataPackage | null;
+}
+/**
+ * Consumer-configurable item appended to the Download Data dropdown.
+ * Custom items render after the built-in actions, separated by a divider.
+ */
+export interface DownloadAction {
+    /** Text shown in the menu item. */
+    label: string;
+    /** Invoked when the menu item is clicked. May be async. */
+    onClick: (ctx: DownloadActionContext) => void | Promise<void>;
+    /**
+     * When `true` (or a function returning `true`), the item is rendered as
+     * disabled. Defaults to `false`.
+     */
+    disabled?: boolean | ((ctx: DownloadActionContext) => boolean);
+}

package/dist/features/tool-calls/types.d.ts

@@ -5,9 +5,17 @@
  * ORCHESTRATOR_TOOLS list and represent the payload the frontend receives
  * inside `tool_calls[].function.arguments`.
  */
+/**
+ * Machine-readable rebuff discriminator. Emitted by the backend only for
+ * cases the frontend needs to branch on (e.g. prompt the user for their
+ * own API key when the server key is over quota). Ordinary rebuffs omit
+ * the field — callers should treat absence as "plain rebuff".
+ */
+export type RebuffReason = 'budget_exceeded';
 export interface RebuffArgs {
     message: string;
     suggestions: string[];
+    reason?: RebuffReason;
 }
 export interface ClarifyCandidate {
     field_name: string;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { UDIChat } from './app/UDIChat';
-export type { UDIChatConfig } from './app/UDIChatConfig';
-export type { DataPackage, DataPackageResource, DataFieldDomain, IntervalDomain, CategoricalDomain, } from './types/dataPackage';
+export type { UDIChatConfig, TrackerFn } from './app/UDIChatConfig';
+export type { DataPackage, DataPackageResource, DataFieldDomain, IntervalDomain, CategoricalDomain, Row, } from './types/dataPackage';
+export type { DownloadAction, DownloadActionContext, EntityIconComponent, EntityIconMap, } from './features/dashboard';
 export { joinDataPath } from './features/data-package/utils/joinDataPath';
 export type { LoadingPhase } from './features/data-package/stores/dataPackageStore';

package/dist/lib/utils.d.ts

@@ -1,2 +1,8 @@
 import { ClassValue } from 'clsx';
 export declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Short unique ID suitable for analytics correlation (sessionId, turnId).
+ * Prefers `crypto.randomUUID` when available; falls back to a
+ * timestamp+random concatenation for environments without WebCrypto.
+ */
+export declare function generateEventId(): string;