feat(workshop): retain daily assistant quotas

* feat(custom-widgets): improve authoring workbench

* fix(custom-widgets): address review and CI

* refactor(custom-widgets): satisfy architecture checks

* fix(custom-widgets): isolate workbench typing updates

* fix(custom-widgets): harden workbench state

.agents/skills/homarr-local-harness/SKILL.md

@@ -1,60 +0,0 @@
----
-name: homarr-local-harness
-description: Build and inspect a writable Docker demo harness from the current Homarr checkout when validating a local branch in a browser.
----
-
-# Homarr Local Harness
-
-Use this skill when a Homarr change needs a real production image and browser validation. Work from the repository root and keep the harness name Docker-safe, such as `feature-board`.
-
-## Set up the harness
-
-Run the TypeScript operations CLI; this workflow does not use the interactive developer TUI:
-
-```sh
-pnpm cli harness setup feature-board
-```
-
-`setup` builds the current checkout as `homarr:feature-board`, replaces the named harness container, and starts it with a persistent data volume. It enables demo mode, mock integrations, and writable demo mutations by default:
-
-- `DEMO_MODE=true`
-- `DEMO_READ_ONLY=false`
-- `UNSAFE_ENABLE_MOCK_INTEGRATION=true`
-
-Pass repeatable environment overrides when the feature needs them:
-
-```sh
-pnpm cli harness setup feature-board \
-  --env WORKSHOP_WEB_URL=https://example.test \
-  --env FEATURE_FLAG=true
-```
-
-Use `pnpm cli harness build <name>` when only the image is needed, and `pnpm cli harness run <name>` to start an already-built image. `--port <number>` pins a host port; otherwise Docker assigns one.
-
-Always use the URL printed by the command. If the output is no longer available, query it directly:
-
-```sh
-pnpm cli harness port feature-board
-```
-
-Do not assume port `7575`; the container listens on `7575`, but the host port is dynamic by default.
-
-## Browser validation
-
-Open the printed URL with the environment's `browser-harness` tool. In this workspace, the `agent-browser` CLI is the supported browser automation fallback. Load its current workflow before invoking it:
-
-```sh
-agent-browser skills get core
-```
-
-Navigate to the exact harness URL, wait for the app to become usable, exercise the changed flow, and capture screenshots or other browser evidence. Keep browser state in a named session when the workflow needs login persistence. Report the exact URL, viewport/session used, and screenshot paths; a Docker process or HTTP health response alone is not browser acceptance.
-
-## Cleanup
-
-Stop the named container when finished:
-
-```sh
-pnpm cli harness stop feature-board
-```
-
-Stopping keeps the data volume so the same harness can be restarted. A later `setup` rebuilds the image and replaces only the container. Preserve unrelated containers, images, volumes, and working-tree changes.

.agents/skills/homarr-local-harness/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Homarr Local Harness"
-  short_description: "Build and browse a writable local Homarr branch harness"
-  default_prompt: "Use $homarr-local-harness to set up a writable Homarr harness for the current branch and validate it in the browser."

.oxlintrc.json

@@ -30,6 +30,26 @@
   "options": {
     "reportUnusedDisableDirectives": "off"
   },
+  "overrides": [
+    {
+      "files": ["apps/nextjs/src/**/*.ts", "apps/nextjs/src/**/*.tsx"],
+      "excludeFiles": ["**/*.spec.ts", "**/*.spec.tsx"],
+      "rules": {
+        "eslint/no-restricted-imports": [
+          "error",
+          {
+            "paths": [
+              {
+                "name": "@homarr/widgets",
+                "allowTypeImports": true,
+                "message": "Import a narrow @homarr/widgets export to preserve widget lazy loading."
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ],
   "ignorePatterns": [
     "**/*.config.js",
     "**/*.config.mjs",

apps/docs/docs/advanced/keyboard-shortcuts/index.mdx

@@ -8,13 +8,28 @@ Homarr has the following keyboard shortcuts:
 
 | Shortcut                                            | Description                                                                                                                |
 | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `MOD` + `K`                                         | Opens the search bar                                                                                                       |
+| `MOD` + `K`                                         | Opens search, including local apps, boards, integrations, pages, commands, and preferences                                 |
+| `MOD` + `P`                                         | Opens app search                                                                                                           |
+| `MOD` + `/`                                         | Opens Homarr Assistant inside search                                                                                       |
+| `MOD` + `Shift` + `/` (`MOD` + `?`)                 | Opens preference search                                                                                                    |
+| `Shift` + `A`                                       | Opens the full Homarr Assistant                                                                                            |
 | `MOD` + `J`                                         | Toggles Dark Mode                                                                                                          |
 | `MOD` + `E`                                         | Toggles Edit Mode                                                                                                          |
 | Hold `Shift` for 500 ms over a supported widget     | Opens its temporary advanced view                                                                                          |
 | Hold `Shift` + `Ctrl`/`Cmd` over a supported widget | Keeps its advanced view open until it is closed                                                                            |
 | `Esc`                                               | Stops keyboard tile editing, cancels an active pointer or touch move/resize, or closes an open advanced view or board menu |
 
+## Search and commands
+
+Search is designed as the fastest route to Homarr. Start typing after `MOD` + `K` to find local apps, boards,
+integrations, pages, commands, and preferences without entering a separate mode first. Local Homarr results appear
+before configured search-engine actions and Assistant fallbacks. Commands include opening the board switcher without
+leaving the keyboard. Type `!` to enter Web mode when you want to browse configured engine shortcuts or discover
+DuckDuckGo bangs; bang discovery is excluded from ordinary Search results.
+
+Use the dedicated shortcuts above to start in apps, Assistant, or preferences. Inside search, choose a mode to narrow
+the same query when needed. Media request search is available only when a supported Seerr integration is configured.
+
 ## Widget advanced view
 
 Supported widgets open a temporary advanced view when you hold `Shift` over them for 500 ms. Hold `Shift` plus `Ctrl`

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

@@ -198,9 +198,13 @@ In the modal you can edit the app that you want to display:
 
 <figure>
   <img src={editItemCurrent} alt="Current Edit item modal for an App tile" style={{ maxWidth: "620px" }} />
-  <figcaption>Use the Edit item modal to choose the app and configure how its tile is displayed.</figcaption>
+  <figcaption>
+    The Edit item workspace previews option changes as you configure the tile. Save changes to apply them to the board.
+  </figcaption>
 </figure>
 
+When adding a widget, set its initial grid width and height directly in the preview. These size controls are only shown before the widget is added.
+
 As soon as you save your changes, the tile on the board will refresh and display your app.
 Resize from any visible edge or corner handle. For a Container, activate its top-left grip before using its resize handles.
 Press and hold a handle, move the pointer, and release it when the tile has the size you want.

apps/docs/docs/management/assistant.mdx

@@ -38,7 +38,7 @@ host gateway address.
 ## Use it
 
 - Select **Assistant** in the user menu or press `Shift + A`.
-- Ask from `Cmd/Ctrl + K`.
+- Press `Cmd/Ctrl + /` to ask from search, or use `Cmd/Ctrl + K` and choose the Assistant fallback.
 - Add the [Assistant widget](../widgets/assistant) to a board.
 
 The assistant can work with boards, apps, integrations, widgets, Custom Widgets, and connected services. Use `@` to

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

@@ -27,9 +27,10 @@ opening it. Containers include their visible widgets and app icons instead of ap
 
 Names of boards must be unique because this will be used in the URL to load the desired board.
 
-Press `Shift+C`, or select **Switch board** from the user menu, to open the board switcher. It shows
-structural previews of the other boards you can access. Start typing to filter by name, use the arrow keys to move
-through the results, and press `Enter` to open the selected board.
+Press `Shift+C`, or select **Switch board** from the user menu, to open the board switcher. It shows structural
+previews of every board you can access, with your current board at the end. Home-board markers and creator avatars
+match the board management view. Use the search field at the top, or simply start typing, to filter by name. Use the
+arrow keys to move through the results and press `Enter` to open the selected board.
 
 ## Create a new board
 

apps/docs/docs/management/custom-widgets/authoring.mdx

@@ -41,6 +41,10 @@ needs attention.
 4. Write responsive JSX using `data`, `status`, `options`, and temporary `inputs`.
 5. Test and preview, inspect Data and the redacted request journal, then save.
 
+While focus is inside a code editor, use `Ctrl+Z`/`Cmd+Z` to undo and `Ctrl+Shift+Z`/`Cmd+Shift+Z` to redo. The toolbar exposes the same actions. This history is local to that editor; builder-wide undo is not yet available.
+
+Changing the definition, instance options, or credentials invalidates the previous preview and its live-action session. Run **Test and preview** again before treating the data or result as current. Automatic load queries are queued with up to four running at once so larger previews stay within the request limit.
+
 <CanonicalCustomWidgetExample
   id="named-widget-requests"
   label="Named queries and actions"

apps/docs/docs/management/search-engines/index.mdx

@@ -7,9 +7,13 @@ tags:
 
 # Search Engines
 
-Using the search engines, terms can be quickly searched simply by opening the search bar at the top or using the keyboard shortcut `CTRL + K`.
+Using the search engines, terms can be quickly searched simply by opening the search bar at the top or using the keyboard shortcut `MOD + K`.
 The management page provides a searchable list with the shortcut, URL template, source, and available row actions for each engine.
 
+The default **Search** mode lists every configured search engine as a fallback action for the current query. To discover
+engines by shortcut, switch to **Web** with `!`. DuckDuckGo bang discovery is intentionally limited to Web mode so an
+ordinary search term never expands into similarly named bang providers.
+
 You can add any search engine that has a search URL that accepts a search term as a parameter.
 
 ## Create search engine
@@ -26,6 +30,8 @@ The name can be chosen freely. It will be displayed in the search box popover.
 
 Prefix that is used to choose the search engine in the popover using the keyboard.
 It is recommended that this value is kept short (for example `g` for Google and `e` for Ecosia).
+Type `!` in Spotlight to browse these shortcuts and, when DuckDuckGo bangs are enabled in preferences, discover
+additional bang providers.
 
 ### Configuration
 

apps/docs/docs/widgets/bookmarks/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Bookmarks"
-description: "Displays multiple app links"
+description: "Keeps useful links together"
 hide_title: true
 ---
 
@@ -13,11 +13,12 @@ import { bookmarksWidget } from ".";
 
 <WidgetHeader widget={bookmarksWidget} categories={["Links", "Apps"]} />
 
-The bookmarks widget allows you to display multiple links in a single widget.
-Select one or more existing Apps directly in the widget settings; these bookmarks keep a reference to the App, so changes to its name, icon, or URL are reflected automatically.
-For links that do not need an App, add their URLs under **Custom links** instead.
-Its normal view adapts each configured layout to the available width and height: lower-priority hostnames are hidden before names or icons, and larger collections scroll instead of crushing cards.
-Advanced view shows every bookmark as a roomy card with its full title, hostname, icon, and complete description regardless of the compact layout and visibility choices.
+The bookmarks widget keeps direct URLs and Homarr Apps in one ordered list.
+Paste a URL and press Enter, paste several comma-separated or one-per-line URLs, or search for an existing App.
+URLs do not need an App record; Homarr uses the site's favicon and falls back to a link icon when it cannot load one.
+Bookmarks selected from Apps continue to use the App name, URL, icon, and description.
+
+**Adaptive** layout is the practical default: it changes between icons, compact rows, and tiles as the widget changes shape. Every compact item exposes its destination on hover, while advanced view expands items into descriptive cards.
 
 ### Screenshots
 

apps/docs/docs/widgets/bookmarks/index.ts

@@ -4,7 +4,7 @@ import { IconBookmark } from "@tabler/icons-react";
 export const bookmarksWidget: WidgetDefinition = {
   icon: IconBookmark,
   name: "Bookmarks",
-  description: "Displays multiple app links",
+  description: "Keeps useful links together",
   path: "../../widgets/bookmarks",
   configuration: {
     items: [
@@ -16,9 +16,21 @@ export const bookmarksWidget: WidgetDefinition = {
       },
       {
         name: "Layout",
-        description: "Layout in which the bookmarks are displayed.",
-        values: { type: "select", options: ["Vertical", "Horizontal", "Grid", "Grid horizontal"] },
-        defaultValue: "Vertical",
+        description: "How bookmarks use the available widget space.",
+        values: { type: "select", options: ["Adaptive", "Vertical", "Horizontal", "Grid", "Compact grid", "Icons"] },
+        defaultValue: "Adaptive",
+      },
+      {
+        name: "Appearance",
+        description: "Card surface style.",
+        values: { type: "select", options: ["Soft", "Filled", "Outline", "Plain"] },
+        defaultValue: "Soft",
+      },
+      {
+        name: "Card spacing",
+        description: "Space between bookmark cards.",
+        values: { type: "select", options: ["Extra small", "Small", "Medium", "Large", "Extra large"] },
+        defaultValue: "Extra small",
       },
       {
         name: "Hide title",
@@ -46,16 +58,10 @@ export const bookmarksWidget: WidgetDefinition = {
       },
       {
         name: "Bookmarks",
-        description: "List of bookmarks to display in the widget.",
-        values: "Select one or more Apps directly, then order them as you like.",
+        description: "URLs and existing Apps shown by the widget.",
+        values: "Paste one or many URLs, or find an existing App. Drag to reorder.",
         defaultValue: "No bookmarks selected",
       },
-      {
-        name: "Custom links",
-        description: "URLs to display without first creating an App.",
-        values: "List of URLs.",
-        defaultValue: "No custom links",
-      },
     ],
   },
 };

apps/docs/docs/workshop/homarr-provider.mdx

@@ -38,8 +38,10 @@ its server; changing the browser clock cannot bypass them.
 Workshop keeps the OpenRouter API key on its server. Homarr and the browser never receive it.
 
 Prompts, attachments, tools, and tool results pass through Workshop and OpenRouter. Workshop does not retain this
-content or the responses. It stores only the user, UTC day, and counters needed to enforce allowances. OpenRouter is
-configured for zero data retention with data collection disabled. Homarr does not use this content to train models.
+content or the responses. It stores only the user, UTC day, and counters needed to enforce allowances. Each active day
+has a separate quota record so Workshop operators can inspect per-user daily usage without seeing request content.
+OpenRouter is configured for zero data retention with data collection disabled. Homarr does not use this content to
+train models.
 
 We would rather become millionaires in a more ethical manner.
 

apps/docs/docs/workshop/operator.mdx

@@ -72,6 +72,9 @@ per-request telemetry. It accepts only uploaded image data, conservatively bound
 allows at most two concurrent requests per user and 100 across the service. Keep an OpenRouter account-level credit
 limit as the final monetary backstop because request quotas are not dollar accounting.
 
+PocketBase stores one `assistant_quotas` record per user and active UTC day. Workshop superusers can use this private
+collection for a daily usage breakdown; regular users cannot list or view its records.
+
 Run `pnpm test:workshop` to test authentication, streaming, UTC reset, atomic per-user and global quota enforcement,
 failed-request accounting, identity attribution, server-selected model routing, function tools, input and output
 controls, privacy routing, spoofing resistance, absence of request logs, and migration rollback.

apps/nextjs/package.json

@@ -76,6 +76,7 @@
     "@tanstack/react-query": "catalog:",
     "@tanstack/react-query-devtools": "catalog:",
     "@tanstack/react-query-next-experimental": "catalog:",
+    "@tanstack/react-query-persist-client": "catalog:",
     "@trpc/client": "catalog:",
     "@trpc/next": "catalog:",
     "@trpc/react-query": "catalog:",

apps/nextjs/public/images/demo-dashboard-background.svg

@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" role="img" aria-labelledby="title description">
+  <title id="title">Abstract homelab network</title>
+  <description id="description">A dark indigo field with subtle connected nodes and cyan signal paths.</description>
+  <defs>
+    <radialGradient id="base" cx="50%" cy="40%" r="80%">
+      <stop offset="0" stop-color="#172047"/>
+      <stop offset="0.48" stop-color="#0b1028"/>
+      <stop offset="1" stop-color="#060814"/>
+    </radialGradient>
+    <radialGradient id="indigoGlow">
+      <stop offset="0" stop-color="#748ffc" stop-opacity="0.32"/>
+      <stop offset="1" stop-color="#748ffc" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="cyanGlow">
+      <stop offset="0" stop-color="#3bc9db" stop-opacity="0.22"/>
+      <stop offset="1" stop-color="#3bc9db" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="signal" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#748ffc" stop-opacity="0.05"/>
+      <stop offset="0.5" stop-color="#748ffc" stop-opacity="0.34"/>
+      <stop offset="1" stop-color="#3bc9db" stop-opacity="0.05"/>
+    </linearGradient>
+    <filter id="blur">
+      <feGaussianBlur stdDeviation="55"/>
+    </filter>
+  </defs>
+  <rect width="1920" height="1080" fill="url(#base)"/>
+  <ellipse cx="330" cy="90" rx="560" ry="430" fill="url(#indigoGlow)" filter="url(#blur)"/>
+  <ellipse cx="1680" cy="940" rx="620" ry="400" fill="url(#cyanGlow)" filter="url(#blur)"/>
+  <g fill="none" stroke="url(#signal)" stroke-width="1.5">
+    <path d="M-80 825C240 570 475 760 720 510s470-165 650-330 330-85 630-250"/>
+    <path d="M-120 1010C220 740 470 920 780 660s520-105 700-270 300-125 560-180"/>
+    <path d="M110 40c180 190 350 220 545 130s390-55 520 80 320 155 620 60" opacity=".45"/>
+  </g>
+  <g fill="#9aa8ff" opacity=".48">
+    <circle cx="248" cy="660" r="3"/>
+    <circle cx="718" cy="511" r="4"/>
+    <circle cx="1118" cy="287" r="3"/>
+    <circle cx="1450" cy="110" r="4"/>
+  </g>
+  <g fill="#5ee0ee" opacity=".42">
+    <circle cx="435" cy="850" r="3"/>
+    <circle cx="908" cy="604" r="4"/>
+    <circle cx="1350" cy="510" r="3"/>
+    <circle cx="1715" cy="285" r="4"/>
+  </g>
+  <g fill="none" stroke="#aeb8ff" stroke-opacity=".055">
+    <circle cx="330" cy="90" r="260"/>
+    <circle cx="330" cy="90" r="345"/>
+    <circle cx="1680" cy="940" r="250"/>
+    <circle cx="1680" cy="940" r="335"/>
+  </g>
+</svg>

apps/nextjs/src/app/[locale]/_client-providers/query-persistence.spec.ts

@@ -0,0 +1,350 @@
+import { dehydrate, QueryClient } from "@tanstack/react-query";
+import type { PersistedClient } from "@tanstack/react-query-persist-client";
+import { persistQueryClientRestore } from "@tanstack/react-query-persist-client";
+import { parse, stringify } from "superjson";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import {
+  createSessionQueryPersister,
+  getQueryPersistenceStorageKey,
+  queryPersistenceBuster,
+  queryPersistenceMaxDataBytes,
+  shouldPersistDashboardQuery,
+} from "./query-persistence";
+
+const createSuccessfulQuery = (queryKey: readonly unknown[], data: unknown, updatedAt = Date.now()) => {
+  const queryClient = new QueryClient();
+  queryClient.setQueryData(queryKey, data, { updatedAt });
+  const query = queryClient.getQueryCache().find({ queryKey });
+  if (!query) throw new Error("Expected query to be present");
+  return { query, queryClient };
+};
+
+const createMemoryStorage = (): Storage => {
+  const values = new Map<string, string>();
+  return {
+    get length() {
+      return values.size;
+    },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => Array.from(values.keys())[index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  };
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  window.sessionStorage.clear();
+});
+
+describe("widget query persistence", () => {
+  test("persists successful dashboard data but not unrelated, ping, pending, or oversized queries", () => {
+    const widget = createSuccessfulQuery([["widget", "weather", "getWeather"], { type: "query" }], { temp: 21 });
+    const supporting = createSuccessfulQuery([["app", "byIds"], { type: "query" }], [{ id: "app-1" }]);
+    const unrelated = createSuccessfulQuery([["board", "getBoardByName"], { type: "query" }], { name: "Home" });
+    const ping = createSuccessfulQuery([["widget", "app", "ping"], { type: "query" }], { status: "online" });
+    const oversized = createSuccessfulQuery([["widget", "example"], { type: "query" }], {
+      value: "x".repeat(queryPersistenceMaxDataBytes + 1),
+    });
+    const pendingClient = new QueryClient();
+    const pending = pendingClient.getQueryCache().build(pendingClient, {
+      queryKey: [["widget", "calendar", "findAllEvents"], { type: "query" }],
+      queryFn: () => Promise.resolve([]),
+    });
+
+    expect(shouldPersistDashboardQuery(widget.query)).toBe(true);
+    expect(shouldPersistDashboardQuery(supporting.query)).toBe(true);
+    expect(shouldPersistDashboardQuery(unrelated.query)).toBe(false);
+    expect(shouldPersistDashboardQuery(ping.query)).toBe(false);
+    expect(shouldPersistDashboardQuery(oversized.query)).toBe(false);
+    expect(shouldPersistDashboardQuery(pending)).toBe(false);
+  });
+
+  test("uses stable, isolated storage keys for anonymous and authenticated scopes", () => {
+    expect(getQueryPersistenceStorageKey("user-a")).toBe(getQueryPersistenceStorageKey("user-a"));
+    expect(getQueryPersistenceStorageKey("user-a")).not.toBe(getQueryPersistenceStorageKey("user-b"));
+    expect(getQueryPersistenceStorageKey(null)).not.toBe(getQueryPersistenceStorageKey("user-a"));
+
+    const userAKey = getQueryPersistenceStorageKey("user-a");
+    window.sessionStorage.setItem(userAKey, "a");
+    createSessionQueryPersister("user-a").removeClient();
+    expect(window.sessionStorage.getItem(userAKey)).toBeNull();
+  });
+
+  test("evicts every other scope so signing out cannot leave data behind", () => {
+    const userAKey = getQueryPersistenceStorageKey("user-a");
+    const anonymousKey = getQueryPersistenceStorageKey(null);
+    window.sessionStorage.setItem(userAKey, "a");
+    window.sessionStorage.setItem(anonymousKey, "anonymous");
+    window.sessionStorage.setItem("unrelated", "kept");
+
+    createSessionQueryPersister("user-b");
+
+    expect(window.sessionStorage.getItem(userAKey)).toBeNull();
+    expect(window.sessionStorage.getItem(anonymousKey)).toBeNull();
+    expect(window.sessionStorage.getItem("unrelated")).toBe("kept");
+  });
+
+  test("never restores another session scope", async () => {
+    const queryKey = [["widget", "weather", "getWeather"], { type: "query" }] as const;
+    const { queryClient } = createSuccessfulQuery(queryKey, { temp: 21 });
+    const userAPersister = createSessionQueryPersister("user-a");
+    userAPersister.persistClient({
+      timestamp: Date.now(),
+      buster: queryPersistenceBuster,
+      clientState: dehydrate(queryClient),
+    });
+    userAPersister.flush();
+    expect((await userAPersister.restoreClient())?.clientState.queries).toHaveLength(1);
+
+    expect(createSessionQueryPersister("user-b").restoreClient()).toBeUndefined();
+  });
+
+  test("stops persisting once the provider tears the cache down", async () => {
+    const storage = createMemoryStorage();
+    const persister = createSessionQueryPersister("user-a", storage);
+    const { queryClient } = createSuccessfulQuery([["widget", "weather", "getWeather"], { type: "query" }], {
+      temp: 21,
+    });
+
+    persister.persistClient({
+      timestamp: Date.now(),
+      buster: queryPersistenceBuster,
+      clientState: dehydrate(queryClient),
+    });
+    persister.flush();
+    persister.stop();
+
+    persister.persistClient({
+      timestamp: Date.now(),
+      buster: queryPersistenceBuster,
+      clientState: { mutations: [], queries: [] },
+    });
+    persister.flush();
+
+    expect((await persister.restoreClient())?.clientState.queries).toHaveLength(1);
+  });
+
+  test("removes the cache instead of storing an empty one", () => {
+    const scope = "user-a";
+    const key = getQueryPersistenceStorageKey(scope);
+    const persister = createSessionQueryPersister(scope);
+    window.sessionStorage.setItem(key, "stale");
+
+    persister.persistClient({
+      timestamp: Date.now(),
+      buster: queryPersistenceBuster,
+      clientState: { mutations: [], queries: [] },
+    });
+    persister.flush();
+
+    expect(window.sessionStorage.getItem(key)).toBeNull();
+  });
+
+  test("round-trips SuperJSON data, strips refresh errors, and removes corrupted storage", async () => {
+    vi.useFakeTimers();
+    const scope = "user-a";
+    const key = getQueryPersistenceStorageKey(scope);
+    const persister = createSessionQueryPersister(scope);
+    const { query, queryClient } = createSuccessfulQuery([["widget", "calendar", "findAllEvents"], { type: "query" }], {
+      startsAt: new Date("2026-08-22T12:00:00.000Z"),
+    });
+    query.setState({ ...query.state, error: new Error("private refresh error"), status: "error" });
+    expect(shouldPersistDashboardQuery(query)).toBe(true);
+    const persistedClient: PersistedClient = {
+      timestamp: Date.now(),
+      buster: queryPersistenceBuster,
+      clientState: dehydrate(queryClient, { shouldDehydrateQuery: shouldPersistDashboardQuery }),
+    };
+
+    persister.persistClient(persistedClient);
+    persister.flush();
+    const restored = await persister.restoreClient();
+    const restoredData = restored?.clientState.queries[0]?.state.data as { startsAt?: Date } | undefined;
+    expect(restoredData?.startsAt).toEqual(new Date("2026-08-22T12:00:00.000Z"));
+    expect(restored?.clientState.queries[0]?.state.status).toBe("success");
+    expect(restored?.clientState.queries[0]?.state.error).toBeNull();
+    expect(restored?.clientState.queries[0]?.state.isInvalidated).toBe(true);
+    expect(window.sessionStorage.getItem(key)).not.toContain("private refresh error");
+
+    window.sessionStorage.setItem(key, "not-valid-superjson");
+    expect(persister.restoreClient()).toBeUndefined();
+    expect(window.sessionStorage.getItem(key)).toBeNull();
+  });
+
+  test("sanitizes structurally valid but unsafe stored state before hydration", async () => {
+    const scope = "user-a";
+    const key = getQueryPersistenceStorageKey(scope);
+    const { queryClient } = createSuccessfulQuery(
+      [["widget", "calendar", "findAllEvents"], { type: "query" }],
+      [{ title: "safe" }],
+    );
+    const validQuery = dehydrate(queryClient).queries[0];
+    if (!validQuery) throw new Error("Expected a dehydrated query");
+
+    window.sessionStorage.setItem(
+      key,
+      stringify({
+        timestamp: Date.now(),
+        buster: queryPersistenceBuster,
+        clientState: {
+          mutations: [{ state: { status: "pending" } }],
+          queries: [
+            {
+              ...validQuery,
+              state: {
+                ...validQuery.state,
+                error: new Error("private refresh error"),
+                fetchStatus: "fetching",
+                status: "error",
+              },
+            },
+            {
+              ...validQuery,
+              queryHash: "unrelated",
+              queryKey: [["board", "getBoardByName"], { type: "query" }],
+            },
+            { queryHash: "malformed", queryKey: [["widget", "weather"]], state: null },
+            {
+              ...validQuery,
+              queryHash: "missing-timestamp",
+              state: { ...validQuery.state, dataUpdatedAt: undefined },
+            },
+          ],
+        },
+      }),
+    );
+
+    const restored = await createSessionQueryPersister(scope).restoreClient();
+    expect(restored?.clientState.mutations).toEqual([]);
+    expect(restored?.clientState.queries).toHaveLength(1);
+    expect(restored?.clientState.queries[0]?.state.status).toBe("success");
+    expect(restored?.clientState.queries[0]?.state.fetchStatus).toBe("idle");
+    expect(restored?.clientState.queries[0]?.state.error).toBeNull();
+  });
+
+  test.each([
+    ["expired", 1, queryPersistenceBuster],
+    ["different buster", new Date("2026-08-22T12:00:00.000Z").getTime(), "old-version"],
+    ["future timestamp", new Date("2026-08-22T12:00:00.000Z").getTime() + 1, queryPersistenceBuster],
+  ])("discards %s cache entries", async (_case, timestamp, storedBuster) => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-08-22T12:00:00.000Z"));
+    const scope = "user-a";
+    const persister = createSessionQueryPersister(scope);
+    const { queryClient } = createSuccessfulQuery([["widget", "weather", "getWeather"], { type: "query" }], {
+      temp: 21,
+    });
+    persister.persistClient({ timestamp, buster: storedBuster, clientState: dehydrate(queryClient) });
+    persister.flush();
+
+    const restoredClient = new QueryClient();
+    await persistQueryClientRestore({
+      queryClient: restoredClient,
+      persister,
+      maxAge: 5 * 60 * 1_000,
+      buster: queryPersistenceBuster,
+    });
+
+    expect(restoredClient.getQueryData([["widget", "weather", "getWeather"], { type: "query" }])).toBeUndefined();
+    expect(window.sessionStorage.getItem(getQueryPersistenceStorageKey(scope))).toBeNull();
+  });
+
+  test("quota retry writes the cache after evicting the oldest query", async () => {
+    const old = createSuccessfulQuery([["widget", "old"], { type: "query" }], "old", 1);
+    const recent = createSuccessfulQuery([["widget", "recent"], { type: "query" }], "recent", 2);
+    const storage = createMemoryStorage();
+    const setItem = storage.setItem.bind(storage);
+    const setItemSpy = vi.spyOn(storage, "setItem").mockImplementation((key, value) => {
+      const client = parse<PersistedClient>(value);
+      if (client.clientState.queries.length > 1) throw new DOMException("quota", "QuotaExceededError");
+      setItem(key, value);
+    });
+    const persistedClient: PersistedClient = {
+      timestamp: Date.now(),
+      buster: queryPersistenceBuster,
+      clientState: {
+        mutations: [],
+        queries: [...dehydrate(old.queryClient).queries, ...dehydrate(recent.queryClient).queries],
+      },
+    };
+    const persister = createSessionQueryPersister("user-a", storage);
+
+    persister.persistClient(persistedClient);
+    persister.flush();
+
+    expect(setItemSpy).toHaveBeenCalledTimes(2);
+    const restored = await persister.restoreClient();
+    expect(restored?.clientState.queries).toHaveLength(1);
+    expect(restored?.clientState.queries[0]?.queryKey).toEqual([["widget", "recent"], { type: "query" }]);
+  });
+
+  test("coalesces pending writes and can synchronously flush the latest cache before reload", async () => {
+    vi.useFakeTimers();
+    const storage = createMemoryStorage();
+    const setItem = vi.spyOn(storage, "setItem");
+    const queryKey = [["widget", "weather", "getWeather"], { type: "query" }] as const;
+    const first = createSuccessfulQuery(queryKey, { temp: 20 }, 1);
+    const latest = createSuccessfulQuery(queryKey, { temp: 21 }, 2);
+    const persister = createSessionQueryPersister("user-a", storage);
+
+    persister.persistClient({
+      timestamp: Date.now(),
+      buster: queryPersistenceBuster,
+      clientState: dehydrate(first.queryClient),
+    });
+    persister.persistClient({
+      timestamp: Date.now(),
+      buster: queryPersistenceBuster,
+      clientState: dehydrate(latest.queryClient),
+    });
+
+    expect(setItem).not.toHaveBeenCalled();
+    persister.flush();
+    expect(setItem).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(setItem).toHaveBeenCalledOnce();
+
+    const restored = await persister.restoreClient();
+    expect(restored?.clientState.queries[0]?.state.data).toEqual({ temp: 21 });
+  });
+
+  test("treats blocked storage operations as an empty cache", async () => {
+    const blockedStorage = {
+      getItem: () => {
+        throw new DOMException("blocked", "SecurityError");
+      },
+      removeItem: () => {
+        throw new DOMException("blocked", "SecurityError");
+      },
+      setItem: () => {
+        throw new DOMException("blocked", "SecurityError");
+      },
+    } as unknown as Storage;
+    const persister = createSessionQueryPersister("blocked", blockedStorage);
+    const { queryClient } = createSuccessfulQuery([["widget", "weather"], { type: "query" }], { temp: 21 });
+
+    expect(persister.restoreClient()).toBeUndefined();
+    expect(() => {
+      persister.persistClient({
+        timestamp: Date.now(),
+        buster: queryPersistenceBuster,
+        clientState: dehydrate(queryClient),
+      });
+      persister.flush();
+    }).not.toThrow();
+    expect(() => persister.removeClient()).not.toThrow();
+  });
+
+  test("treats an unavailable session storage getter as an empty cache", async () => {
+    vi.spyOn(window, "sessionStorage", "get").mockImplementation(() => {
+      throw new DOMException("blocked", "SecurityError");
+    });
+
+    expect(() => createSessionQueryPersister("blocked-getter")).not.toThrow();
+    expect(createSessionQueryPersister("blocked-getter").restoreClient()).toBeUndefined();
+  });
+});

apps/nextjs/src/app/[locale]/_client-providers/query-persistence.ts

@@ -0,0 +1,226 @@
+import type { QueryKey } from "@tanstack/react-query";
+import type { PersistedClient, Persister } from "@tanstack/react-query-persist-client";
+import { removeOldestQuery } from "@tanstack/react-query-persist-client";
+import { parse, stringify } from "superjson";
+
+import { isWidgetDataQueryKey, queryCacheDefaultGcTimeMs } from "@homarr/api/query-cache";
+
+export const queryPersistenceMaxAgeMs = queryCacheDefaultGcTimeMs;
+export const queryPersistenceMaxDataBytes = 256 * 1024;
+export const queryPersistenceBuster = "v2-session-superjson";
+
+const queryPersistenceStoragePrefix = "homarr:widget-query-cache";
+
+export const getQueryPersistenceStorageKey = (scope: string | null) =>
+  `${queryPersistenceStoragePrefix}:${encodeURIComponent(scope ?? "anonymous")}`;
+
+interface PersistableQuery {
+  queryKey: QueryKey;
+  state: {
+    data: unknown;
+    dataUpdatedAt: number;
+  };
+}
+
+export type SessionQueryPersister = Persister & { flush: () => void; stop: () => void };
+
+const textEncoder = new TextEncoder();
+const budgetVerdictCache = new WeakMap<object, boolean>();
+
+const measureFitsBudget = (data: unknown) => {
+  try {
+    return textEncoder.encode(stringify(data)).byteLength <= queryPersistenceMaxDataBytes;
+  } catch {
+    return false;
+  }
+};
+
+const fitsStorageBudget = (data: unknown) => {
+  if (typeof data !== "object" || data === null) return measureFitsBudget(data);
+
+  const cached = budgetVerdictCache.get(data);
+  if (cached !== undefined) return cached;
+
+  const verdict = measureFitsBudget(data);
+  budgetVerdictCache.set(data, verdict);
+  return verdict;
+};
+
+const holdsDashboardData = (query: PersistableQuery) =>
+  query.state.data !== undefined &&
+  Number.isFinite(query.state.dataUpdatedAt) &&
+  query.state.dataUpdatedAt > 0 &&
+  isWidgetDataQueryKey(query.queryKey);
+
+export const shouldPersistDashboardQuery = (query: PersistableQuery) =>
+  holdsDashboardData(query) && fitsStorageBudget(query.state.data);
+
+type DehydratedQuery = PersistedClient["clientState"]["queries"][number];
+
+const sanitizePersistedQuery = (query: DehydratedQuery): DehydratedQuery => ({
+  ...query,
+  state: {
+    ...query.state,
+    error: null,
+    errorUpdateCount: 0,
+    errorUpdatedAt: 0,
+    fetchFailureCount: 0,
+    fetchFailureReason: null,
+    fetchStatus: "idle",
+    isInvalidated: true,
+    status: "success",
+  },
+});
+
+const sanitizePersistedClient = (client: PersistedClient): PersistedClient => ({
+  ...client,
+  clientState: {
+    mutations: [],
+    queries: client.clientState.queries.map(sanitizePersistedQuery),
+  },
+});
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isRestorableQuery = (value: unknown): value is DehydratedQuery => {
+  if (!isRecord(value) || typeof value.queryHash !== "string" || !Array.isArray(value.queryKey)) return false;
+  if (!isRecord(value.state) || typeof value.state.status !== "string") return false;
+
+  return holdsDashboardData(value as unknown as PersistableQuery);
+};
+
+const sanitizeRestoredClient = (value: unknown): PersistedClient | undefined => {
+  if (!isRecord(value) || !Number.isFinite(value.timestamp) || typeof value.buster !== "string") return undefined;
+  if (!isRecord(value.clientState) || !Array.isArray(value.clientState.queries)) return undefined;
+
+  return {
+    timestamp: value.timestamp as number,
+    buster: value.buster,
+    clientState: {
+      mutations: [],
+      queries: value.clientState.queries.filter(isRestorableQuery).map(sanitizePersistedQuery),
+    },
+  };
+};
+
+const getSessionStorage = (): Storage | undefined => {
+  if (typeof window === "undefined") return undefined;
+
+  try {
+    return window.sessionStorage;
+  } catch {
+    return undefined;
+  }
+};
+
+const removeStorageItem = (storage: Storage | undefined, key: string) => {
+  try {
+    storage?.removeItem(key);
+  } catch {
+    return undefined;
+  }
+};
+
+const removeForeignScopes = (storage: Storage | undefined, activeKey: string) => {
+  if (!storage) return;
+
+  try {
+    const foreignKeys: string[] = [];
+    for (let index = 0; index < storage.length; index += 1) {
+      const storedKey = storage.key(index);
+      if (storedKey === null || storedKey === activeKey) continue;
+      if (storedKey.startsWith(`${queryPersistenceStoragePrefix}:`)) foreignKeys.push(storedKey);
+    }
+
+    for (const foreignKey of foreignKeys) storage.removeItem(foreignKey);
+  } catch {
+    return undefined;
+  }
+};
+
+export const createSessionQueryPersister = (
+  scope: string | null,
+  storage: Storage | undefined = getSessionStorage(),
+): SessionQueryPersister => {
+  const key = getQueryPersistenceStorageKey(scope);
+  removeForeignScopes(storage, key);
+  let pendingClient: PersistedClient | undefined;
+  let persistTimer: ReturnType<typeof setTimeout> | undefined;
+  let stopped = false;
+
+  const persistNow = (client: PersistedClient) => {
+    if (!storage) return;
+    let candidate: PersistedClient | undefined = sanitizePersistedClient(client);
+    let errorCount = 0;
+
+    if (candidate.clientState.queries.length === 0) {
+      removeStorageItem(storage, key);
+      return;
+    }
+
+    while (candidate) {
+      try {
+        storage.setItem(key, stringify(candidate));
+        return;
+      } catch (error) {
+        errorCount += 1;
+        candidate = removeOldestQuery({
+          persistedClient: candidate,
+          error: error instanceof Error ? error : new Error("Failed to persist the widget query cache"),
+          errorCount,
+        });
+      }
+    }
+  };
+
+  const clearPersistTimer = () => {
+    if (persistTimer === undefined) return;
+    clearTimeout(persistTimer);
+    persistTimer = undefined;
+  };
+
+  const flush = () => {
+    clearPersistTimer();
+    const client = pendingClient;
+    pendingClient = undefined;
+    if (client) persistNow(client);
+  };
+
+  return {
+    persistClient(client) {
+      if (!storage || stopped) return;
+      pendingClient = client;
+      if (persistTimer !== undefined) return;
+      persistTimer = setTimeout(flush, 0);
+    },
+    restoreClient() {
+      try {
+        const storedValue = storage?.getItem(key);
+        if (!storedValue) return undefined;
+
+        const client = sanitizeRestoredClient(parse<unknown>(storedValue));
+        if (!client || client.timestamp > Date.now() || client.clientState.queries.length === 0) {
+          removeStorageItem(storage, key);
+          return undefined;
+        }
+
+        return client;
+      } catch {
+        removeStorageItem(storage, key);
+        return undefined;
+      }
+    },
+    removeClient() {
+      clearPersistTimer();
+      pendingClient = undefined;
+      removeStorageItem(storage, key);
+    },
+    flush,
+    stop() {
+      stopped = true;
+      clearPersistTimer();
+      pendingClient = undefined;
+    },
+  };
+};

apps/nextjs/src/app/[locale]/_client-providers/trpc.tsx

@@ -1,10 +1,11 @@
 "use client";
 
 import type { PropsWithChildren } from "react";
-import { useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import dynamic from "next/dynamic";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { QueryClient } from "@tanstack/react-query";
 import { ReactQueryStreamedHydration } from "@tanstack/react-query-next-experimental";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
 import {
   createWSClient,
   httpBatchStreamLink,
@@ -35,6 +36,13 @@ import { showWarningNotification } from "@homarr/notifications";
 import { widgetQueryRefetchIntervals } from "@homarr/widgets/refetch-intervals";
 
 import { getSessionQueryScope, SessionQueryScopeGuard } from "./session-query-scope";
+import {
+  createSessionQueryPersister,
+  queryPersistenceBuster,
+  queryPersistenceMaxAgeMs,
+  shouldPersistDashboardQuery,
+} from "./query-persistence";
+import type { SessionQueryPersister } from "./query-persistence";
 import { createQueryRetry } from "./query-retry";
 
 const DevelopmentTools =
@@ -67,21 +75,29 @@ export function TRPCReactProvider({ children }: PropsWithChildren) {
   const { data: session } = useSession();
   const sessionQueryScope = getSessionQueryScope(session);
   const [initialSessionQueryScope] = useState(() => sessionQueryScope);
+  const [queryPersister] = useState(() => createSessionQueryPersister(initialSessionQueryScope));
+  const handleScopeChange = useCallback(() => {
+    void queryPersister.removeClient();
+    reloadPage();
+  }, [queryPersister]);
 
   return (
     <SessionQueryScopeGuard
       initialScope={initialSessionQueryScope}
       currentScope={sessionQueryScope}
-      onScopeChange={reloadPage}
+      onScopeChange={handleScopeChange}
     >
-      <ScopedTRPCReactProvider>{children}</ScopedTRPCReactProvider>
+      <ScopedTRPCReactProvider queryPersister={queryPersister}>{children}</ScopedTRPCReactProvider>
     </SessionQueryScopeGuard>
   );
 }
 
 const reloadPage = () => window.location.reload();
 
-const ScopedTRPCReactProvider = ({ children }: PropsWithChildren) => {
+const ScopedTRPCReactProvider = ({
+  children,
+  queryPersister,
+}: PropsWithChildren<{ queryPersister: SessionQueryPersister }>) => {
   const wsClient = useMemo(
     () =>
       createWSClient({
@@ -136,6 +152,15 @@ const ScopedTRPCReactProvider = ({ children }: PropsWithChildren) => {
     return client;
   });
 
+  useEffect(() => {
+    const flush = () => queryPersister.flush();
+    window.addEventListener("pagehide", flush);
+    return () => {
+      window.removeEventListener("pagehide", flush);
+      flush();
+      queryPersister.stop();
+    };
+  }, [queryPersister]);
   useEffect(() => () => queryClient.clear(), [queryClient]);
 
   const trpcClient = useMemo(() => {
@@ -186,10 +211,18 @@ const ScopedTRPCReactProvider = ({ children }: PropsWithChildren) => {
 
   return (
     <clientApi.Provider client={trpcClient} queryClient={queryClient}>
-      <QueryClientProvider client={queryClient}>
+      <PersistQueryClientProvider
+        client={queryClient}
+        persistOptions={{
+          persister: queryPersister,
+          maxAge: queryPersistenceMaxAgeMs,
+          buster: queryPersistenceBuster,
+          dehydrateOptions: { shouldDehydrateQuery: shouldPersistDashboardQuery },
+        }}
+      >
         <ReactQueryStreamedHydration transformer={superjson}>{children}</ReactQueryStreamedHydration>
         {process.env.NODE_ENV === "development" && <DevelopmentTools />}
-      </QueryClientProvider>
+      </PersistQueryClientProvider>
     </clientApi.Provider>
   );
 };

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

@@ -19,35 +19,11 @@
   align-self: start;
   box-sizing: border-box;
   height: var(--board-gutter-viewport-height);
-  padding-top: 24px;
-  margin-top: -24px;
   overflow: clip;
 }
 
 .gutter[data-board-editing="true"] {
-  outline: 1px dashed var(--mantine-color-default-border);
-  outline-offset: -1px;
+  outline: 0.0625rem solid var(--mantine-color-default-border);
+  outline-offset: -0.0625rem;
   border-radius: var(--mantine-radius-md);
 }
-
-.gutter[data-board-editing="true"]::before {
-  position: sticky;
-  top: 0;
-  inset-inline-start: 0;
-  z-index: 2;
-  display: block;
-  width: fit-content;
-  height: 24px;
-  padding-inline: var(--mantine-spacing-xs);
-  margin-top: -24px;
-  overflow: hidden;
-  font-size: var(--mantine-font-size-xs);
-  line-height: 24px;
-  color: var(--mantine-color-dimmed);
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  pointer-events: none;
-  content: attr(aria-label);
-  background: color-mix(in srgb, var(--mantine-color-body) 88%, transparent);
-  border-radius: var(--mantine-radius-sm);
-}

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

@@ -1,5 +1,6 @@
 "use client";
 
+import type { PropsWithChildren } from "react";
 import { Box, Paper, Stack, Text } from "@mantine/core";
 import { IconBulb } from "@tabler/icons-react";
 
@@ -10,18 +11,20 @@ import { useI18n } from "@homarr/translation/client";
 import { FloatingTip } from "@homarr/ui";
 
 import { BoardAdvancedFocusProvider } from "~/components/board/advanced-focus/context";
+import { BoardAppsSpotlightRegistrar } from "~/components/board/board-apps-spotlight-registrar";
 import { BoardEmptyState } from "~/components/board/board-empty-state";
 import { BoardSetupChecklist } from "~/components/board/board-setup-checklist";
 import {
   getBoardLaneColumnCount,
   getInitialBoardLogicalHeight,
-  getLogicalTrackSize,
+  getLogicalGridSize,
   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 { GridEditorRegistryProvider } from "~/components/board/sections/grid/grid-editor-registry";
 import { BoardGridPortalHost } from "~/components/board/sections/grid/grid-portal-host";
 import { BoardSectionCollapseProvider } from "~/components/board/sections/section-collapse";
 import { BoardBackgroundVideo } from "~/components/layout/background";
@@ -31,6 +34,12 @@ import classes from "./_client.module.css";
 
 const APP_SHELL_INLINE_PADDING = 32;
 
+const BoardSelectionGridProvider = ({ children }: PropsWithChildren) => (
+  <GridEditorRegistryProvider>
+    <BoardSelectionProvider>{children}</BoardSelectionProvider>
+  </GridEditorRegistryProvider>
+);
+
 export const ClientBoard = () => {
   const board = useRequiredBoard();
   const t = useI18n("board.landmark");
@@ -53,24 +62,25 @@ export const ClientBoard = () => {
   const rightColumnCount = getBoardLaneColumnCount(currentLayout, "right");
   const laneWidths = [leftColumnCount, mainColumnCount, rightColumnCount]
     .filter((columnCount) => columnCount > 0)
-    .map(getLogicalTrackSize);
+    .map(getLogicalGridSize);
   const logicalWidth =
     laneWidths.reduce((total, width) => total + width, 0) + (laneWidths.length - 1) * LOGICAL_GRID_GAP;
   const initialLogicalHeight = getInitialBoardLogicalHeight(board, currentLayoutId);
   const representativeWidth = layoutOverrideId ? getRepresentativeLayoutWidth(currentLayout, board.layouts) : null;
   const initialAvailableWidth = Math.max(1, (representativeWidth ?? initialViewportWidth) - APP_SHELL_INLINE_PADDING);
   const gridTemplateColumns = [
-    leftColumnCount > 0 ? `${getLogicalTrackSize(leftColumnCount)}px` : null,
-    `${getLogicalTrackSize(mainColumnCount)}px`,
-    rightColumnCount > 0 ? `${getLogicalTrackSize(rightColumnCount)}px` : null,
+    leftColumnCount > 0 ? `${getLogicalGridSize(leftColumnCount)}px` : null,
+    `${getLogicalGridSize(mainColumnCount)}px`,
+    rightColumnCount > 0 ? `${getLogicalGridSize(rightColumnCount)}px` : null,
   ]
     .filter((value) => value !== null)
     .join(" ");
 
   const content = (
-    <BoardSelectionProvider>
+    <BoardSelectionGridProvider>
       <BoardAdvancedFocusProvider>
         <Box h="100%" pos="relative" data-homarr-dev-benchmark-board>
+          <BoardAppsSpotlightRegistrar />
           <BoardBackgroundVideo />
           <BoardEmptyState />
           <BoardSetupChecklist />
@@ -144,7 +154,7 @@ export const ClientBoard = () => {
           </FloatingTip>
         </Box>
       </BoardAdvancedFocusProvider>
-    </BoardSelectionProvider>
+    </BoardSelectionGridProvider>
   );
 
   if (representativeWidth === null) return content;

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

@@ -111,9 +111,6 @@ export const LayoutSettingsContent = ({ board, form, isSaving, saveSettingsAsync
 
   const nextBreakpoint = getNextCustomBreakpoint(form.values.layouts);
   const baseLayout = form.values.layouts.find((layout) => layout.role === "base");
-  const sortedLayouts = form.values.layouts
-    .map((layout, index) => ({ layout, index }))
-    .toSorted((entryA, entryB) => entryA.layout.breakpoint - entryB.layout.breakpoint);
 
   return (
     <SectionCard title={tBoard("setting.section.layout.title")}>
@@ -129,25 +126,25 @@ export const LayoutSettingsContent = ({ board, form, isSaving, saveSettingsAsync
             disabled={nextBreakpoint === null || !baseLayout}
             onClick={() => {
               if (nextBreakpoint === null || !baseLayout) return;
-              form.setFieldValue("layouts", [
-                ...form.values.layouts,
-                {
-                  id: createId(),
-                  name: tBoard("setting.section.layout.custom.defaultName"),
-                  columnCount: baseLayout.columnCount,
-                  leftGutterColumnCount: baseLayout.leftGutterColumnCount,
-                  rightGutterColumnCount: baseLayout.rightGutterColumnCount,
-                  breakpoint: nextBreakpoint,
-                  role: "custom",
-                },
-              ]);
+              const newLayout: FormValues["layouts"][number] = {
+                id: createId(),
+                name: tBoard("setting.section.layout.custom.defaultName"),
+                columnCount: baseLayout.columnCount,
+                leftGutterColumnCount: baseLayout.leftGutterColumnCount,
+                rightGutterColumnCount: baseLayout.rightGutterColumnCount,
+                breakpoint: nextBreakpoint,
+                role: "custom",
+              };
+              let insertionIndex = form.values.layouts.findIndex((layout) => layout.breakpoint > nextBreakpoint);
+              if (insertionIndex === -1) insertionIndex = form.values.layouts.length;
+              form.insertListItem("layouts", newLayout, insertionIndex);
             }}
           >
             {tBoard("setting.section.layout.responsive.action.add")}
           </Button>
         </Group>
 
-        {sortedLayouts.map(({ layout, index }) => {
+        {form.values.layouts.map((layout, index) => {
           const persistedLayout = board.layouts.find((candidate) => candidate.id === layout.id);
           const sourceLayout = persistedLayout ?? board.layouts.find((candidate) => candidate.role === "base");
           const customBreakpoints = form.values.layouts

apps/nextjs/src/app/[locale]/manage/custom-widgets/_code-editor.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useMemo } from "react";
 import type { ComponentProps } from "react";
 
 import { CustomWidgetCodeEditor } from "@homarr/custom-widgets/workbench";
@@ -12,39 +13,38 @@ type CodeEditorProps = Omit<SharedEditorProps, "messages">;
 export function CodeEditor(props: CodeEditorProps) {
   const t = useI18n("customWidget.editor");
   const tCommon = useI18n("common");
-  return (
-    <CustomWidgetCodeEditor
-      {...props}
-      messages={{
-        languageJsx: invariantTechnicalLabels.jsx,
-        languageJson: invariantTechnicalLabels.json,
-        undo: tCommon("action.undo"),
-        redo: t("action.redo"),
-        components: t("action.components"),
-        componentSearch: t("componentReference.search"),
-        componentEmpty: t("componentReference.empty"),
-        componentCount: (count) => t("componentReference.count", { count }),
-        insertStarter: t("action.insertStarter"),
-        format: t("action.format"),
-        copy: tCommon("action.copy"),
-        copied: t("action.copied"),
-        schema: t("action.schema"),
-        schemaTab: invariantTechnicalLabels.jsonSchema,
-        minimalTab: t("reference.minimal"),
-        fullTab: t("reference.full"),
-        errors: (count) => t("status.errors", { count }),
-        warnings: (count) => t("status.warnings", { count }),
-        ready: t("status.ready"),
-        position: (cursor) => t("status.position", cursor),
-        characters: (count, limit) =>
-          limit ? t("status.charactersWithLimit", { count, limit }) : t("status.characters", { count }),
-        diagnosticsTitle: t("diagnostics.title"),
-        diagnostic: (diagnostic) =>
-          `${diagnostic.line ? `${t("diagnostics.line", { line: diagnostic.line })}: ` : ""}${t(
-            `diagnostics.${diagnostic.code}` as never,
-            { value: diagnostic.value ?? "" } as never,
-          )}`,
-      }}
-    />
+  const messages = useMemo<SharedEditorProps["messages"]>(
+    () => ({
+      languageJsx: invariantTechnicalLabels.jsx,
+      languageJson: invariantTechnicalLabels.json,
+      undo: tCommon("action.undo"),
+      redo: t("action.redo"),
+      components: t("action.components"),
+      componentSearch: t("componentReference.search"),
+      componentEmpty: t("componentReference.empty"),
+      componentCount: (count) => t("componentReference.count", { count }),
+      insertStarter: t("action.insertStarter"),
+      format: t("action.format"),
+      copy: tCommon("action.copy"),
+      copied: t("action.copied"),
+      schema: t("action.schema"),
+      schemaTab: invariantTechnicalLabels.jsonSchema,
+      minimalTab: t("reference.minimal"),
+      fullTab: t("reference.full"),
+      errors: (count) => t("status.errors", { count }),
+      warnings: (count) => t("status.warnings", { count }),
+      ready: t("status.ready"),
+      position: (cursor) => t("status.position", cursor),
+      characters: (count, limit) =>
+        limit ? t("status.charactersWithLimit", { count, limit }) : t("status.characters", { count }),
+      diagnosticsTitle: t("diagnostics.title"),
+      diagnostic: (diagnostic) =>
+        `${diagnostic.line ? `${t("diagnostics.line", { line: diagnostic.line })}: ` : ""}${t(
+          `diagnostics.${diagnostic.code}` as never,
+          { value: diagnostic.value ?? "" } as never,
+        )}`,
+    }),
+    [t, tCommon],
   );
+  return <CustomWidgetCodeEditor {...props} messages={messages} />;
 }

apps/nextjs/src/app/[locale]/manage/custom-widgets/_copy-ai-prompt-button.tsx

@@ -3,37 +3,70 @@
 import { ActionIcon, Group, Tooltip } from "@mantine/core";
 import { IconCopy, IconRobot } from "@tabler/icons-react";
 
-import { buildCustomWidgetAiPrompt } from "@homarr/custom-widgets/authoring-prompt";
+import { buildCustomWidgetAiPrompt, buildCustomWidgetAssistantPrompt } from "@homarr/custom-widgets/authoring-prompt";
+import type { CustomWidgetAiDiagnostic, CustomWidgetAiDraft } from "@homarr/custom-widgets/authoring-prompt";
 import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
 import { useI18n } from "@homarr/translation/client";
 
 import { useOptionalHomarrAssistant } from "~/components/assistant/assistant-context";
 
-interface CopyAiPromptButtonProps {
+interface CopyAiPromptButtonBaseProps {
   rawResponse?: string | null;
-  currentConfig?: Record<string, unknown> | null;
   request?: string | null;
   documentationUrl?: string | null;
 }
 
+type CopyAiPromptButtonProps = CopyAiPromptButtonBaseProps &
+  ({ draft: CustomWidgetAiDraft; getDraft?: never } | { draft?: never; getDraft(): CustomWidgetAiDraft }) &
+  (
+    | { diagnostics: readonly CustomWidgetAiDiagnostic[]; getDiagnostics?: never }
+    | { diagnostics?: never; getDiagnostics(): readonly CustomWidgetAiDiagnostic[] }
+  );
+
 export const CopyAiPromptButton = ({
   rawResponse,
-  currentConfig,
+  draft,
+  getDraft,
+  diagnostics,
+  getDiagnostics,
   request,
   documentationUrl,
 }: CopyAiPromptButtonProps) => {
   const t = useI18n("customWidget");
   const assistant = useOptionalHomarrAssistant();
-  const prompt = () => buildCustomWidgetAiPrompt(undefined, rawResponse, currentConfig, request, documentationUrl);
+
+  const readDraft = () => {
+    if (getDraft) return getDraft();
+    return draft;
+  };
+  const readDiagnostics = () => {
+    if (getDiagnostics) return getDiagnostics();
+    return diagnostics;
+  };
 
   const handleAssistant = () => {
-    if (!assistant?.enabled || !assistant.sendPrompt(prompt())) return;
+    const prompt = buildCustomWidgetAssistantPrompt(
+      undefined,
+      rawResponse,
+      readDraft(),
+      request,
+      documentationUrl,
+      readDiagnostics(),
+    );
+    if (!assistant?.enabled || !assistant.sendPrompt(prompt)) return;
     showSuccessNotification({ title: t("action.aiPrompt"), message: t("notification.aiPromptSent") });
   };
 
   const handleCopy = async () => {
     try {
-      const value = prompt();
+      const value = buildCustomWidgetAiPrompt(
+        undefined,
+        rawResponse,
+        readDraft(),
+        request,
+        documentationUrl,
+        readDiagnostics(),
+      );
       await navigator.clipboard.writeText(value);
       showSuccessNotification({
         title: t("action.copyAiPrompt"),

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-advanced-manifest.tsx

@@ -1,27 +1,38 @@
 "use client";
 
 import { useEffect, useState } from "react";
-import { Accordion } from "@mantine/core";
 
 import { customWidgetDefinitionSchema } from "@homarr/custom-widgets/core";
 import { useI18n } from "@homarr/translation/client";
 
 import { CodeEditor } from "./_code-editor";
+import { useDeferredCustomWidgetFormDocumentValues } from "./_custom-widget-form-state";
 import { applyDefinition, parseJson } from "./_custom-widget-form-utils";
 import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
+import { LazyOnceAccordion } from "./_lazy-once-accordion";
 
 export function CustomWidgetAdvancedManifest({ form }: { form: CustomWidgetWorkbenchForm }) {
   const t = useI18n("customWidget.workbench.builder");
+  return (
+    <LazyOnceAccordion label={t("advancedManifest")}>
+      <CustomWidgetManifestEditor form={form} />
+    </LazyOnceAccordion>
+  );
+}
+
+function CustomWidgetManifestEditor({ form }: { form: CustomWidgetWorkbenchForm }) {
+  const t = useI18n("customWidget.workbench.builder");
+  const values = useDeferredCustomWidgetFormDocumentValues();
   const serialized = JSON.stringify(
     {
       $schema: "homarr-custom-widget-v2",
-      name: form.values.name,
-      ...(form.values.description ? { description: form.values.description } : {}),
-      ...(form.values.iconUrl ? { iconUrl: form.values.iconUrl } : {}),
-      sources: parseJson(form.values.sources),
-      requests: parseJson(form.values.requests),
-      options: parseJson(form.values.options),
-      template: form.values.template,
+      name: values.name,
+      ...(values.description ? { description: values.description } : {}),
+      ...(values.iconUrl ? { iconUrl: values.iconUrl } : {}),
+      sources: parseJson(values.sources),
+      requests: parseJson(values.requests),
+      options: parseJson(values.options),
+      template: values.template,
     },
     null,
     2,
@@ -30,33 +41,26 @@ export function CustomWidgetAdvancedManifest({ form }: { form: CustomWidgetWorkb
   const [error, setError] = useState<string>();
   useEffect(() => setDraft(serialized), [serialized]);
   return (
-    <Accordion variant="contained">
-      <Accordion.Item value="manifest">
-        <Accordion.Control>{t("advancedManifest")}</Accordion.Control>
-        <Accordion.Panel>
-          <CodeEditor
-            id="raw-widget-manifest"
-            label={t("manifestFilename")}
-            language="json"
-            value={draft}
-            error={error}
-            onChange={(next) => {
-              setDraft(next);
-              try {
-                const parsed = customWidgetDefinitionSchema.safeParse(JSON.parse(next) as unknown);
-                if (!parsed.success) {
-                  setError(parsed.error.issues[0]?.message ?? t("invalidWidget"));
-                  return;
-                }
-                setError(undefined);
-                applyDefinition(form, parsed.data);
-              } catch (cause) {
-                setError(cause instanceof Error ? cause.message : t("invalidJson"));
-              }
-            }}
-          />
-        </Accordion.Panel>
-      </Accordion.Item>
-    </Accordion>
+    <CodeEditor
+      id="raw-widget-manifest"
+      label={t("manifestFilename")}
+      language="json"
+      value={draft}
+      error={error}
+      onChange={(next) => {
+        setDraft(next);
+        try {
+          const parsed = customWidgetDefinitionSchema.safeParse(JSON.parse(next) as unknown);
+          if (!parsed.success) {
+            setError(parsed.error.issues[0]?.message ?? t("invalidWidget"));
+            return;
+          }
+          setError(undefined);
+          applyDefinition(form, parsed.data);
+        } catch (cause) {
+          setError(cause instanceof Error ? cause.message : t("invalidJson"));
+        }
+      }}
+    />
   );
 }

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-ai-card.tsx

@@ -3,13 +3,14 @@
 import { Accordion, Button, Group, Stack, Text, TextInput, Textarea } from "@mantine/core";
 import { IconClipboard, IconSparkles } from "@tabler/icons-react";
 
-import type { HomarrCustomWidgetV2 } from "@homarr/custom-widgets/core";
+import type { CustomWidgetAiDiagnostic, CustomWidgetAiDraft } from "@homarr/custom-widgets/authoring-prompt";
 import { useI18n } from "@homarr/translation/client";
 
 import { CopyAiPromptButton } from "./_copy-ai-prompt-button";
 
 interface AiCardProps {
-  candidate: HomarrCustomWidgetV2 | null;
+  getDraft(): CustomWidgetAiDraft;
+  getDiagnostics(): readonly CustomWidgetAiDiagnostic[];
   request: string;
   onRequestChange(value: string): void;
   documentationUrl: string;
@@ -27,14 +28,15 @@ export function CustomWidgetAiCard(props: AiCardProps) {
             {t("title")}
           </Accordion.Control>
           <CopyAiPromptButton
-            currentConfig={props.candidate}
+            getDraft={props.getDraft}
+            getDiagnostics={props.getDiagnostics}
             request={props.request}
             documentationUrl={props.documentationUrl}
           />
         </Group>
         <Accordion.Panel>
           <Stack gap="sm">
-            <Text size="sm" c="dimmed">
+            <Text size="sm" c="light-dark(var(--mantine-color-gray-7), var(--mantine-color-gray-4))">
               {t("description")}
             </Text>
             <Textarea

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-form-analysis.ts

@@ -2,7 +2,10 @@ import type { CustomWidgetFormValues, EditorDiagnostic } from "@homarr/custom-wi
 
 import { isRecord, parseJson, parseSources } from "./_custom-widget-form-utils";
 
-export function createCustomWidgetCompletions(values: CustomWidgetFormValues, requestIds: string[]) {
+export function createCustomWidgetCompletions(
+  values: Pick<CustomWidgetFormValues, "options" | "sources">,
+  requestIds: string[],
+) {
   const options = parseJson(values.options);
   const optionKeys = Object.keys(isRecord(options) ? options : {});
   return [

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-form-layout.tsx

@@ -1,14 +1,40 @@
 "use client";
 
-import type { ReactNode } from "react";
+import { useEffect, useRef } from "react";
+import type { Dispatch, ReactNode, SetStateAction } from "react";
 import type { Icon } from "@tabler/icons-react";
 import { Button, Card, Group, Stack, Text, ThemeIcon } from "@mantine/core";
-import { IconAlertTriangle, IconCheck, IconPlayerPlay } from "@tabler/icons-react";
+import {
+  IconAlertCircle,
+  IconAlertTriangle,
+  IconApi,
+  IconBraces,
+  IconCheck,
+  IconCode,
+  IconDatabase,
+  IconEye,
+  IconPlayerPlay,
+  IconSettings,
+} from "@tabler/icons-react";
 
+import { getCustomWidgetDefaultOptions } from "@homarr/custom-widgets/core";
 import { useI18n } from "@homarr/translation/client";
 
+import { useCustomWidgetFormDocumentDirty } from "./_custom-widget-form-state";
+import { areCustomWidgetValuesEqual } from "./_custom-widget-value-equality";
+import { useCustomWidgetFormAnalysisField } from "./_use-custom-widget-form-analysis";
+import { useUnsavedChangesGuard } from "./_use-unsaved-changes-guard";
 import classes from "./_custom-widget-form.module.css";
 
+const sectionLinks = [
+  ["general", "section.general", IconSettings],
+  ["sources", "section.sources", IconApi],
+  ["requests", "section.requests", IconDatabase],
+  ["options", "section.options", IconBraces],
+  ["jsx", "section.jsx", IconCode],
+  ["preview", "section.preview", IconEye],
+] as const;
+
 export function EditorSection({
   id,
   title,
@@ -84,3 +110,83 @@ export function SaveActions({
     </Group>
   );
 }
+
+export function CustomWidgetSectionNavigation({
+  onSelect,
+}: {
+  onSelect(section: (typeof sectionLinks)[number][0]): void;
+}) {
+  const t = useI18n("customWidget.workbench");
+  const invalidSections = useCustomWidgetFormAnalysisField("invalidSections");
+  return (
+    <nav className={classes.sectionNav} aria-label={t("sectionNavigation")}>
+      {sectionLinks.map(([id, key, SectionIcon]) => {
+        const invalid = invalidSections.has(id);
+        return (
+          <Button
+            key={id}
+            component="a"
+            href={`#${id}`}
+            onClick={() => onSelect(id)}
+            size="compact-sm"
+            variant="subtle"
+            color={invalid ? "red" : undefined}
+            leftSection={<SectionIcon size={14} />}
+            rightSection={invalid ? <IconAlertCircle size={13} aria-label={t("status.invalid")} /> : undefined}
+          >
+            {t(key)}
+          </Button>
+        );
+      })}
+    </nav>
+  );
+}
+
+export function CustomWidgetSaveActions({
+  mode,
+  savePending,
+  previewPending,
+  onPreview,
+}: {
+  mode: "create" | "edit";
+  savePending: boolean;
+  previewPending: boolean;
+  onPreview(): void;
+}) {
+  const dirty = useCustomWidgetFormDocumentDirty();
+  const candidateValid = useCustomWidgetFormAnalysisField("candidateValid");
+  const hasDiagnostics = useCustomWidgetFormAnalysisField("hasDiagnostics");
+  return (
+    <SaveActions
+      dirty={dirty}
+      savePending={savePending}
+      previewPending={previewPending}
+      invalid={hasDiagnostics || !candidateValid}
+      mode={mode}
+      onPreview={onPreview}
+    />
+  );
+}
+
+export function CustomWidgetUnsavedChangesGuard() {
+  const dirty = useCustomWidgetFormDocumentDirty();
+  useUnsavedChangesGuard(dirty);
+  return null;
+}
+
+export function CustomWidgetOptionsSnapshotSync({
+  setOptionsSnapshot,
+}: {
+  setOptionsSnapshot: Dispatch<SetStateAction<Record<string, unknown>>>;
+}) {
+  const parsedOptions = useCustomWidgetFormAnalysisField("parsedOptions");
+  const lastDefaults = useRef<Record<string, unknown> | null>(null);
+  useEffect(() => {
+    if (!parsedOptions.success) return;
+    const defaults = getCustomWidgetDefaultOptions(parsedOptions.data);
+    if (lastDefaults.current && areCustomWidgetValuesEqual(lastDefaults.current, defaults)) return;
+    lastDefaults.current = defaults;
+    setOptionsSnapshot(defaults);
+  }, [parsedOptions, setOptionsSnapshot]);
+  return null;
+}

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-form-sections.tsx

@@ -0,0 +1,222 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type { Dispatch, SetStateAction } from "react";
+import { TextInput, Textarea } from "@mantine/core";
+import { IconApi, IconBraces, IconCode, IconDatabase, IconSettings } from "@tabler/icons-react";
+
+import type { CustomWidgetAiDiagnostic, CustomWidgetAiDraft } from "@homarr/custom-widgets/authoring-prompt";
+import { IconPicker } from "@homarr/forms-collection";
+import { useI18n } from "@homarr/translation/client";
+
+import { CodeEditor } from "./_code-editor";
+import { CustomWidgetAiCard } from "./_custom-widget-ai-card";
+import { EditorSection } from "./_custom-widget-form-layout";
+import { customWidgetOptionsSchemaReference, customWidgetRequestReference } from "./_custom-widget-form-references";
+import { useCustomWidgetFormDocumentField } from "./_custom-widget-form-state";
+import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
+import { CustomWidgetOptionsEditor } from "./_custom-widget-options-editor";
+import { CustomWidgetPreviewPanel } from "./_custom-widget-preview-panel";
+import type { PreviewState } from "./_custom-widget-preview-panel";
+import { CustomWidgetRequestsEditor } from "./_custom-widget-requests-editor";
+import { CustomWidgetSourcesEditor } from "./_custom-widget-sources-editor";
+import { LazyOnceAccordion } from "./_lazy-once-accordion";
+import { useCustomWidgetFormAnalysisField } from "./_use-custom-widget-form-analysis";
+
+export function CustomWidgetAiSection({
+  getDraft,
+  getDiagnostics,
+  onPaste,
+}: {
+  getDraft(): CustomWidgetAiDraft;
+  getDiagnostics(): readonly CustomWidgetAiDiagnostic[];
+  onPaste(): void;
+}) {
+  const [request, setRequest] = useState("");
+  const [documentationUrl, setDocumentationUrl] = useState("");
+  return (
+    <CustomWidgetAiCard
+      getDraft={getDraft}
+      getDiagnostics={getDiagnostics}
+      request={request}
+      onRequestChange={setRequest}
+      documentationUrl={documentationUrl}
+      onDocumentationUrlChange={setDocumentationUrl}
+      onPaste={onPaste}
+    />
+  );
+}
+
+export function CustomWidgetGeneralSection({
+  form,
+  formRevision,
+  mode,
+}: {
+  form: CustomWidgetWorkbenchForm;
+  formRevision: string;
+  mode: "create" | "edit";
+}) {
+  const t = useI18n("customWidget");
+  const tCommon = useI18n("common");
+  const w = useI18n("customWidget.workbench");
+  const [suggestedIconSearch, setSuggestedIconSearch] = useState(() => form.getValues().name);
+  const iconUrl = useCustomWidgetFormDocumentField("iconUrl");
+  const nameInputProps = form.getInputProps("name");
+  useEffect(() => setSuggestedIconSearch(form.getValues().name), [form, formRevision]);
+  return (
+    <EditorSection id="general" title={w("generalInformation")} icon={IconSettings}>
+      <TextInput
+        key={form.key("name")}
+        label={tCommon("field.name")}
+        required
+        {...nameInputProps}
+        onBlur={(event) => {
+          nameInputProps.onBlur?.(event);
+          setSuggestedIconSearch(form.getValues().name);
+        }}
+      />
+      <Textarea
+        key={form.key("description")}
+        label={t("field.description")}
+        autosize
+        minRows={2}
+        {...form.getInputProps("description")}
+      />
+      <IconPicker
+        key={form.key("iconUrl")}
+        withAsterisk={false}
+        suggestedSearch={mode === "create" ? suggestedIconSearch : undefined}
+        {...form.getInputProps("iconUrl")}
+        value={iconUrl}
+      />
+    </EditorSection>
+  );
+}
+
+export function CustomWidgetSourcesSection({
+  form,
+  definitionId,
+}: {
+  form: CustomWidgetWorkbenchForm;
+  definitionId?: string;
+}) {
+  const w = useI18n("customWidget.workbench");
+  useCustomWidgetFormDocumentField("sources");
+  useCustomWidgetFormDocumentField("requests");
+  useCustomWidgetFormDocumentField("secrets");
+  return (
+    <EditorSection id="sources" title={w("sources.title")} icon={IconApi}>
+      <CustomWidgetSourcesEditor form={form} definitionId={definitionId} />
+    </EditorSection>
+  );
+}
+
+export function CustomWidgetRequestsSection({
+  form,
+  onRename,
+}: {
+  form: CustomWidgetWorkbenchForm;
+  onRename(currentId: string, nextId: string): void;
+}) {
+  const w = useI18n("customWidget.workbench");
+  const requests = useCustomWidgetFormDocumentField("requests");
+  useCustomWidgetFormDocumentField("sources");
+  useCustomWidgetFormDocumentField("options");
+  const requestDiagnostics = useCustomWidgetFormAnalysisField("requestDiagnostics");
+  return (
+    <EditorSection id="requests" title={w("requests.title")} icon={IconDatabase}>
+      <CustomWidgetRequestsEditor form={form} onRename={onRename} />
+      <LazyOnceAccordion label={w("builder.advancedJson")}>
+        <CodeEditor
+          id="requests-editor"
+          label={w("requests.label")}
+          description={w("requests.description")}
+          language="json"
+          value={requests}
+          onChange={(value) => form.setFieldValue("requests", value, { forceUpdate: false })}
+          diagnostics={requestDiagnostics}
+          error={form.errors.requests}
+          reference={customWidgetRequestReference}
+          required
+        />
+      </LazyOnceAccordion>
+    </EditorSection>
+  );
+}
+
+export function CustomWidgetOptionsSection({
+  form,
+  onRename,
+}: {
+  form: CustomWidgetWorkbenchForm;
+  onRename(currentName: string, nextName: string): void;
+}) {
+  const w = useI18n("customWidget.workbench");
+  const options = useCustomWidgetFormDocumentField("options");
+  useCustomWidgetFormDocumentField("requests");
+  return (
+    <EditorSection id="options" title={w("options.title")} icon={IconBraces}>
+      <CustomWidgetOptionsEditor form={form} onRename={onRename} />
+      <LazyOnceAccordion label={w("builder.advancedJson")}>
+        <CodeEditor
+          id="options-editor"
+          label={w("options.title")}
+          language="json"
+          value={options}
+          onChange={(value) => form.setFieldValue("options", value, { forceUpdate: false })}
+          error={form.errors.options}
+          reference={customWidgetOptionsSchemaReference}
+        />
+      </LazyOnceAccordion>
+    </EditorSection>
+  );
+}
+
+export function CustomWidgetTemplateSection({ form }: { form: CustomWidgetWorkbenchForm }) {
+  const w = useI18n("customWidget.workbench");
+  const template = useCustomWidgetFormDocumentField("template");
+  const jsxCompletions = useCustomWidgetFormAnalysisField("jsxCompletions");
+  const templateDiagnostics = useCustomWidgetFormAnalysisField("templateDiagnostics");
+  return (
+    <EditorSection id="jsx" title={w("jsx.title")} icon={IconCode}>
+      <CodeEditor
+        id="jsx-editor"
+        label={w("jsx.label")}
+        language="jsx"
+        value={template}
+        onChange={(value) => form.setFieldValue("template", value, { forceUpdate: false })}
+        diagnostics={templateDiagnostics}
+        completions={jsxCompletions}
+        error={form.errors.template}
+        required
+        maxLength={50_000}
+      />
+    </EditorSection>
+  );
+}
+
+interface CustomWidgetPreviewSectionProps {
+  preview: PreviewState;
+  size: string;
+  onSizeChange(size: string): void;
+  optionsSnapshot: Record<string, unknown>;
+  onOptionsChange: Dispatch<SetStateAction<Record<string, unknown>>>;
+  onLiveActionsChange(enabled: boolean): void;
+}
+
+export function CustomWidgetPreviewSection(props: CustomWidgetPreviewSectionProps) {
+  const previewCandidate = useCustomWidgetFormAnalysisField("previewCandidate");
+  const previewValidationIssues = useCustomWidgetFormAnalysisField("previewValidationIssues");
+  return (
+    <CustomWidgetPreviewPanel
+      candidate={previewCandidate}
+      validationIssues={previewValidationIssues}
+      preview={props.preview}
+      size={props.size}
+      onSizeChange={props.onSizeChange}
+      optionsSnapshot={props.optionsSnapshot}
+      onOptionsChange={props.onOptionsChange}
+      onLiveActionsChange={props.onLiveActionsChange}
+    />
+  );
+}

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-form-state.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import {
+  createContext,
+  startTransition,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import type { ReactNode } from "react";
+import type { UseFormReturnType } from "@mantine/form";
+
+import { customWidgetFormSchema } from "@homarr/custom-widgets/workbench";
+import type { CustomWidgetFormValues } from "@homarr/custom-widgets/workbench";
+
+import { areCustomWidgetValuesEqual } from "./_custom-widget-value-equality";
+
+export interface CustomWidgetFormDocumentStore {
+  getValues(): CustomWidgetFormValues;
+  setValues(values: CustomWidgetFormValues): void;
+  getDirty(): boolean;
+  subscribe(listener: () => void): () => void;
+  markSaved(values: CustomWidgetFormValues): void;
+}
+
+const documentValueKeys = customWidgetFormSchema.keyof().options;
+
+function areDocumentValuesEqual(left: CustomWidgetFormValues, right: CustomWidgetFormValues) {
+  if (Object.keys(left).length !== documentValueKeys.length) return false;
+  if (Object.keys(right).length !== documentValueKeys.length) return false;
+  return documentValueKeys.every(
+    (key) => Object.hasOwn(left, key) && Object.hasOwn(right, key) && areCustomWidgetValuesEqual(left[key], right[key]),
+  );
+}
+
+export function createCustomWidgetFormDocumentStore(
+  initialValues: CustomWidgetFormValues,
+): CustomWidgetFormDocumentStore {
+  let values = initialValues;
+  let persistedValues = initialValues;
+  let dirty = false;
+  const listeners = new Set<() => void>();
+
+  const notify = () => listeners.forEach((listener) => listener());
+
+  return {
+    getValues: () => values,
+    setValues: (nextValues) => {
+      if (Object.is(values, nextValues)) return;
+      values = nextValues;
+      dirty = !areDocumentValuesEqual(nextValues, persistedValues);
+      notify();
+    },
+    getDirty: () => dirty,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    markSaved: (savedValues) => {
+      const wasDirty = dirty;
+      persistedValues = savedValues;
+      dirty = !areDocumentValuesEqual(values, persistedValues);
+      if (wasDirty !== dirty) notify();
+    },
+  };
+}
+
+const CustomWidgetFormDocumentContext = createContext<CustomWidgetFormDocumentStore | null>(null);
+
+export function CustomWidgetFormDocumentProvider({
+  store,
+  children,
+}: {
+  store: CustomWidgetFormDocumentStore;
+  children: ReactNode;
+}) {
+  return <CustomWidgetFormDocumentContext.Provider value={store}>{children}</CustomWidgetFormDocumentContext.Provider>;
+}
+
+export function useCustomWidgetFormDocumentStore() {
+  const store = useContext(CustomWidgetFormDocumentContext);
+  if (!store) throw new Error("Custom widget form document provider is missing");
+  return store;
+}
+
+export function useDeferredCustomWidgetFormDocumentValues() {
+  const store = useCustomWidgetFormDocumentStore();
+  const [values, setValues] = useState(() => store.getValues());
+  useEffect(() => {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    const scheduleUpdate = () => {
+      const nextValues = store.getValues();
+      clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        startTransition(() => {
+          setValues((currentValues) => {
+            if (!Object.is(store.getValues(), nextValues)) return currentValues;
+            return nextValues;
+          });
+        });
+      }, 150);
+    };
+    const unsubscribe = store.subscribe(scheduleUpdate);
+    return () => {
+      clearTimeout(timeout);
+      unsubscribe();
+    };
+  }, [store]);
+  return values;
+}
+
+export function useCustomWidgetFormDocumentField<Key extends keyof CustomWidgetFormValues>(field: Key) {
+  const store = useCustomWidgetFormDocumentStore();
+  const getSnapshot = () => store.getValues()[field];
+  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+
+export function useCustomWidgetFormDocumentDirty() {
+  const store = useCustomWidgetFormDocumentStore();
+  return useSyncExternalStore(store.subscribe, store.getDirty, store.getDirty);
+}
+
+export function useCustomWidgetFormDocumentBridge(
+  form: UseFormReturnType<CustomWidgetFormValues>,
+  store: CustomWidgetFormDocumentStore,
+) {
+  const formRef = useRef(form);
+  formRef.current = form;
+  return useMemo(
+    () =>
+      new Proxy({} as UseFormReturnType<CustomWidgetFormValues>, {
+        get: (_target, property) => {
+          if (property === "values") return store.getValues();
+          return Reflect.get(formRef.current, property);
+        },
+      }),
+    [store],
+  );
+}

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-form-utils.spec.ts

@@ -28,7 +28,7 @@ describe("Custom Widget workbench preview options", () => {
     const setValues = vi.fn();
     const result = applyCustomWidgetAiResponse(
       {
-        values: {
+        getValues: () => ({
           name: "",
           description: "",
           iconUrl: "",
@@ -37,7 +37,7 @@ describe("Custom Widget workbench preview options", () => {
           options: "{}",
           template: "",
           secrets: [],
-        },
+        }),
         setValues,
       } as never,
       `\`\`\`json\n${JSON.stringify(definition)}\n\`\`\``,
@@ -84,13 +84,6 @@ describe("Custom Widget workbench preview options", () => {
   it("normalizes only changed secrets", () => {
     expect(
       getChangedSecrets({
-        name: "Widget",
-        description: "",
-        iconUrl: "",
-        sources: "{}",
-        requests: "{}",
-        options: "{}",
-        template: "<Text />",
         secrets: [
           { sourceId: "default", kind: "apiKey", value: "", hasValue: true },
           { sourceId: "other", kind: "password", value: "replacement" },

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-form-utils.ts

@@ -12,6 +12,8 @@ import type { UseFormReturnType } from "@mantine/form";
 
 export type CustomWidgetWorkbenchForm = UseFormReturnType<CustomWidgetFormValues>;
 
+const PREVIEW_QUERY_CONCURRENCY = 4;
+
 export function buildDefinition(values: CustomWidgetFormValues) {
   return customWidgetDefinitionSchema.safeParse({
     $schema: "homarr-custom-widget-v2",
@@ -25,7 +27,7 @@ export function buildDefinition(values: CustomWidgetFormValues) {
   });
 }
 
-export function getChangedSecrets(values: CustomWidgetFormValues) {
+export function getChangedSecrets(values: Pick<CustomWidgetFormValues, "secrets">) {
   return values.secrets
     .filter((secret) => secret.value.trim())
     .map(({ sourceId, kind, value }) => ({
@@ -46,7 +48,7 @@ export function filterSecretsForSourceAuthentication(
 
 export function applyDefinition(form: CustomWidgetWorkbenchForm, widget: HomarrCustomWidgetV2) {
   form.setValues({
-    ...form.values,
+    ...form.getValues(),
     name: widget.name,
     description: widget.description ?? "",
     iconUrl: widget.iconUrl ?? "",
@@ -102,25 +104,43 @@ export function isRuntimeParams(
 }
 
 export async function loadPreviewQueries(definition: HomarrCustomWidgetV2, sessionId: string) {
-  const data: Record<string, unknown> = {};
-  const status: Record<string, unknown> = {};
-  for (const [requestId] of Object.entries(definition.requests).filter(
+  const requests = Object.entries(definition.requests).filter(
     ([, entry]) => entry.kind === "query" && entry.trigger === "load",
-  )) {
-    try {
-      const result = await fetchApi.customWidget.previewQuery.query({ sessionId, requestId, params: {} });
-      data[requestId] = result.data;
-      status[requestId] = { loading: false, ...result };
-    } catch (error) {
-      data[requestId] = null;
-      status[requestId] = {
-        loading: false,
-        ok: false,
-        error: error instanceof Error ? error.message : "Request failed",
-      };
+  );
+  const results: Array<{
+    requestId: string;
+    data: unknown;
+    status: Record<string, unknown>;
+  }> = [];
+  let nextIndex = 0;
+  const worker = async () => {
+    while (true) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const request = requests[index];
+      if (!request) return;
+      const [requestId] = request;
+      try {
+        const result = await fetchApi.customWidget.previewQuery.query({ sessionId, requestId, params: {} });
+        results[index] = { requestId, data: result.data, status: { loading: false, ...result } };
+      } catch (error) {
+        results[index] = {
+          requestId,
+          data: null,
+          status: {
+            loading: false,
+            ok: false,
+            error: error instanceof Error ? error.message : "Request failed",
+          },
+        };
+      }
     }
-  }
-  return { data, status };
+  };
+  await Promise.all(Array.from({ length: Math.min(PREVIEW_QUERY_CONCURRENCY, requests.length) }, () => worker()));
+  return {
+    data: Object.fromEntries(results.map((result) => [result.requestId, result.data])),
+    status: Object.fromEntries(results.map((result) => [result.requestId, result.status])),
+  };
 }
 
 export function getDefinitionDefaults(definition: HomarrCustomWidgetV2) {

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-form.tsx

@@ -1,45 +1,45 @@
 "use client";
 
-import { useEffect, useMemo, useState } from "react";
-import { Accordion, Box, Button, Paper, SegmentedControl, Stack, TextInput, Textarea } from "@mantine/core";
-import {
-  IconAlertCircle,
-  IconApi,
-  IconBraces,
-  IconCode,
-  IconDatabase,
-  IconEye,
-  IconSettings,
-} from "@tabler/icons-react";
+import { memo, useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
+import type { Dispatch, FormEventHandler, SetStateAction } from "react";
+import { Box, Paper, SegmentedControl, Stack } from "@mantine/core";
 
-import {
-  analyzeJsxTemplate,
-  analyzeRequestManifest,
-  customWidgetFormSchema,
-  DEFAULT_CUSTOM_WIDGET_FORM_VALUES,
-} from "@homarr/custom-widgets/workbench";
-import { customWidgetOptionsSchema, getCustomWidgetDefaultOptions } from "@homarr/custom-widgets/core";
+import type { CustomWidgetAiDraft } from "@homarr/custom-widgets/authoring-prompt";
+import { customWidgetFormSchema, DEFAULT_CUSTOM_WIDGET_FORM_VALUES } from "@homarr/custom-widgets/workbench";
 import type { CustomWidgetFormValues } from "@homarr/custom-widgets/workbench";
 import { useZodForm } from "@homarr/form";
-import { IconPicker } from "@homarr/forms-collection";
 import { useI18n } from "@homarr/translation/client";
 
-import { CodeEditor } from "./_code-editor";
-import { CustomWidgetAiCard } from "./_custom-widget-ai-card";
 import { CustomWidgetAdvancedManifest } from "./_custom-widget-advanced-manifest";
-import { createCustomWidgetCompletions, getInvalidCustomWidgetSections } from "./_custom-widget-form-analysis";
-import { EditorSection, SaveActions } from "./_custom-widget-form-layout";
-import { customWidgetOptionsSchemaReference, customWidgetRequestReference } from "./_custom-widget-form-references";
-import { buildDefinition, getDefinitionDefaults, isRecord, parseJson } from "./_custom-widget-form-utils";
-import { CustomWidgetOptionsEditor } from "./_custom-widget-options-editor";
-import { CustomWidgetPreviewPanel } from "./_custom-widget-preview-panel";
+import {
+  CustomWidgetOptionsSnapshotSync,
+  CustomWidgetSaveActions,
+  CustomWidgetSectionNavigation,
+  CustomWidgetUnsavedChangesGuard,
+} from "./_custom-widget-form-layout";
+import {
+  CustomWidgetAiSection,
+  CustomWidgetGeneralSection,
+  CustomWidgetOptionsSection,
+  CustomWidgetPreviewSection,
+  CustomWidgetRequestsSection,
+  CustomWidgetSourcesSection,
+  CustomWidgetTemplateSection,
+} from "./_custom-widget-form-sections";
+import {
+  createCustomWidgetFormDocumentStore,
+  CustomWidgetFormDocumentProvider,
+  useCustomWidgetFormDocumentBridge,
+} from "./_custom-widget-form-state";
+import type { CustomWidgetFormDocumentStore } from "./_custom-widget-form-state";
+import { buildDefinition, getDefinitionDefaults } from "./_custom-widget-form-utils";
+import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
 import type { PreviewState } from "./_custom-widget-preview-panel";
-import { CustomWidgetRequestsEditor } from "./_custom-widget-requests-editor";
 import { createCustomWidgetRenameHandlers } from "./_custom-widget-rename-handlers";
+import type { CustomWidgetSaveIssue } from "./_custom-widget-save-errors";
 import { CustomWidgetSaveIssuesAlert } from "./_custom-widget-save-issues-alert";
-import { CustomWidgetSourcesEditor } from "./_custom-widget-sources-editor";
 import { useCustomWidgetFormActions } from "./_use-custom-widget-form-actions";
-import { useUnsavedChangesGuard } from "./_use-unsaved-changes-guard";
+import { analyzeCustomWidgetAiDiagnostics, CustomWidgetFormAnalysisProvider } from "./_use-custom-widget-form-analysis";
 import classes from "./_custom-widget-form.module.css";
 
 interface CustomWidgetFormProps {
@@ -47,241 +47,204 @@ interface CustomWidgetFormProps {
   initialValues?: Partial<CustomWidgetFormValues>;
   definitionId?: string;
 }
-const sectionLinks = [
-  ["general", "section.general", IconSettings],
-  ["sources", "section.sources", IconApi],
-  ["requests", "section.requests", IconDatabase],
-  ["options", "section.options", IconBraces],
-  ["jsx", "section.jsx", IconCode],
-  ["preview", "section.preview", IconEye],
-] as const;
+
+type MobilePane = "configure" | "preview";
+
+interface CustomWidgetFormViewProps {
+  mode: "create" | "edit";
+  definitionId?: string;
+  form: CustomWidgetWorkbenchForm;
+  formErrors: CustomWidgetWorkbenchForm["errors"];
+  formRevision: string;
+  documentStore: CustomWidgetFormDocumentStore;
+  mobilePane: MobilePane;
+  setMobilePane: Dispatch<SetStateAction<MobilePane>>;
+  preview: PreviewState;
+  setPreview: Dispatch<SetStateAction<PreviewState>>;
+  previewSize: string;
+  setPreviewSize: Dispatch<SetStateAction<string>>;
+  optionsSnapshot: Record<string, unknown>;
+  setOptionsSnapshot: Dispatch<SetStateAction<Record<string, unknown>>>;
+  saveIssues: CustomWidgetSaveIssue[];
+  savePending: boolean;
+  previewPending: boolean;
+  onSubmit: FormEventHandler<HTMLFormElement>;
+  onPreview(): void;
+  onPasteAiResponse(): void;
+}
+
+function getAiDraft(values: CustomWidgetFormValues): CustomWidgetAiDraft {
+  return {
+    name: values.name,
+    description: values.description,
+    iconUrl: values.iconUrl,
+    sources: values.sources,
+    requests: values.requests,
+    options: values.options,
+    template: values.template,
+  };
+}
+
+const CustomWidgetFormView = memo(function CustomWidgetFormView(props: CustomWidgetFormViewProps) {
+  const w = useI18n("customWidget.workbench");
+  const documentStore = props.documentStore;
+  const form = props.form;
+  const setMobilePane = props.setMobilePane;
+  const setPreview = props.setPreview;
+  const { renameRequest, renameOption } = useMemo(
+    () =>
+      createCustomWidgetRenameHandlers({
+        form,
+        invalidWidgetMessage: w("invalidWidget"),
+      }),
+    [form, w],
+  );
+  const readAiDraft = useCallback(() => getAiDraft(documentStore.getValues()), [documentStore]);
+  const readAiDiagnostics = useCallback(
+    () => analyzeCustomWidgetAiDiagnostics(documentStore.getValues()),
+    [documentStore],
+  );
+  const handleSectionSelect = useCallback(
+    (section: string) => {
+      setMobilePane(section === "preview" ? "preview" : "configure");
+    },
+    [setMobilePane],
+  );
+  const handleLiveActionsChange = useCallback(
+    (enabled: boolean) =>
+      setPreview((current) => ({
+        ...current,
+        session: current.session ? { ...current.session, liveActions: enabled } : null,
+      })),
+    [setPreview],
+  );
+
+  return (
+    <CustomWidgetFormDocumentProvider store={documentStore}>
+      <CustomWidgetFormAnalysisProvider>
+        <form onSubmit={props.onSubmit} className={classes.form}>
+          <CustomWidgetUnsavedChangesGuard />
+          <CustomWidgetOptionsSnapshotSync setOptionsSnapshot={props.setOptionsSnapshot} />
+          <SegmentedControl
+            className={classes.paneSwitcher}
+            fullWidth
+            value={props.mobilePane}
+            onChange={(value) => props.setMobilePane(value as MobilePane)}
+            data={[
+              { value: "configure", label: w("configure") },
+              { value: "preview", label: w("section.preview") },
+            ]}
+          />
+          <CustomWidgetSaveIssuesAlert issues={props.saveIssues} />
+          <CustomWidgetSectionNavigation onSelect={handleSectionSelect} />
+          <div className={classes.workbench} data-mobile-pane={props.mobilePane}>
+            <Stack gap="lg" className={classes.configuration}>
+              <CustomWidgetAiSection
+                getDraft={readAiDraft}
+                getDiagnostics={readAiDiagnostics}
+                onPaste={props.onPasteAiResponse}
+              />
+              <CustomWidgetAdvancedManifest form={form} />
+              <CustomWidgetGeneralSection form={form} formRevision={props.formRevision} mode={props.mode} />
+              <CustomWidgetSourcesSection form={form} definitionId={props.definitionId} />
+              <CustomWidgetRequestsSection form={form} onRename={renameRequest} />
+              <CustomWidgetOptionsSection form={form} onRename={renameOption} />
+              <CustomWidgetTemplateSection form={form} />
+              <Paper p="md" className={classes.mobileSaveBar} shadow="sm">
+                <CustomWidgetSaveActions
+                  mode={props.mode}
+                  savePending={props.savePending}
+                  previewPending={props.previewPending}
+                  onPreview={props.onPreview}
+                />
+              </Paper>
+            </Stack>
+            <Box id="preview" component="aside" className={classes.previewPane} aria-label={w("widgetPreview")}>
+              <Paper p="md" className={classes.actionBar} shadow="sm">
+                <CustomWidgetSaveActions
+                  mode={props.mode}
+                  savePending={props.savePending}
+                  previewPending={props.previewPending}
+                  onPreview={props.onPreview}
+                />
+              </Paper>
+              <CustomWidgetPreviewSection
+                preview={props.preview}
+                size={props.previewSize}
+                onSizeChange={props.setPreviewSize}
+                optionsSnapshot={props.optionsSnapshot}
+                onOptionsChange={props.setOptionsSnapshot}
+                onLiveActionsChange={handleLiveActionsChange}
+              />
+            </Box>
+          </div>
+        </form>
+      </CustomWidgetFormAnalysisProvider>
+    </CustomWidgetFormDocumentProvider>
+  );
+});
 
 export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWidgetFormProps) {
-  const t = useI18n("customWidget");
-  const tCommon = useI18n("common");
-  const w = useI18n("customWidget.workbench");
-  const formInitialValues: CustomWidgetFormValues = { ...DEFAULT_CUSTOM_WIDGET_FORM_VALUES, ...initialValues };
-  const form = useZodForm(customWidgetFormSchema, { initialValues: formInitialValues });
-  const [mobilePane, setMobilePane] = useState<"configure" | "preview">("configure");
-  const [request, setRequest] = useState("");
-  const [documentationUrl, setDocumentationUrl] = useState("");
+  const [formInitialValues] = useState<CustomWidgetFormValues>(() => ({
+    ...DEFAULT_CUSTOM_WIDGET_FORM_VALUES,
+    ...initialValues,
+  }));
+  const [documentStore] = useState(() => createCustomWidgetFormDocumentStore(formInitialValues));
+  const mantineForm = useZodForm(customWidgetFormSchema, {
+    initialValues: formInitialValues,
+    mode: "uncontrolled",
+    validateDebounce: 300,
+    validateInputOnChange: false,
+    onValuesChange: documentStore.setValues,
+  });
+  const form = useCustomWidgetFormDocumentBridge(mantineForm, documentStore);
+  const [mobilePane, setMobilePane] = useState<MobilePane>("configure");
   const [preview, setPreview] = useState<PreviewState>({ data: {}, status: {}, session: null, outcome: "idle" });
   const [previewSize, setPreviewSize] = useState("standard");
   const [optionsSnapshot, setOptionsSnapshot] = useState<Record<string, unknown>>(() => {
     const initialDefinition = buildDefinition(formInitialValues);
     return initialDefinition.success ? getDefinitionDefaults(initialDefinition.data) : {};
   });
-  useUnsavedChangesGuard(form.isDirty());
-
-  const candidate = useMemo(() => buildDefinition(form.values), [form.values]);
-  const parsedOptions = useMemo(
-    () => customWidgetOptionsSchema.safeParse(parseJson(form.values.options)),
-    [form.values.options],
-  );
-  const requestIds = useMemo(
-    () =>
-      Object.keys(
-        isRecord(parseJson(form.values.requests)) ? (parseJson(form.values.requests) as Record<string, unknown>) : {},
-      ),
-    [form.values.requests],
-  );
-  const jsxCompletions = useMemo(
-    () => createCustomWidgetCompletions(form.values, requestIds),
-    [form.values, requestIds],
-  );
-  const templateDiagnostics = useMemo(
-    () => analyzeJsxTemplate(form.values.template, { requestIds }),
-    [form.values.template, requestIds],
-  );
-  const requestDiagnostics = useMemo(() => analyzeRequestManifest(form.values.requests), [form.values.requests]);
-  const hasDiagnostics = [...templateDiagnostics, ...requestDiagnostics].some((entry) => entry.severity === "error");
-  const invalidSections = useMemo(
-    () =>
-      getInvalidCustomWidgetSections(
-        candidate.success ? [] : candidate.error.issues,
-        requestDiagnostics,
-        templateDiagnostics,
-      ),
-    [candidate, requestDiagnostics, templateDiagnostics],
-  );
-
-  const { save, runPreview, pasteAiResponse, saveIssues, savePending, previewPending } = useCustomWidgetFormActions({
+  const actions = useCustomWidgetFormActions({
     mode,
     definitionId,
     form,
-    candidate,
-    preview,
+    documentStore,
     setPreview,
     setMobilePane,
     optionsSnapshot,
     setOptionsSnapshot,
   });
-  useEffect(() => {
-    if (parsedOptions.success) setOptionsSnapshot(getCustomWidgetDefaultOptions(parsedOptions.data));
-  }, [parsedOptions]);
+  const latestActions = useRef(actions);
+  useLayoutEffect(() => {
+    latestActions.current = actions;
+  }, [actions]);
+  const handleSubmit = useCallback<FormEventHandler<HTMLFormElement>>((event) => latestActions.current.save(event), []);
+  const handlePreview = useCallback(() => void latestActions.current.runPreview(), []);
+  const handlePasteAiResponse = useCallback(() => void latestActions.current.pasteAiResponse(), []);
 
-  const invalid = hasDiagnostics || !candidate.success;
-  const { renameRequest, renameOption } = createCustomWidgetRenameHandlers({
-    form,
-    candidate,
-    invalidWidgetMessage: w("invalidWidget"),
-  });
   return (
-    <form onSubmit={save} className={classes.form}>
-      <SegmentedControl
-        className={classes.paneSwitcher}
-        fullWidth
-        value={mobilePane}
-        onChange={(value) => setMobilePane(value as typeof mobilePane)}
-        data={[
-          { value: "configure", label: w("configure") },
-          { value: "preview", label: w("section.preview") },
-        ]}
-      />
-      <CustomWidgetSaveIssuesAlert issues={saveIssues} />
-      <nav className={classes.sectionNav} aria-label={w("sectionNavigation")}>
-        {sectionLinks.map(([id, key, SectionIcon]) => (
-          <Button
-            key={id}
-            component="a"
-            href={`#${id}`}
-            onClick={() => setMobilePane(id === "preview" ? "preview" : "configure")}
-            size="compact-sm"
-            variant="subtle"
-            color={invalidSections.has(id) ? "red" : undefined}
-            leftSection={<SectionIcon size={14} />}
-            rightSection={
-              invalidSections.has(id) ? <IconAlertCircle size={13} aria-label={w("status.invalid")} /> : undefined
-            }
-          >
-            {w(key)}
-          </Button>
-        ))}
-      </nav>
-      <div className={classes.workbench} data-mobile-pane={mobilePane}>
-        <Stack gap="lg" className={classes.configuration}>
-          <CustomWidgetAiCard
-            candidate={candidate.success ? candidate.data : null}
-            request={request}
-            onRequestChange={setRequest}
-            documentationUrl={documentationUrl}
-            onDocumentationUrlChange={setDocumentationUrl}
-            onPaste={() => void pasteAiResponse()}
-          />
-          <CustomWidgetAdvancedManifest form={form} />
-          <EditorSection id="general" title={w("generalInformation")} icon={IconSettings}>
-            <TextInput label={tCommon("field.name")} required {...form.getInputProps("name")} />
-            <Textarea label={t("field.description")} autosize minRows={2} {...form.getInputProps("description")} />
-            <IconPicker
-              withAsterisk={false}
-              suggestedSearch={mode === "create" ? form.values.name : undefined}
-              {...form.getInputProps("iconUrl")}
-            />
-          </EditorSection>
-          <EditorSection id="sources" title={w("sources.title")} icon={IconApi}>
-            <CustomWidgetSourcesEditor form={form} definitionId={definitionId} />
-          </EditorSection>
-          <EditorSection id="requests" title={w("requests.title")} icon={IconDatabase}>
-            <CustomWidgetRequestsEditor form={form} onRename={renameRequest} />
-            <Accordion variant="contained">
-              <Accordion.Item value="raw">
-                <Accordion.Control>{w("builder.advancedJson")}</Accordion.Control>
-                <Accordion.Panel>
-                  <CodeEditor
-                    id="requests-editor"
-                    label={w("requests.label")}
-                    description={w("requests.description")}
-                    language="json"
-                    value={form.values.requests}
-                    onChange={(value) => form.setFieldValue("requests", value)}
-                    diagnostics={requestDiagnostics}
-                    error={form.errors.requests}
-                    reference={customWidgetRequestReference}
-                    required
-                  />
-                </Accordion.Panel>
-              </Accordion.Item>
-            </Accordion>
-          </EditorSection>
-          <EditorSection id="options" title={w("options.title")} icon={IconBraces}>
-            <CustomWidgetOptionsEditor form={form} onRename={renameOption} />
-            <Accordion variant="contained">
-              <Accordion.Item value="raw">
-                <Accordion.Control>{w("builder.advancedJson")}</Accordion.Control>
-                <Accordion.Panel>
-                  <CodeEditor
-                    id="options"
-                    label={w("options.title")}
-                    language="json"
-                    value={form.values.options}
-                    onChange={(value) => form.setFieldValue("options", value)}
-                    error={form.errors.options}
-                    reference={customWidgetOptionsSchemaReference}
-                  />
-                </Accordion.Panel>
-              </Accordion.Item>
-            </Accordion>
-          </EditorSection>
-          <EditorSection id="jsx" title={w("jsx.title")} icon={IconCode}>
-            <CodeEditor
-              id="jsx-editor"
-              label={w("jsx.label")}
-              language="jsx"
-              value={form.values.template}
-              onChange={(value) => form.setFieldValue("template", value)}
-              diagnostics={templateDiagnostics}
-              completions={jsxCompletions}
-              error={form.errors.template}
-              required
-              maxLength={50_000}
-            />
-          </EditorSection>
-          <Paper p="md" className={classes.mobileSaveBar} shadow="sm">
-            <SaveActions
-              dirty={form.isDirty()}
-              savePending={savePending}
-              previewPending={previewPending}
-              invalid={invalid}
-              mode={mode}
-              onPreview={() => void runPreview()}
-            />
-          </Paper>
-        </Stack>
-        <Box id="preview" component="aside" className={classes.previewPane} aria-label={w("widgetPreview")}>
-          <Paper p="md" className={classes.actionBar} shadow="sm">
-            <SaveActions
-              dirty={form.isDirty()}
-              savePending={savePending}
-              previewPending={previewPending}
-              invalid={invalid}
-              mode={mode}
-              onPreview={() => void runPreview()}
-            />
-          </Paper>
-          <CustomWidgetPreviewPanel
-            candidate={candidate.success ? candidate.data : null}
-            validationIssues={
-              candidate.success
-                ? []
-                : candidate.error.issues.map((issue) => ({
-                    path: issue.path.map(String).join(".") || undefined,
-                    message: issue.message,
-                  }))
-            }
-            preview={preview}
-            size={previewSize}
-            onSizeChange={setPreviewSize}
-            optionsSnapshot={optionsSnapshot}
-            onOptionsChange={setOptionsSnapshot}
-            onLiveActionsChange={(enabled) =>
-              setPreview((current) => ({
-                ...current,
-                session: current.session ? { ...current.session, liveActions: enabled } : null,
-              }))
-            }
-          />
-        </Box>
-      </div>
-    </form>
+    <CustomWidgetFormView
+      mode={mode}
+      definitionId={definitionId}
+      form={form}
+      formErrors={mantineForm.errors}
+      formRevision={mantineForm.key("name")}
+      documentStore={documentStore}
+      mobilePane={mobilePane}
+      setMobilePane={setMobilePane}
+      preview={preview}
+      setPreview={setPreview}
+      previewSize={previewSize}
+      setPreviewSize={setPreviewSize}
+      optionsSnapshot={optionsSnapshot}
+      setOptionsSnapshot={setOptionsSnapshot}
+      saveIssues={actions.saveIssues}
+      savePending={actions.savePending}
+      previewPending={actions.previewPending}
+      onSubmit={handleSubmit}
+      onPreview={handlePreview}
+      onPasteAiResponse={handlePasteAiResponse}
+    />
   );
 }

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-options-editor.tsx

@@ -69,7 +69,7 @@ export function CustomWidgetOptionsEditor({
             )
           : [];
         return (
-          <Fieldset key={index} legend={typeof option.label === "string" ? option.label : id}>
+          <Fieldset key={id} legend={typeof option.label === "string" ? option.label : id}>
             <Stack gap="sm">
               <Group grow align="start">
                 <CustomWidgetIdentifierInput
@@ -99,7 +99,7 @@ export function CustomWidgetOptionsEditor({
                 }
               />
               <DefaultValueEditor
-                id={`${index}-default`}
+                id={`${id}-default`}
                 control={control}
                 value={option.default}
                 choices={choices}

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-preview-data.ts

@@ -6,6 +6,8 @@ interface PreviewSnapshot {
   session: { id: string; liveActions: boolean } | null;
 }
 
+type PreviewCandidate = Pick<HomarrCustomWidgetV2, "requests" | "template">;
+
 export function createPreviewDisplayData({
   candidate,
   fixture,
@@ -13,7 +15,7 @@ export function createPreviewDisplayData({
   options,
   fixtureError,
 }: {
-  candidate: HomarrCustomWidgetV2 | null;
+  candidate: PreviewCandidate | null;
   fixture: "live" | "loading" | "empty" | "error";
   preview: PreviewSnapshot;
   options: Record<string, unknown>;

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-preview-panel.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { memo, useMemo, useState } from "react";
 import { Alert, Box, Card, Group, Paper, SegmentedControl, Stack, Switch, Tabs, Text } from "@mantine/core";
 
 import { clientApi } from "@homarr/api/client";
@@ -15,9 +15,12 @@ import { getPreviewSummary, PreviewResult, PreviewStatusDot } from "./_custom-wi
 import type { PreviewOutcome } from "./_custom-widget-preview-status";
 import { PreviewActionControl } from "./_custom-widget-preview-action";
 import { createPreviewDisplayData } from "./_custom-widget-preview-data";
+import { CustomWidgetPreviewSizeControl } from "./_custom-widget-preview-size-control";
 import { JsonPreviewEditor } from "./_json-preview-editor";
 import classes from "./_custom-widget-form.module.css";
 
+const previewWidths: Record<string, number> = { compact: 320, standard: 480, wide: 720 };
+
 export interface PreviewState {
   data: Record<string, unknown>;
   status: Record<string, unknown>;
@@ -36,7 +39,7 @@ interface PreviewPanelProps {
   onLiveActionsChange(enabled: boolean): void;
 }
 
-export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
+function CustomWidgetPreviewPanelContent(props: PreviewPanelProps) {
   const t = useI18n("customWidget.workbench.preview");
   const errorBoundaryMessages = useI18n("customWidget.editor.errorBoundary");
   const actionT = useI18n("common.action");
@@ -46,26 +49,55 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
     { sessionId: props.preview.session?.id ?? "" },
     { enabled: Boolean(props.preview.session), refetchInterval: props.preview.session ? 2_000 : false },
   );
-  const widths: Record<string, number> = { compact: 320, standard: 480, wide: 720 };
   const candidate = props.candidate;
-  const accessibilityIssues = candidate ? analyzeCustomWidgetAccessibility(candidate.template) : [];
-  const displayData = createPreviewDisplayData({
-    candidate,
-    fixture,
-    preview: props.preview,
-    options: props.optionsSnapshot,
-    fixtureError: t("fixtureError"),
-  });
-  const previewSummary = getPreviewSummary(props.preview.status);
-  const rendererResetKey = JSON.stringify({
-    template: candidate?.template,
-    requests: candidate?.requests,
-    fixture,
-    data: props.preview.data,
-    status: props.preview.status,
-    sessionId: props.preview.session?.id,
-    options: props.optionsSnapshot,
-  });
+  const candidateTemplate = candidate?.template;
+  const candidateRequests = candidate?.requests;
+  const previewCandidate = useMemo(() => {
+    if (candidateTemplate === undefined || candidateRequests === undefined) return null;
+    return { template: candidateTemplate, requests: candidateRequests };
+  }, [candidateRequests, candidateTemplate]);
+  const previewSnapshot = useMemo(
+    () => ({ data: props.preview.data, status: props.preview.status, session: props.preview.session }),
+    [props.preview.data, props.preview.session, props.preview.status],
+  );
+  const fixtureError = t("fixtureError");
+  const accessibilityIssues = useMemo(() => {
+    if (candidateTemplate === undefined) return [];
+    return analyzeCustomWidgetAccessibility(candidateTemplate);
+  }, [candidateTemplate]);
+  const displayData = useMemo(
+    () =>
+      createPreviewDisplayData({
+        candidate: previewCandidate,
+        fixture,
+        preview: previewSnapshot,
+        options: props.optionsSnapshot,
+        fixtureError,
+      }),
+    [fixture, fixtureError, previewCandidate, previewSnapshot, props.optionsSnapshot],
+  );
+  const previewSummary = useMemo(() => getPreviewSummary(props.preview.status), [props.preview.status]);
+  const rendererResetKey = useMemo(
+    () =>
+      JSON.stringify({
+        template: candidateTemplate,
+        requests: candidateRequests,
+        fixture,
+        data: props.preview.data,
+        status: props.preview.status,
+        sessionId: props.preview.session?.id,
+        options: props.optionsSnapshot,
+      }),
+    [
+      candidateRequests,
+      candidateTemplate,
+      fixture,
+      props.optionsSnapshot,
+      props.preview.data,
+      props.preview.session?.id,
+      props.preview.status,
+    ],
+  );
   const previewResult =
     props.preview.outcome === "success"
       ? {
@@ -85,37 +117,7 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
     <Card withBorder p="md">
       <Stack gap="md">
         <Group gap="xs" justify="space-between">
-          <SegmentedControl
-            size="xs"
-            value={props.size}
-            onChange={props.onSizeChange}
-            data={[
-              {
-                value: "compact",
-                label: (
-                  <span aria-label={t("size.compact")} title={t("size.compact")}>
-                    S
-                  </span>
-                ),
-              },
-              {
-                value: "standard",
-                label: (
-                  <span aria-label={t("size.standard")} title={t("size.standard")}>
-                    M
-                  </span>
-                ),
-              },
-              {
-                value: "wide",
-                label: (
-                  <span aria-label={t("size.wide")} title={t("size.wide")}>
-                    L
-                  </span>
-                ),
-              },
-            ]}
-          />
+          <CustomWidgetPreviewSizeControl value={props.size} onChange={props.onSizeChange} />
           <SegmentedControl
             size="xs"
             value={fixture}
@@ -151,7 +153,14 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
           </Tabs.List>
           <Tabs.Panel value="widget" pt="sm">
             <Box className={classes.previewCanvas}>
-              <Paper withBorder p="sm" h={360} w={widths[props.size] ?? 480} maw="100%" style={{ overflow: "auto" }}>
+              <Paper
+                withBorder
+                p="sm"
+                h={360}
+                w={previewWidths[props.size] ?? 480}
+                maw="100%"
+                style={{ overflow: "auto" }}
+              >
                 {displayData ? (
                   <PreviewErrorBoundary
                     title={errorBoundaryMessages("title")}
@@ -264,3 +273,5 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
     </Card>
   );
 }
+
+export const CustomWidgetPreviewPanel = memo(CustomWidgetPreviewPanelContent);

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-preview-size-control.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { memo } from "react";
+import { SegmentedControl, VisuallyHidden } from "@mantine/core";
+
+import { useI18n } from "@homarr/translation/client";
+
+interface CustomWidgetPreviewSizeControlProps {
+  value: string;
+  onChange(value: string): void;
+}
+
+const previewSizeShortLabels = { compact: "S", standard: "M", wide: "L" } as const;
+
+function CustomWidgetPreviewSizeControlContent({ value, onChange }: CustomWidgetPreviewSizeControlProps) {
+  const t = useI18n("customWidget.workbench.preview");
+
+  return (
+    <SegmentedControl
+      size="xs"
+      value={value}
+      onChange={onChange}
+      data={[
+        {
+          value: "compact",
+          label: (
+            <span title={t("size.compact")}>
+              <span aria-hidden>{previewSizeShortLabels.compact}</span>
+              <VisuallyHidden>{t("size.compact")}</VisuallyHidden>
+            </span>
+          ),
+        },
+        {
+          value: "standard",
+          label: (
+            <span title={t("size.standard")}>
+              <span aria-hidden>{previewSizeShortLabels.standard}</span>
+              <VisuallyHidden>{t("size.standard")}</VisuallyHidden>
+            </span>
+          ),
+        },
+        {
+          value: "wide",
+          label: (
+            <span title={t("size.wide")}>
+              <span aria-hidden>{previewSizeShortLabels.wide}</span>
+              <VisuallyHidden>{t("size.wide")}</VisuallyHidden>
+            </span>
+          ),
+        },
+      ]}
+    />
+  );
+}
+
+export const CustomWidgetPreviewSizeControl = memo(CustomWidgetPreviewSizeControlContent);

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-rename-handlers.ts

@@ -1,34 +1,35 @@
 import { renameCustomWidgetOption, renameCustomWidgetRequest } from "@homarr/custom-widgets/workbench";
 
-import { applyDefinition } from "./_custom-widget-form-utils";
-import type { buildDefinition, CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
+import { applyDefinition, buildDefinition } from "./_custom-widget-form-utils";
+import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
 
 interface RenameHandlersInput {
   form: CustomWidgetWorkbenchForm;
-  candidate: ReturnType<typeof buildDefinition>;
   invalidWidgetMessage: string;
 }
 
 export function createCustomWidgetRenameHandlers(input: RenameHandlersInput) {
   const renameRequest = (currentId: string, nextId: string) => {
-    if (!input.candidate.success) {
+    const candidate = buildDefinition(input.form.getValues());
+    if (!candidate.success) {
       input.form.setFieldError("requests", input.invalidWidgetMessage);
       return;
     }
     try {
-      applyDefinition(input.form, renameCustomWidgetRequest(input.candidate.data, currentId, nextId));
+      applyDefinition(input.form, renameCustomWidgetRequest(candidate.data, currentId, nextId));
       input.form.clearFieldError("requests");
     } catch (error) {
       input.form.setFieldError("requests", error instanceof Error ? error.message : input.invalidWidgetMessage);
     }
   };
   const renameOption = (currentName: string, nextName: string) => {
-    if (!input.candidate.success) {
+    const candidate = buildDefinition(input.form.getValues());
+    if (!candidate.success) {
       input.form.setFieldError("options", input.invalidWidgetMessage);
       return;
     }
     try {
-      applyDefinition(input.form, renameCustomWidgetOption(input.candidate.data, currentName, nextName));
+      applyDefinition(input.form, renameCustomWidgetOption(candidate.data, currentName, nextName));
       input.form.clearFieldError("options");
     } catch (error) {
       input.form.setFieldError("options", error instanceof Error ? error.message : input.invalidWidgetMessage);

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-request-value-editors.tsx

@@ -23,7 +23,7 @@ export function QueryValuesEditor({
 }) {
   const t = useI18n("customWidget.workbench.builder");
   const entries = Object.entries(value);
-  const [nameErrors, setNameErrors] = useState<Record<number, string>>({});
+  const [nameErrors, setNameErrors] = useState<Record<string, string>>({});
   return (
     <Stack gap="xs">
       <Text size="sm" fw={500}>
@@ -65,23 +65,23 @@ export function QueryValuesEditor({
           ...(allowParams ? [{ value: "param", label: t("invocationParameter") }] : []),
         ];
         return (
-          <Group key={index} align="end" wrap="wrap">
+          <Group key={name} align="end" wrap="wrap">
             <CustomWidgetIdentifierInput
               style={{ flex: "1 1 10rem" }}
               label={t("queryKey")}
               value={name}
-              error={nameErrors[index]}
+              error={nameErrors[name]}
               onCommit={(nextName) => {
                 if (
                   !/^[A-Za-z][A-Za-z0-9_-]*$/u.test(nextName) ||
                   entries.some(([entryName], entryIndex) => entryIndex !== index && entryName === nextName)
                 ) {
-                  setNameErrors((currentErrors) => ({ ...currentErrors, [index]: t("queryKeyInvalid") }));
+                  setNameErrors((currentErrors) => ({ ...currentErrors, [name]: t("queryKeyInvalid") }));
                   return;
                 }
                 setNameErrors((currentErrors) => {
                   const nextErrors = { ...currentErrors };
-                  delete nextErrors[index];
+                  delete nextErrors[name];
                   return nextErrors;
                 });
                 commit(nextName, kind, current);

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-requests-editor.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Accordion, ActionIcon, Button, Fieldset, Group, Select, Stack, Switch, Text, TextInput } from "@mantine/core";
+import { ActionIcon, Button, Fieldset, Group, Select, Stack, Switch, Text, TextInput } from "@mantine/core";
 import { IconArrowDown, IconArrowUp, IconPlus, IconTrash } from "@tabler/icons-react";
 
 import { useI18n } from "@homarr/translation/client";
@@ -9,6 +9,7 @@ import { isRecord, parseJson } from "./_custom-widget-form-utils";
 import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
 import { QueryValuesEditor, RequestBodyEditor } from "./_custom-widget-request-value-editors";
 import { CustomWidgetIdentifierInput } from "./_custom-widget-identifier-input";
+import { LazyOnceAccordion } from "./_lazy-once-accordion";
 
 const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 
@@ -24,6 +25,8 @@ export function CustomWidgetRequestsEditor({
   const entries = isRecord(parsed) ? Object.entries(parsed) : [];
   const sources = parseJson(form.values.sources);
   const sourceIds = isRecord(sources) ? Object.keys(sources) : ["default"];
+  const options = parseJson(form.values.options);
+  const optionNames = isRecord(options) ? Object.keys(options) : [];
 
   const commit = (next: Array<[string, unknown]>) =>
     form.setFieldValue("requests", JSON.stringify(Object.fromEntries(next), null, 2));
@@ -50,7 +53,7 @@ export function CustomWidgetRequestsEditor({
         const kind = request.kind === "action" ? "action" : "query";
         const trigger = request.trigger === "manual" ? "manual" : "load";
         return (
-          <Fieldset key={index} legend={id || t("request", { count: index + 1 })}>
+          <Fieldset key={id} legend={id || t("request", { count: index + 1 })}>
             <Stack gap="sm">
               <Group grow align="start">
                 <CustomWidgetIdentifierInput
@@ -119,71 +122,61 @@ export function CustomWidgetRequestsEditor({
               <TextInput
                 label={t("path")}
                 description={t("pathDescription")}
+                descriptionProps={{
+                  style: { color: "light-dark(var(--mantine-color-gray-7), var(--mantine-color-gray-4))" },
+                }}
                 value={typeof request.path === "string" ? request.path : ""}
                 onChange={(event) => update(index, id, { ...request, path: event.currentTarget.value })}
               />
-              <Accordion variant="contained">
-                <Accordion.Item value="values">
-                  <Accordion.Control>{t("requestDetails")}</Accordion.Control>
-                  <Accordion.Panel>
-                    <Stack gap="sm">
-                      <QueryValuesEditor
-                        value={isRecord(request.query) ? request.query : {}}
-                        optionNames={Object.keys(
-                          isRecord(parseJson(form.values.options))
-                            ? (parseJson(form.values.options) as Record<string, unknown>)
-                            : {},
-                        )}
-                        allowParams={trigger === "manual" || kind === "action"}
-                        onChange={(query) => update(index, id, { ...request, query })}
-                      />
-                      <RequestBodyEditor
-                        id={id}
-                        value={request.body}
-                        optionNames={Object.keys(
-                          isRecord(parseJson(form.values.options))
-                            ? (parseJson(form.values.options) as Record<string, unknown>)
-                            : {},
-                        )}
-                        allowParams={trigger === "manual" || kind === "action"}
-                        onChange={(body) => update(index, id, { ...request, body })}
-                      />
-                      {kind === "action" && (
-                        <TextInput
-                          label={t("confirmation")}
-                          value={typeof request.confirmation === "string" ? request.confirmation : ""}
-                          onChange={(event) =>
-                            update(index, id, { ...request, confirmation: event.currentTarget.value || undefined })
-                          }
-                        />
-                      )}
-                      {kind === "action" && (
-                        <TextInput
-                          label={t("invalidation")}
-                          description={t("invalidationDescription")}
-                          value={Array.isArray(request.invalidates) ? request.invalidates.join(", ") : ""}
-                          onChange={(event) =>
-                            update(index, id, {
-                              ...request,
-                              invalidates: event.currentTarget.value
-                                .split(",")
-                                .map((value) => value.trim())
-                                .filter(Boolean),
-                            })
-                          }
-                        />
-                      )}
-                      <Switch
-                        label={t("noAuth")}
-                        checked={request.auth === "none"}
-                        onChange={(event) =>
-                          update(index, id, { ...request, auth: event.currentTarget.checked ? "none" : "inherit" })
-                        }
-                      />
-                    </Stack>
-                  </Accordion.Panel>
-                </Accordion.Item>
-              </Accordion>
+              <LazyOnceAccordion label={t("requestDetails")}>
+                <Stack gap="sm">
+                  <QueryValuesEditor
+                    value={isRecord(request.query) ? request.query : {}}
+                    optionNames={optionNames}
+                    allowParams={trigger === "manual" || kind === "action"}
+                    onChange={(query) => update(index, id, { ...request, query })}
+                  />
+                  <RequestBodyEditor
+                    id={id}
+                    value={request.body}
+                    optionNames={optionNames}
+                    allowParams={trigger === "manual" || kind === "action"}
+                    onChange={(body) => update(index, id, { ...request, body })}
+                  />
+                  {kind === "action" && (
+                    <TextInput
+                      label={t("confirmation")}
+                      value={typeof request.confirmation === "string" ? request.confirmation : ""}
+                      onChange={(event) =>
+                        update(index, id, { ...request, confirmation: event.currentTarget.value || undefined })
+                      }
+                    />
+                  )}
+                  {kind === "action" && (
+                    <TextInput
+                      label={t("invalidation")}
+                      description={t("invalidationDescription")}
+                      value={Array.isArray(request.invalidates) ? request.invalidates.join(", ") : ""}
+                      onChange={(event) =>
+                        update(index, id, {
+                          ...request,
+                          invalidates: event.currentTarget.value
+                            .split(",")
+                            .map((value) => value.trim())
+                            .filter(Boolean),
+                        })
+                      }
+                    />
+                  )}
+                  <Switch
+                    label={t("noAuth")}
+                    checked={request.auth === "none"}
+                    onChange={(event) =>
+                      update(index, id, { ...request, auth: event.currentTarget.checked ? "none" : "inherit" })
+                    }
+                  />
+                </Stack>
+              </LazyOnceAccordion>
               <Group justify="space-between">
                 <Group gap="xs">
                   <ActionIcon

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-save-issue-utils.ts

@@ -0,0 +1,37 @@
+import type { Dispatch, SetStateAction } from "react";
+import type { UseFormReturnType } from "@mantine/form";
+
+import type { CustomWidgetFormValues } from "@homarr/custom-widgets/workbench";
+import { showErrorNotification } from "@homarr/notifications";
+
+import type { CustomWidgetSaveIssue } from "./_custom-widget-save-errors";
+
+export function reportSaveIssues(
+  form: UseFormReturnType<CustomWidgetFormValues>,
+  issues: CustomWidgetSaveIssue[],
+  setIssues: Dispatch<SetStateAction<CustomWidgetSaveIssue[]>>,
+  title: string,
+  getRemainingLabel: (count: number) => string,
+) {
+  setIssues(issues);
+  const messagesByPath = new Map<string, string[]>();
+  for (const issue of issues) {
+    if (!issue.path) continue;
+    const field = issue.path.split(".")[0] ?? issue.path;
+    messagesByPath.set(field, [...(messagesByPath.get(field) ?? []), issue.message]);
+  }
+  for (const [path, messages] of messagesByPath) {
+    form.setFieldError(path, messages.join(" "));
+  }
+  const remaining = issues.length - 1;
+  showErrorNotification({
+    title,
+    message: `${issues[0]?.message ?? ""}${remaining > 0 ? ` ${getRemainingLabel(remaining)}` : ""}`,
+  });
+}
+
+export function clearSaveIssues(form: UseFormReturnType<CustomWidgetFormValues>, issues: CustomWidgetSaveIssue[]) {
+  for (const path of new Set(issues.flatMap((issue) => (issue.path ? [issue.path.split(".")[0] ?? issue.path] : [])))) {
+    form.clearFieldError(path);
+  }
+}

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-value-equality.ts

@@ -0,0 +1,18 @@
+export function areCustomWidgetValuesEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+
+  if (Array.isArray(left)) {
+    if (!Array.isArray(right) || left.length !== right.length) return false;
+    return left.every((value, index) => areCustomWidgetValuesEqual(value, right[index]));
+  }
+
+  if (!isRecord(left) || !isRecord(right)) return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+  return leftKeys.every((key) => Object.hasOwn(right, key) && areCustomWidgetValuesEqual(left[key], right[key]));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

apps/nextjs/src/app/[locale]/manage/custom-widgets/_lazy-once-accordion.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { useId, useState } from "react";
+import { Accordion } from "@mantine/core";
+
+interface LazyOnceAccordionProps {
+  label: ReactNode;
+  children: ReactNode;
+}
+
+export function LazyOnceAccordion({ label, children }: LazyOnceAccordionProps) {
+  const id = useId();
+  const [value, setValue] = useState<string | null>(null);
+  const [hasOpened, setHasOpened] = useState(false);
+  const controlId = `${id}-control`;
+  const panelId = `${id}-panel`;
+
+  const handleChange = (nextValue: string | null) => {
+    setValue(nextValue);
+    if (nextValue === "content") setHasOpened(true);
+  };
+
+  return (
+    <Accordion variant="contained" value={value} onChange={handleChange}>
+      <Accordion.Item value="content">
+        <Accordion.Control id={controlId} aria-controls={panelId}>
+          {label}
+        </Accordion.Control>
+        {/* Native hiding keeps editor effects and CodeMirror history alive while the panel is collapsed. */}
+        <div
+          id={panelId}
+          className={Accordion.classes.panel}
+          // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- The explicit role matches Mantine's panel contract.
+          role="region"
+          aria-labelledby={controlId}
+          hidden={value !== "content"}
+        >
+          <div className={Accordion.classes.content}>{hasOpened && children}</div>
+        </div>
+      </Accordion.Item>
+    </Accordion>
+  );
+}

apps/nextjs/src/app/[locale]/manage/custom-widgets/_use-custom-widget-form-actions.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import type { Dispatch, SetStateAction } from "react";
 import type { UseFormReturnType } from "@mantine/form";
 
@@ -22,13 +22,14 @@ import {
 import type { PreviewState } from "./_custom-widget-preview-panel";
 import { extractCustomWidgetSaveIssues } from "./_custom-widget-save-errors";
 import type { CustomWidgetSaveIssue } from "./_custom-widget-save-errors";
+import { clearSaveIssues, reportSaveIssues } from "./_custom-widget-save-issue-utils";
+import type { CustomWidgetFormDocumentStore } from "./_custom-widget-form-state";
 
 interface FormActionsInput {
   mode: "create" | "edit";
   definitionId?: string;
   form: UseFormReturnType<CustomWidgetFormValues>;
-  candidate: ReturnType<typeof buildDefinition>;
-  preview: PreviewState;
+  documentStore: CustomWidgetFormDocumentStore;
   setPreview: Dispatch<SetStateAction<PreviewState>>;
   setMobilePane: Dispatch<SetStateAction<"configure" | "preview">>;
   optionsSnapshot: Record<string, unknown>;
@@ -45,6 +46,34 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
   const previewMutation = clientApi.customWidget.previewCreate.useMutation();
   const [saveIssues, setSaveIssues] = useState<CustomWidgetSaveIssue[]>([]);
   const [previewPending, setPreviewPending] = useState(false);
+  const setPreview = input.setPreview;
+  const previewGeneration = useRef(0);
+  const activePreviewGeneration = useRef<number | null>(null);
+  const invalidatePreview = useCallback(() => {
+    previewGeneration.current += 1;
+    if (activePreviewGeneration.current !== null) return;
+    setPreview((preview) => {
+      if (
+        preview.outcome === "idle" &&
+        preview.session === null &&
+        Object.keys(preview.data).length === 0 &&
+        Object.keys(preview.status).length === 0
+      )
+        return preview;
+      return { data: {}, status: {}, session: null, outcome: "idle" };
+    });
+  }, [setPreview]);
+  useLayoutEffect(() => {
+    invalidatePreview();
+  }, [input.optionsSnapshot, invalidatePreview]);
+  useEffect(() => input.documentStore.subscribe(invalidatePreview), [input.documentStore, invalidatePreview]);
+  useEffect(
+    () => () => {
+      previewGeneration.current += 1;
+      activePreviewGeneration.current = null;
+    },
+    [],
+  );
   let actionLabel = tCommon("action.save");
   if (input.mode === "create") actionLabel = tCommon("action.create");
 
@@ -73,6 +102,7 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
         });
         input.form.setInitialValues(values);
         input.form.resetDirty();
+        input.documentStore.markSaved(values);
         await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
         window.location.assign(result.managementPath);
       } else if (input.definitionId) {
@@ -88,6 +118,7 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
         ]);
         input.form.setInitialValues(values);
         input.form.resetDirty();
+        input.documentStore.markSaved(values);
         showSuccessNotification({
           title: tCommon("action.save"),
           message: t("notification.updated", { name: values.name }),
@@ -104,15 +135,18 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
   });
 
   const runPreview = async () => {
-    if (previewPending) return;
-    if (!input.candidate.success) {
+    if (activePreviewGeneration.current !== null) return;
+    const valuesAtStart = input.documentStore.getValues();
+    const candidateAtStart = buildDefinition(valuesAtStart);
+    if (!candidateAtStart.success) {
       showErrorNotification({
         title: w("section.preview"),
-        message: input.candidate.error.issues[0]?.message ?? w("invalidWidget"),
+        message: candidateAtStart.error.issues[0]?.message ?? w("invalidWidget"),
       });
       return;
     }
-    const optionIssues = getCustomWidgetPreviewOptionIssues(input.candidate.data, input.optionsSnapshot);
+    const optionsAtStart = input.optionsSnapshot;
+    const optionIssues = getCustomWidgetPreviewOptionIssues(candidateAtStart.data, optionsAtStart);
     if (optionIssues.length > 0) {
       const issue = optionIssues[0];
       showErrorNotification({
@@ -121,17 +155,24 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
       });
       return;
     }
+    const secretsAtStart = getChangedSecrets(valuesAtStart);
+    const generation = previewGeneration.current + 1;
+    previewGeneration.current = generation;
+    activePreviewGeneration.current = generation;
+    const isCurrent = () => previewGeneration.current === generation;
     input.setMobilePane("preview");
     input.setPreview({ data: {}, status: {}, session: null, outcome: "loading" });
     setPreviewPending(true);
     try {
       const created = await previewMutation.mutateAsync({
-        definition: input.candidate.data,
+        definition: candidateAtStart.data,
         definitionId: input.definitionId,
-        options: input.optionsSnapshot,
-        secrets: getChangedSecrets(input.form.values),
+        options: optionsAtStart,
+        secrets: secretsAtStart,
       });
-      const snapshot = await loadPreviewQueries(input.candidate.data, created.previewSession.id);
+      if (!isCurrent()) return;
+      const snapshot = await loadPreviewQueries(candidateAtStart.data, created.previewSession.id);
+      if (!isCurrent()) return;
       const failed = Object.values(snapshot.status).filter((status) => isRecord(status) && status.ok === false).length;
       input.setPreview({
         ...snapshot,
@@ -156,10 +197,15 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
         });
       }
     } catch {
+      if (!isCurrent()) return;
       input.setPreview((current) => ({ ...current, outcome: "error" }));
       showErrorNotification({ title: w("section.preview"), message: t("notification.previewError") });
     } finally {
-      setPreviewPending(false);
+      if (activePreviewGeneration.current === generation) {
+        activePreviewGeneration.current = null;
+        setPreviewPending(false);
+        if (!isCurrent()) setPreview({ data: {}, status: {}, session: null, outcome: "idle" });
+      }
     }
   };
 
@@ -170,7 +216,6 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
         throw new Error(formatCustomWidgetImportIssues(result.issues));
       }
       input.setOptionsSnapshot(getDefinitionDefaults(result.widget));
-      input.setPreview({ data: {}, status: {}, session: null, outcome: "idle" });
       showSuccessNotification({
         title: w("ai.response"),
         message:
@@ -196,33 +241,3 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
     previewPending,
   };
 }
-
-function reportSaveIssues(
-  form: UseFormReturnType<CustomWidgetFormValues>,
-  issues: CustomWidgetSaveIssue[],
-  setIssues: Dispatch<SetStateAction<CustomWidgetSaveIssue[]>>,
-  title: string,
-  getRemainingLabel: (count: number) => string,
-) {
-  setIssues(issues);
-  const messagesByPath = new Map<string, string[]>();
-  for (const issue of issues) {
-    if (!issue.path) continue;
-    const field = issue.path.split(".")[0] ?? issue.path;
-    messagesByPath.set(field, [...(messagesByPath.get(field) ?? []), issue.message]);
-  }
-  for (const [path, messages] of messagesByPath) {
-    form.setFieldError(path, messages.join(" "));
-  }
-  const remaining = issues.length - 1;
-  showErrorNotification({
-    title,
-    message: `${issues[0]?.message ?? ""}${remaining > 0 ? ` ${getRemainingLabel(remaining)}` : ""}`,
-  });
-}
-
-function clearSaveIssues(form: UseFormReturnType<CustomWidgetFormValues>, issues: CustomWidgetSaveIssue[]) {
-  for (const path of new Set(issues.flatMap((issue) => (issue.path ? [issue.path.split(".")[0] ?? issue.path] : [])))) {
-    form.clearFieldError(path);
-  }
-}

apps/nextjs/src/app/[locale]/manage/custom-widgets/_use-custom-widget-form-analysis.ts

@@ -0,0 +1,188 @@
+"use client";
+
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useDeferredValue,
+  useLayoutEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import type { ReactNode } from "react";
+
+import type { CustomWidgetAiDiagnostic } from "@homarr/custom-widgets/authoring-prompt";
+import { customWidgetOptionsSchema } from "@homarr/custom-widgets/core";
+import { analyzeJsxTemplate, analyzeRequestManifest } from "@homarr/custom-widgets/workbench";
+import type { CustomWidgetFormValues, EditorDiagnostic } from "@homarr/custom-widgets/workbench";
+
+import { createCustomWidgetCompletions, getInvalidCustomWidgetSections } from "./_custom-widget-form-analysis";
+import { buildDefinition, isRecord, parseJson } from "./_custom-widget-form-utils";
+import { useDeferredCustomWidgetFormDocumentValues } from "./_custom-widget-form-state";
+
+const emptyPreviewValidationIssues: Array<{ path?: string; message: string }> = [];
+const emptyCandidateIssues: Array<{ path: PropertyKey[] }> = [];
+
+function normalizeEditorDiagnostics(
+  section: "requests" | "template",
+  diagnostics: readonly EditorDiagnostic[],
+): CustomWidgetAiDiagnostic[] {
+  return diagnostics.map((diagnostic) => ({
+    section,
+    severity: diagnostic.severity,
+    code: diagnostic.code,
+    line: diagnostic.line,
+    column: diagnostic.column,
+    message: diagnostic.value,
+  }));
+}
+
+function createAiDiagnostics(
+  candidate: ReturnType<typeof buildDefinition>,
+  requestDiagnostics: readonly EditorDiagnostic[],
+  templateDiagnostics: readonly EditorDiagnostic[],
+) {
+  const editorDiagnostics = [
+    ...normalizeEditorDiagnostics("requests", requestDiagnostics),
+    ...normalizeEditorDiagnostics("template", templateDiagnostics),
+  ];
+  if (candidate.success) return editorDiagnostics;
+  return [
+    ...candidate.error.issues.map((issue) => ({
+      section: String(issue.path[0] ?? "definition"),
+      severity: "error" as const,
+      path: issue.path.map(String).join(".") || undefined,
+      message: issue.message,
+    })),
+    ...editorDiagnostics,
+  ];
+}
+
+export function analyzeCustomWidgetAiDiagnostics(values: CustomWidgetFormValues): CustomWidgetAiDiagnostic[] {
+  const parsedRequests = parseJson(values.requests);
+  const requestIds = isRecord(parsedRequests) ? Object.keys(parsedRequests) : [];
+  return createAiDiagnostics(
+    buildDefinition(values),
+    analyzeRequestManifest(values.requests),
+    analyzeJsxTemplate(values.template, { requestIds }),
+  );
+}
+
+export function useCustomWidgetFormAnalysis(values: CustomWidgetFormValues) {
+  const analysisValues = useDeferredValue(values);
+  const candidate = useMemo(() => buildDefinition(analysisValues), [analysisValues]);
+  const parsedOptions = useMemo(
+    () => customWidgetOptionsSchema.safeParse(parseJson(analysisValues.options)),
+    [analysisValues.options],
+  );
+  const requestIds = useMemo(() => {
+    const parsedRequests = parseJson(analysisValues.requests);
+    return isRecord(parsedRequests) ? Object.keys(parsedRequests) : [];
+  }, [analysisValues.requests]);
+  const requestIdsSignature = requestIds.join("\0");
+  const jsxCompletions = useMemo(
+    () =>
+      createCustomWidgetCompletions(
+        { options: analysisValues.options, sources: analysisValues.sources },
+        requestIdsSignature ? requestIdsSignature.split("\0") : [],
+      ),
+    [analysisValues.options, analysisValues.sources, requestIdsSignature],
+  );
+  const templateDiagnostics = useMemo(
+    () => analyzeJsxTemplate(analysisValues.template, { requestIds }),
+    [analysisValues.template, requestIds],
+  );
+  const requestDiagnostics = useMemo(() => analyzeRequestManifest(analysisValues.requests), [analysisValues.requests]);
+  const hasDiagnostics = [...templateDiagnostics, ...requestDiagnostics].some((entry) => entry.severity === "error");
+  const candidateIssues = candidate.success ? emptyCandidateIssues : candidate.error.issues;
+  const invalidSections = useMemo(
+    () => getInvalidCustomWidgetSections(candidateIssues, requestDiagnostics, templateDiagnostics),
+    [candidateIssues, requestDiagnostics, templateDiagnostics],
+  );
+  const previewCandidate = useMemo(
+    () => (candidate.success ? candidate.data : null),
+    // The preview renderer consumes only these definition fields; other fields affect the validity boolean below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [analysisValues.requests, analysisValues.template, candidate.success],
+  );
+  const previewValidationIssues = useMemo(
+    () =>
+      candidate.success
+        ? emptyPreviewValidationIssues
+        : candidate.error.issues.map((issue) => ({
+            path: issue.path.map(String).join(".") || undefined,
+            message: issue.message,
+          })),
+    [candidate],
+  );
+
+  return useMemo(
+    () => ({
+      candidate,
+      candidateValid: candidate.success,
+      parsedOptions,
+      jsxCompletions,
+      templateDiagnostics,
+      requestDiagnostics,
+      hasDiagnostics,
+      invalidSections,
+      previewCandidate,
+      previewValidationIssues,
+    }),
+    [
+      candidate,
+      hasDiagnostics,
+      invalidSections,
+      jsxCompletions,
+      parsedOptions,
+      previewCandidate,
+      previewValidationIssues,
+      requestDiagnostics,
+      templateDiagnostics,
+    ],
+  );
+}
+
+type CustomWidgetFormAnalysis = ReturnType<typeof useCustomWidgetFormAnalysis>;
+
+interface CustomWidgetFormAnalysisStore {
+  getAnalysis(): CustomWidgetFormAnalysis;
+  setAnalysis(analysis: CustomWidgetFormAnalysis): void;
+  subscribe(listener: () => void): () => void;
+}
+
+function createCustomWidgetFormAnalysisStore(initialAnalysis: CustomWidgetFormAnalysis): CustomWidgetFormAnalysisStore {
+  let analysis = initialAnalysis;
+  const listeners = new Set<() => void>();
+  return {
+    getAnalysis: () => analysis,
+    setAnalysis: (nextAnalysis) => {
+      if (Object.is(analysis, nextAnalysis)) return;
+      analysis = nextAnalysis;
+      listeners.forEach((listener) => listener());
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+const CustomWidgetFormAnalysisContext = createContext<CustomWidgetFormAnalysisStore | null>(null);
+
+export function CustomWidgetFormAnalysisProvider({ children }: { children: ReactNode }) {
+  const values = useDeferredCustomWidgetFormDocumentValues();
+  const analysis = useCustomWidgetFormAnalysis(values);
+  const [store] = useState(() => createCustomWidgetFormAnalysisStore(analysis));
+  useLayoutEffect(() => store.setAnalysis(analysis), [analysis, store]);
+  return createElement(CustomWidgetFormAnalysisContext.Provider, { value: store }, children);
+}
+
+export function useCustomWidgetFormAnalysisField<Key extends keyof CustomWidgetFormAnalysis>(field: Key) {
+  const store = useContext(CustomWidgetFormAnalysisContext);
+  if (!store) throw new Error("Custom widget form analysis provider is missing");
+  const getSnapshot = useCallback(() => store.getAnalysis()[field], [field, store]);
+  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}

apps/nextjs/src/app/[locale]/manage/custom-widgets/new/page.tsx

@@ -23,7 +23,7 @@ export default async function NewCustomWidgetPage() {
         <Stack>
           <div>
             <Title>{t("page.create.title")}</Title>
-            <Text c="dimmed" size="sm" mt={4}>
+            <Text c="light-dark(var(--mantine-color-gray-7), var(--mantine-color-gray-4))" size="sm" mt={4}>
               {t("page.create.subtitle")}
             </Text>
           </div>

apps/nextjs/src/app/[locale]/manage/custom-widgets/workshop/_workshop-browse.tsx

@@ -11,7 +11,6 @@ import { useWorkshopQuery } from "@homarr/workshop/backend";
 
 import { ManagePageLayout } from "~/components/manage/manage-page-layout";
 import { NoResults } from "~/components/no-results";
-import { getWorkshopWebUrl } from "~/components/workshop/workshop-client";
 import { WorkshopAccountButton, useWorkshopSession } from "~/components/workshop/workshop-session";
 import { WorkshopSubmissionGrid } from "~/components/workshop/workshop-submission-grid";
 import { WorkshopVoteControl } from "~/components/workshop/workshop-vote-control";
@@ -23,9 +22,10 @@ interface WorkshopBrowseProps {
   search: string | undefined;
   sort: "top" | "newest";
   page: number;
+  workshopWebUrl: string;
 }
 
-export function WorkshopBrowse({ search, sort, page }: WorkshopBrowseProps) {
+export function WorkshopBrowse({ search, sort, page, workshopWebUrl }: WorkshopBrowseProps) {
   const t = useI18n("workshop");
   const tCommon = useI18n("common.action");
   const session = useWorkshopSession();
@@ -46,7 +46,7 @@ export function WorkshopBrowse({ search, sort, page }: WorkshopBrowseProps) {
           <WorkshopAccountButton session={session} />
           <Button
             component="a"
-            href={getWorkshopWebUrl()}
+            href={workshopWebUrl}
             target="_blank"
             rel="noopener noreferrer"
             variant="default"
@@ -100,7 +100,7 @@ export function WorkshopBrowse({ search, sort, page }: WorkshopBrowseProps) {
               <Tooltip label={t("openCommunity")}>
                 <ActionIcon
                   component="a"
-                  href={getWorkshopWebUrl(item.id)}
+                  href={`${workshopWebUrl.replace(/\/+$/u, "")}/${encodeURIComponent(item.id)}`}
                   target="_blank"
                   rel="noopener noreferrer"
                   variant="subtle"

apps/nextjs/src/app/[locale]/manage/custom-widgets/workshop/page.tsx

@@ -3,6 +3,9 @@ import { z } from "zod/v4";
 
 import { auth } from "@homarr/auth/next";
 import type { inferSearchParamsFromSchema } from "@homarr/common/types";
+import { resolveHomarrUrlConfig } from "@homarr/workshop/schema";
+
+import { env } from "~/env";
 
 import { WorkshopBrowse } from "./_workshop-browse";
 
@@ -26,6 +29,13 @@ export default async function WorkshopBrowsePage(props: WorkshopBrowsePageProps)
   if (!session?.user.permissions.includes("admin")) redirect(session ? "/" : "/auth/login");
 
   const { search, sort, page } = searchParamsSchema.parse(await props.searchParams);
+  const { workshopWebUrl } = resolveHomarrUrlConfig({
+    homarrWebsiteUrl: env.HOMARR_WEBSITE_URL,
+    workshopApiUrl: env.WORKSHOP_API_URL,
+    workshopWebUrl: env.WORKSHOP_WEB_URL,
+  });
 
-  return <WorkshopBrowse search={search?.trim() || undefined} sort={sort} page={page} />;
+  return (
+    <WorkshopBrowse search={search?.trim() || undefined} sort={sort} page={page} workshopWebUrl={workshopWebUrl} />
+  );
 }

apps/nextjs/src/app/[locale]/widgets/[kind]/_content.tsx

@@ -1,5 +1,7 @@
 "use client";
 
+/* eslint-disable react/no-unstable-nested-components -- Widget modules and definition-bound fallbacks are loaded dynamically. */
+
 import { use, useCallback, useState } from "react";
 import { ActionIcon, Affix, Card } from "@mantine/core";
 import { IconDimensions, IconPencil, IconToggleLeft, IconToggleRight } from "@tabler/icons-react";
@@ -71,6 +73,7 @@ export const WidgetPreviewPageContent = ({ kind }: WidgetPreviewPageContentProps
           ),
           integrationSupport: hasIntegrationSupport,
           settings,
+          previewDimensions: dimensions,
         },
         {
           title(translate) {
@@ -86,10 +89,10 @@ export const WidgetPreviewPageContent = ({ kind }: WidgetPreviewPageContentProps
     } finally {
       setIsEditorLoading(false);
     }
-  }, [currentDefinition, kind, openWidgetEditModal, settings, state, t, utils]);
+  }, [currentDefinition, dimensions, kind, openWidgetEditModal, settings, state, t, utils]);
 
   const toggleEditMode = useCallback(() => {
-    setEditMode((editMode) => !editMode);
+    setEditMode((currentEditMode) => !currentEditMode);
     showSuccessNotification({
       message: editMode ? t("widgetPreview.toggle.disabled") : t("widgetPreview.toggle.enabled"),
     });

apps/nextjs/src/app/[locale]/widgets/[kind]/page.tsx

@@ -1,8 +1,14 @@
 import { Suspense } from "react";
-import { notFound } from "next/navigation";
+import { notFound, redirect } from "next/navigation";
 import { Center, Loader } from "@mantine/core";
 
+import { getHomeBoardAsync } from "@homarr/api/board-server";
+import { IntegrationProvider } from "@homarr/auth/client";
+import { auth } from "@homarr/auth/next";
+import { getIntegrationsWithPermissionsAsync } from "@homarr/auth/server";
+import { BoardPreviewProvider } from "@homarr/boards/context";
 import type { WidgetKind } from "@homarr/definitions";
+import { ModalProvider } from "@homarr/modals";
 import { widgetKinds } from "@homarr/widgets/manifest";
 
 import { WidgetPreviewPageContent } from "./_content";
@@ -16,12 +22,24 @@ export default async function WidgetPreview(props: Props) {
   if (!widgetKinds.includes(kind as WidgetKind)) {
     notFound();
   }
+  const session = await auth();
+  if (!session) {
+    redirect(`/auth/login?callbackUrl=${encodeURIComponent(`/widgets/${kind}`)}`);
+  }
+
+  const [integrations, board] = await Promise.all([getIntegrationsWithPermissionsAsync(session), getHomeBoardAsync()]);
 
   return (
-    <Center h="100vh">
-      <Suspense fallback={<Loader size="sm" />}>
-        <WidgetPreviewPageContent key={kind} kind={kind as WidgetKind} />
-      </Suspense>
-    </Center>
+    <IntegrationProvider integrations={integrations}>
+      <BoardPreviewProvider board={board}>
+        <ModalProvider>
+          <Center h="100vh">
+            <Suspense fallback={<Loader size="sm" />}>
+              <WidgetPreviewPageContent key={kind} kind={kind as WidgetKind} />
+            </Suspense>
+          </Center>
+        </ModalProvider>
+      </BoardPreviewProvider>
+    </IntegrationProvider>
   );
 }

apps/nextjs/src/app/api/assistant/chat/assistant-tool-input-repair.ts

@@ -89,8 +89,9 @@ const repairIconSearchInput = <T extends AssistantToolCallInput>(toolCall: T): T
   };
 };
 
-const repairCustomWidgetToolInput = <T extends AssistantToolCallInput>(toolCall: T): T | null => {
-  if (!toolCall.toolName.startsWith("customWidget_")) return null;
+const repairMultilineToolInput = <T extends AssistantToolCallInput>(toolCall: T): T | null => {
+  const isCustomWidgetTool = toolCall.toolName.startsWith("customWidget_");
+  if (!isCustomWidgetTool && toolCall.toolName !== "configure_board_settings") return null;
   if (customWidgetNoInputToolNames.has(toolCall.toolName)) {
     try {
       const input = JSON.parse(toolCall.input) as unknown;
@@ -114,4 +115,4 @@ const repairCustomWidgetToolInput = <T extends AssistantToolCallInput>(toolCall:
 };
 
 export const repairAssistantToolInput = <T extends AssistantToolCallInput>(toolCall: T): T | null =>
-  repairIconSearchInput(toolCall) ?? repairCustomWidgetToolInput(toolCall);
+  repairIconSearchInput(toolCall) ?? repairMultilineToolInput(toolCall);

apps/nextjs/src/app/api/assistant/chat/route.ts

@@ -146,12 +146,12 @@ Homarr concepts:
 
 Action rules:
 - Prefer read-only tools before actions.
-- Whenever you need an answer from the user before choosing the next action, call ask_user. Never end a prose response with a question that expects the user to type a reply. Offer distinct choices, categorize agreement or proceeding as affirmative, refusal as negative, and unrelated selections as alternative, then leave the freeform Other answer enabled. A confirmation question must have exactly one affirmative option. Purely rhetorical questions and open-ended conversation that does not block an action may remain prose, but optional next steps should be stated declaratively instead of phrased as a question.
+- Whenever you need an answer from the user before choosing the next action, call ask_user. Never use ask_user to confirm a board settings or custom CSS change before configure_board_settings, or to confirm another change whose inputs are already sufficient for its native review form or mutating tool. Never end a prose response with a question that expects the user to type a reply. Offer distinct choices, categorize agreement or proceeding as affirmative, refusal as negative, and unrelated selections as alternative, then leave the freeform Other answer enabled. A confirmation question must have exactly one affirmative option. Purely rhetorical questions and open-ended conversation that does not block an action may remain prose, but optional next steps should be stated declaratively instead of phrased as a question.
 - Mutating Homarr tools already pause for native user approval. Calling a mutation only proposes the action; it cannot execute until the user selects Approve and run. Once the requested change is sufficiently specified, call the mutation immediately so the approval UI appears.
 - A prose response such as "Please confirm if you would like me to proceed", "Would you like me to proceed?", or a parameter summary that asks for confirmation is incorrect. Never ask for a second textual confirmation before an approval-gated tool call.
 - Do not retry a denied action.
 - Before creating an app, call configure_app with the app name and every useful default you can infer, including its description, href, pingUrl, and an icon URL returned by icon_findIcons. The user reviews Homarr's native app form. Its icon picker searches Homarr's local icon repository. Use the returned values for app_create. If the user asked to place it on a board, call configure_widget afterward with kind "app" and options { appId: the returned appId }.
-- Before changing a board's custom CSS or visual and behavior settings, call board_getBoardSettings to read the current values, then call configure_board_settings with only the requested proposed changes. The user can edit the complete CSS and settings in Homarr's native form. Use its returned flat object for board_savePartialBoardSettings, which then shows the mutation approval. Never overwrite existing CSS rules unless the user explicitly requests replacement.
+- Before changing a board's custom CSS or visual and behavior settings, call board_getBoardSettings to read the current values, then immediately call configure_board_settings with only the requested proposed changes. For a custom CSS request, include the complete resulting stylesheet in changes.customCss so the native form is prefilled and previews the proposed CSS. The native form is the user's review and confirmation step, so never insert ask_user between these calls when the requested change is known. Use the form's returned flat object for board_savePartialBoardSettings, which then shows the mutation approval. Never overwrite existing CSS rules unless the user explicitly requests replacement.
 - Before adding any widget to a board, call configure_widget with the target board, widget kind, proposed options, and any integration IDs selected from integration_all. Homarr's native widget editor applies defaults, validates the options, and restricts the picker to compatible integrations the user can access. Use the returned boardId, kind, options, and integrationIds exactly as the input to board_addItem. If configure_widget returns cancelled, do not add the widget.
 - To create a formatted note on a dashboard, call configure_widget with kind "notebook". Put valid Tiptap-compatible HTML in options.content and set options.showToolbar and options.allowReadOnlyCheck when useful. Use semantic paragraphs, headings, lists, task lists, blockquotes, tables, links, emphasis, and images as appropriate. Never include scripts, styles, iframes, event handlers, or unsafe URL protocols.
 - When choosing an app icon without configure_app, call the Homarr icon findIcons tool first and use one of its returned local icon URLs. Never invent a third-party icon CDN URL.

apps/nextjs/src/components/assistant/assistant-panel.module.css

@@ -130,6 +130,45 @@
   color: var(--mantine-color-text);
 }
 
+.widgetPanel[data-board-widget] {
+  background: transparent;
+}
+
+.widgetPanel[data-board-widget] .panelHeader,
+.widgetPanel[data-board-widget] .composerWrap {
+  border-color: rgb(from var(--mantine-color-default-border) r g b / var(--opacity, 1));
+}
+
+.widgetPanel[data-board-widget] .composerWrap,
+.widgetPanel[data-board-widget] .composer,
+.widgetPanel[data-board-widget] .composerQuote,
+.widgetPanel[data-board-widget] .pendingQuestionDock {
+  background: transparent;
+}
+
+.widgetPanel[data-board-widget] .suggestion,
+.widgetPanel[data-board-widget] .runtimeSelectorTrigger,
+.widgetPanel[data-board-widget] .composerContext,
+.widgetPanel[data-board-widget] .providerQuotaTrigger {
+  border-color: rgb(from var(--mantine-color-default-border) r g b / var(--opacity, 1));
+  background: transparent;
+}
+
+.widgetPanel[data-board-widget] .suggestion:hover:not(:disabled),
+.widgetPanel[data-board-widget] .runtimeSelectorTrigger:hover:not(:disabled),
+.widgetPanel[data-board-widget] .composerContext:hover:not(:disabled),
+.widgetPanel[data-board-widget] .providerQuotaTrigger:hover:not(:disabled) {
+  background: rgb(from var(--mantine-color-default-hover) r g b / var(--opacity, 1));
+}
+
+.widgetPanel[data-board-widget] .suggestion:focus-visible,
+.widgetPanel[data-board-widget] .runtimeSelectorTrigger:focus-visible,
+.widgetPanel[data-board-widget] .composerContext:focus-visible,
+.widgetPanel[data-board-widget] .providerQuotaTrigger:focus-visible {
+  outline: 2px solid var(--mantine-primary-color-filled);
+  outline-offset: 2px;
+}
+
 .widgetState {
   container-type: inline-size;
   overflow: auto;
@@ -145,10 +184,6 @@
   min-width: 0;
 }
 
-.widgetPanel[data-editing] .panelActions {
-  padding-inline-end: 2.75rem;
-}
-
 .panelHeader {
   min-width: 0;
   min-height: 3.75rem;
@@ -157,30 +192,12 @@
   border-bottom: 1px solid var(--mantine-color-default-border);
 }
 
-.panelIdentity {
-  min-width: 0;
-  flex: 1 1 auto;
-}
-
-.panelIdentityIcon {
-  flex: 0 0 auto;
-}
-
-.panelIdentityTitle,
-.panelThreadTitle {
-  max-width: 14rem;
-}
-
 .panelActions {
   min-width: 0;
   flex: 0 0 auto;
   margin-inline-start: auto;
 }
 
-.newConversationButton {
-  flex: 0 0 auto;
-}
-
 .panelAction {
   width: 2.625rem;
   height: 2.625rem;
@@ -207,21 +224,6 @@
     display: none;
   }
 
-  .newConversationButton {
-    width: 2.625rem;
-    max-width: 2.625rem;
-    height: 2.625rem;
-    padding-inline: 0.75rem;
-  }
-
-  .newConversationButton :global(.mantine-Button-section) {
-    margin-inline: 0;
-  }
-
-  .newConversationButton :global(.mantine-Button-label) {
-    display: none;
-  }
-
   .messages {
     padding: 0.5rem 0.65rem 1rem;
   }
@@ -277,8 +279,7 @@
 
 @container assistant-widget (max-width: 22rem) {
   .panelAction,
-  .historyButton,
-  .newConversationButton {
+  .historyButton {
     width: 2.25rem;
     max-width: 2.25rem;
     height: 2.25rem;
@@ -301,10 +302,6 @@
   .composerContextLabel {
     display: none;
   }
-
-  .panelThreadTitle {
-    display: none;
-  }
 }
 
 @container assistant-widget (max-width: 18rem) {

apps/nextjs/src/components/assistant/assistant-panel.tsx

@@ -2368,7 +2368,7 @@ const EmptyThread = () => {
       <Box className={classes.empty}>
         <Stack align="center" gap="lg" maw={560} w="100%">
           <Stack align="center" gap="xs" maw={430}>
-            <ThemeIcon size={52} radius="xl" variant="light" color="red">
+            <ThemeIcon size={52} radius="xl" variant="light">
               <IconRobot size={27} />
             </ThemeIcon>
             <Text size="xl" fw={700}>
@@ -2957,7 +2957,6 @@ const Composer = (props: ComposerProps) => {
               ) : (
                 <ComposerPrimitive.Send asChild>
                   <ActionIcon
-                    color="red"
                     variant="filled"
                     size="lg"
                     aria-label={
@@ -3162,27 +3161,6 @@ interface AssistantConversationSurfaceProps extends AssistantConversationControl
   onDismiss?: () => void;
 }
 
-const AssistantPanelIdentity = () => {
-  const t = useI18n("assistant");
-  const threadTitle = useAuiState((state) => state.threadListItem.title);
-
-  return (
-    <Group className={classes.panelIdentity} gap="xs" wrap="nowrap">
-      <ThemeIcon className={classes.panelIdentityIcon} variant="light" color="red" radius="xl" size="md">
-        <IconRobot size={16} />
-      </ThemeIcon>
-      <Box miw={0}>
-        <Text className={classes.panelIdentityTitle} size="sm" fw={700} truncate>
-          {t("title")}
-        </Text>
-        <Text className={classes.panelThreadTitle} size="xs" c="dimmed" truncate>
-          {threadTitle ?? t("newConversation")}
-        </Text>
-      </Box>
-    </Group>
-  );
-};
-
 export const AssistantConversationSurface = ({
   isRunning,
   pendingAction,
@@ -3212,23 +3190,20 @@ export const AssistantConversationSurface = ({
   return (
     <AssistantDirectiveEntitiesProvider>
       <Group className={classes.panelHeader} justify="space-between" wrap="nowrap" gap="xs">
-        <AssistantPanelIdentity />
         <Group className={classes.panelActions} gap={2} wrap="nowrap">
           <ConversationHistory />
           <ViewRefreshAction isRefreshing={isRefreshing} onRefresh={onRefresh} />
           <AutoApprovalControl />
           <Tooltip label={t("newConversation")}>
             <ThreadListPrimitive.New asChild>
-              <Button
-                className={classes.newConversationButton}
+              <ActionIcon
+                className={classes.panelAction}
                 variant="subtle"
                 color="gray"
-                size="compact-sm"
-                leftSection={<IconPlus size={17} />}
                 aria-label={t("newConversation")}
               >
-                {t("newConversation")}
-              </Button>
+                <IconPlus size={17} />
+              </ActionIcon>
             </ThreadListPrimitive.New>
           </Tooltip>
           {onExpand && (

apps/nextjs/src/components/assistant/assistant-provider.tsx

@@ -32,7 +32,7 @@ import { showErrorNotification, showWarningNotification } from "@homarr/notifica
 import { closeSpotlight } from "@homarr/spotlight/store";
 import { useI18n } from "@homarr/translation/client";
 import { openMediaRequestSearch, openSpotlight, useRegisterSpotlightContextResults } from "@homarr/spotlight";
-import { AssistantWidgetRendererProvider } from "@homarr/widgets";
+import { AssistantWidgetRendererProvider } from "@homarr/widgets/assistant/context";
 import { createWorkshopClient } from "~/components/workshop/workshop-client";
 
 import { AssistantContext, AssistantPreferencesContext, useAssistantPreferences } from "./assistant-context";
@@ -856,6 +856,7 @@ const EnabledAssistantProvider = ({ children }: PropsWithChildren) => {
           : t("busy.description"),
       unavailable: !canSend,
       alwaysVisible: true,
+      placement: "fallback" as const,
       interaction: (query: string) =>
         createAssistantPromptInteraction({
           sendPrompt,

apps/nextjs/src/components/assistant/assistant-spotlight-placeholder.ts

@@ -19,6 +19,7 @@ export const useRegisterAssistantSpotlightPlaceholder = (description: string) =>
       description,
       unavailable: true,
       alwaysVisible: true,
+      placement: "fallback" as const,
       interaction: (_query: string) => ({ type: "none" as const }),
     }),
     [description, t],

apps/nextjs/src/components/assistant/assistant-spotlight.tsx

@@ -16,7 +16,7 @@ const AssistantPromptDetail = () => {
   const t = useI18n("assistant");
   return (
     <Group px="md" py="sm" wrap="nowrap">
-      <ThemeIcon color="red" variant="light" radius="xl">
+      <ThemeIcon variant="light" radius="xl">
         <IconRobot size={17} />
       </ThemeIcon>
       <Stack gap={1}>

apps/nextjs/src/components/assistant/assistant-tool-contracts.ts

@@ -54,7 +54,7 @@ export const assistantBoardSettingsChangesSchema = z
 export const browserToolContracts = {
   ask_user: {
     description:
-      "Pause and ask the user one concise structured question. Use this for missing information or a meaningful choice, never as a second confirmation before a mutating tool. Provide 2-4 distinct options and classify every option: agreement, approval, or proceeding is affirmative; refusal or stopping is negative; unrelated selections are alternative. A confirmation question must have exactly one affirmative option. The UI adds a freeform Other choice when allowOther is not false.",
+      "Pause and ask the user one concise structured question. Use this only for missing information or a meaningful choice, never to confirm details that are already sufficient for a native review form or mutating tool. In particular, do not use ask_user before configure_app, configure_board_settings, or configure_widget when their inputs are known. Provide 2-4 distinct options and classify every option: agreement, approval, or proceeding is affirmative; refusal or stopping is negative; unrelated selections are alternative. A confirmation question must have exactly one affirmative option. The UI adds a freeform Other choice when allowOther is not false.",
     parameters: z.object({
       question: z.string().trim().min(1).max(240),
       description: z.string().trim().max(400).optional(),
@@ -82,7 +82,7 @@ export const browserToolContracts = {
   },
   configure_board_settings: {
     description:
-      "Open Homarr's native board settings and custom CSS review form. Always call board_getBoardSettings first, then pass only the requested proposed changes here. The user can edit the complete stylesheet and all supported settings. Use the returned flat object directly with board_savePartialBoardSettings; do not ask for confirmation in prose.",
+      "Open Homarr's native board settings and custom CSS review form. This form is the user's confirmation step. Always call board_getBoardSettings first, then call this tool directly with only the requested proposed changes, including the complete resulting stylesheet in changes.customCss for a CSS request. Do not call ask_user between those tools when the requested changes are known. The user can edit the complete stylesheet and all supported settings. Use the returned flat object directly with board_savePartialBoardSettings.",
     parameters: z.object({
       boardId: z.string().trim().min(1).max(64),
       boardName: z.string().trim().min(1).max(255),

apps/nextjs/src/components/assistant/assistant-widget-tool.spec.ts

@@ -20,6 +20,7 @@ describe("getAssistantWidgetConfiguration", () => {
 
   test("preserves generated notebook content and fills its hidden defaults", () => {
     const result = getAssistantWidgetConfiguration(
+      widgetImports.notebook.definition,
       {
         boardId: "board-1",
         boardName: "Home",
@@ -41,6 +42,7 @@ describe("getAssistantWidgetConfiguration", () => {
 
   test("keeps only accessible, compatible integrations and respects the widget maximum", () => {
     const result = getAssistantWidgetConfiguration(
+      widgetImports.audioStats.definition,
       {
         boardId: "board-1",
         boardName: "Home",
@@ -88,11 +90,13 @@ describe("getAssistantWidgetConfiguration", () => {
 
   test("treats integration-backed widgets as required unless explicitly optional", () => {
     const mediaServer = getAssistantWidgetConfiguration(
+      widgetImports.mediaServer.definition,
       { boardId: "board-1", boardName: "Home", kind: "mediaServer", summary: "Show Plex streams" },
       settings,
       [],
     );
     const calendar = getAssistantWidgetConfiguration(
+      widgetImports.calendar.definition,
       { boardId: "board-1", boardName: "Home", kind: "calendar", summary: "Show releases" },
       settings,
       [],

apps/nextjs/src/components/assistant/assistant-widget-tool.tsx

@@ -1,9 +1,11 @@
 "use client";
 
-import { useMemo } from "react";
+import { Suspense, use, useMemo } from "react";
 import type { ToolCallMessagePartProps } from "@assistant-ui/react";
 import { Alert, Box, Button, Group, Skeleton, Stack, Text, ThemeIcon } from "@mantine/core";
 import { IconAlertTriangle, IconCheck, IconSettings } from "@tabler/icons-react";
+import { ErrorBoundary } from "react-error-boundary";
+import type { FallbackProps } from "react-error-boundary";
 
 import { clientApi } from "@homarr/api/client";
 import { useSession } from "@homarr/auth/client";
@@ -13,7 +15,8 @@ import { useModalAction } from "@homarr/modals";
 import type { SettingsContextProps } from "@homarr/settings/creator";
 import { useSettings } from "@homarr/settings";
 import { useI18n } from "@homarr/translation/client";
-import { reduceWidgetOptionsWithDefaultValues, widgetImports } from "@homarr/widgets";
+import type { WidgetDefinition } from "@homarr/widgets/definition";
+import { loadWidgetDefinition, reduceWidgetOptionsWithDefinition } from "@homarr/widgets/manifest";
 import type { IntegrationSelectOption } from "@homarr/widgets/widget-integration-select";
 import { WidgetEditModal } from "@homarr/widgets/modals";
 
@@ -29,11 +32,11 @@ interface AssistantIntegration extends IntegrationSelectOption {
 }
 
 export const getAssistantWidgetConfiguration = (
+  definition: WidgetDefinition,
   args: ConfigureWidgetArgs,
   settings: Pick<SettingsContextProps, "enableStatusByDefault" | "forceDisableStatus">,
   integrations: AssistantIntegration[],
 ) => {
-  const definition = widgetImports[args.kind].definition;
   const integrationSupport = "supportedIntegrations" in definition;
   const supportedIntegrations = integrationSupport
     ? (definition.supportedIntegrations as readonly IntegrationKind[])
@@ -54,35 +57,91 @@ export const getAssistantWidgetConfiguration = (
       integrationSupport && (!("integrationsRequired" in definition) || definition.integrationsRequired !== false),
     value: {
       advancedOptions: { title: null, customCssClasses: [], borderColor: "" },
-      options: reduceWidgetOptionsWithDefaultValues(args.kind, settings, args.options),
+      options: reduceWidgetOptionsWithDefinition(definition, settings, args.options),
       integrationIds,
     },
   };
 };
 
-export const AssistantConfigureWidgetTool = ({
+type AssistantConfigureWidgetToolProps = ToolCallMessagePartProps<ConfigureWidgetArgs, ConfigureWidgetResult>;
+
+export const AssistantConfigureWidgetTool = (props: AssistantConfigureWidgetToolProps) => {
+  const hasCompleteArguments = hasCompleteAssistantToolArguments(props.status);
+  const completeArgs =
+    props.result === undefined && !hasFailedAssistantToolArguments(props.status) && hasCompleteArguments
+      ? props.args
+      : undefined;
+
+  if (!completeArgs) return <AssistantConfigureWidgetToolContent {...props} definition={undefined} />;
+
+  return (
+    <ErrorBoundary FallbackComponent={AssistantWidgetDefinitionErrorFallback} resetKeys={[completeArgs.kind]}>
+      <Suspense fallback={<AssistantConfigureWidgetSkeleton />}>
+        <LoadedAssistantConfigureWidgetTool {...props} args={completeArgs} />
+      </Suspense>
+    </ErrorBoundary>
+  );
+};
+
+const AssistantWidgetDefinitionErrorFallback = ({ resetErrorBoundary }: FallbackProps) => {
+  const t = useI18n("assistant.configureWidget");
+  const actionT = useI18n("common.action");
+
+  return (
+    <Alert color="red" variant="light" title={t("definitionLoadErrorTitle")} icon={<IconAlertTriangle size={18} />}>
+      <Stack gap="sm">
+        <Text size="sm">{t("definitionLoadErrorDescription")}</Text>
+        <Button variant="light" color="red" size="compact-sm" w="fit-content" onClick={resetErrorBoundary}>
+          {actionT("tryAgain")}
+        </Button>
+      </Stack>
+    </Alert>
+  );
+};
+
+const LoadedAssistantConfigureWidgetTool = (
+  props: AssistantConfigureWidgetToolProps & { args: ConfigureWidgetArgs },
+) => {
+  const definition = use(loadWidgetDefinition(props.args.kind));
+  return <AssistantConfigureWidgetToolContent {...props} definition={definition} />;
+};
+
+const AssistantConfigureWidgetSkeleton = () => {
+  const t = useI18n("assistant.configureWidget");
+  return (
+    <Box className={classes.appTool} aria-label={t("preparing")}>
+      <Stack gap="sm">
+        <Skeleton height={18} width="45%" />
+        <Skeleton height={14} width="76%" />
+        <Skeleton height={38} />
+      </Stack>
+    </Box>
+  );
+};
+
+const AssistantConfigureWidgetToolContent = ({
   args,
   result,
   addResult,
   status,
   toolCallId,
-}: ToolCallMessagePartProps<ConfigureWidgetArgs, ConfigureWidgetResult>) => {
+  definition,
+}: AssistantConfigureWidgetToolProps & { definition: WidgetDefinition | undefined }) => {
   const t = useI18n("assistant.configureWidget");
   const actionT = useI18n("common.action");
   const fullT = useI18n();
   const { data: session } = useSession();
   const settings = useSettings();
   const hasCompleteArguments = hasCompleteAssistantToolArguments(status);
-  const definition = args?.kind ? widgetImports[args.kind].definition : undefined;
   const needsIntegrations = definition !== undefined && "supportedIntegrations" in definition;
   const integrations = clientApi.integration.all.useQuery(undefined, {
     enabled: result === undefined && hasCompleteArguments && needsIntegrations,
     retry: false,
   });
   const configuration = useMemo(() => {
-    if (!args || !hasCompleteArguments || (needsIntegrations && !integrations.data)) return null;
-    return getAssistantWidgetConfiguration(args, settings, integrations.data ?? []);
-  }, [args, hasCompleteArguments, integrations.data, needsIntegrations, settings]);
+    if (!args || !definition || !hasCompleteArguments || (needsIntegrations && !integrations.data)) return null;
+    return getAssistantWidgetConfiguration(definition, args, settings, integrations.data ?? []);
+  }, [args, definition, hasCompleteArguments, integrations.data, needsIntegrations, settings]);
   const missingRequiredIntegration =
     configuration?.integrationsRequired === true && configuration.value.integrationIds.length === 0;
   const { openModal: openWidgetModal } = useModalAction(WidgetEditModal);
@@ -134,15 +193,7 @@ export const AssistantConfigureWidgetTool = ({
   }
 
   if (!hasCompleteArguments || !args || (needsIntegrations && integrations.isPending)) {
-    return (
-      <Box className={classes.appTool} aria-label={t("preparing")}>
-        <Stack gap="sm">
-          <Skeleton height={18} width="45%" />
-          <Skeleton height={14} width="76%" />
-          <Skeleton height={38} />
-        </Stack>
-      </Box>
-    );
+    return <AssistantConfigureWidgetSkeleton />;
   }
 
   if (integrations.isError) {
@@ -158,7 +209,7 @@ export const AssistantConfigureWidgetTool = ({
     );
   }
 
-  if (!configuration) return null;
+  if (!configuration || !definition) return null;
 
   const openConfigurationModal = (
     value = configuration.value,
@@ -167,7 +218,7 @@ export const AssistantConfigureWidgetTool = ({
     openWidgetModal(
       {
         kind: args.kind,
-        definition: widgetImports[args.kind].definition,
+        definition,
         value,
         integrationData,
         integrationSupport: configuration.integrationSupport,
@@ -240,7 +291,7 @@ export const AssistantConfigureWidgetTool = ({
     );
   }
 
-  const WidgetIcon = widgetImports[args.kind].definition.icon;
+  const WidgetIcon = definition.icon;
   return (
     <Box className={classes.appTool}>
       <Group gap="sm" align="flex-start" wrap="nowrap">

apps/nextjs/src/components/assistant/assistant-widget.tsx

@@ -137,7 +137,7 @@ const CompactAssistantWidget = ({
     <Box className={classes.widgetPanel}>
       <Group className={classes.compactState} justify="space-between" wrap="nowrap" gap="sm">
         <Group wrap="nowrap" gap="xs" miw={0}>
-          <ThemeIcon variant="light" color="red" radius="xl" size="lg" flex="0 0 auto">
+          <ThemeIcon variant="light" radius="xl" size="lg" flex="0 0 auto">
             <IconRobot size={19} />
           </ThemeIcon>
           <Stack className={classes.compactCopy} gap={1}>
@@ -167,13 +167,7 @@ interface AssistantWidgetStateProps {
   children?: ReactNode;
 }
 
-const AssistantWidgetState = ({
-  icon: Icon,
-  title,
-  description,
-  color = "red",
-  children,
-}: AssistantWidgetStateProps) => (
+const AssistantWidgetState = ({ icon: Icon, title, description, color, children }: AssistantWidgetStateProps) => (
   <Center className={classes.widgetState} h="100%" p="md">
     <Stack align="center" gap="sm" ta="center" maw={360}>
       <ThemeIcon variant="light" color={color} radius="xl" size="xl">

apps/nextjs/src/components/board/board-apps-spotlight-registrar.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+
+import { clientApi } from "@homarr/api/client";
+import { useRequiredBoard } from "@homarr/boards/context";
+import { getSafeAppHref } from "@homarr/common";
+import type { ContextSpecificItem } from "@homarr/spotlight";
+import { useRegisterSpotlightContextResults } from "@homarr/spotlight";
+import { hasPendingSpotlightOpen, spotlightOpenEvent } from "@homarr/spotlight/open";
+
+export const BoardAppsSpotlightRegistrar = () => {
+  const board = useRequiredBoard();
+  const [isSpotlightActivated, setIsSpotlightActivated] = useState(() => hasPendingSpotlightOpen());
+
+  useEffect(() => {
+    if (isSpotlightActivated) return;
+
+    const activateSpotlightQueries = () => setIsSpotlightActivated(true);
+    window.addEventListener(spotlightOpenEvent, activateSpotlightQueries);
+
+    if (hasPendingSpotlightOpen()) activateSpotlightQueries();
+
+    return () => window.removeEventListener(spotlightOpenEvent, activateSpotlightQueries);
+  }, [isSpotlightActivated]);
+
+  const openInNewTabByAppId = useMemo(() => {
+    const result = new Map<string, boolean>();
+
+    for (const item of board.items) {
+      if (item.kind !== "app" || typeof item.options.appId !== "string" || item.options.appId.length === 0) continue;
+
+      const existingOpenInNewTab = result.get(item.options.appId) ?? false;
+      result.set(item.options.appId, existingOpenInNewTab || item.options.openInNewTab === true);
+    }
+
+    return result;
+  }, [board.items]);
+  const appIds = useMemo(() => Array.from(openInNewTabByAppId.keys()), [openInNewTabByAppId]);
+  const activeAppIds = isSpotlightActivated ? appIds : [];
+  const appQueries = clientApi.useQueries((trpc) => activeAppIds.map((id) => trpc.app.byId({ id })));
+  const apps = appQueries.flatMap((query) => query.data ?? []);
+  const spotlightItems = useMemo<ContextSpecificItem[]>(() => {
+    return apps.flatMap((app) => {
+      const href = getSafeAppHref(app.href);
+      if (!href) return [];
+
+      return [
+        {
+          id: app.id,
+          dedupeKey: `app:${app.id}`,
+          name: app.name,
+          icon: app.iconUrl,
+          interaction() {
+            return {
+              type: "link" as const,
+              href,
+              // Opening a new tab wins if any widget instance requests it.
+              newTab: openInNewTabByAppId.get(app.id) ?? false,
+            };
+          },
+        },
+      ];
+    });
+  }, [apps, openInNewTabByAppId]);
+
+  useRegisterSpotlightContextResults("board-apps", spotlightItems, [spotlightItems]);
+
+  return null;
+};

apps/nextjs/src/components/board/board-layout-thumbnail.module.css

@@ -1,5 +1,6 @@
 .canvas {
-  min-height: 8rem;
+  width: 100%;
+  min-width: 0;
   aspect-ratio: 16 / 7;
   overflow: hidden;
   color: var(--mantine-color-dimmed);
@@ -83,9 +84,3 @@
   gap: rem(1px);
   overflow: hidden;
 }
-
-@media (max-width: $mantine-breakpoint-xs) {
-  .canvas {
-    min-height: 7rem;
-  }
-}

apps/nextjs/src/components/board/board-layout-thumbnail.tsx

@@ -11,11 +11,12 @@ import classes from "./board-layout-thumbnail.module.css";
 interface BoardLayoutThumbnailProps {
   preview: BoardPreviewData | null;
   label: string;
+  fitFullLayout?: boolean;
 }
 
 const maxThumbnailRows = 12;
 
-export const BoardLayoutThumbnail = ({ preview, label }: BoardLayoutThumbnailProps) => {
+export const BoardLayoutThumbnail = ({ preview, label, fitFullLayout = false }: BoardLayoutThumbnailProps) => {
   const layout = preview?.layouts.find((candidate) => candidate.role === "base") ?? preview?.layouts.at(0);
   if (!preview || !layout) {
     return (
@@ -26,6 +27,7 @@ export const BoardLayoutThumbnail = ({ preview, label }: BoardLayoutThumbnailPro
   }
 
   const elements = projectBoardLayout(preview, layout, layout);
+  const thumbnailRowLimit = fitFullLayout ? Number.POSITIVE_INFINITY : maxThumbnailRows;
   const roots = preview.sections
     .filter((section) => section.kind === "empty")
     .toSorted((first, second) => (first.xOffset ?? 0) - (second.xOffset ?? 0) || first.id.localeCompare(second.id));
@@ -65,12 +67,12 @@ export const BoardLayoutThumbnail = ({ preview, label }: BoardLayoutThumbnailPro
               element.xOffset >= 0 &&
               element.xOffset < columnCount &&
               element.yOffset >= 0 &&
-              element.yOffset < maxThumbnailRows &&
+              element.yOffset < thumbnailRowLimit &&
               element.width > 0 &&
               element.height > 0,
           );
           const rowCount = Math.min(
-            maxThumbnailRows,
+            thumbnailRowLimit,
             Math.max(4, ...laneElements.map((element) => element.yOffset + element.height)),
           );
 

apps/nextjs/src/components/board/board-switcher.module.css

@@ -1,7 +1,26 @@
+.modalContent {
+  overflow: hidden;
+  border: rem(1px) solid color-mix(in srgb, var(--mantine-color-default-border) 70%, transparent);
+  border-radius: rem(24px);
+  background: color-mix(in srgb, var(--mantine-color-body) 58%, transparent);
+  box-shadow: 0 rem(18px) rem(56px) rgb(0 0 0 / 22%);
+  backdrop-filter: blur(rem(20px)) saturate(140%);
+}
+
+.modalBody {
+  padding: var(--mantine-spacing-sm);
+}
+
 .content {
   outline: none;
 }
 
+.searchInput {
+  border-color: color-mix(in srgb, var(--mantine-color-default-border) 72%, transparent);
+  background: color-mix(in srgb, var(--mantine-color-body) 54%, transparent);
+  backdrop-filter: blur(rem(8px));
+}
+
 .option {
   min-width: 0;
   border-radius: var(--mantine-radius-md);
@@ -11,6 +30,12 @@
 .card {
   height: 100%;
   overflow: hidden;
+  box-shadow: var(--mantine-shadow-sm);
+}
+
+.metadataBadge {
+  width: rem(22px);
+  padding-inline: 0;
 }
 
 .option:hover .card,

apps/nextjs/src/components/board/board-switcher.tsx

@@ -3,29 +3,32 @@
 import type { KeyboardEvent, ReactNode, RefObject } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
+  Badge,
   Card,
   Center,
   Group,
-  Kbd,
   Loader,
   Modal,
   ScrollArea,
   SimpleGrid,
   Stack,
   Text,
+  TextInput,
   ThemeIcon,
+  Tooltip,
   UnstyledButton,
   useMatches,
   VisuallyHidden,
 } from "@mantine/core";
 import { useHotkeys } from "@mantine/hooks";
-import { IconArrowDown, IconArrowRight, IconLayoutBoard, IconReplace } from "@tabler/icons-react";
+import { IconDeviceMobile, IconHomeFilled, IconLayoutBoard, IconSearch } from "@tabler/icons-react";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { useOptionalBoard } from "@homarr/boards/context";
+import { useRegisterSpotlightContextActions } from "@homarr/spotlight";
 import { useI18n } from "@homarr/translation/client";
-import { Link } from "@homarr/ui";
+import { Link, UserAvatar } from "@homarr/ui";
 
 import { BoardLayoutThumbnail } from "~/components/board/board-layout-thumbnail";
 
@@ -39,6 +42,8 @@ interface BoardSwitcherProps {
 
 export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
   const t = useI18n("board.action.switcher");
+  const tBoard = useI18n("board");
+  const manageBoardsT = useI18n("management.page.board");
   const currentBoard = useOptionalBoard();
   const [isOpen, setIsOpen] = useState(false);
   const [search, setSearch] = useState("");
@@ -50,20 +55,27 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
     data: boards = [],
     isPending,
     isError,
-  } = clientApi.board.getManageOverview.useQuery(undefined, {
-    enabled: isOpen,
-  });
+  } = clientApi.board.getManageOverview.useQuery(
+    { fullPreview: true },
+    {
+      enabled: isOpen,
+    },
+  );
 
-  const availableBoards = useMemo(
-    () => boards.filter((board) => board.id !== currentBoard?.id),
+  const switcherBoards = useMemo(
+    () => [
+      ...boards.filter((board) => board.id !== currentBoard?.id),
+      ...boards.filter((board) => board.id === currentBoard?.id),
+    ],
     [boards, currentBoard?.id],
   );
   const filteredBoards = useMemo(() => {
     const normalizedSearch = search.trim().toLocaleLowerCase();
-    if (normalizedSearch.length === 0) return availableBoards;
-    return availableBoards.filter((board) => board.name.toLocaleLowerCase().includes(normalizedSearch));
-  }, [availableBoards, search]);
+    if (normalizedSearch.length === 0) return switcherBoards;
+    return switcherBoards.filter((board) => board.name.toLocaleLowerCase().includes(normalizedSearch));
+  }, [search, switcherBoards]);
   const columnCount = Math.max(1, Math.min(filteredBoards.length, responsiveColumnCount));
+  const modalColumnCount = Math.max(1, Math.min(switcherBoards.length, responsiveColumnCount));
 
   const openSwitcher = useCallback(() => {
     setIsOpen(true);
@@ -73,7 +85,21 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
     setSearch("");
     setActiveIndex(0);
   }, []);
-  const preloadBoards = () => void utils.board.getManageOverview.prefetch();
+  const preloadBoards = () => void utils.board.getManageOverview.prefetch({ fullPreview: true });
+
+  const spotlightAction = useMemo(
+    () => ({
+      id: "open-board-switcher",
+      name: tBoard("action.switch"),
+      icon: IconLayoutBoard,
+      interaction: () => ({
+        type: "javaScript" as const,
+        onSelect: openSwitcher,
+      }),
+    }),
+    [openSwitcher, tBoard],
+  );
+  useRegisterSpotlightContextActions("board-switcher", [spotlightAction], [spotlightAction]);
 
   useHotkeys([[boardSwitcherHotkey, openSwitcher, { preventDefault: true }]]);
 
@@ -88,14 +114,17 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
   }, [activeIndex, filteredBoards.length, isOpen]);
 
   const handleModalKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
-    if (event.key === "Backspace") {
+    const isSearchInput =
+      event.target instanceof HTMLInputElement && event.target.dataset.boardSwitcherSearch !== undefined;
+
+    if (!isSearchInput && event.key === "Backspace") {
       event.preventDefault();
       setSearch((current) => current.slice(0, -1));
       setActiveIndex(0);
       return;
     }
 
-    if (event.key.length === 1 && !event.altKey && !event.ctrlKey && !event.metaKey) {
+    if (!isSearchInput && event.key.length === 1 && !event.altKey && !event.ctrlKey && !event.metaKey) {
       event.preventDefault();
       setSearch((current) => `${current}${event.key}`);
       setActiveIndex(0);
@@ -141,7 +170,7 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
   };
 
   const results = getBoardSwitcherResults({
-    availableBoardCount: availableBoards.length,
+    availableBoardCount: switcherBoards.length,
     filteredBoards,
     isError,
     isPending,
@@ -152,6 +181,7 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
     setActiveIndex,
     optionRefs,
     columnCount,
+    manageBoardsT,
   });
 
   return (
@@ -161,54 +191,40 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
       <Modal
         opened={isOpen}
         onClose={closeSwitcher}
-        title={
-          <Group gap="sm" wrap="nowrap">
-            <ThemeIcon variant="light" radius="md">
-              <IconReplace size={18} stroke={1.5} />
-            </ThemeIcon>
-            <Text fw={700}>{t("title")}</Text>
-          </Group>
-        }
-        size={1280}
-        yOffset={32}
-        overlayProps={{ backgroundOpacity: 0.18, blur: 2 }}
+        withCloseButton={false}
+        yOffset="15vh"
+        aria-label={t("title")}
+        size={`${modalColumnCount * 15 + Math.max(0, modalColumnCount - 1) * 0.75}rem`}
+        overlayProps={{ backgroundOpacity: 0, blur: 2 }}
         transitionProps={{ transition: "fade", duration: 100, timingFunction: "ease" }}
+        classNames={{ content: classes.modalContent, body: classes.modalBody }}
       >
         <Stack
-          data-autofocus
           tabIndex={-1}
-          gap="md"
+          gap="xs"
           onKeyDown={handleModalKeyDown}
           className={classes.content}
           aria-describedby="board-switcher-instructions"
         >
           <VisuallyHidden id="board-switcher-instructions">{t("keyboard.instructions")}</VisuallyHidden>
-          <ScrollArea.Autosize mah={640} type="auto" offsetScrollbars>
+          <TextInput
+            data-autofocus
+            data-board-switcher-search
+            value={search}
+            onChange={(event) => {
+              setSearch(event.currentTarget.value);
+              setActiveIndex(0);
+            }}
+            leftSection={<IconSearch size="1rem" stroke={1.6} />}
+            placeholder={t("title")}
+            aria-label={t("title")}
+            aria-controls="board-switcher-results"
+            radius="xl"
+            classNames={{ input: classes.searchInput }}
+          />
+          <ScrollArea.Autosize mah="min(80vh, 42rem)" type="never">
             {results}
           </ScrollArea.Autosize>
-
-          <Group justify={currentBoard ? "space-between" : "flex-end"} gap="xs" visibleFrom="sm">
-            {currentBoard && (
-              <Text size="xs" c="dimmed">
-                {t("currentHidden", { name: currentBoard.name })}
-              </Text>
-            )}
-            <Group gap="xs">
-              <Kbd size="xs">
-                <IconArrowRight size={12} />
-              </Kbd>
-              <Kbd size="xs">
-                <IconArrowDown size={12} />
-              </Kbd>
-              <Text size="xs" c="dimmed">
-                {t("keyboard.navigate")}
-              </Text>
-              <Kbd size="xs">Enter</Kbd>
-              <Text size="xs" c="dimmed">
-                {t("keyboard.open")}
-              </Text>
-            </Group>
-          </Group>
         </Stack>
       </Modal>
     </>
@@ -227,6 +243,7 @@ interface BoardSwitcherResultsProps {
   setActiveIndex: (index: number) => void;
   optionRefs: RefObject<Array<HTMLAnchorElement | null>>;
   columnCount: number;
+  manageBoardsT: ReturnType<typeof useI18n<"management.page.board">>;
 }
 
 const getBoardSwitcherResults = ({
@@ -241,6 +258,7 @@ const getBoardSwitcherResults = ({
   setActiveIndex,
   optionRefs,
   columnCount,
+  manageBoardsT,
 }: BoardSwitcherResultsProps) => {
   if (isPending) {
     return (
@@ -287,7 +305,7 @@ const getBoardSwitcherResults = ({
   }
 
   return (
-    <SimpleGrid id="board-switcher-results" aria-label={t("results")} cols={columnCount} spacing="md" p={4}>
+    <SimpleGrid id="board-switcher-results" aria-label={t("results")} cols={columnCount} spacing="xs" p={2}>
       {filteredBoards.map((board, index) => (
         <UnstyledButton
           key={board.id}
@@ -296,7 +314,7 @@ const getBoardSwitcherResults = ({
           }}
           className={classes.option}
           w="100%"
-          maw={320}
+          maw={240}
           mx="auto"
           component={Link}
           href={`/boards/${encodeURIComponent(board.name)}`}
@@ -306,21 +324,50 @@ const getBoardSwitcherResults = ({
           onFocus={() => setActiveIndex(index)}
           onPointerEnter={() => setActiveIndex(index)}
         >
-          <Card padding={0} withBorder radius="md" className={classes.card}>
+          <Card padding={0} withBorder radius="lg" className={classes.card}>
             <Card.Section>
               <BoardLayoutThumbnail
                 preview={board.preview}
                 label={t("preview", { name: board.name, count: String(board.preview?.items.length ?? 0) })}
+                fitFullLayout
               />
             </Card.Section>
-            <Card.Section withBorder p="sm">
-              <Group gap="sm" wrap="nowrap">
-                <ThemeIcon variant="light" radius="md" size="md">
-                  <IconLayoutBoard size={16} stroke={1.5} />
-                </ThemeIcon>
-                <Text fw={650} truncate>
+            <Card.Section withBorder px="sm" py={6}>
+              <Group justify="space-between" gap="xs" wrap="nowrap">
+                <Text fw={600} size="sm" truncate>
                   {board.name}
                 </Text>
+                <Group gap={4} wrap="nowrap">
+                  {board.isHome && (
+                    <Tooltip label={manageBoardsT("action.setHomeBoard.badge.tooltip")}>
+                      <Badge
+                        className={classes.metadataBadge}
+                        color="yellow"
+                        variant="light"
+                        aria-label={manageBoardsT("action.setHomeBoard.badge.label")}
+                      >
+                        <IconHomeFilled size="0.7rem" />
+                      </Badge>
+                    </Tooltip>
+                  )}
+                  {board.isMobileHome && (
+                    <Tooltip label={manageBoardsT("action.setMobileHomeBoard.badge.tooltip")}>
+                      <Badge
+                        className={classes.metadataBadge}
+                        color="yellow"
+                        variant="light"
+                        aria-label={manageBoardsT("action.setMobileHomeBoard.badge.label")}
+                      >
+                        <IconDeviceMobile size="0.7rem" />
+                      </Badge>
+                    </Tooltip>
+                  )}
+                  {board.creator && (
+                    <Tooltip label={board.creator.name ?? manageBoardsT("preview.unknownCreator")}>
+                      <UserAvatar user={board.creator} size="xs" />
+                    </Tooltip>
+                  )}
+                </Group>
               </Group>
             </Card.Section>
           </Card>

apps/nextjs/src/components/board/items/item-content.module.css

@@ -1,17 +1,22 @@
-.badge {
-  @mixin dark {
-    --background-color: rgb(from var(--mantine-color-dark-6) r g b / var(--opacity));
-    --border-color: rgb(from var(--mantine-color-dark-4) r g b / var(--opacity));
-  }
-  @mixin light {
-    --background-color: rgb(from var(--mantine-color-white) r g b / var(--opacity));
-    --border-color: rgb(from var(--mantine-color-gray-3) r g b / var(--opacity));
-  }
-  background-color: var(--background-color) !important;
-  border-color: var(--border-color) !important;
+.refreshIndicator {
+  position: absolute;
+  top: 0.25rem;
+  right: 0.25rem;
+  z-index: 3;
+  display: grid;
+  place-items: center;
+  width: 1.25rem;
+  height: 1.25rem;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--mantine-color-body) 78%, transparent);
+  pointer-events: none;
 }
 
 .settingsButton {
+  position: absolute;
+  top: -34px;
+  right: 14px;
+  z-index: 201;
   opacity: 0;
   pointer-events: none;
   transition: opacity 120ms ease;
@@ -58,3 +63,11 @@
     transition: none;
   }
 }
+
+@media (max-width: 768px) {
+  .settingsButton {
+    right: 4px;
+    opacity: 1;
+    pointer-events: auto;
+  }
+}

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

@@ -1,11 +1,10 @@
-import type { ComponentType, CSSProperties, MutableRefObject } from "react";
+import type { ComponentType, CSSProperties, MutableRefObject, PropsWithChildren } from "react";
 import { memo, Suspense, use, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import dynamic from "next/dynamic";
-import type { CardProps } from "@mantine/core";
-import { Badge, Box, Button, Card, Center, Loader, Portal } from "@mantine/core";
+import { Box, Button, Center, Loader, Portal } from "@mantine/core";
 import { useElementSize, useIsomorphicEffect } from "@mantine/hooks";
-import { QueryErrorResetBoundary, useQueryClient } from "@tanstack/react-query";
+import { QueryErrorResetBoundary, useIsFetching, useQueryClient } from "@tanstack/react-query";
 import combineClasses from "clsx";
 import { NoIntegrationSelectedError } from "@homarr/widgets/errors/classes";
 import type { FallbackProps } from "react-error-boundary";
@@ -20,13 +19,16 @@ import { WidgetError } from "@homarr/widgets/errors";
 import {
   createWidgetRuntimeState,
   getWidgetQueryKeys,
+  getWidgetRuntimeQueries,
   supportsAdvancedFocus as definitionSupportsAdvancedFocus,
 } from "@homarr/widgets/definition";
 import type { WidgetComponentProps, WidgetDefinition, WidgetRuntimeRef } from "@homarr/widgets/definition";
 import { loadWidgetResources, reduceWidgetOptionsWithDefinition } from "@homarr/widgets/manifest";
+import { WidgetCardShell, WidgetTitleBadge } from "@homarr/widgets/widget-card-shell";
 
 import type { SectionItem } from "~/app/[locale]/boards/_types";
 import { getLogicalTrackSize } from "~/components/board/layout";
+import { useBoardCanvasScale } from "~/components/board/layout/scaled-board-canvas";
 import advancedFocusClasses from "../advanced-focus/advanced-focus.module.css";
 import { useAdvancedFocus } from "../advanced-focus/context";
 import { startAdvancedFocusEntrance } from "../advanced-focus/entrance";
@@ -34,11 +36,11 @@ import { getAdvancedFocusClosePosition, getAdvancedFocusRect } from "../advanced
 import { AdvancedFocusManualSurface } from "../advanced-focus/manual-surface";
 import { redirectShiftWheel } from "../advanced-focus/wheel";
 import { useBoardGridPortalHost } from "../sections/grid/grid-portal-host";
-import classes from "../sections/item.module.css";
 import { useItemActions } from "./item-actions";
 import itemContentClasses from "./item-content.module.css";
 import { WidgetContextMenu } from "./widget-context-menu";
 import { removeWidgetDataQueries } from "./widget-query-recovery";
+import { matchesWidgetItemQuery } from "./widget-query-scope";
 
 const BoardItemMenu = dynamic(() => import("./item-menu").then((module) => module.BoardItemMenu), {
   ssr: false,
@@ -48,47 +50,28 @@ interface BoardItemContentProps {
   item: SectionItem;
 }
 
-const getOverflowFromKind = (kind: SectionItem["kind"], hasCustomCssClasses: boolean) => {
-  if (kind === "systemResources") return { overflowX: "visible", overflowY: "visible" } as const;
-  if (kind === "iframe" || kind === "assistant") return { overflowX: "hidden", overflowY: "hidden" } as const;
-  if (hasCustomCssClasses) return {};
-  return { overflowX: "hidden", overflowY: "auto" } as const;
-};
-
-type BoardItemCardProps = CardProps & {
+type BoardItemCardProps = PropsWithChildren<{
   item: SectionItem;
   innerRef: (element: HTMLDivElement | null) => void;
-};
+}>;
 
-const BoardItemCard = ({ item, innerRef, children, ...cardProps }: BoardItemCardProps) => {
+const BoardItemCard = ({ item, innerRef, children }: BoardItemCardProps) => {
   const board = useRequiredBoard();
 
   return (
-    <Card
-      {...cardProps}
-      ref={innerRef}
+    <WidgetCardShell
+      innerRef={innerRef}
+      kind={item.kind}
+      advancedOptions={item.advancedOptions}
+      opacity={board.opacity / 100}
       w="100%"
       h="100%"
       data-grid-item-content
-      className={combineClasses(
-        classes.itemCard,
-        `${item.kind}-wrapper`,
-        "board-grid-item-content",
-        item.advancedOptions.customCssClasses.join(" "),
-      )}
       radius={board.itemRadius}
-      styles={{
-        root: {
-          "--opacity": board.opacity / 100,
-          containerType: "size",
-          ...getOverflowFromKind(item.kind, item.advancedOptions.customCssClasses.length > 0),
-          "--border-color": item.advancedOptions.borderColor !== "" ? item.advancedOptions.borderColor : undefined,
-        },
-      }}
       p={0}
     >
       {children}
-    </Card>
+    </WidgetCardShell>
   );
 };
 
@@ -167,6 +150,7 @@ const LoadedBoardItemContent = ({
   const cardRef = useRef<HTMLDivElement>(null);
   const previewEntranceFrameRef = useRef<number | null>(null);
   const board = useRequiredBoard();
+  const boardCanvasScale = useBoardCanvasScale();
   const t = useI18n();
   const [isEditMode] = useEditMode();
   const settings = useSettings();
@@ -174,12 +158,34 @@ const LoadedBoardItemContent = ({
     () => ({ ...item, options: reduceWidgetOptionsWithDefinition(definition, settings, item.options) }),
     [definition, item, settings],
   );
+  const widgetQueryKeys = useMemo(() => getWidgetQueryKeys(definition, item.kind), [definition, item.kind]);
+  const isWidgetRefreshing =
+    useIsFetching({
+      predicate: (query) =>
+        query.state.data !== undefined &&
+        matchesWidgetItemQuery(
+          query.queryKey,
+          widgetQueryKeys,
+          {
+            itemId: item.id,
+            boardId: board.id,
+            integrationIds: item.integrationIds,
+            options: menuItem.options,
+            runtimeQueries: getWidgetRuntimeQueries(widgetRuntimeRef),
+          },
+          definition.queryMatcher,
+        ),
+    }) > 0;
   const [manualSurface, setManualSurface] = useState<HTMLDivElement | null>(null);
   const [surfacePortalTarget, setSurfacePortalTarget] = useState<HTMLDivElement | null>(null);
   const { active, viewportSize, open, close, dismiss, hover, leave } = useAdvancedFocus();
   const { width: viewportWidth, height: viewportHeight } = viewportSize;
   const supportsAdvancedFocus = definitionSupportsAdvancedFocus(definition);
   const widgetName = getWidgetName(item.kind, t);
+  const previewDimensions = useMemo(
+    () => ({ width, height, scale: boardCanvasScale }),
+    [boardCanvasScale, height, width],
+  );
   const advancedViewLabel = t("item.advancedFocus.label", { widget: widgetName });
   const advancedViewId = `advanced-focus-${item.id}`;
   const activeFocus = supportsAdvancedFocus && active?.itemId === item.id ? active : null;
@@ -291,8 +297,11 @@ const LoadedBoardItemContent = ({
       : undefined;
 
   const widgetCard = (
-    <Card
-      ref={cardRef}
+    <WidgetCardShell
+      innerRef={cardRef}
+      kind={item.kind}
+      advancedOptions={item.advancedOptions}
+      opacity={isAdvanced ? 0.98 : board.opacity / 100}
       id={isPreview ? advancedViewId : undefined}
       role={isPreview ? "region" : undefined}
       aria-label={isPreview ? advancedViewLabel : undefined}
@@ -303,21 +312,9 @@ const LoadedBoardItemContent = ({
       h={isManual ? "100%" : isAdvanced ? undefined : "100%"}
       w={isManual ? "100%" : isAdvanced ? undefined : "100%"}
       className={combineClasses(
-        classes.itemCard,
-        `${item.kind}-wrapper`,
-        "board-grid-item-content",
         isPreview && advancedFocusClasses.surface,
         activeFocus?.phase === "closing" && isPreview && advancedFocusClasses.surfaceClosing,
-        item.advancedOptions.customCssClasses.join(" "),
       )}
-      styles={{
-        root: {
-          "--opacity": isAdvanced ? 0.98 : board.opacity / 100,
-          containerType: "size",
-          ...getOverflowFromKind(item.kind, item.advancedOptions.customCssClasses.length > 0),
-          "--border-color": item.advancedOptions.borderColor !== "" ? item.advancedOptions.borderColor : undefined,
-        },
-      }}
       style={previewStyle}
     >
       <Box ref={contentRef} w="100%" h="100%" mih={0}>
@@ -345,15 +342,21 @@ const LoadedBoardItemContent = ({
           />
         </ErrorBoundary>
       </Box>
-    </Card>
+      {isWidgetRefreshing && (
+        <Box className={itemContentClasses.refreshIndicator} data-widget-refreshing aria-hidden>
+          <Loader size="xs" />
+        </Box>
+      )}
+    </WidgetCardShell>
   );
 
   return (
     <>
-      {isEditMode && <BoardItemMenu item={menuItem} definition={definition} />}
+      {isEditMode && <BoardItemMenu item={menuItem} definition={definition} previewDimensions={previewDimensions} />}
       <WidgetContextMenu
         item={item}
         definition={definition}
+        previewDimensions={previewDimensions}
         widgetStateRef={widgetStateRef}
         widgetRuntimeRef={widgetRuntimeRef}
         sourceRef={sourceRef}
@@ -418,25 +421,12 @@ const LoadedBoardItemContent = ({
           )}
         </Box>
       </WidgetContextMenu>
-      {!isAdvanced && item.advancedOptions.title?.trim() && (
-        <Badge
-          pos="absolute"
-          style={{ zIndex: "var(--mantine-z-index-app)" }}
-          top={2}
-          left={16}
-          size="xs"
+      {!isAdvanced && (
+        <WidgetTitleBadge
+          advancedOptions={item.advancedOptions}
+          opacity={board.opacity / 100}
           radius={board.itemRadius}
-          styles={{
-            root: {
-              "--border-color": item.advancedOptions.borderColor !== "" ? item.advancedOptions.borderColor : undefined,
-              "--opacity": board.opacity / 100,
-            },
-          }}
-          className={itemContentClasses.badge}
-          c="var(--mantine-color-text)"
-        >
-          {item.advancedOptions.title}
-        </Badge>
+        />
       )}
     </>
   );

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

@@ -21,6 +21,7 @@ import { LazyWidgetEditModal, preloadWidgetEditModal } from "./lazy-widget-edit-
 interface BoardItemMenuProps {
   item: SectionItem;
   definition: WidgetDefinition;
+  previewDimensions: { width: number; height: number; scale?: number };
   resetErrorBoundary?: () => void;
 }
 
@@ -31,7 +32,7 @@ export const BoardItemMenu = (props: BoardItemMenuProps) => {
 
   return <BoardItemMenuInner {...props} />;
 };
-const BoardItemMenuInner = ({ item, definition, resetErrorBoundary }: BoardItemMenuProps) => {
+const BoardItemMenuInner = ({ item, definition, previewDimensions, resetErrorBoundary }: BoardItemMenuProps) => {
   const { data: session } = useSession();
   const canDuplicate = item.kind !== "customApi" || (session?.user.permissions.includes("admin") ?? false);
   const refResetErrorBoundaryOnNextRender = useRef(false);
@@ -89,6 +90,7 @@ const BoardItemMenuInner = ({ item, definition, resetErrorBoundary }: BoardItemM
         integrationSupport: "supportedIntegrations" in definition,
         settings,
         itemId: item.id,
+        previewDimensions,
         appId: item.kind === "app" ? (item.options.appId as string | undefined) : undefined,
       },
       {
@@ -106,10 +108,6 @@ const BoardItemMenuInner = ({ item, definition, resetErrorBoundary }: BoardItemM
           variant="default"
           size={24}
           radius="sm"
-          pos="absolute"
-          top={4}
-          right={4}
-          style={{ zIndex: 30 }}
           className={itemContentClasses.settingsButton}
           data-menu-open={isMenuOpen || undefined}
           data-board-widget-settings

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

@@ -11,6 +11,7 @@ import { useI18n } from "@homarr/translation/client";
 import type { Board, ContainerSectionItem, SectionItem } from "~/app/[locale]/boards/_types";
 import { getLayoutRowCount } from "../layout";
 import { resolvePinnedGridCollisions } from "../sections/grid/dnd";
+import { useRegisteredGridEditors } from "../sections/grid/grid-editor-registry";
 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";
@@ -57,26 +58,29 @@ export const ItemMoveModal = createModal<InnerProps>(({ actions, innerProps }) =
   const tContainer = useI18n("section.container");
   const tMoveResize = useI18n("item.moveResize");
   const { board, commitSectionGrids, currentLayoutId, entry, sourceSectionId } = innerProps;
+  const registeredGridEditors = useRegisteredGridEditors();
   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 targets = 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),
+        }),
+    },
+    registeredGridEditors,
   );
   const targetById = useMemo(() => new Map(targets.map((target) => [target.id, target])), [targets]);
   const initialTarget = targetById.get(sourceSectionId) ?? targets[0];
@@ -252,6 +256,7 @@ export const getMoveTargets = (
   layoutId: string,
   entry: MovableEntry,
   labels: MoveTargetLabels,
+  registeredGridEditors?: ReadonlyMap<string, { placementMaxRowCount: number | null }>,
 ): MoveTarget[] => {
   const minimum = getEntryMinimumSize(board, layoutId, entry);
 
@@ -260,13 +265,15 @@ export const getMoveTargets = (
       const columnCount = getSectionColumnCount(board, layoutId, section.id);
       const lane = getRootSectionLane(section.xOffset);
       if (columnCount === 0) return [];
+      const registeredEditor = registeredGridEditors?.get(section.id);
+      if (lane !== "main" && registeredGridEditors && !registeredEditor) 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),
+              maxRowCount: registeredEditor?.placementMaxRowCount ?? getSectionMaxRowCount(board, layoutId, section.id),
             },
           ]
         : [];

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

@@ -30,6 +30,7 @@ import {
   getIntegrationName,
   getWidgetName,
   getRootSectionLane,
+  widgetDefaultSizes,
   widgetIntegrationSupport,
   widgetKinds,
   widgetKindsWithOptionalIntegrations,
@@ -47,6 +48,7 @@ import { loadWidgetDefinition, reduceWidgetOptionsWithDefinition } from "@homarr
 import type { EmptySection } from "~/app/[locale]/boards/_types";
 import { useSetupAnalytics } from "~/components/create/setup-analytics";
 import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
+import { getSectionGridColumnCount } from "../sections/grid/section-grid-placements";
 import { useItemActions } from "./item-actions";
 import type { WidgetConnectionStatus } from "./item-select-data";
 import {
@@ -76,6 +78,8 @@ export interface WidgetItemData {
 }
 
 const selectGridCols = { base: 1, xs: 2, sm: 2, md: 3, lg: 4 };
+const defaultWidgetSize = { width: 1, height: 1 };
+const maximumWidgetHeight = 64;
 
 const ItemSelectModalContent = ({
   actions,
@@ -124,6 +128,13 @@ const ItemSelectModalContent = ({
   const effectiveSectionId = placementOptions.some(({ value }) => value === targetSectionId)
     ? targetSectionId
     : (placementOptions[0]?.value ?? null);
+  const maximumWidgetSize = useMemo(() => {
+    if (!effectiveSectionId) return defaultWidgetSize;
+    return {
+      width: Math.max(1, getSectionGridColumnCount(board, currentLayoutId, effectiveSectionId) ?? 1),
+      height: maximumWidgetHeight,
+    };
+  }, [board, currentLayoutId, effectiveSectionId]);
 
   const [loadingSelection, setLoadingSelection] = useState<string | null>(null);
   const selectionLock = useRef(false);
@@ -246,6 +257,7 @@ const ItemSelectModalContent = ({
     try {
       const definition = await loadWidgetDefinition("customApi");
       const itemId = createId();
+      const initialSize = widgetDefaultSizes.customApi ?? defaultWidgetSize;
       const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
       const options = {
         ...defaultOptions,
@@ -263,7 +275,7 @@ const ItemSelectModalContent = ({
             options,
             integrationIds: [],
           },
-          onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }) => {
+          onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }, selectedSize) => {
             const updatedBoard = createItem({
               id: itemId,
               kind: "customApi",
@@ -271,12 +283,14 @@ const ItemSelectModalContent = ({
               options: configuredOptions,
               targetSectionId: effectiveSectionId ?? undefined,
               advancedOptions,
+              size: selectedSize ?? initialSize,
             });
             notifyCreated(updatedBoard, itemId, customWidgetDefinition.name);
           },
           integrationData: [],
           integrationSupport: false,
           settings,
+          previewResize: { initialSize, maximumSize: maximumWidgetSize },
         },
         {
           title: (titleT) => `${titleT("item.edit.title")} - ${customWidgetDefinition.name}`,
@@ -311,6 +325,7 @@ const ItemSelectModalContent = ({
       const matchingIntegrationCount = Math.min(matchingIntegrations.length, maxIntegrations);
       const itemId = createId();
       const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
+      const initialSize = widgetDefaultSizes[kind] ?? defaultWidgetSize;
       const openEditor = (
         availableIntegrations: { id: string; name: string; url: string; kind: IntegrationKind }[],
       ) => {
@@ -326,7 +341,7 @@ const ItemSelectModalContent = ({
               options: defaultOptions,
               integrationIds: selectedIntegrationIds,
             },
-            onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }) => {
+            onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }, selectedSize) => {
               const updatedBoard = createItem({
                 id: itemId,
                 kind,
@@ -334,6 +349,7 @@ const ItemSelectModalContent = ({
                 integrationIds: newIntegrationIds,
                 targetSectionId: effectiveSectionId ?? undefined,
                 advancedOptions,
+                size: selectedSize ?? initialSize,
               });
               if (!notifyCreated(updatedBoard, itemId, getWidgetName(kind, t))) return;
               trackSetup("widget-completed", {
@@ -346,6 +362,7 @@ const ItemSelectModalContent = ({
             integrationData: availableIntegrations,
             integrationSupport: hasIntegrationSupport,
             settings,
+            previewResize: { initialSize, maximumSize: maximumWidgetSize },
           },
           {
             title: (titleT) => `${titleT("item.edit.title")} - ${getWidgetName(kind, titleT)}`,

apps/nextjs/src/components/board/items/lazy-widget-edit-modal.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import type { PropsWithChildren } from "react";
 import { Suspense, use, useCallback, useMemo, useState } from "react";
 import { Center, Loader } from "@mantine/core";
 import { ErrorBoundary } from "react-error-boundary";
@@ -7,16 +8,49 @@ import type { FallbackProps } from "react-error-boundary";
 
 import { clientApi } from "@homarr/api/client";
 import type { WidgetKind } from "@homarr/definitions";
-import { createModal, modalSizeForm, useModalAction } from "@homarr/modals";
+import { widgetDefaultSizes } from "@homarr/definitions";
+import { createModal, useModalAction } from "@homarr/modals";
 import { WidgetError } from "@homarr/widgets/errors";
 import type * as WidgetModalsModule from "@homarr/widgets/modals";
-import type { WidgetEditModalProps } from "@homarr/widgets/modals";
+import type { WidgetEditModalProps, WidgetEditModalSize } from "@homarr/widgets/modals";
+import { loadWidgetComponent } from "@homarr/widgets/manifest";
 import type { IntegrationSelectOption } from "@homarr/widgets/widget-integration-select";
 
+import { AssistantContext, useOptionalHomarrAssistant } from "~/components/assistant/assistant-context";
+import { getLogicalTrackSize } from "~/components/board/layout";
 import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
 import type * as IntegrationEditFormModule from "~/components/integration/embedded-integration-edit-form";
 import type { EmbeddedIntegrationEditFormProps } from "~/components/integration/embedded-integration-edit-form";
 
+const defaultWidgetSize = { width: 1, height: 1 };
+const ignoreAssistantAction = () => undefined;
+const ignoreAssistantPrompt = () => false;
+const ignoreAssistantRefresh = () => Promise.resolve();
+const getPreviewDimensions = (size: WidgetEditModalSize) => ({
+  width: getLogicalTrackSize(size.width),
+  height: getLogicalTrackSize(size.height),
+});
+
+const PreviewRuntimeWrapper = ({ children }: PropsWithChildren) => {
+  const assistant = useOptionalHomarrAssistant();
+  const previewAssistant = useMemo(() => {
+    if (!assistant) return null;
+    return {
+      ...assistant,
+      open: ignoreAssistantAction,
+      close: ignoreAssistantAction,
+      toggle: ignoreAssistantAction,
+      sendPrompt: ignoreAssistantPrompt,
+      refreshCurrentView: ignoreAssistantRefresh,
+      setWidgetVisible: ignoreAssistantAction,
+      activateWidget: ignoreAssistantAction,
+    };
+  }, [assistant]);
+
+  if (!previewAssistant) return children;
+  return <AssistantContext.Provider value={previewAssistant}>{children}</AssistantContext.Provider>;
+};
+
 let widgetEditModalPromise: Promise<typeof WidgetModalsModule> | undefined;
 
 export const loadWidgetEditModal = () => {
@@ -83,6 +117,7 @@ interface LazyWidgetEditModalContentProps {
 
 const LazyWidgetEditModalContent = (props: LazyWidgetEditModalContentProps) => {
   const { WidgetEditModal } = use(loadWidgetEditModal());
+  const { default: PreviewComponent } = use(loadWidgetComponent(props.innerProps.kind));
   const { openModal: openIntegrationModal } = useModalAction(IntegrationSelectModal);
   const Component = WidgetEditModal.component;
   const utils = clientApi.useUtils();
@@ -114,6 +149,18 @@ const LazyWidgetEditModalContent = (props: LazyWidgetEditModalContentProps) => {
     const additional = createdIntegrations.filter((c) => !existing.some((e) => e.id === c.id));
     return [...existing, ...additional];
   }, [props.innerProps.integrationData, createdIntegrations]);
+  const previewDimensions = useMemo(() => {
+    if (props.innerProps.previewDimensions) return props.innerProps.previewDimensions;
+    const size = widgetDefaultSizes[props.innerProps.kind] ?? defaultWidgetSize;
+    return {
+      width: getLogicalTrackSize(size.width),
+      height: getLogicalTrackSize(size.height),
+    };
+  }, [props.innerProps.kind, props.innerProps.previewDimensions]);
+  let previewResize = props.innerProps.previewResize;
+  if (previewResize) {
+    previewResize = { ...previewResize, getDimensions: getPreviewDimensions };
+  }
 
   return (
     <Component
@@ -122,6 +169,10 @@ const LazyWidgetEditModalContent = (props: LazyWidgetEditModalContentProps) => {
         ...props.innerProps,
         integrationData: combinedIntegrationData,
         integrationEditForm: LazyIntegrationEditForm,
+        previewComponent: PreviewComponent,
+        previewDimensions,
+        previewResize,
+        previewWrapper: PreviewRuntimeWrapper,
         onOpenNewIntegration: supportedKinds.length > 0 ? handleOpenNewIntegration : undefined,
       }}
     />
@@ -157,6 +208,10 @@ export const LazyWidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>
   defaultTitle(t) {
     return t("item.edit.title");
   },
-  size: modalSizeForm,
+  size: "100rem",
+  transitionProps: {
+    transition: "pop",
+    duration: 180,
+  },
   closeOnClickOutside: false,
 });

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

@@ -35,6 +35,7 @@ import { matchesWidgetItemQuery } from "./widget-query-scope";
 interface WidgetContextMenuProps {
   item: SectionItem;
   definition: WidgetDefinition;
+  previewDimensions: { width: number; height: number; scale?: number };
   widgetStateRef: MutableRefObject<Record<string, unknown> | null>;
   widgetRuntimeRef: WidgetRuntimeRef;
   sourceRef: RefObject<HTMLElement | null>;
@@ -44,6 +45,7 @@ interface WidgetContextMenuProps {
 export const WidgetContextMenu = ({
   item,
   definition,
+  previewDimensions,
   widgetRuntimeRef,
   sourceRef,
   children,
@@ -160,7 +162,7 @@ export const WidgetContextMenu = ({
         definition,
         value: {
           advancedOptions: item.advancedOptions,
-          options: item.options,
+          options,
           integrationIds: item.integrationIds,
         },
         onSuccessfulEdit: (editResult) => {
@@ -189,6 +191,9 @@ export const WidgetContextMenu = ({
         ),
         integrationSupport: definition.supportedIntegrations !== undefined,
         settings,
+        itemId: item.id,
+        boardId: board.id,
+        previewDimensions,
         appId: item.kind === "app" ? (item.options.appId as string | undefined) : undefined,
       },
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -197,12 +202,15 @@ export const WidgetContextMenu = ({
       },
     );
   }, [
+    board.id,
     definition,
     integrationData,
     item,
     handleRefetch,
     openModal,
+    options,
     persistBoard,
+    previewDimensions,
     settings,
     updateItemAdvancedOptions,
     updateItemIntegrations,

apps/nextjs/src/components/board/items/widget-hover-overlay.module.css

@@ -31,7 +31,7 @@
   align-items: center;
   gap: 8px;
   min-height: 28px;
-  padding: 4px 8px;
+  padding: 4px 40px 4px 8px;
   border: 1px solid var(--border-color);
   border-radius: var(--mantine-radius-md);
   background-color: var(--background-color);

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

@@ -2,17 +2,16 @@
 
 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`);
+- one grid track has a `212 × 212` logical-pixel footprint;
+- cards are inset by `10` visual pixels on every side, matching the legacy GridStack gutter;
+- multi-cell items occupy complete track footprints (`2 × 1` is `424 × 212` before the card inset);
 - the canvas is zoomed 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 visual canvas always fits the available width, every root lane
-keeps at least one viewport of height, and edit-mode previews extend it downward
-as needed.
+Grid footprints keep the same logical dimensions at every viewport. Widget cards
+use a scale-compensated inset so their painted size and content measurements
+match the legacy responsive grid. The visual canvas always fits the available
+width, every root lane keeps at least one viewport of height, and edit-mode
+previews extend it downward as needed.
 
 The read-only renderer should:
 

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

@@ -2,7 +2,7 @@ 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 { getLogicalGridSize, getLayoutRowCount, normalizeGridPlacement } from "./geometry";
 import { getCollapsedDisplayLayout } from "./reflow";
 import type { GridPlacement } from "./types";
 
@@ -90,5 +90,5 @@ export const getInitialBoardLogicalHeight = (board: Board, layoutId: string) =>
     return [getLayoutRowCount(displayPlacements)];
   });
 
-  return getLogicalTrackSize(Math.max(0, ...rowCounts));
+  return getLogicalGridSize(Math.max(0, ...rowCounts));
 };

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

@@ -3,7 +3,7 @@
  * 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_GAP = 12;
 export const LOGICAL_GRID_PITCH = LOGICAL_GRID_CELL_SIZE + LOGICAL_GRID_GAP;
 
 export const COLLAPSED_SECTION_ROW_COUNT = 0.5;

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

@@ -10,12 +10,23 @@ export const getLogicalTrackSize = (trackCount: number) => {
   return normalizedTrackCount * LOGICAL_GRID_CELL_SIZE + (normalizedTrackCount - 1) * LOGICAL_GRID_GAP;
 };
 
+/**
+ * Returns the complete footprint occupied by grid tracks. Cards are inset
+ * inside this footprint so their visual gutters stay fixed while the canvas
+ * is scaled.
+ */
+export const getLogicalGridSize = (trackCount: number) => {
+  const normalizedTrackCount = Math.max(0, toFiniteNumber(trackCount, "trackCount"));
+
+  return normalizedTrackCount * LOGICAL_GRID_PITCH;
+};
+
 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),
+  width: getLogicalGridSize(w),
+  height: getLogicalGridSize(h),
 });
 
 export const getLayoutRowCount = (placements: readonly GridCoordinates[]) =>
@@ -25,7 +36,7 @@ export const getGridRowCountForVisualHeight = (visualHeight: number, visualScale
   if (!Number.isFinite(visualHeight) || visualHeight <= 0) return 1;
   if (!Number.isFinite(visualScale) || visualScale <= 0) return 1;
 
-  return Math.max(1, Math.ceil((visualHeight / visualScale + LOGICAL_GRID_GAP) / LOGICAL_GRID_PITCH));
+  return Math.max(1, Math.ceil(visualHeight / visualScale / LOGICAL_GRID_PITCH));
 };
 
 export const normalizeGridPlacement = <TPlacement extends GridPlacement>(

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

@@ -23,6 +23,8 @@
    * zoom and enlarges everything together.
    */
   --mantine-scale: var(--board-canvas-ui-scale, 1);
+  /* Keep a subtle boundary inset without widening the visual gap too much. */
+  --board-grid-item-inset: calc(var(--mantine-spacing-xs) / 2);
   --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));

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

@@ -5,7 +5,12 @@ import { BoardMockBuilder } from "~/components/board/items/actions/test/mocks/bo
 import { ContainerSectionMockBuilder } from "~/components/board/items/actions/test/mocks/container-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";
+import {
+  getBoardLaneColumnCount,
+  getInitialBoardLogicalHeight,
+  getLogicalGridSize,
+  getRootSectionForLane,
+} from "../index";
 
 describe("board lanes", () => {
   test("gutters consume columns from the main canvas", () => {
@@ -126,6 +131,6 @@ describe("board lanes", () => {
       },
     ];
 
-    expect(getInitialBoardLogicalHeight(board, layoutId)).toBe(872);
+    expect(getInitialBoardLogicalHeight(board, layoutId)).toBe(getLogicalGridSize(4));
   });
 });

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

@@ -3,24 +3,28 @@ import { describe, expect, test } from "vitest";
 import {
   getGridRowCountForVisualHeight,
   getLayoutRowCount,
+  getLogicalGridSize,
   getLogicalItemStyle,
   getLogicalTrackSize,
   normalizeGridPlacement,
 } from "../index";
 
 describe("fixed dashboard geometry", () => {
-  test("keeps a 1x1 item exactly 200px with a fixed 24px gap", () => {
+  test("separates content track sizes from complete grid footprints", () => {
     expect(getLogicalTrackSize(1)).toBe(200);
-    expect(getLogicalTrackSize(0.5)).toBe(88);
-    expect(getLogicalTrackSize(2)).toBe(424);
-    expect(getLogicalTrackSize(3)).toBe(648);
+    expect(getLogicalTrackSize(0.5)).toBe(94);
+    expect(getLogicalTrackSize(2)).toBe(412);
+    expect(getLogicalTrackSize(3)).toBe(624);
+    expect(getLogicalGridSize(1)).toBe(212);
+    expect(getLogicalGridSize(2)).toBe(424);
+    expect(getLogicalGridSize(3)).toBe(636);
 
     expect(getLogicalItemStyle({ x: 1, y: 2, w: 2, h: 3 })).toEqual({
       position: "absolute",
-      left: 224,
-      top: 448,
+      left: 212,
+      top: 424,
       width: 424,
-      height: 648,
+      height: 636,
     });
   });
 
@@ -35,7 +39,7 @@ describe("fixed dashboard geometry", () => {
     expect(getGridRowCountForVisualHeight(1200, 1)).toBe(6);
     expect(getLogicalTrackSize(getGridRowCountForVisualHeight(1200, 1))).toBeGreaterThanOrEqual(1200);
 
-    expect(getGridRowCountForVisualHeight(1200, 0.5)).toBe(11);
+    expect(getGridRowCountForVisualHeight(1200, 0.5)).toBe(12);
     expect(getLogicalTrackSize(getGridRowCountForVisualHeight(1200, 0.5)) * 0.5).toBeGreaterThanOrEqual(1200);
   });
 });

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

@@ -46,6 +46,7 @@ export const BoardContainerSection = ({ section }: Props) => {
       <Card
         className={combineClasses(
           classes.itemCard,
+          classes.containerCard,
           options.customCssClasses.join(" "),
           isVisuallyCollapsed && classes.collapsedContainerCard,
         )}
@@ -56,7 +57,7 @@ export const BoardContainerSection = ({ section }: Props) => {
           root: {
             overflow: "visible",
             "--opacity": board.opacity / 100,
-            "--border-color": options.borderColor || undefined,
+            "--container-border-color": options.borderColor || undefined,
           },
         }}
         radius={board.itemRadius}
@@ -66,7 +67,7 @@ export const BoardContainerSection = ({ section }: Props) => {
           <Button
             className={classes.containerToggle}
             pos="absolute"
-            top={isVisuallyCollapsed ? 0 : -24}
+            top={isVisuallyCollapsed ? 0 : "calc(var(--mantine-spacing-xs) * -1)"}
             left={0}
             w="100%"
             h={isVisuallyCollapsed ? "100%" : 24}
@@ -103,8 +104,9 @@ export const BoardContainerSection = ({ section }: Props) => {
         )}
         {!isVisuallyCollapsed && !options.collapsible && options.showLabel && options.title && (
           <Badge
+            className={classes.containerLabel}
             pos="absolute"
-            top={-24}
+            top="calc(var(--mantine-spacing-xs) * -1)"
             left={labelLeft}
             maw={`calc(100% - ${labelLeft + labelRight}px)`}
             size="md"
@@ -113,12 +115,7 @@ export const BoardContainerSection = ({ section }: Props) => {
             c="var(--mantine-color-text)"
             style={{
               zIndex: 9,
-              overflow: "hidden",
               pointerEvents: "none",
-              textOverflow: "ellipsis",
-              whiteSpace: "nowrap",
-              backgroundColor: "var(--background-color)",
-              borderColor: "var(--border-color)",
             }}
             title={options.title}
             data-board-container-label
@@ -128,8 +125,9 @@ export const BoardContainerSection = ({ section }: Props) => {
         )}
         {options.showOpenAll && !isEditMode && (
           <ActionIcon
+            className={classes.containerAction}
             pos="absolute"
-            top={isVisuallyCollapsed ? "50%" : -24}
+            top={isVisuallyCollapsed ? "50%" : "calc(var(--mantine-spacing-xs) * -1)"}
             right={8}
             style={{ zIndex: 10, transform: isVisuallyCollapsed ? "translateY(-50%)" : undefined }}
             variant={options.collapsible ? "subtle" : "default"}

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

@@ -7,7 +7,7 @@ import { createPortal } from "react-dom";
 import { useEditMode } from "@homarr/boards/edit-mode";
 
 import { getLoadedGridEditorModule, loadGridEditorAsync } from "./grid-editor-loader";
-import { GridEditorRegistryProvider, useRegisteredGridEditors } from "./grid-editor-registry";
+import { useRegisteredGridEditors } from "./grid-editor-registry";
 import { GridEditorRuntimeProvider } from "./grid-editor-runtime";
 
 type BoardGridEditorProviderComponent = ComponentType<PropsWithChildren>;
@@ -54,14 +54,14 @@ export const BoardGridEditorBoundary = ({ children }: PropsWithChildren) => {
   const GridEditor = resolvedEditorModule?.default ?? null;
 
   return (
-    <GridEditorRegistryProvider>
+    <>
       <GridEditorRuntimeProvider status={runtimeStatus}>{children}</GridEditorRuntimeProvider>
       {isEditMode && Provider && GridEditor && (
         <Provider>
           <RegisteredGridEditors GridEditor={GridEditor} />
         </Provider>
       )}
-    </GridEditorRegistryProvider>
+    </>
   );
 };
 

apps/nextjs/src/components/board/sections/grid/dnd/coordinates.spec.ts

@@ -23,7 +23,12 @@ describe("dnd grid coordinates", () => {
   test("uses the dragged shape origin so a non-center grab retains its pointer offset", () => {
     const scale = 0.75;
     const target = { left: -280, top: 390, width: getLogicalTrackSize(5) * scale };
-    const initialShape = { left: target.left, top: target.top, width: 424 * scale, height: 200 * scale };
+    const initialShape = {
+      left: target.left,
+      top: target.top,
+      width: getLogicalTrackSize(2) * scale,
+      height: 200 * scale,
+    };
     const pointerDelta = { x: LOGICAL_GRID_PITCH * scale * 2, y: LOGICAL_GRID_PITCH * scale * 3 };
 
     expect(

apps/nextjs/src/components/board/sections/grid/dnd/coordinates.ts

@@ -1,4 +1,4 @@
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 import type { GridPlacement } from "~/components/board/layout";
 import type { GridResizeDirection } from "./types";
 
@@ -38,7 +38,7 @@ export const getSnappedGridCoordinates = ({
   target: RectangleLike;
   columnCount: number;
 }) => {
-  const logicalWidth = getLogicalTrackSize(columnCount);
+  const logicalWidth = getLogicalGridSize(columnCount);
   const visualScale = logicalWidth > 0 ? target.width / logicalWidth : 0;
   if (!Number.isFinite(visualScale) || visualScale <= 0) return null;
 

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

@@ -55,6 +55,7 @@ export interface GridEditorRenderProps {
 }
 
 export interface RegisteredGridEditor extends GridEditorRenderProps {
+  placementMaxRowCount: number | null;
   host: HTMLElement;
   disabled: boolean;
 }

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

@@ -51,7 +51,7 @@
 
 .board-grid-entry[data-board-item-selected="true"]::after {
   position: absolute;
-  inset: 0;
+  inset: var(--board-grid-item-inset, 0px);
   z-index: 100;
   content: "";
   background: color-mix(in srgb, var(--mantine-primary-color-filled) 12%, transparent);
@@ -121,6 +121,7 @@ body[data-board-grid-interacting="resize"] .board-grid-entry[data-dnd-active="tr
 
 .board-grid-placeholder {
   z-index: 0;
+  clip-path: inset(var(--board-grid-item-inset, 0px));
   background: color-mix(in srgb, var(--mantine-primary-color-filled) 16%, transparent);
   border: 2px dashed var(--mantine-primary-color-filled);
   border-radius: var(--mantine-radius-md);
@@ -139,6 +140,7 @@ body[data-board-grid-interacting="resize"] .board-grid-entry[data-dnd-active="tr
 
 .board-grid-resize-outline {
   z-index: 1002;
+  clip-path: inset(var(--board-grid-item-inset, 0px));
   background: color-mix(in srgb, var(--mantine-primary-color-filled) 6%, transparent);
   border: 2px solid var(--mantine-primary-color-filled);
   border-radius: var(--mantine-radius-md);
@@ -153,17 +155,6 @@ body[data-board-grid-interacting="resize"] .board-grid-entry[data-dnd-active="tr
   box-shadow: inset 0 0 0 2px var(--mantine-color-red-filled);
 }
 
-[data-section-kind="empty"][data-rail-placement="main"] > .board-grid-editor[data-dnd-drop-target="true"] {
-  outline: 2px solid color-mix(in srgb, var(--mantine-primary-color-filled) 60%, transparent);
-  outline-offset: 4px;
-  box-shadow: none;
-}
-
-[data-section-kind="empty"][data-rail-placement="main"]
-  > .board-grid-editor[data-dnd-drop-target="true"][data-dnd-drop-valid="false"] {
-  outline-color: var(--mantine-color-red-filled);
-}
-
 [data-board-container-collapsed]
   > [data-board-container-body]
   > [data-section-id]
@@ -240,11 +231,11 @@ body[data-board-grid-interacting="resize"] .board-grid-entry[data-dnd-active="tr
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="n"] {
-  top: -0.25rem;
+  top: calc(var(--board-grid-item-inset, 0px) - 0.25rem);
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="s"] {
-  bottom: -0.25rem;
+  bottom: calc(var(--board-grid-item-inset, 0px) - 0.25rem);
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="e"],
@@ -258,11 +249,11 @@ body[data-board-grid-interacting="resize"] .board-grid-entry[data-dnd-active="tr
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="e"] {
-  right: -0.25rem;
+  right: calc(var(--board-grid-item-inset, 0px) - 0.25rem);
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="w"] {
-  left: -0.25rem;
+  left: calc(var(--board-grid-item-inset, 0px) - 0.25rem);
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="ne"],
@@ -275,42 +266,30 @@ body[data-board-grid-interacting="resize"] .board-grid-entry[data-dnd-active="tr
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="ne"] {
-  top: -0.625rem;
-  right: -0.625rem;
+  top: calc(var(--board-grid-item-inset, 0px) - 0.625rem);
+  right: calc(var(--board-grid-item-inset, 0px) - 0.625rem);
   cursor: nesw-resize;
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="se"] {
-  right: -0.625rem;
-  bottom: -0.625rem;
+  right: calc(var(--board-grid-item-inset, 0px) - 0.625rem);
+  bottom: calc(var(--board-grid-item-inset, 0px) - 0.625rem);
   cursor: nwse-resize;
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="sw"] {
-  bottom: -0.625rem;
-  left: -0.625rem;
+  bottom: calc(var(--board-grid-item-inset, 0px) - 0.625rem);
+  left: calc(var(--board-grid-item-inset, 0px) - 0.625rem);
   cursor: nesw-resize;
 }
 
 .board-grid-resize-handle[data-grid-resize-handle="nw"] {
-  top: -0.625rem;
-  left: -0.625rem;
+  top: calc(var(--board-grid-item-inset, 0px) - 0.625rem);
+  left: calc(var(--board-grid-item-inset, 0px) - 0.625rem);
   cursor: nwse-resize;
   /* Leaves a thin draggable border around the corner instead of a solid 44x44 hit area,
      so it doesn't sit on top of the container menu button anchored in this same corner. */
-  clip-path: polygon(
-    evenodd,
-    0 0,
-    100% 0,
-    100% 100%,
-    0 100%,
-    0 0,
-    4px 4px,
-    4px 40px,
-    40px 40px,
-    40px 4px,
-    4px 4px
-  );
+  clip-path: polygon(evenodd, 0 0, 100% 0, 100% 100%, 0 100%, 0 0, 4px 4px, 4px 40px, 40px 40px, 40px 4px, 4px 4px);
 }
 
 @media (prefers-reduced-motion: reduce) {

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

@@ -39,7 +39,7 @@ import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
 import { getWidgetName } from "@homarr/definitions";
 import { useI18n } from "@homarr/translation/client";
 
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 import {
   beginGridTransaction,
   cancelGridTransaction,
@@ -792,8 +792,8 @@ export default function GridEditor({
       data-grid-depth={depth}
       style={
         {
-          width: getLogicalTrackSize(columnCount),
-          height: getLogicalTrackSize(rowCount),
+          width: getLogicalGridSize(columnCount),
+          height: getLogicalGridSize(rowCount),
           "--board-grid-pitch": `${LOGICAL_GRID_PITCH}px`,
         } as CSSProperties
       }
@@ -1234,8 +1234,8 @@ const getEntryVisualScale = (element: HTMLElement | null, placement: SectionGrid
   if (!element) return null;
   const rectangle = element.getBoundingClientRect();
   const scale = {
-    x: rectangle.width / getLogicalTrackSize(placement.w),
-    y: rectangle.height / getLogicalTrackSize(placement.h),
+    x: rectangle.width / getLogicalGridSize(placement.w),
+    y: rectangle.height / getLogicalGridSize(placement.h),
   };
   return Number.isFinite(scale.x) && scale.x > 0 && Number.isFinite(scale.y) && scale.y > 0 ? scale : null;
 };

apps/nextjs/src/components/board/sections/grid/grid-preview-geometry.ts

@@ -1,4 +1,4 @@
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 import type { GridPlacement } from "~/components/board/layout";
 
 export interface GridPreviewDomState {
@@ -75,8 +75,8 @@ export const clearGridPreviewGeometry = (
 const applyPreviewGeometry = (element: HTMLElement, controlled: GridPlacement, preview: GridPlacement) => {
   element.style.setProperty("--board-grid-preview-x", `${(preview.x - controlled.x) * LOGICAL_GRID_PITCH}px`);
   element.style.setProperty("--board-grid-preview-y", `${(preview.y - controlled.y) * LOGICAL_GRID_PITCH}px`);
-  element.style.setProperty("--board-grid-preview-width", `${getLogicalTrackSize(preview.w)}px`);
-  element.style.setProperty("--board-grid-preview-height", `${getLogicalTrackSize(preview.h)}px`);
+  element.style.setProperty("--board-grid-preview-width", `${getLogicalGridSize(preview.w)}px`);
+  element.style.setProperty("--board-grid-preview-height", `${getLogicalGridSize(preview.h)}px`);
   element.setAttribute("data-grid-preview", "true");
   setPlacementAttributes(element, preview);
 };

apps/nextjs/src/components/board/sections/grid/grid-preview-layer.tsx

@@ -3,7 +3,7 @@
 import type { RefObject } from "react";
 import { useCallback, useLayoutEffect, useRef, useSyncExternalStore } from "react";
 
-import { getLayoutRowCount, getLogicalItemStyle, getLogicalTrackSize } from "~/components/board/layout";
+import { getLayoutRowCount, getLogicalItemStyle, getLogicalGridSize } from "~/components/board/layout";
 import type { TransactionalGridState } from "./dnd";
 import type { GridInteractionStore } from "./grid-interaction-store";
 import { clearGridPreviewGeometry, createGridPreviewDomState, syncGridPreviewGeometry } from "./grid-preview-geometry";
@@ -87,7 +87,7 @@ export const GridPreviewLayer = ({
     } else {
       delete grid.dataset.dndPreviewRevision;
     }
-    grid.style.height = `${getLogicalTrackSize(renderedRowCount)}px`;
+    grid.style.height = `${getLogicalGridSize(renderedRowCount)}px`;
 
     const viewport = grid.parentElement;
     if (viewport?.hasAttribute("data-section-id")) {
@@ -98,7 +98,7 @@ export const GridPreviewLayer = ({
       // stray value would silently blow the cap open for the rest of the session, well after any
       // drag ended, since nothing else would ever clear it back out.
       if (maxRowCount === null) {
-        viewport.style.setProperty("--board-grid-drag-height", `${getLogicalTrackSize(renderedRowCount)}px`);
+        viewport.style.setProperty("--board-grid-drag-height", `${getLogicalGridSize(renderedRowCount)}px`);
       } else {
         viewport.style.removeProperty("--board-grid-drag-height");
       }

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

@@ -1,4 +1,4 @@
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 import type { GridPlacement } from "~/components/board/layout";
 
 interface ResizeOutlinePreview {
@@ -31,8 +31,8 @@ export const createGridResizeOutlineController = (
     outline.style.position = "absolute";
     outline.style.left = `${(preview.placement.x - visualX) * LOGICAL_GRID_PITCH}px`;
     outline.style.top = `${(preview.placement.y - visualY) * LOGICAL_GRID_PITCH}px`;
-    outline.style.width = `${getLogicalTrackSize(preview.placement.w)}px`;
-    outline.style.height = `${getLogicalTrackSize(preview.placement.h)}px`;
+    outline.style.width = `${getLogicalGridSize(preview.placement.w)}px`;
+    outline.style.height = `${getLogicalGridSize(preview.placement.h)}px`;
     outline.dataset.gridResizeValid = String(preview.valid);
   };
 

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

@@ -46,12 +46,18 @@
 
 .contentMount {
   position: absolute;
-  inset: 0;
-  width: 100%;
-  height: 100%;
+  inset: var(--board-grid-item-inset, 0px);
   overflow: visible;
 }
 
+.staticItem[data-type="item"] > .contentMount {
+  inset: calc(10px * var(--board-canvas-inverse-scale, 1));
+}
+
+.staticItem:has([data-board-container-label]) {
+  z-index: 2;
+}
+
 .editorEntry {
   overflow: visible;
   cursor: grab;

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

@@ -14,7 +14,7 @@ import {
   getEditableCanvasAttributes,
   getGridRowCountForVisualHeight,
   getLayoutRowCount,
-  getLogicalTrackSize,
+  getLogicalGridSize,
   getReadonlyCanvasAttributes,
   normalizeGridPlacement,
 } from "~/components/board/layout";
@@ -130,13 +130,17 @@ export const SectionGrid = ({
   const contentRowCount = Math.max(1, getLayoutRowCount(displayPlacements));
   const rowCount = Math.max(contentRowCount, requestedRowCount, minimumViewportRowCount);
   const maxRowCount = section.kind === "container" || railPlacement !== "main" ? rowCount : null;
+  let placementMaxRowCount = maxRowCount;
+  if (railPlacement !== "main") {
+    placementMaxRowCount = minimumViewportRowCount;
+  }
   // A scrollable container isn't forced to grow with its content - it scrolls internally instead
   // of expanding to fit every widget, so its viewport height is capped independently of rowCount.
   const isScrollableContainer = section.kind === "container" && section.options.scrollable;
   const viewportRowCount = isScrollableContainer ? Math.max(requestedRowCount, 1) : rowCount;
-  const logicalWidth = getLogicalTrackSize(columnCount);
-  const logicalHeight = getLogicalTrackSize(rowCount);
-  const viewportHeight = getLogicalTrackSize(viewportRowCount);
+  const logicalWidth = getLogicalGridSize(columnCount);
+  const logicalHeight = getLogicalGridSize(rowCount);
+  const viewportHeight = getLogicalGridSize(viewportRowCount);
   // A collapsed container's compact coordinates are display-only. Its own
   // nested grid stays inactive until an explicit edit interaction expands it.
   const isInteractionDisabled = section.kind === "container" && collapsedSectionIds.has(section.id);
@@ -175,6 +179,7 @@ export const SectionGrid = ({
       columnCount,
       rowCount,
       maxRowCount,
+      placementMaxRowCount,
       placements: displayPlacements,
       transactionPlacements: placements,
       className: editorClassName,
@@ -190,6 +195,7 @@ export const SectionGrid = ({
     entryElementStore,
     isInteractionDisabled,
     maxRowCount,
+    placementMaxRowCount,
     placements,
     rowCount,
     section,

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

@@ -4,7 +4,7 @@ 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 { getCollapsedDisplayLayout, getLogicalGridSize } from "../../../layout";
 import { FixedGridItem } from "../fixed-grid-item";
 
 const mocks = vi.hoisted(() => ({
@@ -250,14 +250,14 @@ describe("fixed grid item behavior", () => {
     expect(container.querySelector('[data-testid="board-grid-drag-affordance"]')).toBeNull();
   });
 
-  test("renders a view-only 1x1 card at the fixed 200px logical size", () => {
+  test("renders a view-only 1x1 card at the complete grid footprint", () => {
     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?.style.width).toBe(`${getLogicalGridSize(1)}px`);
+    expect(item?.style.height).toBe(`${getLogicalGridSize(1)}px`);
     expect(item?.getAttribute("role")).toBeNull();
 
     act(() => item?.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true })));

apps/nextjs/src/components/board/sections/grid/test/grid-preview-geometry.spec.ts

@@ -1,5 +1,7 @@
 import { beforeEach, describe, expect, test } from "vitest";
 
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+
 import { createGridPreviewDomState, syncGridPreviewGeometry } from "../grid-preview-geometry";
 
 describe("grid preview geometry", () => {
@@ -25,8 +27,12 @@ describe("grid preview geometry", () => {
 
     expect(elements.get("active")?.hasAttribute("data-grid-preview")).toBe(false);
     expect(elements.get("active")?.getAttribute("data-dnd-active")).toBe("true");
-    expect(elements.get("displaced")?.style.getPropertyValue("--board-grid-preview-x")).toBe("-448px");
-    expect(elements.get("displaced")?.style.getPropertyValue("--board-grid-preview-y")).toBe("448px");
+    expect(elements.get("displaced")?.style.getPropertyValue("--board-grid-preview-x")).toBe(
+      `${-2 * LOGICAL_GRID_PITCH}px`,
+    );
+    expect(elements.get("displaced")?.style.getPropertyValue("--board-grid-preview-y")).toBe(
+      `${2 * LOGICAL_GRID_PITCH}px`,
+    );
     expect(elements.get("displaced")?.dataset.gridX).toBe("0");
     expect(elements.get("displaced")?.dataset.gridY).toBe("2");
 
@@ -57,10 +63,10 @@ describe("grid preview geometry", () => {
 
     const active = elements.get("active");
     expect(active?.getAttribute("data-grid-preview")).toBe("true");
-    expect(active?.style.getPropertyValue("--board-grid-preview-x")).toBe("224px");
-    expect(active?.style.getPropertyValue("--board-grid-preview-y")).toBe("224px");
-    expect(active?.style.getPropertyValue("--board-grid-preview-width")).toBe("648px");
-    expect(active?.style.getPropertyValue("--board-grid-preview-height")).toBe("872px");
+    expect(active?.style.getPropertyValue("--board-grid-preview-x")).toBe(`${LOGICAL_GRID_PITCH}px`);
+    expect(active?.style.getPropertyValue("--board-grid-preview-y")).toBe(`${LOGICAL_GRID_PITCH}px`);
+    expect(active?.style.getPropertyValue("--board-grid-preview-width")).toBe(`${getLogicalGridSize(3)}px`);
+    expect(active?.style.getPropertyValue("--board-grid-preview-height")).toBe(`${getLogicalGridSize(4)}px`);
     expect(active?.dataset.gridW).toBe("3");
     expect(active?.dataset.gridH).toBe("4");
   });

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

@@ -1,5 +1,7 @@
 import { afterEach, describe, expect, test, vi } from "vitest";
 
+import { getLogicalGridSize } from "~/components/board/layout";
+
 import { createGridResizeOutlineController } from "../grid-resize-outline";
 
 describe("grid resize outline", () => {
@@ -28,8 +30,8 @@ describe("grid resize outline", () => {
     const outline = shell.querySelector<HTMLElement>("[data-grid-resize-outline]");
     expect(outline?.style.left).toBe("0px");
     expect(outline?.style.top).toBe("0px");
-    expect(outline?.style.width).toBe("200px");
-    expect(outline?.style.height).toBe("424px");
+    expect(outline?.style.width).toBe(`${getLogicalGridSize(1)}px`);
+    expect(outline?.style.height).toBe(`${getLogicalGridSize(2)}px`);
     expect(outline?.dataset.gridResizeValid).toBe("false");
 
     controller.schedule(null);

apps/nextjs/src/components/board/sections/item.module.css

@@ -11,6 +11,18 @@
   border-color: var(--border-color) !important;
 }
 
+.containerCard {
+  @mixin dark {
+    --container-default-border-color: var(--mantine-color-dark-4);
+  }
+  @mixin light {
+    --container-default-border-color: var(--mantine-color-gray-3);
+  }
+  --border-color: rgb(
+    from var(--container-border-color, var(--container-default-border-color)) r g b / var(--opacity, 1)
+  );
+}
+
 .itemCard:global(.iframe-wrapper) {
   background-color: transparent !important;
   border-color: transparent !important;
@@ -26,8 +38,8 @@
   z-index: 9;
   overflow: hidden;
   color: var(--mantine-color-text);
-  background-color: var(--background-color);
-  border-color: var(--border-color);
+  background-color: var(--background-color) !important;
+  border-color: var(--border-color) !important;
 }
 
 .containerToggle :global(.mantine-Button-inner) {
@@ -42,6 +54,24 @@
   white-space: nowrap;
 }
 
+.containerLabel,
+.containerAction {
+  background-color: var(--background-color) !important;
+  border-color: var(--border-color) !important;
+}
+
+.containerLabel {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.containerLabel :global(.mantine-Badge-label) {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
 .containerBody {
   visibility: visible;
   opacity: 1;

apps/nextjs/src/components/board/selection/board-selection-context.tsx

@@ -31,7 +31,7 @@ interface BoardSelectionContextValue {
   copySelectedItems: () => Promise<void>;
   pasteItems: () => Promise<void>;
   removeSelectedItems: () => void;
-  moveSelectedItemsToSection: (sectionId: string) => void;
+  moveSelectedItemsToSection: (sectionId: string, maxRowCount?: number | null) => void;
 }
 
 const BoardSelectionContext = createContext<BoardSelectionContextValue | null>(null);
@@ -229,7 +229,7 @@ export const BoardSelectionProvider = ({ children }: PropsWithChildren) => {
   }, [board.items, clearSelection, persistBoard, selectedItemIds, tCommon, tSelection]);
 
   const moveSelectedItemsToSection = useCallback(
-    (targetSectionId: string) => {
+    (targetSectionId: string, maxRowCount?: number | null) => {
       if (selectedItemIds.size === 0) return;
 
       const idsToMove = new Set(selectedItemIds);
@@ -248,7 +248,7 @@ export const BoardSelectionProvider = ({ children }: PropsWithChildren) => {
           targetSection.kind === "container"
             ? (containerLayout?.width ?? 0)
             : getBoardLaneColumnCount(boardLayout, getRootSectionLane(targetSection.xOffset));
-        const rowCount = containerLayout?.height ?? 9999;
+        const rowCount = containerLayout?.height ?? maxRowCount ?? 9999;
         if (columnCount === 0 || rowCount === 0) return previous;
 
         const existingContainers = previous.sections

apps/nextjs/src/components/board/selection/board-selection-toolbar.tsx

@@ -25,6 +25,7 @@ import { useI18n } from "@homarr/translation/client";
 import { widgetCatalogIcons } from "@homarr/widgets/catalog";
 
 import type { EmptySection } from "~/app/[locale]/boards/_types";
+import { useRegisteredGridEditors } from "~/components/board/sections/grid/grid-editor-registry";
 import { useBoardSelection } from "./board-selection-context";
 
 const MAX_AVATARS_DISPLAYED = 5;
@@ -40,6 +41,7 @@ export const BoardSelectionToolbar = () => {
     moveSelectedItemsToSection,
   } = useBoardSelection();
   const board = useRequiredBoard();
+  const registeredGridEditors = useRegisteredGridEditors();
   const currentLayoutId = useCurrentLayout();
   const currentLayout = board.layouts.find((layout) => layout.id === currentLayoutId);
   const t = useI18n();
@@ -96,7 +98,15 @@ export const BoardSelectionToolbar = () => {
     .at(0);
 
   const placementOptions = [
-    ...(mainCanvasSection ? [{ value: mainCanvasSection.id, label: t("item.create.destination.mainCanvas") }] : []),
+    ...(mainCanvasSection
+      ? [
+          {
+            value: mainCanvasSection.id,
+            label: t("item.create.destination.mainCanvas"),
+            maxRowCount: null,
+          },
+        ]
+      : []),
     ...board.sections.flatMap((section) => {
       if (section.kind !== "empty") return [];
       const lane = getRootSectionLane(section.xOffset);
@@ -105,6 +115,7 @@ export const BoardSelectionToolbar = () => {
         {
           value: section.id,
           label: t(`item.create.destination.${lane === "left" ? "leftRail" : "rightRail"}`),
+          maxRowCount: registeredGridEditors.get(section.id)?.placementMaxRowCount,
         },
       ];
     }),
@@ -113,6 +124,7 @@ export const BoardSelectionToolbar = () => {
       .map((section) => ({
         value: section.id,
         label: section.options.title.trim() || t("section.container.untitled"),
+        maxRowCount: section.layouts.find((layout) => layout.layoutId === currentLayoutId)?.height,
       })),
   ];
 
@@ -244,7 +256,11 @@ export const BoardSelectionToolbar = () => {
               <Menu.Dropdown>
                 <Menu.Label>{tSelection("moveTo")}</Menu.Label>
                 {placementOptions.map((opt) => (
-                  <Menu.Item key={opt.value} onClick={() => moveSelectedItemsToSection(opt.value)}>
+                  <Menu.Item
+                    key={opt.value}
+                    disabled={opt.maxRowCount === undefined}
+                    onClick={() => moveSelectedItemsToSection(opt.value, opt.maxRowCount)}
+                  >
                     {opt.label}
                   </Menu.Item>
                 ))}

apps/nextjs/src/components/layout/header/lazy-spotlight.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect, useState } from "react";
 import dynamic from "next/dynamic";
+import type { HotkeyItem } from "@mantine/hooks";
 import { useHotkeys } from "@mantine/hooks";
 
 import { hotkeys } from "@homarr/definitions";
@@ -13,23 +14,18 @@ const Spotlight = dynamic(() => loadSpotlight().then(({ Spotlight: Component })
   loading: () => null,
 });
 
+const spotlightHotkeys: HotkeyItem[] = [
+  [hotkeys.openSpotlight, () => openSpotlight(), { preventDefault: true }],
+  [hotkeys.openSpotlightApps, () => openSpotlight({ mode: "apps" }), { preventDefault: true }],
+  [hotkeys.openSpotlightAssistant, () => openSpotlight({ mode: "assistant" }), { preventDefault: true }],
+  [hotkeys.openSpotlightPreferences, () => openSpotlight({ mode: "preferences" }), { preventDefault: true }],
+];
+
 export const LazySpotlight = () => {
   const [isMounted, setIsMounted] = useState(false);
   const [isPreloaded, setIsPreloaded] = useState(false);
 
-  useHotkeys(
-    isMounted
-      ? []
-      : [
-          [
-            hotkeys.openSpotlight,
-            () => {
-              setIsMounted(true);
-              openSpotlight();
-            },
-          ],
-        ],
-  );
+  useHotkeys(spotlightHotkeys, [], true);
 
   useEffect(() => {
     let isActive = true;
@@ -61,12 +57,8 @@ export const LazySpotlight = () => {
   return isMounted || isPreloaded ? (
     <>
       {isPreloaded && <span hidden data-homarr-dev-benchmark-spotlight-preloaded />}
-      {isMounted && (
-        <>
-          <span hidden data-homarr-dev-benchmark-spotlight-mounted />
-          <Spotlight />
-        </>
-      )}
+      {isMounted && <span hidden data-homarr-dev-benchmark-spotlight-mounted />}
+      <Spotlight />
     </>
   ) : null;
 };