Files
kandev/docs/plans/app-status-bar/plan.md
T
José Almeida 9c16d337a2 feat(web): add global app status surface (#1869)
* feat(web): add app status bar

* feat(web): add app status bar visibility toggle

* feat(web): persist status bar item order

* fix(web): refine app status bar behavior

* fix(web): polish app status bar presentation

* test(web): split plugin slot coverage groups

* fix(web): address status surface review feedback

* fix(web): stabilize status bar overlay tests
2026-07-23 12:28:54 +01:00

7.6 KiB

status, spec
status spec
done docs/specs/ui/app-status-bar.md

App Status Bar — implementation plan

Outcome

Ship one app-owned status surface: 24 px in-flow bar on desktop/tablet, native Status drawer on phone. It shows only connection plus existing opted-in host/active-executor metrics, exposes live plugin regions without changing chat-local status UI, and lets users preserve a full-bar item order.

Fixed decisions

  • Slots: app-status-bar-left, app-status-bar-right; exact props live in spec and plugin API.
  • One responsive presentation mounts at once. Desktop=full, tablet=compact, drawer=full.
  • Metrics subscribe only when legacy showInTopbar preference permits: desktop/tablet while bar mounted, phone only while drawer open.
  • Shell uses an in-flow footer. --app-status-bar-height offsets audited desktop fixed overlays only.
  • Orca is conceptual reference only. Ship pinned MIT attribution; do not transplant its component or add data providers.
  • app-status-bar-left and app-status-bar-right choose default sides only. Cmd/Ctrl plus mouse drag may move an opaque host item across the full bar; no keyboard-arrow or touch reorder interaction is added.
  • Portable order lives only in backend-owned user settings as app_status_bar_order.left_item_ids/right_item_ids. Phone renders left then right vertically.
  • The top separator is visually inset over a full 24 px alignment box so dots, text, plugin roots, and metric icons do not inherit a half-pixel center from a 23 px bordered content box.

Waves

Wave Tasks Gate
1 01, 02 Stable slot identity; built-in metric/connection primitives tested.
2 03 One 24 px shell-mounted desktop/tablet surface; header metrics removed.
3 04, 05, 06, 08 Phone access, fixed controls, live plugin E2E, records/attribution land.
4 07 Pixel 5 flow proves drawer parity and geometry.
5 09 Focused then full verification clean.
6 10, 11 User-settings round trip and deterministic opaque item identities.
7 12 Full-bar modifier drag, aligned content, and mirrored phone order.
8 13 Public contract, desktop/mobile persistence E2E, review, and full verification.

Dependency graph

01 plugin slots ─┐
                 ├─> 03 status surface + shell ─┬─> 04 mobile entry points ─┐
02 built-ins ────┘                              ├─> 05 fixed-overlay audit   ├─> 07 mobile E2E ─> 09 verify
                                                ├─> 06 fixture + desktop E2E ─┘
                                                └─> 08 attribution/docs ──────> 09 verify

10 portable order ─┐
                   ├─> 12 reorder + alignment ─> 13 docs/E2E/verify
11 stable items ───┘

File / test map

  • Plugin contract: typed status props, stable owned registrations, owner-aware error boundaries, typed left/right wrapper, unit tests.
  • First-party surface: connection item; status metrics presentation; app bar/drawer/provider; remove TopbarMetrics mounts and update settings copy.
  • Shell and geometry: app/legacy shells, shell-owned route heights, audited fixed controls, explicit z-index and CSS variable offsets.
  • Mobile: native Status actions in Home, task, Settings, PageTopbar, Office; no second footer.
  • Proof: fixture plugin hot enable/disable desktop test; mobile-status-drawer.spec.ts; layout/overlay assertions; licenses-page test.
  • Records: public plugin/operations/features docs, resource-metrics decision amendment, MIT notice generation.
  • Portable order extension: existing user settings model/DTO/service/store, boot and WS mapping, deterministic plugin ordering keys, shared ordered item projection, pointer drag behavior, and drawer projection.
  • Alignment regression: 1x-device-scale geometry assertion proving that the separator does not shrink the content alignment box and that representative plugin text/dot/metric items share a center.

Verification order

Run focused task commands after each wave. E2E must rebuild production assets (make build-web, and make build-backend if Go changes) or use make test-e2e; never run against stale output.

Final order:

make fmt
make typecheck test lint

Also run node --test scripts/validate-public-docs.test.mjs and node scripts/validate-public-docs.mjs. Resolve viewport regressions at narrow desktop, tablet, and configured mobile-chrome Pixel 5 before declaring ready.

For the ordering extension, focused verification starts with:

cd apps/backend && go test ./internal/user/...
cd apps && pnpm --filter @kandev/web test -- components/app-status-bar lib/plugins/registry.test.ts lib/ws/handlers/users.test.ts lib/ssr/user-settings.test.ts
cd apps/web && pnpm e2e:run tests/layout/app-status-bar.spec.ts tests/plugins/mobile-status-drawer.spec.ts

Risks

  • Nested viewport roots can create scrollbars: convert only shell-owned routes to h-full min-h-0 and retain h-dvh for genuine phone sheets/dialogs.
  • A fixed footer does not move fixed overlays: use one CSS variable only at audited controls.
  • Responsive double mounting can duplicate plugins/metrics: provider selects exactly one host presentation.
  • Array-index error-boundary keys leak failure state: stable registration IDs are mandatory.
  • Full-bleed plugin routes intentionally opt out of host chrome; their authors own Status trigger placement.
  • Slot registration IDs created from a process counter do not survive re-enable/restart: derive a separate deterministic ordering identity from plugin/slot/ordinal and keep error-boundary identity behavior covered.
  • Pointer dragging can steal plugin clicks: wait for horizontal movement beyond a threshold before starting reorder, and suppress only the click produced by a completed drag.
  • Disabled plugins and hidden metrics can disappear from active rendering: retain their opaque IDs in the saved arrays and reconcile active items without rewriting missing entries.

Tasks

ID Status Wave Task
01 done 1 Stable plugin status slots
02 done 1 Status built-ins
03 done 2 Status surface shell
04 done 3 Mobile Status entry points
05 done 3 Fixed-overlay audit
06 done 3 Plugin fixture desktop E2E
07 done 4 Mobile Status E2E
08 done 3 Attribution and public docs
09 done 5 Integration verification
10 done 6 Portable status item order
11 done 6 Stable status item identities
12 done 7 Reorder interaction and alignment
13 done 8 Reorder docs, E2E, and verification