feat: rebuild board grid experience

PRODUCT.md

@@ -10,7 +10,7 @@ Homarr is used by self-hosters and administrators who assemble dashboards for se
 
 ## Product Purpose
 
-Homarr provides one place to organize, observe, and operate self-hosted services. Success means a user can build a useful dashboard quickly, understand its state, recover from configuration errors, and extend it without requiring a bespoke Homarr feature for every service.
+Homarr provides one place to organize, observe, and operate self-hosted services. Success means a user can build a useful dashboard quickly, understand its state, recover from configuration errors, and extend it without requiring a bespoke Homarr feature for every service. Boards must load immediately, stay visually stable, keep widgets legible across screen sizes, and make editing feel direct and forgiving.
 
 ## Brand Personality
 
@@ -27,7 +27,9 @@ Avoid decorative admin dashboards, wizard flows that fight ordinary scrolling, h
 3. Make simple tasks short without limiting advanced use cases.
 4. Isolate failures so one service or widget cannot disrupt the dashboard.
 5. Use the existing Mantine design language consistently across management and board surfaces.
+6. Keep spatial actions direct: moving, resizing, nesting, and using fixed rails happen on the canvas with immediate feedback.
+7. Preserve predictable widget composition with fixed logical tile sizes and horizontal scrolling before controls become inaccessible.
 
 ## Accessibility & Inclusion
 
-Target WCAG 2.2 AA. Support keyboard navigation, screen readers, visible focus, sufficient contrast, reduced motion, non-color status cues, responsive layouts, and actionable error messages.
+Target WCAG 2.2 AA. Support keyboard navigation, screen readers, visible focus, sufficient contrast, reduced motion, non-color status cues, responsive layouts, actionable error messages, and keyboard equivalents for drag and resize operations.

apps/docs/docs/getting-started/after-the-installation.mdx

@@ -54,11 +54,7 @@ You must choose a username and password (both can later be changed).
 We enforce strict password requirements when you enter your password to protect your instance if you accidentally
 expose it to the internet.
 
-<img
-  src={imageStartFromScratchStepAdminUser}
-  alt={"Screenshot form to create admin user"}
-  width={300}
-/>
+<img src={imageStartFromScratchStepAdminUser} alt={"Screenshot form to create admin user"} width={300} />
 
 If you selected external providers (such as LDAP or OIDC), you'll be prompted to create an admin group.
 This group will be used to synchronize users from your provider to Homarr.
@@ -116,22 +112,14 @@ The onboarding can no longer be started again.
 From here you can click on one of the provided links to continue your journey.
 We recommend you to continue with the section [creating your first board on this page](#creating-your-first-board).
 
-<img
-  src={imageStartFromScratchStepFinish}
-  alt={"Screenshot of the finish onboarding process with links"}
-  width={300}
-/>
+<img src={imageStartFromScratchStepFinish} alt={"Screenshot of the finish onboarding process with links"} width={300} />
 
 ### Importing a ZIP from version before 1.0.0
 
 This is recommended when you used Homarr before and want to re-import your data.
 It is important that you first migrate correctly using [the list of breaking changes for 1.0](/blog/2024/09/23/version-1.0).
 
-<img
-  src={manageExportOldHomarr}
-  alt="Export from old Homarr"
-  style={{ maxWidth: 500 }}
-/>
+<img src={manageExportOldHomarr} alt="Export from old Homarr" style={{ maxWidth: 500 }} />
 
 **How to export and import data**
 
@@ -149,7 +137,8 @@ It is important that you first migrate correctly using [the list of breaking cha
 ## Creating your first board
 
 In Homarr, you organize your apps and widgets on boards.
-Boards can be organized using the interactive drag and drop.
+Boards use fixed-size tiles so the same widget keeps the same proportions on every screen.
+Drag, resize, and section controls are available in edit mode.
 Let's create your first board by navigating here: `Manage` > `Boards` > `New board`:
 ![](./img/manage-create-board-button.png)
 
@@ -197,38 +186,23 @@ Here you have the following options in the header:
 
 When entering the edit mode, you'll get some additional buttons to work with:
 
-<img
-  src={manageBoardHeaderEditMode}
-  alt={"Screenshot of buttons in the edit mode"}
-  width={200}
-/>
+<img src={manageBoardHeaderEditMode} alt={"Screenshot of buttons in the edit mode"} width={200} />
 
 - **Add item**: Click this button to add new elements to your page.
-- **Exit edit mode**: Click this btuton to save your changes and exit edit mode.
+- **Exit edit mode**: Click this button to save your changes and exit edit mode.
 
 To continue, click the option "New Item":
 
-<img
-  src={manageBoardHeaderAddItem}
-  alt={"Screenshot of the add item menu"}
-  width={200}
-/>
+<img src={manageBoardHeaderAddItem} alt={"Screenshot of the add item menu"} width={200} />
 
 Next, you can choose what item you'd like to add.
 We will discuss the other options in the following sections - for now choose "App" to continue.
 
-<img
-  src={manageBoardHeaderChooseItem}
-  alt={"Screenshot of choosing the app item in the modal"}
-  width={300}
-/>
+<img src={manageBoardHeaderChooseItem} alt={"Screenshot of choosing the app item in the modal"} width={300} />
 
 As soon as you chose the app, the modal will close and you'll get the following item on your board:
 
-<img
-  src={manageBoardNoApp}
-  alt="Screenshot of the No app element on the board"
-/>
+<img src={manageBoardNoApp} alt="Screenshot of the No app element on the board" />
 
 This is expected, because you haven't told Homarr what app it should show in this item.
 To configure this, click on the small 3 dots at the top of the item in the edit mode and choose "Edit item" in the menu.
@@ -240,21 +214,27 @@ In the modal you can edit the app that you want to display:
 ![](./img/manage-board-choose-app.png)
 
 As soon as you save your changes, the tile on the board will refresh and display your app.
-Using the small bidirectional arrow at the bottom right you can resize the element.
-Start pressing with your mouse button down, move your mouse to resize and release your finger as soon your you're happy with the size.
+Use the resize handle at the bottom right to resize the tile.
+Press and hold the handle, move the pointer, and release it when the tile has the size you want.
 
 ![](./img/resize-item.gif)
 
-To move your item to a different position on the board, simply hold the mouse button anywhere on the item and move with the mouse to the desired position.
-As soon as you release your finger, the item will snap in place in the grid.
+To move a tile in edit mode, press and hold anywhere on the tile except one of its buttons or controls, move it to the desired position, and release it.
+The tile snaps to the grid and neighboring tiles move out of the way automatically.
 
 ![](./img/move-item.gif)
 
+Every `1 × 1` tile has a logical content size of `200 × 200` pixels.
+Larger tiles use multiples of that fixed unit, with a consistent gap between cells.
+Homarr scales the complete board uniformly, like zooming a page.
+It stops shrinking at 75% and lets you scroll horizontally instead of making text and controls too small.
+It does not squeeze or reflow the content of individual widgets, so a widget keeps the same design and proportions across screen sizes.
+
 :::note
 
-You cannot move items freely on the vertical axis.
-We always align all items to the top of the page to simply organization.
-To move items to the bottom, you must add more items or resize items.
+Viewing a board initially uses the lightweight, non-interactive layout.
+For users with edit access, Homarr prepares drag-and-drop and resize controls in the background after the board becomes interactive.
+If you enter edit mode before that finishes, the existing board stays visible until the editor is ready.
 
 :::
 
@@ -265,8 +245,10 @@ This helps you to explore the capabilities of Homarr before you build your board
 
 :::
 
-Users on touch or mobile devices may not be able to drag and drop or move items.
-They can use the "Move / resize item" option in the edit menu of items instead:
+Keyboard users can focus a tile, press Enter or Space, then use arrow keys to move and Shift plus arrow keys to resize.
+Press Escape to stop.
+For precise numeric controls or touch input, choose **Move / resize item** from the tile's edit menu.
+The dialog can also move the tile to another section or fixed sidebar:
 
 ![](./img/manage-board-move-resize-item-menu.png)
 
@@ -338,43 +320,39 @@ As with every change, don't forget to save your changes using the exit edit mode
 
 ![](./img/exit-edit-mode.png)
 
-## Grouping your items
+## Organizing items with sections
 
-As the last step, let's organize your freshly created items using two different options.
-You can choose either or both of them on your boards.
+Sections are resizable containers for apps, widgets, and other sections.
+The same section works on the main canvas and inside a fixed sidebar.
+Each section can configure:
 
-### Using dynamic sections
-
-Dynamic sections are a simple, resizable visual group to group items.
+- Show or hide its label.
+- Allow or disable collapsing.
+- Show or hide **Open all in new tabs**.
+- Change its border color and custom CSS classes.
 
 ![](./img/create-dynamic-section.png)
 
-After adding a dynamic section, you can simply drag and drop items into the section:
+After adding a section, drag and resize it like any other tile, then drag items into it:
 
 ![](./img/dynamic-section.gif)
 
-### Using categories
+### Labeled and collapsible sections
 
-Categories are more advanced and complicated than dynamic sections.
-To create a category, open the add item modal and choose "new category":
+Open the add-content menu and choose **New section**.
+Use its settings menu to add a label and enable the behavior you want.
+In edit mode, move items into or out of the section directly.
+In view mode, each user can collapse eligible sections without changing the saved board layout.
+If **Open all in new tabs** is enabled, the section menu can open every app link it contains.
 
-![](./img/add-category.png)
+### Fixed sidebars
 
-Every category must have a name. After you click "Add category", you will get a new item on your board:
+Open the board's **Layout** settings to enable the left or right sidebar for each responsive layout.
+Choose one, two, or three columns with the slider and use the preview to check the remaining canvas width.
+The sidebar reserves those columns from the dashboard, so Homarr moves canvas items into the next available positions.
+Sidebar content stays visible while the page scrolls and remains editable.
 
-![](./img/category.gif)
-
-You can drag and drop items in to this category in the edit mode.
-Categories will have a big space before and after them in the edit mode to
-enable you to drag and drop items outside the category.
-You can also collapse or open categories in edit mode to facilitate your editing process.
-
-:::note
-
-A current limitation of categories is, that they will always have a width of 100%.
-You cannot reduce their horizontal width.
-
-:::
+Existing categories become sections automatically, and category rails become fixed sidebars.
 
 ## Guided tours
 

apps/docs/docs/management/api/index.mdx

@@ -84,6 +84,13 @@ The OpenAPI and MCP APIs include board management endpoints for common automatio
 
 Use the interactive API reference to inspect the exact request body for each endpoint under the `boards` and `settings` tags.
 
+### Saving dashboard layouts
+
+The dashboard editor saves item positions and sections as one board update.
+Canvas height follows its content automatically and does not require a separate API setting.
+Responsive layouts store optional left and right gutter widths from zero to three columns.
+Gutter columns are reserved from the layout's total column count, and changing them reflows affected items.
+
 ## Get Custom Widget authoring resources
 
 Custom JSX v2 provides four HTTP discovery endpoints:

apps/docs/docs/management/boards/index.mdx

@@ -36,8 +36,10 @@ Underscores and hyphen-minus are allowed.
 
 ### Column count
 
-Homarr has a complex drag-and-drop system that can be used from the browser.
-The column count defines how many horizontal columns are available to drag and drop elements to.
+The column count defines how many fixed-width cells are available in each row.
+One cell contains a `200 × 200` logical-pixel tile.
+Homarr scales the whole board uniformly instead of changing widget proportions, and always fits it to the available width without horizontal scrolling.
+The main canvas and enabled rails stay at least one viewport tall, and the canvas grows automatically while you drag or resize items near its lower edge.
 
 ### Public
 
@@ -88,26 +90,78 @@ Homarr will fall back to the Homarr logo if nothing is set.
 
 ### Layout
 
-In this section you can configure the different responsive layouts. Depending on your screens width the layout will change.
+In this section you can configure the different responsive layouts.
+Homarr selects a layout from the screen width, then scales its complete fixed-size canvas uniformly.
 
 ![](./img/layout-settings.png)
 
-On each element the position and size of items can be changed seperately.
-When adding a new layout the position and sizes will automatically be generated depending on the column count.
-When adding a new item / dynamic section that will always be 1x1 on each layout and placed on the first available position.
+Every `1 × 1` tile has a `200 × 200` logical-pixel content area.
+The `24` logical-pixel gap between tiles is separate from that size.
+A `2 × 1` tile therefore contains two fixed cell widths plus the gap between them.
+Widgets see their logical size, while the board's visual scale makes the complete layout larger or smaller.
+When fitting below 100%, Homarr keeps widget typography and control density at their normal readable size.
+On larger canvases, the complete board grows together like browser zoom.
+The complete canvas always fits the available width and never adds horizontal board scrolling.
+
+The position and size of every item are independent in each responsive layout.
+Moving or resizing an item in one layout does not change any other layout.
+When adding a new layout, its initial positions and sizes are generated from the column count.
+New items use their widget's default grid size, while a new Container starts at a useful `4 × 3` size when the layout has enough columns.
+Both are placed in the first available position.
+
+The canvas is at least one window tall, even when it is empty.
+Its left and right edges are hard drag boundaries, while its bottom edge extends automatically as a tile is dragged or resized downward.
+Nested Containers keep their own resizable bounds.
 
 #### Name
 
-The name of the layout can be choosen freely. It is only used for the management and will not be visible on the board.
+The name of the layout can be chosen freely. It is only used for management and will not be visible on the board.
 
 #### Column count
 
-Amount of columns for this layout. Defines how many items can be placed in a row. When changed it will automatically adjust the position and size of the items.
+Total number of columns for this layout.
+When changed, Homarr moves items into the next available positions without overlap.
+
+#### Fixed rails
+
+Each responsive layout can enable a fixed left rail, a fixed right rail, or both.
+Set a rail width to zero to disable it for that layout.
+Choose a width from one to three columns with the three-step slider.
+The preview shows how much space remains for the main canvas.
+
+Rail columns are reserved from the layout's total column count.
+For example, a 12-column layout with a two-column left rail leaves ten columns for the canvas.
+Enabling or widening a rail reflows canvas items into the remaining columns.
+Disabling a rail moves its contents back into the next available canvas positions.
+
+Rails fill the available window height and remain fixed while the page scrolls. They do not grow or scroll independently.
+Apps, widgets, and Containers inside them still use the same fixed `200 × 200` cells and can be rearranged in edit mode, where each rail shows its name and boundary.
 
 #### Breakpoint
 
 Minimum width of the screen where the layout will be used.
-Once the minimum of the next layout is reached the layout will change.
+Once the minimum of the next layout is reached, the layout will change.
+
+#### View and edit modes
+
+View mode renders a static board without executing the drag-and-drop editor.
+After the board is interactive, Homarr prepares the editor in the background for users who can modify it.
+Entering edit mode keeps the static board visible until that preparation finishes, then enables collision-aware movement and resizing without changing the board geometry.
+Widget content is inert in edit mode, so dragging anywhere on the content moves the tile instead of activating the widget; its settings button remains visible in the compact header above the tile.
+Dropping a tile into another tile's exact slot swaps their positions when both resulting placements fit without overlapping other content.
+For other collisions, or when a tile grows into occupied space, nearby tiles are compacted out of the way.
+The visible corner controls provide a 44-pixel resize target, and edge controls appear on hover for horizontal or vertical resizing.
+Resize handles stop at the tile's minimum allowed size while the pointer is still moving.
+Exit edit mode to save the resulting positions.
+
+Pointer users can drag anywhere on a widget tile. Containers use the grab button at their top-left corner.
+Resize tiles from any edge or corner handle.
+On a touch screen, press and hold the tile before moving it; resize handles support direct touch input.
+Keyboard users can focus a tile, press Enter or Space to start editing, use the arrow keys to move it, and use Shift plus the arrow keys to resize it.
+Press Enter, Space, or Escape to stop keyboard editing.
+Keyboard moves and resizes apply immediately; Escape stops keyboard editing without undoing those changes.
+During a pointer or touch interaction, Escape cancels the move or resize and restores the layout from before that interaction.
+The **Move / resize item** action in the edit menu remains available for precise numeric input.
 
 #### Preview
 
@@ -115,6 +169,24 @@ Once the minimum of the next layout is reached the layout will change.
 <img src={layoutMediumImage} height={256} />
 <img src={layoutLargeImage} height={256} />
 
+### Containers and rails
+
+Containers can hold apps, widgets, and nested Containers.
+The same Container model works on the main canvas, inside a fixed rail, or inside another Container.
+Move and resize Containers directly in edit mode; nested content stays within the Container's local bounds.
+Resize outlines follow the pointer continuously while a dashed preview marks the grid size that will be applied on release.
+Each responsive layout stores its own Container position and size.
+
+Each Container can configure:
+
+- Its label and whether that label is visible.
+- Whether users can collapse and expand it like an accordion.
+- Whether its menu shows **Open all in new tabs** for the app links it contains.
+- Its border color and custom CSS classes.
+
+Collapsing a Container reduces its full-width header to a half-row expansion bar and compacts the surrounding layout without losing its expanded size.
+Expanding it smoothly restores those bounds and moves following items out of the way without reloading the widgets inside it.
+
 ### Background
 
 #### Background image URL
@@ -159,7 +231,7 @@ Change the color of your bookmark / app icons.
 
 #### Item radius
 
-Change the radius of your items / categories.
+Change the radius of your items and Containers.
 
 <img src={itemRadiusImage} height={100} />
 

apps/nextjs/next.config.ts

@@ -79,6 +79,10 @@ const nextConfig: NextConfig = {
       {
         source: "/(.*)", // Apply CSP to all routes
         headers: [
+          {
+            key: "Accept-CH",
+            value: "Sec-CH-Viewport-Width",
+          },
           {
             key: "Content-Security-Policy",
             // worker-src / media-src with blob: is necessary for video.js, see https://github.com/homarr-labs/homarr/issues/3912 and https://stackoverflow.com/questions/65792855/problem-with-video-js-and-content-security-policy-csp

apps/nextjs/package.json

@@ -32,7 +32,6 @@
     "@homarr/docker": "workspace:^0.1.0",
     "@homarr/form": "workspace:^0.1.0",
     "@homarr/forms-collection": "workspace:^0.1.0",
-    "@homarr/gridstack": "catalog:",
     "@homarr/icons": "workspace:^0.1.0",
     "@homarr/image-proxy": "workspace:^0.1.0",
     "@homarr/integrations": "workspace:^0.1.0",
@@ -83,6 +82,7 @@
     "drizzle-orm": "catalog:",
     "flag-icons": "catalog:",
     "glob": "catalog:",
+    "gridstack": "catalog:",
     "isomorphic-dompurify": "catalog:",
     "jotai": "catalog:",
     "jszip": "catalog:",

apps/nextjs/src/app/[locale]/boards/(content)/_client.module.css

@@ -0,0 +1,20 @@
+.columns {
+  display: grid;
+  align-items: start;
+  gap: 24px;
+}
+
+.lane {
+  min-width: 0;
+}
+
+.gutter {
+  position: sticky;
+  top: 0;
+  align-self: start;
+  max-height: calc(100dvh - var(--app-shell-header-offset, 0px) - var(--mantine-spacing-md));
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-gutter: stable;
+  transform: translateY(var(--board-gutter-sticky-offset, 0px));
+}

apps/nextjs/src/app/[locale]/boards/(content)/_client.tsx

@@ -1,33 +1,121 @@
 "use client";
 
-import { Box, Stack } from "@mantine/core";
+import { Box } from "@mantine/core";
 
-import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
+import { useCurrentLayout, useInitialViewportWidth, useRequiredBoard } from "@homarr/boards/context";
+import { useEditMode } from "@homarr/boards/edit-mode";
+import { useScopedI18n } from "@homarr/translation/client";
 
-import { BoardCategorySection } from "~/components/board/sections/category-section";
+import {
+  getBoardLaneColumnCount,
+  getInitialBoardLogicalHeight,
+  getLogicalTrackSize,
+  LOGICAL_GRID_GAP,
+  getRootSectionForLane,
+} from "~/components/board/layout";
+import { ScaledBoardCanvas } from "~/components/board/layout/scaled-board-canvas";
 import { BoardEmptySection } from "~/components/board/sections/empty-section";
+import { BoardGridEditorBoundary } from "~/components/board/sections/grid/board-grid-editor-boundary";
+import { BoardGridPortalHost, BoardGridPortalRenderer } from "~/components/board/sections/grid/grid-portal-host";
+import { BoardSectionCollapseProvider } from "~/components/board/sections/section-collapse";
 import { BoardBackgroundVideo } from "~/components/layout/background";
+import classes from "./_client.module.css";
+
+const APP_SHELL_INLINE_PADDING = 32;
 
 export const ClientBoard = () => {
   const board = useRequiredBoard();
+  const t = useScopedI18n("board.landmark");
+  const [isEditMode] = useEditMode();
   const currentLayoutId = useCurrentLayout();
+  const initialViewportWidth = useInitialViewportWidth();
+  const currentLayout = board.layouts.find((layout) => layout.id === currentLayoutId) ?? board.layouts.at(0);
+  if (!currentLayout) throw new Error("Expected the board to contain a layout");
 
-  const fullWidthSortedSections = board.sections
-    .filter((section) => section.kind === "empty" || section.kind === "category")
-    .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset);
+  const mainSection = getRootSectionForLane(board, "main");
+  const leftSection = getRootSectionForLane(board, "left");
+  const rightSection = getRootSectionForLane(board, "right");
+  if (!mainSection) throw new Error("Expected the board to contain a main canvas section");
+
+  const leftColumnCount = getBoardLaneColumnCount(currentLayout, "left");
+  const mainColumnCount = getBoardLaneColumnCount(currentLayout, "main");
+  const rightColumnCount = getBoardLaneColumnCount(currentLayout, "right");
+  const laneWidths = [leftColumnCount, mainColumnCount, rightColumnCount]
+    .filter((columnCount) => columnCount > 0)
+    .map(getLogicalTrackSize);
+  const logicalWidth =
+    laneWidths.reduce((total, width) => total + width, 0) + (laneWidths.length - 1) * LOGICAL_GRID_GAP;
+  const initialLogicalHeight = getInitialBoardLogicalHeight(board, currentLayoutId) + LOGICAL_GRID_GAP;
+  const initialAvailableWidth = Math.max(1, initialViewportWidth - APP_SHELL_INLINE_PADDING);
+  const gridTemplateColumns = [
+    leftColumnCount > 0 ? `${getLogicalTrackSize(leftColumnCount)}px` : null,
+    `${getLogicalTrackSize(mainColumnCount)}px`,
+    rightColumnCount > 0 ? `${getLogicalTrackSize(rightColumnCount)}px` : null,
+  ]
+    .filter((value) => value !== null)
+    .join(" ");
 
   return (
     <Box h="100%" pos="relative" data-homarr-dev-benchmark-board>
       <BoardBackgroundVideo />
-      <Stack h="100%">
-        {fullWidthSortedSections.map((section) =>
-          section.kind === "empty" ? (
-            <BoardEmptySection key={`${currentLayoutId}-${section.id}`} section={section} />
-          ) : (
-            <BoardCategorySection key={`${currentLayoutId}-${section.id}`} section={section} />
-          ),
-        )}
-      </Stack>
+      <BoardSectionCollapseProvider>
+        <BoardGridPortalHost>
+          <ScaledBoardCanvas
+            logicalWidth={logicalWidth}
+            initialLogicalHeight={initialLogicalHeight}
+            initialAvailableWidth={initialAvailableWidth}
+            label={board.name}
+          >
+            <BoardGridEditorBoundary key={currentLayoutId}>
+              <BoardGridPortalRenderer />
+              <div className={classes.columns} style={{ gridTemplateColumns, paddingTop: LOGICAL_GRID_GAP }}>
+                {leftColumnCount > 0 && leftSection && (
+                  <aside
+                    className={`${classes.lane} ${classes.gutter}`}
+                    aria-label={t("leftRail")}
+                    data-board-gutter="left"
+                    data-board-editing={isEditMode ? "true" : undefined}
+                  >
+                    <BoardEmptySection
+                      key={`${currentLayoutId}-${leftSection.id}`}
+                      section={leftSection}
+                      columnCount={leftColumnCount}
+                      requestedRowCount={0}
+                      railPlacement="left"
+                    />
+                  </aside>
+                )}
+
+                <section className={classes.lane} aria-label={t("canvas")}>
+                  <BoardEmptySection
+                    key={`${currentLayoutId}-${mainSection.id}`}
+                    section={mainSection}
+                    columnCount={mainColumnCount}
+                    requestedRowCount={0}
+                  />
+                </section>
+
+                {rightColumnCount > 0 && rightSection && (
+                  <aside
+                    className={`${classes.lane} ${classes.gutter}`}
+                    aria-label={t("rightRail")}
+                    data-board-gutter="right"
+                    data-board-editing={isEditMode ? "true" : undefined}
+                  >
+                    <BoardEmptySection
+                      key={`${currentLayoutId}-${rightSection.id}`}
+                      section={rightSection}
+                      columnCount={rightColumnCount}
+                      requestedRowCount={0}
+                      railPlacement="right"
+                    />
+                  </aside>
+                )}
+              </div>
+            </BoardGridEditorBoundary>
+          </ScaledBoardCanvas>
+        </BoardGridPortalHost>
+      </BoardSectionCollapseProvider>
     </Box>
   );
 };

apps/nextjs/src/app/[locale]/boards/(content)/_creator.tsx

@@ -2,9 +2,6 @@ import type { Metadata } from "next";
 import { cache } from "react";
 import { TRPCError } from "@trpc/server";
 
-// Placed here because gridstack styles are used for board content
-import "~/styles/gridstack.scss";
-
 import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
 import { makeQueryClient } from "@homarr/api/shared";
 import { IntegrationProvider } from "@homarr/auth/client";
@@ -21,7 +18,7 @@ import { createMetaTitle } from "~/metadata";
 import { env } from "~/env";
 import { createBoardLayout } from "../_layout-creator";
 import type { Board, Item } from "../_types";
-import { DynamicClientBoard } from "./_dynamic-client";
+import { ClientBoard } from "./_client";
 import { BoardContentHeaderActions } from "./_header-actions";
 
 const logger = createLogger({ module: "createBoardContentPage" });
@@ -76,7 +73,7 @@ export const createBoardContentPage = <TParams extends Record<string, unknown>>(
       return (
         <HydrationBoundary state={dehydrate(queryClient)}>
           <IntegrationProvider integrations={integrations}>
-            <DynamicClientBoard />
+            <ClientBoard />
           </IntegrationProvider>
         </HydrationBoundary>
       );

apps/nextjs/src/app/[locale]/boards/(content)/_dynamic-client.tsx

@@ -1,24 +0,0 @@
-"use client";
-
-import dynamic from "next/dynamic";
-import { SimpleGrid, Skeleton, Stack } from "@mantine/core";
-
-const BoardLoadingShell = () => (
-  <Stack h="100%" p="md" aria-busy aria-label="Loading dashboard" role="status">
-    <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="md">
-      {[2, 1, 2, 2, 1, 2].map((rows, index) => (
-        <Skeleton
-          key={index}
-          data-homarr-dev-benchmark-board-shell
-          height={rows * 96}
-          radius="var(--mantine-radius-default)"
-        />
-      ))}
-    </SimpleGrid>
-  </Stack>
-);
-
-export const DynamicClientBoard = dynamic(() => import("./_client").then((mod) => mod.ClientBoard), {
-  ssr: false,
-  loading: BoardLoadingShell,
-});

apps/nextjs/src/app/[locale]/boards/(content)/_edit-actions.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { Group, Menu } from "@mantine/core";
+import { IconBox, IconChevronDown, IconLayoutGridAdd, IconPlug, IconPlus, IconResize } from "@tabler/icons-react";
+
+import { useSession } from "@homarr/auth/client";
+import { useModalAction } from "@homarr/modals";
+import { AppSelectModal } from "@homarr/modals-collection";
+import { useI18n } from "@homarr/translation/client";
+
+import { useItemActions } from "~/components/board/items/item-actions";
+import { ItemSelectModal } from "~/components/board/items/item-select-modal";
+import { useDynamicSectionActions } from "~/components/board/sections/dynamic/dynamic-actions";
+import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
+import { HeaderButton } from "~/components/layout/header/button";
+
+export default function BoardEditActions() {
+  return <AddMenu />;
+}
+
+const AddMenu = () => {
+  const { data: session } = useSession();
+  const { openModal: openItemSelectModal } = useModalAction(ItemSelectModal);
+  const { openModal: openAppSelectModal } = useModalAction(AppSelectModal);
+  const { openModal: openIntegrationSelectModal } = useModalAction(IntegrationSelectModal);
+  const { addDynamicSection } = useDynamicSectionActions();
+  const { createItem } = useItemActions();
+  const t = useI18n();
+
+  const handleSelectItem = () => {
+    openItemSelectModal();
+  };
+
+  const handleSelectApp = () => {
+    openAppSelectModal({
+      onSelect: (app) => {
+        createItem({
+          kind: "app",
+          options: { appId: app.id },
+        });
+      },
+      withCreate: session?.user.permissions.includes("app-create") ?? false,
+    });
+  };
+
+  const handleAddIntegration = () => {
+    openIntegrationSelectModal({});
+  };
+
+  return (
+    <Menu position="bottom-end">
+      <Menu.Target>
+        <HeaderButton w="auto" px={4} aria-label={t("board.action.addContent")}>
+          <Group gap={4} wrap="nowrap">
+            <IconPlus stroke={1.5} />
+            <IconChevronDown color="gray" size={16} />
+          </Group>
+        </HeaderButton>
+      </Menu.Target>
+      <Menu.Dropdown style={{ transform: "translate(-3px, 0)" }}>
+        <Menu.Item leftSection={<IconResize size={20} />} onClick={handleSelectItem}>
+          {t("item.action.create")}
+        </Menu.Item>
+        <Menu.Item leftSection={<IconBox size={20} />} onClick={handleSelectApp}>
+          {t("app.action.add")}
+        </Menu.Item>
+        <Menu.Item leftSection={<IconPlug size={20} />} onClick={handleAddIntegration}>
+          {t("integration.action.create")}
+        </Menu.Item>
+        <Menu.Divider />
+        <Menu.Item leftSection={<IconLayoutGridAdd size={20} />} onClick={addDynamicSection}>
+          {t("section.dynamic.action.create")}
+        </Menu.Item>
+      </Menu.Dropdown>
+    </Menu>
+  );
+};

apps/nextjs/src/app/[locale]/boards/(content)/_header-actions.tsx

@@ -1,49 +1,50 @@
 "use client";
 
-import { useCallback, useEffect, useRef } from "react";
+import { startTransition, useCallback, useEffect, useRef, useState } from "react";
+import dynamic from "next/dynamic";
 import { useRouter } from "next/navigation";
-import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
-import { Box, Group, Menu, ScrollArea } from "@mantine/core";
+import { Box, Center, Loader, Menu, ScrollArea } from "@mantine/core";
 import { useHotkeys } from "@mantine/hooks";
-import {
-  IconBox,
-  IconBoxAlignTop,
-  IconChevronDown,
-  IconLayoutBoard,
-  IconPencil,
-  IconPencilOff,
-  IconPlug,
-  IconPlus,
-  IconReplace,
-  IconResize,
-  IconSettings,
-} from "@tabler/icons-react";
+import { IconLayoutBoard, IconPencil, IconPencilOff, IconReplace, IconSettings } from "@tabler/icons-react";
 
 import { clientApi } from "@homarr/api/client";
-import { useSession } from "@homarr/auth/client";
 import { useRequiredBoard } from "@homarr/boards/context";
 import { useEditMode } from "@homarr/boards/edit-mode";
 import { revalidatePathActionAsync } from "@homarr/common/client";
 import { env } from "@homarr/common/env";
 import { hotkeys } from "@homarr/definitions";
-import { useConfirmModal, useModalAction } from "@homarr/modals";
-import { AppSelectModal } from "@homarr/modals-collection";
+import { useConfirmModal } from "@homarr/modals";
 import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
 import { useI18n, useScopedI18n } from "@homarr/translation/client";
 import { Link } from "@homarr/ui";
 
-import { useItemActions } from "~/components/board/items/item-actions";
-import { ItemSelectModal } from "~/components/board/items/item-select-modal";
 import { useBoardPermissions } from "~/components/board/permissions/client";
-import { useCategoryActions } from "~/components/board/sections/category/category-actions";
-import { CategoryEditModal } from "~/components/board/sections/category/category-edit-modal";
-import { useDynamicSectionActions } from "~/components/board/sections/dynamic/dynamic-actions";
-import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
+import { loadGridEditorAsync, scheduleGridEditorWarmup } from "~/components/board/sections/grid/grid-editor-loader";
 import { HeaderButton } from "~/components/layout/header/button";
+import { TourTarget } from "~/components/layout/header/tour-target";
+import type * as EditActionsModule from "./_edit-actions";
+
+let editActionsModulePromise: Promise<typeof EditActionsModule> | undefined;
+const loadEditActionsAsync = () => {
+  editActionsModulePromise ??= import("./_edit-actions").catch((error: unknown) => {
+    editActionsModulePromise = undefined;
+    throw error;
+  });
+  return editActionsModulePromise;
+};
+const loadBoardEditorAsync = async () =>
+  await Promise.all([
+    loadGridEditorAsync(),
+    loadEditActionsAsync(),
+    import("~/components/board/items/item-menu"),
+    import("~/components/board/sections/container/container-menu"),
+  ]);
+const BoardEditActions = dynamic(loadEditActionsAsync, { ssr: false });
 
 export const BoardContentHeaderActions = ({ demoReadOnly }: { demoReadOnly: boolean }) => {
   const [isEditMode] = useEditMode();
   const board = useRequiredBoard();
+  const t = useI18n();
   const { hasChangeAccess } = useBoardPermissions(board);
 
   if (!hasChangeAccess) {
@@ -52,16 +53,16 @@ export const BoardContentHeaderActions = ({ demoReadOnly }: { demoReadOnly: bool
 
   return (
     <>
-      {isEditMode && <AddMenu />}
+      {isEditMode && <BoardEditActions />}
 
       <EditModeMenu demoReadOnly={demoReadOnly} />
 
       {!demoReadOnly && (
-        <OnboardingTour.Target id="board-settings">
-          <HeaderButton href={`/boards/${board.name}/settings`}>
+        <TourTarget id="board-settings">
+          <HeaderButton href={`/boards/${board.name}/settings`} aria-label={t("board.action.settings")}>
             <IconSettings stroke={1.5} />
           </HeaderButton>
-        </OnboardingTour.Target>
+        </TourTarget>
       )}
 
       <SelectBoardsMenu />
@@ -69,101 +70,13 @@ export const BoardContentHeaderActions = ({ demoReadOnly }: { demoReadOnly: bool
   );
 };
 
-const AddMenu = () => {
-  const board = useRequiredBoard();
-  const { data: session } = useSession();
-  const { openModal: openCategoryEditModal } = useModalAction(CategoryEditModal);
-  const { openModal: openItemSelectModal } = useModalAction(ItemSelectModal);
-  const { openModal: openAppSelectModal } = useModalAction(AppSelectModal);
-  const { openModal: openIntegrationSelectModal } = useModalAction(IntegrationSelectModal);
-  const { addCategoryToEnd } = useCategoryActions();
-  const { addDynamicSection } = useDynamicSectionActions();
-  const { createItem } = useItemActions();
-  const t = useI18n();
-
-  const handleAddCategory = useCallback(
-    () =>
-      openCategoryEditModal(
-        {
-          category: {
-            id: "new",
-            name: "",
-          },
-          onSuccess({ name }) {
-            addCategoryToEnd({ name });
-          },
-          submitLabel: t("section.category.create.submit"),
-        },
-        {
-          title: (t) => t("section.category.create.title"),
-        },
-      ),
-    [addCategoryToEnd, openCategoryEditModal, t],
-  );
-
-  const handleSelectItem = useCallback(() => {
-    openItemSelectModal({ boardId: board.id });
-  }, [board.id, openItemSelectModal]);
-
-  const handleSelectApp = useCallback(() => {
-    openAppSelectModal({
-      onSelect: (app) => {
-        createItem({
-          kind: "app",
-          options: { appId: app.id },
-        });
-      },
-      withCreate: session?.user.permissions.includes("app-create") ?? false,
-    });
-  }, [openAppSelectModal, createItem]);
-
-  const handleAddIntegration = useCallback(() => {
-    openIntegrationSelectModal({});
-  }, [openIntegrationSelectModal]);
-
-  return (
-    <Menu position="bottom-end">
-      <Menu.Target>
-        <HeaderButton w="auto" px={4} aria-label={t("item.action.create")}>
-          <Group gap={4} wrap="nowrap">
-            <IconPlus stroke={1.5} />
-            <IconChevronDown color="gray" size={16} />
-          </Group>
-        </HeaderButton>
-      </Menu.Target>
-      <Menu.Dropdown style={{ transform: "translate(-3px, 0)" }}>
-        <Menu.Item leftSection={<IconResize size={20} />} onClick={handleSelectItem}>
-          {t("item.action.create")}
-        </Menu.Item>
-
-        <Menu.Item leftSection={<IconBox size={20} />} onClick={handleSelectApp}>
-          {t("app.action.add")}
-        </Menu.Item>
-
-        <Menu.Item leftSection={<IconPlug size={20} />} onClick={handleAddIntegration}>
-          {t("integration.action.create")}
-        </Menu.Item>
-
-        <Menu.Divider />
-
-        <Menu.Item leftSection={<IconBoxAlignTop size={20} />} onClick={handleAddCategory}>
-          {t("section.category.action.create")}
-        </Menu.Item>
-
-        <Menu.Item leftSection={<IconResize size={20} />} onClick={addDynamicSection}>
-          {t("section.dynamic.action.create")}
-        </Menu.Item>
-      </Menu.Dropdown>
-    </Menu>
-  );
-};
-
 const EditModeMenu = ({ demoReadOnly }: { demoReadOnly: boolean }) => {
   const [isEditMode, { open, close }] = useEditMode();
+  const [editorLoadState, setEditorLoadState] = useState<"scheduled" | "loading" | "ready" | "error">("scheduled");
+  const [isEnteringEditMode, setIsEnteringEditMode] = useState(false);
   const board = useRequiredBoard();
   const utils = clientApi.useUtils();
   const t = useScopedI18n("board.action.edit");
-  const commonT = useI18n();
   const latestBoardRef = useRef(board);
 
   latestBoardRef.current = board;
@@ -192,46 +105,101 @@ const EditModeMenu = ({ demoReadOnly }: { demoReadOnly: boolean }) => {
     close();
   }, [utils, board.name, close]);
 
-  const toggle = useCallback(() => {
+  const prepareEditorAsync = useCallback(async () => {
+    if (editorLoadState === "ready") return;
+
+    setEditorLoadState("loading");
+    try {
+      await loadBoardEditorAsync();
+      setEditorLoadState("ready");
+    } catch {
+      setEditorLoadState("error");
+      throw new Error("Unable to load the board editor");
+    }
+  }, [editorLoadState]);
+
+  useEffect(() => {
+    return scheduleGridEditorWarmup(async () => {
+      setEditorLoadState("loading");
+      try {
+        await loadBoardEditorAsync();
+        setEditorLoadState("ready");
+      } catch {
+        setEditorLoadState("error");
+      }
+    });
+  }, []);
+
+  const prewarmEditor = useCallback(() => {
+    void prepareEditorAsync().catch(() => {
+      // A click or hotkey retries and reports the error.
+    });
+  }, [prepareEditorAsync]);
+
+  const toggle = useCallback(async () => {
     if (isEditMode) {
       if (demoReadOnly) return discardDemoChanges();
       return saveBoard(latestBoardRef.current);
     }
-    open();
-  }, [isEditMode, demoReadOnly, saveBoard, open, discardDemoChanges]);
+    setIsEnteringEditMode(true);
+    try {
+      await prepareEditorAsync();
+      startTransition(open);
+    } catch {
+      showErrorNotification({
+        title: t("notification.loadError.title"),
+        message: t("notification.loadError.message"),
+      });
+    } finally {
+      setIsEnteringEditMode(false);
+    }
+  }, [demoReadOnly, discardDemoChanges, isEditMode, open, prepareEditorAsync, saveBoard, t]);
 
-  useHotkeys([[hotkeys.toggleBoardEdit, toggle]]);
+  useHotkeys([[hotkeys.toggleBoardEdit, () => void toggle()]]);
   usePreventLeaveWithDirty(isEditMode);
 
   return (
-    <OnboardingTour.Target id="board-edit-mode">
+    <TourTarget id="board-edit-mode">
       <HeaderButton
-        onClick={toggle}
-        loading={isPending}
+        onClick={() => void toggle()}
+        onFocus={prewarmEditor}
+        onPointerEnter={prewarmEditor}
+        loading={isPending || isEnteringEditMode}
         data-testid="board-edit-mode-toggle"
-        aria-label={isEditMode ? commonT("common.action.save") : commonT("common.action.edit")}
+        data-board-editor-preload-state={editorLoadState}
+        aria-busy={isPending || isEnteringEditMode}
+        aria-label={isEditMode ? (demoReadOnly ? t("exit") : t("save")) : t("enter")}
         aria-pressed={isEditMode}
       >
         {isEditMode ? <IconPencilOff stroke={1.5} /> : <IconPencil stroke={1.5} />}
       </HeaderButton>
-    </OnboardingTour.Target>
+    </TourTarget>
   );
 };
 
 const SelectBoardsMenu = () => {
-  const { data: boards = [] } = clientApi.board.getAllBoards.useQuery();
+  const t = useI18n();
+  const [isOpen, setIsOpen] = useState(false);
+  const utils = clientApi.useUtils();
+  const { data: boards = [], isPending } = clientApi.board.getAllBoards.useQuery(undefined, { enabled: isOpen });
+  const preloadBoards = () => void utils.board.getAllBoards.prefetch();
 
   return (
-    <OnboardingTour.Target id="board-switcher">
-      <Box>
-        <Menu position="bottom-end">
+    <TourTarget id="board-switcher">
+      <Box onFocus={preloadBoards} onPointerEnter={preloadBoards}>
+        <Menu position="bottom-end" opened={isOpen} onChange={setIsOpen}>
           <Menu.Target>
-            <HeaderButton w="auto" px={4}>
+            <HeaderButton w="auto" px={4} aria-label={t("board.action.switch")}>
               <IconReplace stroke={1.5} />
             </HeaderButton>
           </Menu.Target>
           <Menu.Dropdown style={{ transform: "translate(-7px, 0)" }}>
             <ScrollArea.Autosize mah={300}>
+              {isPending && (
+                <Center p="xs">
+                  <Loader size="xs" />
+                </Center>
+              )}
               {boards.map((board) => (
                 <Menu.Item
                   key={board.id}
@@ -246,7 +214,7 @@ const SelectBoardsMenu = () => {
           </Menu.Dropdown>
         </Menu>
       </Box>
-    </OnboardingTour.Target>
+    </TourTarget>
   );
 };
 
@@ -259,15 +227,13 @@ const usePreventLeaveWithDirty = (isDirty: boolean) => {
   useEffect(() => {
     if (!isDirty) return;
 
-    const handleClick = (event: Event) => {
-      const target = (event.target as HTMLElement).closest("a");
-
-      if (!target) {
-        console.warn("No anchor element found for click event", event);
-        return;
-      }
+    const handleClick = (event: MouseEvent) => {
+      if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      const target = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>(anchorSelector) : null;
+      if (!target) return;
 
       event.preventDefault();
+      event.stopPropagation();
 
       openConfirmModal({
         title: t("board.action.edit.confirmLeave.title"),
@@ -293,19 +259,14 @@ const usePreventLeaveWithDirty = (isDirty: boolean) => {
       event.returnValue = true;
     };
 
-    const anchors = document.querySelectorAll(anchorSelector);
-    anchors.forEach((link) => {
-      link.addEventListener("click", handleClick);
-    });
+    document.addEventListener("click", handleClick, true);
     window.addEventListener("popstate", handlePopState);
     window.addEventListener("beforeunload", handleBeforeUnload);
 
     return () => {
-      anchors.forEach((link) => {
-        link.removeEventListener("click", handleClick);
-      });
+      document.removeEventListener("click", handleClick, true);
       window.removeEventListener("popstate", handlePopState);
       window.removeEventListener("beforeunload", handleBeforeUnload);
     };
-  }, [isDirty]);
+  }, [isDirty, openConfirmModal, router, t]);
 };

apps/nextjs/src/app/[locale]/boards/(content)/_integration-provider.spec.ts

@@ -0,0 +1,54 @@
+import { createElement, act } from "react";
+import { createRoot } from "react-dom/client";
+import type { Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { BoardIntegrationProvider } from "./_integration-provider";
+
+const mocks = vi.hoisted(() => ({
+  providedIntegrations: undefined as unknown,
+}));
+
+vi.mock("@homarr/auth/client", async () => {
+  const React = await import("react");
+
+  return {
+    IntegrationProvider: ({ children, integrations }: { children: React.ReactNode; integrations: unknown }) => {
+      mocks.providedIntegrations = integrations;
+      return React.createElement(React.Fragment, null, children);
+    },
+  };
+});
+
+describe("board integration provider", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    mocks.providedIntegrations = undefined;
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  test("provides the permission-filtered server result without a second client query", () => {
+    const initialIntegrations = [{ id: "initial" }];
+
+    act(() => {
+      root.render(
+        createElement(
+          BoardIntegrationProvider,
+          { initialIntegrations: initialIntegrations as never },
+          createElement("span", null, "board"),
+        ),
+      );
+    });
+
+    expect(mocks.providedIntegrations).toBe(initialIntegrations);
+  });
+});

apps/nextjs/src/app/[locale]/boards/(content)/_integration-provider.tsx

@@ -0,0 +1,14 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+
+import type { RouterOutputs } from "@homarr/api";
+import { IntegrationProvider } from "@homarr/auth/client";
+
+interface Props {
+  initialIntegrations: RouterOutputs["integration"]["all"];
+}
+
+export const BoardIntegrationProvider = ({ initialIntegrations, children }: PropsWithChildren<Props>) => {
+  return <IntegrationProvider integrations={initialIntegrations}>{children}</IntegrationProvider>;
+};

apps/nextjs/src/app/[locale]/boards/[name]/settings/_layout.module.css

@@ -0,0 +1,47 @@
+.gutterSettings {
+  background: color-mix(in srgb, var(--mantine-color-default) 55%, transparent);
+}
+
+.gutterPreview {
+  display: grid;
+  gap: 6px;
+  width: 100%;
+  min-height: 112px;
+  padding: 8px;
+  overflow: hidden;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-md);
+  transition: grid-template-columns 180ms ease-out;
+}
+
+.previewCanvas {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 6px;
+  min-width: 0;
+}
+
+.previewCanvas > div,
+.previewGutter {
+  background: var(--mantine-color-default);
+  border-radius: var(--mantine-radius-sm);
+}
+
+.previewCanvas > div:nth-child(1) {
+  grid-row: span 2;
+}
+
+.previewCanvas > div:nth-child(4) {
+  grid-column: span 2;
+}
+
+.previewGutter {
+  min-width: 12px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .gutterPreview {
+    transition: none;
+  }
+}

apps/nextjs/src/app/[locale]/boards/[name]/settings/_layout.tsx

@@ -1,6 +1,20 @@
 "use client";
 
-import { Button, Fieldset, Grid, Group, Input, NumberInput, Slider, Stack, Text, TextInput } from "@mantine/core";
+import {
+  Box,
+  Button,
+  Fieldset,
+  Grid,
+  Group,
+  Input,
+  NumberInput,
+  Paper,
+  Slider,
+  Stack,
+  Switch,
+  Text,
+  TextInput,
+} from "@mantine/core";
 
 import { createId } from "@homarr/common";
 import type { UseFormReturnType } from "@homarr/form";
@@ -8,6 +22,7 @@ import { useI18n } from "@homarr/translation/client";
 
 import { SectionCard } from "~/components/manage/section-card";
 import type { FormValues } from "./_settings-form";
+import classes from "./_layout.module.css";
 
 interface Props {
   form: UseFormReturnType<FormValues>;
@@ -27,7 +42,17 @@ export const LayoutSettingsContent = ({ form }: Props) => {
             onClick={() => {
               form.setValues((previous) => ({
                 ...previous,
-                layouts: [...(previous.layouts ?? []), { id: createId(), name: "", columnCount: 10, breakpoint: 0 }],
+                layouts: [
+                  ...(previous.layouts ?? []),
+                  {
+                    id: createId(),
+                    name: "",
+                    columnCount: 10,
+                    leftGutterColumnCount: 0,
+                    rightGutterColumnCount: 0,
+                    breakpoint: 0,
+                  },
+                ],
               }));
             }}
           >
@@ -44,7 +69,21 @@ export const LayoutSettingsContent = ({ form }: Props) => {
 
               <Grid.Col span={{ sm: 12, md: 6 }}>
                 <Input.Wrapper label={t("layout.field.columnCount.label")}>
-                  <Slider mt="xs" min={1} max={24} step={1} {...form.getInputProps(`layouts.${index}.columnCount`)} />
+                  <Slider
+                    mt="xs"
+                    min={1}
+                    max={24}
+                    step={1}
+                    value={layout.columnCount}
+                    thumbLabel={t("layout.field.columnCount.label")}
+                    onChange={(columnCount) => {
+                      const left = Math.min(layout.leftGutterColumnCount, Math.max(0, columnCount - 1));
+                      const right = Math.min(layout.rightGutterColumnCount, Math.max(0, columnCount - left - 1));
+                      form.setFieldValue(`layouts.${index}.columnCount`, columnCount);
+                      form.setFieldValue(`layouts.${index}.leftGutterColumnCount`, left);
+                      form.setFieldValue(`layouts.${index}.rightGutterColumnCount`, right);
+                    }}
+                  />
                 </Input.Wrapper>
               </Grid.Col>
 
@@ -55,6 +94,15 @@ export const LayoutSettingsContent = ({ form }: Props) => {
                   description={t("layout.field.breakpoint.description")}
                 />
               </Grid.Col>
+              <Grid.Col span={12}>
+                <GutterSettings
+                  left={layout.leftGutterColumnCount}
+                  right={layout.rightGutterColumnCount}
+                  columnCount={layout.columnCount}
+                  onLeftChange={(value) => form.setFieldValue(`layouts.${index}.leftGutterColumnCount`, value)}
+                  onRightChange={(value) => form.setFieldValue(`layouts.${index}.rightGutterColumnCount`, value)}
+                />
+              </Grid.Col>
             </Grid>
             {form.values.layouts.length >= 2 && (
               <Group justify="end">
@@ -78,3 +126,123 @@ export const LayoutSettingsContent = ({ form }: Props) => {
     </SectionCard>
   );
 };
+
+interface GutterSettingsProps {
+  left: number;
+  right: number;
+  columnCount: number;
+  onLeftChange: (value: number) => void;
+  onRightChange: (value: number) => void;
+}
+
+const gutterMarks = [
+  { value: 1, label: "1" },
+  { value: 2, label: "2" },
+  { value: 3, label: "3" },
+];
+
+const GutterSettings = ({ left, right, columnCount, onLeftChange, onRightChange }: GutterSettingsProps) => {
+  const t = useI18n();
+  const maxGutterWidth = Math.min(3, Math.max(1, columnCount - 1));
+
+  return (
+    <Paper className={classes.gutterSettings} p="md">
+      <Stack gap="md">
+        <Box>
+          <Text fw={600}>{t("layout.field.gutters.label")}</Text>
+          <Text size="sm" c="dimmed">
+            {t("layout.field.gutters.description")}
+          </Text>
+        </Box>
+
+        <GutterPreview left={left} right={right} columnCount={columnCount} />
+
+        <Grid>
+          <Grid.Col span={{ base: 12, md: 6 }}>
+            <GutterControl
+              side="left"
+              value={left}
+              max={Math.min(maxGutterWidth, columnCount - right - 1)}
+              onChange={onLeftChange}
+            />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, md: 6 }}>
+            <GutterControl
+              side="right"
+              value={right}
+              max={Math.min(maxGutterWidth, columnCount - left - 1)}
+              onChange={onRightChange}
+            />
+          </Grid.Col>
+        </Grid>
+      </Stack>
+    </Paper>
+  );
+};
+
+const GutterControl = ({
+  side,
+  value,
+  max,
+  onChange,
+}: {
+  side: "left" | "right";
+  value: number;
+  max: number;
+  onChange: (value: number) => void;
+}) => {
+  const t = useI18n();
+  const enabled = value > 0;
+
+  return (
+    <Stack gap="sm">
+      <Switch
+        checked={enabled}
+        disabled={max < 1}
+        onChange={(event) => onChange(event.currentTarget.checked ? Math.min(2, max) : 0)}
+        label={t(`layout.field.gutters.${side}.label`)}
+        description={t(`layout.field.gutters.${side}.description`)}
+      />
+      {enabled && (
+        <Input.Wrapper label={t("layout.field.gutters.width.label")}>
+          <Slider
+            mt="xs"
+            min={1}
+            max={max}
+            value={Math.min(value, max)}
+            marks={gutterMarks.filter((mark) => mark.value <= max)}
+            restrictToMarks
+            thumbLabel={t(`layout.field.gutters.${side}.thumbLabel`)}
+            onChange={(nextValue) => onChange(Math.min(nextValue, max))}
+          />
+        </Input.Wrapper>
+      )}
+    </Stack>
+  );
+};
+
+const GutterPreview = ({ left, right, columnCount }: { left: number; right: number; columnCount: number }) => {
+  const t = useI18n();
+  const safeColumnCount = Math.max(1, columnCount);
+  const main = Math.max(1, safeColumnCount - left - right);
+  const tracks = [left > 0 ? `${left}fr` : null, `${main}fr`, right > 0 ? `${right}fr` : null]
+    .filter((track) => track !== null)
+    .join(" ");
+
+  return (
+    <Box
+      className={classes.gutterPreview}
+      aria-label={t("layout.field.gutters.preview.label")}
+      style={{ gridTemplateColumns: tracks }}
+    >
+      {left > 0 && <Box className={classes.previewGutter} data-side="left" />}
+      <Box className={classes.previewCanvas}>
+        <Box />
+        <Box />
+        <Box />
+        <Box />
+      </Box>
+      {right > 0 && <Box className={classes.previewGutter} data-side="right" />}
+    </Box>
+  );
+};

apps/nextjs/src/app/[locale]/boards/_layout-creator.tsx

@@ -1,4 +1,5 @@
 import type { JSX, PropsWithChildren } from "react";
+import { cookies, headers } from "next/headers";
 import { notFound, redirect } from "next/navigation";
 import { AppShellMain } from "@mantine/core";
 import { TRPCError } from "@trpc/server";
@@ -6,6 +7,7 @@ import { TRPCError } from "@trpc/server";
 import { auth } from "@homarr/auth/next";
 import { BoardProvider } from "@homarr/boards/context";
 import { EditModeProvider } from "@homarr/boards/edit-mode";
+import { boardViewportWidthCookieName, getLayoutIdForViewportWidth } from "@homarr/boards/layout-selection";
 import { createLogger } from "@homarr/core/infrastructure/logs";
 import { ModalProvider } from "@homarr/modals";
 
@@ -63,9 +65,15 @@ export const createBoardLayout = <TParams extends Params>({
       throw error;
     });
     const colorScheme = await getCurrentColorSchemeAsync();
+    const initialViewportWidth = await getInitialViewportWidthAsync();
+    const initialLayoutId = getLayoutIdForViewportWidth(initialBoard.layouts, initialViewportWidth);
 
     return (
-      <BoardProvider initialBoard={initialBoard}>
+      <BoardProvider
+        initialBoard={initialBoard}
+        initialLayoutId={initialLayoutId}
+        initialViewportWidth={initialViewportWidth}
+      >
         <BoardReadyProvider>
           <EditModeProvider>
             <BoardMantineProvider defaultColorScheme={colorScheme}>
@@ -91,3 +99,22 @@ export const createBoardLayout = <TParams extends Params>({
 
   return Layout;
 };
+
+const getInitialViewportWidthAsync = async () => {
+  const cookieValue = (await cookies()).get(boardViewportWidthCookieName)?.value;
+  const cookieWidth = Number(cookieValue);
+  if (Number.isInteger(cookieWidth) && cookieWidth >= 200 && cookieWidth <= 10_000) {
+    return cookieWidth;
+  }
+
+  const requestHeaders = await headers();
+  const clientHintWidth = Number(requestHeaders.get("sec-ch-viewport-width"));
+  if (Number.isInteger(clientHintWidth) && clientHintWidth >= 200 && clientHintWidth <= 10_000) {
+    return clientHintWidth;
+  }
+
+  const userAgent = requestHeaders.get("user-agent") ?? "";
+  if (/iPad|Tablet|PlayBook|Silk/i.test(userAgent)) return 1024;
+  if (/Mobi|Android|iPhone|iPod|IEMobile|Opera Mini/i.test(userAgent)) return 390;
+  return 1440;
+};

apps/nextjs/src/app/[locale]/layout.tsx

@@ -32,6 +32,7 @@ import { env } from "~/env";
 
 import { SearchEngineOptimization } from "~/components/layout/search-engine-optimization";
 import { ServiceWorkerRegistration } from "~/components/layout/service-worker-registration";
+import { ViewportHint } from "~/components/layout/viewport-hint";
 import { getCurrentColorSchemeAsync } from "~/theme/color-scheme";
 import { DayJsLoader } from "./_client-providers/dayjs-loader";
 import { JotaiProvider } from "./_client-providers/jotai";
@@ -154,6 +155,7 @@ export default async function Layout(props: {
       </head>
       <body className={[fontSans.className, fontSans.variable].join(" ")} suppressHydrationWarning>
         <Analytics enabled={serverSettings.analytics.enableGeneral} />
+        <ViewportHint />
         <StackedProvider>
           <Notifications pauseResetOnHover="notification" />
           <ServiceWorkerRegistration />

apps/nextjs/src/components/board/items/actions/create-item.ts

@@ -1,10 +1,12 @@
 import { getBoardLayouts } from "@homarr/boards/context";
 import { createId } from "@homarr/common";
 import type { Modify } from "@homarr/common/types";
+import { getRootSectionLane } from "@homarr/definitions";
 import type { WidgetKind } from "@homarr/definitions";
 import { widgetDefaultSizes } from "@homarr/definitions";
 
 import type { Board, EmptySection, Item, ItemLayout } from "~/app/[locale]/boards/_types";
+import { getBoardLaneColumnCount } from "~/components/board/layout";
 import { getFirstEmptyPosition } from "./empty-position";
 import { getSectionElements } from "./section-elements";
 
@@ -19,17 +21,21 @@ export const createItemCallback =
   ({ id, kind, options = {}, integrationIds = [] }: CreateItemInput) =>
   (previous: Board): Board => {
     const firstSection = previous.sections
-      .filter((section): section is EmptySection => section.kind === "empty")
+      .filter(
+        (section): section is EmptySection =>
+          section.kind === "empty" && getRootSectionLane(section.xOffset) === "main",
+      )
       .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset)
       .at(0);
 
     if (!firstSection) return previous;
 
+    const itemLayouts = createItemLayouts(previous, firstSection, kind);
     const widget = {
       id: id ?? createId(),
       kind,
       options,
-      layouts: createItemLayouts(previous, firstSection, kind),
+      layouts: itemLayouts,
       integrationIds,
       advancedOptions: {
         title: null,
@@ -60,9 +66,14 @@ const createItemLayouts = (board: Board, currentSection: EmptySection, kind: Wid
   return layouts.map((layoutId) => {
     const boardLayout = board.layouts.find((layout) => layout.id === layoutId);
     const elements = getSectionElements(board, { sectionId: currentSection.id, layoutId });
+    const columnCount = boardLayout ? getBoardLaneColumnCount(boardLayout, "main") : itemSize.width;
+    const size = {
+      width: Math.min(itemSize.width, columnCount),
+      height: itemSize.height,
+    };
 
     const emptyPosition = boardLayout
-      ? getFirstEmptyPosition(elements, boardLayout.columnCount, 9999, itemSize)
+      ? getFirstEmptyPosition(elements, columnCount, undefined, size)
       : { xOffset: 0, yOffset: 0 };
 
     if (!emptyPosition) {
@@ -70,8 +81,8 @@ const createItemLayouts = (board: Board, currentSection: EmptySection, kind: Wid
     }
 
     return {
-      width: itemSize.width,
-      height: itemSize.height,
+      width: size.width,
+      height: size.height,
       ...emptyPosition,
       sectionId: currentSection.id,
       layoutId,

apps/nextjs/src/components/board/items/actions/duplicate-item.ts

@@ -1,6 +1,8 @@
 import { createId } from "@homarr/common";
+import { getRootSectionLane } from "@homarr/definitions";
 
 import type { Board, EmptySection, ItemLayout, Section } from "~/app/[locale]/boards/_types";
+import { getBoardLaneColumnCount } from "~/components/board/layout";
 import { getFirstEmptyPosition } from "./empty-position";
 import { getSectionElements } from "./section-elements";
 
@@ -15,16 +17,17 @@ export const duplicateItemCallback =
     if (!itemToDuplicate) return previous;
 
     const clonedItem = structuredClone(itemToDuplicate);
+    const clonedLayouts = clonedItem.layouts.map((layout) => ({
+      ...layout,
+      ...getNextPosition(previous, layout),
+    }));
 
     return {
       ...previous,
       items: previous.items.concat({
         ...clonedItem,
         id: createId(),
-        layouts: clonedItem.layouts.map((layout) => ({
-          ...layout,
-          ...getNextPosition(previous, layout),
-        })),
+        layouts: clonedLayouts,
       }),
     };
   };
@@ -42,8 +45,10 @@ const getNextPosition = (board: Board, layout: ItemLayout): { xOffset: number; y
   }
 
   const firstSection = board.sections
-    .filter((section): section is EmptySection => section.kind === "empty")
-    .sort((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset)
+    .filter(
+      (section): section is EmptySection => section.kind === "empty" && getRootSectionLane(section.xOffset) === "main",
+    )
+    .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset)
     .at(0);
 
   if (!firstSection) {
@@ -67,18 +72,24 @@ const getEmptySectionPosition = (
   layout: ItemLayout,
   section: Section,
 ): { xOffset: number; yOffset: number } | undefined => {
-  const boardLayout = board.layouts.find((boardLayout) => boardLayout.id === layout.layoutId);
+  const boardLayout = board.layouts.find((candidate) => candidate.id === layout.layoutId);
   if (!boardLayout) return;
 
-  const sectionElements = getSectionElements(board, { sectionId: layout.sectionId, layoutId: layout.layoutId });
+  const sectionElements = getSectionElements(board, { sectionId: section.id, layoutId: layout.layoutId });
   if (section.kind !== "dynamic") {
-    return getFirstEmptyPosition(sectionElements, boardLayout.columnCount, undefined, {
+    const columnCount =
+      section.kind === "empty"
+        ? getBoardLaneColumnCount(boardLayout, getRootSectionLane(section.xOffset))
+        : boardLayout.columnCount;
+
+    const size = {
       width: layout.width,
       height: layout.height,
-    });
+    };
+    return getFirstEmptyPosition(sectionElements, columnCount, undefined, size);
   }
 
-  const sectionLayout = section.layouts.find((sectionLayout) => sectionLayout.layoutId === layout.layoutId);
+  const sectionLayout = section.layouts.find((candidate) => candidate.layoutId === layout.layoutId);
   if (!sectionLayout) return;
 
   return getFirstEmptyPosition(sectionElements, sectionLayout.width, sectionLayout.height, {

apps/nextjs/src/components/board/items/actions/empty-position.ts

@@ -7,7 +7,7 @@ export const getFirstEmptyPosition = (
   size: { width: number; height: number } = { width: 1, height: 1 },
 ) => {
   for (let yOffset = 0; yOffset < rowCount + 1 - size.height; yOffset++) {
-    for (let xOffset = 0; xOffset < columnCount; xOffset++) {
+    for (let xOffset = 0; xOffset < columnCount + 1 - size.width; xOffset++) {
       const isOccupied = elements.some(
         (element) =>
           element.yOffset < yOffset + size.height &&

apps/nextjs/src/components/board/items/actions/test/create-item.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, vi } from "vitest";
+import { afterEach, describe, expect, test, vi } from "vitest";
 
 import * as boardContext from "@homarr/boards/context";
 
@@ -10,6 +10,10 @@ import { ItemMockBuilder } from "./mocks/item-mock";
 import { LayoutMockBuilder } from "./mocks/layout-mock";
 
 describe("item actions create-item", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   test("should add it to first section", () => {
     // Arrange
     const itemKind = "clock";
@@ -52,7 +56,7 @@ describe("item actions create-item", () => {
         ],
       }),
     );
-    expect(emptyPositionSpy).toHaveBeenCalledWith([], layout.columnCount, 9999, { height: 1, width: 1 });
+    expect(emptyPositionSpy).toHaveBeenCalledWith([], layout.columnCount, undefined, { height: 1, width: 1 });
   });
   test("should correctly pass dynamic section and items to getFirstEmptyPosition", () => {
     // Arrange
@@ -94,8 +98,10 @@ describe("item actions create-item", () => {
 
     // Assert
     expect(result.items.length).toBe(3);
-    const item = result.items.find((item) => item.id !== itemInFirstSection.id && item.id !== otherItem.id);
-    expect(item).toEqual(
+    const createdItem = result.items.find(
+      (candidate) => candidate.id !== itemInFirstSection.id && candidate.id !== otherItem.id,
+    );
+    expect(createdItem).toEqual(
       expect.objectContaining({
         kind: itemKind,
         layouts: [{ ...emptyPosition, height: 1, width: 1, sectionId: firstSectionId, layoutId }],
@@ -104,8 +110,35 @@ describe("item actions create-item", () => {
     expect(spy).toHaveBeenCalledWith(
       [expect.objectContaining(itemAndSectionPosition), expect.objectContaining(itemAndSectionPosition)],
       layout.columnCount,
-      9999,
+      undefined,
       { height: 1, width: 1 },
     );
   });
+
+  test("clamps wide defaults and places below a full automatic canvas", () => {
+    const board = new BoardMockBuilder().addEmptySection({ id: "canvas", yOffset: 0 }).build();
+    const layout = board.layouts[0];
+    if (!layout) throw new Error("Expected a board layout");
+    layout.id = "layout";
+    layout.columnCount = 1;
+    board.items.push(
+      new ItemMockBuilder({ id: "existing" })
+        .addLayout({ layoutId: layout.id, sectionId: "canvas", width: 1, height: 1 })
+        .build(),
+    );
+
+    const result = createItemCallback({ id: "created", kind: "mediaMissing" })(board);
+    const created = result.items.find((item) => item.id === "created");
+
+    expect(created?.layouts).toEqual([
+      expect.objectContaining({
+        layoutId: layout.id,
+        sectionId: "canvas",
+        width: 1,
+        height: 3,
+        xOffset: 0,
+        yOffset: 1,
+      }),
+    ]);
+  });
 });

apps/nextjs/src/components/board/items/actions/test/duplicate-item.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, vi } from "vitest";
+import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { duplicateItemCallback } from "../duplicate-item";
 import * as emptyPositionModule from "../empty-position";
@@ -7,6 +7,10 @@ import { ItemMockBuilder } from "./mocks/item-mock";
 import { LayoutMockBuilder } from "./mocks/layout-mock";
 
 describe("item actions duplicate-item", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   test("should copy it in the same section", () => {
     // Arrange
     const itemKind = "minecraftServerStatus";
@@ -61,4 +65,28 @@ describe("item actions duplicate-item", () => {
       }),
     );
   });
+
+  test("uses the next automatic canvas row when it is the first available space", () => {
+    const board = new BoardMockBuilder().addEmptySection({ id: "canvas", yOffset: 0 }).build();
+    const layout = board.layouts[0];
+    if (!layout) throw new Error("Expected a board layout");
+    layout.id = "layout";
+    layout.columnCount = 1;
+    const currentItem = new ItemMockBuilder({ id: "source" })
+      .addLayout({ layoutId: layout.id, sectionId: "canvas", width: 1, height: 1 })
+      .build();
+    board.items.push(currentItem);
+
+    const result = duplicateItemCallback({ itemId: currentItem.id })(board);
+    const duplicated = result.items.find((item) => item.id !== currentItem.id);
+
+    expect(duplicated?.layouts[0]).toEqual(
+      expect.objectContaining({
+        layoutId: layout.id,
+        sectionId: "canvas",
+        xOffset: 0,
+        yOffset: 1,
+      }),
+    );
+  });
 });

apps/nextjs/src/components/board/items/actions/test/item-move-targets.spec.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "vitest";
+
+import { getMoveTargets } from "../../item-move-modal";
+import { BoardMockBuilder } from "./mocks/board-mock";
+import { DynamicSectionMockBuilder } from "./mocks/dynamic-section-mock";
+import { EmptySectionMockBuilder } from "./mocks/empty-section-mock";
+import { ItemMockBuilder } from "./mocks/item-mock";
+
+describe("item move targets", () => {
+  test("offers the canvas, enabled gutters, and nested sections", () => {
+    const board = new BoardMockBuilder().build();
+    const layout = board.layouts[0];
+    if (!layout) throw new Error("Expected the board mock to contain a layout");
+    layout.id = "layout";
+    layout.columnCount = 6;
+    layout.leftGutterColumnCount = 1;
+    layout.rightGutterColumnCount = 1;
+
+    board.sections.push(
+      new EmptySectionMockBuilder({ id: "canvas", xOffset: 0 }).build(),
+      new EmptySectionMockBuilder({ id: "left-gutter", xOffset: -1 }).build(),
+      new EmptySectionMockBuilder({ id: "right-gutter", xOffset: 1 }).build(),
+      new DynamicSectionMockBuilder({
+        id: "dynamic",
+        options: {
+          title: "",
+          customCssClasses: [],
+          borderColor: "",
+          showLabel: true,
+          collapsible: false,
+          showOpenAll: false,
+        },
+      })
+        .addLayout({
+          layoutId: layout.id,
+          parentSectionId: "canvas",
+          width: 2,
+          height: 2,
+        })
+        .build(),
+    );
+
+    const targets = getMoveTargets(
+      board,
+      layout.id,
+      {
+        id: "weather",
+        type: "item",
+        xOffset: 0,
+        yOffset: 0,
+        width: 1,
+        height: 1,
+      },
+      {
+        canvas: "Dashboard canvas",
+        dynamicSection: "New section",
+        leftRail: "Left dashboard rail",
+        rightRail: "Right dashboard rail",
+        numbered: (name, index) => `${name}, destination ${index}`,
+        located: (name, location, index) => `${name}, ${location}, destination ${index}`,
+      },
+    );
+
+    expect(targets.map((target) => target.label)).toEqual([
+      "Dashboard canvas, destination 1",
+      "Left dashboard rail, destination 2",
+      "Right dashboard rail, destination 3",
+      "New section, destination 4",
+    ]);
+    expect(new Set(targets.map((target) => target.label))).toHaveLength(targets.length);
+  });
+
+  test("does not offer canvases that are narrower than a nested section's contents", () => {
+    const board = new BoardMockBuilder().build();
+    const layout = board.layouts[0];
+    if (!layout) throw new Error("Expected the board mock to contain a layout");
+    layout.id = "layout";
+    layout.columnCount = 5;
+    layout.leftGutterColumnCount = 2;
+
+    const section = new DynamicSectionMockBuilder({ id: "source" })
+      .addLayout({
+        layoutId: layout.id,
+        parentSectionId: "canvas",
+        width: 4,
+        height: 2,
+      })
+      .build();
+    board.sections.push(
+      new EmptySectionMockBuilder({ id: "canvas" }).build(),
+      new EmptySectionMockBuilder({ id: "left-gutter", xOffset: -1 }).build(),
+      section,
+    );
+    board.items.push(
+      new ItemMockBuilder({ id: "nested" })
+        .addLayout({
+          layoutId: layout.id,
+          sectionId: section.id,
+          xOffset: 2,
+          width: 2,
+        })
+        .build(),
+    );
+
+    const sourceLayout = section.layouts[0];
+    if (!sourceLayout) throw new Error("Expected the source section to contain a layout");
+    const targets = getMoveTargets(
+      board,
+      layout.id,
+      { ...sourceLayout, id: section.id, type: "section" },
+      {
+        canvas: "Canvas",
+        dynamicSection: "Section",
+        leftRail: "Left",
+        rightRail: "Right",
+        numbered: (name, index) => `${name} ${index}`,
+        located: (name, location, index) => `${name} ${location} ${index}`,
+      },
+    );
+
+    expect(targets).toEqual([]);
+  });
+});

apps/nextjs/src/components/board/items/actions/test/mocks/board-mock.ts

@@ -45,6 +45,8 @@ export class BoardMockBuilder {
           id: createId(),
           name: "Base",
           columnCount: 12,
+          leftGutterColumnCount: 0,
+          rightGutterColumnCount: 0,
           breakpoint: 0,
         },
       ],

apps/nextjs/src/components/board/items/actions/test/mocks/category-section-mock.ts

@@ -1,23 +0,0 @@
-import { createId } from "@homarr/common";
-
-import type { CategorySection } from "~/app/[locale]/boards/_types";
-
-export class CategorySectionMockBuilder {
-  private readonly section: CategorySection;
-
-  constructor(section?: Partial<CategorySection>) {
-    this.section = {
-      id: createId(),
-      kind: "category",
-      xOffset: 0,
-      yOffset: 0,
-      name: "Category",
-      collapsed: false,
-      ...section,
-    } satisfies CategorySection;
-  }
-
-  public build(): CategorySection {
-    return this.section;
-  }
-}

apps/nextjs/src/components/board/items/actions/test/mocks/dynamic-section-mock.ts

@@ -1,21 +1,23 @@
 import { createId } from "@homarr/common";
+import { dynamicSectionOptionsSchema } from "@homarr/validation/shared";
 
 import type { DynamicSection } from "~/app/[locale]/boards/_types";
 
+type DynamicSectionMock = Omit<Partial<DynamicSection>, "options"> & {
+  options?: Partial<DynamicSection["options"]>;
+};
+
 export class DynamicSectionMockBuilder {
   private readonly section: DynamicSection;
 
-  constructor(section?: Partial<DynamicSection>) {
+  constructor(section?: DynamicSectionMock) {
     this.section = {
       id: createId(),
       kind: "dynamic",
-      options: {
-        title: "",
-        borderColor: "",
-        customCssClasses: [],
-      },
       layouts: [],
       ...section,
+      collapsed: section?.collapsed ?? false,
+      options: dynamicSectionOptionsSchema.parse(section?.options),
     } satisfies DynamicSection;
   }
 

apps/nextjs/src/components/board/items/actions/test/mocks/layout-mock.ts

@@ -10,6 +10,8 @@ export class LayoutMockBuilder {
       id: createId(),
       name: "Base",
       columnCount: 12,
+      leftGutterColumnCount: 0,
+      rightGutterColumnCount: 0,
       breakpoint: 0,
       ...layout,
     } satisfies Board["layouts"][0];

apps/nextjs/src/components/board/items/item-content.tsx

@@ -1,5 +1,6 @@
 import type { MutableRefObject } from "react";
 import { useRef } from "react";
+import dynamic from "next/dynamic";
 import { Badge, Card } from "@mantine/core";
 import { useElementSize } from "@mantine/hooks";
 import { QueryErrorResetBoundary, useQueryClient } from "@tanstack/react-query";
@@ -17,9 +18,12 @@ import type { SectionItem } from "~/app/[locale]/boards/_types";
 import classes from "../sections/item.module.css";
 import { useItemActions } from "./item-actions";
 import itemContentClasses from "./item-content.module.css";
-import { BoardItemMenu } from "./item-menu";
 import { WidgetContextMenu } from "./widget-context-menu";
 
+const BoardItemMenu = dynamic(() => import("./item-menu").then((module) => module.BoardItemMenu), {
+  ssr: false,
+});
+
 interface BoardItemContentProps {
   item: SectionItem;
 }
@@ -40,6 +44,9 @@ export const BoardItemContent = ({ item }: BoardItemContentProps) => {
       <WidgetContextMenu item={item} widgetStateRef={widgetStateRef}>
         <Card
           ref={ref}
+          w="100%"
+          h="100%"
+          data-grid-item-content
           className={combineClasses(
             classes.itemCard,
             `${item.kind}-wrapper`,
@@ -117,7 +124,7 @@ const InnerContent = ({ item, ...dimensions }: InnerContentProps) => {
           }}
           fallbackRender={({ resetErrorBoundary, error }) => (
             <>
-              <BoardItemMenu offset={4} item={newItem} resetErrorBoundary={resetErrorBoundary} />
+              {isEditMode && <BoardItemMenu offset={4} item={newItem} resetErrorBoundary={resetErrorBoundary} />}
               <WidgetError kind={item.kind} error={error} resetErrorBoundary={resetErrorBoundary} />
             </>
           )}
@@ -130,7 +137,7 @@ const InnerContent = ({ item, ...dimensions }: InnerContentProps) => {
               (!("integrationsRequired" in definition) || definition.integrationsRequired !== false)
             }
           />
-          <BoardItemMenu offset={4} item={newItem} />
+          {isEditMode && <BoardItemMenu offset={4} item={newItem} />}
           <Comp
             options={options as never}
             integrationIds={item.integrationIds}

apps/nextjs/src/components/board/items/item-menu.tsx

@@ -2,7 +2,6 @@ import { useEffect, useRef, useState } from "react";
 import { ActionIcon, Menu } from "@mantine/core";
 import { IconCopy, IconDotsVertical, IconLayoutKanban, IconPencil, IconTrash } from "@tabler/icons-react";
 
-import { clientApi } from "@homarr/api/client";
 import { useSession } from "@homarr/auth/client";
 import { useEditMode } from "@homarr/boards/edit-mode";
 import { useConfirmModal, useModalAction } from "@homarr/modals";
@@ -13,11 +12,10 @@ import type { WidgetDefinition } from "@homarr/widgets/definition";
 import type { SectionItem } from "~/app/[locale]/boards/_types";
 import { useSectionContext } from "../sections/section-context";
 import { useItemActions } from "./item-actions";
-import { LazyItemMoveModal, preloadItemMoveModal } from "./lazy-item-move-modal";
+import { useOpenItemMoveModal } from "./item-move-modal";
 import { LazyWidgetEditModal, preloadWidgetEditModal } from "./lazy-widget-edit-modal";
 
 interface BoardItemMenuProps {
-  offset: number;
   item: SectionItem;
   definition: WidgetDefinition;
   resetErrorBoundary?: () => void;
@@ -31,25 +29,21 @@ export const BoardItemMenu = (props: BoardItemMenuProps) => {
   return <BoardItemMenuInner {...props} />;
 };
 
-const BoardItemMenuInner = ({ offset, item, definition, resetErrorBoundary }: BoardItemMenuProps) => {
+const BoardItemMenuInner = ({ item, definition, resetErrorBoundary }: BoardItemMenuProps) => {
   const { data: session } = useSession();
   const canDuplicate = item.kind !== "customApi" || (session?.user.permissions.includes("admin") ?? false);
   const refResetErrorBoundaryOnNextRender = useRef(false);
   const tItem = useScopedI18n("item");
   const t = useI18n();
   const { openModal } = useModalAction(LazyWidgetEditModal);
-  const { openModal: openMoveModal } = useModalAction(LazyItemMoveModal);
+  const openMoveModal = useOpenItemMoveModal();
   const { openConfirmModal } = useConfirmModal();
   const [isMenuOpen, setIsMenuOpen] = useState(false);
-  const hasSupportedIntegrations =
-    "supportedIntegrations" in definition && (definition.supportedIntegrations?.length ?? 0) > 0;
   const { updateItemOptions, updateItemAdvancedOptions, updateItemIntegrations, duplicateItem, removeItem } =
     useItemActions();
-  const { data: integrationData, isPending } = clientApi.integration.all.useQuery(undefined, {
-    enabled: isMenuOpen && hasSupportedIntegrations,
-  });
-  const { gridstack } = useSectionContext().refs;
+  const { integrations: integrationData = [], section } = useSectionContext();
   const settings = useSettings();
+  const label = item.advancedOptions.title?.trim() || t(`widget.${item.kind}.name`);
 
   // Reset error boundary on next render if item has been edited
   useEffect(() => {
@@ -84,7 +78,7 @@ const BoardItemMenuInner = ({ offset, item, definition, resetErrorBoundary }: Bo
           });
           refResetErrorBoundaryOnNextRender.current = true;
         },
-        integrationData: (integrationData ?? []).filter(
+        integrationData: integrationData.filter(
           (integration) =>
             "supportedIntegrations" in definition &&
             (definition.supportedIntegrations as string[]).some((kind) => kind === integration.kind),
@@ -95,8 +89,8 @@ const BoardItemMenuInner = ({ offset, item, definition, resetErrorBoundary }: Bo
         appId: item.kind === "app" ? (item.options.appId as string | undefined) : undefined,
       },
       {
-        title(t) {
-          return `${t("item.edit.title")} - ${t(`widget.${item.kind}.name`)}`;
+        title(translate) {
+          return `${translate("item.edit.title")} - ${translate(`widget.${item.kind}.name`)}`;
         },
       },
     );
@@ -117,14 +111,16 @@ const BoardItemMenuInner = ({ offset, item, definition, resetErrorBoundary }: Bo
       <Menu.Target>
         <ActionIcon
           variant="default"
-          radius={"xl"}
+          size={24}
+          radius="sm"
           pos="absolute"
-          top={offset}
-          right={offset}
+          top={12}
+          right={8}
           style={{ zIndex: 10 }}
-          aria-label={tItem("menu.label.settings")}
+          data-board-widget-settings
+          aria-label={tItem("menu.label.settingsFor", { name: label })}
         >
-          <IconDotsVertical size={"1rem"} />
+          <IconDotsVertical size="1rem" />
         </ActionIcon>
       </Menu.Target>
       <Menu.Dropdown miw={128}>
@@ -134,24 +130,25 @@ const BoardItemMenuInner = ({ offset, item, definition, resetErrorBoundary }: Bo
           onClick={openEditModal}
           onFocus={preloadWidgetEditModal}
           onPointerEnter={preloadWidgetEditModal}
-          disabled={hasSupportedIntegrations && isPending}
         >
           {tItem("action.edit")}
         </Menu.Item>
         <Menu.Item
           leftSection={<IconLayoutKanban size={16} />}
-          onFocus={preloadItemMoveModal}
-          onPointerEnter={preloadItemMoveModal}
           onClick={() => {
-            if (!gridstack.current) return;
-            openMoveModal({ item, columnCount: gridstack.current.getColumn(), gridStack: gridstack.current });
+            openMoveModal({
+              entry: item,
+              sourceSectionId: section.id,
+            });
           }}
         >
           {tItem("action.moveResize")}
         </Menu.Item>
-        <Menu.Item leftSection={<IconCopy size={16} />} onClick={() => duplicateItem({ itemId: item.id })}>
-          {tItem("action.duplicate")}
-        </Menu.Item>
+        {canDuplicate && (
+          <Menu.Item leftSection={<IconCopy size={16} />} onClick={() => duplicateItem({ itemId: item.id })}>
+            {tItem("action.duplicate")}
+          </Menu.Item>
+        )}
         <Menu.Divider />
         <Menu.Label c="red.6">{t("common.dangerZone")}</Menu.Label>
         <Menu.Item c="red.6" leftSection={<IconTrash size={16} />} onClick={openRemoveModal}>

apps/nextjs/src/components/board/items/item-move-modal.tsx

@@ -1,94 +1,220 @@
-import { useCallback, useRef } from "react";
-import { Grid, NumberInput, Stack } from "@mantine/core";
+import { useCallback, useMemo } from "react";
+import { Grid, NumberInput, Select, Stack } from "@mantine/core";
 import { z } from "zod/v4";
 
+import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
+import { getRootSectionLane } from "@homarr/definitions";
 import { useZodForm } from "@homarr/form";
-import type { GridStack } from "@homarr/gridstack";
-import { createModal, ModalFormFooter, modalSizeForm } from "@homarr/modals";
-import { useI18n } from "@homarr/translation/client";
+import { createModal, ModalFormFooter, modalSizeForm, useModalAction } from "@homarr/modals";
+import { useScopedI18n } from "@homarr/translation/client";
 
-import type { Item, SectionItem } from "~/app/[locale]/boards/_types";
+import type { Board, ContainerSectionItem, SectionItem } from "~/app/[locale]/boards/_types";
+import { getLayoutRowCount } from "../layout";
+import { resolvePinnedGridCollisions } from "../sections/grid/dnd";
+import { getSectionGridColumnCount, getSectionGridPlacements } from "../sections/grid/section-grid-placements";
+import type { CommitSectionGridInput, SectionGridPlacement } from "../sections/grid/use-grid-layout-actions";
+import { useGridLayoutActions } from "../sections/grid/use-grid-layout-actions";
 
-export interface ItemMoveModalProps {
-  gridStack: GridStack;
-  item: Pick<SectionItem, "id" | "width" | "height" | "xOffset" | "yOffset">;
-  columnCount: number;
+export type MovableEntry = Pick<
+  SectionItem | ContainerSectionItem,
+  "id" | "type" | "width" | "height" | "xOffset" | "yOffset"
+>;
+
+export interface OpenItemMoveModalInput {
+  entry: MovableEntry;
+  sourceSectionId: string;
 }
 
-export const ItemMoveModal = createModal<ItemMoveModalProps>(({ actions, innerProps }) => {
-  const t = useI18n();
-  const maxWidthRef = useRef(innerProps.columnCount - innerProps.item.xOffset);
+interface InnerProps extends OpenItemMoveModalInput {
+  board: Board;
+  currentLayoutId: string;
+  commitSectionGrids: (snapshots: readonly CommitSectionGridInput[]) => void;
+}
+
+interface MoveTarget {
+  id: string;
+  label: string;
+  columnCount: number;
+  maxRowCount: number | null;
+}
+
+interface MoveTargetLabels {
+  canvas: string;
+  container: string;
+  leftRail: string;
+  rightRail: string;
+  numbered: (name: string, index: number) => string;
+  located: (name: string, location: string, index: number) => string;
+}
+
+type MoveTargetCandidate = Omit<MoveTarget, "label"> & {
+  name: string;
+  location?: string;
+};
+
+export const ItemMoveModal = createModal<InnerProps>(({ actions, innerProps }) => {
+  const tLandmark = useScopedI18n("board.landmark");
+  const tContainer = useScopedI18n("section.container");
+  const tMoveResize = useScopedI18n("item.moveResize");
+  const { board, commitSectionGrids, currentLayoutId, entry, sourceSectionId } = innerProps;
+  const minimumSize = useMemo(
+    () => getEntryMinimumSize(board, currentLayoutId, entry),
+    [board, currentLayoutId, entry],
+  );
+  const targets = useMemo(
+    () =>
+      getMoveTargets(board, currentLayoutId, entry, {
+        canvas: tLandmark("canvas"),
+        container: tContainer("action.create"),
+        leftRail: tLandmark("leftRail"),
+        rightRail: tLandmark("rightRail"),
+        numbered: (name, index) => tMoveResize("target.numbered", { name, index: String(index) }),
+        located: (name, location, index) =>
+          tMoveResize("target.located", {
+            name,
+            location,
+            index: String(index),
+          }),
+      }),
+    [board, currentLayoutId, entry, tContainer, tLandmark, tMoveResize],
+  );
+  const targetById = useMemo(() => new Map(targets.map((target) => [target.id, target])), [targets]);
+  const initialTarget = targetById.get(sourceSectionId) ?? targets[0];
+
+  if (!initialTarget) {
+    throw new Error("No valid dashboard section is available for this item");
+  }
+
   const form = useZodForm(
     z.object({
-      xOffset: z
-        .number()
-        .min(0)
-        .max(innerProps.columnCount - 1),
-      yOffset: z.number().min(0),
-      width: z.number().min(1).max(maxWidthRef.current),
-      height: z.number().min(1),
+      sectionId: z.string().min(1),
+      xOffset: z.number().int().min(0).max(32767),
+      yOffset: z.number().int().min(0).max(32767),
+      width: z.number().int().min(1).max(32767),
+      height: z.number().int().min(1).max(32767),
     }),
     {
       initialValues: {
-        xOffset: innerProps.item.xOffset,
-        yOffset: innerProps.item.yOffset,
-        width: innerProps.item.width,
-        height: innerProps.item.height,
-      },
-      onValuesChange(values, previous) {
-        if (values.xOffset !== previous.xOffset) {
-          maxWidthRef.current = innerProps.columnCount - values.xOffset;
-        }
+        sectionId: initialTarget.id,
+        xOffset: entry.xOffset,
+        yOffset: entry.yOffset,
+        width: entry.width,
+        height: entry.height,
       },
     },
   );
+  const selectedTarget = targetById.get(form.values.sectionId) ?? initialTarget;
 
   const handleSubmit = useCallback(
-    (values: Pick<Item["layouts"][number], "height" | "width" | "xOffset" | "yOffset">) => {
-      const gridItem = innerProps.gridStack
-        .getGridItems()
-        .find((item) => item.getAttribute("data-id") === innerProps.item.id);
-      if (!gridItem) return;
-      innerProps.gridStack.update(gridItem, {
-        h: values.height,
-        w: values.width,
-        x: values.xOffset,
+    (values: { sectionId: string; xOffset: number; yOffset: number; width: number; height: number }) => {
+      const target = targetById.get(values.sectionId);
+      if (!target) return;
+
+      const width = Math.max(minimumSize.width, Math.min(values.width, target.columnCount));
+      const height = Math.max(minimumSize.height, values.height);
+      const nextPlacement: SectionGridPlacement = {
+        id: entry.id,
+        type: entry.type,
+        x: Math.min(values.xOffset, target.columnCount - width),
         y: values.yOffset,
-      });
+        w: width,
+        h: height,
+      };
+      const targetPlacements = getSectionGridPlacements(board, currentLayoutId, target.id).filter(
+        (placement) => placement.id !== entry.id,
+      );
+      const resolvedTarget = resolvePinnedGridCollisions(
+        [...targetPlacements, nextPlacement],
+        nextPlacement,
+        target.columnCount,
+      );
+      if (target.maxRowCount !== null && getLayoutRowCount(resolvedTarget) > target.maxRowCount) {
+        form.setFieldError("height", tMoveResize("keyboard.boundary"));
+        return;
+      }
+
+      const snapshots =
+        sourceSectionId === target.id
+          ? [{ layoutId: currentLayoutId, sectionId: target.id, placements: resolvedTarget }]
+          : [
+              {
+                layoutId: currentLayoutId,
+                sectionId: sourceSectionId,
+                placements: getSectionGridPlacements(board, currentLayoutId, sourceSectionId).filter(
+                  (placement) => placement.id !== entry.id,
+                ),
+              },
+              { layoutId: currentLayoutId, sectionId: target.id, placements: resolvedTarget },
+            ];
+
+      commitSectionGrids(snapshots);
       actions.closeModal();
+      focusMovedEntry(entry.id, target.id);
     },
-    [actions, innerProps.gridStack, innerProps.item.id],
+    [
+      actions,
+      board,
+      commitSectionGrids,
+      currentLayoutId,
+      entry,
+      form,
+      minimumSize,
+      sourceSectionId,
+      targetById,
+      tMoveResize,
+    ],
   );
 
   return (
     <form onSubmit={form.onSubmit(handleSubmit, console.error)}>
       <Stack>
+        <Select
+          data={targets.map((target) => ({ value: target.id, label: target.label }))}
+          label={tMoveResize("field.section.label")}
+          data-autofocus
+          allowDeselect={false}
+          searchable
+          {...form.getInputProps("sectionId")}
+        />
         <Grid>
           <Grid.Col span={{ base: 12, md: 6 }}>
             <NumberInput
-              label={t("item.moveResize.field.xOffset.label")}
-              data-autofocus
+              label={tMoveResize("field.xOffset.label")}
               min={0}
-              max={innerProps.columnCount - 1}
+              max={selectedTarget.columnCount - 1}
               {...form.getInputProps("xOffset")}
             />
           </Grid.Col>
 
           <Grid.Col span={{ base: 12, md: 6 }}>
-            <NumberInput label={t("item.moveResize.field.yOffset.label")} min={0} {...form.getInputProps("yOffset")} />
+            <NumberInput
+              label={tMoveResize("field.yOffset.label")}
+              min={0}
+              max={selectedTarget.maxRowCount === null ? undefined : selectedTarget.maxRowCount - 1}
+              {...form.getInputProps("yOffset")}
+            />
           </Grid.Col>
 
           <Grid.Col span={{ base: 12, md: 6 }}>
             <NumberInput
-              label={t("item.moveResize.field.width.label")}
-              min={1}
-              max={innerProps.columnCount - form.values.xOffset}
+              label={tMoveResize("field.width.label")}
+              min={minimumSize.width}
+              max={selectedTarget.columnCount - Math.min(form.values.xOffset, selectedTarget.columnCount - 1)}
               {...form.getInputProps("width")}
             />
           </Grid.Col>
 
           <Grid.Col span={{ base: 12, md: 6 }}>
-            <NumberInput label={t("item.moveResize.field.height.label")} min={1} {...form.getInputProps("height")} />
+            <NumberInput
+              label={tMoveResize("field.height.label")}
+              min={minimumSize.height}
+              max={
+                selectedTarget.maxRowCount === null
+                  ? undefined
+                  : selectedTarget.maxRowCount - Math.min(form.values.yOffset, selectedTarget.maxRowCount - 1)
+              }
+              {...form.getInputProps("height")}
+            />
           </Grid.Col>
         </Grid>
         <ModalFormFooter onCancel={actions.closeModal} />
@@ -101,3 +227,137 @@ export const ItemMoveModal = createModal<ItemMoveModalProps>(({ actions, innerPr
   },
   size: modalSizeForm,
 });
+
+export const useOpenItemMoveModal = () => {
+  const board = useRequiredBoard();
+  const currentLayoutId = useCurrentLayout();
+  const { commitSectionGrids } = useGridLayoutActions();
+  const { openModal } = useModalAction(ItemMoveModal);
+
+  return useCallback(
+    (input: OpenItemMoveModalInput) => {
+      openModal({
+        ...input,
+        board,
+        currentLayoutId,
+        commitSectionGrids,
+      });
+    },
+    [board, commitSectionGrids, currentLayoutId, openModal],
+  );
+};
+
+export const getMoveTargets = (
+  board: Board,
+  layoutId: string,
+  entry: MovableEntry,
+  labels: MoveTargetLabels,
+): MoveTarget[] => {
+  const minimum = getEntryMinimumSize(board, layoutId, entry);
+
+  const candidates = board.sections.flatMap((section): MoveTargetCandidate[] => {
+    if (section.kind === "empty") {
+      const columnCount = getSectionColumnCount(board, layoutId, section.id);
+      const lane = getRootSectionLane(section.xOffset);
+      if (columnCount === 0) return [];
+      return minimum.width <= columnCount
+        ? [
+            {
+              id: section.id,
+              name: lane === "left" ? labels.leftRail : lane === "right" ? labels.rightRail : labels.canvas,
+              columnCount,
+              maxRowCount: getSectionMaxRowCount(board, layoutId, section.id),
+            },
+          ]
+        : [];
+    }
+
+    const layout = section.layouts.find((candidate) => candidate.layoutId === layoutId);
+    if (!layout) return [];
+    if (
+      (entry.type === "section" && isSameOrDescendant(board, layoutId, section.id, entry.id)) ||
+      minimum.width > layout.width ||
+      minimum.height > layout.height
+    ) {
+      return [];
+    }
+
+    return [
+      {
+        id: section.id,
+        name: section.options.title || labels.container,
+        columnCount: layout.width,
+        maxRowCount: layout.height,
+      },
+    ];
+  });
+
+  return candidates.map(({ name, location, ...target }, index) => ({
+    ...target,
+    label: location ? labels.located(name, location, index + 1) : labels.numbered(name, index + 1),
+  }));
+};
+
+const getSectionColumnCount = (board: Board, layoutId: string, sectionId: string) => {
+  const layout = board.layouts.find((candidate) => candidate.id === layoutId);
+  if (!layout) throw new Error(`Layout "${layoutId}" was not found`);
+  const section = board.sections.find((candidate) => candidate.id === sectionId);
+  if (!section) throw new Error(`Section "${sectionId}" was not found`);
+
+  const columnCount = getSectionGridColumnCount(board, layoutId, sectionId);
+  if (columnCount === null) throw new Error(`Section "${sectionId}" has no current layout`);
+  return columnCount;
+};
+
+const getSectionMaxRowCount = (board: Board, layoutId: string, sectionId: string) => {
+  const section = board.sections.find((candidate) => candidate.id === sectionId);
+  if (!section) return null;
+  if (section.kind === "container") {
+    return section.layouts.find((candidate) => candidate.layoutId === layoutId)?.height ?? null;
+  }
+  return null;
+};
+
+const getEntryMinimumSize = (board: Board, layoutId: string, entry: MovableEntry) => {
+  if (entry.type === "item") return { width: 1, height: 1 };
+  const children = getSectionGridPlacements(board, layoutId, entry.id);
+  return {
+    width: Math.max(1, ...children.map((child) => child.x + child.w)),
+    height: Math.max(1, ...children.map((child) => child.y + child.h)),
+  };
+};
+
+const isSameOrDescendant = (board: Board, layoutId: string, candidateId: string, ancestorId: string) => {
+  let current: string | undefined = candidateId;
+  const visited = new Set<string>();
+  while (current && !visited.has(current)) {
+    if (current === ancestorId) return true;
+    visited.add(current);
+    const section = board.sections.find((candidate) => candidate.id === current && candidate.kind === "container");
+    if (!section || section.kind !== "container") return false;
+    current = section.layouts.find((layout) => layout.layoutId === layoutId)?.parentSectionId;
+  }
+  return false;
+};
+
+const focusMovedEntry = (entryId: string, sectionId: string) => {
+  let attempts = 0;
+  const tryFocus = () => {
+    const section = Array.from(document.querySelectorAll<HTMLElement>("[data-grid-section-id]")).find(
+      (candidate) => candidate.dataset.gridSectionId === sectionId,
+    );
+    const entry = Array.from(section?.querySelectorAll<HTMLElement>(":scope > [data-grid-item-id]") ?? []).find(
+      (candidate) => candidate.dataset.gridItemId === entryId,
+    );
+    const editorEntry = entry?.querySelector<HTMLElement>("[data-editor-grid-entry]");
+    if (editorEntry) {
+      editorEntry.focus();
+      return;
+    }
+
+    attempts += 1;
+    if (attempts < 10) requestAnimationFrame(tryFocus);
+  };
+
+  requestAnimationFrame(tryFocus);
+};

apps/nextjs/src/components/board/items/item-select-modal.tsx

@@ -1,53 +1,68 @@
-import { useMemo, useState } from "react";
+import { useMemo, useRef, useState } from "react";
 import { Avatar, Box, Button, Card, Center, Divider, Group, Image, Stack, Text, Tooltip } from "@mantine/core";
 import { IconApi } from "@tabler/icons-react";
 
+import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { useSession } from "@homarr/auth/client";
-import { createId, objectEntries } from "@homarr/common";
-import { getIconUrl, getIntegrationName } from "@homarr/definitions";
+import { createId } from "@homarr/common";
+import { getIconUrl, getIntegrationName, widgetIntegrationSupport, widgetKinds } from "@homarr/definitions";
 import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
 import { createModal, modalSizeSelect, useModalAction } from "@homarr/modals";
+import { showErrorNotification } from "@homarr/notifications";
 import { useSettings } from "@homarr/settings";
 import { useI18n } from "@homarr/translation/client";
 import { SelectGridLayout, selectGridCardHeight } from "@homarr/ui";
 import type { TablerIcon } from "@homarr/ui";
-import { reduceWidgetOptionsWithDefaultValues, widgetImports } from "@homarr/widgets";
-import { WidgetEditModal } from "@homarr/widgets/modals";
+import { widgetCatalogIcons } from "@homarr/widgets/catalog";
+import { loadWidgetDefinition, reduceWidgetOptionsWithDefinition } from "@homarr/widgets/manifest";
 
 import { WorkshopInstallButton } from "~/components/workshop/workshop-install-button";
 import { useItemActions } from "./item-actions";
+import { resolveMatchingIntegrationsAsync, tryLockSelection, unlockSelection } from "./item-select-data";
+import { LazyWidgetEditModal, preloadWidgetEditModal } from "./lazy-widget-edit-modal";
+import classes from "./item-select-modal.module.css";
 
-export const ItemSelectModal = createModal<{ boardId: string }>(({ actions, innerProps }) => {
-  const { data: session } = useSession();
-  const isAdmin = session?.user.permissions.includes("admin") ?? false;
+interface ItemSelectModalContentProps {
+  actions: { closeModal: () => void };
+  integrationData: RouterOutputs["integration"]["all"] | undefined;
+  customWidgetDefs: RouterOutputs["customWidget"]["available"] | undefined;
+  ensureIntegrationDataAsync: () => Promise<RouterOutputs["integration"]["all"]>;
+  isAdmin: boolean;
+}
+
+const ItemSelectModalContent = ({
+  actions,
+  integrationData,
+  customWidgetDefs,
+  ensureIntegrationDataAsync,
+  isAdmin,
+}: ItemSelectModalContentProps) => {
   const [search, setSearch] = useState("");
+  const [loadingSelection, setLoadingSelection] = useState<string | null>(null);
+  const selectionLock = useRef(false);
   const t = useI18n();
   const { createItem, updateItemOptions, updateItemAdvancedOptions, updateItemIntegrations } = useItemActions();
-  const { openModal: openEditModal } = useModalAction(WidgetEditModal);
-  const { data: integrationData } = clientApi.integration.all.useQuery();
-  const { data: customWidgetDefs } = clientApi.customWidget.available.useQuery(
-    { boardId: innerProps.boardId },
-    { enabled: isAdmin },
-  );
+  const { openModal: openEditModal } = useModalAction(LazyWidgetEditModal);
   const settings = useSettings();
 
   const availableKinds = useMemo(() => new Set((integrationData ?? []).map((i) => i.kind)), [integrationData]);
 
   const items = useMemo(
     () =>
-      objectEntries(widgetImports)
-        .filter(([kind]) => kind !== "customApi")
-        .map(([kind, value]) => ({
-          kind,
-          supportedIntegrations:
-            "supportedIntegrations" in value.definition
-              ? value.definition.supportedIntegrations.filter((integration) => integration !== "mock")
-              : [],
-          icon: value.definition.icon,
-          name: t(`widget.${kind}.name`),
-          description: t(`widget.${kind}.description`),
-        }))
+      widgetKinds
+        .filter((kind) => kind !== "customApi")
+        .map((kind) => {
+          return {
+            kind,
+            supportedIntegrations: (widgetIntegrationSupport[kind] ?? []).filter(
+              (integration) => integration !== "mock",
+            ),
+            icon: widgetCatalogIcons[kind],
+            name: t(`widget.${kind}.name`),
+            description: t(`widget.${kind}.description`),
+          };
+        })
         .sort((itemA, itemB) => {
           if (itemA.kind === "app") return -1;
           if (itemB.kind === "app") return 1;
@@ -72,77 +87,108 @@ export const ItemSelectModal = createModal<{ boardId: string }>(({ actions, inne
     [customWidgetDefs, search],
   );
 
-  const handleAddCustomWidget = (definition: NonNullable<typeof customWidgetDefs>[number]) => {
-    const itemId = createId();
-    const defaultOptions = reduceWidgetOptionsWithDefaultValues("customApi", settings);
-    const options = {
-      ...defaultOptions,
-      definitionId: definition.id,
-      configuration: definition.defaultOptions,
-      configurationVersion: definition.updatedAt.getTime(),
-    };
-    actions.closeModal();
-    openEditModal(
-      {
-        kind: "customApi",
-        value: {
-          advancedOptions: { title: null, customCssClasses: [], borderColor: "" },
-          options,
-          integrationIds: [],
-        },
-        onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }) => {
-          createItem({ id: itemId, kind: "customApi", integrationIds: [] });
-          updateItemOptions({ itemId, newOptions: configuredOptions });
-          updateItemAdvancedOptions({ itemId, newAdvancedOptions: advancedOptions });
-        },
-        integrationData: [],
-        integrationSupport: false,
-        settings,
-      },
-      {
-        title: (titleT) => `${titleT("item.edit.title")} - ${definition.name}`,
-      },
-    );
+  const notifyDefinitionLoadError = (error: unknown) => {
+    showErrorNotification({
+      title: t("common.error"),
+      message: error instanceof Error ? error.message : String(error),
+    });
   };
 
-  const handleAdd = (kind: WidgetKind) => {
-    const definition = widgetImports[kind].definition;
-    const hasIntegrationSupport = "supportedIntegrations" in definition;
-
-    const matchingIntegrations = hasIntegrationSupport
-      ? (integrationData ?? []).filter((integration) =>
-          (definition.supportedIntegrations as string[]).includes(integration.kind),
-        )
-      : [];
-
-    const integrationIds = matchingIntegrations.map((i) => i.id);
-    const itemId = createId();
-    const defaultOptions = reduceWidgetOptionsWithDefaultValues(kind, settings);
-
-    createItem({ id: itemId, kind, integrationIds });
-    actions.closeModal();
-
-    openEditModal(
-      {
-        kind,
-        value: {
-          advancedOptions: { title: null, customCssClasses: [], borderColor: "" },
-          options: defaultOptions,
-          integrationIds,
+  const handleAddCustomWidget = async (customWidgetDefinition: NonNullable<typeof customWidgetDefs>[number]) => {
+    if (!tryLockSelection(selectionLock)) return;
+    setLoadingSelection(`custom:${customWidgetDefinition.id}`);
+    preloadWidgetEditModal();
+    try {
+      const definition = await loadWidgetDefinition("customApi");
+      const itemId = createId();
+      const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
+      const options = {
+        ...defaultOptions,
+        definitionId: customWidgetDefinition.id,
+        configuration: customWidgetDefinition.defaultOptions,
+        configurationVersion: customWidgetDefinition.updatedAt.getTime(),
+      };
+      actions.closeModal();
+      openEditModal(
+        {
+          kind: "customApi",
+          definition,
+          value: {
+            advancedOptions: { title: null, customCssClasses: [], borderColor: "" },
+            options,
+            integrationIds: [],
+          },
+          onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }) => {
+            createItem({ id: itemId, kind: "customApi", integrationIds: [] });
+            updateItemOptions({ itemId, newOptions: configuredOptions });
+            updateItemAdvancedOptions({ itemId, newAdvancedOptions: advancedOptions });
+          },
+          integrationData: [],
+          integrationSupport: false,
+          settings,
         },
-        onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }) => {
-          updateItemOptions({ itemId, newOptions: options });
-          updateItemAdvancedOptions({ itemId, newAdvancedOptions: advancedOptions });
-          updateItemIntegrations({ itemId, newIntegrations: newIntegrationIds });
+        {
+          title: (titleT) => `${titleT("item.edit.title")} - ${customWidgetDefinition.name}`,
         },
-        integrationData: matchingIntegrations,
-        integrationSupport: hasIntegrationSupport,
-        settings,
-      },
-      {
-        title: (titleT) => `${titleT("item.edit.title")} - ${titleT(`widget.${kind}.name`)}`,
-      },
-    );
+      );
+    } catch (error) {
+      notifyDefinitionLoadError(error);
+    } finally {
+      unlockSelection(selectionLock);
+      setLoadingSelection(null);
+    }
+  };
+
+  const handleAdd = async (kind: WidgetKind) => {
+    if (!tryLockSelection(selectionLock)) return;
+    setLoadingSelection(kind);
+    preloadWidgetEditModal();
+    try {
+      const definition = await loadWidgetDefinition(kind);
+      const hasIntegrationSupport = "supportedIntegrations" in definition;
+
+      const matchingIntegrations = await resolveMatchingIntegrationsAsync({
+        hasIntegrationSupport,
+        supportedIntegrations: definition.supportedIntegrations ?? [],
+        currentData: integrationData,
+        ensureDataAsync: ensureIntegrationDataAsync,
+      });
+
+      const integrationIds = matchingIntegrations.map((i) => i.id);
+      const itemId = createId();
+      const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
+
+      createItem({ id: itemId, kind, integrationIds });
+      actions.closeModal();
+
+      openEditModal(
+        {
+          kind,
+          definition,
+          value: {
+            advancedOptions: { title: null, customCssClasses: [], borderColor: "" },
+            options: defaultOptions,
+            integrationIds,
+          },
+          onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }) => {
+            updateItemOptions({ itemId, newOptions: options });
+            updateItemAdvancedOptions({ itemId, newAdvancedOptions: advancedOptions });
+            updateItemIntegrations({ itemId, newIntegrations: newIntegrationIds });
+          },
+          integrationData: matchingIntegrations,
+          integrationSupport: hasIntegrationSupport,
+          settings,
+        },
+        {
+          title: (titleT) => `${titleT("item.edit.title")} - ${titleT(`widget.${kind}.name`)}`,
+        },
+      );
+    } catch (error) {
+      notifyDefinitionLoadError(error);
+    } finally {
+      unlockSelection(selectionLock);
+      setLoadingSelection(null);
+    }
   };
 
   return (
@@ -151,9 +197,9 @@ export const ItemSelectModal = createModal<{ boardId: string }>(({ actions, inne
       onSearchChange={setSearch}
       placeholder={`${t("item.create.search")}...`}
       onSearchKeyDown={(event) => {
-        if (event.key === "Enter" && filteredItems.length === 1) {
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          handleAdd(filteredItems[0]!.kind);
+        if (event.key === "Enter" && loadingSelection === null && filteredItems.length === 1) {
+          const [item] = filteredItems;
+          if (item) void handleAdd(item.kind);
         }
       }}
     >
@@ -161,7 +207,13 @@ export const ItemSelectModal = createModal<{ boardId: string }>(({ actions, inne
         <WidgetItem
           key={item.kind}
           item={item}
-          onSelect={() => handleAdd(item.kind)}
+          onSelect={() => void handleAdd(item.kind)}
+          onIntent={() => {
+            void loadWidgetDefinition(item.kind).catch(() => undefined);
+            preloadWidgetEditModal();
+          }}
+          disabled={loadingSelection !== null}
+          loading={loadingSelection === item.kind}
           hasMatchingIntegration={item.supportedIntegrations.some((kind) => availableKinds.has(kind))}
         />
       ))}
@@ -177,12 +229,12 @@ export const ItemSelectModal = createModal<{ boardId: string }>(({ actions, inne
           {filteredCustomWidgets.map((def) => (
             <Card
               key={def.id}
+              className={classes.card}
               h={selectGridCardHeight}
               withBorder
               pos="relative"
-              style={{ overflow: "hidden", "--_hover-opacity": "0" }}
-              onMouseEnter={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "1")}
-              onMouseLeave={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "0")}
+              style={{ overflow: "hidden" }}
+              onPointerEnter={() => void loadWidgetDefinition("customApi").catch(() => undefined)}
             >
               <Stack h="100%" gap="xs">
                 <Group gap="sm" wrap="nowrap" align="flex-start">
@@ -200,18 +252,24 @@ export const ItemSelectModal = createModal<{ boardId: string }>(({ actions, inne
                 </Text>
               </Stack>
               <Box
+                className={classes.action}
                 pos="absolute"
                 bottom={0}
                 left={0}
                 right={0}
                 p="xs"
                 style={{
-                  opacity: "var(--_hover-opacity)",
-                  transition: "opacity 150ms ease",
                   background: "linear-gradient(transparent, var(--mantine-color-body) 30%)",
                 }}
               >
-                <Button onClick={() => handleAddCustomWidget(def)} variant="light" size="xs" fullWidth>
+                <Button
+                  onClick={() => void handleAddCustomWidget(def)}
+                  variant="light"
+                  size="xs"
+                  fullWidth
+                  disabled={loadingSelection !== null}
+                  loading={loadingSelection === `custom:${def.id}`}
+                >
                   {t("item.create.addToBoard")}
                 </Button>
               </Box>
@@ -231,7 +289,38 @@ export const ItemSelectModal = createModal<{ boardId: string }>(({ actions, inne
       )}
     </SelectGridLayout>
   );
-}).withOptions({
+};
+
+const ItemSelectModalFrame = ({
+  actions,
+  innerProps,
+}: {
+  actions: { closeModal: () => void };
+  innerProps: { boardId: string };
+}) => {
+  const utils = clientApi.useUtils();
+  const { data: session } = useSession();
+  const isAdmin = session?.user.permissions.includes("admin") ?? false;
+  const { data: integrationData } = clientApi.integration.all.useQuery();
+  const { data: customWidgetDefs } = clientApi.customWidget.available.useQuery(
+    { boardId: innerProps.boardId },
+    { enabled: isAdmin },
+  );
+
+  return (
+    <ItemSelectModalContent
+      actions={actions}
+      integrationData={integrationData}
+      customWidgetDefs={customWidgetDefs}
+      ensureIntegrationDataAsync={() => utils.integration.all.ensureData()}
+      isAdmin={isAdmin}
+    />
+  );
+};
+
+export const ItemSelectModal = createModal<{ boardId: string }>((props) => (
+  <ItemSelectModalFrame {...props} />
+)).withOptions({
   defaultTitle: (t) => t("item.create.title"),
   size: modalSizeSelect,
 });
@@ -239,6 +328,9 @@ export const ItemSelectModal = createModal<{ boardId: string }>(({ actions, inne
 const WidgetItem = ({
   item,
   onSelect,
+  onIntent,
+  disabled,
+  loading,
   hasMatchingIntegration,
 }: {
   item: {
@@ -249,23 +341,27 @@ const WidgetItem = ({
     icon: TablerIcon;
   };
   onSelect: () => void;
+  onIntent: () => void;
+  disabled: boolean;
+  loading: boolean;
   hasMatchingIntegration: boolean;
 }) => {
   const t = useI18n();
 
   return (
     <Card
+      className={classes.card}
       h={selectGridCardHeight}
       withBorder
       pos="relative"
       style={{
         overflow: "hidden",
-        "--_hover-opacity": "0",
         borderColor: hasMatchingIntegration ? "var(--mantine-color-blue-6)" : undefined,
         borderWidth: hasMatchingIntegration ? 2 : undefined,
       }}
-      onMouseEnter={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "1")}
-      onMouseLeave={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "0")}
+      onFocus={onIntent}
+      onPointerEnter={onIntent}
+      aria-busy={loading || undefined}
     >
       <Stack h="100%" gap="xs">
         <Group gap="sm" wrap="nowrap" align="flex-start">
@@ -282,18 +378,17 @@ const WidgetItem = ({
         <SupportedIntegrations integrations={item.supportedIntegrations} />
       </Stack>
       <Box
+        className={classes.action}
         pos="absolute"
         bottom={0}
         left={0}
         right={0}
         p="xs"
         style={{
-          opacity: "var(--_hover-opacity)",
-          transition: "opacity 150ms ease",
           background: "linear-gradient(transparent, var(--mantine-color-body) 30%)",
         }}
       >
-        <Button onClick={onSelect} variant="light" size="xs" fullWidth>
+        <Button onClick={onSelect} variant="light" size="xs" fullWidth disabled={disabled} loading={loading}>
           {t(`item.create.addToBoard`)}
         </Button>
       </Box>

apps/nextjs/src/components/board/items/widget-context-menu.tsx

@@ -3,15 +3,7 @@
 import type { MutableRefObject, ReactNode } from "react";
 import { useCallback, useMemo, useState } from "react";
 import { Group, Loader, Menu, Switch, Text, Tooltip } from "@mantine/core";
-import {
-  IconAlertTriangle,
-  IconCircleCheck,
-  IconCopy,
-  IconLayoutKanban,
-  IconRefresh,
-  IconSettings,
-  IconTrash,
-} from "@tabler/icons-react";
+import { IconAlertTriangle, IconCircleCheck, IconRefresh, IconSettings } from "@tabler/icons-react";
 import type { QueryClient, QueryKey } from "@tanstack/react-query";
 import { partialMatchKey, useIsFetching, useQueryClient } from "@tanstack/react-query";
 
@@ -20,7 +12,7 @@ import { useSession } from "@homarr/auth/client";
 import { useRequiredBoard } from "@homarr/boards/context";
 import { useEditMode } from "@homarr/boards/edit-mode";
 import { useTimeAgo } from "@homarr/common";
-import { useConfirmModal, useModalAction } from "@homarr/modals";
+import { useModalAction } from "@homarr/modals";
 import { useSettings } from "@homarr/settings";
 import { translateIfNecessary } from "@homarr/translation";
 import { useI18n, useScopedI18n } from "@homarr/translation/client";
@@ -30,9 +22,7 @@ import { getWidgetQueryKeys } from "@homarr/widgets/definition";
 import { reduceWidgetOptionsWithDefinition } from "@homarr/widgets/manifest";
 
 import type { SectionItem } from "~/app/[locale]/boards/_types";
-import { useSectionContext } from "../sections/section-context";
 import { useItemActions } from "./item-actions";
-import { LazyItemMoveModal, preloadItemMoveModal } from "./lazy-item-move-modal";
 import { LazyWidgetEditModal, preloadWidgetEditModal } from "./lazy-widget-edit-modal";
 
 interface WidgetContextMenuProps {
@@ -44,9 +34,10 @@ interface WidgetContextMenuProps {
 
 export const WidgetContextMenu = ({ item, definition, widgetStateRef, children }: WidgetContextMenuProps) => {
   const { data: session } = useSession();
+  const [isEditMode] = useEditMode();
   const settings = useSettings();
 
-  if (!session || !settings.enableRightClickOnWidgets) return <>{children}</>;
+  if (!session || !settings.enableRightClickOnWidgets || isEditMode || item.kind === "app") return <>{children}</>;
 
   return (
     <WidgetContextMenuInner item={item} definition={definition} widgetStateRef={widgetStateRef} settings={settings}>
@@ -94,25 +85,20 @@ type WidgetContextMenuDropdownProps = Omit<WidgetContextMenuProps, "children"> &
 };
 
 const WidgetContextMenuDropdown = ({ item, definition, widgetStateRef, settings }: WidgetContextMenuDropdownProps) => {
-  const { data: session } = useSession();
   const [isEditMode] = useEditMode();
   const board = useRequiredBoard();
-  const tItem = useScopedI18n("item");
   const tMenu = useScopedI18n("item.menu.label");
   const t = useI18n();
+  const { data: session } = useSession();
   const canConfigureWidget = item.kind !== "customApi" || (session?.user.permissions.includes("admin") ?? false);
   const hasSupportedIntegrations =
     "supportedIntegrations" in definition && (definition.supportedIntegrations?.length ?? 0) > 0;
   const { openModal } = useModalAction(LazyWidgetEditModal);
-  const { openModal: openMoveModal } = useModalAction(LazyItemMoveModal);
-  const { openConfirmModal } = useConfirmModal();
-  const { updateItemOptions, updateItemAdvancedOptions, updateItemIntegrations, duplicateItem, removeItem } =
-    useItemActions();
-  const { data: integrationData, isPending } = clientApi.integration.all.useQuery(undefined, {
+  const { updateItemOptions, updateItemAdvancedOptions, updateItemIntegrations } = useItemActions();
+  const { data: integrationData = [], isPending } = clientApi.integration.all.useQuery(undefined, {
     enabled: hasSupportedIntegrations,
   });
   const { mutate: saveBoard } = clientApi.board.saveBoard.useMutation();
-  const { gridstack } = useSectionContext().refs;
   const queryClient = useQueryClient();
 
   const widgetQueryKeys = useMemo(() => getWidgetQueryKeys(definition, item.kind), [definition, item.kind]);
@@ -188,7 +174,7 @@ const WidgetContextMenuDropdown = ({ item, definition, widgetStateRef, settings
             );
           }
         },
-        integrationData: (integrationData ?? []).filter(
+        integrationData: integrationData.filter(
           (integration) =>
             "supportedIntegrations" in definition &&
             (definition.supportedIntegrations as string[]).some((kind) => kind === integration.kind),
@@ -266,35 +252,8 @@ const WidgetContextMenuDropdown = ({ item, definition, widgetStateRef, settings
         </>
       )}
 
-      {isEditMode && (
-        <>
-          {(toggleOptions.length > 0 || visibleWidgetActions.length > 0) && <Menu.Divider />}
-          <Menu.Item
-            closeMenuOnClick
-            leftSection={<IconLayoutKanban size={16} />}
-            onFocus={preloadItemMoveModal}
-            onPointerEnter={preloadItemMoveModal}
-            onClick={() => {
-              if (!gridstack.current) return;
-              openMoveModal({ item, columnCount: gridstack.current.getColumn(), gridStack: gridstack.current });
-            }}
-          >
-            {tItem("action.moveResize")}
-          </Menu.Item>
-          {canConfigureWidget && (
-            <Menu.Item
-              closeMenuOnClick
-              leftSection={<IconCopy size={16} />}
-              onClick={() => duplicateItem({ itemId: item.id })}
-            >
-              {tItem("action.duplicate")}
-            </Menu.Item>
-          )}
-        </>
-      )}
-
       <>
-        {(toggleOptions.length > 0 || visibleWidgetActions.length > 0 || isEditMode) && <Menu.Divider />}
+        {(toggleOptions.length > 0 || visibleWidgetActions.length > 0) && <Menu.Divider />}
         <Menu.Item
           leftSection={isWidgetFetching ? <Loader size={16} /> : <IconRefresh size={16} />}
           onClick={handleRefetch}
@@ -316,31 +275,11 @@ const WidgetContextMenuDropdown = ({ item, definition, widgetStateRef, settings
           onClick={openEditModal}
           onFocus={preloadWidgetEditModal}
           onPointerEnter={preloadWidgetEditModal}
-          disabled={hasSupportedIntegrations && isPending}
+          disabled={!canConfigureWidget || (hasSupportedIntegrations && isPending)}
         >
           {tMenu("settings")}
         </Menu.Item>
       </>
-
-      {isEditMode && (
-        <>
-          <Menu.Divider />
-          <Menu.Item
-            closeMenuOnClick
-            color="red"
-            leftSection={<IconTrash size={16} />}
-            onClick={() => {
-              openConfirmModal({
-                title: tItem("remove.title"),
-                children: tItem("remove.message"),
-                onConfirm: () => removeItem({ itemId: item.id }),
-              });
-            }}
-          >
-            {tItem("action.remove")}
-          </Menu.Item>
-        </>
-      )}
     </>
   );
 };

apps/nextjs/src/components/board/layout/README.md

@@ -0,0 +1,27 @@
+# Fixed dashboard geometry
+
+The board uses fixed logical units:
+
+- one `1 × 1` item is exactly `200 × 200` logical pixels;
+- the gap is always `24` logical pixels, giving a `224` pixel track pitch;
+- multi-cell items include the gaps between their cells (`2 × 1` is `424 × 200`);
+- the canvas is transformed once with one uniform scale derived from its available width.
+
+Items keep the same logical dimensions at every viewport. The viewport reserves
+the painted size while the inner canvas remains at its logical dimensions, so a
+widget's `clientWidth`, `clientHeight`, and `ResizeObserver` measurements stay
+stable.
+
+The read-only renderer should:
+
+1. convert persisted `xOffset/yOffset/width/height` values to `x/y/w/h`;
+2. apply collapsed container heights and call `getCollapsedDisplayLayout`;
+3. render DOM children in `sortGridPlacementsForReadingOrder` order;
+4. position children with `getLogicalItemStyle`;
+5. wrap them with `getScaledCanvasStyles` and the read-only semantic helpers.
+
+Edit mode can use any interaction library, but its final coordinates should be
+normalized through this core. `placeGridItem` is the deterministic
+keyboard/numeric fallback: the active item is pinned while collisions move out
+of the way and all other items compact vertically. Pointer coordinates from a
+scaled editor can be converted with `toLogicalCanvasPoint`.

apps/nextjs/src/components/board/layout/board-lanes.ts

@@ -0,0 +1,94 @@
+import type { BoardLane } from "@homarr/definitions";
+import { getBoardLaneColumnCount, getRootSectionLane } from "@homarr/definitions";
+
+import type { Board, EmptySection } from "~/app/[locale]/boards/_types";
+import { getLogicalTrackSize, getLayoutRowCount, normalizeGridPlacement } from "./geometry";
+import { getCollapsedDisplayLayout } from "./reflow";
+import type { GridPlacement } from "./types";
+
+export { getBoardLaneColumnCount };
+
+export const getRootSectionForLane = (board: Board, lane: BoardLane): EmptySection | undefined => {
+  const roots = board.sections.filter(
+    (section): section is EmptySection => section.kind === "empty" && getRootSectionLane(section.xOffset) === lane,
+  );
+  if (roots.length > 1) {
+    throw new Error(`Board "${board.id}" has multiple ${lane} canvas roots`);
+  }
+
+  return roots[0];
+};
+
+export const getInitialBoardLogicalHeight = (board: Board, layoutId: string) => {
+  const layout = board.layouts.find((candidate) => candidate.id === layoutId);
+  if (!layout) return 0;
+
+  const rowCounts = (["left", "main", "right"] as const).flatMap((lane) => {
+    const columnCount = getBoardLaneColumnCount(layout, lane);
+    const root = getRootSectionForLane(board, lane);
+    if (columnCount === 0 || !root) return [];
+
+    const placements: GridPlacement[] = [
+      ...board.items.flatMap((item) => {
+        const itemLayout = item.layouts.find(
+          (candidate) => candidate.layoutId === layoutId && candidate.sectionId === root.id,
+        );
+        return itemLayout
+          ? [
+              normalizeGridPlacement(
+                {
+                  id: item.id,
+                  type: "item" as const,
+                  x: itemLayout.xOffset,
+                  y: itemLayout.yOffset,
+                  w: itemLayout.width,
+                  h: itemLayout.height,
+                },
+                columnCount,
+              ),
+            ]
+          : [];
+      }),
+      ...board.sections.flatMap((section) => {
+        if (section.kind !== "dynamic") return [];
+        const sectionLayout = section.layouts.find(
+          (candidate) => candidate.layoutId === layoutId && candidate.parentSectionId === root.id,
+        );
+        return sectionLayout
+          ? [
+              normalizeGridPlacement(
+                {
+                  id: section.id,
+                  type: "section" as const,
+                  x: sectionLayout.xOffset,
+                  y: sectionLayout.yOffset,
+                  w: sectionLayout.width,
+                  h: sectionLayout.height,
+                },
+                columnCount,
+              ),
+            ]
+          : [];
+      }),
+    ];
+    const collapsedSectionIds = new Set(
+      board.sections
+        .filter(
+          (section) =>
+            section.kind === "dynamic" &&
+            section.collapsed &&
+            section.options.collapsible &&
+            placements.some((placement) => placement.id === section.id),
+        )
+        .map((section) => section.id),
+    );
+    const displayPlacements =
+      collapsedSectionIds.size > 0
+        ? getCollapsedDisplayLayout(placements, { columnCount, collapsedItemIds: collapsedSectionIds })
+        : placements;
+
+    return [getLayoutRowCount(displayPlacements)];
+  });
+
+  return getLogicalTrackSize(Math.max(0, ...rowCounts));
+};

apps/nextjs/src/components/board/layout/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * A grid unit is a fixed logical size. The canvas is scaled as one surface;
+ * individual cards never change their internal layout at different viewports.
+ */
+export const LOGICAL_GRID_CELL_SIZE = 200;
+export const LOGICAL_GRID_GAP = 24;
+export const LOGICAL_GRID_PITCH = LOGICAL_GRID_CELL_SIZE + LOGICAL_GRID_GAP;
+export const MIN_ACCESSIBLE_CANVAS_SCALE = 0.75;
+
+export const COLLAPSED_SECTION_ROW_COUNT = 1;

apps/nextjs/src/components/board/layout/geometry.ts

@@ -0,0 +1,54 @@
+import type { CSSProperties } from "react";
+
+import { LOGICAL_GRID_CELL_SIZE, LOGICAL_GRID_GAP, LOGICAL_GRID_PITCH } from "./constants";
+import type { GridCoordinates, GridPlacement } from "./types";
+
+export const getLogicalTrackSize = (trackCount: number) => {
+  const normalizedTrackCount = toNonNegativeInteger(trackCount);
+  if (normalizedTrackCount === 0) return 0;
+
+  return normalizedTrackCount * LOGICAL_GRID_CELL_SIZE + (normalizedTrackCount - 1) * LOGICAL_GRID_GAP;
+};
+
+export const getLogicalItemStyle = ({ x, y, w, h }: GridCoordinates): CSSProperties => ({
+  position: "absolute",
+  left: x * LOGICAL_GRID_PITCH,
+  top: y * LOGICAL_GRID_PITCH,
+  width: getLogicalTrackSize(w),
+  height: getLogicalTrackSize(h),
+});
+
+export const getLayoutRowCount = (placements: readonly GridCoordinates[]) =>
+  placements.reduce((rowCount, placement) => Math.max(rowCount, placement.y + placement.h), 0);
+
+export const normalizeGridPlacement = <TPlacement extends GridPlacement>(
+  placement: TPlacement,
+  columnCount: number,
+): TPlacement => {
+  const normalizedColumnCount = toPositiveInteger(columnCount, "columnCount");
+  const width = Math.min(toPositiveInteger(placement.w, "placement.w"), normalizedColumnCount);
+  const x = Math.min(Math.max(0, toNonNegativeInteger(placement.x)), normalizedColumnCount - width);
+
+  return {
+    ...placement,
+    x,
+    y: toNonNegativeInteger(placement.y),
+    w: width,
+    h: toPositiveInteger(placement.h, "placement.h"),
+  };
+};
+
+const toNonNegativeInteger = (value: number) => Math.max(0, Math.trunc(toFiniteNumber(value, "value")));
+
+const toPositiveInteger = (value: number, name: string) => {
+  const integer = Math.trunc(toFiniteNumber(value, name));
+  if (integer < 1) throw new RangeError(`${name} must be at least 1`);
+
+  return integer;
+};
+
+const toFiniteNumber = (value: number, name: string) => {
+  if (!Number.isFinite(value)) throw new TypeError(`${name} must be finite`);
+
+  return value;
+};

apps/nextjs/src/components/board/layout/index.ts

@@ -0,0 +1,6 @@
+export * from "./constants";
+export * from "./board-lanes";
+export * from "./geometry";
+export * from "./reflow";
+export * from "./semantics";
+export * from "./types";

apps/nextjs/src/components/board/layout/reflow.ts

@@ -0,0 +1,140 @@
+import { COLLAPSED_SECTION_ROW_COUNT } from "./constants";
+import { normalizeGridPlacement } from "./geometry";
+import type { GridPlacement } from "./types";
+
+interface ReflowOptions {
+  columnCount: number;
+  /**
+   * A pinned item keeps its requested x/y while every other item compacts
+   * around it. Use this for the item currently being moved or resized.
+   */
+  pinnedItemId?: string;
+}
+
+interface CollapsedLayoutOptions {
+  columnCount: number;
+  collapsedItemIds: ReadonlySet<string>;
+  collapsedRowCount?: number;
+}
+
+export const doGridPlacementsOverlap = (first: GridPlacement, second: GridPlacement) =>
+  first.x < second.x + second.w &&
+  first.x + first.w > second.x &&
+  first.y < second.y + second.h &&
+  first.y + first.h > second.y;
+
+/**
+ * Resolves overlaps and vertically compacts items. Ordering is based on the
+ * persisted position and stable id, so the result does not depend on React or
+ * database array order.
+ */
+export const reflowVerticalLayout = <TPlacement extends GridPlacement>(
+  placements: readonly TPlacement[],
+  { columnCount, pinnedItemId }: ReflowOptions,
+): TPlacement[] => {
+  assertUniqueIds(placements);
+
+  const normalized = placements.map((placement) => normalizeGridPlacement(placement, columnCount));
+  const pinned = pinnedItemId ? normalized.find((placement) => placement.id === pinnedItemId) : undefined;
+
+  if (pinnedItemId && !pinned) {
+    throw new Error(`Pinned grid item "${pinnedItemId}" does not exist`);
+  }
+
+  const placed: TPlacement[] = pinned ? [pinned] : [];
+  const candidates = normalized.filter((placement) => placement.id !== pinnedItemId).toSorted(comparePlacements);
+
+  for (const candidate of candidates) {
+    placed.push({
+      ...candidate,
+      y: findFirstAvailableRow(candidate, placed),
+    });
+  }
+
+  const byId = new Map(placed.map((placement) => [placement.id, placement]));
+  return normalized.map((placement) => getRequiredPlacement(byId, placement.id));
+};
+
+/**
+ * Produces the view-only layout after inline containers are collapsed. Only
+ * display geometry changes; callers retain the persisted expanded height.
+ */
+export const getCollapsedDisplayLayout = <TPlacement extends GridPlacement>(
+  placements: readonly TPlacement[],
+  { columnCount, collapsedItemIds, collapsedRowCount = COLLAPSED_SECTION_ROW_COUNT }: CollapsedLayoutOptions,
+): TPlacement[] => {
+  if (collapsedRowCount < 1 || !Number.isInteger(collapsedRowCount)) {
+    throw new RangeError("collapsedRowCount must be a positive integer");
+  }
+
+  return reflowVerticalLayout(
+    placements.map((placement) =>
+      collapsedItemIds.has(placement.id)
+        ? {
+            ...placement,
+            h: collapsedRowCount,
+          }
+        : placement,
+    ),
+    { columnCount },
+  );
+};
+
+/**
+ * Applies the requested placement and pins it while neighbors compact into
+ * free space or move down. This is the deterministic fallback used by
+ * keyboard/numeric editing and can also validate a drag library result.
+ */
+export const placeGridItem = <TPlacement extends GridPlacement>(
+  placements: readonly TPlacement[],
+  nextPlacement: TPlacement,
+  columnCount: number,
+) => {
+  if (!placements.some((placement) => placement.id === nextPlacement.id)) {
+    throw new Error(`Grid item "${nextPlacement.id}" does not exist`);
+  }
+
+  return reflowVerticalLayout(
+    placements.map((placement) => (placement.id === nextPlacement.id ? nextPlacement : placement)),
+    {
+      columnCount,
+      pinnedItemId: nextPlacement.id,
+    },
+  );
+};
+
+export const sortGridPlacementsForReadingOrder = <TPlacement extends GridPlacement>(
+  placements: readonly TPlacement[],
+) => placements.toSorted(comparePlacements);
+
+const findFirstAvailableRow = (candidate: GridPlacement, placed: readonly GridPlacement[]) => {
+  let y = 0;
+  for (;;) {
+    const atRow = { ...candidate, y };
+    const collisions = placed.filter((placement) => doGridPlacementsOverlap(atRow, placement));
+    if (collisions.length === 0) return y;
+
+    y = Math.max(...collisions.map((placement) => placement.y + placement.h));
+  }
+};
+
+const comparePlacements = (first: GridPlacement, second: GridPlacement) =>
+  first.y - second.y || first.x - second.x || (first.id === second.id ? 0 : first.id < second.id ? -1 : 1);
+
+const assertUniqueIds = (placements: readonly GridPlacement[]) => {
+  const ids = new Set<string>();
+  for (const placement of placements) {
+    if (ids.has(placement.id)) throw new Error(`Duplicate grid item id "${placement.id}"`);
+    ids.add(placement.id);
+  }
+};
+
+const getRequiredPlacement = <TPlacement extends GridPlacement>(
+  placements: ReadonlyMap<string, TPlacement>,
+  id: string,
+) => {
+  const placement = placements.get(id);
+  if (!placement) throw new Error(`Grid item "${id}" was lost during layout`);
+
+  return placement;
+};

apps/nextjs/src/components/board/layout/scaled-board-canvas.module.css

@@ -0,0 +1,51 @@
+.viewport {
+  width: 100%;
+  max-width: 100%;
+  min-width: 0;
+  overflow: visible;
+  overscroll-behavior-inline: contain;
+}
+
+.viewport[data-board-hydrated="false"] {
+  overflow: clip;
+}
+
+.sizer {
+  position: relative;
+}
+
+.canvas {
+  position: absolute;
+  inset: 0 auto auto 0;
+  transform-origin: top left;
+  will-change: transform;
+
+  /*
+   * Keep dashboard UI at its normal readable density while the fixed canvas
+   * is fitted below 100%. Above 100%, the canvas still behaves like browser
+   * zoom and enlarges everything together.
+   */
+  --mantine-scale: var(--board-canvas-ui-scale, 1);
+  --mantine-spacing-xs: calc(0.625rem * var(--board-canvas-ui-scale, 1));
+  --mantine-spacing-sm: calc(0.75rem * var(--board-canvas-ui-scale, 1));
+  --mantine-spacing-md: calc(1rem * var(--board-canvas-ui-scale, 1));
+  --mantine-spacing-lg: calc(1.25rem * var(--board-canvas-ui-scale, 1));
+  --mantine-spacing-xl: calc(2rem * var(--board-canvas-ui-scale, 1));
+  --mantine-font-size-xs: calc(0.75rem * var(--board-canvas-ui-scale, 1));
+  --mantine-font-size-sm: calc(0.875rem * var(--board-canvas-ui-scale, 1));
+  --mantine-font-size-md: calc(1rem * var(--board-canvas-ui-scale, 1));
+  --mantine-font-size-lg: calc(1.125rem * var(--board-canvas-ui-scale, 1));
+  --mantine-font-size-xl: calc(1.25rem * var(--board-canvas-ui-scale, 1));
+  --mantine-h1-font-size: calc(2.125rem * var(--board-canvas-ui-scale, 1));
+  --mantine-h2-font-size: calc(1.625rem * var(--board-canvas-ui-scale, 1));
+  --mantine-h3-font-size: calc(1.375rem * var(--board-canvas-ui-scale, 1));
+  --mantine-h4-font-size: calc(1.125rem * var(--board-canvas-ui-scale, 1));
+  --mantine-h5-font-size: calc(1rem * var(--board-canvas-ui-scale, 1));
+  --mantine-h6-font-size: calc(0.875rem * var(--board-canvas-ui-scale, 1));
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .canvas {
+    will-change: auto;
+  }
+}

apps/nextjs/src/components/board/layout/scaled-board-canvas.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { useEffect, useMemo, useState } from "react";
+import { Box } from "@mantine/core";
+import { useElementSize } from "@mantine/hooks";
+
+import { MIN_ACCESSIBLE_CANVAS_SCALE } from "./constants";
+import classes from "./scaled-board-canvas.module.css";
+
+export { MIN_ACCESSIBLE_CANVAS_SCALE };
+
+export const calculateBoardCanvasScale = (availableWidth: number, logicalWidth: number) => {
+  if (!Number.isFinite(availableWidth) || !Number.isFinite(logicalWidth)) return 1;
+  if (availableWidth <= 0 || logicalWidth <= 0) return 1;
+
+  return Math.max(MIN_ACCESSIBLE_CANVAS_SCALE, availableWidth / logicalWidth);
+};
+
+export const calculateBoardUiScale = (canvasScale: number) => {
+  if (!Number.isFinite(canvasScale) || canvasScale <= 0) return 1;
+
+  return canvasScale < 1 ? 1 / canvasScale : 1;
+};
+
+interface ScaledBoardCanvasProps {
+  logicalWidth: number;
+  initialLogicalHeight: number;
+  initialAvailableWidth: number;
+  label: string;
+}
+
+/**
+ * Scales the complete board as one surface while keeping widget layout in
+ * fixed logical pixels. The scale floor deliberately allows horizontal
+ * overflow so browser zoom still magnifies content instead of being cancelled
+ * by responsive downscaling.
+ */
+export const ScaledBoardCanvas = ({
+  logicalWidth,
+  initialLogicalHeight,
+  initialAvailableWidth,
+  label,
+  children,
+}: PropsWithChildren<ScaledBoardCanvasProps>) => {
+  const { ref: viewportRef, width: availableWidth } = useElementSize<HTMLDivElement>();
+  const { ref: canvasRef, height: logicalHeight } = useElementSize<HTMLDivElement>();
+  const [isHydrated, setIsHydrated] = useState(false);
+
+  useEffect(() => {
+    setIsHydrated(true);
+  }, []);
+
+  const resolvedAvailableWidth = availableWidth > 0 ? availableWidth : initialAvailableWidth;
+  const resolvedLogicalHeight = logicalHeight > 0 ? logicalHeight : initialLogicalHeight;
+  const scale = useMemo(
+    () => calculateBoardCanvasScale(resolvedAvailableWidth, logicalWidth),
+    [logicalWidth, resolvedAvailableWidth],
+  );
+  const uiScale = calculateBoardUiScale(scale);
+  const visualWidth = logicalWidth * scale;
+  const hasHorizontalOverflow = resolvedAvailableWidth > 0 && visualWidth - resolvedAvailableWidth > 0.5;
+
+  return (
+    <Box
+      component="section"
+      ref={viewportRef}
+      className={classes.viewport}
+      data-testid="board-canvas"
+      data-board-hydrated={isHydrated ? "true" : "false"}
+      data-canvas-scale={scale}
+      data-canvas-overflow={hasHorizontalOverflow ? "true" : "false"}
+      data-canvas-initial-height={initialLogicalHeight}
+      data-canvas-initial-width={initialAvailableWidth}
+      aria-label={label}
+    >
+      <Box className={classes.sizer} w={visualWidth} h={resolvedLogicalHeight * scale}>
+        <Box
+          ref={canvasRef}
+          className={classes.canvas}
+          w={logicalWidth}
+          style={{
+            "--board-canvas-ui-scale": uiScale,
+            transform: `scale(${scale})`,
+          }}
+        >
+          {children}
+        </Box>
+      </Box>
+    </Box>
+  );
+};

apps/nextjs/src/components/board/layout/semantics.ts

@@ -0,0 +1,56 @@
+import type { GridPlacement } from "./types";
+
+interface ReadonlyCanvasAttributesInput {
+  label: string;
+}
+
+interface EditableCanvasAttributesInput extends ReadonlyCanvasAttributesInput {
+  columnCount: number;
+  rowCount: number;
+}
+
+interface EditableGridCellAttributesInput {
+  label: string;
+  placement: GridPlacement;
+}
+
+/**
+ * View mode is a labelled region, not an ARIA grid. It keeps the native
+ * semantics and focus behavior of links, buttons and widget controls inside.
+ */
+export const getReadonlyCanvasAttributes = ({ label }: ReadonlyCanvasAttributesInput) =>
+  ({
+    role: "region",
+    "aria-label": label,
+    "data-grid-readonly": "true",
+  }) as const;
+
+export const getReadonlyGridItemAttributes = (placement: GridPlacement) =>
+  ({
+    "data-grid-id": placement.id,
+    "data-grid-x": placement.x,
+    "data-grid-y": placement.y,
+    "data-grid-w": placement.w,
+    "data-grid-h": placement.h,
+  }) as const;
+
+/**
+ * Edit mode remains a labelled region. Dashboard placement is not an ARIA
+ * data grid: arrow keys edit geometry rather than navigate rows and columns.
+ * Each tile is one focusable direct-manipulation surface, while controls inside
+ * it keep their native semantics and tab order.
+ */
+export const getEditableCanvasAttributes = ({ label }: EditableCanvasAttributesInput) =>
+  ({
+    role: "region",
+    "aria-label": label,
+    "data-grid-editable": "true",
+  }) as const;
+
+export const getEditableGridCellAttributes = ({ label, placement }: EditableGridCellAttributesInput) =>
+  ({
+    role: "group",
+    "aria-label": label,
+    tabIndex: 0,
+    ...getReadonlyGridItemAttributes(placement),
+  }) as const;

apps/nextjs/src/components/board/layout/test/board-lanes.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from "vitest";
+
+import type { Board } from "~/app/[locale]/boards/_types";
+import { BoardMockBuilder } from "~/components/board/items/actions/test/mocks/board-mock";
+import { DynamicSectionMockBuilder } from "~/components/board/items/actions/test/mocks/dynamic-section-mock";
+import { EmptySectionMockBuilder } from "~/components/board/items/actions/test/mocks/empty-section-mock";
+import { ItemMockBuilder } from "~/components/board/items/actions/test/mocks/item-mock";
+import { getBoardLaneColumnCount, getInitialBoardLogicalHeight, getRootSectionForLane } from "../index";
+
+describe("board lanes", () => {
+  test("gutters consume columns from the main canvas", () => {
+    const layout = {
+      id: "layout",
+      name: "Base",
+      columnCount: 12,
+      leftGutterColumnCount: 2,
+      rightGutterColumnCount: 3,
+      breakpoint: 0,
+    } satisfies Board["layouts"][number];
+
+    expect(getBoardLaneColumnCount(layout, "left")).toBe(2);
+    expect(getBoardLaneColumnCount(layout, "main")).toBe(7);
+    expect(getBoardLaneColumnCount(layout, "right")).toBe(3);
+  });
+
+  test("clamps invalid gutters while preserving one main column", () => {
+    const layout = {
+      id: "layout",
+      name: "Base",
+      columnCount: 4,
+      leftGutterColumnCount: 3,
+      rightGutterColumnCount: 3,
+      breakpoint: 0,
+    } satisfies Board["layouts"][number];
+
+    expect(getBoardLaneColumnCount(layout, "left")).toBe(3);
+    expect(getBoardLaneColumnCount(layout, "main")).toBe(1);
+    expect(getBoardLaneColumnCount(layout, "right")).toBe(0);
+  });
+
+  test("rejects ambiguous duplicate roots", () => {
+    const board = new BoardMockBuilder()
+      .addSection(new EmptySectionMockBuilder({ id: "main-a" }).build())
+      .addSection(new EmptySectionMockBuilder({ id: "main-b" }).build())
+      .build();
+
+    expect(() => getRootSectionForLane(board, "main")).toThrow("multiple main canvas roots");
+  });
+
+  test("calculates a stable server height from the tallest visible lane", () => {
+    const layoutId = "layout";
+    const mainSectionId = "main";
+    const leftSectionId = "left";
+    const dynamicSectionId = "dynamic";
+    const board = new BoardMockBuilder()
+      .addSection(new EmptySectionMockBuilder({ id: mainSectionId }).build())
+      .addSection(new EmptySectionMockBuilder({ id: leftSectionId, xOffset: -1 }).build())
+      .addSection(
+        new DynamicSectionMockBuilder({
+          id: dynamicSectionId,
+          collapsed: true,
+          options: { collapsible: true },
+        })
+          .addLayout({
+            layoutId,
+            parentSectionId: mainSectionId,
+            xOffset: 0,
+            yOffset: 0,
+            width: 2,
+            height: 3,
+          })
+          .build(),
+      )
+      .addItem(
+        new ItemMockBuilder()
+          .addLayout({
+            layoutId,
+            sectionId: mainSectionId,
+            xOffset: 0,
+            yOffset: 3,
+            width: 1,
+            height: 1,
+          })
+          .build(),
+      )
+      .addItem(
+        new ItemMockBuilder()
+          .addLayout({
+            layoutId,
+            sectionId: leftSectionId,
+            xOffset: 0,
+            yOffset: 0,
+            width: 1,
+            height: 4,
+          })
+          .build(),
+      )
+      .build();
+    board.layouts = [
+      {
+        id: layoutId,
+        name: "Base",
+        columnCount: 8,
+        leftGutterColumnCount: 1,
+        rightGutterColumnCount: 0,
+        breakpoint: 0,
+      },
+    ];
+
+    expect(getInitialBoardLogicalHeight(board, layoutId)).toBe(872);
+  });
+});

apps/nextjs/src/components/board/layout/test/geometry.spec.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  getLayoutRowCount,
+  getLogicalItemStyle,
+  getLogicalTrackSize,
+  normalizeGridPlacement,
+} from "../index";
+
+describe("fixed dashboard geometry", () => {
+  test("keeps a 1x1 item exactly 200px with a fixed 24px gap", () => {
+    expect(getLogicalTrackSize(1)).toBe(200);
+    expect(getLogicalTrackSize(2)).toBe(424);
+    expect(getLogicalTrackSize(3)).toBe(648);
+
+    expect(getLogicalItemStyle({ x: 1, y: 2, w: 2, h: 3 })).toEqual({
+      position: "absolute",
+      left: 224,
+      top: 448,
+      width: 424,
+      height: 648,
+    });
+  });
+
+  test("normalizes invalid bounds and derives the required row count", () => {
+    const placement = normalizeGridPlacement({ id: "wide", x: 7, y: -2, w: 8, h: 2 }, 4);
+
+    expect(placement).toEqual({ id: "wide", x: 0, y: 0, w: 4, h: 2 });
+    expect(getLayoutRowCount([placement, { x: 0, y: 4, w: 1, h: 3 }])).toBe(7);
+  });
+});

apps/nextjs/src/components/board/layout/test/reflow.spec.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  doGridPlacementsOverlap,
+  getCollapsedDisplayLayout,
+  placeGridItem,
+  reflowVerticalLayout,
+  sortGridPlacementsForReadingOrder,
+} from "../index";
+import type { GridPlacement } from "../index";
+
+describe("dashboard layout reflow", () => {
+  test("compacts each horizontal lane and removes collisions", () => {
+    const result = reflowVerticalLayout(
+      [
+        { id: "a", x: 0, y: 0, w: 1, h: 1 },
+        { id: "b", x: 0, y: 3, w: 1, h: 1 },
+        { id: "c", x: 1, y: 3, w: 1, h: 1 },
+      ],
+      { columnCount: 2 },
+    );
+
+    expect(result).toEqual([
+      { id: "a", x: 0, y: 0, w: 1, h: 1 },
+      { id: "b", x: 0, y: 1, w: 1, h: 1 },
+      { id: "c", x: 1, y: 0, w: 1, h: 1 },
+    ]);
+    expect(hasOverlap(result)).toBe(false);
+  });
+
+  test("shrinks a collapsed inline container and pulls neighbors up", () => {
+    const result = getCollapsedDisplayLayout(
+      [
+        { id: "section", x: 0, y: 0, w: 2, h: 3 },
+        { id: "below", x: 0, y: 3, w: 2, h: 1 },
+        { id: "other-lane", x: 2, y: 4, w: 1, h: 1 },
+      ],
+      {
+        columnCount: 3,
+        collapsedItemIds: new Set(["section"]),
+      },
+    );
+
+    expect(result).toEqual([
+      { id: "section", x: 0, y: 0, w: 2, h: 1 },
+      { id: "below", x: 0, y: 1, w: 2, h: 1 },
+      { id: "other-lane", x: 2, y: 0, w: 1, h: 1 },
+    ]);
+  });
+
+  test("pins a moved or expanded item and pushes collisions out of the way", () => {
+    const result = placeGridItem(
+      [
+        { id: "section", x: 0, y: 0, w: 2, h: 1 },
+        { id: "neighbor", x: 0, y: 1, w: 2, h: 1 },
+        { id: "side", x: 2, y: 2, w: 1, h: 1 },
+      ],
+      { id: "section", x: 0, y: 0, w: 2, h: 3 },
+      3,
+    );
+
+    expect(result).toEqual([
+      { id: "section", x: 0, y: 0, w: 2, h: 3 },
+      { id: "neighbor", x: 0, y: 3, w: 2, h: 1 },
+      { id: "side", x: 2, y: 0, w: 1, h: 1 },
+    ]);
+    expect(hasOverlap(result)).toBe(false);
+  });
+
+  test("is deterministic regardless of input array order", () => {
+    const first = [
+      { id: "b", x: 0, y: 2, w: 1, h: 1 },
+      { id: "a", x: 0, y: 2, w: 1, h: 1 },
+      { id: "c", x: 1, y: 8, w: 1, h: 1 },
+    ];
+    const second = first.toReversed();
+
+    expect(byId(reflowVerticalLayout(first, { columnCount: 2 }))).toEqual(
+      byId(reflowVerticalLayout(second, { columnCount: 2 })),
+    );
+  });
+
+  test("provides row-major DOM order for the read-only renderer", () => {
+    const items = [
+      { id: "last", x: 0, y: 2, w: 1, h: 1 },
+      { id: "right", x: 1, y: 0, w: 1, h: 1 },
+      { id: "left", x: 0, y: 0, w: 1, h: 1 },
+    ];
+
+    expect(sortGridPlacementsForReadingOrder(items).map((item) => item.id)).toEqual(["left", "right", "last"]);
+  });
+});
+
+const hasOverlap = (placements: readonly GridPlacement[]) =>
+  placements.some((placement, index) =>
+    placements.slice(index + 1).some((otherPlacement) => doGridPlacementsOverlap(placement, otherPlacement)),
+  );
+
+const byId = (placements: readonly GridPlacement[]) =>
+  Object.fromEntries(placements.map((placement) => [placement.id, placement]));

apps/nextjs/src/components/board/layout/test/scaled-board-canvas.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "vitest";
+
+import { calculateBoardCanvasScale, calculateBoardUiScale, MIN_ACCESSIBLE_CANVAS_SCALE } from "../scaled-board-canvas";
+
+describe("board canvas scale policy", () => {
+  test("fits the logical canvas exactly when the viewport can preserve the minimum scale", () => {
+    const scale = calculateBoardCanvasScale(840, 1000);
+
+    expect(scale).toBe(0.84);
+    expect(1000 * scale).toBe(840);
+  });
+
+  test("scales up uniformly on a larger screen", () => {
+    expect(calculateBoardCanvasScale(1800, 1000)).toBe(1.8);
+  });
+
+  test("stops counter-scaling at 0.75 and lets the canvas overflow", () => {
+    const availableWidth = 600;
+    const logicalWidth = 1000;
+    const scale = calculateBoardCanvasScale(availableWidth, logicalWidth);
+
+    expect(scale).toBe(MIN_ACCESSIBLE_CANVAS_SCALE);
+    expect(logicalWidth * scale).toBeGreaterThan(availableWidth);
+  });
+
+  test("keeps content materially magnified at 200% effective zoom", () => {
+    const logicalWidth = 1696;
+    const normalAvailableWidth = 1872;
+    const normalScale = calculateBoardCanvasScale(normalAvailableWidth, logicalWidth);
+    const zoomedScale = calculateBoardCanvasScale(normalAvailableWidth / 2, logicalWidth);
+    const normalPaintedCellSize = 200 * normalScale;
+    const zoomedPaintedCellSize = 200 * zoomedScale * 2;
+
+    expect(zoomedScale).toBe(MIN_ACCESSIBLE_CANVAS_SCALE);
+    expect(zoomedPaintedCellSize).toBeGreaterThan(normalPaintedCellSize * 1.25);
+  });
+
+  test.each([
+    [0, 1000],
+    [1000, 0],
+    [Number.NaN, 1000],
+    [1000, Number.POSITIVE_INFINITY],
+  ])("uses a stable initial scale for unavailable geometry (%s, %s)", (availableWidth, logicalWidth) => {
+    expect(calculateBoardCanvasScale(availableWidth, logicalWidth)).toBe(1);
+  });
+
+  test("keeps UI typography and density at 100% while fitting the canvas down", () => {
+    expect(calculateBoardUiScale(0.75)).toBeCloseTo(4 / 3);
+    expect(calculateBoardUiScale(0.84)).toBeCloseTo(1 / 0.84);
+    expect(calculateBoardUiScale(1)).toBe(1);
+    expect(calculateBoardUiScale(1.5)).toBe(1);
+  });
+
+  test.each([0, -1, Number.NaN, Number.POSITIVE_INFINITY])(
+    "uses stable UI density for an invalid canvas scale (%s)",
+    (scale) => {
+      expect(calculateBoardUiScale(scale)).toBe(1);
+    },
+  );
+});

apps/nextjs/src/components/board/layout/test/semantics.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  getEditableCanvasAttributes,
+  getEditableGridCellAttributes,
+  getReadonlyCanvasAttributes,
+  getReadonlyGridItemAttributes,
+} from "../index";
+
+describe("dashboard layout semantics", () => {
+  const placement = { id: "weather", x: 1, y: 2, w: 3, h: 2 };
+
+  test("keeps read-only mode a native labelled region", () => {
+    expect(getReadonlyCanvasAttributes({ label: "Home dashboard" })).toEqual({
+      role: "region",
+      "aria-label": "Home dashboard",
+      "data-grid-readonly": "true",
+    });
+    expect(getReadonlyGridItemAttributes(placement)).toEqual({
+      "data-grid-id": "weather",
+      "data-grid-x": 1,
+      "data-grid-y": 2,
+      "data-grid-w": 3,
+      "data-grid-h": 2,
+    });
+  });
+
+  test("keeps edit mode a labelled region with spatial item metadata", () => {
+    expect(
+      getEditableCanvasAttributes({
+        label: "Edit home dashboard",
+        columnCount: 12,
+        rowCount: 8,
+      }),
+    ).toEqual({
+      role: "region",
+      "aria-label": "Edit home dashboard",
+      "data-grid-editable": "true",
+    });
+
+    expect(
+      getEditableGridCellAttributes({
+        label: "Weather widget",
+        placement,
+      }),
+    ).toEqual({
+      role: "group",
+      "aria-label": "Weather widget",
+      tabIndex: 0,
+      "data-grid-id": "weather",
+      "data-grid-x": 1,
+      "data-grid-y": 2,
+      "data-grid-w": 3,
+      "data-grid-h": 2,
+    });
+  });
+});

apps/nextjs/src/components/board/layout/types.ts

@@ -0,0 +1,10 @@
+export interface GridCoordinates {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface GridPlacement extends GridCoordinates {
+  id: string;
+}

apps/nextjs/src/components/board/sections/category-section.tsx

@@ -1,65 +0,0 @@
-import { Card, Collapse, Group, Stack, Title, UnstyledButton } from "@mantine/core";
-import { useDisclosure } from "@mantine/hooks";
-import { IconChevronDown, IconChevronUp } from "@tabler/icons-react";
-
-import { clientApi } from "@homarr/api/client";
-import { useSession } from "@homarr/auth/client";
-import { useRequiredBoard } from "@homarr/boards/context";
-
-import type { CategorySection } from "~/app/[locale]/boards/_types";
-import { CategoryMenu } from "./category/category-menu";
-import { GridStack } from "./gridstack/gridstack";
-import classes from "./item.module.css";
-
-const localStorageKey = (sectionId: string) => `homarr-section-collapsed-${sectionId}`;
-
-interface Props {
-  section: CategorySection;
-}
-
-export const BoardCategorySection = ({ section }: Props) => {
-  const { status } = useSession();
-  const { mutate } = clientApi.section.changeCollapsed.useMutation();
-  const board = useRequiredBoard();
-
-  const initialCollapsed =
-    typeof window !== "undefined"
-      ? (localStorage.getItem(localStorageKey(section.id)) ?? String(section.collapsed)) === "true"
-      : section.collapsed;
-
-  const [opened, { toggle }] = useDisclosure(initialCollapsed, {
-    onOpen() {
-      if (status === "authenticated") {
-        mutate({ sectionId: section.id, collapsed: true });
-      } else if (status === "unauthenticated") {
-        localStorage.setItem(localStorageKey(section.id), "true");
-      }
-    },
-    onClose() {
-      if (status === "authenticated") {
-        mutate({ sectionId: section.id, collapsed: false });
-      } else if (status === "unauthenticated") {
-        localStorage.setItem(localStorageKey(section.id), "false");
-      }
-    },
-  });
-
-  return (
-    <Card style={{ "--opacity": board.opacity / 100 }} radius={board.itemRadius} p={0} className={classes.itemCard}>
-      <Stack>
-        <Group wrap="nowrap" gap="sm">
-          <UnstyledButton w="100%" p="sm" onClick={toggle}>
-            <Group wrap="nowrap">
-              {opened ? <IconChevronUp size={20} /> : <IconChevronDown size={20} />}
-              <Title order={3}>{section.name}</Title>
-            </Group>
-          </UnstyledButton>
-          <CategoryMenu category={section} />
-        </Group>
-        <Collapse expanded={opened} p="sm" pt={0}>
-          <GridStack section={section} />
-        </Collapse>
-      </Stack>
-    </Card>
-  );
-};

apps/nextjs/src/components/board/sections/category/actions/move-category.ts

@@ -1,54 +0,0 @@
-import type { RouterOutputs } from "@homarr/api";
-
-import type { CategorySection } from "~/app/[locale]/boards/_types";
-
-export interface MoveCategoryInput {
-  id: string;
-  direction: "up" | "down";
-}
-
-export const moveCategoryCallback =
-  (input: MoveCategoryInput) =>
-  (previous: RouterOutputs["board"]["getHomeBoard"]): RouterOutputs["board"]["getHomeBoard"] => {
-    const currentCategory = previous.sections.find(
-      (section): section is CategorySection => section.kind === "category" && section.id === input.id,
-    );
-    if (!currentCategory) {
-      return previous;
-    }
-    if (currentCategory.yOffset === 1 && input.direction === "up") {
-      return previous;
-    }
-    if (currentCategory.yOffset === previous.sections.length - 2 && input.direction === "down") {
-      return previous;
-    }
-
-    return {
-      ...previous,
-      sections: previous.sections.map((section) => {
-        if (section.kind !== "category" && section.kind !== "empty") {
-          return section;
-        }
-        const offset = input.direction === "up" ? -2 : 2;
-        // Move category and empty section
-        if (section.yOffset === currentCategory.yOffset || section.yOffset === currentCategory.yOffset + 1) {
-          return {
-            ...section,
-            yOffset: section.yOffset + offset,
-          };
-        }
-
-        if (
-          section.yOffset === currentCategory.yOffset + offset ||
-          section.yOffset === currentCategory.yOffset + offset + 1
-        ) {
-          return {
-            ...section,
-            yOffset: section.yOffset - offset,
-          };
-        }
-
-        return section;
-      }),
-    };
-  };

apps/nextjs/src/components/board/sections/category/actions/remove-category.ts

@@ -1,150 +0,0 @@
-import { getBoardLayouts } from "@homarr/boards/context";
-
-import type { Board, CategorySection, EmptySection, Section } from "~/app/[locale]/boards/_types";
-
-export interface RemoveCategoryInput {
-  id: string;
-}
-
-export const removeCategoryCallback =
-  (input: RemoveCategoryInput) =>
-  (previous: Board): Board => {
-    const currentCategory = previous.sections.find(
-      (section): section is CategorySection => section.kind === "category" && section.id === input.id,
-    );
-    if (!currentCategory) {
-      return previous;
-    }
-
-    const emptySectionsAbove = previous.sections.filter(
-      (section): section is EmptySection => section.kind === "empty" && section.yOffset < currentCategory.yOffset,
-    );
-    const aboveSection = emptySectionsAbove.sort((sectionA, sectionB) => sectionB.yOffset - sectionA.yOffset).at(0);
-
-    const emptySectionsBelow = previous.sections.filter(
-      (section): section is EmptySection => section.kind === "empty" && section.yOffset > currentCategory.yOffset,
-    );
-    const removedSection = emptySectionsBelow.sort((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset).at(0);
-
-    if (!aboveSection || !removedSection) {
-      return previous;
-    }
-
-    const aboveYOffsets = getBoardLayouts(previous).map((layoutId) => {
-      return {
-        layoutId,
-        yOffset: Math.max(
-          calculateYHeightWithOffsetForItemLayouts(previous, { sectionId: aboveSection.id, layoutId }),
-          calculateYHeightWithOffsetForDynamicSectionLayouts(previous.sections, {
-            sectionId: aboveSection.id,
-            layoutId,
-          }),
-        ),
-      };
-    });
-
-    const categoryYOffsets = getBoardLayouts(previous).map((layoutId) => {
-      return {
-        layoutId,
-        yOffset: Math.max(
-          calculateYHeightWithOffsetForItemLayouts(previous, { sectionId: currentCategory.id, layoutId }),
-          calculateYHeightWithOffsetForDynamicSectionLayouts(previous.sections, {
-            sectionId: currentCategory.id,
-            layoutId,
-          }),
-        ),
-      };
-    });
-
-    return {
-      ...previous,
-      sections: previous.sections
-        .filter((section) => section.id !== currentCategory.id && section.id !== removedSection.id)
-        .map((section) =>
-          section.kind === "dynamic"
-            ? {
-                ...section,
-                layouts: section.layouts.map((layout) => {
-                  const aboveYOffset = aboveYOffsets.find(({ layoutId }) => layout.layoutId === layoutId)?.yOffset ?? 0;
-                  const categoryYOffset =
-                    categoryYOffsets.find(({ layoutId }) => layout.layoutId === layoutId)?.yOffset ?? 0;
-
-                  if (layout.parentSectionId === currentCategory.id) {
-                    return {
-                      ...layout,
-                      yOffset: layout.yOffset + aboveYOffset,
-                      parentSectionId: aboveSection.id,
-                    };
-                  }
-
-                  if (layout.parentSectionId === removedSection.id) {
-                    return {
-                      ...layout,
-                      yOffset: layout.yOffset + aboveYOffset + categoryYOffset,
-                      parentSectionId: aboveSection.id,
-                    };
-                  }
-
-                  return layout;
-                }),
-              }
-            : section,
-        ),
-
-      items: previous.items.map((item) => ({
-        ...item,
-        layouts: item.layouts.map((layout) => {
-          const aboveYOffset = aboveYOffsets.find(({ layoutId }) => layout.layoutId === layoutId)?.yOffset ?? 0;
-          const categoryYOffset = categoryYOffsets.find(({ layoutId }) => layout.layoutId === layoutId)?.yOffset ?? 0;
-
-          if (layout.sectionId === currentCategory.id) {
-            return {
-              ...layout,
-              yOffset: layout.yOffset + aboveYOffset,
-              sectionId: aboveSection.id,
-            };
-          }
-
-          if (layout.sectionId === removedSection.id) {
-            return {
-              ...layout,
-              yOffset: layout.yOffset + aboveYOffset + categoryYOffset,
-              sectionId: aboveSection.id,
-            };
-          }
-
-          return layout;
-        }),
-      })),
-    };
-  };
-
-const calculateYHeightWithOffsetForDynamicSectionLayouts = (
-  sections: Section[],
-  { sectionId, layoutId }: { sectionId: string; layoutId: string },
-) => {
-  return sections
-    .filter((section) => section.kind === "dynamic")
-    .map((section) => section.layouts.find((layout) => layout.layoutId === layoutId))
-    .filter((layout) => layout !== undefined)
-    .filter((layout) => layout.parentSectionId === sectionId)
-    .reduce((acc, layout) => {
-      const yHeightWithOffset = layout.yOffset + layout.height;
-      if (yHeightWithOffset > acc) return yHeightWithOffset;
-      return acc;
-    }, 0);
-};
-
-const calculateYHeightWithOffsetForItemLayouts = (
-  board: Board,
-  { sectionId, layoutId }: { sectionId: string; layoutId: string },
-) =>
-  board.items
-    .map((item) => item.layouts.find((layout) => layout.layoutId === layoutId))
-    .filter((layout) => layout !== undefined)
-    .filter((layout) => layout.sectionId === sectionId)
-    .reduce((acc, layout) => {
-      const yHeightWithOffset = layout.yOffset + layout.height;
-      if (yHeightWithOffset > acc) return yHeightWithOffset;
-      return acc;
-    }, 0);

apps/nextjs/src/components/board/sections/category/actions/test/move-category.spec.ts

@@ -1,79 +0,0 @@
-import { describe, expect, test } from "vitest";
-
-import type { Section } from "~/app/[locale]/boards/_types";
-import { moveCategoryCallback } from "../move-category";
-
-describe("Move Category", () => {
-  test.each([
-    [3, [0, 3, 4, 1, 2, 5, 6]],
-    [5, [0, 1, 2, 5, 6, 3, 4]],
-  ])("should move category up", (moveId, expectedOrder) => {
-    const sections = createSections(3);
-
-    const input = {
-      id: moveId.toString(),
-      direction: "up" as const,
-    };
-
-    const result = moveCategoryCallback(input)({ sections } as never);
-
-    expect(sortSections(result.sections).map((section) => parseInt(section.id, 10))).toEqual(expectedOrder);
-  });
-  test.each([
-    [1, [0, 3, 4, 1, 2, 5, 6]],
-    [3, [0, 1, 2, 5, 6, 3, 4]],
-  ])("should move category down", (moveId, expectedOrder) => {
-    const sections = createSections(3);
-
-    const input = {
-      id: moveId.toString(),
-      direction: "down" as const,
-    };
-
-    const result = moveCategoryCallback(input)({ sections } as never);
-
-    expect(sortSections(result.sections).map((section) => parseInt(section.id, 10))).toEqual(expectedOrder);
-  });
-  test("should not move category up if it is at the top", () => {
-    const sections = createSections(3);
-
-    const input = {
-      id: "1",
-      direction: "up" as const,
-    };
-
-    const result = moveCategoryCallback(input)({ sections } as never);
-
-    expect(sortSections(result.sections).map((section) => parseInt(section.id, 10))).toEqual([0, 1, 2, 3, 4, 5, 6]);
-  });
-  test("should not move category down if it is at the bottom", () => {
-    const sections = createSections(3);
-
-    const input = {
-      id: "5",
-      direction: "down" as const,
-    };
-
-    const result = moveCategoryCallback(input)({ sections } as never);
-
-    expect(sortSections(result.sections).map((section) => parseInt(section.id, 10))).toEqual([0, 1, 2, 3, 4, 5, 6]);
-  });
-});
-
-const createSections = (categoryCount: number) => {
-  return Array.from({ length: categoryCount * 2 + 1 }, (_, index) => ({
-    id: index.toString(),
-    kind: index % 2 === 1 ? ("category" as const) : ("empty" as const),
-    name: `Category ${index}`,
-    yOffset: index,
-    xOffset: 0,
-    collapsed: false,
-    items: [],
-  })) satisfies Section[];
-};
-
-const sortSections = (sections: Section[]) => {
-  return sections
-    .filter((section) => section.kind !== "dynamic")
-    .sort((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset);
-};

apps/nextjs/src/components/board/sections/category/actions/test/remove-category.spec.ts

@@ -1,145 +0,0 @@
-/* eslint-disable @typescript-eslint/no-non-null-assertion */
-import { describe, expect, test, vi } from "vitest";
-
-import * as boardContext from "@homarr/boards/context";
-
-import type { DynamicSection, Section } from "~/app/[locale]/boards/_types";
-import { BoardMockBuilder } from "~/components/board/items/actions/test/mocks/board-mock";
-import { CategorySectionMockBuilder } from "~/components/board/items/actions/test/mocks/category-section-mock";
-import { DynamicSectionMockBuilder } from "~/components/board/items/actions/test/mocks/dynamic-section-mock";
-import { EmptySectionMockBuilder } from "~/components/board/items/actions/test/mocks/empty-section-mock";
-import { ItemMockBuilder } from "~/components/board/items/actions/test/mocks/item-mock";
-import { removeCategoryCallback } from "../remove-category";
-
-describe("Remove Category", () => {
-  test.each([
-    [3, [0, 1, 2, 3, 4, 5, 6], [0, 1, 2, 5, 6], [3, 4], 2],
-    [5, [0, 1, 2, 3, 4, 5, 6], [0, 1, 2, 3, 4], [5, 6], 4],
-    [1, [0, 1, 2, 3, 4, 5, 6], [0, 3, 4, 5, 6], [1, 2], 0],
-    [3, [0, 3, 6, 7, 8], [0, 7, 8], [3, 6], 0],
-  ])(
-    "should remove category",
-    (removeId, initialYOffsets, expectedYOffsets, expectedRemovals, expectedLocationOfItems) => {
-      // Arrange
-      const layoutId = "1";
-      const input = removeId.toString();
-
-      const board = new BoardMockBuilder()
-        .addLayout({ id: layoutId })
-        .addSections(createSections(initialYOffsets))
-        .addItems(createSectionItems(initialYOffsets, layoutId))
-        .build();
-
-      vi.spyOn(boardContext, "getBoardLayouts").mockReturnValue([layoutId]);
-
-      // Act
-      const result = removeCategoryCallback({ id: input })(board);
-
-      // Assert
-      expect(result.sections.map((section) => parseInt(section.id, 10))).toEqual(expectedYOffsets);
-      expectedRemovals.forEach((expectedRemoval) => {
-        expect(result.sections.find((section) => section.id === expectedRemoval.toString())).toBeUndefined();
-      });
-      const aboveSectionItems = result.items.filter(
-        (item) => item.layouts[0]?.sectionId === expectedLocationOfItems.toString(),
-      );
-      expect(aboveSectionItems.map((item) => parseInt(item.id, 10))).toEqual(expect.arrayContaining(expectedRemovals));
-    },
-  );
-
-  test("should correctly move items to above empty section", () => {
-    // Arrange
-    const layoutId = "1";
-    const sectionIds = {
-      above: "2",
-      category: "3",
-      below: "4",
-      dynamic: "7",
-    };
-    const initialYOffsets = [0, 1, 2, 3, 4, 5, 6];
-
-    const board = new BoardMockBuilder()
-      .addLayout({ id: layoutId })
-      .addSections(createSections(initialYOffsets))
-      .addItems(createSectionItems([0, 1, 5, 6], layoutId)) // Only add items to other sections
-      .addDynamicSection(
-        new DynamicSectionMockBuilder({ id: sectionIds.dynamic })
-          .addLayout({ layoutId, parentSectionId: sectionIds.category, yOffset: 7, height: 3 })
-          .build(),
-      )
-      .addItem(new ItemMockBuilder({ id: "above-1" }).addLayout({ layoutId, sectionId: sectionIds.above }).build())
-      .addItem(
-        new ItemMockBuilder({ id: "above-2" })
-          .addLayout({ layoutId, sectionId: sectionIds.above, yOffset: 3, xOffset: 2, height: 2 })
-          .build(),
-      )
-      .addItem(
-        new ItemMockBuilder({ id: "category-1" }).addLayout({ layoutId, sectionId: sectionIds.category }).build(),
-      )
-      .addItem(
-        new ItemMockBuilder({ id: "category-2" })
-          .addLayout({ layoutId, sectionId: sectionIds.category, yOffset: 2, xOffset: 4, width: 4 })
-          .build(),
-      )
-      .addItem(
-        new ItemMockBuilder({ id: "below-1" }).addLayout({ layoutId, sectionId: sectionIds.below, xOffset: 5 }).build(),
-      )
-      .addItem(
-        new ItemMockBuilder({ id: "below-2" })
-          .addLayout({ layoutId, sectionId: sectionIds.below, yOffset: 1, xOffset: 1, height: 2 })
-          .build(),
-      )
-      .addItem(new ItemMockBuilder({ id: "dynamic-1" }).addLayout({ layoutId, sectionId: sectionIds.dynamic }).build())
-      .build();
-
-    vi.spyOn(boardContext, "getBoardLayouts").mockReturnValue([layoutId]);
-
-    // Act
-    const result = removeCategoryCallback({ id: sectionIds.category })(board);
-
-    // Assert
-    expect(result.sections.map((section) => parseInt(section.id, 10))).toEqual([0, 1, 2, 5, 6, 7]);
-    const aboveSectionItems = result.items.filter((item) => item.layouts[0]?.sectionId === sectionIds.above);
-    expect(aboveSectionItems.length).toBe(6);
-
-    expect(
-      aboveSectionItems
-        .map((item) => ({
-          ...item,
-          ...item.layouts[0]!,
-        }))
-        .sort((itemA, itemB) => itemA.yOffset - itemB.yOffset),
-    ).toEqual([
-      expect.objectContaining({ id: "above-1", yOffset: 0, xOffset: 0 }),
-      expect.objectContaining({ id: "above-2", yOffset: 3, xOffset: 2, height: 2 }),
-      expect.objectContaining({ id: "category-1", yOffset: 5, xOffset: 0 }),
-      expect.objectContaining({ id: "category-2", yOffset: 7, xOffset: 4, width: 4 }),
-      expect.objectContaining({ id: "below-1", yOffset: 15, xOffset: 5 }),
-      expect.objectContaining({ id: "below-2", yOffset: 16, xOffset: 1, height: 2 }),
-    ]);
-
-    const dynamicSection = result.sections.find((section): section is DynamicSection => section.id === "7")!;
-    expect(dynamicSection.layouts.at(0)?.yOffset).toBe(12);
-    expect(dynamicSection.layouts[0]?.parentSectionId).toBe("2");
-  });
-});
-
-const createSections = (initialYOffsets: number[]) => {
-  return initialYOffsets.map((yOffset, index) =>
-    index % 2 === 0
-      ? new EmptySectionMockBuilder({
-          id: yOffset.toString(),
-          yOffset,
-        }).build()
-      : new CategorySectionMockBuilder({
-          id: yOffset.toString(),
-          yOffset,
-        }).build(),
-  ) satisfies Section[];
-};
-
-const createSectionItems = (initialYOffsets: number[], layoutId: string) => {
-  return initialYOffsets.map((yOffset) =>
-    new ItemMockBuilder({ id: yOffset.toString() }).addLayout({ layoutId, sectionId: yOffset.toString() }).build(),
-  );
-};

apps/nextjs/src/components/board/sections/category/category-actions.ts

@@ -1,145 +0,0 @@
-import { useCallback } from "react";
-
-import { useUpdateBoard } from "@homarr/boards/updater";
-import { createId } from "@homarr/common";
-
-import type { CategorySection, EmptySection, Section } from "~/app/[locale]/boards/_types";
-import type { MoveCategoryInput } from "./actions/move-category";
-import { moveCategoryCallback } from "./actions/move-category";
-import type { RemoveCategoryInput } from "./actions/remove-category";
-import { removeCategoryCallback } from "./actions/remove-category";
-
-interface AddCategory {
-  name: string;
-  yOffset: number;
-}
-
-interface RenameCategory {
-  id: string;
-  name: string;
-}
-
-export const useCategoryActions = () => {
-  const { updateBoard } = useUpdateBoard();
-
-  const addCategory = useCallback(
-    ({ name, yOffset }: AddCategory) => {
-      if (yOffset <= -1) {
-        return;
-      }
-      updateBoard((previous) => ({
-        ...previous,
-        sections: [
-          // Place sections before the new category
-          ...previous.sections.filter(
-            (section) => (section.kind === "category" || section.kind === "empty") && section.yOffset < yOffset,
-          ),
-          {
-            id: createId(),
-            name,
-            kind: "category",
-            yOffset,
-            xOffset: 0,
-            collapsed: false,
-          },
-          {
-            id: createId(),
-            kind: "empty",
-            yOffset: yOffset + 1,
-            xOffset: 0,
-          },
-          // Place sections after the new category
-          ...previous.sections
-            .filter(
-              (section): section is CategorySection | EmptySection =>
-                (section.kind === "category" || section.kind === "empty") && section.yOffset >= yOffset,
-            )
-            .map((section) => ({
-              ...section,
-              yOffset: section.yOffset + 2,
-            })),
-          ...previous.sections.filter((section) => section.kind !== "category" && section.kind !== "empty"),
-        ] satisfies Section[],
-      }));
-    },
-    [updateBoard],
-  );
-
-  const addCategoryToEnd = useCallback(
-    ({ name }: { name: string }) => {
-      updateBoard((previous) => {
-        const lastSection = previous.sections
-          .filter(
-            (section): section is CategorySection | EmptySection =>
-              section.kind === "empty" || section.kind === "category",
-          )
-          .sort((sectionA, sectionB) => sectionB.yOffset - sectionA.yOffset)
-          .at(0);
-
-        if (!lastSection) return previous;
-        const lastYOffset = lastSection.yOffset;
-
-        return {
-          ...previous,
-          sections: [
-            ...previous.sections,
-            {
-              id: createId(),
-              name,
-              kind: "category",
-              yOffset: lastYOffset + 1,
-              xOffset: 0,
-              collapsed: false,
-            },
-            {
-              id: createId(),
-              kind: "empty",
-              yOffset: lastYOffset + 2,
-              xOffset: 0,
-            },
-          ] satisfies Section[],
-        };
-      });
-    },
-    [updateBoard],
-  );
-
-  const renameCategory = useCallback(
-    ({ id: categoryId, name }: RenameCategory) => {
-      updateBoard((previous) => ({
-        ...previous,
-        sections: previous.sections.map((section) => {
-          if (section.kind !== "category") return section;
-          if (section.id !== categoryId) return section;
-          return {
-            ...section,
-            name,
-          };
-        }),
-      }));
-    },
-    [updateBoard],
-  );
-
-  const moveCategory = useCallback(
-    (input: MoveCategoryInput) => {
-      updateBoard(moveCategoryCallback(input));
-    },
-    [updateBoard],
-  );
-
-  const removeCategory = useCallback(
-    (input: RemoveCategoryInput) => {
-      updateBoard(removeCategoryCallback(input));
-    },
-    [updateBoard],
-  );
-
-  return {
-    addCategory,
-    addCategoryToEnd,
-    renameCategory,
-    moveCategory,
-    removeCategory,
-  };
-};

apps/nextjs/src/components/board/sections/category/category-edit-modal.tsx

@@ -1,45 +0,0 @@
-import { Stack, TextInput } from "@mantine/core";
-import { z } from "zod/v4";
-
-import { useZodForm } from "@homarr/form";
-import { createModal, ModalFormFooter, modalSizeForm } from "@homarr/modals";
-import { useI18n } from "@homarr/translation/client";
-
-interface Category {
-  id: string;
-  name: string;
-}
-
-interface InnerProps {
-  submitLabel: string;
-  category: Category;
-  onSuccess: (category: Category) => void;
-}
-
-export const CategoryEditModal = createModal<InnerProps>(({ actions, innerProps }) => {
-  const t = useI18n();
-  const form = useZodForm(z.object({ name: z.string().min(1) }), {
-    initialValues: {
-      name: innerProps.category.name,
-    },
-  });
-
-  return (
-    <form
-      onSubmit={form.onSubmit((values) => {
-        void innerProps.onSuccess({
-          ...innerProps.category,
-          name: values.name,
-        });
-        actions.closeModal();
-      })}
-    >
-      <Stack>
-        <TextInput label={t("section.category.field.name.label")} data-autofocus {...form.getInputProps("name")} />
-        <ModalFormFooter onCancel={actions.closeModal} submitLabel={innerProps.submitLabel} />
-      </Stack>
-    </form>
-  );
-}).withOptions({
-  size: modalSizeForm,
-});

apps/nextjs/src/components/board/sections/category/category-menu-actions.tsx

@@ -1,146 +0,0 @@
-import { useCallback } from "react";
-
-import { fetchApi } from "@homarr/api/client";
-import { getCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
-import { createId } from "@homarr/common";
-import { useConfirmModal, useModalAction } from "@homarr/modals";
-import { useSettings } from "@homarr/settings";
-import { useI18n } from "@homarr/translation/client";
-
-import type { CategorySection } from "~/app/[locale]/boards/_types";
-import { useCategoryActions } from "./category-actions";
-import { CategoryEditModal } from "./category-edit-modal";
-import { filterByItemKind } from "./filter";
-
-export const useCategoryMenuActions = (category: CategorySection) => {
-  const { openModal } = useModalAction(CategoryEditModal);
-  const { openConfirmModal } = useConfirmModal();
-  const { addCategory, moveCategory, removeCategory, renameCategory } = useCategoryActions();
-  const t = useI18n();
-  const board = useRequiredBoard();
-
-  const createCategoryAtYOffset = useCallback(
-    (position: number) => {
-      openModal(
-        {
-          category: {
-            id: createId(),
-            name: t("section.category.create.title"),
-          },
-          onSuccess: (category) => {
-            addCategory({
-              name: category.name,
-              yOffset: position,
-            });
-          },
-          submitLabel: t("section.category.create.submit"),
-        },
-        {
-          title: (t) => t("section.category.create.title"),
-        },
-      );
-    },
-    [addCategory, t, openModal],
-  );
-
-  // creates a new category above the current
-  const addCategoryAbove = useCallback(() => {
-    const aboveYOffset = category.yOffset;
-    createCategoryAtYOffset(aboveYOffset);
-  }, [category.yOffset, createCategoryAtYOffset]);
-
-  // creates a new category below the current
-  const addCategoryBelow = useCallback(() => {
-    const belowYOffset = category.yOffset + 2;
-    createCategoryAtYOffset(belowYOffset);
-  }, [category.yOffset, createCategoryAtYOffset]);
-
-  const moveCategoryUp = useCallback(() => {
-    moveCategory({
-      id: category.id,
-      direction: "up",
-    });
-  }, [category.id, moveCategory]);
-
-  const moveCategoryDown = useCallback(() => {
-    moveCategory({
-      id: category.id,
-      direction: "down",
-    });
-  }, [category.id, moveCategory]);
-
-  // Removes the current category
-  const remove = useCallback(() => {
-    openConfirmModal({
-      title: t("section.category.remove.title"),
-      children: t("section.category.remove.message", {
-        name: category.name,
-      }),
-      onConfirm: () => {
-        removeCategory({
-          id: category.id,
-        });
-      },
-    });
-  }, [category.id, category.name, removeCategory, t, openConfirmModal]);
-
-  const edit = useCallback(() => {
-    openModal(
-      {
-        category,
-        submitLabel: t("section.category.edit.submit"),
-        onSuccess: (category) => {
-          renameCategory({
-            id: category.id,
-            name: category.name,
-          });
-        },
-      },
-      {
-        title: (t) => t("section.category.edit.title"),
-      },
-    );
-  }, [category, openModal, renameCategory, t]);
-
-  const settings = useSettings();
-  const openAllInNewTabs = useCallback(async () => {
-    const currentLayoutId = getCurrentLayout(board);
-    const appIds = (
-      await filterByItemKind(
-        board.items.filter(
-          (item) => item.layouts.find((layout) => layout.layoutId === currentLayoutId)?.sectionId === category.id,
-        ),
-        settings,
-        "app",
-      )
-    ).map((item) => {
-      return item.options.appId;
-    });
-
-    const apps = await fetchApi.app.byIds.query(appIds);
-    const appsWithUrls = apps.filter((app) => app.href && app.href.length > 0);
-
-    for (const app of appsWithUrls) {
-      const openedWindow = window.open(app.href ?? undefined);
-      if (openedWindow) {
-        continue;
-      }
-
-      openConfirmModal({
-        title: t("section.category.openAllInNewTabs.title"),
-        children: t("section.category.openAllInNewTabs.text"),
-      });
-      break;
-    }
-  }, [category, board, t, openConfirmModal, settings]);
-
-  return {
-    addCategoryAbove,
-    addCategoryBelow,
-    moveCategoryUp,
-    moveCategoryDown,
-    remove,
-    edit,
-    openAllInNewTabs,
-  };
-};

apps/nextjs/src/components/board/sections/category/category-menu.tsx

@@ -1,128 +0,0 @@
-"use client";
-
-import React, { useMemo } from "react";
-import { ActionIcon, Menu } from "@mantine/core";
-import {
-  IconDotsVertical,
-  IconEdit,
-  IconExternalLink,
-  IconRowInsertBottom,
-  IconRowInsertTop,
-  IconTransitionBottom,
-  IconTransitionTop,
-  IconTrash,
-} from "@tabler/icons-react";
-
-import { useEditMode } from "@homarr/boards/edit-mode";
-import type { MaybePromise } from "@homarr/common/types";
-import { useScopedI18n } from "@homarr/translation/client";
-import type { TablerIcon } from "@homarr/ui";
-
-import type { CategorySection } from "~/app/[locale]/boards/_types";
-import { useCategoryMenuActions } from "./category-menu-actions";
-
-interface Props {
-  category: CategorySection;
-}
-
-export const CategoryMenu = ({ category }: Props) => {
-  const actions = useActions(category);
-  const t = useScopedI18n("section.category");
-
-  return (
-    <Menu>
-      <Menu.Target>
-        <ActionIcon mr="sm" variant="transparent" aria-label={t("menu.label.settings")}>
-          <IconDotsVertical size={20} />
-        </ActionIcon>
-      </Menu.Target>
-      <Menu.Dropdown>
-        {actions.map((action) => {
-          return (
-            <React.Fragment key={action.label}>
-              {"group" in action && <Menu.Label>{t(action.group)}</Menu.Label>}
-              <Menu.Item
-                leftSection={<action.icon size="1rem" />}
-                onClick={action.onClick}
-                color={"color" in action ? action.color : undefined}
-              >
-                {t(action.label)}
-              </Menu.Item>
-            </React.Fragment>
-          );
-        })}
-      </Menu.Dropdown>
-    </Menu>
-  );
-};
-
-const useActions = (category: CategorySection) => {
-  const [isEditMode] = useEditMode();
-  const editModeActions = useEditModeActions(category);
-  const nonEditModeActions = useNonEditModeActions(category);
-
-  return useMemo(
-    () => (isEditMode ? editModeActions : nonEditModeActions),
-    [isEditMode, editModeActions, nonEditModeActions],
-  );
-};
-
-const useEditModeActions = (category: CategorySection) => {
-  const { addCategoryAbove, addCategoryBelow, moveCategoryUp, moveCategoryDown, edit, remove } =
-    useCategoryMenuActions(category);
-
-  return [
-    {
-      icon: IconEdit,
-      label: "action.edit",
-      onClick: edit,
-    },
-    {
-      icon: IconTrash,
-      color: "red",
-      label: "action.remove",
-      onClick: remove,
-    },
-    {
-      group: "menu.label.changePosition",
-      icon: IconTransitionTop,
-      label: "action.moveUp",
-      onClick: moveCategoryUp,
-    },
-    {
-      icon: IconTransitionBottom,
-      label: "action.moveDown",
-      onClick: moveCategoryDown,
-    },
-    {
-      group: "menu.label.create",
-      icon: IconRowInsertTop,
-      label: "action.createAbove",
-      onClick: addCategoryAbove,
-    },
-    {
-      icon: IconRowInsertBottom,
-      label: "action.createBelow",
-      onClick: addCategoryBelow,
-    },
-  ] as const satisfies ActionDefinition[];
-};
-
-const useNonEditModeActions = (category: CategorySection) => {
-  const { openAllInNewTabs } = useCategoryMenuActions(category);
-  return [
-    {
-      icon: IconExternalLink,
-      label: "action.openAllInNewTabs",
-      onClick: openAllInNewTabs,
-    },
-  ] as const satisfies ActionDefinition[];
-};
-
-interface ActionDefinition {
-  icon: TablerIcon;
-  label: string;
-  onClick: () => MaybePromise<void>;
-  color?: string;
-  group?: string;
-}

apps/nextjs/src/components/board/sections/content.tsx

@@ -1,33 +1,19 @@
 import { useMemo } from "react";
 
-import type { GridItemHTMLElement } from "@homarr/gridstack";
-
 import type { RouterOutputs } from "@homarr/api";
-import { clientApi } from "@homarr/api/client";
-import { useSession } from "@homarr/auth/client";
-import { useEditMode } from "@homarr/boards/edit-mode";
 
-import type { DynamicSectionItem, SectionItem } from "~/app/[locale]/boards/_types";
+import type { ContainerSectionItem, SectionItem } from "~/app/[locale]/boards/_types";
 import { BoardItemContent } from "../items/item-content";
 import { WidgetHoverOverlay } from "../items/widget-hover-overlay";
-import { BoardDynamicSection } from "./dynamic-section";
-import { GridStackItem } from "./gridstack/gridstack-item";
+import { BoardContainerSection } from "./container-section";
+import { FixedGridItem } from "./grid/fixed-grid-item";
 import { useSectionContext } from "./section-context";
 import { useSectionItems } from "./use-section-items";
 
 export const SectionContent = () => {
-  const { innerSections, items, refs } = useSectionContext();
-  const { data: session } = useSession();
-  const [isEditMode] = useEditMode();
-  const { data: integrations } = clientApi.integration.all.useQuery(undefined, {
-    enabled: Boolean(session) && isEditMode,
-  });
+  const { innerSections, integrations, items } = useSectionContext();
 
-  /**
-   * IMPORTANT: THE ORDER OF THE BELOW ITEMS HAS TO MATCH THE ORDER OF
-   * THE ITEMS RENDERED WITH GRIDSTACK, OTHERWISE THE ITEMS WILL BE MIXED UP
-   * @see https://github.com/homarr-labs/homarr/pull/1770
-   */
+  /** Keep portal content order deterministic across static and edit renderers. */
   const sortedItems = useMemo(() => {
     return [...items, ...innerSections].toSorted((itemA, itemB) => {
       if (itemA.yOffset === itemB.yOffset) {
@@ -41,57 +27,39 @@ export const SectionContent = () => {
   return (
     <>
       {sortedItems.map((item) => (
-        <Item key={item.id} item={item} innerRef={refs.items.current[item.id]} integrations={integrations} />
+        <SectionContentItem key={item.id} item={item} integrations={integrations} />
       ))}
     </>
   );
 };
 
 interface ItemProps {
-  item: DynamicSectionItem | SectionItem;
-  innerRef: React.RefObject<GridItemHTMLElement | null> | undefined;
+  item: ContainerSectionItem | SectionItem;
   integrations: RouterOutputs["integration"]["all"] | undefined;
 }
 
-const Item = ({ item, innerRef, integrations }: ItemProps) => {
+export const SectionContentItem = ({ item, integrations }: ItemProps) => {
   const minWidth = useMinSize(item, "x");
   const minHeight = useMinSize(item, "y");
   return (
-    <GridStackItem
-      key={item.id}
-      innerRef={innerRef}
-      width={item.width}
-      height={item.height}
-      xOffset={item.xOffset}
-      yOffset={item.yOffset}
-      kind={item.kind}
-      id={item.id}
-      type={item.type}
-      minWidth={minWidth}
-      minHeight={minHeight}
-    >
+    <FixedGridItem key={item.id} item={item} minWidth={minWidth} minHeight={minHeight}>
       {item.type === "item" && item.kind !== "app" && <WidgetHoverOverlay item={item} integrations={integrations} />}
-      {item.type === "item" ? <BoardItemContent item={item} /> : <BoardDynamicSection section={item} />}
-    </GridStackItem>
+      {item.type === "item" ? <BoardItemContent item={item} /> : <BoardContainerSection section={item} />}
+    </FixedGridItem>
   );
 };
 
 /**
- * Calculates the min width / height of a section by taking the maximum of
- * the sum of the offset and size of all items and dynamic sections inside.
- * @param direction either "x" or "y"
- * @param items items of the section
- * @param sections sections of the board to look for dynamic sections
- * @param parentSectionId the id of the section we want to calculate the min size for
- * @returns the min size
+ * Calculates a container's minimum width or height from its direct content.
  */
-const useMinSize = (item: DynamicSectionItem | SectionItem, direction: "x" | "y") => {
+export const useMinSize = (item: ContainerSectionItem | SectionItem, direction: "x" | "y") => {
   const { items, innerSections } = useSectionItems(item.id);
   if (item.type === "item") return undefined;
 
   const size = direction === "x" ? "width" : "height";
   return Math.max(
-    ...items.map((item) => item[`${direction}Offset`] + item[size]),
-    ...innerSections.map((item) => item[`${direction}Offset`] + item[size]),
+    1,
+    ...items.map((childItem) => childItem[`${direction}Offset`] + childItem[size]),
+    ...innerSections.map((childSection) => childSection[`${direction}Offset`] + childSection[size]),
   );
 };

apps/nextjs/src/components/board/sections/dynamic-section.tsx

@@ -1,25 +1,52 @@
-import { Badge, Box, Card } from "@mantine/core";
+import dynamic from "next/dynamic";
+import { ActionIcon, Badge, Box, Card } from "@mantine/core";
+import { IconChevronDown, IconChevronUp, IconExternalLink } from "@tabler/icons-react";
 import combineClasses from "clsx";
 
-import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
+import { useRequiredBoard } from "@homarr/boards/context";
+import { useEditMode } from "@homarr/boards/edit-mode";
+import { useI18n, useScopedI18n } from "@homarr/translation/client";
 
 import type { DynamicSectionItem } from "~/app/[locale]/boards/_types";
-import { BoardDynamicSectionMenu } from "./dynamic/dynamic-menu";
-import { GridStack } from "./gridstack/gridstack";
+import { SectionGrid } from "./grid/section-grid";
+import { useSectionCollapse } from "./section-collapse";
+import { useOpenSectionApps } from "./use-open-section-apps";
 import classes from "./item.module.css";
 
+const BoardDynamicSectionMenu = dynamic(
+  () => import("./dynamic/dynamic-menu").then((module) => module.BoardDynamicSectionMenu),
+  { ssr: false },
+);
+
 interface Props {
   section: DynamicSectionItem;
 }
 
 export const BoardDynamicSection = ({ section }: Props) => {
   const board = useRequiredBoard();
-  const currentLayoutId = useCurrentLayout();
+  const [isEditMode] = useEditMode();
+  const t = useScopedI18n("section.dynamic");
+  const tAll = useI18n();
   const options = section.options;
+  const { open: openAllInNewTabs, isLoading: areAppsLoading } = useOpenSectionApps(
+    section.id,
+    options.showOpenAll && !isEditMode,
+  );
+  const { isVisuallyCollapsed, toggle } = useSectionCollapse({
+    sectionId: section.id,
+    collapsible: options.collapsible,
+  });
+  const label = options.title || t("action.create");
+  const contentId = `board-section-${section.id}-content`;
+  const labelLeft = !isEditMode && options.collapsible ? 40 : 10;
+  const labelRight = isEditMode ? 48 : options.showOpenAll ? 40 : 8;
 
   return (
     <Box
       className="grid-stack-item-content"
+      data-grid-item-content
+      w="100%"
+      h="100%"
       style={{
         overflow: "visible",
       }}
@@ -38,24 +65,65 @@ export const BoardDynamicSection = ({ section }: Props) => {
         radius={board.itemRadius}
         p={0}
       >
-        {options.title && (
+        {options.showLabel && options.title && (
           <Badge
             pos="absolute"
-            top={-15}
-            left={10}
+            top={6}
+            left={labelLeft}
+            maw={`calc(100% - ${labelLeft + labelRight}px)`}
             size="md"
             radius={board.itemRadius}
             color="var(--background-color)"
             c="var(--mantine-color-text)"
             bd="1px solid var(--border-color)"
+            style={{ zIndex: 9, pointerEvents: "none" }}
           >
             {options.title}
           </Badge>
         )}
-        {/* Use unique key by layout to reinitialize gridstack */}
-        <GridStack key={`${currentLayoutId}-${section.id}`} section={section} className="min-row" />
+        {options.collapsible && !isEditMode && (
+          <ActionIcon
+            pos="absolute"
+            top={4}
+            left={4}
+            style={{ zIndex: 10 }}
+            variant="default"
+            radius="xl"
+            onClick={toggle}
+            aria-expanded={!isVisuallyCollapsed}
+            aria-controls={contentId}
+            aria-label={`${isVisuallyCollapsed ? t("action.expand") : t("action.collapse")}: ${label}`}
+          >
+            {isVisuallyCollapsed ? <IconChevronDown size={16} /> : <IconChevronUp size={16} />}
+          </ActionIcon>
+        )}
+        {options.showOpenAll && !isEditMode && (
+          <ActionIcon
+            pos="absolute"
+            top={4}
+            right={4}
+            style={{ zIndex: 10 }}
+            variant="default"
+            radius="xl"
+            loading={areAppsLoading}
+            onClick={openAllInNewTabs}
+            aria-label={tAll("section.action.openAllInNewTabsFor", { name: label })}
+          >
+            <IconExternalLink size={16} />
+          </ActionIcon>
+        )}
+        <Box id={contentId} h="100%" hidden={isVisuallyCollapsed}>
+          {!isVisuallyCollapsed && (
+            <SectionGrid
+              section={section}
+              columnCount={section.width}
+              requestedRowCount={section.height}
+              label={label}
+            />
+          )}
+        </Box>
       </Card>
-      <BoardDynamicSectionMenu section={section} />
+      {isEditMode && <BoardDynamicSectionMenu section={section} />}
     </Box>
   );
 };

apps/nextjs/src/components/board/sections/dynamic/actions/add-dynamic-section.ts

@@ -1,27 +1,30 @@
 import { getBoardLayouts } from "@homarr/boards/context";
 import { createId } from "@homarr/common";
+import { getRootSectionLane } from "@homarr/definitions";
+import { dynamicSectionOptionsSchema } from "@homarr/validation/shared";
 
 import type { Board, DynamicSection, DynamicSectionLayout, EmptySection } from "~/app/[locale]/boards/_types";
+import { getBoardLaneColumnCount } from "~/components/board/layout";
 import { getFirstEmptyPosition } from "~/components/board/items/actions/empty-position";
 import { getSectionElements } from "~/components/board/items/actions/section-elements";
 
 export const addDynamicSectionCallback = () => (board: Board) => {
   const firstSection = board.sections
-    .filter((section) => section.kind === "empty")
-    .sort((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset)
+    .filter(
+      (section): section is EmptySection => section.kind === "empty" && getRootSectionLane(section.xOffset) === "main",
+    )
+    .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset)
     .at(0);
 
   if (!firstSection) return board;
 
+  const sectionLayouts = createDynamicSectionLayouts(board, firstSection);
   const newSection = {
     id: createId(),
     kind: "dynamic",
-    options: {
-      title: "",
-      borderColor: "",
-      customCssClasses: [],
-    },
-    layouts: createDynamicSectionLayouts(board, firstSection),
+    collapsed: false,
+    options: dynamicSectionOptionsSchema.parse(undefined),
+    layouts: sectionLayouts,
   } satisfies DynamicSection;
 
   return {
@@ -36,9 +39,14 @@ const createDynamicSectionLayouts = (board: Board, currentSection: EmptySection)
   return layouts.map((layoutId) => {
     const boardLayout = board.layouts.find((layout) => layout.id === layoutId);
     const elements = getSectionElements(board, { sectionId: currentSection.id, layoutId });
+    const columnCount = boardLayout ? getBoardLaneColumnCount(boardLayout, "main") : 1;
+    const size = {
+      width: Math.min(4, columnCount),
+      height: 3,
+    };
 
     const emptyPosition = boardLayout
-      ? getFirstEmptyPosition(elements, boardLayout.columnCount)
+      ? getFirstEmptyPosition(elements, columnCount, undefined, size)
       : { xOffset: 0, yOffset: 0 };
 
     if (!emptyPosition) {
@@ -46,8 +54,7 @@ const createDynamicSectionLayouts = (board: Board, currentSection: EmptySection)
     }
 
     return {
-      width: 1,
-      height: 1,
+      ...size,
       ...emptyPosition,
       parentSectionId: currentSection.id,
       layoutId,

apps/nextjs/src/components/board/sections/dynamic/dynamic-actions.ts

@@ -24,7 +24,9 @@ export const useDynamicSectionActions = () => {
     ({ itemId, newOptions }: UpdateDynamicOptions) => {
       updateBoard((previous) => ({
         ...previous,
-        sections: previous.sections.map((item) => (item.id !== itemId ? item : { ...item, options: newOptions })),
+        sections: previous.sections.map((item) =>
+          item.id !== itemId || item.kind !== "dynamic" ? item : { ...item, options: newOptions },
+        ),
       }));
     },
     [updateBoard],

apps/nextjs/src/components/board/sections/dynamic/dynamic-edit-modal.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { CloseButton, ColorInput, Stack, TextInput, useMantineTheme } from "@mantine/core";
+import { CloseButton, ColorInput, Stack, Switch, TextInput, useMantineTheme } from "@mantine/core";
 import type { z } from "zod/v4";
 
 import { useZodForm } from "@homarr/form";
@@ -18,7 +18,7 @@ export const DynamicSectionEditModal = createModal<ModalProps>(({ actions, inner
   const t = useI18n();
   const theme = useMantineTheme();
 
-  const form = useZodForm(dynamicSectionOptionsSchema, {
+  const form = useZodForm(dynamicSectionOptionsSchema.unwrap(), {
     mode: "controlled",
     initialValues: { ...innerProps.value },
   });
@@ -32,6 +32,21 @@ export const DynamicSectionEditModal = createModal<ModalProps>(({ actions, inner
     >
       <Stack>
         <TextInput label={t("section.dynamic.option.title.label")} data-autofocus {...form.getInputProps("title")} />
+        <Switch
+          label={t("section.option.showLabel.label")}
+          description={t("section.option.showLabel.description")}
+          {...form.getInputProps("showLabel", { type: "checkbox" })}
+        />
+        <Switch
+          label={t("section.option.collapsible.label")}
+          description={t("section.option.collapsible.description")}
+          {...form.getInputProps("collapsible", { type: "checkbox" })}
+        />
+        <Switch
+          label={t("section.option.showOpenAll.label")}
+          description={t("section.option.showOpenAll.description")}
+          {...form.getInputProps("showOpenAll", { type: "checkbox" })}
+        />
         <TextMultiSelect
           label={t("section.dynamic.option.customCssClasses.label")}
           {...form.getInputProps("customCssClasses")}

apps/nextjs/src/components/board/sections/dynamic/dynamic-menu.tsx

@@ -1,11 +1,13 @@
 import { ActionIcon, Menu } from "@mantine/core";
-import { IconDotsVertical, IconPencil, IconTrash } from "@tabler/icons-react";
+import { IconArrowsMove, IconLayoutKanban, IconPencil, IconTrash } from "@tabler/icons-react";
 
 import { useEditMode } from "@homarr/boards/edit-mode";
 import { useConfirmModal, useModalAction } from "@homarr/modals";
 import { useI18n, useScopedI18n } from "@homarr/translation/client";
 
 import type { DynamicSectionItem } from "~/app/[locale]/boards/_types";
+import { useOpenItemMoveModal } from "../../items/item-move-modal";
+import { useSectionContext } from "../section-context";
 import { useDynamicSectionActions } from "./dynamic-actions";
 import { DynamicSectionEditModal } from "./dynamic-edit-modal";
 
@@ -14,9 +16,13 @@ export const BoardDynamicSectionMenu = ({ section }: { section: DynamicSectionIt
   const tDynamic = useScopedI18n("section.dynamic");
   const tItem = useScopedI18n("item");
   const { openModal } = useModalAction(DynamicSectionEditModal);
+  const openMoveModal = useOpenItemMoveModal();
   const { updateDynamicSection, removeDynamicSection } = useDynamicSectionActions();
   const { openConfirmModal } = useConfirmModal();
   const [isEditMode] = useEditMode();
+  const { section: parentSection } = useSectionContext();
+  const label = section.options.title || tDynamic("action.create");
+  const menuRightOffset = parentSection.kind === "dynamic" ? 44 : 4;
 
   if (!isEditMode) return null;
 
@@ -50,11 +56,11 @@ export const BoardDynamicSectionMenu = ({ section }: { section: DynamicSectionIt
           radius={"xl"}
           pos="absolute"
           top={4}
-          right={4}
+          right={menuRightOffset}
           style={{ zIndex: 10 }}
-          aria-label={tItem("menu.label.settings")}
+          aria-label={tItem("menu.label.settingsFor", { name: label })}
         >
-          <IconDotsVertical size={"1rem"} />
+          <IconLayoutKanban size={"1rem"} />
         </ActionIcon>
       </Menu.Target>
       <Menu.Dropdown miw={128}>
@@ -62,6 +68,17 @@ export const BoardDynamicSectionMenu = ({ section }: { section: DynamicSectionIt
         <Menu.Item leftSection={<IconPencil size={16} />} onClick={openEditModal}>
           {tItem("action.edit")}
         </Menu.Item>
+        <Menu.Item
+          leftSection={<IconArrowsMove size={16} />}
+          onClick={() =>
+            openMoveModal({
+              entry: section,
+              sourceSectionId: section.parentSectionId,
+            })
+          }
+        >
+          {tItem("action.moveResize")}
+        </Menu.Item>
         <Menu.Divider />
         <Menu.Label c="red.6">{t("common.dangerZone")}</Menu.Label>
         <Menu.Item c="red.6" leftSection={<IconTrash size={16} />} onClick={openRemoveModal}>

apps/nextjs/src/components/board/sections/empty-section.tsx

@@ -1,25 +1,32 @@
-import combineClasses from "clsx";
-
 import { useEditMode } from "@homarr/boards/edit-mode";
+import { useScopedI18n } from "@homarr/translation/client";
 
 import type { EmptySection } from "~/app/[locale]/boards/_types";
-import { GridStack } from "./gridstack/gridstack";
+import { SectionGrid } from "./grid/section-grid";
 import { useSectionItems } from "./use-section-items";
 
 interface Props {
   section: EmptySection;
+  columnCount: number;
+  requestedRowCount: number;
+  railPlacement?: "main" | "left" | "right";
 }
 
-export const BoardEmptySection = ({ section }: Props) => {
+export const BoardEmptySection = ({ section, columnCount, requestedRowCount, railPlacement = "main" }: Props) => {
   const { items, innerSections } = useSectionItems(section.id);
   const totalLength = items.length + innerSections.length;
   const [isEditMode] = useEditMode();
+  const t = useScopedI18n("board.landmark");
+
+  if (totalLength === 0 && !isEditMode && requestedRowCount === 0) return null;
 
   return (
-    <GridStack
+    <SectionGrid
       section={section}
-      style={{ transitionDuration: "0s" }}
-      className={combineClasses("min-row", totalLength > 0 || isEditMode ? undefined : "grid-stack-empty-wrapper")}
+      columnCount={columnCount}
+      requestedRowCount={requestedRowCount}
+      label={t("items")}
+      railPlacement={railPlacement}
     />
   );
 };

apps/nextjs/src/components/board/sections/grid/fixed-grid-item.tsx

@@ -0,0 +1,201 @@
+"use client";
+
+import type { FocusEvent, KeyboardEvent, PropsWithChildren } from "react";
+import { useId, useState } from "react";
+import { Box } from "@mantine/core";
+import combineClasses from "clsx";
+
+import { useCurrentLayout } from "@homarr/boards/context";
+import { useEditMode } from "@homarr/boards/edit-mode";
+import { useI18n } from "@homarr/translation/client";
+
+import type { DynamicSectionItem, SectionItem } from "~/app/[locale]/boards/_types";
+import {
+  getEditableGridCellAttributes,
+  getLayoutRowCount,
+  getLogicalItemStyle,
+  getReadonlyGridItemAttributes,
+  placeGridItem,
+} from "~/components/board/layout";
+import type { GridPlacement } from "~/components/board/layout";
+import { useSectionContext } from "../section-context";
+import classes from "./section-grid.module.css";
+import type { SectionGridPlacement } from "./use-grid-layout-actions";
+import { useGridLayoutActions } from "./use-grid-layout-actions";
+
+interface FixedGridItemProps {
+  item: DynamicSectionItem | SectionItem;
+  minWidth?: number;
+  minHeight?: number;
+}
+
+export const FixedGridItem = ({
+  item,
+  minWidth = 1,
+  minHeight = 1,
+  children,
+}: PropsWithChildren<FixedGridItemProps>) => {
+  const [isEditMode] = useEditMode();
+  const currentLayoutId = useCurrentLayout();
+  const t = useI18n();
+  const { section, items, innerSections, columnCount, maxRowCount, announce } = useSectionContext();
+  const { commitSectionGrid } = useGridLayoutActions();
+  const [isKeyboardEditing, setIsKeyboardEditing] = useState(false);
+  const instructionsId = useId();
+  const placement = toPlacement(item);
+  const displayName =
+    item.type === "item"
+      ? item.advancedOptions.title?.trim() || t(`widget.${item.kind}.name`)
+      : item.options.title.trim() || t("section.dynamic.untitled");
+  const accessibleLabel = t("item.moveResize.entryLabel", {
+    name: displayName,
+    column: String(placement.x + 1),
+    row: String(placement.y + 1),
+  });
+
+  const setKeyboardEditing = (next: boolean) => {
+    setIsKeyboardEditing(next);
+    announce(
+      `${accessibleLabel}: ${t(next ? "item.moveResize.keyboard.started" : "item.moveResize.keyboard.stopped")}`,
+    );
+  };
+
+  const handleKeyboard = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.target !== event.currentTarget || !isEditMode || event.altKey || event.ctrlKey || event.metaKey) {
+      return;
+    }
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      setKeyboardEditing(!isKeyboardEditing);
+      return;
+    }
+    if (event.key === "Escape" && isKeyboardEditing) {
+      event.preventDefault();
+      setKeyboardEditing(false);
+      return;
+    }
+    if (!isKeyboardEditing || !isArrowKey(event.key)) return;
+
+    event.preventDefault();
+    const allPlacements = [...items, ...innerSections].map(toPlacement);
+    const current = allPlacements.find((candidate) => candidate.id === item.id);
+    if (!current) return;
+
+    const next = getKeyboardPlacement(current, event.key, event.shiftKey, {
+      columnCount,
+      minWidth,
+      minHeight,
+      maxRowCount,
+    });
+    if (next.x === current.x && next.y === current.y && next.w === current.w && next.h === current.h) {
+      announce(`${accessibleLabel}: ${t("item.moveResize.keyboard.boundary")}`);
+      return;
+    }
+
+    const resolved = placeGridItem(allPlacements, next, columnCount) as SectionGridPlacement[];
+    if (maxRowCount !== null && getLayoutRowCount(resolved) > maxRowCount) {
+      announce(`${accessibleLabel}: ${t("item.moveResize.keyboard.boundary")}`);
+      return;
+    }
+    commitSectionGrid({ layoutId: currentLayoutId, sectionId: section.id, placements: resolved });
+    announce(
+      `${displayName}: ${t("item.moveResize.field.xOffset.label")} ${next.x + 1}, ${t(
+        "item.moveResize.field.yOffset.label",
+      )} ${next.y + 1}, ${t("item.moveResize.field.width.label")} ${next.w}, ${t(
+        "item.moveResize.field.height.label",
+      )} ${next.h}`,
+    );
+  };
+
+  const handleBlur = (event: FocusEvent<HTMLDivElement>) => {
+    if (isKeyboardEditing && !event.currentTarget.contains(event.relatedTarget)) {
+      setIsKeyboardEditing(false);
+    }
+  };
+
+  const semantics = isEditMode
+    ? getEditableGridCellAttributes({ label: accessibleLabel, placement })
+    : getReadonlyGridItemAttributes(placement);
+
+  return (
+    <Box
+      {...semantics}
+      className={combineClasses(isEditMode ? classes.editorEntry : classes.staticItem)}
+      style={isEditMode ? { position: "relative", width: "100%", height: "100%" } : getLogicalItemStyle(placement)}
+      data-grid-item-id={isEditMode ? undefined : item.id}
+      data-grid-item-type={isEditMode ? undefined : item.type}
+      data-editor-grid-entry={isEditMode ? "true" : undefined}
+      data-type={item.type}
+      data-kind={item.kind}
+      data-keyboard-editing={isEditMode ? String(isKeyboardEditing) : undefined}
+      aria-describedby={isEditMode ? instructionsId : undefined}
+      aria-keyshortcuts={
+        isEditMode
+          ? "Enter Space Escape ArrowLeft ArrowRight ArrowUp ArrowDown Shift+ArrowLeft Shift+ArrowRight Shift+ArrowUp Shift+ArrowDown"
+          : undefined
+      }
+      onBlur={isEditMode ? handleBlur : undefined}
+      onKeyDown={isEditMode ? handleKeyboard : undefined}
+    >
+      {children}
+      {isEditMode && (
+        <span id={instructionsId} className={classes.liveRegion}>
+          {t("item.moveResize.keyboard.instructions")}
+        </span>
+      )}
+    </Box>
+  );
+};
+
+const toPlacement = (item: DynamicSectionItem | SectionItem): SectionGridPlacement => ({
+  id: item.id,
+  type: item.type,
+  x: item.xOffset,
+  y: item.yOffset,
+  w: item.width,
+  h: item.height,
+});
+
+const isArrowKey = (key: string): key is "ArrowLeft" | "ArrowRight" | "ArrowUp" | "ArrowDown" =>
+  key === "ArrowLeft" || key === "ArrowRight" || key === "ArrowUp" || key === "ArrowDown";
+
+const getKeyboardPlacement = (
+  current: SectionGridPlacement,
+  key: "ArrowLeft" | "ArrowRight" | "ArrowUp" | "ArrowDown",
+  resize: boolean,
+  {
+    columnCount,
+    minWidth,
+    minHeight,
+    maxRowCount,
+  }: {
+    columnCount: number;
+    minWidth: number;
+    minHeight: number;
+    maxRowCount: number | null;
+  },
+): GridPlacement & Pick<SectionGridPlacement, "type"> => {
+  if (resize) {
+    const widthDelta = key === "ArrowLeft" ? -1 : key === "ArrowRight" ? 1 : 0;
+    const heightDelta = key === "ArrowUp" ? -1 : key === "ArrowDown" ? 1 : 0;
+    return {
+      ...current,
+      w: Math.max(minWidth, Math.min(columnCount - current.x, current.w + widthDelta)),
+      h: Math.max(
+        minHeight,
+        Math.min(maxRowCount === null ? Number.MAX_SAFE_INTEGER : maxRowCount - current.y, current.h + heightDelta),
+      ),
+    };
+  }
+
+  const xDelta = key === "ArrowLeft" ? -1 : key === "ArrowRight" ? 1 : 0;
+  const yDelta = key === "ArrowUp" ? -1 : key === "ArrowDown" ? 1 : 0;
+  return {
+    ...current,
+    x: Math.max(0, Math.min(columnCount - current.w, current.x + xDelta)),
+    y: Math.max(
+      0,
+      Math.min(maxRowCount === null ? Number.MAX_SAFE_INTEGER : maxRowCount - current.h, current.y + yDelta),
+    ),
+  };
+};

apps/nextjs/src/components/board/sections/grid/grid-editor-loader.ts

@@ -0,0 +1,76 @@
+"use client";
+
+import type * as GridEditorModule from "./grid-editor";
+
+let editorModulePromise: Promise<typeof GridEditorModule> | undefined;
+
+export const loadGridEditorAsync = () => {
+  editorModulePromise ??= import("./grid-editor").catch((error: unknown) => {
+    editorModulePromise = undefined;
+    throw error;
+  });
+
+  return editorModulePromise;
+};
+
+export const scheduleGridEditorWarmup = (loadAsync: () => Promise<unknown>) => {
+  let animationFrameId: number | undefined;
+  let idleCallbackId: number | undefined;
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  let hydrationObserver: MutationObserver | undefined;
+  let cancelled = false;
+
+  const load = () => {
+    if (!cancelled) void loadAsync().catch(() => undefined);
+  };
+  const scheduleAfterPaint = () => {
+    animationFrameId = window.requestAnimationFrame(() => {
+      if ("requestIdleCallback" in window) {
+        idleCallbackId = window.requestIdleCallback(load, { timeout: 2_000 });
+      } else {
+        timeoutId = setTimeout(load, 1_000);
+      }
+    });
+  };
+  const scheduleWhenInteractive = () => {
+    if (document.querySelector('[data-board-hydrated="true"]')) {
+      scheduleAfterPaint();
+      return;
+    }
+
+    hydrationObserver = new MutationObserver(() => {
+      if (!document.querySelector('[data-board-hydrated="true"]')) return;
+      hydrationObserver?.disconnect();
+      hydrationObserver = undefined;
+      scheduleAfterPaint();
+    });
+    hydrationObserver.observe(document.documentElement, {
+      attributeFilter: ["data-board-hydrated"],
+      attributes: true,
+      childList: true,
+      subtree: true,
+    });
+  };
+  const handleVisibilityChange = () => {
+    if (document.visibilityState !== "visible") return;
+    document.removeEventListener("visibilitychange", handleVisibilityChange);
+    scheduleWhenInteractive();
+  };
+
+  if (document.visibilityState === "visible") {
+    scheduleWhenInteractive();
+  } else {
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+  }
+
+  return () => {
+    cancelled = true;
+    document.removeEventListener("visibilitychange", handleVisibilityChange);
+    hydrationObserver?.disconnect();
+    if (animationFrameId !== undefined) window.cancelAnimationFrame(animationFrameId);
+    if (idleCallbackId !== undefined && "cancelIdleCallback" in window) {
+      window.cancelIdleCallback(idleCallbackId);
+    }
+    if (timeoutId !== undefined) clearTimeout(timeoutId);
+  };
+};

apps/nextjs/src/components/board/sections/grid/grid-editor.css

@@ -0,0 +1,36 @@
+.grid-stack.grid-stack-editing > .grid-stack-placeholder > .placeholder-content {
+  background: color-mix(in srgb, var(--mantine-primary-color-filled) 20%, transparent);
+  border: 2px dashed var(--mantine-primary-color-filled);
+  border-radius: var(--mantine-radius-md);
+}
+
+.grid-stack.grid-stack-editing > .grid-stack-item.ui-draggable-dragging {
+  filter: drop-shadow(var(--mantine-shadow-lg));
+}
+
+.grid-stack.grid-stack-editing > .grid-stack-item > .ui-resizable-handle {
+  z-index: 8;
+}
+
+.grid-stack.grid-stack-editing > .grid-stack-item > .ui-resizable-e,
+.grid-stack.grid-stack-editing > .grid-stack-item > .ui-resizable-w {
+  width: 28px;
+}
+
+.grid-stack.grid-stack-editing > .grid-stack-item > .ui-resizable-s {
+  height: 28px;
+}
+
+.grid-stack.grid-stack-editing > .grid-stack-item > .ui-resizable-se,
+.grid-stack.grid-stack-editing > .grid-stack-item > .ui-resizable-sw {
+  width: 28px;
+  height: 28px;
+  background-size: 12px 12px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .grid-stack.grid-stack-editing,
+  .grid-stack.grid-stack-editing .grid-stack-item {
+    transition: none !important;
+  }
+}

apps/nextjs/src/components/board/sections/grid/grid-editor.tsx

@@ -0,0 +1,421 @@
+"use client";
+
+import type { CSSProperties } from "react";
+import { useCallback, useLayoutEffect, useMemo, useRef } from "react";
+
+import "gridstack/dist/gridstack.min.css"; // oxlint-disable-line import/no-unassigned-import
+import "./grid-editor.css"; // oxlint-disable-line import/no-unassigned-import
+
+import type { AddRemoveFcn, GridItemHTMLElement, GridStackNode, GridStackWidget } from "gridstack";
+import { GridStack } from "gridstack";
+
+import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
+import { useI18n } from "@homarr/translation/client";
+
+import { getLogicalTrackSize, LOGICAL_GRID_GAP, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { useSectionContext } from "../section-context";
+import { useBoardGridPortalHost } from "./grid-portal-host";
+import { decorateGridResizeHandles } from "./grid-resize-handles";
+import type { SectionGridPlacement } from "./use-grid-layout-actions";
+import { useGridLayoutActions } from "./use-grid-layout-actions";
+
+const AUTO_EXPAND_ROW_BUFFER = 8;
+
+interface GridEditorProps {
+  sectionId: string;
+  columnCount: number;
+  rowCount: number;
+  fixedRowCount: boolean;
+  placements: readonly SectionGridPlacement[];
+  className: string;
+}
+
+/**
+ * The only board module that imports GridStack. The library owns every
+ * positioned shell, while one board-level portal host owns React content.
+ * Moving a shell between independent grids therefore never reparents a
+ * React-owned element.
+ */
+export default function GridEditor({
+  sectionId,
+  columnCount,
+  rowCount,
+  fixedRowCount,
+  placements,
+  className,
+}: GridEditorProps) {
+  const board = useRequiredBoard();
+  const currentLayoutId = useCurrentLayout();
+  const t = useI18n();
+  const { announce, innerSections, items } = useSectionContext();
+  const { acquireContainer, releaseContainer } = useBoardGridPortalHost();
+  const { commitSectionGrid, commitSectionGrids } = useGridLayoutActions();
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const gridRef = useRef<GridStack | null>(null);
+  const applyingControlledLayoutRef = useRef(false);
+  const placementsRef = useRef(placements);
+  const entriesRef = useRef([...items, ...innerSections]);
+  const acceptWidgetRef = useRef<(element: Element) => boolean>(() => false);
+  const dimensionsRef = useRef({ columnCount, fixedRowCount, rowCount });
+
+  placementsRef.current = placements;
+  entriesRef.current = [...items, ...innerSections];
+  dimensionsRef.current = { columnCount, fixedRowCount, rowCount };
+
+  const forbiddenDynamicSectionIds = useMemo(
+    () => getTargetAncestorSectionIds(board.sections, currentLayoutId, sectionId),
+    [board.sections, currentLayoutId, sectionId],
+  );
+  acceptWidgetRef.current = (element) => {
+    const node = (element as GridItemHTMLElement).gridstackNode;
+    const id = element.getAttribute("data-grid-item-id") ?? node?.id;
+    if (!id) return false;
+    if ((node?.minW ?? 1) > columnCount) return false;
+    if (fixedRowCount && (node?.minH ?? 1) > rowCount) return false;
+
+    return element.getAttribute("data-grid-item-type") !== "section" || !forbiddenDynamicSectionIds.has(String(id));
+  };
+
+  const shellCallback = useCallback<AddRemoveFcn>(
+    (_parent, widget, add, isGrid) => {
+      if (isGrid) return undefined;
+      const id = widget.id ? String(widget.id) : null;
+      if (!id) return undefined;
+
+      if (!add) {
+        const element = (widget as GridStackNode).el;
+        const container = element?.querySelector<HTMLElement>(":scope > .grid-stack-item-content");
+        if (container) releaseContainer(id, container);
+        element?.remove();
+        return undefined;
+      }
+
+      const element = document.createElement("div") as GridItemHTMLElement;
+      element.className = "grid-stack-item";
+      element.appendChild(acquireContainer(id));
+      return element;
+    },
+    [acquireContainer, releaseContainer],
+  );
+
+  const snapshotGrid = useCallback(
+    (grid: GridStack | undefined) => {
+      if (!grid?.el) return null;
+      const snapshotSectionId = grid.el.getAttribute("data-grid-section-id");
+      if (!snapshotSectionId) return null;
+
+      return {
+        layoutId: currentLayoutId,
+        sectionId: snapshotSectionId,
+        placements: getGridPlacements(grid),
+      };
+    },
+    [currentLayoutId],
+  );
+
+  const commitGrid = useCallback(
+    (grid: GridStack | undefined) => {
+      if (applyingControlledLayoutRef.current) return;
+      const snapshot = snapshotGrid(grid);
+      if (snapshot) commitSectionGrid(snapshot);
+    },
+    [commitSectionGrid, snapshotGrid],
+  );
+
+  const announceNode = useCallback(
+    (node: GridStackNode | undefined) => {
+      if (!node?.id) return;
+      const entry = entriesRef.current.find((candidate) => candidate.id === String(node.id));
+      const displayName =
+        entry?.type === "item"
+          ? entry.advancedOptions.title?.trim() || t(`widget.${entry.kind}.name`)
+          : entry?.type === "section"
+            ? entry.options.title.trim() || t("section.dynamic.untitled")
+            : t("item.action.moveResize");
+      const label = t("item.moveResize.entryLabel", {
+        name: displayName,
+        column: String((node.x ?? 0) + 1),
+        row: String((node.y ?? 0) + 1),
+      });
+      announce(
+        `${label}: ${t("item.moveResize.field.width.label")} ${node.w ?? 1}, ${t(
+          "item.moveResize.field.height.label",
+        )} ${node.h ?? 1}`,
+      );
+    },
+    [announce, t],
+  );
+  const eventHandlersRef = useRef({
+    announceNode,
+    commitGrid,
+    commitSectionGrids,
+    snapshotGrid,
+  });
+  eventHandlersRef.current = {
+    announceNode,
+    commitGrid,
+    commitSectionGrids,
+    snapshotGrid,
+  };
+
+  useLayoutEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (!wrapper) return;
+    const dimensions = dimensionsRef.current;
+
+    const grid = GridStack.init(
+      {
+        acceptWidgets: (element) => acceptWidgetRef.current(element),
+        alwaysShowResizeHandle: true,
+        animate: !window.matchMedia("(prefers-reduced-motion: reduce)").matches,
+        cellHeight: LOGICAL_GRID_PITCH,
+        column: dimensions.columnCount,
+        draggable: {
+          cancel:
+            'a,button,input,textarea,select,option,[contenteditable="true"],[role="button"],[data-grid-no-drag],.ui-resizable-handle',
+          handle: "[data-editor-grid-entry]",
+          scroll: true,
+        },
+        float: true,
+        margin: `0 ${LOGICAL_GRID_GAP}px ${LOGICAL_GRID_GAP}px 0`,
+        maxRow: dimensions.fixedRowCount ? dimensions.rowCount : 0,
+        minRow: dimensions.fixedRowCount ? dimensions.rowCount : 1,
+        resizable: {
+          autoHide: false,
+          handles: "e, se, s, sw, w",
+        },
+      },
+      wrapper,
+    );
+    if (!grid) return;
+
+    // GridStack infers a native sub-grid from DOM nesting. Homarr owns nested
+    // grids independently so content can move between them without remounting;
+    // keeping the inferred link makes parent/child teardown order unsafe.
+    const inferredParentNode = grid.parentGridNode;
+    if (inferredParentNode) {
+      if (inferredParentNode.subGrid === grid) delete inferredParentNode.subGrid;
+      delete grid.parentGridNode;
+      wrapper.classList.remove("grid-stack-nested");
+      inferredParentNode.el?.classList.remove("grid-stack-sub-grid");
+    }
+
+    gridRef.current = grid;
+    wrapper.setAttribute("data-grid-section-id", sectionId);
+    wrapper.classList.add("grid-stack-editing");
+
+    const handleStop = (_event: Event, element: GridItemHTMLElement) => {
+      eventHandlersRef.current.commitGrid(element.gridstackNode?.grid ?? grid);
+      eventHandlersRef.current.announceNode(element.gridstackNode);
+      decorateGrid(element.gridstackNode?.grid ?? grid, placementsRef.current);
+      restoreContentHeight(grid);
+    };
+    const handleDragStart = () => {
+      const currentDimensions = dimensionsRef.current;
+      if (currentDimensions.fixedRowCount) return;
+
+      grid.updateOptions({
+        minRow: currentDimensions.rowCount + AUTO_EXPAND_ROW_BUFFER,
+      });
+      setViewportRowCount(grid, currentDimensions.rowCount + AUTO_EXPAND_ROW_BUFFER);
+    };
+    const handleDropped = (
+      _event: Event,
+      previousNode: GridStackNode | undefined,
+      newNode: GridStackNode | undefined,
+    ) => {
+      queueMicrotask(() => {
+        if (applyingControlledLayoutRef.current) return;
+        const snapshots = uniqueGrids([previousNode?.grid, newNode?.grid ?? grid])
+          .map((changedGrid) => eventHandlersRef.current.snapshotGrid(changedGrid))
+          .filter((snapshot) => snapshot !== null);
+        if (snapshots.length > 0) eventHandlersRef.current.commitSectionGrids(snapshots);
+        eventHandlersRef.current.announceNode(newNode);
+        for (const changedGrid of uniqueGrids([previousNode?.grid, newNode?.grid])) {
+          decorateGrid(changedGrid, placementsRef.current);
+          restoreContentHeight(changedGrid);
+        }
+      });
+    };
+
+    grid.on("dragstart", handleDragStart);
+    grid.on("dragstop", handleStop);
+    grid.on("resizestop", handleStop);
+    grid.on("dropped", handleDropped);
+
+    return () => {
+      grid.offAll();
+      const elements = grid.getGridItems();
+      for (const element of elements) {
+        const id = element.getAttribute("data-grid-item-id") ?? element.gridstackNode?.id;
+        const container = element.querySelector<HTMLElement>(":scope > .grid-stack-item-content");
+        if (id && container) releaseContainer(String(id), container);
+      }
+      grid.destroy(false);
+      for (const element of elements) element.remove();
+      if (gridRef.current === grid) gridRef.current = null;
+    };
+  }, [releaseContainer, sectionId, shellCallback]);
+
+  useLayoutEffect(() => {
+    const grid = gridRef.current;
+    if (!grid) return;
+    grid.updateOptions({
+      column: columnCount,
+      maxRow: fixedRowCount ? rowCount : 0,
+      minRow: fixedRowCount ? rowCount : 1,
+    });
+  }, [columnCount, fixedRowCount, rowCount]);
+
+  useLayoutEffect(() => {
+    const grid = gridRef.current;
+    if (!grid) return;
+
+    applyingControlledLayoutRef.current = true;
+    grid.load(placements.map(toGridStackWidget), shellCallback);
+    applyingControlledLayoutRef.current = false;
+    decorateGrid(grid, placements);
+    restoreContentHeight(grid);
+
+    const actual = getGridPlacements(grid);
+    if (!arePlacementsEqual(actual, placements)) {
+      commitSectionGrid({ layoutId: currentLayoutId, sectionId, placements: actual });
+    }
+  }, [commitSectionGrid, currentLayoutId, placements, sectionId, shellCallback]);
+
+  return (
+    <>
+      <div
+        ref={wrapperRef}
+        className={className}
+        data-grid-section-id={sectionId}
+        style={
+          {
+            width: columnCount * LOGICAL_GRID_PITCH,
+            minHeight: rowCount * LOGICAL_GRID_PITCH,
+          } as CSSProperties
+        }
+      />
+      <span
+        data-grid-runtime="homarr-edit-grid-v1"
+        data-editor-section-id={sectionId}
+        aria-hidden="true"
+        style={{ position: "absolute", width: 1, height: 1, pointerEvents: "none" }}
+      />
+    </>
+  );
+}
+
+const toGridStackWidget = (placement: SectionGridPlacement): GridStackWidget => ({
+  id: placement.id,
+  x: placement.x,
+  y: placement.y,
+  w: placement.w,
+  h: placement.h,
+  minW: placement.minW ?? 1,
+  minH: placement.minH ?? 1,
+});
+
+const getGridPlacements = (grid: GridStack): SectionGridPlacement[] =>
+  grid.getGridItems().flatMap((element) => {
+    const node = element.gridstackNode;
+    const id = element.getAttribute("data-grid-item-id") ?? node?.id;
+    const type = element.getAttribute("data-grid-item-type");
+    if (!node || !id || (type !== "item" && type !== "section")) return [];
+
+    return [
+      {
+        id: String(id),
+        type,
+        x: node.x ?? 0,
+        y: node.y ?? 0,
+        w: node.w ?? 1,
+        h: node.h ?? 1,
+        minW: node.minW,
+        minH: node.minH,
+      },
+    ];
+  });
+
+const decorateGrid = (grid: GridStack | undefined, placements: readonly SectionGridPlacement[]) => {
+  if (!grid?.el) return;
+  const placementById = new Map(placements.map((placement) => [placement.id, placement]));
+  grid.el.classList.add("grid-stack-editing");
+  for (const item of grid.getGridItems()) {
+    const id = item.getAttribute("data-grid-item-id") ?? item.gridstackNode?.id;
+    const placement = id ? placementById.get(String(id)) : undefined;
+    decorateItem(item, placement?.type ?? getElementItemType(item));
+  }
+};
+
+const decorateItem = (element: GridItemHTMLElement, type: SectionGridPlacement["type"] | undefined) => {
+  const node = element.gridstackNode;
+  if (!node?.id) return;
+
+  element.setAttribute("data-grid-item-id", String(node.id));
+  if (type) element.setAttribute("data-grid-item-type", type);
+  element.setAttribute("data-grid-x", String(node.x ?? 0));
+  element.setAttribute("data-grid-y", String(node.y ?? 0));
+  element.setAttribute("data-grid-w", String(node.w ?? 1));
+  element.setAttribute("data-grid-h", String(node.h ?? 1));
+  decorateGridResizeHandles(element);
+};
+
+const getElementItemType = (element: Element): SectionGridPlacement["type"] | undefined => {
+  const type = element.getAttribute("data-grid-item-type");
+  return type === "item" || type === "section" ? type : undefined;
+};
+
+const arePlacementsEqual = (first: readonly SectionGridPlacement[], second: readonly SectionGridPlacement[]) => {
+  if (first.length !== second.length) return false;
+  const secondById = new Map(second.map((placement) => [placement.id, placement]));
+  return first.every((placement) => {
+    const other = secondById.get(placement.id);
+    return (
+      other !== undefined &&
+      placement.type === other.type &&
+      placement.x === other.x &&
+      placement.y === other.y &&
+      placement.w === other.w &&
+      placement.h === other.h
+    );
+  });
+};
+
+const uniqueGrids = (grids: Array<GridStack | undefined>) =>
+  Array.from(new Set(grids.filter((grid): grid is GridStack => grid !== undefined)));
+
+const restoreContentHeight = (grid: GridStack | undefined) => {
+  if (!grid || (grid.opts.maxRow ?? 0) > 0) return;
+  const contentRowCount = Math.max(1, ...getGridPlacements(grid).map((placement) => placement.y + placement.h));
+  grid.updateOptions({ minRow: contentRowCount });
+  setViewportRowCount(grid, contentRowCount);
+};
+
+const setViewportRowCount = (grid: GridStack, rowCount: number) => {
+  const viewport = grid.el.parentElement;
+  if (!viewport?.hasAttribute("data-section-id")) return;
+  viewport.style.setProperty("--board-grid-drag-height", `${getLogicalTrackSize(rowCount)}px`);
+};
+
+const getTargetAncestorSectionIds = (
+  sections: ReturnType<typeof useRequiredBoard>["sections"],
+  layoutId: string,
+  targetSectionId: string,
+) => {
+  const parentById = new Map(
+    sections
+      .filter((section) => section.kind === "dynamic")
+      .flatMap((section) => {
+        const layout = section.layouts.find((candidate) => candidate.layoutId === layoutId);
+        return layout ? ([[section.id, layout.parentSectionId]] as const) : [];
+      }),
+  );
+  const ancestors = new Set<string>();
+  let current: string | undefined = targetSectionId;
+  while (current && !ancestors.has(current)) {
+    ancestors.add(current);
+    current = parentById.get(current);
+  }
+  return ancestors;
+};

apps/nextjs/src/components/board/sections/grid/grid-portal-host.tsx

@@ -0,0 +1,194 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import type { GridItemHTMLElement } from "gridstack";
+
+import type { RouterOutputs } from "@homarr/api";
+import { useIntegrations } from "@homarr/auth/client";
+import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
+import { getRootSectionLane } from "@homarr/definitions";
+
+import type { DynamicSectionItem, Section } from "~/app/[locale]/boards/_types";
+import { getBoardLaneColumnCount } from "~/components/board/layout";
+import { SectionContentItem } from "../content";
+import { SectionProvider } from "../section-context";
+import { useSectionItems } from "../use-section-items";
+import { decorateGridResizeHandles } from "./grid-resize-handles";
+import classes from "./section-grid.module.css";
+
+interface GridPortalHostContextValue {
+  announce: (message: string) => void;
+  integrations: RouterOutputs["integration"]["all"] | undefined;
+  acquireContainer: (id: string) => HTMLElement;
+  releaseContainer: (id: string, container: HTMLElement) => void;
+}
+
+const GridPortalHostContext = createContext<GridPortalHostContextValue | null>(null);
+
+/**
+ * One portal registry owns every edit-mode item on the board. Its content
+ * containers are stable even when GridStack replaces or transfers the outer
+ * positioning shell, so moving between grids does not remount widget content.
+ */
+export const BoardGridPortalHost = ({ children }: PropsWithChildren) => {
+  const board = useRequiredBoard();
+  const currentLayoutId = useCurrentLayout();
+  const integrations = useIntegrations();
+  const containersRef = useRef<Map<string, HTMLElement>>(new Map());
+  const [containers, setContainers] = useState<Map<string, HTMLElement>>(() => new Map());
+  const [announcement, setAnnouncement] = useState({ id: 0, message: "" });
+  const announce = useCallback((message: string) => {
+    setAnnouncement((previous) => ({ id: previous.id + 1, message }));
+  }, []);
+
+  const acquireContainer = useCallback((id: string) => {
+    const existing = containersRef.current.get(id);
+    if (existing) return existing;
+
+    const container = document.createElement("div");
+    container.className = "grid-stack-item-content";
+    container.style.overflow = "visible";
+    containersRef.current.set(id, container);
+    setContainers(new Map(containersRef.current));
+    return container;
+  }, []);
+
+  const releaseContainer = useCallback((id: string, container: HTMLElement) => {
+    // Controlled cross-grid moves remove the source shell before the target
+    // adopts this container. Wait until all grid effects in the commit ran.
+    queueMicrotask(() => {
+      if (container.isConnected || containersRef.current.get(id) !== container) return;
+      containersRef.current.delete(id);
+      setContainers(new Map(containersRef.current));
+    });
+  }, []);
+
+  const value = useMemo<GridPortalHostContextValue>(
+    () => ({
+      announce,
+      integrations,
+      acquireContainer,
+      releaseContainer,
+    }),
+    [acquireContainer, announce, integrations, releaseContainer],
+  );
+
+  return (
+    <GridPortalHostContext.Provider value={value}>
+      {children}
+      {Array.from(containers, ([id, container]) => {
+        const ownerSectionId = getOwnerSectionId(board, currentLayoutId, id);
+        return ownerSectionId
+          ? createPortal(
+              <GridPortalContent
+                itemId={id}
+                ownerSectionId={ownerSectionId}
+                container={container}
+                integrations={integrations}
+                announce={announce}
+              />,
+              container,
+              id,
+            )
+          : null;
+      })}
+      <div className={classes.liveRegion} aria-live="polite" aria-atomic="true">
+        <span key={announcement.id}>{announcement.message}</span>
+      </div>
+    </GridPortalHostContext.Provider>
+  );
+};
+
+export const useBoardGridPortalHost = () => {
+  const context = useContext(GridPortalHostContext);
+  if (!context) throw new Error("BoardGridPortalHost is required");
+  return context;
+};
+
+interface GridPortalContentProps {
+  itemId: string;
+  ownerSectionId: string;
+  container: HTMLElement;
+  integrations: RouterOutputs["integration"]["all"] | undefined;
+  announce: (message: string) => void;
+}
+
+const GridPortalContent = ({ itemId, ownerSectionId, container, integrations, announce }: GridPortalContentProps) => {
+  const board = useRequiredBoard();
+  const currentLayoutId = useCurrentLayout();
+  const { items, innerSections } = useSectionItems(ownerSectionId);
+  const entry = [...items, ...innerSections].find((candidate) => candidate.id === itemId);
+  const rawSection = board.sections.find((section) => section.id === ownerSectionId);
+  const currentLayout = board.layouts.find((layout) => layout.id === currentLayoutId);
+  const section = toGridSection(rawSection, currentLayoutId);
+
+  useLayoutEffect(() => {
+    const itemElement = container.parentElement as GridItemHTMLElement | null;
+    if (!itemElement) return;
+
+    itemElement.gridstackNode?.grid?.refreshDragHandles(itemElement);
+    decorateGridResizeHandles(itemElement);
+  }, [container, ownerSectionId]);
+
+  if (!entry || !section || !currentLayout) return null;
+
+  const columnCount =
+    section.kind === "dynamic"
+      ? section.width
+      : section.kind === "empty"
+        ? getBoardLaneColumnCount(currentLayout, getRootSectionLane(section.xOffset))
+        : currentLayout.columnCount;
+  const configuredMaxRowCount = section.kind === "dynamic" ? section.height : null;
+  const contentRowCount = Math.max(
+    1,
+    ...items.map((item) => item.yOffset + item.height),
+    ...innerSections.map((innerSection) => innerSection.yOffset + innerSection.height),
+  );
+  const maxRowCount = configuredMaxRowCount === null ? null : Math.max(configuredMaxRowCount, contentRowCount);
+
+  return (
+    <SectionProvider
+      value={{
+        section,
+        items,
+        innerSections,
+        integrations,
+        columnCount,
+        maxRowCount,
+        announce,
+      }}
+    >
+      <SectionContentItem item={entry} integrations={integrations} />
+    </SectionProvider>
+  );
+};
+
+const toGridSection = (
+  section: Section | undefined,
+  layoutId: string,
+): Exclude<Section, { kind: "dynamic" }> | DynamicSectionItem | null => {
+  if (!section) return null;
+  if (section.kind !== "dynamic") return section;
+
+  const layout = section.layouts.find((candidate) => candidate.layoutId === layoutId);
+  if (!layout) return null;
+
+  return {
+    ...section,
+    ...layout,
+    type: "section",
+  };
+};
+
+const getOwnerSectionId = (board: ReturnType<typeof useRequiredBoard>, layoutId: string, entryId: string) => {
+  const item = board.items.find((candidate) => candidate.id === entryId);
+  if (item) {
+    return item.layouts.find((layout) => layout.layoutId === layoutId)?.sectionId ?? null;
+  }
+
+  const section = board.sections.find((candidate) => candidate.kind === "dynamic" && candidate.id === entryId);
+  if (!section || section.kind !== "dynamic") return null;
+  return section.layouts.find((layout) => layout.layoutId === layoutId)?.parentSectionId ?? null;
+};

apps/nextjs/src/components/board/sections/grid/grid-resize-handles.ts

@@ -0,0 +1,16 @@
+export const decorateGridResizeHandles = (element: Element) => {
+  for (const handle of element.querySelectorAll<HTMLElement>(".ui-resizable-handle")) {
+    const direction = Array.from(handle.classList).find((className) =>
+      /^ui-resizable-(?:n|ne|e|se|s|sw|w|nw)$/.test(className),
+    );
+    if (!direction) continue;
+    const directionName = direction.replace("ui-resizable-", "");
+
+    handle.setAttribute(
+      "data-testid",
+      directionName === "se" ? "board-grid-resize-handle" : `board-grid-resize-handle-${directionName}`,
+    );
+    handle.setAttribute("data-grid-resize-direction", directionName);
+    handle.setAttribute("aria-hidden", "true");
+  }
+};

apps/nextjs/src/components/board/sections/grid/section-grid.module.css

@@ -0,0 +1,77 @@
+.viewport {
+  position: relative;
+  overflow: visible;
+}
+
+.staticGrid,
+.editorGrid {
+  position: relative;
+  overflow: visible;
+}
+
+.editorGrid {
+  position: absolute;
+  inset: 0 auto auto 0;
+}
+
+.editorGrid:not(:global(.grid-stack-editing)) {
+  visibility: hidden;
+}
+
+.staticItem {
+  overflow: visible;
+  transition:
+    left 220ms ease,
+    top 220ms ease,
+    width 220ms ease,
+    height 220ms ease;
+}
+
+.editorEntry {
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+  cursor: grab;
+}
+
+.editorEntry:active {
+  cursor: grabbing;
+}
+
+.editorEntry:focus-visible,
+.editorEntry[data-keyboard-editing="true"] {
+  outline: 2px solid var(--mantine-primary-color-filled);
+  outline-offset: 2px;
+  border-radius: var(--mantine-radius-md);
+}
+
+.editorLoading {
+  position: absolute;
+  inset: 0;
+  z-index: 20;
+  overflow: hidden;
+}
+
+.editorLoadingItem {
+  background-color: var(--mantine-color-default);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-md);
+}
+
+.liveRegion {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .staticItem {
+    transition: none;
+  }
+}

apps/nextjs/src/components/board/sections/grid/section-grid.tsx

@@ -0,0 +1,241 @@
+"use client";
+
+import { useMemo } from "react";
+import dynamic from "next/dynamic";
+import { Box, LoadingOverlay } from "@mantine/core";
+import combineClasses from "clsx";
+
+import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
+import { useEditMode } from "@homarr/boards/edit-mode";
+import { useI18n } from "@homarr/translation/client";
+
+import type { DynamicSectionItem, Section } from "~/app/[locale]/boards/_types";
+import {
+  getCollapsedDisplayLayout,
+  getEditableCanvasAttributes,
+  getLayoutRowCount,
+  getLogicalItemStyle,
+  getLogicalTrackSize,
+  getReadonlyCanvasAttributes,
+  normalizeGridPlacement,
+} from "~/components/board/layout";
+import { loadGridEditorAsync } from "./grid-editor-loader";
+import type { SectionGridPlacement } from "./use-grid-layout-actions";
+import { SectionContent } from "../content";
+import { useCollapsedSectionIds } from "../section-collapse";
+import { SectionProvider, useSectionContext } from "../section-context";
+import { useSectionItems } from "../use-section-items";
+import { useBoardGridPortalHost } from "./grid-portal-host";
+import classes from "./section-grid.module.css";
+
+const GridEditor = dynamic(loadGridEditorAsync, {
+  loading: GridEditorLoading,
+  ssr: false,
+});
+
+function GridEditorLoading() {
+  const t = useI18n();
+  const { items, innerSections } = useSectionContext();
+
+  return (
+    <Box
+      component="output"
+      className={classes.editorLoading}
+      data-testid="board-grid-editor-loading"
+      aria-label={t("common.action.loading")}
+    >
+      {[...items, ...innerSections].map((item) => (
+        <Box
+          key={item.id}
+          className={classes.editorLoadingItem}
+          style={getLogicalItemStyle({
+            x: item.xOffset,
+            y: item.yOffset,
+            w: item.width,
+            h: item.height,
+          })}
+          aria-hidden="true"
+        />
+      ))}
+      <LoadingOverlay visible />
+    </Box>
+  );
+}
+
+interface SectionGridProps {
+  section: Exclude<Section, { kind: "dynamic" }> | DynamicSectionItem;
+  columnCount: number;
+  requestedRowCount?: number;
+  label: string;
+  railPlacement?: "main" | "left" | "right";
+  className?: string;
+}
+
+export const SectionGrid = ({
+  section,
+  columnCount,
+  requestedRowCount = 0,
+  label,
+  railPlacement = "main",
+  className,
+}: SectionGridProps) => {
+  const [isEditMode] = useEditMode();
+  const board = useRequiredBoard();
+  const currentLayoutId = useCurrentLayout();
+  const { items, innerSections } = useSectionItems(section.id);
+  const { announce, integrations } = useBoardGridPortalHost();
+  const collapsedSectionIds = useCollapsedSectionIds();
+  const minimumBySectionId = useMemo(
+    () =>
+      new Map(
+        innerSections.map((innerSection) => [
+          innerSection.id,
+          getDynamicSectionMinimumSize(board, currentLayoutId, innerSection.id),
+        ]),
+      ),
+    [board, currentLayoutId, innerSections],
+  );
+
+  const placements = useMemo(
+    () =>
+      [...items, ...innerSections].map((item): SectionGridPlacement => {
+        const minimum = item.type === "section" ? minimumBySectionId.get(item.id) : undefined;
+        return normalizeGridPlacement(
+          {
+            id: item.id,
+            type: item.type,
+            x: item.xOffset,
+            y: item.yOffset,
+            w: item.width,
+            h: item.height,
+            minW: minimum?.width,
+            minH: minimum?.height,
+          },
+          columnCount,
+        );
+      }),
+    [columnCount, innerSections, items, minimumBySectionId],
+  );
+
+  const displayPlacements = useMemo(() => {
+    const directCollapsedIds = new Set(
+      placements
+        .filter(
+          (placement) =>
+            placement.type === "section" &&
+            collapsedSectionIds.has(placement.id) &&
+            innerSections.find((innerSection) => innerSection.id === placement.id)?.options.collapsible,
+        )
+        .map((placement) => placement.id),
+    );
+    if (directCollapsedIds.size === 0) return placements;
+
+    return getCollapsedDisplayLayout(placements, {
+      columnCount,
+      collapsedItemIds: directCollapsedIds,
+    });
+  }, [collapsedSectionIds, columnCount, innerSections, placements]);
+
+  const placementById = useMemo(
+    () => new Map(displayPlacements.map((placement) => [placement.id, placement])),
+    [displayPlacements],
+  );
+  const displayedItems = items.map((item) => withPlacement(item, placementById.get(item.id)));
+  const displayedInnerSections = innerSections.map((item) => withPlacement(item, placementById.get(item.id)));
+  const contentRowCount = Math.max(1, getLayoutRowCount(displayPlacements));
+  const rowCount = Math.max(contentRowCount, requestedRowCount);
+  const fixedRowCount = section.kind === "dynamic";
+  const logicalWidth = getLogicalTrackSize(columnCount);
+  const logicalHeight = getLogicalTrackSize(rowCount);
+  const canvasAttributes = isEditMode
+    ? getEditableCanvasAttributes({ label, columnCount, rowCount })
+    : getReadonlyCanvasAttributes({ label });
+
+  return (
+    <SectionProvider
+      value={{
+        section,
+        items: displayedItems,
+        innerSections: displayedInnerSections,
+        integrations,
+        columnCount,
+        maxRowCount: fixedRowCount ? rowCount : null,
+        announce,
+      }}
+    >
+      <Box
+        {...canvasAttributes}
+        className={combineClasses(classes.viewport, className)}
+        w={logicalWidth}
+        h={`var(--board-grid-drag-height, ${logicalHeight}px)`}
+        data-section-id={section.id}
+        data-section-kind={section.kind}
+        data-rail-placement={railPlacement}
+      >
+        {isEditMode ? (
+          <GridEditor
+            sectionId={section.id}
+            columnCount={columnCount}
+            rowCount={rowCount}
+            fixedRowCount={fixedRowCount}
+            placements={displayPlacements}
+            className={combineClasses("grid-stack", classes.editorGrid)}
+          />
+        ) : (
+          <Box
+            className={classes.staticGrid}
+            style={{ width: logicalWidth, height: logicalHeight }}
+            data-grid-section-id={section.id}
+            data-kind={section.kind}
+          >
+            <SectionContent />
+          </Box>
+        )}
+      </Box>
+    </SectionProvider>
+  );
+};
+
+const getDynamicSectionMinimumSize = (
+  board: ReturnType<typeof useRequiredBoard>,
+  layoutId: string,
+  sectionId: string,
+) => {
+  const directItems = board.items.flatMap((item) => {
+    const layout = item.layouts.find((candidate) => candidate.layoutId === layoutId);
+    return layout?.sectionId === sectionId ? [layout] : [];
+  });
+  const directSections = board.sections.flatMap((candidate) => {
+    if (candidate.kind !== "dynamic") return [];
+    const layout = candidate.layouts.find((candidateLayout) => candidateLayout.layoutId === layoutId);
+    return layout?.parentSectionId === sectionId ? [layout] : [];
+  });
+  const children = [...directItems, ...directSections];
+
+  return {
+    width: Math.max(1, ...children.map((child) => child.xOffset + child.width)),
+    height: Math.max(1, ...children.map((child) => child.yOffset + child.height)),
+  };
+};
+
+const withPlacement = <
+  TItem extends {
+    id: string;
+    xOffset: number;
+    yOffset: number;
+    width: number;
+    height: number;
+  },
+>(
+  item: TItem,
+  placement: SectionGridPlacement | undefined,
+): TItem => {
+  if (!placement) return item;
+  return {
+    ...item,
+    xOffset: placement.x,
+    yOffset: placement.y,
+    width: placement.w,
+    height: placement.h,
+  };
+};

apps/nextjs/src/components/board/sections/grid/test/fixed-grid-item.spec.ts

@@ -0,0 +1,254 @@
+import { act, createElement } from "react";
+import type { ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import type { Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { getCollapsedDisplayLayout, LOGICAL_GRID_CELL_SIZE } from "../../../layout";
+import { FixedGridItem } from "../fixed-grid-item";
+
+const mocks = vi.hoisted(() => ({
+  announce: vi.fn(),
+  commitSectionGrid: vi.fn(),
+  editMode: true,
+  maxRowCount: null as number | null,
+  items: [
+    {
+      id: "weather",
+      type: "item" as const,
+      kind: "weather" as const,
+      xOffset: 0,
+      yOffset: 0,
+      width: 1,
+      height: 1,
+      advancedOptions: {
+        title: null as string | null,
+      },
+    },
+    {
+      id: "clock",
+      type: "item" as const,
+      kind: "clock" as const,
+      xOffset: 1,
+      yOffset: 0,
+      width: 1,
+      height: 1,
+      advancedOptions: {
+        title: null as string | null,
+      },
+    },
+  ],
+}));
+
+vi.mock("@homarr/boards/edit-mode", () => ({
+  useEditMode: () => [mocks.editMode],
+}));
+
+vi.mock("@homarr/boards/context", () => ({
+  useCurrentLayout: () => "layout",
+}));
+
+vi.mock("@homarr/translation/client", () => ({
+  useI18n: () => (key: string, values?: Record<string, string>) =>
+    key === "item.moveResize.entryLabel" ? `${values?.name}, column ${values?.column}, row ${values?.row}` : key,
+}));
+
+vi.mock("../use-grid-layout-actions", () => ({
+  useGridLayoutActions: () => ({
+    commitSectionGrid: mocks.commitSectionGrid,
+  }),
+}));
+
+vi.mock("../../section-context", () => ({
+  useSectionContext: () => ({
+    section: { id: "root", kind: "empty", options: {} },
+    items: mocks.items,
+    innerSections: [],
+    columnCount: 3,
+    maxRowCount: mocks.maxRowCount,
+    announce: mocks.announce,
+  }),
+}));
+
+vi.mock("@mantine/core", async () => {
+  const React = await import("react");
+
+  return {
+    Box: ({ children, ...props }: { children?: ReactNode }) => React.createElement("div", props, children),
+  };
+});
+
+describe("fixed grid item behavior", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    mocks.announce.mockReset();
+    mocks.commitSectionGrid.mockReset();
+    mocks.editMode = true;
+    mocks.maxRowCount = null;
+    getWeatherMock().advancedOptions.title = null;
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  test("moves with the keyboard and deterministically pushes a collision down", () => {
+    renderWeather(root);
+
+    const entry = getEditorEntry(container);
+    startKeyboardEditing(entry);
+    act(() => entry.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true })));
+
+    expect(mocks.commitSectionGrid).toHaveBeenCalledWith({
+      layoutId: "layout",
+      sectionId: "root",
+      placements: [
+        { id: "weather", type: "item", x: 1, y: 0, w: 1, h: 1 },
+        { id: "clock", type: "item", x: 1, y: 1, w: 1, h: 1 },
+      ],
+    });
+    expect(mocks.announce).toHaveBeenCalledTimes(2);
+  });
+
+  test("uses shift plus an arrow to resize while honoring grid bounds", () => {
+    renderWeather(root);
+
+    const entry = getEditorEntry(container);
+    startKeyboardEditing(entry);
+    act(() =>
+      entry.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "ArrowRight",
+          shiftKey: true,
+          bubbles: true,
+        }),
+      ),
+    );
+
+    expect(mocks.commitSectionGrid).toHaveBeenCalledWith({
+      layoutId: "layout",
+      sectionId: "root",
+      placements: [
+        { id: "weather", type: "item", x: 0, y: 0, w: 2, h: 1 },
+        { id: "clock", type: "item", x: 1, y: 1, w: 1, h: 1 },
+      ],
+    });
+
+    mocks.commitSectionGrid.mockReset();
+    act(() =>
+      entry.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "ArrowLeft",
+          shiftKey: true,
+          bubbles: true,
+        }),
+      ),
+    );
+    expect(mocks.commitSectionGrid).not.toHaveBeenCalled();
+    expect(mocks.announce).toHaveBeenLastCalledWith(
+      "widget.weather.name, column 1, row 1: item.moveResize.keyboard.boundary",
+    );
+  });
+
+  test("uses the whole tile as the focusable move surface without a grab button", () => {
+    getWeatherMock().advancedOptions.title = "  Balcony forecast  ";
+    renderWeather(root);
+
+    const entry = getEditorEntry(container);
+
+    expect(entry.getAttribute("aria-label")).toBe("Balcony forecast, column 1, row 1");
+    expect(entry.tabIndex).toBe(0);
+    expect(entry.getAttribute("aria-describedby")).not.toBeNull();
+    expect(container.querySelector('[data-testid="board-grid-drag-handle"]')).toBeNull();
+  });
+
+  test("renders a view-only 1x1 card at the fixed 200px logical size", () => {
+    mocks.editMode = false;
+    renderWeather(root);
+
+    const item = container.querySelector<HTMLElement>('[data-grid-id="weather"]');
+    expect(item).not.toBeNull();
+    expect(item?.style.width).toBe(`${LOGICAL_GRID_CELL_SIZE}px`);
+    expect(item?.style.height).toBe(`${LOGICAL_GRID_CELL_SIZE}px`);
+    expect(item?.getAttribute("role")).toBeNull();
+
+    act(() => item?.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true })));
+    expect(mocks.commitSectionGrid).not.toHaveBeenCalled();
+  });
+
+  test("does not move or resize beyond a fixed section row boundary", () => {
+    mocks.maxRowCount = 1;
+    renderWeather(root);
+
+    const entry = getEditorEntry(container);
+    startKeyboardEditing(entry);
+    act(() => entry.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true })));
+    act(() => entry.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowDown", shiftKey: true, bubbles: true })));
+
+    expect(mocks.commitSectionGrid).not.toHaveBeenCalled();
+    expect(mocks.announce).toHaveBeenNthCalledWith(
+      2,
+      "widget.weather.name, column 1, row 1: item.moveResize.keyboard.boundary",
+    );
+    expect(mocks.announce).toHaveBeenNthCalledWith(
+      3,
+      "widget.weather.name, column 1, row 1: item.moveResize.keyboard.boundary",
+    );
+  });
+
+  test("collapsing an expanded box changes display geometry without mutating persisted placement", () => {
+    const persisted = [
+      { id: "box", type: "section" as const, x: 0, y: 0, w: 2, h: 4 },
+      { id: "app", type: "item" as const, x: 0, y: 4, w: 1, h: 1 },
+    ];
+
+    const displayed = getCollapsedDisplayLayout(persisted, {
+      columnCount: 2,
+      collapsedItemIds: new Set(["box"]),
+    });
+
+    expect(displayed).toEqual([
+      { ...persisted[0], h: 1 },
+      { ...persisted[1], y: 1 },
+    ]);
+    expect(persisted[0]?.h).toBe(4);
+    expect(persisted[1]?.y).toBe(4);
+  });
+});
+
+const renderWeather = (root: Root) => {
+  act(() => {
+    root.render(
+      createElement(
+        FixedGridItem,
+        {
+          item: getWeatherMock() as never,
+        },
+        createElement("span", null, "Weather"),
+      ),
+    );
+  });
+};
+
+const getWeatherMock = () => {
+  const item = mocks.items[0];
+  if (!item) throw new Error("Expected the weather item mock to exist");
+  return item;
+};
+
+const getEditorEntry = (container: HTMLElement) => {
+  const entry = container.querySelector<HTMLDivElement>("[data-editor-grid-entry]");
+  if (!entry) throw new Error("Expected the fixed grid item to render an editor entry");
+
+  return entry;
+};
+
+const startKeyboardEditing = (entry: HTMLDivElement) => {
+  act(() => entry.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true })));
+};

apps/nextjs/src/components/board/sections/grid/test/grid-editor-loader.spec.ts

@@ -0,0 +1,106 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import { scheduleGridEditorWarmup } from "../grid-editor-loader";
+
+describe("grid editor warm-up", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+  });
+
+  test("waits for board hydration, a paint, and browser idle time", async () => {
+    let animationFrameCallback: FrameRequestCallback | undefined;
+    let idleCallback: IdleRequestCallback | undefined;
+    vi.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => {
+      animationFrameCallback = callback;
+      return 1;
+    });
+    vi.stubGlobal("requestIdleCallback", (callback: IdleRequestCallback) => {
+      idleCallback = callback;
+      return 2;
+    });
+    vi.stubGlobal("cancelIdleCallback", vi.fn());
+    const loadAsync = vi.fn().mockResolvedValue(undefined);
+
+    const cancel = scheduleGridEditorWarmup(loadAsync);
+    expect(animationFrameCallback).toBeUndefined();
+
+    const canvas = document.createElement("section");
+    canvas.dataset.boardHydrated = "true";
+    document.body.append(canvas);
+    await vi.waitFor(() => expect(animationFrameCallback).toBeDefined());
+    expect(loadAsync).not.toHaveBeenCalled();
+
+    animationFrameCallback?.(0);
+    expect(idleCallback).toBeDefined();
+    expect(loadAsync).not.toHaveBeenCalled();
+
+    idleCallback?.({
+      didTimeout: false,
+      timeRemaining: () => 10,
+    });
+    expect(loadAsync).toHaveBeenCalledOnce();
+    cancel();
+  });
+
+  test("does not load after cancellation", () => {
+    let idleCallback: IdleRequestCallback | undefined;
+    vi.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => {
+      callback(0);
+      return 1;
+    });
+    vi.stubGlobal("requestIdleCallback", (callback: IdleRequestCallback) => {
+      idleCallback = callback;
+      return 2;
+    });
+    vi.stubGlobal("cancelIdleCallback", vi.fn());
+    document.body.innerHTML = '<section data-board-hydrated="true"></section>';
+    const loadAsync = vi.fn().mockResolvedValue(undefined);
+
+    const cancel = scheduleGridEditorWarmup(loadAsync);
+    cancel();
+    idleCallback?.({ didTimeout: false, timeRemaining: () => 10 });
+
+    expect(loadAsync).not.toHaveBeenCalled();
+  });
+
+  test("falls back to a timeout when requestIdleCallback is unavailable", async () => {
+    vi.useFakeTimers();
+    const requestIdleCallbackDescriptor = Object.getOwnPropertyDescriptor(window, "requestIdleCallback");
+    Reflect.deleteProperty(window, "requestIdleCallback");
+    vi.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => {
+      callback(0);
+      return 1;
+    });
+    document.body.innerHTML = '<section data-board-hydrated="true"></section>';
+    const loadAsync = vi.fn().mockResolvedValue(undefined);
+
+    const cancel = scheduleGridEditorWarmup(loadAsync);
+    await vi.advanceTimersByTimeAsync(1_000);
+
+    expect(loadAsync).toHaveBeenCalledOnce();
+    cancel();
+    vi.useRealTimers();
+    if (requestIdleCallbackDescriptor) {
+      Object.defineProperty(window, "requestIdleCallback", requestIdleCallbackDescriptor);
+    }
+  });
+
+  test("waits until the document becomes visible", () => {
+    let visibilityState: DocumentVisibilityState = "hidden";
+    vi.spyOn(document, "visibilityState", "get").mockImplementation(() => visibilityState);
+    const animationFrame = vi.spyOn(window, "requestAnimationFrame").mockReturnValue(1);
+    const loadAsync = vi.fn().mockResolvedValue(undefined);
+    document.body.innerHTML = '<section data-board-hydrated="true"></section>';
+
+    const cancel = scheduleGridEditorWarmup(loadAsync);
+    expect(animationFrame).not.toHaveBeenCalled();
+
+    visibilityState = "visible";
+    document.dispatchEvent(new Event("visibilitychange"));
+    expect(animationFrame).toHaveBeenCalledOnce();
+    cancel();
+  });
+});

apps/nextjs/src/components/board/sections/grid/test/grid-import-boundary.spec.ts

@@ -0,0 +1,236 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import ts from "typescript";
+import { describe, expect, test } from "vitest";
+
+const gridDirectory = resolve(import.meta.dirname, "..");
+const nextjsSourceDirectory = resolve(gridDirectory, "../../../../");
+const sectionGridPath = resolve(gridDirectory, "section-grid.tsx");
+const editorLoaderPath = resolve(gridDirectory, "grid-editor-loader.ts");
+
+describe("board grid import boundary", () => {
+  test("keeps every GridStack runtime import inside the edit-only module", () => {
+    const runtimeImports = getSourceFiles(nextjsSourceDirectory)
+      .flatMap(getRuntimeImports)
+      .filter(({ specifier }) => specifier === "gridstack" || specifier.startsWith("gridstack/"))
+      .map(({ filePath, kind, specifier }) => ({
+        file: toSourceRelativePath(filePath),
+        kind,
+        specifier,
+      }))
+      .toSorted((first, second) =>
+        `${first.file}:${first.specifier}:${first.kind}`.localeCompare(
+          `${second.file}:${second.specifier}:${second.kind}`,
+        ),
+      );
+
+    expect(runtimeImports).toEqual([
+      {
+        file: "components/board/sections/grid/grid-editor.tsx",
+        kind: "static",
+        specifier: "gridstack",
+      },
+      {
+        file: "components/board/sections/grid/grid-editor.tsx",
+        kind: "static",
+        specifier: "gridstack/dist/gridstack.min.css",
+      },
+    ]);
+  });
+
+  test("loads the editor through next/dynamic only in the edit branch", () => {
+    const sourceFile = parseSourceFile(sectionGridPath);
+    const dynamicImport = sourceFile.statements.find(
+      (statement): statement is ts.ImportDeclaration =>
+        ts.isImportDeclaration(statement) &&
+        ts.isStringLiteral(statement.moduleSpecifier) &&
+        statement.moduleSpecifier.text === "next/dynamic",
+    );
+
+    expect(dynamicImport?.importClause?.name?.text).toBe("dynamic");
+
+    const gridEditorDeclaration = findNode(
+      sourceFile,
+      (node): node is ts.VariableDeclaration =>
+        ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === "GridEditor",
+    );
+    expect(gridEditorDeclaration).toBeDefined();
+    expect(gridEditorDeclaration?.initializer && ts.isCallExpression(gridEditorDeclaration.initializer)).toBe(true);
+
+    const dynamicCall = gridEditorDeclaration?.initializer;
+    if (!dynamicCall || !ts.isCallExpression(dynamicCall)) {
+      throw new Error("GridEditor must be initialized with next/dynamic");
+    }
+
+    expect(ts.isIdentifier(dynamicCall.expression) && dynamicCall.expression.text === "dynamic").toBe(true);
+    expect(
+      dynamicCall.arguments.some((argument) => ts.isIdentifier(argument) && argument.text === "loadGridEditorAsync"),
+    ).toBe(true);
+    expect(dynamicCall.arguments.some(hasDisabledSsrOption)).toBe(true);
+    expect(dynamicCall.arguments.some(hasEditorLoadingOption)).toBe(true);
+    expect(getRuntimeImports(sectionGridPath).filter(({ specifier }) => specifier === "./grid-editor")).toEqual([]);
+    expect(
+      getRuntimeImports(editorLoaderPath)
+        .filter(({ specifier }) => specifier === "./grid-editor")
+        .map(({ kind }) => kind),
+    ).toEqual(["dynamic"]);
+
+    const usages = findNodes(
+      sourceFile,
+      (node): node is ts.JsxSelfClosingElement =>
+        ts.isJsxSelfClosingElement(node) && ts.isIdentifier(node.tagName) && node.tagName.text === "GridEditor",
+    );
+    expect(usages).toHaveLength(1);
+
+    const gridEditorUsage = usages[0];
+    if (!gridEditorUsage) {
+      throw new Error("GridEditor must be rendered once");
+    }
+
+    const editConditional = findAncestor(gridEditorUsage, ts.isConditionalExpression);
+    expect(
+      editConditional !== undefined &&
+        ts.isIdentifier(editConditional.condition) &&
+        editConditional.condition.text === "isEditMode" &&
+        isDescendantOf(gridEditorUsage, editConditional.whenTrue),
+    ).toBe(true);
+  });
+});
+
+interface RuntimeImport {
+  filePath: string;
+  kind: "dynamic" | "require" | "static";
+  specifier: string;
+}
+
+const getSourceFiles = (directory: string): string[] =>
+  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = resolve(directory, entry.name);
+    if (entry.isDirectory()) return getSourceFiles(path);
+    return /\.[cm]?[jt]sx?$/.test(entry.name) ? [path] : [];
+  });
+
+const getRuntimeImports = (filePath: string): RuntimeImport[] => {
+  const sourceFile = parseSourceFile(filePath);
+  const imports: RuntimeImport[] = [];
+
+  const visit = (node: ts.Node) => {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && isRuntimeImportDeclaration(node)) {
+      imports.push({ filePath, kind: "static", specifier: node.moduleSpecifier.text });
+    } else if (
+      ts.isExportDeclaration(node) &&
+      node.moduleSpecifier &&
+      ts.isStringLiteral(node.moduleSpecifier) &&
+      isRuntimeExportDeclaration(node)
+    ) {
+      imports.push({ filePath, kind: "static", specifier: node.moduleSpecifier.text });
+    } else if (
+      ts.isCallExpression(node) &&
+      (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(node.expression) && node.expression.text === "require"))
+    ) {
+      const [argument] = node.arguments;
+      if (node.arguments.length === 1 && argument && ts.isStringLiteral(argument)) {
+        imports.push({
+          filePath,
+          kind: node.expression.kind === ts.SyntaxKind.ImportKeyword ? "dynamic" : "require",
+          specifier: argument.text,
+        });
+      }
+    } else if (
+      ts.isImportEqualsDeclaration(node) &&
+      !node.isTypeOnly &&
+      ts.isExternalModuleReference(node.moduleReference) &&
+      node.moduleReference.expression &&
+      ts.isStringLiteral(node.moduleReference.expression)
+    ) {
+      imports.push({ filePath, kind: "static", specifier: node.moduleReference.expression.text });
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return imports;
+};
+
+const isRuntimeImportDeclaration = (declaration: ts.ImportDeclaration) => {
+  const clause = declaration.importClause;
+  if (!clause) return true;
+  if (clause.isTypeOnly) return false;
+  if (clause.name) return true;
+  if (!clause.namedBindings || ts.isNamespaceImport(clause.namedBindings)) return true;
+  if (clause.namedBindings.elements.length === 0) return true;
+  return clause.namedBindings.elements.some((element) => !element.isTypeOnly);
+};
+
+const isRuntimeExportDeclaration = (declaration: ts.ExportDeclaration) => {
+  if (declaration.isTypeOnly) return false;
+  if (!declaration.exportClause || ts.isNamespaceExport(declaration.exportClause)) return true;
+  if (declaration.exportClause.elements.length === 0) return true;
+  return declaration.exportClause.elements.some((element) => !element.isTypeOnly);
+};
+
+const parseSourceFile = (filePath: string) =>
+  ts.createSourceFile(filePath, readFileSync(filePath, "utf8"), ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+
+const getScriptKind = (filePath: string) => {
+  if (filePath.endsWith(".tsx")) return ts.ScriptKind.TSX;
+  if (filePath.endsWith(".jsx")) return ts.ScriptKind.JSX;
+  if (filePath.endsWith(".js") || filePath.endsWith(".mjs") || filePath.endsWith(".cjs")) return ts.ScriptKind.JS;
+  return ts.ScriptKind.TS;
+};
+
+const hasDisabledSsrOption = (node: ts.Node) => {
+  if (!ts.isObjectLiteralExpression(node)) return false;
+  return node.properties.some(
+    (property) =>
+      ts.isPropertyAssignment(property) &&
+      ts.isIdentifier(property.name) &&
+      property.name.text === "ssr" &&
+      property.initializer.kind === ts.SyntaxKind.FalseKeyword,
+  );
+};
+
+const hasEditorLoadingOption = (node: ts.Node) => {
+  if (!ts.isObjectLiteralExpression(node)) return false;
+  return node.properties.some(
+    (property) =>
+      ts.isPropertyAssignment(property) &&
+      ts.isIdentifier(property.name) &&
+      property.name.text === "loading" &&
+      ts.isIdentifier(property.initializer) &&
+      property.initializer.text === "GridEditorLoading",
+  );
+};
+
+const findNode = <TNode extends ts.Node>(
+  root: ts.Node,
+  predicate: (node: ts.Node) => node is TNode,
+): TNode | undefined => findNodes(root, predicate)[0];
+
+const findNodes = <TNode extends ts.Node>(root: ts.Node, predicate: (node: ts.Node) => node is TNode) => {
+  const matches: TNode[] = [];
+  const visit = (node: ts.Node) => {
+    if (predicate(node)) matches.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(root);
+  return matches;
+};
+
+const findAncestor = <TNode extends ts.Node>(
+  node: ts.Node,
+  predicate: (candidate: ts.Node) => candidate is TNode,
+): TNode | undefined => {
+  let current = node.parent;
+  while (current) {
+    if (predicate(current)) return current;
+    current = current.parent;
+  }
+  return undefined;
+};
+
+const isDescendantOf = (node: ts.Node, ancestor: ts.Node) => node.pos >= ancestor.pos && node.end <= ancestor.end;
+
+const toSourceRelativePath = (filePath: string) => relative(nextjsSourceDirectory, filePath).replaceAll("\\", "/");

apps/nextjs/src/components/board/sections/grid/test/grid-resize-handles.spec.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "vitest";
+
+import { decorateGridResizeHandles } from "../grid-resize-handles";
+
+describe("grid resize handle decoration", () => {
+  test("restores accessible hit-target markers after GridStack refreshes its handles", () => {
+    const item = document.createElement("div");
+    item.innerHTML = `
+      <div class="ui-resizable-handle ui-resizable-e"></div>
+      <div class="ui-resizable-handle ui-resizable-se"></div>
+    `;
+
+    decorateGridResizeHandles(item);
+
+    const east = item.querySelector<HTMLElement>(".ui-resizable-e");
+    const southeast = item.querySelector<HTMLElement>(".ui-resizable-se");
+    expect(east?.dataset.testid).toBe("board-grid-resize-handle-e");
+    expect(east?.dataset.gridResizeDirection).toBe("e");
+    expect(east?.getAttribute("aria-hidden")).toBe("true");
+    expect(southeast?.dataset.testid).toBe("board-grid-resize-handle");
+    expect(southeast?.dataset.gridResizeDirection).toBe("se");
+    expect(southeast?.getAttribute("aria-hidden")).toBe("true");
+  });
+});

apps/nextjs/src/components/board/sections/grid/use-grid-layout-actions.ts

@@ -0,0 +1,92 @@
+"use client";
+
+import { useCallback } from "react";
+
+import { useUpdateBoard } from "@homarr/boards/updater";
+
+import type { GridPlacement } from "~/components/board/layout";
+
+export interface SectionGridPlacement extends GridPlacement {
+  type: "item" | "section";
+  minW?: number;
+  minH?: number;
+}
+
+export interface CommitSectionGridInput {
+  layoutId: string;
+  sectionId: string;
+  placements: readonly SectionGridPlacement[];
+}
+
+/**
+ * Commits a complete section snapshot in one cache update. GridStack can move
+ * several neighbours for one gesture, so persisting only the active item would
+ * lose its collision result.
+ */
+export const useGridLayoutActions = () => {
+  const { updateBoard } = useUpdateBoard();
+
+  const commitSectionGrids = useCallback(
+    (snapshots: readonly CommitSectionGridInput[]) => {
+      const byId = new Map(
+        snapshots.flatMap(({ layoutId, sectionId, placements }) =>
+          placements.map((placement) => [`${layoutId}:${placement.id}`, { layoutId, sectionId, placement }] as const),
+        ),
+      );
+      updateBoard((previous) => {
+        return {
+          ...previous,
+          items: previous.items.map((item) => {
+            const layouts = item.layouts.map((layout) => {
+              const resolved = byId.get(`${layout.layoutId}:${item.id}`);
+              if (!resolved || resolved.placement.type !== "item") return layout;
+              const { placement, sectionId } = resolved;
+
+              return {
+                ...layout,
+                sectionId,
+                xOffset: placement.x,
+                yOffset: placement.y,
+                width: placement.w,
+                height: placement.h,
+              };
+            });
+
+            return layouts.some((layout, index) => layout !== item.layouts[index]) ? { ...item, layouts } : item;
+          }),
+          sections: previous.sections.map((innerSection) => {
+            if (innerSection.kind !== "dynamic") return innerSection;
+            const layouts = innerSection.layouts.map((layout) => {
+              const resolved = byId.get(`${layout.layoutId}:${innerSection.id}`);
+              if (!resolved || resolved.placement.type !== "section") return layout;
+              const { placement, sectionId } = resolved;
+
+              return {
+                ...layout,
+                parentSectionId: sectionId,
+                xOffset: placement.x,
+                yOffset: placement.y,
+                width: placement.w,
+                height: placement.h,
+              };
+            });
+
+            return layouts.some((layout, index) => layout !== innerSection.layouts[index])
+              ? { ...innerSection, layouts }
+              : innerSection;
+          }),
+        };
+      });
+    },
+    [updateBoard],
+  );
+
+  const commitSectionGrid = useCallback(
+    (snapshot: CommitSectionGridInput) => {
+      commitSectionGrids([snapshot]);
+    },
+    [commitSectionGrids],
+  );
+
+  return { commitSectionGrid, commitSectionGrids };
+};

apps/nextjs/src/components/board/sections/gridstack/gridstack-item.tsx

@@ -1,62 +0,0 @@
-import { useEffect } from "react";
-import type { PropsWithChildren } from "react";
-import type { BoxProps } from "@mantine/core";
-import { Box } from "@mantine/core";
-import combineClasses from "clsx";
-
-import type { SectionKind, WidgetKind } from "@homarr/definitions";
-import type { GridItemHTMLElement } from "@homarr/gridstack";
-
-interface Props extends BoxProps {
-  id: string;
-  type: "item" | "section";
-  kind: WidgetKind | SectionKind;
-  xOffset: number;
-  yOffset: number;
-  width: number;
-  height: number;
-  minWidth?: number;
-  minHeight?: number;
-  innerRef: React.RefObject<GridItemHTMLElement | null> | undefined;
-}
-
-export const GridStackItem = ({
-  id,
-  type,
-  kind,
-  xOffset,
-  yOffset,
-  width,
-  height,
-  minWidth = 1,
-  minHeight = 1,
-  innerRef,
-  children,
-  ...boxProps
-}: PropsWithChildren<Props>) => {
-  useEffect(() => {
-    if (!innerRef?.current?.gridstackNode) return;
-    if (type !== "section") return;
-    innerRef.current.gridstackNode.minW = minWidth;
-    innerRef.current.gridstackNode.minH = minHeight;
-  }, [minWidth, minHeight, innerRef, type]);
-
-  return (
-    <Box
-      {...boxProps}
-      className={combineClasses("grid-stack-item", boxProps.className)}
-      data-id={id}
-      data-type={type}
-      data-kind={kind}
-      gs-x={xOffset}
-      gs-y={yOffset}
-      gs-w={width}
-      gs-h={height}
-      gs-min-w={minWidth}
-      gs-min-h={minHeight}
-      ref={innerRef as React.RefObject<HTMLDivElement>}
-    >
-      {children}
-    </Box>
-  );
-};

apps/nextjs/src/components/board/sections/gridstack/gridstack.tsx

@@ -1,36 +0,0 @@
-"use client";
-
-import type { BoxProps } from "@mantine/core";
-import { Box } from "@mantine/core";
-import combineClasses from "clsx";
-
-import type { DynamicSectionItem, Section } from "~/app/[locale]/boards/_types";
-import { SectionContent } from "../content";
-import { SectionProvider } from "../section-context";
-import { useSectionItems } from "../use-section-items";
-import { useGridstack } from "./use-gridstack";
-
-interface Props extends BoxProps {
-  section: Exclude<Section, { kind: "dynamic" }> | DynamicSectionItem;
-}
-
-export const GridStack = ({ section, ...props }: Props) => {
-  const { items, innerSections } = useSectionItems(section.id);
-  const itemIds = [...items, ...innerSections].map((item) => item.id);
-
-  const { refs } = useGridstack(section, itemIds);
-
-  return (
-    <SectionProvider value={{ section, items, innerSections, refs }}>
-      <Box
-        {...props}
-        data-kind={section.kind}
-        data-section-id={section.id}
-        className={combineClasses(`grid-stack grid-stack-${section.kind}`, props.className)}
-        ref={refs.wrapper}
-      >
-        <SectionContent />
-      </Box>
-    </SectionProvider>
-  );
-};

apps/nextjs/src/components/board/sections/gridstack/init-gridstack.ts

@@ -1,56 +0,0 @@
-import type { RefObject } from "react";
-
-import type { GridItemHTMLElement } from "@homarr/gridstack";
-import { GridStack } from "@homarr/gridstack";
-
-import type { Section } from "~/app/[locale]/boards/_types";
-
-interface InitializeGridstackProps {
-  section: Omit<Section, "items">;
-  itemIds: string[];
-  refs: {
-    wrapper: RefObject<HTMLDivElement | null>;
-    items: RefObject<Record<string, RefObject<GridItemHTMLElement | null>>>;
-    gridstack: RefObject<GridStack | null>;
-  };
-  sectionColumnCount: number;
-}
-
-export const initializeGridstack = ({ section, itemIds, refs, sectionColumnCount }: InitializeGridstackProps) => {
-  if (!refs.wrapper.current) return false;
-  // initialize gridstack
-  const newGrid = refs.gridstack;
-  newGrid.current = GridStack.init(
-    {
-      column: sectionColumnCount,
-      margin: 10,
-      cellHeight: 128,
-      float: true,
-      alwaysShowResizeHandle: true,
-      acceptWidgets: true,
-      staticGrid: true,
-      minRow: section.kind === "dynamic" && "height" in section ? (section.height as number) : 1,
-      maxRow: section.kind === "dynamic" && "height" in section ? (section.height as number) : 0,
-      animate: false,
-      styleInHead: true,
-      disableRemoveNodeOnDrop: true,
-    },
-    // selector of the gridstack item (it's eather category or wrapper)
-    `.grid-stack-${section.kind}[data-section-id='${section.id}']`,
-  );
-  const grid = newGrid.current;
-
-  // Must be used to update the column count after the initialization
-  grid.column(sectionColumnCount, "none");
-
-  grid.batchUpdate();
-  grid.removeAll(false);
-  itemIds.forEach((id) => {
-    const ref = refs.items.current[id]?.current;
-    if (!ref) return;
-
-    grid.makeWidget(ref);
-  });
-  grid.batchUpdate(false);
-  return true;
-};

apps/nextjs/src/components/board/sections/gridstack/use-gridstack.ts

@@ -1,372 +0,0 @@
-import type { Ref, RefObject } from "react";
-import { createRef, useCallback, useEffect, useRef } from "react";
-import { useElementSize, useMergedRef } from "@mantine/hooks";
-
-import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
-import { useEditMode } from "@homarr/boards/edit-mode";
-import type { GridHTMLElement, GridItemHTMLElement, GridStack, GridStackNode } from "@homarr/gridstack";
-
-import type { Section } from "~/app/[locale]/boards/_types";
-import { useMarkSectionAsReady } from "~/app/[locale]/boards/(content)/_ready-context";
-import { useItemActions } from "../../items/item-actions";
-import { useSectionActions } from "../section-actions";
-import { initializeGridstack } from "./init-gridstack";
-
-export interface UseGridstackRefs {
-  wrapper: Ref<HTMLDivElement | null>;
-  items: RefObject<Record<string, RefObject<GridItemHTMLElement | null>>>;
-  gridstack: RefObject<GridStack | null>;
-}
-
-interface UseGristackReturnType {
-  refs: UseGridstackRefs;
-}
-
-/**
- * When the size of a gridstack changes we need to update the css variables
- * so the gridstack items are displayed correctly
- * @param wrapper gridstack wrapper
- * @param gridstack gridstack object
- * @param width width of the section (column count)
- * @param height height of the section (row count)
- * @param isDynamic if the section is dynamic
- */
-const handleResizeChange = (
-  wrapper: HTMLDivElement,
-  gridstack: GridStack,
-  width: number,
-  height: number,
-  isDynamic: boolean,
-) => {
-  wrapper.style.setProperty("--gridstack-column-count", width.toString());
-  wrapper.style.setProperty("--gridstack-row-count", height.toString());
-
-  let cellHeight = wrapper.clientWidth / width;
-  if (isDynamic) {
-    cellHeight = wrapper.clientHeight / height;
-  }
-
-  if (!isDynamic) {
-    document.body.style.setProperty("--gridstack-cell-size", cellHeight.toString());
-  }
-
-  gridstack.cellHeight(cellHeight);
-};
-
-export const useGridstack = (section: Omit<Section, "items">, itemIds: string[]): UseGristackReturnType => {
-  const [isEditMode] = useEditMode();
-  const markAsReady = useMarkSectionAsReady();
-  const { moveAndResizeItem, moveItemToSection } = useItemActions();
-  const { moveAndResizeInnerSection, moveInnerSectionToSection } = useSectionActions();
-
-  const wrapperElementRef = useRef<HTMLDivElement | null>(null);
-  const { ref: measureWrapperRef, width, height } = useElementSize<HTMLDivElement>();
-  const wrapperRef = useMergedRef(measureWrapperRef, wrapperElementRef);
-  // references to the diffrent items contained in the gridstack
-  const itemRefs = useRef<Record<string, RefObject<GridItemHTMLElement | null>>>({});
-  // reference of the gridstack object for modifications after initialization
-  const gridRef = useRef<GridStack>(null);
-
-  const board = useRequiredBoard();
-
-  const currentLayoutId = useCurrentLayout();
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  const currentLayout = board.layouts.find((layout) => layout.id === currentLayoutId)!;
-  const columnCount =
-    section.kind === "dynamic" && "width" in section && typeof section.width === "number"
-      ? section.width
-      : currentLayout.columnCount;
-
-  const itemRefKeys = Object.keys(itemRefs.current);
-  // define items in itemRefs for easy access and reference to items
-  if (itemRefKeys.length !== itemIds.length) {
-    // Remove items that are not in the itemIds
-    // Otherwise when an item is removed and then another item is added, this foreach below will not run.
-    itemRefKeys.forEach((id) => {
-      if (!itemIds.includes(id)) {
-        delete itemRefs.current[id];
-      }
-    });
-    itemIds.forEach((id) => {
-      itemRefs.current[id] = itemRefs.current[id] ?? createRef();
-    });
-  }
-
-  const onChange = useCallback(
-    (changedNode: GridStackNode) => {
-      const id = changedNode.el?.getAttribute("data-id");
-      const type = changedNode.el?.getAttribute("data-type");
-
-      if (!id || !type) return;
-
-      if (type === "item") {
-        // Updates the react-query state
-        moveAndResizeItem({
-          itemId: id,
-          // We want the following properties to be null by default
-          // so the next free position is used from the gridstack
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          xOffset: changedNode.x!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          yOffset: changedNode.y!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          width: changedNode.w!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          height: changedNode.h!,
-        });
-        return;
-      }
-
-      if (type === "section") {
-        moveAndResizeInnerSection({
-          innerSectionId: id,
-          // We want the following properties to be null by default
-          // so the next free position is used from the gridstack
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          xOffset: changedNode.x!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          yOffset: changedNode.y!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          width: changedNode.w!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          height: changedNode.h!,
-        });
-        return;
-      }
-
-      console.error(`Unknown grid-stack-item type to move. type='${type}' id='${id}'`);
-    },
-    [moveAndResizeItem, moveAndResizeInnerSection],
-  );
-  const onAdd = useCallback(
-    (addedNode: GridStackNode) => {
-      const id = addedNode.el?.getAttribute("data-id");
-      const type = addedNode.el?.getAttribute("data-type");
-
-      if (!id || !type) return;
-
-      if (type === "item") {
-        // Updates the react-query state
-        moveItemToSection({
-          itemId: id,
-          sectionId: section.id,
-          // We want the following properties to be null by default
-          // so the next free position is used from the gridstack
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          xOffset: addedNode.x!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          yOffset: addedNode.y!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          width: addedNode.w!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          height: addedNode.h!,
-        });
-        return;
-      }
-
-      if (type === "section") {
-        moveInnerSectionToSection({
-          innerSectionId: id,
-          sectionId: section.id,
-          // We want the following properties to be null by default
-          // so the next free position is used from the gridstack
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          xOffset: addedNode.x!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          yOffset: addedNode.y!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          width: addedNode.w!,
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          height: addedNode.h!,
-        });
-        return;
-      }
-
-      console.error(`Unknown grid-stack-item type to add. type='${type}' id='${id}'`);
-    },
-    [moveItemToSection, moveInnerSectionToSection, section.id],
-  );
-
-  // initialize the gridstack
-  useEffect(() => {
-    const isReady = initializeGridstack({
-      section,
-      itemIds,
-      refs: {
-        items: itemRefs,
-        wrapper: wrapperElementRef,
-        gridstack: gridRef,
-      },
-      sectionColumnCount: columnCount,
-    });
-
-    // If the section is ready mark it as ready
-    // When all sections are ready the board is ready and will get visible
-    if (isReady) {
-      markAsReady(section.id);
-    }
-
-    // Only run this effect when the section items change
-  }, [itemIds.length, columnCount]);
-
-  /**
-   * IMPORTANT: This effect has to be placed after the effect to initialize the gridstack
-   * because we need the gridstack object to add the listeners
-   */
-  useEffect(() => {
-    if (!isEditMode) return;
-    const currentGrid = gridRef.current;
-    // Add listener for moving items around in a wrapper
-    currentGrid?.on("change", (_, nodes) => {
-      nodes.forEach(onChange);
-
-      // For all dynamic section items that changed we want to update the inner gridstack
-      nodes
-        .filter((node) => node.el?.getAttribute("data-type") === "section")
-        .forEach((node) => {
-          const dynamicInnerGrid = node.el?.querySelector<GridHTMLElement>('.grid-stack[data-kind="dynamic"]');
-
-          if (!dynamicInnerGrid?.gridstack) return;
-
-          handleResizeChange(
-            dynamicInnerGrid as HTMLDivElement,
-            dynamicInnerGrid.gridstack,
-            node.w ?? 1,
-            node.h ?? 1,
-            true,
-          );
-        });
-    });
-
-    // Add listener for moving items in config from one wrapper to another
-    currentGrid?.on("added", (_, nodes) => {
-      nodes.forEach(onAdd);
-    });
-
-    return () => {
-      currentGrid?.off("change");
-      currentGrid?.off("added");
-    };
-  }, [isEditMode, onAdd, onChange]);
-
-  /**
-   * IMPORTANT: This effect has to be placed after the effect to initialize the gridstack
-   * because we need the gridstack object to add the listeners
-   * Toggle the gridstack to be static or not based on the edit mode
-   */
-  useEffect(() => {
-    gridRef.current?.setStatic(!isEditMode);
-  }, [isEditMode]);
-
-  const sectionHeight = section.kind === "dynamic" && "height" in section ? (section.height as number) : null;
-
-  /**
-   * IMPORTANT: This effect has to be placed after the effect to initialize the gridstack
-   * because we need the gridstack object to add the listeners
-   * We want the amount of rows in a dynamic section to be the height of the section in the outer gridstack
-   */
-  useEffect(() => {
-    if (!sectionHeight) return;
-    gridRef.current?.row(sectionHeight);
-  }, [sectionHeight]);
-
-  /**
-   * IMPORTANT: This effect has to be placed after the effect to initialize the gridstack
-   * because we need the gridstack object to add the listeners
-   */
-  useCssVariableConfiguration({
-    columnCount,
-    gridRef,
-    wrapperRef: wrapperElementRef,
-    width,
-    height,
-    isDynamic: section.kind === "dynamic",
-  });
-
-  return {
-    refs: {
-      items: itemRefs,
-      wrapper: wrapperRef,
-      gridstack: gridRef,
-    },
-  };
-};
-
-interface UseCssVariableConfiguration {
-  gridRef: UseGridstackRefs["gridstack"];
-  wrapperRef: RefObject<HTMLDivElement | null>;
-  width: number;
-  height: number;
-  columnCount: number;
-  isDynamic: boolean;
-}
-
-/**
- * This hook is used to configure the css variables for the gridstack
- * Those css variables are used to define the size of the gridstack items
- * @see gridstack.scss
- * @param gridRef reference to the gridstack object
- * @param wrapperRef reference to the wrapper of the gridstack
- * @param width width of the section
- * @param height height of the section
- * @param columnCount column count of the gridstack
- */
-const useCssVariableConfiguration = ({
-  gridRef,
-  wrapperRef,
-  width,
-  height,
-  columnCount,
-  isDynamic,
-}: UseCssVariableConfiguration) => {
-  const onResize = useCallback(() => {
-    if (!wrapperRef.current) return;
-    if (!gridRef.current) return;
-    handleResizeChange(
-      wrapperRef.current,
-      gridRef.current,
-      gridRef.current.getColumn(),
-      gridRef.current.getRow(),
-      isDynamic,
-    );
-  }, [wrapperRef, gridRef, isDynamic]);
-
-  useCallback(() => {
-    if (!wrapperRef.current) return;
-    if (!gridRef.current) return;
-
-    wrapperRef.current.style.setProperty("--gridstack-column-count", gridRef.current.getColumn().toString());
-    wrapperRef.current.style.setProperty("--gridstack-row-count", gridRef.current.getRow().toString());
-
-    let cellHeight = wrapperRef.current.clientWidth / gridRef.current.getColumn();
-    if (isDynamic) {
-      cellHeight = wrapperRef.current.clientHeight / gridRef.current.getRow();
-    }
-
-    gridRef.current.cellHeight(cellHeight);
-  }, [wrapperRef, gridRef, isDynamic]);
-
-  // Define widget-width by calculating the width of one column with mainRef width and column count
-  useEffect(() => {
-    onResize();
-    if (typeof window === "undefined") return;
-    window.addEventListener("resize", onResize);
-    const wrapper = wrapperRef.current;
-    wrapper?.addEventListener("resize", onResize);
-    return () => {
-      if (typeof window === "undefined") return;
-      window.removeEventListener("resize", onResize);
-      wrapper?.removeEventListener("resize", onResize);
-    };
-  }, [wrapperRef, gridRef, onResize]);
-
-  // Handle resize of inner sections when there size changes
-  useEffect(() => {
-    onResize();
-  }, [width, height, onResize]);
-
-  // Define column count by using the sectionColumnCount
-  useEffect(() => {
-    wrapperRef.current?.style.setProperty("--gridstack-column-count", columnCount.toString());
-  }, [columnCount, wrapperRef]);
-};

apps/nextjs/src/components/board/sections/section-collapse-storage.ts

@@ -0,0 +1,46 @@
+interface SectionCollapseStorage {
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+}
+
+const legacyStorageKey = (sectionId: string) => `homarr-section-collapsed-${sectionId}`;
+
+export const sectionCollapseStorageKey = (sectionId: string) => `homarr-section-collapsed-v2-${sectionId}`;
+
+/**
+ * Legacy values represented whether the section was open even though the key
+ * and database column called the value "collapsed". Migrate once into a
+ * versioned key whose boolean has the corrected meaning.
+ */
+export const readSectionCollapsedFromStorage = (
+  storage: SectionCollapseStorage,
+  sectionId: string,
+  fallback: boolean,
+) => {
+  const currentKey = sectionCollapseStorageKey(sectionId);
+  const legacyKey = legacyStorageKey(sectionId);
+  const current = storage.getItem(currentKey);
+
+  if (current !== null) {
+    storage.removeItem(legacyKey);
+    return current === "true";
+  }
+
+  const legacy = storage.getItem(legacyKey);
+  if (legacy === null) return fallback;
+
+  const collapsed = legacy !== "true";
+  storage.setItem(currentKey, String(collapsed));
+  storage.removeItem(legacyKey);
+  return collapsed;
+};
+
+export const writeSectionCollapsedToStorage = (
+  storage: SectionCollapseStorage,
+  sectionId: string,
+  collapsed: boolean,
+) => {
+  storage.setItem(sectionCollapseStorageKey(sectionId), String(collapsed));
+  storage.removeItem(legacyStorageKey(sectionId));
+};

apps/nextjs/src/components/board/sections/section-collapse.tsx

@@ -0,0 +1,122 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+
+import { clientApi } from "@homarr/api/client";
+import { useSession } from "@homarr/auth/client";
+import { useRequiredBoard } from "@homarr/boards/context";
+import { useEditMode } from "@homarr/boards/edit-mode";
+
+import { readSectionCollapsedFromStorage, writeSectionCollapsedToStorage } from "./section-collapse-storage";
+
+interface SectionCollapseContextValue {
+  collapsedSectionIds: ReadonlySet<string>;
+  setCollapsed: (sectionId: string, collapsed: boolean) => void;
+}
+
+const SectionCollapseContext = createContext<SectionCollapseContextValue | null>(null);
+
+export const BoardSectionCollapseProvider = ({ children }: PropsWithChildren) => {
+  const board = useRequiredBoard();
+  const { status } = useSession();
+  const { mutate } = clientApi.section.changeCollapsed.useMutation();
+  const [collapsedById, setCollapsedById] = useState<Record<string, boolean>>(() =>
+    Object.fromEntries(
+      board.sections.filter((section) => section.kind !== "empty").map((section) => [section.id, section.collapsed]),
+    ),
+  );
+  const collapsedByIdRef = useRef(collapsedById);
+  collapsedByIdRef.current = collapsedById;
+
+  useEffect(() => {
+    setCollapsedById((previous) => {
+      const next = { ...previous };
+      for (const section of board.sections) {
+        if (section.kind === "empty" || section.id in next) continue;
+        next[section.id] = section.collapsed;
+      }
+      return next;
+    });
+  }, [board.sections]);
+
+  useEffect(() => {
+    if (status !== "unauthenticated") return;
+
+    setCollapsedById((previous) => {
+      const next = { ...previous };
+      for (const sectionId of Object.keys(next)) {
+        next[sectionId] = readSectionCollapsedFromStorage(window.localStorage, sectionId, next[sectionId] ?? false);
+      }
+      return next;
+    });
+  }, [status]);
+
+  const setCollapsed = useCallback(
+    (sectionId: string, collapsed: boolean) => {
+      const previousCollapsed = collapsedByIdRef.current[sectionId] ?? false;
+      collapsedByIdRef.current = { ...collapsedByIdRef.current, [sectionId]: collapsed };
+      setCollapsedById((previous) => ({ ...previous, [sectionId]: collapsed }));
+
+      if (status === "authenticated") {
+        mutate(
+          { sectionId, collapsed },
+          {
+            onError: () => {
+              if (collapsedByIdRef.current[sectionId] !== collapsed) return;
+              collapsedByIdRef.current = { ...collapsedByIdRef.current, [sectionId]: previousCollapsed };
+              setCollapsedById((previous) => ({ ...previous, [sectionId]: previousCollapsed }));
+            },
+          },
+        );
+      } else if (status === "unauthenticated") {
+        writeSectionCollapsedToStorage(window.localStorage, sectionId, collapsed);
+      }
+    },
+    [mutate, status],
+  );
+
+  const value = useMemo<SectionCollapseContextValue>(
+    () => ({
+      collapsedSectionIds: new Set(
+        Object.entries(collapsedById)
+          .filter(([, collapsed]) => collapsed)
+          .map(([sectionId]) => sectionId),
+      ),
+      setCollapsed,
+    }),
+    [collapsedById, setCollapsed],
+  );
+
+  return <SectionCollapseContext.Provider value={value}>{children}</SectionCollapseContext.Provider>;
+};
+
+export const useSectionCollapse = ({ sectionId, collapsible }: { sectionId: string; collapsible: boolean }) => {
+  const context = useContext(SectionCollapseContext);
+  const [isEditMode] = useEditMode();
+
+  if (!context) {
+    throw new Error("BoardSectionCollapseProvider is required");
+  }
+
+  const isCollapsed = collapsible && context.collapsedSectionIds.has(sectionId);
+  return {
+    isCollapsed,
+    isVisuallyCollapsed: isCollapsed && !isEditMode,
+    setCollapsed: (collapsed: boolean) => context.setCollapsed(sectionId, collapsed),
+    toggle: () => context.setCollapsed(sectionId, !isCollapsed),
+  };
+};
+
+export const useCollapsedSectionIds = () => {
+  const context = useContext(SectionCollapseContext);
+  const [isEditMode] = useEditMode();
+
+  if (!context) {
+    throw new Error("BoardSectionCollapseProvider is required");
+  }
+
+  return isEditMode ? EMPTY_SET : context.collapsedSectionIds;
+};
+
+const EMPTY_SET = new Set<string>();

apps/nextjs/src/components/board/sections/section-context.ts

@@ -1,13 +1,17 @@
 import { createContext, useContext } from "react";
 
+import type { RouterOutputs } from "@homarr/api";
+
 import type { DynamicSectionItem, Section, SectionItem } from "~/app/[locale]/boards/_types";
-import type { UseGridstackRefs } from "./gridstack/use-gridstack";
 
 interface SectionContextProps {
   section: Exclude<Section, { kind: "dynamic" }> | DynamicSectionItem;
   innerSections: DynamicSectionItem[];
   items: SectionItem[];
-  refs: UseGridstackRefs;
+  integrations: RouterOutputs["integration"]["all"] | undefined;
+  columnCount: number;
+  maxRowCount: number | null;
+  announce: (message: string) => void;
 }
 
 const SectionContext = createContext<SectionContextProps | null>(null);

apps/nextjs/src/components/board/sections/test/section-collapse-storage.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  readSectionCollapsedFromStorage,
+  sectionCollapseStorageKey,
+  writeSectionCollapsedToStorage,
+} from "../section-collapse-storage";
+
+describe("section collapse storage", () => {
+  test.each([
+    ["true", false],
+    ["false", true],
+  ])("inverts a legacy open value of %s exactly once", (legacyValue, expectedCollapsed) => {
+    const sectionId = "media";
+    const legacyKey = `homarr-section-collapsed-${sectionId}`;
+    const storage = createStorage({ [legacyKey]: legacyValue });
+
+    expect(readSectionCollapsedFromStorage(storage, sectionId, false)).toBe(expectedCollapsed);
+    expect(storage.getItem(legacyKey)).toBeNull();
+    expect(storage.getItem(sectionCollapseStorageKey(sectionId))).toBe(String(expectedCollapsed));
+    expect(readSectionCollapsedFromStorage(storage, sectionId, !expectedCollapsed)).toBe(expectedCollapsed);
+  });
+
+  test("uses the corrected fallback when no browser preference exists", () => {
+    const storage = createStorage();
+
+    expect(readSectionCollapsedFromStorage(storage, "category", true)).toBe(true);
+    expect(readSectionCollapsedFromStorage(storage, "dynamic", false)).toBe(false);
+  });
+
+  test("writes only the versioned corrected state", () => {
+    const sectionId = "media";
+    const legacyKey = `homarr-section-collapsed-${sectionId}`;
+    const storage = createStorage({ [legacyKey]: "true" });
+
+    writeSectionCollapsedToStorage(storage, sectionId, true);
+
+    expect(storage.getItem(legacyKey)).toBeNull();
+    expect(storage.getItem(sectionCollapseStorageKey(sectionId))).toBe("true");
+  });
+});
+
+const createStorage = (initial: Record<string, string> = {}) => {
+  const values = new Map(Object.entries(initial));
+
+  return {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => values.set(key, value),
+    removeItem: (key: string) => {
+      values.delete(key);
+    },
+  };
+};

apps/nextjs/src/components/board/sections/test/use-open-section-apps.spec.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "vitest";
+
+import { getSectionItemsForLayout } from "../use-open-section-apps";
+
+describe("getSectionItemsForLayout", () => {
+  test("includes items in recursively nested dynamic sections", () => {
+    const board = {
+      sections: [
+        { id: "category", kind: "category" },
+        {
+          id: "first",
+          kind: "dynamic",
+          layouts: [{ layoutId: "desktop", parentSectionId: "category" }],
+        },
+        {
+          id: "second",
+          kind: "dynamic",
+          layouts: [{ layoutId: "desktop", parentSectionId: "first" }],
+        },
+      ],
+      items: [
+        { id: "direct", layouts: [{ layoutId: "desktop", sectionId: "category" }] },
+        { id: "nested", layouts: [{ layoutId: "desktop", sectionId: "second" }] },
+      ],
+    };
+
+    expect(getSectionItemsForLayout(board, "category", "desktop").map((item) => item.id)).toEqual(["direct", "nested"]);
+  });
+
+  test("uses containment from only the requested responsive layout", () => {
+    const board = {
+      sections: [
+        { id: "category", kind: "category" },
+        { id: "other", kind: "category" },
+        {
+          id: "dynamic",
+          kind: "dynamic",
+          layouts: [
+            { layoutId: "mobile", parentSectionId: "category" },
+            { layoutId: "desktop", parentSectionId: "other" },
+          ],
+        },
+      ],
+      items: [
+        {
+          id: "app",
+          layouts: [
+            { layoutId: "mobile", sectionId: "dynamic" },
+            { layoutId: "desktop", sectionId: "dynamic" },
+          ],
+        },
+      ],
+    };
+
+    expect(getSectionItemsForLayout(board, "category", "mobile").map((item) => item.id)).toEqual(["app"]);
+    expect(getSectionItemsForLayout(board, "category", "desktop")).toEqual([]);
+  });
+
+  test("does not loop when malformed section containment is cyclic", () => {
+    const board = {
+      sections: [
+        {
+          id: "root",
+          kind: "dynamic",
+          layouts: [{ layoutId: "desktop", parentSectionId: "child" }],
+        },
+        {
+          id: "child",
+          kind: "dynamic",
+          layouts: [{ layoutId: "desktop", parentSectionId: "root" }],
+        },
+      ],
+      items: [{ id: "app", layouts: [{ layoutId: "desktop", sectionId: "child" }] }],
+    };
+
+    expect(getSectionItemsForLayout(board, "root", "desktop").map((item) => item.id)).toEqual(["app"]);
+  });
+});

apps/nextjs/src/components/board/sections/use-open-section-apps.ts

@@ -0,0 +1,110 @@
+import { useCallback, useMemo } from "react";
+
+import { clientApi } from "@homarr/api/client";
+import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
+import { useConfirmModal } from "@homarr/modals";
+import { useSettings } from "@homarr/settings";
+import { useI18n } from "@homarr/translation/client";
+
+import type { Item } from "~/app/[locale]/boards/_types";
+import { filterByItemKind } from "./category/filter";
+
+interface SectionItemLayout {
+  layoutId: string;
+  sectionId: string;
+}
+
+interface SectionLayout {
+  layoutId: string;
+  parentSectionId: string;
+}
+
+interface SectionTreeItem {
+  layouts: readonly SectionItemLayout[];
+}
+
+interface SectionTreeSection {
+  id: string;
+  kind: string;
+  layouts?: readonly SectionLayout[];
+}
+
+interface SectionTree<TItem extends SectionTreeItem> {
+  items: readonly TItem[];
+  sections: readonly SectionTreeSection[];
+}
+
+/**
+ * Finds every item contained by a section in one responsive layout. Dynamic
+ * sections can be nested, so their descendants are traversed recursively.
+ */
+export const getSectionItemsForLayout = <TItem extends SectionTreeItem>(
+  board: SectionTree<TItem>,
+  rootSectionId: string,
+  layoutId: string,
+) => {
+  const childrenByParent = new Map<string, string[]>();
+
+  for (const section of board.sections) {
+    if (section.kind !== "dynamic") continue;
+
+    const layout = section.layouts?.find((candidate) => candidate.layoutId === layoutId);
+    if (!layout) continue;
+
+    const children = childrenByParent.get(layout.parentSectionId) ?? [];
+    children.push(section.id);
+    childrenByParent.set(layout.parentSectionId, children);
+  }
+
+  const includedSectionIds = new Set([rootSectionId]);
+  const queue = [rootSectionId];
+
+  for (const sectionId of queue) {
+    for (const childSectionId of childrenByParent.get(sectionId) ?? []) {
+      if (includedSectionIds.has(childSectionId)) continue;
+
+      includedSectionIds.add(childSectionId);
+      queue.push(childSectionId);
+    }
+  }
+
+  return board.items.filter((item) =>
+    item.layouts.some((layout) => layout.layoutId === layoutId && includedSectionIds.has(layout.sectionId)),
+  );
+};
+
+export const useOpenSectionApps = (sectionId: string, enabled: boolean) => {
+  const board = useRequiredBoard();
+  const currentLayoutId = useCurrentLayout();
+  const settings = useSettings();
+  const { openConfirmModal } = useConfirmModal();
+  const t = useI18n();
+  const appIds = useMemo(() => {
+    const items: Item[] = getSectionItemsForLayout(board, sectionId, currentLayoutId);
+    return Array.from(new Set(filterByItemKind(items, settings, "app").map((item) => item.options.appId)));
+  }, [board, currentLayoutId, sectionId, settings]);
+  const { data: apps = [], isLoading } = clientApi.app.byIds.useQuery(appIds, {
+    enabled: enabled && appIds.length > 0,
+    staleTime: 30_000,
+  });
+
+  const open = useCallback(() => {
+    const appsWithUrls = apps.filter((app) => app.href && app.href.length > 0);
+
+    for (const app of appsWithUrls) {
+      const openedWindow = window.open(app.href ?? undefined);
+      if (openedWindow) continue;
+
+      openConfirmModal({
+        title: t("section.openAllInNewTabs.title"),
+        children: t("section.openAllInNewTabs.text"),
+      });
+      break;
+    }
+  }, [apps, openConfirmModal, t]);
+
+  return {
+    open,
+    isLoading: enabled && appIds.length > 0 && isLoading,
+  };
+};

apps/nextjs/src/components/layout/header/button.tsx

@@ -1,4 +1,4 @@
-import type { ForwardedRef, ReactNode } from "react";
+import type { FocusEventHandler, ForwardedRef, PointerEventHandler, ReactNode } from "react";
 import { forwardRef } from "react";
 import type { ActionIconProps } from "@mantine/core";
 import { ActionIcon } from "@mantine/core";
@@ -8,6 +8,8 @@ import { Link } from "@homarr/ui";
 type HeaderButtonProps = (
   | {
       onClick?: () => void;
+      onFocus?: FocusEventHandler<HTMLButtonElement>;
+      onPointerEnter?: PointerEventHandler<HTMLButtonElement>;
     }
   | {
       href: string;

apps/nextjs/src/components/layout/viewport-hint.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { useEffect } from "react";
+
+import { boardViewportWidthCookieName } from "@homarr/boards/layout-selection";
+
+export const ViewportHint = () => {
+  useEffect(() => {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    const persist = () => {
+      const viewportWidth = document.documentElement.clientWidth || window.innerWidth;
+      document.cookie = `${boardViewportWidthCookieName}=${Math.round(viewportWidth)}; Path=/; Max-Age=31536000; SameSite=Lax`;
+    };
+    const handleResize = () => {
+      clearTimeout(timeout);
+      timeout = setTimeout(persist, 150);
+    };
+
+    persist();
+    window.addEventListener("resize", handleResize, { passive: true });
+    return () => {
+      clearTimeout(timeout);
+      window.removeEventListener("resize", handleResize);
+    };
+  }, []);
+
+  return null;
+};

apps/nextjs/src/styles/gridstack.scss

@@ -1,118 +0,0 @@
-@import "@homarr/gridstack/dist/gridstack.min.css";
-
-:root {
-  --gridstack-column-count: 12;
-  --gridstack-row-count: 1;
-  --gridstack-cell-size: 0;
-}
-
-.ui-resizable-handle {
-  // Override default z-index of 100 to prevent it from being on top of the header.
-  // See https://github.com/homarr-labs/homarr/issues/1999
-  z-index: 1 !important;
-}
-
-.grid-stack-placeholder > .placeholder-content {
-  background-color: rgb(248, 249, 250) !important;
-  border-radius: 12px;
-  border: 1px solid rgba(0, 0, 0, 0.05);
-}
-
-@media (prefers-color-scheme: dark) {
-  .grid-stack-placeholder > .placeholder-content {
-    background-color: rgba(255, 255, 255, 0.05) !important;
-  }
-}
-
-// Define min size for gridstack items
-.grid-stack > .grid-stack-item {
-  min-width: calc(100% / var(--gridstack-column-count));
-  min-height: calc(100% / var(--gridstack-row-count));
-}
-
-.grid-stack > .grid-stack-item.ui-draggable-dragging {
-  min-width: calc(var(--gridstack-cell-size) * 1px) !important;
-  min-height: calc(var(--gridstack-cell-size) * 1px) !important;
-}
-
-// Define fix size while dragging
-@for $i from 1 to 96 {
-  .grid-stack > .grid-stack-item.ui-draggable-dragging[gs-w="#{$i}"] {
-    width: calc(var(--gridstack-cell-size) * #{$i} * 1px) !important;
-  }
-
-  .grid-stack > .grid-stack-item.ui-draggable-dragging[gs-h="#{$i}"] {
-    height: calc(var(--gridstack-cell-size) * #{$i} * 1px) !important;
-  }
-}
-
-// Styling for grid-stack main area
-@for $i from 1 to 96 {
-  .grid-stack > .grid-stack-item[gs-w="#{$i}"] {
-    width: calc(100% / #{var(--gridstack-column-count)} * #{$i});
-  }
-  .grid-stack > .grid-stack-item[gs-min-w="#{$i}"] {
-    min-width: calc(100% / #{var(--gridstack-column-count)} * #{$i});
-  }
-  .grid-stack > .grid-stack-item[gs-max-w="#{$i}"] {
-    max-width: calc(100% / #{var(--gridstack-column-count)} * #{$i});
-  }
-}
-
-@for $i from 1 to 96 {
-  .grid-stack > .grid-stack-item[gs-h="#{$i}"] {
-    height: calc(100% / var(--gridstack-row-count) * #{$i});
-  }
-  .grid-stack > .grid-stack-item[gs-min-h="#{$i}"] {
-    min-height: calc(100% / var(--gridstack-row-count) * #{$i});
-  }
-  .grid-stack > .grid-stack-item[gs-max-h="#{$i}"] {
-    max-height: calc(100% / var(--gridstack-row-count) * #{$i});
-  }
-}
-
-@for $i from 1 to 96 {
-  .grid-stack > .grid-stack-item[gs-x="#{$i}"] {
-    left: calc(100% / #{var(--gridstack-column-count)} * #{$i});
-  }
-}
-
-@for $i from 1 to 96 {
-  .grid-stack > .grid-stack-item[gs-y="#{$i}"] {
-    top: calc(100% / var(--gridstack-row-count) * #{$i});
-  }
-}
-
-.grid-stack[data-kind="dynamic"] {
-  height: 100% !important;
-}
-
-// General gridstack styling
-.grid-stack > .grid-stack-item > .grid-stack-item-content,
-.grid-stack > .grid-stack-item > .placeholder-content {
-  inset: 10px;
-}
-
-.grid-stack > .grid-stack-item > .ui-resizable-se {
-  bottom: 10px;
-  right: 10px;
-}
-
-.grid-stack > .grid-stack-item > .grid-stack-item-content {
-  overflow-y: auto;
-}
-
-.grid-stack > .grid-stack-item[data-type="item"] {
-  overflow: visible;
-}
-
-.grid-stack.grid-stack-animate {
-  transition: none;
-}
-
-/**
- * Hide empty wrapper (class is used when no items are inside and not in edit mode)
- */
-.grid-stack-empty-wrapper {
-  display: none !important;
-}

e2e/board-grid.spec.ts

@@ -0,0 +1,946 @@
+import { mkdir } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
+import { chromium, expect } from "@playwright/test";
+import type { Locator, Page, Request, Response } from "@playwright/test";
+import { createId } from "@paralleldrive/cuid2";
+import { stringify as stringifySuperJSON } from "superjson";
+import { describe, test } from "vitest";
+
+import {
+  LOGICAL_GRID_CELL_SIZE,
+  LOGICAL_GRID_GAP,
+  MIN_ACCESSIBLE_CANVAS_SCALE,
+} from "../apps/nextjs/src/components/board/layout/constants";
+import * as sqliteSchema from "../packages/db/schema/sqlite";
+import { createHomarrContainer } from "./shared/create-homarr-container";
+import { createSqliteDbFileAsync } from "./shared/e2e-db";
+import type { SqliteDatabase } from "./shared/e2e-db";
+import { seedAdminUserAsync } from "./shared/seed-admin-user";
+
+const adminCredentials = {
+  username: "admin",
+  password: "Comp(exP4sswOrd",
+};
+
+const editRuntimeMarker = "homarr-edit-grid-v1";
+const gridStackPayloadMarker = "--gs-column-width";
+const logicalCellSize = LOGICAL_GRID_CELL_SIZE;
+const logicalCellPitch = LOGICAL_GRID_CELL_SIZE + LOGICAL_GRID_GAP;
+const minimumCanvasScale = MIN_ACCESSIBLE_CANVAS_SCALE;
+
+describe("Board grid", () => {
+  test("supports fixed, nested, rail, pointer, keyboard and reconciliation workflows", async () => {
+    const { db, localMountPath } = await createSqliteDbFileAsync();
+    const { userId } = await seedAdminUserAsync(db, adminCredentials);
+    const fixture = await seedBoardGridAsync(db, userId);
+    const screenshotDirectory = await prepareScreenshotDirectoryAsync();
+
+    const homarrContainer = await createHomarrContainer({
+      environment: {
+        AUTH_PROVIDERS: "credentials",
+      },
+      mounts: {
+        "/appdata": localMountPath,
+      },
+    }).start();
+
+    let browser: Awaited<ReturnType<typeof chromium.launch>> | undefined;
+    let runtimeResources: ReturnType<typeof trackRuntimeResources> | undefined;
+
+    try {
+      const baseUrl = `http://${homarrContainer.getHost()}:${homarrContainer.getMappedPort(7575)}`;
+      browser = await chromium.launch();
+      const context = await browser.newContext({
+        viewport: {
+          width: 1920,
+          height: 1200,
+        },
+      });
+      const page = await context.newPage();
+      await installLayoutShiftObserverAsync(page);
+      runtimeResources = trackRuntimeResources(page);
+      const pageErrors: Error[] = [];
+      page.on("pageerror", (error) => {
+        pageErrors.push(error);
+        console.error(error.stack);
+      });
+
+      const noScriptContext = await browser.newContext({
+        javaScriptEnabled: false,
+        viewport: {
+          width: 1920,
+          height: 1200,
+        },
+      });
+      const noScriptPage = await noScriptContext.newPage();
+      await noScriptPage.goto(`${baseUrl}/boards/${fixture.boardName}`);
+      const serverRenderedCanvas = noScriptPage.getByTestId("board-canvas");
+      await expect(serverRenderedCanvas).toHaveAttribute("data-board-hydrated", "false");
+      const initialCanvasHeight = Number(await serverRenderedCanvas.getAttribute("data-canvas-initial-height"));
+      expect(initialCanvasHeight).toBeGreaterThan(0);
+      await expect(serverRenderedCanvas.locator(`[data-grid-item-id="${fixture.firstItemId}"]`)).toHaveCount(1);
+      await noScriptContext.close();
+
+      await signInAsync(page, baseUrl, `/boards/${fixture.boardName}`);
+
+      const canvas = page.getByTestId("board-canvas");
+      await expect(canvas).toHaveAttribute("data-board-hydrated", "true");
+      await expect(page.locator(`[data-grid-runtime="${editRuntimeMarker}"]`)).toHaveCount(0);
+
+      const mainSection = page.locator(`[data-section-id="${fixture.sectionId}"]`);
+      const rail = page.getByRole("complementary", { name: "Left dashboard rail" });
+      const railSection = page.locator(`[data-grid-item-id="${fixture.railSectionId}"]`);
+      const railRootSection = rail.locator("[data-section-kind='empty']");
+      const railItem = page.locator(`[data-grid-item-id="${fixture.railItemId}"]`);
+      const dynamicSection = page.locator(`[data-grid-item-id="${fixture.dynamicSectionId}"]`);
+      const nestedItem = page.locator(`[data-grid-item-id="${fixture.nestedItemId}"]`);
+      const belowItem = page.locator(`[data-grid-item-id="${fixture.belowItemId}"]`);
+      await expect(mainSection).toHaveAttribute("data-section-kind", "empty");
+      await expect(mainSection).toHaveAttribute("data-rail-placement", "main");
+      await expect(rail).toBeVisible();
+      await expect(rail).toHaveAttribute("data-board-gutter", "left");
+      await expect(railRootSection).toHaveAttribute("data-rail-placement", "left");
+      await expect(railSection).toHaveAttribute("data-grid-w", "2");
+      await expect(railItem).toHaveAttribute("data-grid-x", "0");
+      await expect(dynamicSection).toHaveAttribute("data-grid-w", "2");
+      await expect(dynamicSection).toHaveAttribute("data-grid-h", "2");
+      await expect(dynamicSection.getByText("Nested box", { exact: true })).toBeVisible();
+      await expect(nestedItem).toHaveAttribute("data-grid-x", "0");
+      await expect(belowItem).toHaveAttribute("data-grid-y", "2");
+
+      const firstItem = page.locator(`[data-grid-item-id="${fixture.firstItemId}"]`);
+      const secondItem = page.locator(`[data-grid-item-id="${fixture.secondItemId}"]`);
+      await expect(firstItem).toHaveAttribute("data-grid-x", "0");
+      await expect(firstItem).toHaveAttribute("data-grid-y", "0");
+      await expect(firstItem).toHaveAttribute("data-grid-w", "1");
+      await expect(firstItem).toHaveAttribute("data-grid-h", "1");
+      await expect(secondItem).toHaveAttribute("data-grid-x", "1");
+      await expect(secondItem).toHaveAttribute("data-grid-y", "0");
+
+      const logicalTile = firstItem.locator("[data-grid-item-content]");
+      await expect(logicalTile).toHaveCount(1);
+      await expectFixedLogicalTileAsync(logicalTile);
+      await expect(canvas).toHaveAttribute("data-canvas-overflow", "false");
+      const normalZoomTileBox = await expectBoundingBoxAsync(logicalTile);
+      const normalCanvasScale = await readCanvasScaleAsync(canvas);
+      const secondItemBox = await expectBoundingBoxAsync(secondItem);
+      expect(secondItemBox.x - (normalZoomTileBox.x + normalZoomTileBox.width)).toBeCloseTo(
+        (logicalCellPitch - logicalCellSize) * normalCanvasScale,
+        1,
+      );
+
+      const editToggle = page.getByTestId("board-edit-mode-toggle");
+      await runtimeResources.waitForQuietAsync();
+      expect(runtimeResources.urlsFor("read-only", "editor")).toEqual([]);
+      expect(runtimeResources.urlsFor("read-only", "gridstack")).toEqual([]);
+      expect(await readLayoutShiftScoreAsync(page)).toBeLessThan(0.01);
+
+      await resetLayoutShiftScoreAsync(page);
+      await releaseIdleCallbacksAsync(page);
+      await expect(editToggle).toHaveAttribute("data-board-editor-preload-state", "ready", {
+        timeout: 15_000,
+      });
+      await runtimeResources.waitForQuietAsync();
+      expect(runtimeResources.urlsFor("read-only", "editor").length).toBeGreaterThan(0);
+      expect(runtimeResources.urlsFor("read-only", "gridstack").length).toBeGreaterThan(0);
+      expect(await readLayoutShiftScoreAsync(page)).toBeLessThan(0.01);
+
+      // CSS zoom exercises Chromium's browser-zoom layout path without relying
+      // on desktop browser chrome. At 200% the scale floor must preserve
+      // magnification and expose horizontal scrolling instead of shrinking the
+      // board by the inverse zoom factor.
+      await setDocumentZoomAsync(page, 2);
+      await expect(canvas).toHaveAttribute("data-canvas-scale", String(minimumCanvasScale));
+      await expect(canvas).toHaveAttribute("data-canvas-overflow", "true");
+      await expectFixedLogicalTileAsync(logicalTile);
+      await expectUniformVisualScaleAsync(logicalTile);
+      const fittedClockFontSize = await firstItem.locator(".clock-time-text").evaluate((element) => {
+        return Number.parseFloat(getComputedStyle(element).fontSize);
+      });
+      expect(fittedClockFontSize * minimumCanvasScale).toBeGreaterThanOrEqual(25);
+      const zoomedTileBox = await expectBoundingBoxAsync(logicalTile);
+      expect(zoomedTileBox.width).toBeGreaterThan(normalZoomTileBox.width * 1.25);
+      await expectHorizontalOverflowAsync(canvas);
+      const overflowRailY = (await expectBoundingBoxAsync(rail)).y;
+      await page.evaluate(() => window.scrollTo({ top: 300, behavior: "auto" }));
+      await expect.poll(async () => (await expectBoundingBoxAsync(rail)).y).toBeGreaterThanOrEqual(0);
+      expect((await expectBoundingBoxAsync(rail)).y).toBeLessThanOrEqual(overflowRailY);
+      await page.evaluate(() => window.scrollTo({ top: 0, behavior: "auto" }));
+      await setDocumentZoomAsync(page, 1);
+      await expect(canvas).toHaveAttribute("data-canvas-overflow", "false");
+
+      const collapseDynamic = page.getByRole("button", {
+        name: "Collapse: Nested box",
+        exact: true,
+      });
+      await collapseDynamic.click();
+      await expect(dynamicSection).toHaveAttribute("data-grid-h", "1");
+      await expect(belowItem).toHaveAttribute("data-grid-y", "1");
+      await expect(nestedItem).toHaveCount(0);
+
+      await page
+        .getByRole("button", {
+          name: "Expand: Nested box",
+          exact: true,
+        })
+        .click();
+      await expect(dynamicSection).toHaveAttribute("data-grid-h", "2");
+      await expect(belowItem).toHaveAttribute("data-grid-y", "2");
+      await expect(nestedItem).toHaveCount(1);
+      await captureBoardScreenshotAsync(canvas, screenshotDirectory, "board-grid-read-only.png");
+
+      const viewMainSectionBox = await expectBoundingBoxAsync(mainSection);
+      const viewFirstItemBox = await expectBoundingBoxAsync(logicalTile);
+      runtimeResources.enterEditMode();
+      await editToggle.click();
+      await expect(page.locator(`[data-grid-runtime="${editRuntimeMarker}"]`)).toHaveCount(4);
+      await expect(page.getByTestId("board-grid-editor-loading")).toHaveCount(0);
+      await expect(page.getByTestId("board-canvas-row-count-button")).toHaveCount(0);
+      await expectBoundingBoxToMatchAsync(mainSection, viewMainSectionBox);
+      await expectBoundingBoxToMatchAsync(logicalTile, viewFirstItemBox);
+      await runtimeResources.waitForQuietAsync();
+      expect(runtimeResources.urlsFor("edit", "editor")).toEqual([]);
+      expect(runtimeResources.urlsFor("edit", "gridstack")).toEqual([]);
+      runtimeResources.stop();
+
+      await expect(mainSection).toHaveAttribute("role", "region");
+      await expect(mainSection).toHaveAttribute("data-grid-editable", "true");
+      await expect(firstItem.locator(`[data-grid-id="${fixture.firstItemId}"]`)).toHaveAttribute("role", "group");
+      await expectTargetSizeAsync(getEditorEntry(firstItem));
+      await expectTargetSizeAsync(firstItem.locator(':scope > [data-testid="board-grid-resize-handle"]'));
+
+      await page.getByRole("button", { name: "Add board content" }).click();
+      await expect(page.getByRole("menuitem", { name: "New section", exact: true })).toBeVisible();
+      await expect(page.getByRole("menuitem", { name: "New category", exact: true })).toHaveCount(0);
+      await page.getByRole("menuitem", { name: "New item", exact: true }).click();
+      const itemSelectDialog = page.getByRole("dialog", { name: "Choose item to add" });
+      await expect(itemSelectDialog).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(itemSelectDialog).toHaveCount(0);
+
+      const railBoxBeforeMainDrag = await expectBoundingBoxAsync(rail);
+      const canvasScale = await readCanvasScaleAsync(canvas);
+      await dragLocatorByAsync(page, getEditorEntry(firstItem), logicalCellPitch * canvasScale * 4, 0);
+      await expect(firstItem).toHaveAttribute("data-grid-x", "4");
+      expect(gridLayoutsOverlap(await readGridLayoutAsync(firstItem), await readGridLayoutAsync(secondItem))).toBe(
+        false,
+      );
+
+      const railBoxAfterMainDrag = await expectBoundingBoxAsync(rail);
+      expect(railBoxAfterMainDrag.x).toBeCloseTo(railBoxBeforeMainDrag.x, 1);
+      expect(railBoxAfterMainDrag.width).toBeCloseTo(railBoxBeforeMainDrag.width, 1);
+      await expect(railItem.locator("xpath=ancestor::aside[1]")).toHaveAttribute("aria-label", "Left dashboard rail");
+
+      const secondItemContent = secondItem.locator("[data-grid-item-content]");
+      await expect(secondItemContent).toHaveCount(1);
+      await secondItemContent.evaluate((element) => {
+        element.setAttribute("data-e2e-portal-instance", "second-item-content");
+      });
+
+      const railEditor = rail.locator("[data-grid-section-id]").first();
+      const railGridBox = await expectBoundingBoxAsync(railEditor);
+      await dragLocatorToAsync(
+        page,
+        getEditorEntry(secondItem),
+        railGridBox.x + logicalCellPitch * canvasScale * 1.5,
+        railGridBox.y + logicalCellSize * canvasScale * 0.5,
+      );
+      await expect(secondItem.locator("xpath=ancestor::aside[1]")).toHaveAttribute("data-board-gutter", "left");
+      await expect(
+        secondItem.locator('[data-grid-item-content][data-e2e-portal-instance="second-item-content"]'),
+      ).toBeVisible();
+      await expect(getEditorEntry(secondItem)).toHaveCount(1);
+      expect(pageErrors).toEqual([]);
+
+      await moveEntryWithModalAsync(page, secondItem, /Dashboard canvas, destination \d+/);
+      await expect(secondItem.locator("xpath=ancestor::*[@data-grid-section-id][1]")).toHaveAttribute(
+        "data-grid-section-id",
+        fixture.sectionId,
+      );
+      await expect(getEditorEntry(secondItem)).toBeFocused();
+      await moveEntryWithModalAsync(page, secondItem, /Left dashboard rail, destination \d+/);
+      await expect(secondItem.locator("xpath=ancestor::aside[1]")).toHaveAttribute("data-board-gutter", "left");
+      await expect(getEditorEntry(secondItem)).toBeFocused();
+      await expect(
+        secondItem.locator('[data-grid-item-content][data-e2e-portal-instance="second-item-content"]'),
+      ).toBeVisible();
+
+      const railKeyboardEntry = getEditorEntry(railItem);
+      await railKeyboardEntry.focus();
+      await railKeyboardEntry.press("Enter");
+      await expect(railKeyboardEntry).toHaveAttribute("data-keyboard-editing", "true");
+      await railKeyboardEntry.press("Shift+ArrowRight");
+      await expect(railItem).toHaveAttribute("data-grid-w", "2");
+      await railKeyboardEntry.press("Shift+ArrowLeft");
+      await expect(railItem).toHaveAttribute("data-grid-w", "1");
+      await railKeyboardEntry.press("ArrowRight");
+      await expect(railItem).toHaveAttribute("data-grid-x", "1");
+      await railKeyboardEntry.press("Escape");
+      await expect(railKeyboardEntry).toHaveAttribute("data-keyboard-editing", "false");
+
+      const dynamicResizeHandle = dynamicSection.locator(':scope > [data-testid="board-grid-resize-handle"]');
+      await dragLocatorByAsync(page, dynamicResizeHandle, 0, logicalCellPitch * canvasScale);
+      await expect(dynamicSection).toHaveAttribute("data-grid-h", "3");
+      await expect(belowItem).toHaveAttribute("data-grid-y", "3");
+      expect(gridLayoutsOverlap(await readGridLayoutAsync(dynamicSection), await readGridLayoutAsync(belowItem))).toBe(
+        false,
+      );
+
+      // The main canvas grows with its content instead of requiring a manual
+      // row limit, and items can occupy empty rows below their original position.
+      for (let targetRow = 1; targetRow <= 8; targetRow += 1) {
+        await firstItem.evaluate((element) => element.scrollIntoView({ block: "center", behavior: "instant" }));
+        await dragLocatorByAsync(page, getEditorEntry(firstItem), 0, logicalCellPitch * canvasScale);
+        await expect(firstItem).toHaveAttribute("data-grid-y", String(targetRow));
+      }
+      await expect(firstItem).toHaveAttribute("data-grid-y", "8");
+      expect(gridLayoutsOverlap(await readGridLayoutAsync(firstItem), await readGridLayoutAsync(belowItem))).toBe(
+        false,
+      );
+
+      const stickyRailY = (await expectBoundingBoxAsync(rail)).y;
+      await page.evaluate(() => window.scrollTo({ top: 500, behavior: "auto" }));
+      expect((await expectBoundingBoxAsync(rail)).y).toBeGreaterThanOrEqual(0);
+      expect((await expectBoundingBoxAsync(rail)).y).toBeLessThanOrEqual(stickyRailY);
+      await page.evaluate(() => window.scrollTo({ top: 0, behavior: "auto" }));
+
+      await setDocumentZoomAsync(page, 1.25);
+      await expectFixedLogicalTileAsync(logicalTile);
+      await expectUniformVisualScaleAsync(logicalTile);
+      await expectTargetSizeAsync(getEditorEntry(firstItem));
+      await expectTargetSizeAsync(firstItem.locator(':scope > [data-testid="board-grid-resize-handle"]'));
+      await setDocumentZoomAsync(page, 1);
+      await captureBoardScreenshotAsync(canvas, screenshotDirectory, "board-grid-edit-mode.png");
+
+      const dynamicLayoutBeforeDelete = await readGridLayoutAsync(dynamicSection);
+      await dynamicSection.getByRole("button", { name: "Settings for Nested box" }).click();
+      await page
+        .getByRole("menuitem", {
+          name: "Remove section",
+          exact: true,
+        })
+        .click();
+      await page
+        .getByRole("dialog", {
+          name: "Remove section",
+        })
+        .getByRole("button", {
+          name: "Confirm",
+          exact: true,
+        })
+        .click();
+
+      await expect(dynamicSection).toHaveCount(0);
+      await expect(nestedItem).toHaveCount(1);
+      await expect(nestedItem.locator("xpath=ancestor::*[@data-grid-section-id][1]")).toHaveAttribute(
+        "data-grid-section-id",
+        fixture.sectionId,
+      );
+      await expect(nestedItem).toHaveAttribute("data-grid-x", String(dynamicLayoutBeforeDelete.x));
+      await expect(nestedItem).toHaveAttribute("data-grid-y", String(dynamicLayoutBeforeDelete.y));
+
+      await page.getByTestId("board-edit-mode-toggle").click();
+      await expect(page.locator(`[data-grid-runtime="${editRuntimeMarker}"]`)).toHaveCount(0);
+
+      await page.reload();
+      const reloadedCanvas = page.locator('[data-testid="board-canvas"][data-board-hydrated="true"]');
+      const reloadedFirstItem = reloadedCanvas.locator(`[data-grid-item-id="${fixture.firstItemId}"]`);
+      const reloadedSecondItem = reloadedCanvas.locator(`[data-grid-item-id="${fixture.secondItemId}"]`);
+      const reloadedRailItem = reloadedCanvas.locator(`[data-grid-item-id="${fixture.railItemId}"]`);
+      const reloadedDynamicSection = reloadedCanvas.locator(`[data-grid-item-id="${fixture.dynamicSectionId}"]`);
+      const reloadedNestedItem = reloadedCanvas.locator(`[data-grid-item-id="${fixture.nestedItemId}"]`);
+      await expect(reloadedCanvas).toHaveCount(1);
+      await expect(reloadedFirstItem).toHaveAttribute("data-grid-x", "4");
+      await expect(reloadedFirstItem).toHaveAttribute("data-grid-y", "8");
+      await expect(reloadedRailItem).toHaveAttribute("data-grid-x", "1");
+      await expect(reloadedRailItem).toHaveAttribute("data-grid-w", "1");
+      await expect(reloadedDynamicSection).toHaveCount(0);
+      await expect(reloadedNestedItem).toHaveCount(1);
+      await expect(reloadedNestedItem.locator("xpath=ancestor::*[@data-grid-section-id][1]")).toHaveAttribute(
+        "data-grid-section-id",
+        fixture.sectionId,
+      );
+      await expect(reloadedSecondItem.locator("xpath=ancestor::aside[1]")).toHaveAttribute("data-board-gutter", "left");
+      const persistedFirstLayout = await readGridLayoutAsync(reloadedFirstItem);
+      const persistedSecondLayout = await readGridLayoutAsync(reloadedSecondItem);
+      expect(gridLayoutsOverlap(persistedFirstLayout, persistedSecondLayout)).toBe(false);
+
+      await page.goto(`${baseUrl}/boards/${fixture.boardName}/settings?tab=layout`);
+      const gutterPreview = page.getByLabel("Dashboard layout preview");
+      await expect(gutterPreview).toBeVisible();
+      const rightGutterSwitch = page.getByRole("switch", { name: "Right sidebar" });
+      await rightGutterSwitch.check();
+      const rightGutterSlider = page.getByRole("slider", { name: "Right sidebar width" });
+      await expect(rightGutterSlider).toHaveAttribute("aria-valuenow", "2");
+      await rightGutterSlider.press("ArrowRight");
+      await expect(rightGutterSlider).toHaveAttribute("aria-valuenow", "3");
+      await captureBoardScreenshotAsync(page.locator("main"), screenshotDirectory, "board-layout-gutter-settings.png");
+      await Promise.all([
+        page.waitForResponse(
+          (response) => response.url().includes("/api/trpc/board.saveLayouts") && response.status() === 200,
+        ),
+        rightGutterSwitch.locator("xpath=ancestor::form[1]").getByRole("button", { name: "Save changes" }).click(),
+      ]);
+
+      await page.goto(`${baseUrl}/boards/${fixture.boardName}`);
+      const boardWithBothGutters = page.locator('[data-testid="board-canvas"][data-board-hydrated="true"]');
+      await expect(boardWithBothGutters).toHaveCount(1);
+      await expect(page.getByRole("complementary", { name: "Left dashboard rail" })).toBeVisible();
+      const emptyRightGutter = page.getByRole("complementary", { name: "Right dashboard rail" });
+      await expect(emptyRightGutter).toHaveCount(1);
+      expect((await expectBoundingBoxAsync(emptyRightGutter)).width).toBeGreaterThan(0);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      runtimeResources?.stop();
+      await browser?.close();
+      await homarrContainer.stop();
+    }
+  }, 180_000);
+});
+
+const seedBoardGridAsync = async (db: SqliteDatabase, creatorId: string) => {
+  const boardId = createId();
+  const boardName = "grid-e2e";
+  const layoutId = createId();
+  const sectionId = createId();
+  const railSectionId = createId();
+  const dynamicSectionId = createId();
+  const firstItemId = createId();
+  const secondItemId = createId();
+  const belowItemId = createId();
+  const nestedItemId = createId();
+  const railItemId = createId();
+
+  await db.insert(sqliteSchema.boards).values({
+    id: boardId,
+    name: boardName,
+    creatorId,
+    isPublic: true,
+  });
+  await db.insert(sqliteSchema.layouts).values({
+    id: layoutId,
+    name: "Desktop",
+    boardId,
+    columnCount: 8,
+    breakpoint: 0,
+  });
+  await db.insert(sqliteSchema.sections).values([
+    {
+      id: sectionId,
+      boardId,
+      kind: "empty",
+      xOffset: 0,
+      yOffset: 0,
+    },
+    {
+      id: railSectionId,
+      boardId,
+      kind: "category",
+      name: "Pinned rail",
+      xOffset: 0,
+      yOffset: 0,
+      options: stringifySuperJSON({
+        showLabel: true,
+        collapsible: true,
+        showOpenAll: false,
+        railPlacement: "left",
+        columnCount: 2,
+      }),
+    },
+    {
+      id: dynamicSectionId,
+      boardId,
+      kind: "dynamic",
+      options: stringifySuperJSON({
+        title: "Nested box",
+        customCssClasses: [],
+        borderColor: "",
+        showLabel: true,
+        collapsible: true,
+        showOpenAll: false,
+      }),
+    },
+  ]);
+  await db.insert(sqliteSchema.sectionCollapseStates).values({
+    userId: creatorId,
+    sectionId: railSectionId,
+    // Legacy categories stored true when the category was open.
+    collapsed: true,
+  });
+  await db.insert(sqliteSchema.sectionLayouts).values({
+    sectionId: dynamicSectionId,
+    layoutId,
+    parentSectionId: sectionId,
+    xOffset: 2,
+    yOffset: 0,
+    width: 2,
+    height: 2,
+  });
+  await db.insert(sqliteSchema.items).values([
+    {
+      id: firstItemId,
+      boardId,
+      kind: "clock",
+      options: stringifySuperJSON({ is24HourFormat: true }),
+    },
+    {
+      id: secondItemId,
+      boardId,
+      kind: "clock",
+      options: stringifySuperJSON({ is24HourFormat: true }),
+    },
+    {
+      id: belowItemId,
+      boardId,
+      kind: "clock",
+      options: stringifySuperJSON({ is24HourFormat: true }),
+    },
+    {
+      id: nestedItemId,
+      boardId,
+      kind: "clock",
+      options: stringifySuperJSON({ is24HourFormat: true }),
+    },
+    {
+      id: railItemId,
+      boardId,
+      kind: "clock",
+      options: stringifySuperJSON({ is24HourFormat: true }),
+    },
+  ]);
+  await db.insert(sqliteSchema.itemLayouts).values([
+    {
+      itemId: firstItemId,
+      sectionId,
+      layoutId,
+      xOffset: 0,
+      yOffset: 0,
+      width: 1,
+      height: 1,
+    },
+    {
+      itemId: secondItemId,
+      sectionId,
+      layoutId,
+      xOffset: 1,
+      yOffset: 0,
+      width: 1,
+      height: 1,
+    },
+    {
+      itemId: belowItemId,
+      sectionId,
+      layoutId,
+      xOffset: 2,
+      yOffset: 2,
+      width: 2,
+      height: 1,
+    },
+    {
+      itemId: nestedItemId,
+      sectionId: dynamicSectionId,
+      layoutId,
+      xOffset: 0,
+      yOffset: 0,
+      width: 1,
+      height: 1,
+    },
+    {
+      itemId: railItemId,
+      sectionId: railSectionId,
+      layoutId,
+      xOffset: 0,
+      yOffset: 0,
+      width: 1,
+      height: 1,
+    },
+  ]);
+
+  return {
+    boardName,
+    sectionId,
+    railSectionId,
+    dynamicSectionId,
+    firstItemId,
+    secondItemId,
+    belowItemId,
+    nestedItemId,
+    railItemId,
+  };
+};
+
+const signInAsync = async (page: Page, baseUrl: string, callbackPath: string) => {
+  const loginUrl = new URL("/auth/login", baseUrl);
+  loginUrl.searchParams.set("callbackUrl", callbackPath);
+  await page.goto(loginUrl.href);
+  await page.getByLabel("Username").fill(adminCredentials.username);
+  await page.getByRole("textbox", { name: "Password", exact: true }).fill(adminCredentials.password);
+  await page.locator("button[type='submit']").click();
+  await page.waitForURL(`${baseUrl}${callbackPath}`, { timeout: 15_000 });
+};
+
+const prepareScreenshotDirectoryAsync = async () => {
+  const configuredDirectory = process.env.HOMARR_E2E_SCREENSHOT_DIR?.trim();
+  if (!configuredDirectory) return undefined;
+
+  const directory = resolvePath(configuredDirectory);
+  await mkdir(directory, { recursive: true });
+  return directory;
+};
+
+const captureBoardScreenshotAsync = async (
+  canvas: Locator,
+  screenshotDirectory: string | undefined,
+  fileName: string,
+) => {
+  if (!screenshotDirectory) return;
+  await canvas.screenshot({
+    animations: "disabled",
+    caret: "hide",
+    path: resolvePath(screenshotDirectory, fileName),
+  });
+};
+
+type RuntimeResourcePhase = "read-only" | "edit";
+type RuntimePayload = "editor" | "gridstack";
+
+interface RuntimeResource {
+  phase: RuntimeResourcePhase;
+  url: string;
+  hasEditorPayload: boolean;
+  hasGridStackPayload: boolean;
+}
+
+const trackRuntimeResources = (page: Page) => {
+  const resources: RuntimeResource[] = [];
+  const pendingResponses = new Set<Promise<void>>();
+  const inFlightRequests = new Set<Request>();
+  const requestPhases = new WeakMap<Request, RuntimeResourcePhase>();
+  const bodyErrors: Error[] = [];
+  let phase: RuntimeResourcePhase = "read-only";
+  let lastActivityAt = Date.now();
+  let stopped = false;
+
+  const handleRequest = (request: Request) => {
+    requestPhases.set(request, phase);
+    if (!isRuntimeResourceType(request.resourceType())) return;
+    inFlightRequests.add(request);
+    lastActivityAt = Date.now();
+  };
+
+  const handleRequestFailed = (request: Request) => {
+    if (!inFlightRequests.delete(request)) return;
+    lastActivityAt = Date.now();
+  };
+
+  const handleResponse = (response: Response) => {
+    const resourceKind = getRuntimeResourceKind(response);
+    if (!resourceKind) return;
+
+    const request = response.request();
+    const responsePhase = requestPhases.get(request) ?? phase;
+    inFlightRequests.delete(request);
+    lastActivityAt = Date.now();
+    const task = readRuntimeResponseBodyAsync(page, response)
+      .then((body) => {
+        resources.push({
+          phase: responsePhase,
+          url: response.url(),
+          hasEditorPayload: body.includes(Buffer.from(editRuntimeMarker)),
+          hasGridStackPayload: body.includes(Buffer.from(gridStackPayloadMarker)),
+        });
+      })
+      .catch((error: unknown) => {
+        bodyErrors.push(new Error(`Unable to inspect ${resourceKind} response ${response.url()}`, { cause: error }));
+      });
+
+    pendingResponses.add(task);
+    void task.finally(() => {
+      pendingResponses.delete(task);
+      lastActivityAt = Date.now();
+    });
+  };
+
+  page.on("request", handleRequest);
+  page.on("requestfailed", handleRequestFailed);
+  page.on("response", handleResponse);
+
+  return {
+    enterEditMode() {
+      phase = "edit";
+    },
+    urlsFor(resourcePhase: RuntimeResourcePhase, payload: RuntimePayload) {
+      const key = payload === "editor" ? "hasEditorPayload" : "hasGridStackPayload";
+      return [
+        ...new Set(
+          resources
+            .filter((resource) => resource.phase === resourcePhase && resource[key])
+            .map((resource) => resource.url),
+        ),
+      ];
+    },
+    async waitForQuietAsync({ quietMs = 300, timeoutMs = 15_000 } = {}) {
+      const deadline = Date.now() + timeoutMs;
+
+      while (true) {
+        if (pendingResponses.size > 0) {
+          await Promise.all(pendingResponses);
+        }
+        if (bodyErrors.length > 0) {
+          throw new AggregateError(bodyErrors, "Unable to inspect one or more JavaScript or CSS responses");
+        }
+
+        const quietFor = Date.now() - lastActivityAt;
+        if (pendingResponses.size === 0 && inFlightRequests.size === 0 && quietFor >= quietMs) return;
+        if (Date.now() >= deadline) {
+          throw new Error(
+            `JavaScript and CSS requests did not become quiet within ${timeoutMs}ms ` +
+              `(${inFlightRequests.size} requests and ${pendingResponses.size} response bodies pending)`,
+          );
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(1, quietMs - quietFor))));
+      }
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      page.off("request", handleRequest);
+      page.off("requestfailed", handleRequestFailed);
+      page.off("response", handleResponse);
+    },
+  };
+};
+
+const readRuntimeResponseBodyAsync = async (page: Page, response: Response) => {
+  try {
+    return await response.body();
+  } catch (originalError) {
+    try {
+      const fallbackResponse = await page.request.get(response.url(), {
+        failOnStatusCode: false,
+      });
+      if (!fallbackResponse.ok()) {
+        throw new Error(`Fallback request returned HTTP ${fallbackResponse.status()}`, {
+          cause: originalError,
+        });
+      }
+      return await fallbackResponse.body();
+    } catch (fallbackError) {
+      throw new Error(
+        `Unable to read or refetch runtime response ${response.url()}. Original read error: ${String(originalError)}`,
+        { cause: fallbackError },
+      );
+    }
+  }
+};
+
+const isRuntimeResourceType = (resourceType: string) => resourceType === "script" || resourceType === "stylesheet";
+
+const getRuntimeResourceKind = (response: Response): "script" | "stylesheet" | null => {
+  const resourceType = response.request().resourceType();
+  if (resourceType === "script" || resourceType === "stylesheet") return resourceType;
+
+  const contentType = response.headers()["content-type"]?.toLowerCase() ?? "";
+  if (contentType.includes("javascript") || contentType.includes("ecmascript")) return "script";
+  if (contentType.includes("text/css")) return "stylesheet";
+  return null;
+};
+
+const expectBoundingBoxAsync = async (locator: Locator) => {
+  const box = await locator.boundingBox();
+  expect(box).not.toBeNull();
+  if (box === null) {
+    throw new Error("Expected locator to have a bounding box");
+  }
+  return box;
+};
+
+const expectBoundingBoxToMatchAsync = async (
+  locator: Locator,
+  expected: { x: number; y: number; width: number; height: number },
+) => {
+  const actual = await expectBoundingBoxAsync(locator);
+  expect(actual.x).toBeCloseTo(expected.x, 0);
+  expect(actual.y).toBeCloseTo(expected.y, 0);
+  expect(actual.width).toBeCloseTo(expected.width, 0);
+  expect(actual.height).toBeCloseTo(expected.height, 0);
+};
+
+const installLayoutShiftObserverAsync = async (page: Page) => {
+  await page.addInitScript(() => {
+    const target = window as typeof window & {
+      homarrLayoutShiftScore?: number;
+      homarrReleaseIdleCallbacks?: () => void;
+    };
+    const idleCallbacks = new Map<number, IdleRequestCallback>();
+    let nextIdleCallbackId = 1;
+
+    target.homarrLayoutShiftScore = 0;
+    target.requestIdleCallback = (callback) => {
+      const callbackId = nextIdleCallbackId++;
+      idleCallbacks.set(callbackId, callback);
+      return callbackId;
+    };
+    target.cancelIdleCallback = (callbackId) => {
+      idleCallbacks.delete(callbackId);
+    };
+    target.homarrReleaseIdleCallbacks = () => {
+      const callbacks = [...idleCallbacks.values()];
+      idleCallbacks.clear();
+      for (const callback of callbacks) {
+        callback({
+          didTimeout: false,
+          timeRemaining: () => 50,
+        });
+      }
+    };
+
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        const shift = entry as PerformanceEntry & { hadRecentInput: boolean; value: number };
+        if (!shift.hadRecentInput) {
+          target.homarrLayoutShiftScore = (target.homarrLayoutShiftScore ?? 0) + shift.value;
+        }
+      }
+    }).observe({ type: "layout-shift", buffered: true });
+  });
+};
+
+const releaseIdleCallbacksAsync = async (page: Page) => {
+  await page.evaluate(() => {
+    const release = (
+      window as typeof window & {
+        homarrReleaseIdleCallbacks?: () => void;
+      }
+    ).homarrReleaseIdleCallbacks;
+    if (!release) {
+      throw new Error("Idle callback release hook was not installed");
+    }
+    release();
+  });
+};
+
+const readLayoutShiftScoreAsync = async (page: Page) =>
+  await page.evaluate(
+    () => (window as typeof window & { homarrLayoutShiftScore?: number }).homarrLayoutShiftScore ?? 0,
+  );
+
+const resetLayoutShiftScoreAsync = async (page: Page) => {
+  await page.evaluate(() => {
+    (window as typeof window & { homarrLayoutShiftScore?: number }).homarrLayoutShiftScore = 0;
+  });
+};
+
+const dragLocatorByAsync = async (page: Page, locator: Locator, deltaX: number, deltaY: number) => {
+  const box = await expectBoundingBoxAsync(locator);
+  await dragLocatorToAsync(page, locator, box.x + box.width / 2 + deltaX, box.y + box.height / 2 + deltaY);
+};
+
+const dragLocatorToAsync = async (page: Page, locator: Locator, targetX: number, targetY: number) => {
+  const box = await expectBoundingBoxAsync(locator);
+  const startX = box.x + box.width / 2;
+  const startY = box.y + box.height / 2;
+
+  await page.mouse.move(startX, startY);
+  await page.mouse.down();
+  await page.mouse.move(targetX, targetY, { steps: 12 });
+  await page.mouse.up();
+};
+
+const readCanvasScaleAsync = async (canvas: Locator) => {
+  const scale = Number(await canvas.getAttribute("data-canvas-scale"));
+  expect(Number.isFinite(scale)).toBe(true);
+  expect(scale).toBeGreaterThan(0);
+  return scale;
+};
+
+const setDocumentZoomAsync = async (page: Page, zoom: number) => {
+  await page.evaluate((nextZoom) => {
+    document.documentElement.style.zoom = String(nextZoom);
+  }, zoom);
+  await page.evaluate(
+    () =>
+      new Promise<void>((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+      }),
+  );
+};
+
+const moveEntryWithModalAsync = async (page: Page, entry: Locator, targetName: RegExp) => {
+  await entry.getByRole("button", { name: /^Settings for / }).click();
+  await page.getByRole("menuitem", { name: "Move / resize item", exact: true }).click();
+
+  const dialog = page.getByRole("dialog", { name: "Move / resize item" });
+  await dialog.getByLabel("Section or rail").click();
+  await page.getByRole("option", { name: targetName }).click();
+  await dialog.getByRole("button", { name: "Save changes", exact: true }).click();
+};
+
+const getEditorEntry = (entry: Locator) => entry.locator("[data-editor-grid-entry]").first();
+
+const expectFixedLogicalTileAsync = async (locator: Locator) => {
+  await expect(locator).toHaveJSProperty("offsetWidth", logicalCellSize);
+  await expect(locator).toHaveJSProperty("offsetHeight", logicalCellSize);
+};
+
+const expectUniformVisualScaleAsync = async (locator: Locator) => {
+  const scale = await locator.evaluate((element) => {
+    const rect = element.getBoundingClientRect();
+    const htmlElement = element as HTMLElement;
+    return {
+      horizontal: rect.width / htmlElement.offsetWidth,
+      vertical: rect.height / htmlElement.offsetHeight,
+    };
+  });
+
+  expect(scale.horizontal).toBeCloseTo(scale.vertical, 3);
+};
+
+const expectHorizontalOverflowAsync = async (locator: Locator) => {
+  const dimensions = await locator.evaluate((element) => {
+    const htmlElement = element as HTMLElement;
+    return {
+      clientWidth: htmlElement.clientWidth,
+      scrollWidth: htmlElement.scrollWidth,
+    };
+  });
+
+  expect(dimensions.scrollWidth).toBeGreaterThan(dimensions.clientWidth);
+};
+
+const expectTargetSizeAsync = async (locator: Locator) => {
+  const box = await expectBoundingBoxAsync(locator);
+  expect(box.width).toBeGreaterThanOrEqual(24);
+  expect(box.height).toBeGreaterThanOrEqual(24);
+};
+
+const readGridLayoutAsync = async (locator: Locator) => {
+  const [x, y, width, height] = await Promise.all([
+    locator.getAttribute("data-grid-x"),
+    locator.getAttribute("data-grid-y"),
+    locator.getAttribute("data-grid-w"),
+    locator.getAttribute("data-grid-h"),
+  ]);
+
+  expect(x).not.toBeNull();
+  expect(y).not.toBeNull();
+  expect(width).not.toBeNull();
+  expect(height).not.toBeNull();
+
+  return {
+    x: Number(x),
+    y: Number(y),
+    width: Number(width),
+    height: Number(height),
+  };
+};
+
+const gridLayoutsOverlap = (
+  first: { x: number; y: number; width: number; height: number },
+  second: { x: number; y: number; width: number; height: number },
+) =>
+  first.x < second.x + second.width &&
+  first.x + first.width > second.x &&
+  first.y < second.y + second.height &&
+  first.y + first.height > second.y;

e2e/shared/seed-admin-user.ts

@@ -36,6 +36,8 @@ export const seedAdminUserAsync = async (db: SqliteDatabase, input: SeedAdminUse
     name: input.username,
     provider: "credentials",
     password: await hashPasswordAsync(input.password),
+    completedManageTour: true,
+    completedBoardTour: true,
   });
 
   await db.insert(sqliteSchema.groups).values({

packages/api/src/router/board.ts

@@ -29,12 +29,16 @@ import {
   sections,
   users,
 } from "@homarr/db/schema";
-import type { WidgetKind } from "@homarr/definitions";
+import type { BoardLane, WidgetKind } from "@homarr/definitions";
 import {
+  boardLanes,
   emptySuperJSON,
   everyoneGroup,
+  getBoardLaneColumnCount,
+  getRootSectionLane,
   getPermissionsWithChildren,
   getPermissionsWithParents,
+  rootSectionOffsets,
   widgetDefaultSizes,
   widgetKinds,
 } from "@homarr/definitions";
@@ -321,6 +325,8 @@ export const boardRouter = createTRPCRouter({
         id: createId(),
         name: "Base",
         columnCount: input.columnCount,
+        leftGutterColumnCount: 0,
+        rightGutterColumnCount: 0,
         breakpoint: 0,
         boardId,
       });
@@ -690,7 +696,25 @@ export const boardRouter = createTRPCRouter({
   saveLayouts: protectedProcedure.input(boardSaveLayoutsSchema).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);
+    let board = await getFullBoardWithWhereAsync(ctx.db, eq(boards.id, input.id), ctx.session.user.id);
+    const missingGutterRoots = (["left", "right"] as const).filter(
+      (lane) =>
+        input.layouts.some((layout) => getBoardLaneColumnCount(layout, lane) > 0) &&
+        !getRootSectionForLane(board, lane),
+    );
+    if (missingGutterRoots.length > 0) {
+      await ctx.db.insert(sections).values(
+        missingGutterRoots.map((lane) => ({
+          id: createId(),
+          boardId: board.id,
+          kind: "empty" as const,
+          xOffset: rootSectionOffsets[lane],
+          yOffset: 0,
+          options: emptySuperJSON,
+        })),
+      );
+      board = await getFullBoardWithWhereAsync(ctx.db, eq(boards.id, input.id), ctx.session.user.id);
+    }
 
     const addedLayouts = filterAddedItems(input.layouts, board.layouts);
 
@@ -701,14 +725,6 @@ export const boardRouter = createTRPCRouter({
     for (const addedLayout of addedLayouts) {
       const layoutId = createId();
 
-      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);
       // Fallback to biggest if none exists with columnCount bigger than addedLayout.columnCount
       const layoutToClone =
@@ -719,13 +735,27 @@ export const boardRouter = createTRPCRouter({
         previous: {
           layoutId: layoutToClone.id,
           columnCount: layoutToClone.columnCount,
+          leftGutterColumnCount: layoutToClone.leftGutterColumnCount,
+          rightGutterColumnCount: layoutToClone.rightGutterColumnCount,
         },
         current: {
           layoutId,
           columnCount: addedLayout.columnCount,
+          leftGutterColumnCount: addedLayout.leftGutterColumnCount,
+          rightGutterColumnCount: addedLayout.rightGutterColumnCount,
         },
       });
 
+      layoutsToInsert.push({
+        id: layoutId,
+        name: addedLayout.name,
+        columnCount: addedLayout.columnCount,
+        leftGutterColumnCount: addedLayout.leftGutterColumnCount,
+        rightGutterColumnCount: addedLayout.rightGutterColumnCount,
+        breakpoint: addedLayout.breakpoint,
+        boardId: board.id,
+      });
+
       itemSectionLayoutsToInsert.push(...updatedBoardLayout.itemSectionLayouts);
       sectionLayoutsToInsert.push(...updatedBoardLayout.sectionLayouts);
     }
@@ -746,16 +776,25 @@ export const boardRouter = createTRPCRouter({
     for (const updatedLayout of updatedLayouts) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       const dbLayout = board.layouts.find((layout) => layout.id === updatedLayout.id)!;
+      let updatedBoardLayout: ReturnType<typeof getUpdatedBoardLayout> | undefined;
 
-      if (dbLayout.columnCount !== updatedLayout.columnCount) {
-        const updatedBoardLayout = getUpdatedBoardLayout(board, {
+      if (
+        dbLayout.columnCount !== updatedLayout.columnCount ||
+        dbLayout.leftGutterColumnCount !== updatedLayout.leftGutterColumnCount ||
+        dbLayout.rightGutterColumnCount !== updatedLayout.rightGutterColumnCount
+      ) {
+        updatedBoardLayout = getUpdatedBoardLayout(board, {
           previous: {
             layoutId: dbLayout.id,
             columnCount: dbLayout.columnCount,
+            leftGutterColumnCount: dbLayout.leftGutterColumnCount,
+            rightGutterColumnCount: dbLayout.rightGutterColumnCount,
           },
           current: {
             layoutId: dbLayout.id,
             columnCount: updatedLayout.columnCount,
+            leftGutterColumnCount: updatedLayout.leftGutterColumnCount,
+            rightGutterColumnCount: updatedLayout.rightGutterColumnCount,
           },
         });
 
@@ -801,6 +840,8 @@ export const boardRouter = createTRPCRouter({
         .set({
           name: updatedLayout.name,
           columnCount: updatedLayout.columnCount,
+          leftGutterColumnCount: updatedLayout.leftGutterColumnCount,
+          rightGutterColumnCount: updatedLayout.rightGutterColumnCount,
           breakpoint: updatedLayout.breakpoint,
         })
         .where(eq(layouts.id, updatedLayout.id));
@@ -877,8 +918,8 @@ export const boardRouter = createTRPCRouter({
                 id: section.id,
                 kind: section.kind,
                 yOffset: section.kind !== "dynamic" ? section.yOffset : null,
-                xOffset: section.kind === "dynamic" ? null : 0,
-                options: section.kind === "dynamic" ? superjson.stringify(section.options) : emptySuperJSON,
+                xOffset: section.kind === "dynamic" ? null : section.xOffset,
+                options: section.kind === "empty" ? emptySuperJSON : superjson.stringify(section.options),
                 name: "name" in section ? section.name : null,
                 boardId: dbBoard.id,
               })),
@@ -1003,8 +1044,8 @@ export const boardRouter = createTRPCRouter({
               .update(schema.sections)
               .set({
                 yOffset: prev?.kind !== "dynamic" && "yOffset" in section ? section.yOffset : null,
-                xOffset: prev?.kind !== "dynamic" && "yOffset" in section ? 0 : null,
-                options: section.kind === "dynamic" ? superjson.stringify(section.options) : emptySuperJSON,
+                xOffset: prev?.kind !== "dynamic" && "xOffset" in section ? section.xOffset : null,
+                options: section.kind === "empty" ? emptySuperJSON : superjson.stringify(section.options),
                 name: prev?.kind === "category" && "name" in section ? section.name : null,
               })
               .where(eq(schema.sections.id, section.id));
@@ -1077,8 +1118,8 @@ export const boardRouter = createTRPCRouter({
                   id: section.id,
                   kind: section.kind,
                   yOffset: section.kind !== "dynamic" ? section.yOffset : null,
-                  xOffset: section.kind === "dynamic" ? null : 0,
-                  options: section.kind === "dynamic" ? superjson.stringify(section.options) : emptySuperJSON,
+                  xOffset: section.kind === "dynamic" ? null : section.xOffset,
+                  options: section.kind === "empty" ? emptySuperJSON : superjson.stringify(section.options),
                   name: "name" in section ? section.name : null,
                   boardId: dbBoard.id,
                 })),
@@ -1213,8 +1254,8 @@ export const boardRouter = createTRPCRouter({
               .update(sections)
               .set({
                 yOffset: prev?.kind !== "dynamic" && "yOffset" in section ? section.yOffset : null,
-                xOffset: prev?.kind !== "dynamic" && "yOffset" in section ? 0 : null,
-                options: section.kind === "dynamic" ? superjson.stringify(section.options) : emptySuperJSON,
+                xOffset: prev?.kind !== "dynamic" && "xOffset" in section ? section.xOffset : null,
+                options: section.kind === "empty" ? emptySuperJSON : superjson.stringify(section.options),
                 name: prev?.kind === "category" && "name" in section ? section.name : null,
               })
               .where(eq(sections.id, section.id))
@@ -1657,77 +1698,96 @@ const noBoardWithSimilarNameAsync = async (db: Database, name: string, ignoredId
 const getUpdatedBoardLayout = (
   board: Awaited<ReturnType<typeof getFullBoardWithWhereAsync>>,
   options: {
-    previous: {
-      layoutId: string;
-      columnCount: number;
-    };
-    current: {
-      layoutId: string;
-      columnCount: number;
-    };
+    previous: BoardLayoutGeometry;
+    current: BoardLayoutGeometry;
   },
 ) => {
-  const itemSectionLayoutsCollection: InferInsertModel<typeof itemLayouts>[] = [];
-  const sectionLayoutsCollection: InferInsertModel<typeof sectionLayouts>[] = [];
-
   const elements = getElementsForLayout(board, options.previous.layoutId);
-  const rootSections = board.sections.filter((section) => section.kind !== "dynamic");
-
-  for (const rootSection of rootSections) {
-    const result = generateResponsiveGridFor({
-      items: elements,
-      previousWidth: options.previous.columnCount,
-      width: options.current.columnCount,
-      sectionId: rootSection.id,
-    });
-
-    itemSectionLayoutsCollection.push(
-      ...board.items
-        .map((item): InferInsertModel<typeof itemLayouts> | null => {
-          const currentElement = result.items.find((element) => element.type === "item" && element.id === item.id);
-
-          if (!currentElement) {
-            return null;
-          }
-
-          return {
-            itemId: item.id,
-            layoutId: options.current.layoutId,
-            sectionId: currentElement.sectionId,
-            height: currentElement.height,
-            width: currentElement.width,
-            xOffset: currentElement.xOffset,
-            yOffset: currentElement.yOffset,
-          };
-        })
-        .filter((item) => item !== null),
-    );
-
-    sectionLayoutsCollection.push(
-      ...board.sections
-        .filter((section) => section.kind === "dynamic")
-        .map((section): InferInsertModel<typeof sectionLayouts> | null => {
-          const currentElement = result.items.find(
-            (element) => element.type === "section" && element.id === section.id,
-          );
-
-          if (!currentElement) {
-            return null;
-          }
-
-          return {
-            layoutId: options.current.layoutId,
-            sectionId: section.id,
-            parentSectionId: currentElement.sectionId,
-            height: currentElement.height,
-            width: currentElement.width,
-            xOffset: currentElement.xOffset,
-            yOffset: currentElement.yOffset,
-          };
-        })
-        .filter((section) => section !== null),
-    );
+  const emptyRoots = board.sections
+    .filter((section) => section.kind === "empty")
+    .toSorted((first, second) => (first.yOffset ?? 0) - (second.yOffset ?? 0) || first.id.localeCompare(second.id));
+  const rootByLane = new Map<BoardLane, (typeof emptyRoots)[number]>();
+  for (const root of emptyRoots) {
+    const lane = getRootSectionLane(root.xOffset);
+    if (!rootByLane.has(lane)) rootByLane.set(lane, root);
   }
+  const mainRoot = rootByLane.get("main");
+  if (!mainRoot) throw new Error(`Board "${board.id}" has no main canvas root`);
+
+  const sourceRootById = new Map(emptyRoots.map((section) => [section.id, getRootSectionLane(section.xOffset)] as const));
+  const targetLaneBySourceLane = new Map<BoardLane, BoardLane>(
+    boardLanes.map((lane) => [
+      lane,
+      lane !== "main" && getBoardLaneColumnCount(options.current, lane) === 0 ? "main" : lane,
+    ]),
+  );
+  const remappedElements = elements.map((element) => {
+    const sourceLane = sourceRootById.get(element.sectionId);
+    if (!sourceLane) return element;
+    const targetLane = targetLaneBySourceLane.get(sourceLane) ?? "main";
+    const targetRoot = rootByLane.get(targetLane) ?? mainRoot;
+    return {
+      ...element,
+      sectionId: targetRoot.id,
+    };
+  });
+
+  const results = boardLanes.flatMap((lane) => {
+    const root = rootByLane.get(lane);
+    const width = getBoardLaneColumnCount(options.current, lane);
+    if (!root || width === 0) return [];
+    const sourceLanes = boardLanes.filter((sourceLane) => targetLaneBySourceLane.get(sourceLane) === lane);
+    const previousWidth =
+      sourceLanes.length === 1
+        ? getBoardLaneColumnCount(options.previous, sourceLanes[0] ?? "main")
+        : Number.MAX_SAFE_INTEGER;
+
+    return [
+      generateResponsiveGridFor({
+        items: remappedElements,
+        previousWidth,
+        width,
+        sectionId: root.id,
+      }),
+    ];
+  });
+  const updatedElements = results.flatMap((result) => result.items);
+  const updatedElementById = new Map(updatedElements.map((element) => [element.id, element]));
+
+  const itemSectionLayoutsCollection = board.items.flatMap((item): InferInsertModel<typeof itemLayouts>[] => {
+    const currentElement = updatedElementById.get(item.id);
+    if (!currentElement || currentElement.type !== "item") return [];
+
+    return [
+      {
+        itemId: item.id,
+        layoutId: options.current.layoutId,
+        sectionId: currentElement.sectionId,
+        height: currentElement.height,
+        width: currentElement.width,
+        xOffset: currentElement.xOffset,
+        yOffset: currentElement.yOffset,
+      },
+    ];
+  });
+
+  const sectionLayoutsCollection = board.sections.flatMap((section): InferInsertModel<typeof sectionLayouts>[] => {
+    if (section.kind !== "dynamic") return [];
+    const currentElement = updatedElementById.get(section.id);
+    if (!currentElement || currentElement.type !== "section") return [];
+
+    return [
+      {
+        layoutId: options.current.layoutId,
+        sectionId: section.id,
+        parentSectionId: currentElement.sectionId,
+        height: currentElement.height,
+        width: currentElement.width,
+        xOffset: currentElement.xOffset,
+        yOffset: currentElement.yOffset,
+      },
+    ];
+  });
 
   return {
     itemSectionLayouts: itemSectionLayoutsCollection,
@@ -1735,6 +1795,24 @@ const getUpdatedBoardLayout = (
   };
 };
 
+interface BoardLayoutGeometry {
+  layoutId: string;
+  columnCount: number;
+  leftGutterColumnCount: number;
+  rightGutterColumnCount: number;
+}
+
+const getRootSectionForLane = (
+  board: Awaited<ReturnType<typeof getFullBoardWithWhereAsync>>,
+  lane: BoardLane,
+) => {
+  const roots = board.sections.filter(
+    (section) => section.kind === "empty" && getRootSectionLane(section.xOffset) === lane,
+  );
+  if (roots.length > 1) throw new Error(`Board "${board.id}" has multiple ${lane} canvas roots`);
+  return roots[0];
+};
+
 const getElementsForLayout = (board: Awaited<ReturnType<typeof getFullBoardWithWhereAsync>>, layoutId: string) => {
   const sectionElements = board.sections
     .filter((section) => section.kind === "dynamic")
@@ -1848,7 +1926,7 @@ const getFullBoardWithWhereAsync = async (db: Database, where: SQL<unknown>, use
           parentSectionId: layout.parentSectionId,
           layoutId: layout.layoutId,
         })),
-        collapsed: collapseStates.at(0)?.collapsed ?? false,
+        collapsed: collapseStates.at(0)?.collapsed ?? section.kind === "category",
       }),
     ),
     items: items

packages/api/src/router/section/section-router.ts

@@ -1,8 +1,11 @@
 import { TRPCError } from "@trpc/server";
+import superjson from "superjson";
 import { z } from "zod/v4";
 
 import { and, eq } from "@homarr/db";
 import { sectionCollapseStates, sections } from "@homarr/db/schema";
+import { emptySuperJSON } from "@homarr/definitions";
+import { categorySectionOptionsSchema, dynamicSectionOptionsSchema } from "@homarr/validation/shared";
 
 import { createTRPCRouter, protectedProcedure } from "../../trpc";
 
@@ -16,7 +19,7 @@ export const sectionRouter = createTRPCRouter({
     )
     .mutation(async ({ ctx, input }) => {
       const section = await ctx.db.query.sections.findFirst({
-        where: and(eq(sections.id, input.sectionId), eq(sections.kind, "category")),
+        where: eq(sections.id, input.sectionId),
         with: {
           collapseStates: {
             where: eq(sectionCollapseStates.userId, ctx.session.user.id),
@@ -31,6 +34,26 @@ export const sectionRouter = createTRPCRouter({
         });
       }
 
+      if (section.kind === "empty") {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: `Section cannot be collapsed id=${input.sectionId}`,
+        });
+      }
+
+      const rawOptions = superjson.parse(section.options ?? emptySuperJSON);
+      const parsedOptions =
+        section.kind === "category"
+          ? categorySectionOptionsSchema.safeParse(rawOptions)
+          : dynamicSectionOptionsSchema.safeParse(rawOptions);
+
+      if (!parsedOptions.success || !parsedOptions.data.collapsible) {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: `Section cannot be collapsed id=${input.sectionId}`,
+        });
+      }
+
       if (section.collapseStates.length === 0) {
         await ctx.db.insert(sectionCollapseStates).values({
           sectionId: section.id,

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

@@ -572,6 +572,35 @@ describe("getBoardByName should return board by name", () => {
     expect(spy).toHaveBeenCalledWith(expect.anything(), expect.anything(), "view");
   });
 
+  it("normalizes legacy category behavior options in the response", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, sectionId } = await createFullBoardAsync(db, "default");
+    await db
+      .update(sections)
+      .set({
+        kind: "category",
+        name: "Media",
+      })
+      .where(eq(sections.id, sectionId));
+
+    const result = await caller.getBoardByName({ name: "default" });
+    const section = expectToBeDefined(result.sections[0]);
+
+    expect(result.id).toBe(boardId);
+    expect(section.kind).toBe("category");
+    if (section.kind === "category") {
+      expect(section.collapsed).toBe(true);
+      expect(section.options).toEqual({
+        showLabel: true,
+        collapsible: true,
+        showOpenAll: true,
+        railPlacement: "main",
+        columnCount: 2,
+      });
+    }
+  });
+
   it("should throw error when not present", async () => {
     // Arrange
     const db = createDb();
@@ -882,6 +911,68 @@ describe("saveBoard should save full board", () => {
       expect(spy).toHaveBeenCalledWith(expect.anything(), expect.anything(), "modify");
     },
   );
+  it("should add and update category behavior options", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId } = await createFullBoardAsync(db, "default");
+    const sectionId = createId();
+
+    await caller.saveBoard({
+      id: boardId,
+      sections: [
+        {
+          id: sectionId,
+          kind: "category",
+          name: "Navigation",
+          xOffset: 0,
+          yOffset: 0,
+          collapsed: false,
+          options: {
+            showLabel: true,
+            collapsible: true,
+            showOpenAll: true,
+            railPlacement: "left",
+            columnCount: 3,
+          },
+        },
+      ],
+      items: [],
+    });
+
+    await caller.saveBoard({
+      id: boardId,
+      sections: [
+        {
+          id: sectionId,
+          kind: "category",
+          name: "Navigation",
+          xOffset: 0,
+          yOffset: 0,
+          collapsed: false,
+          options: {
+            showLabel: false,
+            collapsible: false,
+            showOpenAll: false,
+            railPlacement: "right",
+            columnCount: 4,
+          },
+        },
+      ],
+      items: [],
+    });
+
+    const section = await db.query.sections.findFirst({
+      where: eq(sections.id, sectionId),
+    });
+
+    expect(SuperJSON.parse(section?.options ?? "")).toEqual({
+      showLabel: false,
+      collapsible: false,
+      showOpenAll: false,
+      railPlacement: "right",
+      columnCount: 4,
+    });
+  });
   it("should add item when present in input", async () => {
     const spy = vi.spyOn(boardAccess, "throwIfActionForbiddenAsync");
     const db = createDb();
@@ -1328,12 +1419,16 @@ const createExistingLayout = (id: string) => ({
   id,
   name: "Base",
   columnCount: 10,
+  leftGutterColumnCount: 0,
+  rightGutterColumnCount: 0,
   breakpoint: 0,
 });
 const createNewLayout = (columnCount: number) => ({
   id: createId(),
   name: "New layout",
   columnCount,
+  leftGutterColumnCount: 0,
+  rightGutterColumnCount: 0,
   breakpoint: 1400,
 });
 describe("saveLayouts should save layout changes", () => {
@@ -1445,6 +1540,59 @@ describe("saveLayouts should save layout changes", () => {
     });
     await expectLayoutForDynamicSectionAsync(db, assignments.inRoot.f, layoutId, assignments.inDynamicSection);
   });
+  test("should reserve gutter columns and return gutter contents to the canvas when disabled", async () => {
+    const db = createDb();
+    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
+    const { boardId, layoutId, sectionId, itemId } = await createFullBoardAsync(db, "gutters");
+
+    await db
+      .update(itemLayouts)
+      .set({
+        xOffset: 9,
+      })
+      .where(and(eq(itemLayouts.itemId, itemId), eq(itemLayouts.layoutId, layoutId)));
+
+    await caller.saveLayouts({
+      id: boardId,
+      layouts: [
+        {
+          ...createExistingLayout(layoutId),
+          leftGutterColumnCount: 2,
+        },
+      ],
+    });
+
+    const enabledLayout = expectToBeDefined(await db.query.layouts.findFirst({ where: eq(layouts.id, layoutId) }));
+    expect(enabledLayout.leftGutterColumnCount).toBe(2);
+    const leftRoot = expectToBeDefined(
+      await db.query.sections.findFirst({
+        where: and(eq(sections.boardId, boardId), eq(sections.kind, "empty"), eq(sections.xOffset, -1)),
+      }),
+    );
+    const reflowedMainItem = expectToBeDefined(
+      await db.query.itemLayouts.findFirst({
+        where: and(eq(itemLayouts.itemId, itemId), eq(itemLayouts.layoutId, layoutId)),
+      }),
+    );
+    expect(reflowedMainItem.xOffset + reflowedMainItem.width).toBeLessThanOrEqual(8);
+
+    const gutterItemId = await addItemAsync(db, {
+      boardId,
+      layoutId,
+      sectionId: leftRoot.id,
+    });
+    await caller.saveLayouts({
+      id: boardId,
+      layouts: [createExistingLayout(layoutId)],
+    });
+
+    const returnedItem = expectToBeDefined(
+      await db.query.itemLayouts.findFirst({
+        where: and(eq(itemLayouts.itemId, gutterItemId), eq(itemLayouts.layoutId, layoutId)),
+      }),
+    );
+    expect(returnedItem.sectionId).toBe(sectionId);
+  });
   test("should remove layout when not present in input", async () => {
     // Arrange
     const db = createDb();

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

@@ -0,0 +1,96 @@
+import { stringify } from "superjson";
+import { describe, expect, it } from "vitest";
+
+import type { Session } from "@homarr/auth";
+import { createId } from "@homarr/common";
+import { eq } from "@homarr/db";
+import { boards, sectionCollapseStates, sections, users } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+
+import { sectionRouter } from "../section/section-router";
+
+const userId = createId();
+const session = {
+  user: {
+    id: userId,
+    permissions: [],
+    colorScheme: "light",
+  },
+  expires: new Date().toISOString(),
+} satisfies Session;
+
+const createCallerAsync = async () => {
+  const db = createDb();
+  const boardId = createId();
+
+  await db.insert(users).values({ id: userId });
+  await db.insert(boards).values({
+    id: boardId,
+    name: createId(),
+    creatorId: userId,
+  });
+
+  return {
+    boardId,
+    db,
+    caller: sectionRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session,
+    }),
+  };
+};
+
+describe("changeCollapsed", () => {
+  it("preserves collapse support for legacy categories", async () => {
+    const { boardId, caller, db } = await createCallerAsync();
+    const sectionId = createId();
+    await db.insert(sections).values({
+      id: sectionId,
+      boardId,
+      kind: "category",
+      name: "Media",
+      xOffset: 0,
+      yOffset: 0,
+    });
+
+    await caller.changeCollapsed({ sectionId, collapsed: true });
+
+    const state = await db.query.sectionCollapseStates.findFirst({
+      where: eq(sectionCollapseStates.sectionId, sectionId),
+    });
+    expect(state?.collapsed).toBe(true);
+  });
+
+  it("creates and updates collapse state for an enabled dynamic section", async () => {
+    const { boardId, caller, db } = await createCallerAsync();
+    const sectionId = createId();
+    await db.insert(sections).values({
+      id: sectionId,
+      boardId,
+      kind: "dynamic",
+      options: stringify({ collapsible: true }),
+    });
+
+    await caller.changeCollapsed({ sectionId, collapsed: true });
+    await caller.changeCollapsed({ sectionId, collapsed: false });
+
+    const states = await db.query.sectionCollapseStates.findMany({
+      where: eq(sectionCollapseStates.sectionId, sectionId),
+    });
+    expect(states).toHaveLength(1);
+    expect(states[0]?.collapsed).toBe(false);
+  });
+
+  it("rejects a dynamic section when collapsing is disabled", async () => {
+    const { boardId, caller, db } = await createCallerAsync();
+    const sectionId = createId();
+    await db.insert(sections).values({
+      id: sectionId,
+      boardId,
+      kind: "dynamic",
+    });
+
+    await expect(caller.changeCollapsed({ sectionId, collapsed: true })).rejects.toThrow("Section cannot be collapsed");
+  });
+});

packages/auth/permissions/integration-provider.tsx

@@ -20,32 +20,27 @@ export const IntegrationProvider = ({ integrations, children }: PropsWithChildre
   return <IntegrationContext.Provider value={{ integrations }}>{children}</IntegrationContext.Provider>;
 };
 
-export const useIntegrationsWithUseAccess = () => {
+const useIntegrationContext = () => {
   const context = useContext(IntegrationContext);
 
   if (!context) {
-    throw new Error("useIntegrationsWithUseAccess must be used within an IntegrationProvider");
+    throw new Error("Integration hooks must be used within an IntegrationProvider");
   }
 
-  return context.integrations.filter((integration) => integration.permissions.hasUseAccess);
+  return context;
 };
 
+export const useIntegrations = () => useIntegrationContext().integrations;
+
+export const useIntegrationsWithUseAccess = () =>
+  useIntegrationContext().integrations.filter((integration) => integration.permissions.hasUseAccess);
+
 export const useIntegrationsWithInteractAccess = () => {
-  const context = useContext(IntegrationContext);
-
-  if (!context) {
-    throw new Error("useIntegrationsWithInteractAccess must be used within an IntegrationProvider");
-  }
-
+  const context = useIntegrationContext();
   return context.integrations.filter((integration) => integration.permissions.hasInteractAccess);
 };
 
 export const useIntegrationsWithFullAccess = () => {
-  const context = useContext(IntegrationContext);
-
-  if (!context) {
-    throw new Error("useIntegrationsWithFullAccess must be used within an IntegrationProvider");
-  }
-
+  const context = useIntegrationContext();
   return context.integrations.filter((integration) => integration.permissions.hasFullAccess);
 };

packages/boards/package.json

@@ -13,6 +13,7 @@
   },
   "exports": {
     "./context": "./src/context.tsx",
+    "./layout-selection": "./src/layout-selection.ts",
     "./updater": "./src/updater.ts",
     "./edit-mode": "./src/edit-mode.tsx"
   },

packages/boards/src/context.tsx

@@ -1,25 +1,66 @@
 "use client";
 
 import type { PropsWithChildren } from "react";
-import { createContext, useCallback, useContext, useEffect, useState } from "react";
+import { createContext, useContext, useEffect, useSyncExternalStore } from "react";
 import { usePathname } from "next/navigation";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 
+import { boardViewportWidthCookieName, getLayoutIdForViewportWidth } from "./layout-selection";
 import { updateBoardName } from "./updater";
 
 const BoardContext = createContext<{
   board: RouterOutputs["board"]["getBoardByName"];
+  currentLayout: string;
+  initialViewportWidth: number;
 } | null>(null);
 
+const subscribeToViewport = (onStoreChange: () => void) => {
+  if (typeof window === "undefined") return () => undefined;
+
+  let animationFrame = 0;
+  const handleResize = () => {
+    if (animationFrame !== 0) return;
+    animationFrame = window.requestAnimationFrame(() => {
+      animationFrame = 0;
+      persistViewportWidth(getViewportWidth());
+      onStoreChange();
+    });
+  };
+  window.addEventListener("resize", handleResize);
+
+  return () => {
+    window.removeEventListener("resize", handleResize);
+    window.cancelAnimationFrame(animationFrame);
+  };
+};
+
 export const BoardProvider = ({
   children,
   initialBoard,
+  initialLayoutId,
+  initialViewportWidth,
 }: PropsWithChildren<{
   initialBoard: RouterOutputs["board"]["getBoardByName"];
+  initialLayoutId: string;
+  initialViewportWidth: number;
 }>) => {
-  const { data } = clientApi.board.getBoardByName.useQuery({ name: initialBoard.name }, { initialData: initialBoard });
+  const { data } = clientApi.board.getBoardByName.useQuery(
+    { name: initialBoard.name },
+    {
+      initialData: initialBoard,
+      // The route already fetched this board, so keep it fresh long enough to
+      // avoid an immediate duplicate request while still surfacing remote edits
+      // when a user later returns to the board.
+      staleTime: 30_000,
+    },
+  );
+  const currentLayout = useSyncExternalStore(
+    subscribeToViewport,
+    () => getCurrentLayout(data),
+    () => initialLayoutId,
+  );
 
   // Update the board name so it can be used within updateBoard method
   updateBoardName(initialBoard.name);
@@ -35,10 +76,15 @@ export const BoardProvider = ({
     };
   }, [pathname, utils, initialBoard.name]);
 
+  useEffect(() => {
+    persistViewportWidth(getViewportWidth());
+  }, []);
   return (
     <BoardContext.Provider
       value={{
         board: data,
+        currentLayout,
+        initialViewportWidth,
       }}
     >
       {children}
@@ -63,34 +109,28 @@ export const useOptionalBoard = () => {
 };
 
 export const getCurrentLayout = (board: RouterOutputs["board"]["getBoardByName"]) => {
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  if (typeof window === "undefined") return board.layouts.at(0)!.id;
-
-  const sortedLayouts = board.layouts.toSorted((layoutA, layoutB) => layoutB.breakpoint - layoutA.breakpoint);
-
-  // Fallback to smallest if none exists with breakpoint smaller than window width
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  return sortedLayouts.find((layout) => layout.breakpoint <= window.innerWidth)?.id ?? sortedLayouts.at(0)!.id;
+  const viewportWidth = typeof window === "undefined" ? 0 : getViewportWidth();
+  return getLayoutIdForViewportWidth(board.layouts, viewportWidth);
 };
 
 export const useCurrentLayout = () => {
-  const board = useRequiredBoard();
-  const [currentLayout, setCurrentLayout] = useState(getCurrentLayout(board));
+  const context = useContext(BoardContext);
 
-  const onResize = useCallback(() => {
-    setCurrentLayout(getCurrentLayout(board));
-  }, [board]);
+  if (!context) {
+    throw new Error("Board is required");
+  }
 
-  useEffect(() => {
-    if (typeof window === "undefined") return;
-    window.addEventListener("resize", onResize);
+  return context.currentLayout;
+};
 
-    return () => {
-      window.removeEventListener("resize", onResize);
-    };
-  }, [onResize]);
+export const useInitialViewportWidth = () => {
+  const context = useContext(BoardContext);
 
-  return currentLayout;
+  if (!context) {
+    throw new Error("Board is required");
+  }
+
+  return context.initialViewportWidth;
 };
 
 export const getBoardLayouts = (board: RouterOutputs["board"]["getBoardByName"]) =>
@@ -101,3 +141,9 @@ export const useLayouts = () => {
 
   return getBoardLayouts(board);
 };
+
+const persistViewportWidth = (viewportWidth: number) => {
+  document.cookie = `${boardViewportWidthCookieName}=${Math.round(viewportWidth)}; Path=/; Max-Age=31536000; SameSite=Lax`;
+};
+
+const getViewportWidth = () => document.documentElement.clientWidth || window.innerWidth;

packages/boards/src/layout-selection.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "vitest";
+
+import { getLayoutIdForViewportWidth } from "./layout-selection";
+
+const layouts = [
+  { id: "mobile", breakpoint: 0 },
+  { id: "tablet", breakpoint: 768 },
+  { id: "desktop", breakpoint: 1280 },
+];
+
+describe("getLayoutIdForViewportWidth", () => {
+  test.each([
+    [390, "mobile"],
+    [768, "tablet"],
+    [1279, "tablet"],
+    [1920, "desktop"],
+  ])("selects the responsive layout for %ipx", (width, expected) => {
+    expect(getLayoutIdForViewportWidth(layouts, width)).toBe(expected);
+  });
+
+  test("falls back to the smallest layout for invalid widths", () => {
+    expect(getLayoutIdForViewportWidth(layouts, Number.NaN)).toBe("mobile");
+  });
+
+  test("rejects boards without layouts", () => {
+    expect(() => getLayoutIdForViewportWidth([], 1280)).toThrow("Expected the board to contain a layout");
+  });
+});