@devicechain/dashboards 0.21.1-rc.1 → 0.22.0-rc.1

package/README.md

@@ -54,15 +54,23 @@ Ten widgets pointed at the same device open **one** upstream subscription, not
 ten. Each widget declares the measurement names it cares about (none means all),
 and the hub fans a single stream out to the subscribers that asked for each name.
 
-Four channels, each with its own `subscribe*` method and disposer:
+Each channel has its own method, and each subscription returns its disposer:
 
-| channel | what it carries |
+| method | what it carries |
 | --- | --- |
 | `subscribeWidget` | measurement samples for a datasource selector |
+| `subscribeMembers` | a fleet widget's members, then each member's samples tagged with its device |
+| `bucketMeasurements` | the time buckets (count, minimum, maximum, sum) a stat widget folds into one figure |
 | `subscribeAlarms` | live alarm rows, plus `acknowledgeAlarm` / `clearAlarm` |
-| `subscribeCommands` | command rows and their delivery status, plus dispatch |
+| `subscribeCommands` | command rows and their delivery status, plus `sendCommand` |
 | `subscribeLocations` | position series for map widgets |
 
+The widget layer depends on the `WidgetDataSource` interface, not on the hub
+class, so a host can feed it from the hub, from `SyntheticDataSource` or from a
+recorded run (`RecordedDataSource`). `subscribeMembers`, `bucketMeasurements` and
+`readMemberSeeds` are optional on that interface: a source without them leaves
+the widgets that need them saying so instead of showing a number.
+
 `disposeAll()` tears down every open channel — a host calls it when the board
 closes, which is what keeps a poll and a socket from outliving the page.
 
@@ -77,11 +85,49 @@ import { parseDashboardDefinition, serializeDefinition } from '@devicechain/dash
 const board = parseDashboardDefinition(json); // throws DashboardDefinitionError
 ```
 
+A board saved by a newer release than this package is refused rather than read as
+the current format: the `DashboardDefinitionError` carries `code: 'schemaTooNew'`
+and the version it found in `found`. Test `code`, not `instanceof`, so the check
+still holds when an application ends up with two copies of the package.
+
 Parsing is validating: a malformed board fails here, in your code, rather than
-half-rendering later. `isDirty` compares a working copy against its saved
-original, `resolveWidgetBox` and `activeBreakpoint` resolve responsive layout,
-and the `editor-model` transforms (`addWidget`, `setWidgetBox`, `deleteWidget`,
-`bringToFront`, …) are pure functions an authoring UI can wire to drag and resize.
+half-rendering later. A board stored in an older format is converted as it is
+parsed, and the result carries a `convertedFrom` mark until it is saved again
+(`withoutConversionMark` drops it). `isDirty` compares a working copy against its
+saved original.
+
+### Layout
+
+A board lays out on a grid of square cells. Each widget has a `WidgetLayout`: a
+`Placement` per breakpoint, with `base` required. A placement is either a grid
+footprint (`GridPlacement`, measured in cells) or a position relative to another
+widget (`RelativePlacement`). The column count follows the container, so the same
+board reads on a phone and on a wall display.
+
+| need | exports |
+| --- | --- |
+| the placement a widget shows at a width | `activeBreakpoint`, `resolvePlacement` |
+| what a renderer draws for a container width | `effectiveLayout`, `layoutShape`, `liveColumns` |
+| pixel boxes for every widget | `layoutRects`, `gridRect`, `relativeRect`, `cellSizeAt` |
+| grid lengths and the widget frame | `gridLengthPx`, `gutterPx`, `paddingPx`, `resolveFrame` |
+| placement against what each widget can show | `lintLayout`, `blockingLayoutFindings` |
+
+The `editor-model` transforms are pure functions an authoring UI can wire to drag
+and resize: `addWidget`, `moveWidget`, `resizeWidget`, `setWidgetPlacement`,
+`placeOnGrid`, `placeRelative`, `deleteWidget`, `setTitle`, `setCanvasGrid`,
+`setCanvasDensity` and `updateWidget`, with `gridPlacementToPx` and
+`pxToGridPlacement` to convert between cells and pixels. Moving or resizing a
+grid widget pushes whatever it now covers out of its way. Grid widgets never
+overlap, so there is no stacking order to manage.
+
+### Time range and density
+
+A board has a time range: `TIME_RANGE_PRESETS` (15 minutes to 7 days),
+`initialTimeRange`, `pauseRange` / `resumeRange` and `rangeWindow` manage it, and
+`timeRangeFromSearch` reads the `range` and `paused` URL parameters. Its density
+(`CANVAS_DENSITIES`: `compact`, `comfortable`, `wall`) scales every text and
+spacing size by `DENSITY_SCALE`; a host may override the board's own value at
+view time.
 
 ## Slots
 
@@ -113,6 +159,41 @@ is still in flight but is no longer cancellable. The underlying sets are
 deliberately not exported: every surface asks the predicate, so a new status
 cannot be learned by some call sites and not others.
 
+## Upgrading from 0.21
+
+0.22 replaces the layout model, so code written against 0.21 needs changes:
+
+| 0.21 | 0.22 |
+| --- | --- |
+| `WidgetBox` | `Placement` (`GridPlacement` or `RelativePlacement`) |
+| `resolveWidgetBox` | `resolvePlacement` |
+| `baseBox` | `basePlacement` |
+| `setWidgetBox` | `setWidgetPlacement`, or `moveWidget` / `resizeWidget` |
+| `gridBoxToPx` / `pxToGridBox` | `gridPlacementToPx` / `pxToGridPlacement` |
+| `bringToFront` | removed: grid widgets cannot overlap, so there is no stacking order |
+
+These keep their names but change type:
+
+- `WidgetLayout` maps a breakpoint to a `Placement`, and `Breakpoints` maps a
+  name to a `BreakpointSpec`.
+- `CanvasGrid` replaces `gap` and `rowHeight` with `minCellSize`, `gutter` and
+  `padding`; `GridGeometry` replaces its column and row sizes with `cell` and
+  `gutter`.
+- `SYNTHETIC_GENERATORS` is a list of generator ids (`'sine'`, `'ramp'`,
+  `'random-walk'`) instead of `{ value, label }` pairs. Supply your own labels;
+  the stored ids are unchanged.
+- `parseDashboardDefinition` refuses a definition whose grid widgets overlap. A
+  definition in an older format is converted before that check.
+
+Some unions gained members, which breaks an exhaustive `switch` over them:
+`WidgetChannel` has `'aggregate'` (the stat card), `OptionSpec` has
+`ListOptionSpec`, and `WidgetType`, `WidgetId` and `BuiltinWidgetId` have the new
+built-in widgets.
+
+The release's upgrade guide covers what changes for stored boards and for the
+other packages:
+[If you build against the npm packages](https://docs.devicechain.io/deployment/releases-and-upgrades#v0220-packages).
+
 ## Compatibility
 
 ESM only, built for bundler resolution (Vite, webpack, Rollup, esbuild). The

package/dist/channel-snapshots.d.ts

@@ -3,6 +3,22 @@ export interface MeasurementStreamState {
     latest: Record<string, MeasurementSample>;
     samples: MeasurementSample[];
     error: unknown | null;
+    truncatedBefore?: string;
+    members?: FleetState;
+}
+export interface FleetMember {
+    token: string;
+    name: string | null;
+    latest: Record<string, MeasurementSample>;
+    seed: 'pending' | 'ready' | 'failed';
+    observed: string[];
+    unread?: string[];
+}
+export interface FleetState {
+    status: 'loading' | 'ready' | 'unbound' | 'forbidden' | 'unsupported';
+    members: FleetMember[];
+    total: number;
+    truncated: boolean;
 }
 export interface AlarmStreamState {
     alarms: AlarmRow[];
@@ -24,3 +40,30 @@ export interface LocationStreamState {
     loading: boolean;
     error: unknown | null;
 }
+export interface MeasurementAggregate {
+    count: number;
+    min: number;
+    max: number;
+    sum: number;
+    avg: number;
+}
+export interface AggregateSpan {
+    startTime: string;
+    endTime: string;
+    spanSeconds: number;
+}
+export type AggregateResult = {
+    status: 'loading';
+} | ({
+    status: 'ready';
+    byName: Record<string, MeasurementAggregate>;
+} & AggregateSpan) | {
+    status: 'unavailable';
+    reason: 'unsupported' | 'failed';
+    message?: string;
+};
+export interface AggregateStreamState {
+    aggregates: AggregateResult;
+    latest: Record<string, MeasurementSample>;
+    error: unknown | null;
+}

package/dist/connection.d.ts

@@ -0,0 +1,27 @@
+export type HubConnectionState = 'live' | 'reconnecting' | 'offline';
+export declare const OFFLINE_AFTER_MS = 20000;
+export declare const STABLE_AFTER_MS = 10000;
+export interface ConnectionHandle {
+    connected(): void;
+    closed(): void;
+    release(): void;
+}
+export declare class ConnectionTracker {
+    private readonly offlineAfterMs;
+    private readonly stableAfterMs;
+    private readonly down;
+    private readonly listeners;
+    private escalated;
+    private escalate;
+    private recover;
+    private browserOffline;
+    private current;
+    private detach;
+    constructor(offlineAfterMs?: number, stableAfterMs?: number);
+    get state(): HubConnectionState;
+    register(): ConnectionHandle;
+    subscribe(listener: () => void): () => void;
+    private attach;
+    private release;
+    private settle;
+}

package/dist/definition.d.ts

@@ -1,13 +1,16 @@
-import { type Breakpoints, type DashboardDefinition, type ExtensionWidgetInstance, type KnownWidgetInstance, type SlotBinding, type SlotDefinition, type WidgetBox, type WidgetLayout } from './types';
+import { type DashboardDefinition, type ExtensionWidgetInstance, type KnownWidgetInstance, type SlotBinding, type SlotDefinition } from './types';
+import { BASE_BREAKPOINT } from './grid';
 import type { WidgetCatalog } from './widget-catalog';
-export declare const BASE_BREAKPOINT = "base";
+export { BASE_BREAKPOINT };
 export declare class DashboardDefinitionError extends Error {
-    constructor(message: string);
+    readonly code?: 'schemaTooNew' | undefined;
+    readonly found?: number | undefined;
+    constructor(message: string, code?: 'schemaTooNew' | undefined, found?: number | undefined);
 }
 export interface ParseDefinitionOptions {
     catalog?: WidgetCatalog;
 }
-export declare function parseDashboardDefinition(raw: unknown, options?: ParseDefinitionOptions): DashboardDefinition;
+export declare function parseDashboardDefinition(input: unknown, options?: ParseDefinitionOptions): DashboardDefinition;
 export declare function canScopeSlot(slots: Record<string, SlotDefinition>, child: string, parentName: string): boolean;
 export declare function parseSlotBinding(raw: unknown): SlotBinding | undefined;
 export type StoredDashboardDefinition = Omit<DashboardDefinition, 'widgets'> & {
@@ -15,7 +18,6 @@ export type StoredDashboardDefinition = Omit<DashboardDefinition, 'widgets'> & {
 };
 export declare function storedDefinition(def: DashboardDefinition): StoredDashboardDefinition;
 export declare function serializeDefinition(def: DashboardDefinition): string;
+export declare function withoutConversionMark(def: DashboardDefinition): DashboardDefinition;
 export declare function isDirty(a: DashboardDefinition, b: DashboardDefinition): boolean;
-export declare function resolveWidgetBox(layout: WidgetLayout, breakpoint: string): WidgetBox;
-export declare function activeBreakpoint(breakpoints: Breakpoints, viewportWidth: number): string;
 export declare function generateWidgetId(): string;

package/dist/editor-clipboard.d.ts

@@ -0,0 +1,42 @@
+import { type ParseDefinitionOptions } from './definition';
+import { type Canvas, type DashboardDefinition, type ResolvedWidgetInstance, type SlotDefinition } from './types';
+export declare const WIDGET_CLIPBOARD_FORMAT = "devicechain/dashboard-widgets";
+export declare const WIDGET_CLIPBOARD_VERSION = 1;
+export interface ClipboardOrigin {
+    tenant: string;
+    board: string;
+}
+export interface WidgetClipboard {
+    tenant: string;
+    board: string;
+    canvas: Canvas;
+    widgets: ResolvedWidgetInstance[];
+    slots: Record<string, SlotDefinition>;
+}
+export interface RefusedWidget {
+    type: string;
+    reason: string;
+}
+export interface UnboundPaste {
+    widgetId: string;
+    slot: string;
+    from: string;
+    reason: 'missing' | 'different' | 'tenant';
+}
+export interface PasteResult {
+    definition: DashboardDefinition;
+    ids: string[];
+    unbound: UnboundPaste[];
+}
+export declare function copyWidget(def: DashboardDefinition, id: string, origin: ClipboardOrigin): WidgetClipboard | undefined;
+export declare function serializeWidgetClipboard(clip: WidgetClipboard): string;
+export declare function parseWidgetClipboard(text: string, options?: ParseDefinitionOptions): {
+    clipboard: WidgetClipboard;
+    refused: RefusedWidget[];
+} | undefined;
+export declare function pasteWidgets(def: DashboardDefinition, clip: WidgetClipboard, at: ClipboardOrigin): PasteResult;
+export declare function duplicateWidget(def: DashboardDefinition, id: string): {
+    definition: DashboardDefinition;
+    id: string;
+    unbound: UnboundPaste[];
+} | undefined;

package/dist/editor-history.d.ts

@@ -0,0 +1,30 @@
+export declare const DEFAULT_HISTORY_LIMIT = 100;
+export interface HistoryEntry<T, L> {
+    state: T;
+    label: L;
+}
+export interface EditHistory<T, L> {
+    readonly past: readonly HistoryEntry<T, L>[];
+    readonly present: T;
+    readonly future: readonly HistoryEntry<T, L>[];
+    readonly open?: string;
+    readonly limit: number;
+}
+export declare function createEditHistory<T, L = string>(present: T, options?: {
+    limit?: number;
+}): EditHistory<T, L>;
+export interface CommitOptions<T> {
+    key?: string;
+    equals?: (a: T, b: T) => boolean;
+}
+export declare function commitEdit<T, L>(h: EditHistory<T, L>, next: T, label: L, options?: CommitOptions<T>): EditHistory<T, L>;
+export declare function sealHistory<T, L>(h: EditHistory<T, L>): EditHistory<T, L>;
+export interface Step<T, L> {
+    history: EditHistory<T, L>;
+    label?: L;
+}
+export declare function undoEdit<T, L>(h: EditHistory<T, L>): Step<T, L>;
+export declare function redoEdit<T, L>(h: EditHistory<T, L>): Step<T, L>;
+export declare const canUndo: (h: EditHistory<unknown, unknown>) => boolean;
+export declare const canRedo: (h: EditHistory<unknown, unknown>) => boolean;
+export declare function rebaseHistory<T, L>(h: EditHistory<T, L>, fn: (state: T) => T): EditHistory<T, L>;

package/dist/editor-model.d.ts

@@ -1,14 +1,44 @@
-import type { CanvasGrid, CanvasSizing, DashboardDefinition, WidgetBox, WidgetInstance } from './types';
-import type { WidgetDescriptor } from './widget-descriptor';
-export declare function baseBox(widget: WidgetInstance): WidgetBox;
-export declare function setWidgetBox(def: DashboardDefinition, id: string, box: WidgetBox): DashboardDefinition;
+import { type Gutter } from './grid';
+import { type SpanLimits } from './layout-lint';
+import type { CanvasDensity, CanvasGrid, CanvasSizing, DashboardDefinition, GridPlacement, Placement, PlacementAnchor, WidgetInstance } from './types';
+import { type WidgetDescriptor } from './widget-descriptor';
+export declare function basePlacement(widget: WidgetInstance): Placement;
+export declare function resolveEverywhere(def: DashboardDefinition, first: readonly string[], aside?: boolean): DashboardDefinition;
+export interface EditOptions {
+    nearest?: boolean;
+}
+export declare function setWidgetPlacement(def: DashboardDefinition, id: string, placement: Placement, options?: EditOptions): DashboardDefinition;
+export declare function clampSpan(span: {
+    cols: number;
+    rows: number;
+}, limits: SpanLimits | undefined, room: number): {
+    cols: number;
+    rows: number;
+};
+export declare function moveWidget(def: DashboardDefinition, id: string, to: {
+    col: number;
+    row: number;
+}, columns?: number, options?: EditOptions): DashboardDefinition;
+export declare function resizeWidget(def: DashboardDefinition, id: string, target: {
+    col: number;
+    row: number;
+    cols: number;
+    rows: number;
+}, limits: SpanLimits | undefined, edges?: {
+    fromLeft?: boolean;
+    fromTop?: boolean;
+}, columns?: number, options?: EditOptions): DashboardDefinition;
 export declare function deleteWidget(def: DashboardDefinition, id: string): DashboardDefinition;
-export declare function bringToFront(def: DashboardDefinition, id: string): DashboardDefinition;
+export declare function hostSpan(p: Placement, def: DashboardDefinition, bp: string): {
+    cols: number;
+    rows: number;
+};
 export declare function setTitle(def: DashboardDefinition, title: string): DashboardDefinition;
 export declare function setCanvasGrid(def: DashboardDefinition, patch: Partial<CanvasGrid>): DashboardDefinition;
 export declare function setCanvasSizing(def: DashboardDefinition, sizing: CanvasSizing): DashboardDefinition;
+export declare function setCanvasDensity(def: DashboardDefinition, density: CanvasDensity): DashboardDefinition;
 export declare function updateWidget(def: DashboardDefinition, id: string, next: WidgetInstance): DashboardDefinition;
-export declare function addWidget(def: DashboardDefinition, descriptor: Pick<WidgetDescriptor, 'id' | 'defaults' | 'version' | 'optionsVersion' | 'sdkApiVersion'>): {
+export declare function addWidget(def: DashboardDefinition, descriptor: Pick<WidgetDescriptor, 'id' | 'defaults' | 'version' | 'optionsVersion' | 'sdkApiVersion' | 'layout'>): {
     definition: DashboardDefinition;
     id: string;
 };
@@ -19,13 +49,32 @@ export interface PixelRect {
     h: number;
 }
 export interface GridGeometry {
-    colWidth: number;
-    colGap: number;
-    rowHeight: number;
-    rowGap: number;
+    cell: number;
+    gutter: Gutter;
+}
+export declare function gridPlacementToPx(p: GridPlacement, geom: GridGeometry): PixelRect;
+export declare function pxToGridPlacement(px: PixelRect, geom: GridGeometry, columns?: number): GridPlacement;
+export declare function formatSpan(span: {
+    cols: number;
+    rows: number;
+}): string;
+export declare const OFFSET_STEP = 1;
+export declare const OFFSET_STEP_FINE = 0.25;
+export declare function snapOffset(value: number, fine?: boolean): number;
+export interface RelativeBounds {
+    cell: number;
+    gutter: Gutter;
+    columns: number;
 }
-export declare function gridBoxToPx(box: WidgetBox, geom: GridGeometry): PixelRect;
-export declare function pxToGridBox(px: PixelRect, geom: GridGeometry, z: number, offset?: {
+export declare function setRelativeOffset(def: DashboardDefinition, id: string, offset: {
     x: number;
     y: number;
-}, columns?: number): WidgetBox;
+}, options?: {
+    fine?: boolean;
+    bounds?: RelativeBounds;
+}): DashboardDefinition;
+export declare function canHostRelative(def: DashboardDefinition, id: string, hostId: string): boolean;
+export declare function placeRelative(def: DashboardDefinition, id: string, hostId: string, anchor: PlacementAnchor): DashboardDefinition;
+export declare function setRelativeAnchor(def: DashboardDefinition, id: string, anchor: PlacementAnchor): DashboardDefinition;
+export declare function placeOnGrid(def: DashboardDefinition, id: string): DashboardDefinition;
+export declare function fitToLimits(def: DashboardDefinition, spanLimitsOf: (widget: WidgetInstance) => SpanLimits | undefined): DashboardDefinition;

package/dist/grid.d.ts

@@ -0,0 +1,53 @@
+import { type Breakpoints, type BreakpointSpec, type Canvas, type CanvasGrid, type GridLength, type GridPlacement, type Placement, type PlacementAnchor, type RelativePlacement, type ResolvedFrame, type SpaceTokenName, type WidgetFrameSpec, type WidgetInstance, type WidgetLayout } from './types';
+export declare const BASE_BREAKPOINT = "base";
+export declare const DEFAULT_GRID: Readonly<CanvasGrid>;
+export declare const PHONE_MIN_COLUMNS = 4;
+export declare function isSpaceToken(v: unknown): v is SpaceTokenName;
+export declare function gridLengthPx(len: GridLength, scale?: number): number;
+export interface Gutter {
+    x: number;
+    y: number;
+}
+export interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export declare function gutterPx(grid: CanvasGrid, scale?: number): Gutter;
+export declare function paddingPx(grid: CanvasGrid, scale?: number): Insets;
+export declare function cellSizeAt(grid: CanvasGrid, containerWidth: number, columns?: number, scale?: number): number;
+export declare function containerWidthFor(grid: CanvasGrid, cell: number, columns?: number, scale?: number): number;
+export declare function breakpointMinWidth(spec: BreakpointSpec): number;
+export declare function breakpointColumns(canvas: Pick<Canvas, 'grid' | 'breakpoints'>, breakpoint: string): number;
+export declare function activeBreakpoint(breakpoints: Breakpoints, width: number): string;
+export declare function resolvePlacement(layout: WidgetLayout, breakpoint: string): Placement;
+export declare function layoutBreakpoints(breakpoints: Breakpoints, widgets: readonly {
+    layout: WidgetLayout;
+}[]): string[];
+export declare function gridFootprintsOverlap(a: GridPlacement, b: GridPlacement): boolean;
+export interface PlacedGrid {
+    id: string;
+    placement: GridPlacement;
+}
+export declare function pushDown(items: readonly PlacedGrid[], first?: readonly string[]): Map<string, GridPlacement>;
+export declare function pushAside(items: readonly PlacedGrid[], first?: readonly string[]): Map<string, GridPlacement>;
+export declare function firstFreeSlot(occupied: readonly GridPlacement[], cols: number, rows: number, columns: number): {
+    col: number;
+    row: number;
+};
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare function spanPx(n: number, cell: number, gutter: number): number;
+export declare function gridRect(p: GridPlacement, cell: number, gutter: Gutter): Rect;
+export declare function anchorFraction(anchor: PlacementAnchor): {
+    fx: number;
+    fy: number;
+};
+export declare function relativeRect(p: RelativePlacement, host: Rect, cell: number, gutter: Gutter): Rect;
+export declare function layoutRects(widgets: readonly WidgetInstance[], breakpoint: string, cell: number, gutter: Gutter): Map<string, Rect>;
+export declare function resolveFrame(canvasFrame: WidgetFrameSpec | undefined, widgetFrame: WidgetFrameSpec | undefined): ResolvedFrame;

package/dist/history.d.ts

@@ -4,5 +4,6 @@ export interface HistoryWindow {
     endTime: string;
     intervalSeconds: number;
 }
+export declare function historyWindowFor(spanSeconds: number, end: number): HistoryWindow;
 export declare function defaultHistoryWindow(): HistoryWindow;
 export declare function fetchWidgetHistory(widget: WidgetInstance, window: HistoryWindow): Promise<MeasurementSample[]>;

package/dist/hub.d.ts

@@ -1,7 +1,15 @@
+import { type HubConnectionState } from './connection';
+import type { HistoryWindow } from './history';
+import type { MemberRef, MemberSeed, MemberSeedPlan, MemberSink, SeedFailure } from './members';
+import { type MeasurementBucket } from './queries';
 import type { AlarmRow, AnchorTarget, CommandRow, DatasourceSelector, LocationSample, MeasurementSample } from './types';
 export interface DeviceResolver {
     devicesForAnchor(anchor: AnchorTarget): Promise<string[]>;
     deviceExists(deviceToken: string): Promise<boolean>;
+    anchorMembers?(anchor: AnchorTarget): Promise<{
+        members: MemberRef[];
+        total: number;
+    }>;
 }
 export interface WidgetStreamSink {
     next: (sample: MeasurementSample) => void;
@@ -73,6 +81,10 @@ export interface WidgetDataSource {
     subscribeCommands(subscription: CommandSubscription, sink: CommandStreamSink): () => void;
     subscribeLocations(subscription: LocationSubscription, sink: LocationStreamSink): () => void;
     isDatasourceAvailable(datasource: DatasourceSelector | undefined): Promise<boolean>;
+    now?(): number;
+    bucketMeasurements?(datasource: DatasourceSelector, window: HistoryWindow): Promise<MeasurementBucket[]>;
+    subscribeMembers?(datasource: DatasourceSelector, sink: MemberSink): () => void;
+    readMemberSeeds?(deviceTokens: readonly string[], plan: MemberSeedPlan, onSeed: (deviceToken: string, seed: MemberSeed | null, failure?: SeedFailure) => void, cancelled?: () => boolean): Promise<void>;
 }
 export declare class DashboardHub implements WidgetDataSource, WidgetActions {
     private readonly resolver;
@@ -83,8 +95,21 @@ export declare class DashboardHub implements WidgetDataSource, WidgetActions {
     private readonly alarmDisposers;
     private readonly commandDisposers;
     private readonly locationDisposers;
+    private readonly connection;
+    private readonly deadStreams;
     constructor(config: DashboardHubConfig);
+    get connectionState(): HubConnectionState;
+    onConnectionState(listener: () => void): () => void;
     subscribeWidget(datasource: DatasourceSelector, sink: WidgetStreamSink): () => void;
+    subscribeMembers(datasource: DatasourceSelector, sink: MemberSink): () => void;
+    private resolveRoster;
+    private readonly seedLimiter;
+    private readonly seedReads;
+    readMemberSeeds(deviceTokens: readonly string[], plan: MemberSeedPlan, onSeed: (deviceToken: string, seed: MemberSeed | null, failure?: SeedFailure) => void, cancelled?: () => boolean): Promise<void>;
+    private memberBuckets;
+    private readonly bucketReads;
+    bucketMeasurements(datasource: DatasourceSelector, window: HistoryWindow): Promise<MeasurementBucket[]>;
+    private readBuckets;
     subscribeAlarms(subscription: AlarmSubscription, sink: AlarmStreamSink): () => void;
     private resolveAlarmScope;
     private queryAlarms;

package/dist/index.d.ts

@@ -1,21 +1,34 @@
-export type { DashboardDefinition, Canvas, CanvasBackground, CanvasGrid, CanvasSizing, Breakpoints, WidgetInstance, KnownWidgetInstance, ExtensionWidgetInstance, ExtensionWidgetType, ResolvedWidgetInstance, UnknownWidgetInstance, UnknownWidgetType, UnresolvedWidgetCode, UnresolvedWidgetReason, WidgetImplementationRef, WidgetType, WidgetLayout, WidgetBox, DatasourceSelector, DeviceSelector, AnchorSelector, AnchorTarget, AnchorAggregation, DevicesSelector, RelatedTraversalSelector, SlotSelector, UnboundSelector, SlotDefinition, SlotScope, SlotBinding, SelectionTarget, SelectionCandidate, EntityCandidateLister, EntityListKind, MeasurementSample, LocationSample, LocationSeries, LocationSelection, AlarmRow, CommandRow, CommandParameter, CommandParamDataType, } from './types';
+export type { DashboardDefinition, BoardTimeRange, Canvas, CanvasBackground, CanvasGrid, CanvasSizing, Breakpoints, BreakpointSpec, GridLength, GridPlacement, RelativePlacement, RelativeSize, Placement, PlacementAnchor, PlacementMode, FrameBorder, FrameBorderWidth, FrameHeader, FrameRadius, FrameVariant, ResolvedFrame, SpaceTokenName, ThemeColorToken, WidgetFrameSpec, WidgetInstance, KnownWidgetInstance, ExtensionWidgetInstance, ExtensionWidgetType, ResolvedWidgetInstance, UnknownWidgetInstance, UnknownWidgetType, UnresolvedWidgetCode, UnresolvedWidgetReason, WidgetImplementationRef, WidgetType, WidgetLayout, DatasourceSelector, DeviceSelector, AnchorSelector, AnchorTarget, AnchorAggregation, DevicesSelector, RelatedTraversalSelector, SlotSelector, UnboundSelector, SlotDefinition, SlotScope, SlotBinding, SelectionTarget, SelectionCandidate, EntityCandidateLister, EntityListKind, MeasurementSample, LocationSample, LocationSeries, LocationSelection, AlarmRow, CommandRow, CommandParameter, CommandParamDataType, } from './types';
 export { COMMAND_STATUSES, isTerminalCommandStatus, isCancellableCommandStatus, type CommandStatus, } from './command-status';
 export { effectiveBindings, parseBindingManifest, resolveWidgetDatasource, stripDefaultBindings, type ParsedBindingManifest, } from './bindings';
 export { resolveContextBindings, hasScopedSlots, applySelection, bindingsWithoutScopedSlots, type MemberResolver, } from './context';
 export { migrateToSlots, bindWidgetSlot, clearWidgetDatasource, pruneSlots, widgetBinding, widgetSlotName, sameBinding, resolveConcrete, setSlotScope, anchorSlotNames, type ConcreteSelector, } from './slots';
 export { resolveSlotCandidates } from './candidates';
 export { createEntityLister } from './entity-lister';
-export { WIDGET_TYPES, UNKNOWN_WIDGET_TYPE } from './types';
+export { WIDGET_TYPES, UNKNOWN_WIDGET_TYPE, CURRENT_SCHEMA_VERSION, PLACEMENT_ANCHORS, PLACEMENT_MODES, RESERVED_PLACEMENT_MODES, THEME_COLOR_TOKENS, SPACE_TOKEN_PX, FRAME_VARIANTS, FRAME_RADII, FRAME_BORDER_WIDTHS, FRAME_HEADERS, } from './types';
+export { CANVAS_DENSITIES, DEFAULT_CANVAS_DENSITY, DENSITY_SCALE, isCanvasDensity, type CanvasDensity, } from './types';
+export { sameLabel } from './same-label';
+export { ConnectionTracker, OFFLINE_AFTER_MS, type ConnectionHandle, type HubConnectionState } from './connection';
 export { DashboardHub, type DashboardHubConfig, type DeviceResolver, type WidgetStreamSink, type WidgetDataSource, type AlarmSubscription, type AlarmSnapshot, type AlarmStreamSink, type CommandSubscription, type CommandSnapshot, type CommandStreamSink, type CommandDispatch, type LocationSubscription, type LocationSnapshot, type LocationStreamSink, type WidgetActions, } from './hub';
 export { SyntheticDataSource, SYNTHETIC_GENERATORS, type SyntheticGenerator, type SyntheticDataSourceConfig, } from './synthetic';
 export { RECORDING_FORMAT_VERSION, RECORDING_KIND, RecordingFormatError, parseBoardRecording, recordedWallTimeMs, recordingBounds, simulationScaleAt, type BoardRecording, type RecordedAlarm, type RecordedAlarmEvent, type RecordedAlarmSnapshot, type RecordedChannels, type RecordedChapter, type RecordedClockSegment, type RecordedDevice, type RecordedMeasurementColumns, } from './recording';
 export { PLAYBACK_RATES, RECORDED_HISTORY_WINDOW_MS, NotInRecordingError, RecordedClock, RecordedDataSource, createRecordedClock, createRecordedLister, createRecordedResolver, type ClockEvent, type ClockTicker, type PlaybackRate, type RecordedChannel, type RecordedSiteOptions, } from './recorded';
-export { parseDashboardDefinition, type ParseDefinitionOptions, parseSlotBinding, serializeDefinition, storedDefinition, isDirty, resolveWidgetBox, activeBreakpoint, generateWidgetId, canScopeSlot, DashboardDefinitionError, BASE_BREAKPOINT, } from './definition';
-export { baseBox, setWidgetBox, deleteWidget, bringToFront, setTitle, setCanvasGrid, setCanvasSizing, updateWidget, addWidget, gridBoxToPx, pxToGridBox, type PixelRect, type GridGeometry, } from './editor-model';
+export { parseDashboardDefinition, type ParseDefinitionOptions, parseSlotBinding, serializeDefinition, storedDefinition, isDirty, withoutConversionMark, generateWidgetId, canScopeSlot, DashboardDefinitionError, BASE_BREAKPOINT, } from './definition';
+export { basePlacement, clampSpan, moveWidget, resizeWidget, setWidgetPlacement, deleteWidget, setTitle, setCanvasGrid, setCanvasSizing, setCanvasDensity, updateWidget, addWidget, canHostRelative, fitToLimits, formatSpan, OFFSET_STEP, OFFSET_STEP_FINE, placeOnGrid, placeRelative, setRelativeAnchor, setRelativeOffset, snapOffset, gridPlacementToPx, pxToGridPlacement, type EditOptions, type PixelRect, type RelativeBounds, type GridGeometry, } from './editor-model';
+export { DEFAULT_HISTORY_LIMIT, canRedo, canUndo, commitEdit, createEditHistory, rebaseHistory, redoEdit, sealHistory, undoEdit, type CommitOptions, type EditHistory, type HistoryEntry, type Step, } from './editor-history';
+export { WIDGET_CLIPBOARD_FORMAT, WIDGET_CLIPBOARD_VERSION, copyWidget, duplicateWidget, parseWidgetClipboard, pasteWidgets, serializeWidgetClipboard, type ClipboardOrigin, type PasteResult, type RefusedWidget, type UnboundPaste, type WidgetClipboard, } from './editor-clipboard';
 export { createDeviceResolver } from './resolver';
-export { defaultHistoryWindow, fetchWidgetHistory, type HistoryWindow } from './history';
-export type { AlarmStreamState, CommandStreamState, LocationStreamState, MeasurementStreamState, } from './channel-snapshots';
-export { applyOptionPatch, clampNumberOption, enumValues, numberSpec, validateOptions, HOST_OPTION_CONTROLS, type HostOptionControl, type BooleanOptionSpec, type DefaultsOf, type EnumOptionSpec, type GreaterThanConstraint, type NumberOptionSpec, type OptionConstraint, type OptionIssue, type OptionIssueCode, type OptionKeysOfKind, type OptionSpec, type OptionsOf, type RequiredOptionKeys, type SpecValue, type StringOptionSpec, type ValidateOptionsContext, type WidgetOptionSpecs, } from './option-schema';
-export { SDK_API_VERSION, defineWidgetDescriptor, isBuiltinWidgetId, isNamespacedWidgetId, type AckOptionRef, type BuiltinWidgetId, type ChannelBindingPolicy, type ChannelSnapshot, type ConstBinding, type DatasourcePolicy, type DatasourcePolicyFor, type DatasourceSelectorKind, type InteractionsFor, type NamespacedWidgetId, type NumberOptionRef, type StringOptionRef, type WidgetChannel, type WidgetDescriptor, type WidgetDisplay, type WidgetId, type WidgetInteractionDeclaration, } from './widget-descriptor';
+export type { MeasurementBucket } from './queries';
+export { ANCHOR_PAGE_SIZE } from './resolver';
+export type { MemberBucketCriteria, MemberBucketRead, MemberRef, MemberRoster, MemberSeed, MemberSeedPlan, MemberSink, SeedFailure, } from './members';
+export { defaultHistoryWindow, fetchWidgetHistory, historyWindowFor, type HistoryWindow } from './history';
+export { DEFAULT_TIME_RANGE_SECONDS, MAX_SEED_BUCKETS, MAX_TIME_RANGE_SECONDS, MIN_TIME_RANGE_SECONDS, TIME_RANGE_PRESETS, bucketSecondsFor, initialTimeRange, isValidSpanSeconds, parsePausedParam, parseRangeParam, pauseRange, presetIdOf, rangeEnd, rangeWindow, resumeRange, seedBucketCount, setBoardTimeRange, spanLabel, timeRangeFromSearch, withSpan, type RangeWindow, type TimeRangePresetId, type TimeRangeState, } from './time-range';
+export type { AggregateResult, AggregateSpan, AggregateStreamState, AlarmStreamState, CommandStreamState, FleetMember, FleetState, LocationStreamState, MeasurementAggregate, MeasurementStreamState, } from './channel-snapshots';
+export { applyOptionPatch, clampNumberOption, enumValues, numberSpec, validateOptions, HOST_OPTION_CONTROLS, type HostOptionControl, type BooleanOptionSpec, type DefaultsOf, type EnumOptionSpec, type ListItemFieldSpec, type ListOptionSpec, type GreaterThanConstraint, type NumberOptionSpec, type OptionConstraint, type OptionIssue, type OptionIssueCode, type OptionKeysOfKind, type OptionSpec, type OptionsOf, type RequiredOptionKeys, type SpecValue, type StringOptionSpec, type ValidateOptionsContext, type WidgetOptionSpecs, } from './option-schema';
+export { SDK_API_VERSION, defineWidgetDescriptor, isBuiltinWidgetId, isNamespacedWidgetId, type AckOptionRef, type BuiltinWidgetId, type ChannelBindingPolicy, type ChannelSnapshot, type ConstBinding, type DatasourcePolicy, type DatasourcePolicyFor, type DatasourceSelectorKind, type InteractionsFor, type NamespacedWidgetId, type NumberOptionRef, type StringOptionRef, type WidgetChannel, type WidgetDescriptor, type WidgetDisplay, type WidgetId, type WidgetInteractionDeclaration, FALLBACK_DEFAULT_SPAN, pinnedAxes, type WidgetLayoutSpec, type WidgetResizeMode, type WidgetSpan, } from './widget-descriptor';
 export { WidgetCatalogError, collectCatalogIssues, createWidgetCatalog, describeIssues, validateWidgetDescriptor, type DescriptorIssue, type WidgetCatalog, } from './widget-catalog';
 export { isBuiltinWidget, isResolvedWidget, parseWidgetRef, checkWidgetCompatibility, widgetVersionNotice, unresolvedWidgets, type UnresolvedWidgetReport, } from './widget-compat';
+export { DEFAULT_GRID, PHONE_MIN_COLUMNS, activeBreakpoint, anchorFraction, breakpointColumns, breakpointMinWidth, cellSizeAt, containerWidthFor, firstFreeSlot, gridFootprintsOverlap, gridLengthPx, gridRect, gutterPx, isSpaceToken, layoutBreakpoints, layoutRects, paddingPx, pushDown, pushAside, relativeRect, resolveFrame, resolvePlacement, spanPx, type Gutter, type Insets, type PlacedGrid, type Rect, } from './grid';
+export { effectiveLayout, layoutShape, liveColumns, reflowGrid, STACK_BELOW_WIDTH, type EffectiveLayout, type LayoutShape, type ReflowItem, } from './reflow';
+export { LEGACY_REFERENCE_WIDTH } from './legacy-grid';
+export { blockingLayoutFindings, lintLayout, PUBLISH_BLOCKING_LAYOUT_CODES, spanLimitsOfLayout, type LayoutFinding, type LayoutLintCode, type LayoutLintOptions, type LayoutLintSeverity, type SpanLimits, } from './layout-lint';