* 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
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
showInTopbarpreference permits: desktop/tablet while bar mounted, phone only while drawer open. - Shell uses an in-flow footer.
--app-status-bar-heightoffsets 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-leftandapp-status-bar-rightchoose 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
TopbarMetricsmounts 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-0and retainh-dvhfor 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 |