react-semaphor 0.1.541 → 0.1.543

package/dist/types/shared/format-utils/exporters/export-cells.d.ts

@@ -0,0 +1,90 @@
+import { ExactNumericValue } from '../../analytics-protocol/scalar-value.js';
+import { MeasureCanonicalFormat } from '../types/format-types.js';
+export type ExportDataType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+/** What an export path knows about one column. Input to resolveXlsxColumn. */
+export type XlsxColumnInput = {
+    key: string;
+    /** The column's header label. */
+    label: string;
+    /** "Use formatted values". False means stored values. */
+    formattedValues: boolean;
+    /** Authoritative: from the result's `resultColumns` (SemaphorResultColumn.dataType); 'unknown' when absent. */
+    dataType: ExportDataType;
+    /** The presentation that made this column's display text, if any. */
+    presentation?: XlsxColumnPresentation;
+};
+export type XlsxColumnPresentation = 
+/** A numeric or duration measure format (from the presentation snapshot). */
+{
+    kind: 'measure';
+    format: MeasureCanonicalFormat;
+}
+/** A grouped date. `grain` from the bucket metadata; an unlisted grain is 'custom'. */
+ | {
+    kind: 'temporal_bucket';
+    grain: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'fiscal' | 'custom';
+}
+/** A raw date or datetime column, or a column with date settings. `dateOnly` when its values carry no time. */
+ | {
+    kind: 'datetime';
+    dateOnly: boolean;
+}
+/** Shown as text, including epoch numbers shown as dates. */
+ | {
+    kind: 'text';
+};
+/** A column as the Excel writer needs it. Built only by resolveXlsxColumn. */
+export type XlsxColumn = {
+    readonly key: string;
+    readonly label: string;
+    /** 'by_value' types each value by its JS type: stored-value exports and columns of unknown type. */
+    readonly cellType: 'number' | 'date' | 'boolean' | 'text' | 'by_value';
+    /** Excel number format code for number and date cells; undefined means General. */
+    readonly numberFormat?: string;
+};
+/** One exported cell. `text` is its display text. */
+export type ExportCell = {
+    kind: 'empty';
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'number';
+    text: string;
+    /** A JS number, an exact decimal, or plain decimal text. */
+    value: number | ExactNumericValue | string;
+} | {
+    kind: 'date';
+    text: string;
+    serial: number;
+} | {
+    kind: 'boolean';
+    text: string;
+    value: boolean;
+};
+/** A calendar date and time with no zone, as a temporal owner interpreted it for display. */
+export type ExportWallClock = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+};
+/** Pure. Never throws. The complete rule is the two tables in the Excel exports spec (§2.2). */
+export declare function resolveXlsxColumn(input: XlsxColumnInput): XlsxColumn;
+/** A plain decimal: optional '-', digits, optional '.digits', optional exponent. No grouping separators, no spaces. */
+export declare function parsePlainNumericString(value: string): string | undefined;
+/**
+ * The cell rule. Pure; never throws. `text` is the display text the path made.
+ * `wallClock` is supplied for date columns by the temporal owner that made
+ * `text`; this module never parses dates. First matching rule wins (spec §2.3).
+ */
+export declare function toExportCell(input: {
+    value: unknown;
+    text: string;
+    column: XlsxColumn;
+    wallClock?: ExportWallClock;
+}): ExportCell;
+/** The display text: '' for empty, otherwise `text`. */
+export declare function exportCellText(cell: ExportCell): string;

package/dist/types/shared/format-utils/exporters/export-file-format.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The export file format owner: what a CSV or Excel export file is called,
+ * typed, keyed and stored as. Every export producer (browser downloads, the
+ * app's export routes, the chunk and compaction Lambdas, Briefing
+ * attachments) reads these traits instead of writing its own extension,
+ * content type or storage-key suffix. See "Excel file standard" in the
+ * format-utils README.
+ * IMPORTANT: No React or browser-specific imports allowed
+ */
+/** Data file formats a Table, Detail Table or Matrix export can produce. */
+export declare const EXPORT_FILE_FORMATS: readonly ["csv", "xlsx"];
+export type ExportFileFormat = (typeof EXPORT_FILE_FORMATS)[number];
+/** Content type of every delivered Excel workbook. */
+export declare const XLSX_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+export type ExportFileTraits = {
+    format: ExportFileFormat;
+    /** File name extension without the dot: 'csv' | 'xlsx'. */
+    extension: 'csv' | 'xlsx';
+    /** CSV_CONTENT_TYPE | XLSX_CONTENT_TYPE. */
+    contentType: string;
+    /** Extension of one chunk or Matrix batch object before compaction: 'csv' | 'xml'. */
+    partExtension: 'csv' | 'xml';
+    /** Content type that object is stored with: 'text/csv' (as Matrix attempts have always been stored) | 'application/xml'. */
+    partContentType: 'text/csv' | 'application/xml';
+    /** File name of the compacted background artifact: 'export.csv.gz' | 'export.xlsx'. */
+    compactedFileName: 'export.csv.gz' | 'export.xlsx';
+    /** How the compacted artifact is stored: CSV gzipped, a workbook as is (already a zip). */
+    storedEncoding: 'gzip' | 'identity';
+    /** Stored form: Prisma ExportFormat value and the export job config's `format`. */
+    storedValue: 'CSV' | 'XLSX';
+    /** Customer-facing name: 'CSV' | 'Excel'. */
+    label: 'CSV' | 'Excel';
+};
+export declare function parseExportFileFormat(value: unknown): ExportFileFormat | undefined;
+export declare function exportFileTraits(format: ExportFileFormat): ExportFileTraits;
+export declare function exportFileFormatFromStored(value: 'CSV' | 'XLSX'): ExportFileFormat;
+/** For a client reading a server response: the format whose contentType matches (ignoring parameters), else undefined. */
+export declare function exportFileFormatFromContentType(contentType: string | null): ExportFileFormat | undefined;
+/** `${safeTitle}-${UTC timestamp}.${extension}`. The only export file name builder. */
+export declare function exportFileName(input: {
+    format: ExportFileFormat;
+    title: string | null | undefined;
+    at?: Date;
+}): string;

package/dist/types/shared/format-utils/exporters/index.d.ts

@@ -1,2 +1,8 @@
 export { CSV_ENCODINGS, DEFAULT_CSV_ENCODING, CSV_DELIMITERS, CSV_RECORD_SEPARATOR, CSV_CONTENT_TYPE, parseCsvEncoding, parseCsvDelimiter, resolveCsvEncoding, csvFilePreamble, toCsvCell, escapeCSVValue, protectCSVText, csvRecord, csvRecords, encodeCsvFile, } from './csv-utils.js';
 export type { CsvEncoding, CsvDelimiter, CsvCell } from './csv-utils.js';
+export { EXPORT_FILE_FORMATS, XLSX_CONTENT_TYPE, parseExportFileFormat, exportFileTraits, exportFileFormatFromStored, exportFileFormatFromContentType, exportFileName, } from './export-file-format.js';
+export type { ExportFileFormat, ExportFileTraits } from './export-file-format.js';
+export { resolveXlsxColumn, exportCellText } from './export-cells.js';
+export type { ExportDataType, XlsxColumnInput, XlsxColumnPresentation, XlsxColumn, ExportCell, ExportWallClock, } from './export-cells.js';
+export { XlsxLimitError, isXlsxLimitError, XLSX_LIMIT_FAILURE_REASONS, xlsxLimitFailureReason, assertXlsxColumnCount, defineXlsxSheet, serializeXlsxSheet, parseXlsxSheet, withXlsxSheetColumns, serializeXlsxColumns, parseXlsxColumns, xlsxColumnsFingerprint, encodeXlsxFile, encodeXlsxRows, streamXlsxFile, } from './xlsx-file.js';
+export type { XlsxSheet, XlsxRow, XlsxMerge, XlsxLimitFailureReason } from './xlsx-file.js';

package/dist/types/shared/format-utils/exporters/xlsx-file.d.ts

@@ -0,0 +1,90 @@
+import { ExportCell, XlsxColumn } from './export-cells.js';
+/** The only error the Excel modules throw on purpose. Its message is customer-facing and product-neutral. */
+export declare class XlsxLimitError extends Error {
+    /** `size` counts sheet XML bytes. */
+    readonly limit: 'rows' | 'columns' | 'size';
+    readonly actual: number;
+    readonly max: number;
+    constructor(limit: 'rows' | 'columns' | 'size', actual: number, max: number);
+}
+/**
+ * The export failure catalog reason for each Excel limit (SPEC §2.6). A worker
+ * that hits a limit inside a job reports this reason; the app's catalog holds
+ * the message. Nothing ever recovers a reason from message text.
+ */
+export declare const XLSX_LIMIT_FAILURE_REASONS: readonly ["excel_row_limit", "excel_column_limit", "excel_size_limit"];
+export type XlsxLimitFailureReason = (typeof XLSX_LIMIT_FAILURE_REASONS)[number];
+export declare function xlsxLimitFailureReason(error: XlsxLimitError): XlsxLimitFailureReason;
+/** Throws XlsxLimitError('columns') when a sheet would be wider than Excel allows: for callers that know the width before any rows exist (XL-D33). */
+export declare function assertXlsxColumnCount(count: number): void;
+/** Structural, so an error from another copy of this module still counts. */
+export declare function isXlsxLimitError(error: unknown): error is XlsxLimitError;
+export type XlsxMerge = {
+    row: number;
+    firstColumn: number;
+    lastColumn: number;
+};
+/** A validated sheet layout that every writer of one file shares. Built only by defineXlsxSheet. */
+export type XlsxSheet = {
+    readonly name: string;
+    readonly columns: readonly XlsxColumn[];
+    /** Header rows above the data, top first. Empty when headers are off. */
+    readonly headerRows: readonly (readonly string[])[];
+    /** Horizontal merges inside header rows (Matrix column bands). Zero-based. */
+    readonly merges: readonly XlsxMerge[];
+    /** Column widths in characters, one per column. */
+    readonly widths: readonly number[];
+};
+/**
+ * Validates and freezes a sheet. Throws XlsxLimitError('columns') above 16,384
+ * columns. `sampleRows` only tunes widths.
+ */
+export declare function defineXlsxSheet(input: {
+    title: string;
+    columns: readonly XlsxColumn[];
+    headerRows: readonly (readonly string[])[];
+    /** Explicit header merges. The caller derives them from identity (Matrix: member paths and roles); the writer only validates and writes them. */
+    merges?: readonly XlsxMerge[];
+    sampleRows?: readonly (readonly ExportCell[])[];
+}): XlsxSheet;
+/** JSON form, for workers that share one sheet (the first chunk or layout batch writes it; compaction reads it). */
+export declare function serializeXlsxSheet(sheet: XlsxSheet): string;
+/**
+ * The same sheet with settled columns, one per existing column. A background
+ * job's first chunk writes the sheet; a column its rows could not type takes
+ * the type the other chunks found (row fragments do not depend on it: styles
+ * go by column position).
+ */
+export declare function withXlsxSheetColumns(sheet: XlsxSheet, columns: readonly XlsxColumn[]): XlsxSheet;
+/** A column list as JSON and back, checked as a sheet's columns are. */
+export declare function serializeXlsxColumns(columns: readonly XlsxColumn[]): string;
+export declare function parseXlsxColumns(value: unknown): XlsxColumn[];
+export declare function parseXlsxSheet(json: string): XlsxSheet;
+/** Stable hash of a column list; equal for structurally equal columns. */
+export declare function xlsxColumnsFingerprint(columns: readonly XlsxColumn[]): string;
+export type XlsxRow = {
+    role: 'body' | 'total';
+    cells: readonly ExportCell[];
+};
+/** Joinable sheet XML for some rows (one chunk, one Matrix batch, or a totals row). Pure. */
+export declare function encodeXlsxRows(sheet: XlsxSheet, rows: Iterable<XlsxRow>): string;
+/** A whole workbook in memory: browser downloads and Matrix direct. */
+export declare function encodeXlsxFile(sheet: XlsxSheet, rows: Iterable<XlsxRow>): Uint8Array;
+/**
+ * The whole workbook as zip bytes, from row fragments made by encodeXlsxRows,
+ * in order. A totals row is just a last fragment. `rowCount` counts every
+ * row in the fragments (body and total); `fragmentBytes` is their UTF-8 size
+ * (the stored size of the chunk or batch objects). Backpressure follows the
+ * consumer: the next fragment is read only after the bytes before it were
+ * taken. Throws XlsxLimitError('rows') or ('size') here, before anything is
+ * written. Fragments that turn out larger than `fragmentBytes` fail with
+ * XlsxLimitError('size') before the sheet passes the limit, and any other
+ * mismatch fails with TypeError before the file is finished, so a wrong count
+ * never yields a complete file.
+ */
+export declare function streamXlsxFile(input: {
+    sheet: XlsxSheet;
+    fragments: AsyncIterable<string | Uint8Array>;
+    rowCount: number;
+    fragmentBytes: number;
+}): AsyncIterable<Uint8Array>;

package/dist/types/shared/format-utils/formatters/date-formatter.d.ts

@@ -1,15 +1,4 @@
-/**
- * Date formatting utilities with timezone support
- * IMPORTANT: No React imports allowed in this file
- *
- * Uses date-fns and date-fns-tz for consistent behavior in browser and Node.js
- *
- * This module provides the canonical date formatting functions used by:
- * - data-table component
- * - pivot-table component
- * - aggregated-table component
- * - Lambda CSV export (chunk-processor)
- */
+import { ExportWallClock } from '../exporters/export-cells.js';
 /**
  * Resolve which timezone to use for formatting
  * Priority: column-specific > context timezone
@@ -52,6 +41,13 @@ export declare function parseWithSourceTimezone(dateString: string, sourceTimezo
  * formatDate('2024-01-15T10:30:00Z', 'MM/dd/yyyy HH:mm', 'America/Chicago') // '01/15/2024 04:30'
  */
 export declare const formatDate: (dateString: string | null | undefined, formatPattern: string | undefined, displayTimezone?: string, sourceTimezone?: string) => string;
+/**
+ * The calendar date and time `formatDate` shows for the same inputs, with no
+ * zone: the same source-zone interpretation and display-zone conversion.
+ * Undefined when `formatDate` would return the input unchanged (empty or not
+ * a date). Excel exports write it as a date serial (Excel exports plan XL-D35).
+ */
+export declare function dateWallClock(dateString: string | null | undefined, displayTimezone?: string, sourceTimezone?: string): ExportWallClock | undefined;
 /**
  * Format relative time using date-fns (e.g., "2 days ago")
  *

package/dist/types/shared/format-utils/formatters/index.d.ts

@@ -1,6 +1,6 @@
 export { formatNumber, formatCurrency, formatPercent, formatScientific, formatNumericCanonical, formatMeasureCanonical, formatNumberWithColumnSettings, formatNumberCustom, } from './number-formatter.js';
 export { formatDuration, formatDurationCanonical } from './duration-formatter.js';
 export { formatMetricComparison, type FormattedMetricComparison, type FormattedMetricComparisonPart, type FormatMetricComparisonOptions, type MetricComparisonDisplayMode, } from './metric-comparison-formatter.js';
-export { formatDate, formatRelativeTime, resolveTimezone, getTimezoneAbbreviation, getTimezoneName, parseWithSourceTimezone, } from './date-formatter.js';
+export { formatDate, formatRelativeTime, dateWallClock, resolveTimezone, getTimezoneAbbreviation, getTimezoneName, parseWithSourceTimezone, } from './date-formatter.js';
 export { formatCellValue, formatRowForExport } from './cell-formatter.js';
 export type { CellAbsencePresentation } from './cell-formatter.js';

package/dist/types/shared/format-utils/formatters/matrix-formatter.d.ts

@@ -1,5 +1,6 @@
 import { MatrixPath, MatrixPresentation, MatrixWindow, SemaphorScalarValue, SemaphorValueFormat } from '../../analytics-protocol/index.js';
 import { ReportRuntimeContext } from '../../report-runtime-context/index.js';
+import { MeasureCanonicalFormat } from '../types/index.js';
 /** Null hierarchy members stay identifiable even when null cells render blank. */
 export declare function matrixMemberLabel(path: MatrixPath, levels?: ReadonlyMap<string, (value: SemaphorScalarValue) => string>): string;
 /**
@@ -39,6 +40,7 @@ export declare function prepareMatrixFormatting(descriptors: MatrixWindow['descr
         isNumeric: boolean;
         hasTextAffixes: boolean;
     }>;
+    measureFormats: Map<string, MeasureCanonicalFormat>;
     absence: {
         emptyText: string;
         nullText: string;

package/dist/types/shared/format-utils/index.d.ts

@@ -18,6 +18,7 @@ export * from './exporters/index.js';
 export * from './export-policy.js';
 export * from './matrix-continuation.js';
 export * from './matrix-export-presentation.js';
+export * from './matrix-export-xlsx.js';
 export * from './matrix-print.js';
 export { fromSemanticFormat } from './semantic-format.js';
 export type * from './table-structure.js';
@@ -30,6 +31,7 @@ export * from './temporal-bucket.js';
 export * from './raw-temporal.js';
 export * from './temporal-input-presentation.js';
 export * from './flat-table-export-totals.js';
+export * from './table-export/index.js';
 export * from './filter-line.js';
 export * from './attachment-filter-line.js';
 export { describeFilterValueInFullDetail, type FullDetailFilterValue, } from './filter-value-text.js';

package/dist/types/shared/format-utils/matrix-continuation.d.ts

@@ -1,6 +1,12 @@
 import { z } from 'zod';
 /** Transport budget, independent of total export bytes and analytical tile budgets. */
 export declare const MATRIX_EXPORT_TRANSFER_BYTES: number;
+/**
+ * Largest decoded Excel data part of one batch. Excel rows travel gzipped
+ * (their markup is several times the CSV text), so the transfer budget bounds
+ * them compressed; this bounds what the worker decodes and stores.
+ */
+export declare const MATRIX_EXPORT_DECODED_PART_BYTES: number;
 export declare const matrixExportDeadlineSchema: z.ZodNumber;
 export declare function parseMatrixAttemptKey(jobId: string, key: string): {
     attemptId: string;
@@ -37,27 +43,27 @@ export declare const matrixBatchResponseSchema: z.ZodDiscriminatedUnion<"kind",
     objects: z.ZodArray<z.ZodEffects<z.ZodObject<{
         key: z.ZodString;
         content: z.ZodString;
-        contentType: z.ZodEnum<["text/csv", "application/json"]>;
+        contentType: z.ZodEnum<[string, ...string[]]>;
         encoding: z.ZodOptional<z.ZodLiteral<"gzip-base64">>;
     }, "strip", z.ZodTypeAny, {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }, {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }>, {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }, {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }>, "many">;
     deadlineAt: z.ZodNumber;
@@ -69,7 +75,7 @@ export declare const matrixBatchResponseSchema: z.ZodDiscriminatedUnion<"kind",
     objects: {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }[];
 }, {
@@ -80,7 +86,7 @@ export declare const matrixBatchResponseSchema: z.ZodDiscriminatedUnion<"kind",
     objects: {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }[];
 }>, z.ZodObject<{
@@ -110,7 +116,7 @@ export declare function parseMatrixBatchResponse(value: unknown, input: MatrixBa
     objects: {
         key: string;
         content: string;
-        contentType: "text/csv" | "application/json";
+        contentType: string;
         encoding?: "gzip-base64" | undefined;
     }[];
 } | {
@@ -119,7 +125,7 @@ export declare function parseMatrixBatchResponse(value: unknown, input: MatrixBa
     done: boolean;
     deadlineAt: number;
 };
-export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
+export declare const matrixManifestSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     acquisition: z.ZodLiteral<"continuation">;
     deadlineAt: z.ZodNumber;
     chunks: z.ZodArray<z.ZodObject<{
@@ -136,6 +142,10 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     totalBytes: z.ZodNumber;
     fileKey: z.ZodOptional<z.ZodString>;
     fileSize: z.ZodOptional<z.ZodNumber>;
+    /** The file the job writes; absent means CSV (manifests from before Excel). */
+    format: z.ZodOptional<z.ZodEnum<["csv", "xlsx"]>>;
+    /** Excel only: the sheet layout the layout batch stored, which compaction wraps the rows in. */
+    sheetKey: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     acquisition: "continuation";
     deadlineAt: number;
@@ -145,8 +155,10 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 }, {
     acquisition: "continuation";
     deadlineAt: number;
@@ -156,8 +168,10 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 }>, {
     acquisition: "continuation";
     deadlineAt: number;
@@ -167,8 +181,10 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 }, {
     acquisition: "continuation";
     deadlineAt: number;
@@ -178,8 +194,36 @@ export declare const matrixManifestSchema: z.ZodEffects<z.ZodObject<{
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
+}>, {
+    acquisition: "continuation";
+    deadlineAt: number;
+    chunks: {
+        chunkNumber: number;
+        dataKey: string;
+    }[];
+    totalRows: number;
+    totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
+    fileKey?: string | undefined;
+    fileSize?: number | undefined;
+    sheetKey?: string | undefined;
+}, {
+    acquisition: "continuation";
+    deadlineAt: number;
+    chunks: {
+        chunkNumber: number;
+        dataKey: string;
+    }[];
+    totalRows: number;
+    totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
+    fileKey?: string | undefined;
+    fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 }>;
 export declare function parseMatrixManifest(value: unknown, jobId: string, deadlineAt: number): {
     acquisition: "continuation";
@@ -190,6 +234,8 @@ export declare function parseMatrixManifest(value: unknown, jobId: string, deadl
     }[];
     totalRows: number;
     totalBytes: number;
+    format?: "csv" | "xlsx" | undefined;
     fileKey?: string | undefined;
     fileSize?: number | undefined;
+    sheetKey?: string | undefined;
 };

package/dist/types/shared/format-utils/matrix-export-presentation.d.ts

@@ -18,6 +18,20 @@ export declare function prepareMatrixExportPresentation(layout: MatrixExportLayo
     headers: string[];
     headerBands: string[][];
     numericColumns: boolean[];
+    /** The card's prepared formats this presentation formats with (the Excel form reads its measure formats). */
+    formatting: {
+        levels: Map<string, (value: import('../analytics-protocol/index.js').SemaphorScalarValue) => string>;
+        measures: Map<string, (value: import('../analytics-protocol/index.js').SemaphorScalarValue) => string>;
+        measureSemantics: Map<string, {
+            isNumeric: boolean;
+            hasTextAffixes: boolean;
+        }>;
+        measureFormats: Map<string, import('./types/index.js').MeasureCanonicalFormat>;
+        absence: {
+            emptyText: string;
+            nullText: string;
+        };
+    };
     /** A row's cells; after `previous`, a tabular layout prints each label once. */
     row: (data: MatrixExportRow, previous?: MatrixExportRow) => string[];
     /**
@@ -45,6 +59,12 @@ export declare function matrixFlatCsvHeaders(layout: MatrixExportLayout): string
  * CSV. Prepare `formatting` once per batch with `prepareMatrixFormatting`.
  */
 export declare function matrixFlatCsvRow(data: MatrixExportRow, layout: MatrixExportLayout, formatting: MatrixFormatting): string[];
+/**
+ * One Flat row's display text, unguarded: what the Excel form writes and the
+ * CSV form protects. Level values as the screen and Layout label members
+ * (`(Blank)` for a null member); measures through the card's formatter.
+ */
+export declare function matrixFlatRowText(data: MatrixExportRow, layout: MatrixExportLayout, formatting: MatrixFormatting): string[];
 /** Bounded physical projection only; values and totals have already been acquired. */
 export declare function buildMatrixTableStructure(input: {
     layout: MatrixExportLayout;
@@ -647,7 +667,7 @@ export declare function buildMatrixPrintTable(input: {
             } | undefined;
         };
         mode: "flat";
-        format: "csv";
+        format: "csv" | "xlsx";
         spec: {
             source: {
                 kind: "semantic";

package/dist/types/shared/format-utils/matrix-export-xlsx.d.ts

@@ -0,0 +1,27 @@
+import { MatrixExportLayout, MatrixExportRequest, MatrixExportRow } from '../analytics-protocol/index.js';
+import { ReportRuntimeContext } from '../report-runtime-context/index.js';
+import { XlsxRow, XlsxSheet } from './exporters/xlsx-file.js';
+import { MatrixFormatting } from './formatters/matrix-formatter.js';
+/** Prepared once per batch, like the CSV presentation it reads. */
+export declare function prepareMatrixXlsxPresentation(layout: MatrixExportLayout, request: MatrixExportRequest, report: ReportRuntimeContext): {
+    /** Header bands as header rows (XL-D16), with merges from identity (XL-D34). */
+    xlsxSheet: (input: {
+        title: string;
+        includeHeaders: boolean;
+    }) => XlsxSheet;
+    /** Every row label repeated; subtotal and grand-total rows are 'total' (bold). */
+    xlsxRows: (rows: readonly MatrixExportRow[]) => XlsxRow[];
+};
+/**
+ * The Flat form, prepared once per batch like the layout form: its columns
+ * (and their number formats) are built once, never per row.
+ */
+export declare function prepareMatrixFlatXlsxPresentation(layout: MatrixExportLayout, formatting: MatrixFormatting): {
+    /** One header row of the layout's column labels. */
+    xlsxSheet: (input: {
+        title: string;
+        includeHeaders: boolean;
+    }) => XlsxSheet;
+    /** Flat rows with the card's formats (MX-D10) and typed measure cells. */
+    xlsxRows: (rows: readonly MatrixExportRow[]) => XlsxRow[];
+};

package/dist/types/shared/format-utils/presentation-execution.d.ts

@@ -2,7 +2,7 @@ import { ResolvedRawTemporalFormat } from './raw-temporal.js';
 import { ReportRuntimeContext } from '../report-runtime-context/index.js';
 import { NumericPresentationTarget } from './numeric-presentation.js';
 import { ResolvedTemporalBucketFormat } from './temporal-bucket.js';
-import { DurationCanonicalFormat, MeasureCanonicalFormat, NumericCanonicalFormat } from './types/index.js';
+import { DateCanonicalFormat, DurationCanonicalFormat, MeasureCanonicalFormat, NumericCanonicalFormat } from './types/index.js';
 export type PresentationScope = {
     dashboardId: string;
     cardId?: string;
@@ -30,6 +30,22 @@ export type ResolvedDurationPresentationEntry = {
     target: NumericPresentationTarget;
     format: DurationCanonicalFormat;
 };
+/**
+ * A date presentation on a numeric (epoch milliseconds) column: a semantic
+ * date format the dashboard shows as a date (Excel exports plan XL-D27).
+ * Column targets only; `locale` is resolved at capture.
+ */
+export type ResolvedDatePresentationEntry = {
+    scope: PresentationScope;
+    target: {
+        kind: 'column';
+        columnKey: string;
+    };
+    format: ResolvedDateFormat;
+};
+export type ResolvedDateFormat = Pick<DateCanonicalFormat, 'type' | 'pattern' | 'timezone' | 'sourceTimezone'> & {
+    locale: string;
+};
 export type ResolvedTemporalBucketPresentationEntry = {
     scope: PresentationScope;
     target: TemporalBucketPresentationTarget;
@@ -44,7 +60,7 @@ export type ResolvedRawTemporalPresentationEntry = {
     target: RawTemporalPresentationTarget;
     format: ResolvedRawTemporalFormat;
 };
-export type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedDurationPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
+export type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedDurationPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry | ResolvedDatePresentationEntry;
 export type PresentationExecutionSnapshot = {
     version: 1;
     reportContext: ReportRuntimeContext;
@@ -82,6 +98,15 @@ export declare function findResolvedMeasureFormat(input: {
     scope: PresentationScope;
     target: NumericPresentationTarget;
 }): MeasureCanonicalFormat | undefined;
+/** The date presentation captured for an epoch column (XL-D27), if any. */
+export declare function findResolvedDateFormat(input: {
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
+    target: {
+        kind: 'column';
+        columnKey: string;
+    };
+}): ResolvedDateFormat | undefined;
 export declare function findResolvedRawTemporalFormat(input: {
     snapshot: PresentationExecutionSnapshot;
     scope: PresentationScope;

package/dist/types/shared/format-utils/raw-temporal.d.ts

@@ -1,3 +1,4 @@
+import { ExportWallClock } from './exporters/export-cells.js';
 import { CalendarContext } from '../report-runtime-context/report-runtime-context.js';
 import { RawTemporalValueKind, RawTemporalValueMetadata } from '../analytics-protocol/contracts.js';
 import { parseRawTemporalValueMetadata, validateRawTemporalResultColumn } from '../analytics-protocol/raw-temporal-contract.js';
@@ -31,6 +32,13 @@ export type RawTemporalFormatResult = {
     ok: true;
     text: string;
     status: 'formatted' | 'empty';
+    /**
+     * The calendar date and time `text` shows, with no zone: the same
+     * interpretation (date-only, wall clock, instant, source zone) that made
+     * the text. Present when `status` is 'formatted'. Excel exports write it
+     * as a date serial (Excel exports plan XL-D35).
+     */
+    wallClock?: ExportWallClock;
 } | {
     ok: false;
     text: string;

package/dist/types/shared/format-utils/table-export/index.d.ts

@@ -0,0 +1,8 @@
+export { prepareTableExport } from './prepare-table-export.js';
+export type { PreparedTableColumn, TableExportContent, TableExportFormatter, } from './prepare-table-export.js';
+export { parseTableExportFormatting, tableExportFormattingFromOptions } from './table-export-formatting.js';
+export type { TableExportFormatting } from './table-export-formatting.js';
+export type { TableExportResult, TableExportResultColumn } from './table-export-result.js';
+export { requiresRawTemporalSqlChunkEvidence } from './table-export-raw-temporal.js';
+export { TABLE_EXPORT_SHEET_SAMPLE_ROWS, defineTableExportSheet, tableExportXlsxRows, encodeTableExportWorkbook, tableExportSheetColumns, serializeTableExportSheetColumns, parseTableExportSheetColumns, tableExportJobSheet, } from './table-export-sheet.js';
+export type { TableExportSheetColumns } from './table-export-sheet.js';