stack/docs/scratchpads/ms18-theme-widgets-20260223.md

Mission Scratchpad — MS18 Theme & Widget System

Append-only log. NEVER delete entries. NEVER overwrite sections. This is the orchestrator's working memory across sessions.

Original Mission Prompt

Close out MS16+MS17 mission and initialize new mission for MS18 — Theme/Widgets.
User confirmed: all 4 feature areas (themes, widgets, WYSIWYG, Kanban filtering).
WYSIWYG editor library: agent's choice → Tiptap selected.

Planning Decisions

2026-02-23 — Scope & Architecture

Decision: Tiptap for WYSIWYG editor

• ProseMirror-based, headless (fits our CSS variable design system perfectly)
• Excellent markdown import/export via tiptap-markdown
• Battle-tested, TypeScript-first, largest React ecosystem
• Alternatives considered: Plate (Slate-based, more opinionated UI, smaller community)

Decision: Theme packages as TypeScript files, not DB

• Themes defined in apps/web/src/themes/ as TS files exporting CSS variable maps
• Aligns with PRD's "installable packages from Mosaic Stack repo" concept
• No new Prisma model needed — UserPreference.theme (string field) already exists
• Theme files export: name, displayName, description, author, colorPreview, cssVariables
• Built-in themes: Dark (default), Light, Nord, Dracula, Solarized Dark
• ASSUMPTION: Theme packages are code-level packages (TS files), not runtime-installable npm packages. Rationale: keeps the system simple for MS18; runtime package loading can be added later.

Decision: Dashboard migration to WidgetGrid

• Current dashboard has hardcoded layout (DashboardMetrics, OrchestratorSessions, QuickActions, ActivityFeed, TokenBudget)
• Will migrate to WidgetGrid with these as default widget placements
• Need to seed WidgetDefinition records for the 7 registered widgets
• Default layout created on first visit if no UserLayout exists
• Existing dashboard components become widget implementations

Decision: Kanban filtering approach

• Add filter bar above columns (project, assignee, priority, search)
• User-level view: tasks assigned to current user across all projects
• Project-level view: all tasks in selected project
• Filters stored in URL params for shareability/bookmarkability

Codebase findings:

• 7 widgets already registered in WidgetRegistry.tsx
• WidgetGrid.tsx uses react-grid-layout (12-col, 100px row height)
• BaseWidget.tsx provides consistent wrapper with loading/error states
• Backend widget data endpoints exist (stat-card, chart, list, calendar-preview, active-projects, agent-chains)
• UserLayout model ready (workspace+user scoped, JSON layout, metadata)
• Widget definitions NOT seeded in DB — need seed data
• KnowledgeEntry.contentHtml field exists but unused (ready for WYSIWYG)

Task structure: 17 tasks across 5 phases:

• Phase 1 (Theme System): Theme architecture + built-in themes + theme UI + ThemeProvider upgrade
• Phase 2 (Widget Dashboard): Widget seeding + dashboard migration + picker UI + config UI + layout management
• Phase 3 (WYSIWYG): Tiptap setup + markdown round-trip + file manager integration
• Phase 4 (Kanban): Filtering + user-level view
• Phase 5 (Verification): Tests + theme verification + deploy

Estimate: ~500K tokens total across multiple sessions.

Session Log

Session	Date	Milestone	Tasks Done	Outcome
S1	2026-02-23	MS18	PLAN-001	Planning complete
S2	2026-02-23	MS18	THM-001, THM-002, THM-003	Theme system complete — PRs #493, #494, #495

Open Questions

1. Widget config schema: How complex should per-widget configuration be? Start simple (title, data source) and extend later.
2. Theme hot-reload: Should theme changes apply instantly or require page reload? RESOLVED — Instant via CSS variable injection on html element.
3. Tiptap extensions: Which extensions to include? Start with: StarterKit, Markdown, Table, CodeBlockLowlight, Link, Image, Placeholder.

Corrections

(none)