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
@@ -6,7 +6,7 @@
|
||||
|
||||
## Context
|
||||
|
||||
Kandev needs lightweight CPU, memory, disk, load, temperature, and IO pressure visibility for users running the app on a remote server or using isolated execution environments. The values should appear in desktop task and kanban topbars only when a user opts in. Kandev also runs agentctl in multiple runtime shapes: some share the backend host, while Docker, remote, and cloud executors have their own resource boundary.
|
||||
Kandev needs lightweight CPU, memory, disk, load, temperature, and IO pressure visibility for users running the app on a remote server or using isolated execution environments. The values should appear in the opt-in global status surface. Kandev also runs agentctl in multiple runtime shapes: some share the backend host, while Docker, remote, and cloud executors have their own resource boundary.
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -14,13 +14,13 @@ Use global system metrics settings for collection policy and per-user settings o
|
||||
|
||||
The backend process samples the backend host. Agentctl exposes an execution-environment metrics endpoint for runtimes with a distinct boundary: local Docker, remote Docker, SSH/remote VPS, and cloud/Sprites. Local process and worktree agentctl instances are not sampled separately in v1 because they duplicate the backend host. Containerized agentctl collectors prefer cgroup CPU and memory accounting when available, falling back to procfs only when no meaningful cgroup limit exists.
|
||||
|
||||
Metrics updates are delivered over a dedicated WebSocket stream to subscribed connections only, not via global broadcast. Mobile clients do not subscribe and do not render the metrics strip.
|
||||
Metrics updates are delivered over a dedicated WebSocket stream to subscribed connections only, not via global broadcast. Desktop and tablet render only the Kandev backend-host source in the app status surface; phone subscribes and renders that same host source only while the global Status drawer is open. Execution-source sampling remains a backend capability, but the global status surface does not couple its built-in presentation to an active task or session. Plugins may use host state for separately owned context-specific presentations.
|
||||
|
||||
## Consequences
|
||||
|
||||
The backend avoids background procfs/cgroup/agentctl polling when no visible UI needs metrics. Multi-user behavior stays clear: global settings control what is sampled and how often, while each user controls whether they see it. Docker and remote users get the execution-environment values that matter instead of duplicated backend-host values.
|
||||
The backend avoids background procfs/cgroup/agentctl polling when no visible UI needs metrics. Multi-user behavior stays clear: global settings control what is sampled and how often, while each user controls whether they see it. Docker and remote execution values remain available in the metrics stream without making the global status surface task-dependent.
|
||||
|
||||
This adds a small connection-interest registry, a reusable install-wide settings table, and a new agentctl API surface. It also means homepage/list views intentionally show backend metrics only in v1; execution metrics are scoped to task detail where the active session is unambiguous.
|
||||
This adds a small connection-interest registry, a reusable install-wide settings table, and a new agentctl API surface. The status surface makes host metrics available consistently across hosted routes and deliberately ignores active-session execution sources. A closed phone Status drawer creates no sampling interest.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
# ADR-2026-07-21-portable-status-bar-order: Portable Status Bar Order
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-07-21
|
||||
**Area:** backend, frontend, protocol
|
||||
|
||||
## Context
|
||||
|
||||
The app status surface exposes separate `app-status-bar-left` and
|
||||
`app-status-bar-right` plugin slots, with built-in connection and metrics items on
|
||||
opposite sides of a flexible spacer. Users need to move any visible item across
|
||||
that spacer and keep the resulting layout after reloads, restarts, plugin
|
||||
enable/disable cycles, and use from another client. Browser storage would make
|
||||
the preference device-local and conflict with the backend-owned portable-settings
|
||||
rule in ADR 0041.
|
||||
|
||||
## Decision
|
||||
|
||||
The slot name determines a plugin contribution's default side only. The host
|
||||
treats the connection indicator, the complete metrics cluster, and each plugin
|
||||
component registration as opaque, reorderable items. A plugin registration's
|
||||
ordering identity is derived deterministically from its plugin ID, original slot,
|
||||
and zero-based registration ordinal within that plugin and slot; plugin children
|
||||
are never inspected or reordered independently.
|
||||
|
||||
The existing backend user-settings JSON owns an `app_status_bar_order` object
|
||||
with ordered `left_item_ids` and `right_item_ids` arrays. Moving an item across
|
||||
the flexible spacer transfers its ID between arrays. Temporarily unavailable IDs
|
||||
remain in the arrays so disabled plugins and hidden metrics can recover their
|
||||
positions. New items that have no saved identity enter at the end of their
|
||||
default side. Existing PATCH omission semantics and the
|
||||
`user.settings.updated` event carry the setting; no relational schema or new
|
||||
endpoint is introduced.
|
||||
|
||||
Desktop and tablet provide Cmd-drag on macOS and Ctrl-drag elsewhere. Phone has
|
||||
no drag interaction and renders the saved left sequence followed by the saved
|
||||
right sequence, without the desktop spacer.
|
||||
|
||||
## Consequences
|
||||
|
||||
- User order is portable and has one durable owner instead of competing browser
|
||||
and backend copies.
|
||||
- `left` and `right` remain useful defaults for plugin authors but are not
|
||||
permanent placement guarantees after user customization.
|
||||
- Plugins must register multiple contributions in deterministic order if they
|
||||
want ordinal-derived identities to keep matching across reloads.
|
||||
- The host can preserve disabled contributions without mounting them, at the
|
||||
cost of retaining opaque stale IDs until their plugin returns or the user
|
||||
resets the preference in a future surface.
|
||||
- Phone reflects desktop customization while retaining its native drawer and no
|
||||
second persistent bar.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
1. **Reorder only inside each named slot.** Rejected because the requested
|
||||
interaction explicitly allows crossing the full bar.
|
||||
2. **Persist in localStorage.** Rejected because order is a portable preference
|
||||
and ADR 0041 makes backend user settings authoritative.
|
||||
3. **Let plugins declare global priorities.** Rejected because it would compete
|
||||
with user order and expand the public plugin contract.
|
||||
4. **Add keyboard or touch reordering.** Not selected for this interaction; the
|
||||
confirmed scope is modifier-plus-mouse dragging on the desktop/tablet bar.
|
||||
@@ -62,4 +62,5 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
|
||||
| 2026-07-20-explicit-local-repository-trust | [Explicit Local Repository Trust](2026-07-20-explicit-local-repository-trust.md) | accepted | backend, frontend | 2026-07-20 |
|
||||
| 2026-07-20-provider-neutral-remote-repositories | [Provider-neutral remote repositories](2026-07-20-provider-neutral-remote-repositories.md) | accepted | backend, frontend, protocol | 2026-07-20 |
|
||||
| 2026-07-20-repository-provider-origin-identity | [Persist Provider Origin In Repository Identity](2026-07-20-repository-provider-origin-identity.md) | accepted | backend, frontend | 2026-07-20 |
|
||||
| 2026-07-21-portable-status-bar-order | [Portable Status Bar Order](2026-07-21-portable-status-bar-order.md) | accepted | backend, frontend, protocol | 2026-07-21 |
|
||||
| 2026-07-21-work-item-reference-search | [Backend-normalized work-item references](2026-07-21-work-item-reference-search.md) | accepted | backend, frontend, protocol | 2026-07-21 |
|
||||
|
||||
@@ -30,7 +30,8 @@ This page expands the short feature list in the README without turning the READM
|
||||
- **Executor profiles:** save per-runtime configuration, including prepare scripts, environment variables, credentials, and profile-specific settings.
|
||||
- **Worktree isolation:** concurrent agents work in isolated git worktrees so their changes do not collide.
|
||||
- **Per-task repository setup:** repositories can copy selected ignored files, such as `.env` files, into newly created worktrees.
|
||||
- **Resource monitor:** optionally show CPU, memory, disk, CPU temperature, and load metrics in desktop task and kanban topbars. Kandev can also collect execution-environment metrics for Docker, SSH, Sprites, and other remote runtimes.
|
||||
- **Resource monitor:** optionally show Kandev-host CPU, memory, disk, CPU temperature, and load metrics in the global desktop/tablet status bar or phone Status drawer. Kandev can also collect execution-environment metrics for separately owned consumers.
|
||||
- **Customizable app status:** opt into connection state, optional host metrics, and live plugin contributions in a 24 px desktop/tablet bar or phone Status drawer. Cmd/Ctrl plus mouse-drag reorders whole status items, with portable backend persistence.
|
||||
|
||||
## Integrations And MCP
|
||||
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
status: done
|
||||
spec: 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](../../specs/ui/app-status-bar.md#plugin-slots) and [plugin API](../plugins/PLUGIN-API.md#app-status-bar-slots).
|
||||
- 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](task-01-plugin-status-slots.md), [02](task-02-status-builtins.md) | Stable slot identity; built-in metric/connection primitives tested. |
|
||||
| 2 | [03](task-03-status-surface-shell.md) | One 24 px shell-mounted desktop/tablet surface; header metrics removed. |
|
||||
| 3 | [04](task-04-mobile-status-entry-points.md), [05](task-05-fixed-overlay-audit.md), [06](task-06-plugin-fixture-desktop-e2e.md), [08](task-08-attribution-public-docs.md) | Phone access, fixed controls, live plugin E2E, records/attribution land. |
|
||||
| 4 | [07](task-07-mobile-status-e2e.md) | Pixel 5 flow proves drawer parity and geometry. |
|
||||
| 5 | [09](task-09-integration-verification.md) | Focused then full verification clean. |
|
||||
| 6 | [10](task-10-portable-item-order.md), [11](task-11-stable-status-item-identities.md) | User-settings round trip and deterministic opaque item identities. |
|
||||
| 7 | [12](task-12-reorder-interaction-and-alignment.md) | Full-bar modifier drag, aligned content, and mirrored phone order. |
|
||||
| 8 | [13](task-13-reorder-docs-e2e-verification.md) | Public contract, desktop/mobile persistence E2E, review, and full verification. |
|
||||
|
||||
## Dependency graph
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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](task-01-plugin-status-slots.md) |
|
||||
| 02 | done | 1 | [Status built-ins](task-02-status-builtins.md) |
|
||||
| 03 | done | 2 | [Status surface shell](task-03-status-surface-shell.md) |
|
||||
| 04 | done | 3 | [Mobile Status entry points](task-04-mobile-status-entry-points.md) |
|
||||
| 05 | done | 3 | [Fixed-overlay audit](task-05-fixed-overlay-audit.md) |
|
||||
| 06 | done | 3 | [Plugin fixture desktop E2E](task-06-plugin-fixture-desktop-e2e.md) |
|
||||
| 07 | done | 4 | [Mobile Status E2E](task-07-mobile-status-e2e.md) |
|
||||
| 08 | done | 3 | [Attribution and public docs](task-08-attribution-public-docs.md) |
|
||||
| 09 | done | 5 | [Integration verification](task-09-integration-verification.md) |
|
||||
| 10 | done | 6 | [Portable status item order](task-10-portable-item-order.md) |
|
||||
| 11 | done | 6 | [Stable status item identities](task-11-stable-status-item-identities.md) |
|
||||
| 12 | done | 7 | [Reorder interaction and alignment](task-12-reorder-interaction-and-alignment.md) |
|
||||
| 13 | done | 8 | [Reorder docs, E2E, and verification](task-13-reorder-docs-e2e-verification.md) |
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
id: app-status-bar-01
|
||||
title: Stable plugin status slots
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Stable plugin status slots
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: plugin slots](../../specs/ui/app-status-bar.md#plugin-slots); [frozen API](../plugins/PLUGIN-API.md#app-status-bar-slots); existing chat-input typed wrapper.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/lib/plugins/types.ts`
|
||||
- `apps/web/lib/plugins/registry.ts`
|
||||
- `apps/web/components/plugins/plugin-slot.tsx`
|
||||
- `apps/web/components/plugins/plugin-slot.test.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-bar-plugin-slots.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-bar-plugin-slots.test.tsx`
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Export exact `AppStatusBarSlotProps`; left/right wrappers forward current context, presentation, density, and placement to their matching slots.
|
||||
2. Registry exposes stable owned registrations (`registrationId`, `pluginId`, `Component`) while old `getSlotComponents` callers remain compatible.
|
||||
3. Error boundaries use stable registration identity and owner/slot context; removing a failed first plugin cannot poison a healthy following plugin.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps && pnpm --filter @kandev/web test -- components/plugins/plugin-slot.test.tsx components/app-status-bar/app-status-bar-plugin-slots.test.tsx
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report changed files, red/green commands, compatibility result, and blockers. Mark task frontmatter and plan row `done` only after tests pass.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
id: app-status-bar-02
|
||||
title: Status built-ins and metrics gating
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Status built-ins and metrics gating
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: What](../../specs/ui/app-status-bar.md#what); current `TopbarMetrics`; canonical connection types; existing system-metrics subscription hook.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/components/app-status-bar/connection-status-item.tsx`
|
||||
- `apps/web/components/app-status-bar/connection-status-item.test.tsx`
|
||||
- `apps/web/components/system-metrics/status-surface-metrics.tsx`
|
||||
- `apps/web/components/system-metrics/status-surface-metrics.test.tsx`
|
||||
- `apps/web/components/system-metrics/topbar-metrics.tsx`
|
||||
- `apps/web/components/system-metrics/topbar-metrics.test.tsx`
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Connection item maps every canonical connection state and error to semantic visible, tooltip, and screen-reader output.
|
||||
2. Status metrics preserve current source selection, labels, formatting, thresholds, and details for compact/full bar and drawer presentations.
|
||||
3. Subscription is false when preference is disabled; on phone it is false until drawer opens. Primitives create no independent duplicate subscription.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps && pnpm --filter @kandev/web test -- components/app-status-bar/connection-status-item.test.tsx components/system-metrics
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report changed files, preference/presentation subscription matrix, tests, blockers, and task status.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: app-status-bar-03
|
||||
title: Mount status surface in application shell
|
||||
status: done
|
||||
wave: 2
|
||||
depends_on: [app-status-bar-01, app-status-bar-02]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Mount status surface in application shell
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: responsive/layout](../../specs/ui/app-status-bar.md#responsive-and-layout-contract); tasks 01–02; `AppShell`; legacy layout; current route-height patterns.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/components/app-status-bar/app-status-surface-provider.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-bar.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-drawer.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-bar.test.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-surface-provider.test.tsx`
|
||||
- `apps/web/src/app-shell.tsx`, `apps/web/app/layout.tsx`, `apps/web/app/globals.css`
|
||||
- `apps/web/src/task-detail-route.tsx`, `apps/web/app/stats/stats-page-client.tsx`, `apps/web/app/stats/loading.tsx`, `apps/web/components/plugin-page.tsx`
|
||||
- `apps/web/components/kanban/kanban-board.tsx`, `apps/web/components/task/task-page-content.tsx`, `apps/web/components/task/task-page-inner.tsx`
|
||||
- `apps/web/app/gitlab/gitlab-page-client.tsx`, `apps/web/app/github/github-page-client.tsx`, `apps/web/app/jira/jira-page-client.tsx`, `apps/web/app/tasks/[id]/kanban-task-shell.tsx`, `apps/web/app/tasks/tasks-page-client.tsx`
|
||||
- `apps/web/components/kanban/kanban-header.tsx`, `apps/web/components/kanban/kanban-header-mobile.tsx`, `apps/web/components/kanban/kanban-header-mobile.test.tsx`, `apps/web/components/task/task-top-bar.tsx`
|
||||
- `apps/web/components/settings/system-metrics-settings-card.tsx`
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Shell is `h-dvh` column; sidebar/route row owns remaining height; desktop/tablet status bar is exactly 24 px and in flow.
|
||||
2. Provider mounts bar or drawer, never both; built-ins and left/right plugin wrappers receive active route/workspace/task/session context.
|
||||
3. Header metric mounts are removed, setting copy says Status bar, and shell-owned route roots use parent height/local overflow.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps && pnpm --filter @kandev/web test -- components/app-status-bar components/kanban/kanban-header-mobile.test.tsx
|
||||
cd apps && pnpm --filter @kandev/web typecheck
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report height/scroll ownership changes, removed metric mounts, tests, visual-check result, blockers, and task status.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
id: app-status-bar-04
|
||||
title: Add mobile Status entry points
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: [app-status-bar-03]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Add mobile Status entry points
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: responsive/layout](../../specs/ui/app-status-bar.md#responsive-and-layout-contract); mobile UI language; task 03 provider trigger.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/components/kanban/mobile-menu-sheet.tsx`
|
||||
- `apps/web/components/task/mobile/session-mobile-bottom-nav.tsx`
|
||||
- `apps/web/components/task/mobile/session-mobile-layout.tsx`
|
||||
- `apps/web/components/settings/settings-layout-client.tsx`
|
||||
- `apps/web/components/page-topbar.tsx`
|
||||
- `apps/web/app/office/components/office-topbar.tsx`
|
||||
- Focused tests beside each changed surface.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Home, task, Settings, standard PageTopbar, and Office expose Status through native mobile controls; existing task navigation height and terminal offsets stay intact.
|
||||
2. Menus close before drawer opens; triggers have accessible labels and at least 44 px active target dimension.
|
||||
3. Normal routes have one Status drawer owner; full-bleed plugin-page guidance remains explicit rather than forcing host chrome.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps && pnpm --filter @kandev/web test -- components/kanban components/task/mobile components/settings/settings-layout-client.test.tsx components/page-topbar.test.tsx
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report changed entry points, close/open and focus behavior, rendered mobile check, tests, blockers, and task status.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
id: app-status-bar-05
|
||||
title: Offset fixed desktop overlays
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: [app-status-bar-03]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Offset fixed desktop overlays
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: responsive/layout](../../specs/ui/app-status-bar.md#responsive-and-layout-contract); task 03 CSS variable; current overlay z-index layers.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/components/toast-provider.tsx`
|
||||
- `apps/web/components/config-chat/config-chat-panel.tsx`
|
||||
- `apps/web/components/kanban/task-multi-select-toolbar.tsx`
|
||||
- `apps/web/components/kanban-with-preview.tsx`
|
||||
- `apps/web/components/review/walkthrough-overlay.tsx`
|
||||
- `apps/web/components/diff/walkthrough-floating-window.tsx`
|
||||
- Focused component/layout tests where coverage exists.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Each audited desktop fixed control clears the 24 px bar through `--app-status-bar-height` and retains its current phone `bottom: 0` behavior.
|
||||
2. Preview and walkthrough surfaces retain usable z-index relative to bar, drawer, and modal layers.
|
||||
3. No global fixed-element padding rule or unrelated phone offset is introduced.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps && pnpm --filter @kandev/web test -- components/kanban components/review components/diff
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report audited offsets/z-indexes, desktop and phone rendered checks, tests, blockers, and task status.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
id: app-status-bar-06
|
||||
title: Prove live plugin slots on desktop
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: [app-status-bar-01, app-status-bar-03]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Prove live plugin slots on desktop
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: plugin slots](../../specs/ui/app-status-bar.md#plugin-slots); tasks 01 and 03; plugin fixture and existing plugin E2E setup.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/backend/cmd/plugin-fixture/fixture-package/ui/bundle.js`
|
||||
- `apps/web/e2e/tests/plugins/plugins.spec.ts`
|
||||
- `apps/web/e2e/pages/session-page.ts`
|
||||
- Supporting fixture assertions only when needed.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Fixture registers visible left and right contributions and exposes presentation plus active-context values for host tests.
|
||||
2. Desktop E2E proves both contributions appear, receive `bar` props, disappear after disable, and reappear after enable without reload.
|
||||
3. Page object gains an app-status locator; existing chat-status locator semantics remain unchanged.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
make build-web
|
||||
cd apps/web && pnpm e2e:run tests/plugins/plugins.spec.ts
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report fixture behavior, E2E result/build command, locator compatibility, blockers, and task status.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
id: app-status-bar-07
|
||||
title: Prove mobile Status drawer parity
|
||||
status: done
|
||||
wave: 4
|
||||
depends_on: [app-status-bar-04, app-status-bar-06]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Prove mobile Status drawer parity
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec scenarios](../../specs/ui/app-status-bar.md#scenarios); mobile UI language; tasks 04 and 06; configured Pixel 5 project.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/e2e/tests/plugins/mobile-status-drawer.spec.ts`
|
||||
- Existing mobile helpers/page objects only when strictly needed.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Mobile E2E installs fixture, opens Status from Home, task bottom navigation, and PageTopbar route, then sees built-ins plus plugin contribution with `mobile-drawer` props.
|
||||
2. Test proves dismiss/focus return, 44 px trigger, safe-area clearance, one internal scroll owner, zero document horizontal overflow, and no persistent second footer.
|
||||
3. Existing task navigation still works after drawer dismissal.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
make build-web
|
||||
cd apps/web && pnpm e2e:run tests/plugins/mobile-status-drawer.spec.ts -- --project=mobile-chrome
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report mobile assertions, screenshot/rendered check, build/E2E result, blockers, and task status.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
id: app-status-bar-08
|
||||
title: Ship attribution and public records
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: [app-status-bar-03]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Ship attribution and public records
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: attribution](../../specs/ui/app-status-bar.md#attribution); exact public slot contract; Orca revision `d9d939a33b5858495ffb33489a952f1ac9293610` and MIT license.
|
||||
|
||||
## Files
|
||||
|
||||
- `docs/public/plugins-authoring.md`, `docs/public/plugins.md`, `docs/public/operations.md`, `docs/features.md`
|
||||
- `docs/decisions/0017-resource-metrics-sampling.md`
|
||||
- `apps/web/components/app-status-bar/app-status-bar.tsx`
|
||||
- `apps/web/scripts/generate-licenses.ts`, `apps/web/lib/types/system.ts`, generated `apps/web/generated/licenses.json`
|
||||
- `apps/web/e2e/tests/system/licenses-page.spec.ts`
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Public authoring docs show both slot registrations, exact props, one-presentation lifecycle, mobile adaptation, and full-bleed trigger responsibility.
|
||||
2. Operations/features and decision 0017 name Status bar/drawer semantics and phone drawer-only metric subscription.
|
||||
3. Shipped licenses manifest contains one pinned Orca source notice with full MIT text; implementation has one focused source comment; license E2E finds it.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps && pnpm --filter @kandev/web licenses:gen
|
||||
make build-web
|
||||
cd apps/web && pnpm e2e:run tests/system/licenses-page.spec.ts
|
||||
node --test scripts/validate-public-docs.test.mjs
|
||||
node scripts/validate-public-docs.mjs
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report documentation/decision changes, regenerated artifact status, attribution proof, tests, blockers, and task status.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
id: app-status-bar-09
|
||||
title: Integrate and verify app status surface
|
||||
status: done
|
||||
wave: 5
|
||||
depends_on: [app-status-bar-05, app-status-bar-07, app-status-bar-08]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
---
|
||||
|
||||
# Integrate and verify app status surface
|
||||
|
||||
## Inputs
|
||||
|
||||
Tasks 01–08; [feature spec](../../specs/ui/app-status-bar.md); task reports and changed-file map.
|
||||
|
||||
## Files
|
||||
|
||||
No planned source file. Update task/plan status and only fix verified integration defects in their owning files.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Desktop/tablet bar, phone drawer, connection, preference-gated metrics, plugin hot-toggle, chat-local status, fixed overlays, and mobile navigation meet spec scenarios together.
|
||||
2. No duplicate metrics subscription or plugin mount occurs across breakpoint/drawer transitions.
|
||||
3. Formatting, typecheck, tests, lint, focused desktop/mobile E2E, public-doc validation, and license proof pass in required order.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
make fmt
|
||||
make typecheck test lint
|
||||
cd apps/web && pnpm e2e:run tests/layout/app-status-bar.spec.ts tests/plugins/plugins.spec.ts
|
||||
cd apps/web && pnpm e2e:run tests/plugins/mobile-status-drawer.spec.ts -- --project=mobile-chrome
|
||||
cd apps/web && pnpm e2e:run tests/system/licenses-page.spec.ts
|
||||
node --test scripts/validate-public-docs.test.mjs
|
||||
node scripts/validate-public-docs.mjs
|
||||
```
|
||||
|
||||
## Output contract
|
||||
|
||||
Report all commands/results, manual viewport matrix, integration fixes, residual risks, and final task/plan statuses.
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
id: app-status-bar-10
|
||||
title: Portable status item order
|
||||
status: done
|
||||
wave: 6
|
||||
depends_on: []
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
spec: docs/specs/ui/app-status-bar.md
|
||||
---
|
||||
|
||||
# Portable status item order
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: data, API, and persistence](../../specs/ui/app-status-bar.md#data-api-and-persistence),
|
||||
[ADR 0041](../../decisions/0041-backend-owned-portable-user-settings.md), and
|
||||
[portable-order ADR](../../decisions/2026-07-21-portable-status-bar-order.md).
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/internal/user/models/models.go`
|
||||
- `apps/backend/internal/user/dto/dto.go`, `dto_test.go`
|
||||
- `apps/backend/internal/user/service/service.go`, `service_test.go`
|
||||
- `apps/backend/internal/user/store/sqlite.go`, `sqlite_test.go`
|
||||
- `apps/backend/internal/user/controller/controller.go`, `controller_test.go`
|
||||
- `apps/backend/internal/backendapp/boot_state_routes.go`
|
||||
- `apps/web/lib/types/http-user-settings.ts`, `backend.ts`
|
||||
- `apps/web/lib/state/slices/settings/types.ts`, `settings-slice.ts`
|
||||
- `apps/web/lib/ssr/user-settings.ts`, `user-settings.test.ts`
|
||||
- `apps/web/lib/ws/handlers/users.ts`, `users.test.ts`
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Existing user-settings GET/PATCH/event/boot flows round-trip
|
||||
`app_status_bar_order.left_item_ids/right_item_ids`; omission leaves the prior
|
||||
value unchanged and an absent value maps to empty arrays for host reconciliation.
|
||||
2. The preference is stored in the existing JSON blob with no relational schema,
|
||||
endpoint, browser-storage, or plugin-protocol addition.
|
||||
3. Backend and frontend tests cover empty/default, explicit replacement, omitted
|
||||
PATCH, reload, boot hydration, and live `user.settings.updated` mapping.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/backend && go test ./internal/user/... ./internal/backendapp/...
|
||||
cd apps && pnpm --filter @kandev/web test -- lib/ssr/user-settings.test.ts lib/ws/handlers/users.test.ts
|
||||
cd apps/web && pnpm run typecheck
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
None; this can run in parallel with task 11.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report the exact wire shape, persistence/omission behavior, files changed, red
|
||||
and green tests, and blockers. Mark the task and plan row done only after focused
|
||||
verification passes.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: app-status-bar-11
|
||||
title: Stable status item identities
|
||||
status: done
|
||||
wave: 6
|
||||
depends_on: []
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
spec: docs/specs/ui/app-status-bar.md
|
||||
---
|
||||
|
||||
# Stable status item identities
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: plugin slots](../../specs/ui/app-status-bar.md#plugin-slots),
|
||||
[portable-order ADR](../../decisions/2026-07-21-portable-status-bar-order.md),
|
||||
and existing owned slot registrations in `lib/plugins/registry.ts`.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/lib/plugins/registry.ts`, `registry.test.ts`
|
||||
- `apps/web/lib/plugins/types.ts`
|
||||
- `apps/web/components/plugins/plugin-slot.tsx`, `plugin-slot.test.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-bar-plugin-slots.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-bar-plugin-slots.test.tsx`
|
||||
- New pure status-item projection/reconciliation module and unit test beside the
|
||||
app-status-bar components.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Built-ins have reserved identities and every plugin contribution exposes a
|
||||
deterministic ordering identity derived from plugin ID, original slot, and
|
||||
slot-local registration ordinal; existing component/error-boundary behavior
|
||||
and `getSlotComponents` compatibility remain intact.
|
||||
2. Reconciliation filters duplicate active identities, retains unknown saved
|
||||
identities, restores re-enabled registrations, and appends newly seen items
|
||||
to their default side.
|
||||
3. The host treats one component registration as one opaque item and never
|
||||
introspects or reorders its rendered children.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps && pnpm --filter @kandev/web test -- lib/plugins/registry.test.ts components/plugins/plugin-slot.test.tsx components/app-status-bar/app-status-bar-plugin-slots.test.tsx components/app-status-bar
|
||||
cd apps/web && pnpm run typecheck
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
None; this can run in parallel with task 10.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report identity/reconciliation rules, compatibility evidence, files changed,
|
||||
red and green tests, and blockers. Mark the task and plan row done only after
|
||||
focused verification passes.
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
id: app-status-bar-12
|
||||
title: Reorder interaction and alignment
|
||||
status: done
|
||||
wave: 7
|
||||
depends_on: [app-status-bar-10, app-status-bar-11]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
spec: docs/specs/ui/app-status-bar.md
|
||||
---
|
||||
|
||||
# Reorder interaction and alignment
|
||||
|
||||
## Inputs
|
||||
|
||||
[Spec: What](../../specs/ui/app-status-bar.md#what), tasks 10-11, and the live
|
||||
geometry diagnosis: `border-top` currently leaves a 23 px content box and puts
|
||||
12 px plugin text at a half-pixel vertical position.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/components/app-status-bar/app-status-bar.tsx`, `.test.tsx`
|
||||
- `apps/web/components/app-status-bar/app-status-drawer.tsx` and focused tests
|
||||
- `apps/web/components/app-status-bar/app-status-bar-plugin-slots.tsx`
|
||||
- New reorder hook/controller and pure movement helpers beside the status bar
|
||||
- `apps/web/components/app-status-bar/connection-status-item.tsx`
|
||||
- `apps/web/components/system-metrics/status-surface-metrics.tsx`
|
||||
- `apps/web/lib/user-settings-sync.ts` or the existing queued-sync call pattern
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. The separator is inset/overlaid so all content uses the full 24 px alignment
|
||||
box; representative dot, plugin text, and metric roots share the same center
|
||||
at 1x scale.
|
||||
2. Cmd-drag on macOS and Ctrl-drag elsewhere reorders any built-in/plugin item
|
||||
horizontally across items and the spacer. Reorder begins only after a horizontal
|
||||
movement threshold, suppresses only the completed drag click, and never starts
|
||||
from plain mouse or touch input.
|
||||
3. A successful drop optimistically changes order and persists through the queued
|
||||
user-settings PATCH. Exhausted failure restores the confirmed order and reports
|
||||
an error. Plugin interactive children remain directly usable without nested
|
||||
host buttons or added tab stops.
|
||||
4. Phone renders the active saved left sequence followed by the active saved right
|
||||
sequence as vertical rows, creates no drag listeners, and preserves metrics
|
||||
subscription/focus/safe-area behavior.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps && pnpm --filter @kandev/web test -- components/app-status-bar components/system-metrics lib/user-settings-sync.test.ts
|
||||
cd apps/web && pnpm run typecheck
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 10 and 11.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report pointer-state rules, persistence/failure behavior, measured before/after
|
||||
geometry, phone projection, files changed, tests, and blockers. Mark the task and
|
||||
plan row done only after focused verification passes.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
id: app-status-bar-13
|
||||
title: Reorder docs, E2E, and verification
|
||||
status: done
|
||||
wave: 8
|
||||
depends_on: [app-status-bar-12]
|
||||
plan: docs/plans/app-status-bar/plan.md
|
||||
spec: docs/specs/ui/app-status-bar.md
|
||||
---
|
||||
|
||||
# Reorder docs, E2E, and verification
|
||||
|
||||
## Inputs
|
||||
|
||||
[App status bar spec](../../specs/ui/app-status-bar.md),
|
||||
[plugin spec](../../specs/plugins/spec.md), task 12, public plugin docs, and the
|
||||
real in-tree plugin fixture.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `docs/plans/plugins/PLUGIN-API.md`
|
||||
- `docs/public/plugins-authoring.md`, `docs/public/plugins.md`
|
||||
- `docs/public/operations.md`, `docs/features.md`
|
||||
- `apps/backend/cmd/plugin-fixture/fixture-package/ui/bundle.js`
|
||||
- `apps/web/e2e/tests/layout/app-status-bar.spec.ts`
|
||||
- `apps/web/e2e/tests/plugins/plugins.spec.ts`
|
||||
- `apps/web/e2e/tests/plugins/mobile-status-drawer.spec.ts`
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Public/frozen docs explain opaque registration items, default-side slot
|
||||
semantics, Cmd/Ctrl plus mouse drag, backend persistence, disabled-plugin
|
||||
restoration, and phone order; they do not promise keyboard/touch reordering.
|
||||
2. Real-host desktop E2E moves a fixture contribution across the spacer, reloads,
|
||||
restarts the backend if the fixture supports it, and verifies persisted order;
|
||||
plugin disable/enable restores position without a reload or duplicate mount.
|
||||
3. Mobile E2E verifies the corresponding vertical order, 44 px rows, one scroll
|
||||
owner, no drag affordance/listener effect, no persistent bar, and existing
|
||||
navigation/focus return.
|
||||
4. A 1x geometry assertion covers the separator and vertical centers. Simplify,
|
||||
strict review, docs validation, focused tests, and full verification are green.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/web && pnpm e2e:run tests/layout/app-status-bar.spec.ts tests/plugins/plugins.spec.ts
|
||||
cd apps/web && pnpm e2e:run tests/plugins/mobile-status-drawer.spec.ts -- --project=mobile-chrome
|
||||
node --test scripts/validate-public-docs.test.mjs
|
||||
node scripts/validate-public-docs.mjs
|
||||
make fmt
|
||||
VITEST_MAX_WORKERS=2 TMPDIR=/tmp make typecheck test lint
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 12.
|
||||
|
||||
## Output contract
|
||||
|
||||
Report desktop/mobile scenarios, persistence proof, geometry evidence, docs and
|
||||
review results, exact full-verification commands, and blockers. Mark this task,
|
||||
the plan, and the spec shipped only when every acceptance item passes.
|
||||
@@ -122,14 +122,15 @@ interface PluginRegistry {
|
||||
registerSettingsRoute(path: string, Component: React.ComponentType): void;
|
||||
|
||||
// Named slot injection. Host renders all components registered for a slot via
|
||||
// <PluginSlot name="..." props={...}/>. Initial slots: "task-sidebar",
|
||||
// <PluginSlot name="..." slotProps={...}/>. Initial slots: "task-sidebar",
|
||||
// "settings-nav", "main-nav-footer", "chat-input-actions", "chat-top-bar",
|
||||
// "main-top-bar", "plugin-settings".
|
||||
// "main-top-bar", "app-status-bar-left", "app-status-bar-right", and
|
||||
// "plugin-settings".
|
||||
// "chat-input-actions" renders icon buttons in the chat composer toolbar
|
||||
// (beside the model picker, mic, and send) and forwards
|
||||
// `{ taskId, taskTitle, activeSessionId, sessionIds }` as `slotProps`.
|
||||
// "chat-top-bar" renders status in the session top bar (beside the CPU/DB
|
||||
// metrics and the document/editor/debug controls) and forwards
|
||||
// "chat-top-bar" renders status in the session top bar (beside the
|
||||
// document/editor/debug controls) and forwards
|
||||
// `{ taskId, taskTitle, workspaceId, activeSessionId, sessionIds }`. Both
|
||||
// carry the active session plus every kandev session id on the task.
|
||||
// "main-top-bar" renders status/actions in the default app top bar on the
|
||||
@@ -155,6 +156,46 @@ interface PluginRegistry {
|
||||
}
|
||||
```
|
||||
|
||||
### App-status-bar slots
|
||||
|
||||
`app-status-bar-left` and `app-status-bar-right` are live named component slots.
|
||||
Each registration is one opaque status item; the slot chooses its default side,
|
||||
not a permanent side after user customization. Components receive
|
||||
`slotProps` with this exact shape:
|
||||
|
||||
```ts
|
||||
interface AppStatusBarSlotProps {
|
||||
placement: "left" | "right";
|
||||
presentation: "bar" | "mobile-drawer";
|
||||
density: "full" | "compact";
|
||||
pathname: string;
|
||||
activeWorkspaceId: string | null;
|
||||
activeTaskId: string | null;
|
||||
activeSessionId: string | null;
|
||||
}
|
||||
```
|
||||
|
||||
`placement` matches registration slot. `presentation` identifies the mounted host;
|
||||
the host mounts only one presentation at once. `density` is `full` on desktop and
|
||||
phone drawer, `compact` on tablet. `pathname` and active IDs are current-context
|
||||
hints, not entity payloads; read complete records from `host.store`.
|
||||
|
||||
Before customization, registration order is render order within each default side.
|
||||
Users can Cmd-drag on macOS or Ctrl-drag elsewhere with a mouse to move any item
|
||||
across the whole desktop/tablet bar. Kandev stores that order in backend user
|
||||
settings; disabled contributions keep their place and return there when enabled.
|
||||
Phone renders the saved left sequence followed by the saved right sequence, without
|
||||
dragging. There is no cross-plugin priority API, keyboard-arrow ordering, or touch
|
||||
ordering. Enable, disable, and uninstall update slots without reload. Each component
|
||||
is isolated by an owner-aware error boundary, so plugins must tolerate remounting and
|
||||
render a compact bar control or touch-usable drawer row for the supplied presentation.
|
||||
The host neither inspects nor separately reorders children inside a registration, and
|
||||
does not add a nested interactive wrapper.
|
||||
|
||||
A full-bleed plugin route (`topbar: false`) opts out of host chrome. It may mount
|
||||
the host-provided Status drawer trigger when its own chrome should expose status;
|
||||
otherwise status access is intentionally its responsibility.
|
||||
|
||||
## Registry internals (host side)
|
||||
|
||||
`apps/web/lib/plugins/registry.ts` holds a singleton `PluginRegistry` whose data
|
||||
|
||||
@@ -117,6 +117,7 @@ The launcher starts `agentctl`, performs a one-time nonce handshake, and supplie
|
||||
| `voice.openAIApiKey` | `KANDEV_VOICE_OPENAI_API_KEY` | empty | Server-side transcription fallback when browser speech recognition is unavailable. Empty disables the fallback and its endpoint returns unavailable. |
|
||||
| `features.office` | `KANDEV_FEATURES_OFFICE` | `false` in production | Experimental Office UI, routes, services, and automation. |
|
||||
| `features.plugins` | `KANDEV_FEATURES_PLUGINS` | `false` in production | Extensible plugin system: install/manage plugins, spawn plugin backends, and load native UI bundles. Loaded plugin code runs with backend privileges. |
|
||||
| `features.app_status_bar` | `KANDEV_FEATURES_APP_STATUS_BAR` | `false` in production | Opt-in global connection/host-metrics/plugin surface: bottom bar on tablet/desktop and Status drawer on phones. |
|
||||
|
||||
Do not infer security from `auth.jwtSecret`: setting it currently does not turn the local server into an authenticated public service. Office's JWT key has a narrower, active purpose. Store both active secrets and third-party API keys in your deployment secret manager; never commit them in `config.yaml`.
|
||||
|
||||
@@ -278,23 +279,25 @@ voice:
|
||||
features:
|
||||
office: false
|
||||
plugins: false
|
||||
app_status_bar: true
|
||||
```
|
||||
|
||||
Copying this entire file is unnecessary and can freeze old defaults in a deployment. Keep only deliberate overrides. On Windows, do not copy the Unix Docker host/path literals from this example.
|
||||
|
||||
## Runtime feature toggles
|
||||
|
||||
**Settings → System → Feature Toggles** manages three startup-time flags:
|
||||
**Settings → System → Feature Toggles** manages startup-time flags:
|
||||
|
||||
| Key | Environment lock | Production default | Effect |
|
||||
|---|---|---|---|
|
||||
| `features.office` | `KANDEV_FEATURES_OFFICE` | off | Experimental autonomous-agent Office surfaces and automation. |
|
||||
| `features.plugins` | `KANDEV_FEATURES_PLUGINS` | off | Extensible plugin system: install/manage plugins and load their backends and native UI bundles. |
|
||||
| `features.appStatusBar` | `KANDEV_FEATURES_APP_STATUS_BAR` | off | Global status bar on tablet/desktop and Status drawer entry on phones. Enabling changes visibility only. |
|
||||
| `debug.devMode` | `KANDEV_DEBUG_DEV_MODE` (also locked by explicit legacy/debug-message vars) | off | High-risk diagnostic endpoints and ACP frame logging. |
|
||||
|
||||
UI changes are persisted in the database and require a restart. An explicitly set environment value wins and locks the UI control. Otherwise a database override wins over the embedded profile/default. Resetting a toggle removes its database override.
|
||||
|
||||
The source checkout's `make dev` activates the embedded development profile, which enables Office, debug surfaces, ACP logging, and a mock agent. Installed `run`/desktop builds select the safe production profile unless the environment explicitly opts in. E2E mock variables and routes are test-only and must never be enabled on a public deployment.
|
||||
The source checkout's `make dev` activates the embedded development profile, which enables Office, debug surfaces, ACP logging, and a mock agent; the App status bar remains opt-in. Installed `run`/desktop builds select the safe production profile unless the environment explicitly opts in. E2E mock variables and routes are test-only and must never be enabled on a public deployment.
|
||||
|
||||
## Credentials and product settings
|
||||
|
||||
|
||||
@@ -226,9 +226,9 @@ After restart, verify `/health`, **System > About**, **System > Status**, the da
|
||||
|
||||
## Resource metrics
|
||||
|
||||
Configure sampling at **Settings > General > Appearance > Resource Metrics**. Defaults are CPU, memory, and disk percentage every five seconds, backend disk path `/`, and execution-environment collection off. Valid intervals are 1–300 seconds; at least one of CPU, memory, disk, CPU temperature, or load average remains selected.
|
||||
Configure sampling at **Settings > General > Appearance > Resource Metrics**. Defaults are CPU, memory, and disk percentage every five seconds, backend disk path `/`, and execution-environment collection off. Valid intervals are 1–300 seconds; at least one of CPU, memory, disk, CPU temperature, or 1-minute system load remains selected. System load is the average number of tasks running or waiting for CPU during the last minute; compare it with the host's CPU core count.
|
||||
|
||||
Collection starts only while at least one connected client shows metrics in a kanban or task topbar. Enabling execution metrics adds active Docker, SSH, and Sprites `agentctl` sources; execution disk sampling uses `/`. A provider hook also exists for remote Docker, but creating that runtime currently returns a not-implemented error. Missing platform APIs, container permissions, an invalid disk path, a disconnected executor, macOS/Windows temperature support, or Windows load-average support produce unavailable samples rather than quotas.
|
||||
Collection starts only while at least one connected client displays metrics in the global status bar. Phone clients subscribe only while their Status drawer is open. The built-in status surface renders the Kandev host source only. Enabling execution metrics also adds active Docker, SSH, and Sprites `agentctl` sources to the metrics stream for separately owned consumers such as plugins; execution disk sampling uses `/`. A provider hook also exists for remote Docker, but creating that runtime currently returns a not-implemented error. Missing platform APIs, container permissions, an invalid disk path, a disconnected executor, macOS/Windows temperature support, or Windows load-average support produce unavailable samples rather than quotas.
|
||||
|
||||
These metrics are lightweight UI observability. Set alerts, retention, CPU/memory limits, and disk quotas in the host, container platform, or external monitoring stack.
|
||||
|
||||
@@ -237,9 +237,15 @@ These metrics are lightweight UI observability. Set alerts, retention, CPU/memor
|
||||
**Settings > System > Feature Toggles** currently exposes:
|
||||
|
||||
- **Office mode** — experimental, medium risk, and off in the production profile by default.
|
||||
- **App status bar** — stable, low risk, and off in the production profile by default. Enabling it adds the desktop/tablet bar and phone Status entry after restart; disabling it again does not stop connections, metrics collection requested by other clients, or plugins.
|
||||
- **Debug mode** — high risk; enables diagnostic endpoints and agent-message logging that can contain sensitive content.
|
||||
|
||||
Both require restart. A value supplied explicitly by its environment variable locks the UI control; the debug toggle is also locked by explicit legacy/debug-message environment variables. Otherwise the UI stores an override in the database. The page can request restart only when the native local supervisor is available. A normal Unix `kandev` terminal launch is supervised; Desktop, a service, a container, a directly started backend, a deploy preview, or Windows requires a manual application restart.
|
||||
Each requires restart. A value supplied explicitly by its environment variable locks the UI control; the debug toggle is also locked by explicit legacy/debug-message environment variables. Otherwise the UI stores an override in the database. The page can request restart only when the native local supervisor is available. A normal Unix `kandev` terminal launch is supervised; Desktop, a service, a container, a directly started backend, a deploy preview, or Windows requires a manual application restart.
|
||||
|
||||
Status-bar layout is a separate per-user preference. Hold Cmd on macOS or Ctrl
|
||||
elsewhere while mouse-dragging an item to move it across the desktop/tablet bar.
|
||||
The backend preserves the layout across reloads and restarts; the phone Status
|
||||
drawer mirrors it as the saved left sequence followed by the saved right sequence.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@@ -303,7 +303,8 @@ interface PluginRegistry {
|
||||
registerSettingsRoute(path: string, Component: React.ComponentType): void;
|
||||
// Named slot injection. Initial slots: "task-sidebar", "settings-nav",
|
||||
// "main-nav-footer", "chat-input-actions", "chat-top-bar", "main-top-bar",
|
||||
// "plugin-settings" (see "Named slots" below).
|
||||
// "app-status-bar-left", "app-status-bar-right", and "plugin-settings"
|
||||
// (see "Named slots" below).
|
||||
registerComponent(slot: string, Component: React.ComponentType<{ slotProps?: unknown }>): void;
|
||||
// WS action handler, bridged into the existing lib/ws dispatch.
|
||||
registerWsHandler(action: string, handler: (payload: unknown) => void): void;
|
||||
@@ -395,6 +396,8 @@ plugins at once. Available slots:
|
||||
| `chat-input-actions` | Chat composer toolbar, beside the model picker, mic, and send button | `{ taskId, taskTitle, activeSessionId, sessionIds }` |
|
||||
| `chat-top-bar` | Session top bar, beside the CPU/DB metrics and the document/editor/debug controls | `{ taskId, taskTitle, workspaceId, activeSessionId, sessionIds }` |
|
||||
| `main-top-bar` | Default app top bar (Home / Kanban / Tasks), beside the CPU/DB metrics and the view/display controls | `{ workspaceId, workspaceLabel, currentPage }` |
|
||||
| `app-status-bar-left` | Default-left item in the global status surface | `AppStatusBarSlotProps` |
|
||||
| `app-status-bar-right` | Default-right item in the global status surface | `AppStatusBarSlotProps` |
|
||||
| `plugin-settings` | A plugin's own settings page (**Settings > Plugins > `<plugin>`**), at the top above the settings form | `{ pluginId, status }` |
|
||||
|
||||
`plugin-settings` is the one exception to "every plugin's component renders":
|
||||
@@ -467,8 +470,7 @@ example.
|
||||
### Session top bar
|
||||
|
||||
Register a `chat-top-bar` component to surface at-a-glance status in the
|
||||
session top bar, beside the first-party CPU/DB metrics and the
|
||||
document/editor/debug controls. The host passes the current context as
|
||||
session top bar, beside first-party document/editor/debug controls. The host passes the current context as
|
||||
`slotProps`:
|
||||
|
||||
```ts
|
||||
@@ -545,6 +547,53 @@ show.
|
||||
registry.registerComponent("plugin-settings", makeSettingsStatus(host));
|
||||
```
|
||||
|
||||
### Global Status bar
|
||||
|
||||
Register `app-status-bar-left` or `app-status-bar-right` for app-wide, compact
|
||||
status UI. Kandev mounts exactly one presentation: a 24 px bar on tablet and
|
||||
desktop, or an in-flow Status drawer section on phone. Keep bar content small;
|
||||
render a touch-usable row when `presentation` is `"mobile-drawer"`.
|
||||
|
||||
```js
|
||||
function StatusContribution({ slotProps }) {
|
||||
const { placement, presentation, activeTaskId } = slotProps ?? {};
|
||||
return host.jsx(
|
||||
"span",
|
||||
{ className: presentation === "bar" ? "truncate text-xs" : "block min-h-11 px-3 py-2" },
|
||||
`${placement}: ${activeTaskId ?? "no active task"}`,
|
||||
);
|
||||
}
|
||||
|
||||
registry.registerComponent("app-status-bar-left", StatusContribution);
|
||||
registry.registerComponent("app-status-bar-right", StatusContribution);
|
||||
```
|
||||
|
||||
Each contribution receives this exact context:
|
||||
|
||||
```ts
|
||||
type AppStatusBarSlotProps = {
|
||||
placement: "left" | "right";
|
||||
presentation: "bar" | "mobile-drawer";
|
||||
density: "full" | "compact";
|
||||
pathname: string;
|
||||
activeWorkspaceId: string | null;
|
||||
activeTaskId: string | null;
|
||||
activeSessionId: string | null;
|
||||
};
|
||||
```
|
||||
|
||||
The IDs are hints; use `host.store` for full records. Each component registration
|
||||
is one opaque item: Kandev does not inspect or separately reorder its children.
|
||||
The slot chooses the default side. A user can Cmd-drag (macOS) or Ctrl-drag
|
||||
(other desktop platforms) with a mouse across the full bar, and Kandev preserves
|
||||
that backend-owned order across reloads, restarts, and plugin disable/enable.
|
||||
Phone lists the saved left sequence followed by the saved right sequence and does
|
||||
not offer drag ordering. There is no keyboard-arrow, touch, or plugin-priority
|
||||
ordering API. Enable, disable, and uninstall update the live surface without a
|
||||
reload, and each contribution has its own error boundary. A full-bleed route
|
||||
(`topbar: false`) owns its own chrome; mount the host Status trigger there if that
|
||||
route should expose Status.
|
||||
|
||||
## Three integration patterns
|
||||
|
||||
Both example repos are full, working plugins — read them rather than
|
||||
|
||||
@@ -40,6 +40,35 @@ host-defined slots, including **icon buttons in the chat composer toolbar**
|
||||
(beside the model picker, mic, and send button), so an active plugin can add
|
||||
its own action right where you message an agent.
|
||||
|
||||
### Global Status contributions
|
||||
|
||||
Native UI bundles can also add compact, live status UI on every hosted route:
|
||||
|
||||
```js
|
||||
function StatusContribution({ slotProps }) {
|
||||
return host.jsx(
|
||||
"span",
|
||||
null,
|
||||
`${slotProps.presentation}: ${slotProps.activeTaskId ?? "no task"}`,
|
||||
);
|
||||
}
|
||||
|
||||
registry.registerComponent("app-status-bar-left", StatusContribution);
|
||||
registry.registerComponent("app-status-bar-right", StatusContribution);
|
||||
```
|
||||
|
||||
Each registration is one opaque item in Kandev's 24 px desktop/tablet status bar
|
||||
and phone Status drawer. The slot chooses its default side; users can Cmd/Ctrl plus
|
||||
mouse-drag items across the desktop spacer, and Kandev preserves their order in
|
||||
backend user settings. Phone shows the saved left sequence followed by the right
|
||||
sequence, with no drag ordering. `slotProps` includes
|
||||
`placement`, `presentation`, `density`, `pathname`, `activeWorkspaceId`,
|
||||
`activeTaskId`, and `activeSessionId`. Only one presentation mounts at once;
|
||||
adapt each contribution for both compact bar and touch-friendly drawer use.
|
||||
Kandev does not inspect or reorder children inside a contribution, and disabled
|
||||
plugins return to their saved position when re-enabled.
|
||||
Full-bleed routes that opt out of host topbar chrome own their Status trigger.
|
||||
|
||||
## Installing a plugin
|
||||
|
||||
The easiest way to install is from the in-app catalog — **Settings > Plugins >
|
||||
|
||||
|
Before Width: | Height: | Size: 122 KiB After Width: | Height: | Size: 126 KiB |
|
Before Width: | Height: | Size: 65 KiB After Width: | Height: | Size: 66 KiB |
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 66 KiB After Width: | Height: | Size: 74 KiB |
|
Before Width: | Height: | Size: 98 KiB After Width: | Height: | Size: 96 KiB |
@@ -119,6 +119,7 @@ Subscription quota tracking and per-agent cheap-model profile routing.
|
||||
| [slash-command-composer](ui/slash-command-composer.md) | shipped |
|
||||
| [entity-reference-composer](ui/entity-reference-composer.md) | draft |
|
||||
| [settings-manual-save](ui/settings-manual-save.md) | shipped |
|
||||
| [app-status-bar](ui/app-status-bar.md) | draft |
|
||||
| [mobile-task-navigation](ui/mobile-task-navigation.md) | shipped |
|
||||
| [task-layout-profiles](ui/task-layout-profiles.md) | draft |
|
||||
| [agent-message-comments](ui/agent-message-comments.md) | shipped |
|
||||
|
||||
@@ -19,8 +19,9 @@ restart required for startup-gated features such as Office mode and Debug mode.
|
||||
- Kandev adds a **Feature Toggles** settings page at
|
||||
`/settings/system/feature-toggles`.
|
||||
- The page shows user-facing runtime toggles, not every profile/env knob.
|
||||
- V1 exposes two user-facing toggles:
|
||||
- V1 exposes three user-facing toggles:
|
||||
- **Office mode** — enables the autonomous-agent Office surface.
|
||||
- **App status bar** — shows the global desktop/tablet status bar and the phone Status drawer entry. It is stable and off by default in production; enabling it changes visibility only.
|
||||
- **Debug mode** — enables local diagnostic/debug behavior, including agent
|
||||
message debug logs.
|
||||
- Office mode is marked **Experimental** and includes a concise description of
|
||||
@@ -259,6 +260,9 @@ especially Debug mode, to admins.
|
||||
- **GIVEN** Debug mode is off, **WHEN** the user enables it, **THEN** the page
|
||||
explains that local diagnostic endpoints and agent message debug logs will be
|
||||
enabled after restart.
|
||||
- **GIVEN** App status bar is using its default, **WHEN** the user opens Feature
|
||||
Toggles, **THEN** it appears off and explains that enabling it adds both the
|
||||
desktop/tablet bar and phone Status entry after restart.
|
||||
- **GIVEN** a toggle override exists, **WHEN** the user clicks `Reset to default`,
|
||||
**THEN** the override is removed and the page shows restart-required state if
|
||||
the effective runtime value differs from the restored default.
|
||||
@@ -276,6 +280,8 @@ especially Debug mode, to admins.
|
||||
|
||||
- A user can enable or disable Office mode from Feature Toggles and understand
|
||||
that restart is required.
|
||||
- A user can enable or hide the App status bar from Feature Toggles and
|
||||
understand that it applies after restart on every breakpoint.
|
||||
- Office mode clearly communicates experimental status and risk.
|
||||
- A user can enable or disable Debug mode without seeing duplicate agent-message
|
||||
debug toggles.
|
||||
|
||||
@@ -487,8 +487,14 @@ Mattermost-webapp model), not iframes. The full contract lives in
|
||||
`api.fetch`, a curated `@kandev/ui` subset, and the theme — so a plugin can build
|
||||
a page indistinguishable from first-party UI (e.g. a native `/jira` page).
|
||||
- **Registry surface:** `registerRoute(path, C)`, `registerNavItem(item)`,
|
||||
`registerSettingsRoute(path, C)`, `registerComponent(slot, C)` (slots:
|
||||
`task-sidebar`, `settings-nav`, ...), `registerWsHandler(action, fn)`.
|
||||
`registerSettingsRoute(path, C)`, `registerComponent(slot, C)` (including
|
||||
`app-status-bar-left` and `app-status-bar-right`), `registerWsHandler(action, fn)`.
|
||||
Status-slot components receive the exact `AppStatusBarSlotProps` contract in
|
||||
`PLUGIN-API.md`: current path/context plus placement and presentation. The host
|
||||
renders one responsive presentation at once — 24 px bar on tablet/desktop or
|
||||
phone Status drawer — so a plugin must tolerate remounting and adapt its own UI.
|
||||
A status slot chooses the contribution's default side; portable user order may
|
||||
move either contribution across the desktop spacer and determines drawer order.
|
||||
Registrations are namespaced per plugin and bulk-revoked on disable/uninstall.
|
||||
- **Isolation (v1):** only active, operator-installed plugins load; a failing
|
||||
bundle/`initialize` is caught and never breaks boot; slot components render behind
|
||||
@@ -647,6 +653,16 @@ restart with backoff (max 5 attempts, then `error`). Next successful handshake/`
|
||||
without `include_ephemeral`, **THEN** quick-chat ephemeral tasks are excluded from
|
||||
the results.
|
||||
|
||||
- **GIVEN** an active plugin registers `app-status-bar-left` or
|
||||
`app-status-bar-right`, **WHEN** Kandev switches between desktop/tablet and phone,
|
||||
**THEN** the plugin receives the exact slot props for the active bar or Status
|
||||
drawer presentation, and only that presentation is mounted.
|
||||
|
||||
- **GIVEN** a user has moved a registered status contribution, **WHEN** the plugin
|
||||
disables and later enables or Kandev restarts, **THEN** its deterministic
|
||||
plugin/slot/ordinal identity restores the saved position; the original slot
|
||||
remains its default side rather than overriding user order.
|
||||
|
||||
- **GIVEN** a plugin whose manifest declares `api_write: ["tasks"]` in this phase,
|
||||
**WHEN** it calls `CreateTask`, **THEN** kandev returns gRPC status `Unimplemented`
|
||||
(write RPCs are deferred), and declaring the capability has no other effect.
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
status: shipped
|
||||
created: 2026-07-21
|
||||
owner: kandev
|
||||
---
|
||||
|
||||
# App Status Bar
|
||||
|
||||
## Why
|
||||
|
||||
Kandev has useful app-wide state, but it is scattered through route headers. A small global surface makes connection and opted-in resource state consistently available without inventing new operational data or changing chat-local controls. Users can arrange that dense surface around what they scan most often and keep the layout across Kandev clients.
|
||||
|
||||
## What
|
||||
|
||||
- Desktop and tablet render one persistent **24 px**, in-flow bottom status bar across the app shell, including sidebar and route content. Desktop uses `full` density; tablet uses `compact` density.
|
||||
- Phone renders no persistent second bottom bar. Native route controls open one global **Status** inset bottom drawer, so it does not collide with task bottom navigation. The drawer mirrors the saved bar order vertically (saved left sequence, then saved right sequence), has a fixed header, one internal scroll body, safe-area clearance, 44 px action rows, and returns focus to its trigger.
|
||||
- The production-default-off `features.appStatusBar` runtime toggle controls both presentations. When disabled, neither the desktop/tablet bar nor phone Status entry points render. Enabling or disabling it requires a Kandev restart. It changes visibility only; it does not stop connections, metrics collection requested by other clients, or plugin execution.
|
||||
- Built-ins are limited to Kandev-owned state:
|
||||
- Canonical connection state and error from `state.connection.status` / `state.connection.error`, with a restrained semantic dot, the connected detail **Connected to Kandev**, accessible text, and readable failure detail.
|
||||
- Existing Kandev-host CPU/memory metrics, preserving current formatting, thresholds, and tooltips. The built-in surface does not render active-task, active-session, or executor metrics.
|
||||
- `userSettings.systemMetricsDisplay.showInTopbar` remains the persisted/wire compatibility key. User-visible copy calls this the Status bar setting; no migration or API break occurs.
|
||||
- Existing composer-local `ChatStatusBar` remains separate. Queue, PR, share, and next-step affordances stay with chat.
|
||||
- The connection indicator, complete metrics cluster, and each plugin component registration are individual status items. Holding Cmd on macOS or Ctrl on other platforms while dragging with the mouse reorders an item horizontally across the full bar, including across its flexible spacer.
|
||||
- A modified pointer press that does not become a horizontal drag preserves the contribution's normal click behavior. Plain mouse/touch interaction never starts reordering.
|
||||
- Modified dragging does not start browser text selection. The surface uses a clear grabbing state after the horizontal drag threshold is crossed.
|
||||
- Status item contents share one optical vertical center. The 1 px top separator does not reduce or offset the 24 px content alignment box.
|
||||
- The bar is a quiet technical strip rather than a collection of chips: its background, foreground, and separator use the same Kandev app-surface tokens as the sidebar, with deliberate space between opaque status items, Geist Sans for labels, Geist Mono plus tabular numerals for changing metrics, consistent icon weight, and no decorative elevation.
|
||||
|
||||
## Responsive and layout contract
|
||||
|
||||
- `AppShell` owns viewport geometry: an `h-dvh` column with a `min-h-0 flex-1` sidebar/route row, followed by the status surface. Shell-owned route roots use parent height and explicit local overflow rather than adding a second viewport height.
|
||||
- `--app-status-bar-height` is `1.5rem` on tablet/desktop and `0` on phone. It offsets only audited desktop `position: fixed` overlays; it is not global content padding. Phone bottom navigation and phone drop targets retain `bottom: 0`.
|
||||
- Exactly one presentation mounts at once: bar on tablet/desktop, drawer contents only while the phone drawer is open. This prevents duplicate plugin effects and metrics subscriptions at breakpoints. Disabling `features.appStatusBar` mounts neither.
|
||||
- Standard mobile headers, Home utility menu, task bottom navigation, Settings mobile menu, and Office topbar expose Status. A full-bleed plugin route (`topbar: false`) owns its chrome and must mount `AppStatusDrawerTrigger` if it wants status access.
|
||||
|
||||
## Plugin slots
|
||||
|
||||
Plugins may register components in two live slots: `app-status-bar-left` and `app-status-bar-right`. The slot chooses a contribution's default side; after user customization it is not a permanent placement guarantee. Desktop items may move across the spacer, and the phone drawer renders the resulting saved order vertically. Registry enable/disable changes render without reload; every contribution stays behind its own plugin error boundary.
|
||||
|
||||
```ts
|
||||
export interface AppStatusBarSlotProps {
|
||||
placement: "left" | "right";
|
||||
presentation: "bar" | "mobile-drawer";
|
||||
density: "full" | "compact";
|
||||
pathname: string;
|
||||
activeWorkspaceId: string | null;
|
||||
activeTaskId: string | null;
|
||||
activeSessionId: string | null;
|
||||
}
|
||||
```
|
||||
|
||||
IDs are current-context hints, not entity records; plugins read complete records from `host.store`. Default registration order is preserved until the user moves items. Each component registration is one opaque status item: the host does not inspect or separately order elements rendered inside it. No cross-plugin priority, manifest field, or sandbox change is introduced. Plugin UI must fit the supplied presentation and must not rely on one presentation remaining mounted.
|
||||
|
||||
## Metrics subscription
|
||||
|
||||
The existing setting is the first gate. If disabled, no status-surface metrics subscription exists. If enabled, tablet/desktop subscribe while their bar is mounted; phone subscribes only while Status drawer is open. The existing ref-counted WebSocket client owns reconnect behavior. The change must not leave header metrics mounted or create duplicate subscriptions.
|
||||
|
||||
## Data, API, and persistence
|
||||
|
||||
The surface reads existing Zustand connection, active-context, user-settings, system-metrics, and feature state. `features.appStatusBar` is a default-off, restart-required runtime flag exposed through the existing Feature Toggles page; `KANDEV_FEATURES_APP_STATUS_BAR` takes precedence and locks the control when set explicitly. The E2E profile enables it only for browser coverage. The phone drawer's open state is presentation-local and is not persisted. Existing `show_in_topbar` user-setting persistence remains authoritative.
|
||||
|
||||
The existing backend-owned user settings JSON stores the portable layout:
|
||||
|
||||
```ts
|
||||
type AppStatusBarOrder = {
|
||||
left_item_ids: string[];
|
||||
right_item_ids: string[];
|
||||
};
|
||||
```
|
||||
|
||||
The field name is `app_status_bar_order`. Omission keeps the existing value and an absent value uses the default order: connection plus left-slot registrations, flexible spacer, metrics plus right-slot registrations. Built-ins have reserved stable identities. A plugin identity is derived from its plugin ID, original slot, and zero-based registration ordinal within that plugin and slot; the serialized ID is host-owned and opaque to plugins. Temporarily unavailable identities remain stored but are not rendered, so a disabled plugin or hidden metrics cluster returns to its saved position. A newly seen identity appends to its default side. Successful PATCHes survive frontend/backend restarts and propagate through `user.settings.updated`; last successful write wins across clients. See [ADR-2026-07-21-portable-status-bar-order](../../decisions/2026-07-21-portable-status-bar-order.md).
|
||||
|
||||
No new relational schema, endpoint, WebSocket action, plugin manifest field, or plugin protocol is added. The existing user-settings PATCH/event contracts carry the order, and the existing runtime-flags persistence and `/api/v1/features` response carry the visibility setting.
|
||||
|
||||
The only public API addition is `registerComponent("app-status-bar-left" | "app-status-bar-right", Component)` with the exact slot props above. Plugin registration ownership, enable/disable lifecycle, and error isolation reuse the existing registry.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- Missing metrics snapshot renders a recognizable unavailable/loading state; it does not create a fallback fetch or provider.
|
||||
- Connection errors remain inspectable through accessible detail; reconnecting is not misrepresented as connected.
|
||||
- A failed plugin contribution is contained by its own boundary; remaining contributions and first-party state remain usable.
|
||||
- If Status drawer closes during a metrics update or breakpoint changes, the inactive presentation unmounts and releases only its own ref-counted subscription.
|
||||
- Invalid, duplicate, or temporarily unavailable saved item identities never mount duplicate UI. The host normalizes active items once and retains unavailable identities for later plugin re-enable.
|
||||
- If an order write fails after the standard user-settings retries, the UI restores the last confirmed order and reports the save failure; it does not create a browser-storage fallback.
|
||||
|
||||
## Accessibility
|
||||
|
||||
- Connection state is programmatically named and changes are announced without relying on color or hover.
|
||||
- Bar details remain keyboard reachable with visible focus and accessible labels; reorder wrappers do not introduce nested interactive controls or extra tab stops.
|
||||
- Reordering is an optional pointer customization activated only by Cmd/Ctrl plus mouse drag. Keyboard-arrow and touch reordering are not part of this interaction; content remains usable in its current order without reordering.
|
||||
- Phone Status entry points and drawer rows meet the 44 px touch target expectation. Drawer dismissal supports Escape/back, outside dismissal, and focus return.
|
||||
- The bar and drawer avoid document horizontal overflow; plugin content truncates or scrolls within its owning surface rather than widening it.
|
||||
|
||||
## Attribution
|
||||
|
||||
Visual interaction is a clean Kandev adaptation of Orca's public status-bar ideas, not a source transplant. The implementation carries one focused source comment and ships a third-party notice naming Orca, pinned revision `d9d939a33b5858495ffb33489a952f1ac9293610`, repository URL, and full MIT notice through Kandev's generated licenses manifest. A licenses-page test proves that notice is visible.
|
||||
|
||||
## Scenarios
|
||||
|
||||
- **GIVEN** the feature is enabled on a desktop or tablet route, **WHEN** it opens, **THEN** one 24 px app status bar remains at its bottom and route/sidebar content use the remaining height without a new page scrollbar.
|
||||
- **GIVEN** metrics preference enabled, **WHEN** a desktop/tablet status bar mounts, **THEN** existing Kandev-host metrics appear there, task/session/executor metrics do not, and no route header still renders metrics.
|
||||
- **GIVEN** metrics preference disabled, or a phone Status drawer closed, **WHEN** the app runs, **THEN** no system-metrics WebSocket subscription is held by this feature.
|
||||
- **GIVEN** the feature is enabled for a phone user, **WHEN** they choose Status from a native entry point, **THEN** the drawer shows the same built-ins and plugin regions; dismissing it restores focus and leaves no persistent status bar.
|
||||
- **GIVEN** an administrator disables **App status bar** in Feature Toggles and restarts Kandev, **WHEN** a route renders on any breakpoint, **THEN** the bar/drawer and native Status triggers are absent while the rest of the shell remains available.
|
||||
- **GIVEN** a plugin registered for either status slot, **WHEN** it enables or disables, **THEN** its contribution appears or disappears without reload in the active presentation. A failed contribution does not suppress a following healthy one after registrations change.
|
||||
- **GIVEN** a desktop/tablet bar, **WHEN** the user holds Cmd/Ctrl and mouse-drags a built-in or plugin contribution across another item or the spacer, **THEN** the item moves horizontally, normal click activation is suppressed only after a drag begins, and the new side/order survives reload and backend restart.
|
||||
- **GIVEN** a modified mouse press begins on status text, **WHEN** the pointer crosses the drag threshold, **THEN** the item enters its dragging state without selecting text in the bar.
|
||||
- **GIVEN** a saved order containing a disabled plugin contribution, **WHEN** that plugin enables again, **THEN** its stable item returns to the saved position without remounting any other item twice.
|
||||
- **GIVEN** a saved desktop order, **WHEN** Status opens on phone, **THEN** the drawer renders the saved left sequence followed by the saved right sequence as vertical 44 px rows and offers no drag interaction.
|
||||
- **GIVEN** the bar at a 1x device scale, **WHEN** text, dots, and metric icons render beside one another, **THEN** they share the same vertical content center and the top separator does not create a half-pixel offset.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- New provider-usage, account, ports, SSH, process-management, update-check, billing, or metrics backend built to fill the bar.
|
||||
- Changing `ChatStatusBar` or moving its chat-local controls.
|
||||
- A phone persistent bar, plugin slot priority system, plugin manifest/protocol change, plugin JavaScript sandbox, keyboard-arrow reordering, or touch reordering.
|
||||
- Broad global fixed-position padding; only audited desktop overlays receive the height offset.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
[App status bar plan](../../plans/app-status-bar/plan.md)
|
||||