react-semaphor 0.1.544 → 0.1.546

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

@@ -0,0 +1,201 @@
+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;
+    /** The filter's label (and variable name); default the field's label. */
+    label?: 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/prepare-loaded-dashboard.d.ts

@@ -0,0 +1,15 @@
+import { TDashboard } from '../types/common-types.js';
+/**
+ * A saved dashboard as it enters a runtime (one filter model SPEC 5.1): the
+ * filter model's stored shape, every filter an embedded input, when the
+ * model reads it without issues; otherwise the template as received, read
+ * tolerantly (rejected inputs left out) and refused on save. Then the
+ * Include / Exclude repair. Loading never throws on model issues.
+ *
+ * The one entry for every runtime: the client load (`useDashboard`), the
+ * store's replace and load (`setDashboard`, `setDashboardWithFilterValues`)
+ * and the server's saved-dashboard reader, so they all hold the same shape.
+ * The same object when nothing changes. Alias-based text is bound to stable
+ * input ids before the upgrade (`upgradeToStoredDashboard`, ledger P5-11).
+ */
+export declare function prepareLoadedDashboard<TDashboardShape extends TDashboard>(dashboard: TDashboardShape): TDashboardShape;

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>>;

package/dist/types/lib/dashboard-viewer/viewer-state.d.ts

@@ -1,16 +1,13 @@
 import { DashboardInputValues, TDashboard } from '../types/common-types.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
 import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { HostFilterValue } from '../../shared/dashboard-authoring/filter-model/filter-values.js';
 import { ViewerTableSettings } from '../../shared/dashboard-viewer/table-settings.js';
 import { Bookmark, BookmarkState } from '../../shared/dashboard-viewer/viewer-contract.js';
 /** The report runtime's calendar, as filter defaults read it. */
 /** The viewer's report calendar, from report preferences (card query assembly CQ-D8). */
 export type ViewerCalendar = CalendarContext;
-/** A host filter default: a full filter value, or the short `{ filterId, values }` embed form. */
-export type HostFilterValue = TFilterValue | {
-    readonly filterId: string;
-    readonly values: string[] | number[];
-};
+export type { HostFilterValue };
 /** Host app defaults, exactly as hydration receives them today (embed props). */
 export type HostDefaults = {
     readonly filterValues?: readonly HostFilterValue[];
@@ -19,7 +16,11 @@ export type HostDefaults = {
     readonly selectedSheetId?: string;
 };
 export type ViewerBaseline = {
-    readonly filterValues: readonly TFilterValue[];
+    /**
+     * The host's filter defaults as input slots (M5 `hostFilterValuesToSlots`).
+     * Authored defaults are not seeded: input resolution hydrates them.
+     */
+    readonly hostInputValues: DashboardInputValues;
     /** Passed to `setDashboardWithFilterValues` as `runtimeOverrides`. */
     readonly controlOverrides: Readonly<Record<string, unknown>> | undefined;
     /** The host's sheet when valid, else the author's first sheet. */
@@ -55,9 +56,10 @@ export type RememberedSettingsWrite = {
 };
 /** The store values a view consists of. */
 export type ViewerValues = {
-    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;
-    /** Runtime input slots: a bookmark's slots only (overlay). Never completed as `cleared`. */
+    /** Runtime input slots: the host's defaults with a bookmark's slots over them. Never completed as `cleared`. */
     readonly dashboardInputValues: DashboardInputValues;
     /** Card inline filter values when they differ from the cards' defaults. Absent: the defaults. */
     readonly inlineFilterValuesMap?: Readonly<Record<string, readonly TFilterValue[]>>;
@@ -90,7 +92,7 @@ export type ViewerLiveState = {
     readonly previousDashboard: TDashboard;
     /** The baseline of the previous hydration; a changed host prop wins over the live value. */
     readonly previousBaseline: ViewerBaseline | null;
-    readonly filterValues: readonly TFilterValue[];
+    readonly adHocFilterValues: readonly TFilterValue[];
     /**
      * Live control values, flattened. `undefined` when the control contract
      * changed: the baseline's control defaults apply again.

package/dist/types/lib/download-pdf.d.ts

@@ -44,7 +44,41 @@ export type VisualPdfParams = {
     presentationExecutionSnapshot: PresentationExecutionSnapshot;
     timezone?: string;
 };
-type VisualPrintRuntimeOverrides = {
+type DashboardPdfParams = {
+    /** The viewer's table settings captured at the click (PLAN B20). */
+    viewerTableSettings?: Readonly<Record<string, ViewerTableSettings>>;
+    authToken: AuthToken;
+    theme: string;
+    filterValues: TFilterValue[];
+    defaultControlValues?: Record<string, unknown>;
+    controlDefinitions?: ControlDefinition[];
+    cardControlDefinitions?: ControlDefinition[];
+    controlBindings?: ControlBinding[];
+    dashboardId: string;
+    fileName: string;
+    password?: string;
+    cardTitle?: string;
+    filterLine?: string;
+    timezone?: string;
+    dashboardTitle?: string;
+    selectedSheetId?: string;
+    sheetSelection?: 'current' | 'all';
+    visualId?: string;
+    frameId?: string;
+    tableMode?: boolean;
+    pdfMode?: 'document';
+    documentSheetId?: string;
+    dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
+    printInputCapture?: PrintInputCapture;
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
+    documentInputValues?: DocumentInputRuntimeValues;
+    cardType?: string;
+    pageSize?: string;
+    orientation?: string;
+    expandedState?: Record<string, boolean>;
+    wideTableStrategy?: 'auto' | 'fit' | 'horizontal_paginate';
+};
+export type VisualPrintRuntimeOverrides = {
     filterValues?: TFilterValue[];
     /** Replaces the store's viewer table settings (`{}` where the authored table applies, such as the editor preview). */
     viewerTableSettings?: Readonly<Record<string, ViewerTableSettings>>;
@@ -73,6 +107,46 @@ export declare function appendControlContractParams(urlParams: URLSearchParams,
     cardControlDefinitions?: ControlDefinition[];
     controlBindings?: ControlBinding[];
 }): void;
+/**
+ * The render state the print view needs to reproduce what the user saw. It is
+ * posted with the presentation snapshot and stored server-side behind the
+ * snapshot reference; it never travels in a URL. Key names match the print
+ * view's props contract in the app (`PrintViewState`).
+ */
+type PrintViewStateInput = Pick<DashboardPdfParams, 'filterValues' | 'defaultControlValues' | 'controlDefinitions' | 'cardControlDefinitions' | 'controlBindings' | 'documentInputValues' | 'dashboardInputExecutionSnapshot' | 'printInputCapture' | 'expandedState' | 'viewerTableSettings'>;
+export declare function buildPrintViewState(params: PrintViewStateInput): {
+    viewerTableSettings: Readonly<Record<string, ViewerTableSettings>>;
+    expandedState?: Record<string, boolean> | undefined;
+    printInputCapture?: PrintInputCapture | undefined;
+    dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot | undefined;
+    documentInputValues?: DocumentInputRuntimeValues | undefined;
+    controlBindings?: ControlBinding[] | undefined;
+    cardControlDefinitions?: ControlDefinition[] | undefined;
+    controlDefinitions?: ControlDefinition[] | undefined;
+    filterValues: TFilterValue[];
+    controlValues: Record<string, unknown>;
+};
+/** A rendered export the server refused or could not make, with its error code when it sent one. */
+export declare class RenderedExportError extends Error {
+    readonly code: string | null;
+    constructor(message: string, code: string | null);
+}
+export type PrintViewStateBody = ReturnType<typeof buildPrintViewState>;
+/**
+ * The one transport for every file the renderer draws from the print view
+ * (PDF and PNG, PNG exports SPEC §3.1): the view state goes into a print
+ * render record, `query` (identity and options) and the record reference go
+ * to `GET /v1/pdf`, and the returned link is saved as `fileName`. Undefined
+ * when another rendered export is running in this dashboard; nothing is sent.
+ */
+export declare function requestRenderedFile(apiServiceUrl: string, request: {
+    authToken: AuthToken;
+    viewState: PrintViewStateBody;
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
+    password?: string;
+    query: URLSearchParams;
+    fileName: string;
+}): Promise<PdfDownloadResponse | undefined>;
 export declare function getDashboardParamsForPrint(authToken: AuthToken | undefined, options?: {
     selectedSheetId?: string | null;
     sheetSelection?: 'current' | 'all';

package/dist/types/lib/hooks/use-date-filter.d.ts

@@ -4,6 +4,11 @@ type UseDateFilterOptions = FilterStorageOptions;
 type DateFilterChangeOptions = {
     temporalPrecision?: TemporalPrecision;
 };
+/**
+ * The public hook: the filter resolves through the filter model, so any
+ * dashboard filter works, and its value is its input's slot on the current
+ * tab (one filter model SPEC 4.7).
+ */
 export declare function useDateFilterHook(filterId: string): {
     records: Record<string, unknown>[] | undefined;
     isLoading: boolean;

package/dist/types/lib/hooks/use-text-filter.d.ts

@@ -1,5 +1,10 @@
 import { TFilter, TFilterValue, TSelectedRecord, FilterStorageOptions } from '../../components/surfboard/filter/types.js';
 import { FilterMode } from '../filter-values/filter-mode.js';
+/**
+ * The public hook: the filter resolves through the filter model, so any
+ * dashboard filter works, and its value is its input's slot on the current
+ * tab (one filter model SPEC 4.7).
+ */
 export declare function useTextFilterHook(filterId: string): {
     isLoading: boolean;
     isFetching: boolean;

package/dist/types/lib/matrix-table/matrix-delivery-policy.d.ts

@@ -13,8 +13,9 @@ export declare const MATRIX_EXPORT_CONTENT: readonly [{
 /**
  * What a Matrix download or attachment may be: PDF, CSV and Excel for the
  * layout, CSV and Excel for Flat content, which is a data file only
- * (XL-D16). Downloads off leaves PDF of the layout. One policy for the export
- * dialog and Briefing attachments.
+ * (XL-D16). A PNG is the Matrix as it opens, so it belongs to the current
+ * layout only (PNG exports PN-SI-9). Downloads off leaves PDF and PNG of the
+ * layout. One policy for the export dialog and Briefing attachments.
  */
 export declare function matrixDeliveryOptions(allowDownload?: boolean, content?: MatrixExportContent): {
     contents: ({
@@ -27,7 +28,7 @@ export declare function matrixDeliveryOptions(allowDownload?: boolean, content?:
         readonly value: "flat";
         readonly label: "Flat aggregate table";
     })[];
-    formats: import('../types/index.js').BriefingAttachmentFormat[];
+    formats: ("csv" | "xlsx" | "pdf" | "png")[];
 };
 /** Matrix delivery requires an effective capture, never resident cells. */
-export declare function resolveMatrixExportEngine(card: TCard | null | undefined, hasContext: boolean): "unavailable" | "window" | "ordinary";
+export declare function resolveMatrixExportEngine(card: TCard | null | undefined, hasContext: boolean): "window" | "unavailable" | "ordinary";

package/dist/types/lib/matrix-table/matrix-editor.d.ts

@@ -0,0 +1,52 @@
+import { ContainerId, Field } from '../types/explorer-types.js';
+import { TCard } from '../types/common-types.js';
+import { FieldPlacement, FieldPlacementContext, FieldPlacementOutcome } from '../utils/field-placement.js';
+import { MatrixViewState, MatrixConfig, MatrixSpec } from '../../shared/analytics-protocol/index.js';
+import { MatrixAuthoringChange, MatrixAuthoringNotice } from '../../shared/dashboard-authoring/matrix-authoring.js';
+import { MatrixCardCatalog } from './matrix-card-adapter.js';
+/** Source-panel fields already carry catalog identity; do not infer it from names or SQL. */
+export declare function matrixEditorCatalogFromFields(card: Pick<TCard, 'dataSource'> & {
+    config?: {
+        matrix?: {
+            spec: Pick<MatrixSpec, 'source'>;
+        };
+    };
+}, fields: readonly Field[]): MatrixCardCatalog;
+export type MatrixEditorChange = {
+    card: TCard;
+    notices: readonly MatrixAuthoringNotice[];
+};
+export declare function changeMatrixEditor(card: TCard, config: MatrixConfig, change: MatrixAuthoringChange, catalog: MatrixCardCatalog): MatrixEditorChange;
+/**
+ * Copy the live session into the authored config: expansion on both axes
+ * becomes defaultView and effective sorts become the authored sorts. This is
+ * the one explicit path from exploration to persisted state.
+ */
+export declare function persistMatrixEditorView(card: TCard, config: MatrixConfig, view: MatrixViewState, catalog: MatrixCardCatalog): MatrixEditorChange;
+/** All editor surfaces replace the canonical config and its bindings atomically. */
+export declare function applyMatrixEditorResult(card: TCard, result: {
+    config: MatrixConfig;
+    bindings: readonly NonNullable<TCard['controlBindings']>[number][];
+    notices: readonly MatrixAuthoringNotice[];
+}): MatrixEditorChange;
+/**
+ * Field placement for Matrix cards: the field-list entity gate, then the one
+ * spec transaction. Side-effect-free; the new instance id is context input.
+ * Called through `evaluateFieldPlacement` by both the drop and its preview.
+ */
+export declare function evaluateMatrixPlacement(card: TCard, placement: FieldPlacement, context: FieldPlacementContext): FieldPlacementOutcome;
+/**
+ * One atomic mutation for source drops, cross-shelf moves and reordering.
+ * A field-list drop creates an instance and needs `newInstanceId`; the
+ * committing adapter mints it, so this function reads no random source.
+ */
+export declare function dropMatrixEditorField(card: TCard, catalog: MatrixCardCatalog, input: {
+    field: Field;
+    from: ContainerId;
+    to: ContainerId;
+    beforeId?: string;
+    newInstanceId?: string;
+}): MatrixEditorChange;
+export declare function removeMatrixEditorField(card: TCard, zone: ContainerId, id: string, catalog: MatrixCardCatalog): MatrixEditorChange;
+/** Scope storage stays with calculated-field transitions; this owns selected Matrix copies. */
+export declare function reconcileMatrixCalculatedField(card: TCard, fields: readonly Field[], previous: Field | undefined, updated?: Field): MatrixEditorChange;