khal-os 1.260324.2

package/src/app/desktop/desktop-shell.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { Desktop } from '@/components/desktop/Desktop';
+import { DesktopBackground } from '@/components/desktop/DesktopBackground';
+import { ShortcutViewer } from '@/components/desktop/ShortcutViewer';
+import { WindowRenderer } from '@/components/desktop/WindowRenderer';
+import { WindowSwitcher } from '@/components/desktop/WindowSwitcher';
+import { NotificationCenter } from '@/components/notifications/NotificationCenter';
+import { NotificationToasts } from '@/components/notifications/NotificationToasts';
+import { OrphanSessionToast } from '@/components/notifications/OrphanSessionToast';
+import { Taskbar } from '@/components/taskbar/Taskbar';
+import { useKhalAuth } from '@/lib/auth/use-auth';
+import { useDesktopNats } from '@/lib/hooks/use-desktop-nats';
+import { useNatsNotifications } from '@/lib/hooks/use-nats-notifications';
+import { useGlobalKeybinds } from '@/lib/keyboard/use-global-keybinds';
+import { useWindowStore } from '@/stores/window-store';
+
+/** Fallback workspace ID for unauthenticated / loading state. */
+const LOCAL_WORKSPACE_ID = 'local';
+
+function useDocumentTitle() {
+	useEffect(() => {
+		document.title = 'Khal';
+	}, []);
+}
+
+/**
+ * Derives the workspace key from auth state.
+ * Returns `orgId:userId` when authenticated, or `'local'` as fallback.
+ */
+function getWorkspaceId(auth: { orgId: string; userId: string } | null): string {
+	if (!auth || !auth.userId) return LOCAL_WORKSPACE_ID;
+	return `${auth.orgId}:${auth.userId}`;
+}
+
+interface DesktopShellProps {
+	/** Role resolved server-side via withAuth(), normalized to canonical slug. */
+	serverRole: string;
+	/** Permissions resolved server-side via withAuth(). */
+	serverPermissions: string[];
+}
+
+export function DesktopShell(_props: DesktopShellProps) {
+	useDocumentTitle();
+	useNatsNotifications();
+	useDesktopNats();
+	const { switcher, launcherToggle, shortcutViewerVisible, setShortcutViewerVisible } = useGlobalKeybinds();
+
+	const auth = useKhalAuth();
+
+	// SSR hydration guard: only render after client-side mount
+	const [mounted, setMounted] = useState(false);
+
+	// Bootstrap: set the workspace from auth
+	const bootstrappedRef = useRef(false);
+	useEffect(() => {
+		setMounted(true);
+	}, []);
+
+	// Set workspace when auth resolves (or changes)
+	useEffect(() => {
+		if (!mounted) return;
+		if (auth?.loading) return;
+
+		const workspaceId = getWorkspaceId(auth);
+		const store = useWindowStore.getState();
+
+		// Migrate: if 'local' workspace has data and the user's workspace doesn't, copy it
+		if (workspaceId !== LOCAL_WORKSPACE_ID && !bootstrappedRef.current) {
+			const localWindows = store.windowsByWorkspace[LOCAL_WORKSPACE_ID];
+			const userWindows = store.windowsByWorkspace[workspaceId];
+
+			if (localWindows && localWindows.length > 0 && (!userWindows || userWindows.length === 0)) {
+				store.loadWindowState(workspaceId, localWindows);
+			}
+			// Clear local workspace after migration to prevent re-copying on every refresh
+			if (localWindows && localWindows.length > 0) {
+				store.loadWindowState(LOCAL_WORKSPACE_ID, []);
+			}
+		}
+
+		bootstrappedRef.current = true;
+		store.setActiveWorkspace(workspaceId);
+	}, [mounted, auth?.loading, auth?.userId, auth?.orgId]);
+
+	// Prevent hydration mismatch by not rendering until mounted
+	// Also show loading state while auth is resolving
+	if (!mounted || auth?.loading) {
+		return (
+			<div className="h-screen w-screen overflow-hidden">
+				<DesktopBackground />
+			</div>
+		);
+	}
+
+	return (
+		<div className="h-screen w-screen overflow-hidden">
+			<DesktopBackground />
+			<Desktop />
+			<WindowRenderer />
+			<Taskbar launcherToggle={launcherToggle} />
+			<NotificationToasts />
+			<NotificationCenter />
+			<OrphanSessionToast />
+			<WindowSwitcher visible={switcher.visible} windows={switcher.windows} selectedIndex={switcher.selectedIndex} />
+			<ShortcutViewer visible={shortcutViewerVisible} onClose={() => setShortcutViewerVisible(false)} />
+		</div>
+	);
+}

package/src/app/desktop/layout.tsx

@@ -0,0 +1,8 @@
+export default function DesktopLayout({ children }: { children: React.ReactNode }) {
+	return (
+		<>
+			<style>{':root { --os-html-bg: var(--os-bg-primary, var(--ds-background-100, #0a0a0a)); }'}</style>
+			{children}
+		</>
+	);
+}

package/src/app/desktop/page.tsx

@@ -0,0 +1,24 @@
+import { withAuth } from '@workos-inc/authkit-nextjs';
+import { normalizeRole } from '@/lib/auth/roles';
+import { DesktopShell } from './desktop-shell';
+
+/**
+ * Server component that bridges WorkOS session data to the client.
+ *
+ * `withAuth()` runs server-side and returns { user, role, permissions, organizationId }.
+ * The `useAuth()` client hook doesn't expose role/permissions, so this server component
+ * is the bridge that passes them as props to the client-side DesktopShell.
+ *
+ * HeadlessChrome bypass: when middleware skips auth (d3k monitoring), withAuth()
+ * returns { user: null } — we fall back to platform-owner for machine access.
+ */
+export default async function DesktopPage() {
+	const session = await withAuth();
+
+	// HeadlessChrome bypass: no user means d3k monitoring mode
+	const isMachine = !session.user;
+	const serverRole = isMachine ? 'platform-owner' : normalizeRole(session.role);
+	const serverPermissions = isMachine ? [] : (session.permissions ?? []);
+
+	return <DesktopShell serverRole={serverRole} serverPermissions={serverPermissions} />;
+}

package/src/app/globals.css

@@ -0,0 +1,7 @@
+@layer theme, base, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@import "../theme/index.css";

package/src/app/layout.tsx

@@ -0,0 +1,64 @@
+import { AuthKitProvider } from '@workos-inc/authkit-nextjs/components';
+import type { Metadata, Viewport } from 'next';
+import { Geist, Geist_Mono, JetBrains_Mono } from 'next/font/google';
+import { ThemeProvider } from '@/components/ui/theme-provider';
+import './globals.css';
+
+const geistSans = Geist({
+	variable: '--font-geist-sans',
+	subsets: ['latin'],
+});
+
+const geistMono = Geist_Mono({
+	variable: '--font-geist-mono',
+	subsets: ['latin'],
+});
+
+const jetbrainsMono = JetBrains_Mono({
+	variable: '--font-jetbrains-mono',
+	subsets: ['latin'],
+	weight: ['400', '500', '600', '700'],
+});
+
+export const metadata: Metadata = {
+	title: 'Khal',
+	description: 'Desktop-in-browser OS shell',
+};
+
+export const viewport: Viewport = {
+	width: 'device-width',
+	initialScale: 1,
+	maximumScale: 1,
+	userScalable: false,
+	viewportFit: 'cover',
+	interactiveWidget: 'resizes-content',
+};
+
+export default function RootLayout({
+	children,
+}: Readonly<{
+	children: React.ReactNode;
+}>) {
+	return (
+		<html
+			lang="en"
+			suppressHydrationWarning
+			className="tailwind !min-h-screen"
+			style={{ background: 'var(--os-html-bg, transparent)' }}
+		>
+			<body className={`${geistSans.variable} ${geistMono.variable} ${jetbrainsMono.variable} antialiased`}>
+				<AuthKitProvider>
+					<ThemeProvider
+						attribute="class"
+						storageKey="khal-theme-mode"
+						defaultTheme="light"
+						enableSystem
+						disableTransitionOnChange
+					>
+						{children}
+					</ThemeProvider>
+				</AuthKitProvider>
+			</body>
+		</html>
+	);
+}

package/src/app/offline/page.tsx

@@ -0,0 +1,83 @@
+'use client';
+
+export default function OfflinePage() {
+	return (
+		<div
+			style={{
+				height: '100svh',
+				width: '100vw',
+				display: 'flex',
+				flexDirection: 'column',
+				alignItems: 'center',
+				justifyContent: 'center',
+				background: '#0a0f0a',
+				color: '#e0e0e0',
+				fontFamily: "'JetBrains Mono', ui-monospace, monospace",
+				gap: '24px',
+			}}
+		>
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				width="80"
+				height="80"
+				viewBox="0 0 24 24"
+				fill="#39ff14"
+				stroke="none"
+				aria-hidden="true"
+			>
+				<path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z" />
+			</svg>
+
+			<h1
+				style={{
+					margin: 0,
+					fontSize: '2rem',
+					fontWeight: 700,
+					color: '#39ff14',
+					letterSpacing: '0.05em',
+				}}
+			>
+				Khal
+			</h1>
+
+			<p
+				style={{
+					margin: 0,
+					fontSize: '1rem',
+					color: '#a0a0a0',
+					textAlign: 'center',
+					maxWidth: '360px',
+					lineHeight: 1.6,
+				}}
+			>
+				Server is unreachable. Start the services and reload.
+			</p>
+
+			<button
+				onClick={() => window.location.reload()}
+				style={{
+					marginTop: '8px',
+					padding: '10px 28px',
+					background: 'transparent',
+					border: '2px solid #39ff14',
+					borderRadius: '6px',
+					color: '#39ff14',
+					fontFamily: "'JetBrains Mono', ui-monospace, monospace",
+					fontSize: '0.9rem',
+					fontWeight: 600,
+					letterSpacing: '0.08em',
+					cursor: 'pointer',
+					transition: 'background 0.15s',
+				}}
+				onMouseEnter={(e) => {
+					(e.currentTarget as HTMLButtonElement).style.background = 'rgba(57, 255, 20, 0.12)';
+				}}
+				onMouseLeave={(e) => {
+					(e.currentTarget as HTMLButtonElement).style.background = 'transparent';
+				}}
+			>
+				Reload
+			</button>
+		</div>
+	);
+}

package/src/app/page.tsx

@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function Home() {
+	redirect('/desktop');
+}

package/src/app/standalone/[appId]/page.tsx

@@ -0,0 +1,28 @@
+'use client';
+import { useParams } from 'next/navigation';
+import { APP_COMPONENTS, APP_REGISTRY, type AppComponentProps } from '@/components/apps/app-registry';
+import { StandaloneFrame } from '@/components/window/StandaloneFrame';
+
+export default function StandalonePage() {
+	const params = useParams<{ appId: string }>();
+	const appId = params.appId;
+	const AppComponent = APP_COMPONENTS[appId as keyof typeof APP_COMPONENTS] as
+		| React.ComponentType<AppComponentProps>
+		| undefined;
+	const registryEntry = APP_REGISTRY[appId as keyof typeof APP_REGISTRY];
+	const title = registryEntry?.label ?? appId;
+
+	if (!AppComponent) {
+		return (
+			<div style={{ padding: 40, color: '#ef4444' }}>
+				App not found: <code>{appId}</code>
+			</div>
+		);
+	}
+
+	return (
+		<StandaloneFrame appId={appId} title={title}>
+			<AppComponent windowId={`standalone-${appId}`} />
+		</StandaloneFrame>
+	);
+}

package/src/app/standalone/layout.tsx

@@ -0,0 +1,10 @@
+export default function StandaloneLayout({ children }: { children: React.ReactNode }) {
+	return (
+		<>
+			<style>
+				{':root { --os-html-bg: transparent !important; } html, body { background: transparent !important; }'}
+			</style>
+			{children}
+		</>
+	);
+}

package/src/components/app-icon.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { useResolvedIcon } from '@/lib/icons/resolve-window-icon';
+
+interface AppIconProps {
+	appId: string;
+	size?: number;
+	className?: string;
+}
+
+export function AppIcon({ appId, size = 16, className }: AppIconProps) {
+	const iconUrl = useResolvedIcon(appId);
+
+	if (!iconUrl) return null;
+
+	return (
+		<img
+			src={iconUrl}
+			alt=""
+			width={size}
+			height={size}
+			className={className ?? `h-[${size}px] w-[${size}px] shrink-0`}
+			style={{ width: size, height: size }}
+		/>
+	);
+}
+
+/**
+ * Variant that renders a letter-initial fallback when no icon is available.
+ */
+export function AppIconWithFallback({ appId, title, size = 16, className }: AppIconProps & { title: string }) {
+	const iconUrl = useResolvedIcon(appId);
+
+	if (iconUrl) {
+		return (
+			<img
+				src={iconUrl}
+				alt=""
+				width={size}
+				height={size}
+				className={className ?? 'shrink-0 object-contain'}
+				style={{ width: size, height: size }}
+			/>
+		);
+	}
+
+	return (
+		<div
+			className="flex items-center justify-center rounded-lg bg-gray-alpha-200 font-medium text-gray-900 shrink-0"
+			style={{ width: size, height: size, fontSize: size * 0.4 }}
+		>
+			{title.charAt(0).toUpperCase()}
+		</div>
+	);
+}

package/src/components/apps/_echo/schema.ts

@@ -0,0 +1,14 @@
+import { Static, Type } from '@sinclair/typebox';
+
+export const EchoRequest = Type.Object({
+	message: Type.Optional(Type.String()),
+});
+export type EchoRequest = Static<typeof EchoRequest>;
+
+export const EchoResponse = Type.Object({
+	ts: Type.String(),
+	service: Type.Literal('echo'),
+	uptime: Type.Number(),
+	echo: Type.Optional(Type.String()),
+});
+export type EchoResponse = Static<typeof EchoResponse>;

package/src/components/apps/_echo/service/index.ts

@@ -0,0 +1,42 @@
+import { connect } from '@nats-io/transport-node';
+import type { EchoRequest, EchoResponse } from '../schema';
+
+const startTime = Date.now();
+
+async function main() {
+	const nc = await connect({
+		servers: process.env.NATS_URL || 'nats://localhost:4222',
+	});
+
+	console.log('[echo] connected to NATS, subscribing to khal.*.echo');
+
+	const sub = nc.subscribe('khal.*.echo');
+
+	for await (const msg of sub) {
+		let request: EchoRequest = {};
+		try {
+			if (msg.data.length > 0) {
+				request = msg.json<EchoRequest>();
+			}
+		} catch {
+			// empty or invalid payload is fine, echo without message
+		}
+
+		const response: EchoResponse = {
+			ts: new Date().toISOString(),
+			service: 'echo',
+			uptime: (Date.now() - startTime) / 1000,
+			...(request.message != null ? { echo: request.message } : {}),
+		};
+
+		console.log('[echo] request:', request, '-> response:', response);
+		msg.respond(JSON.stringify(response));
+	}
+
+	await nc.closed();
+}
+
+main().catch((err) => {
+	console.error('[echo] fatal:', err);
+	process.exit(1);
+});

package/src/components/apps/app-manifest.ts

@@ -0,0 +1,97 @@
+/**
+ * App manifest — pure data, no React imports.
+ *
+ * Each app declares its metadata here. This is the single source of truth
+ * for app identity, permissions, NATS subject prefixes, and access levels.
+ *
+ * Importable by both the UI (app-registry.ts) and the WS bridge (Bun process).
+ */
+
+/** Role hierarchy from least to most privileged (forward-compatible with Phase 2 multi-org). */
+export const ROLE_HIERARCHY = ['member', 'platform-dev', 'platform-admin', 'platform-owner'] as const;
+export type Role = (typeof ROLE_HIERARCHY)[number];
+
+export interface AppManifestEntry {
+	label: string;
+	/** Permission string required to use this app. */
+	permission: string;
+	/** Minimum role required to access this app. */
+	minRole: Role;
+	/** NATS subject segment after `khal.<orgId>.` — if the app uses NATS subjects. */
+	natsPrefix?: string;
+	defaultSize: { width: number; height: number };
+	/**
+	 * When true, the window skips the normal WindowFrame/WindowContent wrapper.
+	 * The app renders its entire surface including the title bar area.
+	 * Floating window controls (min/max/close) overlay on top.
+	 */
+	fullSizeContent?: boolean;
+}
+
+export type AppId = 'terminal' | 'settings' | 'files' | 'nats-viewer' | 'dev3000';
+
+export const APP_MANIFEST: Record<AppId, AppManifestEntry> = {
+	terminal: {
+		label: 'Terminal',
+		permission: 'terminal',
+		minRole: 'platform-dev',
+		natsPrefix: 'pty',
+		defaultSize: { width: 720, height: 480 },
+		fullSizeContent: true,
+	},
+	settings: {
+		label: 'Settings',
+		permission: 'settings',
+		minRole: 'platform-dev',
+		defaultSize: { width: 800, height: 600 },
+	},
+	files: {
+		label: 'Files',
+		permission: 'files',
+		minRole: 'member',
+		natsPrefix: 'fs',
+		defaultSize: { width: 800, height: 600 },
+	},
+	'nats-viewer': {
+		label: 'NATS Viewer',
+		permission: 'nats-viewer',
+		minRole: 'platform-dev',
+		defaultSize: { width: 900, height: 600 },
+	},
+	dev3000: {
+		label: 'dev3000',
+		permission: 'dev3000',
+		minRole: 'platform-dev',
+		natsPrefix: 'd3k',
+		defaultSize: { width: 960, height: 640 },
+	},
+};
+
+/**
+ * Derived: NATS subject segment → required permission.
+ * Used by the WS bridge for server-side subject-level access control.
+ */
+export const SUBJECT_PERMISSIONS: Record<string, string> = {
+	...Object.fromEntries(
+		Object.values(APP_MANIFEST)
+			.filter((e) => e.natsPrefix)
+			.map((e) => [e.natsPrefix, e.permission])
+	),
+	desktop: 'desktop',
+};
+
+/**
+ * Derived: role → list of permissions granted.
+ * A role gets access to all apps whose minRole is at or below it in the hierarchy.
+ * Used by both client (use-auth.ts) and server (ws-server.ts) for role-based fallback.
+ */
+export const DEFAULT_ROLE_PERMISSIONS: Record<string, string[]> = Object.fromEntries(
+	ROLE_HIERARCHY.map((role) => {
+		const roleLevel = ROLE_HIERARCHY.indexOf(role);
+		const permissions = Object.values(APP_MANIFEST)
+			.filter((app) => ROLE_HIERARCHY.indexOf(app.minRole) <= roleLevel)
+			.map((app) => app.permission);
+		// Desktop control is available to all roles
+		return [role, [...permissions, 'desktop']];
+	})
+);

package/src/components/apps/app-registry.ts

@@ -0,0 +1,55 @@
+'use client';
+
+import { APP_MANIFEST, type AppId } from './app-manifest';
+import { Dev3000App } from './dev3000';
+import { FilesApp } from './files/FilesApp';
+import { NatsViewer } from './nats-viewer';
+import { Settings } from './settings/Settings';
+import { MultiTerminalApp } from './terminal/ui/MultiTerminalApp';
+
+export type { AppId } from './app-manifest';
+
+export interface AppComponentProps {
+	windowId: string;
+	meta?: Record<string, unknown>;
+}
+
+export interface AppRegistryEntry {
+	component: React.ComponentType<AppComponentProps>;
+	label: string;
+	defaultSize: { width: number; height: number };
+	requiredPermission?: string;
+}
+
+/** Map appId → React component. Add new apps here. */
+const APP_COMPONENTS_MAP: Record<AppId, React.ComponentType<AppComponentProps>> = {
+	terminal: MultiTerminalApp,
+	settings: Settings,
+	files: FilesApp,
+	'nats-viewer': NatsViewer,
+	dev3000: Dev3000App,
+};
+
+/**
+ * Central registry derived from APP_MANIFEST + component map.
+ * Metadata (label, permission, size) comes from the manifest.
+ * Components are added here (can't live in manifest — React dependency).
+ */
+export const APP_REGISTRY: Record<AppId, AppRegistryEntry> = Object.fromEntries(
+	(Object.keys(APP_MANIFEST) as AppId[]).map((id) => [
+		id,
+		{
+			component: APP_COMPONENTS_MAP[id],
+			label: APP_MANIFEST[id].label,
+			defaultSize: APP_MANIFEST[id].defaultSize,
+			requiredPermission: APP_MANIFEST[id].permission,
+		},
+	])
+) as Record<AppId, AppRegistryEntry>;
+
+/**
+ * Flat component lookup for backwards compatibility.
+ */
+export const APP_COMPONENTS: Record<string, React.ComponentType<AppComponentProps>> = Object.fromEntries(
+	Object.entries(APP_REGISTRY).map(([id, entry]) => [id, entry.component])
+);