react-semaphor 0.1.537 → 0.1.538

package/dist/types/lib/stores/dashboard-store.d.ts

@@ -9,12 +9,12 @@ import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.j
 import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
 import { MissingPrintInputs } from '../print/print-inputs.js';
 import { default as ReactGridLayout } from 'react-grid-layout';
+import { DashboardFramePlacement } from '../../shared/dashboard-authoring/operations/apply-dashboard-operations.js';
 import { FilterGroup, Field } from '../types/explorer-types.js';
 import { DashboardControlsModelOptions } from '../controls/control-authoring-types.js';
 import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
 import { DocumentPanelTarget } from '../document/document-panel-target.js';
 import { DocumentEdit, DocumentEditResult } from '../document/document-edits.js';
-import { DocumentFilterMode } from '../document/document-input-runtime.js';
 import { DashboardInputRuntimeTarget } from '../dashboard-inputs/dashboard-input-values.js';
 import { DashboardFilterMappingAuthoringIssue, DashboardFilterInputAcceptanceResult, DashboardFilterMappingAcceptanceResult, DashboardFilterMappingAuthoringRequest, DashboardFilterMappingDisableResult } from '../dashboard-inputs/dashboard-filter-mapping-authoring.js';
 import { DashboardFilterOptionSource } from '../../shared/dashboard-authoring/index.js';
@@ -25,10 +25,10 @@ import { ResolvedValueFormatPreferenceSources, ResolvedValueFormatPreferences }
 import { DashboardNavigationEntry, DashboardNavigationState, DashboardTransientContextScope, InsightRenderRequest, NavigationRejection } from '../dashboard-navigation/index.js';
 import { CardViewStateMap, DrillStep } from '../dashboard-view-state/index.js';
 import { DashboardCardPaginationState } from '../dashboard-pagination/dashboard-card-pagination.js';
+export declare function mergeSemanticExecutionPayloadIntoTarget(target: SemanticExecutionPayload, incoming?: SemanticExecutionPayload): void;
 type AddFrameOptions = {
-    position?: 'start' | 'end';
-    insertAfterFrameId?: string;
-    copyLayoutFromFrameId?: string;
+    /** Default `end`; beside a frame is how a duplicate lands next to its original. */
+    placement?: DashboardFramePlacement;
     semanticExecutionPayload?: SemanticExecutionPayload;
 };
 export type FilterDashboardInputDefinitionUpdateMetadata = {
@@ -87,6 +87,15 @@ export type DashboardStore = {
     /** Live edit-session check for host navigation; owned by dashboard controls. */
     checkUnsavedDashboardChanges: (() => boolean) | null;
     isDashboardEditing: boolean;
+    /**
+     * The dashboard and its semantic payload when editing turned on (Phase 7a,
+     * D7-7). The toolbars' "before editing" reads this, so a change made in the
+     * same step that turns editing on (Add to dashboard) is an unsaved change.
+     */
+    editingStartedWith: {
+        dashboard: TDashboard;
+        semanticExecutionPayload: SemanticExecutionPayload;
+    } | null;
     isVisualEditing: boolean;
     showDashboardJSON: boolean;
     showFilters: boolean;
@@ -160,24 +169,27 @@ export type DashboardStore = {
 };
 export type DocumentInputRuntimeState = {
     filterValuesByInputId: Record<string, TFilterValue | undefined>;
-    filterModesByInputId: Record<string, DocumentFilterMode>;
     controlValuesByInputId: Record<string, unknown>;
 };
 type Actions = {
     applyResolvedCalendarPreferences: (resolved: CalendarPreferencesResponse['resolved'], sources: ResolvedCalendarPreferenceSources) => void;
     applyResolvedValueFormatPreferences: (resolved: ResolvedValueFormatPreferences, sources: ResolvedValueFormatPreferenceSources) => void;
     triggerReload: () => void;
-    setFilterMode: (filterId: string, filterMode: 'include' | 'exclude') => void;
     setInitStore: () => void;
     setGlobalStyle: (style: TStyle) => void;
-    setDefaultFilterValues: (filterValues: TFilterValue[] | undefined) => void;
-    setDefaultControlValues: (controlValues: Record<string, unknown> | undefined) => void;
     setDashboardInputs: (inputs: DashboardInput[]) => void;
     upsertDashboardInput: (input: DashboardInput) => void;
     updateFilterDashboardInputDefinition: (inputId: string, filter: TFilter, metadata?: FilterDashboardInputDefinitionUpdateMetadata) => FilterDashboardInputDefinitionUpdateResult;
     acceptDashboardFilterInput: (updatedFilter: TFilter, optionSource: DashboardFilterOptionSource | undefined, settings?: DashboardFilterAuthoringSettingsUpdate, inputMetadata?: {
         variableName?: string;
     }) => DashboardFilterInputAcceptanceResult;
+    /**
+     * Saves filter settings for a dashboard filter no Input owns: the
+     * definition, and through the default-storage owner its live value and
+     * saved overlay entry when the default changed (FM-D9). A comparison
+     * default keeps its own action (`setDefaultDashboardInputComparisonSelection`).
+     */
+    acceptOrdinaryDashboardFilter: (updatedFilter: TFilter, settings?: Pick<DashboardFilterAuthoringSettingsUpdate, 'defaultValueChanged' | 'selectionIdentityChanged' | 'target'>) => void;
     acceptDashboardFilterMapping: (request: DashboardFilterMappingAuthoringRequest, updatedFilter?: TFilter, settings?: DashboardFilterAuthoringSettingsUpdate) => DashboardFilterMappingAcceptanceResult;
     disableDashboardFilterMapping: (filterId: string, updatedFilter?: TFilter, settings?: DashboardFilterAuthoringSettingsUpdate) => DashboardFilterMappingDisableResult;
     removeDashboardInput: (inputId: string) => void;
@@ -230,6 +242,11 @@ type Actions = {
         missingPrintInputs?: MissingPrintInputs;
         /** The viewer layer for this hydration, written in the same store update. */
         viewer?: DashboardViewerState;
+        /**
+         * The viewer's inline filter values (a default bookmark's, or the live
+         * ones on a refetch). Absent: the cards' inline filter defaults.
+         */
+        inlineFilterValuesMap?: Record<string, TFilterValue[]>;
     }) => void;
     /**
      * The host's control defaults changed for the dashboard on screen: writes
@@ -260,8 +277,6 @@ type Actions = {
     setDocumentInputFilterValues: (sheetId: string, valuesByInputId: Record<string, TFilterValue | undefined>) => void;
     setDocumentInputFilterValue: (sheetId: string, inputId: string, filterValue: TFilterValue) => void;
     removeDocumentInputFilterValue: (sheetId: string, inputId: string) => void;
-    setDocumentInputFilterModes: (sheetId: string, modesByInputId: Record<string, DocumentFilterMode>) => void;
-    setDocumentInputFilterMode: (sheetId: string, inputId: string, filterMode: DocumentFilterMode) => void;
     setDocumentInputControlValues: (sheetId: string, valuesByInputId: Record<string, unknown>) => void;
     setDocumentInputControlValue: (sheetId: string, inputId: string, value: unknown) => void;
     clearDocumentInputRuntime: (sheetId?: string) => void;
@@ -294,7 +309,6 @@ type Actions = {
     }) => void;
     clearAllInlineFilterValues: () => void;
     setInlineFilterValuesMap: (map: Record<string, TFilterValue[]>) => void;
-    setCardInlineFilterMode: (sheetId: string, cardId: string, filterId: string, filterMode: 'include' | 'exclude') => void;
     setCardInlineFilterDefaultValues: (sheetId: string, cardId: string, filterId: string, defaultValues: (string | number)[] | undefined) => void;
     addFrame: (sheetId: string, frame: TFrame, positionOrOptions?: 'start' | 'end' | AddFrameOptions) => void;
     updateFrame: (sheetId: string, frame: TFrame, options?: {
@@ -432,6 +446,15 @@ export type ViewerRequestToken = {
     readonly restoreSeq: number;
     readonly client: ViewerStateClient | null;
 };
+/**
+ * Where the current edit session starts (D7-7): what the store recorded when
+ * editing turned on, else the dashboard as it is now. Both toolbars' "before
+ * editing" capture reads this.
+ */
+export declare function selectEditSessionStart(state: Pick<DashboardStore, 'editingStartedWith' | 'dashboard' | 'semanticExecutionPayload'>): {
+    dashboard: TDashboard;
+    semanticExecutionPayload: SemanticExecutionPayload;
+};
 export declare const useDashboardStore: import('zustand').UseBoundStore<Omit<import('zustand').StoreApi<DashboardStore>, "setState"> & {
     setState(nextStateOrUpdater: DashboardStore | Partial<DashboardStore> | ((state: import('immer').WritableDraft<DashboardStore>) => void), shouldReplace?: false): void;
     setState(nextStateOrUpdater: DashboardStore | ((state: import('immer').WritableDraft<DashboardStore>) => void), shouldReplace: true): void;

package/dist/types/lib/stores/editor-store.d.ts

@@ -4,6 +4,7 @@ import { TChartType } from '../charts/types.js';
 import { FilterByColumn, OldFilterValue, GroupByColumn, MetricColumn, OrderBy, QueryConfig } from '../types/query-types.js';
 import { TableActions } from './table-actions.js';
 import { CardConfig, QueryColumnKeyMap } from '../types/explorer-types.js';
+import { CardTypeChange, CardTypeChangeOptions } from '../utils/card-type-change.js';
 import { ExplorerActions } from './explorer-actions.js';
 /**
  * Draft slots for preserving work when switching between dev and standard modes.
@@ -173,8 +174,9 @@ type Actions = TableActions & ExplorerActions & {
     setSqlGen: (sqlGen: SqlGen) => void;
     setSqlGenMeasure: (name: string, calc: AggregateCalc) => void;
     setSqlGenDimension: (dimension: string) => void;
-    switchCardType: (type: TChartType) => void;
-    setCardType: (type: TChartType) => void;
+    /** `catalog` completes a join carried across the Matrix boundary (see useCardTypeSwitch). */
+    /** The one card type change (`changeCardType`); returns its decision. */
+    setCardType: (type: TChartType, options?: CardTypeChangeOptions) => CardTypeChange;
     setCardSql: (sql: string | undefined) => void;
     setCardPython: (python: string | undefined) => void;
     setCardCustomCfg: (cfg: any) => void;

package/dist/types/lib/types/token-types.d.ts

@@ -109,9 +109,13 @@ export type UIConfig = {
     projectFeatures?: {
         schemaVersion: 'project-features/v1';
         features: {
+            /** Master switch over every AI feature. Absent in tokens minted before it existed. */
+            aiFeatures?: boolean;
             dashboardAiAuthoring: boolean;
             analyticalBriefings: boolean;
             aiWritingHelpers: boolean;
+            /** The assistant switch. Absent in tokens minted before it existed. */
+            assistant?: boolean;
         };
     };
     /**
@@ -119,6 +123,13 @@ export type UIConfig = {
      * Defaults to true unless explicitly disabled.
      */
     showDirectSource?: boolean;
+    /**
+     * The assistant (analytics agent Plan 1): `enabled`, `name`, `layout`.
+     * Tokens semaphor-app issues for its own pages enable it; customers enable
+     * it in embeds. When `enabled` is absent, a token's old
+     * `showDashboardAssistant` is read in its place.
+     */
+    assistant?: import('../../shared/assistant-protocol/token-config.js').AssistantTokenConfig;
     /**
      * Enables QueryInfo debug tools for Explorer troubleshooting.
      * Defaults to true unless explicitly disabled.

package/dist/types/lib/utils/card-type-change.d.ts

@@ -0,0 +1,30 @@
+import { TCard, TCardPreferences, TCustomCardPreferences } from '../types/common-types.js';
+import { Field } from '../types/explorer-types.js';
+export declare function sharedCardPreferences(preferences: TCardPreferences | undefined): TCardPreferences;
+export type CardTypeChangeOptions = {
+    /** The loaded column catalog; the Matrix carry resolves fields against it. */
+    catalog?: readonly Field[];
+    /** True while the catalog loads: a Matrix carry then waits (P4-09). */
+    catalogLoading?: boolean;
+    /** A plugin visual chosen as `custom`. */
+    customVisual?: TCustomCardPreferences;
+};
+export type CardTypeChange = {
+    status: 'refused';
+    reason: 'catalog_loading';
+} | {
+    status: 'unchanged';
+} | {
+    status: 'changed';
+    card: TCard;
+    /** Labels of authored parts the new type could not keep. */
+    leftOut: readonly string[];
+    crossedMatrixBoundary: boolean;
+    forcesSqlMode: boolean;
+};
+/**
+ * The one decision of what changing a card's type does (ledger H-2). Every
+ * picker goes through it, so a refusal or a reset holds on every path. Pure:
+ * the editor store applies the result.
+ */
+export declare function changeCardType(card: TCard, type: TCard['type'], options?: CardTypeChangeOptions): CardTypeChange;

package/dist/types/lib/utils/comparison-window-caption.d.ts

@@ -0,0 +1,12 @@
+import { MetricComparisonWindowGrain } from '../../shared/analytics-protocol/index.js';
+export declare function formatCanonicalComparisonRange(period: {
+    start: string;
+    end: string;
+}, timezone: string, windowGrain: MetricComparisonWindowGrain | undefined, short?: boolean): string;
+export declare function formatCanonicalComparisonBoundaries(period: {
+    start: string;
+    end: string;
+}, timezone: string, windowGrain: MetricComparisonWindowGrain | undefined, short?: boolean): {
+    start: string;
+    end: string;
+};

package/dist/types/lib/utils/filter-default-value-utils.d.ts

@@ -6,12 +6,24 @@ import { TInlineFilter } from '../types/common-types.js';
  * clock and Monday weeks; a calendar carries its anchor and fiscal periods.
  */
 export type DefaultsCalendar = string | DefaultDateCalendar;
-type DefaultBackedFilter = Pick<TFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'> & Partial<Pick<TInlineFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'>>;
+export type DefaultBackedFilter = Pick<TFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'> & Partial<Pick<TInlineFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'>>;
 /**
  * Converts a filter's default configuration into an active runtime filter value.
  * Returns undefined when no defaults are configured.
  */
 export declare function buildFilterValueFromDefaults(filter: DefaultBackedFilter, calendar?: DefaultsCalendar | null): TFilterValue | undefined;
+/** A filter's authored default as settings fields: mode or range condition, values, date window. */
+export type FilterDefaultSettings = Partial<Pick<DefaultBackedFilter, 'operation' | 'defaultValues' | 'defaultDateFilter'>>;
+/** The default fields of a filter, every key present so a spread replaces them all. */
+export declare function pickFilterDefaultSettings(filter: FilterDefaultSettings): FilterDefaultSettings;
+/**
+ * Whether an edit changed what the filter's default applies: its values, its
+ * date window, or the operation it applies under (Include / Exclude, a range
+ * condition), which `buildFilterValueFromDefaults` carries onto the value.
+ * The definition's operation is authored only (filter-mode-ownership FM-D1),
+ * so an operation change is always an authoring change.
+ */
+export declare function haveFilterDefaultsChanged(previous: FilterDefaultSettings | undefined, next: FilterDefaultSettings): boolean;
 export declare function buildFilterValuesFromDefaults(filters: DefaultBackedFilter[] | undefined, calendar?: DefaultsCalendar): TFilterValue[];
 /**
  * The window a saved relative date names at the report calendar's anchor, by the
@@ -34,4 +46,3 @@ export declare function resolveSameDashboardFilterValues(params: {
     currentFilterValues: TFilterValue[] | undefined;
     defaultFilterValues: TFilterValue[];
 }): TFilterValue[];
-export {};

package/dist/types/shared/analytics-protocol/applied-constraints.d.ts

@@ -0,0 +1,74 @@
+import { FilterGroup } from '../../lib/types/explorer-types.js';
+import { MetricComparisonWindowGrain, ResolvedDateWindow } from './metric-comparison.js';
+import { RelativeDateFilter } from './relative-date-filter.js';
+/**
+ * What a governed query applied, as evidence (analytics agent Plan 1, Phase
+ * 3b, ledger D3b-4): the public conditions of the executed query, decided
+ * where the query builder settles its final filters, and the conditions it
+ * skipped with the reason. Public only: conditions are taken before security
+ * is added, and nothing here can hold a policy, a security parameter or SQL.
+ */
+/** A filter value's operation, as the query transports it. */
+export type AppliedFilterOperation = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
+/** The field a condition is on, as the query named it. */
+export type AppliedConstraintField = {
+    name: string;
+    /** The field's label, when the filter carried one. */
+    label?: string;
+    qualifiedName?: string;
+};
+export type AppliedFilterCondition = {
+    /** The filter the condition came from: a dashboard input, a request filter, a time window. */
+    filterId: string;
+    field: AppliedConstraintField;
+    operation: AppliedFilterOperation;
+    /** As executed: a relative window's values are its resolved bounds. */
+    values: unknown[];
+    valueType: 'string' | 'number' | 'date' | 'boolean';
+    /** A relative window, with the bounds it resolved to in `values`. */
+    relative?: RelativeDateFilter;
+    /**
+     * On a date condition: the calendar zone the query ran in, which its
+     * bounds' day boundaries are in. Bounds that span whole days in it read as
+     * those dates (as a comparison window's `timezone`).
+     */
+    timezone?: string;
+    /** The dashboard date replaced the card's own date range on this field for the run. */
+    replacesCardRange?: true;
+    /**
+     * The measures this condition applied to, when it applied to some of the
+     * answer's measures only (two measures compared over different periods).
+     * Absent when it applied to the whole answer.
+     */
+    measures?: string[];
+};
+export type SemaphorAppliedConstraint = ({
+    kind: 'filter';
+} & AppliedFilterCondition)
+/** The card's own saved filters (with drill steps and selections), as it ran them; `measures` as for a filter. */
+ | {
+    kind: 'card_filters';
+    filters: FilterGroup;
+    measures?: string[];
+}
+/** One measure's comparison, with both windows as the server placed them. */
+ | {
+    kind: 'comparison_window';
+    measure: string;
+    current: ResolvedDateWindow;
+    comparison: ResolvedDateWindow;
+    /** The grain the windows were placed at, for wording them. */
+    grain?: MetricComparisonWindowGrain;
+};
+/** Why a condition was left out of the executed query. */
+export type SemaphorSkippedConstraintReason = 'dataset_not_reachable' | 'field_not_resolvable' | 'missing_metadata' | 'unsupported_calculated_filter';
+export type SemaphorSkippedConstraint = {
+    filterId?: string;
+    field?: AppliedConstraintField;
+    reason: SemaphorSkippedConstraintReason;
+};
+/** On a governed analyze result; SQL and Matrix results carry none. */
+export type SemaphorQueryConstraints = {
+    applied: SemaphorAppliedConstraint[];
+    skipped: SemaphorSkippedConstraint[];
+};

package/dist/types/shared/analytics-protocol/contracts.d.ts

@@ -3,6 +3,7 @@ import { matrixAnalyticalIntentSchema } from './matrix-definition-contract.js';
 import { matrixResultSchema } from './matrix-window-contract.js';
 import { CalendarContext } from '../report-runtime-context/index.js';
 import { DateUnit } from './relative-date-filter.js';
+import { SemaphorQueryConstraints } from './applied-constraints.js';
 export type SemaphorProtocolVersion = 1;
 export type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 export type SemaphorSourceLevel = 'database' | 'schema' | 'table';
@@ -798,6 +799,8 @@ export type SemaphorAnalyticsExecutionResult = {
     relationshipDiagnostics?: SemaphorRelationshipDiagnostics;
     diagnosticFeedback?: SemaphorAnalyticsDiagnosticFeedback;
     population?: SemaphorAnalyticsPopulation;
+    /** The public conditions the executed query applied and skipped (analytics agent Plan 1, D3b-4). */
+    constraints?: SemaphorQueryConstraints;
     metadata?: Record<string, unknown>;
 };
 export type SemaphorAnalyticsDiagnosticReasonCode = 'ambiguous_fields' | 'empty_result' | 'missing_grounded_fields' | 'missing_relationship' | 'no_grounded_query' | 'partial_result' | 'presentation_incomplete' | 'query_validation_failed' | 'unsafe_join';

package/dist/types/shared/analytics-protocol/filter-field-ownership.d.ts

@@ -0,0 +1,43 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { FilterCondition, FilterGroup } from '../../lib/types/explorer-types.js';
+/**
+ * Which dashboard filter owns which of a card's fields. One field matcher
+ * and one notion of "a condition every row must pass" for the run's Global
+ * Date ownership (app `withGlobalDateOwnership`) and for adding an answer to
+ * a dashboard (`withDashboardFilterOwnership`, analytics agent Plan 1,
+ * Phase 7a, D7-6).
+ */
+/**
+ * Whether a dashboard filter value targets this field: its qualified field
+ * name, or the last name segment for an unqualified field.
+ */
+export declare function filterValueTargetsField(filter: TFilterValue, field: {
+    name: string;
+    qualifiedFieldName?: string;
+}): boolean;
+/**
+ * Whether every condition of this group must hold for a row: it is not
+ * negated, and it joins with AND (or has at most one child, so its operator
+ * joins nothing). A condition inside any other group is a branch, never a
+ * constraint on the whole card.
+ */
+export declare function isUnconditionalGroup(group: FilterGroup): boolean;
+/**
+ * The card's conditions every row must pass: the root group's and those of
+ * nested groups reached only through unconditional groups.
+ */
+export declare function unconditionalConditions(filters: FilterGroup | null | undefined): FilterCondition[];
+/**
+ * The card config without its own conditions on every field a dashboard
+ * filter that applies to it targets, so the dashboard filter decides that
+ * field (D7-6). As Global Date ownership: only the root group's conditions,
+ * and only when the root is unconditional, since removing a condition from
+ * an OR or negated group would change what the rest of the group means. The
+ * same object when nothing is owned. Pass only the filter values that apply
+ * to the card. A value with no qualified identity (a dashboard filter by
+ * column) is applied by its column name, so it owns the card's field of that
+ * name.
+ */
+export declare function withDashboardFilterOwnership<T extends {
+    filters?: FilterGroup | null;
+}>(cardConfig: T, appliedFilters: readonly TFilterValue[]): T;

package/dist/types/shared/analytics-protocol/index.d.ts

@@ -13,6 +13,8 @@ export * from './physical-source-resolution.js';
 export * from './source-entity-resolution.js';
 export * from './fixtures.js';
 export * from './metric-comparison.js';
+export * from './applied-constraints.js';
+export * from './filter-field-ownership.js';
 export * from './sort-target.js';
 export * from './dashboard-date-comparison-definition.js';
 export * from './dashboard-input-contract.js';
@@ -27,6 +29,7 @@ export * from './operation-temporal-state.js';
 export * from './aggregate-expression.js';
 export * from './measure-aggregation-profile.js';
 export * from './analytics-refusal.js';
+export * from './visual-choice.js';
 /**
  * The saved filter contract, strict: a key outside it (an execution-only
  * field the server adds while it runs a filter) fails to parse, so a save

package/dist/types/shared/analytics-protocol/matrix-window-contract.d.ts

@@ -78,7 +78,7 @@ export type MatrixFailure = {
     };
 };
 export type MatrixCapabilities = {
-    dialect: 'postgres' | 'clickhouse' | 'duckdb';
+    dialect: 'postgres' | 'clickhouse' | 'duckdb' | 'snowflake';
     aggregates: readonly MatrixAggregate[];
 };
 export type MatrixWindow = {

package/dist/types/shared/analytics-protocol/visual-choice.d.ts

@@ -0,0 +1,75 @@
+import { SemaphorResultColumn } from './contracts.js';
+/**
+ * Which visual fits a result (analytics agent Plan 1, spec 2.5, AG-D15, D4b-1).
+ * Pure and conservative: a chart only when the result proves its shape, else
+ * a table. The assistant's artifacts and the MCP analyze result's visual hint
+ * (Phase 4c) both read it.
+ */
+export declare const VISUAL_KINDS: readonly ["number", "line", "bar", "stackedBar", "table"];
+export type VisualKind = (typeof VISUAL_KINDS)[number];
+export type VisualSpec = {
+    kind: VisualKind;
+    /** Result column keys by role. A table shows every column and has none. */
+    encodings: {
+        x?: string;
+        y?: string[];
+        series?: string;
+    };
+};
+/** Everything eligibility needs. */
+export type VisualChoiceInput = {
+    columns: SemaphorResultColumn[];
+    /** The rows in hand. */
+    records: Array<Record<string, unknown>>;
+    /** Rows in the whole result. */
+    rowCount: number;
+    /** True for governed semantic analysis; false for advanced SQL. */
+    governed: boolean;
+    /** False when the result answered only part of the question. */
+    complete: boolean;
+    /** True when the result has more rows than `records`, or hit its row limit. */
+    truncated: boolean;
+};
+export type VisualChoice = {
+    ok: true;
+    visual: VisualSpec;
+    eligible: VisualKind[];
+    reason: string;
+} | {
+    ok: false;
+    code: 'kind_not_eligible';
+    eligible: VisualKind[];
+    message: string;
+};
+/** Thresholds, tuned by the regression set. */
+export declare const VISUAL_CHOICE_LIMITS: {
+    /** Fewest points on a line. */
+    readonly lineMinPoints: 2;
+    /** Most measures on one line chart. */
+    readonly lineMaxMeasures: 3;
+    /**
+     * Categories (or time points) on a bar chart. Up to `barDefaultMaxCategories`
+     * a category breakdown opens as bars; past it, up to `barMaxCategories`, it
+     * opens as a table with bars in the toggle and on request; past that, a
+     * table only.
+     */
+    readonly barMinCategories: 2;
+    readonly barDefaultMaxCategories: 12;
+    readonly barMaxCategories: 30;
+    /** Series a bar with series shows, at least and at most. */
+    readonly seriesMin: 2;
+    readonly seriesMax: 6;
+};
+export type VisualColumnRole = 'time' | 'dimension' | 'measure' | 'other';
+/**
+ * Without `requested`: the default visual and the eligible kinds, default
+ * first. With `requested`: that visual if eligible, else a refusal that names
+ * the eligible kinds.
+ */
+export declare function chooseVisual(input: VisualChoiceInput, requested?: VisualKind): VisualChoice;
+/**
+ * A column's part in a visual: a governed column by its role (a time bucket
+ * or date is time); an SQL column, or a governed one without a role, by its
+ * data type.
+ */
+export declare function visualColumnRole(column: SemaphorResultColumn, governed: boolean): VisualColumnRole;

package/dist/types/shared/assistant-context/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `react-semaphor/assistant-context`: builds the assistant's context from a
+ * dashboard (analytics agent Plan 1, spec 2.2, ledger D3a-9). Apart from the
+ * server-safe `assistant-protocol` entry because it reads the dashboard
+ * runtime's compilers; it loads in Node, where the regression set builds a
+ * case's context from a saved dashboard with `projectSavedDashboardContext`.
+ */
+export { AssistantContextSourceError, projectAssistantContext, type AssistantContextSource, type AssistantContextSourceIssue, } from './project-context.js';
+export { assistantCardReplayFields, buildSavedCardRequest, cardReplayOf, projectSavedDashboardContext, projectSavedDashboardTurn, type AssistantCardReplayFields, type SavedCardRequestRefusal, type SavedDashboardPlace, } from './saved-dashboard-context.js';

package/dist/types/shared/assistant-context/project-context.d.ts

@@ -0,0 +1,55 @@
+import { TCard, TDashboard } from '../../lib/types/common-types.js';
+import { TransientInputContext } from '../../lib/dashboard-inputs/transient-input-context.js';
+import { DashboardInputRuntimeValues } from '../../lib/dashboard-inputs/resolve-dashboard-input-context.js';
+import { CardExecutionSnapshotState } from '../../lib/query-context/describe-card-execution-snapshot.js';
+import { CalendarContext } from '../report-runtime-context/index.js';
+import { AssistantContext } from '../assistant-protocol/context.js';
+/**
+ * Builds the assistant's context from a dashboard (analytics agent Plan 1,
+ * spec 2.2, ledger D3a-2 to D3a-9). The browser calls it at send time with the
+ * asked-about card's snapshot from that card's store adapter; the regression
+ * set calls it in Node with a snapshot built from the saved dashboard.
+ *
+ * It formats what the owners compiled: inputs through the input resolver,
+ * scope through `doesDashboardInputApplyToTarget` (inside the resolver), the
+ * asked-about card through `describeCardExecutionSnapshot`, every condition
+ * through the one full-detail renderer. Throws `AssistantContextTooLargeError`
+ * when the result is over `contextBytes`, and `AssistantContextSourceError`
+ * when the source names a sheet or a selected card it does not hold: nothing
+ * asked about is dropped silently.
+ */
+export type AssistantContextSourceIssue = 'sheet_not_found' | 'card_not_found' | 'card_not_on_sheet' | 'document_inputs_not_built';
+export declare class AssistantContextSourceError extends Error {
+    readonly code: AssistantContextSourceIssue;
+    constructor(code: AssistantContextSourceIssue, message: string);
+}
+export type AssistantContextSource = {
+    surface: 'none';
+    timeZone: string;
+} | {
+    surface: 'dashboard';
+    dashboard: TDashboard;
+    /** Null only for a dashboard with no sheets. */
+    sheetId: string | null;
+    unsavedEdits: boolean;
+    /** The dashboard store's input values (the same values its cards run with). */
+    runtimeValues: DashboardInputRuntimeValues;
+    transientContexts: readonly TransientInputContext[] | undefined;
+    /**
+     * The card in focus with its snapshot: the one the user asked about, or
+     * in the editor the draft (`card`), which is described instead of the
+     * dashboard's copy (D5-3).
+     */
+    selectedCard?: {
+        cardId: string;
+        snapshot: CardExecutionSnapshotState;
+        card?: TCard;
+    };
+    /** The editor is open on the card in focus (Phase 5): the surface is the editor. */
+    editing?: {
+        mode: 'visual' | 'sql';
+    };
+    /** The report calendar the cards run in; its zone is the viewer's. */
+    calendar: CalendarContext;
+};
+export declare function projectAssistantContext(source: AssistantContextSource): AssistantContext;