--- status: current system: ui requirements: - REQ-UI-SIDEBAR-CUSTOMIZATION-001 - REQ-UI-SIDEBAR-CUSTOMIZATION-002 - REQ-UI-SIDEBAR-CUSTOMIZATION-003 - REQ-UI-SIDEBAR-CUSTOMIZATION-004 - REQ-UI-SIDEBAR-CUSTOMIZATION-005 --- # Sidebar Customization Design ## Ownership and existing boundaries UI owns navigation composition and personal layout. Automation activity, canvas lifecycle, plugin registrations, and workspace access keep their owners. This extends the portable settings pattern from [workspace sidebar task views](workspace-sidebar-task-views.md). `AppSidebarModeNav` currently assembles fixed sections. `AppSidebarPrimaryNav` owns Home and New Task. `TasksSection` owns the remaining scroll space. `AppSidebarSettingsMode` temporarily replaces navigation on settings routes. `MobileMenuSheet` and `AppNavSections` compose the phone menu separately. Static links already use `lib/navigation/core-destinations.ts`, `resolveDestinations`, and plugin registrations. Reuse these identities and availability rules. Do not create another table of hrefs or change global catalog order to implement a personal layout. ## Requirement mapping | Requirement | Design sections | | --- | --- | | REQ-UI-SIDEBAR-CUSTOMIZATION-001 | Persistence; Composition | | REQ-UI-SIDEBAR-CUSTOMIZATION-002 | References and catalog; Composition | | REQ-UI-SIDEBAR-CUSTOMIZATION-003 | Activity | | REQ-UI-SIDEBAR-CUSTOMIZATION-004 | Persistence; Editor; Recovery | | REQ-UI-SIDEBAR-CUSTOMIZATION-005 | Phone; Verification | ## Persistence Proposed new contracts are marked here; they are not existing symbols. Add `SidebarLayoutsByWorkspace` to `internal/user/models.UserSettings`, exposed as `sidebar_layouts_by_workspace`. Store entries in existing user-settings JSON, using the current settings revision and CAS transaction. No new table is needed. A proposed `SidebarLayout` contains `version: 1`, `revision`, and ordered `nodes`. Each node has a stable client-generated ID and a `visible` boolean: - `builtin`: a registered layout entry ID, such as `home` or `integrations`. - `plugin`: an owner-qualified destination ID for an original plugin nav entry. - `shortcuts`: a nonempty display name and ordered shortcut references. A shortcut has an instance ID and a discriminated target: `destination {id}`, `host_action {id}`, `canvas {id}`, or `automation {id}`. Names and icons for targets resolve at runtime; they are not copied into settings. Section names are user data. Never serialize React nodes, callbacks, tokens, provider credentials, resource content, or arbitrary executable strings. The proposed PATCH object is `sidebar_layout_state` with explicit `workspace_id`, `expected_revision`, and a complete `layout`; `layout: null` means reset. Omission leaves settings unchanged. Reject whole-map replacement. Resolve the authenticated user through the existing user-settings path and validate workspace access using the scoped-sidebar service dependency. Each CAS retry reads fresh settings and changes only the addressed workspace. Compare its layout revision; a mismatch returns a conflict without changing it. Keep a revision tombstone after reset to reject pre-reset delayed writes. Concurrent changes to unrelated settings or another workspace remain intact. Validate the full replacement atomically. Reject unsupported schema versions, unknown node/target kinds, invalid IDs, and protected built-in nodes. Retain syntactically valid unresolved resource and plugin references. Implementation limits: 20 shortcut groups per workspace, 20 shortcuts per group, 100 total shortcuts, and 1-60 Unicode code points per trimmed section name. Reject duplicate node/instance IDs and duplicate targets within one group. The same target may appear in different groups. Mirror validation in the editor; the server remains authoritative. An absent layout resolves to a backend-owned canonical default preserving current ordering and visibility. No legacy import is needed: task views and collapse preferences are separate. The canonical layout skeleton and version must reach the client with complete settings; do not invent defaults in components. Extend model, DTO, PATCH mapping, store serialization/deserialization, HTTP, boot payload, WebSocket projection, and `mapUserSettingsData` in `lib/ssr/user-settings.ts`. Expose only accessible workspace entries. Add settings-catalog discovery and agent-settings schema coverage through existing domain machinery. Do not create a parallel API or MCP-specific preference implementation. ## References and catalog Create proposed `lib/sidebar/layout-types.ts`, `layout-operations.ts`, and `shortcut-catalog.ts`. The catalog adapts existing resolved navigation data, not a second navigation manifest. Preserve `pluginDestinationId` ownership: `plugin::`. Include eligible registered main, integrations, and sidebar-footer plugin links. Their original positions can be hidden independently of pinned references. Unregistered slot components are not selectable. No plugin SDK extension is required to pin registered links. GitHub resolves through existing integration availability. Slack resolves only through an installed plugin registration. Resource adapters resolve active workspace canvases and automations by ID. Canvas eligibility follows `isActiveWorkspaceCanvas`; use `canvasHref` and existing automation history routes. Access or feature gates always take precedence over personal visibility. Captured workspace identity accompanies picker loads and action callbacks; late results cannot cross workspace scope. The host action allowlist initially includes New Task, Quick Chat, and Quick Terminal through existing launchers. Each invocation remains an explicit click. No action transport is persisted. Pinned automations only navigate to history. Settings holds a searchable catalog grouped by Built-in, Plugins, Canvases, and Automations. Availability and resource loading have explicit pending/error states. A failed catalog load is not treated as an empty resource collection. ## Composition Apply layout ordering as a surface-specific projection after destination resolution. Leave command palette ordering, feature eligibility, startup page, brand links, and settings navigation unchanged. Defaults preserve existing order. Newly registered plugin destinations append in their canonical location until customized. Retain hidden entries rather than treating omission as hidden. Unknown future node kinds must not be written back by an older editor. On desktop, render optional nodes above the fixed Tasks region in regular workspaces. Keep Office-only regions in their existing order; apply common customizable nodes before them. Required Inbox/Needs you entries retain their existing mode and feature gates and cannot be hidden in this editor. Create proposed `ShortcutSection` with sibling disclosure and action controls. Do not nest links/buttons inside the disclosure button. Name and chevron toggle only expansion. Header icons activate only their target. The expanded list uses the same resolved array, including order, identity, unavailable state, and status. Use existing section collapse mechanics with workspace/group-qualified IDs. Collapse remains device-local and separate from portable layout revisions. The header reserves the name/disclosure area and fits as many 28px icon controls as remaining width permits. Four icons fit the ordinary expanded desktop width. Extra icons enter a More menu; they remain listed when expanded. Overflow never shrinks controls below their applicable pointer size. Full names appear on hover/focus and in accessible labels. In the 56px rail, render one group launcher opening a labelled menu of all shortcuts. These menus use existing responsive primitives. Empty groups remain visible as named disclosures with empty content; the settings editor supplies Add shortcut. Never add or run anything implicitly. The agreed icon header and labelled expanded list are fixed interaction choices. An optional icon-plus-label header style is deferred: it would crowd this layout. ## Activity Reuse `automationState(automation, openRuns)` from `automation-rows.ts`. The current source returns running, idle, or paused. Running wins when open runs exist, even if the automation is disabled. Preserve these meanings; do not map paused to failed or invent waiting/error lifecycle states. Reuse the bubble geometry of `QuickChatActivityIndicator`: an overlaid circular marker with a background ring. Extract a presentation-only primitive if needed; keep Quick Chat selectors, test IDs, and unread semantics unchanged. Automation markers use existing state colors: blue running, green idle, muted paused. No new animation is needed. A tooltip and accessible name provide state text; expanded rows also show the label. Unknown/loading/error is visually distinct from all three domain states and never passes through an idle fallback. Use one proposed workspace activity controller per mounted navigation surface, shared by all shortcut groups and the visible automation section. Adapt existing `useWorkspaceAutomations`, `useAutomationSummaries`, and `useLiveRefresh`. Do not create one request loop per button. Poll summaries every ten seconds while at least one pinned automation is visible, including folded groups and rail/overflow launchers. Poll idle pins too, so later starts become visible. Refresh immediately on mount, workspace change, reconnect, and return to visible navigation. Pause when the document or phone menu is hidden and no consumer needs activity. Invalidate/refresh automation definitions for pause changes too. Keep request generations and workspace identity. Failed refreshes show unknown status rather than an authoritative stale running/idle marker; retry at the next refresh or through the normal recovery control. Successfully loaded summaries with no record may use existing never-run semantics. An unloaded collection may not. Aggregate a running bubble on More and collapsed-rail group launchers when any shortcut behind them is running. Their accessible text identifies activity; opening the menu shows each resource's state. ## Editor Add an Appearance entry opening `/settings/sidebar` and register it in SPA routes and settings discovery. This dedicated page has the workspace name, explanatory copy, layout nodes, a draft preview, and Restore defaults. Register one workspace-bound contributor with `useSettingsSaveContributor`. Use the existing floating Save changes and discard/navigation flows; no page-local save buttons. The live sidebar retains saved state while the editor previews drafts locally. Rows have visibility switches and reorder handles. Shortcut groups additionally have a name, ordered contents, Add shortcut, remove, and move-to-group controls. Use the repository's existing drag-and-drop dependency and keyboard sensors. Explicit Move up/down and Move to group controls provide an alternative. Do not implement drag-to-execute or navigation while dragging. Capture the workspace and base layout revision on edit. A conflicting save keeps the draft and offers reload/discard or deliberate reapplication after the latest revision is loaded. Do not retry by silently overwriting another client. A workspace switch invokes existing dirty-state protection; after discard or successful save, rebind the editor. Stale callbacks cannot write the new scope. ## Recovery Unavailable targets keep their position with a generic icon and localized Unavailable label. A disabled menu item explains the missing capability without showing cached private resource details. They can be removed or replaced in settings. Temporary plugin loading is distinguished from completed registration without a matching target. Returning resources re-resolve the saved identity. Save failures retain draft and authoritative saved layout. Unsupported schema versions preserve stored data and offer refresh rather than destructive repair. Malformed stored known-version data falls back to defaults for display without overwriting the stored entry on read; surface a reset/recovery notice in settings. No-workspace state disables editing and never displays a previous workspace's resource names. Reset remains an explicit saved operation. ## Phone Nearest exemplar: `MobileMenuSheet`, with an inset Drawer, fixed header, and one internal scroll region. Reuse this navigation surface through `AppNavSections`. A phone group uses a full-width disclosure row, followed by a compact icon strip; expansion reveals labelled shortcuts beneath it. The extra line preserves 44px hit targets and name space. More contains overflow, without horizontal page scroll. The saved-layout renderer places visible Home and quick actions before the existing `afterPrimary` task/local-navigation outlet. Remaining visible nodes follow that outlet in saved relative order. This is an effective phone projection; neither layout revisions nor desktop ordering change. Wider sheet consumers retain their existing ordering. Required inbox destinations remain reachable. Regular phone workspaces use the Tasks heading plus for built-in task creation; Office and explicit custom New Task shortcuts keep their existing launch controls. Built-in resource sections do not use the custom group's icon-strip presentation. Reuse `MobileAutomationsSection` and `MobileIntegrationsSection` for their labelled disclosures, availability, loading/retry, and setup paths. Saved automation rows consume the existing catalog and activity controller through the disclosure body slot, avoiding a second polling loop. Saved integration plugin nodes retain their own ordering and visibility, so the built-in integration section excludes those independently rendered plugin links. Canvases use a labelled phone disclosure and the shared catalog, including loading/error state and workspace settings. Custom mixed groups retain direct shortcuts and automation activity, with an explicit chevron on the disclosure. The shared app drawer remains the only vertical scroller. The editor uses direct full-page settings navigation because it is a multi-step editing task. Show the layout list, then a focused section editor, then a picker; Back returns to the draft without losing changes. Retain the shared save control and guard. Use `100dvh`, one active scroll owner, and safe-area padding. Shared operations and state power both presentations. No desktop preference is rewritten because the phone needs a different composition or overflow count. ## Verification and documentation Tests cover validation, scoped CAS and revisions, reset, default projection, reference resolution, layout operations, fetch readiness, delayed callbacks, editor behavior, navigation rendering, and activity states. The dedicated desktop and phone sidebar customization E2E files cover the mixed four-shortcut editing flow, saved navigation, phone composition, and a pinned automation status transition. Existing desktop and phone E2E regression suites continue to cover the established automation list, settings navigation, phone access, and 44px touch sizing. Broader overflow and plugin lifecycle scenarios remain represented by the named unit/component suites rather than unrun browser files. Implementation updates `docs/public/use-kandev.md` with navigation, hide-versus-disable semantics, persistence, and recovery. The public guide and coverage manifest are validated with the documentation checks. ## Related decisions - [Portable settings](../../../decisions/0041-backend-owned-portable-user-settings.md) - [Navigation manifest boundaries](../../../decisions/2026-08-04-navigation-manifest-boundaries.md) This design applies existing ownership rules. The preference model and local tradeoffs fit this document; no additional ADR is required. ## Delivery - [Plan and work orders](../../../plans/sidebar-customization/plan.md) - [Mobile saved navigation repair](../../../plans/mobile-saved-navigation/plan.md)