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
perf(shell): defer the lock curtain, keeping its timer eager
Abdurrahman Fakhrul198a9f5155b9
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 687f2d32..4af2abc2 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -14,7 +14,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh**Fixed**-- `tui` stop the panel erasing the slash menu, and keep the banner ASCII art+- `tui` stop the panel erasing the slash menu, and keep the banner ASCII art (#221)- `security` validate the model half of a provider/model ref- `security` read only .message from a caught error, never stringify it- `ci` check out full history, or the changelog gate fails on every rundiff --git a/frontend/slices/appshell/defer-eager-boundaries.test.ts b/frontend/slices/appshell/defer-eager-boundaries.test.tsindex bb78165b..82e4cffc 100644--- a/frontend/slices/appshell/defer-eager-boundaries.test.ts+++ b/frontend/slices/appshell/defer-eager-boundaries.test.ts@@ -40,20 +40,25 @@ describe("Eager bundle boundaries", () => {expect(alfaBarrel).toContain("alfa-run-state");});- it("defers widgets and shortcut-help while keeping lock-screen eager for security boundary", () => {+ it("defers widgets, shortcut-help and the lock-screen curtain, but never the auto-lock timer", () => {const widgetsIndex = readFileSync("frontend/slices/appshell/features/widgets/index.ts", "utf8");const shortcutIndex = readFileSync("frontend/slices/appshell/features/shortcut-help/index.ts", "utf8");const lockIndex = readFileSync("frontend/slices/appshell/features/lock-screen/index.ts", "utf8");- const lockScreenSource = readFileSync("frontend/slices/appshell/features/lock-screen/components/lock-screen.tsx", "utf8");+ const provider = readFileSync("frontend/slices/appshell/provider/app-shell.tsx", "utf8");+ const timer = readFileSync("frontend/slices/appshell/lib/use-idle-auto-lock.ts", "utf8");expect(widgetsIndex).toContain("DeferredDesktopWidgets");expect(widgetsIndex).toContain("DeferredMobileWidgets");expect(shortcutIndex).toContain("DeferredShortcutHelp");- // Security invariant: lock-screen remains eagerly mounted to preserve idle auto-lock- // as enforced by frontend/slices/organization/bundle-boundary.test.ts- expect(lockIndex).toContain('from "./components/lock-screen"');- expect(lockScreenSource).toContain("autoLockMinutes");- expect(lockScreenSource).toContain("setTimeout(lock");+ // Security invariant, restated: the curtain may be deferred because it is only presentation.+ // The idle timer must stay eager, mounted from the shell provider that always renders.+ expect(lockIndex).toContain("DeferredLockScreen");+ expect(lockIndex).not.toContain('from "./components/lock-screen"');+ expect(provider).toContain("useIdleAutoLock()");+ expect(timer).toContain("autoLockMinutes");+ expect(timer).toContain("setTimeout(lock");+ // And the deferred wrapper must still gate on the lock state, not mount unconditionally.+ expect(readFileSync("frontend/slices/appshell/features/lock-screen/deferred.tsx", "utf8")).toContain("useLocked()");});});diff --git a/frontend/slices/appshell/features/lock-screen/components/lock-screen.tsx b/frontend/slices/appshell/features/lock-screen/components/lock-screen.tsxindex 74a1c562..c3fdb01f 100644--- a/frontend/slices/appshell/features/lock-screen/components/lock-screen.tsx+++ b/frontend/slices/appshell/features/lock-screen/components/lock-screen.tsx@@ -4,32 +4,16 @@ import { useEffect, useState } from "react";import { Lock } from "lucide-react";import { useActiveShell } from "../../../registry/shells";import { IosLockScreen } from "./ios-lock-screen";-import { autoLockMinutes, lock, requestUnlock, useLocked } from "../../../lib/lock";+import { requestUnlock, useLocked } from "../../../lib/lock";// Fullscreen privacy curtain: blurred backdrop, big clock, click/key unlocks-// (through the consumer guard when one is injected). Owns the idle timer.+// (through the consumer guard when one is injected). The idle timer is NOT here: it lives in+// appshell/provider via useIdleAutoLock, so deferring this component cannot defer the auto-lock.// The curtain MOUNTS per lock, so the clock seeds in a lazy initializer// instead of an effect-driven setState (react-hooks v6).export function LockScreen() {const locked = useLocked();- // idle auto-lock — any pointer/key activity resets the countdown- useEffect(() => {- let timer: number | undefined;- const arm = () => {- const min = autoLockMinutes();- if (timer) window.clearTimeout(timer);- if (min) timer = window.setTimeout(lock, min * 60_000);- };- const events: (keyof WindowEventMap)[] = ["pointerdown", "pointermove", "keydown", "wheel"];- events.forEach((e) => window.addEventListener(e, arm, { passive: true }));- arm();- return () => {- if (timer) window.clearTimeout(timer);- events.forEach((e) => window.removeEventListener(e, arm));- };- }, []);-const shell = useActiveShell();if (!locked) return null;return shell.id === "ios" ? <IosLockScreen /> : <LockCurtain />;diff --git a/frontend/slices/appshell/features/lock-screen/deferred.tsx b/frontend/slices/appshell/features/lock-screen/deferred.tsxnew file mode 100644index 00000000..0c1a1fbb--- /dev/null+++ b/frontend/slices/appshell/features/lock-screen/deferred.tsx@@ -0,0 +1,22 @@+"use client";++import { useLocked } from "../../lib/lock";+import { DeferredSurface } from "../../primitives/deferred-surface";++const load = () => import("./components/lock-screen").then((module) => ({ default: module.LockScreen }));++/**+ * Lock screen presentation, deferred — but only the presentation.+ *+ * The idle auto-lock timer that used to justify keeping this eager now lives in+ * `appshell/provider/app-shell.tsx` via `useIdleAutoLock`, mounted whether or not this chunk has+ * been fetched. So `useLocked()` is read here (it is a cheap subscription in `lib/lock`), and the+ * curtain's chunk is requested the moment the shell is actually locked.+ *+ * `keepMounted` is deliberately not set: the curtain already returns null when unlocked, and+ * keeping a locked shell's overlay alive after unlock would hold its clock interval running.+ */+export function DeferredLockScreen() {+ const locked = useLocked();+ return <DeferredSurface active={locked} load={load} label="Lock screen" />;+}diff --git a/frontend/slices/appshell/features/lock-screen/index.ts b/frontend/slices/appshell/features/lock-screen/index.tsindex 93a03381..09028299 100644--- a/frontend/slices/appshell/features/lock-screen/index.ts+++ b/frontend/slices/appshell/features/lock-screen/index.ts@@ -1,8 +1,10 @@import { defineFeature } from "../../registry/types";-import { LockScreen } from "./components/lock-screen";+import { DeferredLockScreen } from "./deferred";-// Lock screen — privacy curtain overlay + idle auto-lock (lib/lock).+// Lock screen — privacy curtain overlay. The idle auto-lock timer is NOT part of this feature's+// eager cost any more: it moved to appshell/provider (useIdleAutoLock), so this overlay can be+// deferred without weakening protection.export const lockScreenFeature = defineFeature({id: "lock-screen",- slots: { overlay: LockScreen },+ slots: { overlay: DeferredLockScreen },});diff --git a/frontend/slices/appshell/lib/lock.ts b/frontend/slices/appshell/lib/lock.tsindex 3d3a919b..281a03be 100644--- a/frontend/slices/appshell/lib/lock.ts+++ b/frontend/slices/appshell/lib/lock.ts@@ -5,8 +5,9 @@ import { registerCommands } from "./commands";// Lock screen — overlay state + an optional consumer-injected unlock guard// (auth check). No guard → click/key unlocks (kiosk-style privacy curtain).-// Idle auto-lock minutes persist to sv:autolock; the bundled lock-screen-// feature owns the idle timer.+// Idle auto-lock minutes persist to sv:autolock. The TIMER is not here: it is+// useIdleAutoLock (./use-idle-auto-lock), mounted from the shell provider so it+// stays eager even though the curtain's chunk is deferred.let locked = false;let guard: (() => boolean | Promise<boolean>) | null = null;diff --git a/frontend/slices/appshell/lib/use-idle-auto-lock.ts b/frontend/slices/appshell/lib/use-idle-auto-lock.tsnew file mode 100644index 00000000..da42c9a9--- /dev/null+++ b/frontend/slices/appshell/lib/use-idle-auto-lock.ts@@ -0,0 +1,39 @@+"use client";++import { useEffect } from "react";+import { autoLockMinutes, lock } from "./lock";++/**+ * Idle auto-lock timer, owned outside the lock-screen component.+ *+ * Why this is separate: the timer used to live in `LockScreen`'s effect, which only mounted+ * when the feature was eagerly imported. That made the timer a reason to keep the whole lock+ * screen (and its iOS variant, clock and complications) in the first-load bundle — and a+ * security-critical timer that only starts once its UI is loaded is the wrong shape anyway.+ *+ * Armed here, from the shell provider that is always mounted, so deferring the lock screen's+ * *presentation* cannot defer its *protection*. Behaviour is unchanged: any pointer, key or+ * wheel activity re-arms the countdown, and a null preference disarms it.+ *+ * ponytail: re-arms on every qualifying event with a fresh timeout, exactly as the old effect+ * did. A throttled deadline (`deadline = now + min`, checked on tick) would do less work, but it+ * would also change what "idle" means at the boundary; add it if profiling shows this costs+ * anything measurable.+ */+export function useIdleAutoLock(): void {+ useEffect(() => {+ let timer: number | undefined;+ const arm = () => {+ const min = autoLockMinutes();+ if (timer) window.clearTimeout(timer);+ timer = min ? window.setTimeout(lock, min * 60_000) : undefined;+ };+ const events: (keyof WindowEventMap)[] = ["pointerdown", "pointermove", "keydown", "wheel"];+ events.forEach((e) => window.addEventListener(e, arm, { passive: true }));+ arm();+ return () => {+ if (timer) window.clearTimeout(timer);+ events.forEach((e) => window.removeEventListener(e, arm));+ };+ }, []);+}diff --git a/frontend/slices/appshell/provider/app-shell.tsx b/frontend/slices/appshell/provider/app-shell.tsxindex d1ab2ff0..f80166f2 100644--- a/frontend/slices/appshell/provider/app-shell.tsx+++ b/frontend/slices/appshell/provider/app-shell.tsx@@ -3,6 +3,7 @@import { useEffect, useMemo, type ComponentType, type ReactNode } from "react";import { OsDesktop } from "../components/desktop";import { configureWindowTitle, startWindowTitleSync } from "../lib/window-title";+import { useIdleAutoLock } from "../lib/use-idle-auto-lock";import { AppRegistryProvider } from "../lib/registry";import { ResponsiveProvider } from "../responsive/responsive-provider";import { BrandProvider } from "../registry/brand";@@ -41,6 +42,10 @@ export function AppShell({ manifest }: { manifest: ShellManifest }) {configureWindowTitle({ suffix: manifest.brand.name });startWindowTitleSync();}, [manifest.brand.name]);++ // Idle auto-lock is armed here, not in the lock-screen component: the component may be+ // deferred for bundle reasons, its protection may not.+ useIdleAutoLock();const providers = features.map((f) => f.provider).filter((p): p is ComponentType<{ children: ReactNode }> => Boolean(p));diff --git a/frontend/slices/organization/bundle-boundary.test.ts b/frontend/slices/organization/bundle-boundary.test.tsindex 7c0b309b..229c409c 100644--- a/frontend/slices/organization/bundle-boundary.test.ts+++ b/frontend/slices/organization/bundle-boundary.test.ts@@ -14,7 +14,13 @@ describe("shell graph loading boundaries", () => {expect(read("components/shared/graph-canvas.tsx")).toContain('import "@xyflow/react/dist/style.css"');});it("keeps lock protection, notification plumbing and clipboard capture eager", () => {- expect(read("frontend/slices/appshell/features/lock-screen/index.ts")).toContain('from "./components/lock-screen"');+ // The invariant is that auto-lock is ARMED at boot, not that the curtain's markup ships in the+ // first-load bundle. The timer moved to appshell/provider (useIdleAutoLock) precisely so the+ // presentation can be deferred without deferring the protection.+ expect(read("frontend/slices/appshell/provider/app-shell.tsx")).toContain("useIdleAutoLock()");+ expect(read("frontend/slices/appshell/lib/use-idle-auto-lock.ts")).toContain("setTimeout(lock");+ expect(read("frontend/slices/appshell/lib/use-idle-auto-lock.ts")).toContain("autoLockMinutes");+ expect(read("frontend/slices/appshell/features/lock-screen/index.ts")).not.toContain('from "./components/lock-screen"');expect(read("frontend/slices/appshell/features/notifications/index.ts")).toContain('from "./components/toast-host"');const clipboard = read("frontend/slices/appshell/features/clipboard/components/clipboard-overlay.tsx");expect(clipboard).toContain("useEffect(() => startClipboardCapture(), [])");