feat(custom-widgets): improve authoring workbench (#6689)

* feat(custom-widgets): improve authoring workbench

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

* refactor(custom-widgets): satisfy architecture checks

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

* fix(custom-widgets): harden workbench state

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

apps/nextjs/src/components/workshop/workshop-install-flow.spec.ts

@@ -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");
   });