react-semaphor 0.1.422 → 0.1.423

package/dist/types/briefings.d.ts

@@ -1,3 +1,39 @@
+import { ColumnSizingState } from '@tanstack/react-table';
+
+declare type AggregateFunction = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+declare type AxisConfig = {
+    enabled?: boolean;
+    name?: {
+        enabled: boolean;
+        text?: string;
+        /** Font size for the axis title */
+        fontSize?: number;
+        /** Font weight for the axis title */
+        fontWeight?: 'normal' | 'bold';
+    };
+    position?: 'auto' | 'top' | 'bottom' | 'left' | 'right';
+    labels?: {
+        enabled: boolean;
+        rotation?: 'auto' | 0 | 45 | 90 | -45 | -90;
+    };
+    formatMode?: 'inherit' | 'override';
+    formatOptions?: TFormatOptions;
+    scale?: {
+        min?: number | 'auto';
+        max?: number | 'auto';
+        stepSize?: number | 'auto';
+    };
+};
+
+declare interface BaseColumn {
+    id: string;
+    name: string;
+    label?: string;
+    type: ColumnType;
+    table?: string;
+}
+
 export declare const BRIEFING_ARTIFACT_FORMATS: readonly ["markdown", "html"];
 
 export declare const BRIEFING_CONTENT_LIMITS: {
@@ -47,16 +83,11 @@ export declare type BriefingAttachment = (BriefingAttachmentBase & {
     dashboardId: string;
     sheetId: string;
     format: 'pdf';
-}) | (BriefingAttachmentBase & {
-    type: 'visual';
-    dashboardId: string;
-    visualId: string;
-    format: 'pdf' | 'png';
 }) | (BriefingAttachmentBase & {
     type: 'card';
     dashboardId: string;
     cardId: string;
-    format: 'csv' | 'pdf' | 'png';
+    format: 'csv' | 'pdf';
 });
 
 declare type BriefingAttachmentBase = {
@@ -64,7 +95,7 @@ declare type BriefingAttachmentBase = {
     settings?: BriefingAttachmentSettings;
 };
 
-export declare type BriefingAttachmentFormat = 'pdf' | 'csv' | 'png';
+export declare type BriefingAttachmentFormat = 'pdf' | 'csv';
 
 export declare type BriefingAttachmentSettings = {
     theme?: string;
@@ -90,8 +121,11 @@ export declare type BriefingAttachmentSettings = {
     dashboardInputExecutionSnapshot?: Record<string, unknown>;
     selectedSheetId?: string;
     cardType?: string;
+    allowDownload?: boolean;
 };
 
+export declare type BriefingAuthorIntent = 'scheduled_report' | 'analytical_briefing';
+
 export declare type BriefingBody = {
     type: 'generated_analysis';
     instruction: string;
@@ -102,6 +136,11 @@ export declare type BriefingBody = {
     type: 'none';
 };
 
+export declare type BriefingCardAttachmentCapability = {
+    formats: BriefingAttachmentFormat[];
+    defaultFormat: BriefingAttachmentFormat | null;
+};
+
 export declare type BriefingChannelConfig = {
     formatProfile?: BriefingFormatProfile;
     subjectOverride?: string;
@@ -220,6 +259,8 @@ export declare type BriefingDeliveryConfig = {
     channelConfigs?: Partial<Record<BriefingDeliveryChannel, BriefingChannelConfig>>;
 };
 
+export declare type BriefingDisplayTypeLabel = 'Analytical briefing' | 'Scheduled report' | 'On-demand report' | 'Plain briefing';
+
 export declare type BriefingDraft = {
     name: string;
     description?: string | null;
@@ -234,6 +275,12 @@ export declare type BriefingDraft = {
     deliveryConfig?: BriefingDeliveryConfig | null;
 };
 
+export declare type BriefingEntityPresentation = {
+    typeLabel: BriefingDisplayTypeLabel;
+    noun: 'report' | 'briefing';
+    pluralNoun: 'reports' | 'briefings';
+};
+
 export declare type BriefingFormatProfile = 'concise' | 'balanced' | 'detailed';
 
 export declare type BriefingJobConfig = {
@@ -290,6 +337,15 @@ export declare type BriefingRecipient = {
     groupId: string;
 };
 
+export declare type BriefingScheduleCadence = 'daily' | 'weekly' | 'twice_monthly' | 'monthly';
+
+export declare type BriefingScheduleViewModel = {
+    cadence: BriefingScheduleCadence;
+    hour: number;
+    minute: number;
+    weekdays: number[];
+};
+
 export declare type BriefingSheetSelection = 'current' | 'all';
 
 export declare type BriefingSlackChannelDestination = {
@@ -323,6 +379,11 @@ export declare type BriefingSource = {
 
 export declare type BriefingStatus = 'ACTIVE' | 'PAUSED' | 'DISABLED';
 
+export declare type BriefingUiUser = {
+    type: 'organization' | 'tenant';
+    role?: string;
+};
+
 export declare type BriefingValidationIssue = {
     field: string;
     message: string;
@@ -348,10 +409,416 @@ export declare function buildBriefingJobConfig(input: Omit<Partial<BriefingJobCo
     body: BriefingBody;
 }): BriefingJobConfig;
 
+export declare function buildBriefingScheduleExpr(view: BriefingScheduleViewModel): string;
+
 export declare function buildCreateBriefingRequest(draft: BriefingDraft): CreateBriefingRequest;
 
 export declare function buildUpdateBriefingRequest(draft: BriefingDraft): UpdateBriefingRequest;
 
+/**
+ * Formula metadata for calculated fields (UI-only metadata)
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
+ *
+ * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
+ * Both are generated together from the same dialog inputs, preventing drift.
+ */
+declare interface CalculatedFieldFormula {
+    operation: CalculatedFieldOperation;
+    /**
+     * Array of full MetricField objects used as inputs to the calculated field.
+     *
+     * Storing complete Field objects eliminates the need for runtime lookups and ensures:
+     * - Table alias resolution works with schema-qualified tables (Issue 1)
+     * - All field metadata is available even if the input field isn't selected on the card (Issue 2)
+     * - Aggregate functions, filters, and entity info are preserved
+     *
+     * Each input field contains complete metadata:
+     * - name, entityId, entityName, qualifiedEntityName (for table qualification)
+     * - aggregate (for proper post-aggregation: SUM(sales) / COUNT(orders))
+     * - parameters.filters (for filtered metrics)
+     * - dataType and other properties
+     *
+     * Example: [
+     *   {name: 'sales', aggregate: 'SUM', entityName: 'sales_data', ...},
+     *   {name: 'order_id', aggregate: 'COUNT', entityName: 'sales_data', ...}
+     * ]
+     */
+    inputFields: Array<MetricField | GroupByField>;
+    /**
+     * Constant value used in scale operations (e.g., multiply by 0.15)
+     * Only applicable for 'scale' operation type
+     */
+    constant?: number;
+}
+
+/**
+ * Operations supported for calculated fields
+ */
+declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
+
+export declare function canCreateBriefingForUser(user: BriefingUiUser | null | undefined): boolean;
+
+declare interface CardConfig {
+    /**
+     * Matrix table is the shared analytics-spine successor for pivot and
+     * hierarchical aggregate tables. Dashboard cards store the public matrix
+     * intent shape so Data Apps, MCP, and dashboard runtime consume one contract.
+     */
+    matrixIntent?: SemaphorMatrixIntent;
+    /**
+     * Deprecated compatibility fields for older matrix table drafts. New
+     * dashboard-authored matrix cards should use `matrixIntent` so normal
+     * `filters` can remain the explorer/card-level `FilterGroup`.
+     */
+    version?: SemaphorMatrixIntent['version'];
+    source?: SemaphorMatrixIntent['source'];
+    rows?: SemaphorMatrixIntent['rows'];
+    columns?: SemaphorMatrixIntent['columns'];
+    values?: SemaphorMatrixIntent['values'];
+    inputs?: SemaphorMatrixIntent['inputs'];
+    totals?: SemaphorMatrixIntent['totals'];
+    sort?: SemaphorMatrixIntent['sort'];
+    expansion?: SemaphorMatrixIntent['expansion'];
+    layout?: SemaphorMatrixIntent['layout'];
+    displayLimits?: SemaphorMatrixIntent['displayLimits'];
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    detailColumns?: DetailField[];
+    /**
+     * Typed source that anchors the query before auto-join materializes an
+     * executable joinPlan.baseEntity. This is distinct from
+     * DataSource.selectedEntities, which lists available datasets but does not
+     * define join-root semantics.
+     */
+    queryBaseSource?: SemaphorSourceRef;
+    /** Preserves non-detail config when switching to detail tables. */
+    detailTableBackup?: DetailTableBackupConfig;
+    filters?: FilterGroup;
+    joinPlan?: JoinPlan;
+    rowLimit?: number;
+    /**
+     * One or more hierarchies that define drillable paths through dimensions.
+     */
+    drillHierarchies?: DrillHierarchy[];
+    /**
+     * Optional list of dimensions allowed for dynamic drill-down across this card.
+     * Used only when drill steps contain `mode: 'dynamicDrill'` or `type: 'dynamic'`.
+     */
+    allowedDrillTargets?: Field[];
+    /**
+     * NOT UOptional preload settings for inline drill previews
+     */
+    inlineDrillPreview?: {
+        enabled: boolean;
+        limit: number;
+        mode: 'lazy' | 'preloaded';
+    };
+    /**
+     * Configuration for on-click dashboard filters triggered by this card.
+     */
+    clickFilterInteractions?: ClickFilterInteraction[];
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
+    targetValue?: number;
+    showComparisonInLegend?: boolean;
+    showTrendline?: boolean;
+    trendlineWindow?: number;
+    trendlineGranularity?: 'day' | 'week' | 'month';
+    summary?: {
+        enabled?: boolean;
+        showOnCard?: boolean;
+        includeInDashboardSummary?: boolean;
+        breakdownDimensions?: GroupByField[];
+    };
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        pivotLevel: string | 'ALL';
+    }>;
+}
+
+declare interface CardInteractionConfig {
+    /**
+     * V2: Unified interactions array.
+     * Each interaction includes a trigger that specifies what element must be clicked.
+     */
+    interactions?: PersistedInteraction[];
+    allowedDrillTargets?: Field[];
+    drillHierarchies?: DrillHierarchy[];
+}
+
+declare interface ClickFilterInteraction {
+    mode: 'clickFilter';
+    /**
+     * What element must be clicked to trigger this interaction.
+     * Determines both the matching logic and the filtering behavior.
+     *
+     * @migration Optional during migration. Will be required in V2.
+     * Old configs without trigger will apply to any click (legacy behavior).
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * Fields from the chart element that should be used as filters.
+     * e.g., [region, ship_mode] from a stacked bar chart
+     */
+    filterFields: Field[];
+    /**
+     * Should this card visually highlight when clicked?
+     */
+    highlightSelf?: boolean;
+    /**
+     * Cards this filter applies to (inclusive).
+     * If omitted and `excludeCardIds` is also omitted → applies to all cards except self.
+     */
+    applyToCardIds?: string[];
+    /**
+     * Cards to explicitly exclude from receiving this filter.
+     * Takes effect only if `applyToCardIds` is undefined (acts as override).
+     */
+    excludeCardIds?: string[];
+    /**
+     * Optional UI label or tooltip.
+     */
+    label?: string;
+}
+
+declare type ColorConfig = {
+    segments: Record<string, string>;
+};
+
+declare type ColorRange = {
+    start: number;
+    end: number;
+    color: string;
+};
+
+declare interface ColorRange_2 {
+    min: number;
+    max: number;
+    color: string;
+    applyTo: 'cell' | 'row';
+}
+
+declare interface ColumnSettings {
+    type: 'none' | 'text' | 'number' | 'date' | 'badge' | 'link' | 'progress';
+    inheritMetricFormat?: boolean;
+    textAlign: 'left' | 'center' | 'right';
+    width: number;
+    minWidth?: number;
+    maxWidth?: number;
+    textOverflow?: 'ellipsis' | 'wrap' | 'clip';
+    textWrap: ColumnTextWrap;
+    /** Deprecated/inert. Totals are controlled by tablePrefs.tableStyle.totals. */
+    totalsBehavior?: TotalsBehavior;
+    totalsLabel?: string;
+    numberFormat: {
+        style: 'decimal' | 'currency' | 'percent' | 'scientific';
+        currency: string;
+        locale: string;
+        minimumFractionDigits: number;
+        maximumFractionDigits: number;
+        useGrouping?: boolean;
+        percentValueMode?: 'fraction' | 'whole';
+        showDataBar: boolean;
+        dataBarColor: string;
+        dataBarMinValue?: number;
+        dataBarMaxValue?: number;
+        /**
+         * When true, render the cell bg with a heatmap intensity tint scaled
+         * across the column's value range. Composes with the existing text
+         * color/color-range logic (tint is bg only). `showDataBar` takes
+         * precedence when both are set — per the canonical design, a cell is
+         * either a data-bar or a heatmap, never both.
+         */
+        showHeatmap?: boolean;
+    };
+    dateFormat: {
+        format: string;
+        useCustomFormat: boolean;
+        customFormat: string;
+        useRelativeTime: boolean;
+        timezone?: string;
+        sourceTimezone?: string;
+    };
+    linkFormat: LinkFormat;
+    colorRanges: ColorRange_2[];
+}
+
+declare type ColumnSettingsMap = Record<string, ColumnSettings>;
+
+declare type ColumnTextWrap = 'default' | 'truncate' | 'wrap' | 'nowrap' | 'preserve';
+
+declare type ColumnType = 'string' | 'number' | 'date';
+
+declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
+
+declare type ConditionalFormatCondition = {
+    kind: 'comparison';
+    columnId: string;
+    operator: ComparisonOperator;
+    value: unknown;
+} | {
+    kind: 'between';
+    columnId: string;
+    min: unknown;
+    max: unknown;
+    inclusive?: boolean;
+} | {
+    kind: 'blank';
+    columnId: string;
+    isBlank: boolean;
+} | {
+    kind: 'contains';
+    columnId: string;
+    value: string;
+    caseSensitive?: boolean;
+    exact?: boolean;
+} | {
+    kind: 'topBottom';
+    columnId: string;
+    direction: 'top' | 'bottom';
+    count: number;
+} | {
+    kind: 'colorScale';
+    columnId: string;
+    range: 'auto' | 'manual';
+    min?: number;
+    mid?: number;
+    max?: number;
+    colors: {
+        min: string;
+        mid?: string;
+        max: string;
+    };
+} | {
+    kind: 'dataBar';
+    columnId: string;
+    range: 'auto' | 'manual';
+    min?: number;
+    max?: number;
+    color: string;
+    showValue?: boolean;
+};
+
+declare type ConditionalFormatRule = {
+    id: string;
+    name?: string;
+    enabled?: boolean;
+    target: ConditionalFormatTarget;
+    condition: ConditionalFormatCondition;
+    style?: ConditionalFormatStyle;
+};
+
+declare type ConditionalFormatStyle = {
+    backgroundColor?: string;
+    textColor?: string;
+    fontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    italic?: boolean;
+    textDecoration?: 'none' | 'underline' | 'line-through';
+    icon?: 'arrowUp' | 'arrowDown' | 'warning' | 'check' | 'x';
+    dataBar?: {
+        color: string;
+        showValue: boolean;
+    };
+};
+
+declare type ConditionalFormatTarget = {
+    level: 'cell' | 'row';
+    columnIds?: string[];
+    conditionColumnId?: string;
+    applyToColumnIds?: string[];
+    tableParts?: TablePart[];
+    rowRoles?: string[];
+    depth?: number;
+    includeTotals?: boolean;
+    includeSubtotals?: boolean;
+};
+
+declare type ConnectionType = 'GoogleSheets' | 'FileUpload' | 'MySQL' | 'MSSQL' | 'PostgreSQL' | 'BigQuery' | 'Redshift' | 'Snowflake' | 'S3' | 'clickhouse' | 'S3Tables' | 'API' | 'none';
+
+declare type ControlBinding = {
+    controlId: string;
+    target: 'sql_param';
+    paramId: string;
+} | {
+    controlId: string;
+    target: 'config_metric_selector';
+    mapping: Record<string, StructuralMetricSelectorTarget>;
+} | {
+    controlId: string;
+    target: 'config_field_selector';
+    mapping: Record<string, StructuralFieldSelectorTarget>;
+} | {
+    controlId: string;
+    target: 'config_aggregation';
+    mapping: Record<string, string>;
+} | {
+    controlId: string;
+    target: 'config_grain';
+    mapping: Record<string, string>;
+};
+
+declare type ControlDefinition = {
+    id: string;
+    label: string;
+    scope: ControlScope;
+    type: ControlType;
+    source: ControlSource;
+    initialValueStrategy: ControlInitialValueStrategy;
+    defaultValue?: unknown;
+    requiredAtExecution: boolean;
+    hidden?: boolean;
+    locked?: boolean;
+    helpText?: string;
+    placement?: 'toolbar' | 'card_header' | 'advanced';
+    showLabel?: boolean;
+    toolbarWidth?: number;
+};
+
+declare type ControlInitialValueStrategy = 'saved_default' | 'builtin' | 'embed_required' | 'schedule_snapshot';
+
+declare type ControlOption = {
+    value: string;
+    label: string;
+    presentation?: {
+        granularity?: TimeGranularity;
+        dateFormat?: DateFormatValue;
+        customFormat?: string;
+    };
+};
+
+declare type ControlScope = 'dashboard' | 'card';
+
+declare type ControlSource = {
+    kind: 'manual';
+    options: ControlOption[];
+} | {
+    kind: 'dataset_values';
+    fieldId: string;
+    connectionId?: string;
+} | {
+    kind: 'field_allowlist';
+    fieldIds: string[];
+} | {
+    kind: 'metric_allowlist';
+    metricIds: string[];
+} | SqlQueryControlSource;
+
+declare type ControlType = 'enum' | 'multi_enum' | 'text' | 'number' | 'boolean' | 'date' | 'field_selector' | 'metric_selector' | 'aggregation_selector' | 'grain_selector';
+
 export declare type CreateBriefingRequest = {
     name: string;
     description: string | null;
@@ -366,26 +833,1940 @@ export declare type CreateBriefingRequest = {
     deliveryConfig: BriefingDeliveryConfig | null;
 };
 
+declare type DashboardInputExportKey = 'label' | 'value' | 'start' | 'end' | 'range';
+
+declare type DashboardInputTextContent = Array<{
+    type: 'text';
+    value: string;
+} | {
+    type: 'variable';
+    ref: DashboardInputVariableRef;
+}>;
+
+declare type DashboardInputVariableRef = {
+    source: 'dashboardInput';
+    inputId: string;
+    export: DashboardInputExportKey;
+} | {
+    source: 'dashboardInputAlias';
+    variableName: string;
+    export?: DashboardInputExportKey;
+} | {
+    source: 'documentMeta';
+    key: 'generatedAt' | 'pageNumber' | 'pageCount';
+};
+
+declare interface DatabaseEntityReference {
+    connectionId: string;
+    connectionType: ConnectionType;
+    type: EntityType;
+    dbObjectType?: string;
+    dialect?: Dialect;
+    database?: string;
+    schema?: string;
+    name: string;
+}
+
+declare type DatabaseEntityType = 'table' | 'view' | 'materialized view';
+
+declare interface DataModelEntityReference extends DatabaseEntityReference {
+    type: 'model';
+    id: string;
+    label: string;
+    description: string;
+}
+
+declare interface DatasetEntityReference extends DatabaseEntityReference {
+    type: 'dataset';
+    datasetType: 'physical' | 'virtual';
+    table?: string | null;
+    datamodelId?: string | null;
+    sql?: string | null;
+    id: string;
+    domainId: string;
+    label: string;
+    description?: string;
+}
+
+declare interface DataSource {
+    connectionId: string;
+    semanticDomainId?: string;
+    connectionType: string;
+    mode: 'database' | 'upload' | 'url' | 'semanticDomain';
+    dbSelection?: {
+        database: string;
+        schema: string;
+        entityType: DatabaseEntityType;
+    };
+    selectedEntities: SelectedEntities;
+}
+
+declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM-DD HH:mm", "YYYY-MM-DD HH:mm:ss", "YYYY-MM-DD HH:mm Z", "YYYY-MM-DD HH:mm:ss Z", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
+
+declare type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
+
+declare type DateOptions = {
+    locale: string;
+    format: string;
+    options: Intl.DateTimeFormatOptions;
+};
+
+declare type DateSelectionMode = 'range' | 'months';
+
+declare type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
+
 export declare const DEFAULT_BRIEFING_ARTIFACT_FORMATS: readonly ["markdown"];
 
+export declare const DEFAULT_BRIEFING_SCHEDULE: BriefingScheduleViewModel;
+
+declare type DefaultDateFilter = RelativeDateFilter | FixedMonthDefaultDateFilter;
+
+export declare function describeBriefingSchedule(expression: string, timezone: string, locale?: string): string | null;
+
+/**
+ * Field configuration for detail table columns.
+ * Unlike GroupByField, DetailField does not support aggregation or granularity.
+ * Columns are selected and displayed as-is from the database.
+ */
+declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
+    role: 'detail';
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+    /**
+     * Optional SQL expression for calculated detail fields.
+     */
+    expression?: string;
+    /**
+     * Formula metadata for calculated fields (used for token qualification).
+     */
+    calculatedFormula?: CalculatedFieldFormula;
+}
+
+declare interface DetailTableBackupConfig {
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        pivotLevel: string | 'ALL';
+    }>;
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
+}
+
+declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
+
+declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
+
+declare interface DrillDownInteraction {
+    mode: 'drillDown';
+    /**
+     * What element must be clicked to trigger this drill-down.
+     * Optional during configuration, but must be defined before execution.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    hierarchyId?: string;
+    label?: string;
+}
+
+declare interface DrillHierarchy {
+    id: string;
+    label?: string;
+    type: 'static' | 'date';
+    steps: DrillHierarchyStep[];
+    default?: boolean;
+    baseField?: Field;
+}
+
+declare interface DrillHierarchyStep {
+    field: Field;
+    mode: 'drillDown';
+    preferredChartType?: TChartType;
+    breadcrumbLabelTemplate?: string;
+    retainFilters?: boolean;
+    label?: string;
+    linkedInsightId?: string;
+}
+
+declare interface DrillThroughInteraction {
+    mode: 'drillThrough';
+    /**
+     * What element must be clicked to trigger this drill-through.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    targetDashboardId: string;
+    /**
+     * How to pass context to the target dashboard
+     * @default 'interactionFilters'
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    label?: string;
+}
+
+declare interface DrillToDetailInteraction {
+    mode: 'drillToDetail';
+    /**
+     * What element must be clicked to trigger this drill to detail.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    detailFields?: Field[];
+    sortBy?: SortByField[];
+    limit?: number;
+    detailTitle?: string;
+    /**
+     * Target insight ID to navigate to
+     */
+    targetInsightId?: string;
+    /**
+     * How to pass context to the target insight
+     * @default 'interactionFilters'
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    /**
+     * How to display the insight
+     * @default 'modal'
+     */
+    displayMode?: 'modal' | 'replace-card';
+    label?: string;
+}
+
+declare interface DrillToURLInteraction {
+    mode: 'drillToURL';
+    /**
+     * What element must be clicked to trigger this URL drill.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    /**
+     * URL template with placeholders (e.g., 'https://example.com/product/{{product_id}}')
+     */
+    urlTemplate: string;
+    /**
+     * List of parameters used in the URL template
+     */
+    parameters: URLParameter[];
+    /**
+     * Whether to URL-encode parameter values
+     * @default true
+     */
+    encodeParameters?: boolean;
+    /**
+     * Custom label for this interaction in the menu
+     */
+    label?: string;
+}
+
+declare interface DrillUpInteraction {
+    mode: 'drillUp';
+    /**
+     * What element must be clicked to trigger this drill-up.
+     * For synthetic drill-up interactions, this is inherited from the original drill-down.
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * The hierarchy ID to reference for display purposes.
+     * Used to show the parent level name in the interaction menu.
+     */
+    hierarchyId?: string;
+    label?: string;
+}
+
+declare interface DynamicDrillInteraction {
+    mode: 'dynamicDrill';
+    /**
+     * What element must be clicked to trigger this dynamic drill menu.
+     * When this trigger fires, user sees a menu of available fields to explore.
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * List of fields available for dynamic exploration.
+     * User can choose which field to drill into at runtime.
+     * Only drillable fields (string, boolean types) should be included.
+     */
+    availableFields: Field[];
+    /**
+     * Optional label for the menu item.
+     * Defaults to "Explore Fields" if not specified.
+     */
+    label?: string;
+    /* Excluded from this release type: drillField */
+}
+
+declare type EntityType = 'table' | 'view' | 'materialized view' | 'model' | 'file' | 'dataset' | 'url' | 'upload';
+
+declare interface Field {
+    /**
+     * Unique identifier for this field instance (for joins, UI state, etc.).
+     * Should be unique within the context of the query or data model.
+     * Example: 'orders.customer_id', 'expr_12345', etc.
+     */
+    id: string;
+    /**
+     * The physical/source column name in the database or data source.
+     * Used for mapping to the underlying data model and SQL generation (unless overridden by expression).
+     */
+    name: string;
+    /**
+     * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
+     */
+    label: string;
+    /**
+     * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
+     * If not provided, should be auto-generated from label or name.
+     */
+    alias?: string;
+    sourceField?: string;
+    qualifiedFieldName: string;
+    dataType: string;
+    description?: string;
+    qualifiedEntityName?: string;
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+    granularity?: TimeGranularity;
+    entityId: string;
+    entityName: string;
+    entityType: EntityType;
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
+    format?: FormatSpec;
+    aggregate?: AggregateFunction;
+    fieldScope?: FieldScope;
+}
+
+declare type FieldScope = 'card' | 'sheet' | 'dashboard' | 'domain';
+
+declare interface FileEntityReference extends DatabaseEntityReference {
+    id: string;
+    type: 'file' | 'url' | 'upload';
+    label: string;
+    description: string;
+    originalName: string;
+    file?: File;
+    url?: string;
+}
+
+declare interface FilterByColumn extends BaseColumn {
+    role: 'filter';
+    operators?: string[];
+    mode?: 'include' | 'exclude';
+    sql?: string;
+    fetchValues?: boolean;
+    fetchLimit?: number;
+    valueSource?: 'distinct' | 'static' | 'range';
+    staticValues?: string[];
+}
+
+declare interface FilterCondition {
+    id: string;
+    field: Field;
+    operator: Operator;
+    value: FilterValue;
+}
+
+declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+    entityName?: Field['entityName'];
+    entityType?: string;
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+};
+
+declare interface FilterGroup {
+    id: string;
+    logicalOperator: LogicalOperator;
+    negate: boolean;
+    conditions: FilterCondition[];
+    groups: FilterGroup[];
+}
+
+declare type FilterOnClick = {
+    expression?: string;
+    columnIndex: number;
+};
+
+declare type FilterSemanticContext = {
+    semanticDomainId?: string;
+    selectedEntities?: unknown[];
+    connectionId?: string;
+    connectionType?: string;
+};
+
+declare type FilterValue = string | number | boolean | Date | null | [number, number] | [string, string] | string[] | number[];
+
+/**
+ * Absolute fixed month/year default used by Month Picker defaults.
+ * - `month` is 0-indexed (0=January, 11=December) to align with MonthPicker.
+ */
+declare type FixedMonthDefaultDateFilter = {
+    mode: 'fixed';
+    unit: 'month';
+    year: number;
+    month: number;
+};
+
+declare type FormatSpec = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
+export declare function getBriefingCardAttachmentCapability(card: TCard): BriefingCardAttachmentCapability;
+
+export declare function getBriefingCardAttachmentFormats(input: {
+    cardType: string;
+    allowDownload?: boolean;
+}): BriefingAttachmentFormat[];
+
+export declare function getBriefingCreationIntents(input: {
+    canCreate: boolean;
+    analyticalBriefingsEnabled: boolean;
+    scheduledReportAvailable: boolean;
+}): BriefingAuthorIntent[];
+
+export declare function getBriefingDisplayTypeLabel(input: {
+    body: BriefingBody;
+    attachments: BriefingAttachment[];
+    deliveryConfig: BriefingDeliveryConfig | null;
+    scheduleExpr: string | null;
+}): BriefingDisplayTypeLabel;
+
+/** Derives customer-facing terminology without changing the Briefing model. */
+export declare function getBriefingPresentation(input: {
+    body: BriefingBody;
+    attachments: BriefingAttachment[];
+    deliveryConfig: BriefingDeliveryConfig | null;
+    scheduleExpr: string | null;
+}): BriefingEntityPresentation;
+
+export declare function getDefaultBriefingCardAttachmentFormat(input: {
+    cardType: string;
+    allowDownload?: boolean;
+}): BriefingAttachmentFormat;
+
+declare type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+
+declare interface GroupByColumn extends BaseColumn {
+    role: 'groupby';
+    granularity?: Granularity;
+    format?: string;
+}
+
+declare interface GroupByField extends Field {
+    role: 'groupby';
+    granularity?: TimeGranularity;
+    /**
+     * Optional SQL expression for grouping (e.g., DATE_TRUNC('month', order_date)).
+     * If present, used in SELECT and GROUP BY instead of just the column name.
+     */
+    expression?: string;
+    timeDrillPath?: TimeDrillStep[];
+    calculatedFormula?: CalculatedFieldFormula;
+}
+
+declare type HtmlOptions = {
+    html: string;
+};
+
+declare interface InlineDrillInteraction {
+    mode: 'inlineDrill';
+    /**
+     * What element must be clicked to trigger this inline drill.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    /**
+     * When to fetch the detailed data
+     * @default 'lazy'
+     */
+    fetchMode?: 'lazy' | 'preloaded';
+    /**
+     * Maximum number of records to show (0 for unlimited)
+     * @default 100
+     */
+    inlineLimit?: number;
+    /**
+     * How to display the detailed records
+     * @default 'table'
+     */
+    displayMode?: 'table' | 'list' | 'cards';
+    /**
+     * Whether to show records in a modal overlay
+     * @default false
+     */
+    showInModal?: boolean;
+    /**
+     * Whether to allow exporting the detailed records
+     * @default true
+     */
+    allowExport?: boolean;
+    label?: string;
+}
+
+/**
+ * Unified Interaction type (V2)
+ * Combines all interaction types into a single union for the new interactions array.
+ */
+declare type Interaction = ClickFilterInteraction | DrillDownInteraction | DrillThroughInteraction | DrillToDetailInteraction | DrillToURLInteraction | InlineDrillInteraction | DrillUpInteraction | DynamicDrillInteraction;
+
+declare interface InteractionTargetOverride {
+    applyToCardIds?: string[] | null;
+    excludeCardIds?: string[] | null;
+}
+
+/**
+ * Defines what element must be clicked to trigger an interaction.
+ *
+ * The `type` determines filtering behavior:
+ * - 'metric': Captures intersection of ALL dimensions (e.g., country='USA' AND state='CA')
+ * - 'attribute': Captures ONLY the clicked dimension (e.g., country='USA')
+ *
+ * Note: `trigger.type` is different from `field.type`:
+ * - trigger.type = filtering behavior ('metric' | 'attribute')
+ * - field.type = data type ('dimension' | 'metric' | 'measure')
+ */
+declare interface InteractionTrigger {
+    /**
+     * Determines filtering behavior when this trigger fires:
+     * - 'metric': Capture intersection of all dimensions
+     * - 'attribute': Capture only this specific dimension
+     */
+    type: 'metric' | 'attribute';
+    /**
+     * The field (metric or attribute) that must be clicked.
+     * For multi-series charts: Use the specific metric Field with unique ID
+     * (e.g., Field with id='count_of_orders')
+     */
+    field: Field;
+}
+
 export declare function isBriefingArtifactFormat(input: unknown): input is BriefingArtifactFormat;
 
 export declare function isBriefingDeliveryChannel(input: unknown): input is BriefingDeliveryChannel;
 
+export declare function isEmailOnlyBriefingDelivery(deliveryConfig: BriefingDeliveryConfig | null): boolean;
+
+export declare function isValidBriefingTimezone(value: unknown): value is string;
+
+declare interface Join {
+    id: string;
+    source: DatabaseEntityReference;
+    target: DatabaseEntityReference;
+    joinType: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
+    joinKeyGroups: JoinKeyGroup[];
+    sequence: number;
+    relationshipId?: string;
+    relationshipName?: string;
+    relationshipCardinality?: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
+    relationshipTraversalDirection?: 'forward' | 'reverse';
+}
+
+declare interface JoinKey {
+    id?: string;
+    source: Field;
+    target: Field;
+    operator: string;
+}
+
+declare interface JoinKeyGroup {
+    id: string;
+    operator: string;
+    keys: JoinKey[];
+}
+
+declare interface JoinPlan {
+    baseEntity: DatabaseEntityReference;
+    joins: Join[];
+}
+
+declare interface LinkFormat {
+    urlTemplate: string;
+    labelType: 'value' | 'static' | 'column';
+    staticLabel?: string;
+    labelColumn?: string;
+    openInNewTab: boolean;
+}
+
+declare type LogicalOperator = 'AND' | 'OR';
+
 export declare const MAX_BRIEFING_ATTACHMENTS = 20;
 
+declare interface MetricColumn extends BaseColumn {
+    role: 'metric';
+    aggregate: AggregateFunction;
+    aliasTemplate?: string;
+}
+
+declare interface MetricField extends Field {
+    role: 'metric';
+    aggregate?: AggregateFunction;
+    /**
+     * Optional SQL expression for the metric (e.g., ship_date - order_date).
+     * If present, used as aggregate(expression) instead of aggregate(name).
+     */
+    expression?: string;
+    /**
+     * Optional parameters for future extensibility (e.g., window functions).
+     * * Example:
+     * {
+     aggregate: "SUM",
+     name: "sales",
+     parameters: {
+     window: "PARTITION BY region ORDER BY date ROWS BETWEEN 1 PRECEDING AND CURRENT ROW"
+     }
+     }
+
+     {
+     aggregate: "COUNT",
+     name: "order_id",
+     parameters: {
+     filter: "status = 'Active'"
+     }
+     }
+     */
+    parameters?: {
+        filters?: FilterGroup;
+        windowTransform?: WindowTransform;
+    };
+    aliasTemplate?: string;
+    valueAliases?: Record<string, string>;
+    /**
+     * Formula metadata for calculated fields (UI-only metadata)
+     * This is supplementary data to help the UI display and edit calculated fields.
+     * The `expression` field remains the source of truth for the backend.
+     *
+     * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
+     * Both are generated together from the same dialog inputs, preventing drift.
+     */
+    calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Indicates the metric expression must be evaluated after row-level filtering,
+     * either because it contains an aggregate function directly or depends on a
+     * pre-aggregated metric input.
+     */
+    isPreAggregated?: boolean;
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'start_vs_end' | 'target';
+    comparisonDisplay?: 'column' | 'inline' | 'hover';
+    targetValue?: number;
+}
+
+declare type NoneOptions = {};
+
 export declare function normalizeBriefingContentDocument(input: unknown): BriefingContentDocument;
 
 export declare function normalizeBriefingDraft(input: unknown): CreateBriefingRequest;
 
 export declare function normalizeBriefingJobConfig(input: unknown): BriefingJobConfig;
 
+declare type NumberAxisFormat = {
+    decimalPlaces?: number;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    suffix?: string;
+    currency?: string;
+    locale?: string;
+    useGrouping?: boolean;
+    percentValueMode?: 'fraction' | 'whole';
+};
+
+declare type NumberOptions = {
+    locale: string;
+    currency?: string;
+    options: Intl.NumberFormatOptions;
+    colorRanges?: ColorRange[];
+};
+
+declare type OldFilterValue = string | number | null | (string | number)[] | RangeValue;
+
+declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
+
+declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'like' | 'not like' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';
+
+declare type OptionsMap = {
+    number: NumberOptions;
+    string: StringOptions;
+    date: DateOptions;
+    html: HtmlOptions;
+    none: NoneOptions;
+};
+
+declare interface OrderBy {
+    columnId: string;
+    direction: 'asc' | 'desc';
+}
+
+/**
+ * Pagination configuration for table queries
+ */
+declare interface PaginationConfig {
+    page: number;
+    pageSize: number;
+}
+
+export declare function parseBriefingScheduleExpr(expression: string): {
+    ok: true;
+    value: BriefingScheduleViewModel;
+} | {
+    ok: false;
+    issue: string;
+};
+
+declare type PersistedInteraction = Interaction & {
+    id?: string;
+};
+
+declare interface PivotByField extends Field {
+    role: 'pivotby';
+}
+
+declare interface QueryConfig {
+    groupByColumns?: GroupByColumn[];
+    pivotColumns?: GroupByColumn[];
+    metricColumns?: MetricColumn[];
+    filterColumns?: FilterByColumn[];
+    filters?: QueryFilter[];
+    limit?: number;
+    orderBy?: OrderBy[];
+}
+
+declare type QueryFilter = {
+    filterColumnName: string;
+    filterValue: OldFilterValue;
+};
+
+declare type RangeValue = {
+    gte?: string | number;
+    lte?: string | number;
+    lt?: string | number;
+    gt?: string | number;
+};
+
+declare type RelativeDateFilter = {
+    mode: 'last';
+    n: number;
+    unit: SubDayDateUnit;
+    complete?: false;
+} | {
+    mode: 'last';
+    n: number;
+    unit: DateUnit;
+    complete?: boolean;
+} | {
+    mode: 'this';
+    unit: DateUnit;
+    toDate?: boolean;
+} | {
+    mode: 'previous';
+    unit: DateUnit;
+} | {
+    mode: 'between';
+    unit: DateUnit;
+    from: number;
+    to: number;
+};
+
+declare type SelectedEntities = SelectedEntity[];
+
+declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
+
+declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
+
+declare type SemaphorAnalyticsFilterBase = {
+    id?: string;
+    field: SemaphorFieldRef;
+    /**
+     * Controls where the filter is applied in an aggregate query.
+     *
+     * `row` means pre-aggregation filtering (`WHERE`).
+     * `aggregate` means post-aggregation filtering (`HAVING`) and is valid only
+     * for measure fields the execution engine can aggregate safely.
+     */
+    scope?: 'row' | 'aggregate';
+};
+
+declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
+    operator: SemaphorAnalyticsNullFilterOperator;
+    values?: never;
+};
+
+declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
+    operator?: SemaphorAnalyticsValueFilterOperator;
+    values: unknown[];
+};
+
+declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
+
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: SemaphorValueFormat;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
+
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+/**
+ * Explorer-backed table source. This is intentionally distinct from raw SQL:
+ * matrix planning needs stable source metadata, fields, and dialect context.
+ */
+declare type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'physical';
+}>;
+
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+declare type SemaphorInputBinding = {
+    inputId: string;
+    kind?: 'filter' | 'control';
+    controlRole?: 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
+    operator?: SemaphorInputOperator;
+    field?: SemaphorFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+
+declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
+
+declare type SemaphorMatrixAxisExpansionOptions = {
+    defaultDepth?: number;
+    lazy?: boolean;
+    expandedPaths?: SemaphorMatrixMemberPathSegment[][];
+};
+
+declare type SemaphorMatrixAxisLevel = {
+    id?: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    label?: string;
+    subtotal?: boolean | SemaphorMatrixSubtotalOptions;
+    sortBy?: SemaphorMatrixAxisSortRule;
+};
+
+declare type SemaphorMatrixAxisSortRule = {
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixDisplayLimitOptions = {
+    rows?: SemaphorMatrixDisplayLimitRule;
+    columns?: SemaphorMatrixDisplayLimitRule;
+};
+
+declare type SemaphorMatrixDisplayLimitRule = {
+    limit: number;
+};
+
+declare type SemaphorMatrixExpansionOptions = {
+    rows?: SemaphorMatrixAxisExpansionOptions;
+    columns?: SemaphorMatrixAxisExpansionOptions;
+};
+
+declare type SemaphorMatrixIntent = {
+    kind: 'matrix';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorMatrixAxisLevel[];
+    columns?: SemaphorMatrixAxisLevel[];
+    values: SemaphorMatrixValueField[];
+    filters?: SemaphorAnalyticsFilter[];
+    inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixLayoutOptions;
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+declare type SemaphorMatrixLayoutOptions = {
+    hierarchy?: 'compact' | 'tabular' | 'outline';
+    valuesPlacement?: 'columns' | 'rows';
+    stickyRowHeaders?: boolean;
+    stickyColumnHeaders?: boolean;
+};
+
+declare type SemaphorMatrixMemberPathSegment = {
+    levelId: string;
+    value: unknown;
+};
+
+declare type SemaphorMatrixSortRule = {
+    axis: 'row' | 'column';
+    targetId?: string;
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    } | {
+        kind: 'value';
+        valueId: string;
+        rowPath?: SemaphorMatrixMemberPathSegment[];
+        columnPath?: SemaphorMatrixMemberPathSegment[];
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixSourceRef = SemaphorSemanticSourceRef | SemaphorExplorerSourceRef;
+
+declare type SemaphorMatrixSubtotalOptions = {
+    enabled?: boolean;
+    position?: 'before' | 'after';
+    label?: string;
+};
+
+declare type SemaphorMatrixTotalCalculation = {
+    kind: 'defaultAggregate';
+} | {
+    kind: 'blank';
+} | {
+    kind: 'labelOnly';
+    label?: string;
+} | {
+    kind: 'customAggregate';
+    aggregate: SemaphorAggregateFunction;
+} | {
+    kind: 'percentOfParent';
+} | {
+    kind: 'percentOfGrandTotal';
+} | {
+    kind: 'customExpression';
+    expressionId: string;
+};
+
+declare type SemaphorMatrixTotalOptions = {
+    rows?: boolean | 'perLevel';
+    columns?: boolean | 'perLevel';
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+    rowPosition?: 'top' | 'bottom';
+    columnPosition?: 'left' | 'right';
+};
+
+declare type SemaphorMatrixValueField = {
+    id?: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    label?: string;
+    format?: SemaphorValueFormat;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
+declare type SemaphorProtocolVersion = 1;
+
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    connectionType?: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
+declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+declare type SemaphorValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
+declare interface SortByField extends Field {
+    role: 'sortby';
+    direction: 'asc' | 'desc';
+}
+
+declare type SqlQueryControlSource = {
+    kind: 'sql_query';
+    connectionId: string;
+    sql: string;
+    valueColumn: string;
+    labelColumn?: string;
+};
+
+declare type StringOptions = {
+    maxLength?: number;
+};
+
+declare type StructuralFieldSelectorTarget = GroupByField;
+
+declare type StructuralMetricSelectorTarget = MetricField;
+
+declare type SubDayDateUnit = 'minute' | 'hour';
+
+declare type TableBaseFormatting = {
+    version: TableFormattingVersion;
+    tableParts?: Partial<Record<TablePart, TableBaseStyle>>;
+    columns?: Record<string, {
+        body?: TableBaseStyle;
+        header?: TableBaseStyle;
+        footer?: TableBaseStyle;
+    }>;
+};
+
+declare type TableBaseStyle = {
+    fontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    italic?: boolean;
+    textColor?: string;
+    backgroundColor?: string;
+    textDecoration?: 'none' | 'underline' | 'line-through';
+};
+
+declare type TableConditionalFormatting = {
+    version: TableFormattingVersion;
+    rules: ConditionalFormatRule[];
+};
+
+/**
+ * Row rhythm for the whole table. Authors pick one per card; undefined
+ * falls back to 'compact' (the canonical default — dense scanning, matches
+ * the Linear-style spec). Drives row padding, cell font size, and header
+ * font size via a shared density spec in DataTable.
+ */
+declare type TableDensity = 'dense' | 'compact' | 'standard' | 'comfortable' | 'spacious';
+
+declare type TableFormattingVersion = 1;
+
+declare type TableGridLines = 'none' | 'outer' | 'inner' | 'horizontal' | 'vertical' | 'top' | 'right' | 'bottom' | 'left' | 'full';
+
+declare type TableHeaderStyle = 'plain' | 'filled' | 'accent';
+
+declare type TablePart = 'body' | 'header' | 'footer' | 'subtotal' | 'grandTotal';
+
+declare type TablePreferences = {
+    columnSettingsMap?: ColumnSettingsMap;
+    baseFormatting?: TableBaseFormatting;
+    conditionalFormatting?: TableConditionalFormatting;
+    selectColumnVisible?: boolean;
+    columnVisibility?: Record<string, boolean>;
+    columnSizing?: ColumnSizingState;
+    pageSize?: number;
+    enableDevModePagination?: boolean;
+    forceClientPagination?: boolean;
+    density?: TableDensity;
+    tableStyle?: TableStylePreferences;
+};
+
+declare type TableStylePreferences = {
+    headerStyle?: TableHeaderStyle;
+    headerBackgroundColor?: string;
+    headerTextColor?: string;
+    headerWrapText?: boolean;
+    stripedRows?: boolean;
+    gridLines?: TableGridLines;
+    wrapText?: boolean;
+    totals?: TableTotalsStylePreferences;
+};
+
+declare type TableTotalsFontWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+
+declare type TableTotalsStylePreferences = {
+    enabled?: boolean;
+    backgroundColor?: string;
+    textColor?: string;
+    fontWeight?: TableTotalsFontWeight;
+    borderTop?: boolean;
+    borderTopStyle?: 'solid' | 'dashed' | 'dotted' | 'double';
+    borderTopColor?: string;
+};
+
+/** Global bar style configuration */
+declare type TBarStyleConfig = {
+    /** Default border radius for all bars - 0-20 pixels */
+    borderRadius?: number;
+    /** Default border width for all bars - 0-5 pixels */
+    borderWidth?: number;
+    /** Default bar width as percentage of category width (0.1-1.0) */
+    barPercentage?: number;
+    /** Default category width as percentage of available space (0.1-1.0) */
+    categoryPercentage?: number;
+};
+
+declare type TBubbleScatterConfig = {
+    /**
+     * Explicit key for X-axis metric. Falls back to auto-detection.
+     */
+    xMetricKey?: string;
+    /**
+     * Explicit key for Y-axis metric. Falls back to auto-detection.
+     */
+    yMetricKey?: string;
+    /**
+     * Explicit key for radius metric (bubble only). Falls back to auto-detection.
+     */
+    radiusMetricKey?: string;
+    /**
+     * Key for point labels (first dimension).
+     */
+    labelKey?: string;
+    /**
+     * Whether to group points into series. Defaults to auto-detect in card config mode.
+     */
+    enableGrouping?: boolean;
+    /**
+     * Key for series grouping. Can be any data type (string, number, date).
+     */
+    groupKey?: string;
+    /**
+     * Scaling mode for bubble radius.
+     */
+    radiusScale?: 'linear' | 'sqrt' | 'fixed';
+    /**
+     * Fixed radius value when radiusScale is 'fixed' or for scatter charts.
+     */
+    fixedRadius?: number;
+    /**
+     * Minimum radius for bubble scaling.
+     */
+    minRadius?: number;
+    /**
+     * Maximum radius for bubble scaling.
+     */
+    maxRadius?: number;
+};
+
+declare type TBulletConfig = {
+    /**
+     * Orientation of the bullet chart. Defaults to horizontal.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Explicit metric key to use for target markers. Falls back to the next metric column.
+     */
+    targetMetricKey?: string;
+    /**
+     * Optional comparative metric (e.g., previous period).
+     */
+    comparativeMetricKey?: string;
+    /**
+     * When true, disables automatic comparative assignment even if a metric exists.
+     */
+    disableAutoComparative?: boolean;
+    /**
+     * Mapping of qualitative range names to column keys.
+     */
+    rangeKeys?: TBulletRangeKeys;
+    /**
+     * Static range values if columns are not provided.
+     */
+    ranges?: TBulletRangeValues;
+    /**
+     * Global target value if a column is not provided.
+     */
+    targetValue?: number;
+    /**
+     * Show numeric labels on the actual bar. Default true.
+     */
+    showValueLabels?: boolean;
+    /**
+     * Treat provided range values as percentages (0-1) when true.
+     */
+    rangesArePercentages?: boolean;
+    /**
+     * Whether qualitative ranges should be rendered.
+     */
+    showRanges?: boolean;
+    /**
+     * Display labels for qualitative ranges.
+     */
+    rangeLabels?: TBulletRangeLabelOverrides;
+};
+
+declare type TBulletRangeKeys = Partial<Record<TBulletRangeLabels, string>>;
+
+declare type TBulletRangeLabelOverrides = Partial<Record<TBulletRangeLabels, string>>;
+
+declare type TBulletRangeLabels = 'poor' | 'satisfactory' | 'good';
+
+declare type TBulletRangeValues = Partial<Record<TBulletRangeLabels, number>>;
+
+declare type TCard = {
+    id: string;
+    title: string;
+    tabTitle?: string;
+    displayTab?: boolean;
+    description?: string;
+    info?: string;
+    connectionId?: string;
+    datamodelId?: string;
+    type: TChartType;
+    sql?: string;
+    python?: string;
+    dataSource?: DataSource;
+    config?: CardConfig;
+    interactionConfig?: CardInteractionConfig;
+    linkedSourceCardId?: string;
+    linkedInteractionTargetOverrides?: Record<string, InteractionTargetOverride>;
+    paginationConfig?: PaginationConfig;
+    queryConfig?: QueryConfig;
+    customCfg?: any;
+    preferences?: TCardPreferences;
+    customCardPreferences?: TCustomCardPreferences;
+    visualizationMode?: TVisualizationMode;
+    dynamicCardPreferences?: TDynamicCardPreferences;
+    lastSelectedDatabase?: string;
+    lastSelectedDatamodelId?: string;
+    lastSelectedSchema?: string;
+    lastSelectedTable?: string;
+    refreshInterval?: string;
+    /**
+     * Card-specific display preferences that override dashboard-level preferences.
+     * If not specified, the card will use the dashboard's display preferences.
+     */
+    displayPreferences?: VisualDisplayPreferences;
+    /**
+     * Inline filter definitions for this card.
+     * Configured by editors via the visual editor settings.
+     */
+    inlineFilters?: TInlineFilter[];
+    /**
+     * Card-scoped calculated fields that should remain available even when they
+     * are not actively selected in the chart configuration.
+     */
+    calculatedFields?: Field[];
+    /**
+     * Card-scoped control definitions for this card.
+     */
+    controls?: ControlDefinition[];
+    /**
+     * Per-card bindings that connect dashboard or card controls to this card's runtime targets.
+     */
+    controlBindings?: ControlBinding[];
+};
+
+declare type TCardPreferences = {
+    onClickFilter?: FilterOnClick[];
+    filterOnClick?: boolean;
+    filterOnClickField?: string;
+    filterOnClickColumnIndex?: number;
+    sortChart?: 'asc' | 'desc' | 'none';
+    formatNumber?: {
+        decimalPlaces?: number;
+        minimumFractionDigits?: number;
+        maximumFractionDigits?: number;
+        currency?: string;
+        locale?: string;
+        suffix?: string;
+        prefix?: string;
+        useGrouping?: boolean;
+        percentValueMode?: 'fraction' | 'whole';
+        enabled?: boolean | string;
+        colorRanges?: ColorRange[];
+    };
+    numberAxisFormat?: NumberAxisFormat;
+    datasetOptions?: TDatasetOptions[];
+    chartOptions?: TChartOptions;
+    columnSettings?: TColumnSetting<DisplayDataType>[];
+    colorConfig?: ColorConfig;
+    xAxisConfig?: AxisConfig;
+    yAxisConfig?: AxisConfig;
+    secondaryYAxisConfig?: AxisConfig;
+    tooltipConfig?: TTooltipFormatConfig;
+    dataLabelsConfig?: TDataLabelsConfig;
+    bulletConfig?: TBulletConfig;
+    heatmapConfig?: THeatmapConfig;
+    bubbleScatterConfig?: TBubbleScatterConfig;
+    funnelConfig?: TFunnelConfig;
+    /** Global line/point style defaults for line and area charts */
+    lineStyleConfig?: {
+        lineStyle?: TLineStyle;
+        pointRadius?: number;
+        pointStyle?: TPointStyle;
+    };
+    /** Global bar style defaults for bar charts */
+    barStyleConfig?: TBarStyleConfig;
+    tablePrefs?: TablePreferences;
+    allowDownload?: boolean;
+    customVisualCode?: string;
+    textVisualOptions?: {
+        isDynamicText?: boolean;
+        /**
+         * Legacy structured content with dashboard-input variable refs.
+         * Authored via the plain-text ContentEditableText editor. New cards
+         * use `richContent` instead; this stays for backward compatibility
+         * and is never set on a card that has `richContent`.
+         */
+        content?: DashboardInputTextContent;
+        /**
+         * Editor-agnostic rich content authored via the Lexical-based
+         * editor. When this is present, the card renders via the rich-
+         * content path on both the dashboard surface and inside the visual
+         * editor. When absent (and `description` is set), the card falls
+         * back to the legacy HTML-string render path.
+         */
+        richContent?: TextCardRichContent;
+    };
+    mapVisualOptions?: {
+        topoJsonUrl?: string;
+        objectKey?: string;
+        outlineKey?: string;
+        customTopoJsonUrl?: string;
+        projection?: string;
+        projectionScale?: number;
+        projectionOffset?: [number, number];
+        colorScale?: string;
+    };
+    kpiVisualOptions?: {
+        lowerIsBetter?: boolean;
+        countryLogoId?: string;
+        valueAlignment?: 'left' | 'center';
+        formatOptions?: TFormatOptions;
+        metricComparison?: {
+            enabled?: boolean;
+            calculationType?: 'difference' | 'change' | 'change_difference' | 'ratio';
+            formatOptions?: TFormatOptions;
+            showArrow?: boolean;
+            showColor?: boolean;
+            conditionalLabel?: boolean;
+            labelName?: string;
+            position?: 'left' | 'right' | 'top';
+            conditionalLabels?: {
+                increase?: string;
+                decrease?: string;
+                noChange?: string;
+            };
+            colorConfig?: {
+                increase?: 'green' | 'red' | 'neutral' | string;
+                decrease?: 'green' | 'red' | 'neutral' | string;
+                noChange?: 'green' | 'red' | 'neutral' | string;
+            };
+        };
+    };
+    tableVisualOptions?: {
+        metricComparison?: {
+            calculatedAs?: 'difference' | 'change' | 'change_difference' | 'ratio';
+            indicatorStyle?: 'arrow_badge' | 'arrow' | 'badge' | 'none';
+            formatOptions?: TFormatOptions;
+            colors?: {
+                increase?: 'green' | 'red' | 'neutral' | string;
+                decrease?: 'green' | 'red' | 'neutral' | string;
+                neutral?: 'green' | 'red' | 'neutral' | string;
+            };
+            lowerIsBetter?: boolean;
+        };
+    };
+    pivotTableOptions?: {
+        showRowTotals?: boolean;
+        showColumnTotals?: boolean;
+        showGrandTotal?: boolean;
+        sortRowsBy?: 'label' | 'total' | 'metric';
+        sortColumnsBy?: 'label' | 'total' | 'metric';
+    };
+    displayOptions?: {
+        showFilterInfo?: boolean;
+        showCardToolbar?: boolean;
+        showChrome?: boolean;
+        allowScroll?: boolean;
+        showInlineFilterBar?: boolean;
+    };
+};
+
+declare type TChartOptions = {
+    type?: TChartType;
+    scales?: {
+        y?: {
+            type?: 'linear' | 'logarithmic';
+            min?: number;
+            max?: number;
+            ticks?: {
+                stepSize?: number;
+            };
+            grid?: {
+                display?: boolean;
+            };
+        };
+        x?: {
+            type?: 'linear' | 'logarithmic';
+            min?: number;
+            max?: number;
+            ticks?: {
+                stepSize?: number;
+            };
+            grid?: {
+                display?: boolean;
+            };
+        };
+    };
+    indexAxis?: 'x' | 'y' | undefined;
+    plugins?: {
+        legend?: TLegendOptions;
+        datalabels?: {
+            anchor?: string;
+        };
+    };
+    treemapColorMode?: 'branch' | 'category';
+};
+
+declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'matrixTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
+
+declare type TColumnSetting<T extends DisplayDataType> = {
+    columnIdx: number;
+    textAlign?: 'left' | 'center' | 'right';
+    width?: number;
+    type: T;
+    options: OptionsMap[T];
+};
+
+declare type TCustomCardPreferences = {
+    showCardHeader?: boolean;
+    url?: string;
+    componentName?: string;
+    icon?: string;
+    pluginChartType?: string;
+    type?: 'iframe' | 'component';
+    visualType?: 'single' | 'multiple';
+    minInputs?: number;
+    maxInputs?: number;
+    slotIndex?: number;
+    settings?: any;
+    slotSettings?: any;
+    /** @deprecated Use position-based data collection. Kept for legacy dashboard support. */
+    dataInputCardIds?: {
+        [key: number]: {
+            cardId: string;
+        };
+    };
+};
+
+declare type TCustomFilterPreferences = {
+    url: string;
+    componentName: string;
+    pluginFilterType?: string;
+    icon?: string;
+    settings?: Record<string, string | number | boolean>;
+};
+
+declare type TDataLabelsConfig = {
+    enabled?: boolean;
+    position?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'custom';
+    anchor?: 'center' | 'start' | 'end';
+    align?: 'center' | 'start' | 'end' | 'top' | 'bottom' | number;
+    display?: 'auto' | boolean;
+    formatMode?: 'inherit' | 'override';
+    /** @deprecated Use formatMode + formatOptions.type */
+    format?: 'auto' | 'number' | 'currency' | 'percent' | 'date' | 'scientific' | 'duration' | 'none';
+    formatOptions?: TFormatOptions;
+    font?: {
+        size?: number;
+        weight?: 'normal' | 'bold';
+    };
+    color?: 'auto' | string;
+    clamp?: boolean;
+    clip?: boolean;
+    rotation?: number;
+    showTotal?: boolean;
+    offset?: number;
+};
+
+declare type TDatasetOptions = {
+    idx: number;
+    type?: 'bar' | 'line';
+    fill?: string | number;
+    /** Y-axis assignment for combo charts: 'y' (primary/left) or 'y2' (secondary/right) */
+    yAxisId?: 'y' | 'y2';
+    /** Per-series data labels configuration - uses full TDataLabelsConfig for feature parity */
+    dataLabels?: TDataLabelsConfig;
+    /** Point radius (size) for line/area charts - 0 hides points */
+    pointRadius?: number;
+    /** Point shape style for line/area charts */
+    pointStyle?: TPointStyle;
+    /** Point radius on hover - defaults to pointRadius + 2 */
+    pointHoverRadius?: number;
+    /** Line dash style for line/area charts */
+    lineStyle?: TLineStyle;
+    /** Border radius (rounded corners) for bar charts - 0-20 pixels */
+    borderRadius?: number;
+    /** Border width for bar charts - 0-5 pixels */
+    barBorderWidth?: number;
+    /** Bar width as percentage of category width (0.1-1.0) */
+    barPercentage?: number;
+    /** Category width as percentage of available space (0.1-1.0) */
+    categoryPercentage?: number;
+    /** @deprecated Use dataLabels instead */
+    datalabels?: {
+        display?: boolean;
+        align?: string;
+        anchor?: string;
+        clamp?: boolean;
+        color?: string;
+    };
+};
+
+declare type TDynamicCardPreferences = {
+    renderer: 'dynamic-visual';
+    artifactId?: string;
+    parentArtifactId?: string;
+    title?: string;
+    rendererCode?: string;
+    question?: string;
+    provenance?: 'card-config' | 'query_spec' | 'sql' | 'sql+python';
+    visualIntent?: TDynamicVisualIntent;
+    assistantNote?: string;
+    builtinDisplayOptions?: {
+        showChrome?: boolean;
+        allowScroll?: boolean;
+    };
+    fallback: TDynamicVisualFallback;
+    error?: {
+        stage: string;
+        message: string;
+        details?: string[];
+    };
+};
+
+declare type TDynamicVisualFallback = {
+    mode: 'chart' | 'table';
+    chartType?: TChartType;
+    reason: string;
+};
+
+declare type TDynamicVisualIntent = {
+    primaryChartType?: TChartType | 'custom';
+    layout: 'chart-only' | 'composite';
+    includesKpis: boolean;
+};
+
+declare type TextCardInlineFormat = {
+    bold?: boolean;
+    italic?: boolean;
+};
+
+declare type TextCardRichBlock = {
+    type: 'paragraph';
+    children: TextCardRichInline[];
+} | {
+    type: 'heading';
+    level: 1 | 2;
+    children: TextCardRichInline[];
+} | {
+    type: 'list';
+    style: 'bulleted' | 'numbered';
+    items: TextCardRichInline[][];
+};
+
+declare type TextCardRichContent = {
+    version: 1;
+    blocks: TextCardRichBlock[];
+};
+
+declare type TextCardRichInline = {
+    type: 'text';
+    value: string;
+    format?: TextCardInlineFormat;
+} | {
+    type: 'variable';
+    ref: DashboardInputVariableRef;
+    format?: TextCardInlineFormat;
+} | {
+    type: 'link';
+    url: string;
+    children: Array<{
+        type: 'text';
+        value: string;
+        format?: TextCardInlineFormat;
+    } | {
+        type: 'variable';
+        ref: DashboardInputVariableRef;
+        format?: TextCardInlineFormat;
+    }>;
+};
+
+declare type TFormatOptions = {
+    type?: 'auto' | 'number' | 'currency' | 'percent' | 'scientific' | 'date' | 'duration';
+    decimalPlaces?: number;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    currency?: string;
+    locale?: string;
+    prefix?: string;
+    suffix?: string;
+    useSuffix?: boolean;
+    useGrouping?: boolean;
+    negativeInParentheses?: boolean;
+    multiplyBy?: number;
+    percentValueMode?: 'fraction' | 'whole';
+    dateFormat?: string;
+    timezone?: string;
+    sourceTimezone?: string;
+    relative?: boolean;
+    durationInputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationDisplayStyle?: 'compact' | 'digital' | 'long';
+    durationLargestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationSmallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationMaxUnits?: number;
+};
+
+declare type TFunnelConfig = {
+    /**
+     * How to calculate percentage in tooltips and data labels.
+     * - 'percentOfTotal': Each stage shows % of total sum (default/current behavior)
+     * - 'percentOfFirst': First stage = 100%, others relative to first
+     */
+    percentMode?: TFunnelPercentMode;
+    /**
+     * Controls how much funnel segments narrow based on their values.
+     * - 0: No shrink (all segments same width)
+     * - 1: Full shrink (segments narrow proportionally to values, default)
+     * Lower values prevent segments from becoming too narrow for labels.
+     */
+    shrinkFraction?: number;
+    /**
+     * Hide labels for segments smaller than this percentage of total.
+     * - 0: Show all labels (default)
+     * - 10: Hide labels for segments < 10% of total
+     * Range: 0-25
+     */
+    labelThreshold?: number;
+};
+
+/**
+ * Tooltip/data label percentage calculation mode for funnel charts.
+ * - 'percentOfTotal': Percentage relative to sum of all values (default)
+ * - 'percentOfFirst': Percentage relative to the first stage value (first stage = 100%)
+ */
+declare type TFunnelPercentMode = 'percentOfTotal' | 'percentOfFirst';
+
+declare type THeatmapConfig = {
+    colorMode?: 'continuous' | 'stepped';
+    steps?: number;
+    colorRange?: [string, string];
+    colorPalette?: 'blue' | 'green' | 'purple' | 'orange' | 'custom';
+    showLegend?: boolean;
+    legendPosition?: 'top' | 'bottom' | 'left' | 'right';
+    showDataLabels?: boolean;
+    nullFillColor?: string;
+    fillMissingCells?: boolean;
+    xAxisBuckets?: string[];
+    yAxisBuckets?: string[];
+};
+
+declare interface TimeDrillStep {
+    granularity: TimeGranularity;
+    next?: TimeGranularity;
+    comparison?: 'previous_year' | 'previous_period';
+    rollingWindow?: number;
+}
+
+declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+
+/**
+ * Inline filter definition stored on a card.
+ * Inline filters appear on the right-hand side of the card header,
+ * allowing ad-hoc data exploration without affecting other cards.
+ */
+declare type TInlineFilter = {
+    id: string;
+    /** Alias exposed to document/text variables, for example {{region}}. */
+    variableName?: string;
+    column: string;
+    title: string;
+    dataType: string;
+    table: string;
+    database: string;
+    qualifiedTableName?: string;
+    connectionId: string;
+    operation: Operation;
+    sql: string;
+    fieldMeta?: FilterFieldMeta;
+    semanticContext?: FilterSemanticContext;
+    /** Selection type: 'single' allows one value, 'multiple' allows many */
+    type?: 'single' | 'multiple';
+    /** UI component for single-select filters */
+    uiType?: 'radio' | 'dropdown' | 'tabs';
+    /** Date picker type: 'range' for full calendar, 'months' for month picker */
+    dateSelectionMode?: DateSelectionMode;
+    /** Default values applied when the dashboard first loads */
+    defaultValues?: (string | number)[];
+    /** Default date filter applied on dashboard load (relative or fixed month/year) */
+    defaultDateFilter?: DefaultDateFilter;
+    /** Search mode for numeric filters: 'text' treats as text, 'numeric' enables operators (>, <, =) */
+    searchMode?: 'text' | 'numeric' | 'auto';
+    /** Custom filter UI from a plugin */
+    customFilterPreferences?: TCustomFilterPreferences;
+    /** Width of the inline filter in pixels (default: 250) */
+    width?: number;
+    /** Whether to show the label above the filter (default: true) */
+    showLabel?: boolean;
+};
+
+declare type TLegendOptions = {
+    display?: boolean;
+    position?: 'top' | 'left' | 'bottom' | 'right';
+    align?: 'start' | 'center' | 'end';
+    labels?: {
+        generateLabels?: (chart: any) => any[];
+        [key: string]: any;
+    };
+};
+
+/** Line dash style options */
+declare type TLineStyle = 'solid' | 'dashed' | 'dotted' | 'dash-dot';
+
+/** Historical per-column totals shape. Runtime totals are table-level now. */
+declare type TotalsBehavior = 'sum' | 'avg' | 'count' | 'label' | 'none';
+
+/** Point style options supported by Chart.js */
+declare type TPointStyle = 'circle' | 'cross' | 'crossRot' | 'dash' | 'line' | 'rect' | 'rectRounded' | 'rectRot' | 'star' | 'triangle';
+
+declare type TTooltipFormatConfig = {
+    formatMode?: 'inherit' | 'override';
+    /** @deprecated Use formatMode */
+    mode?: 'inherit' | 'override';
+    formatOptions?: TFormatOptions;
+};
+
+declare type TVisualizationMode = 'builtin' | 'dynamic';
+
 export declare type UpdateBriefingRequest = CreateBriefingRequest;
 
+/**
+ * URL Parameter for drill-to-URL interpolation
+ * Represents a placeholder in the URL template (e.g., {{product_id}})
+ */
+declare interface URLParameter {
+    /**
+     * Unique identifier for the parameter (e.g., 'product_id', 'card_id')
+     * Used in template as {{id}}
+     */
+    id: string;
+    /**
+     * Display label for the parameter
+     */
+    label: string;
+    /**
+     * Category of the parameter
+     * - attribute: From card dimensions/attributes (e.g., product name, region)
+     * - identifier: System values (card_id, frame_id, sheet_id)
+     */
+    category: 'attribute' | 'identifier';
+    /**
+     * For attribute parameters: the complete field object
+     * Provides access to all field properties (name, qualifiedFieldName, dataType, etc.)
+     */
+    field?: Field;
+}
+
 export declare function validateBriefingContentDocument(input: unknown): BriefingValidationResult<BriefingContentDocument>;
 
 export declare function validateBriefingDraft(draft: unknown): BriefingValidationResult<CreateBriefingRequest>;
 
 export declare function validateBriefingJobConfig(input: unknown): BriefingValidationResult<BriefingJobConfig>;
 
+/**
+ * Display mode for visual components - controls which UI elements are shown
+ */
+declare type VisualDisplayMode = 'full' | 'print' | 'table-print';
+
+/**
+ * Display preferences for controlling visual component rendering
+ */
+declare type VisualDisplayPreferences = {
+    /**
+     * Predefined display mode
+     * - 'full': All UI elements (default)
+     * - 'print': Optimized for printing (shows title and description, hides interactive elements)
+     * - 'table-print': Table-specific print mode (title only, no pagination/toolbar)
+     */
+    mode?: VisualDisplayMode;
+    /**
+     * Override specific UI elements visibility
+     * These overrides take precedence over the mode presets
+     */
+    overrides?: {
+        showHeader?: boolean;
+        showTitle?: boolean;
+        showDescription?: boolean;
+        showTabs?: boolean;
+        showFooter?: boolean;
+        showFilters?: boolean;
+        showBreadcrumbs?: boolean;
+        showRefreshIndicator?: boolean;
+        showFilterInfo?: boolean;
+        showPagination?: boolean;
+        showTableToolbar?: boolean;
+        showColumnSettings?: boolean;
+    };
+};
+
+declare type WindowFunction = 'running_total' | 'moving_average' | 'previous_period_delta' | 'percent_of_total';
+
+declare interface WindowTransform {
+    function: WindowFunction;
+    orderBy?: {
+        fieldId: string;
+        direction?: 'asc' | 'desc';
+    };
+    partitionByFieldIds?: string[];
+    frame?: 'unbounded_preceding';
+    movingAverage?: {
+        windowSize?: number;
+        minPeriods?: number;
+    };
+    previousPeriodDelta?: {
+        mode?: 'absolute' | 'percent';
+    };
+    percentOfTotal?: {
+        scope?: 'grand_total' | 'partition_total';
+        output?: 'fraction' | 'percent';
+    };
+}
+
 export { }