Coleo Workbench

For the current cross-client architecture, see Workbench across clients. Its illustrated guide reconciles the implemented web, Python CLI/TUI, and native macOS clients with the staged plans below. Older dated descriptions remain a migration record.

This directory records the architecture and migration decisions for Coleo's browser workbench. It is intentionally kept beside the product documentation so future changes to the UI can be reviewed against the same small set of domain rules. The current decision is ADR-004: Workbench UI Architecture and Component System (.project/decisions/004-shadcn-components.md). This guide explains its implementation; the dated entries below preserve migration history.

Current architecture (2026-09-21)

Portability direction update: the terminal bake-off is concluded in favor of Python/Rich + Textual. The Bun CLI remains available during parity work and is not deprecated until the gates in the implementation plan pass. The target monorepo layout gives the Python client a root-level project and puts server/web in its own directory to leave room for native and mobile clients. That relocation is planned, not yet reflected by the current-architecture description below.

The September architecture review compares these ownership claims with the implementation. Its implementation plan records the direction selected on September 29: Messaging first, independent panels, portable resource models, semantic toolbars, and retirement of classic mode. Those are planned changes; the current-implementation description below continues to describe the reviewed code until that work lands.

The workbench refactor covers the application shell and the shared presentation of domain screens. React 19, HeroUI v3, and Tailwind v4 provide the control and styling foundation. Golden Layout is the default shell; classic mode uses the same route registry. Tabulator, Adaptive Cards, custom charts, and the Garden's 3D renderer remain specialized adapters inside that shared architecture.

• Collections: Tasks, Bugs, Inbox, Project Mail, and Processes support shared grid/card display preferences. Domain code owns card filtering and sorting; AdaptiveCardCollection preserves the supplied order.
• Controls: Profile-backed toolbar templates arrange allowlisted widgets in two rows with configurable order, visibility, and row size. Shared shape, typography, status-color, and theme tokens apply across library boundaries.
• Panels: A route-backed detail view owns its record. An Inbox item viewer uses a seeded per-item cache and targeted record/attention requests, rather than mounting the collection and fetching the entire Inbox. Message details retain the thread context they need.
• Continuity: Live refreshes preserve active editors, expanded cards, and unchanged SDK DOM. Opening the first side panel reparents the existing stack instead of rebuilding the workspace. Per-tab and per-card error boundaries contain rendering failures and preserve healthy siblings.
• Persistence: Profiles, views, layouts, and toolbar overrides use the API. Theme, shell mode, and some presentation/cache settings remain browser-local. The default theme follows the system preference.
• Navigation: Project Mail is a separate visible /mail projection. Activity, History, and Proposals retain compatibility routes into Inbox. Viewer opens with a selected Arm rather than appearing as a standalone destination.

Use the Adaptive Cards guide, sheet performance gates, and theme guide for the detailed contracts. Source-level guidance lives in src/web/src/design-system/README.md and src/web/src/workbench/README.md.

Product model

Coleo is an operating environment for a project, not a collection of unrelated dashboard pages. The browser shell presents live, configurable views over the same project state while the Brain and Arms continue to operate independently.

The workbench uses these concepts:

• Resource: a stable reference to a task, bug, Arm, Brain, message, plan, template, document, proposal, or run.
• Event: an immutable fact emitted by the server or event stream.
• Metric sample: numeric, time-indexed telemetry. Metric samples are not events and retain their existing sampling and aggregation semantics.
• Conversation: an ordered exchange among people, Brain, Arms, and the system, optionally attached to another resource.
• Run: the execution interval that begins when an Arm claims a task or bug after asking Brain for work. Launching an Arm does not itself create a run.
• Document: a versioned project artifact. A plan is a specialized collaborative document whose edits can regenerate and reconcile tasks.
• Command: a context-sensitive user action.
• Projection: a live query presented as a sheet, inbox, timeline, process monitor, document, conversation, or dashboard.
• Workspace: persisted Golden Layout geometry plus the view instance stored in each panel.

Runtime data flow

1. The API remains the browser's boundary for authoritative domain data and event history; JetStream is a service-side implementation detail.
2. Existing Arm metric history and message metric tables remain authoritative for sampled telemetry.
3. One browser WebSocket connection fans server messages out to projections.
4. A projection either applies a small append/update directly, invalidates its React Query cache, or reloads its own local collection state. Not every projection has been converted to React Query.
5. Background changes mark relevant workbench panels as needing attention.
6. View preferences and complete workspace layouts are persisted through the workbench API and may be private or shared.

UI layers

The frontend is divided into four layers:

1. design-system/ contains visual primitives and tokens. These components do not know about tasks, Arms, Brain, or routing.
2. workbench/ contains registries, live projection infrastructure, saved-view state, and resource/view contracts.
3. Domain features supply projection schemas, row renderers, commands, and detail components.
4. Golden Layout hosts registered view instances and persists their placement; the classic shell hosts the same routes without the pane tree.

Tabulator is the production ResourceSheet runtime for Tasks, plan items, Bugs, and Discovery. The Inbox's grid mode also uses Tabulator, but as a separate read-only scan table whose rows expand into full Adaptive Cards. Timeline, document, process, and dashboard surfaces use the Coleo design system so the application shares one compact interaction language.

Persistence

workbench_profiles represents a portable UI identity even when Coleo is running behind a single API key. A profile owns view definitions and layouts. Each view has both a database ID and a stable per-profile key; this lets two profiles customize tasks-sheet independently and makes shared views copy-on-edit instead of mutating their owner.

Saved views contain:

• projection kind and resource type;
• filters and sort order;
• visible, hidden, and ordered columns;
• column widths and density;
• grid font size and collection display/card preferences;
• optional sharing metadata.

Saved layouts contain Golden Layout configuration and a schema version. The export endpoint returns a portable bundle containing the profile, its views, and layouts. Import creates or replaces that configuration without changing project-domain data.

Migration rules

• Preserve existing domain behavior while replacing presentation components.
• Keep plans specialized; never reduce plan reconciliation to generic document persistence.
• Keep telemetry sampling separate from the event stream.
• Use stable resource IDs in panel state instead of component-owned selection.
• Route every live subscription through the shared projection provider.
• Add file-level documentation to every migrated or newly created source file.
• Start with static registries in the main bundle. Dynamic third-party plugins are deliberately outside this migration.

Current surface map

Existing surface	Workbench destination
TaskGrid, BugGrid	Tabulator ResourceSheet
Operational activity, history, and proposals	Inbox facets backed by ProjectionInbox
Project Mail	Separate mail projection with shared messaging infrastructure
Arm telemetry components	metric-backed dashboard panels
Setup plan editor	retained as the specialized collaborative plan document
Golden Layout local storage	versioned database-backed workspace layout
Grid-specific local storage	database-backed saved view preferences

Legacy row/grid components remain in the source tree only as type/style compatibility dependencies for detail pages. No navigation route renders them as its list implementation.

Implementation record

These dated entries record earlier milestones and their validation at the time. The current architecture above supersedes older navigation and presentation descriptions, including the earlier treatment of Mail as a compatibility route.

The initial workbench migration was completed on 2026-07-31 in codex/workbench-ui.

• Tasks, bugs, and discovery lists use the shared Tabulator sheet.
• Brain, Arm, project, system, and attention streams share one inbox surface.
• Activity uses the reusable event timeline; implicit Arm work uses Processes.
• Saved views, profiles, portable imports/exports, and complete Golden Layout workspaces persist in SQLite.
• Golden Layout remains mounted across profile/query refreshes; current event callbacks are supplied through refs so database auto-save cannot recreate the pane tree.
• Verification covered the full 930-test suite, project type checking, web linting, a production build, and visual checks of the sheet, inbox, Processes, and Settings surfaces.

2026-08-01 overlay reliability follow-up

• View configuration panels use an explicit overlay layer above grid headers, editors, and menus.
• Column and context menus are initialized outside routine React prop updates, preventing unrelated profile or workspace renders from closing open menus.
• Focusing a Golden Layout pane no longer schedules a redundant layout save; actual layout state changes remain the persistence trigger.
• Portaled grid menus receive the same light/dark design tokens as the sheet that opened them.

2026-08-02 projection migration

• Arm Fleet and Viewer now share one compact Arm row and the same workbench framing, while preserving Viewer as a dedicated workspace panel.
• Brain status and operational history use common projection surfaces.
• Task and bug sheets use shared spreadsheet interaction and consistent workbench headers, toolbars, and detail framing.
• Dashboard cards and activity summaries use shared surfaces without changing the existing metric and chart implementations.
• Inbox is the primary stream interface. Its virtualized scan table keeps state, source, subject, type, and received time sortable at a glance, while each row can expand into its full Adaptive Card. Its Messages facet preserves read, reply, archive, full-thread viewing, and reply indentation. Brain, Arm, attention, and history facets expose the other operational streams.
• Mail, Activity, History, and Proposals remain compatibility redirects for old deep links and saved workspaces, but are omitted from launchers and navigation.
• Settings, project documents, and Garden now share workbench framing while retaining their specialized profile, plan-reconciliation, and 3D scene behavior.
• Brain links to the Inbox's Brain facet rather than maintaining a second activity feed. The Inbox retains Brain-specific semantic categories, formatted summaries, target navigation, live connection state, and retained-history paging.
• Viewer remains a route-backed detail projection for selected Arms, but is not exposed as a standalone launcher or navigation destination.
• Dashboard no longer owns recent-activity or notable-event feeds. It links to Inbox, which now ingests the high-signal server event stream while retaining task, bug, and Arm target navigation.
• Eight Playwright scenarios protect the Inbox, Brain handoff, Arm Fleet/Viewer, and task spreadsheet/detail flows.

2026-08-02 sheet performance follow-up

• Resource sheets own one imperative grid instance instead of routing its editor portals and settings updates through React renders.
• Explicit column widths and row heights disable unnecessary automatic sizing, while virtual row rendering remains enabled with a small viewport buffer.
• The Subject column scrolls with the rest of the sheet. Removing its frozen overlay eliminates the duplicated first-column layer that made row-header repainting visible during selection.
• Sheet pagination runs only when the vertical viewport reaches the bottom threshold, not on every scroll event.
• The Tasks browser coverage samples row-header selection over multiple animation frames and rejects duplicate frozen-column cells.

2026-08-02 row metadata restoration

• Task and Bug sheets expose metadata tags through one custom, creatable MultiSelect editor. Selected tags render as compact chips, and edits persist string arrays while preserving unrelated metadata.
• Selecting any data cell or row header reveals the shared row-formatting toolbar without recreating the Tabulator instance.
• Bold and the existing slate, blue, green, amber, and rose row colors persist through each resource's metadata.ui object and render across the full row.
• Browser coverage protects Task formatting and the restored Bug tags/color behavior while keeping the critical workbench suite at eight scenarios.
• Every sheet with editable cells exposes Coleo-owned Undo and Redo through keyboard shortcuts and the context menu. React Query reconciliation uses updateData() so server responses preserve the current history stack.

2026-08-03 Tabulator production migration

• The validated spike now powers the shared ResourceSheet; Tasks, plan items, Bugs, and Discovery no longer carry a second grid runtime.
• The common column model maps text, numeric, checkbox, date, dropdown, and creatable multi-select cells while keeping status and row-formatting styles in Coleo design tokens.
• Coleo-owned history records only user edits and manual row moves. React Query, server responses, and streamed same-shape updates use updateData() and stay out of the undo stack.
• Context actions provide Details, between-row insertion, deletion, Undo, Redo, and copying. Whole-row dragging persists through the existing domain reorder APIs.
• Saved visibility, order, width, density, filters, sort, and sharing continue through the database-backed view/profile APIs.
• Model gates cover 1k, 10k, and 50k projections. Playwright covers Tasks, Bugs, Discovery, plan items, Tags creation, formatting, history, ordering, insertion, dark editing, and Golden Layout resizing.
• THIRD_PARTY_NOTICES.md records the pinned MIT dependency. The package, bundle, and source contain no retired evaluation key.