react-semaphor 0.1.526 → 0.1.527

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

@@ -1,4 +1,5 @@
 import { MatrixConfig, MatrixViewState } from '../../shared/analytics-protocol/index.js';
+import { CsvEncoding } from '../../shared/format-utils/exporters/csv-utils.js';
 import { MatrixExportContent } from '../../shared/dashboard-authoring/matrix-delivery.js';
 import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
 import { CompiledCardQueryContext } from '../query-context/build-card-query-context.js';
@@ -34,6 +35,8 @@ export declare function buildMatrixDeliveryPayload(input: {
     content: MatrixExportContent;
     format: 'csv' | 'pdf';
     delimiter: ',' | ';' | '\t';
+    /** CSV only; absent lets the app resolve the dashboard's setting. */
+    csvEncoding?: CsvEncoding;
     includeHeaders: boolean;
 }): {
     controlValues: Record<string, unknown>;
@@ -64,7 +67,7 @@ export declare function buildMatrixDeliveryPayload(input: {
         levelId: string;
         axis: "columns" | "rows";
         direction: "asc" | "desc";
-        nulls: "first" | "last";
+        nulls: "last" | "first";
     }[] | undefined;
     runtimeFilters?: import('../types/explorer-types.js').FilterGroup | undefined;
 } & {
@@ -381,7 +384,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                     levelId: string;
                     axis: "columns" | "rows";
                     direction: "asc" | "desc";
-                    nulls: "first" | "last";
+                    nulls: "last" | "first";
                 }[];
                 rankings: readonly import('../../shared/analytics-protocol/index.js').MatrixRanking[];
                 filters?: import('../types/explorer-types.js').FilterGroup | undefined;
@@ -733,7 +736,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                     levelId: string;
                     axis: "columns" | "rows";
                     direction: "asc" | "desc";
-                    nulls: "first" | "last";
+                    nulls: "last" | "first";
                 }[];
                 rankings: readonly import('../../shared/analytics-protocol/index.js').MatrixRanking[];
                 filters?: import('../types/explorer-types.js').FilterGroup | undefined;
@@ -747,6 +750,7 @@ export declare function buildMatrixDeliveryPayload(input: {
         includeHeaders: boolean;
         timezone: string;
         presentationExecutionSnapshot: import('../../shared/format-utils/index.js').PresentationExecutionSnapshot;
+        csvEncoding?: "utf-8-bom" | "utf-8" | undefined;
         acquisition?: "continuation" | undefined;
     };
 };

package/dist/types/lib/matrix-table/matrix-execution-context.d.ts

@@ -2,6 +2,7 @@ import { CompiledCardQueryContext } from '../query-context/build-card-query-cont
 import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
 import { MatrixWindowExecutor } from './matrix-runtime-types.js';
 import { MatrixOperationQueue } from './matrix-operation-queue.js';
+import { MatrixDatasetHistory } from './matrix-dataset-history.js';
 export type MatrixExecutionEnvironment = {
     ready: boolean;
     /** Existing auth/project scope identity, never a token in the query key. */
@@ -15,4 +16,5 @@ export type MatrixExecutionEnvironment = {
 };
 export declare const MatrixExecutionContext: import('react').Context<(MatrixExecutionEnvironment & {
     queue: MatrixOperationQueue;
+    history: MatrixDatasetHistory;
 }) | null>;

package/dist/types/lib/matrix-table/matrix-query-transport.d.ts

@@ -1,3 +1,6 @@
 import { MatrixExecutionEnvironment } from './matrix-execution-context.js';
-/** The dashboard endpoint owns auth and grounding; no data/SQL reconstruction here. */
+/**
+ * The dashboard endpoint owns auth and grounding; no data/SQL reconstruction
+ * here. Successful windows arrive indexed (efficiency plan E-D8).
+ */
 export declare function createMatrixQueryTransport(endpoint: string, token: string): MatrixExecutionEnvironment['execute'];

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

@@ -1,4 +1,4 @@
-import { MatrixAxis, MatrixAxisPage, MatrixCoordinate, MatrixFailure, MatrixPageRequest, MatrixPath, MatrixPresentation, MatrixSpec, MatrixViewState, MatrixWindow, MatrixWindowOutcome, MatrixWindowRequest, SemaphorScalarValue } from '../../shared/analytics-protocol/index.js';
+import { MatrixAxis, MatrixAxisPage, MatrixCellBlock, MatrixCoordinate, MatrixFailure, MatrixPageRequest, MatrixPath, MatrixPresentation, MatrixSpec, MatrixViewState, MatrixWindow, MatrixIndexedWindowOutcome, MatrixWindowRequest, OperationTemporalState, SemaphorScalarValue } from '../../shared/analytics-protocol/index.js';
 export type MatrixRuntimeError = {
     failure: MatrixFailure;
     retryKey: string | null;
@@ -53,15 +53,110 @@ export type MatrixAxisItem = {
         error: MatrixRuntimeError;
     };
 };
+/**
+ * Slots are per runtime; a copied dataset duplicates them. The loaded data a
+ * slot points to (request, page, coverage, values) is replaced whole, never
+ * modified, so copies may share it (efficiency plan E-INV-6).
+ */
 export type MatrixPageSlot = {
     key: string;
-    request: MatrixPageRequest;
+    request: Readonly<MatrixPageRequest>;
     ordinal: number;
-    data?: MatrixAxisPage;
+    data?: Readonly<MatrixAxisPage>;
+    status: 'idle' | 'loading' | 'ready' | 'failed';
+    error?: MatrixRuntimeError;
+    touched: number;
+    bytes: number;
+};
+/** A loaded cell tile: one row owner (page or singleton path) by one column owner. */
+export type MatrixTileSlot = {
+    key: string;
+    rowOwner: string;
+    columnOwner: string;
+    rows: readonly MatrixPath[];
+    columns: readonly MatrixPath[];
     status: 'idle' | 'loading' | 'ready' | 'failed';
     error?: MatrixRuntimeError;
+    coverage?: Readonly<MatrixCellBlock['coverage']>;
+    /**
+     * Present values by position in `coverage`, keyed
+     * `(row * columns + column) * measures + measure`; absent means no data.
+     */
+    values: ReadonlyMap<number, Readonly<MatrixCellBlock['cells'][number]['value']>>;
+    /** Coverage positions by row key, column key and measure id, for `readCell`. */
+    positions?: MatrixTilePositions;
     touched: number;
     bytes: number;
+    cells: number;
+};
+export type MatrixTilePositions = {
+    rows: ReadonlyMap<string, number>;
+    columns: ReadonlyMap<string, number>;
+    measures: ReadonlyMap<string, number>;
+};
+/** Resident usage in every retention dimension. Bytes are serialized payload, never heap. */
+export type MatrixUsage = {
+    pages: number;
+    blocks: number;
+    cells: number;
+    bytes: number;
+};
+/**
+ * One card's loaded data for one query identity and sort order. It holds only
+ * ready pages and tiles, never failed or loading ones. It is in one runtime or
+ * in the dataset History, never both; a seeded runtime holds its own copy.
+ */
+export type MatrixDataset = {
+    /** The effective sort order it was acquired under. */
+    sorts: string;
+    /** The card generation it belongs to; a refresh makes it unusable. */
+    generation: number;
+    /** When its oldest piece was fetched; saving or restoring never resets it. */
+    fetchedAt: number;
+    queryIdentity: string;
+    descriptors: MatrixWindow['descriptors'];
+    pages: readonly MatrixPageSlot[];
+    tiles: readonly MatrixTileSlot[];
+    usage: MatrixUsage;
+    /**
+     * The operation state its first response reported (analytics kernel K14):
+     * every later page and expansion of this dataset runs on it, so a restored
+     * or seeded dataset continues on the same instant.
+     */
+    temporalState?: OperationTemporalState;
+};
+/** What a mounted runtime exposes to History. */
+export type MatrixLiveView = {
+    usage: () => MatrixUsage;
+    /** A copy of its ready pieces, or nothing while it has none or is in an error state. */
+    snapshot: () => MatrixDataset | undefined;
+};
+/** How one runtime keeps and restores its card's datasets for one query identity. */
+export type MatrixDatasetRetention = {
+    now(): number;
+    /** The card generation a dataset starting now belongs to. */
+    generation(): number;
+    /**
+     * A restorable dataset for these sorts: a saved one, else a copy of another
+     * live view's. A pure read, safe during render.
+     */
+    peek(sorts: string): MatrixDataset | undefined;
+    /**
+     * Takes ownership of a peeked dataset (a saved one leaves History; a live
+     * copy leaves its source untouched); false when it is gone, stale or expired.
+     */
+    adopt(dataset: MatrixDataset): boolean;
+    /** Moves a stopped dataset into History; a stale generation or scope is rejected. */
+    save(dataset: MatrixDataset): void;
+    /** Clears the card's History and returns the card's new generation. */
+    invalidate(): number;
+    /**
+     * Registers this runtime as a live view: its usage counts against the card's
+     * History allowance, and its snapshot may seed another view of the card.
+     */
+    register(view: MatrixLiveView): () => void;
+    /** Live usage grew; History re-fits the card's allowance. */
+    usageChanged(): void;
 };
 export type MatrixRuntimeSnapshot = {
     rows: readonly MatrixAxisItem[];
@@ -107,7 +202,13 @@ export type MatrixWindowExecutor = (input: {
     spec: MatrixSpec;
     window: MatrixWindowRequest;
     signal: AbortSignal;
-}) => Promise<MatrixWindowOutcome>;
+    /** The acquisition's state once its first response reported one. */
+    temporalState?: OperationTemporalState;
+}) => Promise<MatrixWindowExecution>;
+/** A window outcome and the operation state the server ran it on. */
+export type MatrixWindowExecution = MatrixIndexedWindowOutcome & {
+    temporalState?: OperationTemporalState;
+};
 export type MatrixRuntimeInput = {
     spec: MatrixSpec;
     presentation: MatrixPresentation;

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

@@ -1,10 +1,11 @@
 import { QueryClient } from '@tanstack/react-query';
 import { MatrixAxis, MatrixCoordinate, MatrixPath, MatrixSort, MatrixViewState } from '../../shared/analytics-protocol/index.js';
-import { MatrixCellAddress, MatrixCellState, MatrixRuntimeInput, MatrixRuntimeSnapshot, MatrixViewport, MatrixVisibleCoverage, MatrixWindowExecutor } from './matrix-runtime-types.js';
+import { MatrixCellAddress, MatrixCellState, MatrixDatasetRetention, MatrixRuntimeInput, MatrixRuntimeSnapshot, MatrixViewport, MatrixVisibleCoverage, MatrixWindowExecutor } from './matrix-runtime-types.js';
 /** Owns acquisition, errors, generation fencing and retention for exactly one card. */
 export declare class MatrixRuntimeController {
     private query;
     private execute;
+    private retention;
     private readonly prefix;
     private listeners;
     private pages;
@@ -19,6 +20,12 @@ export declare class MatrixRuntimeController {
     private mounted;
     private scheduled;
     private queryIdentity?;
+    /**
+     * The acquisition's operation state (analytics kernel K14): until its first
+     * response reports one, the generation runs one request at a time; after,
+     * every page and expansion sends it, so they all run on one instant.
+     */
+    private temporalState?;
     private error?;
     private notice?;
     private blockingFailures;
@@ -28,12 +35,24 @@ export declare class MatrixRuntimeController {
     private view;
     private spec;
     private snapshot;
-    constructor(input: MatrixRuntimeInput, query: QueryClient, execute: MatrixWindowExecutor, session?: MatrixViewState);
+    /** Card generation of the current dataset; set when the dataset starts. */
+    private datasetGeneration;
+    /** Fetch time of the current dataset's oldest piece. */
+    private datasetFetchedAt?;
+    /** Installed at construction, adopted from History when the runtime starts. */
+    private restored?;
+    private unregister?;
+    constructor(input: MatrixRuntimeInput, query: QueryClient, execute: MatrixWindowExecutor, session?: MatrixViewState, retention?: MatrixDatasetRetention);
     subscribe: (listener: () => void) => () => boolean;
     getSnapshot: () => MatrixRuntimeSnapshot;
     start: () => void;
     stop: () => void;
     private clear;
+    /**
+     * "This card, as of now": every refresh, retry of a request-wide failure and
+     * server-forced reset invalidates the card's History (plan MF-D5), and the new
+     * dataset starts under the bumped generation.
+     */
     refresh: () => void;
     dismissNotice: () => void;
     /** Presentation updates never change the acquisition generation. */
@@ -66,6 +85,12 @@ export declare class MatrixRuntimeController {
     private loadTile;
     private enqueue;
     private pump;
+    /**
+     * Re-derived on every pump, never a flag cleared on success: a bootstrap that
+     * fails, is cancelled or is superseded ends its active work, and the next
+     * queued request becomes the bootstrap.
+     */
+    private awaitingTemporalState;
     private run;
     private current;
     private runtimeError;
@@ -74,6 +99,22 @@ export declare class MatrixRuntimeController {
     private removeTile;
     private removeResource;
     private trim;
+    /** One measure of resident usage for the runtime budget and History. */
+    private usage;
+    /** Order-insensitive, like the sort comparison that decides a reset. */
+    private sortsKey;
+    /** Page ownership for acquired and restored pages alike. */
+    private ownPage;
+    /**
+     * The ready pieces of the current dataset. Failed and loading pieces never
+     * leave (plan INV-7), and a view in a request-wide failure saves nothing.
+     * Copies are taken, so History entries are never mutated afterwards.
+     */
+    private exportDataset;
+    /** Installs copies, so a dataset peeked by two runtimes is never shared mutably. */
+    private install;
+    /** Adopts a fresh saved dataset for the current sorts, if History has one. */
+    private restore;
     private deferPlan;
     private publish;
 }

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

@@ -9,6 +9,12 @@ type MatrixInput = MatrixRuntimeInput & {
     cardId?: string;
     /** Authored controls input; runtime spec is the resolved display definition. */
     authoredSpec?: MatrixSpec;
+    /**
+     * The shared card query identity (`createCompiledCardQueryIdentities`) of the
+     * same `queryContext` and calendar this card sends. It is the only source of
+     * query-context identity here; never hash query-context fields locally.
+     */
+    queryInputIdentity: string;
     queryContext: CompiledCardQueryContext;
     reportContext: ReportRuntimeContext;
     /** Milliseconds from the card refresh setting; absent while editing. */

package/dist/types/lib/query-context/build-card-query-context.d.ts

@@ -1,6 +1,7 @@
 import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
 import { ControlBinding, ControlDefinition, ResolvedDashboardDateComparisonInput, ResolvedDashboardInputContext, TCard, TDashboard } from '../types/common-types.js';
-import { GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
+import { GlobalDateComparisonContext, GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
+import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
 import { CardConfig } from '../types/explorer-types.js';
 import { resolveRuntimeCardFilters } from './resolve-runtime-card-filters.js';
 import { CardViewState } from '../dashboard-view-state/index.js';
@@ -50,6 +51,9 @@ export type CardQueryContext = {
 export type CompiledCardQueryContext = Omit<CardQueryContext, 'filterCompilationInput'> & {
     cardFilterValues: TFilterValue[];
     queryFilterDefinitions: TFilter[];
+    /** Compiled outputs the shared card query identity reads; see `createCompiledCardQueryIdentities`. */
+    resolvedPrimaryDateField: ResolvedPrimaryDateField | null;
+    globalDateComparison: GlobalDateComparisonContext | undefined;
     globalDateComparisonSelection?: GlobalDateComparisonSelection;
     dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
 };

package/dist/types/lib/query-context/build-dashboard-card-query-contract.d.ts

@@ -51,7 +51,6 @@ export type DashboardCardQueryExecutionOptions = {
     resolvedPrimaryDateField?: ResolvedPrimaryDateField;
     calendarContext: CalendarContext;
     allowGlobalDateMinutePrecision?: boolean;
-    globalDateComparisonReferenceTime?: string;
     resolvePaginationConfig?: (queryInputIdentity: string) => PaginationConfig | undefined;
 };
 /** One final compilation for interactive requests and immutable input captures. */

package/dist/types/lib/query-context/build-global-date-comparison-context.d.ts

@@ -1,9 +1,8 @@
 import { TCard } from '../types/common-types.js';
 import { DashboardDateComparisonOwner, GlobalDateComparisonContext, GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
 import { DashboardDateComparisonResolution } from '../dashboard-inputs/dashboard-date-comparison-plan.js';
-export declare function buildGlobalDateComparisonContext(card: Pick<TCard, 'preferences'>, selection: GlobalDateComparisonSelection | undefined, referenceTime?: string, owner?: DashboardDateComparisonOwner): GlobalDateComparisonContext | undefined;
+export declare function buildGlobalDateComparisonContext(card: Pick<TCard, 'preferences'>, selection: GlobalDateComparisonSelection | undefined, owner?: DashboardDateComparisonOwner): GlobalDateComparisonContext | undefined;
 export declare function buildDashboardDateComparisonContext(params: {
     card: TCard;
     resolution: DashboardDateComparisonResolution;
-    referenceTime?: string;
 }): GlobalDateComparisonContext | undefined;

package/dist/types/lib/query-context/compile-dashboard-card-filters.d.ts

@@ -35,7 +35,6 @@ export type CompileDashboardCardFiltersParams = {
     semanticExecutionPayload?: SemanticExecutionPayload;
     timezone?: string;
     allowMinutePrecision?: boolean;
-    comparisonReferenceTime?: string;
 };
 export type CompiledDashboardCardFilters = {
     cardFilterValues: TFilterValue[];
@@ -68,5 +67,5 @@ export declare function composeCardFilterValues(card: TCard, input: DashboardCar
  * The single final per-card filter compiler. Every card execution consumer
  * calls this once and treats its result as immutable query state.
  */
-export declare function compileDashboardCardFilters({ card, cardConfig, input, resolvedPrimaryDateField, resolvedFields, semanticExecutionPayload, timezone, allowMinutePrecision, comparisonReferenceTime, }: CompileDashboardCardFiltersParams): DashboardCardFilterCompilationResult;
+export declare function compileDashboardCardFilters({ card, cardConfig, input, resolvedPrimaryDateField, resolvedFields, semanticExecutionPayload, timezone, allowMinutePrecision, }: CompileDashboardCardFiltersParams): DashboardCardFilterCompilationResult;
 export {};

package/dist/types/lib/query-context/dashboard-card-query-key.d.ts

@@ -3,6 +3,7 @@ import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
 import { CardConfig, PaginationConfig } from '../types/explorer-types.js';
 import { GlobalDateComparisonContext } from '../../shared/analytics-protocol/index.js';
 import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { CompiledCardQueryContext } from './build-card-query-context.js';
 export declare const isPaginatedCardType: (card: TCard) => boolean;
 export type CreateDashboardCardQueryKeyOptions = {
     finalFiltersKey: string;
@@ -36,4 +37,13 @@ export declare function createDashboardCardQueryIdentities(card: TCard, options:
     queryInputIdentity: string;
     paginationConfig: PaginationConfig | undefined;
 };
+/**
+ * The one identity for a compiled card context. Regular cards and the Matrix
+ * both use it, so a card's identity always covers what its request sends.
+ */
+export declare function createCompiledCardQueryIdentities(card: TCard, context: CompiledCardQueryContext, calendarContext: CalendarContext, identityOptions?: Parameters<typeof createDashboardCardQueryIdentities>[2]): {
+    queryKey: string[];
+    queryInputIdentity: string;
+    paginationConfig: PaginationConfig | undefined;
+};
 export declare function createDashboardCardQueryKey(card: TCard, options: CreateDashboardCardQueryKeyOptions): string[];

package/dist/types/lib/query-context/query-auth-scope.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The auth scope every card puts in its query identity: a stable hash of the
+ * access token, never the token itself. A new token is a new scope.
+ */
+export declare function hashTokenForQueryKey(accessToken?: string): string;

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

@@ -101,8 +101,12 @@ export type DashboardStore = {
     cardViewState: CardViewStateMap;
     /** Session-only server pagination, attached to the query identity that owns each page. */
     dashboardCardPagination: Record<string, DashboardCardPaginationState>;
-    /** Fixed execution clock from a strict dashboard input replay snapshot. */
-    dashboardInputReferenceTime?: string;
+    /**
+     * When the replayed input snapshot was generated, for a document's
+     * "Generated at" text only. Queries never read it: a print render's
+     * instant comes from its pinned calendar (analytics kernel K15).
+     */
+    dashboardInputGeneratedAt?: string;
     /**
      * Set when a PDF render's sheet has applicable inputs that were never
      * captured. The sheet must not print; DashboardTabs renders the reason.
@@ -205,14 +209,14 @@ type Actions = {
     setDashboard: (dashboard: TDashboard, options?: {
         semanticExecutionPayload?: SemanticExecutionPayload;
         dashboardInputValues?: DashboardInputValues;
-        dashboardInputReferenceTime?: string;
+        dashboardInputGeneratedAt?: string;
         reportContext?: ReportRuntimeContext;
     }) => void;
     setDashboardWithFilterValues: (dashboard: TDashboard, filterValues: TFilterValue[], runtimeOverrides?: Record<string, unknown>, options?: {
         selectedSheetId?: string | null;
         semanticExecutionPayload?: SemanticExecutionPayload;
         dashboardInputValues?: DashboardInputValues;
-        dashboardInputReferenceTime?: string;
+        dashboardInputGeneratedAt?: string;
         /** Drill paths replayed from an execution snapshot. */
         cardViewState?: CardViewStateMap;
         transientContexts?: TransientInputContext[];
@@ -226,6 +230,7 @@ type Actions = {
     setDashboardTheme: (theme: 'light' | 'dark' | 'system') => void;
     setDashboardTitle: (title: string) => void;
     setDashboardDescription: (description: string) => void;
+    setDashboardExportDefaults: (exportDefaults: TDashboard['exportDefaults']) => void;
     setSheets: (sheets: TSheet[]) => void;
     addSheet: (sheet: TSheet) => void;
     duplicateSheet: (sheetId: string) => string | null;

package/dist/types/lib/temporal-filter/temporal-filter-utils.d.ts

@@ -31,11 +31,18 @@ export declare function formatTimeInTimezone(date: Date, timezone: string): stri
 export declare function composeDateTimeInTimezone(date: Date, time: string, timezone: string, options?: {
     boundary?: 'start' | 'end';
 }): Date | null;
-export declare function normalizeDateFilterRange(date: DateRange, options?: {
+/**
+ * The range a date filter stores. At day precision, a single day (a start
+ * with no end, or an end equal to the start) becomes that whole calendar day
+ * in the report timezone, ending its last millisecond: 23 or 25 hours on a
+ * daylight-saving day, and never the next day's midnight, which an inclusive
+ * range would count (on a date column, as the whole next day).
+ */
+export declare function normalizeDateFilterRange(date: DateRange, options: {
     temporalPrecision?: TemporalPrecision;
+    timezone: string;
 }): {
     from?: Date;
     to?: Date;
     values: [Date | string, Date | string] | [Date | string];
 };
-export declare function resolveSubDayRelativeDateRange(meta: RelativeDateFilter, anchor?: Date): [Date, Date] | null;

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

@@ -15,6 +15,7 @@ import { DashboardAIContext } from './assistant-types.js';
 import { CardInteractionConfig, InteractionTargetOverride } from './interaction-types.js';
 import { SemanticExecutionPayload } from './semantic-runtime-types.js';
 import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
+import { CsvEncoding } from '../../shared/format-utils/exporters/csv-utils.js';
 import { PresentationExecutionSnapshot, TemporalInputPresentation } from '../../shared/format-utils/index.js';
 import { JSX } from 'react';
 export type { DashboardFilterApplication, DashboardFilterBoundCardApplication, DashboardFilterCardApplication, DashboardFilterExcludedCardApplication, DashboardFilterTarget, DashboardFilterTargetField, DashboardFilterTargetSource, DashboardFilterOptionSource, } from '../../shared/dashboard-authoring/dashboard-filter-mapping-types.js';
@@ -1573,6 +1574,10 @@ export type TDashboard = {
         /** Dashboard creation sets 'on'. Absent resolves to 'off', so existing dashboards do not change. */
         clickToFilter: 'on' | 'off';
     };
+    exportDefaults?: {
+        /** Absent resolves to DEFAULT_CSV_ENCODING, so existing dashboards do not change. */
+        csvEncoding?: CsvEncoding;
+    };
     aiContext?: DashboardAIContext;
     summary?: {
         enabled?: boolean;

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

@@ -2,6 +2,7 @@ import { TimeDrillStep } from './interaction-types.js';
 import { SemaphorDerivedFieldDefinition, MatrixConfig, SemaphorSourceRef, SemaphorResultColumn, SemaphorPivotValue, SemaphorTimeGrain, SemanticGroupedTemporalInput, TemporalBucketMetadata, TemporalBucketFormat, MetricComparisonConfig, MetricComparisonPolarity } from '../../shared/analytics-protocol/index.js';
 import { CanonicalPivotResultContract, CanonicalPivotResultState, FlatTableExportTotalsBehavior, FlatTableExportTotalsRequest, QueryColumnKeyMap as SharedQueryColumnKeyMap } from '../../shared/format-utils/index.js';
 import { TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
+import { RelativeDateFilter } from '../../shared/analytics-protocol/relative-date-filter.js';
 /**
  * Special entity name marker for calculated fields.
  *
@@ -464,6 +465,19 @@ export interface FilterCondition {
     label?: string;
     /** Governed meaning for a canonical grouped-temporal scalar. */
     temporalBucket?: TemporalBucketMetadata;
+    /**
+     * Relative date window ("This month"). When present it is authoritative:
+     * the server resolves it on every run and `value` only keeps the range seen
+     * when it was saved. Valid only with `between` and `not between`.
+     */
+    relativeMeta?: RelativeDateFilter;
+    /**
+     * "Equals the latest value of this field" (analytics kernel K13). With `=`
+     * on a date or timestamp field only. The server resolves it on every run
+     * through the field's data anchor; `value` only keeps the value seen when
+     * it was saved.
+     */
+    latestValue?: true;
 }
 export interface FilterGroup {
     id: string;

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

@@ -117,7 +117,6 @@ export type UIConfig = {
         features: {
             dashboardAssistant: boolean;
             dashboardAiAuthoring: boolean;
-            dataAppBuilder: boolean;
             analyticalBriefings: boolean;
             aiWritingHelpers: boolean;
         };

package/dist/types/lib/utils/card-definition.d.ts

@@ -326,7 +326,7 @@ export declare function getCardDefinition(card: DefinitionCard, catalog?: Matrix
                 levelId: string;
                 axis: "columns" | "rows";
                 direction: "asc" | "desc";
-                nulls: "first" | "last";
+                nulls: "last" | "first";
             }[];
             rankings: readonly import('../../shared/analytics-protocol/matrix-definition-contract.js').MatrixRanking[];
             filters?: import('../types/explorer-types.js').FilterGroup | undefined;

package/dist/types/lib/utils/date-timezone-utils.d.ts

@@ -1,4 +1,4 @@
-import { CalendarContext, WeekStart } from '../types/token-types.js';
+import { CalendarContext } from '../types/token-types.js';
 /**
  * Gets the start of day (00:00:00.000) for a date in the specified timezone.
  * This ensures that when the Date is serialized to UTC, it represents the correct day boundary.
@@ -18,7 +18,9 @@ import { CalendarContext, WeekStart } from '../types/token-types.js';
  */
 export declare const startOfDayInTimezone: (date: Date, timezone: string) => Date;
 /**
- * Gets the end of day (23:59:59.999) for a date in the specified timezone.
+ * Gets the last millisecond of the day for a date in the specified timezone:
+ * 23:59:59.999, or the instant before the next day starts on a day that
+ * ends inside a daylight-saving change.
  * This ensures that when the Date is serialized to UTC, it represents the correct day boundary.
  *
  * @param date - The date to get end of day for
@@ -49,42 +51,6 @@ export declare const endOfDayInTimezone: (date: Date, timezone: string) => Date;
  * `getEffectiveTimezone` does.
  */
 export declare const parseFilterDateValue: (value: unknown, timezone: string | null | undefined, bound?: "start" | "end") => Date | undefined;
-/**
- * Gets the start of week (midnight) for a date in the specified timezone.
- *
- * @param date - The date to get start of week for
- * @param timezone - The timezone to use (e.g., 'America/Los_Angeles')
- * @param weekStartsOn - Day the week starts on (0=Sunday, 1=Monday). Can also pass CalendarContext.
- * @returns A Date object representing midnight on the first day of the week
- *
- * @example
- * // With weekStartsOn number
- * startOfWeekInTimezone(new Date(), 'America/Chicago', 0) // Sunday start
- *
- * // With CalendarContext
- * startOfWeekInTimezone(new Date(), 'America/Chicago', { tz: 'America/Chicago', weekStart: 0, anchor: 'now' })
- */
-export declare const startOfWeekInTimezone: (date: Date, timezone: string, weekStartsOn?: WeekStart | CalendarContext) => Date;
-/**
- * Gets the end of week (23:59:59.999) for a date in the specified timezone.
- *
- * @param date - The date to get end of week for
- * @param timezone - The timezone to use (e.g., 'America/Los_Angeles')
- * @param weekStartsOn - Day the week starts on (0=Sunday, 1=Monday). Can also pass CalendarContext.
- * @returns A Date object representing the last moment of the last day of the week
- */
-export declare const endOfWeekInTimezone: (date: Date, timezone: string, weekStartsOn?: WeekStart | CalendarContext) => Date;
-export declare const startOfMonthInTimezone: (date: Date, timezone: string) => Date;
-export declare const endOfMonthInTimezone: (date: Date, timezone: string) => Date;
-export declare const startOfQuarterInTimezone: (date: Date, timezone: string) => Date;
-export declare const endOfQuarterInTimezone: (date: Date, timezone: string) => Date;
-export declare const startOfYearInTimezone: (date: Date, timezone: string) => Date;
-export declare const endOfYearInTimezone: (date: Date, timezone: string) => Date;
-export declare const shiftDateByDaysInTimezone: (date: Date, timezone: string, days: number) => Date;
-export declare const shiftDateByWeeksInTimezone: (date: Date, timezone: string, weeks: number) => Date;
-export declare const shiftDateByMonthsInTimezone: (date: Date, timezone: string, months: number) => Date;
-export declare const shiftDateByQuartersInTimezone: (date: Date, timezone: string, quarters: number) => Date;
-export declare const shiftDateByYearsInTimezone: (date: Date, timezone: string, years: number) => Date;
 /**
  * Resolves the effective timezone.
  *
@@ -111,11 +77,3 @@ export declare const shiftDateByYearsInTimezone: (date: Date, timezone: string,
  * getEffectiveTimezone() // Returns browser's timezone (e.g., 'America/Los_Angeles')
  */
 export declare const getEffectiveTimezone: (timezoneOrContext?: string | CalendarContext | null) => string;
-/**
- * Resolves the effective weekStart from CalendarContext.
- *
- * @param calendarContext - Optional CalendarContext
- * @returns The week start day (0=Sunday, 1=Monday)
- * @default 1 (Monday) for backward compatibility with ISO standard
- */
-export declare const getEffectiveWeekStart: (calendarContext?: CalendarContext | null) => WeekStart;

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

@@ -1,12 +1,18 @@
 import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
 import { TInlineFilter } from '../types/common-types.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+/**
+ * The report calendar defaults resolve in: its timezone, or the calendar
+ * with its week start too, so a week default matches the server's week.
+ */
+export type DefaultsCalendar = string | Pick<CalendarContext, 'tz' | 'weekStart'>;
 type DefaultBackedFilter = Pick<TFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'> & Partial<Pick<TInlineFilter, 'id' | 'column' | 'operation' | 'dataType' | 'nativeDataType' | 'dateSelectionMode' | 'defaultValues' | 'defaultDateFilter' | 'fieldMeta' | 'semanticContext'>>;
 /**
  * Converts a filter's default configuration into an active runtime filter value.
  * Returns undefined when no defaults are configured.
  */
-export declare function buildFilterValueFromDefaults(filter: DefaultBackedFilter, timezone?: string): TFilterValue | undefined;
-export declare function buildFilterValuesFromDefaults(filters: DefaultBackedFilter[] | undefined, timezone?: string): TFilterValue[];
+export declare function buildFilterValueFromDefaults(filter: DefaultBackedFilter, calendar?: DefaultsCalendar | null): TFilterValue | undefined;
+export declare function buildFilterValuesFromDefaults(filters: DefaultBackedFilter[] | undefined, calendar?: DefaultsCalendar): TFilterValue[];
 export declare function isCompatibleFilterValue(filter: Pick<TFilter, 'id' | 'operation' | 'dataType'>, filterValue: TFilterValue): boolean;
 export declare function filterCompatibleFilterValues(filters: TFilter[] | undefined, filterValues: TFilterValue[] | undefined): TFilterValue[];
 export declare function mergeFilterValueLayers(baseValues: TFilterValue[], overrideValues: TFilterValue[]): TFilterValue[];

package/dist/types/lib/utils/inline-filter-utils.d.ts

@@ -1,5 +1,6 @@
 import { TDashboard } from '../types/common-types.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DefaultsCalendar } from './filter-default-value-utils.js';
 /**
  * Hydrate inline filter defaults for all cards in the dashboard.
  * Returns a map of cardId → TFilterValue[] for runtime-only storage.
@@ -9,7 +10,7 @@ import { TFilterValue } from '../../components/surfboard/filter/types.js';
  * function only owns traversal and card-scoped runtime storage.
  *
  * @param dashboard - The dashboard to extract inline filter defaults from
- * @param timezone - Optional timezone for date calculations (defaults to browser timezone)
+ * @param calendar - The report calendar (or its timezone) for date defaults (defaults to the browser timezone)
  * @returns Map of cardId to array of filter values
  */
-export declare function computeInlineFilterDefaults(dashboard: TDashboard, timezone?: string): Record<string, TFilterValue[]>;
+export declare function computeInlineFilterDefaults(dashboard: TDashboard, calendar?: DefaultsCalendar): Record<string, TFilterValue[]>;