react-semaphor 0.1.544 → 0.1.546

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

@@ -4,21 +4,21 @@ import { TableColumnEditResult } from '../dashboard-viewer/table-view-edit.js';
 import { Bookmark } from '../../shared/dashboard-viewer/index.js';
 import { DashboardViewerState } from '../dashboard-viewer/viewer-store-state.js';
 import { ViewerStateClient } from '../dashboard-viewer/viewer-state-client.js';
-import { AuthToken, TBaseQuery, Breakpoint, ControlDefinition, CustomCard, StyleProps, TCard, TDashboard, TEvent, TFrame, TSheet, TStyle, CacheConfig, FilterLayoutSettings, DocumentDefinition, DashboardInput, DashboardInputSlot, DashboardInputValues, DashboardLifecycleEvent } from '../types/common-types.js';
+import { AuthToken, TBaseQuery, Breakpoint, ControlDefinition, CustomCard, StyleProps, TCard, TDashboard, TEvent, TFrame, TSheet, TStyle, CacheConfig, FilterLayoutSettings, DocumentDefinition, DashboardInput, DashboardInputScope, DashboardInputSlot, DashboardInputValues, DashboardLifecycleEvent } from '../types/common-types.js';
 import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
 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 { CustomizableBreakpoint, EditableBreakpoint, FramePlacement, GridEditBreakpoint, LayoutItem } from '../../shared/layouts/index.js';
+import { DashboardOperation, OperationContext } 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 { FilterSettingsChange, FilterSettingsSaveResult } from '../dashboard-inputs/filter-settings.js';
+import { FilterRef } from '../../shared/dashboard-authoring/filter-model/index.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';
-import { DashboardFilterAuthoringSettingsUpdate } from '../dashboard-inputs/dashboard-filter-mapping-storage-transition.js';
 import { GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
 import { CalendarPreferencesResponse, ReportRuntimeContext, ResolvedCalendarPreferenceSources } from '../../shared/report-runtime-context/index.js';
 import { ResolvedValueFormatPreferenceSources, ResolvedValueFormatPreferences } from '../../shared/value-format-preferences/index.js';
@@ -27,35 +27,86 @@ 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 = {
-    /** Default `end`; beside a frame is how a duplicate lands next to its original. */
-    placement?: DashboardFramePlacement;
+    /** By intent; absent: placed by kind (RL-D12). A duplicate passes `{ position: { beside: originalId } }`. */
+    placement?: FramePlacement;
     semanticExecutionPayload?: SemanticExecutionPayload;
 };
-export type FilterDashboardInputDefinitionUpdateMetadata = {
-    variableName?: string;
-    label?: string;
-    forceSelection?: boolean;
-    exports?: DashboardInput['exports'];
-    /**
-     * Option source, dependency and population edits for an embedded Input,
-     * persisted through the same contract validation as mapped dashboard
-     * filters. Presentations that bind an embedded Input (the document input
-     * bar) carry these; dashboard-filter references persist through
-     * `acceptDashboardFilterInput` and `acceptDashboardFilterMapping` instead.
-     */
-    optionSettings?: DashboardFilterAuthoringSettingsUpdate;
+/**
+ * A proposal the assistant applied in this edit session (analytics agent
+ * Plan 1, spec 8.1, D7-20): the document before and after it, for Undo.
+ */
+export type AppliedProposal = {
+    proposalId: string;
+    before: TDashboard;
+    beforePayload: SemanticExecutionPayload;
+    after: TDashboard;
+};
+export type ApplyProposalInput = {
+    proposalId: string;
+    operations: DashboardOperation[];
+    /** The context the proposal was resolved with: its pinned calendar. */
+    context: OperationContext;
+    /** The exact document the proposal was built from (D7-19). */
+    basedOn: TDashboard;
+    /** Metadata loaded for cards the loaded metadata doesn't cover. */
+    semanticExecutionPayload?: SemanticExecutionPayload;
+};
+export type ApplyProposalRefusal = {
+    ok: false;
+    reason: 'dashboard_changed' | 'not_editable' | 'refused' | 'previous_not_applied';
+    message: string;
+};
+export type ApplyProposalResult = {
+    ok: true;
+    after: TDashboard;
+} | ApplyProposalRefusal;
+export type UndoProposalResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'changed_since' | 'not_found' | 'not_editable';
+};
+/** Arrange from the toolbar (responsive layouts SPEC §6.4, RL-D13). */
+export type ArrangeSheetResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not_editable' | 'not_a_grid';
 };
-export type FilterDashboardInputDefinitionUpdateResult = {
+export type UndoArrangeResult = {
     ok: true;
 } | {
     ok: false;
-    issues: DashboardFilterMappingAuthoringIssue[];
+    reason: 'changed_since' | 'not_found';
+};
+/** The last toolbar Arrange: `after` is the store's own document, so Undo can tell whether anything changed since (RL-INV-7). */
+export type LastArrange = {
+    sheetId: string;
+    before: TDashboard;
+    after: TDashboard;
+};
+/** The words for a proposal the dashboard could not take, for the viewer. */
+export declare const PROPOSAL_REFUSALS: {
+    readonly dashboard_changed: "Not applied: the dashboard changed while I was answering.";
+    readonly not_editable: "Not applied: close the editor and ask again.";
+    readonly no_save: "Not applied: changes to this dashboard can't be saved here.";
+    /** A change built on one that wasn't applied here: nothing to build on (P7-46). */
+    readonly previous_not_applied: "Not applied: the change before it wasn't applied.";
 };
 export type DashboardStore = {
     isDownloadingPdf?: boolean;
     isSessionExpired: boolean;
     authToken?: AuthToken;
+    /** The breakpoint the sheet grid renders: from the container width in view mode, `layoutEditBreakpoint` while editing, `lg` in print (responsive layouts SPEC §6.3). semaphor-app's BreakpointIndicator reads it. */
     currentBreakpoint: Breakpoint;
+    /** The breakpoint the editor edits (RL-D11). Reset to `lg` on dashboard load and on leaving edit mode. */
+    layoutEditBreakpoint: EditableBreakpoint;
+    /**
+     * A screen size shown look-only, or Laptop or Small phone while editing
+     * (responsive layouts RL-D18, RL-D19). null: no preview. Never saved; cleared
+     * on load, on entering or leaving edit mode, and when an editable size is chosen.
+     */
+    layoutPreviewBreakpoint: Breakpoint | null;
     theme?: 'light' | 'dark' | 'system';
     themeStyle?: StyleProps;
     filteringCards?: TCard[];
@@ -73,11 +124,6 @@ export type DashboardStore = {
      * draft-only until the editor Save path applies the current frame.
      */
     visualEditPendingFrameRewrites: Record<string, TFrame[]>;
-    /**
-     * Pending dashboard-filter metadata rewrites produced while visual editing.
-     * These stay draft-only until the editor Save path applies the current frame.
-     */
-    visualEditPendingFilterRewrites: Record<string, TFilter[]>;
     /**
      * Pending dashboard-scoped calculated-field rewrites produced while visual
      * editing. These stay draft-only until the editor Save path applies the
@@ -96,10 +142,23 @@ export type DashboardStore = {
         dashboard: TDashboard;
         semanticExecutionPayload: SemanticExecutionPayload;
     } | null;
+    /**
+     * The assistant's proposals applied in this edit session, oldest first
+     * (analytics agent Plan 1, spec 8.1, D7-20). Leaving edit mode, and every
+     * replacement of the document but a proposal's own Undo, clears them.
+     */
+    appliedProposals: AppliedProposal[];
+    /** The last toolbar Arrange, for its Undo. Cleared by any dashboard load, leaving edit mode, or a successful undo (responsive layouts SPEC §6.4). */
+    lastArrange?: LastArrange;
     isVisualEditing: boolean;
     showDashboardJSON: boolean;
     showFilters: boolean;
-    filterValues?: TFilterValue[];
+    /**
+     * Runtime-only values no filter defines: chart clicks on SQL charts and
+     * summary chips (one filter model SPEC 5.8). Never saved. Authored filter
+     * values are `dashboardInputValues` slots.
+     */
+    adHocFilterValues: TFilterValue[];
     /** Runtime-only inline filter values, keyed by cardId. Not persisted with dashboard. */
     inlineFilterValuesMap: Record<string, TFilterValue[]>;
     /** Runtime-only dashboard control values keyed by globally unique controlId. */
@@ -179,20 +238,25 @@ type Actions = {
     setGlobalStyle: (style: TStyle) => 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`).
+     * Every settings write of a filter (one filter model M4, SPEC 4.5): the
+     * definition, label, variable name, keep selection, required, scope, option
+     * settings, mapping and value effects, in one write. Nothing is written
+     * when the change is refused.
      */
-    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;
+    saveFilterSettings: (ref: FilterRef, change: FilterSettingsChange) => FilterSettingsSaveResult;
     removeDashboardInput: (inputId: string) => void;
+    /**
+     * Adds a new filter as an input holding this definition, reaching `scope`
+     * (one filter model Phase 5: every filter is an input). One Global Date per
+     * dashboard: a second is refused. Returns the new input's id.
+     */
+    addFilterInput: (filter: TFilter, scope: DashboardInputScope) => string | undefined;
+    /**
+     * Removes a filter, whichever input holds it, with its saved and runtime
+     * values (one filter model SP-9; from Phase 5 every filter is an input).
+     */
+    removeFilterInput: (ref: FilterRef) => void;
     reorderDashboardInputs: (orderedInputIds: string[]) => void;
     setDefaultDashboardInputValues: (values: DashboardInputValues | undefined) => void;
     setDefaultDashboardInputComparisonSelection: (input: Pick<DashboardInput, 'id' | 'runtimeScope'>, target: DashboardInputRuntimeTarget, selection: GlobalDateComparisonSelection | undefined) => void;
@@ -228,7 +292,14 @@ type Actions = {
         dashboardInputGeneratedAt?: string;
         reportContext?: ReportRuntimeContext;
     }) => void;
+    /**
+     * Loads a dashboard. `filterValues` is a host overlay (one filter model M5):
+     * each filter's value becomes its input's slot, under any slots in
+     * `options.dashboardInputValues`; a value no filter defines is ad-hoc.
+     */
     setDashboardWithFilterValues: (dashboard: TDashboard, filterValues: TFilterValue[], runtimeOverrides?: Record<string, unknown>, options?: {
+        /** Ad-hoc values to load (SPEC 5.8). */
+        adHocFilterValues?: TFilterValue[];
         selectedSheetId?: string | null;
         semanticExecutionPayload?: SemanticExecutionPayload;
         dashboardInputValues?: DashboardInputValues;
@@ -282,7 +353,20 @@ type Actions = {
     clearDocumentInputRuntime: (sheetId?: string) => void;
     setSelectedSheetId: (sheetId: string | null) => void;
     setSheetLayout: (sheetId: string, layout: ReactGridLayout.Layout[]) => void;
-    setSheetLayouts: (sheetId: string, layouts: ReactGridLayout.Layouts) => void;
+    /** The grid's items at the edited breakpoint after a drag or resize stop, through the layout engine (`grid_edited`). */
+    editSheetLayout: (sheetId: string, breakpoint: GridEditBreakpoint, items: LayoutItem[]) => void;
+    /** Shows a screen size look-only, or ends the preview with null (RL-D19). */
+    setLayoutPreviewBreakpoint: (breakpoint: Breakpoint | null) => void;
+    /** The screen size the editor edits: Desktop, Tablet or Phone (RL-D11). */
+    setLayoutEditBreakpoint: (breakpoint: EditableBreakpoint) => void;
+    /** "Back to automatic" for a customized Tablet or Phone layout, through the layout engine (`reset_to_automatic`). */
+    resetSheetLayout: (sheetId: string, breakpoint: CustomizableBreakpoint) => void;
+    /** Arrange from the toolbar: the `layout.arrange` operation, with edit mode on and an undo record (RL-D13, RL-INV-7). */
+    arrangeSheet: (sheetId: string, options?: {
+        keepOrder?: boolean;
+    }) => ArrangeSheetResult;
+    /** Restores the dashboard from before the last toolbar Arrange while it is still what the Arrange left. */
+    undoArrange: () => UndoArrangeResult;
     setSelectedCardId: (sheetId: string, cardId: string | null) => void;
     setSelectedFrameId: (frameId: string) => void;
     clearSelectedFrameId: () => void;
@@ -290,7 +374,7 @@ type Actions = {
     setCardInfo: (cardId: string, info: string) => void;
     setCardSql: (sheetId: string, cardId: string, sql: string) => void;
     setCardPython: (cardId: string, pythonCode: string) => void;
-    setCardDescription: (sheetId: string, cardId: string, description: string, preferences?: TCard['preferences']) => void;
+    setCardDescription: (sheetId: string, cardId: string, description: string) => void;
     setCardKpiOptions: (sheetId: string, cardId: string, kpiOptions: Record<string, any>) => void;
     updateCardFilters: (cardId: string, filters: FilterGroup | undefined) => void;
     clearCardFilters: (cardId: string) => void;
@@ -310,37 +394,40 @@ type Actions = {
     clearAllInlineFilterValues: () => void;
     setInlineFilterValuesMap: (map: Record<string, TFilterValue[]>) => void;
     setCardInlineFilterDefaultValues: (sheetId: string, cardId: string, filterId: string, defaultValues: (string | number)[] | undefined) => void;
-    addFrame: (sheetId: string, frame: TFrame, positionOrOptions?: 'start' | 'end' | AddFrameOptions) => void;
+    addFrame: (sheetId: string, frame: TFrame, options?: AddFrameOptions) => void;
     updateFrame: (sheetId: string, frame: TFrame, options?: {
         semanticExecutionPayload?: SemanticExecutionPayload;
     }) => void;
     updateSheetCalculatedFields: (sheetId: string, calculatedFields: Field[]) => void;
     updateDashboardCalculatedFields: (calculatedFields: Field[]) => void;
     setVisualEditPendingFrameRewrites: (sheetId: string, frames: TFrame[]) => void;
-    setVisualEditPendingFilterRewrites: (sheetId: string, filters: TFilter[]) => void;
     clearVisualEditPendingFrameRewrites: (sheetId?: string) => void;
-    clearVisualEditPendingFilterRewrites: (sheetId?: string) => void;
     updateCard: (sheetId: string, card: TCard) => void;
     updateFrameCard?: (sheetId: string, frameId: string, card: TCard) => void;
     updateCurrentDashboardCard: (card: TCard) => void;
     removeFrame: (sheetId: string, frameId: string) => void;
     removeCard: (sheetId: string, card: TCard) => void;
     setIsDashboardEditing: (editing: boolean) => void;
+    /**
+     * Applies an assistant proposal to the dashboard on screen (spec 8.1,
+     * D7-18, D7-27): only while the dashboard is still `basedOn`, checked and
+     * written in one step, with edit mode on and an undo record. Callers go
+     * through `useApplyProposal`, which loads the metadata first.
+     */
+    applyProposal: (input: ApplyProposalInput) => ApplyProposalResult;
+    /** Undoes the newest applied proposal while the dashboard is still what it left (D7-20). */
+    undoProposal: (proposalId: string) => UndoProposalResult;
     setShowDashboardJSON: (show: boolean) => void;
     setIsVisualEditing: (editing: boolean) => void;
     setShowFilters: (show: boolean) => void;
     setFilterLayout: (settings: Partial<FilterLayoutSettings>) => void;
-    addFilter: (filter: TFilter) => void;
-    removeFilter: (filterId: string) => void;
-    reorderFilters: (orderedFilterIds: string[]) => void;
-    updateFilter: (filter: TFilter) => void;
-    updateFilterId: (filterId: string, newId: string) => void;
-    setFilterDefaultValues: (filterId: string, defaultValues: (string | number)[] | undefined) => void;
-    setFilterValues: (filterValues: TFilterValue[] | undefined) => void;
-    addOrUpdateFilterValue: (filterValue: TFilterValue) => void;
-    addOrUpdateFilterValues: (filterValues: TFilterValue[]) => void;
-    removeFilterValues: (filterId: string) => void;
-    replaceFilterValue: (filterValue: TFilterValue) => void;
+    /** Adds or replaces ad-hoc values by `filterId`; a value with no values removes its entry. */
+    addOrUpdateAdHocFilterValues: (filterValues: TFilterValue[]) => void;
+    /** Removes every ad-hoc value whose id starts with the prefix: everything one chart added (SPEC 5.8). */
+    removeAdHocFilterValues: (idPrefix: string) => void;
+    clearAdHocFilterValues: () => void;
+    /** Clears every filter's value on every target, and every ad-hoc value (a card popover's Clear all). */
+    clearAllFilterValues: () => void;
     setStyle: (style: TStyle) => void;
     getStyle: () => TStyle | undefined;
     setOnSaveFunction: (onSaveFunction: (dashboard: TDashboard) => void) => void;
@@ -358,7 +445,6 @@ type Actions = {
     getCardSheet: (cardId: string) => TSheet | undefined;
     getSelectedSheetLayout: () => ReactGridLayout.Layout[] | undefined;
     getSelectedSheetLayouts: () => ReactGridLayout.Layouts | undefined;
-    handleDataPointClickAction: (card: TCard, dataPoint: any) => void;
     addBaseQuery: (baseQuery: TBaseQuery) => void;
     removeBaseQuery: (baseQueryId: string) => void;
     setBaseQueries: (baseQueries: TBaseQuery[]) => void;
@@ -451,6 +537,23 @@ export type ViewerRequestToken = {
  * editing turned on, else the dashboard as it is now. Both toolbars' "before
  * editing" capture reads this.
  */
+/**
+ * Whether a toolbar that owns the edit session (the package's or the app's)
+ * is mounted: each registers its unsaved-changes check while mounted. Where
+ * none is, there is no Save, so nothing changes the dashboard (D7-32).
+ */
+export declare function selectHasEditingToolbar(state: Pick<DashboardStore, 'checkUnsavedDashboardChanges'>): boolean;
+/**
+ * Where an applied proposal stands for its block (spec 8.1, D7-20):
+ * `undoable` while it is the newest and the dashboard is still what it left,
+ * `older` with a newer one after it while the dashboard is still what the
+ * newest left, `changed_since` for every record after the person's own edit
+ * (their change may have undone this one, P7-36), `none` when its record is
+ * gone.
+ */
+export type ProposalRecordState = 'undoable' | 'older' | 'changed_since' | 'none';
+export declare function selectProposalRecordState(state: Pick<DashboardStore, 'appliedProposals' | 'dashboard'>, proposalId: string): ProposalRecordState;
+export declare function selectProposalUndoable(state: Pick<DashboardStore, 'appliedProposals' | 'dashboard'>, proposalId: string): boolean;
 export declare function selectEditSessionStart(state: Pick<DashboardStore, 'editingStartedWith' | 'dashboard' | 'semanticExecutionPayload'>): {
     dashboard: TDashboard;
     semanticExecutionPayload: SemanticExecutionPayload;

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

@@ -33,7 +33,6 @@ export type EditorContext = {
     documentFilterValues?: TFilterValue[];
     documentControlDefinitions?: ControlDefinition[];
     documentControlValues?: Record<string, unknown>;
-    missingRequiredInputLabels?: string[];
 };
 /**
  * Factory function to create empty KPI card configuration
@@ -71,7 +70,6 @@ export type EditorStore = {
     activeTabCardId?: string | null;
     showFilters: boolean;
     applyFilters: boolean;
-    filterValues?: TFilterValue[];
     inlineFilterValuesMap: Record<string, TFilterValue[]>;
     queryResultColumns: string[];
     queryResultColumnKeyMap?: QueryColumnKeyMap;
@@ -183,7 +181,6 @@ type Actions = TableActions & ExplorerActions & {
     setCardConfig: (config: CardConfig | undefined) => void;
     setShowFilters: (showFilters: boolean) => void;
     setApplyFilters: (applyFilters: boolean) => void;
-    setFilterValues: (filterValues: TFilterValue[]) => void;
     setInlineFilterValuesMap: (map: Record<string, TFilterValue[]>) => void;
     setCardInlineFilterValue: (cardId: string, filterValue: TFilterValue) => void;
     removeCardInlineFilterValue: (cardId: string, filterId: string) => void;

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

@@ -138,6 +138,14 @@ export type VisualDisplayPreferences = {
      * exactly as today (report attachment delivery RA-D11).
      */
     delivery?: 'strict';
+    /**
+     * An emailed card image (PNG exports PN-D13): the card is drawn at the size
+     * its saved layout has on a dashboard this many CSS pixels wide, by the
+     * dashboard grid's own geometry. Read by `Visual` only.
+     */
+    imageLayout?: {
+        dashboardWidth: number;
+    };
     /**
      * Override specific UI elements visibility
      * These overrides take precedence over the mode presets
@@ -161,12 +169,6 @@ export type VisualDisplayPreferences = {
  * Filter layout settings for controlling how dashboard filters are displayed
  */
 export type FilterLayoutSettings = {
-    /**
-     * Display mode for filters
-     * - 'canvas': Filters displayed as draggable/resizable cards on the dashboard canvas (default)
-     * - 'toolbar': Filters displayed in a compact horizontal toolbar below dashboard controls
-     */
-    displayMode?: 'canvas' | 'toolbar';
     /**
      * Whether the toolbar should wrap filters to multiple lines
      * - false: Horizontal scroll when filters overflow (default)
@@ -313,6 +315,8 @@ export type AuthToken = {
     refreshToken?: string;
 };
 export type Breakpoint = 'lg' | 'md' | 'sm' | 'xs' | 'xxs';
+/** The breakpoints a person may customize on purpose: Tablet and Phone (responsive layouts RL-D14). */
+export type CustomizableBreakpoint = Extract<Breakpoint, 'sm' | 'xs'>;
 type FilterOnClick = {
     expression?: string;
     columnIndex: number;
@@ -931,14 +935,27 @@ export type ControlBinding = {
     mapping: Record<string, string>;
 } | CurrencyPresentationBinding;
 export type DashboardInput = FilterDashboardInput | ControlDashboardInput;
+/**
+ * Which tabs and cards an input reaches. The one owner of reach; read it only
+ * through the scope rule (`doesDashboardInputApplyToTarget`,
+ * `isDashboardInputOnTab` in react-semaphor `dashboard-authoring`).
+ */
 export type DashboardInputScope = {
     kind: 'allSheets';
+    /** Omitted = tabs of both kinds. */
     sheetKinds?: Array<'dashboard' | 'document'>;
+    /** Every allowed tab except these. A tab added later is included. */
+    exceptSheetIds?: string[];
+    /** Every card on the reached tabs except these. A card added later is included. */
+    exceptCardIds?: string[];
 } | {
     kind: 'sheets';
+    /** May be empty: the input reaches nothing. */
     sheetIds: string[];
+    exceptCardIds?: string[];
 } | {
     kind: 'cards';
+    /** May be empty: the input reaches nothing. */
     cardIds: string[];
 } | {
     kind: 'documentSections';
@@ -1506,6 +1523,12 @@ export type TSheet = {
     description?: string;
     layout?: ReactGridLayout.Layout[];
     layouts?: ReactGridLayout.Layouts;
+    /**
+     * The breakpoints edited on purpose (responsive layouts RL-D3); every other
+     * breakpoint but `lg` is derived from `lg` by the layout engine
+     * (`src/shared/layouts`). Absent on a sheet the engine has never written.
+     */
+    customizedBreakpoints?: CustomizableBreakpoint[];
     cards?: TCard[];
     frames?: TFrame[];
     calculatedFields?: Field[];

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

@@ -212,6 +212,14 @@ export interface MetricField extends Field {
      * pre-aggregated metric input.
      */
     isPreAggregated?: boolean;
+    /**
+     * The governed compiler's aggregate provenance, saved with every card it
+     * compiles (semaphor-app `buildMetricField`): the semantic model's
+     * aggregate, the one applied, and where it came from.
+     */
+    semanticAggregate?: AggregateFunction;
+    effectiveAggregate?: AggregateFunction;
+    aggregateSource?: 'semantic_model' | 'caller_override' | 'default_sum';
     comparison?: MetricComparisonConfig;
     comparisonPolarity?: MetricComparisonPolarity;
     /** Governed runtime annotation. When present, authoring polarity is read-only. */
@@ -478,6 +486,8 @@ export interface FilterCondition {
      * it was saved.
      */
     latestValue?: true;
+    /** Set when the governed compiler added the latest-value condition by a snapshot dataset's policy (no stated window), not someone's choice: a read leaves it unstated and a recompile adds it again. */
+    latestValuePolicy?: 'snapshot';
 }
 export interface FilterGroup {
     id: string;

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

@@ -0,0 +1,84 @@
+/**
+ * Joinability types: the response of GET /api/v1/domains/[domainId]/joinability,
+ * used by field draggability states in the query builder.
+ *
+ * The domain template contract (datasets, fields, metrics, relationships) has one
+ * owner, semaphor-app (`src/lib/semantic/template/contract.ts`); it is not copied
+ * here. If a react-semaphor consumer ever needs template types, move the contract
+ * into react-semaphor's shared contracts and have the app import it, rather than
+ * copy it (domain template 2.1, ledger P2-20).
+ */
+/**
+ * Joinability map for a semantic domain
+ *
+ * Maps each dataset to the datasets it can join with, including both direct (1-hop)
+ * and indirect (2-hop) joins. This is a lightweight topology representation used by
+ * the frontend for UX feedback (field draggability states).
+ *
+ * The backend generates this from the full relationship definitions and serves it
+ * via GET /api/v1/domains/[domainId]/joinability
+ */
+export interface JoinabilityMap {
+    [datasetName: string]: {
+        /**
+         * Datasets that can be joined directly (1-hop)
+         * Example: orders.canJoinTo = ['customers', 'products']
+         */
+        canJoinTo: string[];
+        /**
+         * Datasets that require multi-hop joins (2-hop)
+         * Key: target dataset name
+         * Value: array of intermediate datasets to traverse
+         *
+         * Example: orders.indirectJoins = { countries: ['stores'] }
+         * Means: orders → stores → countries
+         */
+        indirectJoins: {
+            [targetDataset: string]: string[];
+        };
+        /**
+         * Datasets related by an ACTIVE relationship that is not set to join
+         * automatically. The query engine will not auto-join these; the user
+         * has to enable automatic join on the relationship or configure the
+         * join on the chart. Drives the "Requires setup" field state.
+         * Optional: older servers omit it.
+         */
+        manualJoins?: string[];
+        /**
+         * Direct neighbours connected by MORE THAN ONE active auto-join
+         * relationship, with the count. The engine picks by join priority,
+         * so this is informational ("Multiple relationships; highest
+         * priority is used"), never blocking. Optional.
+         */
+        ambiguousJoins?: {
+            [targetDataset: string]: number;
+        };
+        /**
+         * Cardinality of the direct auto-join, from THIS dataset's side.
+         * `one_to_many` means one row here matches many rows there, so an
+         * aggregate over this dataset's values joined to that dataset may
+         * repeat. `unknown` when the relationship has no authored cardinality
+         * (the planner refuses repeat-sensitive measures across it).
+         * Informational; drives a warning, never a block. Optional.
+         */
+        cardinality?: {
+            [targetDataset: string]: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many' | 'unknown';
+        };
+    };
+}
+/**
+ * Response from the joinability map API
+ */
+export interface JoinabilityMapResponse {
+    /** Lightweight joinability map for field state calculation */
+    joinabilityMap: JoinabilityMap;
+    /** Minimal dataset information */
+    datasets: Array<{
+        name: string;
+        label: string;
+        type: string;
+        table?: string | null;
+        catalog?: string | null;
+        schema?: string | null;
+    }>;
+}

package/dist/types/lib/utils/build-saved-editor-card.d.ts

@@ -0,0 +1,20 @@
+import { TCard } from '../types/common-types.js';
+type BuildSavedEditorCardOptions = {
+    isDevMode: boolean;
+    cardSql?: string;
+    selectedSchemaName?: string;
+    selectedDatabaseName?: string;
+    selectedTableName?: string;
+    selectedConnectionId?: string;
+    remoteChartSettings?: unknown;
+    stripConfig: (config: TCard['config']) => TCard['config'];
+};
+/**
+ * The card the editor saves. The editor's picker selection (database,
+ * schema, table, data model) is not written onto the card: a card's source is
+ * its `dataSource`, so Done with no change leaves the card as it was
+ * (MCP dashboard editing ledger V-50, V-58). A stored card's older copies of
+ * the picker stay as they are, read by nothing at run time.
+ */
+export declare function buildSavedEditorCard(card: TCard, { isDevMode, cardSql, selectedSchemaName, selectedDatabaseName, selectedTableName, selectedConnectionId, remoteChartSettings, stripConfig, }: BuildSavedEditorCardOptions): TCard;
+export {};

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

@@ -8,6 +8,11 @@ export type CardTypeChangeOptions = {
     catalogLoading?: boolean;
     /** A plugin visual chosen as `custom`. */
     customVisual?: TCustomCardPreferences;
+    /**
+     * Mints the ids the conversion needs (Matrix field instances), in order.
+     * Default `crypto.randomUUID`; a replayed change passes its stored ids (DE-D54).
+     */
+    createId?: () => string;
 };
 export type CardTypeChange = {
     status: 'refused';
@@ -19,6 +24,8 @@ export type CardTypeChange = {
     card: TCard;
     /** Labels of authored parts the new type could not keep. */
     leftOut: readonly string[];
+    /** Chart-scoped preference keys the new type drops (DE-D43). */
+    droppedPreferences: readonly (keyof TCardPreferences)[];
     crossedMatrixBoundary: boolean;
     forcesSqlMode: boolean;
 };
@@ -28,3 +35,12 @@ export type CardTypeChange = {
  * the editor store applies the result.
  */
 export declare function changeCardType(card: TCard, type: TCard['type'], options?: CardTypeChangeOptions): CardTypeChange;
+/**
+ * A type change as a person makes it in the editor (MCP dashboard editing
+ * DE-D51, ledger P2-01): the chart picker is `changeCardType`; between table
+ * kinds the table editor's tabs are `switchTableType`. A detail table is
+ * reached only through the tabs, so a change into or out of one goes through
+ * a table, as the editor's two steps do. The dashboard reducer's `retype`
+ * calls this; the editor keeps calling each half from its own control.
+ */
+export declare function changeCardTypeAsEditor(card: TCard, type: TCard['type'], options?: CardTypeChangeOptions): CardTypeChange;

package/dist/types/lib/utils/field-availability-context.d.ts

@@ -0,0 +1,25 @@
+import { TCard } from '../types/common-types.js';
+import { AutoJoinMetadata } from '../types/query-types.js';
+import { JoinabilityMapResponse } from '../types/semantic-types.js';
+import { FieldStateContext } from './field-state-calculator.js';
+/**
+ * Everything `calculateFieldState` needs about a visual, except the
+ * selected fields (which differ per call). Built by ONE function so the
+ * field list, the click gate, the drop gate, and the matrix editor judge
+ * the same card from the same facts: the same join plan (the authored
+ * one, which is also right for matrix cards), the same auto-resolved
+ * base, the same relationship map, aliases, labels, mode, and data-source
+ * anchor. A caller that assembles these by hand will eventually disagree
+ * with the others; do not.
+ */
+export type FieldAvailabilityContext = Omit<FieldStateContext, 'selectedFields'> & {
+    /** The semantic domain the card reads, when any. */
+    semanticDomainId?: string;
+};
+export declare function buildFieldAvailabilityContext(input: {
+    card: Pick<TCard, 'type' | 'config' | 'dataSource'> | null | undefined;
+    joinabilityData?: JoinabilityMapResponse | null;
+    autoJoinMetadata?: AutoJoinMetadata;
+    /** Labels the caller knows from elsewhere (entity groups); catalog labels win. */
+    extraDatasetLabels?: Record<string, string>;
+}): FieldAvailabilityContext;