react-semaphor 0.1.542 → 0.1.544

package/dist/surfboard/index.js

@@ -1,4 +1,4 @@
-import { a, R as s, D as o } from "../chunks/report-preferences-dialog-MRUWpMcJ.js";
+import { a, R as s, D as o } from "../chunks/report-preferences-dialog-Df7VpRVW.js";
 import { C as f, E as D } from "../chunks/table-settings-CLZocegs.js";
 export {
   f as CONTROL_CARD_DEFAULT_VALUE,

package/dist/types/activity.d.ts

@@ -0,0 +1,2 @@
+export * from './shared/activity/index.js'
+export {}

package/dist/types/components/activity/activity-bell.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+/**
+ * The bell is a button over the nearest Activity provider (background-activity
+ * BA-D9): the package toolbar, the app's navbar and the Briefings page header.
+ * The badge counts running work, or shows a dot for finished work not seen yet.
+ */
+export declare function ActivityBell({ variant }: {
+    variant?: 'outline' | 'ghost';
+}): React.JSX.Element;
+/** Every export and Briefing run the person started, running first (SPEC §2.5). Mounted only while open. */
+export declare function ActivityTray(): React.JSX.Element;

package/dist/types/components/activity/activity-instance.d.ts

@@ -0,0 +1,50 @@
+import { QueryClient, Query } from '@tanstack/react-query';
+import { StoreApi } from 'zustand/vanilla';
+import { ActivityApi, ActivityData, ActivityLocalState, ActivitySnapshot, UserToken } from './activity-types.js';
+/**
+ * One Activity instance per identity (background-activity SPEC §4.3, BA-D7):
+ * its own query client (passed to `useQuery`, never provided as context), its
+ * own local store, the watchers and the one clock. Everything that changes
+ * Activity state goes through here.
+ */
+/** The page's user token Activity lists and cancels with. */
+export type ActivityHost = UserToken;
+export type ActivityClock = {
+    /** The current time, for decisions. */
+    now(): number;
+    /** The time of the last tick, stable between ticks, for rendering. */
+    tick(): number;
+    subscribe(listener: () => void): () => void;
+};
+/** The only interval in Activity code: one 1 s tick while anything subscribes (BA-INV-7). */
+export declare function createActivityClock(): ActivityClock;
+export type ActivityState = {
+    data: ActivityData | undefined;
+    local: ActivityLocalState;
+};
+export type ActivityInstance = {
+    readonly identityKey: string;
+    readonly queryKey: readonly ['activity', string];
+    readonly queryClient: QueryClient;
+    readonly store: StoreApi<ActivityLocalState>;
+    readonly clock: ActivityClock;
+    readonly api: ActivityApi;
+    getHost(): ActivityHost | null;
+    /** Same identity, new token (refresh, navigation): history stays; the next request uses it. */
+    setHost(host: ActivityHost | null): void;
+    /** False once the server rejected this user token, until a new one arrives. */
+    canList(): boolean;
+    setViewBriefingRun(view: ActivityApi['viewBriefingRun']): void;
+    setOnSessionExpired(callback: (() => void) | null): void;
+    /** Ends every live attempt (identity change or provider unmount). */
+    dispose(): void;
+    /** Holds a watch while mounted; returns the release. */
+    watch(watchId: string): () => void;
+    isWatched(id: string): boolean;
+    subscribe(listener: () => void): () => void;
+    getState(): ActivityState;
+    snapshotOf(state: ActivityState): ActivitySnapshot;
+    fetchActivity(signal: AbortSignal): Promise<ActivityData>;
+    pollInterval(query: Query<ActivityData, Error, ActivityData, readonly ['activity', string]>): number | false;
+};
+export declare function createActivityInstance(identityKey: string, host: ActivityHost | null): ActivityInstance;

package/dist/types/components/activity/activity-notices.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The one completion message for work that finished while nobody watched it
+ * (background-activity BA-D8), rendered once per provider. A success notice
+ * hides after a few seconds by the Activity clock; a danger notice stays until
+ * dismissed. Never a toast (BA-INV-8).
+ */
+export declare function ActivityNotices(): import("react").JSX.Element | null;

package/dist/types/components/activity/activity-provider.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+import { AuthToken } from '../../lib/types/common-types.js';
+export declare function ActivityProvider({ children, authToken, onViewBriefingRun, }: {
+    children: ReactNode;
+    /** The page's user token, to list and cancel with. Null: Activity is inert. Omitted: read Surfboard's context. */
+    authToken?: AuthToken | null;
+    /** Opens a Briefing run where the host shows it (the app's run page). Omitted: Briefing rows offer no View. */
+    onViewBriefingRun?: (input: {
+        briefingId: string;
+        runId: string;
+    }) => void;
+}): import("react").JSX.Element;
+/**
+ * Reuses an outer provider of the same identity, so history is shared and one
+ * request lists it; otherwise mounts its own with `authToken` or Surfboard's
+ * context (an embed, a Briefing sheet outside the app).
+ */
+export declare function ActivityScope({ children, authToken }: {
+    children: ReactNode;
+    authToken?: AuthToken | null;
+}): import("react").JSX.Element;

package/dist/types/components/activity/activity-types.d.ts

@@ -0,0 +1,177 @@
+import { ActivityItem, ExportActivityItem } from '../../shared/activity/index.js';
+import { UserToken } from '../../lib/activity-identity.js';
+/**
+ * The Activity client's shapes (background-activity SPEC §2.5, §4.3, §4.5).
+ * Server items live in the instance's query cache as merged records; the
+ * local store holds presentation state only.
+ */
+export type { UserToken };
+/** Reads the page's user token fresh for each request; nothing holds a copy. */
+export type UserTokenReader = {
+    current(): UserToken | null;
+};
+/** One reconciled record per run; kept when a bounded response omits the run (BA-D15). */
+export type ActivityRecord = {
+    item: ActivityItem;
+    /** Observed running here, or started here; first-sight finals are false. */
+    seenRunning: boolean;
+    notified: boolean;
+    /** When a response last included it. */
+    lastConfirmedAt: number;
+};
+export type ActivityData = {
+    records: ReadonlyMap<string, ActivityRecord>;
+    /** From the last response, newest first. */
+    activeIds: readonly string[];
+    recentIds: readonly string[];
+    activeTruncated: boolean;
+};
+/**
+ * A browser-only export (a direct file or a PDF) while it runs or its dialog
+ * shows it (BA-D5). Never a tray row: the server does not know it. Finishing
+ * after its dialog's line was shown and closed raises the one notice and
+ * removes it; finishing before the line first shows it (a synchronous file)
+ * or while it shows it raises none, and the line shows the result.
+ */
+export type BrowserExport = {
+    /** 'browser:' + a random id; also the attempt's watch id. */
+    id: string;
+    title: string;
+    status: 'running' | 'ready' | 'failed' | 'cancelled';
+    /** 'starting' while a background start waits for the server's reply (M36). */
+    stage: 'preparing' | 'starting';
+    /** A line has watched it; until then the dialog that began it is about to show it. */
+    shown: boolean;
+    startedAt: string;
+    finishedAt: string | null;
+    failure: {
+        message: string;
+    } | null;
+    /** Rows and size of a finished file, for the line and the notice. */
+    details?: {
+        rows?: number;
+        fileSize?: number;
+    };
+};
+export type TrackInput = {
+    kind: 'export';
+    id: string;
+    exportRequestId: string;
+    title: string;
+    format: ExportActivityItem['format'];
+    deadlineAt: string | null;
+} | {
+    kind: 'briefing';
+    id: string;
+    title: string;
+    briefingId: string;
+};
+export type ActivityRowAction = 'download' | 'view' | 'cancel';
+export type ActivityNotice = {
+    id: string;
+    tone: 'success' | 'danger';
+    /** M25 or M26. */
+    title: string;
+    /** Rows and size, the failure message, or M31. */
+    body: string;
+    /** The run or browser export the notice is about; a run's action is derived from its row when shown. */
+    rowId: string;
+    shownAt: number;
+};
+export type ActivityLocalState = {
+    browser: ReadonlyMap<string, BrowserExport>;
+    /** Tracked or handed off, not yet in a response. */
+    pending: ReadonlyMap<string, TrackInput & {
+        trackedAt: number;
+    }>;
+    /** A handed-off browser export's watch id to its run id. */
+    aliases: ReadonlyMap<string, string>;
+    /** Known non-final ids the last response omitted. */
+    unresolved: ReadonlySet<string>;
+    /** Local give-up or missing (M17), with when it was decided. */
+    overrides: ReadonlyMap<string, {
+        message: string;
+        at: number;
+    }>;
+    cleared: ReadonlySet<string>;
+    notices: readonly ActivityNotice[];
+    lastSeenFinishedAt: number;
+};
+/** A tray row: work the server runs (an export job or a Briefing run). */
+export type ActivityRow = ActivityRecord;
+/** What a watch id shows where the work started: a browser-only export, or a run. */
+export type WatchedWork = {
+    kind: 'browser';
+    work: BrowserExport;
+} | {
+    kind: 'run';
+    row: ActivityRow;
+};
+export type ActivitySnapshot = {
+    /** Running first, then newest finishedAt; cleared rows excluded. */
+    rows: readonly ActivityRow[];
+    runningCount: number;
+    hasUnseenFinished: boolean;
+    /** Shows M34. */
+    activeTruncated: boolean;
+    notices: readonly ActivityNotice[];
+};
+/** A browser-only export's handle, for the code that runs it. */
+export type BrowserExportWork = {
+    id: string;
+    /** A background start was sent; the line reads "Starting..." until the server replies. */
+    starting(): void;
+    succeed(details?: {
+        rows?: number;
+        fileSize?: number;
+    }): void;
+    fail(message: string): void;
+    /** Stopped by the person: no notice. */
+    cancel(): void;
+    /** The server replied with a run: the run is tracked and this watch id follows it (the one identity transition, H-06). */
+    handOff(input: TrackInput): void;
+};
+export type ActivityApi = {
+    track(input: TrackInput): void;
+    begin(input: {
+        title: string;
+    }): BrowserExportWork;
+    clearFinished(): void;
+    dismissNotice(id: string): void;
+    /** Marks finished rows seen (the tray was opened). */
+    markSeen(): void;
+    /** Lists again now (the tray's refresh, which also lets a denied download sign again, M18). */
+    refresh(): void;
+    /** Call it inside the click: it opens the tab before signing. 'blocked': the browser blocked the tab (M37); 'denied': the link could not be signed (M18). */
+    download(id: string): Promise<'opened' | 'denied' | 'blocked'>;
+    /** Cancels a run with the page's user token. */
+    cancelExport(runId: string): Promise<void>;
+    /** Opens a Briefing run where the host shows it; null when nothing can. */
+    viewBriefingRun: ((input: {
+        briefingId: string;
+        runId: string;
+    }) => void) | null;
+    /** A surface that can open a Briefing run (the dashboard's Briefings sheet) offers itself while mounted; the host's page wins. */
+    registerBriefingViewer(view: (input: {
+        briefingId: string;
+        runId: string;
+    }) => void): () => void;
+    /** For an export attempt: the run row an id resolves to now (a handed-off watch id resolves to its run). */
+    row(id: string): ActivityRow | null;
+    /** For an export attempt: called on every Activity change. */
+    subscribe(listener: () => void): () => void;
+    /** The instance owns a live attempt: an identity change disposes it (SPEC §4.3). Returns the release. */
+    adopt(attempt: {
+        dispose(): void;
+    }): () => void;
+};
+export declare function isFinalStatus(status: ActivityItem['status'] | BrowserExport['status']): boolean;
+export declare function rowId(row: ActivityRow): string;
+/**
+ * The one action a row offers (SPEC §2.5): a ready export downloads, a
+ * Briefing run opens, a running export can be cancelled.
+ */
+export declare function activityRowAction(row: ActivityRow, options: {
+    canViewBriefing: boolean;
+}): ActivityRowAction | null;
+export type { ActivityItem, ExportActivityItem };

package/dist/types/components/activity/index.d.ts

@@ -0,0 +1,6 @@
+export { ActivityProvider, ActivityScope } from './activity-provider.js';
+export { useActivity, useWatchActivity, useActivityClock } from './use-activity.js';
+export { ActivityBell, ActivityTray } from './activity-bell.js';
+export { ActivityNotices } from './activity-notices.js';
+export { activityRowAction } from './activity-types.js';
+export type { ActivityApi, ActivityNotice, ActivityRecord, ActivityRow, ActivityRowAction, ActivitySnapshot, BrowserExport, BrowserExportWork, TrackInput, UserToken, UserTokenReader, WatchedWork, } from './activity-types.js';

package/dist/types/components/activity/use-activity.d.ts

@@ -0,0 +1,20 @@
+import { ActivityInstance } from './activity-instance.js';
+import { ActivityApi, ActivitySnapshot, WatchedWork } from './activity-types.js';
+/**
+ * Reading the nearest Activity instance (background-activity SPEC §4.3, §4.4).
+ * The provider and scope live in `activity-provider.tsx`.
+ */
+export declare const ActivityInstanceContext: import('react').Context<ActivityInstance | null>;
+export declare function useActivityInstance(): ActivityInstance | null;
+/** The nearest Activity: its actions and what it shows. Outside a provider: throws in development, inert in production. */
+export declare function useActivity(): ActivityApi & {
+    snapshot: ActivitySnapshot;
+};
+/**
+ * Holds the watch while mounted (BA-D10): watched work never notifies. The
+ * id shows its browser-only export, or the run it was handed off to.
+ * Watchers are keyed by the stable watch id, so a hand-off never moves a count.
+ */
+export declare function useWatchActivity(watchId: string | null): WatchedWork | null;
+/** The instance clock in ms, for elapsed times; one 1 s interval while anything subscribes. */
+export declare function useActivityClock(): number;

package/dist/types/components/briefings/briefing-author/run-model.d.ts

@@ -1,5 +1,5 @@
 import { BriefingDeliveryChannel, BriefingRecipient, BriefingRun } from '../../../lib/types/briefing-types.js';
-import { isActiveBriefingRunStatus, isTerminalBriefingRunStatus } from '../use-briefing-run-polling.js';
+import { isActiveBriefingRunStatus, isTerminalBriefingRunStatus } from '../use-briefing-run-detail.js';
 export declare const isTerminalRunStatus: typeof isTerminalBriefingRunStatus;
 export declare const isActiveRunStatus: typeof isActiveBriefingRunStatus;
 export declare function deliveryChannels(current: BriefingDeliveryChannel[], channel: BriefingDeliveryChannel, checked: boolean): BriefingDeliveryChannel[];
@@ -7,7 +7,6 @@ export declare function creatorEmailRecipient(currentUser: {
     email?: string | null;
     name?: string | null;
 } | null | undefined): BriefingRecipient | null;
-export declare function useElapsedSeconds(startedAt: string | null | undefined): number | null;
 export declare function formatElapsed(seconds: number): string;
 export type EmailPreviewRecipient = {
     label: string;

package/dist/types/components/briefings/briefing-author.d.ts

@@ -2,8 +2,7 @@ import { cancelBriefingPreviewRun, cancelBriefingRun, createBriefing, deleteBrie
 import { BriefingAttachment, BriefingDetail, BriefingRun, RunBriefingNowResponse } from '../../lib/types/briefing-types.js';
 import { TDashboard } from '../../lib/types/common-types.js';
 import { BriefingAuthorIntent, BriefingAuthorSourceContext } from './briefing-author/policy.js';
-export { formatElapsed, useElapsedSeconds } from './briefing-author/run-model.js';
-export { BackgroundRunPill, RunCompletionBanner } from './briefing-author/run-ui.js';
+export { formatElapsed } from './briefing-author/run-model.js';
 export type BriefingAuthorClient = {
     createBriefing: typeof createBriefing;
     updateBriefing: typeof updateBriefing;
@@ -28,6 +27,8 @@ export type BriefingAuthorProps = {
     briefing?: BriefingDetail | null;
     intent?: BriefingAuthorIntent;
     initialAttachments?: BriefingAttachment[];
+    /** Opens the sheet at this saved run (Activity's View), whatever its status; otherwise the latest active run. */
+    initialRunId?: string;
     initialName?: string;
     initialMessage?: string;
     initialTimezone?: string;
@@ -47,15 +48,11 @@ export type BriefingAuthorProps = {
     onRunStarted?: (response: RunBriefingNowResponse) => void;
     onCancel?: () => void;
     /**
-     * Fires when the user clicks "Run in background" on the active-run sticky
-     * strip. The parent is expected to track the run, render a persistent
-     * background-run UI (pill + completion banner), and close any modal/sheet
-     * that hosts the author so the user can navigate freely while the run
-     * continues server-side.
-     *
-     * Only ever called for *saved* runs — preview runs are short-lived
-     * synthetic things with no notification path, so the sticky bar hides
-     * the CTA in that case.
+     * Fires when the user clicks "Run in background" on the active-run strip:
+     * the parent closes the sheet. Activity already follows the run (it was
+     * tracked when it started) and shows one notice when it finishes
+     * (background-activity BA-D1, BA-D20). Saved runs only: previews never
+     * enter Activity.
      */
     onMinimizeRun?: (input: {
         briefing: BriefingDetail;
@@ -69,4 +66,9 @@ export type BriefingAuthorProps = {
      */
     onBack?: () => void;
 };
-export declare function BriefingAuthor({ apiServiceUrl, token, briefing, intent, initialAttachments, initialName, initialMessage, initialTimezone, availableDashboards, sourceContext, title, hideHeader, className, client, generateRequestId, onSaved, onDeleted, onRunStarted, onCancel, onBack, onMinimizeRun, }: BriefingAuthorProps): import("react").JSX.Element;
+/**
+ * The Briefing sheet inside Activity (background-activity BA-D19): it reuses
+ * the host's provider of the same identity, or lists with the token it was
+ * given when it stands alone.
+ */
+export declare function BriefingAuthor(props: BriefingAuthorProps): import("react").JSX.Element;

package/dist/types/components/briefings/dashboard-briefing-launcher.d.ts

@@ -12,6 +12,11 @@ export type DashboardBriefingLauncherProps = {
     onOpenChange?: (open: boolean) => void;
     hideTrigger?: boolean;
     workflowIntent?: BriefingAuthorIntent;
+    /** Opens this run's Briefing at the run (Activity's View, in a host without a run page). */
+    openRun?: {
+        briefingId: string;
+        runId: string;
+    };
     client?: Partial<DashboardBriefingLauncherClient>;
 };
 export type DashboardBriefingLauncherClient = {

package/dist/types/components/briefings/use-briefing-run-detail.d.ts

@@ -0,0 +1,34 @@
+import { BriefingPreviewRun, BriefingRun } from '../../lib/types/briefing-types.js';
+/**
+ * The Briefing panel reads its own run (background-activity BA-D20, SPEC
+ * §4.6): every 2 s while the panel is open and the run is active, whoever
+ * started it (a person's Run now, a schedule, a teammate's run). Activity
+ * lists the runs a person started for the tray; the two never coordinate.
+ * The server expires a stale run when it is read, so a saved run has no
+ * client timeout; a preview polls for at most `PREVIEW_RUN_POLL_TIMEOUT_MS`.
+ * The sheet that shows a run holds its Activity watch (it outlives this
+ * hook's target, which clears when the run is final).
+ */
+export declare const BRIEFING_RUN_POLL_INTERVAL_MS = 2000;
+export declare const PREVIEW_RUN_POLL_TIMEOUT_MS: number;
+export type BriefingRunDetailTarget = {
+    kind: 'saved';
+    briefingId: string;
+    runId: string;
+} | {
+    kind: 'preview';
+    previewRunId: string;
+};
+export type BriefingRunDetailStatus = 'idle' | 'loading' | 'active' | 'final' | 'timed_out' | 'error';
+export declare function isActiveBriefingRunStatus(status: string | undefined): boolean;
+export declare function isTerminalBriefingRunStatus(status: string | undefined): boolean;
+export declare function useBriefingRunDetail<Run extends BriefingRun | BriefingPreviewRun>(input: {
+    run: BriefingRunDetailTarget | null;
+    /** The sheet's own fetchers (its API client), read on every fetch. */
+    fetchSaved: (briefingId: string, runId: string) => Promise<BriefingRun>;
+    fetchPreview: (previewRunId: string) => Promise<BriefingPreviewRun>;
+}): {
+    run: Run | null;
+    status: BriefingRunDetailStatus;
+    error: unknown;
+};

package/dist/types/components/index.d.ts

@@ -58,10 +58,7 @@ export { useCardSummary } from '../lib/hooks/use-card-summary.js';
 export type { SummaryResponse } from '../lib/types/summary-types.js';
 export { useDataColumns, useAddNewFrame } from '../lib/hooks/index.js';
 export { useExposePrintState, type PrintState, } from '../lib/print-state/use-expose-print-state.js';
-export { NotificationBell, ExportNotificationList, ExportNotificationItem, } from './notifications/index.js';
-export { useExportStore, useExportActions, useActiveExports, useInProgressExportsCount, type ActiveExport, } from '../lib/stores/export-store.js';
-export { useExportPolling } from '../lib/hooks/use-export-polling.js';
-export { useExportRecovery } from '../lib/hooks/use-export-recovery.js';
+export { ActivityProvider, ActivityScope, ActivityBell, useActivity, type ActivityApi, type ActivitySnapshot, } from './activity/index.js';
 export { DashboardControlsSettings } from './surfboard/controls/dashboard-controls-settings.js';
 export { DocumentControlsSettings } from './document-sheet/document-controls-settings.js';
 export { DashboardFilterControlsButton } from './surfboard/controls/dashboard-filter-controls-button.js';

package/dist/types/lib/activity-identity.d.ts

@@ -0,0 +1,21 @@
+import { AuthToken } from './types/common-types.js';
+/**
+ * Whose Activity history, and the page's user token as a request sends it
+ * (background-activity SPEC §4.2, §4.3). History follows the identity, so
+ * moving between a dashboard and the Briefings page keeps it. The browser
+ * trusts the token: the server decides what each request may do.
+ */
+/** The page's user token, as a request sends it (SPEC §4.2). */
+export type UserToken = {
+    token: string;
+    apiServiceUrl: string;
+};
+/** A decoded token: the typed `TokenProps` claims plus any the issuer adds. */
+type Claims = Record<string, unknown>;
+/** The identity the server lists by. Navigation, token type and presentation do not change it. */
+export declare function activityIdentityKey(token: Claims): string;
+/** The token's claims; empty when there is no token or it cannot be read. */
+export declare function decodeActivityToken(authToken: AuthToken | null | undefined): Claims;
+/** The one way the browser reads the user token for a request: the token and the server it names. */
+export declare function userTokenFrom(authToken: AuthToken | null | undefined): UserToken | null;
+export {};

package/dist/types/lib/api/exports-api.d.ts

@@ -10,9 +10,9 @@ export interface CreateExportResponse {
     totalChunks: number | null;
     chunkSize: number;
     estimatedRows: number | null;
-    wasTruncated?: boolean;
-    originalRows?: number;
-    maxRows?: number;
+    /** False when the server returned the run an earlier start of this export made (BA-D17). */
+    created?: boolean;
+    deadlineAt?: string | null;
 }
 export type CardExportRequest = CreateExportRequest | MatrixFileExportRequest;
 /** Export job status response */
@@ -85,7 +85,7 @@ export type MatrixDirectExportResult = {
  * the response's content type. Errors carry the server's catalog reason in
  * `details.message` (an Excel limit answers 422 `excel_limit`).
  */
-export declare function createMatrixDirectExport(apiServiceUrl: string, token: string, params: MatrixFileExportRequest): Promise<MatrixDirectExportResult>;
+export declare function createMatrixDirectExport(apiServiceUrl: string, token: string, params: MatrixFileExportRequest, signal?: AbortSignal): Promise<MatrixDirectExportResult>;
 /**
  * Get list of user's exports
  */

package/dist/types/lib/hooks/index.d.ts

@@ -6,8 +6,6 @@ import { useDebounce } from './use-debounce.js';
 import { useDebouncedEditorValue } from './use-debounced-editor-value.js';
 import { useClickOutside } from './use-click-outside.js';
 import { useStableValue, rowsEqual } from './use-stable-value.js';
-import { useExportPolling } from './use-export-polling.js';
-import { useExportRecovery } from './use-export-recovery.js';
 import { useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart } from './use-calendar-context.js';
 import { useValueFormatPreferences } from './use-value-format-preferences.js';
-export { useDashboard, useCard, useDataColumns, useAddNewFrame, useDebounce, useDebouncedEditorValue, useClickOutside, useStableValue, rowsEqual, useExportPolling, useExportRecovery, useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart, useValueFormatPreferences, };
+export { useDashboard, useCard, useDataColumns, useAddNewFrame, useDebounce, useDebouncedEditorValue, useClickOutside, useStableValue, rowsEqual, useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart, useValueFormatPreferences, };

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

@@ -758,4 +758,8 @@ export declare function buildMatrixDeliveryPayload(input: {
 /** A Matrix data file request (CSV or Excel) for the direct path or a job. */
 export type MatrixFileExportRequest = ReturnType<typeof buildMatrixDeliveryPayload> & {
     format: ExportFileFormat;
+    /** One logical export (BA-D17): the direct attempt, its fallback and Run in background share it. */
+    exportRequestId: string;
+    /** 'background' skips the direct attempt (Run in background, BA-D11). */
+    delivery?: 'direct' | 'background';
 };

package/dist/types/shared/activity/activity-contract.d.ts

@@ -0,0 +1,84 @@
+import { ExportFileFormat } from '../format-utils/exporters/export-file-format.js';
+/**
+ * The Activity contract (background-activity SPEC §2.2): what
+ * `GET /api/v1/activity` answers about a person's exports and Briefing runs.
+ * React-free; the app builds it and the client reads it with
+ * `parseActivityListResponse`. It never carries a token, lease, file key,
+ * signed URL, config, filter, SQL or free-text error.
+ */
+export declare const ACTIVITY_STATUSES: readonly ["running", "ready", "failed", "cancelled"];
+export type ActivityStatus = (typeof ACTIVITY_STATUSES)[number];
+/** Where a running export is, from signals the server already has (MX-D17). */
+export type ExportActivityStage = {
+    kind: 'queued';
+} | {
+    kind: 'preparing';
+} | {
+    kind: 'fetching';
+    rowsProcessed: number;
+} | {
+    kind: 'processing';
+    percent: number | null;
+} | {
+    kind: 'finalizing';
+};
+/** `message` is catalog text; no free-text server error crosses this contract. */
+export type ActivityFailure = {
+    kind: 'export';
+    reason: string;
+    message: string;
+} | {
+    kind: 'briefing';
+};
+type ActivityItemBase = {
+    /** The AutomationRun id. */
+    id: string;
+    title: string;
+    status: ActivityStatus;
+    /** ISO timestamps. */
+    startedAt: string;
+    finishedAt: string | null;
+    failure: ActivityFailure | null;
+};
+export type ExportActivityItem = ActivityItemBase & {
+    kind: 'export';
+    /** The run's requestId: the client's id of the logical export (BA-D17). */
+    exportRequestId: string;
+    format: ExportFileFormat;
+    stage: ExportActivityStage | null;
+    totalRows: number | null;
+    fileSize: number | null;
+    /** When the server stops the export; the client gives up a grace period later (MX-D9). */
+    deadlineAt: string | null;
+};
+export type BriefingActivityItem = ActivityItemBase & {
+    kind: 'briefing';
+    briefingId: string;
+    /** The run's progress label while running, as the sheet shows it. */
+    stageLabel: string | null;
+    omittedAttachmentCount: number;
+};
+export type ActivityItem = ExportActivityItem | BriefingActivityItem;
+export type ActivityListRequest = {
+    /** Known runs the previous responses omitted; answered explicitly (BA-D15). */
+    resolve: readonly string[];
+};
+export type ActivityListResponse = {
+    /** Every running item the person started, newest first, up to ACTIVITY_ACTIVE_LIMIT. */
+    active: ActivityItem[];
+    activeTruncated: boolean;
+    /** Finished items from the last ACTIVITY_RECENT_WINDOW_MS, newest finishedAt first. */
+    recent: ActivityItem[];
+    /** Each `resolve` id the person owns that is in neither list, whatever its age or status. */
+    resolved: ActivityItem[];
+    /** Each `resolve` id that does not exist or is not the person's: the only proof of "missing". */
+    missing: string[];
+};
+export declare const ACTIVITY_ACTIVE_LIMIT = 100;
+export declare const ACTIVITY_RECENT_LIMIT = 50;
+export declare const ACTIVITY_RECENT_WINDOW_MS: number;
+/** The most `resolve` ids one request names. */
+export declare const ACTIVITY_RESOLVE_LIMIT = 20;
+/** Parses a response; throws on a shape it does not recognize (the client never guesses). */
+export declare function parseActivityListResponse(value: unknown): ActivityListResponse;
+export {};

package/dist/types/shared/activity/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `react-semaphor/activity`: the Activity contract (background-activity SPEC
+ * §2.2). Server-safe: no React, store or component module.
+ */
+export * from './activity-contract.js';

package/dist/types/shared/dashboard-authoring/card-export-request.d.ts

@@ -56,6 +56,12 @@ export interface CreateExportRequest {
     /** The file the job writes: CSV, or Excel for Table and Detail Table. */
     format: ExportFileFormat;
     formatOptions: AuthoritativeExportFormattingConfig;
+    /**
+     * One logical export (background-activity BA-D17): every start of the same
+     * export sends the same id, so the server returns one run. Required by
+     * POST /api/v1/exports; a server-started attachment has none.
+     */
+    exportRequestId?: string;
 }
 /** The facts a result gives an export: a viewer's loaded result, or the server's sizing query. */
 export type CardResultFacts = {

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

@@ -17,3 +17,15 @@ export declare const MATRIX_EXPORT_MAX_ENCODED_BYTES: number;
 export declare const MATRIX_EXPORT_MAX_ARTIFACT_BYTES: number;
 /** Return true when a complete CSV must use the asynchronous chunked path. */
 export declare function requiresChunkedCsvExport(totalRows: number): boolean;
+/** Where a data export (CSV or Excel) runs (background-activity BA-D2, SPEC §4.1). */
+export type DataExportRoute = 'direct' | 'background' | 'try-direct' | 'blocked';
+/**
+ * The one route rule for data exports in CSV and Excel (they share every
+ * limit): a Matrix tries the direct path first; a table routes on its loaded
+ * row count. The loaded count only routes; the server sizes the job (BA-D3).
+ */
+export declare function dataExportRoute(input: {
+    cardType: 'table' | 'detailTable' | 'matrixTable';
+    /** The loaded row count of a server-paged table, else null. */
+    loadedRowCount: number | null;
+}): DataExportRoute;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.542",
+  "version": "0.1.544",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -88,6 +88,10 @@
       "types": "./dist/types/brand-studio.d.ts",
       "import": "./dist/brand-studio/index.js"
     },
+    "./activity": {
+      "types": "./dist/types/activity.d.ts",
+      "import": "./dist/activity/index.js"
+    },
     "./briefings": {
       "types": "./dist/types/briefings.d.ts",
       "import": "./dist/briefings/index.js"