react-semaphor 0.1.515 → 0.1.516

package/dist/types/lib/document/document-section-render-state.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Print readiness for a Document section. The scheduler's document mode
+ * waits while any `data-document-render-loading` marker is present and fails
+ * the PDF on `data-document-render-error` or a delivery error code
+ * (`semaphor-report-scheduler/pdf-generation/lib/modes/document.js`).
+ *
+ * - `ready` and `empty` print as they are.
+ * - `loading` holds the PDF until the section settles.
+ * - `blocked` (required inputs missing, or the section is not configured) and
+ *   `error` fail the PDF instead of printing an incomplete report.
+ */
+export type DocumentSectionRenderState = 'ready' | 'empty' | 'loading' | 'blocked' | 'error';
+/**
+ * One state for a section with several cards: an error or blocked card fails
+ * the section, then any loading card holds it, and it is empty only when every
+ * card is empty.
+ */
+export declare function summarizeDocumentSectionRenderStates(states: readonly DocumentSectionRenderState[]): DocumentSectionRenderState;
+export type DocumentSectionRenderAttributes = {
+    'data-document-render-loading'?: 'true';
+    'data-document-render-error'?: 'true';
+    'data-semaphor-render-error-code'?: string;
+    'data-semaphor-render-error-message'?: string;
+};
+/** The markers for one render state. `error` is the failure, used for delivery error codes. */
+export declare function getDocumentSectionRenderAttributes(state: DocumentSectionRenderState | undefined, error?: unknown): DocumentSectionRenderAttributes;

package/dist/types/lib/document/document-section-utils.d.ts

@@ -1,11 +1,18 @@
 import { LucideIcon } from 'lucide-react';
+import { DocumentSectionKindId } from './document-section-kinds.js';
 import { DocumentInputDefinition, DocumentSection } from '../types/common-types.js';
 export type DocumentSectionType = DocumentSection['type'];
-export type AddableDocumentSectionType = Exclude<DocumentSectionType, 'chart'>;
+/** Section kinds offered when adding a section (Matrix is stored as a table). */
+export type AddableDocumentSectionType = Exclude<DocumentSectionKindId, 'chart' | 'pivot'>;
 export declare const DOCUMENT_SECTION_LABELS: Record<DocumentSectionType, string>;
-export declare const ADDABLE_DOCUMENT_SECTION_TYPES: AddableDocumentSectionType[];
-export declare function documentSectionIcon(type: DocumentSectionType): LucideIcon;
-export declare function createDocumentSection(type: AddableDocumentSectionType): DocumentSection;
+/** The icon of a section kind; pass `getDocumentSectionKind(section).id` for a stored section. */
+export declare function documentSectionIcon(type: DocumentSectionKindId): LucideIcon;
 export declare function getDocumentSectionLabel(section: DocumentSection, inputs: DocumentInputDefinition[]): string;
 export declare function getDocumentSectionTitle(section: DocumentSection, inputs: DocumentInputDefinition[]): string;
 export declare function getDocumentSectionSubtitle(section: DocumentSection): string | null;
+/**
+ * What a data section reads, for its toolbar label: the dataset of a table
+ * section's card, or how many KPIs a KPI section holds. Undefined for other
+ * kinds and for a card with no dataset yet (SQL cards name none).
+ */
+export declare function getDocumentSectionDataLabel(section: DocumentSection): string | undefined;

package/dist/types/lib/document/document-table-dom.d.ts

@@ -10,22 +10,20 @@ export declare function getDocumentTableMeasuredChromeMetrics({ sectionElement,
     chromeHeightPx: number;
     trailingChromePx: number;
 };
-export declare function getDocumentPageElement(element: HTMLElement | null): HTMLElement | null;
-export declare function getDocumentPageFooterElement(pageElement: HTMLElement | null): HTMLElement | null;
-export declare function getIntendedDocumentPageBoxHeightPx(pageElement: HTMLElement): number;
-export declare function getDocumentPageBodyBoundaryPx(pageElement: HTMLElement): number;
 export declare function hasMaterialTableLayoutMeasurementChange(previousMeasurement: {
     rowHeightPx: number;
     averageRowHeightPx?: number;
     rowHeightsPx?: Array<number | undefined>;
     chromeHeightPx: number;
     renderedMinHeightPx?: number;
-    rowsPerPage?: number;
+    columnWidthsPx?: number[];
+    matrixFit?: unknown;
 } | null, nextMeasurement: {
     rowHeightPx: number;
     averageRowHeightPx?: number;
     rowHeightsPx?: Array<number | undefined>;
     chromeHeightPx: number;
     renderedMinHeightPx?: number;
-    rowsPerPage?: number;
+    columnWidthsPx?: number[];
+    matrixFit?: unknown;
 }): boolean;

package/dist/types/lib/document/document-table-pagination-model.d.ts

@@ -55,11 +55,6 @@ export declare function getDocumentTableRowsThatFit({ rowMeasurementState, start
     availableHeightPx: number;
 }): number;
 export declare function getDocumentTableEffectiveRowHeightFromState(rowMeasurementState: DocumentTableRowMeasurementState): number;
-export declare function shouldReportDocumentTableLayoutMeasurement(_options: {
-    tableSlice?: {
-        pageIndex: number;
-    } | undefined;
-}): boolean;
 export declare function canUpdateDocumentTableLayoutChrome({ tableSlice, }: {
     tableSlice?: {
         pageIndex: number;

package/dist/types/lib/document/document-table-print-model.d.ts

@@ -1,9 +1,10 @@
 import { DOCUMENT_TABLE_PRINT_RENDER_CONTRACT } from './document-visual-render-contract.js';
+import { DocumentMatrixFit } from './document-matrix-bands.js';
 import { DocumentTableSection } from '../types/common-types.js';
 export declare const DOCUMENT_TABLE_DEFAULT_ROW_HEIGHT_PX = 40;
 export declare const DOCUMENT_TABLE_MIN_MEASURED_ROW_HEIGHT_PX = 18;
 export declare const DOCUMENT_TABLE_MIN_RENDERED_SURFACE_HEIGHT_PX = 120;
-export type DocumentTablePrintKind = 'table' | 'pivotTable';
+export type DocumentTablePrintKind = 'table' | 'pivotTable' | 'matrix';
 export type DocumentTableLayoutMeasurement = {
     rowHeightPx: number;
     averageRowHeightPx?: number;
@@ -14,7 +15,8 @@ export type DocumentTableLayoutMeasurement = {
     chromeHeightPx: number;
     renderedMinHeightPx?: number;
     canUpdateLayoutChrome?: boolean;
-    rowsPerPage?: number;
+    columnWidthsPx?: number[];
+    matrixFit?: DocumentMatrixFit;
 };
 export type DocumentTablePrintModel = {
     sectionId: string;
@@ -34,7 +36,6 @@ export type DocumentTablePrintModel = {
     effectiveRowHeightPx: number;
     chromeHeightPx?: number;
     renderedMinHeightPx?: number;
-    measuredRowsPerPage?: number;
     renderContract: typeof DOCUMENT_TABLE_PRINT_RENDER_CONTRACT;
 };
 export declare function getDocumentTablePrintModel({ section, totalRowCount, layoutMeasurement, }: {

package/dist/types/lib/document/document-table-style.d.ts

@@ -1,7 +1,9 @@
 import { TableDensity } from '../../components/visual/data-table/types/data-table.js';
 import { DocumentTableSection } from '../types/common-types.js';
 import { getTableTotalsBorderTopWidthValue, getTableTotalsFontWeightValue, ResolvedTablePresentationStyle } from '../table-formatting/table-presentation-style.js';
-export declare const DOCUMENT_TABLE_DENSITY_OPTIONS: readonly ["spacious", "comfortable", "standard", "compact", "dense"];
+/** The densities a Document offers: on paper, only a few row heights differ.
+ * Stored Spacious and Dense values still print as they are. */
+export declare const DOCUMENT_TABLE_DENSITY_OPTIONS: readonly TableDensity[];
 export declare const DOCUMENT_TABLE_HEADER_STYLE_OPTIONS: readonly ["plain", "filled", "accent"];
 export declare const DOCUMENT_TABLE_GRID_LINE_OPTIONS: readonly ["full", "outer", "inner", "horizontal", "vertical", "top", "right", "bottom", "left", "none"];
 export declare const DOCUMENT_TABLE_DEFAULT_STYLE: {
@@ -15,14 +17,23 @@ export declare const DOCUMENT_TABLE_DEFAULT_STYLE: {
     wrapText: false;
 };
 export declare const DOCUMENT_TABLE_TOTALS_FONT_WEIGHT_OPTIONS: readonly ["normal", "medium", "semibold", "bold"];
+/**
+ * A Document table's total prints like a Matrix section's grand total
+ * (Plan 2, P1): no tint, semibold, between a firm top rule and a double
+ * bottom rule (drawn by the surface). What an author sets still wins, except
+ * that the double rule is always the closing one: a double top rule prints
+ * single, so the total never sits between two double rules.
+ */
+/** Top-rule styles a Document offers: its closing rule is already double. */
+export declare const DOCUMENT_TABLE_TOTALS_BORDER_STYLE_OPTIONS: readonly ["solid", "dashed", "dotted"];
 export declare const DOCUMENT_TABLE_DEFAULT_TOTALS_STYLE: {
-    enabled: false;
     backgroundColor: string;
+    fontWeight: "semibold";
+    borderTopColor: string;
+    enabled: false;
     textColor: string;
-    fontWeight: "medium";
     borderTop: true;
     borderTopStyle: "solid";
-    borderTopColor: string;
 };
 export type ResolvedDocumentTableStyle = ResolvedTablePresentationStyle;
 export declare function resolveDocumentTableStyle(section: DocumentTableSection): ResolvedDocumentTableStyle;

package/dist/types/lib/document/document-table-surface.d.ts

@@ -0,0 +1,15 @@
+import { CSSProperties } from 'react';
+import { ResolvedDocumentTableStyle } from './document-table-style.js';
+/**
+ * Light theme tokens for anything drawn on the page. A Document is paper, so
+ * its content stays light when the app is in dark mode.
+ */
+export declare const DOCUMENT_TABLE_LIGHT_THEME_STYLE: CSSProperties;
+export declare function getDocumentTableSurfaceClassName(style: ResolvedDocumentTableStyle): string;
+/** The surface's CSS variables: row height, header and totals colors. */
+export declare function getDocumentTableSurfaceStyle({ style, rowHeightPx, isSliced, }: {
+    style: ResolvedDocumentTableStyle;
+    rowHeightPx: number;
+    /** A page slice has no minimum surface height. */
+    isSliced: boolean;
+}): CSSProperties;

package/dist/types/lib/document/document-variables.d.ts

@@ -1,5 +1,6 @@
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
 import { ControlOption, DocumentInputDefinition, DocumentTextInlineFormat, DocumentTextContent, DocumentVariableRef, ResolvedDocumentInput } from '../types/common-types.js';
+import { TextVariableChipFace, TextVariableOption, TextVariableSelection } from '../text-variables/text-variable-types.js';
 export type DocumentTextRenderContext = {
     inputs: DocumentInputDefinition[];
     resolvedInputsById: Record<string, ResolvedDocumentInput>;
@@ -11,11 +12,6 @@ export type DocumentTextRenderContext = {
     timezone?: string;
     generatedAtFormat?: string;
 };
-export type DocumentVariableChoice = {
-    label: string;
-    token: string;
-    ref: DocumentVariableRef;
-};
 export type ParsedDocumentTextContent = {
     content: DocumentTextContent;
     unresolvedTokens: string[];
@@ -38,12 +34,50 @@ export type RenderedDocumentTextPart = {
     type: 'text' | 'variable';
     value: string;
     format?: DocumentTextInlineFormat;
+    /** Authoring: how a variable reads as a chip. */
+    chip?: TextVariableChipFace;
 };
 export declare function parseDocumentTextContent(value: string, inputs: DocumentInputDefinition[]): ParsedDocumentTextContent;
 export declare function parseDocumentTextContentWithSource(value: string, inputs: DocumentInputDefinition[]): ParsedDocumentTextContentWithSource;
-export declare function getDocumentVariableChoices(inputs: DocumentInputDefinition[]): DocumentVariableChoice[];
 export declare function appendDocumentVariable(content: DocumentTextContent | undefined, ref: DocumentVariableRef): DocumentTextContent;
 export declare function getDocumentVariableLabel(ref: DocumentVariableRef, inputs: DocumentInputDefinition[]): string;
+/** What a reference shows, as the picker names it. */
+export declare function getDocumentVariableSelection(ref: DocumentVariableRef): TextVariableSelection;
+/** The reference a picker selection stands for. */
+export declare function getDocumentVariableRefFromSelection(selection: TextVariableSelection): DocumentVariableRef;
+/** How a reference reads as a chip: the input's name, or Missing input. */
+export declare function getDocumentVariableChipFace(ref: DocumentVariableRef, inputs: DocumentInputDefinition[]): TextVariableChipFace;
+/**
+ * The inputs and report values a Document text can show, each part with what
+ * it holds now when `context` is given.
+ */
+export declare function getDocumentTextVariableOptions(inputs: DocumentInputDefinition[], context?: DocumentTextRenderContext): TextVariableOption[];
+/**
+ * Where a document shows an input: the header, the footer and its text
+ * sections, in reading order.
+ */
+export declare function getDocumentInputTextUsage(document: {
+    header?: {
+        blocks: Array<{
+            type: string;
+            content?: DocumentTextContent;
+        }>;
+    };
+    footer?: {
+        blocks: Array<{
+            type: string;
+            content?: DocumentTextContent;
+        }>;
+    };
+    sections: Array<{
+        type: string;
+        content?: DocumentTextContent;
+    }>;
+}, inputId: string): {
+    header: boolean;
+    footer: boolean;
+    textSections: number;
+};
 export declare function buildDocumentTextRenderContext({ inputs, filterValuesByInputId, controlValuesByInputId, controlOptionsByInputId, generatedAt, timezone, generatedAtFormat, pageNumber, pageCount, }: {
     inputs: DocumentInputDefinition[];
     filterValuesByInputId: Record<string, TFilterValue | undefined>;

package/dist/types/lib/document/use-document-section-data.d.ts

@@ -0,0 +1,39 @@
+import { DocumentSectionRenderState } from './document-section-render-state.js';
+import { DashboardCardQueryResult } from '../hooks/use-dashboard-frame-query.js';
+import { DocumentKpiSection, TCard } from '../types/common-types.js';
+import { ComparisonMetadataMap } from '../types/query-types.js';
+import { DocumentSectionRuntime } from './document-section-query-options.js';
+export type DocumentCardDataStatus = 'unconfigured'
+/** Waiting for required inputs; the query will not run until they are set. */
+ | 'blocked' | 'loading' | 'ready' | 'empty' | 'error';
+export type DocumentCardDataState = {
+    cardId: string;
+    card: TCard;
+    status: DocumentCardDataStatus;
+    /** The card query's records, unchanged. Empty unless `ready`. */
+    records: Record<string, unknown>[];
+    comparisonMetadata?: ComparisonMetadataMap;
+    errorMessage?: string;
+    /** The query failure, for delivery error attributes. */
+    error?: unknown;
+    /** `blocked` only: the required inputs to set. */
+    missingRequiredInputLabels?: string[];
+};
+/** A card can run once it is set up (the dashboard's own rule: a connection plus SQL or fields). */
+export declare function isDocumentSectionCardRunnable(card: TCard): boolean;
+/** The print readiness a card's data status means. */
+export declare function getDocumentCardRenderState(status: DocumentCardDataStatus): DocumentSectionRenderState;
+/** One card's data state from its query result. Exported for tests. */
+export declare function toDocumentCardDataState(card: TCard, result: Pick<DashboardCardQueryResult, 'data' | 'isPending' | 'isFetching' | 'isError' | 'error' | 'errorMessage' | 'comparisonMetadata' | 'isCurrentQueryResult' | 'missingRequiredInputLabels'>): DocumentCardDataState;
+/**
+ * Data for every card of a KPI section, in display order. Each card runs
+ * through the dashboard card query in the section's runtime (section-scoped
+ * inputs, document filters and controls), so a Document never has its own
+ * query path.
+ *
+ * KPI sections only: table sections acquire their rows through
+ * `useDocumentTableRows` (row policy, full-result acquisition for export) and
+ * share only the options builder. Reading a table through this hook would
+ * print a partial result.
+ */
+export declare function useDocumentSectionData(section: DocumentKpiSection, runtime: Omit<DocumentSectionRuntime, 'missingRequiredInputLabels'>): readonly DocumentCardDataState[];

package/dist/types/lib/document/use-measured-document-table-layout.d.ts

@@ -0,0 +1,50 @@
+import { RefObject } from 'react';
+import { DocumentTableSlice } from './document-pagination.js';
+import { DocumentTableLayoutMeasurement } from './document-table-print-model.js';
+export declare function useMeasuredTableLayout({ sectionId, sectionRef, tableSurfaceRef, enabled, measureKey, measurementScale, fallbackRowHeightPx, rowRangeStartIndex, rowRangeEndIndex, totalRowCount, canUpdateLayoutChrome, measureColumnWidths, extraMeasurement, onTableLayoutMeasure, }: {
+    sectionId: string;
+    sectionRef: RefObject<HTMLDivElement | null>;
+    tableSurfaceRef: RefObject<HTMLDivElement | null>;
+    enabled: boolean;
+    measureKey: string;
+    measurementScale: number;
+    /** For a drawn row with no layout box (a test DOM). */
+    fallbackRowHeightPx: number;
+    rowRangeStartIndex: number;
+    rowRangeEndIndex: number;
+    totalRowCount: number;
+    canUpdateLayoutChrome: boolean;
+    /** Report the first drawn row's cell widths (Matrix). */
+    measureColumnWidths?: boolean;
+    /** Reported with the measurement (a Matrix's fit). Keep it stable. */
+    extraMeasurement?: Pick<DocumentTableLayoutMeasurement, 'matrixFit'>;
+    onTableLayoutMeasure?: (sectionId: string, measurement: DocumentTableLayoutMeasurement) => void;
+}): void;
+/**
+ * Measures a Matrix printed in column bands (Plan 2, 2c, B2): every band draws
+ * every row, inside a `[data-document-matrix-band]` container under
+ * `bandsRef`. A row's height is its tallest across the bands, and the chrome
+ * is the tallest band's, so a slice of rows fits the page in every band.
+ */
+export declare function useMeasuredBandedTableLayout({ sectionId, sectionRef, bandsRef, enabled, measureKey, measurementScale, fallbackRowHeightPx, rowCount, extraMeasurement, onTableLayoutMeasure, }: {
+    sectionId: string;
+    sectionRef: RefObject<HTMLDivElement | null>;
+    bandsRef: RefObject<HTMLDivElement | null>;
+    enabled: boolean;
+    measureKey: string;
+    measurementScale: number;
+    fallbackRowHeightPx: number;
+    rowCount: number;
+    /** Reported with the measurement: widths and the fit. Keep it stable. */
+    extraMeasurement?: Pick<DocumentTableLayoutMeasurement, 'matrixFit' | 'columnWidthsPx'>;
+    onTableLayoutMeasure?: (sectionId: string, measurement: DocumentTableLayoutMeasurement) => void;
+}): void;
+export declare function getMeasurementRowRange({ tableSlice, initialRowsPerPageLimit, totalRowCount, }: {
+    tableSlice?: DocumentTableSlice;
+    initialRowsPerPageLimit?: number;
+    totalRowCount: number;
+}): {
+    startIndex: number;
+    endIndex: number;
+    totalRowCount: number;
+};

package/dist/types/lib/formatters/kpi-result-values.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Reads KPI values out of a card query result. Shared by the dashboard KPI
+ * cards and the Document KPI section, so both read the same number from the
+ * same result.
+ */
+/** A finite number from a numeric value or a numeric string (thousands commas allowed). */
+export declare function toFiniteKpiNumber(value: unknown): number | null;
+/**
+ * SQL-backed KPI: the first row's first displayed numeric column is the
+ * current value, the second is the previous value.
+ */
+export declare function readSqlKpiValues(data?: Record<string, unknown>[] | null): {
+    current: number | null;
+    previous: number | null;
+};
+/**
+ * Explorer KPI: the value of a result segment (`current`, `comparison`) for
+ * the primary metric. Rows without a `metricId` match any metric.
+ */
+export declare function readKpiSegmentValue(data: Record<string, unknown>[] | null | undefined, segment: string, metricId?: string): number | null;

package/dist/types/lib/hooks/query-context/use-dashboard-card-execution-snapshot.d.ts

@@ -1,4 +1,10 @@
 import { MatrixCardCatalog } from '../../matrix-table/matrix-card-adapter.js';
 import { TCard } from '../../types/common-types.js';
-/** Store adapter only: field, input, scope and precision decisions stay in the compiler. */
-export declare function useDashboardCardExecutionSnapshot(card: TCard, matrixCatalog: MatrixCardCatalog): import('../../query-context/build-dashboard-execution-snapshot.js').DashboardCardExecutionSnapshotResult;
+import { DocumentSectionCardRuntime } from '../../query-context/document-section-card-query.js';
+/**
+ * Store adapter only: field, input, scope and precision decisions stay in the
+ * compiler. A Document section passes its runtime; the editor's preview of a
+ * section's card uses the editor's snapshot of the document inputs, as the
+ * card's frame query does.
+ */
+export declare function useDashboardCardExecutionSnapshot(card: TCard, matrixCatalog: MatrixCardCatalog, documentSection?: DocumentSectionCardRuntime): import('../../query-context/build-dashboard-execution-snapshot.js').DashboardCardExecutionSnapshotResult;

package/dist/types/lib/hooks/use-dashboard-frame-query.d.ts

@@ -27,6 +27,12 @@ type AdditionalState = {
     effectiveCardConfig?: CardConfig;
     resultOwner: TemporalResultOwner;
     isCurrentQueryResult: boolean;
+    /**
+     * Required inputs this card's Document section query is waiting for. When
+     * non-empty the query is disabled and will not run until they are set, so
+     * a Document renders it as blocked, not loading.
+     */
+    missingRequiredInputLabels: string[];
 };
 export type DashboardCardQueryResult = UseQueryResult<any, Error> & AdditionalState;
 export type DashboardCardQueryOptions = {

package/dist/types/lib/hooks/use-dashboard-kpi-actions.d.ts

@@ -2,7 +2,7 @@ import { TCard } from '../types/common-types.js';
 /**
  * Hook that provides KPI card actions scoped to visual editor mode.
  */
-export declare function useDashboardKpiActions(_card: TCard): {
+export declare function useDashboardKpiActions(card: TCard): {
     setTitle: (title: string) => void;
     setCountryLogo: (countryId: string | null) => void;
     isEditable: boolean;

package/dist/types/lib/hooks/use-document-section-editor.d.ts

@@ -1,3 +1,3 @@
-import { ControlDefinition, DocumentTableSection } from '../types/common-types.js';
+import { ControlDefinition, DocumentKpiSection, DocumentTableSection } from '../types/common-types.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
-export declare function useDocumentSectionEditor(): (sheetId: string, section: DocumentTableSection, documentFilterValues?: TFilterValue[], documentControlDefinitions?: ControlDefinition[], documentControlValues?: Record<string, unknown>, missingRequiredInputLabels?: string[]) => void;
+export declare function useDocumentSectionEditor(): (sheetId: string, section: DocumentTableSection | DocumentKpiSection, documentFilterValues?: TFilterValue[], documentControlDefinitions?: ControlDefinition[], documentControlValues?: Record<string, unknown>, missingRequiredInputLabels?: string[], cardId?: string) => void;

package/dist/types/lib/hooks/use-document-section-session.d.ts

@@ -0,0 +1,36 @@
+import { ControlDefinition, DocumentKpiSection, DocumentTableSection, TFrame } from '../types/common-types.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+export type DocumentSectionCommitResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type OpenDocumentSectionSession = {
+    sheetId: string;
+    section: DocumentTableSection | DocumentKpiSection;
+    /** The card to edit; required for a KPI section with several cards. */
+    cardId?: string;
+    documentFilterValues?: TFilterValue[];
+    documentControlDefinitions?: ControlDefinition[];
+    documentControlValues?: Record<string, unknown>;
+    missingRequiredInputLabels?: string[];
+};
+export type DocumentSectionSession = {
+    open(target: OpenDocumentSectionSession): void;
+    /**
+     * Writes the accepted frame's card, and its calculated fields, in one
+     * document edit. `acceptedFrame` is the frame Accept built and validated:
+     * metadata is resolved for it and it is what is written, as a dashboard
+     * visual's save does, so the two always match.
+     */
+    commit(acceptedFrame: TFrame): Promise<DocumentSectionCommitResult>;
+    discard(): void;
+};
+/**
+ * One editor session on one card of a document section. It opens today's
+ * full-screen visual editor on the existing path (`setupEditorWithCard`, so
+ * `isVisualEditing` stays the calculated-field draft boundary and query gate),
+ * and nothing reaches the dashboard until `commit()`.
+ */
+export declare function useDocumentSectionSession(): DocumentSectionSession;

package/dist/types/lib/hooks/use-editor-preview.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+/**
+ * Marks everything below it as the visual editor's preview. Only `<Editor>`
+ * provides it. Whether a component is the editor's preview is a fact about
+ * where it renders, not a global mode: a Document page stays on screen while
+ * one of its cards is open in the editor, and it is a report, not the
+ * editor's preview.
+ */
+export declare function EditorPreviewScope({ children }: {
+    children: ReactNode;
+}): import('react').FunctionComponentElement<import('react').ProviderProps<boolean>>;
+/**
+ * Whether this component renders inside the visual editor. Visuals, filters
+ * and queries read this, never the store's `isVisualEditing`, which only
+ * means "the editor UI is open" (tech spec M7).
+ */
+export declare function useIsEditorPreview(): boolean;

package/dist/types/lib/hooks/use-is-editing-card.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether this card is the one open in the visual editor. Card-level editing
+ * affordances (inline title and description) key on this rather than the
+ * global `isVisualEditing`, so a page that shows several cards while one is
+ * edited, such as a Document, keeps the others read-only.
+ */
+export declare function useIsEditingCard(cardId: string | undefined): boolean;

package/dist/types/lib/matrix-table/matrix-card-adapter.d.ts

@@ -35,6 +35,7 @@ export declare function prepareMatrixCard(card: TCard, catalog: MatrixCardCatalo
                         position: "before" | "after";
                         label?: string | undefined;
                     }>>;
+                    skipRedundant?: boolean | undefined;
                 };
                 rows: {
                     grand: {
@@ -47,6 +48,7 @@ export declare function prepareMatrixCard(card: TCard, catalog: MatrixCardCatalo
                         position: "before" | "after";
                         label?: string | undefined;
                     }>>;
+                    skipRedundant?: boolean | undefined;
                 };
             };
             layout: {

package/dist/types/lib/matrix-table/matrix-card-draft.d.ts

@@ -15,6 +15,7 @@ export declare function initializeMatrixCardDraft(card: Pick<TCard, 'config' | '
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -27,6 +28,7 @@ export declare function initializeMatrixCardDraft(card: Pick<TCard, 'config' | '
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {

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

@@ -98,6 +98,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                             position: "before" | "after";
                             label?: string | undefined;
                         }>>;
+                        skipRedundant?: boolean | undefined;
                     };
                     rows: {
                         grand: {
@@ -110,6 +111,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                             position: "before" | "after";
                             label?: string | undefined;
                         }>>;
+                        skipRedundant?: boolean | undefined;
                     };
                 };
                 layout: {
@@ -448,6 +450,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                             position: "before" | "after";
                             label?: string | undefined;
                         }>>;
+                        skipRedundant?: boolean | undefined;
                     };
                     rows: {
                         grand: {
@@ -460,6 +463,7 @@ export declare function buildMatrixDeliveryPayload(input: {
                             position: "before" | "after";
                             label?: string | undefined;
                         }>>;
+                        skipRedundant?: boolean | undefined;
                     };
                 };
                 layout: {

package/dist/types/lib/matrix-table/matrix-layout-read.d.ts

@@ -0,0 +1,68 @@
+import { MatrixLayoutReadResult } from '../../shared/dashboard-authoring/matrix-delivery.js';
+import { buildMatrixDeliveryPayload } from './matrix-delivery.js';
+import { DocumentTableRowFacts } from '../document/document-pagination.js';
+import { FastPathTableStructure } from '../../shared/format-utils/table-structure.js';
+import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
+/** Matrix sections on one page read at most this many full results at once (tech spec G6). */
+export declare const MATRIX_LAYOUT_READ_CONCURRENCY = 2;
+/**
+ * The full Matrix result a Document section prints, from the delivery-authorized
+ * layout route (tech spec D-M1). Always resolves to the typed result; an abort
+ * rejects, so it is never kept as a result.
+ */
+export declare function readMatrixLayout(input: {
+    apiServiceUrl: string;
+    token: string;
+    payload: ReturnType<typeof buildMatrixDeliveryPayload>;
+    signal: AbortSignal;
+}): Promise<MatrixLayoutReadResult>;
+/** How a printed row reads: its role and where it sits in the hierarchy. */
+export type MatrixPrintRowKind = 'member'
+/** A parent row in outline layout, heading its children. */
+ | 'group'
+/** The subtotal of the innermost group level. */
+ | 'subtotal_inner'
+/** The subtotal of an outer group level. */
+ | 'subtotal_outer' | 'grand_total';
+export type MatrixPrintRow = {
+    kind: MatrixPrintRowKind;
+    /**
+     * Group labels this row hides because the row above shows them, by column
+     * index. A page that starts at this row repeats them, marked "(cont.)".
+     */
+    continuation?: Readonly<Record<number, string>>;
+    /**
+     * Indented layout: the parent header rows a page that starts at this row
+     * repeats, outermost first, already indented and marked "(cont.)".
+     */
+    continuationHeaders?: readonly string[];
+};
+/** A read as the page draws it: the formatted table and each row's print facts. */
+export type DocumentMatrixRead = {
+    status: 'ok';
+    table: FastPathTableStructure;
+    rows: readonly MatrixPrintRow[];
+    /** Indented layout: the column that carries the row labels. */
+    hierarchyColumn?: number;
+    /**
+     * Column groups for bands (Plan 2, 2c): per column, the index of its
+     * group in `groups`, or `null` for a row-label column. A group is one
+     * column member (or total) with all its measures.
+     */
+    columnGroups: readonly (number | null)[];
+    /** Each group's label, as the header prints it ("Houston", "Grand Total"). */
+    groupLabels: readonly string[];
+    /** What bands name their groups by: the innermost column level, or "Measures". */
+    groupLevelLabel: string;
+    /** How the paginator may split these rows (Plan 2, L1 and L5). */
+    pageBreaks: DocumentTableRowFacts;
+} | Extract<MatrixLayoutReadResult, {
+    status: 'failed';
+}>;
+/**
+ * Formats a read once, with the definition that ran. The Document section
+ * does this in its query, so every page slice shares one formatted table.
+ * The table is the one every Matrix PDF prints (`buildMatrixPrintTable`);
+ * this adds what only a Document uses, such as "(cont.)" labels.
+ */
+export declare function formatMatrixLayoutRead(result: MatrixLayoutReadResult, report: ReportRuntimeContext): DocumentMatrixRead;

package/dist/types/lib/query-context/build-dashboard-execution-snapshot.d.ts

@@ -6,6 +6,7 @@ import { BuildCardQueryContextParams, CompiledCardQueryContext } from './build-c
 import { CompiledDashboardCardFilters } from './compile-dashboard-card-filters.js';
 import { DashboardInputResolveMode } from '../dashboard-inputs/resolve-dashboard-input-context.js';
 import { prepareMatrixCard, MatrixCardCatalog } from '../matrix-table/matrix-card-adapter.js';
+import { DocumentSectionCardRuntime } from './document-section-card-query.js';
 export type DashboardExecutionSnapshot = {
     selectedSheetId: string | null;
     filterValues: TFilterValue[];
@@ -36,6 +37,12 @@ export type BuildDashboardCardExecutionSnapshotParams = Omit<BuildCardQueryConte
     /** Editor drafts replace their persisted card only for this computation. */
     cardOverride?: TCard;
     sheetId?: string | null;
+    /**
+     * Runs the target card as a Document section (tech spec G3), with the same
+     * rules as every section card's frame query. Other cards keep the dashboard
+     * runtime.
+     */
+    documentSection?: DocumentSectionCardRuntime;
 };
 export type DashboardCardExecutionSnapshot = {
     status: 'ready';
@@ -52,5 +59,5 @@ export type DashboardCardExecutionSnapshotResult = DashboardCardExecutionSnapsho
     message?: string;
 } | null;
 export declare function requireReadyDashboardCardExecutionSnapshot(result: DashboardCardExecutionSnapshotResult): DashboardCardExecutionSnapshot | null;
-export declare function buildDashboardCardExecutionSnapshot({ dashboard, cardId, transientContexts, cardViewStates, semanticExecutionPayload, filters, filterValues, inlineFilterValuesMap, dashboardControls, dashboardControlValues, cardControlValuesMap, dashboardInputValues, dashboardInputMode, timezone, matrixCatalog, cardOverride, sheetId, }: BuildDashboardCardExecutionSnapshotParams): DashboardCardExecutionSnapshotResult;
+export declare function buildDashboardCardExecutionSnapshot({ dashboard, cardId, transientContexts, cardViewStates, semanticExecutionPayload, filters, filterValues, inlineFilterValuesMap, dashboardControls, dashboardControlValues, cardControlValuesMap, dashboardInputValues, dashboardInputMode, timezone, matrixCatalog, cardOverride, sheetId, documentSection, }: BuildDashboardCardExecutionSnapshotParams): DashboardCardExecutionSnapshotResult;
 export {};