EPIC: Rebuild the Symbolics WebUI without sacrificing plugin-level UI control #161

New issue

Open

opened 2026-09-09 15:05:16 +00:00 by nsaspy · 0 comments

nsaspy commented 2026-09-09 15:05:16 +00:00

Owner

Copy link

Goal

Design and implement a modern Agent Zero WebUI while preserving the defining capability that plugins can materially extend and modify the interface.

This is not just a visual reskin. The current WebUI has accumulated strong plugin contracts (<x-extension>, JS extension hooks, <x-component>, modal/surface APIs, runtime extension manifests) but the core shell/navigation does not scale cleanly to large chat collections and is difficult to evolve as a coherent product surface.

Design principles

Modern core experience

• clean, dense-but-readable visual hierarchy
• responsive desktop/mobile shell
• first-class keyboard navigation/command palette
• strong chat/task/project navigation
• clear running/paused/error/status treatment
• modern settings/model/profile/project surfaces
• accessibility and reduced-motion support
• consistent design tokens and primitives rather than component-local one-offs

Plugins remain first-class

A redesign must not turn plugins into a few decorative buttons. Plugins need a documented, stable ability to contribute to or replace meaningful regions of the UI.

Preserve existing extension IDs/hooks through a compatibility layer and define a public slot/surface contract for at least:

• global navigation / command palette entries
• chat navigator rows, badges, filters, groups, actions and context menus
• task navigator rows/actions
• top bar / status rail
• composer controls
• message/process-step renderers and decorations
• right-side/work surfaces
• modals/settings pages
• themes/design-token overlays where safe
• plugin-owned full surfaces/pages

Plugins should be able to register capabilities declaratively from the existing runtime extension manifest rather than monkey-patching core DOM.

Performance is an API requirement

Plugin extension points on large lists or streaming DOM paths need explicit performance contracts. A plugin must not force the core to re-sort 10,000 chats once per row or rescan the whole document on every token.

Compatibility

Current contracts under webui/AGENTS.md and webui/js/AGENTS.md are migration constraints:

• existing <x-extension id="..."> breakpoints
• callJsExtensions() hook names/mutable contexts
• <x-component> loader
• modal/surface APIs
• same-origin/offline-capable assets
• Alpine store compatibility for existing bundled/third-party extensions

Do not require all plugins to rewrite on day one. If the core shell architecture changes, ship a compatibility adapter and explicit deprecation/version policy.

Framework choice is secondary to the plugin ABI. Do not casually rewrite to React/Vue/etc. if doing so strands the existing extension ecosystem; any framework change requires an ADADR design proving compatibility, performance, and migration.

2026-08-24 full-UI redesign directive

This epic is now a whole-product visual and interaction redesign, not incremental cleanup.

Use Impeccable-style design discipline as the working quality bar: establish clear product hierarchy first, avoid generic dashboard/card soup, use deliberate typography/spacing, keep decoration subordinate to function, then run explicit critique/audit/hardening/polish passes before calling a surface done.

Product direction

Symbolics should feel like a serious symbolic-agent workstation rather than an upstream Agent Zero skin.

The default desktop composition should prioritize:

1. active conversation/work surface;
2. agent/run state and symbolic context state;
3. project/chat/task navigation;
4. tools/artifacts/debug surfaces only when needed.

Do not permanently consume large areas for controls that are rarely touched. Prefer compact rails, command surfaces, progressive disclosure, and contextual panes.

Required redesign surfaces

• global shell and responsive layout
• left navigation/chat/task hierarchy
• welcome/new-chat surface
• chat message/process rendering
• composer/input controls
• top/status rail
• project/profile/model selectors
• settings navigation and forms
• plugin management/configuration
• system jobs/tasks
• memory/knowledge surfaces
• right canvas/work surfaces
• errors/retries/paused/running states
• empty/loading/offline states
• mobile layout used by Android WebView

Symbolics-specific status

The UI should surface symbolic runtime state without flooding the user with implementation detail.

Useful inspectable status includes:

• Prolog-RLM ready/degraded/off
• current provider/model
• current context budget and actual projected tokens
• active symbolic tools/capabilities
• live task/run state
• memory KB status
• debug I/O capture state from #59

Detailed traces belong behind an inspector/developer surface, not the main chat chrome.

Developer/debug integration

Developer Settings must include the raw debug capture controls from #59 and make the danger/state visually unambiguous. When raw I/O capture is enabled, show a persistent but compact indicator so the user cannot forget sensitive logging is active.

Accessibility and interaction quality

• keyboard-first navigation for desktop
• visible focus treatment
• sensible tab order
• WCAG-aware contrast
• reduced-motion support
• no hover-only critical controls
• minimum touch targets on mobile
• responsive behavior verified at phone, tablet, laptop and wide desktop sizes

Design verification

A substantial redesign slice is not done from code inspection alone. Capture/render the actual UI and perform a design QA pass against the intended hierarchy and states. Validate both dark and light modes and at least one narrow mobile viewport.

Architecture work

Use the repository ADADR control plane (roam/, once #17 lands) to define:

• UI shell ownership and state boundaries
• slot/surface registry
• extension capability/version negotiation
• event/state contracts
• performance budgets
• theme/design-token contract
• backwards-compatibility adapter
• failure isolation for broken plugins
• testing strategy for core + plugin combinations

Acceptance

• Modern shell/design spec approved through ADADR.
• Existing public/bundled extension points are inventoried before redesign.
• Stable versioned plugin UI capability/slot registry exists.
• Legacy x-extension / JS hooks continue working through documented compatibility or are migrated with an explicit supported path.
• Plugins can add/replace meaningful UI surfaces, not just append controls.
• One broken/slow plugin cannot permanently break initial shell rendering; failures are isolated/diagnosable.
• UI has defined frame/render/startup budgets and large-chat benchmarks.
• Desktop and mobile accessibility gates exist.
• Core surfaces share a consistent tokenized design system.
• Modern chat navigation work integrates with the large-chat performance/catalog issues rather than rendering the full corpus.
• Main shell, welcome screen, chat, composer, settings and plugin surfaces are visually redesigned as one coherent product.
• Symbolics runtime/context/memory state is inspectable without cluttering the main workspace.
• Debug I/O enabled state from #59 is visible and cannot be forgotten accidentally.
• Dark/light and desktop/mobile states are visually QA'd before merge.
• Existing plugin UI compatibility remains a release gate.

---

Mirrored from lost-rob0t/a0-symbolics#23 via tracker sync.

## Goal Design and implement a modern Agent Zero WebUI while preserving the defining capability that plugins can materially extend and modify the interface. This is not just a visual reskin. The current WebUI has accumulated strong plugin contracts (`<x-extension>`, JS extension hooks, `<x-component>`, modal/surface APIs, runtime extension manifests) but the core shell/navigation does not scale cleanly to large chat collections and is difficult to evolve as a coherent product surface. ## Design principles ### Modern core experience - clean, dense-but-readable visual hierarchy - responsive desktop/mobile shell - first-class keyboard navigation/command palette - strong chat/task/project navigation - clear running/paused/error/status treatment - modern settings/model/profile/project surfaces - accessibility and reduced-motion support - consistent design tokens and primitives rather than component-local one-offs ### Plugins remain first-class A redesign must **not** turn plugins into a few decorative buttons. Plugins need a documented, stable ability to contribute to or replace meaningful regions of the UI. Preserve existing extension IDs/hooks through a compatibility layer and define a public slot/surface contract for at least: - global navigation / command palette entries - chat navigator rows, badges, filters, groups, actions and context menus - task navigator rows/actions - top bar / status rail - composer controls - message/process-step renderers and decorations - right-side/work surfaces - modals/settings pages - themes/design-token overlays where safe - plugin-owned full surfaces/pages Plugins should be able to register capabilities declaratively from the existing runtime extension manifest rather than monkey-patching core DOM. ### Performance is an API requirement Plugin extension points on large lists or streaming DOM paths need explicit performance contracts. A plugin must not force the core to re-sort 10,000 chats once per row or rescan the whole document on every token. ## Compatibility Current contracts under `webui/AGENTS.md` and `webui/js/AGENTS.md` are migration constraints: - existing `<x-extension id="...">` breakpoints - `callJsExtensions()` hook names/mutable contexts - `<x-component>` loader - modal/surface APIs - same-origin/offline-capable assets - Alpine store compatibility for existing bundled/third-party extensions Do not require all plugins to rewrite on day one. If the core shell architecture changes, ship a compatibility adapter and explicit deprecation/version policy. Framework choice is secondary to the plugin ABI. Do not casually rewrite to React/Vue/etc. if doing so strands the existing extension ecosystem; any framework change requires an ADADR design proving compatibility, performance, and migration. ## 2026-08-24 full-UI redesign directive This epic is now a **whole-product visual and interaction redesign**, not incremental cleanup. Use Impeccable-style design discipline as the working quality bar: establish clear product hierarchy first, avoid generic dashboard/card soup, use deliberate typography/spacing, keep decoration subordinate to function, then run explicit critique/audit/hardening/polish passes before calling a surface done. ### Product direction Symbolics should feel like a serious symbolic-agent workstation rather than an upstream Agent Zero skin. The default desktop composition should prioritize: 1. active conversation/work surface; 2. agent/run state and symbolic context state; 3. project/chat/task navigation; 4. tools/artifacts/debug surfaces only when needed. Do not permanently consume large areas for controls that are rarely touched. Prefer compact rails, command surfaces, progressive disclosure, and contextual panes. ### Required redesign surfaces - global shell and responsive layout - left navigation/chat/task hierarchy - welcome/new-chat surface - chat message/process rendering - composer/input controls - top/status rail - project/profile/model selectors - settings navigation and forms - plugin management/configuration - system jobs/tasks - memory/knowledge surfaces - right canvas/work surfaces - errors/retries/paused/running states - empty/loading/offline states - mobile layout used by Android WebView ### Symbolics-specific status The UI should surface symbolic runtime state without flooding the user with implementation detail. Useful inspectable status includes: - Prolog-RLM ready/degraded/off - current provider/model - current context budget and actual projected tokens - active symbolic tools/capabilities - live task/run state - memory KB status - debug I/O capture state from #59 Detailed traces belong behind an inspector/developer surface, not the main chat chrome. ### Developer/debug integration Developer Settings must include the raw debug capture controls from #59 and make the danger/state visually unambiguous. When raw I/O capture is enabled, show a persistent but compact indicator so the user cannot forget sensitive logging is active. ### Accessibility and interaction quality - keyboard-first navigation for desktop - visible focus treatment - sensible tab order - WCAG-aware contrast - reduced-motion support - no hover-only critical controls - minimum touch targets on mobile - responsive behavior verified at phone, tablet, laptop and wide desktop sizes ### Design verification A substantial redesign slice is not done from code inspection alone. Capture/render the actual UI and perform a design QA pass against the intended hierarchy and states. Validate both dark and light modes and at least one narrow mobile viewport. ## Architecture work Use the repository ADADR control plane (`roam/`, once #17 lands) to define: - UI shell ownership and state boundaries - slot/surface registry - extension capability/version negotiation - event/state contracts - performance budgets - theme/design-token contract - backwards-compatibility adapter - failure isolation for broken plugins - testing strategy for core + plugin combinations ## Acceptance - [ ] Modern shell/design spec approved through ADADR. - [ ] Existing public/bundled extension points are inventoried before redesign. - [ ] Stable versioned plugin UI capability/slot registry exists. - [ ] Legacy `x-extension` / JS hooks continue working through documented compatibility or are migrated with an explicit supported path. - [ ] Plugins can add/replace meaningful UI surfaces, not just append controls. - [ ] One broken/slow plugin cannot permanently break initial shell rendering; failures are isolated/diagnosable. - [ ] UI has defined frame/render/startup budgets and large-chat benchmarks. - [ ] Desktop and mobile accessibility gates exist. - [ ] Core surfaces share a consistent tokenized design system. - [ ] Modern chat navigation work integrates with the large-chat performance/catalog issues rather than rendering the full corpus. - [ ] Main shell, welcome screen, chat, composer, settings and plugin surfaces are visually redesigned as one coherent product. - [ ] Symbolics runtime/context/memory state is inspectable without cluttering the main workspace. - [ ] Debug I/O enabled state from #59 is visible and cannot be forgotten accidentally. - [ ] Dark/light and desktop/mobile states are visually QA'd before merge. - [ ] Existing plugin UI compatibility remains a release gate. --- *Mirrored from [`lost-rob0t/a0-symbolics#23`](https://github.com/lost-rob0t/a0-symbolics/issues/23)* via tracker sync.

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

upstream/v2.12

feat/prolog-rlm-tool-flow

feat/upstream-replayable-model

fix/drop-forced-tool-choice-mid-stream

fix/boot-enable-symbolic-plugins

fix/prolog-rlm-pin-rlm_direct

fix/ui-scroll-autoscroll

fix/responses-upstream-tool-choice

feat/task-kb-and-run-reset

feat/runner-deploy-kit

feature/symbolics-runtime-mode

fix/dev-path-display-mapping

rage/43-context-id-containment

rage/33-log-secret-mask-fail-closed

ci/split-concurrency-lanes

feat/android-native-app-redesign

ci/serialize-heavy-jobs

fix/prolog-rlm-native-routing

fix/nix-mcp-rootless-tests

fix/ci-missing-actions

codex/issue-110

fix/persistent-home-restore

fix/context-compiler-unused

fix/native-responses-xml-tool-calls

fix/rlm-empty-query-runtime-error

feat/77-prolog-rlm-python-harness

fix/docker-oom-smoke-crash-loop

docs/sync-runtime-contracts-20260902

feat/zara-bridge-66

feat/chat-ui-rework

fix/launch-build-memory

chore/add-launch-script

fix/api-startup-smoke

feature/symbolics-live-ci-ui-debug-io

fix/openrouter-responses-system-jobs

rage/8-prolog-rlm-current-api

fix/android-default-localhost

fix/android-connection-ui

feature/issue-49-android-app

codex/move-prolog-adaptor

codex/sol-high-integration

fix/openrouter-prompt-cache-policy

fix/openrouter-reasoning-effort

chore/local-compose-example

feat/nix-cron-skill

bootstrap/context-debloat

feat/canonical-agent-pack

feat/symbolics-home-manager-image

No results found.

Labels

Clear labels   

accessibility

Barrier affecting people with disabilities

  

bug

Something isn't working

  

documentation

Improvements or additions to documentation

  

duplicate

This issue or pull request already exists

  

enhancement

New feature or request

  

good first issue

Good for newcomers

  

help wanted

Extra attention is needed

  

invalid

This doesn't seem right

  

question

Further information is requested

  

wontfix

This will not be worked on

No labels

accessibility

bug

documentation

duplicate

enhancement

good first issue

help wanted

invalid

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

nsaspy/a0-symbolics#161

No description provided.