8.3 KiB
status, spec
| status | spec |
|---|---|
| done | docs/specs/ui/requirements/app-status-bar.md |
App Status Bar — implementation plan
Outcome
Ship one app-owned status surface: 24 px in-flow bar in the non-phone route-content column, 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 places the full-height sidebar beside a route/status column whose in-flow footer starts at the sidebar layout edge.
--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. |
| 9 | 14 | Sidebar and status-bar geometry agree in expanded, collapsed, resized, and sidebar-hidden layouts. |
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 ───┘
13 shipped surface ──> 14 sidebar-aligned status bar
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: full-height sidebar beside the route/status column, 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.
- Sidebar collapse deliberately snaps its layout reservation while the visual panel animates over content. Align the bar to the shared layout edge without changing that established animation contract or duplicating sidebar-width calculations.
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 |
| 14 | done | 9 | Sidebar-aligned status bar |