react-semaphor 0.1.547 → 0.1.549

package/dist/surfboard/index.js

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

package/dist/types/components/surfboard/dashboard-plus.d.ts

@@ -3,5 +3,5 @@ type DashboardPlusProps = {
     showControls?: boolean;
     showFooter?: boolean;
 } & DashboardProps;
-export declare function DashboardPlus({ showControls, showFooter, ...rest }: DashboardPlusProps): import("react").JSX.Element;
+export declare function DashboardPlus({ showControls, showFooter, liveScreen, ...rest }: DashboardPlusProps): import("react").JSX.Element;
 export {};

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

@@ -194,11 +194,15 @@ export type DashboardFilterMappingDraftRow = DashboardFilterCardState & {
 export type DashboardFilterMappingRowTrigger = {
     kind: 'notApplied';
 }
-/** A field, with "Auto ·" or "Suggested ·" before it. */
+/**
+ * A field, with "Auto ·" or "Suggested ·" before it. `muted`: the field
+ * doesn't apply yet (a suggestion), so all of it reads quiet.
+ */
  | {
     kind: 'field';
     target: DashboardFilterFieldTarget;
     prefix?: 'Auto' | 'Suggested';
+    muted?: true;
 }
 /** A SQL card's Auto: the field it takes the value by. */
  | {
@@ -265,11 +269,22 @@ export type DashboardFilterMappingRowView = {
     state: DashboardFilterMappingRowState;
     /** The status column of the table review. */
     label: string;
-    tone: 'quiet' | 'review' | 'warning' | 'invalid';
-    /** How the row counts in the summary; none while its source or the server's answer is pending. */
-    count?: 'covered' | 'review' | 'excluded' | 'invalid';
-    /** Counted to review or invalid. */
+    /**
+     * Colour means something needs fixing (relationship filter reach R-31):
+     * `review` (amber) a field must be chosen before saving, `invalid` (red) a
+     * decision that no longer runs. Everything else is `quiet`, offers too.
+     */
+    tone: 'quiet' | 'review' | 'invalid';
+    /**
+     * How the row counts in the summary: applied, an open offer (a suggested
+     * field, a path to choose), not applied, a field to choose, or invalid;
+     * none while its source or the server's answer is pending.
+     */
+    count?: 'covered' | 'suggested' | 'pathChoice' | 'excluded' | 'needsChoice' | 'invalid';
+    /** Something breaks or blocks saving: a field to choose, or invalid. The Cards tab dot and the chip warning. */
     attention: boolean;
+    /** A suggested field the row offers to use in one click ("Use"). */
+    suggestion?: DashboardFilterFieldTarget;
     /** Accept is refused while the row stands: a decision that can't run, a field to choose, fields not loaded. */
     blocksAccept: boolean;
     /** A menu, or a control that only says why there is nothing to choose. */
@@ -337,9 +352,15 @@ export type DashboardFilterMappingAcceptance = {
 };
 export type DashboardFilterMappingStatusSummary = {
     coveredCount: number;
-    reviewCount: number;
+    /** Cards with a suggested field to use; they aren't filtered until it's used. */
+    suggestedCount: number;
+    /** Cards with equally preferred paths; they aren't filtered until one is chosen. */
+    pathChoiceCount: number;
     excludedCount: number;
+    /** Cards that need a field chosen before the mapping can be saved. */
+    needsChoiceCount: number;
     invalidCount: number;
+    /** What breaks or blocks saving (needs a field, invalid): the Cards tab dot and the chip warning. */
     attentionCount: number;
 };
 export type DashboardFilterMappingDraft = {
@@ -409,6 +430,21 @@ export type DashboardFilterMappingRequest = {
  * surface uses to decide whether the author needs to act.
  */
 export declare function summarizeDashboardFilterMappingRows(rows: DashboardFilterMappingDraftRow[]): DashboardFilterMappingStatusSummary;
+/**
+ * What breaks or blocks saving, in words, for the chip warning, the Cards
+ * tab dot and the popover footer (relationship filter reach R-31). Absent
+ * when nothing does.
+ */
+export declare function describeDashboardFilterMappingAttention(summary: DashboardFilterMappingStatusSummary): {
+    tone: 'invalid' | 'review';
+    text: string;
+} | undefined;
+/**
+ * Open offers, in words, for the popover footer: cards that aren't filtered
+ * until the author uses a suggestion or chooses a path. Information, not a
+ * warning (R-31). Absent when there are none.
+ */
+export declare function describeDashboardFilterMappingOffers(summary: DashboardFilterMappingStatusSummary): string | undefined;
 /**
  * One Cards row for a source-qualified value field that is not a toolbar
  * filter, such as a field a click carries. It is the same decision chain the

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

@@ -154,6 +154,13 @@ export type DashboardStore = {
      * replacement of the document but a proposal's own Undo, clears them.
      */
     appliedProposals: AppliedProposal[];
+    /**
+     * Advances each time an edit session ends: leaving edit mode (Cancel,
+     * close) or a successful Save that stays in edit mode. Save keeps the
+     * dashboard object (P7-27), so identity alone can't mark it; a live screen
+     * drops every kept copy here (embedded live changes LC-D14).
+     */
+    editSessionEpoch: number;
     /** The last toolbar Arrange, for its Undo. Cleared by any dashboard load, leaving edit mode, or a successful undo (responsive layouts SPEC §6.4). */
     lastArrange?: LastArrange;
     isVisualEditing: boolean;
@@ -420,6 +427,8 @@ type Actions = {
     removeFrame: (sheetId: string, frameId: string) => void;
     removeCard: (sheetId: string, card: TCard) => void;
     setIsDashboardEditing: (editing: boolean) => void;
+    /** The toolbar's Save succeeded: the edit session's changes are saved (LC-D14). */
+    markDashboardSaved: () => void;
     /**
      * Applies an assistant proposal to the dashboard on screen (spec 8.1,
      * D7-18, D7-27): only while the dashboard is still `basedOn`, checked and

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

@@ -15,6 +15,7 @@ import { DashboardAIContext } from './ai-context-types.js';
 import { CardInteractionConfig, InteractionTargetOverride } from './interaction-types.js';
 import { SemanticExecutionPayload } from './semantic-runtime-types.js';
 import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
+import { LiveScreenPort } from '../../shared/live-channel/index.js';
 import { CsvEncoding } from '../../shared/format-utils/exporters/csv-utils.js';
 import { PresentationExecutionSnapshot, TemporalInputPresentation } from '../../shared/format-utils/index.js';
 import { JSX } from 'react';
@@ -285,6 +286,12 @@ export type DashboardProps = {
     onEvent?: (event: TEvent) => void;
     /** Receives dashboard editing lifecycle transitions from the shared runtime. */
     onDashboardLifecycleEvent?: (event: DashboardLifecycleEvent) => void;
+    /**
+     * Makes this dashboard a live screen: an agent's changes arrive through the
+     * port and land unsaved, with Undo in a one-line note (embedded live changes
+     * LC-D31). Only Semaphor's embed page passes it.
+     */
+    liveScreen?: LiveScreenPort;
     onSave?: (dashboard: TDashboard) => void;
     onFilterValuesChange?: (filterValues: TFilterValue[]) => void;
     LoadingComponent?: (props: LoadingProps) => React.ReactNode;
@@ -1578,13 +1585,31 @@ export type TEvent = {
     type: 'success' | 'error' | 'info' | 'warning';
     message: any;
 };
-/** Supported lifecycle transitions emitted by an editable dashboard session. */
+/**
+ * Supported lifecycle transitions emitted by an editable dashboard session:
+ * its unsaved state, and an assistant's change applied on a live screen or
+ * undone from its note (embedded live changes LC-D13).
+ */
 export type DashboardLifecycleEvent = {
     type: 'dashboard:dirty-state';
     dashboardId: string;
     payload: {
         dirty: boolean;
     };
+} | {
+    type: 'dashboard:change-applied';
+    dashboardId: string;
+    payload: {
+        deliveryId: string;
+        summary: string[];
+    };
+} | {
+    type: 'dashboard:change-undone';
+    dashboardId: string;
+    payload: {
+        deliveryId: string;
+        summary: string[];
+    };
 };
 /**
  * Style for the dashboard

package/dist/types/live-channel.d.ts

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

package/dist/types/shared/assistant-protocol/parts.d.ts

@@ -82,12 +82,23 @@ export type AssistantStagePart = {
     stageId: string;
     label: string;
     state: 'live' | 'done' | 'skipped';
+    /**
+     * What kind of work the step does, for its icon: the server picks it with
+     * the label, from the same table. Absent on a step with no kind of its own
+     * and on turns stored before it.
+     */
+    activity?: AssistantStepActivity;
     /**
      * A step that changes the dashboard on screen (Phase 7): what the model
      * wrote before it is the answer, not a working note (P7-23, P7-45).
      */
     change?: true;
 };
+/**
+ * Finding what to use, reading it, running an analysis or SQL, changing the
+ * dashboard, or working out another way after a step failed.
+ */
+export type AssistantStepActivity = 'find' | 'read' | 'analyze' | 'sql' | 'change' | 'retry';
 /**
  * Where one answer's time and tokens went (spec 3.9, AG-D25). The server
  * sends it only to people who may see it (a development server, a super

package/dist/types/shared/dashboard-authoring/changes/dashboard-change.d.ts

@@ -7821,56 +7821,26 @@ export type ProposeChangeCaller = {
     generate: boolean;
     /** The SQL query form. */
     sql: boolean;
+    /**
+     * A session that changes the dashboard on the user's screen (a live token,
+     * Semaphor's own assistant): it changes only the open dashboard, in place,
+     * so `saveAs`, `preview` and `domainId` are not offered and, since the schema
+     * is strict, are refused if sent (embedded live changes LC-D17).
+     */
+    onScreen: boolean;
 };
 /**
  * The propose tool's input for one caller (DE-INV-7, design rule 5): only the
  * changes and query forms this caller may use. `shape` is what an MCP tool
- * registers; `schema` parses a call.
+ * registers; `schema` parses a call. This is the one place that decides what
+ * on-screen propose accepts (LC-D17).
  */
 export declare function buildProposeChangeInputSchema(caller: ProposeChangeCaller): {
-    shape: {
-        projectId: z.ZodOptional<z.ZodString>;
-        dashboardId: z.ZodOptional<z.ZodString>;
-        domainId: z.ZodOptional<z.ZodString>;
-        changes: z.ZodArray<z.ZodDiscriminatedUnion<"op", [z.ZodDiscriminatedUnionOption<"op">, ...z.ZodDiscriminatedUnionOption<"op">[]]>, "many">;
-        saveAs: z.ZodOptional<z.ZodEnum<["original", "copy"]>>;
-        preview: z.ZodOptional<z.ZodEnum<["sample", "rows", "none"]>>;
-        include: z.ZodOptional<z.ZodArray<z.ZodLiteral<"outline">, "many">>;
-        rationale: z.ZodOptional<z.ZodString>;
-    };
-    schema: z.ZodObject<{
-        projectId: z.ZodOptional<z.ZodString>;
-        dashboardId: z.ZodOptional<z.ZodString>;
-        domainId: z.ZodOptional<z.ZodString>;
-        changes: z.ZodArray<z.ZodDiscriminatedUnion<"op", [z.ZodDiscriminatedUnionOption<"op">, ...z.ZodDiscriminatedUnionOption<"op">[]]>, "many">;
-        saveAs: z.ZodOptional<z.ZodEnum<["original", "copy"]>>;
-        preview: z.ZodOptional<z.ZodEnum<["sample", "rows", "none"]>>;
-        include: z.ZodOptional<z.ZodArray<z.ZodLiteral<"outline">, "many">>;
-        rationale: z.ZodOptional<z.ZodString>;
-    }, "strict", z.ZodTypeAny, {
-        changes: {
-            [x: string]: any;
-            op?: unknown;
-        }[];
-        domainId?: string | undefined;
-        dashboardId?: string | undefined;
-        projectId?: string | undefined;
-        saveAs?: "original" | "copy" | undefined;
-        preview?: "rows" | "none" | "sample" | undefined;
-        include?: "outline"[] | undefined;
-        rationale?: string | undefined;
-    }, {
-        changes: {
-            [x: string]: any;
-            op?: unknown;
-        }[];
-        domainId?: string | undefined;
-        dashboardId?: string | undefined;
-        projectId?: string | undefined;
-        saveAs?: "original" | "copy" | undefined;
-        preview?: "rows" | "none" | "sample" | undefined;
-        include?: "outline"[] | undefined;
-        rationale?: string | undefined;
+    shape: z.ZodRawShape;
+    schema: z.ZodObject<z.ZodRawShape, "strict", z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
     }>;
 };
 export type ProposeChangeInput = {

package/dist/types/shared/live-channel/index.d.ts

@@ -0,0 +1 @@
+export * from './live-channel-contract.js';

package/dist/types/shared/live-channel/live-channel-contract.d.ts

@@ -0,0 +1,126 @@
+import { TDashboard } from '../../lib/types/common-types.js';
+import { DashboardOperation, OperationContext } from '../dashboard-authoring/operations/operation-types.js';
+/**
+ * The live channel's shared contract (embedded live changes LC-D30, SPEC.md
+ * section 2): what travels between Semaphor's server and a live screen (the
+ * embedded dashboard), what agents hear back, and every timing. Pure and
+ * server-safe; semaphor-app imports it as `react-semaphor/live-channel`, and
+ * nothing else in either repo declares these types (LC-INV-30).
+ *
+ * Every value crossing the wire is parsed by its validator on receipt, on
+ * both sides; a value that fails is dropped (an event) or refused 400 (a
+ * POST), never half-used (C-1).
+ */
+/** Always the first event on a connection. */
+export type ConnectedEvent = {
+    type: 'connected';
+    connectionId: string;
+};
+export type ScreenCopyRequest = {
+    type: 'copy_request';
+    requestId: string;
+    /** The dashboard the call asked for. */
+    dashboardId: string;
+};
+export type ScreenDelivery = {
+    type: 'delivery';
+    deliveryId: string;
+    /** The revision it was built on. */
+    revisionId: string;
+    proposalId: string;
+    operations: DashboardOperation[];
+    context: OperationContext;
+    /** Propose's summary sentences. */
+    summary: string[];
+    /** Positive; the screen never writes after receipt plus this. */
+    applyWithinMs: number;
+};
+export type LiveChannelEvent = ConnectedEvent | ScreenCopyRequest | ScreenDelivery;
+export type ScreenCopyAnswer = {
+    kind: 'uploaded';
+    screenId: string;
+    requestId: string;
+    revisionId: string;
+    dashboard: TDashboard;
+};
+export type ScreenOutcome = {
+    status: 'applied';
+} | {
+    status: 'not_applied';
+    reason: 'dashboard_changed' | 'not_editable' | 'refused' | 'expired';
+    message: string;
+};
+export type DeliveryOutcomeReport = {
+    screenId: string;
+    deliveryId: string;
+    outcome: ScreenOutcome;
+};
+/**
+ * A delivery ends when propose returns (plan revision 20): the screen's
+ * report, or `not_confirmed` when none came within the outcome wait. The
+ * dashboard on screen is the truth; the agent reads it again to see whether
+ * the change is there.
+ */
+export type DeliveryOutcome = ScreenOutcome | {
+    status: 'not_confirmed';
+};
+export type LiveDelivery = {
+    deliveryId: string;
+    outcome: DeliveryOutcome;
+};
+export type LiveScreenState = {
+    eligible: boolean;
+    dashboardId?: string;
+};
+/**
+ * What the embed page hands the dashboard (LC-D31): semaphor-app owns the
+ * transport behind it; react-semaphor's dashboard owns the screen state.
+ */
+export type LiveScreenPort = {
+    /** UUID v4, made once per page load. */
+    screenId: string;
+    setScreenState(state: LiveScreenState): void;
+    subscribe(listener: (event: ScreenCopyRequest | ScreenDelivery) => void): () => void;
+    /** Once, no retry: the server's wait is short. */
+    answerCopyRequest(answer: ScreenCopyAnswer): Promise<void>;
+    /** Once, no retry: a report that doesn't arrive is `not_confirmed`. */
+    reportOutcome(report: DeliveryOutcomeReport): Promise<void>;
+};
+export declare const LIVE_CHANNEL_TIMINGS: {
+    readonly heartbeatMs: 25000;
+    /** A screen's record expires this long after its last heartbeat: it is gone. */
+    readonly heartbeatExpiryMs: 75000;
+    readonly hiddenTabGraceMs: 120000;
+    /** Then the last value repeatedly. */
+    readonly reconnectBackoffMs: readonly [0, 1000, 2000, 5000];
+    /** One per call. */
+    readonly copyAnswerWaitMs: 3000;
+    readonly outcomeWaitMs: 8000;
+    /** applyWithinMs = the outcome wait less this. */
+    readonly applyMarginMs: 1000;
+    /** A copy answer or an outcome is kept this long past its call's wait. */
+    readonly replyRetentionMs: 30000;
+    /** Distinct screens; a sixth gets 429. */
+    readonly connectionsPerToken: 5;
+};
+/** The shape of the timings; tests pass shorter ones. */
+export type LiveChannelTimings = {
+    readonly [K in keyof typeof LIVE_CHANNEL_TIMINGS]: (typeof LIVE_CHANNEL_TIMINGS)[K] extends readonly number[] ? readonly number[] : number;
+};
+export type Parsed<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    problem: string;
+};
+/** A screen id: a UUID v4. */
+export declare function isScreenId(value: unknown): value is string;
+export declare function parseLiveChannelEvent(eventName: string, data: string): Parsed<LiveChannelEvent>;
+export declare function parseScreenCopyAnswer(body: unknown, query: {
+    screenId: string;
+    requestId: string;
+}): Parsed<ScreenCopyAnswer>;
+export declare function parseDeliveryOutcomeReport(body: unknown): Parsed<DeliveryOutcomeReport>;
+/** A screen's outcome, as reported and as stored. */
+export declare function parseScreenOutcome(value: unknown): ScreenOutcome | null;

package/package.json

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