fix: keep mobile board widgets unchanged

packages/api/src/router/board.ts

@@ -49,6 +49,7 @@ import {
   boardDuplicateSchema,
   boardRenameSchema,
   boardSaveLayoutSchema,
+  boardSaveLayoutsSchema,
   boardSavePartialSettingsSchema,
   boardSavePermissionsSchema,
   boardSaveSchema,
@@ -687,7 +688,7 @@ export const boardRouter = createTRPCRouter({
       mcp: {
         enabled: true,
         description:
-          "Set a board's desktop column count and remove legacy responsive layouts. Requires modify permission. REQUIRED: id (board ID), columnCount (1-24)",
+          "Set a board's desktop column count while preserving saved responsive layouts. Requires modify permission. REQUIRED: id (board ID), columnCount (1-24)",
       },
     })
     .input(boardSaveLayoutSchema)
@@ -761,12 +762,8 @@ export const boardRouter = createTRPCRouter({
 
             await transaction
               .update(schema.layouts)
-              .set({ name: "Base", columnCount: input.columnCount, breakpoint: 0 })
+              .set({ columnCount: input.columnCount })
               .where(eq(schema.layouts.id, desktopLayout.id));
-
-            await transaction
-              .delete(schema.layouts)
-              .where(and(eq(schema.layouts.boardId, board.id), not(eq(schema.layouts.id, desktopLayout.id))));
           });
         },
         handleSync(db) {
@@ -811,18 +808,230 @@ export const boardRouter = createTRPCRouter({
 
             transaction
               .update(layouts)
-              .set({ name: "Base", columnCount: input.columnCount, breakpoint: 0 })
+              .set({ columnCount: input.columnCount })
               .where(eq(layouts.id, desktopLayout.id))
               .run();
-
-            transaction
-              .delete(layouts)
-              .where(and(eq(layouts.boardId, board.id), not(eq(layouts.id, desktopLayout.id))))
-              .run();
           });
         },
       });
     }),
+  saveLayouts: protectedProcedure
+    .input(boardSaveLayoutsSchema)
+    .output(boardSaveLayoutsSchema.shape.layouts)
+    .mutation(async ({ ctx, input }) => {
+      await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "modify");
+
+      const board = await getFullBoardWithWhereAsync(ctx.db, eq(boards.id, input.id), ctx.session.user.id);
+      const addedLayouts = filterAddedItems(input.layouts, board.layouts);
+      const layoutsToInsert: InferInsertModel<typeof layouts>[] = [];
+      const itemSectionLayoutsToInsert: InferInsertModel<typeof itemLayouts>[] = [];
+      const sectionLayoutsToInsert: InferInsertModel<typeof sectionLayouts>[] = [];
+      const savedLayoutIds = new Map<string, string>();
+
+      for (const addedLayout of addedLayouts) {
+        const layoutId = createId();
+        savedLayoutIds.set(addedLayout.id, layoutId);
+
+        layoutsToInsert.push({
+          id: layoutId,
+          name: addedLayout.name,
+          columnCount: addedLayout.columnCount,
+          breakpoint: addedLayout.breakpoint,
+          boardId: board.id,
+        });
+
+        const sortedLayouts = board.layouts.toSorted((layoutA, layoutB) => layoutA.columnCount - layoutB.columnCount);
+        const layoutToClone =
+          sortedLayouts.find((layout) => layout.columnCount >= addedLayout.columnCount) ?? sortedLayouts.at(-1);
+
+        if (!layoutToClone) {
+          throw new TRPCError({ code: "INTERNAL_SERVER_ERROR", message: "Board must have a layout" });
+        }
+
+        const updatedBoardLayout = getUpdatedBoardLayout(board, {
+          previous: {
+            layoutId: layoutToClone.id,
+            columnCount: layoutToClone.columnCount,
+          },
+          current: {
+            layoutId,
+            columnCount: addedLayout.columnCount,
+          },
+        });
+
+        itemSectionLayoutsToInsert.push(...updatedBoardLayout.itemSectionLayouts);
+        sectionLayoutsToInsert.push(...updatedBoardLayout.sectionLayouts);
+      }
+
+      const updatedLayouts = filterUpdatedItems(input.layouts, board.layouts);
+      const itemSectionLayoutsToUpdate: InferInsertModel<typeof itemLayouts>[] = [];
+      const sectionLayoutsToUpdate: InferInsertModel<typeof sectionLayouts>[] = [];
+      const layoutsToUpdate: typeof input.layouts = [];
+
+      for (const updatedLayout of updatedLayouts) {
+        const dbLayout = board.layouts.find((layout) => layout.id === updatedLayout.id);
+        if (!dbLayout) continue;
+
+        if (dbLayout.columnCount !== updatedLayout.columnCount) {
+          const updatedBoardLayout = getUpdatedBoardLayout(board, {
+            previous: {
+              layoutId: dbLayout.id,
+              columnCount: dbLayout.columnCount,
+            },
+            current: {
+              layoutId: dbLayout.id,
+              columnCount: updatedLayout.columnCount,
+            },
+          });
+
+          itemSectionLayoutsToUpdate.push(...updatedBoardLayout.itemSectionLayouts);
+          sectionLayoutsToUpdate.push(...updatedBoardLayout.sectionLayouts);
+        }
+
+        layoutsToUpdate.push(updatedLayout);
+      }
+
+      const removedLayoutIds = filterRemovedItems(input.layouts, board.layouts).map((layout) => layout.id);
+
+      await handleTransactionsAsync(ctx.db, {
+        async handleAsync(db, schema) {
+          await db.transaction(async (transaction) => {
+            if (layoutsToInsert.length > 0) {
+              await transaction.insert(schema.layouts).values(layoutsToInsert);
+            }
+            if (itemSectionLayoutsToInsert.length > 0) {
+              await transaction.insert(schema.itemLayouts).values(itemSectionLayoutsToInsert);
+            }
+            if (sectionLayoutsToInsert.length > 0) {
+              await transaction.insert(schema.sectionLayouts).values(sectionLayoutsToInsert);
+            }
+
+            for (const itemSectionLayout of itemSectionLayoutsToUpdate) {
+              await transaction
+                .update(schema.itemLayouts)
+                .set({
+                  height: itemSectionLayout.height,
+                  width: itemSectionLayout.width,
+                  xOffset: itemSectionLayout.xOffset,
+                  yOffset: itemSectionLayout.yOffset,
+                  sectionId: itemSectionLayout.sectionId,
+                })
+                .where(
+                  and(
+                    eq(schema.itemLayouts.itemId, itemSectionLayout.itemId),
+                    eq(schema.itemLayouts.layoutId, itemSectionLayout.layoutId),
+                  ),
+                );
+            }
+
+            for (const sectionLayout of sectionLayoutsToUpdate) {
+              await transaction
+                .update(schema.sectionLayouts)
+                .set({
+                  height: sectionLayout.height,
+                  width: sectionLayout.width,
+                  xOffset: sectionLayout.xOffset,
+                  yOffset: sectionLayout.yOffset,
+                  parentSectionId: sectionLayout.parentSectionId,
+                })
+                .where(
+                  and(
+                    eq(schema.sectionLayouts.sectionId, sectionLayout.sectionId),
+                    eq(schema.sectionLayouts.layoutId, sectionLayout.layoutId),
+                  ),
+                );
+            }
+
+            for (const layout of layoutsToUpdate) {
+              await transaction
+                .update(schema.layouts)
+                .set({
+                  name: layout.name,
+                  columnCount: layout.columnCount,
+                  breakpoint: layout.breakpoint,
+                })
+                .where(eq(schema.layouts.id, layout.id));
+            }
+
+            if (removedLayoutIds.length > 0) {
+              await transaction.delete(schema.layouts).where(inArray(schema.layouts.id, removedLayoutIds));
+            }
+          });
+        },
+        handleSync(db) {
+          db.transaction((transaction) => {
+            if (layoutsToInsert.length > 0) {
+              transaction.insert(layouts).values(layoutsToInsert).run();
+            }
+            if (itemSectionLayoutsToInsert.length > 0) {
+              transaction.insert(itemLayouts).values(itemSectionLayoutsToInsert).run();
+            }
+            if (sectionLayoutsToInsert.length > 0) {
+              transaction.insert(sectionLayouts).values(sectionLayoutsToInsert).run();
+            }
+
+            for (const itemSectionLayout of itemSectionLayoutsToUpdate) {
+              transaction
+                .update(itemLayouts)
+                .set({
+                  height: itemSectionLayout.height,
+                  width: itemSectionLayout.width,
+                  xOffset: itemSectionLayout.xOffset,
+                  yOffset: itemSectionLayout.yOffset,
+                  sectionId: itemSectionLayout.sectionId,
+                })
+                .where(
+                  and(
+                    eq(itemLayouts.itemId, itemSectionLayout.itemId),
+                    eq(itemLayouts.layoutId, itemSectionLayout.layoutId),
+                  ),
+                )
+                .run();
+            }
+
+            for (const sectionLayout of sectionLayoutsToUpdate) {
+              transaction
+                .update(sectionLayouts)
+                .set({
+                  height: sectionLayout.height,
+                  width: sectionLayout.width,
+                  xOffset: sectionLayout.xOffset,
+                  yOffset: sectionLayout.yOffset,
+                  parentSectionId: sectionLayout.parentSectionId,
+                })
+                .where(
+                  and(
+                    eq(sectionLayouts.sectionId, sectionLayout.sectionId),
+                    eq(sectionLayouts.layoutId, sectionLayout.layoutId),
+                  ),
+                )
+                .run();
+            }
+
+            for (const layout of layoutsToUpdate) {
+              transaction
+                .update(layouts)
+                .set({
+                  name: layout.name,
+                  columnCount: layout.columnCount,
+                  breakpoint: layout.breakpoint,
+                })
+                .where(eq(layouts.id, layout.id))
+                .run();
+            }
+
+            if (removedLayoutIds.length > 0) {
+              transaction.delete(layouts).where(inArray(layouts.id, removedLayoutIds)).run();
+            }
+          });
+        },
+      });
+
+      return input.layouts.map((layout) => ({
+        ...layout,
+        id: savedLayoutIds.get(layout.id) ?? layout.id,
+      }));
+    }),
   savePartialBoardSettings: protectedProcedure
     .meta({
       openapi: { method: "PATCH", path: "/api/boards/{id}/settings", tags: ["boards"], protect: true },
@@ -1491,16 +1700,16 @@ export const boardRouter = createTRPCRouter({
       }
 
       const itemId = createId();
-
-      await ctx.db.insert(items).values({
+      const itemRow = {
         id: itemId,
         boardId: input.boardId,
         kind: input.kind,
         options: superjson.stringify(input.options),
         advancedOptions: emptySuperJSON,
-      });
+      };
 
       const layoutRows: (typeof itemLayouts.$inferInsert)[] = [];
+      const defaultSize = widgetDefaultSizes[input.kind as WidgetKind] ?? { width: 1, height: 1 };
 
       for (const layout of board.layouts) {
         const existingInSection = board.items
@@ -1519,14 +1728,17 @@ export const boardRouter = createTRPCRouter({
           }
         }
 
-        const defaultSize = widgetDefaultSizes[input.kind as WidgetKind] ?? { width: 1, height: 1 };
+        const layoutItemSize = {
+          ...defaultSize,
+          width: Math.min(defaultSize.width, layout.columnCount),
+        };
 
         const fitsAt = (x: number, y: number) => {
-          if (x + defaultSize.width > layout.columnCount) return false;
-          for (let dy = 0; dy < defaultSize.height; dy++) {
+          if (x + layoutItemSize.width > layout.columnCount) return false;
+          for (let dy = 0; dy < layoutItemSize.height; dy++) {
             const row = occupied[y + dy];
             if (!row) continue;
-            for (let dx = 0; dx < defaultSize.width; dx++) {
+            for (let dx = 0; dx < layoutItemSize.width; dx++) {
               if (row[x + dx]) return false;
             }
           }
@@ -1544,8 +1756,8 @@ export const boardRouter = createTRPCRouter({
                 layoutId: layout.id,
                 xOffset: x,
                 yOffset: y,
-                width: defaultSize.width,
-                height: defaultSize.height,
+                width: layoutItemSize.width,
+                height: layoutItemSize.height,
               });
               placed = true;
             }
@@ -1560,15 +1772,32 @@ export const boardRouter = createTRPCRouter({
         }
       }
 
-      if (layoutRows.length > 0) {
-        await ctx.db.insert(itemLayouts).values(layoutRows);
-      }
+      const integrationRows = input.integrationIds.map((integrationId) => ({ itemId, integrationId }));
 
-      if (input.integrationIds.length > 0) {
-        await ctx.db
-          .insert(integrationItems)
-          .values(input.integrationIds.map((integrationId) => ({ itemId, integrationId })));
-      }
+      await handleTransactionsAsync(ctx.db, {
+        async handleAsync(db, schema) {
+          await db.transaction(async (transaction) => {
+            await transaction.insert(schema.items).values(itemRow);
+            if (layoutRows.length > 0) {
+              await transaction.insert(schema.itemLayouts).values(layoutRows);
+            }
+            if (integrationRows.length > 0) {
+              await transaction.insert(schema.integrationItems).values(integrationRows);
+            }
+          });
+        },
+        handleSync(db) {
+          db.transaction((transaction) => {
+            transaction.insert(items).values(itemRow).run();
+            if (layoutRows.length > 0) {
+              transaction.insert(itemLayouts).values(layoutRows).run();
+            }
+            if (integrationRows.length > 0) {
+              transaction.insert(integrationItems).values(integrationRows).run();
+            }
+          });
+        },
+      });
 
       return { itemId };
     }),
@@ -1592,6 +1821,9 @@ const getHomeIdBoardAsync = async (
   user: InferSelectModel<typeof users> | null,
   deviceType: DeviceType,
 ) => {
+  // Mobile home-board selection remains device-based because the server does
+  // not know the resolved CSS viewport. Tablet rendering is resolved against
+  // 48em on the client and must not be guessed here.
   const settingKey = deviceType === "mobile" ? "mobileHomeBoardId" : "homeBoardId";
 
   if (!user) {
@@ -1613,8 +1845,7 @@ const getHomeIdBoardAsync = async (
       and(
         eq(groupMembers.userId, user.id),
         not(eq(groups.name, everyoneGroup)),
-        not(isNull(groups[settingKey])),
-        not(isNull(groups.homeBoardId)),
+        or(not(isNull(groups[settingKey])), not(isNull(groups.homeBoardId))),
       ),
     )
     .orderBy(asc(groups.position))

packages/api/src/router/serverSettings.ts

@@ -5,10 +5,10 @@ import { and, eq, inArray } from "@homarr/db";
 import {
   getServerSettingByKeyAsync,
   getServerSettingsAsync,
-  insertServerSettingByKeyAsync,
+  mergeServerSettingByKeyAsync,
   updateServerSettingByKeyAsync,
 } from "@homarr/db/queries";
-import { boards, serverSettings } from "@homarr/db/schema";
+import { boards } from "@homarr/db/schema";
 import type { ServerSettings } from "@homarr/server-settings";
 import { defaultServerSettingsKeys } from "@homarr/server-settings";
 import { settingsInitSchema } from "@homarr/validation/settings";
@@ -19,6 +19,7 @@ import { nextOnboardingStepAsync } from "./onboard/onboard-queries";
 const boardServerSettingsSchema = z.object({
   homeBoardId: z.string().nullable(),
   mobileHomeBoardId: z.string().nullable(),
+  enableAutomaticMobileLayout: z.boolean(),
   enableStatusByDefault: z.boolean(),
   forceDisableStatus: z.boolean(),
 }) satisfies z.ZodType<ServerSettings["board"]>;
@@ -39,7 +40,7 @@ export const serverSettingsRouter = createTRPCRouter({
       mcp: {
         enabled: true,
         description:
-          "Get global board defaults, including desktop/mobile home board IDs and status behavior. Requires admin permission",
+          "Get global board defaults, including desktop/mobile home board IDs, automatic mobile layout mode, and status behavior. Requires admin permission",
       },
     })
     .input(z.void())
@@ -54,7 +55,7 @@ export const serverSettingsRouter = createTRPCRouter({
       mcp: {
         enabled: true,
         description:
-          "Update global board defaults. Requires admin permission. Optional fields: homeBoardId, mobileHomeBoardId, enableStatusByDefault, forceDisableStatus. Home board IDs must reference public boards or be null",
+          "Update global board defaults. Requires admin permission. Optional fields: homeBoardId, mobileHomeBoardId, enableAutomaticMobileLayout, enableStatusByDefault, forceDisableStatus. Home board IDs must reference public boards or be null",
       },
     })
     .input(boardServerSettingsUpdateSchema)
@@ -81,17 +82,9 @@ export const serverSettingsRouter = createTRPCRouter({
 
       const current = await getServerSettingByKeyAsync(ctx.db, "board");
       const next = { ...current, ...input };
-      const existing = await ctx.db.query.serverSettings.findFirst({
-        where: eq(serverSettings.settingKey, "board"),
-      });
+      await mergeServerSettingByKeyAsync(ctx.db, "board", next, input);
 
-      if (existing) {
-        await updateServerSettingByKeyAsync(ctx.db, "board", next);
-      } else {
-        await insertServerSettingByKeyAsync(ctx.db, "board", next);
-      }
-
-      return next;
+      return await getServerSettingByKeyAsync(ctx.db, "board");
     }),
   saveSettings: permissionRequiredProcedure
     .requiresPermission("admin")
@@ -103,10 +96,11 @@ export const serverSettingsRouter = createTRPCRouter({
     )
     .mutation(async ({ ctx, input }) => {
       const current = await getServerSettingByKeyAsync(ctx.db, input.settingsKey);
-      await updateServerSettingByKeyAsync(ctx.db, input.settingsKey, {
+      const next = {
         ...current,
         ...input.value,
-      } as ServerSettings[keyof ServerSettings]);
+      } as ServerSettings[keyof ServerSettings];
+      await mergeServerSettingByKeyAsync(ctx.db, input.settingsKey, next, input.value);
     }),
   initSettings: onboardingProcedure
     .requiresStep("settings")

packages/api/src/router/test/board.spec.ts

@@ -4,7 +4,7 @@ import { describe, expect, it, test, vi } from "vitest";
 import type { Session } from "@homarr/auth";
 import { createId } from "@homarr/common";
 import type { Database, InferInsertModel } from "@homarr/db";
-import { and, eq } from "@homarr/db";
+import { and, eq, not } from "@homarr/db";
 import {
   boardGroupPermissions,
   boards,
@@ -516,6 +516,64 @@ describe("getHomeBoard should return home board", () => {
     });
     expect(spy).toHaveBeenCalledWith(expect.anything(), expect.anything(), "view");
   });
+  test.each([
+    { deviceType: "mobile", expectedBoard: "mobile-home" },
+    { deviceType: "tablet", expectedBoard: "desktop-home" },
+  ] as const)(
+    "should use the $expectedBoard preference for a $deviceType device",
+    async ({ deviceType, expectedBoard }) => {
+      // Arrange
+      const db = createDb();
+      const caller = boardRouter.createCaller({ db, deviceType, session: defaultSession });
+
+      const mobileBoardProps = await createFullBoardAsync(db, "mobile-home");
+      const desktopBoardProps = await createFullBoardAsync(db, "desktop-home");
+      await db
+        .update(users)
+        .set({
+          homeBoardId: desktopBoardProps.boardId,
+          mobileHomeBoardId: mobileBoardProps.boardId,
+        })
+        .where(eq(users.id, defaultCreatorId));
+
+      // Act
+      const result = await caller.getHomeBoard();
+
+      // Assert
+      expectInputToBeFullBoardWithName(result, {
+        ...(expectedBoard === "mobile-home" ? mobileBoardProps : desktopBoardProps),
+        name: expectedBoard,
+      });
+    },
+  );
+  test("should return a mobile-only group home board", async () => {
+    // Arrange
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: "mobile", session: defaultSession });
+
+    const mobileBoardProps = await createFullBoardAsync(db, "group-mobile-home");
+    const groupId = createId();
+    await db.insert(groups).values({
+      id: groupId,
+      name: "mobile group",
+      position: 1,
+      homeBoardId: null,
+      mobileHomeBoardId: mobileBoardProps.boardId,
+    });
+    await db.insert(groupMembers).values({
+      userId: defaultCreatorId,
+      groupId,
+    });
+
+    // Act
+    const result = await caller.getHomeBoard();
+
+    // Assert
+    expectInputToBeFullBoardWithName(result, {
+      name: "group-mobile-home",
+      ...mobileBoardProps,
+    });
+  });
   test("should return global home board when user doesn't have one", async () => {
     // Arrange
     const spy = vi.spyOn(boardAccess, "throwIfActionForbiddenAsync");
@@ -1324,6 +1382,187 @@ describe("saveGroupBoardPermissions should save group board permissions", () =>
   );
 });
 
+const createExistingLayout = (id: string) => ({
+  id,
+  name: "Base",
+  columnCount: 10,
+  breakpoint: 0,
+});
+
+const createNewLayout = (columnCount: number) => ({
+  id: createId(),
+  name: "New layout",
+  columnCount,
+  breakpoint: 1400,
+});
+
+describe("saveLayouts should preserve legacy responsive layout editing", () => {
+  test("should add a layout and clone item and dynamic-section placements", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId, sectionId, itemId } = await createFullBoardAsync(db, "default");
+    const assignments = await createItemsAndSectionsAsync(db, {
+      boardId,
+      layoutId,
+      sectionId,
+    });
+    const newLayout = createNewLayout(3);
+
+    const savedLayouts = await caller.saveLayouts({
+      id: boardId,
+      layouts: [createExistingLayout(layoutId), newLayout],
+    });
+
+    const layout = expectToBeDefined(
+      await db.query.layouts.findFirst({
+        where: not(eq(layouts.id, layoutId)),
+      }),
+    );
+    expect(layout).toMatchObject({
+      name: newLayout.name,
+      columnCount: newLayout.columnCount,
+      breakpoint: newLayout.breakpoint,
+    });
+    expect(savedLayouts).toEqual([createExistingLayout(layoutId), { ...newLayout, id: layout.id }]);
+    await expectLayoutForRootLayoutAsync(db, sectionId, layout.id, {
+      ...assignments.inRoot,
+      a: itemId,
+    });
+    await expectLayoutForDynamicSectionAsync(db, assignments.inRoot.f, layout.id, assignments.inDynamicSection);
+
+    await caller.saveLayouts({ id: boardId, layouts: savedLayouts });
+    await expect(db.query.layouts.findMany({ where: eq(layouts.boardId, boardId) })).resolves.toHaveLength(2);
+  });
+
+  test("should update layout metadata and positions", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId, sectionId, itemId } = await createFullBoardAsync(db, "default");
+    const assignments = await createItemsAndSectionsAsync(db, {
+      boardId,
+      layoutId,
+      sectionId,
+    });
+
+    await caller.saveLayouts({
+      id: boardId,
+      layouts: [
+        {
+          id: layoutId,
+          name: "Phone",
+          columnCount: 3,
+          breakpoint: 480,
+        },
+      ],
+    });
+
+    await expect(db.query.layouts.findFirst({ where: eq(layouts.id, layoutId) })).resolves.toMatchObject({
+      name: "Phone",
+      columnCount: 3,
+      breakpoint: 480,
+    });
+    await expectLayoutForRootLayoutAsync(db, sectionId, layoutId, {
+      ...assignments.inRoot,
+      a: itemId,
+    });
+    await expectLayoutForDynamicSectionAsync(db, assignments.inRoot.f, layoutId, assignments.inDynamicSection);
+  });
+
+  test("should remove layouts omitted from the saved responsive configuration", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId } = await createFullBoardAsync(db, "default");
+
+    await caller.saveLayouts({
+      id: boardId,
+      layouts: [createNewLayout(12)],
+    });
+
+    await expect(db.query.layouts.findFirst({ where: eq(layouts.id, layoutId) })).resolves.toBeUndefined();
+  });
+
+  test("should reject duplicate responsive breakpoints", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId } = await createFullBoardAsync(db, "default");
+
+    await expect(
+      caller.saveLayouts({
+        id: boardId,
+        layouts: [
+          createExistingLayout(layoutId),
+          {
+            ...createNewLayout(4),
+            breakpoint: 0,
+          },
+        ],
+      }),
+    ).rejects.toMatchObject({ code: "BAD_REQUEST" });
+  });
+
+  test("should reject duplicate responsive layout IDs", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId } = await createFullBoardAsync(db, "default");
+    const existingLayout = createExistingLayout(layoutId);
+
+    await expect(
+      caller.saveLayouts({
+        id: boardId,
+        layouts: [existingLayout, { ...existingLayout, name: "Phone", breakpoint: 480 }],
+      }),
+    ).rejects.toMatchObject({ code: "BAD_REQUEST" });
+  });
+
+  test("should reject fractional responsive layout values", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId } = await createFullBoardAsync(db, "default");
+
+    await expect(
+      caller.saveLayouts({
+        id: boardId,
+        layouts: [{ ...createExistingLayout(layoutId), breakpoint: 480.5 }],
+      }),
+    ).rejects.toMatchObject({ code: "BAD_REQUEST" });
+
+    await expect(
+      caller.saveLayouts({
+        id: boardId,
+        layouts: [{ ...createExistingLayout(layoutId), columnCount: 3.5 }],
+      }),
+    ).rejects.toMatchObject({ code: "BAD_REQUEST" });
+  });
+});
+
+describe("addItem should preserve every saved layout", () => {
+  test("should clamp wide widgets to a retained narrow layout", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId } = await createFullBoardAsync(db, "default");
+    const mobileLayoutId = createId();
+    await db.insert(layouts).values({
+      id: mobileLayoutId,
+      name: "Mobile",
+      columnCount: 1,
+      breakpoint: 480,
+      boardId,
+    });
+
+    const { itemId } = await caller.addItem({
+      boardId,
+      kind: "mediaMissing",
+    });
+
+    const savedItemLayouts = await db.query.itemLayouts.findMany({
+      where: eq(itemLayouts.itemId, itemId),
+    });
+    expect(savedItemLayouts).toHaveLength(2);
+    expect(savedItemLayouts).toContainEqual(expect.objectContaining({ layoutId, width: 4 }));
+    expect(savedItemLayouts).toContainEqual(expect.objectContaining({ layoutId: mobileLayoutId, width: 1 }));
+  });
+});
+
 describe("saveLayout should save the desktop layout", () => {
   test("should update position of items when column count changes", async () => {
     // Arrange
@@ -1349,7 +1588,7 @@ describe("saveLayout should save the desktop layout", () => {
     });
     await expectLayoutForDynamicSectionAsync(db, assignments.inRoot.f, layoutId, assignments.inDynamicSection);
   });
-  test("should keep the desktop layout and remove legacy responsive layouts", async () => {
+  test("should preserve legacy layouts and desktop metadata", async () => {
     // Arrange
     const db = createDb();
     const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
@@ -1376,15 +1615,18 @@ describe("saveLayout should save the desktop layout", () => {
     // Act
     await caller.saveLayout({
       id: boardId,
-      columnCount: 16,
+      columnCount: 14,
     });
 
     // Assert
     const savedLayouts = await db.query.layouts.findMany({ where: eq(layouts.boardId, boardId) });
-    expect(savedLayouts).toEqual([
-      expect.objectContaining({ id: desktopLayoutId, name: "Base", columnCount: 16, breakpoint: 0 }),
-    ]);
-    expect(savedLayouts.some((layout) => layout.id === layoutId)).toBe(false);
+    expect(savedLayouts).toHaveLength(2);
+    expect(savedLayouts).toContainEqual(
+      expect.objectContaining({ id: layoutId, name: "Base", columnCount: 10, breakpoint: 0 }),
+    );
+    expect(savedLayouts).toContainEqual(
+      expect.objectContaining({ id: desktopLayoutId, name: "Large", columnCount: 14, breakpoint: 1200 }),
+    );
   });
   test("should fail when board not found", async () => {
     // Arrange
@@ -1427,9 +1669,12 @@ const expectInputToBeFullBoardWithName = (
 };
 
 const createFullBoardAsync = async (db: Database, name: string) => {
-  await db.insert(users).values({
-    id: defaultCreatorId,
-  });
+  await db
+    .insert(users)
+    .values({
+      id: defaultCreatorId,
+    })
+    .onConflictDoNothing();
 
   const boardId = createId();
   await db.insert(boards).values({

packages/api/src/router/test/serverSettings.spec.ts

@@ -3,7 +3,7 @@ import { describe, expect, test, vi } from "vitest";
 
 import type { Session } from "@homarr/auth";
 import { createId } from "@homarr/common";
-import { boards, serverSettings } from "@homarr/db/schema";
+import { boards, layouts, serverSettings } from "@homarr/db/schema";
 import { createDb } from "@homarr/db/test";
 import { defaultServerSettings, defaultServerSettingsKeys } from "@homarr/server-settings";
 
@@ -56,6 +56,33 @@ describe("getAll server settings", () => {
 });
 
 describe("saveSettings", () => {
+  test("saveSettings should persist settings when defaults are not seeded", async () => {
+    const db = createDb();
+    const caller = serverSettingsRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+
+    await caller.saveSettings({
+      settingsKey: "board",
+      value: {
+        enableAutomaticMobileLayout: false,
+      },
+    });
+
+    const dbSettings = await db.select().from(serverSettings);
+    expect(dbSettings).toStrictEqual([
+      {
+        settingKey: "board",
+        value: stringify({
+          ...defaultServerSettings.board,
+          enableAutomaticMobileLayout: false,
+        }),
+      },
+    ]);
+  });
+
   test("saveSettings should update settings and return true when it updated only one", async () => {
     const db = createDb();
     const caller = serverSettingsRouter.createCaller({
@@ -89,6 +116,33 @@ describe("saveSettings", () => {
       },
     ]);
   });
+
+  test("saveSettings should preserve concurrent partial updates", async () => {
+    const db = createDb();
+    const caller = serverSettingsRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+
+    await Promise.all([
+      caller.saveSettings({
+        settingsKey: "analytics",
+        value: { enableGeneral: false },
+      }),
+      caller.saveSettings({
+        settingsKey: "analytics",
+        value: { instanceId: "concurrent-instance" },
+      }),
+    ]);
+
+    await expect(caller.getAll()).resolves.toMatchObject({
+      analytics: {
+        enableGeneral: false,
+        instanceId: "concurrent-instance",
+      },
+    });
+  });
 });
 
 describe("board settings API", () => {
@@ -103,6 +157,36 @@ describe("board settings API", () => {
     await expect(caller.getBoardSettings()).resolves.toStrictEqual(defaultServerSettings.board);
   });
 
+  test("getBoardSettings should backfill the automatic layout default for legacy values", async () => {
+    const db = createDb();
+    const caller = serverSettingsRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+    const boardId = createId();
+    await db.insert(boards).values({ id: boardId, name: "legacy", isPublic: false });
+    await db.insert(layouts).values([
+      { id: createId(), boardId, name: "Base", columnCount: 12, breakpoint: 0 },
+      { id: createId(), boardId, name: "Mobile", columnCount: 4, breakpoint: 480 },
+    ]);
+    const legacyBoardSettings = {
+      homeBoardId: defaultServerSettings.board.homeBoardId,
+      mobileHomeBoardId: defaultServerSettings.board.mobileHomeBoardId,
+      enableStatusByDefault: defaultServerSettings.board.enableStatusByDefault,
+      forceDisableStatus: defaultServerSettings.board.forceDisableStatus,
+    };
+    await db.insert(serverSettings).values({
+      settingKey: "board",
+      value: stringify(legacyBoardSettings),
+    });
+
+    await expect(caller.getBoardSettings()).resolves.toStrictEqual({
+      ...defaultServerSettings.board,
+      enableAutomaticMobileLayout: false,
+    });
+  });
+
   test("updateBoardSettings should insert settings when defaults are not persisted", async () => {
     const db = createDb();
     const caller = serverSettingsRouter.createCaller({
@@ -145,6 +229,7 @@ describe("board settings API", () => {
     await caller.updateBoardSettings({ homeBoardId: boardId });
     const result = await caller.updateBoardSettings({
       mobileHomeBoardId: boardId,
+      enableAutomaticMobileLayout: false,
       enableStatusByDefault: false,
     });
 
@@ -152,6 +237,7 @@ describe("board settings API", () => {
       ...defaultServerSettings.board,
       homeBoardId: boardId,
       mobileHomeBoardId: boardId,
+      enableAutomaticMobileLayout: false,
       enableStatusByDefault: false,
     });
     const dbSettings = await db.select().from(serverSettings);
@@ -163,6 +249,25 @@ describe("board settings API", () => {
     ]);
   });
 
+  test("updateBoardSettings should preserve concurrent partial updates", async () => {
+    const db = createDb();
+    const caller = serverSettingsRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+
+    await Promise.all([
+      caller.updateBoardSettings({ forceDisableStatus: true }),
+      caller.updateBoardSettings({ enableStatusByDefault: false }),
+    ]);
+
+    await expect(caller.getBoardSettings()).resolves.toMatchObject({
+      forceDisableStatus: true,
+      enableStatusByDefault: false,
+    });
+  });
+
   test("updateBoardSettings should reject private home boards", async () => {
     const db = createDb();
     const caller = serverSettingsRouter.createCaller({

packages/api/src/test/mcp.spec.ts

@@ -33,6 +33,7 @@ test("MCP tools should contain expected procedures", () => {
   expect(toolNames).toContain("app_byId");
   expect(toolNames).toContain("app_create");
   expect(toolNames).toContain("board_savePartialBoardSettings");
+  expect(toolNames).toContain("board_saveLayout");
   expect(toolNames).toContain("board_duplicateBoard");
   expect(toolNames).toContain("info_getInfo");
   expect(toolNames).toContain("invite_getAll");

packages/boards/package.json

@@ -24,6 +24,7 @@
   },
   "dependencies": {
     "@homarr/api": "workspace:^0.1.0",
+    "@homarr/settings": "workspace:^0.1.0",
     "react": "catalog:",
     "react-dom": "catalog:"
   },

packages/boards/src/context.spec.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "vitest";
+
+import type { RouterOutputs } from "@homarr/api";
+
+import { getBoardLayouts, getCurrentLayout, getDesktopLayout } from "./context";
+
+const createBoard = () =>
+  ({
+    layouts: [
+      { id: "small", name: "Small", columnCount: 4, breakpoint: 0 },
+      { id: "medium", name: "Medium", columnCount: 8, breakpoint: 768 },
+      { id: "large", name: "Large", columnCount: 12, breakpoint: 1200 },
+    ],
+  }) as RouterOutputs["board"]["getBoardByName"];
+
+describe("board layout selection", () => {
+  test("automatic mode always uses the desktop layout", () => {
+    const board = createBoard();
+
+    expect(getDesktopLayout(board).id).toBe("large");
+    expect(getCurrentLayout(board, true, 390)).toBe("large");
+  });
+
+  test.each([
+    [390, "small"],
+    [768, "medium"],
+    [1024, "medium"],
+    [1440, "large"],
+  ])("legacy mode selects the matching responsive layout at %spx", (viewportWidth, expectedLayoutId) => {
+    expect(getCurrentLayout(createBoard(), false, viewportWidth)).toBe(expectedLayoutId);
+  });
+
+  test("legacy mode falls back to the desktop layout before the client viewport is known", () => {
+    expect(getCurrentLayout(createBoard(), false, undefined)).toBe("large");
+  });
+
+  test("rejects boards without a layout", () => {
+    const board = { ...createBoard(), layouts: [] };
+
+    expect(() => getDesktopLayout(board)).toThrow("Board must have a layout");
+    expect(() => getCurrentLayout(board, false, 390)).toThrow("Board must have a layout");
+  });
+
+  test("keeps every saved layout available for reversible mutations", () => {
+    expect(getBoardLayouts(createBoard())).toEqual(["small", "medium", "large"]);
+  });
+});

packages/boards/src/context.tsx

@@ -1,12 +1,13 @@
 "use client";
 
 import type { PropsWithChildren } from "react";
-import { createContext, useContext, useEffect } from "react";
+import { createContext, useCallback, useContext, useEffect, useState } from "react";
 import { usePathname } from "next/navigation";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { getActiveQueryCacheBoardId, setActiveQueryCacheBoardId } from "@homarr/api/query-cache";
+import { useSettings } from "@homarr/settings";
 
 import { updateBoardName } from "./updater";
 
@@ -73,10 +74,6 @@ export const useOptionalBoard = () => {
   return context?.board ?? null;
 };
 
-export const getCurrentLayout = (board: RouterOutputs["board"]["getBoardByName"]) => {
-  return getDesktopLayout(board).id;
-};
-
 export const getDesktopLayout = (board: RouterOutputs["board"]["getBoardByName"]) => {
   const layout = board.layouts
     .toSorted(
@@ -91,9 +88,57 @@ export const getDesktopLayout = (board: RouterOutputs["board"]["getBoardByName"]
   return layout;
 };
 
-export const useCurrentLayout = () => getCurrentLayout(useRequiredBoard());
+export const getCurrentLayout = (
+  board: RouterOutputs["board"]["getBoardByName"],
+  enableAutomaticMobileLayout: boolean,
+  viewportWidth?: number,
+) => {
+  if (enableAutomaticMobileLayout || viewportWidth === undefined) {
+    return getDesktopLayout(board).id;
+  }
 
-export const getBoardLayouts = (board: RouterOutputs["board"]["getBoardByName"]) => [getCurrentLayout(board)];
+  const sortedLayouts = board.layouts.toSorted((layoutA, layoutB) => layoutB.breakpoint - layoutA.breakpoint);
+  const layout = sortedLayouts.find((candidate) => candidate.breakpoint <= viewportWidth) ?? sortedLayouts.at(-1);
+
+  if (!layout) {
+    throw new Error("Board must have a layout");
+  }
+
+  return layout.id;
+};
+
+export const useCurrentLayout = () => {
+  const board = useRequiredBoard();
+  const { enableAutomaticMobileLayout } = useSettings();
+  const [currentLayout, setCurrentLayout] = useState(() =>
+    getCurrentLayout(
+      board,
+      enableAutomaticMobileLayout,
+      !enableAutomaticMobileLayout && typeof window !== "undefined" ? window.innerWidth : undefined,
+    ),
+  );
+
+  const updateCurrentLayout = useCallback(() => {
+    setCurrentLayout(getCurrentLayout(board, enableAutomaticMobileLayout, window.innerWidth));
+  }, [board, enableAutomaticMobileLayout]);
+
+  useEffect(() => {
+    updateCurrentLayout();
+
+    if (enableAutomaticMobileLayout) return;
+
+    window.addEventListener("resize", updateCurrentLayout);
+
+    return () => {
+      window.removeEventListener("resize", updateCurrentLayout);
+    };
+  }, [enableAutomaticMobileLayout, updateCurrentLayout]);
+
+  return currentLayout;
+};
+
+export const getBoardLayouts = (board: RouterOutputs["board"]["getBoardByName"]) =>
+  board.layouts.map((layout) => layout.id);
 
 export const useLayouts = () => {
   const board = useRequiredBoard();

packages/db/collection.ts

@@ -4,7 +4,7 @@ import { objectEntries } from "@homarr/common";
 import { dbEnv } from "@homarr/core/infrastructure/db/env";
 
 import type { HomarrDatabase, HomarrDatabaseMysql, HomarrDatabasePostgresql } from "./driver";
-import * as schema from "./schema";
+import { schema } from "./schema";
 
 type TableKey = {
   [K in keyof typeof schema]: (typeof schema)[K] extends { _: { brand: "Table" } } ? K : never;

packages/db/migrations/seed.spec.ts

@@ -0,0 +1,115 @@
+import { stringify } from "superjson";
+import { describe, expect, test } from "vitest";
+
+import { createId } from "@homarr/common";
+import { eq } from "@homarr/db";
+import {
+  getServerSettingByKeyAsync,
+  getServerSettingsAsync,
+  shouldEnableAutomaticMobileLayoutForUpgrade,
+} from "@homarr/db/queries";
+import { boards, layouts, serverSettings } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+import { defaultServerSettings } from "@homarr/server-settings";
+
+import { seedServerSettingsAsync } from "./seed";
+
+describe("automatic mobile layout upgrade default", () => {
+  test("enables automatic mode for a new instance", () => {
+    expect(shouldEnableAutomaticMobileLayoutForUpgrade([])).toBe(true);
+  });
+
+  test("enables automatic mode when every existing board has only its canonical layout", () => {
+    expect(
+      shouldEnableAutomaticMobileLayoutForUpgrade([
+        { boardId: "first", name: "Base", breakpoint: 0 },
+        { boardId: "second", name: "Base", breakpoint: 0 },
+      ]),
+    ).toBe(true);
+  });
+
+  test("preserves legacy mode when a board has multiple responsive layouts", () => {
+    expect(
+      shouldEnableAutomaticMobileLayoutForUpgrade([
+        { boardId: "board", name: "Base", breakpoint: 0 },
+        { boardId: "board", name: "Mobile", breakpoint: 480 },
+      ]),
+    ).toBe(false);
+  });
+
+  test("preserves legacy mode when a board has duplicate canonical layouts", () => {
+    expect(
+      shouldEnableAutomaticMobileLayoutForUpgrade([
+        { boardId: "board", name: "Base", breakpoint: 0 },
+        { boardId: "board", name: "Base", breakpoint: 0 },
+      ]),
+    ).toBe(false);
+  });
+
+  test.each([
+    { boardId: "board", name: "Phone", breakpoint: 0 },
+    { boardId: "board", name: "Base", breakpoint: 480 },
+  ])("preserves legacy mode for a noncanonical saved layout", (existingLayout) => {
+    expect(shouldEnableAutomaticMobileLayoutForUpgrade([existingLayout])).toBe(false);
+  });
+
+  test("uses the upgrade heuristic when migrations and seeding are skipped", async () => {
+    const db = createDb();
+    const boardId = createId();
+    await db.insert(boards).values({ id: boardId, name: "dashboard", isPublic: false });
+    await db.insert(layouts).values([
+      { id: createId(), boardId, name: "Base", columnCount: 12, breakpoint: 0 },
+      { id: createId(), boardId, name: "Phone", columnCount: 4, breakpoint: 480 },
+    ]);
+
+    await expect(getServerSettingByKeyAsync(db, "board")).resolves.toMatchObject({
+      enableAutomaticMobileLayout: false,
+    });
+    await expect(getServerSettingsAsync(db)).resolves.toMatchObject({
+      board: {
+        enableAutomaticMobileLayout: false,
+      },
+    });
+  });
+
+  test("backfills legacy responsive instances once without overriding an explicit choice", async () => {
+    const db = createDb();
+    const boardId = createId();
+    await db.insert(boards).values({ id: boardId, name: "dashboard", isPublic: false });
+    await db.insert(layouts).values([
+      { id: createId(), boardId, name: "Base", columnCount: 12, breakpoint: 0 },
+      { id: createId(), boardId, name: "Phone", columnCount: 4, breakpoint: 480 },
+    ]);
+    await db.insert(serverSettings).values({
+      settingKey: "board",
+      value: stringify({
+        homeBoardId: null,
+        mobileHomeBoardId: null,
+        enableStatusByDefault: true,
+        forceDisableStatus: false,
+      }),
+    });
+
+    await seedServerSettingsAsync(db);
+    await seedServerSettingsAsync(db);
+
+    await expect(getServerSettingByKeyAsync(db, "board")).resolves.toStrictEqual({
+      ...defaultServerSettings.board,
+      enableAutomaticMobileLayout: false,
+    });
+
+    await db
+      .update(serverSettings)
+      .set({
+        value: stringify({
+          ...defaultServerSettings.board,
+          enableAutomaticMobileLayout: true,
+        }),
+      })
+      .where(eq(serverSettings.settingKey, "board"));
+
+    await seedServerSettingsAsync(db);
+
+    await expect(getServerSettingByKeyAsync(db, "board")).resolves.toStrictEqual(defaultServerSettings.board);
+  });
+});

packages/db/migrations/seed.ts

@@ -21,6 +21,7 @@ import { getMaxGroupPositionAsync, placeAllWidgetsAsync } from "../queries";
 import {
   getServerSettingByKeyAsync,
   insertServerSettingByKeyAsync,
+  shouldEnableAutomaticMobileLayoutForUpgrade,
   updateServerSettingByKeyAsync,
 } from "../queries/server-setting";
 
@@ -245,19 +246,33 @@ const seedDefaultSearchEnginesAsync = async (db: Database) => {
   console.log("Set Homarr docs as the default search engine");
 };
 
-const seedServerSettingsAsync = async (db: Database) => {
+export const seedServerSettingsAsync = async (db: Database) => {
   const serverSettingsData = await db.query.serverSettings.findMany();
+  const existingLayouts = await db.query.layouts.findMany({
+    columns: {
+      boardId: true,
+      name: true,
+      breakpoint: true,
+    },
+  });
+  const defaultsForThisInstance = {
+    ...defaultServerSettings,
+    board: {
+      ...defaultServerSettings.board,
+      enableAutomaticMobileLayout: shouldEnableAutomaticMobileLayoutForUpgrade(existingLayouts),
+    },
+  };
 
   for (const settingsKey of defaultServerSettingsKeys) {
     const currentDbEntry = serverSettingsData.find((setting) => setting.settingKey === settingsKey);
     if (!currentDbEntry) {
-      await insertServerSettingByKeyAsync(db, settingsKey, defaultServerSettings[settingsKey]);
+      await insertServerSettingByKeyAsync(db, settingsKey, defaultsForThisInstance[settingsKey]);
       console.log(`Created serverSetting through seed key=${settingsKey}`);
       continue;
     }
 
-    const currentSettings = await getServerSettingByKeyAsync(db, settingsKey);
-    const defaultSettings = defaultServerSettings[settingsKey];
+    const currentSettings = SuperJSON.parse<(typeof defaultServerSettings)[typeof settingsKey]>(currentDbEntry.value);
+    const defaultSettings = defaultsForThisInstance[settingsKey];
     const missingKeys = objectKeys(defaultSettings).filter((key) => !(key in currentSettings));
 
     if (missingKeys.length === 0) {

packages/db/queries/server-setting.ts

@@ -1,29 +1,80 @@
-import SuperJSON from "superjson";
+import { parse, stringify } from "superjson";
 
 import type { ServerSettings } from "@homarr/server-settings";
 import { defaultServerSettings, defaultServerSettingsKeys } from "@homarr/server-settings";
 
 import type { Database } from "..";
-import { eq } from "..";
+import { eq, sql } from "..";
+import { isMysql, isPostgresql } from "../collection";
+import type { HomarrDatabaseMysql, HomarrDatabasePostgresql } from "../driver";
 import { serverSettings } from "../schema";
+import { serverSettings as mysqlServerSettings } from "../schema/mysql";
+import { serverSettings as postgresqlServerSettings } from "../schema/postgresql";
+
+interface ExistingBoardLayout {
+  boardId: string;
+  name: string;
+  breakpoint: number;
+}
+
+export const shouldEnableAutomaticMobileLayoutForUpgrade = (existingLayouts: ExistingBoardLayout[]) => {
+  const layoutCounts = new Map<string, number>();
+
+  for (const layout of existingLayouts) {
+    if (layout.name !== "Base" || layout.breakpoint !== 0) {
+      return false;
+    }
+
+    const nextCount = (layoutCounts.get(layout.boardId) ?? 0) + 1;
+    if (nextCount > 1) {
+      return false;
+    }
+    layoutCounts.set(layout.boardId, nextCount);
+  }
+
+  return true;
+};
+
+const getAutomaticMobileLayoutUpgradeDefaultAsync = async (db: Database) => {
+  const existingLayouts = await db.query.layouts.findMany({
+    columns: {
+      boardId: true,
+      name: true,
+      breakpoint: true,
+    },
+  });
+
+  return shouldEnableAutomaticMobileLayoutForUpgrade(existingLayouts);
+};
 
 export const getServerSettingsAsync = async (db: Database) => {
   const settings = await db.query.serverSettings.findMany();
+  let parsedBoardSettings: Partial<ServerSettings["board"]> = {};
 
-  return defaultServerSettingsKeys.reduce((acc, settingKey) => {
-    const setting = settings.find((setting) => setting.settingKey === settingKey);
+  const mergedSettings = defaultServerSettingsKeys.reduce((acc, settingKey) => {
+    const setting = settings.find((candidate) => candidate.settingKey === settingKey);
     if (!setting) {
       // Typescript is not happy because the key is a union and it does not know that they are the same
-      acc[settingKey] = defaultServerSettings[settingKey] as never;
+      acc[settingKey] = { ...defaultServerSettings[settingKey] } as never;
       return acc;
     }
 
+    const persistedSettings = parse<Record<string, unknown>>(setting.value);
+    if (settingKey === "board") {
+      parsedBoardSettings = persistedSettings as Partial<ServerSettings["board"]>;
+    }
     acc[settingKey] = {
       ...defaultServerSettings[settingKey],
-      ...SuperJSON.parse(setting.value),
-    };
+      ...persistedSettings,
+    } as never;
     return acc;
   }, {} as ServerSettings);
+
+  if (typeof parsedBoardSettings.enableAutomaticMobileLayout !== "boolean") {
+    mergedSettings.board.enableAutomaticMobileLayout = await getAutomaticMobileLayoutUpgradeDefaultAsync(db);
+  }
+
+  return mergedSettings;
 };
 
 export const getServerSettingByKeyAsync = async <TKey extends keyof ServerSettings>(db: Database, key: TKey) => {
@@ -32,10 +83,31 @@ export const getServerSettingByKeyAsync = async <TKey extends keyof ServerSettin
   });
 
   if (!dbSettings) {
+    if (key === "board") {
+      return {
+        ...defaultServerSettings.board,
+        enableAutomaticMobileLayout: await getAutomaticMobileLayoutUpgradeDefaultAsync(db),
+      } as ServerSettings[TKey];
+    }
+
     return defaultServerSettings[key];
   }
 
-  return SuperJSON.parse<ServerSettings[TKey]>(dbSettings.value);
+  const persistedSettings = parse<Partial<ServerSettings[TKey]>>(dbSettings.value);
+  const mergedSettings = {
+    ...defaultServerSettings[key],
+    ...persistedSettings,
+  } as ServerSettings[TKey];
+
+  if (
+    key === "board" &&
+    typeof (persistedSettings as Partial<ServerSettings["board"]>).enableAutomaticMobileLayout !== "boolean"
+  ) {
+    (mergedSettings as ServerSettings["board"]).enableAutomaticMobileLayout =
+      await getAutomaticMobileLayoutUpgradeDefaultAsync(db);
+  }
+
+  return mergedSettings;
 };
 
 export const updateServerSettingByKeyAsync = async <TKey extends keyof ServerSettings>(
@@ -46,7 +118,7 @@ export const updateServerSettingByKeyAsync = async <TKey extends keyof ServerSet
   await db
     .update(serverSettings)
     .set({
-      value: SuperJSON.stringify(value),
+      value: stringify(value),
     })
     .where(eq(serverSettings.settingKey, key));
 };
@@ -58,6 +130,56 @@ export const insertServerSettingByKeyAsync = async <TKey extends keyof ServerSet
 ) => {
   await db.insert(serverSettings).values({
     settingKey: key,
-    value: SuperJSON.stringify(value),
+    value: stringify(value),
   });
 };
+
+export const mergeServerSettingByKeyAsync = async <TKey extends keyof ServerSettings>(
+  db: Database,
+  key: TKey,
+  value: ServerSettings[TKey],
+  patch: Partial<ServerSettings[TKey]>,
+) => {
+  const serializedValue = stringify(value);
+  const serializedPatch = stringify(patch);
+
+  if (isMysql()) {
+    await (db as unknown as HomarrDatabaseMysql)
+      .insert(mysqlServerSettings)
+      .values({ settingKey: key, value: serializedValue })
+      .onDuplicateKeyUpdate({
+        set: {
+          value: sql`JSON_MERGE_PATCH(${mysqlServerSettings.value}, ${serializedPatch})`,
+        },
+      });
+    return;
+  }
+
+  if (isPostgresql()) {
+    await (db as unknown as HomarrDatabasePostgresql)
+      .insert(postgresqlServerSettings)
+      .values({ settingKey: key, value: serializedValue })
+      .onConflictDoUpdate({
+        target: postgresqlServerSettings.settingKey,
+        set: {
+          value: sql`jsonb_set(
+            ${postgresqlServerSettings.value}::jsonb,
+            '{json}',
+            (${postgresqlServerSettings.value}::jsonb -> 'json') || (${serializedPatch}::jsonb -> 'json'),
+            true
+          )::text`,
+        },
+      });
+    return;
+  }
+
+  await db
+    .insert(serverSettings)
+    .values({ settingKey: key, value: serializedValue })
+    .onConflictDoUpdate({
+      target: serverSettings.settingKey,
+      set: {
+        value: sql`json_patch(${serverSettings.value}, ${serializedPatch})`,
+      },
+    });
+};

packages/db/test/schema.spec.ts

@@ -11,6 +11,9 @@ import * as mysqlSchema from "../schema/mysql";
 import * as postgresqlSchema from "../schema/postgresql";
 import * as sqliteSchema from "../schema/sqlite";
 
+const mysqlTables = { ...mysqlSchema };
+const postgresqlTables = { ...postgresqlSchema };
+
 // We need the following three types as there is currently no support for Buffer in mysql & pg and
 // so we use a custom type which results in the config beeing different
 type FixedMysqlConfig = {
@@ -63,7 +66,7 @@ test("schemas should match", () => {
       if (!("uniqueName" in sqliteColumn)) return;
       if (!("primary" in sqliteColumn)) return;
 
-      const mysqlTable = mysqlSchema[tableName];
+      const mysqlTable = mysqlTables[tableName];
 
       const mysqlColumn = mysqlTable[columnName as keyof typeof mysqlTable] as object;
       if (!("isUnique" in mysqlColumn)) return;
@@ -84,7 +87,7 @@ test("schemas should match", () => {
       ).toEqual(mysqlColumn.primary);
     });
 
-    const mysqlTable = mysqlSchema[tableName];
+    const mysqlTable = mysqlTables[tableName];
     const sqliteForeignKeys = sqliteTable[Symbol.for("drizzle:SQLiteInlineForeignKeys") as keyof typeof sqliteTable] as
       | SqliteForeignKey[]
       | undefined;
@@ -144,7 +147,7 @@ test("schemas should match for postgresql", () => {
   objectEntries(sqliteSchema).forEach(([tableName, sqliteTable]) => {
     // keys of sqliteSchema and postgresqlSchema are the same, so we can safely use tableName as key
     // skipcq: JS-E1007
-    const postgresqlTable = postgresqlSchema[tableName];
+    const postgresqlTable = postgresqlTables[tableName];
     Object.entries(sqliteTable).forEach(([columnName, sqliteColumn]: [string, object]) => {
       if (!("isUnique" in sqliteColumn)) return;
       if (!("uniqueName" in sqliteColumn)) return;

packages/server-settings/src/index.ts

@@ -27,6 +27,7 @@ export const defaultServerSettings = {
   board: {
     homeBoardId: null as string | null,
     mobileHomeBoardId: null as string | null,
+    enableAutomaticMobileLayout: true,
     enableStatusByDefault: true,
     forceDisableStatus: false,
   },

packages/settings/src/creator.ts

@@ -12,14 +12,14 @@ export type SettingsContextProps = Pick<
   | "pingIconsEnabled"
   | "enableRightClickOnWidgets"
 > &
-  Pick<ServerSettings["board"], "enableStatusByDefault" | "forceDisableStatus"> &
+  Pick<ServerSettings["board"], "enableAutomaticMobileLayout" | "enableStatusByDefault" | "forceDisableStatus"> &
   Pick<ServerSettings["user"], "enableGravatar">;
 
 export interface PublicServerSettings {
   search: Pick<ServerSettings["search"], "defaultSearchEngineId">;
   board: Pick<
     ServerSettings["board"],
-    "homeBoardId" | "mobileHomeBoardId" | "enableStatusByDefault" | "forceDisableStatus"
+    "homeBoardId" | "mobileHomeBoardId" | "enableAutomaticMobileLayout" | "enableStatusByDefault" | "forceDisableStatus"
   >;
   user: Pick<ServerSettings["user"], "enableGravatar">;
 }
@@ -51,6 +51,7 @@ export const createSettings = ({
   mobileHomeBoardId: user?.mobileHomeBoardId ?? serverSettings.board.mobileHomeBoardId,
   pingIconsEnabled: user?.pingIconsEnabled ?? false,
   enableRightClickOnWidgets: user?.enableRightClickOnWidgets ?? true,
+  enableAutomaticMobileLayout: serverSettings.board.enableAutomaticMobileLayout,
   enableStatusByDefault: serverSettings.board.enableStatusByDefault,
   forceDisableStatus: serverSettings.board.forceDisableStatus,
   enableGravatar: serverSettings.user.enableGravatar,

packages/translation/src/lang/en.json

@@ -4391,7 +4391,15 @@
             "description": "Configure the layout used on desktop and larger screens."
           },
           "mobile": {
-            "description": "On mobile, items are automatically arranged in two columns and cannot be moved or resized. Categories and dynamic sections are flattened into the item list."
+            "automaticDescription": "On mobile, the normal widgets are arranged in two columns and cannot be moved or resized. Categories and dynamic sections are flattened into the item list."
+          },
+          "responsive": {
+            "title": "Responsive layouts",
+            "description": "Automatic mobile layout is disabled for this server. Configure the saved layouts selected at each viewport breakpoint; these layouts can also be edited directly on mobile.",
+            "defaultName": "New layout",
+            "action": {
+              "add": "Add layout"
+            }
           }
         },
         "background": {
@@ -4841,6 +4849,13 @@
               "mobileLabel": "Global mobile board",
               "description": "Only public boards are available for selection"
             },
+            "mobileLayout": {
+              "title": "Mobile layout",
+              "enable": {
+                "label": "Use automatic mobile layout",
+                "description": "Squeeze every board into a read-only two-column grid on phones and small tablets without changing widget content. Turn this off to use saved responsive layouts and mobile layout editing. Saved layouts are kept while automatic mode is enabled."
+              }
+            },
             "status": {
               "title": "App status",
               "enableStatusByDefault": {

packages/validation/src/board.ts

@@ -24,7 +24,7 @@ export const boardNameSchema = z
   .min(1)
   .max(255)
   .regex(/^[A-Za-z0-9-_]*$/);
-export const boardColumnCountSchema = z.number().min(1).max(24);
+export const boardColumnCountSchema = z.number().int().min(1).max(24);
 
 export const boardByNameSchema = z.object({
   name: boardNameSchema,
@@ -75,6 +75,46 @@ export const boardSaveLayoutSchema = z.object({
   columnCount: boardColumnCountSchema,
 });
 
+const responsiveBoardLayoutsSchema = z
+  .array(
+    z.object({
+      id: z.string(),
+      name: z.string().trim().nonempty().max(32),
+      columnCount: boardColumnCountSchema,
+      breakpoint: z.number().int().min(0).max(32767),
+    }),
+  )
+  .min(1)
+  .superRefine((layouts, context) => {
+    const seenBreakpoints = new Set<number>();
+    const seenIds = new Set<string>();
+
+    layouts.forEach((layout, index) => {
+      if (seenIds.has(layout.id)) {
+        context.addIssue({
+          code: "custom",
+          message: "Each responsive layout must have a unique ID",
+          path: [index, "id"],
+        });
+      }
+      seenIds.add(layout.id);
+
+      if (seenBreakpoints.has(layout.breakpoint)) {
+        context.addIssue({
+          code: "custom",
+          message: "Each responsive layout must have a unique breakpoint",
+          path: [index, "breakpoint"],
+        });
+      }
+      seenBreakpoints.add(layout.breakpoint);
+    });
+  });
+
+export const boardSaveLayoutsSchema = z.object({
+  id: z.string(),
+  layouts: responsiveBoardLayoutsSchema,
+});
+
 export const boardSaveSchema = z.object({
   id: z.string(),
   sections: z.array(sectionSchema),