stella-desktop

name	stella-desktop
description	Use this skill before modifying Stella, the desktop app and runtime the user is talking to you on. It provides necessary guidance and rules.

Modifying Stella Desktop

Operating rules

• File tools require absolute paths. Write/Edit/apply_patch reject relative paths and do NOT follow the shell's cd — a relative path is never resolved against your exec_command working directory. When editing Stella's own source, pass the full absolute path under the running install root (the directory containing desktop/ and runtime/). Find that root once (e.g. with pwd from the install root, or the Install root value when given) and prefix every file-tool path with it, even after you cd elsewhere in a command.
• Never launch Stella's dev servers for testing. Stella is already running for the user; starting another desktop/runtime dev server can interrupt the active session. Use typecheck, lint, focused tests, and code inspection instead.
• Never adjust onboarding unless specifically told. The user cannot see it, so there is no point making changes to it.

Surface map (for app-wide visual changes)

For broad Stella UI changes, these are the main surfaces to inspect:

• Shell chrome / nav / account: desktop/src/shell/ShellTopBar.tsx, shell/sidebar/ShellTopBarNav.tsx, shell/sidebar/ShellTopBarAccount.tsx.
• Home cover + greeting + launcher: desktop/src/app/home/HomeContent.tsx.
• Chat: desktop/src/app/chat/ — ChatColumn.tsx, ConversationEvents.tsx, MessageRow.tsx, UserMessageBody.tsx, Markdown.tsx.
• Composer: desktop/src/app/chat/Composer.tsx + features/chat/ComposerPrimitives.tsx.
• Compact chat surface: desktop/src/shell/ChatSidebar.tsx.
• Display sidebar + tabs (media, canvas, activity): desktop/src/shell/DisplaySidebar.tsx, shell/display/.
• Menus / dialogs / buttons: desktop/src/ui/ (dropdown-menu, dialog, popover, pill, button, select), desktop/src/shell/context-menu/StellaContextMenu.tsx, desktop/src/shell/overlay/RadialDial.tsx.
• Other app routes: desktop/src/app/{settings,store,social,pets,apps,media}/, each with its own App.tsx + css.

Aesthetic redesigns go in the Custom theme

Every user is on the built-in Custom overlay theme (desktop/src/shared/theme/themes/custom.ts), which inherits a base theme until it is populated. Write redesigns and personal look changes into Custom so they show immediately — the user is already on it — and survive switching palettes. Never create a new named theme or scope styling to a non-active [data-theme="…"]: that strands the change until the user selects it in Settings, which is the wrong experience.

• Colors: add entries to overrides.light / overrides.dark, then set populated: true so Custom surfaces in the picker.
• Structure, typography, backgrounds: target :root[data-theme="custom"] in CSS. The base theme's tuning still applies via data-base-theme, so empty Custom stays identical to its base.
• Reserve theme-agnostic (ungated) global CSS for layout/behavior that should hold across every palette.

For background-image looks, make the image visible through the Custom surface, not hidden behind ShiftingGradient. Stella's UI is glass-heavy, so tune the background treatment and foreground surfaces together: dim or blur busy imagery, strengthen translucent shells where needed, and add fit-to-content assistant message bubbles if readability requires them. Preserve the requested aesthetic rather than simply making every panel opaque.

Validation

Run from the Stella install root (the directory containing desktop/ and runtime/):

node node_modules/typescript-7/lib/tsc.js -p desktop/tsconfig.app.json --noEmit
bun run electron:typecheck
bun run lint
bun run test:run -- tests/runtime/sidebar-discovery.test.ts tests/runtime/route-smoke.test.ts

Non-obvious gotchas

• There's one package.json at the repo root — install all dependencies there.
• desktop/src/routeTree.gen.ts is auto-generated by Vite's TanStack plugin on every save. Don't edit it; edit files under desktop/src/routes/ instead.
• Top-bar nav apps are discovered via import.meta.glob("../../app/*/metadata.ts") in desktop/src/shell/sidebar/app-registry.ts and rendered by ShellTopBarNav.tsx. Add an app by dropping a new desktop/src/app/<id>/metadata.ts; don't hardcode entries in the nav.
• The voice overlay has no router — features that need to be reachable from it must flow through UiState, not router state.
• useFullShellChat() is mounted exactly once in desktop/src/routes/__root.tsx inside <ChatRuntimeProvider>. Everything else (chat route, sidebars) reads it via useChatRuntime(). Mounting it elsewhere double-instantiates the streaming subscription.

Backlinks

• create-stella-app — scaffold a single-file user app on the /apps page (also covers canvas / game surfaces)