feat(custom-widgets): improve authoring workbench

2026-08-23 22:25:54 +02:00
1 parent ec295fe26e
commit 2153069a2f
@@ -41,6 +41,10 @@ needs attention.
 4. Write responsive JSX using `data`, `status`, `options`, and temporary `inputs`.
 5. Test and preview, inspect Data and the redacted request journal, then save.

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

+import { useMemo } from "react";
 import type { ComponentProps } from "react";

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

-import { buildCustomWidgetAiPrompt } from "@homarr/custom-widgets/authoring-prompt";
+import { buildCustomWidgetAiPrompt, buildCustomWidgetAssistantPrompt } from "@homarr/custom-widgets/authoring-prompt";
+import type { CustomWidgetAiDiagnostic, CustomWidgetAiDraft } from "@homarr/custom-widgets/authoring-prompt";
 import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
 import { useI18n } from "@homarr/translation/client";

@@ -11,29 +12,38 @@ import { useOptionalHomarrAssistant } from "~/components/assistant/assistant-con

 interface CopyAiPromptButtonProps {
  rawResponse?: string | null;
-  currentConfig?: Record<string, unknown> | null;
+  draft: CustomWidgetAiDraft;
+  diagnostics: readonly CustomWidgetAiDiagnostic[];
  request?: string | null;
  documentationUrl?: string | null;
 }

 export const CopyAiPromptButton = ({
  rawResponse,
-  currentConfig,
+  draft,
+  diagnostics,
  request,
  documentationUrl,
 }: CopyAiPromptButtonProps) => {
  const t = useI18n("customWidget");
  const assistant = useOptionalHomarrAssistant();
-  const prompt = () => buildCustomWidgetAiPrompt(undefined, rawResponse, currentConfig, request, documentationUrl);

  const handleAssistant = () => {
-    if (!assistant?.enabled || !assistant.sendPrompt(prompt())) return;
+    const prompt = buildCustomWidgetAssistantPrompt(
+      undefined,
+      rawResponse,
+      draft,
+      request,
+      documentationUrl,
+      diagnostics,
+    );
+    if (!assistant?.enabled || !assistant.sendPrompt(prompt)) return;
    showSuccessNotification({ title: t("action.aiPrompt"), message: t("notification.aiPromptSent") });
  };

  const handleCopy = async () => {
    try {
-      const value = prompt();
+      const value = buildCustomWidgetAiPrompt(undefined, rawResponse, draft, request, documentationUrl, diagnostics);
      await navigator.clipboard.writeText(value);
      showSuccessNotification({
        title: t("action.copyAiPrompt"),
@@ -1,7 +1,6 @@
 "use client";

 import { useEffect, useState } from "react";
-import { Accordion } from "@mantine/core";

 import { customWidgetDefinitionSchema } from "@homarr/custom-widgets/core";
 import { useI18n } from "@homarr/translation/client";
@@ -9,8 +8,18 @@ import { useI18n } from "@homarr/translation/client";
 import { CodeEditor } from "./_code-editor";
 import { applyDefinition, parseJson } from "./_custom-widget-form-utils";
 import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
+import { LazyOnceAccordion } from "./_lazy-once-accordion";

 export function CustomWidgetAdvancedManifest({ form }: { form: CustomWidgetWorkbenchForm }) {
+  const t = useI18n("customWidget.workbench.builder");
+  return (
+    <LazyOnceAccordion label={t("advancedManifest")}>
+      <CustomWidgetManifestEditor form={form} />
+    </LazyOnceAccordion>
+  );
+}
+
+function CustomWidgetManifestEditor({ form }: { form: CustomWidgetWorkbenchForm }) {
  const t = useI18n("customWidget.workbench.builder");
  const serialized = JSON.stringify(
    {
@@ -30,33 +39,26 @@ export function CustomWidgetAdvancedManifest({ form }: { form: CustomWidgetWorkb
  const [error, setError] = useState<string>();
  useEffect(() => setDraft(serialized), [serialized]);
  return (
-    <Accordion variant="contained">
-      <Accordion.Item value="manifest">
-        <Accordion.Control>{t("advancedManifest")}</Accordion.Control>
-        <Accordion.Panel>
-          <CodeEditor
-            id="raw-widget-manifest"
-            label={t("manifestFilename")}
-            language="json"
-            value={draft}
-            error={error}
-            onChange={(next) => {
-              setDraft(next);
-              try {
-                const parsed = customWidgetDefinitionSchema.safeParse(JSON.parse(next) as unknown);
-                if (!parsed.success) {
-                  setError(parsed.error.issues[0]?.message ?? t("invalidWidget"));
-                  return;
-                }
-                setError(undefined);
-                applyDefinition(form, parsed.data);
-              } catch (cause) {
-                setError(cause instanceof Error ? cause.message : t("invalidJson"));
-              }
-            }}
-          />
-        </Accordion.Panel>
-      </Accordion.Item>
-    </Accordion>
+    <CodeEditor
+      id="raw-widget-manifest"
+      label={t("manifestFilename")}
+      language="json"
+      value={draft}
+      error={error}
+      onChange={(next) => {
+        setDraft(next);
+        try {
+          const parsed = customWidgetDefinitionSchema.safeParse(JSON.parse(next) as unknown);
+          if (!parsed.success) {
+            setError(parsed.error.issues[0]?.message ?? t("invalidWidget"));
+            return;
+          }
+          setError(undefined);
+          applyDefinition(form, parsed.data);
+        } catch (cause) {
+          setError(cause instanceof Error ? cause.message : t("invalidJson"));
+        }
+      }}
+    />
  );
 }
@@ -3,13 +3,14 @@
 import { Accordion, Button, Group, Stack, Text, TextInput, Textarea } from "@mantine/core";
 import { IconClipboard, IconSparkles } from "@tabler/icons-react";

-import type { HomarrCustomWidgetV2 } from "@homarr/custom-widgets/core";
+import type { CustomWidgetAiDiagnostic, CustomWidgetAiDraft } from "@homarr/custom-widgets/authoring-prompt";
 import { useI18n } from "@homarr/translation/client";

 import { CopyAiPromptButton } from "./_copy-ai-prompt-button";

 interface AiCardProps {
-  candidate: HomarrCustomWidgetV2 | null;
+  draft: CustomWidgetAiDraft;
+  diagnostics: readonly CustomWidgetAiDiagnostic[];
  request: string;
  onRequestChange(value: string): void;
  documentationUrl: string;
@@ -27,14 +28,15 @@ export function CustomWidgetAiCard(props: AiCardProps) {
            {t("title")}
          </Accordion.Control>
          <CopyAiPromptButton
-            currentConfig={props.candidate}
+            draft={props.draft}
+            diagnostics={props.diagnostics}
            request={props.request}
            documentationUrl={props.documentationUrl}
          />
        </Group>
        <Accordion.Panel>
          <Stack gap="sm">
-            <Text size="sm" c="dimmed">
+            <Text size="sm" c="light-dark(var(--mantine-color-gray-7), var(--mantine-color-gray-4))">
              {t("description")}
            </Text>
            <Textarea
@@ -2,7 +2,10 @@ import type { CustomWidgetFormValues, EditorDiagnostic } from "@homarr/custom-wi

 import { isRecord, parseJson, parseSources } from "./_custom-widget-form-utils";

-export function createCustomWidgetCompletions(values: CustomWidgetFormValues, requestIds: string[]) {
+export function createCustomWidgetCompletions(
+  values: Pick<CustomWidgetFormValues, "options" | "sources">,
+  requestIds: string[],
+) {
  const options = parseJson(values.options);
  const optionKeys = Object.keys(isRecord(options) ? options : {});
  return [
@@ -12,6 +12,8 @@ import type { UseFormReturnType } from "@mantine/form";

 export type CustomWidgetWorkbenchForm = UseFormReturnType<CustomWidgetFormValues>;

+const PREVIEW_QUERY_CONCURRENCY = 4;
+
 export function buildDefinition(values: CustomWidgetFormValues) {
  return customWidgetDefinitionSchema.safeParse({
    $schema: "homarr-custom-widget-v2",
@@ -25,7 +27,7 @@ export function buildDefinition(values: CustomWidgetFormValues) {
  });
 }

-export function getChangedSecrets(values: CustomWidgetFormValues) {
+export function getChangedSecrets(values: Pick<CustomWidgetFormValues, "secrets">) {
  return values.secrets
    .filter((secret) => secret.value.trim())
    .map(({ sourceId, kind, value }) => ({
@@ -102,25 +104,43 @@ export function isRuntimeParams(
 }

 export async function loadPreviewQueries(definition: HomarrCustomWidgetV2, sessionId: string) {
-  const data: Record<string, unknown> = {};
-  const status: Record<string, unknown> = {};
-  for (const [requestId] of Object.entries(definition.requests).filter(
+  const requests = Object.entries(definition.requests).filter(
    ([, entry]) => entry.kind === "query" && entry.trigger === "load",
-  )) {
-    try {
-      const result = await fetchApi.customWidget.previewQuery.query({ sessionId, requestId, params: {} });
-      data[requestId] = result.data;
-      status[requestId] = { loading: false, ...result };
-    } catch (error) {
-      data[requestId] = null;
-      status[requestId] = {
-        loading: false,
-        ok: false,
-        error: error instanceof Error ? error.message : "Request failed",
-      };
+  );
+  const results: Array<{
+    requestId: string;
+    data: unknown;
+    status: Record<string, unknown>;
+  }> = [];
+  let nextIndex = 0;
+  const worker = async () => {
+    while (true) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const request = requests[index];
+      if (!request) return;
+      const [requestId] = request;
+      try {
+        const result = await fetchApi.customWidget.previewQuery.query({ sessionId, requestId, params: {} });
+        results[index] = { requestId, data: result.data, status: { loading: false, ...result } };
+      } catch (error) {
+        results[index] = {
+          requestId,
+          data: null,
+          status: {
+            loading: false,
+            ok: false,
+            error: error instanceof Error ? error.message : "Request failed",
+          },
+        };
+      }
    }
-  }
-  return { data, status };
+  };
+  await Promise.all(Array.from({ length: Math.min(PREVIEW_QUERY_CONCURRENCY, requests.length) }, () => worker()));
+  return {
+    data: Object.fromEntries(results.map((result) => [result.requestId, result.data])),
+    status: Object.fromEntries(results.map((result) => [result.requestId, result.status])),
+  };
 }

 export function getDefinitionDefaults(definition: HomarrCustomWidgetV2) {
@@ -1,7 +1,7 @@
 "use client";

-import { useEffect, useMemo, useState } from "react";
-import { Accordion, Box, Button, Paper, SegmentedControl, Stack, TextInput, Textarea } from "@mantine/core";
+import { useCallback, useDeferredValue, useEffect, useMemo, useState } from "react";
+import { Box, Button, Paper, SegmentedControl, Stack, TextInput, Textarea } from "@mantine/core";
 import {
  IconAlertCircle,
  IconApi,
@@ -18,8 +18,9 @@ import {
  customWidgetFormSchema,
  DEFAULT_CUSTOM_WIDGET_FORM_VALUES,
 } from "@homarr/custom-widgets/workbench";
+import type { CustomWidgetAiDiagnostic, CustomWidgetAiDraft } from "@homarr/custom-widgets/authoring-prompt";
 import { customWidgetOptionsSchema, getCustomWidgetDefaultOptions } from "@homarr/custom-widgets/core";
-import type { CustomWidgetFormValues } from "@homarr/custom-widgets/workbench";
+import type { CustomWidgetFormValues, EditorDiagnostic } from "@homarr/custom-widgets/workbench";
 import { useZodForm } from "@homarr/form";
 import { IconPicker } from "@homarr/forms-collection";
 import { useI18n } from "@homarr/translation/client";
@@ -38,6 +39,7 @@ import { CustomWidgetRequestsEditor } from "./_custom-widget-requests-editor";
 import { createCustomWidgetRenameHandlers } from "./_custom-widget-rename-handlers";
 import { CustomWidgetSaveIssuesAlert } from "./_custom-widget-save-issues-alert";
 import { CustomWidgetSourcesEditor } from "./_custom-widget-sources-editor";
+import { LazyOnceAccordion } from "./_lazy-once-accordion";
 import { useCustomWidgetFormActions } from "./_use-custom-widget-form-actions";
 import { useUnsavedChangesGuard } from "./_use-unsaved-changes-guard";
 import classes from "./_custom-widget-form.module.css";
@@ -56,6 +58,20 @@ const sectionLinks = [
  ["preview", "section.preview", IconEye],
 ] as const;

+function normalizeEditorDiagnostics(
+  section: "requests" | "template",
+  diagnostics: readonly EditorDiagnostic[],
+): CustomWidgetAiDiagnostic[] {
+  return diagnostics.map((diagnostic) => ({
+    section,
+    severity: diagnostic.severity,
+    code: diagnostic.code,
+    line: diagnostic.line,
+    column: diagnostic.column,
+    message: diagnostic.value,
+  }));
+}
+
 export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWidgetFormProps) {
  const t = useI18n("customWidget");
  const tCommon = useI18n("common");
@@ -73,27 +89,30 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
  });
  useUnsavedChangesGuard(form.isDirty());

-  const candidate = useMemo(() => buildDefinition(form.values), [form.values]);
+  const analysisValues = useDeferredValue(form.values);
+  const candidate = useMemo(() => buildDefinition(analysisValues), [analysisValues]);
  const parsedOptions = useMemo(
-    () => customWidgetOptionsSchema.safeParse(parseJson(form.values.options)),
-    [form.values.options],
-  );
-  const requestIds = useMemo(
-    () =>
-      Object.keys(
-        isRecord(parseJson(form.values.requests)) ? (parseJson(form.values.requests) as Record<string, unknown>) : {},
-      ),
-    [form.values.requests],
+    () => customWidgetOptionsSchema.safeParse(parseJson(analysisValues.options)),
+    [analysisValues.options],
  );
+  const requestIds = useMemo(() => {
+    const parsedRequests = parseJson(analysisValues.requests);
+    return isRecord(parsedRequests) ? Object.keys(parsedRequests) : [];
+  }, [analysisValues.requests]);
+  const requestIdsSignature = requestIds.join("\0");
  const jsxCompletions = useMemo(
-    () => createCustomWidgetCompletions(form.values, requestIds),
-    [form.values, requestIds],
+    () =>
+      createCustomWidgetCompletions(
+        { options: analysisValues.options, sources: analysisValues.sources },
+        requestIdsSignature ? requestIdsSignature.split("\0") : [],
+      ),
+    [analysisValues.options, analysisValues.sources, requestIdsSignature],
  );
  const templateDiagnostics = useMemo(
-    () => analyzeJsxTemplate(form.values.template, { requestIds }),
-    [form.values.template, requestIds],
+    () => analyzeJsxTemplate(analysisValues.template, { requestIds }),
+    [analysisValues.template, requestIds],
  );
-  const requestDiagnostics = useMemo(() => analyzeRequestManifest(form.values.requests), [form.values.requests]);
+  const requestDiagnostics = useMemo(() => analyzeRequestManifest(analysisValues.requests), [analysisValues.requests]);
  const hasDiagnostics = [...templateDiagnostics, ...requestDiagnostics].some((entry) => entry.severity === "error");
  const invalidSections = useMemo(
    () =>
@@ -104,13 +123,47 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
      ),
    [candidate, requestDiagnostics, templateDiagnostics],
  );
+  const aiDraft = useMemo<CustomWidgetAiDraft>(
+    () => ({
+      name: form.values.name,
+      description: form.values.description,
+      iconUrl: form.values.iconUrl,
+      sources: form.values.sources,
+      requests: form.values.requests,
+      options: form.values.options,
+      template: form.values.template,
+    }),
+    [
+      form.values.description,
+      form.values.iconUrl,
+      form.values.name,
+      form.values.options,
+      form.values.requests,
+      form.values.sources,
+      form.values.template,
+    ],
+  );
+  const aiDiagnostics = useMemo<CustomWidgetAiDiagnostic[]>(() => {
+    const diagnostics = [
+      ...normalizeEditorDiagnostics("requests", requestDiagnostics),
+      ...normalizeEditorDiagnostics("template", templateDiagnostics),
+    ];
+    if (candidate.success) return diagnostics;
+    return [
+      ...candidate.error.issues.map((issue) => ({
+        section: String(issue.path[0] ?? "definition"),
+        severity: "error" as const,
+        path: issue.path.map(String).join(".") || undefined,
+        message: issue.message,
+      })),
+      ...diagnostics,
+    ];
+  }, [candidate, requestDiagnostics, templateDiagnostics]);

  const { save, runPreview, pasteAiResponse, saveIssues, savePending, previewPending } = useCustomWidgetFormActions({
    mode,
    definitionId,
    form,
-    candidate,
-    preview,
    setPreview,
    setMobilePane,
    optionsSnapshot,
@@ -123,9 +176,26 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
  const invalid = hasDiagnostics || !candidate.success;
  const { renameRequest, renameOption } = createCustomWidgetRenameHandlers({
    form,
-    candidate,
    invalidWidgetMessage: w("invalidWidget"),
  });
+  const previewValidationIssues = useMemo(
+    () =>
+      candidate.success
+        ? []
+        : candidate.error.issues.map((issue) => ({
+            path: issue.path.map(String).join(".") || undefined,
+            message: issue.message,
+          })),
+    [candidate],
+  );
+  const handleLiveActionsChange = useCallback(
+    (enabled: boolean) =>
+      setPreview((current) => ({
+        ...current,
+        session: current.session ? { ...current.session, liveActions: enabled } : null,
+      })),
+    [],
+  );
  return (
    <form onSubmit={save} className={classes.form}>
      <SegmentedControl
@@ -161,7 +231,8 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
      <div className={classes.workbench} data-mobile-pane={mobilePane}>
        <Stack gap="lg" className={classes.configuration}>
          <CustomWidgetAiCard
-            candidate={candidate.success ? candidate.data : null}
+            draft={aiDraft}
+            diagnostics={aiDiagnostics}
            request={request}
            onRequestChange={setRequest}
            documentationUrl={documentationUrl}
@@ -183,44 +254,34 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
          </EditorSection>
          <EditorSection id="requests" title={w("requests.title")} icon={IconDatabase}>
            <CustomWidgetRequestsEditor form={form} onRename={renameRequest} />
-            <Accordion variant="contained">
-              <Accordion.Item value="raw">
-                <Accordion.Control>{w("builder.advancedJson")}</Accordion.Control>
-                <Accordion.Panel>
-                  <CodeEditor
-                    id="requests-editor"
-                    label={w("requests.label")}
-                    description={w("requests.description")}
-                    language="json"
-                    value={form.values.requests}
-                    onChange={(value) => form.setFieldValue("requests", value)}
-                    diagnostics={requestDiagnostics}
-                    error={form.errors.requests}
-                    reference={customWidgetRequestReference}
-                    required
-                  />
-                </Accordion.Panel>
-              </Accordion.Item>
-            </Accordion>
+            <LazyOnceAccordion label={w("builder.advancedJson")}>
+              <CodeEditor
+                id="requests-editor"
+                label={w("requests.label")}
+                description={w("requests.description")}
+                language="json"
+                value={form.values.requests}
+                onChange={(value) => form.setFieldValue("requests", value)}
+                diagnostics={requestDiagnostics}
+                error={form.errors.requests}
+                reference={customWidgetRequestReference}
+                required
+              />
+            </LazyOnceAccordion>
          </EditorSection>
          <EditorSection id="options" title={w("options.title")} icon={IconBraces}>
            <CustomWidgetOptionsEditor form={form} onRename={renameOption} />
-            <Accordion variant="contained">
-              <Accordion.Item value="raw">
-                <Accordion.Control>{w("builder.advancedJson")}</Accordion.Control>
-                <Accordion.Panel>
-                  <CodeEditor
-                    id="options"
-                    label={w("options.title")}
-                    language="json"
-                    value={form.values.options}
-                    onChange={(value) => form.setFieldValue("options", value)}
-                    error={form.errors.options}
-                    reference={customWidgetOptionsSchemaReference}
-                  />
-                </Accordion.Panel>
-              </Accordion.Item>
-            </Accordion>
+            <LazyOnceAccordion label={w("builder.advancedJson")}>
+              <CodeEditor
+                id="options-editor"
+                label={w("options.title")}
+                language="json"
+                value={form.values.options}
+                onChange={(value) => form.setFieldValue("options", value)}
+                error={form.errors.options}
+                reference={customWidgetOptionsSchemaReference}
+              />
+            </LazyOnceAccordion>
          </EditorSection>
          <EditorSection id="jsx" title={w("jsx.title")} icon={IconCode}>
            <CodeEditor
@@ -260,25 +321,13 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
          </Paper>
          <CustomWidgetPreviewPanel
            candidate={candidate.success ? candidate.data : null}
-            validationIssues={
-              candidate.success
-                ? []
-                : candidate.error.issues.map((issue) => ({
-                    path: issue.path.map(String).join(".") || undefined,
-                    message: issue.message,
-                  }))
-            }
+            validationIssues={previewValidationIssues}
            preview={preview}
            size={previewSize}
            onSizeChange={setPreviewSize}
            optionsSnapshot={optionsSnapshot}
            onOptionsChange={setOptionsSnapshot}
-            onLiveActionsChange={(enabled) =>
-              setPreview((current) => ({
-                ...current,
-                session: current.session ? { ...current.session, liveActions: enabled } : null,
-              }))
-            }
+            onLiveActionsChange={handleLiveActionsChange}
          />
        </Box>
      </div>
@@ -69,7 +69,7 @@ export function CustomWidgetOptionsEditor({
            )
          : [];
        return (
-          <Fieldset key={index} legend={typeof option.label === "string" ? option.label : id}>
+          <Fieldset key={id} legend={typeof option.label === "string" ? option.label : id}>
            <Stack gap="sm">
              <Group grow align="start">
                <CustomWidgetIdentifierInput
@@ -99,7 +99,7 @@ export function CustomWidgetOptionsEditor({
                }
              />
              <DefaultValueEditor
-                id={`${index}-default`}
+                id={`${id}-default`}
                control={control}
                value={option.default}
                choices={choices}
@@ -6,6 +6,8 @@ interface PreviewSnapshot {
  session: { id: string; liveActions: boolean } | null;
 }

+type PreviewCandidate = Pick<HomarrCustomWidgetV2, "requests" | "template">;
+
 export function createPreviewDisplayData({
  candidate,
  fixture,
@@ -13,7 +15,7 @@ export function createPreviewDisplayData({
  options,
  fixtureError,
 }: {
-  candidate: HomarrCustomWidgetV2 | null;
+  candidate: PreviewCandidate | null;
  fixture: "live" | "loading" | "empty" | "error";
  preview: PreviewSnapshot;
  options: Record<string, unknown>;
@@ -1,7 +1,19 @@
 "use client";

-import { useState } from "react";
-import { Alert, Box, Card, Group, Paper, SegmentedControl, Stack, Switch, Tabs, Text } from "@mantine/core";
+import { memo, useMemo, useState } from "react";
+import {
+  Alert,
+  Box,
+  Card,
+  Group,
+  Paper,
+  SegmentedControl,
+  Stack,
+  Switch,
+  Tabs,
+  Text,
+  VisuallyHidden,
+} from "@mantine/core";

 import { clientApi } from "@homarr/api/client";
 import type { HomarrCustomWidgetV2 } from "@homarr/custom-widgets/core";
@@ -18,6 +30,8 @@ import { createPreviewDisplayData } from "./_custom-widget-preview-data";
 import { JsonPreviewEditor } from "./_json-preview-editor";
 import classes from "./_custom-widget-form.module.css";

+const previewWidths: Record<string, number> = { compact: 320, standard: 480, wide: 720 };
+
 export interface PreviewState {
  data: Record<string, unknown>;
  status: Record<string, unknown>;
@@ -36,7 +50,7 @@ interface PreviewPanelProps {
  onLiveActionsChange(enabled: boolean): void;
 }

-export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
+function CustomWidgetPreviewPanelContent(props: PreviewPanelProps) {
  const t = useI18n("customWidget.workbench.preview");
  const errorBoundaryMessages = useI18n("customWidget.editor.errorBoundary");
  const actionT = useI18n("common.action");
@@ -46,26 +60,55 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
    { sessionId: props.preview.session?.id ?? "" },
    { enabled: Boolean(props.preview.session), refetchInterval: props.preview.session ? 2_000 : false },
  );
-  const widths: Record<string, number> = { compact: 320, standard: 480, wide: 720 };
  const candidate = props.candidate;
-  const accessibilityIssues = candidate ? analyzeCustomWidgetAccessibility(candidate.template) : [];
-  const displayData = createPreviewDisplayData({
-    candidate,
-    fixture,
-    preview: props.preview,
-    options: props.optionsSnapshot,
-    fixtureError: t("fixtureError"),
-  });
-  const previewSummary = getPreviewSummary(props.preview.status);
-  const rendererResetKey = JSON.stringify({
-    template: candidate?.template,
-    requests: candidate?.requests,
-    fixture,
-    data: props.preview.data,
-    status: props.preview.status,
-    sessionId: props.preview.session?.id,
-    options: props.optionsSnapshot,
-  });
+  const candidateTemplate = candidate?.template;
+  const candidateRequests = candidate?.requests;
+  const previewCandidate = useMemo(() => {
+    if (candidateTemplate === undefined || candidateRequests === undefined) return null;
+    return { template: candidateTemplate, requests: candidateRequests };
+  }, [candidateRequests, candidateTemplate]);
+  const previewSnapshot = useMemo(
+    () => ({ data: props.preview.data, status: props.preview.status, session: props.preview.session }),
+    [props.preview.data, props.preview.session, props.preview.status],
+  );
+  const fixtureError = t("fixtureError");
+  const accessibilityIssues = useMemo(() => {
+    if (candidateTemplate === undefined) return [];
+    return analyzeCustomWidgetAccessibility(candidateTemplate);
+  }, [candidateTemplate]);
+  const displayData = useMemo(
+    () =>
+      createPreviewDisplayData({
+        candidate: previewCandidate,
+        fixture,
+        preview: previewSnapshot,
+        options: props.optionsSnapshot,
+        fixtureError,
+      }),
+    [fixture, fixtureError, previewCandidate, previewSnapshot, props.optionsSnapshot],
+  );
+  const previewSummary = useMemo(() => getPreviewSummary(props.preview.status), [props.preview.status]);
+  const rendererResetKey = useMemo(
+    () =>
+      JSON.stringify({
+        template: candidateTemplate,
+        requests: candidateRequests,
+        fixture,
+        data: props.preview.data,
+        status: props.preview.status,
+        sessionId: props.preview.session?.id,
+        options: props.optionsSnapshot,
+      }),
+    [
+      candidateRequests,
+      candidateTemplate,
+      fixture,
+      props.optionsSnapshot,
+      props.preview.data,
+      props.preview.session?.id,
+      props.preview.status,
+    ],
+  );
  const previewResult =
    props.preview.outcome === "success"
      ? {
@@ -93,24 +136,27 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
              {
                value: "compact",
                label: (
-                  <span aria-label={t("size.compact")} title={t("size.compact")}>
-                    S
+                  <span title={t("size.compact")}>
+                    <span aria-hidden>S</span>
+                    <VisuallyHidden>{t("size.compact")}</VisuallyHidden>
                  </span>
                ),
              },
              {
                value: "standard",
                label: (
-                  <span aria-label={t("size.standard")} title={t("size.standard")}>
-                    M
+                  <span title={t("size.standard")}>
+                    <span aria-hidden>M</span>
+                    <VisuallyHidden>{t("size.standard")}</VisuallyHidden>
                  </span>
                ),
              },
              {
                value: "wide",
                label: (
-                  <span aria-label={t("size.wide")} title={t("size.wide")}>
-                    L
+                  <span title={t("size.wide")}>
+                    <span aria-hidden>L</span>
+                    <VisuallyHidden>{t("size.wide")}</VisuallyHidden>
                  </span>
                ),
              },
@@ -151,7 +197,14 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
          </Tabs.List>
          <Tabs.Panel value="widget" pt="sm">
            <Box className={classes.previewCanvas}>
-              <Paper withBorder p="sm" h={360} w={widths[props.size] ?? 480} maw="100%" style={{ overflow: "auto" }}>
+              <Paper
+                withBorder
+                p="sm"
+                h={360}
+                w={previewWidths[props.size] ?? 480}
+                maw="100%"
+                style={{ overflow: "auto" }}
+              >
                {displayData ? (
                  <PreviewErrorBoundary
                    title={errorBoundaryMessages("title")}
@@ -264,3 +317,5 @@ export function CustomWidgetPreviewPanel(props: PreviewPanelProps) {
    </Card>
  );
 }
+
+export const CustomWidgetPreviewPanel = memo(CustomWidgetPreviewPanelContent);
@@ -1,34 +1,35 @@
 import { renameCustomWidgetOption, renameCustomWidgetRequest } from "@homarr/custom-widgets/workbench";

-import { applyDefinition } from "./_custom-widget-form-utils";
-import type { buildDefinition, CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
+import { applyDefinition, buildDefinition } from "./_custom-widget-form-utils";
+import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";

 interface RenameHandlersInput {
  form: CustomWidgetWorkbenchForm;
-  candidate: ReturnType<typeof buildDefinition>;
  invalidWidgetMessage: string;
 }

 export function createCustomWidgetRenameHandlers(input: RenameHandlersInput) {
  const renameRequest = (currentId: string, nextId: string) => {
-    if (!input.candidate.success) {
+    const candidate = buildDefinition(input.form.values);
+    if (!candidate.success) {
      input.form.setFieldError("requests", input.invalidWidgetMessage);
      return;
    }
    try {
-      applyDefinition(input.form, renameCustomWidgetRequest(input.candidate.data, currentId, nextId));
+      applyDefinition(input.form, renameCustomWidgetRequest(candidate.data, currentId, nextId));
      input.form.clearFieldError("requests");
    } catch (error) {
      input.form.setFieldError("requests", error instanceof Error ? error.message : input.invalidWidgetMessage);
    }
  };
  const renameOption = (currentName: string, nextName: string) => {
-    if (!input.candidate.success) {
+    const candidate = buildDefinition(input.form.values);
+    if (!candidate.success) {
      input.form.setFieldError("options", input.invalidWidgetMessage);
      return;
    }
    try {
-      applyDefinition(input.form, renameCustomWidgetOption(input.candidate.data, currentName, nextName));
+      applyDefinition(input.form, renameCustomWidgetOption(candidate.data, currentName, nextName));
      input.form.clearFieldError("options");
    } catch (error) {
      input.form.setFieldError("options", error instanceof Error ? error.message : input.invalidWidgetMessage);
@@ -23,7 +23,7 @@ export function QueryValuesEditor({
 }) {
  const t = useI18n("customWidget.workbench.builder");
  const entries = Object.entries(value);
-  const [nameErrors, setNameErrors] = useState<Record<number, string>>({});
+  const [nameErrors, setNameErrors] = useState<Record<string, string>>({});
  return (
    <Stack gap="xs">
      <Text size="sm" fw={500}>
@@ -65,23 +65,23 @@ export function QueryValuesEditor({
          ...(allowParams ? [{ value: "param", label: t("invocationParameter") }] : []),
        ];
        return (
-          <Group key={index} align="end" wrap="wrap">
+          <Group key={name} align="end" wrap="wrap">
            <CustomWidgetIdentifierInput
              style={{ flex: "1 1 10rem" }}
              label={t("queryKey")}
              value={name}
-              error={nameErrors[index]}
+              error={nameErrors[name]}
              onCommit={(nextName) => {
                if (
                  !/^[A-Za-z][A-Za-z0-9_-]*$/u.test(nextName) ||
                  entries.some(([entryName], entryIndex) => entryIndex !== index && entryName === nextName)
                ) {
-                  setNameErrors((currentErrors) => ({ ...currentErrors, [index]: t("queryKeyInvalid") }));
+                  setNameErrors((currentErrors) => ({ ...currentErrors, [name]: t("queryKeyInvalid") }));
                  return;
                }
                setNameErrors((currentErrors) => {
                  const nextErrors = { ...currentErrors };
-                  delete nextErrors[index];
+                  delete nextErrors[name];
                  return nextErrors;
                });
                commit(nextName, kind, current);
@@ -1,6 +1,6 @@
 "use client";

-import { Accordion, ActionIcon, Button, Fieldset, Group, Select, Stack, Switch, Text, TextInput } from "@mantine/core";
+import { ActionIcon, Button, Fieldset, Group, Select, Stack, Switch, Text, TextInput } from "@mantine/core";
 import { IconArrowDown, IconArrowUp, IconPlus, IconTrash } from "@tabler/icons-react";

 import { useI18n } from "@homarr/translation/client";
@@ -9,6 +9,7 @@ import { isRecord, parseJson } from "./_custom-widget-form-utils";
 import type { CustomWidgetWorkbenchForm } from "./_custom-widget-form-utils";
 import { QueryValuesEditor, RequestBodyEditor } from "./_custom-widget-request-value-editors";
 import { CustomWidgetIdentifierInput } from "./_custom-widget-identifier-input";
+import { LazyOnceAccordion } from "./_lazy-once-accordion";

 const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"];

@@ -24,6 +25,8 @@ export function CustomWidgetRequestsEditor({
  const entries = isRecord(parsed) ? Object.entries(parsed) : [];
  const sources = parseJson(form.values.sources);
  const sourceIds = isRecord(sources) ? Object.keys(sources) : ["default"];
+  const options = parseJson(form.values.options);
+  const optionNames = isRecord(options) ? Object.keys(options) : [];

  const commit = (next: Array<[string, unknown]>) =>
    form.setFieldValue("requests", JSON.stringify(Object.fromEntries(next), null, 2));
@@ -50,7 +53,7 @@ export function CustomWidgetRequestsEditor({
        const kind = request.kind === "action" ? "action" : "query";
        const trigger = request.trigger === "manual" ? "manual" : "load";
        return (
-          <Fieldset key={index} legend={id || t("request", { count: index + 1 })}>
+          <Fieldset key={id} legend={id || t("request", { count: index + 1 })}>
            <Stack gap="sm">
              <Group grow align="start">
                <CustomWidgetIdentifierInput
@@ -119,71 +122,61 @@ export function CustomWidgetRequestsEditor({
              <TextInput
                label={t("path")}
                description={t("pathDescription")}
+                descriptionProps={{
+                  style: { color: "light-dark(var(--mantine-color-gray-7), var(--mantine-color-gray-4))" },
+                }}
                value={typeof request.path === "string" ? request.path : ""}
                onChange={(event) => update(index, id, { ...request, path: event.currentTarget.value })}
              />
-              <Accordion variant="contained">
-                <Accordion.Item value="values">
-                  <Accordion.Control>{t("requestDetails")}</Accordion.Control>
-                  <Accordion.Panel>
-                    <Stack gap="sm">
-                      <QueryValuesEditor
-                        value={isRecord(request.query) ? request.query : {}}
-                        optionNames={Object.keys(
-                          isRecord(parseJson(form.values.options))
-                            ? (parseJson(form.values.options) as Record<string, unknown>)
-                            : {},
-                        )}
-                        allowParams={trigger === "manual" || kind === "action"}
-                        onChange={(query) => update(index, id, { ...request, query })}
-                      />
-                      <RequestBodyEditor
-                        id={id}
-                        value={request.body}
-                        optionNames={Object.keys(
-                          isRecord(parseJson(form.values.options))
-                            ? (parseJson(form.values.options) as Record<string, unknown>)
-                            : {},
-                        )}
-                        allowParams={trigger === "manual" || kind === "action"}
-                        onChange={(body) => update(index, id, { ...request, body })}
-                      />
-                      {kind === "action" && (
-                        <TextInput
-                          label={t("confirmation")}
-                          value={typeof request.confirmation === "string" ? request.confirmation : ""}
-                          onChange={(event) =>
-                            update(index, id, { ...request, confirmation: event.currentTarget.value || undefined })
-                          }
-                        />
-                      )}
-                      {kind === "action" && (
-                        <TextInput
-                          label={t("invalidation")}
-                          description={t("invalidationDescription")}
-                          value={Array.isArray(request.invalidates) ? request.invalidates.join(", ") : ""}
-                          onChange={(event) =>
-                            update(index, id, {
-                              ...request,
-                              invalidates: event.currentTarget.value
-                                .split(",")
-                                .map((value) => value.trim())
-                                .filter(Boolean),
-                            })
-                          }
-                        />
-                      )}
-                      <Switch
-                        label={t("noAuth")}
-                        checked={request.auth === "none"}
-                        onChange={(event) =>
-                          update(index, id, { ...request, auth: event.currentTarget.checked ? "none" : "inherit" })
-                        }
-                      />
-                    </Stack>
-                  </Accordion.Panel>
-                </Accordion.Item>
-              </Accordion>
+              <LazyOnceAccordion label={t("requestDetails")}>
+                <Stack gap="sm">
+                  <QueryValuesEditor
+                    value={isRecord(request.query) ? request.query : {}}
+                    optionNames={optionNames}
+                    allowParams={trigger === "manual" || kind === "action"}
+                    onChange={(query) => update(index, id, { ...request, query })}
+                  />
+                  <RequestBodyEditor
+                    id={id}
+                    value={request.body}
+                    optionNames={optionNames}
+                    allowParams={trigger === "manual" || kind === "action"}
+                    onChange={(body) => update(index, id, { ...request, body })}
+                  />
+                  {kind === "action" && (
+                    <TextInput
+                      label={t("confirmation")}
+                      value={typeof request.confirmation === "string" ? request.confirmation : ""}
+                      onChange={(event) =>
+                        update(index, id, { ...request, confirmation: event.currentTarget.value || undefined })
+                      }
+                    />
+                  )}
+                  {kind === "action" && (
+                    <TextInput
+                      label={t("invalidation")}
+                      description={t("invalidationDescription")}
+                      value={Array.isArray(request.invalidates) ? request.invalidates.join(", ") : ""}
+                      onChange={(event) =>
+                        update(index, id, {
+                          ...request,
+                          invalidates: event.currentTarget.value
+                            .split(",")
+                            .map((value) => value.trim())
+                            .filter(Boolean),
+                        })
+                      }
+                    />
+                  )}
+                  <Switch
+                    label={t("noAuth")}
+                    checked={request.auth === "none"}
+                    onChange={(event) =>
+                      update(index, id, { ...request, auth: event.currentTarget.checked ? "none" : "inherit" })
+                    }
+                  />
+                </Stack>
+              </LazyOnceAccordion>
              <Group justify="space-between">
                <Group gap="xs">
                  <ActionIcon
@@ -0,0 +1,44 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { useId, useState } from "react";
+import { Accordion } from "@mantine/core";
+
+interface LazyOnceAccordionProps {
+  label: ReactNode;
+  children: ReactNode;
+}
+
+export function LazyOnceAccordion({ label, children }: LazyOnceAccordionProps) {
+  const id = useId();
+  const [value, setValue] = useState<string | null>(null);
+  const [hasOpened, setHasOpened] = useState(false);
+  const controlId = `${id}-control`;
+  const panelId = `${id}-panel`;
+
+  const handleChange = (nextValue: string | null) => {
+    setValue(nextValue);
+    if (nextValue === "content") setHasOpened(true);
+  };
+
+  return (
+    <Accordion variant="contained" value={value} onChange={handleChange}>
+      <Accordion.Item value="content">
+        <Accordion.Control id={controlId} aria-controls={panelId}>
+          {label}
+        </Accordion.Control>
+        {/* Native hiding keeps editor effects and CodeMirror history alive while the panel is collapsed. */}
+        <div
+          id={panelId}
+          className={Accordion.classes.panel}
+          // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- The explicit role matches Mantine's panel contract.
+          role="region"
+          aria-labelledby={controlId}
+          hidden={value !== "content"}
+        >
+          <div className={Accordion.classes.content}>{hasOpened && children}</div>
+        </div>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
@@ -1,6 +1,6 @@
 "use client";

-import { useState } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import type { Dispatch, SetStateAction } from "react";
 import type { UseFormReturnType } from "@mantine/form";

@@ -27,8 +27,6 @@ interface FormActionsInput {
  mode: "create" | "edit";
  definitionId?: string;
  form: UseFormReturnType<CustomWidgetFormValues>;
-  candidate: ReturnType<typeof buildDefinition>;
-  preview: PreviewState;
  setPreview: Dispatch<SetStateAction<PreviewState>>;
  setMobilePane: Dispatch<SetStateAction<"configure" | "preview">>;
  optionsSnapshot: Record<string, unknown>;
@@ -45,6 +43,71 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
  const previewMutation = clientApi.customWidget.previewCreate.useMutation();
  const [saveIssues, setSaveIssues] = useState<CustomWidgetSaveIssue[]>([]);
  const [previewPending, setPreviewPending] = useState(false);
+  const previewOptions = input.optionsSnapshot;
+  const previewOptionsFingerprint = useMemo(() => JSON.stringify(previewOptions), [previewOptions]);
+  const previewSecretValues = input.form.values.secrets;
+  const previewSecrets = useMemo(() => getChangedSecrets({ secrets: previewSecretValues }), [previewSecretValues]);
+  const previewSecretsFingerprint = useMemo(() => JSON.stringify(previewSecrets), [previewSecrets]);
+  const previewDefinitionValues = useMemo(
+    () => ({
+      name: input.form.values.name,
+      description: input.form.values.description,
+      iconUrl: input.form.values.iconUrl,
+      sources: input.form.values.sources,
+      requests: input.form.values.requests,
+      options: input.form.values.options,
+      template: input.form.values.template,
+    }),
+    [
+      input.form.values.description,
+      input.form.values.iconUrl,
+      input.form.values.name,
+      input.form.values.options,
+      input.form.values.requests,
+      input.form.values.sources,
+      input.form.values.template,
+    ],
+  );
+  const setPreview = input.setPreview;
+  const previewGeneration = useRef(0);
+  const latestPreviewInput = useRef({
+    definitionValues: previewDefinitionValues,
+    optionsFingerprint: previewOptionsFingerprint,
+    secretsFingerprint: previewSecretsFingerprint,
+  });
+  useLayoutEffect(() => {
+    const previous = latestPreviewInput.current;
+    const current = {
+      definitionValues: previewDefinitionValues,
+      optionsFingerprint: previewOptionsFingerprint,
+      secretsFingerprint: previewSecretsFingerprint,
+    };
+    latestPreviewInput.current = current;
+    if (
+      previous.definitionValues === current.definitionValues &&
+      previous.optionsFingerprint === current.optionsFingerprint &&
+      previous.secretsFingerprint === current.secretsFingerprint
+    )
+      return;
+    previewGeneration.current += 1;
+    setPreview((preview) => {
+      if (
+        preview.outcome === "idle" &&
+        preview.session === null &&
+        Object.keys(preview.data).length === 0 &&
+        Object.keys(preview.status).length === 0
+      )
+        return preview;
+      return { data: {}, status: {}, session: null, outcome: "idle" };
+    });
+    setPreviewPending(false);
+  }, [previewDefinitionValues, previewOptionsFingerprint, previewSecretsFingerprint, setPreview]);
+  useEffect(
+    () => () => {
+      previewGeneration.current += 1;
+    },
+    [],
+  );
  let actionLabel = tCommon("action.save");
  if (input.mode === "create") actionLabel = tCommon("action.create");

@@ -105,14 +168,15 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {

  const runPreview = async () => {
    if (previewPending) return;
-    if (!input.candidate.success) {
+    const candidateAtStart = buildDefinition(input.form.values);
+    if (!candidateAtStart.success) {
      showErrorNotification({
        title: w("section.preview"),
-        message: input.candidate.error.issues[0]?.message ?? w("invalidWidget"),
+        message: candidateAtStart.error.issues[0]?.message ?? w("invalidWidget"),
      });
      return;
    }
-    const optionIssues = getCustomWidgetPreviewOptionIssues(input.candidate.data, input.optionsSnapshot);
+    const optionIssues = getCustomWidgetPreviewOptionIssues(candidateAtStart.data, input.optionsSnapshot);
    if (optionIssues.length > 0) {
      const issue = optionIssues[0];
      showErrorNotification({
@@ -121,17 +185,35 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
      });
      return;
    }
+    const definitionValuesAtStart = previewDefinitionValues;
+    const optionsAtStart = input.optionsSnapshot;
+    const optionsFingerprintAtStart = previewOptionsFingerprint;
+    const secretsAtStart = previewSecrets;
+    const secretsFingerprintAtStart = previewSecretsFingerprint;
+    const generation = previewGeneration.current + 1;
+    previewGeneration.current = generation;
+    const isCurrent = () => {
+      const latest = latestPreviewInput.current;
+      return (
+        previewGeneration.current === generation &&
+        latest.definitionValues === definitionValuesAtStart &&
+        latest.optionsFingerprint === optionsFingerprintAtStart &&
+        latest.secretsFingerprint === secretsFingerprintAtStart
+      );
+    };
    input.setMobilePane("preview");
    input.setPreview({ data: {}, status: {}, session: null, outcome: "loading" });
    setPreviewPending(true);
    try {
      const created = await previewMutation.mutateAsync({
-        definition: input.candidate.data,
+        definition: candidateAtStart.data,
        definitionId: input.definitionId,
-        options: input.optionsSnapshot,
-        secrets: getChangedSecrets(input.form.values),
+        options: optionsAtStart,
+        secrets: secretsAtStart,
      });
-      const snapshot = await loadPreviewQueries(input.candidate.data, created.previewSession.id);
+      if (!isCurrent()) return;
+      const snapshot = await loadPreviewQueries(candidateAtStart.data, created.previewSession.id);
+      if (!isCurrent()) return;
      const failed = Object.values(snapshot.status).filter((status) => isRecord(status) && status.ok === false).length;
      input.setPreview({
        ...snapshot,
@@ -156,10 +238,13 @@ export function useCustomWidgetFormActions(input: FormActionsInput) {
        });
      }
    } catch {
+      if (!isCurrent()) return;
      input.setPreview((current) => ({ ...current, outcome: "error" }));
      showErrorNotification({ title: w("section.preview"), message: t("notification.previewError") });
    } finally {
-      setPreviewPending(false);
+      if (isCurrent()) {
+        setPreviewPending(false);
+      }
    }
  };

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

 import { ManagePageLayout } from "~/components/manage/manage-page-layout";
 import { NoResults } from "~/components/no-results";
-import { getWorkshopWebUrl } from "~/components/workshop/workshop-client";
 import { WorkshopAccountButton, useWorkshopSession } from "~/components/workshop/workshop-session";
 import { WorkshopSubmissionGrid } from "~/components/workshop/workshop-submission-grid";
 import { WorkshopVoteControl } from "~/components/workshop/workshop-vote-control";
@@ -23,9 +22,10 @@ interface WorkshopBrowseProps {
  search: string | undefined;
  sort: "top" | "newest";
  page: number;
+  workshopWebUrl: string;
 }

-export function WorkshopBrowse({ search, sort, page }: WorkshopBrowseProps) {
+export function WorkshopBrowse({ search, sort, page, workshopWebUrl }: WorkshopBrowseProps) {
  const t = useI18n("workshop");
  const tCommon = useI18n("common.action");
  const session = useWorkshopSession();
@@ -46,7 +46,7 @@ export function WorkshopBrowse({ search, sort, page }: WorkshopBrowseProps) {
          <WorkshopAccountButton session={session} />
          <Button
            component="a"
-            href={getWorkshopWebUrl()}
+            href={workshopWebUrl}
            target="_blank"
            rel="noopener noreferrer"
            variant="default"
@@ -100,7 +100,7 @@ export function WorkshopBrowse({ search, sort, page }: WorkshopBrowseProps) {
              <Tooltip label={t("openCommunity")}>
                <ActionIcon
                  component="a"
-                  href={getWorkshopWebUrl(item.id)}
+                  href={`${workshopWebUrl.replace(/\/+$/u, "")}/${encodeURIComponent(item.id)}`}
                  target="_blank"
                  rel="noopener noreferrer"
                  variant="subtle"
@@ -3,6 +3,9 @@ import { z } from "zod/v4";

 import { auth } from "@homarr/auth/next";
 import type { inferSearchParamsFromSchema } from "@homarr/common/types";
+import { resolveHomarrUrlConfig } from "@homarr/workshop/schema";
+
+import { env } from "~/env";

 import { WorkshopBrowse } from "./_workshop-browse";

@@ -26,6 +29,13 @@ export default async function WorkshopBrowsePage(props: WorkshopBrowsePageProps)
  if (!session?.user.permissions.includes("admin")) redirect(session ? "/" : "/auth/login");

  const { search, sort, page } = searchParamsSchema.parse(await props.searchParams);
+  const { workshopWebUrl } = resolveHomarrUrlConfig({
+    homarrWebsiteUrl: env.HOMARR_WEBSITE_URL,
+    workshopApiUrl: env.WORKSHOP_API_URL,
+    workshopWebUrl: env.WORKSHOP_WEB_URL,
+  });

-  return <WorkshopBrowse search={search?.trim() || undefined} sort={sort} page={page} />;
+  return (
+    <WorkshopBrowse search={search?.trim() || undefined} sort={sort} page={page} workshopWebUrl={workshopWebUrl} />
+  );
 }
@@ -9,6 +9,7 @@ const read = (path: string) => readFileSync(`${process.cwd()}/${path}`, "utf8");

 const detailPage = "apps/nextjs/src/app/[locale]/manage/custom-widgets/workshop/[id]/_workshop-detail.tsx";
 const browsePage = "apps/nextjs/src/app/[locale]/manage/custom-widgets/workshop/_workshop-browse.tsx";
+const browseRoutePage = "apps/nextjs/src/app/[locale]/manage/custom-widgets/workshop/page.tsx";
 const publishPage = "apps/nextjs/src/app/[locale]/manage/custom-widgets/publish/[id]/_workshop-publish-form.tsx";
 const cssButton = "apps/nextjs/src/components/workshop/workshop-css-import-button.tsx";

@@ -52,12 +53,18 @@ describe("Workshop widget install flow", () => {

  it("browses the Workshop as a card grid with per-item Workshop links", () => {
    const browse = read(browsePage);
+    const route = read(browseRoutePage);

    expect(browse).toContain("WorkshopSubmissionGrid");
    expect(browse).toContain("SearchInput");
    expect(browse).toContain("TablePagination");
    expect(browse).toContain("CustomWidgetTabs");
-    expect(browse).toContain("getWorkshopWebUrl(item.id)");
+    expect(route).toContain("resolveHomarrUrlConfig");
+    expect(route).toContain("workshopWebUrl={workshopWebUrl}");
+    expect(browse).toContain("workshopWebUrl: string");
+    expect(browse).toContain("href={workshopWebUrl}");
+    expect(browse).toContain('workshopWebUrl.replace(/\\/+$/u, "")');
+    expect(browse).toContain("encodeURIComponent(item.id)");
    expect(browse).toContain("WorkshopVoteControl");
    expect(browse).not.toContain("Modal");
  });