Merge remote-tracking branch 'origin/main' into fix/ui

# Conflicts:
#	apps/app-frontend/src/locales/en-US/index.json
#	apps/app-frontend/src/locales/zh-CN/index.json

apps/app-frontend/src/components/ui/library/DraggableInstanceCard.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import { KeyboardSensor, PointerSensor, useDraggable } from '@dnd-kit/vue'
+import { useEventListener } from '@vueuse/core'
+import { computed, ref } from 'vue'
+
+import type { GameInstance } from '@/helpers/types'
+
+const props = defineProps<{
+	instance: GameInstance
+	instanceGroupId: string
+	disabled: boolean
+}>()
+
+const emit = defineEmits<{
+	(e: 'contextmenu' | 'card-click', event: MouseEvent): void
+	(e: 'start-long-press' | 'cancel-long-press'): void
+}>()
+
+const cardElement = ref<HTMLElement>()
+
+const instanceCardSensors = [
+	PointerSensor.configure({
+		preventActivation: () => false,
+	}),
+	KeyboardSensor,
+]
+
+const dragDisabled = computed(() => props.disabled)
+
+const { isDragging } = useDraggable({
+	id: computed(() => `instance:${props.instanceGroupId}:${props.instance.id}`),
+	element: cardElement,
+	disabled: dragDisabled,
+	sensors: instanceCardSensors,
+	data: computed(() => ({
+		instanceId: props.instance.id,
+		fromGroup: props.instanceGroupId,
+	})),
+})
+
+let wantsClick = false
+
+useEventListener(window, 'pointerdown', () => {
+	wantsClick = true
+})
+useEventListener(window, 'pointerup', () => {
+	if (isDragging.value) {
+		wantsClick = false
+	}
+})
+useEventListener(window, 'blur', () => {
+	wantsClick = false
+})
+
+function onCardClick(event: MouseEvent) {
+	if (!wantsClick || isDragging.value) return
+	wantsClick = false
+	emit('card-click', event)
+}
+
+function onContextMenu(event: MouseEvent) {
+	emit('contextmenu', event)
+}
+
+function onMouseDown() {
+	if (!dragDisabled.value) {
+		emit('start-long-press')
+	}
+}
+
+function onMouseUp() {
+	emit('cancel-long-press')
+}
+</script>
+
+<template>
+	<div
+		ref="cardElement"
+		class="group relative min-w-0 w-full"
+		@click="onCardClick"
+		@mousedown="onMouseDown"
+		@mouseup="onMouseUp"
+		@mouseleave="onMouseUp"
+		@touchstart="!dragDisabled && onMouseDown()"
+		@touchend="onMouseUp"
+		@touchcancel="onMouseUp"
+		@contextmenu.prevent.stop="onContextMenu"
+	>
+		<slot :is-dragging="isDragging" />
+		<slot v-if="!isDragging" name="overlay" />
+	</div>
+</template>

apps/app-frontend/src/components/ui/library/InstanceGroup.vue

@@ -0,0 +1,521 @@
+<script setup lang="ts">
+import { useDroppable } from '@dnd-kit/vue'
+import {
+	ArrowDownIcon,
+	ArrowUpIcon,
+	DropdownIcon,
+	EditIcon,
+	PlusIcon,
+	TrashIcon,
+	XIcon,
+} from '@modrinth/assets'
+import {
+	Button,
+	Checkbox,
+	commonMessages,
+	defineMessages,
+	IconButton,
+	InlineEditableText,
+	NewModal,
+	TagItem,
+	useVIntl,
+} from '@modrinth/ui'
+import { computed, nextTick, ref, watch } from 'vue'
+
+import ContextMenu from '@/components/ui/ContextMenu.vue'
+import Instance from '@/components/ui/Instance.vue'
+import DraggableInstanceCard from '@/components/ui/library/DraggableInstanceCard.vue'
+import { UNGROUPED_GROUP_KEY } from '@/composables/useGridGrouping'
+import { FAVORITES_GROUP_ID } from '@/composables/useInstanceGroups'
+import type { GameInstance } from '@/helpers/types'
+
+const MAX_GROUP_NAME_LENGTH = 256
+
+const { formatMessage } = useVIntl()
+
+const messages = defineMessages({
+	ungrouped: { id: 'app.instances.group.ungrouped', defaultMessage: 'No group' },
+	pinned: { id: 'app.instances.group.pinned', defaultMessage: 'Pinned' },
+	emptyGroup: {
+		id: 'app.instances.group.empty',
+		defaultMessage: 'Drag and drop to add instances.',
+	},
+	editGroupName: {
+		id: 'app.instances.group.edit-name',
+		defaultMessage: 'Edit group name',
+	},
+	deleteGroup: {
+		id: 'app.instances.group.delete-group',
+		defaultMessage: 'Delete group',
+	},
+	deleteGroupDescription: {
+		id: 'app.instances.group.delete-description',
+		defaultMessage: 'Instances in this group will be ungrouped.',
+	},
+	moveGroupUp: {
+		id: 'app.instances.group.move-up',
+		defaultMessage: 'Move group up',
+	},
+	moveGroupDown: {
+		id: 'app.instances.group.move-down',
+		defaultMessage: 'Move group down',
+	},
+	addToGroup: {
+		id: 'app.instances.group.add-to-group',
+		defaultMessage: 'Add to group',
+	},
+	newInstance: {
+		id: 'app.instances.group.new-instance',
+		defaultMessage: 'New instance',
+	},
+	collapseGroup: {
+		id: 'app.instances.group.collapse',
+		defaultMessage: 'Collapse group',
+	},
+	expandGroup: {
+		id: 'app.instances.group.expand',
+		defaultMessage: 'Expand group',
+	},
+	renameGroup: {
+		id: 'app.instances.group.rename-group',
+		defaultMessage: 'Rename group',
+	},
+	groupNameEmpty: {
+		id: 'app.instances.group.name-empty',
+		defaultMessage: 'Group names cannot be empty.',
+	},
+	groupNameTooLong: {
+		id: 'app.instances.group.name-too-long',
+		defaultMessage: 'Group names cannot be longer than {maxLength} characters.',
+	},
+})
+
+const props = defineProps<{
+	sectionKey: string
+	groupName?: string
+	instances: GameInstance[]
+	grouping: string
+	isCollapsed: boolean
+	displayMode: string
+	selectMode: boolean
+	selectedInstanceIds: Set<string>
+	isSortAscending?: boolean
+	hideHeader?: boolean
+	canMoveUp?: boolean
+	canMoveDown?: boolean
+	groupPendingNameEdit?: string | null
+}>()
+
+// Events are grouped only where the payload shapes genuinely match; the
+// per-event names are documentation, not part of the type.
+const emit = defineEmits<{
+	(e: 'toggleCollapse' | 'deleteGroup' | 'addToGroup' | 'startLongPress', id: string): void
+	(e: 'handleCheckboxClick' | 'handleCardClick', instanceId: string, event: MouseEvent): void
+	(e: 'handleContextMenu', event: MouseEvent, instanceId: string, sectionKey: string): void
+	(e: 'renameGroup', oldKey: string, newKey: string): void
+	(e: 'cancelLongPress' | 'newInstance' | 'renameComplete'): void
+	(e: 'moveGroup', groupKey: string, direction: -1 | 1): void
+}>()
+
+const groupOptions = ref<InstanceType<typeof ContextMenu>>()
+const groupContainerRef = ref<HTMLElement>()
+const groupNameInput = ref<InstanceType<typeof InlineEditableText>>()
+const deletingGroup = ref(false)
+const confirmDeleteGroupModal = ref<InstanceType<typeof NewModal>>()
+const groupName = ref(props.groupName ?? props.sectionKey)
+
+const isUngrouped = computed(() => props.sectionKey === UNGROUPED_GROUP_KEY)
+const isFavorites = computed(() => props.sectionKey === FAVORITES_GROUP_ID)
+const isCustomGroup = computed(
+	() => props.grouping === 'Group' && !isUngrouped.value && !isFavorites.value,
+)
+const isGroupDragActive = computed(() => props.grouping === 'Group')
+const effectiveCollapsed = computed(() => (props.hideHeader ? false : props.isCollapsed))
+
+const { isDropTarget } = useDroppable({
+	id: computed(() => `instance-group:${props.sectionKey}`),
+	element: groupContainerRef,
+	disabled: computed(() => props.hideHeader || !isGroupDragActive.value),
+	data: computed(() => ({
+		groupId: props.sectionKey,
+	})),
+})
+
+watch(
+	() => [props.sectionKey, props.groupName],
+	() => {
+		groupName.value = props.groupName ?? props.sectionKey
+	},
+)
+
+watch(
+	() => props.groupPendingNameEdit,
+	async (pendingId) => {
+		if (pendingId !== props.sectionKey) return
+
+		await nextTick()
+		groupContainerRef.value?.scrollIntoView({ block: 'nearest' })
+		await groupNameInput.value?.startEditing()
+		emit('renameComplete')
+	},
+	{ immediate: true, flush: 'post' },
+)
+
+function validateGroupName(value: string) {
+	const normalized = value.trim()
+	if (normalized.length === 0) return false
+	if (normalized.length > MAX_GROUP_NAME_LENGTH) return false
+	return true
+}
+
+async function updateGroupName(value: string) {
+	const newName = value.trim()
+	if (!newName || newName === groupName.value) return false
+	emit('renameGroup', props.sectionKey, newName)
+	return true
+}
+
+function openGroupContextMenu(event: MouseEvent) {
+	groupOptions.value?.showMenu(
+		event,
+		props.sectionKey,
+		isCustomGroup.value
+			? [
+					{ name: 'new_instance' },
+					{ name: 'add_instances' },
+					{ name: 'edit_name' },
+					{ type: 'divider' },
+					{ name: 'delete_group', color: 'danger' },
+				]
+			: [{ name: 'new_instance' }],
+	)
+}
+
+async function handleGroupOption({ option }: { option: string }) {
+	if (option === 'new_instance') {
+		emit('newInstance')
+	} else if (option === 'add_instances') {
+		emit('addToGroup', props.sectionKey)
+	} else if (option === 'edit_name') {
+		groupNameInput.value?.startEditing()
+	} else if (option === 'delete_group') {
+		requestGroupDeletion()
+	}
+}
+
+function requestGroupDeletion() {
+	if (isUngrouped.value || isFavorites.value) return
+
+	if (props.instances.length > 0) {
+		confirmDeleteGroupModal.value?.show()
+	} else {
+		void removeGroup()
+	}
+}
+
+async function removeGroup() {
+	if (deletingGroup.value) return
+
+	deletingGroup.value = true
+	emit('deleteGroup', props.sectionKey)
+	setTimeout(() => {
+		deletingGroup.value = false
+		confirmDeleteGroupModal.value?.hide()
+	}, 300)
+}
+
+function onCardClick(instanceId: string, event: MouseEvent) {
+	emit('handleCardClick', instanceId, event)
+}
+
+function onStartLongPress(instanceId: string) {
+	emit('startLongPress', instanceId)
+}
+</script>
+
+<template>
+	<div
+		ref="groupContainerRef"
+		class="instance-group group/instance-container relative select-none pb-3"
+		@contextmenu.prevent.stop="openGroupContextMenu"
+	>
+		<div
+			v-if="!hideHeader && isDropTarget && isGroupDragActive"
+			class="pointer-events-none absolute -inset-2 inset-y-0 z-20 rounded-xl border-2 border-dashed border-contrast opacity-40 bg-transparent transition-opacity duration-150"
+		/>
+		<div
+			v-if="!hideHeader && (grouping === 'Group' || sectionKey !== UNGROUPED_GROUP_KEY)"
+			class="group/header flex h-10 w-full items-center gap-2 border-0 border-b border-solid border-b-surface-5"
+			:class="{ 'group-drag-handle cursor-grab': isCustomGroup }"
+		>
+			<div
+				class="flex min-w-0 cursor-pointer items-center gap-2"
+				@click="emit('toggleCollapse', sectionKey)"
+			>
+				<button
+					class="flex shrink-0 items-center border-0 bg-transparent p-0 cursor-pointer"
+					type="button"
+					:aria-expanded="!effectiveCollapsed"
+					:aria-label="
+						formatMessage(effectiveCollapsed ? messages.expandGroup : messages.collapseGroup)
+					"
+					@click.stop="emit('toggleCollapse', sectionKey)"
+				>
+					<DropdownIcon
+						class="size-5 shrink-0 text-[var(--color-text-tertiary)] transition-transform duration-300"
+						:class="{ 'rotate-180': !effectiveCollapsed }"
+					/>
+				</button>
+				<InlineEditableText
+					v-if="!isUngrouped && !isFavorites"
+					ref="groupNameInput"
+					v-model="groupName"
+					activation-mode="manual"
+					class="text-base font-semibold !h-10 text-[var(--color-text-default)] select-none"
+					max-width="24rem"
+					:max-length="MAX_GROUP_NAME_LENGTH"
+					:on-change="updateGroupName"
+					:validate="validateGroupName"
+				/>
+				<span v-else class="text-base font-semibold text-[var(--color-text-default)] select-none">
+					{{ isFavorites ? formatMessage(messages.pinned) : formatMessage(messages.ungrouped) }}
+				</span>
+				<TagItem v-if="instances.length" class="shrink-0 border-surface-3 bg-surface-2">
+					{{ instances.length }}
+				</TagItem>
+			</div>
+			<div class="min-w-0 flex-1" />
+			<div
+				v-if="isCustomGroup"
+				class="flex shrink-0 items-center opacity-0 transition-opacity duration-250 group-hover/header:opacity-100 focus-within:opacity-100"
+			>
+				<IconButton
+					v-tooltip="formatMessage(messages.moveGroupUp)"
+					:label="formatMessage(messages.moveGroupUp)"
+					type="quiet"
+					size="sm"
+					:disabled="!canMoveUp"
+					@click.stop="emit('moveGroup', sectionKey, -1)"
+				>
+					<ArrowUpIcon />
+				</IconButton>
+				<IconButton
+					v-tooltip="formatMessage(messages.moveGroupDown)"
+					:label="formatMessage(messages.moveGroupDown)"
+					type="quiet"
+					size="sm"
+					:disabled="!canMoveDown"
+					@click.stop="emit('moveGroup', sectionKey, 1)"
+				>
+					<ArrowDownIcon />
+				</IconButton>
+				<IconButton
+					v-tooltip="formatMessage(messages.editGroupName)"
+					:label="formatMessage(messages.editGroupName)"
+					type="quiet"
+					size="sm"
+					@click.stop="groupNameInput?.startEditing()"
+				>
+					<EditIcon />
+				</IconButton>
+				<IconButton
+					v-tooltip="formatMessage(messages.addToGroup)"
+					:label="formatMessage(messages.addToGroup)"
+					type="quiet"
+					size="sm"
+					@click.stop="emit('addToGroup', sectionKey)"
+				>
+					<PlusIcon />
+				</IconButton>
+				<IconButton
+					v-tooltip="formatMessage(messages.deleteGroup)"
+					:label="formatMessage(messages.deleteGroup)"
+					type="quiet"
+					size="sm"
+					:disabled="deletingGroup"
+					@click.stop="handleGroupOption({ option: 'delete_group' })"
+				>
+					<TrashIcon />
+				</IconButton>
+			</div>
+		</div>
+		<div v-if="!effectiveCollapsed" class="mt-2.5">
+			<section
+				class="grid grid-cols-[repeat(auto-fill,minmax(16rem,1fr))] w-full gap-3 mr-auto scroll-smooth overflow-y-auto"
+				:class="{
+					'grid-cols-[repeat(auto-fill,minmax(13rem,1fr))] gap-4': displayMode === 'cards',
+				}"
+			>
+				<template v-for="instance in instances" :key="instance.id">
+					<DraggableInstanceCard
+						v-if="isGroupDragActive"
+						:instance="instance"
+						:instance-group-id="sectionKey"
+						:disabled="selectMode"
+						@card-click="(event: MouseEvent) => onCardClick(instance.id, event)"
+						@contextmenu="
+							(event: MouseEvent) => emit('handleContextMenu', event, instance.id, props.sectionKey)
+						"
+						@start-long-press="onStartLongPress(instance.id)"
+						@cancel-long-press="emit('cancelLongPress')"
+					>
+						<template #default="{ isDragging }">
+							<div
+								:class="{
+									'pointer-events-none': selectMode,
+									'relative cursor-pointer select-none rounded-lg transition-all hover:brightness-90 active:scale-[0.98]': true,
+								}"
+								@click.capture="
+									(event: MouseEvent) => {
+										if (event.shiftKey && !selectMode) {
+											event.stopPropagation()
+											emit('handleCardClick', instance.id, event)
+										}
+									}
+								"
+							>
+								<Instance
+									:instance="instance"
+									:disabled="selectMode || isDragging"
+									:variant="displayMode === 'cards' ? 'library' : 'standard'"
+									:class="{
+										'opacity-50': selectMode && !selectedInstanceIds.has(instance.id),
+									}"
+								/>
+							</div>
+						</template>
+						<template #overlay>
+							<div
+								class="absolute right-2 bottom-2 z-10 transition-opacity"
+								:class="
+									selectMode && selectedInstanceIds.has(instance.id)
+										? ''
+										: 'opacity-0 group-hover:opacity-100'
+								"
+								@click.stop="emit('handleCheckboxClick', instance.id, $event)"
+							>
+								<Checkbox :model-value="selectedInstanceIds.has(instance.id)" />
+							</div>
+							<div
+								v-if="!selectMode"
+								class="absolute right-2 top-2 opacity-0 group-hover:opacity-100 transition-opacity"
+								@click.stop="
+									emit('handleContextMenu', $event as MouseEvent, instance.id, props.sectionKey)
+								"
+							>
+								<Button type="quiet" size="2xs" circular icon-only
+									><slot name="moreIcon" />
+								</Button>
+							</div>
+						</template>
+					</DraggableInstanceCard>
+
+					<div v-else class="group relative">
+						<div
+							class="relative cursor-pointer select-none rounded-lg transition-all hover:brightness-90 active:scale-[0.98]"
+							@click.capture="
+								(event: MouseEvent) => {
+									if (event.shiftKey && !selectMode) {
+										event.stopPropagation()
+										emit('handleCardClick', instance.id, event)
+									}
+								}
+							"
+							@click="emit('handleCardClick', instance.id, $event as MouseEvent)"
+							@mousedown="!selectMode && emit('startLongPress', instance.id)"
+							@mouseup="emit('cancelLongPress')"
+							@mouseleave="emit('cancelLongPress')"
+							@touchstart="!selectMode && emit('startLongPress', instance.id)"
+							@touchend="emit('cancelLongPress')"
+							@touchcancel="emit('cancelLongPress')"
+						>
+							<div :class="{ 'pointer-events-none': selectMode }">
+								<Instance
+									:instance="instance"
+									:disabled="selectMode"
+									:variant="displayMode === 'cards' ? 'library' : 'standard'"
+									:class="{
+										'opacity-50': selectMode && !selectedInstanceIds.has(instance.id),
+									}"
+									@contextmenu.prevent.stop="
+										(event: MouseEvent) =>
+											emit('handleContextMenu', event, instance.id, props.sectionKey)
+									"
+								/>
+							</div>
+						</div>
+						<div
+							class="absolute right-2 bottom-2 z-10 transition-opacity"
+							:class="
+								selectMode && selectedInstanceIds.has(instance.id)
+									? ''
+									: 'opacity-0 group-hover:opacity-100'
+							"
+							@click.stop="emit('handleCheckboxClick', instance.id, $event)"
+						>
+							<Checkbox :model-value="selectedInstanceIds.has(instance.id)" />
+						</div>
+						<div
+							v-if="!selectMode"
+							class="absolute right-2 top-2 opacity-0 group-hover:opacity-100 transition-opacity"
+							@click.stop="
+								emit('handleContextMenu', $event as MouseEvent, instance.id, props.sectionKey)
+							"
+						>
+							<Button type="quiet" size="2xs" circular icon-only><slot name="moreIcon" /> </Button>
+						</div>
+					</div>
+				</template>
+				<p
+					v-if="instances.length === 0"
+					class="col-span-full m-0 pt-1 pl-0.5 text-base font-base text-[var(--color-text-tertiary)] opacity-80"
+				>
+					{{ formatMessage(messages.emptyGroup) }}
+				</p>
+			</section>
+		</div>
+	</div>
+
+	<ContextMenu ref="groupOptions" @option-clicked="handleGroupOption">
+		<template #new_instance>
+			<PlusIcon />
+			{{ formatMessage(messages.newInstance) }}
+		</template>
+		<template #add_instances>
+			<PlusIcon />
+			{{ formatMessage(messages.addToGroup) }}
+		</template>
+		<template #edit_name>
+			<EditIcon />
+			{{ formatMessage(messages.editGroupName) }}
+		</template>
+		<template #delete_group>
+			<TrashIcon />
+			{{ formatMessage(messages.deleteGroup) }}
+		</template>
+	</ContextMenu>
+
+	<NewModal
+		ref="confirmDeleteGroupModal"
+		:header="formatMessage(messages.deleteGroup)"
+		fade="danger"
+		width="500px"
+	>
+		<p class="m-0 text-base text-[var(--color-text-default)]">
+			{{ formatMessage(messages.deleteGroupDescription) }}
+		</p>
+
+		<template #actions>
+			<div class="flex justify-end gap-2">
+				<Button type="outlined" @click="confirmDeleteGroupModal?.hide()">
+					<XIcon />
+					{{ formatMessage(commonMessages.cancelButton) }}
+				</Button>
+				<Button type="colored" color="red" :disabled="deletingGroup" @click="removeGroup">
+					<TrashIcon />
+					{{ formatMessage(messages.deleteGroup) }}
+				</Button>
+			</div>
+		</template>
+	</NewModal>
+</template>

apps/app-frontend/src/components/ui/modal/InstanceGroupModal.vue

@@ -0,0 +1,313 @@
+<template>
+	<NewModal ref="modal" no-padding scrollable actions-divider max-width="560px" width="560px">
+		<template #title>
+			<span class="text-2xl font-semibold text-[var(--color-text-primary)]">
+				{{
+					existingGroupName
+						? formatMessage(messages.addToGroupTitle, { groupName: existingGroupName })
+						: formatMessage(messages.header)
+				}}
+			</span>
+		</template>
+
+		<template v-if="!existingGroupName">
+			<div class="flex flex-col gap-2.5 p-6">
+				<label for="new-group-name" class="font-semibold text-[var(--color-text-primary)]">
+					{{ formatMessage(messages.groupName) }}
+				</label>
+				<StyledInput
+					id="new-group-name"
+					ref="groupNameInput"
+					v-model="newGroupName"
+					:placeholder="formatMessage(messages.groupNamePlaceholder)"
+					:maxlength="32"
+					@click="groupNameInput?.select()"
+				/>
+			</div>
+
+			<div class="h-px bg-divider" />
+		</template>
+
+		<div class="flex h-[400px] flex-col gap-3 overflow-y-auto bg-surface-2 py-4">
+			<div class="px-6">
+				<StyledInput
+					v-model="newGroupSearch"
+					:icon="SearchIcon"
+					:placeholder="formatMessage(messages.searchInstance)"
+					class="w-full"
+				/>
+			</div>
+
+			<div
+				v-if="newGroupInstances.length === 0"
+				class="flex items-center justify-center py-12 text-[var(--color-text-tertiary)]"
+			>
+				{{ formatMessage(messages.noInstancesFound) }}
+			</div>
+			<div v-else class="flex flex-col gap-1">
+				<div
+					v-for="instance in newGroupInstances"
+					:key="instance.id"
+					class="flex items-center justify-between gap-4 px-6 py-1.5 hover:bg-surface-3"
+					:class="{ 'opacity-60': selectedNewGroupInstanceIds.has(instance.id) }"
+				>
+					<div class="flex min-w-0 items-center gap-2.5">
+						<InstanceIcon
+							:icon-path="instance.icon_path"
+							:instance-id="instance.id"
+							:loader="instance.loader"
+							class="!size-[2rem] !rounded-md"
+						/>
+						<div class="flex min-w-0 items-center gap-2">
+							<span class="truncate font-semibold text-[var(--color-text-primary)]">{{
+								instance.name
+							}}</span>
+							<TagItem v-if="instance.groups && instance.groups.length > 0" class="shrink-0">
+								{{ getGroupName(instance.groups[0]) }}
+							</TagItem>
+						</div>
+					</div>
+					<Button
+						:type="selectedNewGroupInstanceIds.has(instance.id) ? 'outlined' : 'base'"
+						@click="toggleNewGroupInstance(instance.id)"
+					>
+						<CheckIcon v-if="selectedNewGroupInstanceIds.has(instance.id)" />
+						{{
+							formatMessage(
+								selectedNewGroupInstanceIds.has(instance.id) ? messages.added : messages.add,
+							)
+						}}
+					</Button>
+				</div>
+			</div>
+		</div>
+
+		<template #actions>
+			<div class="flex items-center justify-end gap-2">
+				<Button type="outlined" @click="modal?.hide()">
+					<XIcon />
+					{{ formatMessage(messages.cancel) }}
+				</Button>
+				<Button
+					type="colored"
+					color="brand"
+					:disabled="existingGroupName ? !canSaveGroups : !canCreateGroup"
+					@click="existingGroupName ? handleSaveGroups() : handleCreateGroup()"
+				>
+					<SpinnerIcon v-if="creatingGroup" class="animate-spin" />
+					<CheckIcon v-else-if="existingGroupName" />
+					<PlusIcon v-else />
+					{{ formatMessage(existingGroupName ? messages.saveChanges : messages.createGroup) }}
+				</Button>
+			</div>
+		</template>
+	</NewModal>
+</template>
+
+<script setup lang="ts">
+import { CheckIcon, PlusIcon, SearchIcon, SpinnerIcon, XIcon } from '@modrinth/assets'
+import { Button, defineMessages, NewModal, StyledInput, TagItem, useVIntl } from '@modrinth/ui'
+import { computed, ref } from 'vue'
+
+import InstanceIcon from '@/components/ui/InstanceIcon.vue'
+import { FAVORITES_GROUP_ID } from '@/composables/useInstanceGroups'
+import { list } from '@/helpers/instance'
+import { create_group, list_groups, set_group_memberships } from '@/helpers/instance-groups'
+import type { GameInstance } from '@/helpers/types'
+
+const { formatMessage } = useVIntl()
+
+const props = defineProps<{
+	instanceIds: string[]
+	existingGroupName?: string
+	existingGroupId?: string
+}>()
+
+const emit = defineEmits<{
+	(e: 'applied'): void
+}>()
+
+const messages = defineMessages({
+	header: {
+		id: 'app.instances.batch-edit-groups.header',
+		defaultMessage: 'Create group',
+	},
+	addToGroupTitle: {
+		id: 'app.instances.batch-edit-groups.add-to-group-title',
+		defaultMessage: 'Add instances to "{groupName}"',
+	},
+	groupName: {
+		id: 'app.instances.batch-edit-groups.group-name',
+		defaultMessage: 'Group name',
+	},
+	groupNamePlaceholder: {
+		id: 'app.instances.batch-edit-groups.group-name-placeholder',
+		defaultMessage: 'Enter group name',
+	},
+	searchInstance: {
+		id: 'app.instances.batch-edit-groups.search-instance',
+		defaultMessage: 'Search instances',
+	},
+	noInstancesFound: {
+		id: 'app.instances.batch-edit-groups.no-instances-found',
+		defaultMessage: 'No instances found',
+	},
+	add: {
+		id: 'app.instances.batch-edit-groups.add',
+		defaultMessage: 'Add',
+	},
+	added: {
+		id: 'app.instances.batch-edit-groups.added',
+		defaultMessage: 'Added',
+	},
+	cancel: {
+		id: 'app.instances.batch-edit-groups.cancel',
+		defaultMessage: 'Cancel',
+	},
+	createGroup: {
+		id: 'app.instances.batch-edit-groups.create',
+		defaultMessage: 'Create group',
+	},
+	pinnedGroupName: {
+		id: 'app.instances.group.pinned',
+		defaultMessage: 'Pinned',
+	},
+	saveChanges: {
+		id: 'app.instances.batch-edit-groups.save-changes',
+		defaultMessage: 'Save',
+	},
+})
+
+const modal = ref<InstanceType<typeof NewModal>>()
+const groupNameInput = ref<InstanceType<typeof StyledInput>>()
+const newGroupName = ref('')
+const newGroupSearch = ref('')
+const creatingGroup = ref(false)
+const allInstances = ref<GameInstance[]>([])
+const groupNameMap = ref(new Map<string, string>())
+const selectedNewGroupInstanceIds = ref(new Set<string>())
+
+const canCreateGroup = computed(() => newGroupName.value.trim().length > 0)
+
+const canSaveGroups = computed(() => {
+	if (!props.existingGroupName) return false
+	const groupId = props.existingGroupId
+	if (!groupId) return false
+	return allInstances.value.some((instance) => {
+		const isSelected = selectedNewGroupInstanceIds.value.has(instance.id)
+		const hasGroup = (instance.groups || []).includes(groupId)
+		return isSelected !== hasGroup
+	})
+})
+
+const newGroupInstances = computed(() => {
+	const search = newGroupSearch.value.toLowerCase()
+	return allInstances.value.filter((instance) => {
+		if (!search) return true
+		return instance.name.toLowerCase().includes(search)
+	})
+})
+
+function getGroupName(groupId: string) {
+	if (groupId === FAVORITES_GROUP_ID) {
+		return formatMessage(messages.pinnedGroupName)
+	}
+	return groupNameMap.value.get(groupId) || groupId
+}
+
+function show(ids?: string[]) {
+	newGroupSearch.value = ''
+	creatingGroup.value = false
+	Promise.all([list(), list_groups()]).then(([instances, groups]) => {
+		allInstances.value = instances as GameInstance[]
+		const map = new Map<string, string>()
+		for (const g of groups) {
+			map.set(g.id, g.name)
+		}
+		groupNameMap.value = map
+
+		if (!props.existingGroupName) {
+			const customGroups = groups.filter((g: { id: string }) => g.id !== 'group:favorites')
+			let groupNumber = customGroups.length + 1
+			const existingNames = new Set(groups.map((g: { name: string }) => g.name.toLowerCase()))
+			while (existingNames.has(`group ${groupNumber}`)) {
+				groupNumber++
+			}
+			newGroupName.value = `Group ${groupNumber}`
+		}
+
+		if (props.existingGroupName) {
+			const groupId = props.existingGroupId
+			selectedNewGroupInstanceIds.value = new Set(
+				allInstances.value.filter((i) => (i.groups || []).includes(groupId || '')).map((i) => i.id),
+			)
+		} else {
+			selectedNewGroupInstanceIds.value = new Set(ids ?? props.instanceIds)
+		}
+	})
+	modal.value?.show()
+}
+
+function toggleNewGroupInstance(instanceId: string) {
+	const next = new Set(selectedNewGroupInstanceIds.value)
+	if (next.has(instanceId)) {
+		next.delete(instanceId)
+	} else {
+		next.add(instanceId)
+	}
+	selectedNewGroupInstanceIds.value = next
+}
+
+async function handleCreateGroup() {
+	const name = newGroupName.value.trim()
+	if (!name || selectedNewGroupInstanceIds.value.size === 0) return
+
+	creatingGroup.value = true
+
+	const group = await create_group(name).catch(() => null)
+	if (!group) {
+		creatingGroup.value = false
+		return
+	}
+
+	if (selectedNewGroupInstanceIds.value.size > 0) {
+		const updates = [...selectedNewGroupInstanceIds.value].map((instanceId) => ({
+			instance_id: instanceId,
+			group_ids: [group.id],
+		}))
+		await set_group_memberships(updates).catch(() => {})
+	}
+
+	creatingGroup.value = false
+	modal.value?.hide()
+	emit('applied')
+}
+
+async function handleSaveGroups() {
+	if (!props.existingGroupName) return
+
+	creatingGroup.value = true
+	const groupId = props.existingGroupId
+
+	const changedInstances = allInstances.value.filter((instance) => {
+		const isSelected = selectedNewGroupInstanceIds.value.has(instance.id)
+		const hasGroup = (instance.groups || []).includes(groupId || '')
+		return isSelected !== hasGroup
+	})
+
+	const updates = changedInstances.map((instance) => {
+		const isSelected = selectedNewGroupInstanceIds.value.has(instance.id)
+		return {
+			instance_id: instance.id,
+			group_ids: isSelected ? [groupId!] : [],
+		}
+	})
+	await set_group_memberships(updates).catch(() => {})
+
+	creatingGroup.value = false
+	modal.value?.hide()
+	emit('applied')
+}
+
+defineExpose({ show })
+</script>

apps/app-frontend/src/composables/useGridGrouping.ts

@@ -7,15 +7,22 @@ export const UNGROUPED_GROUP_KEY = '__ungrouped__'
 
 export type GridGroupingOption = 'Group' | 'Loader' | 'Game version' | 'None'
 export type GridSortOption =
-	| 'Name'
-	| 'Last played'
-	| 'Date created'
-	| 'Date modified'
-	| 'Game version'
+	'Name' | 'Last played' | 'Date created' | 'Date modified' | 'Game version'
+
+export type GridSortDirection = 'asc' | 'desc'
+
+export const defaultSortDirections: Record<GridSortOption, GridSortDirection> = {
+	Name: 'asc',
+	'Last played': 'desc',
+	'Date created': 'desc',
+	'Date modified': 'desc',
+	'Game version': 'asc',
+}
 
 export interface GridDisplayState {
 	group: GridGroupingOption
 	sortBy: GridSortOption
+	sortDirections: Partial<Record<GridSortOption, GridSortDirection>>
 	collapsedGroups: string[]
 }
 
@@ -38,6 +45,7 @@ export function useGridGrouping<T extends Record<string, unknown>>(
 		{
 			group: 'Group',
 			sortBy: 'Name',
+			sortDirections: {},
 			collapsedGroups: [],
 		},
 		localStorage,
@@ -66,7 +74,7 @@ export function useGridGrouping<T extends Record<string, unknown>>(
 		state.value.collapsedGroups = [...collapsedSections]
 	}
 
-	function sortInstances(instances: T[], sortBy: GridSortOption): T[] {
+	function sortInstances(instances: T[], sortBy: GridSortOption, ascending: boolean): T[] {
 		const sorted = [...instances]
 		const getGameVersion = options.getGameVersion ?? ((i: T) => i.game_version ?? '')
 		const getLastPlayed = options.getLastPlayed ?? ((i: T) => i.last_played ?? 0)
@@ -83,16 +91,19 @@ export function useGridGrouping<T extends Record<string, unknown>>(
 				)
 				break
 			case 'Last played':
-				sorted.sort((a, b) => dayjs(getLastPlayed(b)).diff(dayjs(getLastPlayed(a))))
+				sorted.sort((a, b) => dayjs(getLastPlayed(a)).diff(dayjs(getLastPlayed(b))))
 				break
 			case 'Date created':
-				sorted.sort((a, b) => dayjs(getDateCreated(b)).diff(dayjs(getDateCreated(a))))
+				sorted.sort((a, b) => dayjs(getDateCreated(a)).diff(dayjs(getDateCreated(b))))
 				break
 			case 'Date modified':
-				sorted.sort((a, b) => dayjs(getDateModified(b)).diff(dayjs(getDateModified(a))))
+				sorted.sort((a, b) => dayjs(getDateModified(a)).diff(dayjs(getDateModified(b))))
 				break
 		}
 
+		if (!ascending) {
+			sorted.reverse()
+		}
 		return sorted
 	}
 
@@ -148,11 +159,25 @@ export function useGridGrouping<T extends Record<string, unknown>>(
 	function sortSections(
 		instanceMap: Map<string, T[]>,
 		group: GridGroupingOption,
+		sortBy: GridSortOption,
 	): Map<string, T[]> {
 		if (group !== 'Group' && group !== 'Game version') {
 			return instanceMap
 		}
 
+		if (group === 'Group' && sortBy !== 'Name') {
+			if (instanceMap.has(UNGROUPED_GROUP_KEY) && instanceMap.size > 1) {
+				const ungroupedInstances = instanceMap.get(UNGROUPED_GROUP_KEY)!
+				instanceMap.delete(UNGROUPED_GROUP_KEY)
+				const newMap = new Map<string, T[]>([[UNGROUPED_GROUP_KEY, ungroupedInstances]])
+				for (const [key, instances] of instanceMap) {
+					newMap.set(key, instances)
+				}
+				return newMap
+			}
+			return instanceMap
+		}
+
 		const sortedEntries = [...instanceMap.entries()].sort((a, b) => {
 			if (group === 'Group') {
 				if (a[0] === UNGROUPED_GROUP_KEY && b[0] !== UNGROUPED_GROUP_KEY) return -1
@@ -166,12 +191,30 @@ export function useGridGrouping<T extends Record<string, unknown>>(
 		return instanceMap
 	}
 
+	const sortDirection = computed<GridSortDirection>(() => {
+		return (
+			state.value.sortDirections[state.value.sortBy] ?? defaultSortDirections[state.value.sortBy]
+		)
+	})
+
+	const isSortAscending = computed(() => sortDirection.value === 'asc')
+
+	const toggleSortDirection = () => {
+		const current = sortDirection.value
+		const next: GridSortDirection = current === 'asc' ? 'desc' : 'asc'
+		state.value.sortDirections = {
+			...state.value.sortDirections,
+			[state.value.sortBy]: next,
+		}
+	}
+
 	const filteredResults = computed(() => {
 		const { group = 'Group', sortBy = 'Name' } = state.value
+		const ascending = isSortAscending.value
 
-		const sorted = sortInstances(instances.value, sortBy)
+		const sorted = sortInstances(instances.value, sortBy, ascending)
 		const grouped = groupInstances(sorted, group)
-		return sortSections(grouped, group)
+		return sortSections(grouped, group, sortBy)
 	})
 
 	return {
@@ -180,6 +223,9 @@ export function useGridGrouping<T extends Record<string, unknown>>(
 		filteredResults,
 		isSectionCollapsed,
 		setSectionCollapsed,
+		sortDirection,
+		isSortAscending,
+		toggleSortDirection,
 		UNGROUPED_GROUP_KEY,
 	}
-}
+}

apps/app-frontend/src/composables/useInstanceGroups.ts

@@ -0,0 +1,182 @@
+import { computed, type Ref, ref, watch } from 'vue'
+
+import { instance_groups_listener } from '@/helpers/events'
+import {
+	create_group,
+	delete_group,
+	type InstanceGroupDefinition,
+	type InstanceGroupMembershipUpdate,
+	list_groups,
+	MAX_INSTANCE_GROUP_NAME_LENGTH,
+	rename_group,
+	set_group_memberships,
+	set_group_order,
+} from '@/helpers/instance-groups'
+
+export const FAVORITES_GROUP_ID = 'group:favorites'
+
+export const UNGROUPED_GROUP_ID = 'group:none'
+
+export { MAX_INSTANCE_GROUP_NAME_LENGTH }
+
+export { type InstanceGroupDefinition, type InstanceGroupMembershipUpdate }
+
+export interface InstanceGroupWithMembership {
+	key: string
+	name: string
+	instances: string[]
+}
+
+export function useInstanceGroups(instances: Ref<{ id: string; groups: string[] }[]>) {
+	const libraryGroups = ref<InstanceGroupDefinition[]>([])
+	const libraryGroupsLoaded = ref(false)
+
+	async function fetchGroups() {
+		libraryGroups.value = await list_groups()
+		libraryGroupsLoaded.value = true
+	}
+
+	fetchGroups()
+
+	instance_groups_listener(() => {
+		fetchGroups()
+	})
+
+	const orderedLibraryGroupIds = ref<string[]>([])
+
+	watch(
+		libraryGroups,
+		(groups) => {
+			orderedLibraryGroupIds.value = groups.map((g) => g.id)
+		},
+		{ immediate: true },
+	)
+
+	const instanceGroups = computed(() => {
+		if (!libraryGroupsLoaded.value) {
+			return []
+		}
+
+		const instanceGroupMap = new Map<string, string[]>()
+
+		for (const instance of instances.value) {
+			const groups = instance.groups ?? []
+			for (const groupId of groups) {
+				if (!instanceGroupMap.has(groupId)) {
+					instanceGroupMap.set(groupId, [])
+				}
+				instanceGroupMap.get(groupId)!.push(instance.id)
+			}
+		}
+
+		const allGroupIds = new Set<string>()
+		const groupMap = new Map<string, string[]>()
+
+		for (const groupId of orderedLibraryGroupIds.value) {
+			allGroupIds.add(groupId)
+			groupMap.set(groupId, instanceGroupMap.get(groupId) ?? [])
+		}
+
+		const ungroupedIds: string[] = []
+		for (const instance of instances.value) {
+			const instanceGroups = instance.groups ?? []
+			const isInAnyGroup = instanceGroups.some((g) => allGroupIds.has(g))
+			if (!isInAnyGroup) {
+				ungroupedIds.push(instance.id)
+			}
+		}
+
+		if (ungroupedIds.length > 0) {
+			groupMap.set(UNGROUPED_GROUP_ID, ungroupedIds)
+		}
+
+		return [...groupMap.entries()].map(([key, instances]) => ({
+			key,
+			name:
+				key === UNGROUPED_GROUP_ID
+					? 'Ungrouped'
+					: (libraryGroups.value.find((g) => g.id === key)?.name ?? key),
+			instances,
+		}))
+	})
+
+	const creatingGroup = ref(false)
+	const reorderingGroups = ref(false)
+
+	async function createNewGroup(name: string): Promise<string | null> {
+		creatingGroup.value = true
+		try {
+			const group = await create_group(name)
+			libraryGroups.value = [...libraryGroups.value, group]
+			orderedLibraryGroupIds.value = [...orderedLibraryGroupIds.value, group.id]
+			return group.id
+		} finally {
+			creatingGroup.value = false
+		}
+	}
+
+	async function renameGroupById(id: string, newName: string): Promise<boolean> {
+		if (id === FAVORITES_GROUP_ID) return false
+		const result = await rename_group(id, newName)
+		const idx = libraryGroups.value.findIndex((g) => g.id === id)
+		if (idx !== -1) {
+			libraryGroups.value = [
+				...libraryGroups.value.slice(0, idx),
+				result,
+				...libraryGroups.value.slice(idx + 1),
+			]
+		}
+		return true
+	}
+
+	async function deleteGroupById(id: string): Promise<boolean> {
+		if (id === FAVORITES_GROUP_ID) return false
+		await delete_group(id)
+		libraryGroups.value = libraryGroups.value.filter((g) => g.id !== id)
+		orderedLibraryGroupIds.value = orderedLibraryGroupIds.value.filter((gid) => gid !== id)
+		return true
+	}
+
+	async function reorderGroups(groupIds: string[]): Promise<boolean> {
+		reorderingGroups.value = true
+		try {
+			await set_group_order(groupIds)
+			// Favorites is rendered separately from draggable sections. Keep it in
+			// the local order after a drag even though the backend accepts only the
+			// reorderable group ids; otherwise it appears again as an ordinary
+			// section until the next full group refresh.
+			orderedLibraryGroupIds.value = [
+				FAVORITES_GROUP_ID,
+				...groupIds.filter((id) => id !== FAVORITES_GROUP_ID),
+			]
+			return true
+		} finally {
+			reorderingGroups.value = false
+		}
+	}
+
+	async function setMemberships(updates: InstanceGroupMembershipUpdate[]): Promise<boolean> {
+		await set_group_memberships(updates)
+		return true
+	}
+
+	function groupNameById(id: string): string | undefined {
+		if (id === UNGROUPED_GROUP_ID) return 'Ungrouped'
+		return libraryGroups.value.find((g) => g.id === id)?.name
+	}
+
+	return {
+		libraryGroups,
+		libraryGroupsLoaded,
+		orderedLibraryGroupIds,
+		instanceGroups,
+		creatingGroup,
+		reorderingGroups,
+		createGroup: createNewGroup,
+		renameGroupById,
+		deleteGroupById,
+		reorderGroups,
+		setMemberships,
+		groupNameById,
+	}
+}

apps/app-frontend/src/helpers/analytics.ts

@@ -0,0 +1,75 @@
+interface InstanceProperties {
+	loader: string
+	game_version: string
+}
+
+interface ProjectProperties extends InstanceProperties {
+	id: string
+	project_type: string
+}
+
+type AnalyticsEventMap = {
+	Launched: { version: string; dev: boolean; onboarded: boolean }
+	PageView: { path: string; fromPath: string; failed: unknown }
+	InstanceCreate: { source: string }
+	InstanceCreateStart: { source: string }
+	InstanceStart: InstanceProperties & { source: string }
+	InstanceStop: Partial<InstanceProperties> & { source?: string }
+	InstanceDuplicate: InstanceProperties
+	InstanceRepair: InstanceProperties
+	InstanceSetIcon: Record<string, never>
+	InstanceRemoveIcon: Record<string, never>
+	InstanceUpdateAll: InstanceProperties & { count: number; selected: boolean }
+	InstanceProjectUpdate: InstanceProperties & { id: string; name: string; project_type: string }
+	InstanceProjectDisable: InstanceProperties & {
+		id: string
+		name: string
+		project_type: string
+		disabled: boolean
+	}
+	InstanceProjectRemove: InstanceProperties & { id: string; name: string; project_type: string }
+	ProjectInstall: ProjectProperties & { version_id: string; title: string; source: string }
+	ProjectInstallStart: { source: string }
+	PackInstall: { id: string; version_id: string; title: string; source: string }
+	PackInstallStart: Record<string, never>
+	AccountLogIn: { source?: string }
+	AccountLogOut: Record<string, never>
+	JavaTest: { path: string; success: boolean }
+	JavaManualSelect: { version: string }
+	JavaAutoDetect: { path: string; version: string }
+	GalleryImageNext: { project_id: string; url: string }
+	GalleryImagePrevious: { project_id: string; url: unknown }
+	GalleryImageExpand: { project_id: string; url: string }
+}
+
+export type AnalyticsEvent = keyof AnalyticsEventMap
+
+let optedIn = false
+let debugEnabled = false
+
+export const initAnalytics = () => {
+	optedIn = true
+}
+
+export const debugAnalytics = () => {
+	debugEnabled = true
+}
+
+export const optOutAnalytics = () => {
+	optedIn = false
+}
+
+export const optInAnalytics = () => {
+	optedIn = true
+}
+
+type OptionalArgs<T> = Record<string, never> extends T ? [properties?: T] : [properties: T]
+
+export const trackEvent = <E extends AnalyticsEvent>(
+	eventName: E,
+	...args: OptionalArgs<AnalyticsEventMap[E]>
+) => {
+	if (optedIn && debugEnabled) {
+		console.debug('[Starlight telemetry disabled]', eventName, args[0])
+	}
+}

apps/app-frontend/src/helpers/events.js

@@ -82,6 +82,16 @@ export async function instance_bulk_update_progress_listener(callback) {
 	return await listen('instance_bulk_update_progress', (event) => callback(event.payload))
 }
 
+/// Payload for the 'instance_groups_changed' event
+/*
+	InstanceGroupsChangedPayload {
+		instance_ids: string[]
+	}
+*/
+export async function instance_groups_listener(callback) {
+	return await listen('instance_groups_changed', (event) => callback(event.payload))
+}
+
 export async function install_job_listener(callback) {
 	return await listen('install_job', (event) => callback(event.payload))
 }

apps/app-frontend/src/helpers/instance-groups.ts

@@ -1 +1,46 @@
-export const MAX_INSTANCE_GROUP_NAME_LENGTH = 256
+import { invoke } from '@tauri-apps/api/core'
+
+export const MAX_INSTANCE_GROUP_NAME_LENGTH = 256
+
+export type InstanceGroupDefinition = {
+	id: string
+	name: string
+}
+
+export type InstanceGroupMembershipUpdate = {
+	instance_id: string
+	group_ids: string[]
+}
+
+export async function list_groups(): Promise<InstanceGroupDefinition[]> {
+	return await invoke('plugin:instance|instance_list_groups')
+}
+
+export async function create_group(name: string): Promise<InstanceGroupDefinition> {
+	return await invoke('plugin:instance|instance_create_group', { name })
+}
+
+export async function rename_group(id: string, newName: string): Promise<InstanceGroupDefinition> {
+	return await invoke('plugin:instance|instance_rename_group', {
+		id,
+		newName,
+	})
+}
+
+export async function delete_group(id: string): Promise<void> {
+	return await invoke('plugin:instance|instance_delete_group', { id })
+}
+
+export async function set_group_order(group_ids: string[]): Promise<void> {
+	return await invoke('plugin:instance|instance_set_group_order', {
+		groupIds: group_ids,
+	})
+}
+
+export async function set_group_memberships(
+	updates: InstanceGroupMembershipUpdate[],
+): Promise<void> {
+	return await invoke('plugin:instance|instance_set_group_memberships', {
+		updates,
+	})
+}

apps/app-frontend/src/locales/en-US/index.json

@@ -11561,5 +11561,43 @@
   "app.skins.armor.description": {"message": "Try armour and trims on your skin. Nothing is stored until you save it."},
   "app.skins.armor.unsaved": {"message": "Unsaved changes"},
   "app.skins.armor.reset-to-saved": {"message": "Reset to saved"},
-  "app.skins.armor.restore-defaults": {"message": "Restore defaults"}
-}
+  "app.skins.armor.restore-defaults": {"message": "Restore defaults"},
+  "app.instances.batch-edit-groups.add": {"message": "Add"},
+  "app.instances.batch-edit-groups.add-to-group-title": {"message": "Add instances to \"{groupName}\""},
+  "app.instances.batch-edit-groups.added": {"message": "Added"},
+  "app.instances.batch-edit-groups.cancel": {"message": "Cancel"},
+  "app.instances.batch-edit-groups.create": {"message": "Create group"},
+  "app.instances.batch-edit-groups.group-name": {"message": "Group name"},
+  "app.instances.batch-edit-groups.group-name-placeholder": {"message": "Enter group name"},
+  "app.instances.batch-edit-groups.no-instances-found": {"message": "No instances found"},
+  "app.instances.batch-edit-groups.save-changes": {"message": "Save"},
+  "app.instances.batch-edit-groups.search-instance": {"message": "Search instances"},
+  "app.instances.group.add-to-group": {"message": "Add to group"},
+  "app.instances.group.collapse": {"message": "Collapse group"},
+  "app.instances.group.delete-description": {"message": "Instances in this group will be ungrouped."},
+  "app.instances.group.delete-group": {"message": "Delete group"},
+  "app.instances.group.edit-name": {"message": "Edit group name"},
+  "app.instances.group.empty": {"message": "Drag and drop to add instances."},
+  "app.instances.group.expand": {"message": "Expand group"},
+  "app.instances.group.move-down": {"message": "Move group down"},
+  "app.instances.group.move-up": {"message": "Move group up"},
+  "app.instances.group.name-empty": {"message": "Group names cannot be empty."},
+  "app.instances.group.name-too-long": {"message": "Group names cannot be longer than {maxLength} characters."},
+  "app.instances.group.new-instance": {"message": "New instance"},
+  "app.instances.group.pinned": {"message": "Pinned"},
+  "app.instances.group.rename-group": {"message": "Rename group"},
+  "app.instances.sort-by": {"message": "Sort by"},
+  "app.instances.sort.direction.asc-alphabetical": {"message": "A–Z"},
+  "app.instances.sort.direction.asc-date": {"message": "Oldest first"},
+  "app.instances.sort.direction.asc-recency": {"message": "Least recent first"},
+  "app.instances.sort.direction.asc-version": {"message": "Oldest version first"},
+  "app.instances.sort.direction.desc-alphabetical": {"message": "Z–A"},
+  "app.instances.sort.direction.desc-date": {"message": "Newest first"},
+  "app.instances.sort.direction.desc-recency": {"message": "Most recent first"},
+  "app.instances.sort.direction.desc-version": {"message": "Newest version first"},
+  "app.library.context-menu.pin-instance": {"message": "Pin instance"},
+  "app.library.context-menu.remove-from-group": {"message": "Remove from group"},
+  "app.library.context-menu.unpin-instance": {"message": "Unpin instance"},
+  "app.library.group.new": {"message": "New group"},
+  "app.library.selection.new-group": {"message": "New group"},
+  "app.library.selection.remove-from-group": {"message": "Remove from group"}}

apps/app-frontend/src/locales/zh-CN/index.json

@@ -11392,5 +11392,43 @@
   "app.skins.armor.description": {"message": "在皮肤上试穿盔甲与纹饰。未保存前不会写入任何内容。"},
   "app.skins.armor.unsaved": {"message": "有未保存的更改"},
   "app.skins.armor.reset-to-saved": {"message": "重置为已保存"},
-  "app.skins.armor.restore-defaults": {"message": "恢复默认"}
-}
+  "app.skins.armor.restore-defaults": {"message": "恢复默认"},
+  "app.instances.batch-edit-groups.add": {"message": "添加"},
+  "app.instances.batch-edit-groups.add-to-group-title": {"message": "添加实例到「{groupName}」"},
+  "app.instances.batch-edit-groups.added": {"message": "已添加"},
+  "app.instances.batch-edit-groups.cancel": {"message": "取消"},
+  "app.instances.batch-edit-groups.create": {"message": "创建分组"},
+  "app.instances.batch-edit-groups.group-name": {"message": "分组名称"},
+  "app.instances.batch-edit-groups.group-name-placeholder": {"message": "输入分组名称"},
+  "app.instances.batch-edit-groups.no-instances-found": {"message": "未找到实例"},
+  "app.instances.batch-edit-groups.save-changes": {"message": "保存"},
+  "app.instances.batch-edit-groups.search-instance": {"message": "搜索实例"},
+  "app.instances.group.add-to-group": {"message": "添加到分组"},
+  "app.instances.group.collapse": {"message": "折叠分组"},
+  "app.instances.group.delete-description": {"message": "此分组中的实例将被取消分组。"},
+  "app.instances.group.delete-group": {"message": "删除分组"},
+  "app.instances.group.edit-name": {"message": "编辑分组名称"},
+  "app.instances.group.empty": {"message": "拖放实例到此处添加。"},
+  "app.instances.group.expand": {"message": "展开分组"},
+  "app.instances.group.move-down": {"message": "下移分组"},
+  "app.instances.group.move-up": {"message": "上移分组"},
+  "app.instances.group.name-empty": {"message": "分组名称不能为空。"},
+  "app.instances.group.name-too-long": {"message": "分组名称不能超过 {maxLength} 个字符。"},
+  "app.instances.group.new-instance": {"message": "新建实例"},
+  "app.instances.group.pinned": {"message": "已置顶"},
+  "app.instances.group.rename-group": {"message": "重命名分组"},
+  "app.instances.sort-by": {"message": "排序方式"},
+  "app.instances.sort.direction.asc-alphabetical": {"message": "A–Z 正序"},
+  "app.instances.sort.direction.asc-date": {"message": "最早的在前"},
+  "app.instances.sort.direction.asc-recency": {"message": "最早游玩在前"},
+  "app.instances.sort.direction.asc-version": {"message": "旧版本在前"},
+  "app.instances.sort.direction.desc-alphabetical": {"message": "Z–A 倒序"},
+  "app.instances.sort.direction.desc-date": {"message": "最新的在前"},
+  "app.instances.sort.direction.desc-recency": {"message": "最近游玩在前"},
+  "app.instances.sort.direction.desc-version": {"message": "新版本在前"},
+  "app.library.context-menu.pin-instance": {"message": "置顶实例"},
+  "app.library.context-menu.remove-from-group": {"message": "移出分组"},
+  "app.library.context-menu.unpin-instance": {"message": "取消置顶"},
+  "app.library.group.new": {"message": "新建分组"},
+  "app.library.selection.new-group": {"message": "新建分组"},
+  "app.library.selection.remove-from-group": {"message": "移出分组"}}

apps/app/build.rs

@@ -534,6 +534,12 @@ fn main() {
                         "instance_delete_screenshot_group",
                         "instance_set_screenshot_group_memberships",
                         "instance_import_screenshot_groups",
+                        "instance_list_groups",
+                        "instance_create_group",
+                        "instance_rename_group",
+                        "instance_delete_group",
+                        "instance_set_group_order",
+                        "instance_set_group_memberships",
                         "instance_delete_screenshots",
                         "instance_export_screenshots",
                         "instance_move_screenshots",

apps/app/src/api/instance/mod.rs

@@ -131,6 +131,12 @@ pub fn init<R: tauri::Runtime>() -> tauri::plugin::TauriPlugin<R> {
             instance_delete_screenshot_group,
             instance_set_screenshot_group_memberships,
             instance_import_screenshot_groups,
+            instance_list_groups,
+            instance_create_group,
+            instance_rename_group,
+            instance_delete_group,
+            instance_set_group_order,
+            instance_set_group_memberships,
             instance_delete_screenshots,
             instance_export_screenshots,
             instance_move_screenshots,
@@ -1717,6 +1723,44 @@ pub async fn instance_import_screenshot_groups(
     Ok(theseus::instance::import_screenshot_groups(groups).await?)
 }
 
+#[tauri::command]
+pub async fn instance_list_groups()
+-> Result<Vec<theseus::instance::InstanceGroup>> {
+    Ok(theseus::instance::list_groups().await?)
+}
+
+#[tauri::command]
+pub async fn instance_create_group(
+    name: String,
+) -> Result<theseus::instance::InstanceGroup> {
+    Ok(theseus::instance::create_group(name).await?)
+}
+
+#[tauri::command]
+pub async fn instance_rename_group(
+    id: String,
+    new_name: String,
+) -> Result<theseus::instance::InstanceGroup> {
+    Ok(theseus::instance::rename_group(id, new_name).await?)
+}
+
+#[tauri::command]
+pub async fn instance_delete_group(id: String) -> Result<()> {
+    Ok(theseus::instance::delete_group(id).await?)
+}
+
+#[tauri::command]
+pub async fn instance_set_group_order(group_ids: Vec<String>) -> Result<()> {
+    Ok(theseus::instance::set_group_order(group_ids).await?)
+}
+
+#[tauri::command]
+pub async fn instance_set_group_memberships(
+    updates: Vec<theseus::instance::InstanceGroupMembershipUpdate>,
+) -> Result<()> {
+    Ok(theseus::instance::set_group_memberships(updates).await?)
+}
+
 #[tauri::command]
 pub async fn instance_delete_screenshots(
     keys: Vec<theseus::instance::ScreenshotKey>,

packages/app-lib/src/api/instance/groups.rs

@@ -0,0 +1,261 @@
+use crate::event::emit::emit_instance_groups_changed;
+use crate::state::instance_groups;
+use serde::{Deserialize, Serialize};
+use std::collections::HashSet;
+use uuid::Uuid;
+
+const MAX_GROUP_NAME_LENGTH: usize = 256;
+pub const FAVORITES_GROUP_ID: &str = instance_groups::FAVORITES_GROUP_ID;
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct InstanceGroup {
+    pub id: String,
+    pub name: String,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct InstanceGroupMembershipUpdate {
+    pub instance_id: String,
+    pub group_ids: Vec<String>,
+}
+
+fn validate_group_name(name: &str) -> crate::Result<&str> {
+    let name = name.trim();
+
+    if name.is_empty() {
+        return Err(crate::ErrorKind::InputError(
+            "Group name cannot be empty".to_string(),
+        )
+        .into());
+    }
+
+    if name.chars().count() > MAX_GROUP_NAME_LENGTH {
+        return Err(crate::ErrorKind::InputError(format!(
+            "Group name cannot exceed {MAX_GROUP_NAME_LENGTH} characters"
+        ))
+        .into());
+    }
+
+    if name.eq_ignore_ascii_case("none") {
+        return Err(crate::ErrorKind::InputError(
+            "Group name cannot be None".to_string(),
+        )
+        .into());
+    }
+
+    Ok(name)
+}
+
+fn normalize_membership_updates(
+    mut updates: Vec<InstanceGroupMembershipUpdate>,
+) -> crate::Result<Vec<InstanceGroupMembershipUpdate>> {
+    let mut instance_ids = HashSet::new();
+    for update in &mut updates {
+        if !instance_ids.insert(update.instance_id.clone()) {
+            return Err(crate::ErrorKind::InputError(format!(
+                "Duplicate instance {} in group membership update",
+                update.instance_id
+            ))
+            .into());
+        }
+
+        let mut group_ids = HashSet::new();
+        update
+            .group_ids
+            .retain(|group_id| group_ids.insert(group_id.clone()));
+    }
+
+    Ok(updates)
+}
+
+pub async fn list_groups() -> crate::Result<Vec<InstanceGroup>> {
+    Ok(instance_groups::list()
+        .into_iter()
+        .map(|group| InstanceGroup {
+            id: group.id,
+            name: group.name,
+        })
+        .collect())
+}
+
+pub async fn create_group(name: String) -> crate::Result<InstanceGroup> {
+    let name = validate_group_name(&name)?;
+    let id = Uuid::new_v4().to_string();
+    instance_groups::create(&id, name);
+
+    Ok(InstanceGroup {
+        id,
+        name: name.to_string(),
+    })
+}
+
+pub async fn set_group_order(group_ids: Vec<String>) -> crate::Result<()> {
+    instance_groups::set_order(&group_ids);
+    Ok(())
+}
+
+pub async fn set_group_memberships(
+    updates: Vec<InstanceGroupMembershipUpdate>,
+) -> crate::Result<()> {
+    if updates.is_empty() {
+        return Ok(());
+    }
+
+    let updates = normalize_membership_updates(updates)?;
+
+    // Note: the instances themselves are deliberately not validated here.
+    // JSON-backed instances (`local:` ids) have no row in the `instances` table,
+    // and requiring one is what used to make grouping them fail outright.
+    let unique_group_ids = updates
+        .iter()
+        .flat_map(|update| update.group_ids.iter())
+        .collect::<HashSet<_>>();
+    for group_id in unique_group_ids {
+        if !instance_groups::group_exists(group_id) {
+            return Err(crate::ErrorKind::InputError(format!(
+                "Unknown instance group {group_id}"
+            ))
+            .into());
+        }
+    }
+
+    instance_groups::set_memberships(
+        &updates
+            .iter()
+            .map(|update| {
+                (update.instance_id.clone(), update.group_ids.clone())
+            })
+            .collect::<Vec<_>>(),
+    );
+
+    let instance_ids = updates
+        .into_iter()
+        .map(|update| update.instance_id)
+        .collect::<Vec<_>>();
+    emit_instance_groups_changed(&instance_ids).await?;
+
+    Ok(())
+}
+
+pub async fn rename_group(
+    id: String,
+    new_name: String,
+) -> crate::Result<InstanceGroup> {
+    if id == FAVORITES_GROUP_ID {
+        return Err(crate::ErrorKind::InputError(
+            "Favorites cannot be renamed".to_string(),
+        )
+        .into());
+    }
+
+    let new_name = validate_group_name(&new_name)?;
+
+    let Some(instance_ids) = instance_groups::rename(&id, new_name) else {
+        return Err(crate::ErrorKind::InputError(format!(
+            "Unknown instance group {id}"
+        ))
+        .into());
+    };
+
+    emit_instance_groups_changed(&instance_ids).await?;
+
+    Ok(InstanceGroup {
+        id,
+        name: new_name.to_string(),
+    })
+}
+
+pub async fn delete_group(id: String) -> crate::Result<()> {
+    if id == FAVORITES_GROUP_ID {
+        return Err(crate::ErrorKind::InputError(
+            "Favorites cannot be deleted".to_string(),
+        )
+        .into());
+    }
+
+    let Some(instance_ids) = instance_groups::delete(&id) else {
+        return Err(crate::ErrorKind::InputError(format!(
+            "Unknown instance group {id}"
+        ))
+        .into());
+    };
+
+    emit_instance_groups_changed(&instance_ids).await?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        FAVORITES_GROUP_ID, InstanceGroupMembershipUpdate,
+        MAX_GROUP_NAME_LENGTH, normalize_membership_updates,
+        validate_group_name,
+    };
+
+    #[test]
+    fn group_name_validation_trims_valid_names() {
+        assert_eq!(validate_group_name("  My group  ").unwrap(), "My group");
+    }
+
+    #[test]
+    fn group_name_validation_rejects_empty_names() {
+        assert!(validate_group_name("   ").is_err());
+    }
+
+    #[test]
+    fn group_name_validation_rejects_reserved_name() {
+        assert!(validate_group_name("NoNe").is_err());
+    }
+
+    #[test]
+    fn group_name_validation_allows_favorites() {
+        assert_eq!(validate_group_name("Favorites").unwrap(), "Favorites");
+    }
+
+    #[test]
+    fn group_name_validation_rejects_long_names() {
+        assert!(
+            validate_group_name(&"a".repeat(MAX_GROUP_NAME_LENGTH + 1))
+                .is_err()
+        );
+    }
+
+    #[test]
+    fn favorites_group_id_is_stable() {
+        assert_eq!(FAVORITES_GROUP_ID, "group:favorites");
+    }
+
+    #[test]
+    fn membership_updates_reject_duplicate_instances() {
+        let updates = vec![
+            InstanceGroupMembershipUpdate {
+                instance_id: "instance".to_string(),
+                group_ids: vec!["first".to_string()],
+            },
+            InstanceGroupMembershipUpdate {
+                instance_id: "instance".to_string(),
+                group_ids: vec!["second".to_string()],
+            },
+        ];
+
+        assert!(normalize_membership_updates(updates).is_err());
+    }
+
+    #[test]
+    fn membership_updates_deduplicate_groups() {
+        let updates =
+            normalize_membership_updates(vec![InstanceGroupMembershipUpdate {
+                instance_id: "instance".to_string(),
+                group_ids: vec![
+                    "a".to_string(),
+                    "b".to_string(),
+                    "a".to_string(),
+                    "b".to_string(),
+                ],
+            }])
+            .unwrap();
+
+        assert_eq!(updates[0].group_ids, &["a", "b"]);
+    }
+}

packages/app-lib/src/api/instance/mod.rs

@@ -5,6 +5,7 @@ mod content;
 mod core_components;
 mod export_mrpack;
 mod get;
+mod groups;
 mod home;
 mod install;
 mod lifecycle;
@@ -72,6 +73,11 @@ pub use self::export_mrpack::{
     create_mrpack_json, export_mrpack, get_pack_export_candidates,
 };
 pub use self::get::{get, get_many, list};
+pub use self::groups::{
+    FAVORITES_GROUP_ID, InstanceGroup, InstanceGroupMembershipUpdate,
+    create_group, delete_group, list_groups, rename_group,
+    set_group_memberships, set_group_order,
+};
 pub use self::home::{
     get_daily_playtime, get_daily_playtime_details, set_pinned,
 };

packages/app-lib/src/event/emit.rs

@@ -6,8 +6,9 @@ use crate::event::{
 };
 #[cfg(feature = "tauri")]
 use crate::event::{
-    InstancePayload, JavaDiscoveryPayload, JavaDownloadConfirmationPayload,
-    LoadingPayload, ProcessPayload, ServerPayload, WarningPayload,
+    InstanceGroupsChangedPayload, InstancePayload, JavaDiscoveryPayload,
+    JavaDownloadConfirmationPayload, LoadingPayload, ProcessPayload,
+    ServerPayload, WarningPayload,
 };
 use futures::prelude::*;
 use serde_json::Value;
@@ -488,6 +489,26 @@ pub async fn emit_friend(payload: FriendPayload) -> crate::Result<()> {
     Ok(())
 }
 
+#[allow(unused_variables)]
+pub async fn emit_instance_groups_changed(
+    instance_ids: &[String],
+) -> crate::Result<()> {
+    #[cfg(feature = "tauri")]
+    {
+        let event_state = crate::EventState::get()?;
+        event_state
+            .app
+            .emit(
+                "instance_groups_changed",
+                InstanceGroupsChangedPayload {
+                    instance_ids: instance_ids.to_vec(),
+                },
+            )
+            .map_err(EventError::from)?;
+    }
+    Ok(())
+}
+
 #[allow(unused_variables)]
 pub async fn emit_notification(payload: Value) -> crate::Result<()> {
     #[cfg(feature = "tauri")]

packages/app-lib/src/event/mod.rs

@@ -395,6 +395,10 @@ pub enum ServerPayloadType {
         eula_text: String,
     },
 }
+#[derive(Serialize, Clone)]
+pub struct InstanceGroupsChangedPayload {
+    pub instance_ids: Vec<String>,
+}
 
 #[derive(Serialize, Clone)]
 #[cfg(feature = "tauri")]

packages/app-lib/src/state/instance_groups.rs

@@ -0,0 +1,613 @@
+//! Instance grouping backed by a standalone JSON file in the app's settings
+//! directory, next to `settings.json`.
+//!
+//! Groups used to live in SQLite (`instance_groups` /
+//! `instance_group_memberships`). That layout could not express membership for
+//! JSON-backed instances (`local:` ids, i.e. every `.minecraft` and
+//! multi-library instance) because they have no row in the `instances` table,
+//! and it duplicated membership into the per-instance sidecars. This module is
+//! the single source of truth instead; the SQL tables are left untouched but
+//! are no longer read or written (they are only read once, at import time).
+
+use crate::state::State;
+use serde::{Deserialize, Serialize};
+use std::collections::{HashMap, HashSet};
+use std::fs;
+use std::path::PathBuf;
+use std::sync::{OnceLock, RwLock};
+use tracing::{info, warn};
+
+pub const INSTANCE_GROUPS_FILE_NAME: &str = "instance_groups.json";
+
+/// Current `instance_groups.json` schema version.
+pub const INSTANCE_GROUPS_SCHEMA_VERSION: u32 = 1;
+
+pub const FAVORITES_GROUP_ID: &str = "group:favorites";
+const FAVORITES_GROUP_NAME: &str = "Pinned";
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct GroupDefinition {
+    pub id: String,
+    pub name: String,
+}
+
+/// On-disk shape. The order of `groups` *is* the display order, so no
+/// `display_order` field is needed: the public API only ever communicates
+/// ordering through the order of `list()` and `set_order()`.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct InstanceGroupsFile {
+    #[serde(default)]
+    pub schema_version: u32,
+    #[serde(default)]
+    pub groups: Vec<GroupDefinition>,
+    /// instance id -> group ids.
+    #[serde(default)]
+    pub memberships: HashMap<String, Vec<String>>,
+}
+
+impl Default for InstanceGroupsFile {
+    fn default() -> Self {
+        Self {
+            schema_version: INSTANCE_GROUPS_SCHEMA_VERSION,
+            groups: vec![GroupDefinition {
+                id: FAVORITES_GROUP_ID.to_string(),
+                name: FAVORITES_GROUP_NAME.to_string(),
+            }],
+            memberships: HashMap::new(),
+        }
+    }
+}
+
+impl InstanceGroupsFile {
+    fn has_group(&self, id: &str) -> bool {
+        self.groups.iter().any(|group| group.id == id)
+    }
+
+    /// Guarantees the favorites sentinel exists and sits first, drops
+    /// memberships pointing at groups that no longer exist, and drops instances
+    /// left with no groups at all.
+    fn normalize(&mut self) {
+        self.schema_version = INSTANCE_GROUPS_SCHEMA_VERSION;
+
+        match self.groups.iter().position(|g| g.id == FAVORITES_GROUP_ID) {
+            Some(0) => {}
+            Some(index) => {
+                let favorites = self.groups.remove(index);
+                self.groups.insert(0, favorites);
+            }
+            None => self.groups.insert(
+                0,
+                GroupDefinition {
+                    id: FAVORITES_GROUP_ID.to_string(),
+                    name: FAVORITES_GROUP_NAME.to_string(),
+                },
+            ),
+        }
+
+        let known = self
+            .groups
+            .iter()
+            .map(|group| group.id.clone())
+            .collect::<HashSet<_>>();
+
+        for group_ids in self.memberships.values_mut() {
+            let mut seen = HashSet::new();
+            group_ids
+                .retain(|id| known.contains(id) && seen.insert(id.clone()));
+        }
+        self.memberships
+            .retain(|_, group_ids| !group_ids.is_empty());
+    }
+}
+
+static STORE: OnceLock<RwLock<InstanceGroupsFile>> = OnceLock::new();
+
+fn file_path() -> Option<PathBuf> {
+    let state = State::get_if_initialized()?;
+    Some(
+        state
+            .directories
+            .settings_dir
+            .join(INSTANCE_GROUPS_FILE_NAME),
+    )
+}
+
+/// Reads the store from disk, or `None` when it has never been written.
+fn read_from_disk() -> Option<InstanceGroupsFile> {
+    let path = file_path()?;
+    if !path.exists() {
+        return None;
+    }
+    match fs::read_to_string(&path)
+        .map_err(|e| e.to_string())
+        .and_then(|content| {
+            serde_json::from_str::<InstanceGroupsFile>(&content)
+                .map_err(|e| e.to_string())
+        }) {
+        Ok(mut file) => {
+            file.normalize();
+            Some(file)
+        }
+        Err(error) => {
+            // A corrupt file must not wipe the user's groups silently on the
+            // next write, so bail out to an empty store without touching disk.
+            warn!("Failed to read {INSTANCE_GROUPS_FILE_NAME}: {error}");
+            None
+        }
+    }
+}
+
+fn write_to_disk(file: &InstanceGroupsFile) {
+    let Some(path) = file_path() else {
+        return;
+    };
+    let write = serde_json::to_string_pretty(file)
+        .map_err(|e| e.to_string())
+        .and_then(|content| {
+            fs::write(&path, content).map_err(|e| e.to_string())
+        });
+    if let Err(error) = write {
+        warn!("Failed to save {INSTANCE_GROUPS_FILE_NAME}: {error}");
+    }
+}
+
+fn store() -> &'static RwLock<InstanceGroupsFile> {
+    STORE.get_or_init(|| RwLock::new(read_from_disk().unwrap_or_default()))
+}
+
+fn with_read<T>(f: impl FnOnce(&InstanceGroupsFile) -> T) -> T {
+    let guard = store().read().unwrap_or_else(|e| e.into_inner());
+    f(&guard)
+}
+
+/// Mutates the store and persists the whole file. `f` returns the instance ids
+/// whose membership changed, so callers can emit the change event.
+fn with_write<T>(f: impl FnOnce(&mut InstanceGroupsFile) -> T) -> T {
+    let mut guard = store().write().unwrap_or_else(|e| e.into_inner());
+    let result = f(&mut guard);
+    guard.normalize();
+    write_to_disk(&guard);
+    result
+}
+
+// ── Reads ───────────────────────────────────────────────────────────────────
+
+pub fn list() -> Vec<GroupDefinition> {
+    with_read(|file| file.groups.clone())
+}
+
+pub fn group_exists(id: &str) -> bool {
+    with_read(|file| file.has_group(id))
+}
+
+/// Group ids for one instance, in the order they were assigned. Synchronous so
+/// that `instance_metadata_from_instance` can call it.
+pub fn group_ids_for(instance_id: &str) -> Vec<String> {
+    with_read(|file| {
+        file.memberships
+            .get(instance_id)
+            .cloned()
+            .unwrap_or_default()
+    })
+}
+
+fn instances_in_group(
+    file: &InstanceGroupsFile,
+    group_id: &str,
+) -> Vec<String> {
+    file.memberships
+        .iter()
+        .filter(|(_, group_ids)| group_ids.iter().any(|id| id == group_id))
+        .map(|(instance_id, _)| instance_id.clone())
+        .collect()
+}
+
+// ── Writes ──────────────────────────────────────────────────────────────────
+
+/// Adds a group at the top of the list, matching the previous SQL behavior
+/// where new groups got the lowest `display_order`. Favorites stays first.
+pub fn create(id: &str, name: &str) {
+    with_write(|file| {
+        let definition = GroupDefinition {
+            id: id.to_string(),
+            name: name.to_string(),
+        };
+        // `normalize` moves favorites back to index 0 afterwards.
+        file.groups.insert(0, definition);
+    });
+}
+
+/// Renames a group, returning the affected instance ids, or `None` when the
+/// group does not exist.
+pub fn rename(id: &str, name: &str) -> Option<Vec<String>> {
+    with_write(|file| {
+        let group = file.groups.iter_mut().find(|group| group.id == id)?;
+        group.name = name.to_string();
+        Some(instances_in_group(file, id))
+    })
+}
+
+/// Deletes a group and strips it from every instance, returning the affected
+/// instance ids, or `None` when the group does not exist.
+pub fn delete(id: &str) -> Option<Vec<String>> {
+    with_write(|file| {
+        let index = file.groups.iter().position(|group| group.id == id)?;
+        let affected = instances_in_group(file, id);
+        file.groups.remove(index);
+        // `normalize` prunes the now-dangling ids out of `memberships`.
+        Some(affected)
+    })
+}
+
+/// Reorders groups to match `group_ids`. Groups missing from the argument keep
+/// their relative order at the end, so a stale frontend list can never drop a
+/// group. Favorites is pinned first regardless.
+pub fn set_order(group_ids: &[String]) {
+    with_write(|file| reorder_groups(&mut file.groups, group_ids));
+}
+
+/// Reorders `groups` to match `group_ids`. Groups the argument omits keep their
+/// relative order after the listed ones, so a stale frontend list can never drop
+/// a group. Pure so the ordering rules can be tested without the process-wide
+/// store, which tests would otherwise race over.
+fn reorder_groups(groups: &mut Vec<GroupDefinition>, group_ids: &[String]) {
+    let mut remaining = std::mem::take(groups);
+    let mut ordered = Vec::with_capacity(remaining.len());
+    for id in group_ids {
+        if id == FAVORITES_GROUP_ID {
+            continue;
+        }
+        if let Some(index) = remaining.iter().position(|group| &group.id == id)
+        {
+            ordered.push(remaining.remove(index));
+        }
+    }
+    ordered.extend(remaining);
+    *groups = ordered;
+}
+
+/// Replaces the group list of each given instance wholesale.
+pub fn set_memberships(updates: &[(String, Vec<String>)]) {
+    with_write(|file| {
+        for (instance_id, group_ids) in updates {
+            if group_ids.is_empty() {
+                file.memberships.remove(instance_id);
+            } else {
+                file.memberships
+                    .insert(instance_id.clone(), group_ids.clone());
+            }
+        }
+    });
+}
+
+/// Replaces the group list of a single instance.
+pub fn set_instance_groups(instance_id: &str, group_ids: &[String]) {
+    set_memberships(&[(instance_id.to_string(), group_ids.to_vec())]);
+}
+
+/// Looks a group up by name, creating it if absent, and returns its id.
+/// Used by the legacy launcher import, which only knows group names.
+pub fn find_or_create_by_name(name: &str) -> String {
+    with_write(|file| {
+        if let Some(group) = file.groups.iter().find(|group| group.name == name)
+        {
+            return group.id.clone();
+        }
+        let id = uuid::Uuid::new_v4().to_string();
+        file.groups.push(GroupDefinition {
+            id: id.clone(),
+            name: name.to_string(),
+        });
+        id
+    })
+}
+
+/// Adds one group to an instance, keeping its existing groups.
+pub fn add_instance_to_group(instance_id: &str, group_id: &str) {
+    with_write(|file| {
+        let entry =
+            file.memberships.entry(instance_id.to_string()).or_default();
+        if !entry.iter().any(|id| id == group_id) {
+            entry.push(group_id.to_string());
+        }
+    });
+}
+
+/// Drops an instance's membership entry, e.g. after the instance is deleted.
+pub fn forget_instance(instance_id: &str) {
+    with_write(|file| {
+        file.memberships.remove(instance_id);
+    });
+}
+
+/// Re-keys an instance's membership, e.g. when a `local:` id changes because the
+/// instance directory moved.
+pub fn rename_instance(old_id: &str, new_id: &str) {
+    if old_id == new_id {
+        return;
+    }
+    with_write(|file| {
+        if let Some(group_ids) = file.memberships.remove(old_id) {
+            file.memberships.insert(new_id.to_string(), group_ids);
+        }
+    });
+}
+
+// ── One-time import ─────────────────────────────────────────────────────────
+
+async fn import_sql_groups(
+    pool: &sqlx::SqlitePool,
+) -> crate::Result<InstanceGroupsFile> {
+    let columns: Vec<String> = sqlx::query_scalar(
+        "SELECT name FROM pragma_table_info('instance_groups')",
+    )
+    .fetch_all(pool)
+    .await?;
+    let has_column = |name: &str| columns.iter().any(|column| column == name);
+
+    let mut file = InstanceGroupsFile {
+        schema_version: INSTANCE_GROUPS_SCHEMA_VERSION,
+        groups: Vec::new(),
+        memberships: HashMap::new(),
+    };
+
+    if has_column("id") && has_column("name") {
+        let rows = sqlx::query_as::<_, (String, String)>(
+            "SELECT id, name FROM instance_groups ORDER BY display_order, name, id",
+        )
+        .fetch_all(pool)
+        .await?;
+        for (id, name) in rows {
+            file.groups.push(GroupDefinition { id, name });
+        }
+
+        let has_memberships: bool = sqlx::query_scalar(
+            "SELECT EXISTS(
+                SELECT 1 FROM sqlite_master
+                WHERE type = 'table' AND name = 'instance_group_memberships'
+            )",
+        )
+        .fetch_one(pool)
+        .await?;
+        if has_memberships {
+            let memberships = sqlx::query_as::<_, (String, String)>(
+                "SELECT instance_id, group_id FROM instance_group_memberships",
+            )
+            .fetch_all(pool)
+            .await?;
+            for (instance_id, group_id) in memberships {
+                file.memberships
+                    .entry(instance_id)
+                    .or_default()
+                    .push(group_id);
+            }
+        }
+    } else if has_column("instance_id") && has_column("group_name") {
+        let rows = sqlx::query_as::<_, (String, String)>(
+            "SELECT instance_id, group_name
+             FROM instance_groups
+             ORDER BY group_name, instance_id",
+        )
+        .fetch_all(pool)
+        .await?;
+        let mut group_ids = HashMap::<String, String>::new();
+        for (instance_id, group_name) in rows {
+            let group_id = group_ids
+                .entry(group_name.clone())
+                .or_insert_with(|| uuid::Uuid::new_v4().to_string())
+                .clone();
+            file.memberships
+                .entry(instance_id)
+                .or_default()
+                .push(group_id.clone());
+            if !file.groups.iter().any(|group| group.id == group_id) {
+                file.groups.push(GroupDefinition {
+                    id: group_id,
+                    name: group_name,
+                });
+            }
+        }
+    } else if !columns.is_empty() {
+        warn!(
+            columns = ?columns,
+            "Skipping instance group import from an unrecognized SQLite schema"
+        );
+    }
+
+    file.normalize();
+    Ok(file)
+}
+
+/// Creates `instance_groups.json` from the pre-existing SQLite tables and
+/// instance sidecars, the first time the app runs after this change.
+///
+/// The SQL access here is read-only and happens exactly once; afterwards the
+/// tables are never touched again (they are kept as-is so no DB migration is
+/// needed).
+pub async fn ensure_imported(state: &State) -> crate::Result<()> {
+    let Some(path) = file_path() else {
+        return Ok(());
+    };
+    if path.exists() {
+        // Populate the in-memory cache eagerly so the first synchronous read
+        // does not race with a write.
+        let _ = list();
+        return Ok(());
+    }
+
+    let file = import_sql_groups(&state.pool).await?;
+    let group_count = file.groups.len();
+    let instance_count = file.memberships.len();
+
+    // Seed the cache with the imported data instead of letting `store()` read
+    // the file we are about to write.
+    {
+        let lock = store();
+        let mut guard = lock.write().unwrap_or_else(|e| e.into_inner());
+        *guard = file;
+        write_to_disk(&guard);
+    }
+
+    info!(
+        "Imported {group_count} instance groups covering {instance_count} instances into {INSTANCE_GROUPS_FILE_NAME}"
+    );
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use sqlx::sqlite::SqlitePoolOptions;
+
+    fn file_with_groups(ids: &[&str]) -> InstanceGroupsFile {
+        InstanceGroupsFile {
+            schema_version: INSTANCE_GROUPS_SCHEMA_VERSION,
+            groups: ids
+                .iter()
+                .map(|id| GroupDefinition {
+                    id: id.to_string(),
+                    name: id.to_string(),
+                })
+                .collect(),
+            memberships: HashMap::new(),
+        }
+    }
+
+    #[test]
+    fn normalize_inserts_favorites_first() {
+        let mut file = file_with_groups(&["a", "b"]);
+        file.normalize();
+        assert_eq!(file.groups[0].id, FAVORITES_GROUP_ID);
+        assert_eq!(file.groups.len(), 3);
+    }
+
+    #[test]
+    fn normalize_moves_favorites_to_front() {
+        let mut file = file_with_groups(&["a", FAVORITES_GROUP_ID, "b"]);
+        file.normalize();
+        assert_eq!(file.groups[0].id, FAVORITES_GROUP_ID);
+        assert_eq!(file.groups[1].id, "a");
+        assert_eq!(file.groups[2].id, "b");
+    }
+
+    #[test]
+    fn normalize_drops_orphan_memberships() {
+        let mut file = file_with_groups(&["a"]);
+        file.memberships.insert(
+            "instance".to_string(),
+            vec!["a".to_string(), "nonexistent".to_string()],
+        );
+
+        file.normalize();
+        assert_eq!(file.memberships["instance"], &["a"]);
+    }
+
+    #[test]
+    fn normalize_drops_memberships_for_nonexistent_instances() {
+        let mut file = file_with_groups(&["a"]);
+        file.memberships.insert(
+            "instance".to_string(),
+            vec!["nonexistent1".to_string(), "nonexistent2".to_string()],
+        );
+        file.normalize();
+        assert!(!file.memberships.contains_key("instance"));
+    }
+
+    fn group_ids(groups: &[GroupDefinition]) -> Vec<String> {
+        groups.iter().map(|group| group.id.clone()).collect()
+    }
+
+    #[test]
+    fn set_order_ignores_unknown_ids() {
+        let mut groups = file_with_groups(&["a", "b", "c"]).groups;
+
+        reorder_groups(&mut groups, &["unknown".to_string(), "c".to_string()]);
+
+        // The unknown id matches nothing and simply contributes no group.
+        assert_eq!(group_ids(&groups), vec!["c", "a", "b"]);
+    }
+
+    #[test]
+    fn set_order_retains_missing_groups_at_end() {
+        let mut groups = file_with_groups(&["a", "b", "c"]).groups;
+        groups.push(GroupDefinition {
+            id: "extra".to_string(),
+            name: "extra".to_string(),
+        });
+
+        reorder_groups(&mut groups, &["b".to_string()]);
+
+        // `b` moves to the front and every group the argument omitted survives
+        // after it, so a stale list can never drop a group. Favorites is pinned
+        // by `normalize`, which the store applies around this call.
+        assert_eq!(group_ids(&groups), vec!["b", "a", "c", "extra"]);
+    }
+
+    #[test]
+    fn set_order_keeps_favorites_out_of_the_reorder() {
+        let mut groups = file_with_groups(&["a", FAVORITES_GROUP_ID]).groups;
+
+        reorder_groups(&mut groups, &[FAVORITES_GROUP_ID.to_string()]);
+
+        // Favorites is skipped explicitly and survives at its previous position;
+        // `normalize` moves it to the front afterwards.
+        assert_eq!(group_ids(&groups), vec!["a", FAVORITES_GROUP_ID]);
+    }
+
+    #[test]
+    fn normalize_does_not_lose_favorites_membership() {
+        let mut file = file_with_groups(&[]);
+        file.memberships.insert(
+            "my_instance".to_string(),
+            vec![FAVORITES_GROUP_ID.to_string()],
+        );
+        file.normalize();
+        assert_eq!(file.memberships["my_instance"], &[FAVORITES_GROUP_ID]);
+    }
+
+    #[test]
+    fn normalize_deduplicates_group_ids() {
+        let mut file = file_with_groups(&["a", "b"]);
+        file.memberships.insert(
+            "instance".to_string(),
+            vec!["a".to_string(), "a".to_string(), "b".to_string()],
+        );
+        file.normalize();
+        assert_eq!(file.memberships["instance"].len(), 2);
+    }
+
+    #[tokio::test]
+    async fn imports_legacy_instance_group_schema() {
+        let pool = SqlitePoolOptions::new()
+            .connect("sqlite::memory:")
+            .await
+            .unwrap();
+        sqlx::query(
+            "CREATE TABLE instance_groups (
+                instance_id TEXT NOT NULL,
+                group_name TEXT NOT NULL,
+                PRIMARY KEY (instance_id, group_name)
+            )",
+        )
+        .execute(&pool)
+        .await
+        .unwrap();
+        sqlx::query(
+            "INSERT INTO instance_groups (instance_id, group_name)
+             VALUES ('instance-1', 'Survival'), ('instance-2', 'Survival'),
+                    ('instance-1', 'Creative')",
+        )
+        .execute(&pool)
+        .await
+        .unwrap();
+
+        let file = import_sql_groups(&pool).await.unwrap();
+
+        assert_eq!(file.groups.len(), 3);
+        assert_eq!(file.groups[0].id, FAVORITES_GROUP_ID);
+        assert_eq!(file.memberships["instance-1"].len(), 2);
+        assert_eq!(file.memberships["instance-2"].len(), 1);
+        assert!(file.groups.iter().any(|group| group.name == "Survival"));
+    }
+}

packages/app-lib/src/state/instances/commands/get_instance.rs

@@ -1,3 +1,4 @@
+use crate::state::instance_groups;
 use crate::state::instances::{
     ContentSet, Instance, InstanceLaunchOverrides, InstanceLink,
     LoaderComponent,
@@ -91,11 +92,12 @@ impl InstanceMetadata {
         record: instance_rows::InstanceMetadataRecord,
         loader_components: Vec<LoaderComponent>,
     ) -> Self {
+        let groups = instance_groups::group_ids_for(&record.instance.id);
         Self {
             instance: record.instance,
             applied_content_set: record.applied_content_set,
             link: record.link,
-            groups: record.groups,
+            groups,
             launch_overrides: record.launch_overrides,
             loader_components,
             synced_options: Default::default(),

packages/app-lib/src/state/mod.rs

@@ -26,6 +26,7 @@ pub use self::instance_types::*;
 pub(crate) mod instances;
 pub use self::instances::*;
 
+pub(crate) mod instance_groups;
 mod settings;
 pub use self::settings::*;
 
@@ -487,6 +488,10 @@ impl State {
             .get_or_try_init(move || Self::initialize_state(app_identifier))
             .await?;
 
+        if let Err(e) = instance_groups::ensure_imported(state).await {
+            tracing::error!("Error importing legacy instance groups: {e}");
+        }
+
         if let Err(e) =
             crate::install::recovery::recover_interrupted_jobs(state).await
         {