react-semaphor 0.1.548 → 0.1.550

package/dist/surfboard/index.js

@@ -1,4 +1,4 @@
-import { a, R as s, D as o } from "../chunks/report-preferences-dialog-CM7kXmXp.js";
+import { a, R as s, D as o } from "../chunks/report-preferences-dialog-D_fEDaS4.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/assistant/assistant-entry-points.d.ts

@@ -3,7 +3,10 @@ import { AssistantLayout } from '../../shared/assistant-protocol/conversation.js
 export type AssistantPanelSurface = 'dashboard' | 'none';
 /** Where the panel shows now: the viewer's layout, or beside the asked-about card (Phase 10, D10-1). */
 export type AssistantPlacement = AssistantLayout | 'beside-card';
-/** Opens and closes the panel. Named after the assistant; no other wording. */
+/**
+ * Opens and closes the panel. Named after the assistant; no other wording.
+ * Below a wide toolbar it keeps its place as an icon (responsive toolbars).
+ */
 export declare function AssistantToolbarButton(): import("react").JSX.Element | null;
 /**
  * The panel. Beside a dashboard (`surface="dashboard"`), the chat mounts on

package/dist/types/components/dashboard/favorites/dashboard-favorite-toggle.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The open dashboard's favorite star for a toolbar (dashboard favorites,
+ * FAV-D14, FAV-D17). Access and the server's `isFavorite` come from the
+ * dashboard's viewer state; this viewer's own writes win over it (the
+ * favorites store, ledger R-05). Nothing for a session that saves nothing (no
+ * person in the token, or a PDF render), a read-only star while signed in as
+ * someone else. Mounted in this package's toolbar and in the app's own toolbar.
+ */
+export declare function DashboardFavoriteToggle({ dashboardId }: {
+    dashboardId: string;
+}): import("react").JSX.Element | null;

package/dist/types/components/dashboard/favorites/favorite-star-button.d.ts

@@ -0,0 +1,16 @@
+/** Shown on a read-only star: the session is signed in as someone else (FAV-D3). */
+export declare const FAVORITES_READ_ONLY_MESSAGE = "Favorites can't be changed while you're signed in as someone else.";
+/**
+ * The one favorite star (dashboard favorites, FAV-D13): monochrome, an outline
+ * in muted ink when off, filled with foreground ink when on. On rows it shows
+ * on hover or keyboard focus and stays visible once on.
+ */
+export declare function FavoriteStarButton({ isFavorite, onToggle, readOnly, pending, variant, className, }: {
+    isFavorite: boolean;
+    onToggle: () => void;
+    readOnly?: boolean;
+    pending?: boolean;
+    /** `row`: hub and list rows, revealed on hover. `toolbar`: always shown. */
+    variant?: 'row' | 'toolbar';
+    className?: string;
+}): import("react").JSX.Element;

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

@@ -37,6 +37,14 @@ export { AssistantProvider } from './assistant/assistant-provider.js';
 export { AssistantPanel, AssistantToolbarButton } from './assistant/assistant-entry-points.js';
 export { ArrangeLayoutButton } from './surfboard/arrange-layout-button.js';
 export { ScreenSizePreviewButton } from './surfboard/screen-size-preview-button.js';
+export { DashboardFavoriteToggle } from './dashboard/favorites/dashboard-favorite-toggle.js';
+export { FavoriteStarButton, FAVORITES_READ_ONLY_MESSAGE, } from './dashboard/favorites/favorite-star-button.js';
+export { ToolbarOverflowAnchorSlot, ToolbarProvider } from './surfboard/toolbar/toolbar-overflow.js';
+export { TOOLBAR_LG_MIN, TOOLBAR_MD_MIN, fitsToolbar, toolbarWidthFor, useMeasuredToolbarWidth, useToolbarItem, useToolbarOverflowItems, useToolbarWidth, } from './surfboard/toolbar/toolbar-context.js';
+export type { ToolbarOverflowItem, ToolbarTier, ToolbarWidth, } from './surfboard/toolbar/toolbar-context.js';
+export { useDefaultDashboardToggle } from '../lib/hooks/use-default-dashboard-toggle.js';
+export { useDashboardFavorite } from '../lib/hooks/use-dashboard-favorite.js';
+export type { DashboardFavorites } from '../lib/hooks/use-dashboard-favorite.js';
 export type { AssistantPanelSurface } from './assistant/assistant-entry-points.js';
 export { useAssistant } from './assistant/use-assistant.js';
 export * from '../lib/types/common-types.js';

package/dist/types/components/sharing-and-management/hooks/use-resource-management.d.ts

@@ -1,6 +1,7 @@
 import { ResourceType, ShareRole, ShareScope } from '../utils/types.js';
 import { TDashboard, TFrame } from '../../../lib/types/index.js';
 import { AppearanceSpec } from '../../../lib/appearance/index.js';
+import { DashboardListViewer } from '../../../shared/dashboard-viewer/index.js';
 export interface ResourceListItem {
     id: string;
     title: string;
@@ -38,6 +39,9 @@ export interface ResourceListItem {
             email: string;
         };
     };
+    /** Dashboard lists only (dashboard favorites, FAV-D5); absent from older servers, read as false. */
+    isFavorite?: boolean;
+    favoritedAt?: string | null;
 }
 export interface CreateResourceRequest {
     title: string;
@@ -115,6 +119,10 @@ export declare function useResourceUpdateState(): {
 export declare function useResourceManagement(resourceType: ResourceType, onDeleteSuccess?: () => void, onCreateSuccess?: (data?: any) => void): {
     resources: any;
     organizationAppearance: AppearanceSpec | null;
+    /** When the list arrived (client clock, ms); favorites resolve against it (FAV-D20). */
+    listFetchedAt: number;
+    /** Dashboard lists: whether this session can change favorites (FAV-D18). */
+    listViewer: DashboardListViewer | null;
     isLoading: boolean;
     isError: boolean;
     isFetching: boolean;
@@ -152,6 +160,10 @@ export declare function useResourceManagement(resourceType: ResourceType, onDele
 export declare function useDashboardManagement(onDeleteSuccess?: () => void, onCreateSuccess?: (data?: any) => void): {
     resources: any;
     organizationAppearance: AppearanceSpec | null;
+    /** When the list arrived (client clock, ms); favorites resolve against it (FAV-D20). */
+    listFetchedAt: number;
+    /** Dashboard lists: whether this session can change favorites (FAV-D18). */
+    listViewer: DashboardListViewer | null;
     isLoading: boolean;
     isError: boolean;
     isFetching: boolean;
@@ -189,6 +201,10 @@ export declare function useDashboardManagement(onDeleteSuccess?: () => void, onC
 export declare function useVisualManagement(onDeleteSuccess?: () => void, onCreateSuccess?: (data?: any) => void): {
     resources: any;
     organizationAppearance: AppearanceSpec | null;
+    /** When the list arrived (client clock, ms); favorites resolve against it (FAV-D20). */
+    listFetchedAt: number;
+    /** Dashboard lists: whether this session can change favorites (FAV-D18). */
+    listViewer: DashboardListViewer | null;
     isLoading: boolean;
     isError: boolean;
     isFetching: boolean;

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/components/surfboard/toolbar/toolbar-context.d.ts

@@ -0,0 +1,86 @@
+import { ReactNode } from 'react';
+/**
+ * Responsive dashboard toolbars (design: semaphor-app `/design/responsive-toolbars`).
+ *
+ * Both toolbars, this package's and the app's navbar, follow one rule set. A
+ * toolbar measures its own width (an embed lives in a host column of any
+ * size, so the viewport says nothing). Every item has a tier: `always`, `md`
+ * (shown from 640px of toolbar) or `lg` (from 960px). As the toolbar narrows,
+ * labels collapse to icons first, then an item below its tier stops rendering
+ * its button and registers its menu form here, which the toolbar's existing
+ * ⋯ menu renders in toolbar order. A `menu` item lives in ⋯ at every width.
+ * Editing controls cannot move, so their group scrolls when it still does not
+ * fit, and ⋯ stays in view.
+ *
+ * Outside a toolbar (for example the Activity bell on the Briefings page) the
+ * context reads as `lg` with no menu, so every control renders as before.
+ */
+export type ToolbarWidth = 'sm' | 'md' | 'lg';
+export type ToolbarTier = 'always' | 'md' | 'lg' | 'menu';
+/** Toolbar widths (px) where the `md` and `lg` tiers start. */
+export declare const TOOLBAR_MD_MIN = 640;
+export declare const TOOLBAR_LG_MIN = 960;
+export declare function toolbarWidthFor(px: number): ToolbarWidth;
+/** Whether an item of `tier` shows its button at `width`. */
+export declare function fitsToolbar(tier: ToolbarTier, width: ToolbarWidth): boolean;
+/** The menu form an item registers while its button does not fit. */
+export type ToolbarOverflowItem = {
+    readonly id: string;
+    readonly label: string;
+    readonly icon?: ReactNode;
+    /** A short right-aligned note: a count, a current value. */
+    readonly hint?: string;
+    /** Shown as a check, for a toggle. */
+    readonly checked?: boolean;
+    /** Toolbar order, so the menu lists moved items as the toolbar did. */
+    readonly order: number;
+    readonly onSelect: () => void;
+};
+export type ToolbarContextValue = {
+    readonly width: ToolbarWidth;
+    /** Inside a toolbar that has a ⋯ menu for moved items. */
+    readonly hasOverflowMenu: boolean;
+    readonly overflowItems: readonly ToolbarOverflowItem[];
+    register(item: ToolbarOverflowItem): () => void;
+    /** Which moved control's popover is open from the menu. */
+    readonly openOverflowId: string | null;
+    setOpenOverflowId(id: string | null): void;
+    /** Beside the ⋯ button: where a moved control anchors its popover. */
+    readonly anchorSlot: HTMLElement | null;
+    setAnchorSlot(element: HTMLElement | null): void;
+};
+export declare const ToolbarContext: import('react').Context<ToolbarContextValue>;
+/**
+ * Measures an element's width: pass `measure` as the element's `ref`. Starts
+ * at `lg` so a wide first paint never jumps.
+ */
+export declare function useMeasuredToolbarWidth<T extends HTMLElement>(): {
+    measure: (element: T | null) => void;
+    width: ToolbarWidth;
+};
+/** The toolbar's width (`lg` outside a toolbar). */
+export declare function useToolbarWidth(): ToolbarWidth;
+/** The moved items, for a toolbar's ⋯ menu. */
+export declare function useToolbarOverflowItems(): readonly ToolbarOverflowItem[];
+/**
+ * One toolbar item. `collapsed` means it should not render its button. While
+ * collapsed and `menu` is given, its menu form is registered. Popover controls
+ * use `popoverOpen` and `setPopoverOpen`: from the menu they open anchored at
+ * the ⋯ menu, which is where the item now lives.
+ */
+export declare function useToolbarItem(id: string, tier: ToolbarTier, menu?: Omit<ToolbarOverflowItem, 'id' | 'onSelect'> & {
+    /** Defaults to opening the item's popover from the menu. */
+    readonly onSelect?: () => void;
+    /**
+     * Runs when the menu opens the item's popover. Radix calls `onOpenChange`
+     * only for its own trigger, not when the `open` prop changes, so work a
+     * control does on open (Activity marks finished work seen) goes here too.
+     */
+    readonly onOpen?: () => void;
+}): {
+    collapsed: boolean;
+    popoverOpen: boolean;
+    setPopoverOpen(open: boolean): void;
+    /** Where to portal a collapsed popover's anchor (`null` outside a toolbar). */
+    anchorSlot: HTMLElement | null;
+};

package/dist/types/components/surfboard/toolbar/toolbar-overflow.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { ToolbarWidth } from './toolbar-context.js';
+/** Wraps one toolbar: its width, and the moved items its ⋯ menu renders. */
+export declare function ToolbarProvider({ width, hasOverflowMenu, children, }: {
+    width: ToolbarWidth;
+    /** False while the toolbar shows no ⋯ menu: then nothing moves into one. */
+    hasOverflowMenu?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Place right before the toolbar's ⋯ button: a moved control's popover
+ * anchors here, so it opens under the menu it was chosen from.
+ */
+export declare function ToolbarOverflowAnchorSlot(): import("react").JSX.Element;

package/dist/types/lib/dashboard-viewer/viewer-store-state.d.ts

@@ -18,6 +18,13 @@ export type DashboardViewerState = {
     /** Live table settings per card. Never written into `card.config` or `tablePrefs`. */
     readonly tableSettings: Readonly<Record<string, ViewerTableSettings>>;
     readonly notices: readonly ViewerNotice[];
+    /**
+     * The server's answer from the dashboard's viewer payload (FAV-D17). Read
+     * through the favorites store, where this viewer's later writes win.
+     */
+    readonly isFavorite: boolean;
+    /** When the dashboard response this state came from arrived (client clock, ms; 0 when unknown). */
+    readonly fetchedAt: number;
 };
 /** Session-only until the dashboard load says otherwise (TECH-SPEC 7). */
 export declare const INITIAL_DASHBOARD_VIEWER_STATE: DashboardViewerState;

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

@@ -0,0 +1,24 @@
+export type SetDashboardFavoriteInput = {
+    readonly dashboardId: string;
+    readonly isFavorite: boolean;
+};
+export type DashboardFavorites = {
+    /**
+     * What to show: this viewer's write while in flight or newer than the
+     * server data, else the server's value. `serverFetchedAt` is when that data
+     * arrived (client clock, ms).
+     */
+    isFavorite(dashboardId: string, serverIsFavorite: boolean, serverFetchedAt?: number): boolean;
+    /** A write for this dashboard is waiting for the server. */
+    isPending(dashboardId: string): boolean;
+    /** Resolves true when the server saved it; false after it was put back. */
+    setFavorite(input: SetDashboardFavoriteInput): Promise<boolean>;
+};
+/**
+ * Dashboard favorites for the viewer the token names (FAV-D15). Reads and
+ * writes go through one viewer-scoped store (`dashboard-favorites-store.ts`);
+ * server responses are read as they are and never edited, so a cached list or
+ * dashboard response cannot disagree with a write made since (ledger R-01,
+ * R-02, R-05).
+ */
+export declare function useDashboardFavorite(): DashboardFavorites;

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

@@ -6,6 +6,8 @@ export declare function useDashboardQuery(): {
         organizationAppearance?: import('../types/index.js').AppearanceSpec | null;
         viewer?: import('../types/index.js').DashboardViewerPayload;
     } | null | undefined;
+    /** When `data` arrived (client clock, ms); dashboard favorites read it (FAV-D20). */
+    dataUpdatedAt: number;
     isLoading: boolean;
     isFetching: boolean;
     isError: boolean;

package/dist/types/lib/hooks/use-default-dashboard-toggle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The viewer's default dashboard, as one ⋯ menu item in both dashboard
+ * toolbars (responsive toolbars: the DEFAULT chip and house button left the
+ * toolbar). The hub list keeps its Default chip.
+ */
+export declare function useDefaultDashboardToggle(dashboardId: string | null | undefined): {
+    available: boolean;
+    isDefault: boolean;
+    /** True until the preference has loaded, and while a change is saving. */
+    disabled: boolean;
+    toggle(): void;
+};

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/dashboard-viewer/viewer-contract.d.ts

@@ -63,6 +63,24 @@ export type DashboardViewerPayload = {
         readonly teamScope?: 'tenant' | 'organization';
         readonly canPublish: boolean;
     };
+    /**
+     * Whether the person has favorited this dashboard (dashboard favorites,
+     * FAV-D17). Read with the rest of the preference row; `false` for
+     * session-only access.
+     */
+    readonly isFavorite: boolean;
+};
+/**
+ * The dashboard list's top-level `viewer` (`GET /api/management/v1/dashboards`,
+ * FAV-D18): whether the person the token names can change favorites.
+ */
+export type DashboardListViewer = Pick<DashboardViewerPayload, 'access' | 'accessReason'>;
+/** `PUT` and `DELETE /api/management/v1/dashboards/{id}/favorite` (FAV-D4). */
+export type DashboardFavoriteState = {
+    readonly dashboardId: string;
+    readonly isFavorite: boolean;
+    /** ISO 8601; `null` when not a favorite. */
+    readonly favoritedAt: string | null;
 };
 /**
  * How many saved bookmarks and remembered table settings reference each part

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.548",
+  "version": "0.1.550",
   "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"