openpetswithchatandmcp/docs/front_refactor.md

Desktop Frontend Refactor

Current Situation

The desktop app now uses the React Control Center as the production management UI. Familiars, Settings, Plugins, and Integrations are routed inside the singleton Control Center window, and tray actions target those routes directly.

The legacy generated task-window UI has been removed: apps/desktop/preload.cjs, apps/desktop/src/plugins-window.ts, and the legacy plugins-window test are gone. Transparent familiar windows and plugin SDK windows remain separate lightweight renderers.

Goal

Move the desktop management UI from generated HTML/CSS strings and preload-driven DOM updates to a React + Tailwind Control Center, while keeping desktop familiar windows lightweight and separate.

End Goal

The end goal is a single polished desktop management experience for FamiliarOS:

Tray app
  ├─ animated desktop familiar windows
  └─ one React/Tailwind Control Center
       ├─ Dashboard
       ├─ Familiars
       ├─ Integrations
       ├─ Plugins
       └─ Settings

The Control Center should become the one place where users manage everything:

• choose and install familiars
• configure coding-agent integrations
• manage plugins
• tune settings
• inspect status/errors/update prompts

The old separate task windows should eventually disappear. The tray should still exist, but tray actions should route into the Control Center instead of opening independent windows.

The familiar windows themselves should stay separate from React. They are performance- and behavior-sensitive transparent desktop windows, so they should remain small, focused renderers responsible only for showing familiars, speech bubbles, and reactions.

Final architecture target:

• Main process: app lifecycle, tray, state, IPC handlers, services, familiar/plugin/integration logic.
• Control Center renderer: React UI, routes, forms, visual polish, local UI state.
• Preloads: narrow typed bridges only, no DOM rendering.
• Familiar renderers: lightweight sprite/speech renderers, not part of Control Center.

From a product perspective, the end state should feel like a clean native-quality companion app rather than a set of separate utility dialogs.

Current Direction

• Keep the app tray-first.
• Keep existing transparent familiar windows outside React.
• Use a single Control Center window for management UI.
• Route tray actions into Control Center pages instead of independent task windows.
• Keep transparent familiar windows separate from React.

Phase 1: Familiars Preview

Implemented first as a reviewable prototype and now promoted into the primary management shell:

• Control Center... opens the React renderer.
• Familiar management opens through the Control Center Familiars route.
• Renderer lives under apps/desktop/src/renderer/.
• Vite outputs packaged assets to apps/desktop/dist/renderer/.
• control-center-preload.cjs exposes narrow page-specific APIs.

The Familiars page includes:

• installed familiars
• catalog familiars
• catalog pagination
• catalog search
• Codex familiars
• familiar selection/detail pane
• install/import/set default/remove actions
• animated sprite-frame preview
• styling based on the existing Familiar Manager and Integrations pages

What We Changed

Renderer foundation

Added a modern renderer stack for the desktop app:

• React
• ReactDOM
• Vite
• TailwindCSS
• PostCSS
• Autoprefixer

New renderer files live in:

apps/desktop/src/renderer/

Production renderer output is built to:

apps/desktop/dist/renderer/

Control Center window

Added a dedicated Control Center BrowserWindow in apps/desktop/src/windows.ts.

Important details:

• It is a separate singleton window.
• It does not use the old task-window data URL system.
• It keeps the usual Electron hardening:
  • sandbox enabled
  • context isolation enabled
  • Node integration disabled
  • navigation blocked
  • window.open blocked
• In development, it can load FAMILIAROS_RENDERER_URL, but only from loopback hosts.
• In packaged builds, it loads dist/renderer/index.html.

Tray integration

Tray items now route to the Control Center singleton:

• Control Center...
• Manage Familiars... → Familiars route
• Plugins, Integrations, and Settings → matching Control Center routes

Narrow preload bridge

Added:

apps/desktop/control-center-preload.cjs

It exposes narrow, page-specific methods to the React renderer. It now covers Familiars, Settings, Plugins, and Integrations without exposing ipcRenderer directly.

Familiars methods include:

• getPetsState
• getCatalog
• getCatalogPage
• getCatalogSearch
• getCodexPets
• setDefaultPet
• installPet
• importCodexPet
• removePet

Settings methods include startup preferences, launch-at-login, familiar scale, reaction animation mapping, update checks, and default familiar position reset.

Plugins methods include plugin snapshots, catalog snapshots, enable/disable, config save, reload, command execution, local plugin loading, catalog install/update, and uninstall.

Integrations methods include agent setup snapshots, setup actions, and command path updates for Claude Code, OpenCode, and Cursor.

It does not expose ipcRenderer directly.

Narrow page state

The Control Center does not receive the full app state. It receives narrowed page snapshots only.

The Familiars page receives:

• default familiar id
• installed familiars

The Settings page receives only settings preferences/options needed by the route.

The Plugins page receives safe plugin and catalog records from PluginService, intentionally excluding raw install paths and manifest paths.

The Integrations page receives the existing narrowed agent setup snapshot used by the legacy task window: status/details for Claude Code, OpenCode, Cursor, Pi guidance, command paths, familiar routing choices, and safe previews.

This avoids exposing unrelated state to the new renderer.

Familiars page UI

The new Familiars page now supports:

• installed familiar list
• remote catalog familiars
• catalog pagination
• catalog search
• Codex familiars
• search/filter UI
• set default
• install catalog familiar
• import Codex familiar
• remove familiar
• detail panel
• animated sprite-frame preview

Settings page UI

The Control Center Settings page now supports:

• show-familiar-on-launch preference
• launch-at-login preference
• familiar scale selection
• reaction-to-animation mapping
• default familiar position reset
• compact system/update status
• default-familiar reaction previews using the familiaros-familiar-preview: protocol
• bottom-center floating notifications that do not shift layout

Settings is now served by the Control Center route.

Plugins page UI

The Control Center Plugins page now supports:

• gallery-first plugin hub
• installed/catalog/local/broken filters
• catalog refresh and local plugin loading in the bottom utility row
• plugin install from catalog
• enable/disable directly from plugin cards
• on-demand configuration modal instead of a persistent split inspector
• dynamic config forms for supported plugin schema fields
• command execution when plugins expose commands
• reload, update, and uninstall actions
• safe no-op/cancel feedback for install/update/local-load flows

Plugins is now served by the Control Center route; broken plugins cannot be re-enabled until fixed.

Integrations page UI

The Control Center Integrations page now supports:

• grid-first integration hub with icons and status pills
• direct install/connect actions from Claude Code, OpenCode, and Cursor cards
• detail inspector opened by Configure/View setup buttons
• Claude MCP setup, replace/remove, hooks, instructions, familiar routing, command paths, and advanced previews
• OpenCode global setup, remove, familiar routing, command paths, and config preview
• Cursor MCP setup, replace/remove, familiar routing, MCP preview, and Cursor rules preview
• Pi manual setup guidance
• polished disabled cards for future editor integrations

Integrations is now served by the Control Center route, including command-source selection for published, bundled, or local development CLI modes.

Dashboard UI

The Control Center Dashboard now supports:

• default companion overview with animated sprite preview
• quick navigation into familiar selection
• message and reaction activity totals
• top companion and top reaction summaries
• last-interaction timestamp
• compact system health for installed familiars, plugins, catalog, updates, and app version

Dashboard is now the default Control Center landing route.

Build/test integration

Updated desktop scripts/configs so the new renderer participates in normal validation.

Important files:

• apps/desktop/package.json
• apps/desktop/vite.config.ts
• apps/desktop/tailwind.config.cjs
• apps/desktop/postcss.config.cjs
• apps/desktop/tsconfig.renderer.json
• apps/desktop/electron-builder.yml
• apps/desktop/scripts/run-tests.mjs

Validated with:

pnpm --filter @familiaros/desktop typecheck
pnpm --filter @familiaros/desktop build
pnpm --filter @familiaros/desktop test
node --check apps/desktop/control-center-preload.cjs

All passed.

Styling Principles

Reuse the current polished desktop visual language:

• light blue gradient background
• white glass cards
• soft blue shadows
• navy text
• brand blue CTAs
• rounded mono buttons and status pills
• orange Originals filter accent
• two-column gallery/detail layout

Security Constraints

• nodeIntegration: false
• contextIsolation: true
• sandbox: true
• no direct ipcRenderer exposure
• deny navigation, redirects, and window.open
• dev renderer URL allowed only for loopback hosts in non-packaged builds
• Control Center receives narrow page snapshots, not full app state

Migration Status and Next Order

Completed phases:

• Manual Familiars review and refinement
• Control Center routing/shell
• Settings migration
• Plugins migration
• Integrations migration
• Tray route switch to Control Center
• Legacy generated task-window UI removal

Remaining follow-up:

• Continue manual smoke coverage for tray route retargeting, plugin workflows, and integration setup flows.

Validation Commands

Use these after each phase:

pnpm --filter @familiaros/desktop typecheck
pnpm --filter @familiaros/desktop build
pnpm --filter @familiaros/desktop test
node --check apps/desktop/control-center-preload.cjs