Add new portable UI app shell (apps/ui)

Introduces a new UI layer that can run as both an Electron renderer
and a standalone web app. Uses an injectable connector pattern for
data access (IPC for Electron, Telex REST API for web), TanStack
Router (code-based) and TanStack Query with localStorage persistence.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: youknowriad

apps/studio/electron.vite.config.new-ui.ts

@@ -0,0 +1,50 @@
+/**
+ * Electron-vite dev config for running the Electron app with the new @studio/ui renderer.
+ * Builds main + preload in development mode; skips the renderer since it's handled
+ * by the @studio/ui Vite dev server (pointed to via ELECTRON_RENDERER_URL).
+ */
+
+import { resolve } from 'path';
+import { defineConfig } from 'electron-vite';
+
+export default defineConfig( {
+	main: {
+		plugins: [],
+		resolve: {
+			alias: {
+				src: resolve( __dirname, 'src' ),
+				'@studio/common': resolve( __dirname, '../../tools/common' ),
+				'@wp-playground/blueprints/blueprint-schema-validator': resolve(
+					__dirname,
+					'../../node_modules/@wp-playground/blueprints/blueprint-schema-validator.js'
+				),
+			},
+		},
+		define: {
+			'process.env.NODE_ENV': JSON.stringify( process.env.NODE_ENV ),
+			COMMIT_HASH: JSON.stringify( 'dev' ),
+		},
+		build: {
+			externalizeDeps: {
+				exclude: [ '@studio/common' ],
+			},
+			rollupOptions: {
+				input: {
+					index: resolve( __dirname, 'src/index.ts' ),
+				},
+				output: {
+					entryFileNames: '[name].js',
+				},
+				external: [ /^@php-wasm\/.*/ ],
+			},
+		},
+	},
+	preload: {
+		build: {
+			externalizeDeps: { exclude: [ '@sentry/electron' ] },
+			lib: {
+				entry: resolve( __dirname, 'src/preload.ts' ),
+			},
+		},
+	},
+} );

apps/studio/src/main-window.ts

@@ -65,7 +65,7 @@ export async function createMainWindow(): Promise< BrowserWindow > {
 	}
 
 	const userData = await loadUserData();
-	nativeTheme.themeSource = userData.colorScheme ?? 'light';
+	nativeTheme.themeSource = userData.colorScheme ?? 'system';
 
 	const savedBounds = await loadWindowBounds();
 	let windowOptions: BrowserWindowConstructorOptions = {

apps/studio/src/modules/user-settings/lib/ipc-handlers.ts

@@ -85,7 +85,7 @@ export async function saveColorScheme(
 
 export async function getColorScheme(): Promise< 'system' | 'light' | 'dark' > {
 	const userData = await loadUserData();
-	const colorScheme = userData.colorScheme ?? 'light';
+	const colorScheme = userData.colorScheme ?? 'system';
 	nativeTheme.themeSource = colorScheme;
 	return colorScheme;
 }

apps/ui/README.md

@@ -0,0 +1,99 @@
+# @studio/ui
+
+A portable UI layer for Studio that can run as both an Electron renderer and a standalone web app.
+
+## Architecture
+
+### Dual-target design
+
+The same React application runs in two environments with different data backends:
+
+- **Electron**: Uses an IPC connector that delegates to `window.ipcApi` (exposed by the Electron preload script). Auth is optional (handled by the desktop app).
+- **Web**: Uses a REST connector backed by the Telex API (`telex.automattic.ai`) with WordPress.com OAuth for authentication.
+
+A single entry point (`main.tsx`) selects the connector at runtime based on the `__IS_ELECTRON__` Vite define (set via the `--mode` flag). The UI code never imports environment-specific modules directly.
+
+### Connector pattern
+
+The `Connector` interface (`data/core/types.ts`) defines the data operations the UI needs:
+
+```
+data/core/
+  types.ts                # Connector interface + domain types (SiteDetails, AuthUser)
+  connector-context.tsx   # React Context provider + useConnector() hook
+  query-client.ts         # TanStack Query client with localStorage persistence
+  connectors/
+    ipc/index.ts          # Electron IPC implementation (requiresAuth: false)
+    rest/index.ts         # Telex REST API + WP.com OAuth (requiresAuth: true)
+```
+
+Components access data through the `useConnector()` hook, which pulls the active connector from React Context. This keeps all UI code environment-agnostic.
+
+The `Connector` interface includes an auth surface (`requiresAuth`, `isAuthenticated`, `authenticate`, `logout`, `getAuthUser`) alongside data methods (`getSites`, `createSite`, `deleteSite`, `startSite`, `stopSite`). The interface is intentionally minimal -- new methods are added as features are built.
+
+### Authentication
+
+The REST connector uses WordPress.com OAuth (implicit grant flow) for authentication:
+
+1. `connector.authenticate()` redirects to `public-api.wordpress.com/oauth2/authorize`
+2. After authorization, WordPress.com redirects back to `/auth/callback#access_token=...`
+3. `main.tsx` intercepts the callback **before React mounts** to avoid TanStack Router parsing issues with special characters in the hash fragment
+4. The token and user profile are stored in `localStorage`
+
+Route protection is handled in the root route's `beforeLoad` hook. When `connector.requiresAuth` is true, all routes except `/login` require authentication -- unauthenticated users are redirected to `/login`.
+
+The IPC connector sets `requiresAuth: false`, so auth checks are skipped entirely in Electron.
+
+### Data fetching with TanStack Query
+
+Query hooks in `data/queries/` wrap connector methods with TanStack Query for caching, deduplication, and cache invalidation. The query client uses localStorage persistence (24h max age) mirroring the wp-calypso setup.
+
+```typescript
+function useSites() {
+  const connector = useConnector();
+  return useQuery({
+    queryKey: ['sites'],
+    queryFn: () => connector.getSites(),
+  });
+}
+```
+
+Mutations invalidate related queries on success, keeping the UI in sync without manual refetching.
+
+### Routing with TanStack Router
+
+Routes are **code-based** (not file-based), following the wp-calypso hosting dashboard pattern. Routes are defined with `createRoute()` calls under `router/` and assembled into a route tree in `router/router.tsx`.
+
+The router context carries both the `QueryClient` and `Connector`, enabling route-level data prefetching and auth checks in `beforeLoad` hooks.
+
+### Component structure
+
+Components use a folder-per-component pattern with CSS Modules:
+
+```
+components/
+  sidebar-layout/
+    index.tsx
+    style.module.css
+  site-list/
+    index.tsx
+    style.module.css
+  onboarding-layout/
+    index.tsx
+    style.module.css
+```
+
+UI is built with `@wordpress/ui` and `@wordpress/theme` from the WordPress Design System, plus `@wordpress/icons` for iconography.
+
+## Development
+
+You can run the UI in two modes during development:
+
+
+```bash
+# Web mode (REST connector, Telex API)
+npm -w @studio/ui run dev:web
+
+# Electron mode (Electron app with IPC connector)
+npm run start:new-ui
+```

apps/ui/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>Studio</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/main.tsx"></script>
+	</body>
+</html>

apps/ui/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@studio/ui",
+	"private": true,
+	"version": "0.1.0",
+	"type": "module",
+	"scripts": {
+		"dev:web": "vite --mode web",
+		"dev:electron": "vite --mode electron",
+		"build:web": "vite build --mode web",
+		"build:electron": "vite build --mode electron",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"preview": "vite preview"
+	},
+	"dependencies": {
+		"@tanstack/query-sync-storage-persister": "^5.96.2",
+		"@tanstack/react-query": "^5.75.5",
+		"@tanstack/react-query-persist-client": "^5.96.2",
+		"@tanstack/react-router": "^1.120.14",
+		"@wordpress/icons": "^11.8.0",
+		"@wordpress/private-apis": "^1.10.0",
+		"@wordpress/theme": "0.10.0",
+		"@wordpress/ui": "0.10.0",
+		"react": "^18.2.0",
+		"react-dom": "^18.2.0"
+	},
+	"devDependencies": {
+		"@types/react": "^18.3.27",
+		"@types/react-dom": "^18.3.7",
+		"@vitejs/plugin-react": "^5.1.4",
+		"typescript": "~5.9.3",
+		"vite": "^7.3.1"
+	}
+}

apps/ui/src/app.tsx

@@ -0,0 +1,34 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import { RouterProvider } from '@tanstack/react-router';
+import { privateApis } from '@wordpress/theme';
+import { ConnectorProvider, queryClient } from '@/data/core';
+import { unlock } from '@/lock-unlock';
+import { createAppRouter } from '@/router/router';
+import '@wordpress/theme/design-tokens.css';
+import '@/index.css';
+import type { Connector } from '@/data/core';
+
+const { ThemeProvider } = unlock( privateApis );
+
+export type AppTarget = 'electron' | 'web';
+
+interface AppProps {
+	connector: Connector;
+	target: AppTarget;
+}
+
+export function App( { connector, target }: AppProps ) {
+	const router = createAppRouter( { queryClient, connector } );
+
+	return (
+		<div className={ `studio-${ target }` }>
+			<ConnectorProvider connector={ connector }>
+				<QueryClientProvider client={ queryClient }>
+					<ThemeProvider isRoot>
+						<RouterProvider router={ router } />
+					</ThemeProvider>
+				</QueryClientProvider>
+			</ConnectorProvider>
+		</div>
+	);
+}

apps/ui/src/components/onboarding-layout/index.tsx

@@ -0,0 +1,10 @@
+import styles from './style.module.css';
+import type { ReactNode } from 'react';
+
+export function OnboardingLayout( { children }: { children: ReactNode } ) {
+	return (
+		<div className={ styles.root }>
+			<div className={ styles.content }>{ children }</div>
+		</div>
+	);
+}

apps/ui/src/components/onboarding-layout/style.module.css

@@ -0,0 +1,12 @@
+.root {
+	display: flex;
+	height: 100vh;
+	align-items: center;
+	justify-content: center;
+}
+
+.content {
+	max-width: 640px;
+	width: 100%;
+	padding: 32px;
+}

apps/ui/src/components/sidebar-layout/index.tsx

@@ -0,0 +1,16 @@
+import { SiteList } from '@/components/site-list';
+import styles from './style.module.css';
+import type { ReactNode } from 'react';
+
+export function SidebarLayout( { children }: { children: ReactNode } ) {
+	return (
+		<div className={ styles.root }>
+			<aside className={ styles.sidebar }>
+				<div className={ styles.spacer } />
+				<div className={ styles.separator } />
+				<SiteList />
+			</aside>
+			<main className={ styles.main }>{ children }</main>
+		</div>
+	);
+}