fix: show board settings in dashboard header

perf: persist widget data across reloads

.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/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/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/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.tsx

@@ -16,7 +16,7 @@ import { BoardSetupChecklist } from "~/components/board/board-setup-checklist";
 import {
   getBoardLaneColumnCount,
   getInitialBoardLogicalHeight,
-  getLogicalTrackSize,
+  getLogicalGridSize,
   LOGICAL_GRID_GAP,
   getRootSectionForLane,
 } from "~/components/board/layout";
@@ -61,16 +61,16 @@ 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(" ");

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

@@ -53,13 +53,11 @@ export const BoardContentHeaderActions = ({ demoReadOnly }: { demoReadOnly: bool
 
       <EditModeMenu demoReadOnly={demoReadOnly} />
 
-      {!demoReadOnly && (
-        <TourTarget id="board-settings">
-          <HeaderButton href={`/boards/${board.name}/settings`} aria-label={t("action.settings")}>
-            <IconSettings stroke={1.5} />
-          </HeaderButton>
-        </TourTarget>
-      )}
+      <TourTarget id="board-settings">
+        <HeaderButton href={`/boards/${board.name}/settings`} aria-label={t("action.settings")}>
+          <IconSettings stroke={1.5} />
+        </HeaderButton>
+      </TourTarget>
     </>
   );
 };

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]/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/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";

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/board/items/item-content.module.css

@@ -1,14 +1,15 @@
-.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 {

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,
       },
       {

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/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 matches Mantine's `sm` spacing at `12` logical pixels, giving a `212` pixel track pitch;
-- multi-cell items include the gaps between their cells (`2 × 1` is `412 × 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/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/test/board-lanes.spec.ts

@@ -8,7 +8,7 @@ import { ItemMockBuilder } from "~/components/board/items/actions/test/mocks/ite
 import {
   getBoardLaneColumnCount,
   getInitialBoardLogicalHeight,
-  getLogicalTrackSize,
+  getLogicalGridSize,
   getRootSectionForLane,
 } from "../index";
 
@@ -131,6 +131,6 @@ describe("board lanes", () => {
       },
     ];
 
-    expect(getInitialBoardLogicalHeight(board, layoutId)).toBe(getLogicalTrackSize(4));
+    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 12px gap", () => {
+  test("separates content track sizes from complete grid footprints", () => {
     expect(getLogicalTrackSize(1)).toBe(200);
     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: 212,
       top: 424,
-      width: 412,
-      height: 624,
+      width: 424,
+      height: 636,
     });
   });
 

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.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

@@ -50,6 +50,10 @@
   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;
 }

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";
@@ -138,9 +138,9 @@ export const SectionGrid = ({
   // 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);

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,6 +1,6 @@
 import { beforeEach, describe, expect, test } from "vitest";
 
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 
 import { createGridPreviewDomState, syncGridPreviewGeometry } from "../grid-preview-geometry";
 
@@ -65,8 +65,8 @@ describe("grid preview geometry", () => {
     expect(active?.getAttribute("data-grid-preview")).toBe("true");
     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(`${getLogicalTrackSize(3)}px`);
-    expect(active?.style.getPropertyValue("--board-grid-preview-height")).toBe(`${getLogicalTrackSize(4)}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,6 +1,6 @@
 import { afterEach, describe, expect, test, vi } from "vitest";
 
-import { getLogicalTrackSize } from "~/components/board/layout";
+import { getLogicalGridSize } from "~/components/board/layout";
 
 import { createGridResizeOutlineController } from "../grid-resize-outline";
 
@@ -30,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(`${getLogicalTrackSize(1)}px`);
-    expect(outline?.style.height).toBe(`${getLogicalTrackSize(2)}px`);
+    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);

e2e/lazy-widgets.spec.ts

@@ -1,5 +1,6 @@
 import { createId } from "@paralleldrive/cuid2";
 import { chromium, expect } from "@playwright/test";
+import type { Route } from "@playwright/test";
 import { eq } from "drizzle-orm";
 import { stringify } from "superjson";
 import { describe, test } from "vitest";
@@ -21,7 +22,9 @@ describe("lazy widget application graph", () => {
     const boardId = createId();
     const layoutId = createId();
     const sectionId = createId();
-    const itemId = createId();
+    const clockItemId = createId();
+    const downloadsItemId = createId();
+    const mockIntegrationId = createId();
 
     await db.insert(sqliteSchema.boards).values({
       id: boardId,
@@ -41,26 +44,56 @@ describe("lazy widget application graph", () => {
       xOffset: 0,
       yOffset: 0,
     });
-    await db.insert(sqliteSchema.items).values({
-      id: itemId,
-      boardId,
-      kind: "clock",
-      options: stringify({ showSeconds: true }),
+    await db.insert(sqliteSchema.integrations).values({
+      id: mockIntegrationId,
+      name: "Mock downloads",
+      url: "http://mock.local",
+      kind: "mock",
     });
-    await db.insert(sqliteSchema.itemLayouts).values({
-      itemId,
-      sectionId,
-      layoutId,
-      xOffset: 0,
-      yOffset: 0,
-      width: 4,
-      height: 2,
+    await db.insert(sqliteSchema.items).values([
+      {
+        id: clockItemId,
+        boardId,
+        kind: "clock",
+        options: stringify({ showSeconds: true }),
+      },
+      {
+        id: downloadsItemId,
+        boardId,
+        kind: "downloads",
+        options: stringify({}),
+      },
+    ]);
+    await db.insert(sqliteSchema.itemLayouts).values([
+      {
+        itemId: clockItemId,
+        sectionId,
+        layoutId,
+        xOffset: 0,
+        yOffset: 0,
+        width: 4,
+        height: 2,
+      },
+      {
+        itemId: downloadsItemId,
+        sectionId,
+        layoutId,
+        xOffset: 0,
+        yOffset: 2,
+        width: 8,
+        height: 5,
+      },
+    ]);
+    await db.insert(sqliteSchema.integrationItems).values({
+      itemId: downloadsItemId,
+      integrationId: mockIntegrationId,
     });
     await db.update(sqliteSchema.users).set({ homeBoardId: boardId }).where(eq(sqliteSchema.users.id, userId));
 
     const homarrContainer = await createHomarrContainer({
       environment: {
         AUTH_PROVIDERS: "credentials",
+        UNSAFE_ENABLE_MOCK_INTEGRATION: "true",
       },
       mounts: {
         "/appdata": localMountPath,
@@ -69,10 +102,18 @@ describe("lazy widget application graph", () => {
 
     const baseUrl = `http://${homarrContainer.getHost()}:${homarrContainer.getMappedPort(7575)}`;
     const browser = await chromium.launch();
-    const context = await browser.newContext();
+    const context = await browser.newContext({ serviceWorkers: "block" });
     const page = await context.newPage();
     const pageErrors: Error[] = [];
+    const hydrationErrors: string[] = [];
     page.on("pageerror", (error) => pageErrors.push(error));
+    const hydrationErrorPattern = /hydrat|did not match|react\.dev\/errors\/4(18|2[1235])|react error #4(18|2[1235])/i;
+    page.on("console", (message) => {
+      if (message.type() === "error" && hydrationErrorPattern.test(message.text())) {
+        hydrationErrors.push(message.text());
+      }
+    });
+    let releaseRefresh: (() => void) | undefined;
 
     try {
       await page.goto(`${baseUrl}/auth/login`);
@@ -88,9 +129,18 @@ describe("lazy widget application graph", () => {
       const visibleBoard = page.locator("[data-homarr-dev-benchmark-board]").filter({ visible: true }).first();
       await expect(visibleBoard).toBeVisible({ timeout: 30_000 });
       const clockWidget = page.locator(
-        `[data-id="${itemId}"] .clock-widget-container, [data-grid-item-id="${itemId}"] .clock-widget-container`,
+        `[data-id="${clockItemId}"] .clock-widget-container, [data-grid-item-id="${clockItemId}"] .clock-widget-container`,
       );
       await expect(clockWidget.filter({ visible: true }).first()).toBeVisible({ timeout: 30_000 });
+      await expect(clockWidget.locator("time").filter({ visible: true }).first()).not.toHaveText("--:--", {
+        timeout: 30_000,
+      });
+      const downloadsWidget = page
+        .locator(`[data-id="${downloadsItemId}"], [data-grid-item-id="${downloadsItemId}"]`)
+        .filter({ visible: true })
+        .first();
+      const cachedDownload = downloadsWidget.getByText("Big.Buck.Bunny.2008.1080p.BluRay.x264");
+      await expect(cachedDownload).toBeVisible({ timeout: 30_000 });
 
       await expect(page.locator("[data-homarr-dev-benchmark-spotlight-preloaded]")).toHaveCount(1, {
         timeout: 15_000,
@@ -101,23 +151,59 @@ describe("lazy widget application graph", () => {
       await page.keyboard.press("Escape");
       await expect(page.locator("[data-homarr-dev-benchmark-spotlight]")).not.toBeVisible();
 
-      await expect
-        .poll(
-          async () =>
-            await page.evaluate(async () => {
-              const registrations = await navigator.serviceWorker.getRegistrations();
-              return registrations[0]?.scope ?? null;
-            }),
-          { timeout: 15_000 },
-        )
-        .toBe(`${baseUrl}/`);
+      let refreshRequestStarted = false;
+      const refreshGate = new Promise<void>((resolve) => {
+        releaseRefresh = resolve;
+      });
+      const downloadsRequestPattern = "**/*widget.downloads.getJobsAndStatuses*";
+      const delayDownloadsRefresh = async (route: Route) => {
+        refreshRequestStarted = true;
+        await refreshGate;
+        await route.continue();
+      };
+      await page.route(downloadsRequestPattern, delayDownloadsRefresh);
 
-      await page.reload();
+      await page.reload({ waitUntil: "domcontentloaded" });
       await expect(clockWidget.filter({ visible: true }).first()).toBeVisible({ timeout: 30_000 });
+      await expect(clockWidget.locator("time").filter({ visible: true }).first()).not.toHaveText("--:--", {
+        timeout: 30_000,
+      });
+      await expect.poll(() => refreshRequestStarted, { timeout: 10_000 }).toBe(true);
+      await expect(cachedDownload).toBeVisible({ timeout: 5_000 });
+      await expect(downloadsWidget.locator("[data-widget-refreshing]")).toBeVisible();
+
+      const refreshedDownloadsResponse = page.waitForResponse(
+        (response) => response.url().includes("widget.downloads.getJobsAndStatuses") && response.ok(),
+      );
+      releaseRefresh();
+      releaseRefresh = undefined;
+      await refreshedDownloadsResponse;
+      await expect(downloadsWidget.locator("[data-widget-refreshing]")).toHaveCount(0);
+      await page.unroute(downloadsRequestPattern, delayDownloadsRefresh);
       expect(pageErrors).toEqual([]);
+      expect(hydrationErrors).toEqual([]);
+
+      const serviceWorkerContext = await browser.newContext();
+      const serviceWorkerPage = await serviceWorkerContext.newPage();
+      try {
+        await serviceWorkerPage.goto(`${baseUrl}/auth/login`);
+        await expect
+          .poll(
+            async () =>
+              await serviceWorkerPage.evaluate(async () => {
+                const registrations = await navigator.serviceWorker.getRegistrations();
+                return registrations[0]?.scope ?? null;
+              }),
+            { timeout: 15_000 },
+          )
+          .toBe(`${baseUrl}/`);
+      } finally {
+        await serviceWorkerContext.close();
+      }
     } finally {
+      releaseRefresh?.();
       await browser.close();
       await homarrContainer.stop();
     }
-  }, 120_000);
+  }, 180_000);
 });

packages/api/src/query-cache.ts

@@ -8,6 +8,8 @@ export const queryCacheDefaultGcTimeMs = 1000 * 60 * 5;
 export const queryCacheMetadataStaleTimeMs = 1000 * 60 * 5;
 
 const widgetDataQueryPaths = new Set(["app.byId", "app.byIds", "docker.getContainers", "integration.byIds"]);
+// Beszel system stats are large time-series payloads and were deliberately kept out of
+// the persisted cache in #6289; live stats come from an SSE subscription instead.
 const excludedWidgetPaths = new Set(["widget.app.ping", "widget.beszel.getSystemStats"]);
 
 export const isWidgetDataTrpcPath = (path: string) => {

packages/boards/src/context.tsx

@@ -10,12 +10,16 @@ import { clientApi } from "@homarr/api/client";
 import { boardViewportWidthCookieName, getLayoutIdForViewportWidth } from "./layout-selection";
 import { updateBoardName } from "./updater";
 
-const BoardContext = createContext<{
-  board: RouterOutputs["board"]["getBoardByName"];
+type Board = RouterOutputs["board"]["getBoardByName"];
+
+interface BoardContextValue {
+  board: Board;
   layoutOverrideId: string | null;
   currentLayout: string;
   initialViewportWidth: number;
-} | null>(null);
+}
+
+const BoardContext = createContext<BoardContextValue | null>(null);
 
 const subscribeToViewport = (onStoreChange: () => void) => {
   if (typeof window === "undefined") return () => undefined;
@@ -37,6 +41,23 @@ const subscribeToViewport = (onStoreChange: () => void) => {
   };
 };
 
+export const BoardPreviewProvider = ({ children, board }: PropsWithChildren<{ board: Board }>) => {
+  const currentLayout = board.layouts[0]?.id ?? "";
+
+  return (
+    <BoardContext.Provider
+      value={{
+        board,
+        layoutOverrideId: null,
+        currentLayout,
+        initialViewportWidth: 0,
+      }}
+    >
+      {children}
+    </BoardContext.Provider>
+  );
+};
+
 export const BoardProvider = ({
   children,
   initialBoard,

packages/translation/src/lang/en.json

@@ -2082,10 +2082,12 @@
           "label": "Section or rail"
         },
         "width": {
-          "label": "Width"
+          "label": "Width",
+          "shortLabel": "W"
         },
         "height": {
-          "label": "Height"
+          "label": "Height",
+          "shortLabel": "H"
         },
         "xOffset": {
           "label": "X offset"
@@ -2114,6 +2116,13 @@
         "loading": "Loading integration",
         "loadError": "This integration could not be loaded. Try again before changing its connection settings."
       },
+      "preview": {
+        "integrationRequired": "Choose a connection to preview this widget.",
+        "size": "Size"
+      },
+      "settings": {
+        "label": "Widget settings"
+      },
       "advancedOptions": {
         "label": "Advanced options",
         "title": "Advanced item options"
@@ -7762,6 +7771,8 @@
       "ready": "Widget configuration ready",
       "cancelled": "Widget was not added",
       "automaticContinue": "Accepting the proposed widget configuration automatically",
+      "definitionLoadErrorTitle": "Widget settings could not be loaded",
+      "definitionLoadErrorDescription": "Homarr could not load this widget's settings. Try again.",
       "loadErrorTitle": "Integrations could not be loaded",
       "loadErrorDescription": "Homarr could not load the integrations available for this widget.",
       "noIntegrationTitle": "A compatible integration is required",

packages/ui/src/index.ts

@@ -2,7 +2,7 @@ import type { MantineProviderProps } from "@mantine/core";
 
 import { theme } from "./theme";
 
-export { theme } from "./theme";
+export { scrollAreaDefaultProps, theme } from "./theme";
 export { modalSizeForm, modalSizeSelect } from "./theme/modal";
 export * from "./components";
 

packages/ui/src/theme.ts

@@ -2,6 +2,13 @@ import { createTheme, rem } from "@mantine/core";
 
 import { modalComponent } from "./theme/modal";
 
+export const scrollAreaDefaultProps = {
+  type: "hover",
+  scrollbarSize: 2,
+  scrollHideDelay: 500,
+  offsetScrollbars: true,
+} as const;
+
 export const theme = createTheme({
   primaryColor: "red",
   autoContrast: true,
@@ -96,6 +103,12 @@ export const theme = createTheme({
         style: { borderRadius: 5 },
       },
     },
+    ScrollArea: {
+      defaultProps: scrollAreaDefaultProps,
+    },
+    ScrollAreaAutosize: {
+      defaultProps: scrollAreaDefaultProps,
+    },
     LoadingOverlay: {
       defaultProps: {
         zIndex: 1000,

packages/widgets/package.json

@@ -30,7 +30,8 @@
     "./widget-integration-select": "./src/widget-integration-select.tsx",
     "./modals": "./src/modals/index.ts",
     "./prefetch": "./src/prefetch.ts",
-    "./refetch-intervals": "./src/refetch-intervals.ts"
+    "./refetch-intervals": "./src/refetch-intervals.ts",
+    "./widget-card-shell": "./src/widget-card-shell.tsx"
   },
   "scripts": {
     "clean": "rm -rf .turbo node_modules",

packages/widgets/src/_inputs/json-path-tree-picker.tsx

@@ -324,7 +324,7 @@ export function JsonPathTreePicker({
           </Combobox.Header>
         )}
         <Combobox.Options>
-          <ScrollArea.Autosize mah={420} type="scroll">
+          <ScrollArea.Autosize mah={420}>
             {!hasData && <Combobox.Empty>{noDataHint}</Combobox.Empty>}
             {hasData && visibleNodes.length === 0 && <Combobox.Empty>No matching paths</Combobox.Empty>}
             {visibleNodes.map((node) => (

packages/widgets/src/air-quality/component.tsx

@@ -171,7 +171,7 @@ const AdvancedAirQuality = ({ airQuality, options, width }: AirQualityViewProps
   ];
 
   return (
-    <ScrollArea h="100%" w="100%" type="auto" offsetScrollbars scrollbarSize={6}>
+    <ScrollArea h="100%" w="100%">
       <Stack gap="md" p="md">
         <Group justify="space-between" align="flex-start" wrap="wrap">
           <Stack gap={2}>

packages/widgets/src/bookmarks/add-button.tsx

@@ -163,7 +163,7 @@ export const BookmarkAddButton: SortableItemListInput<BookmarkSelectionItem, str
       </Combobox.DropdownTarget>
 
       <Combobox.Dropdown>
-        <ScrollArea.Autosize mah={280} type="auto">
+        <ScrollArea.Autosize mah={280}>
           <Combobox.Options>
             {pendingUrl && !selectedValues.has(pendingUrl.id) ? (
               <Combobox.Option value={createOptionValue}>

packages/widgets/src/bookmarks/bookmarks-widget.tsx

@@ -23,7 +23,8 @@ import { useRegisterSpotlightContextResults } from "@homarr/spotlight";
 import { useI18n } from "@homarr/translation/client";
 
 import { getSafeAppHref, SAFE_NEW_TAB_REL } from "../common/application-url";
-import { getUsableWidgetQueryData } from "../common/query-state";
+import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../common/query-state";
+import { WidgetQueryLoadingState } from "../common/query-state-indicator";
 import type { WidgetComponentProps } from "../definition";
 import { createDirectBookmark, getBookmarkFaviconUrl, getDirectBookmarkUrl } from "./bookmark-item";
 import type { BookmarkItem } from "./bookmark-item";
@@ -43,14 +44,12 @@ export default function BookmarksWidget({
   const board = useRequiredBoard();
   const advanced = displayMode === "advanced";
   const appIds = useMemo(() => options.items.filter((value) => !getDirectBookmarkUrl(value)), [options.items]);
-  const apps =
-    getUsableWidgetQueryData(
-      clientApi.app.byIds.useQuery(appIds, {
-        select(selectedApps) {
-          return selectedApps;
-        },
-      }),
-    ) ?? [];
+  const appsQuery = clientApi.app.byIds.useQuery(appIds, {
+    select(selectedApps) {
+      return selectedApps;
+    },
+  });
+  const apps = getUsableWidgetQueryData(appsQuery) ?? [];
   const appsById = new Map(apps.map((app) => [app.id, app]));
   const configuredItems = options.items.flatMap((value) => {
     const directUrl = getDirectBookmarkUrl(value);
@@ -127,6 +126,8 @@ export default function BookmarksWidget({
     />
   ));
 
+  if (appIds.length > 0 && isInitialWidgetQueryPending(appsQuery)) return <WidgetQueryLoadingState />;
+
   return (
     <Stack h="100%" mih={0} gap={height < 120 ? 6 : "sm"} p={height < 120 ? 6 : "sm"}>
       {options.title.length > 0 ? (
@@ -148,11 +149,7 @@ export default function BookmarksWidget({
         </Center>
       ) : (
         <ScrollArea
-          type="hover"
           scrollbars={plan.horizontalScroll ? "x" : "y"}
-          scrollbarSize={2}
-          scrollHideDelay={500}
-          offsetScrollbars
           style={{ flex: 1, minHeight: 0 }}
         >
           <Box miw="100%" mih="100%" pb={2}>

packages/widgets/src/calendar/calendar-event-list.tsx

@@ -56,7 +56,6 @@ export const CalendarEventList = ({
 
   return (
     <ScrollArea
-      offsetScrollbars
       pt={5}
       w="100%"
       h={fillHeight ? "100%" : undefined}

packages/widgets/src/calendar/component.tsx

@@ -15,7 +15,8 @@ import { useCurrentIntlLocale, useI18n } from "@homarr/translation/client";
 
 import actionTargetClasses from "../common/action-target.module.css";
 import type { WidgetComponentProps } from "../definition";
-import { getUsableWidgetQueryData } from "../common/query-state";
+import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../common/query-state";
+import { WidgetQueryLoadingState } from "../common/query-state-indicator";
 import { useWidgetRuntimeQueries } from "../runtime-hooks";
 import { IntegrationErrorIndicator } from "../common/integration-error-indicator";
 import { CalendarDay } from "./calender-day";
@@ -98,6 +99,8 @@ const FetchCalendar = ({ month, setMonth, isEditMode, integrationIds, options, d
       error ? [{ integrationId: integration.id, integrationName: integration.name, error }] : [],
     ) ?? [];
 
+  if (isInitialWidgetQueryPending(calendarQuery)) return <WidgetQueryLoadingState />;
+
   return (
     <CalendarBase
       isEditMode={isEditMode}

packages/widgets/src/clock/advanced-view.tsx

@@ -68,9 +68,6 @@ export const AdvancedClockView = ({
     <ScrollArea
       h="100%"
       w="100%"
-      type="auto"
-      offsetScrollbars
-      scrollbarSize={6}
       aria-label={t("worldClock.advancedLabel")}
     >
       <Stack gap="md" p={{ base: "sm", sm: "md" }}>

packages/widgets/src/common/homarr-data-table.css

@@ -22,6 +22,16 @@
   background-color: color-mix(in srgb, var(--mantine-color-default-hover) 40%, transparent) !important;
 }
 
+.homarr-data-table .mantine-datatable-scroll-area-scrollbar[data-state="visible"]:hover {
+  @mixin light {
+    background-color: var(--mantine-color-gray-0);
+  }
+
+  @mixin dark {
+    background-color: var(--mantine-color-dark-8);
+  }
+}
+
 .homarr-data-table th {
   padding: 0;
   white-space: nowrap;

packages/widgets/src/common/homarr-data-table.tsx

@@ -6,6 +6,8 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { DataTableColumn, DataTableProps } from "mantine-datatable";
 import { DataTable } from "mantine-datatable";
 
+import { scrollAreaDefaultProps } from "@homarr/ui";
+
 const fallbackColumnWidth = 60;
 
 const getColumnWidth = (width: string | number | undefined): number => {
@@ -153,7 +155,7 @@ export function HomarrDataTable<T>({
         resizable: true,
         cellsStyle: defaultColumnProps?.cellsStyle ?? (() => ({ padding: cellPadding })),
       }}
-      scrollAreaProps={{ type: "auto", scrollbarSize: 6, ...scrollAreaProps }}
+      scrollAreaProps={{ ...scrollAreaDefaultProps, ...scrollAreaProps }}
     />
   );
 }

packages/widgets/src/countdown/component.tsx

@@ -184,7 +184,7 @@ export default function CountdownWidget({
         onNotificationsChange={setNotifications}
       />
 
-      <ScrollArea type="auto" style={{ flex: 1, minHeight: 0 }}>
+      <ScrollArea style={{ flex: 1, minHeight: 0 }}>
         <Stack gap="md" pb="xs">
           <EventSection
             title={t("upcoming")}

packages/widgets/src/dns-hole/controls/component.tsx

@@ -34,7 +34,8 @@ import { MaskedOrNormalImage } from "@homarr/ui";
 import type { widgetKind } from ".";
 import type { WidgetComponentProps } from "../../definition";
 import { IntegrationErrorIndicator } from "../../common/integration-error-indicator";
-import { getUsableWidgetQueryData } from "../../common/query-state";
+import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../../common/query-state";
+import { WidgetQueryLoadingState } from "../../common/query-state-indicator";
 import actionTargetClasses from "../../common/action-target.module.css";
 import classes from "./component.module.css";
 import TimerModal from "./TimerModal";
@@ -67,7 +68,6 @@ export default function DnsHoleControlsWidget({
   const summaryQuery = clientApi.widget.dnsHole.summary.useQuery({ integrationIds });
   const summaryResults = getUsableWidgetQueryData(summaryQuery) ?? [];
   const summaries = summaryResults.filter(isAvailableDnsSummaryResult);
-  const { isPending: isSummaryPending } = summaryQuery;
   const utils = clientApi.useUtils();
 
   const {
@@ -122,7 +122,6 @@ export default function DnsHoleControlsWidget({
   );
 
   const t = useI18n("widget.dnsHoleControls");
-  const tCommon = useI18n("common");
 
   // Timer modal setup
   const [selectedIntegrationIds, setSelectedIntegrationIds] = useState<string[]>([]);
@@ -141,15 +140,7 @@ export default function DnsHoleControlsWidget({
     setBulkPending(false);
   };
 
-  if (isSummaryPending) {
-    return (
-      <Stack h="100%" justify="center" align="center">
-        <Text c="dimmed" size="sm">
-          {tCommon("action.loading")}
-        </Text>
-      </Stack>
-    );
-  }
+  if (isInitialWidgetQueryPending(summaryQuery)) return <WidgetQueryLoadingState />;
 
   return (
     <Stack

packages/widgets/src/dns-hole/summary/component.tsx

@@ -31,7 +31,8 @@ import type { TablerIcon } from "@homarr/ui";
 import type { widgetKind } from ".";
 import type { WidgetComponentProps, WidgetProps } from "../../definition";
 import { IntegrationErrorIndicator } from "../../common/integration-error-indicator";
-import { getUsableWidgetQueryData } from "../../common/query-state";
+import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../../common/query-state";
+import { WidgetQueryLoadingState } from "../../common/query-state-indicator";
 
 export default function DnsHoleSummaryWidget({
   options,
@@ -43,10 +44,8 @@ export default function DnsHoleSummaryWidget({
     integrationIds,
   });
   const summaries = getUsableWidgetQueryData(summaryQuery) ?? [];
-  const { isPending } = summaryQuery;
 
   const t = useI18n();
-  const tCommon = useI18n("common");
   const tDns = useI18n("widget.dnsHoleSummary");
   const tWidgetCommon = useI18n("widget.common");
 
@@ -55,15 +54,7 @@ export default function DnsHoleSummaryWidget({
   const layoutProps = boxPropsByLayout(options.layout);
   const showSourceStatuses = successfulSummaries.length > 1 && width >= 240 && height >= 220;
 
-  if (isPending) {
-    return (
-      <Stack h="100%" justify="center" align="center">
-        <Text c="dimmed" size="sm">
-          {tCommon("action.loading")}
-        </Text>
-      </Stack>
-    );
-  }
+  if (isInitialWidgetQueryPending(summaryQuery)) return <WidgetQueryLoadingState />;
 
   return (
     <Stack h="100%" gap={0} pos="relative">
@@ -102,7 +93,7 @@ export default function DnsHoleSummaryWidget({
         )}
       </SimpleGrid>
       {showSourceStatuses && (
-        <ScrollArea type="auto" scrollbarSize={4} px="xs" pb="xs">
+        <ScrollArea px="xs" pb="xs">
           <Group gap="xs" wrap="nowrap">
             {successfulSummaries.map(({ integration, summary }) => (
               <Badge

packages/widgets/src/downloads/component.tsx

@@ -54,7 +54,8 @@ import { useCurrentIntlLocale, useI18n } from "@homarr/translation/client";
 
 import type { WidgetComponentProps } from "../definition";
 import { IntegrationErrorIndicator } from "../common/integration-error-indicator";
-import { getUsableWidgetQueryData } from "../common/query-state";
+import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../common/query-state";
+import { WidgetQueryLoadingState } from "../common/query-state-indicator";
 import { HomarrDataTable } from "../common/homarr-data-table";
 import { formatLocalizedDateTime } from "../common/locale";
 import { usePersistedTableLayout, useTableLayoutPersistence } from "../common/use-persisted-table-layout";
@@ -741,6 +742,8 @@ export default function DownloadClientsWidget({
     );
   }
 
+  if (isInitialWidgetQueryPending(downloadsQuery)) return <WidgetQueryLoadingState />;
+
   let rowContextMenuHandler: typeof handleContextMenu | undefined = handleContextMenu;
   if (isEditMode) rowContextMenuHandler = undefined;
 

packages/widgets/src/immich/album-carousel/component.tsx

@@ -223,7 +223,7 @@ function Carousel({
         )}
       </Box>
       {advanced && (
-        <ScrollArea type="never" scrollbarSize={0} px="xs" py={6}>
+        <ScrollArea px="xs" py={6}>
           <Group gap={6} wrap="nowrap">
             {assets.map((asset, index) => (
               <UnstyledButton

packages/widgets/src/index.tsx

@@ -3,9 +3,7 @@ import type { Loader } from "next/dynamic";
 import dynamic from "next/dynamic";
 import { Center, Loader as UiLoader } from "@mantine/core";
 
-import { objectEntries } from "@homarr/common";
 import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
-import type { SettingsContextProps } from "@homarr/settings/creator";
 
 import * as anchorNote from "./anchor-note";
 import * as audioStats from "./audio-stats";
@@ -41,7 +39,6 @@ import * as notebook from "./notebook";
 import * as paperlessNgx from "./paperless-ngx";
 import * as patchmon from "./patchmon";
 import * as notifications from "./notifications";
-import type { WidgetOptionDefinition } from "./options";
 import * as releases from "./releases";
 import * as rssFeed from "./rssFeed";
 import * as smartHomeEntityState from "./smart-home/entity-state";
@@ -191,19 +188,3 @@ export type inferSupportedIntegrationsStrict<TKind extends WidgetKind> = (Widget
 }
   ? WidgetImports[TKind]["definition"]["supportedIntegrations"]
   : never[])[number];
-
-export const reduceWidgetOptionsWithDefaultValues = (
-  kind: WidgetKind,
-  settings: Pick<SettingsContextProps, "enableStatusByDefault" | "forceDisableStatus">,
-  currentValue: Record<string, unknown> = {},
-) => {
-  const definition = widgetImports[kind].definition;
-  const options = definition.createOptions(settings) as Record<string, WidgetOptionDefinition>;
-  return objectEntries(options).reduce(
-    (prev, [key, value]) => ({
-      ...prev,
-      [key]: currentValue[key] ?? value.defaultValue,
-    }),
-    {} as Record<string, unknown>,
-  );
-};

packages/widgets/src/media-missing/component.tsx

@@ -125,7 +125,6 @@ export default function MediaMissingWidget({
   ) => (
     <ScrollArea
       h="100%"
-      scrollbarSize={4}
       startScrollPosition={tabScrollPositionsRef.current[tab]}
       onScrollPositionChange={(position) => {
         tabScrollPositionsRef.current[tab] = position;

packages/widgets/src/media-requests/list/component.tsx

@@ -15,7 +15,8 @@ import { useI18n } from "@homarr/translation/client";
 
 import { WidgetEmptyState } from "../../common/empty-state";
 import { getSafeApplicationUrl, SAFE_NEW_TAB_REL } from "../../common/application-url";
-import { getUsableWidgetQueryData } from "../../common/query-state";
+import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../../common/query-state";
+import { WidgetQueryLoadingState } from "../../common/query-state-indicator";
 import actionTargetClasses from "../../common/action-target.module.css";
 import { IntegrationErrorIndicator } from "../../common/integration-error-indicator";
 import type { WidgetComponentProps } from "../../definition";
@@ -35,17 +36,17 @@ export default function MediaServerWidget({
       .filter(({ id }) => integrationIds.includes(id))
       .map(({ id }) => id),
   );
-  const mediaRequestData = getUsableWidgetQueryData(
-    clientApi.widget.mediaRequests.getLatestRequests.useQuery({
-      integrationIds,
-      statuses:
-        options.statusFilter.length > 0
-          ? options.statusFilter
-          : ["pending", "approved", "declined", "failed", "completed"],
-      recentDays: options.recentDays,
-    }),
-  );
+  const mediaRequestQuery = clientApi.widget.mediaRequests.getLatestRequests.useQuery({
+    integrationIds,
+    statuses:
+      options.statusFilter.length > 0
+        ? options.statusFilter
+        : ["pending", "approved", "declined", "failed", "completed"],
+    recentDays: options.recentDays,
+  });
+  const mediaRequestData = getUsableWidgetQueryData(mediaRequestQuery);
 
+  if (isInitialWidgetQueryPending(mediaRequestQuery)) return <WidgetQueryLoadingState />;
   if (!mediaRequestData) return <WidgetEmptyState />;
   const { requests: mediaRequests, failedIntegrations } = mediaRequestData;
   if (mediaRequests.length === 0 && failedIntegrations.length === 0) throw new NoIntegrationDataError();
@@ -61,7 +62,6 @@ export default function MediaServerWidget({
       )}
       <ScrollArea
         className="mediaRequests-list-scrollArea"
-        scrollbarSize="md"
         style={{ flex: 1, minHeight: 0, pointerEvents: isEditMode ? "none" : undefined }}
       >
         <Stack className="mediaRequests-list-list" gap="xs" p="sm">

packages/widgets/src/media-requests/stats/component.tsx

@@ -23,7 +23,8 @@ import { useI18n } from "@homarr/translation/client";
 
 import { WidgetEmptyState } from "../../common/empty-state";
 import { getSafeApplicationUrl, SAFE_NEW_TAB_REL } from "../../common/application-url";
-import { getUsableWidgetQueryData } from "../../common/query-state";
+import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../../common/query-state";
+import { WidgetQueryLoadingState } from "../../common/query-state-indicator";
 import actionTargetClasses from "../../common/action-target.module.css";
 import { IntegrationErrorIndicator } from "../../common/integration-error-indicator";
 import type { WidgetComponentProps } from "../../definition";
@@ -42,10 +43,12 @@ export default function MediaServerWidget({
 }: WidgetComponentProps<"mediaRequests-requestStats">) {
   const t = useI18n("widget.mediaRequests-requestStats");
   const tCommon = useI18n("common");
-  const requestStats = getUsableWidgetQueryData(clientApi.widget.mediaRequests.getStats.useQuery({ integrationIds }));
+  const requestStatsQuery = clientApi.widget.mediaRequests.getStats.useQuery({ integrationIds });
+  const requestStats = getUsableWidgetQueryData(requestStatsQuery);
 
   const board = useRequiredBoard();
 
+  if (isInitialWidgetQueryPending(requestStatsQuery)) return <WidgetQueryLoadingState />;
   if (!requestStats) return <WidgetEmptyState />;
   if (
     requestStats.users.length === 0 &&

packages/widgets/src/modals/widget-edit-modal.module.css

@@ -0,0 +1,191 @@
+.workspace {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--mantine-spacing-lg);
+  align-items: start;
+}
+
+.workspace[data-with-preview][data-with-settings] {
+  grid-template-columns: minmax(0, 3fr) auto minmax(34rem, 2fr);
+}
+
+.previewPanel {
+  position: sticky;
+  top: 0;
+  width: 100%;
+  max-width: 52rem;
+  min-width: 0;
+  justify-self: center;
+}
+
+.previewDimensions {
+  position: absolute;
+  z-index: 2;
+  top: var(--mantine-spacing-xs);
+  right: var(--mantine-spacing-xs);
+  pointer-events: none;
+}
+
+.previewSizeControls {
+  position: absolute;
+  z-index: 3;
+  top: var(--mantine-spacing-xs);
+  left: var(--mantine-spacing-xs);
+  padding: 0.25rem 0.375rem;
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-sm);
+  background: color-mix(in srgb, var(--mantine-color-body) 92%, transparent);
+  box-shadow: var(--mantine-shadow-xs);
+  backdrop-filter: blur(8px);
+}
+
+.previewSizeInput {
+  width: 5rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.previewCanvas {
+  position: relative;
+  width: 100%;
+  height: clamp(24rem, calc(100dvh - 17rem), 44rem);
+  padding: var(--mantine-spacing-lg);
+  overflow: hidden;
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-md);
+  background-color: light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-8));
+  background-image:
+    linear-gradient(to right, color-mix(in srgb, var(--mantine-color-dimmed) 14%, transparent) 1px, transparent 1px),
+    linear-gradient(to bottom, color-mix(in srgb, var(--mantine-color-dimmed) 14%, transparent) 1px, transparent 1px);
+  background-size: 2rem 2rem;
+}
+
+.previewDivider {
+  height: auto;
+  align-self: stretch;
+}
+
+.previewViewport {
+  position: relative;
+  flex: 0 0 auto;
+  animation: dock-widget 260ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+.previewWidget {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform-origin: top left;
+}
+
+.previewContent {
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  user-select: none;
+}
+
+.settingsPanel {
+  min-width: 0;
+  max-height: calc(100dvh - 13rem);
+  padding-right: 0.25rem;
+  overflow-y: auto;
+  scrollbar-gutter: stable;
+}
+
+.settingsForm {
+  min-width: 0;
+}
+
+.fullWidthField {
+  grid-column: 1 / -1;
+}
+
+.switchOption {
+  display: flex;
+  cursor: pointer;
+  height: 4.5rem;
+  align-items: center;
+  padding: 0.625rem 0.75rem;
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-sm);
+  background: var(--mantine-color-body);
+}
+
+.switchOption > *,
+.switchOption :global(.mantine-Switch-root),
+.switchOption :global(.mantine-Switch-body) {
+  width: 100%;
+}
+
+.switchOption :global(.mantine-Switch-body) {
+  flex-direction: row-reverse;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--mantine-spacing-md);
+}
+
+.switchOption :global(.mantine-Switch-labelWrapper) {
+  min-width: 0;
+  flex: 1;
+}
+
+.switchOption :global(.mantine-Switch-description) {
+  display: -webkit-box;
+  overflow: hidden;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.footer {
+  position: sticky;
+  z-index: 3;
+  bottom: calc(var(--mantine-spacing-md) * -1);
+  margin-inline: calc(var(--mantine-spacing-md) * -1);
+  margin-bottom: calc(var(--mantine-spacing-md) * -1);
+  padding: var(--mantine-spacing-sm) var(--mantine-spacing-md);
+  border-top: 1px solid var(--mantine-color-default-border);
+  background: color-mix(in srgb, var(--mantine-color-body) 94%, transparent);
+  backdrop-filter: blur(10px);
+}
+
+@keyframes dock-widget {
+  from {
+    opacity: 0;
+    transform: translate(-1.25rem, 1rem) scale(0.92);
+  }
+
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@media (max-width: 68em) {
+  .workspace[data-with-preview][data-with-settings] {
+    grid-template-columns: 1fr;
+  }
+
+  .previewPanel {
+    position: static;
+    max-width: 44rem;
+  }
+
+  .previewDivider {
+    display: none;
+  }
+
+  .previewCanvas {
+    height: 24rem;
+  }
+
+  .settingsPanel {
+    max-height: none;
+    overflow: visible;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .previewViewport {
+    animation: none;
+  }
+}

packages/widgets/src/modals/widget-edit-modal.tsx

@@ -1,18 +1,38 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
-import type { ComponentType, FormEvent } from "react";
-import { Box, Button, Group, Stack, Tabs, Text } from "@mantine/core";
+/* eslint-disable react/no-unstable-nested-components -- Widget modules and definition-bound fallbacks are loaded dynamically. */
+
+import { useEffect, useId, useRef, useState } from "react";
+import type { ComponentType, FormEvent, PropsWithChildren } from "react";
+import {
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Center,
+  Divider,
+  Group,
+  NumberInput,
+  SimpleGrid,
+  Stack,
+  Tabs,
+  Text,
+  Tooltip,
+} from "@mantine/core";
 import { schemaResolver } from "@mantine/form";
-import { IconArrowLeft, IconPencil } from "@tabler/icons-react";
+import { useElementSize } from "@mantine/hooks";
+import { IconArrowLeft, IconEye, IconPencil, IconSettings } from "@tabler/icons-react";
+import { QueryErrorResetBoundary } from "@tanstack/react-query";
+import { ErrorBoundary } from "react-error-boundary";
 import { z } from "zod/v4";
 
 import { objectEntries } from "@homarr/common";
-import { useSession } from "@homarr/auth/client";
+import { IntegrationProvider, useSession } from "@homarr/auth/client";
 import { useOptionalBoard } from "@homarr/boards/context";
 import type { WidgetKind } from "@homarr/definitions";
-import { createModal, ModalFormFooter, modalSizeForm, useModalAction } from "@homarr/modals";
+import { createModal, modalSizeForm, useModalAction } from "@homarr/modals";
 import type { SettingsContextProps } from "@homarr/settings/creator";
+import { SpotlightProvider } from "@homarr/spotlight";
 import { useI18n } from "@homarr/translation/client";
 import { IntegrationAvatar } from "@homarr/ui";
 import { zodErrorMap } from "@homarr/validation/form/i18n";
@@ -21,13 +41,16 @@ import { getInputForType } from "../_inputs";
 import { FormProvider, useForm } from "../_inputs/form";
 import type { BoardItemAdvancedOptions } from "../../../validation/src/shared";
 import type { OptionsBuilderResult } from "../options";
-import type { WidgetDefinition } from "../definition";
+import type { WidgetComponentProps, WidgetDefinition } from "../definition";
+import { WidgetError } from "../errors/component";
 import { OPTIONS_SUPER_REFINE } from "../options";
 import type { IntegrationSelectOption } from "../widget-integration-select";
 import { WidgetIntegrationSelect } from "../widget-integration-select";
+import { WidgetCardShell, WidgetTitleBadge } from "../widget-card-shell";
 import { WidgetAdvancedOptionsModal } from "./widget-advanced-options-modal";
 import type { EmbeddedAppEditFormHandle } from "./embedded-app-edit-form";
 import { EmbeddedAppEditForm } from "./embedded-app-edit-form";
+import classes from "./widget-edit-modal.module.css";
 
 export interface WidgetEditModalState {
   options: Record<string, unknown>;
@@ -35,6 +58,17 @@ export interface WidgetEditModalState {
   advancedOptions: BoardItemAdvancedOptions;
 }
 
+export interface WidgetEditModalSize {
+  width: number;
+  height: number;
+}
+
+interface WidgetEditPreviewResizeOptions {
+  initialSize: WidgetEditModalSize;
+  maximumSize: WidgetEditModalSize;
+  getDimensions?: (size: WidgetEditModalSize) => { width: number; height: number; scale?: number };
+}
+
 export interface EmbeddedIntegrationEditFormHandle {
   submitIfDirty: () => Promise<boolean>;
 }
@@ -49,7 +83,7 @@ export interface WidgetEditModalProps<TSort extends WidgetKind> {
   kind: TSort;
   definition: WidgetDefinition;
   value: WidgetEditModalState;
-  onSuccessfulEdit: (value: WidgetEditModalState) => void;
+  onSuccessfulEdit: (value: WidgetEditModalState, size?: WidgetEditModalSize) => void;
   integrationData: IntegrationSelectOption[];
   integrationSupport: boolean;
   settings: SettingsContextProps;
@@ -59,8 +93,215 @@ export interface WidgetEditModalProps<TSort extends WidgetKind> {
   integrationEditForm?: ComponentType<EmbeddedIntegrationEditFormProps>;
   onIntegrationSaved?: () => void;
   onOpenNewIntegration?: (onCreated?: (id: string) => void) => void;
+  previewComponent?: ComponentType<WidgetComponentProps<TSort>>;
+  previewDimensions?: { width: number; height: number; scale?: number };
+  previewResize?: WidgetEditPreviewResizeOptions;
+  previewWrapper?: ComponentType<PropsWithChildren>;
 }
 
+interface WidgetEditPreviewProps {
+  kind: WidgetKind;
+  Component: ComponentType<WidgetComponentProps<WidgetKind>>;
+  definition: WidgetDefinition;
+  state: WidgetEditModalState;
+  itemId?: string;
+  boardId?: string;
+  dimensions?: { width: number; height: number; scale?: number };
+  integrationData: IntegrationSelectOption[];
+  onChangeOptions: (newOptions: Record<string, unknown>) => void;
+  resize?: {
+    size: WidgetEditModalSize;
+    maximumSize: WidgetEditModalSize;
+    onChange: (size: WidgetEditModalSize) => void;
+  };
+  PreviewWrapper?: ComponentType<PropsWithChildren>;
+}
+
+const PreviewRuntimeBoundary = ({
+  Wrapper,
+  children,
+}: PropsWithChildren<{ Wrapper?: ComponentType<PropsWithChildren> }>) => {
+  if (!Wrapper) return children;
+  return <Wrapper>{children}</Wrapper>;
+};
+
+const normalizePreviewSize = (size: WidgetEditModalSize, maximumSize: WidgetEditModalSize): WidgetEditModalSize => ({
+  width: Math.max(1, Math.min(Math.round(size.width), maximumSize.width)),
+  height: Math.max(1, Math.min(Math.round(size.height), maximumSize.height)),
+});
+
+const WidgetEditPreview = ({
+  kind,
+  Component,
+  definition,
+  state,
+  itemId,
+  boardId,
+  dimensions = { width: 400, height: 240 },
+  integrationData,
+  onChangeOptions,
+  resize,
+  PreviewWrapper,
+}: WidgetEditPreviewProps) => {
+  const t = useI18n();
+  const tItem = useI18n("item.edit");
+  const board = useOptionalBoard();
+  const generatedPreviewId = useId().replaceAll(":", "");
+  const { ref, width: availableWidth, height: availableHeight } = useElementSize<HTMLDivElement>();
+  const sourceWidth = Math.max(dimensions.width, 1);
+  const sourceHeight = Math.max(dimensions.height, 1);
+  let maximumScale = dimensions.scale ?? 0.9;
+  if (!Number.isFinite(maximumScale) || maximumScale <= 0) maximumScale = 0.9;
+  maximumScale = Math.min(maximumScale, 0.9);
+  let previewScale = maximumScale;
+  if (availableWidth > 0 && availableHeight > 0) {
+    previewScale = Math.min(availableWidth / sourceWidth, availableHeight / sourceHeight, maximumScale);
+  }
+  const previewWidth = sourceWidth * previewScale;
+  const previewHeight = sourceHeight * previewScale;
+
+  const hasIntegrationSupport = "supportedIntegrations" in definition;
+  const integrationRequired = hasIntegrationSupport && definition.integrationsRequired !== false;
+  const isMissingIntegration = integrationRequired && state.integrationIds.length === 0;
+  const previewIntegrations = integrationData
+    .filter((integration) => state.integrationIds.includes(integration.id))
+    .map((integration) => ({
+      id: integration.id,
+      permissions: integration.permissions ?? {
+        hasFullAccess: false,
+        hasInteractAccess: false,
+        hasUseAccess: false,
+      },
+    }));
+  let componentItemId = itemId;
+  if (kind === "assistant") componentItemId = `widget-preview-${generatedPreviewId}`;
+  const isPendingCustomWidget = kind === "customApi" && !itemId;
+  const previewOpacity = (board?.opacity ?? 100) / 100;
+  const handleResizeValue = (dimension: keyof WidgetEditModalSize, value: string | number) => {
+    if (typeof value !== "number" || !Number.isFinite(value) || !resize) return;
+    resize.onChange(
+      normalizePreviewSize(
+        {
+          ...resize.size,
+          [dimension]: value,
+        },
+        resize.maximumSize,
+      ),
+    );
+  };
+
+  return (
+    <Stack className={classes.previewPanel} gap={0}>
+      <Center ref={ref} className={classes.previewCanvas}>
+        {resize && (
+          <Group className={classes.previewSizeControls} gap={6} wrap="nowrap">
+            <Text size="xs" fw={600} c="dimmed">
+              {tItem("preview.size")}
+            </Text>
+            <Tooltip label={t("item.moveResize.field.width.label")}>
+              <NumberInput
+                className={classes.previewSizeInput}
+                aria-label={t("item.moveResize.field.width.label")}
+                value={resize.size.width}
+                onChange={(value) => handleResizeValue("width", value)}
+                min={1}
+                max={resize.maximumSize.width}
+                step={1}
+                allowDecimal={false}
+                allowNegative={false}
+                clampBehavior="strict"
+                size="xs"
+                leftSection={t("item.moveResize.field.width.shortLabel")}
+                leftSectionPointerEvents="none"
+              />
+            </Tooltip>
+            <Text size="xs" c="dimmed" aria-hidden>
+              ×
+            </Text>
+            <Tooltip label={t("item.moveResize.field.height.label")}>
+              <NumberInput
+                className={classes.previewSizeInput}
+                aria-label={t("item.moveResize.field.height.label")}
+                value={resize.size.height}
+                onChange={(value) => handleResizeValue("height", value)}
+                min={1}
+                max={resize.maximumSize.height}
+                step={1}
+                allowDecimal={false}
+                allowNegative={false}
+                clampBehavior="strict"
+                size="xs"
+                leftSection={t("item.moveResize.field.height.shortLabel")}
+                leftSectionPointerEvents="none"
+              />
+            </Tooltip>
+          </Group>
+        )}
+        <Badge className={classes.previewDimensions} size="xs" variant="light" color="gray">
+          {Math.round(sourceWidth)} × {Math.round(sourceHeight)}
+        </Badge>
+        {isMissingIntegration ? (
+          <Alert color="gray" variant="light" icon={<IconEye size={18} />} maw={320}>
+            {tItem("preview.integrationRequired")}
+          </Alert>
+        ) : (
+          <Box className={classes.previewViewport} w={previewWidth} h={previewHeight}>
+            <WidgetCardShell
+              className={classes.previewWidget}
+              kind={kind}
+              advancedOptions={state.advancedOptions}
+              opacity={previewOpacity}
+              radius={board?.itemRadius}
+              w={sourceWidth}
+              h={sourceHeight}
+              p={0}
+              data-grid-item-content
+              style={{ transform: `scale(${previewScale})` }}
+            >
+              <WidgetTitleBadge
+                advancedOptions={state.advancedOptions}
+                opacity={previewOpacity}
+                radius={board?.itemRadius}
+              />
+              <QueryErrorResetBoundary>
+                {({ reset }) => (
+                  <ErrorBoundary
+                    onReset={reset}
+                    resetKeys={[state.options, state.integrationIds]}
+                    fallbackRender={({ resetErrorBoundary, error }) => (
+                      <WidgetError definition={definition} error={error} resetErrorBoundary={resetErrorBoundary} />
+                    )}
+                  >
+                    <PreviewRuntimeBoundary Wrapper={PreviewWrapper}>
+                      <SpotlightProvider>
+                        <IntegrationProvider integrations={previewIntegrations}>
+                          <div className={classes.previewContent} inert>
+                            <Component
+                              options={state.options as never}
+                              integrationIds={state.integrationIds}
+                              width={sourceWidth}
+                              height={sourceHeight}
+                              isEditMode={isPendingCustomWidget}
+                              displayMode="compact"
+                              boardId={boardId}
+                              itemId={componentItemId}
+                              setOptions={({ newOptions }) => onChangeOptions(newOptions as Record<string, unknown>)}
+                            />
+                          </div>
+                        </IntegrationProvider>
+                      </SpotlightProvider>
+                    </PreviewRuntimeBoundary>
+                  </ErrorBoundary>
+                )}
+              </QueryErrorResetBoundary>
+            </WidgetCardShell>
+          </Box>
+        )}
+      </Center>
+    </Stack>
+  );
+};
+
 export const getSelectedWidgetIntegrations = (
   integrationData: readonly IntegrationSelectOption[],
   selectedIds: readonly string[],
@@ -81,6 +322,12 @@ export const WidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>(({
   const [mountedIntegrationIds, setMountedIntegrationIds] = useState<string[]>([]);
   const [activeIntegrationId, setActiveIntegrationId] = useState<string | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
+  const [previewSize, setPreviewSize] = useState<WidgetEditModalSize | null>(() => {
+    const resize = innerProps.previewResize;
+    if (!resize) return null;
+    return normalizePreviewSize(resize.initialSize, resize.maximumSize);
+  });
+  const widgetFormId = useId();
 
   z.config({
     customError: zodErrorMap(t),
@@ -206,10 +453,13 @@ export const WidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>(({
         }
       }
 
-      innerProps.onSuccessfulEdit({
-        ...values,
-        advancedOptions,
-      });
+      innerProps.onSuccessfulEdit(
+        {
+          ...values,
+          advancedOptions,
+        },
+        previewSize ?? undefined,
+      );
       actions.closeModal();
     } finally {
       setIsSubmitting(false);
@@ -231,47 +481,149 @@ export const WidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>(({
       }
     : undefined;
 
+  const handlePreviewOptionsChange = (newOptions: Record<string, unknown>) => {
+    form.setFieldValue("options", {
+      ...form.values.options,
+      ...newOptions,
+    });
+  };
+
+  const selectedIntegrationKinds = innerProps.integrationData
+    .filter(({ id }) => form.values.integrationIds.includes(id))
+    .map(({ kind }) => kind);
+  const visibleOptions = Object.entries(options).filter(([, value]) => {
+    const Input = getInputForType(value.type);
+    if (!Input) {
+      return false;
+    }
+
+    return !value.shouldHide?.(form.values.options as never, selectedIntegrationKinds);
+  });
+  const switchOptions = visibleOptions.filter(([, value]) => value.type === "switch");
+  const otherOptions = visibleOptions.filter(([, value]) => value.type !== "switch");
+  const hasWidgetSettings = canConfigureWidget && (innerProps.integrationSupport || visibleOptions.length > 0);
+  const previewResize = innerProps.previewResize;
+  let previewDimensions = innerProps.previewDimensions;
+  let resizeControls: WidgetEditPreviewProps["resize"];
+  if (previewSize && previewResize?.getDimensions) {
+    previewDimensions = previewResize.getDimensions(previewSize);
+    resizeControls = {
+      size: previewSize,
+      maximumSize: previewResize.maximumSize,
+      onChange: setPreviewSize,
+    };
+  }
+
   const widgetFormContent = (
-    <Stack>
-      {canConfigureWidget && innerProps.integrationSupport && (
-        <WidgetIntegrationSelect
-          label={tItem("field.integrations.label")}
-          data={innerProps.integrationData}
-          canSelectMultiple={maxIntegrations > 1}
-          withAsterisk={integrationsRequired}
-          onOpenNewIntegration={canCreateIntegration ? handleOpenNewIntegration : undefined}
-          {...form.getInputProps("integrationIds")}
+    <Box
+      className={classes.workspace}
+      data-with-preview={innerProps.previewComponent ? true : undefined}
+      data-with-settings={hasWidgetSettings ? true : undefined}
+    >
+      {innerProps.previewComponent && (
+        <WidgetEditPreview
+          kind={innerProps.kind}
+          Component={innerProps.previewComponent}
+          definition={definition}
+          state={{ ...form.values, advancedOptions }}
+          itemId={innerProps.itemId}
+          boardId={innerProps.boardId ?? board?.id}
+          dimensions={previewDimensions}
+          integrationData={innerProps.integrationData}
+          onChangeOptions={handlePreviewOptionsChange}
+          resize={resizeControls}
+          PreviewWrapper={innerProps.previewWrapper}
         />
       )}
-      {canConfigureWidget &&
-        Object.entries(options).map(([key, value]) => {
-          const Input = getInputForType(value.type);
+      {innerProps.previewComponent && hasWidgetSettings && (
+        <Divider orientation="vertical" className={classes.previewDivider} />
+      )}
+      <form id={widgetFormId} className={classes.settingsForm} onSubmit={onFormSubmit} hidden={!hasWidgetSettings}>
+        {hasWidgetSettings && (
+          <Stack className={classes.settingsPanel} gap="sm">
+            <Group gap="xs" wrap="nowrap">
+              <IconSettings size={16} />
+              <Text fw={600} size="sm">
+                {tItem("settings.label")}
+              </Text>
+            </Group>
+            {canConfigureWidget && innerProps.integrationSupport && (
+              <Box className={classes.fullWidthField}>
+                <WidgetIntegrationSelect
+                  label={tItem("field.integrations.label")}
+                  data={innerProps.integrationData}
+                  canSelectMultiple={maxIntegrations > 1}
+                  withAsterisk={integrationsRequired}
+                  onOpenNewIntegration={canCreateIntegration ? handleOpenNewIntegration : undefined}
+                  {...form.getInputProps("integrationIds")}
+                />
+              </Box>
+            )}
+            {canConfigureWidget && (
+              <Stack gap="sm">
+                {switchOptions.length > 0 && (
+                  <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="sm" verticalSpacing="sm">
+                    {switchOptions.map(([key, value]) => {
+                      const Input = getInputForType(value.type);
+                      if (!Input) {
+                        return null;
+                      }
 
-          if (
-            !Input ||
-            value.shouldHide?.(
-              form.values.options as never,
-              innerProps.integrationData
-                .filter(({ id }) => form.values.integrationIds.includes(id))
-                .map(({ kind }) => kind),
-            )
-          ) {
-            return null;
-          }
+                      return (
+                        <Box
+                          key={key}
+                          className={classes.switchOption}
+                          data-option-type={value.type}
+                          onClick={(event) => {
+                            const target = event.target;
+                            if (target instanceof Element && target.closest("label, input")) return;
+                            const input = event.currentTarget.querySelector<HTMLInputElement>("input[type=checkbox]");
+                            if (!input?.disabled) input?.click();
+                          }}
+                        >
+                          <Input
+                            kind={innerProps.kind}
+                            property={key}
+                            options={value as never}
+                            initialOptions={innerProps.value.options}
+                            itemId={innerProps.itemId}
+                            boardId={innerProps.boardId ?? board?.id}
+                          />
+                        </Box>
+                      );
+                    })}
+                  </SimpleGrid>
+                )}
+                {otherOptions.map(([key, value]) => {
+                  const Input = getInputForType(value.type);
+                  if (!Input) {
+                    return null;
+                  }
 
-          return (
-            <Input
-              key={key}
-              kind={innerProps.kind}
-              property={key}
-              options={value as never}
-              initialOptions={innerProps.value.options}
-              itemId={innerProps.itemId}
-              boardId={innerProps.boardId ?? board?.id}
-            />
-          );
-        })}
-      {showResourceTabs ? (
+                  return (
+                    <Box key={key} data-option-type={value.type}>
+                      <Input
+                        kind={innerProps.kind}
+                        property={key}
+                        options={value as never}
+                        initialOptions={innerProps.value.options}
+                        itemId={innerProps.itemId}
+                        boardId={innerProps.boardId ?? board?.id}
+                      />
+                    </Box>
+                  );
+                })}
+              </Stack>
+            )}
+          </Stack>
+        )}
+      </form>
+    </Box>
+  );
+
+  const footer = (
+    <Box className={classes.footer}>
+      <Group justify="space-between" wrap="nowrap">
         <Button
           variant="subtle"
           type="button"
@@ -284,143 +636,111 @@ export const WidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>(({
         >
           {tItem("advancedOptions.label")}
         </Button>
-      ) : (
-        <ModalFormFooter
-          onCancel={actions.closeModal}
-          leftSection={
-            <Button
-              variant="subtle"
-              type="button"
-              onClick={() =>
-                openModal({
-                  advancedOptions,
-                  onSuccess: setAdvancedOptions,
-                })
-              }
-            >
-              {tItem("advancedOptions.label")}
-            </Button>
-          }
-        />
-      )}
-    </Stack>
+        <Group gap="xs" wrap="nowrap">
+          <Button onClick={actions.closeModal} variant="subtle" color="gray">
+            {tCommon("action.cancel")}
+          </Button>
+          <Button type="submit" form={widgetFormId} loading={isSubmitting}>
+            {tCommon("action.saveChanges")}
+          </Button>
+        </Group>
+      </Group>
+    </Box>
   );
 
   return (
-    <form onSubmit={onFormSubmit}>
-      <FormProvider form={form}>
+    <FormProvider form={form}>
+      <Stack gap="sm">
         {showResourceTabs ? (
-          <Stack>
-            <Tabs value={activeTab} onChange={setActiveTab}>
-              <Tabs.List grow>
-                <Tabs.Tab value="widget">{tItem("tab.widget")}</Tabs.Tab>
-                {showAppTab && <Tabs.Tab value="app">{tItem("tab.app")}</Tabs.Tab>}
-                {showIntegrationTab && <Tabs.Tab value="integration">{tItem("tab.integration")}</Tabs.Tab>}
-              </Tabs.List>
-              <Tabs.Panel value="widget" pt="md">
-                {widgetFormContent}
+          <Tabs value={activeTab} onChange={setActiveTab}>
+            <Tabs.List grow>
+              <Tabs.Tab value="widget">{tItem("tab.widget")}</Tabs.Tab>
+              {showAppTab && <Tabs.Tab value="app">{tItem("tab.app")}</Tabs.Tab>}
+              {showIntegrationTab && <Tabs.Tab value="integration">{tItem("tab.integration")}</Tabs.Tab>}
+            </Tabs.List>
+            <Tabs.Panel value="widget" pt="sm">
+              {widgetFormContent}
+            </Tabs.Panel>
+            {showAppTab && (
+              <Tabs.Panel value="app" pt="sm">
+                {appId && <EmbeddedAppEditForm appId={appId} handleRef={appEditRef} />}
               </Tabs.Panel>
-              {showAppTab && (
-                <Tabs.Panel value="app" pt="md">
-                  {appId && <EmbeddedAppEditForm appId={appId} handleRef={appEditRef} />}
-                </Tabs.Panel>
-              )}
-              {showIntegrationTab && (
-                <Tabs.Panel value="integration" pt="md">
-                  <Stack>
-                    {displayedIntegrationId === null && (
-                      <>
-                        <Text size="sm" c="dimmed">
-                          {tItem("integration.description")}
-                        </Text>
-                        {selectedIntegrations.map((integration) => {
-                          const canEdit = editableIntegrationIds.includes(integration.id);
-                          return (
-                            <Group key={integration.id} justify="space-between" wrap="nowrap" gap="sm">
-                              <Group gap="sm" wrap="nowrap" style={{ minWidth: 0 }}>
-                                <IntegrationAvatar kind={integration.kind} size="sm" />
-                                <Stack gap={0} style={{ minWidth: 0 }}>
-                                  <Text fw={600} size="sm" truncate>
-                                    {integration.name}
-                                  </Text>
-                                  <Text size="xs" c="dimmed" truncate>
-                                    {integration.url}
-                                  </Text>
-                                </Stack>
-                              </Group>
-                              {canEdit ? (
-                                <Button
-                                  type="button"
-                                  variant="light"
-                                  leftSection={<IconPencil size={16} />}
-                                  onClick={() => beginEditingIntegration(integration.id)}
-                                  aria-label={tItem("integration.editLabel", { name: integration.name })}
-                                >
-                                  {tItem("integration.action")}
-                                </Button>
-                              ) : (
-                                <Text size="xs" c="dimmed" ta="end">
-                                  {tItem("integration.fullAccessRequired")}
+            )}
+            {showIntegrationTab && (
+              <Tabs.Panel value="integration" pt="sm">
+                <Stack>
+                  {displayedIntegrationId === null && (
+                    <>
+                      <Text size="sm" c="dimmed">
+                        {tItem("integration.description")}
+                      </Text>
+                      {selectedIntegrations.map((integration) => {
+                        const canEdit = editableIntegrationIds.includes(integration.id);
+                        return (
+                          <Group key={integration.id} justify="space-between" wrap="nowrap" gap="sm">
+                            <Group gap="sm" wrap="nowrap" style={{ minWidth: 0 }}>
+                              <IntegrationAvatar kind={integration.kind} size="sm" />
+                              <Stack gap={0} style={{ minWidth: 0 }}>
+                                <Text fw={600} size="sm" truncate>
+                                  {integration.name}
                                 </Text>
-                              )}
+                                <Text size="xs" c="dimmed" truncate>
+                                  {integration.url}
+                                </Text>
+                              </Stack>
                             </Group>
-                          );
-                        })}
-                      </>
-                    )}
-                    {displayedIntegrationId !== null && selectedIntegrations.length > 1 && (
-                      <Button
-                        type="button"
-                        variant="subtle"
-                        leftSection={<IconArrowLeft size={16} />}
-                        onClick={() => setActiveIntegrationId(null)}
-                        style={{ alignSelf: "start" }}
-                      >
-                        {tCommon("action.previous")}
-                      </Button>
-                    )}
-                    {integrationIdsToRender.map((integrationId) => (
-                      <Box key={integrationId} hidden={displayedIntegrationId !== integrationId}>
-                        {IntegrationEditForm && (
-                          <IntegrationEditForm
-                            integrationId={integrationId}
-                            handleRef={getIntegrationEditRef(integrationId)}
-                            onSuccess={innerProps.onIntegrationSaved}
-                          />
-                        )}
-                      </Box>
-                    ))}
-                  </Stack>
-                </Tabs.Panel>
-              )}
-            </Tabs>
-            <Box
-              pos="sticky"
-              bottom={0}
-              style={{
-                marginInline: "calc(var(--mantine-spacing-md) * -1)",
-                marginBottom: "calc(var(--mantine-spacing-md) * -1)",
-                paddingInline: "var(--mantine-spacing-md)",
-                paddingBlock: "var(--mantine-spacing-sm)",
-                background: "var(--mantine-color-body)",
-                borderTop: "1px solid var(--mantine-color-default-border)",
-              }}
-            >
-              <Group justify="end">
-                <Button onClick={actions.closeModal} variant="subtle" color="gray">
-                  {tCommon("action.cancel")}
-                </Button>
-                <Button type="submit" loading={isSubmitting}>
-                  {tCommon("action.saveChanges")}
-                </Button>
-              </Group>
-            </Box>
-          </Stack>
+                            {canEdit ? (
+                              <Button
+                                type="button"
+                                variant="light"
+                                leftSection={<IconPencil size={16} />}
+                                onClick={() => beginEditingIntegration(integration.id)}
+                                aria-label={tItem("integration.editLabel", { name: integration.name })}
+                              >
+                                {tItem("integration.action")}
+                              </Button>
+                            ) : (
+                              <Text size="xs" c="dimmed" ta="end">
+                                {tItem("integration.fullAccessRequired")}
+                              </Text>
+                            )}
+                          </Group>
+                        );
+                      })}
+                    </>
+                  )}
+                  {displayedIntegrationId !== null && selectedIntegrations.length > 1 && (
+                    <Button
+                      type="button"
+                      variant="subtle"
+                      leftSection={<IconArrowLeft size={16} />}
+                      onClick={() => setActiveIntegrationId(null)}
+                      style={{ alignSelf: "start" }}
+                    >
+                      {tCommon("action.previous")}
+                    </Button>
+                  )}
+                  {integrationIdsToRender.map((integrationId) => (
+                    <Box key={integrationId} hidden={displayedIntegrationId !== integrationId}>
+                      {IntegrationEditForm && (
+                        <IntegrationEditForm
+                          integrationId={integrationId}
+                          handleRef={getIntegrationEditRef(integrationId)}
+                          onSuccess={innerProps.onIntegrationSaved}
+                        />
+                      )}
+                    </Box>
+                  ))}
+                </Stack>
+              </Tabs.Panel>
+            )}
+          </Tabs>
         ) : (
           widgetFormContent
         )}
-      </FormProvider>
-    </form>
+        {footer}
+      </Stack>
+    </FormProvider>
   );
 }).withOptions({
   keepMounted: true,

packages/widgets/src/notebook/notebook.tsx

@@ -500,7 +500,6 @@ export function Notebook({
 
         <ScrollArea
           mih="4rem"
-          offsetScrollbars
           pl={12}
           pt={12}
           styles={{

packages/widgets/src/timer/component.tsx

@@ -387,7 +387,7 @@ const AdvancedTimer = ({
   const t = useI18n("widget.timer");
   const phaseLabel = getTimerPhaseLabel(runtime, t);
   return (
-    <ScrollArea h="100%" w="100%" type="auto" offsetScrollbars scrollbarSize={6}>
+    <ScrollArea h="100%" w="100%">
       <Stack gap="md" p="md">
         <Paper
           withBorder

packages/widgets/src/umami/component.module.css

@@ -5,7 +5,6 @@
 }
 
 .chartSurface :global(.mantine-ScrollArea-viewport),
-.chartSurface :global(.mantine-ScrollArea-scrollbar),
 .chartSurface :global(.recharts-wrapper),
 .chartSurface :global(.recharts-surface) {
   background-color: transparent !important;

packages/widgets/src/vpn/component.tsx

@@ -46,7 +46,7 @@ export default function VpnWidget({ options, integrationIds, width, height }: Wi
   }
 
   return (
-    <ScrollArea className="scroll-area-w100" w="100%" h="100%" offsetScrollbars p="xs">
+    <ScrollArea className="scroll-area-w100" w="100%" h="100%" p="xs">
       <SimpleGrid cols={width >= 640 ? 2 : 1} spacing="sm">
         {integrations.map((result) => (
           <Stack key={result.integration.id} gap={4}>

packages/widgets/src/weather/advanced.tsx

@@ -143,7 +143,7 @@ export const AdvancedWeather = ({ height, options, weather, width }: AdvancedWea
   const ticks = hourly.filter((_, index) => index % layout.hourlyTickStep === 0).map((hour) => hour.observedAt);
 
   return (
-    <ScrollArea h="100%" w="100%" type="auto" offsetScrollbars scrollbarSize={6}>
+    <ScrollArea h="100%" w="100%">
       <Stack className={classes.advancedRoot} gap="md" p="md">
         <Group justify="space-between" align="flex-start" gap="md" wrap="wrap">
           <Group gap="md" wrap="nowrap">

packages/widgets/src/widget-card-shell.module.css

@@ -0,0 +1,34 @@
+.card {
+  @mixin dark {
+    --background-color: rgb(from var(--mantine-color-dark-6) r g b / var(--opacity));
+    --default-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));
+    --default-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, var(--default-border-color)) !important;
+}
+
+.card.iframe {
+  background-color: transparent !important;
+  border-color: transparent !important;
+}
+
+.title {
+  @mixin dark {
+    --background-color: rgb(from var(--mantine-color-dark-6) r g b / var(--opacity));
+    --default-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));
+    --default-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, var(--default-border-color)) !important;
+}

packages/widgets/src/widget-card-shell.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import type { AriaRole, CSSProperties, PropsWithChildren, Ref } from "react";
+import type { CardProps } from "@mantine/core";
+import { Badge, Card } from "@mantine/core";
+import combineClasses from "clsx";
+
+import type { WidgetKind } from "@homarr/definitions";
+import type { BoardItemAdvancedOptions } from "@homarr/validation/shared";
+
+import classes from "./widget-card-shell.module.css";
+
+const getOverflow = (kind: WidgetKind, hasCustomCssClasses: boolean): CSSProperties => {
+  if (kind === "systemResources") return { overflowX: "visible", overflowY: "visible" };
+  if (kind === "iframe" || kind === "assistant") return { overflowX: "hidden", overflowY: "hidden" };
+  if (hasCustomCssClasses) return {};
+  return { overflowX: "hidden", overflowY: "auto" };
+};
+
+interface WidgetCardShellProps extends PropsWithChildren<Omit<CardProps, "className" | "styles">> {
+  kind: WidgetKind;
+  advancedOptions: BoardItemAdvancedOptions;
+  opacity: number;
+  className?: string;
+  innerRef?: Ref<HTMLDivElement>;
+  id?: string;
+  role?: AriaRole;
+  "aria-label"?: string;
+  "data-advanced-focus-surface"?: boolean;
+  "data-grid-item-content"?: boolean;
+}
+
+export const WidgetCardShell = ({
+  kind,
+  advancedOptions,
+  opacity,
+  className,
+  innerRef,
+  children,
+  ...cardProps
+}: WidgetCardShellProps) => (
+  <Card
+    {...cardProps}
+    ref={innerRef}
+    className={combineClasses(
+      classes.card,
+      kind === "iframe" && classes.iframe,
+      `${kind}-wrapper`,
+      "board-grid-item-content",
+      advancedOptions.customCssClasses.join(" "),
+      className,
+    )}
+    styles={{
+      root: {
+        "--opacity": opacity,
+        "--border-color": advancedOptions.borderColor || undefined,
+        containerType: "size",
+        ...getOverflow(kind, advancedOptions.customCssClasses.length > 0),
+      } as CSSProperties,
+    }}
+  >
+    {children}
+  </Card>
+);
+
+interface WidgetTitleBadgeProps {
+  advancedOptions: BoardItemAdvancedOptions;
+  opacity: number;
+  radius: CardProps["radius"];
+}
+
+export const WidgetTitleBadge = ({ advancedOptions, opacity, radius }: WidgetTitleBadgeProps) => {
+  if (!advancedOptions.title?.trim()) return null;
+
+  return (
+    <Badge
+      pos="absolute"
+      style={{ zIndex: "var(--mantine-z-index-app)" }}
+      top={2}
+      left={16}
+      size="xs"
+      radius={radius}
+      styles={{
+        root: {
+          "--border-color": advancedOptions.borderColor || undefined,
+          "--opacity": opacity,
+        } as CSSProperties,
+      }}
+      className={classes.title}
+      c="var(--mantine-color-text)"
+    >
+      {advancedOptions.title}
+    </Badge>
+  );
+};

pnpm-lock.yaml

@@ -201,6 +201,9 @@ catalogs:
     '@tanstack/react-query-next-experimental':
       specifier: ^5.101.2
       version: 5.101.2
+    '@tanstack/react-query-persist-client':
+      specifier: ^5.101.2
+      version: 5.101.2
     '@testcontainers/mysql':
       specifier: ^12.0.4
       version: 12.0.4
@@ -1142,6 +1145,9 @@ importers:
       '@tanstack/react-query-next-experimental':
         specifier: 'catalog:'
         version: 5.101.2(@tanstack/react-query@5.101.2(react@19.2.7))(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7)
+      '@tanstack/react-query-persist-client':
+        specifier: 'catalog:'
+        version: 5.101.2(@tanstack/react-query@5.101.2(react@19.2.7))(react@19.2.7)
       '@trpc/client':
         specifier: 'catalog:'
         version: 11.18.0(@trpc/server@11.18.0(typescript@7.0.2))(typescript@7.0.2)
@@ -8831,6 +8837,9 @@ packages:
   '@tanstack/query-devtools@5.101.2':
     resolution: {integrity: sha512-o+wHcqgN7Pp0s8v1i0UGq/ZrrEKrxdIiMQmKRdYb2w7NPtylYSJ4+wg/tIn71m9DLstwUwdEGAvROdly6HXP6w==}
 
+  '@tanstack/query-persist-client-core@5.101.2':
+    resolution: {integrity: sha512-rgMsbvBVpSPDUsprC9FYxojdG0Q1LH6yq1i3DXz2aps4VEqv2l4Msj3YDqIifU3xkl/DrYe9YWntZAJLrM6xTg==}
+
   '@tanstack/react-devtools@0.10.9':
     resolution: {integrity: sha512-lS6mtccEmUaodsWiRORGM/MGKT0jgzcy5v+eY6pzOPxEgzTHUDhca+WGxShFqKxmF4oneRxXjww1gkvMrWq6uw==}
     engines: {node: '>=18'}
@@ -8853,6 +8862,12 @@ packages:
       next: ^13 || ^14 || ^15 || ^16
       react: ^18 || ^19
 
+  '@tanstack/react-query-persist-client@5.101.2':
+    resolution: {integrity: sha512-19UpaRtf0lvB2QAJ2MoixxtGf3osMOd508g99EsttUj4+3eLs+ulnNgYjB7AkQMHrRlcbVXqpVNqWkB4a7g8Zw==}
+    peerDependencies:
+      '@tanstack/react-query': ^5.101.2
+      react: ^18 || ^19
+
   '@tanstack/react-query@5.101.2':
     resolution: {integrity: sha512-seDkr6kzGzX1okaaTtZPtgA688CDPlXUz1C6xSg0ESqn04Vuc8tlrYms1s3de+znBqhPVxFRfpAfUf+6XvfPWg==}
     peerDependencies:
@@ -23923,6 +23938,10 @@ snapshots:
 
   '@tanstack/query-devtools@5.101.2': {}
 
+  '@tanstack/query-persist-client-core@5.101.2':
+    dependencies:
+      '@tanstack/query-core': 5.101.2
+
   '@tanstack/react-devtools@0.10.9(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(csstype@3.2.3)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(solid-js@1.9.14)':
     dependencies:
       '@tanstack/devtools': 0.13.0(csstype@3.2.3)(solid-js@1.9.14)
@@ -23948,6 +23967,12 @@ snapshots:
       next: 16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0)
       react: 19.2.7
 
+  '@tanstack/react-query-persist-client@5.101.2(@tanstack/react-query@5.101.2(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@tanstack/query-persist-client-core': 5.101.2
+      '@tanstack/react-query': 5.101.2(react@19.2.7)
+      react: 19.2.7
+
   '@tanstack/react-query@5.101.2(react@19.2.7)':
     dependencies:
       '@tanstack/query-core': 5.101.2

pnpm-workspace.yaml

@@ -63,6 +63,7 @@ catalog:
   "@tanstack/react-query": ^5.101.2
   "@tanstack/react-query-devtools": ^5.101.2
   "@tanstack/react-query-next-experimental": ^5.101.2
+  "@tanstack/react-query-persist-client": ^5.101.2
   "@testcontainers/mysql": ^12.0.4
   "@testcontainers/postgresql": ^12.0.4
   "@testcontainers/redis": ^12.0.4