Dashboard v1 phase 4 (#280): DashboardViewerSession + normative flow@1 layout

[BorisTyshkevich]

Part of #280 (Dashboard as a first-class module). Phase 4 of 6, after Phase 3. Normative spec in #280.

Folds in and closes: #235 (refresh serializes the Filter wave before every Panel tile), the drag-reorder half of #153, and the baseline filter-bar usability items from #188 (clear one/all, active count, never-hide-blocking — see scope below; #188's impact hints and overflow are dropped as deferred-until-demonstrated-need).

Goal

A standalone read-only DashboardViewerSession plus the normative flow@1 layout (viewer + editor behavior), constructible and testable without Workbench, editors, full App, or global AppState.

Scope (from #280 "Phase 4: viewer and flow layout")

• DashboardViewerSession: immutable document snapshot, resolved queries/presentations, filter values, execution queue with bounded concurrency, per-tile cancellation, stale-wave protection, results/errors/progress, layout controller, destroy() cleanup. Depends only on narrow interfaces (query execution, connection session, resolvers, layout registry) — builds directly on Refactor app.ts into explicit application services and route sessions #276 phase 3b (DashboardSession).
• Dashboard Refresh serializes the Filter wave before the Panel wave for every tile, even unaffected ones #235 resolution inside the session's execution planner: panels whose declared params cannot be affected by any filter source run in parallel with the filter wave instead of behind it; affected panels still see correct blanked/active values on first pass (the invariant prepareBatch guarantees today). The explicit DashboardFilterDefinitionV1.parameter/targets contract supplies the overlap knowledge Dashboard Refresh serializes the Filter wave before the Panel wave for every tile, even unaffected ones #235 said was missing.
• flow@1 per the normative contract: presets, DEFAULT_FLOW_PLACEMENT, effective-span clamping, deterministic row-major packing, semantic = DOM = visual = keyboard = print order, mobile one-column normalization without persistence mutation.
• Derived KPI bands (deterministic grouping algorithm; not persisted entities) — preserve Dashboard KPI bands: flat content-sized cards across layout modes #240 behavior.
• Accessible authoring controls: moveTileEarlier/Later, setTileSpan/Height, keyboard-focusable handle, focus retention, ARIA live announcements — pointer drag (Dashboard: drag-reorder, open panel in window. #153) is an equivalent alternative, never the only mechanism.
• Layout registry with lazy-loadable, compile-time-registered modules and the flow@1 fallback contract.
• Filter-bar baseline usability (absorbed from Dashboard filter bar: clear actions, active count, impact hints, and overflow #188):
  • Clear one filter: keyboard-accessible affordance per active filter; deactivates without discarding the last value (reactivation restores it), one affected-panel wave.
  • Clear all filters: one toolbar action resetting every filter of the current document to its defaultActive/defaultValue; all changes coalesce into one preparation + rerun wave; hidden/disabled when nothing is active.
  • Active count: a compact "N active" indicator counting active filter definitions (not non-empty stored values), updated on every activation change, readable by assistive technology without per-repaint announcements.
  • Never silently hide a blocking filter: a filter whose state blocks a target panel (invalid value, required-and-unset, source-query error) must stay visible or carry a visible badge — the user can always see why a panel is waiting.
  • Explicitly not in scope (dropped from Dashboard filter bar: clear actions, active count, impact hints, and overflow #188, refile only against a real dashboard that needs them): per-filter impact hints ("used by N panels" — trivially derivable from DashboardFilterDefinitionV1.targets if ever wanted) and More filters (N) overflow collapse.

Dependencies

#276 phase 3b (DashboardSession extraction) should land first — this phase replaces/absorbs that runtime. Phases 1–3 of #280.

Tests

Per #280 "Flow layout" test list, plus dependency-boundary tests (check:arch rules: dashboard model/application must not import Workbench UI, full App, AppState, or editor modules), plus a #235 regression pair: unaffected panel starts before the filter wave completes; affected panel still sees correct first-pass values.

Acceptance

• Viewer session runs a dashboard document end-to-end in unit tests with no Workbench construction.
• All Make Dashboard a first-class module with one-dashboard-per-current-workspace v1 UX #280 flow@1 and KPI-band acceptance points.
• Filter bar ships with per-filter clear, coalesced clear-all, accurate active count, and no silently hidden blocking state (tests for each, including the single-wave guarantee on clear-all).
• Dashboard Refresh serializes the Filter wave before the Panel wave for every tile, even unaffected ones #235 and Dashboard: drag-reorder, open panel in window. #153 closed by this phase (reorder here; open-in-window arrives in Phase 6); Dashboard filter bar: clear actions, active count, impact hints, and overflow #188 closed by its dissolution into this scope.