react-semaphor 0.1.543 → 0.1.545

package/dist/types/lib/dashboard-inputs/dashboard-filter-mapping-authoring.d.ts

@@ -1,7 +1,12 @@
 import { TFilter } from '../../components/surfboard/filter/types.js';
-import { DashboardInputScope, ReferencedFilterDashboardInput, TDashboard } from '../types/common-types.js';
-import { buildDashboardCardSourceIndex, DashboardFilterCardApplication, DashboardFilterOptionSource, DashboardFilterTarget, DashboardFilterTargetField } from '../../shared/dashboard-authoring/index.js';
-import { DashboardFilterOptionPolicy } from './dashboard-filter-mapping-storage-transition.js';
+import { DashboardInputScope, TCard, TDashboard } from '../types/common-types.js';
+import { DashboardFilterApplication, DashboardFilterCardApplication, DashboardFilterTarget, DashboardFilterTargetField } from '../../shared/dashboard-authoring/index.js';
+import { FilterRef, ReachedCard } from '../../shared/dashboard-authoring/filter-model/index.js';
+/**
+ * Filter mapping (one filter model M3, SPEC 4.4): the Cards tab of any filter
+ * input. `draftDashboardFilterMapping` builds the rows from the cards the
+ * input reaches and, with them, exactly what Accept would save. Pure.
+ */
 export type DashboardFilterMappingCandidateCatalog = {
     status: 'ready';
     targets: DashboardFilterTarget[];
@@ -18,7 +23,13 @@ export type DashboardFilterMappingDraftDecision = {
 export type DashboardFilterMappingDraftStatus = 'pendingSource' | 'automatic' | 'suggested' | 'needsMapping' | 'mapped' | 'notApplicable' | 'excluded' | 'invalidMapping' | 'metadataUnavailable';
 export type DashboardFilterMappingDraftRow = {
     cardId: string;
+    /** The panel reads the title and meta line from it. */
+    card: TCard;
     sheetId: string;
+    sheetKind: 'dashboard' | 'document';
+    sectionId?: string;
+    /** The section's title, for a card in a Document section. */
+    sectionTitle?: string;
     executionKind: 'config' | 'sql' | 'unconfigured';
     status: DashboardFilterMappingDraftStatus;
     candidates: DashboardFilterTarget[];
@@ -28,27 +39,28 @@ export type DashboardFilterMappingDraftRow = {
     guidanceMessage?: string;
     automaticFieldName?: string;
 };
-export type DashboardFilterMappingDraft = {
-    filterId: string;
-    existingInputId?: string;
-    outerScope: Extract<DashboardInputScope, {
-        kind: 'allSheets' | 'sheets';
-    }>;
+export type DashboardFilterMappingGroup = {
+    sheetId: string;
+    sheetTitle: string;
+    sheetKind: 'dashboard' | 'document';
     rows: DashboardFilterMappingDraftRow[];
 };
-export type DashboardFilterMappingAuthoringIssueCode = 'filterNotFound' | 'mappingNotFound' | 'globalDateUnsupported' | 'conflictingDashboardInput' | 'unsupportedOuterScope' | 'unsupportedRuntimeScope' | 'missingDecision' | 'invalidTarget' | 'metadataUnavailable';
-export type DashboardFilterMappingAuthoringIssue = {
-    code: DashboardFilterMappingAuthoringIssueCode;
+export type DashboardFilterMappingIssueCode = 'inputNotFound' | 'globalDateUnsupported' | 'unsupportedOuterScope' | 'unsupportedRuntimeScope' | 'missingDecision' | 'invalidTarget' | 'metadataUnavailable';
+export type DashboardFilterMappingIssue = {
+    code: DashboardFilterMappingIssueCode;
     message: string;
-    filterId: string;
+    ref: FilterRef;
+    /** Set once the ref resolved. */
+    inputId?: string;
     cardId?: string;
 };
-export type DashboardFilterMappingDraftResult = {
+/** What Accept would save, computed with the rows. */
+export type DashboardFilterMappingAcceptance = {
     ok: true;
-    draft: DashboardFilterMappingDraft;
+    application: DashboardFilterApplication;
 } | {
     ok: false;
-    issues: DashboardFilterMappingAuthoringIssue[];
+    issues: DashboardFilterMappingIssue[];
 };
 export type DashboardFilterMappingStatusSummary = {
     coveredCount: number;
@@ -57,65 +69,58 @@ export type DashboardFilterMappingStatusSummary = {
     invalidCount: number;
     attentionCount: number;
 };
-/**
- * One presentation-neutral projection of authoritative Cards-tab rows.
- * Consumers must not independently reinterpret draft statuses when deciding
- * whether an author needs to act.
- */
-export declare function summarizeDashboardFilterMappingRows(rows: DashboardFilterMappingDraftRow[]): DashboardFilterMappingStatusSummary;
-export type DashboardFilterMappingAcceptanceResult = {
-    ok: true;
-    draft: DashboardFilterMappingDraft;
-    input: ReferencedFilterDashboardInput;
-} | {
-    ok: false;
-    draft?: DashboardFilterMappingDraft;
-    issues: DashboardFilterMappingAuthoringIssue[];
-};
-export type DashboardFilterMappingDisableResult = {
-    ok: true;
+export type DashboardFilterMappingDraft = {
     inputId: string;
-} | {
-    ok: false;
-    issues: DashboardFilterMappingAuthoringIssue[];
+    filterId: string;
+    /** The scope the rows were computed with: the staged scope, else the saved one. Accept never changes it (S-5). */
+    scope: Exclude<DashboardInputScope, {
+        kind: 'documentSections';
+    }>;
+    /** The cards the rows were built for; the catalogs hook fetches metadata for exactly these. */
+    cards: readonly ReachedCard[];
+    /** One group per reached tab, in dashboard tab order; rows in `cards` order. */
+    groups: DashboardFilterMappingGroup[];
+    summary: DashboardFilterMappingStatusSummary;
+    acceptance: DashboardFilterMappingAcceptance;
 };
-export type DashboardFilterInputAcceptanceResult = {
+export type DashboardFilterMappingDraftResult = {
     ok: true;
-    input: ReferencedFilterDashboardInput;
-    created: boolean;
+    draft: DashboardFilterMappingDraft;
 } | {
     ok: false;
-    issues: DashboardFilterMappingAuthoringIssue[];
+    issues: DashboardFilterMappingIssue[];
 };
-export type DashboardFilterMappingAuthoringRequest = {
-    filterId: string;
+export type DashboardFilterMappingRequest = {
+    /** The filter. Chips pass `{ inputId }`, a toolbar filter's compatibility id included. */
+    ref: FilterRef;
+    /** The dashboard as saved. */
+    dashboard: TDashboard;
+    /** The definition being edited, if changed. */
+    stagedDefinition?: TFilter;
+    /** The scope being edited, if changed; otherwise the saved scope, unnarrowed (OF-D8). */
+    stagedScope?: DashboardInputScope;
     candidatesByCardId: Record<string, DashboardFilterMappingCandidateCatalog | undefined>;
     /** Grounded field that supplies the current filter value. */
     selectionField?: Pick<DashboardFilterTargetField, 'name' | 'sourceField'> & Partial<Pick<DashboardFilterTargetField, 'source'>>;
     /**
-     * Strictly proven identities eligible for Auto. Physical datasets in a
-     * semantic domain may expose both physical and semantic identities. An
-     * explicit empty array is authoritative and must not fall back to a
-     * candidate-only selectionField source.
+     * Strictly proven identities eligible for Auto. An explicit empty array is
+     * authoritative and must not fall back to a candidate-only selectionField source.
      */
     automaticSelectionSources?: DashboardFilterTargetField['source'][];
     /** Datatype of the raw selection value, which may differ from the label. */
     selectionDataType?: string;
-    /**
-     * Re-check saved targets against selectionField after the author changes
-     * the raw Option Value identity. Explicit draft decisions still win.
-     */
+    /** Re-check saved targets after the option value field changed. */
     revalidatePersistedTargets?: boolean;
     decisionsByCardId?: Record<string, DashboardFilterMappingDraftDecision | undefined>;
-    /** Staged outer sheet scope. Omit when the author did not edit Scope. */
-    outerScope?: DashboardFilterMappingDraft['outerScope'];
-    /** Test seam; production callers use opaque random UUIDs. */
+    /** Test seam for new binding ids; production uses opaque random UUIDs. */
     createId?: () => string;
 };
-export declare function buildDashboardFilterMappingOuterScope(params: {
-    filter: Pick<TFilter, 'sheetId' | 'applyToSheetIds' | 'excludeSheetIds'>;
-    dashboard: Pick<TDashboard, 'sheets'>;
-}): DashboardFilterMappingDraft['outerScope'];
+/**
+ * One presentation-neutral projection of authoritative Cards-tab rows.
+ * Consumers must not independently reinterpret draft statuses when deciding
+ * whether an author needs to act.
+ */
+export declare function summarizeDashboardFilterMappingRows(rows: DashboardFilterMappingDraftRow[]): DashboardFilterMappingStatusSummary;
 /**
  * One Cards row for a source-qualified value field that is not a toolbar
  * filter, such as a field a click carries. It is the same decision chain the
@@ -124,8 +129,11 @@ export declare function buildDashboardFilterMappingOuterScope(params: {
  * authoring surface. Equality is the only operation a click applies.
  */
 export declare function buildDashboardFilterMappingDraftRowForValueField(params: {
-    card: Parameters<typeof buildDashboardCardSourceIndex>[0];
+    card: TCard;
     sheetId: string;
+    sheetKind: 'dashboard' | 'document';
+    sectionId?: string;
+    sectionTitle?: string;
     valueField: DashboardFilterTargetField;
     catalog: DashboardFilterMappingCandidateCatalog | undefined;
     decision?: DashboardFilterMappingDraftDecision;
@@ -133,27 +141,5 @@ export declare function buildDashboardFilterMappingDraftRowForValueField(params:
     /** Bindings already accepted elsewhere for this value field, offered as inherited matches. */
     acceptedTargets?: DashboardFilterTarget[];
 }): DashboardFilterMappingDraftRow;
-/** The reference-backed Input for a dashboard filter, mapped or not. */
-export declare function findReferencedDashboardFilterInput(dashboard: Pick<TDashboard, 'inputs'>, filterId: string): ReferencedFilterDashboardInput | undefined;
-export declare function acceptDashboardFilterInputDraft(params: {
-    dashboard: Pick<TDashboard, 'filters' | 'sheets' | 'inputs'>;
-    updatedFilter: TFilter;
-    optionSource?: DashboardFilterOptionSource;
-    /** Option dependency policy to persist; omitted keeps the existing one. */
-    optionPolicy?: DashboardFilterOptionPolicy;
-    inputMetadata?: {
-        variableName?: string;
-        forceSelection?: boolean;
-    };
-    createId?: () => string;
-}): DashboardFilterInputAcceptanceResult;
-export declare function buildDashboardFilterMappingDraft(params: {
-    dashboard: Pick<TDashboard, 'filters' | 'sheets' | 'inputs'>;
-    request: DashboardFilterMappingAuthoringRequest;
-}): DashboardFilterMappingDraftResult;
-export declare function acceptDashboardFilterMappingDraft(params: {
-    dashboard: Pick<TDashboard, 'filters' | 'sheets' | 'inputs'>;
-    request: DashboardFilterMappingAuthoringRequest;
-    updatedFilter?: TFilter;
-}): DashboardFilterMappingAcceptanceResult;
-export declare function findMappedDashboardFilterInput(dashboard: Pick<TDashboard, 'inputs'>, filterId: string): ReferencedFilterDashboardInput | undefined;
+/** The one entry point of M3 (SPEC 4.4). Pure. */
+export declare function draftDashboardFilterMapping(request: DashboardFilterMappingRequest): DashboardFilterMappingDraftResult;

package/dist/types/lib/dashboard-inputs/dashboard-input-target-context.d.ts

@@ -108,12 +108,4 @@ export declare function createExplicitDashboardInputTargetContext(params: {
     controls?: DashboardInputTargetContext['controls'];
     target?: NormalizedFilterDashboardInput;
 }): DashboardInputTargetContext;
-/**
- * Applicability for option peers. A card-local or section-local target sees
- * exactly what applies to it. A sheet-level target additionally sees the
- * Inputs local to cards or sections on that sheet, the same rule the toolbar
- * uses to decide what a sheet presents, so option narrowing and presentation
- * agree on what "on this sheet" means.
- */
-export declare function doesDashboardInputApplyToTargetScope(input: Pick<NormalizedDashboardInput, 'scope' | 'compatibility'>, scope: DashboardInputTargetScope, sheetLocalCardIds: ReadonlySet<string>): boolean;
 export declare function describeInput(input: Pick<NormalizedDashboardInput, 'id' | 'label'> & Partial<Pick<NormalizedFilterDashboardInput, 'filter'>>): string;

package/dist/types/lib/dashboard-inputs/dashboard-input-values.d.ts

@@ -18,8 +18,27 @@ export declare function setDashboardInputRuntimeSlot(values: DashboardInputValue
  */
 export declare function materializeDashboardInputRuntimeSlot(input: NormalizedDashboardInput, slot: DashboardInputSlot | undefined): DashboardInputSlot | undefined;
 export declare function removeDashboardInputRuntimeSlot(values: DashboardInputValues, input: Pick<DashboardInput, 'id' | 'runtimeScope'>, target: DashboardInputRuntimeTarget): DashboardInputValues;
+/**
+ * Whether a filter input holds an active value on a tab, as its chip shows
+ * it: its slot for the tab, the saved default included. The one rule both
+ * filter bars (the toolbar and a Document's input bar) count and clear by
+ * for Clear all. It reads the slot directly, so a filter scoped to specific
+ * cards on the tab counts although it applies to no tab-level target.
+ */
+export declare function hasActiveFilterInputValueOnTab(params: {
+    dashboard: Pick<TDashboard, 'defaultInputValues' | 'defaultFilterValues'>;
+    input: NormalizedDashboardInput;
+    runtimeValues?: DashboardInputValues;
+    sheetId: string | null | undefined;
+    calendar: CalendarContext | null;
+}): boolean;
 export declare function hydrateAuthoredDashboardInputSlot(params: {
-    dashboard: Pick<TDashboard, 'defaultInputValues'>;
+    /**
+     * Saved defaults come from the filter model (SPEC 5.2), so a toolbar
+     * filter's `defaultFilterValues` entry counts. A caller with only stored
+     * slot defaults may pass just those.
+     */
+    dashboard: Pick<TDashboard, 'defaultInputValues' | 'defaultFilterValues'>;
     input: NormalizedDashboardInput;
     runtimeValues?: DashboardInputValues;
     target: DashboardInputRuntimeTarget;
@@ -46,3 +65,18 @@ export declare function createFilterDashboardInputSlot(filterValue: TFilterValue
 export declare function createControlDashboardInputSlot(value: unknown): DashboardInputSlot | undefined;
 export declare function cloneDashboardInputValues(values: DashboardInputValues | undefined): DashboardInputValues;
 export declare function compactDashboardInputValues(values: DashboardInputValues): DashboardInputValues;
+/**
+ * `over`'s slots win; a slot it does not have keeps `base`'s. A slot of `over`
+ * that holds only a comparison choice keeps `base`'s value under it, as the
+ * old filter value list and the comparison slot stayed apart. `base` itself
+ * when `over` is empty.
+ */
+export declare function overlayDashboardInputValues(base: DashboardInputValues, over: DashboardInputValues): DashboardInputValues;
+/** The values without any slot of these inputs, on every target. `values` itself when none is held. */
+export declare function removeDashboardInputSlotsById(values: DashboardInputValues, inputIds: ReadonlySet<string>): DashboardInputValues;
+/**
+ * The saved defaults the runtime reads (SPEC 5.2): the filter model's, which
+ * hold owned `defaultFilterValues` entries as slots. With no such entry they
+ * are the stored slots, read without building the model.
+ */
+export declare function savedDefaultInputValues(dashboard: Pick<TDashboard, 'defaultInputValues' | 'defaultFilterValues'>): DashboardInputValues | undefined;

package/dist/types/lib/dashboard-inputs/filter-settings.d.ts

@@ -0,0 +1,199 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardInput, DashboardInputScope, DashboardInputValues, EmbeddedFilterDashboardInput, TDashboard } from '../types/common-types.js';
+import { GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { DashboardFilterMappingContractIssue, DashboardFilterOptionDependencies, DashboardFilterOptionPopulation, DashboardFilterOptionSource } from '../../shared/dashboard-authoring/index.js';
+import { FilterRef } from '../../shared/dashboard-authoring/filter-model/index.js';
+import { DataSource, Field } from '../types/explorer-types.js';
+import { DashboardFilterMappingDraft, DashboardFilterMappingIssue } from './dashboard-filter-mapping-authoring.js';
+import { DashboardInputRuntimeTarget } from './dashboard-input-values.js';
+import { DefaultsCalendar } from '../utils/filter-default-value-utils.js';
+/**
+ * Filter settings (one filter model M4, SPEC 4.5): every settings write of a
+ * filter input, in one transaction. `applyFilterSettingsChange` is the pure
+ * core (the next dashboard, with saved defaults, and the runtime value
+ * effects); the store's `saveFilterSettings` applies both in one write with
+ * `applyFilterValueEffects`. Every filter is an input that holds its own
+ * definition (Phase 5), so there is one storage row: the input and its slots.
+ */
+/** Every authorable setting. `undefined` = unchanged; `null` = remove. */
+export type FilterSettingsChange = {
+    /** Column, title, operator, defaults, presentation fields. Reach fields in it are ignored. */
+    definition?: TFilter;
+    label?: string;
+    variableName?: string;
+    forceSelection?: boolean;
+    requiredAtExecution?: boolean;
+    scope?: DashboardInputScope;
+    optionSource?: DashboardFilterOptionSource | null;
+    optionDependencies?: DashboardFilterOptionDependencies | null;
+    optionPopulation?: DashboardFilterOptionPopulation | null;
+    /** Save a draft's acceptance, or remove the mapping. */
+    mapping?: {
+        kind: 'save';
+        draft: DashboardFilterMappingDraft;
+    } | {
+        kind: 'remove';
+    };
+    /** Value effects the author asked for, at one runtime target. */
+    values?: {
+        /** The default this target loads changed; its runtime slot resets to the default. */
+        defaultChanged?: boolean;
+        /** Global Date and date filters: the saved comparison selection (`null` removes it). */
+        defaultComparisonSelection?: GlobalDateComparisonSelection | null;
+        /** The option value field changed; stored selections no longer mean the same values. */
+        selectionIdentityChanged?: boolean;
+        target: DashboardInputRuntimeTarget;
+    };
+};
+export type FilterSettingsIssue = DashboardFilterMappingIssue | {
+    code: 'invalidSettings';
+    message: string;
+    ref: FilterRef;
+    inputId?: string;
+    contractIssue?: DashboardFilterMappingContractIssue;
+};
+export type FilterValueEffect = {
+    kind: 'resetToDefault';
+    inputId: string;
+    target: DashboardInputRuntimeTarget;
+    filterValue?: TFilterValue;
+} | {
+    kind: 'clear';
+    inputId: string;
+    target: DashboardInputRuntimeTarget;
+} | {
+    kind: 'setDefaultComparison';
+    inputId: string;
+    target: DashboardInputRuntimeTarget;
+}
+/** A scope change: drop the live slot of a target the input no longer reaches. */
+ | {
+    kind: 'dropTargetSlot';
+    inputId: string;
+    target: DashboardInputRuntimeTarget;
+};
+export type FilterSettingsChangeResult = {
+    ok: true;
+    dashboard: TDashboard;
+    inputId: string;
+    valueEffects: FilterValueEffect[];
+} | {
+    ok: false;
+    issues: FilterSettingsIssue[];
+};
+export type FilterSettingsSaveResult = {
+    ok: true;
+    inputId: string;
+} | {
+    ok: false;
+    issues: FilterSettingsIssue[];
+};
+export type FilterSettingsContext = {
+    /** The report calendar defaults resolve in; null only before the report context loads. */
+    calendar: CalendarContext | null;
+};
+/** The effective forceSelection for a filter (moved unchanged from the authoring policy). */
+export declare function resolveFilterInputForceSelection(requested: boolean | undefined, filter: TFilter | undefined, timezone?: string): true | undefined;
+/**
+ * A new filter from a catalog field (SPEC 4.5): one shared value for every
+ * target it reaches (OF-D18), its placement derived from the definition
+ * (S-7), and a variable name unique against the existing inputs.
+ */
+export declare function buildFilterInputFromField(params: {
+    field: Field;
+    dataSource?: DataSource | null;
+    connectionId?: string;
+    connectionType?: string;
+    scope: DashboardInputScope;
+    existingInputs: readonly DashboardInput[];
+    createId?: () => string;
+}): EmbeddedFilterDashboardInput;
+/**
+ * A new filter input holding this definition (one filter model Phase 5):
+ * every new filter, from a catalog field or the toolbar's field picker, or
+ * the Global Date. One shared value for every target it reaches (OF-D18), its
+ * placement derived from the definition (S-7), a variable name unique against
+ * the existing inputs, and no reach fields (reach is the scope).
+ */
+export declare function buildFilterInputFromDefinition(params: {
+    filter: TFilter;
+    label?: string;
+    scope: DashboardInputScope;
+    existingInputs: readonly DashboardInput[];
+    createId?: () => string;
+}): EmbeddedFilterDashboardInput;
+/** The pure core (SPEC 4.5). Never partially applies. */
+export declare function applyFilterSettingsChange(dashboard: TDashboard, ref: FilterRef, change: FilterSettingsChange, context?: FilterSettingsContext): FilterSettingsChangeResult;
+/**
+ * Applies the core's value effects to the store's input values, in the same
+ * write as the dashboard (SPEC 4.5 rule 4). `before` is the dashboard the
+ * change was made on.
+ */
+export declare function applyFilterValueEffects(params: {
+    dashboardInputValues: DashboardInputValues;
+    effects: readonly FilterValueEffect[];
+    before: TDashboard;
+    after: TDashboard;
+    calendar: CalendarContext | null;
+}): DashboardInputValues;
+export type DashboardFilterStorageState = {
+    dashboardInputValues: DashboardInputValues;
+    defaultInputValues?: DashboardInputValues;
+};
+export type DashboardFilterAuthoringSettingsUpdate = {
+    forceSelection?: boolean;
+    /**
+     * The caller changed the default its target loads. Filter settings start
+     * from the target's saved default (`resolveAuthoredFilterDefaultFields`),
+     * which can differ from the definition for a scoped Input or an overlay
+     * entry, so they say so; callers that start from the definition leave it
+     * unset and the owner compares definitions. Also resets a saved slot that
+     * has no backing default.
+     */
+    defaultValueChanged?: boolean;
+    defaultComparisonChanged?: boolean;
+    defaultComparisonSelection?: GlobalDateComparisonSelection;
+    target?: DashboardInputRuntimeTarget;
+    optionSourceChanged?: boolean;
+    optionSource?: DashboardFilterOptionSource;
+    /** Authored option dependency policy edit; undefined value restores the
+     * dashboard default (omitted, meaning All applicable). */
+    optionDependenciesChanged?: boolean;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulationChanged?: boolean;
+    optionPopulation?: DashboardFilterOptionPopulation;
+    /** Raw selection identity changed; the previous runtime value is invalid. */
+    selectionIdentityChanged?: boolean;
+};
+/**
+ * Callers submit edits; the owner decides whether defaults must be reseeded.
+ * A default change (values, date window or mode) writes the target's saved
+ * default and live value; the definition, which the caller submits whole,
+ * holds the last authored default.
+ */
+export declare function resolveFilterAuthoringSettings(previous: TFilter | undefined, filter: TFilter, settings: DashboardFilterAuthoringSettingsUpdate | undefined, target: DashboardInputRuntimeTarget, calendar?: DefaultsCalendar): {
+    target: DashboardInputRuntimeTarget;
+    defaultValueChanged: boolean;
+    defaultFilterValue: TFilterValue | undefined;
+    forceSelection?: boolean;
+    defaultComparisonChanged?: boolean;
+    defaultComparisonSelection?: GlobalDateComparisonSelection;
+    optionSourceChanged?: boolean;
+    optionSource?: DashboardFilterOptionSource;
+    optionDependenciesChanged?: boolean;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulationChanged?: boolean;
+    optionPopulation?: DashboardFilterOptionPopulation;
+    selectionIdentityChanged?: boolean;
+};
+/**
+ * Applies Basic-tab default edits to the same storage transaction that changes
+ * mapped participation. This keeps the authoritative filter, mapped input, and
+ * its runtime/default slots from becoming observable in mixed states.
+ */
+export declare function applyFilterAuthoringSettingsToStorage(params: {
+    state: DashboardFilterStorageState;
+    input: Pick<DashboardInput, 'id' | 'runtimeScope'>;
+    settings?: ReturnType<typeof resolveFilterAuthoringSettings>;
+}): DashboardFilterStorageState;

package/dist/types/lib/dashboard-inputs/resolve-dashboard-input-context.d.ts

@@ -3,12 +3,17 @@ import { CardViewStateMap } from '../dashboard-view-state/index.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
 import { DashboardInputValues, NormalizedDashboardInput, ResolvedDashboardInput, ResolvedDashboardInputContext, TCard, TDashboard } from '../types/common-types.js';
 import { DashboardInputRuntimeTarget } from './dashboard-input-values.js';
-import { doesDashboardInputApplyToTarget } from './dashboard-input-scope.js';
+import { doesDashboardInputApplyToTarget } from '../../shared/dashboard-authoring/dashboard-input-scope.js';
 import { TransientInputContext } from './transient-input-context.js';
 export { doesDashboardInputApplyToTarget };
 export type DashboardInputRuntimeValues = {
     dashboardInputValues?: DashboardInputValues;
-    filterValues?: TFilterValue[];
+    /**
+     * Runtime-only values no filter defines (chart clicks, summary chips; one
+     * filter model SPEC 5.8). Input resolution never reads them; authored filter
+     * values are slots.
+     */
+    adHocFilterValues?: TFilterValue[];
     controlValues?: Record<string, unknown>;
     inlineFilterValuesMap?: Record<string, TFilterValue[] | undefined>;
     cardControlValuesMap?: Record<string, Record<string, unknown>>;

package/dist/types/lib/dashboard-inputs/resolve-selection-input.d.ts

@@ -1,6 +1,6 @@
 import { SelectionField, SelectionInputValue } from '../../shared/analytics-protocol/selection-contract.js';
 import { DashboardFilterTarget } from '../../shared/dashboard-authoring/index.js';
-import { ScopedDashboardInputTarget } from './dashboard-input-scope.js';
+import { ScopedDashboardInputTarget } from '../../shared/dashboard-authoring/dashboard-input-scope.js';
 import { NormalizedFilterDashboardInput, SelectionDashboardInput, TCard } from '../types/common-types.js';
 import { FilterCondition } from '../types/explorer-types.js';
 export type SelectionSkipReason = 

package/dist/types/lib/dashboard-viewer/captured-runtime-values.d.ts

@@ -0,0 +1,40 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardInputExecutionSnapshot, TDashboard } from '../types/common-types.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { CardViewStateMap } from '../dashboard-view-state/index.js';
+import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
+import { ViewerStoreInputValues } from './compatibility-input-storage.js';
+/** The values a card runs with: the store's input values and its view state. */
+export type CardRuntimeValues = ViewerStoreInputValues & {
+    cardViewState: CardViewStateMap;
+};
+/** The stored values one capture opens with (a print view state, a Briefing attachment's settings). */
+export type StoredCaptureValues = {
+    filterValues?: readonly TFilterValue[];
+    controlValues?: Readonly<Record<string, unknown>>;
+    /** Already selected by the caller: for a dashboard PDF, the tab's snapshot from `resolvePrintInputs`. */
+    dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
+};
+/**
+ * How a stored capture opens (one filter model SPEC 5.9): a print render, a
+ * scheduled card attachment on the server, and, with an empty capture, a
+ * fresh viewer (MCP `fromCard`). In order:
+ * 1. saved defaults, through hydration (SPEC 5.2);
+ * 2. the capture's filter value list as a host overlay (`hostFilterValuesToSlots`);
+ * 3. the capture's slot snapshot, replayed exactly (`completeDashboardInputReplacementValues`);
+ * 4. the snapshot's drill paths and carried contexts.
+ * A listed value whose `filterId` owns no input is an ad-hoc value (SPEC 5.8).
+ * The capture crossed storage, so it is read defensively, as before. Control
+ * values pass through as overrides; the caller applies the control contract
+ * to the dashboard first. Pure and server-safe: the server's
+ * `buildSavedCardRequest` calls it.
+ */
+export declare function resolveCapturedRuntimeValues(input: {
+    dashboard: TDashboard;
+    capture: StoredCaptureValues;
+    calendar: CalendarContext | undefined;
+}): {
+    runtimeValues: CardRuntimeValues;
+    controlOverrides: Readonly<Record<string, unknown>> | undefined;
+    transientContexts?: readonly TransientInputContext[];
+};

package/dist/types/lib/dashboard-viewer/compatibility-input-storage.d.ts

@@ -3,15 +3,17 @@ import { DashboardInputCompatibilityMetadata, DashboardInputValues, TDashboard }
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
 /**
  * The bridge between bookmark slots and the storage compatibility inputs
- * still use (TECH-SPEC 12, ledger P2-08). Legacy dashboard filters, controls
- * and card inline filters keep their values in `filterValues`, control values
- * and inline filter values, where the filter bar, controls and queries read
- * them. Reading turns that storage into slots; writing turns a bookmark's
- * slots back into it. When those inputs keep their values in slots, this
- * file is deleted.
+ * still use (TECH-SPEC 12, ledger P2-08). Controls and card inline filters
+ * keep their values in control values and inline filter values, where the
+ * controls and queries read them. Reading turns that storage into slots;
+ * writing turns a bookmark's slots back into it. Every dashboard filter keeps
+ * its value in a slot (one filter model Phase 4a), so its slots pass through.
+ * When controls and inline filters keep their values in slots, this file is
+ * deleted.
  */
 export type ViewerRuntimeInputs = {
-    readonly filterValues: readonly TFilterValue[];
+    /** Runtime-only values no filter defines (one filter model SPEC 5.8). */
+    readonly adHocFilterValues: readonly TFilterValue[];
     readonly controlOverrides: Readonly<Record<string, unknown>> | undefined;
     readonly dashboardInputValues: DashboardInputValues;
     /** Absent: the cards' inline filter defaults. */
@@ -19,7 +21,7 @@ export type ViewerRuntimeInputs = {
 };
 /** The input values the dashboard store holds, which cards run with. */
 export type ViewerStoreInputValues = {
-    filterValues: TFilterValue[];
+    adHocFilterValues: TFilterValue[];
     controlValues: Record<string, unknown>;
     cardControlValuesMap: Record<string, Record<string, unknown>>;
     dashboardInputValues: DashboardInputValues;
@@ -49,23 +51,21 @@ export declare function materializeViewerInputs(dashboard: TDashboard, runtime:
  */
 export declare function materializeViewerRuntimeInputs(dashboard: TDashboard, runtimeValues: Parameters<typeof materializeRuntimeInputs>[1], calendar: CalendarContext | undefined): DashboardInputValues;
 declare function materializeRuntimeInputs(dashboard: TDashboard, runtimeValues: {
-    filterValues?: TFilterValue[];
+    adHocFilterValues?: TFilterValue[];
     controlValues?: Record<string, unknown>;
     cardControlValuesMap?: Record<string, Record<string, unknown>>;
     dashboardInputValues?: DashboardInputValues;
     inlineFilterValuesMap?: Record<string, TFilterValue[] | undefined>;
 }, calendar: CalendarContext | undefined): DashboardInputValues;
 /**
- * A bookmark's slots, split by where each value lives. Authored inputs and
- * click selections are runtime slots. Inputs synthesized from legacy dashboard
- * filters, controls and card inline filters keep their values where the
- * filter bar, controls and queries read them: `filterValues`, control values
- * and inline filter values. A comparison choice stays a runtime aspect slot.
+ * A bookmark's slots, split by where each value lives. Filter inputs (every
+ * dashboard filter included) and click selections are runtime slots.
+ * Controls and card inline filters keep their values where the controls and
+ * queries read them: control values and inline filter values. A comparison
+ * choice stays a runtime aspect slot.
  */
 export type BookmarkInputs = {
     readonly runtime: DashboardInputValues;
-    /** filterId -> value, or `null` for a default the viewer removed. */
-    readonly filterValues: ReadonlyMap<string, TFilterValue | null>;
     readonly controlValues: Readonly<Record<string, unknown>>;
     /** cardId -> filterId -> value, or `null` for a removed default. */
     readonly inlineFilterValues: ReadonlyMap<string, ReadonlyMap<string, TFilterValue | null>>;