6ab3bb64d8
- Rename all user-facing and technical identifiers from OpenPets/Pet to FamiliarOS/Familiar. - Rename packages from @open-pets/* to @familiaros/*; rename install-pet/pet-format packages. - Rename plugin IDs and directories from openpets.* to familiaros.*. - Rename IPC namespace from openpets:* to familiaros:* and state filenames from openpets-* to familiaros-* with legacy migration. - Rename source files (pet-window, built-in-pet, default-pet-controller, etc.) to familiar equivalents. - Update locales (en, es-419, ja, ko, pt-BR, zh-Hans, zh-Hant) and tray/pet context menu strings. - Add Familiar naming feature: preference, settings input, tray menu display. - Update assets and packaging config; all desktop tests pass.
326 lines
10 KiB
Markdown
326 lines
10 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
apps/desktop/src/renderer/
|
|
```
|
|
|
|
Production renderer output is built to:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pnpm --filter @familiaros/desktop typecheck
|
|
pnpm --filter @familiaros/desktop build
|
|
pnpm --filter @familiaros/desktop test
|
|
node --check apps/desktop/control-center-preload.cjs
|
|
```
|