feat(web): pick settings environment and project as two selects#10636

@@ -0,0 +1,49 @@
+import type { EnvironmentPresentation } from "../../state/environments";
+import type { SettingsScopeSearch } from "./settingsScope";
+
+type ScopeEnvironment = Pick<EnvironmentPresentation, "environmentId" | "label" | "displayUrl">;
+
+export function settingsScopeEnvironmentLabel(
+  environment: ScopeEnvironment,
+  environments: readonly ScopeEnvironment[],
+) {
+  const duplicate = environments.some(
+    (other) =>
+      other.environmentId !== environment.environmentId && other.label === environment.label,
+  );
+  return duplicate
+    ? `${environment.label} · ${environment.displayUrl ?? environment.environmentId}`
+    : environment.label;
+}
+
+export const ALL_ENVIRONMENTS_VALUE = "all";
+export const ALL_PROJECTS_VALUE = "all";
+
+/** The environment axis: `all` or an environment id. */
+export function environmentAxisValue(search: SettingsScopeSearch): string {
+  return search.machine ?? ALL_ENVIRONMENTS_VALUE;

@@ -0,0 +1,260 @@
+import { resolveEnvironmentMachineKind } from "@t3tools/contracts";
+import { ChevronDownIcon, ComputerIcon, FolderIcon, LayersIcon } from "lucide-react";
+import { type ReactNode, useMemo, useState } from "react";
+
+import { cn } from "../../lib/utils";
+import type { SidebarProjectSnapshot } from "../../sidebarProjectGrouping";
+import type { EnvironmentPresentation } from "../../state/environments";
+import { EnvironmentMachineIcon } from "../EnvironmentMachineIcon";
+import { ProjectFavicon } from "../ProjectFavicon";
+import {
+  Combobox,
+  ComboboxCollection,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxGroupLabel,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxPopup,
+  ComboboxSearchInput,
+  ComboboxTrigger,
+} from "../ui/combobox";
+import { selectTriggerVariants } from "../ui/select";
+import { resolveSettingsScope, type SettingsScopeSearch } from "./settingsScope";
+
+interface ScopeOption {
+  label: string;
+  searchLabel: string;
+  detail?: string | undefined;
+  scope: SettingsScopeSearch;
+  icon: ReactNode;
+  indented?: boolean;
+}
+
+function optionKey(scope: SettingsScopeSearch): string {
+  return JSON.stringify([scope.scope, scope.project, scope.machine, scope.checkout]);
+}
+
+export function SettingsScopePicker({
+  value,
+  groups,
+  environments,
+  onChange,
+  includeDevice = false,
+}: {
+  value: SettingsScopeSearch;
+  groups: readonly SidebarProjectSnapshot[];
+  environments: readonly EnvironmentPresentation[];
+  onChange: (next: SettingsScopeSearch) => void;
+  includeDevice?: boolean;
+}) {
+  const [query, setQuery] = useState("");
+  const resolved = resolveSettingsScope(value, groups, environments);
+  const selectedEnvironment =
+    resolved.kind === "environment"
+      ? environments.find((environment) => environment.environmentId === value.machine)
+      : undefined;
+  const triggerLabel =
+    selectedEnvironment?.displayUrl &&
+    environments.some(
+      (environment) =>
+        environment.environmentId !== selectedEnvironment.environmentId &&
+        environment.label === selectedEnvironment.label,
+    )
+      ? `${resolved.label} · ${selectedEnvironment.displayUrl}`
+      : resolved.label;
+  const optionGroups = useMemo(() => {
+    const environmentById = new Map<string, EnvironmentPresentation>(
+      environments.map((environment) => [environment.environmentId, environment]),
+    );
+    const defaults: ScopeOption[] = [
+      {
+        label: "All environments",
+        searchLabel: "All environments defaults",
+        scope: { scope: "all" },
+        icon: <LayersIcon aria-hidden className="size-3.5" />,
+      },
+    ];
+    if (includeDevice) {
+      defaults.push({
+        label: "This device",
+        searchLabel: "This device appearance preferences",
+        scope: { scope: "device" },
+        icon: <ComputerIcon aria-hidden className="size-3.5" />,
+      });
+    }
+    return [
+      { id: "defaults", label: "Settings for", items: defaults },
+      {
+        id: "environments",
+        label: "Environments",
+        items: environments.map((environment): ScopeOption => ({
+          label: environment.label,
+          searchLabel: `${environment.label} ${environment.displayUrl ?? ""} environment defaults`,
+          detail:
+            [
+              environments.some(
+                (other) =>
+                  other.environmentId !== environment.environmentId &&
+                  other.label === environment.label,
+              )
+                ? environment.displayUrl
+                : null,
+              environment.connection.phase === "connected" ? null : "Offline",
+            ]
+              .filter(Boolean)
+              .join(" · ") || undefined,
+          scope: { machine: environment.environmentId },
+          icon: (
+            <EnvironmentMachineIcon
+              aria-hidden
+              kind={resolveEnvironmentMachineKind(environment.serverConfig)}
+              className="size-3.5"
+            />
+          ),
+        })),
+      },
+      ...groups.map((group) => {
+        const items: ScopeOption[] = [
+          {
+            label: "All checkouts",
+            searchLabel: `${group.displayName} all checkouts`,
+            detail: `${group.memberProjects.length} ${group.memberProjects.length === 1 ? "checkout" : "checkouts"}`,
+            scope: { project: group.projectKey },
+            icon: (
+              <ProjectFavicon
+                environmentId={group.environmentId}
+                cwd={group.workspaceRoot}
+                projectName={group.title}
+                faviconPath={group.faviconPath}
+                projectIcon={group.projectIcon}
+                className="size-3.5"
+              />
+            ),
+          },
+        ];
+        // Old links can select several checkouts on one environment. Keep that
+        // exact aggregate selected until the user chooses a different target.
+        if (value.project === group.projectKey && value.machine && !value.checkout) {
+          const environment = environmentById.get(value.machine);
+          if (
+            environment &&
+            group.memberProjects.some((member) => member.environmentId === value.machine)
+          ) {
+            items.push({
+              label: `All checkouts on ${environment.label}`,
+              searchLabel: `${group.displayName} all checkouts ${environment.label}`,
+              scope: { project: group.projectKey, machine: environment.environmentId },
+              icon: <FolderIcon aria-hidden className="size-3.5" />,
+              indented: true,
+            });
+          }
+        }
+        for (const member of group.memberProjects) {
+          const environment = environmentById.get(member.environmentId);
+          const environmentLabel =
+            environment?.label ?? member.environmentLabel ?? "Unavailable environment";
+          items.push({
+            label: environmentLabel,
+            searchLabel: `${group.displayName} ${environmentLabel} ${member.workspaceRoot}`,
+            detail: member.workspaceRoot,

@@ -1,177 +1,51 @@
-import { resolveEnvironmentMachineKind } from "@t3tools/contracts";
-import { ChevronDownIcon, FolderIcon } from "lucide-react";
-import { type ReactNode, useState } from "react";
-import { EnvironmentMachineIcon } from "../EnvironmentMachineIcon";
-import { ProjectFavicon } from "../ProjectFavicon";
 import { WorkspacePageContainer } from "../WorkspacePageContainer";
 import { useEnvironments } from "../../state/environments";
-import { Toggle, ToggleGroup } from "../ui/toggle-group";
-import {
-  Combobox,
-  ComboboxEmpty,
-  ComboboxSearchInput,
-  ComboboxItem,
-  ComboboxList,
-  ComboboxPopup,
-  ComboboxTrigger,
-} from "../ui/combobox";
-import { selectTriggerVariants } from "../ui/select";
-import { cn } from "../../lib/utils";
-import { ProjectSettingsPanel, useSettingsProjectGroups } from "./ProjectSettingsPanel";
+import { ProjectSettingsPanel } from "./ProjectSettingsPanel";
 import { ProjectDefaultsSettings } from "./ProjectDefaultsSettings";
-
-function ScopePicker({
-  label,
-  value,
-  options,
-  onChange,
-}: {
-  label: "project" | "machine";
-  value: string | null;
-  options: ReadonlyArray<{ value: string; label: string; icon?: ReactNode }>;
-  onChange: (value: string | null) => void;
-}) {
-  const [query, setQuery] = useState("");
-  const selected = options.find((option) => option.value === value);
-  const allIcon =
-    label === "project" ? <FolderIcon aria-hidden className="size-3.5 shrink-0" /> : null;
-  const items = [{ value: "all", label: `All ${label}s`, icon: allIcon }, ...options];
-  return (
-    <Combobox
-      items={items}
-      value={items.find((item) => item.value === (value ?? "all")) ?? null}
-      inputValue={query}
-      onInputValueChange={setQuery}
-      onOpenChange={() => setQuery("")}
-      onValueChange={(next) => {
-        if (next) onChange(next.value === "all" ? null : next.value);
-      }}
-    >
-      <ComboboxTrigger
-        aria-label={`${label === "project" ? "Project" : "Machine"} scope`}
-        className={cn(selectTriggerVariants({ size: "compact" }), "w-auto min-w-0 max-w-52")}
-      >
-        <span className="flex min-w-0 items-center gap-1.5">
-          {value === null ? allIcon : selected?.icon}
-          <span className="truncate">
-            {value === null ? `All ${label}s` : (selected?.label ?? `Unavailable ${label}`)}
-          </span>
-        </span>
-        <ChevronDownIcon aria-hidden className="-me-1 size-3 opacity-50" />
-      </ComboboxTrigger>
-      <ComboboxPopup align="start" className="w-64">
-        <ComboboxSearchInput aria-label={`Search ${label}s`} placeholder={`Search ${label}s...`} />
-        <ComboboxEmpty>No matching {label}s.</ComboboxEmpty>
-        <ComboboxList>
-          {(item: (typeof items)[number]) => (
-            <ComboboxItem
-              key={item.value}
-              value={item}
-              contentClassName="flex min-w-0 items-center gap-2"
-            >
-              {item.icon}
-              <span className="truncate">{item.label}</span>
-            </ComboboxItem>
-          )}
-        </ComboboxList>
-      </ComboboxPopup>
-    </Combobox>
-  );
-}
+import { SettingsScopePicker } from "./SettingsScopePicker";
+import { resolveSettingsScope, type SettingsScopeSearch } from "./settingsScope";
+import { useSettingsProjectGroups } from "./useSettingsProjectGroups";
 
 export function ProjectsSettings({
-  projectKey,
-  machineId,
+  value,
   onScopeChange,
 }: {
-  projectKey: string | null;
-  machineId: string | null;
-  onScopeChange: (project: string | null, machine: string | null) => void;
+  value: SettingsScopeSearch;
+  onScopeChange: (scope: SettingsScopeSearch) => void;
 }) {
   const groups = useSettingsProjectGroups();
   const { environments } = useEnvironments();
-  const machine = environments.find((environment) => environment.environmentId === machineId);
-  const machineOptions = environments.map((environment) => ({
-    value: environment.environmentId,
-    label: environment.label,
-    icon: (
-      <EnvironmentMachineIcon
-        aria-hidden
-        kind={resolveEnvironmentMachineKind(environment.serverConfig)}
-        className="size-3.5 shrink-0"
-      />
-    ),
-  }));
+  const scope = resolveSettingsScope(value, groups, environments);
   return (
     <div className="flex min-h-0 flex-1 flex-col">
       <div className="scrollbar-gutter-both shrink-0 overflow-y-auto">
-        <WorkspacePageContainer className="pb-0">
-          <div
-            className="flex flex-wrap items-center gap-2"
-            role="group"
-            aria-label="Settings scope"
-          >
-            {environments.length > 3 ? (
-              <ScopePicker
-                label="machine"
-                value={machineId}
-                options={machineOptions}
-                onChange={(value) => onScopeChange(projectKey, value)}
-              />
-            ) : (
-              <ToggleGroup
-                aria-label="Machine scope"
-                variant="segmented"
-                className="max-w-full flex-wrap"
-                value={[machineId ?? "all"]}
-                onValueChange={(next) => {
-                  const value = next[0];
-                  if (value) onScopeChange(projectKey, value === "all" ? null : value);
-                }}
-              >
-                <Toggle value="all">All machines</Toggle>
-                {machineOptions.map((option) => (
-                  <Toggle key={option.value} value={option.value} title={option.label}>
-                    {option.icon}
-                    <span className="max-w-36 truncate">{option.label}</span>
-                  </Toggle>
-                ))}
-              </ToggleGroup>
-            )}
-            <div className="ms-auto">
-              <ScopePicker
-                label="project"
-                value={projectKey}
-                options={groups.map((group) => ({
-                  value: group.projectKey,
-                  label: group.displayName,
-                  icon: (
-                    <ProjectFavicon
-                      environmentId={group.environmentId}
-                      cwd={group.workspaceRoot}
-                      projectName={group.title}
-                      faviconPath={group.faviconPath}
-                      projectIcon={group.projectIcon}
-                      className="size-3.5"
-                    />
-                  ),
-                }))}
-                onChange={(value) => onScopeChange(value, machineId)}
-              />
-            </div>
-          </div>
+        <WorkspacePageContainer className="items-start pb-0">
+          <SettingsScopePicker
+            value={value}
+            groups={groups}
+            environments={environments}
+            onChange={onScopeChange}
+          />
         </WorkspacePageContainer>
       </div>
-      {machineId !== null && !machine ? (
-        <p className="p-8 text-sm text-muted-foreground">This machine is no longer available.</p>
-      ) : projectKey === null ? (
-        <ProjectDefaultsSettings environmentId={machine?.environmentId ?? null} />
-      ) : (
+      {value.project && scope.kind !== "all" && scope.kind !== "device" ? (

@@ -1,168 +1,53 @@
-import { resolveEnvironmentMachineKind } from "@t3tools/contracts";
-import { ChevronDownIcon, FolderIcon } from "lucide-react";
-import { type ReactNode, useState } from "react";
-import { EnvironmentMachineIcon } from "../EnvironmentMachineIcon";
-import { ProjectFavicon } from "../ProjectFavicon";
 import { WorkspacePageContainer } from "../WorkspacePageContainer";
 import { useEnvironments } from "../../state/environments";
-import { Toggle, ToggleGroup } from "../ui/toggle-group";
-import {
-  Combobox,
-  ComboboxEmpty,
-  ComboboxSearchInput,
-  ComboboxItem,
-  ComboboxList,
-  ComboboxPopup,
-  ComboboxTrigger,
-} from "../ui/combobox";
-import { selectTriggerVariants } from "../ui/select";
-import { cn } from "../../lib/utils";
-import { ProjectSettingsPanel, useSettingsProjectGroups } from "./ProjectSettingsPanel";
+import { ProjectSettingsPanel } from "./ProjectSettingsPanel";
 import { ProjectDefaultsSettings } from "./ProjectDefaultsSettings";
-
-function ScopePicker({
-  label,
-  value,
-  options,
-  onChange,
-}: {
-  label: "project" | "machine";
-  value: string | null;
-  options: ReadonlyArray<{ value: string; label: string; icon?: ReactNode }>;
-  onChange: (value: string | null) => void;
-}) {
-  const [query, setQuery] = useState("");
-  const selected = options.find((option) => option.value === value);
-  const allIcon =
-    label === "project" ? <FolderIcon aria-hidden className="size-3.5 shrink-0" /> : null;
-  const items = [{ value: "all", label: `All ${label}s`, icon: allIcon }, ...options];
-  return (
-    <Combobox
-      items={items}
-      value={items.find((item) => item.value === (value ?? "all")) ?? null}
-      inputValue={query}
-      onInputValueChange={setQuery}
-      onOpenChange={() => setQuery("")}
-      onValueChange={(next) => {
-        if (next) onChange(next.value === "all" ? null : next.value);
-      }}
-    >
-      <ComboboxTrigger
-        aria-label={`${label === "project" ? "Project" : "Machine"} scope`}
-        className={cn(selectTriggerVariants({ size: "compact" }), "w-auto min-w-0 max-w-52")}
-      >
-        <span className="flex min-w-0 items-center gap-1.5">
-          {value === null ? allIcon : selected?.icon}
-          <span className="truncate">
-            {value === null ? `All ${label}s` : (selected?.label ?? `Unavailable ${label}`)}
-          </span>
-        </span>
-        <ChevronDownIcon aria-hidden className="-me-1 size-3 opacity-50" />
-      </ComboboxTrigger>
-      <ComboboxPopup align="start" className="w-64">
-        <ComboboxSearchInput aria-label={`Search ${label}s`} placeholder={`Search ${label}s...`} />
-        <ComboboxEmpty>No matching {label}s.</ComboboxEmpty>
-        <ComboboxList>
-          {(item: (typeof items)[number]) => (
-            <ComboboxItem
-              key={item.value}
-              value={item}
-              contentClassName="flex min-w-0 items-center gap-2"
-            >
-              {item.icon}
-              <span className="truncate">{item.label}</span>
-            </ComboboxItem>
-          )}
-        </ComboboxList>
-      </ComboboxPopup>
-    </Combobox>
-  );
-}
+import { SettingsScopeSelects } from "./SettingsScopeSelects";
+import { resolveSettingsScope, type SettingsScopeSearch } from "./settingsScope";
+import { useSettingsProjectGroups } from "./useSettingsProjectGroups";
 
 export function ProjectsSettings({
-  projectKey,
-  machineId,
+  value,
   onScopeChange,
 }: {
-  projectKey: string | null;
-  machineId: string | null;
-  onScopeChange: (project: string | null, machine: string | null) => void;
+  value: SettingsScopeSearch;
+  onScopeChange: (scope: SettingsScopeSearch) => void;
 }) {
   const groups = useSettingsProjectGroups();
   const { environments } = useEnvironments();
-  const machine = environments.find((environment) => environment.environmentId === machineId);
-  const machineOptions = environments.map((environment) => ({
-    value: environment.environmentId,
-    label: environment.label,
-    icon: (
-      <EnvironmentMachineIcon
-        aria-hidden
-        kind={resolveEnvironmentMachineKind(environment.serverConfig)}
-        className="size-3.5 shrink-0"
-      />
-    ),
-  }));
+  const scope = resolveSettingsScope(value, groups, environments);
+  // The panel follows remembered members when grouping replaces a project key.
+  const projectScope =
+    scope.kind === "project" ||
+    scope.kind === "checkout" ||
+    (scope.kind === "unavailable" &&
+      (scope.reason === "project-missing" || scope.reason === "checkout-missing"));
   return (
     <div className="flex min-h-0 flex-1 flex-col">
       <div className="scrollbar-gutter-both shrink-0 overflow-y-auto">
-        <WorkspacePageContainer className="pb-0">
-          <div
-            className="flex flex-wrap items-center gap-2"
-            role="group"
-            aria-label="Settings scope"
-          >
-            {environments.length > 3 ? (
-              <ScopePicker
-                label="machine"
-                value={machineId}
-                options={machineOptions}
-                onChange={(value) => onScopeChange(projectKey, value)}
-              />
-            ) : (
-              <ToggleGroup
-                aria-label="Machine scope"
-                variant="segmented"
-                className="max-w-full flex-wrap"
-                value={[machineId ?? "all"]}
-                onValueChange={(next) => {
-                  const value = next[0];
-                  if (value) onScopeChange(projectKey, value === "all" ? null : value);
-                }}
-              >
-                <Toggle value="all">All machines</Toggle>
-                {machineOptions.map((option) => (
-                  <Toggle key={option.value} value={option.value} title={option.label}>
-                    {option.icon}
-                    <span className="max-w-36 truncate">{option.label}</span>
-                  </Toggle>
-                ))}
-              </ToggleGroup>
-            )}
-            <div className="ms-auto">
-              <ScopePicker
-                label="project"
-                value={projectKey}
-                options={groups.map((group) => ({
-                  value: group.projectKey,
-                  label: group.displayName,
-                  icon: <ProjectFavicon project={group} className="size-3.5" />,
-                }))}
-                onChange={(value) => onScopeChange(value, machineId)}
-              />
-            </div>
-          </div>
+        <WorkspacePageContainer className="items-end pb-0">
+          <SettingsScopeSelects

@@ -0,0 +1,163 @@
+import type { EnvironmentId } from "@t3tools/contracts";
+
+import type {
+  SidebarProjectGroupMember,
+  SidebarProjectSnapshot,
+} from "../../sidebarProjectGrouping";
+import type { EnvironmentPresentation } from "../../state/environments";
+
+export interface SettingsScopeSearch {
+  scope?: "device" | "all" | undefined;
+  project?: string | undefined;
+  machine?: string | undefined;
+  checkout?: string | undefined;
+}
+
+type ScopeTargets = {
+  label: string;
+  members: readonly SidebarProjectGroupMember[];
+  environmentIds: readonly EnvironmentId[];
+};
+
+export type ResolvedSettingsScope = ScopeTargets &
+  (
+    | { kind: "device" | "all" }
+    | { kind: "environment"; environmentId: EnvironmentId }
+    | {
+        kind: "project";
+        group: SidebarProjectSnapshot;
+        environmentId: EnvironmentId | null;
+      }
+    | {
+        kind: "checkout";
+        group: SidebarProjectSnapshot;
+        checkout: SidebarProjectGroupMember;
+        environmentId: EnvironmentId;
+      }
+    | {
+        kind: "unavailable";
+        reason: "project-required" | "project-missing" | "environment-missing" | "checkout-missing";
+        message: string;
+      }
+  );
+
+/** Explicit broad targets replace narrower selections; stale IDs remain visible to the resolver. */
+export function validateSettingsScopeSearch(raw: Record<string, unknown>): SettingsScopeSearch {
+  if (raw.scope === "device" || raw.scope === "all") return { scope: raw.scope };
+  const stringValue = (value: unknown) =>
+    typeof value === "string" && value.trim().length > 0 ? value : undefined;
+  const project = stringValue(raw.project);
+  const machine = stringValue(raw.machine);
+  const checkout = stringValue(raw.checkout);
+  return {
+    ...(project === undefined ? {} : { project }),
+    ...(machine === undefined ? {} : { machine }),
+    ...(checkout === undefined ? {} : { checkout }),
+  };
+}
+
+/** Resolves only existing targets. An unavailable selection never broadens a subsequent write. */
+export function resolveSettingsScope(
+  search: SettingsScopeSearch,
+  groups: readonly SidebarProjectSnapshot[],
+  environments: readonly Pick<EnvironmentPresentation, "environmentId" | "label">[],
+): ResolvedSettingsScope {
+  const unavailable = (
+    reason: Extract<ResolvedSettingsScope, { kind: "unavailable" }>["reason"],
+    message: string,
+  ): ResolvedSettingsScope => ({
+    kind: "unavailable",
+    reason,
+    label: "Unavailable selection",
+    message,
+    members: [],
+    environmentIds: [],
+  });
+
+  if (search.scope === "device") {
+    return { kind: "device", label: "This device", members: [], environmentIds: [] };
+  }
+  if (search.scope === "all") {
+    return {
+      kind: "all",
+      label: "All environments",
+      members: [],
+      environmentIds: environments.map((environment) => environment.environmentId),
+    };
+  }
+  if (search.checkout && !search.project) {
+    return unavailable("project-required", "Select a project to choose one of its checkouts.");
+  }
+
+  const environment = environments.find((candidate) => candidate.environmentId === search.machine);
+  if (search.machine && !environment) {
+    return unavailable("environment-missing", "This environment is no longer available.");
+  }
+
+  if (search.project) {
+    const group = groups.find((candidate) => candidate.projectKey === search.project);
+    if (!group) return unavailable("project-missing", "This project is no longer available.");
+    const members = group.memberProjects.filter(
+      (member) =>
+        (search.machine === undefined || member.environmentId === search.machine) &&
+        (search.checkout === undefined || member.physicalProjectKey === search.checkout),
+    );

@@ -0,0 +1,163 @@
+import type { EnvironmentId } from "@t3tools/contracts";
+
+import type {
+  SidebarProjectGroupMember,
+  SidebarProjectSnapshot,
+} from "../../sidebarProjectGrouping";
+import type { EnvironmentPresentation } from "../../state/environments";
+
+export interface SettingsScopeSearch {
+  scope?: "device" | "all" | undefined;
+  project?: string | undefined;
+  machine?: string | undefined;
+  checkout?: string | undefined;
+}
+
+type ScopeTargets = {
+  label: string;
+  members: readonly SidebarProjectGroupMember[];
+  environmentIds: readonly EnvironmentId[];
+};
+
+export type ResolvedSettingsScope = ScopeTargets &
+  (
+    | { kind: "device" | "all" }
+    | { kind: "environment"; environmentId: EnvironmentId }
+    | {
+        kind: "project";
+        group: SidebarProjectSnapshot;
+        environmentId: EnvironmentId | null;
+      }
+    | {
+        kind: "checkout";
+        group: SidebarProjectSnapshot;
+        checkout: SidebarProjectGroupMember;
+        environmentId: EnvironmentId;
+      }
+    | {
+        kind: "unavailable";
+        reason: "project-required" | "project-missing" | "environment-missing" | "checkout-missing";
+        message: string;
+      }
+  );
+
+/** Explicit broad targets replace narrower selections; stale IDs remain visible to the resolver. */
+export function validateSettingsScopeSearch(raw: Record<string, unknown>): SettingsScopeSearch {
+  if (raw.scope === "device" || raw.scope === "all") return { scope: raw.scope };
+  const stringValue = (value: unknown) =>
+    typeof value === "string" && value.trim().length > 0 ? value : undefined;
+  const project = stringValue(raw.project);
+  const machine = stringValue(raw.machine);
+  const checkout = stringValue(raw.checkout);
+  return {
+    ...(project === undefined ? {} : { project }),
+    ...(machine === undefined ? {} : { machine }),
+    ...(checkout === undefined ? {} : { checkout }),
+  };
+}
+
+/** Resolves only existing targets. An unavailable selection never broadens a subsequent write. */
+export function resolveSettingsScope(
+  search: SettingsScopeSearch,
+  groups: readonly SidebarProjectSnapshot[],
+  environments: readonly Pick<EnvironmentPresentation, "environmentId" | "label">[],
+): ResolvedSettingsScope {
+  const unavailable = (
+    reason: Extract<ResolvedSettingsScope, { kind: "unavailable" }>["reason"],
+    message: string,
+  ): ResolvedSettingsScope => ({
+    kind: "unavailable",
+    reason,
+    label: "Unavailable selection",
+    message,
+    members: [],
+    environmentIds: [],
+  });
+
+  if (search.scope === "device") {
+    return { kind: "device", label: "This device", members: [], environmentIds: [] };