Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
"use client";
/* Android (Material-You) mobile shell — same store + apps as every other shell,
one fullscreen app at a time (mirrors MobileShell). Chrome: pull-DOWN on the home
surface → the REAL Control Center feature (controlCenter slot; the old fake Shade
is gone), big clock + date on the wallpaper, search pill → Spotlight, an App Drawer
opened by TAPPING the bottom "All apps" target — it is drawn as a grabber, but no
swipe-up gesture is wired here, and this line claiming one is what sent a later
motion comment on to justify an animation direction by a gesture that does not
exist — gesture nav (back / home / recents), and a Recents card deck. Transparent
root: the shared <Wallpaper> shows through, like every other shell. Bottom inset
system: the root sets `--android-nav` (NavBar row height); every surface that must
clear the bottom chrome pads with `calc(var(--android-nav) + var(--sai-bottom))`. */
import { Button } from "@/components/ui/button";
import { useCallback, useMemo, useRef, useState, type CSSProperties } from "react";
import { useUrlHome } from "../../../hooks/use-url-home";
import { Search } from "lucide-react";
import { useApps } from "../../../lib/registry";
import { usePullDown } from "../../../hooks/use-pull-down";
import { useWindowOrder, useFocused, useWindow } from "../../../hooks/use-shell";
import { shellStore, openWindow, focusApp, minimizeWindow, restoreWindow, toggleSpotlight, toggleInspector } from "../../../lib/store";
import { WindowContent } from "../../window-content";
import { Slot } from "../../../registry/feature-registry";
import { ShellUIProvider, type ShellUI } from "../../../registry/shell-ui";
import { Clock } from "../../clock";
import { AppCell, AppDrawer, NavBar, Recents } from "./android-parts";
import { M3_PRESS } from "./android-motion";
import { ShellContextMenu, useShellContextMenu } from "../context-menu";
import type { AppDescriptor } from "../../../lib/types";
import { AndroidNotifications } from "./android-notifications";
import { useMobileNavigationInfo } from "../../../lib/mobile-navigation";
import { useResponsive } from "../../../responsive/use-responsive";
import { useAndroidBrowserBack } from "./use-android-browser-back";
import { AndroidFeatureHeader } from "./android-feature-header";
function AndroidShell() {
const apps = useApps();
const responsive = useResponsive();
const showSystemNav = responsive.vw >= 768; // only the desktop PhoneFrame preview draws fake Android system buttons
const order = useWindowOrder();
const focused = useFocused();
const [drawer, setDrawer] = useState(false);
const [cc, setCc] = useState(false); // control center (pull down on home)
const [notif, setNotif] = useState(false); // notification shade (pull down, left half)
const [recents, setRecents] = useState(false);
const gridRef = useRef<HTMLDivElement>(null);
// URL → surface (same derivation as the iOS shell): a pathname naming an app slug
// shows the app pane (UrlSync opens/focuses its window); user gestures override,
// keyed to the pathname made at — deep links AND back/forward, no effect setState.
const { home, setHome } = useUrlHome(apps);
const dockable = useMemo(() => apps.filter((a) => !a.noDock), [apps]);
const pinned = useMemo(() => dockable.filter((a) => a.pinned), [dockable]);
const topId =
focused && !shellStore.getWindow(focused)?.minimized
? focused
: ([...order].reverse().find((id) => !shellStore.getWindow(id)?.minimized) ?? null);
const top = useWindow(topId ?? "__none__"); // reactive: re-renders on the active window's own payload/title changes
const showApp = !home && !!top;
const activeApp = top ? apps.find((a) => a.id === top.app) : null;
const mobileNav = useMobileNavigationInfo(activeApp?.id);
const launch = useCallback(
(app: AppDescriptor) => {
// Resume-don't-duplicate (real-Android): a home/drawer tap brings the
// existing window forward; only a missing one spawns.
if (!focusApp(app.id)) openWindow(app.id, app.title, app.defaultSize, undefined, { multi: app.multi });
setDrawer(false);
setRecents(false);
setHome(false);
},
[setHome],
);
const launchById = useCallback(
(id: string) => {
const app = apps.find((a) => a.id === id);
if (app) launch(app);
},
[apps, launch],
);
const goHome = useCallback(() => {
if (topId) minimizeWindow(topId);
setHome(true);
setDrawer(false);
setRecents(false);
setCc(false);
setNotif(false);
}, [topId, setHome]);
const resume = (id: string) => {
restoreWindow(id);
setRecents(false);
setHome(false);
};
const browserLayer = drawer
? { key: "drawer", onBack: () => setDrawer(false) }
: showApp && activeApp
? {
key: mobileNav?.backLabel && mobileNav.backLabel !== "Home"
? `detail:${activeApp.id}:${mobileNav.title}`
: `app:${activeApp.id}`,
onBack: mobileNav?.onBack ?? goHome,
}
: null;
// On a real Android phone the browser/OS already owns the system Back gesture.
// Mirror shell layers into same-URL history entries so that gesture closes the
// app drawer/detail/app before it ever navigates away from MSO. PhoneFrame keeps
// the simulated 3-button row for desktop preview and does not install this trap.
const browserBack = useAndroidBrowserBack(!showSystemNav, browserLayer);
// Pull-DOWN on home: LEFT half → notifications, RIGHT half → Control Center
// (mirrors the iOS split). The grid keeps scrolling — the pull only arms at top.
const pullDown = usePullDown((sx) => (sx < window.innerWidth / 2 ? setNotif(true) : setCc(true)), gridRef);
// Home-background long-press / right-click → this shell's registry menu
// (native long-press fires contextmenu; controls are skipped).
const menu = useShellContextMenu("android", "mobile");
const onHomeContext = (e: React.MouseEvent) => {
if ((e.target as HTMLElement).closest("button,a,input")) return;
menu.open(e);
};
const quickAppIds = useMemo(
() => (pinned.length ? pinned : dockable.slice(0, 4)).map((a) => a.id),
[pinned, dockable],
);
const shellUI = useMemo<ShellUI>(
() => ({
controlCenterOpen: cc,
setControlCenterOpen: setCc,
openApp: launch,
openAppById: launchById,
quickAppIds,
}),
[cc, launch, launchById, quickAppIds],
);
return (
<ShellUIProvider value={shellUI}>
<div
className="absolute inset-0 z-[10] flex flex-col overflow-hidden text-foreground"
style={{ "--android-nav": showSystemNav ? "48px" : "0px" } as CSSProperties}
>
<div
data-slot="system-status-host"
data-status-placement="android-status-bar"
className="pointer-events-none absolute inset-x-0 top-0 z-[40] flex items-center justify-end px-2"
style={{ height: "var(--sai-top)" }}
>
<div className="pointer-events-auto"><Slot region="systemStatus" /></div>
</div>
{/* HOME (always mounted; app overlays it — inert while covered so its
grid + NavBar drop out of tab/AT order under the z-20 app layer).
Pull down → Control Center; clock+date live on the wallpaper. */}
<div className="flex min-h-0 flex-1 flex-col overflow-y-auto px-5 pb-1" inert={showApp} aria-hidden={showApp} onPointerDown={pullDown} onContextMenu={onHomeContext} style={{ paddingTop: "var(--sai-top, 0px)", paddingBottom: showSystemNav ? undefined : "var(--sai-bottom)" }}>
{/* Same reason as the app labels: the clock sits on the wallpaper, so it
needs its own light-on-dark treatment rather than the theme foreground. */}
{/* `[&_div]:text-white/80` targets Clock mode="date", which hard-codes
text-muted-foreground — correct on a card, invisible on a wallpaper. The
descendant selector is (0,1,1) so it beats that class deterministically,
without !important and without changing Clock's shared API for one caller. */}
<div className="mt-6 shrink-0 text-white [text-shadow:0_1px_3px_rgba(0,0,0,0.5)] [&_div]:text-white/80">
<Clock mode="big" />
<Clock mode="date" />
</div>
<button
type="button"
onClick={toggleSpotlight}
className={`mt-4 flex h-11 shrink-0 items-center gap-3 rounded-full border border-border bg-card/80 px-4 text-left shadow-sm backdrop-blur active:scale-[0.97] ${M3_PRESS}`}
>
<Search className="size-4 text-muted-foreground" />
<span className="text-sm text-muted-foreground">Search</span>
</button>
{/* Home widgets — shared Today surface, height-capped so it never crowds the grid. */}
<div className="mt-4 max-h-[36vh] min-w-0 max-w-full shrink-0 overflow-x-hidden overflow-y-auto [scrollbar-width:none]">
<Slot region="today" />
</div>
{/* EVERY dockable app gets a home icon — the old slice(0, 12) cap hid most of
an agent workspace (20-24 Hermes/OpenClaw features). The grid is already
`min-h-0 overflow-y-auto`, so it just scrolls a longer list; usePullDown
still arms only at scrollTop 0, so the shade gesture is unchanged. */}
{/* White + shadow HERE rather than inside AppCell: the same cell is reused by
the App Drawer, which is a light sheet where white text would vanish. This
grid is the only surface that sits directly on the wallpaper. Matches the
treatment the iOS home and app library already use. */}
<div ref={gridRef} className="mt-5 grid min-h-0 grid-cols-4 content-start gap-x-3 gap-y-5 overflow-y-auto text-white [scrollbar-width:none] [text-shadow:0_1px_3px_rgba(0,0,0,0.5)] [&::-webkit-scrollbar]:hidden">
{dockable.map((a) => (
<AppCell key={a.id} app={a} onClick={() => launch(a)} />
))}
</div>
{/* 0.97, not the 0.90 the icon-only buttons get: this target carries an
11px text label, and scaling type resamples it — blurry for the length
of the press on a low-DPI panel. Same reason AppCell scales its icon
and leaves its label alone, and the same 0.97 the search pill uses. */}
<Button type="button" variant="ghost"
onClick={() => setDrawer(true)}
className={`h-auto p-0 font-normal hover:bg-transparent mx-auto mb-1 mt-auto flex flex-col items-center gap-0.5 text-[11px] text-muted-foreground active:scale-[0.97] ${M3_PRESS}`}
>
<span className="h-1 w-9 rounded-full bg-foreground/30" />
All apps
</Button>
</div>
{showSystemNav && <NavBar inactive={showApp} onBack={goHome} onHome={goHome} onRecents={() => setRecents(true)} />}
{/* Fullscreen app. Open = M3 SPATIAL SLOW (k=200, ζ=0.8, ~511ms). The speed
tier is chosen by the SIZE of the thing that moves, not by how far it
moves: this is the largest surface in the shell, so "slow" is right even
though mobileAppOpen only travels 10px. Most of the perceived movement is over
by ~40% of that; the tail is the settle, which is exactly the part a
cubic-bezier cannot express. Transform-only on purpose — no opacity,
because pairing an effects fade with a spatial slide inside ONE animation
would force a single easing on both families. */}
{showApp && activeApp && top && (
<div className="absolute inset-0 z-[20] flex flex-col bg-background [animation:mobileAppOpen_var(--m3-dur-spatial-slow)_var(--m3-spatial)] [transform-origin:center_bottom]">
<AndroidFeatureHeader
title={mobileNav?.title ?? activeApp.title}
backLabel={mobileNav?.backLabel ?? "Home"}
onBack={() => browserBack()}
onAI={toggleInspector}
/>
<main className="relative min-h-0 flex-1 overflow-x-hidden overflow-y-auto [container-type:inline-size]">
<WindowContent key={top.id} app={top.app} payload={top.payload} winId={top.id} />
</main>
{showSystemNav && <NavBar onBack={mobileNav?.onBack ?? goHome} onHome={goHome} onRecents={() => setRecents(true)} />}
</div>
)}
{drawer && <AppDrawer apps={dockable} onLaunch={launch} onClose={() => browserBack()} />}
{recents && <Recents order={order} apps={apps} onResume={resume} onHome={goHome} />}
{/* live-activity chip (parity with iOS Dynamic Island) — renders only
while an app reports an activity (render/copy…); reads the same store. */}
<Slot region="topPill" />
<Slot region="controlCenter" />
<AndroidNotifications open={notif} onClose={() => setNotif(false)} />
<ShellContextMenu state={menu.state} onClose={menu.close} />
</div>
</ShellUIProvider>
);
}
export { AndroidShell };