@factorialco/f0-react 1.482.0 → 2.0.1

package/dist/ai.d.ts

@@ -157,6 +157,14 @@ export declare type AiChatProviderProps = {
      * Provides save/create functions for persisting canvas entities externally.
      */
     canvasActions?: CanvasActions;
+    /**
+     * Canvas entity definitions keyed by `CanvasContent["type"]`. The canvas
+     * panel looks up the matching definition when `openCanvas` is called.
+     *
+     * F0AiChat ships without built-in canvas entities; the host app supplies
+     * them here so canvas logic lives in one place.
+     */
+    canvasEntities?: Record<string, CanvasEntityDefinition>;
     /**
      * Available tool hints that the user can activate to provide intent context
      * to the AI. Renders a selector button next to the send button.
@@ -355,7 +363,7 @@ declare type AiChatProviderReturnValue = {
     pendingQuote: PendingQuote | null;
     /** Set the pending quote (pass null to clear). */
     setPendingQuote: React.Dispatch<React.SetStateAction<PendingQuote | null>>;
-} & Pick<AiChatState, "greeting" | "agent" | "disclaimer" | "resizable" | "entityRefs" | "canvasActions" | "toolHints" | "credits" | "creditWarning" | "fileAttachments"> & {
+} & Pick<AiChatState, "greeting" | "agent" | "disclaimer" | "resizable" | "entityRefs" | "canvasActions" | "canvasEntities" | "toolHints" | "credits" | "creditWarning" | "fileAttachments"> & {
     /** The current canvas content, or null when canvas is closed */
     canvasContent: CanvasContent | null;
     /** Open the canvas panel with the given content */
@@ -392,6 +400,7 @@ declare interface AiChatState {
     VoiceMode?: React.ComponentType;
     entityRefs?: EntityRefs;
     canvasActions?: CanvasActions;
+    canvasEntities?: Record<string, CanvasEntityDefinition>;
     toolHints?: AiChatToolHint[];
     credits?: AiChatCredits;
     creditWarning?: AiChatCreditWarning;
@@ -859,6 +868,36 @@ export declare type CanvasActions = {
     dashboard?: DashboardCanvasActions;
 };
 
+/**
+ * Shared inline card rendered in the AI chat for any canvas entity.
+ * Shows a module avatar, title, description, and an Open/Close toggle button.
+ * When active, displays a focus ring and the button switches to "Close".
+ */
+export declare function CanvasCard({ module: cardModule, title, description, onOpen, showOpenButton, onClose, isActive, children, }: CanvasCardProps): JSX_2.Element;
+
+export declare namespace CanvasCard {
+    var displayName: string;
+}
+
+export declare type CanvasCardProps = {
+    /** Module avatar to display (e.g. "analytics", "surveys", "goals") */
+    module?: ModuleId;
+    /** Primary title */
+    title: string;
+    /** Secondary description line */
+    description: string;
+    /** Called when the user clicks the "Open" button */
+    onOpen: () => void;
+    /** Whether to show the "Open" button */
+    showOpenButton?: boolean;
+    /** Called when the user clicks the "Close" button (active state) */
+    onClose: () => void;
+    /** Whether this card's content is currently shown in the canvas */
+    isActive: boolean;
+    /** Optional content rendered below the card header (e.g. a data preview) */
+    children?: React.ReactNode;
+};
+
 /**
  * Discriminated union for canvas panel content.
  * Add new entity types to this union as they are implemented.
@@ -972,7 +1011,7 @@ declare interface ChatDashboardColumn {
  * Contains fetchSpecs that describe how to obtain data server-side —
  * no raw data is included. Fully JSON-serializable.
  */
-declare interface ChatDashboardConfig {
+export declare interface ChatDashboardConfig {
     /** Dashboard title displayed in the canvas header and chat report card */
     title: string;
     /**
@@ -1154,7 +1193,7 @@ declare interface ClarifyingOption {
  * Navigation metadata (currentStepIndex, totalSteps) and callbacks live
  * here so the panel component stays a pure view of this state.
  */
-declare interface ClarifyingQuestionState {
+export declare interface ClarifyingQuestionState {
     /** The current step's data + interaction state */
     currentStep: ClarifyingStepState;
     /** Zero-based index of the current step */
@@ -1188,13 +1227,13 @@ declare interface ClarifyingQuestionState {
  * - "single": only one option can be selected (rendered as radio buttons)
  * - "multiple": multiple options can be selected (rendered as checkboxes)
  */
-declare type ClarifyingSelectionMode = "single" | "multiple";
+export declare type ClarifyingSelectionMode = "single" | "multiple";
 
 /**
  * Pure data describing a single clarifying question step.
  * This is what the AI backend sends — no UI state or callbacks.
  */
-declare interface ClarifyingStepData {
+export declare interface ClarifyingStepData {
     /** The question text displayed to the user */
     question: string;
     /** Available options the user can select from */
@@ -1220,6 +1259,10 @@ declare interface ClarifyingStepState extends ClarifyingStepData {
     isCustomAnswerActive: boolean;
 }
 
+export declare function CloseCanvasButton({ onClick }: {
+    onClick: () => void;
+}): JSX_2.Element;
+
 declare interface CollectionComputation {
     datasetId: string;
     sortBy?: string;
@@ -1256,7 +1299,7 @@ export declare type CSSRgbString = `rgb(${number}, ${number}, ${number})` | `rgb
 /**
  * Callbacks for persisting dashboards externally (beyond chat history).
  */
-declare type DashboardCanvasActions = {
+export declare type DashboardCanvasActions = {
     /** Update an existing saved dashboard */
     save: (id: string, category: string, config: ChatDashboardConfig) => Promise<void>;
     /**
@@ -1299,6 +1342,50 @@ export declare type DashboardCanvasContent = CanvasContentBase & {
     savedDashboardUnsaved?: boolean;
 };
 
+export declare function DashboardCanvasProvider({ content, children, }: {
+    content: DashboardCanvasContent;
+    children: ReactNode;
+}): ReactNode;
+
+/**
+ * Dashboard-specific card that wraps CanvasCard with config-store
+ * subscription logic. Re-renders when the user edits and saves
+ * the dashboard layout.
+ *
+ * All saved-dashboard state (id, category, unsaved) is passed through
+ * from the action arguments. The meta store overrides props after
+ * save/create operations so close/re-open preserves the latest state.
+ */
+export declare function DashboardCard({ config: originalConfig, apiConfig, savedDashboardId: propSavedId, savedDashboardCategory: propSavedCategory, savedDashboardDescription: propSavedDescription, savedDashboardUnsaved: propSavedUnsaved, }: DashboardCardProps): JSX_2.Element;
+
+export declare namespace DashboardCard {
+    var displayName: string;
+}
+
+export declare type DashboardCardProps = {
+    /** The original dashboard config from the agent */
+    config: ChatDashboardConfig;
+    /** API config for server-side dashboard computation */
+    apiConfig: {
+        baseUrl: string;
+        headers: Record<string, string>;
+        runtimeFetch?: typeof fetch;
+    };
+    /** Present when the dashboard is a pre-saved dashboard */
+    savedDashboardId?: string;
+    /** Category of the saved dashboard */
+    savedDashboardCategory?: string;
+    /** Description of the saved dashboard */
+    savedDashboardDescription?: string;
+    /** Whether the dashboard has unsaved changes */
+    savedDashboardUnsaved?: boolean;
+};
+
+export declare function DashboardContent({ content, refreshKey: _parentRefreshKey, }: {
+    content: DashboardCanvasContent;
+    refreshKey: number;
+}): ReactNode;
+
 declare interface DashboardFetchSpec {
     fetch: Array<{
         toolId: string;
@@ -1308,6 +1395,18 @@ declare interface DashboardFetchSpec {
     columnLabels?: Record<string, string>;
 }
 
+/**
+ * Canvas header for the dashboard entity. Layout, title, status tag,
+ * metadata strip, and the action row (export + close) are all delegated
+ * to `ResourceHeader`. The close button is just another `secondaryAction`
+ * with `hideLabel`, so the shared header component doesn't need to know
+ * about canvas-specific close affordances.
+ */
+export declare function DashboardHeader({ content, onClose, }: {
+    content: DashboardCanvasContent;
+    onClose: () => void;
+}): JSX_2.Element;
+
 /**
  * Creator + last-edited metadata for a saved dashboard. Returned by
  * `DashboardCanvasActions.getMetadata` so the header can render the author
@@ -1347,18 +1446,36 @@ declare type DashboardMetadata = {
 /**
  * Data download canvas content — renders a full data table with download options.
  */
-declare type DataDownloadCanvasContent = CanvasContentBase & {
+export declare type DataDownloadCanvasContent = CanvasContentBase & {
     type: "dataDownload";
     dataset: DataDownloadDataset;
     filename?: string;
     markdown?: string;
 };
 
+export declare function DataDownloadCard({ title: titleProp, dataset, filename, markdown, }: DataDownloadCardProps): JSX_2.Element;
+
+export declare namespace DataDownloadCard {
+    var displayName: string;
+}
+
+export declare type DataDownloadCardProps = {
+    title?: string;
+    dataset: DataDownloadDataset;
+    filename?: string;
+    markdown?: string;
+};
+
+export declare function DataDownloadContent({ content, }: {
+    content: DataDownloadCanvasContent;
+    refreshKey?: number;
+}): JSX_2.Element;
+
 /**
  * Inline dataset for client-side file generation (Excel / CSV).
  * Sent by the agent with the raw query results.
  */
-declare type DataDownloadDataset = {
+export declare type DataDownloadDataset = {
     /**
      * Column headers in display order.
      */
@@ -1384,6 +1501,16 @@ declare type DataDownloadDataset = {
     columnLabels?: Record<string, string>;
 };
 
+export declare function DataDownloadHeader({ content, onClose, }: {
+    content: DataDownloadCanvasContent;
+    onClose: () => void;
+}): JSX_2.Element;
+
+export declare function DataDownloadProvider({ content, children, }: {
+    content: DataDownloadCanvasContent;
+    children: ReactNode;
+}): JSX_2.Element;
+
 declare const DataList: ForwardRefExoticComponent<DataListProps & RefAttributes<HTMLUListElement>> & {
     Item: ForwardRefExoticComponent<ItemProps & RefAttributes<HTMLLIElement>>;
     CompanyItem: ForwardRefExoticComponent<CompanyItemProps & RefAttributes<HTMLLIElement>>;
@@ -2315,7 +2442,7 @@ export declare const F0AiChat: () => JSX_2.Element | null;
 /**
  * @experimental This is an experimental component use it at your own risk
  */
-export declare const F0AiChatProvider: ({ enabled, greeting, initialMessage, welcomeScreenSuggestions, disclaimer, resizable, defaultVisualizationMode, lockVisualizationMode, historyEnabled, footer, VoiceMode, entityRefs, canvasActions, toolHints, credits, creditWarning, fileAttachments, onThumbsUp, onThumbsDown, onBeforeSendMessage, runtimeFetch, children, agent, tracking, ...copilotKitProps }: AiChatProviderProps) => JSX_2.Element;
+export declare const F0AiChatProvider: ({ enabled, greeting, initialMessage, welcomeScreenSuggestions, disclaimer, resizable, defaultVisualizationMode, lockVisualizationMode, historyEnabled, footer, VoiceMode, entityRefs, canvasActions, canvasEntities, toolHints, credits, creditWarning, fileAttachments, onThumbsUp, onThumbsDown, onBeforeSendMessage, runtimeFetch, children, agent, tracking, ...copilotKitProps }: AiChatProviderProps) => JSX_2.Element;
 
 export declare const F0AiChatTextArea: ({ submitLabel, inProgress, onSend, onStop, creditWarning, }: ChatTextareaProps) => JSX_2.Element;
 
@@ -2547,6 +2674,25 @@ declare interface F0IconProps extends SVGProps<SVGSVGElement>, VariantProps<type
     color?: "default" | "currentColor" | `#${string}` | Lowercase<NestedKeyOf<typeof f1Colors.icon>>;
 }
 
+export declare const F0MessageCreditsWarning: ({ actionHref, }: F0MessageCreditsWarningProps) => JSX_2.Element;
+
+/**
+ * Args for credits warning copilot action
+ */
+export declare interface F0MessageCreditsWarningArgs {
+    actionHref?: string;
+}
+
+/**
+ * Props for the F0MessageCreditsWarning component
+ */
+export declare interface F0MessageCreditsWarningProps {
+    /**
+     * Optional URL used by the action button.
+     */
+    actionHref?: string;
+}
+
 export declare const F0OneIcon: ForwardRefExoticComponent<Omit<F0OneIconProps, "ref"> & RefAttributes<SVGSVGElement>>;
 
 /**
@@ -2681,6 +2827,12 @@ declare interface F0TagStatusProps {
 
 declare const F0TagTeam: WithDataTestIdReturnType<ForwardRefExoticComponent<F0TagTeamProps & RefAttributes<HTMLDivElement>>>;
 
+declare type FieldMeta = {
+    label: string;
+    fieldType?: string;
+    customFieldName?: string;
+};
+
 declare type FileAvatarVariant = Extract<AvatarVariant, {
     type: "file";
 }>;
@@ -2713,13 +2865,52 @@ declare type FormatPreset = {
 /**
  * Form canvas content — renders an interactive F0Form in the canvas panel.
  */
-declare type FormCanvasContent = CanvasContentBase & {
+export declare type FormCanvasContent = CanvasContentBase & {
     type: "form";
     formName: string;
     formDescription?: string;
     formModule?: ModuleId;
 };
 
+/**
+ * Form-specific card rendered inline in the AI chat stream.
+ * Shows the active form name, description, and an Open/Close button
+ * that opens the form in the canvas panel.
+ * When field data is provided, displays a summary of field labels and values.
+ */
+export declare function FormCard({ formName, formDescription, module: formModule, cardTitle, cardDescription, fieldDescriptions, formValues, valueFormatter, }: FormCardProps): JSX_2.Element;
+
+export declare namespace FormCard {
+    var displayName: string;
+}
+
+export declare type FormCardProps = {
+    /** Unique name of the form in the registry */
+    formName: string;
+    /** Optional description shown on the card */
+    formDescription?: string;
+    /** Module avatar for the card */
+    module?: ModuleId;
+    /** Custom title override for the card (set by the AI via fillForm) */
+    cardTitle: string;
+    /** Custom description override for the card (set by the AI via fillForm) */
+    cardDescription: string;
+    /** Field label metadata from the form schema */
+    fieldDescriptions?: Record<string, FieldMeta>;
+    /** Current form values */
+    formValues?: Record<string, unknown>;
+    /**
+     * Optional callback to format a field value into a DetailsItemContent.
+     * Return `undefined` to fall back to built-in formatting.
+     */
+    valueFormatter?: FormCardValueFormatter;
+};
+
+declare type FormCardValueFormatter = (key: string, value: unknown, meta: {
+    fieldType?: string;
+    customFieldName?: string;
+}) => DetailsItemContent | DetailsItemContent[] | undefined;
+
 export declare interface FormCardValueFormatterEntry<T = unknown> {
     /** Scope to a specific form. Omit to apply to all forms. */
     formName?: string;
@@ -2737,6 +2928,24 @@ export declare function FormCardValueFormatterProvider({ children, }: {
     children: ReactNode;
 }): JSX_2.Element;
 
+/**
+ * Canvas panel content for forms.
+ * Propless — reads the active form from coagent shared state
+ * and delegates to VirtualFormContent for rendering.
+ */
+export declare function FormContent(): ReactNode;
+
+export declare namespace FormContent {
+    var displayName: string;
+}
+
+export declare function FormHeader({ title, description, module, onClose, }: {
+    title: string;
+    description?: string;
+    module?: ModuleId;
+    onClose: () => void;
+}): JSX_2.Element;
+
 declare interface GaugeComputation {
     datasetId: string;
     aggregation: AggregationType;
@@ -2746,12 +2955,6 @@ declare interface GaugeComputation {
     name?: string;
 }
 
-/**
- * Look up a canvas entity definition by content type.
- * Returns `undefined` if the type is not configured.
- */
-export declare function getCanvasEntity(type: string): CanvasEntityDefinition<any> | undefined;
-
 declare interface HeatmapComputation {
     datasetId: string;
     xAxis: string;
@@ -2817,6 +3020,16 @@ declare type Level = (typeof levels)[number];
 
 declare const levels: readonly ["info", "warning", "critical", "positive"];
 
+/**
+ * External store for saved (user-edited) dashboard configs.
+ *
+ * This lives outside React's component tree so that `F0ChatReportCard`
+ * (rendered inside CopilotKit's message list) can subscribe to changes
+ * via `useSyncExternalStore` — which works regardless of whether the
+ * React context provider is an ancestor.
+ */
+declare type Listener = () => void;
+
 export declare type MaskOptions = {
     /**
      * The width of the Mask element.
@@ -2873,6 +3086,18 @@ export declare type MaskOptions = {
     styles?: Partial<CSSStyleDeclaration>;
 };
 
+export declare const MessageSources: ({ sources }: MessageSourcesProps) => JSX_2.Element | null;
+
+/**
+ * Props for the F0MessageSources component
+ */
+export declare type MessageSourcesProps = {
+    /**
+     * Array of sources to display
+     */
+    sources: Source[];
+};
+
 declare interface MetricComputation {
     datasetId: string;
     aggregation: AggregationType;
@@ -3088,6 +3313,10 @@ export declare type OneIconSize = (typeof oneIconSizes)[number];
 
 export declare const oneIconSizes: readonly ["xs", "sm", "md", "lg"];
 
+export declare type OrchestratorThinkingResult = {
+    inGroup?: boolean;
+};
+
 declare type PathsToStringProps<T> = T extends string ? [] : {
     [K in Extract<keyof T, string>]: [K, ...PathsToStringProps<T[K]>];
 }[Extract<keyof T, string>];
@@ -3202,8 +3431,58 @@ export declare type RequisitionProfile = {
     };
 };
 
+/**
+ * Snapshot of a resolved step's answer — persisted alongside the tool args
+ * so the render can restore state without re-invoking the panel.
+ */
+export declare interface ResolvedStepAnswer {
+    /** The question text (matches the source step) */
+    question: string;
+    /** Selected option IDs at submit time */
+    selectedOptionIds: string[];
+    /** Custom free-text answer if provided */
+    customAnswer?: string;
+    /** True when the user explicitly skipped an optional step */
+    skipped?: boolean;
+    /**
+     * True when the user cancelled the flow before reaching this step.
+     * The step was therefore neither answered nor intentionally skipped —
+     * callers (e.g. the agent) should treat this as "no information".
+     */
+    cancelled?: boolean;
+}
+
+export declare const savedDashboardConfigStore: {
+    get(toolCallId: string): ChatDashboardConfig | undefined;
+    set(toolCallId: string, config: ChatDashboardConfig): void;
+    subscribe(listener: Listener): () => void;
+    getSnapshot(): number;
+};
+
 declare type SetFormCardValueFormatter = <T = unknown>(entry: FormCardValueFormatterEntry<T>) => void;
 
+/**
+ * Source object for message sources
+ */
+export declare type Source = {
+    /**
+     * Title of the source
+     */
+    title: string;
+    /**
+     * Optional link URL
+     */
+    link?: string;
+    /**
+     * Optional icon name (from @/icons/app)
+     */
+    icon?: string;
+    /**
+     * Whether to open link in new tab
+     */
+    targetBlank?: boolean;
+};
+
 export declare type SparklineDataPoint = {
     value: number;
 };
@@ -3286,10 +3565,11 @@ export declare function useAiChat(): AiChatProviderReturnValue;
 export declare function useAiChatTranslations(): AiChatTranslations;
 
 /**
- * Hook that invokes every configured copilot action factory.
- * Actions are declared in the `copilotActions` array in `registry.ts`.
+ * Hook returning the canvas entity definition for `type` from the registry
+ * supplied to `F0AiChatProvider.canvasEntities`. Returns `undefined` when no
+ * matching entity is configured.
  */
-export declare function useDefaultCopilotActions(): void;
+export declare function useCanvasEntity(type: string | undefined): CanvasEntityDefinition<any> | undefined;
 
 /**
  * Returns a resolved formatter for the given `formName`.
@@ -3306,18 +3586,6 @@ export declare function useI18n(): TranslationsType & {
     t: (key: TranslationKey, args?: Record<string, string | number>) => string;
 };
 
-/**
- * Hook to register the message sources action.
- * Attaches information sources to the assistant's response to show where the AI got its information from.
- */
-export declare const useMessageSourcesAction: () => void;
-
-/**
- * Hook to register the orchestrator thinking action.
- * Displays the orchestrator's thinking process as a non-blocking UI element.
- */
-export declare const useOrchestratorThinkingAction: () => void;
-
 /**
  * Returns a setter to register value formatters used by FormCard.
  *
@@ -3339,6 +3607,9 @@ export declare const useOrchestratorThinkingAction: () => void;
  */
 export declare function useSetFormCardValueFormatter(): SetFormCardValueFormatter;
 
+/** Read the tool call ID injected by AssistantMessage. */
+export declare const useToolCallId: () => string | undefined;
+
 /**
  * Profile data for a vacancy entity (ATS vacancy/position), resolved asynchronously
  * and displayed in the entity reference hover card.

package/dist/ai.js

@@ -1,34 +1,48 @@
-import { l as t, k as e, F as r, a as o, C as i, b as n, m as F, n as u, d as A, I as c, g as C, c as m, h, e as l, u as d, j as I, i as f, f as T } from "./F0AiChat-JWFVPdAK.js";
-import { defaultTranslations as S } from "./i18n-provider-defaults.js";
-import { A as v, e as x, F as P, c as V, d as k, b as O, a as b, f as y, o as M, u as j } from "./types-D7xpTwmC.js";
+import { d as o, l as e, k as r, F as t, a as n, C as i, b as d, m as C, n as F, e as l, h as m, I as u, g as h, c as A, i as D, u as c, j as v, f as I } from "./useDataCollectionSource-DNTWm7Va.js";
+import { defaultTranslations as b } from "./i18n-provider-defaults.js";
+import { A as S, C as T, c as p, D as P, a as w, b as x, e as H, f as M, g as V, h as k, p as j, l as y, m as O, n as q, i as z, F as B, d as E, M as L, k as W, j as G, q as J, o as K, s as N, u as Q } from "./types-1gWIB_Uz.js";
 export {
-  v as AiChatTranslationsProvider,
-  t as ChatSpinner,
-  e as F0ActionItem,
-  r as F0AiChat,
-  o as F0AiChatProvider,
+  S as AiChatTranslationsProvider,
+  o as CanvasCard,
+  e as ChatSpinner,
+  T as CloseCanvasButton,
+  p as DashboardCanvasProvider,
+  P as DashboardCard,
+  w as DashboardContent,
+  x as DashboardHeader,
+  H as DataDownloadCard,
+  M as DataDownloadContent,
+  V as DataDownloadHeader,
+  k as DataDownloadProvider,
+  r as F0ActionItem,
+  t as F0AiChat,
+  n as F0AiChatProvider,
   i as F0AiChatTextArea,
-  n as F0AiFullscreenChat,
-  x as F0AiInsightCard,
-  P as F0AiMask,
-  V as F0AuraVoiceAnimation,
-  k as F0HILActionConfirmation,
-  F as F0OneIcon,
-  u as F0OneSwitch,
-  A as FormCardValueFormatterProvider,
-  c as I18nProvider,
-  O as actionItemStatuses,
-  b as aiTranslations,
-  y as contentTypes,
-  S as defaultTranslations,
-  C as getCanvasEntity,
-  M as oneIconSizes,
-  m as useAiChat,
-  j as useAiChatTranslations,
-  h as useDefaultCopilotActions,
-  l as useFormCardValueFormatter,
-  d as useI18n,
-  I as useMessageSourcesAction,
-  f as useOrchestratorThinkingAction,
-  T as useSetFormCardValueFormatter
+  d as F0AiFullscreenChat,
+  j as F0AiInsightCard,
+  y as F0AiMask,
+  O as F0AuraVoiceAnimation,
+  q as F0HILActionConfirmation,
+  z as F0MessageCreditsWarning,
+  C as F0OneIcon,
+  F as F0OneSwitch,
+  l as FormCard,
+  m as FormCardValueFormatterProvider,
+  B as FormContent,
+  E as FormHeader,
+  u as I18nProvider,
+  L as MessageSources,
+  W as actionItemStatuses,
+  G as aiTranslations,
+  J as contentTypes,
+  b as defaultTranslations,
+  K as oneIconSizes,
+  N as savedDashboardConfigStore,
+  h as useAiChat,
+  Q as useAiChatTranslations,
+  A as useCanvasEntity,
+  D as useFormCardValueFormatter,
+  c as useI18n,
+  v as useSetFormCardValueFormatter,
+  I as useToolCallId
 };

package/dist/experimental.d.ts

@@ -522,6 +522,14 @@ declare type AiChatProviderProps = {
      * Provides save/create functions for persisting canvas entities externally.
      */
     canvasActions?: CanvasActions;
+    /**
+     * Canvas entity definitions keyed by `CanvasContent["type"]`. The canvas
+     * panel looks up the matching definition when `openCanvas` is called.
+     *
+     * F0AiChat ships without built-in canvas entities; the host app supplies
+     * them here so canvas logic lives in one place.
+     */
+    canvasEntities?: Record<string, CanvasEntityDefinition>;
     /**
      * Available tool hints that the user can activate to provide intent context
      * to the AI. Renders a selector button next to the send button.
@@ -1387,6 +1395,57 @@ declare type CanvasActions = {
     dashboard?: DashboardCanvasActions;
 };
 
+/**
+ * Base shape shared by all canvas content types.
+ * Every entity adds its own fields on top of this.
+ */
+declare type CanvasContentBase = {
+    type: string;
+    title: string;
+    description?: string;
+    toolCallId?: string;
+};
+
+/**
+ * Contract for a canvas entity type.
+ *
+ * Each entity (dashboard, survey, goal, job-posting…) implements this
+ * interface and is added to the `canvasEntities` record in `registry.ts`.
+ *
+ * To add a new entity type:
+ * 1. Create a folder in `canvas/entities/<your-entity>/`
+ * 2. Define a type extending `CanvasContentBase` in `types.ts`
+ * 3. Implement and export `CanvasEntityDefinition` in `index.tsx`
+ * 4. Add the entity to the record in `canvas/registry.ts`
+ */
+declare type CanvasEntityDefinition<T extends CanvasContentBase = CanvasContentBase> = {
+    /** Must match the `type` discriminant on the content object */
+    type: T["type"];
+    /** Renders the main body of the canvas panel */
+    renderContent: (props: {
+        content: T;
+        refreshKey: number;
+    }) => ReactNode;
+    /** Renders the full header (title, actions, close button) */
+    renderHeader: (props: {
+        content: T;
+        onClose: () => void;
+    }) => ReactNode;
+    /**
+     * Optional wrapper providing entity-scoped context around
+     * both header and body (e.g. shared edit-mode state).
+     */
+    wrapper?: (props: {
+        content: T;
+        children: ReactNode;
+    }) => ReactNode;
+    /**
+     * When true the content area uses `overflow-hidden` instead of
+     * `overflow-auto`, letting the entity manage its own scrolling.
+     */
+    overflowHidden?: boolean;
+};
+
 declare type CardAvatarVariant = AvatarVariant | {
     type: "emoji";
     emoji: string;