Skip to content

🙌 OpenHands: AI-Driven Development

feat: pin a favorite sidebar page as the home route (#16868)

Hiep Lef48eca6ab914
diff --git a/__tests__/components/features/sidebar/sidebar.test.tsx b/__tests__/components/features/sidebar/sidebar.test.tsx
index 194aa439da..b2bfcc3b25 100644
--- a/__tests__/components/features/sidebar/sidebar.test.tsx
+++ b/__tests__/components/features/sidebar/sidebar.test.tsx
@@ -15,6 +15,7 @@ import {
NavigationProvider,
type NavigationContextValue,
} from "#/context/navigation-context";
+import { getPinnedHomeRouteKey } from "#/hooks/use-pinned-home-route";
import translations from "#/i18n/translation.json";
// The global `useTranslation` mock in `vitest.setup.ts` returns the key
@@ -507,4 +508,33 @@ describe("Sidebar", () => {
"Automate",
);
});
+
+ it("pins and unpins a sidebar page as the home route without navigating", () => {
+ // Arrange: the mocked active backend is `local` with no org.
+ const pinKey = getPinnedHomeRouteKey("local", null);
+ const { navigate } = renderSidebar("/conversations");
+ const pinToggle = screen.getByTestId("sidebar-pin-home-toggle-customize");
+ expect(pinToggle).toHaveAttribute("aria-pressed", "false");
+ expect(pinToggle).toHaveAttribute("aria-label", "Pin as home page");
+
+ // Act: pin Customize as the home page.
+ fireEvent.click(pinToggle);
+
+ // Assert: the toggle flips and the pin persists for the active backend.
+ expect(pinToggle).toHaveAttribute("aria-pressed", "true");
+ expect(pinToggle).toHaveAttribute("aria-label", "Unpin as home page");
+ expect(window.localStorage.getItem(pinKey)).toBe(
+ JSON.stringify("/customize"),
+ );
+ expect(navigate).not.toHaveBeenCalled();
+
+ // Act: unpin from the same control.
+ fireEvent.click(pinToggle);
+
+ // Assert: the pin is gone.
+ expect(pinToggle).toHaveAttribute("aria-pressed", "false");
+ expect(window.localStorage.getItem(pinKey)).not.toBe(
+ JSON.stringify("/customize"),
+ );
+ });
});
diff --git a/__tests__/hooks/use-pinned-home-route.test.ts b/__tests__/hooks/use-pinned-home-route.test.ts
new file mode 100644
index 0000000000..bfeb09c72d
--- /dev/null
+++ b/__tests__/hooks/use-pinned-home-route.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import {
+ getPinnedHomeRouteKey,
+ PINNED_HOME_ROUTE_KEY,
+} from "#/hooks/use-pinned-home-route";
+
+describe("getPinnedHomeRouteKey", () => {
+ it("scopes the storage key by backend and org", () => {
+ expect(getPinnedHomeRouteKey("backend-a", "org-1")).toBe(
+ `${PINNED_HOME_ROUTE_KEY}:backend-a:org-1`,
+ );
+ expect(getPinnedHomeRouteKey("backend-a", null)).toBe(
+ `${PINNED_HOME_ROUTE_KEY}:backend-a:-`,
+ );
+ expect(getPinnedHomeRouteKey("backend-a", "org-1")).not.toBe(
+ getPinnedHomeRouteKey("backend-b", "org-1"),
+ );
+ });
+});
diff --git a/__tests__/routes/index-home-pinned-route.test.ts b/__tests__/routes/index-home-pinned-route.test.ts
new file mode 100644
index 0000000000..9bee797376
--- /dev/null
+++ b/__tests__/routes/index-home-pinned-route.test.ts
@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ __resetActiveStoreForTests,
+ setActiveSelection,
+ setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { getPinnedHomeRouteKey } from "#/hooks/use-pinned-home-route";
+import { clientLoader } from "#/routes/index-home";
+
+/**
+ * The automation interface manifest is withheld so the "pinned page's
+ * feature is no longer available" case is exercisable; /customize has no
+ * such gate and stays pinnable.
+ */
+vi.mock("#/manifests/manifest-sources", async (importOriginal) => {
+ const actual =
+ await importOriginal<typeof import("#/manifests/manifest-sources")>();
+ return { ...actual, AUTOMATION_INTERFACE_CANDIDATE: undefined };
+});
+
+// Only the loader is under test; keep the home screen's tree out of it.
+vi.mock("#/routes/home", () => ({ default: () => null }));
+
+const BACKEND: Backend = {
+ id: "backend-a",
+ name: "Backend A",
+ host: "http://localhost:3000",
+ apiKey: "",
+ kind: "local",
+};
+
+const PIN_KEY = getPinnedHomeRouteKey(BACKEND.id, null);
+
+describe("the index route with a pinned home page", () => {
+ beforeEach(() => {
+ window.localStorage.clear();
+ setRegisteredBackends([BACKEND]);
+ setActiveSelection({ backendId: BACKEND.id });
+ });
+
+ afterEach(() => {
+ window.localStorage.clear();
+ window.sessionStorage.clear();
+ __resetActiveStoreForTests();
+ });
+
+ it("redirects / to the pinned page of the active backend", () => {
+ // Arrange
+ window.localStorage.setItem(PIN_KEY, JSON.stringify("/customize"));
+
+ // Act
+ const result = clientLoader();
+
+ // Assert
+ expect(result).toBeInstanceOf(Response);
+ expect((result as Response).headers.get("Location")).toBe("/customize");
+ });
+
+ it("renders the default home when no pin is set", () => {
+ expect(clientLoader()).toBeNull();
+ });
+
+ it("falls back to the default home when the stored pin does not resolve, leaving the value intact", () => {
+ for (const rawValue of ['"/"', '"/nonexistent"', "not-json"]) {
+ // Arrange
+ window.localStorage.setItem(PIN_KEY, rawValue);
+
+ // Act & Assert
+ expect(clientLoader()).toBeNull();
+ expect(window.localStorage.getItem(PIN_KEY)).toBe(rawValue);
+ }
+ });
+
+ it("falls back to the default home when the pinned page's interface is absent", () => {
+ // Arrange: /automations was pinnable when set, but this deployment has
+ // no admitted automation interface manifest.
+ window.localStorage.setItem(PIN_KEY, JSON.stringify("/automations"));
+
+ // Act & Assert
+ expect(clientLoader()).toBeNull();
+ });
+
+ it("ignores a pin stored for a different backend", () => {
+ // Arrange
+ window.localStorage.setItem(
+ getPinnedHomeRouteKey("backend-b", null),
+ JSON.stringify("/customize"),
+ );
+
+ // Act & Assert
+ expect(clientLoader()).toBeNull();
+ });
+});
diff --git a/src/components/features/sidebar/sidebar-nav-link.tsx b/src/components/features/sidebar/sidebar-nav-link.tsx
index d8a1fcc9b7..eaa9faae34 100644
--- a/src/components/features/sidebar/sidebar-nav-link.tsx
+++ b/src/components/features/sidebar/sidebar-nav-link.tsx
@@ -1,7 +1,9 @@
import React from "react";
+import { Pin } from "lucide-react";
import { NavigationLink } from "#/components/shared/navigation-link";
import { StyledTooltip } from "#/components/shared/buttons/styled-tooltip";
import { useNavigation } from "#/context/navigation-context";
+import { hoverRevealActionClassName } from "#/utils/hover-reveal-classes";
import { cn } from "#/utils/utils";
import { SidebarCollapsedIconSlot } from "./sidebar-collapsed-icon-slot";
import {
@@ -23,6 +25,14 @@ function isPathActive(currentPath: string, to: string, end: boolean) {
return currentPath === to || currentPath.startsWith(`${to}/`);
}
+export interface SidebarNavLinkPinAction {
+ pinned: boolean;
+ onToggle: () => void;
+ /** Localized aria-label; pin vs unpin variants resolved by the caller. */
+ label: string;
+ testId: string;
+}
+
interface SidebarNavLinkProps {
to: string;
label: string;
@@ -39,6 +49,8 @@ interface SidebarNavLinkProps {
* (e.g. the Extensions link being active on /mcp and /plugins too).
*/
forceActive?: boolean;
+ /** Pin-as-home toggle; rendered only when the sidebar is expanded. */
+ pinAction?: SidebarNavLinkPinAction;
}
export function SidebarNavLink({
@@ -52,9 +64,11 @@ export function SidebarNavLink({
collapsed = false,
hoverContent,
forceActive = false,
+ pinAction,
}: SidebarNavLinkProps) {
const { currentPath } = useNavigation();
const active = forceActive || isPathActive(currentPath, to, end);
+ const showPinAction = !collapsed && pinAction != null;
const link = (
<NavigationLink
@@ -81,6 +95,8 @@ export function SidebarNavLink({
: SIDEBAR_ROW_INTERACTIVE_CLASS.idle),
disabled && "opacity-50",
disabled && "pointer-events-none",
+ // Constant right reserve so label truncation doesn't reflow on hover.
+ showPinAction && "pr-9",
)}
>
{icon ? (
@@ -96,7 +112,40 @@ export function SidebarNavLink({
</NavigationLink>
);
- if (!collapsed) return link;
+ if (!collapsed) {
+ if (!pinAction) return link;
+
+ // NavigationLink renders an <a>, so the pin toggle is an absolutely
+ // positioned sibling rather than a nested button. Bare `group` is safe
+ // here: only collapsed rows use it, and this branch is expanded-only.
+ return (
+ <div className="group relative">
+ {link}
+ <button
+ type="button"
+ data-testid={pinAction.testId}
+ aria-pressed={pinAction.pinned}
+ aria-label={pinAction.label}
+ onClick={(event) => {
+ event.preventDefault();
+ event.stopPropagation();
+ pinAction.onToggle();
+ }}
+ className={cn(
+ "absolute right-1.5 top-1/2 -translate-y-1/2",
+ "flex shrink-0 cursor-pointer items-center justify-center rounded-md p-1",
+ "text-[var(--oh-muted)] hover:bg-white/10 hover:text-white",
+ hoverRevealActionClassName(pinAction.pinned),
+ )}
+ >
+ <Pin
+ className={cn("h-3.5 w-3.5", pinAction.pinned && "fill-current")}
+ aria-hidden
+ />
+ </button>
+ </div>
+ );
+ }
return (
<StyledTooltip
diff --git a/src/components/features/sidebar/sidebar-rail-body.tsx b/src/components/features/sidebar/sidebar-rail-body.tsx
index e1ffaa5558..98fbd3ca15 100644
--- a/src/components/features/sidebar/sidebar-rail-body.tsx
+++ b/src/components/features/sidebar/sidebar-rail-body.tsx
@@ -14,6 +14,10 @@ import {
getInterfaceCopy,
hasAutomationInterface,
} from "#/manifests/automation-interface";
+import {
+ CUSTOMIZE_PATH,
+ usePinnedHomeRoute,
+} from "#/hooks/use-pinned-home-route";
import { SidebarCollapsedIconSlot } from "./sidebar-collapsed-icon-slot";
import { SidebarNavLink } from "./sidebar-nav-link";
import { I18nKey } from "#/i18n/declaration";
@@ -84,6 +88,19 @@ export function SidebarRailBody({
}: SidebarRailBodyProps) {
const { t } = useTranslation("openhands");
const backendCloseTimerRef = collapsedBackendCloseTimer;
+ const { isPinnedRoute, togglePinnedRoute } = usePinnedHomeRoute();
+
+ const buildPinAction = (path: string, testId: string) => {
+ const pinned = isPinnedRoute(path);
+ return {
+ pinned,
+ onToggle: () => togglePinnedRoute(path),
+ label: pinned
+ ? t(I18nKey.SIDEBAR$UNPIN_AS_HOME)
+ : t(I18nKey.SIDEBAR$PIN_AS_HOME),
+ testId,
+ };
+ };
return (
<div className="flex min-h-0 flex-1 flex-col">
@@ -172,11 +189,15 @@ export function SidebarRailBody({
icon={<Plus width={ICON_SIZE} height={ICON_SIZE} />}
/>
<SidebarNavLink
- to="/customize"
+ to={CUSTOMIZE_PATH}
label={t(I18nKey.NAV$CUSTOMIZE)}
testId="sidebar-skills-link"
collapsed={collapsed}
forceActive={isExtensionsActive}
+ pinAction={buildPinAction(
+ CUSTOMIZE_PATH,
+ "sidebar-pin-home-toggle-customize",
+ )}
icon={
<svg
xmlns="http://www.w3.org/2000/svg"
@@ -214,6 +235,10 @@ export function SidebarRailBody({
testId="sidebar-automations-link"
collapsed={collapsed}
icon={<AutomationsIcon width={ICON_SIZE} height={ICON_SIZE} />}
+ pinAction={buildPinAction(
+ automationListPath(),
+ "sidebar-pin-home-toggle-automations",
+ )}
/>
)}
</nav>
diff --git a/src/hooks/use-pinned-home-route.ts b/src/hooks/use-pinned-home-route.ts
new file mode 100644
index 0000000000..91347ce84e
--- /dev/null
+++ b/src/hooks/use-pinned-home-route.ts
@@ -0,0 +1,113 @@
+import { useLocalStorage } from "@uidotdev/usehooks";
+import { useCallback, useMemo } from "react";
+import {
+ getActiveBackend,
+ isNoBackend,
+} from "#/api/backend-registry/active-store";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import {
+ automationListPath,
+ hasAutomationInterface,
+} from "#/manifests/automation-interface";
+
+export const PINNED_HOME_ROUTE_KEY = "oh:pinned-home-route";
+
+/** Sidebar Customize entry; also the pin target, so the two cannot drift. */
+export const CUSTOMIZE_PATH = "/customize";
+
+/**
+ * The pin is stored per backend + org: it may reference a surface that only
+ * exists on the backend that set it (e.g. /automations requires that
+ * deployment's interface manifest) — a shared key would let one backend
+ * redirect `/` on another.
+ */
+export function getPinnedHomeRouteKey(
+ backendId: string,
+ orgId: string | null,
+): string {
+ return `${PINNED_HOME_ROUTE_KEY}:${backendId}:${orgId ?? "-"}`;
+}
+
+/**
+ * Whether `path` may serve as the home route right now. Shared by the
+ * sidebar pin affordance and the `/` loader, so a stored pin that stops
+ * resolving (backend switch, manifest absent) is ignored rather than an
+ * error. `/` is never pinnable, which makes a redirect loop impossible.
+ * Canvas Extensions pages can later add an `/extensions/…` branch here
+ * without any storage or loader change.
+ */
+export function isPinnableRoute(path: string): boolean {
+ if (path === CUSTOMIZE_PATH) return true;
+ if (path === automationListPath()) return hasAutomationInterface();
+ return false;
+}
+
+function sanitizePinnedRoute(value: unknown): string | null {
+ if (typeof value !== "string" || !value) return null;
+ return isPinnableRoute(value) ? value : null;
+}
+
+/**
+ * Synchronous pin read for route loaders (no React context). Reads the key
+ * `usePinnedHomeRoute` writes; `useLocalStorage` JSON-serializes values, so
+ * parse defensively and treat anything unreadable as "no pin". An invalid
+ * pin is ignored, not cleared — it may become valid again (e.g. the
+ * automations interface returning after a backend switch back).
+ */
+export function readPinnedHomeRoute(): string | null {
+ const active = getActiveBackend();
+ if (isNoBackend(active.backend)) return null;
+
+ let raw: string | null = null;
+ try {
+ raw = window.localStorage.getItem(
+ getPinnedHomeRouteKey(active.backend.id, active.orgId),
+ );
+ } catch {
+ return null;
+ }
+ if (raw === null) return null;
+
+ try {
+ return sanitizePinnedRoute(JSON.parse(raw));
+ } catch {
+ return null;
+ }
+}
+
+/** Pin state for the home route: `/` redirects to the pinned sidebar page. */
+export function usePinnedHomeRoute() {
+ const active = useActiveBackend();
+ const [rawPinnedRoute, setRawPinnedRoute] = useLocalStorage<string | null>(
+ getPinnedHomeRouteKey(active.backend.id, active.orgId),
+ null,
+ );
+
+ const pinnedRoute = useMemo(
+ () => sanitizePinnedRoute(rawPinnedRoute),
+ [rawPinnedRoute],
+ );
+
+ const isPinnedRoute = useCallback(
+ (path: string) => pinnedRoute === path,
+ [pinnedRoute],
+ );
+
+ const togglePinnedRoute = useCallback(
+ (path: string) => {
+ if (pinnedRoute === path) {
+ setRawPinnedRoute(null);
+ return;
+ }
+ if (!isPinnableRoute(path)) return;
+ setRawPinnedRoute(path);
+ },
+ [pinnedRoute, setRawPinnedRoute],
+ );
+
+ return {
+ pinnedRoute,
+ isPinnedRoute,
+ togglePinnedRoute,
+ };
+}
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 03a5565b6f..226d3b1286 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -35937,6 +35937,40 @@
"uk": "Новий чат",
"ca": "Xat nou"
},
+ "SIDEBAR$PIN_AS_HOME": {
+ "en": "Pin as home page",
+ "zh-CN": "固定为主页",
+ "zh-TW": "釘選為首頁",
+ "de": "Als Startseite anheften",
+ "ko-KR": "홈 페이지로 고정",
+ "no": "Pin as home page",
+ "it": "Fissa come pagina iniziale",
+ "pt": "Fixar como página inicial",
+ "es": "Fijar como página de inicio",
+ "ar": "Pin as home page",
+ "fr": "Épingler comme page d'accueil",
+ "tr": "Pin as home page",
+ "ja": "ホームページとしてピン留め",
+ "uk": "Pin as home page",
+ "ca": "Pin as home page"
+ },
+ "SIDEBAR$UNPIN_AS_HOME": {
+ "en": "Unpin as home page",
+ "zh-CN": "取消固定为主页",
+ "zh-TW": "取消釘選為首頁",
+ "de": "Als Startseite lösen",
+ "ko-KR": "홈 페이지 고정 해제",
+ "no": "Unpin as home page",
+ "it": "Rimuovi come pagina iniziale",
+ "pt": "Desafixar como página inicial",
+ "es": "Quitar como página de inicio",
+ "ar": "Unpin as home page",
+ "fr": "Désépingler comme page d'accueil",
+ "tr": "Unpin as home page",
+ "ja": "ホームページのピン留め解除",
+ "uk": "Unpin as home page",
+ "ca": "Unpin as home page"
+ },
"SETTINGS$SECRET_NAME_PATTERN_TITLE": {
"en": "Must start with a letter, contain only letters/numbers/underscores, and be 1-64 characters",
"zh-CN": "必须以字母开头,只能包含字母/数字/下划线,且长度为 1-64 个字符",
diff --git a/src/routes/index-home.tsx b/src/routes/index-home.tsx
index ba04027686..085f083f0e 100644
--- a/src/routes/index-home.tsx
+++ b/src/routes/index-home.tsx
@@ -1 +1,17 @@
+import { redirect } from "react-router";
+import { readPinnedHomeRoute } from "#/hooks/use-pinned-home-route";
+
+/**
+ * With a home pin set for the active backend + org, `/` redirects to the
+ * pinned page. `readPinnedHomeRoute` only returns routes that currently
+ * resolve (never `/` itself), so a stale pin falls back to the default
+ * home with no error and no redirect loop; the built-in home stays
+ * reachable unmodified at /conversations.
+ */
+export const clientLoader = () => {
+ const pinnedRoute = readPinnedHomeRoute();
+ if (pinnedRoute) return redirect(pinnedRoute);
+ return null;
+};
+
export { default } from "./home";