From 04c44bad871f5b3105f44705db41428510912c5f Mon Sep 17 00:00:00 2001
From: Ayushi Gupta <ayushigupta36881@gmail.com>
Date: Sat, 9 May 2026 13:36:13 +0100
Subject: [PATCH 01/31] admin: improve settings editor UX and restore comments
 (#7603)

Original work by @AyushiGupta160604 in #7666 (squashed).
---
 admin/src/App.css                |  20 +++
 admin/src/pages/SettingsPage.tsx | 208 +++++++++++++++++++++++--------
 2 files changed, 179 insertions(+), 49 deletions(-)

diff --git a/admin/src/App.css b/admin/src/App.css
index e69de29bb2d..d9b4b0dc9d8 100644
--- a/admin/src/App.css
+++ b/admin/src/App.css
@@ -0,0 +1,20 @@
+/* Enhanced Admin Settings Editor Styles */
+.settings {
+  font-family: "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
+  font-size: 14px;
+  white-space: pre;
+  overflow-wrap: normal;
+  overflow-x: auto;
+}
+
+/* VS Code style focus ring requested by John */
+.settings:focus {
+  outline: 2px solid #007acc !important;
+  outline-offset: -1px;
+}
+
+.settings-button-bar {
+  display: flex;
+  gap: 10px;
+  margin-top: 15px;
+}
diff --git a/admin/src/pages/SettingsPage.tsx b/admin/src/pages/SettingsPage.tsx
index 6c2f9bf333c..acfac2d553d 100644
--- a/admin/src/pages/SettingsPage.tsx
+++ b/admin/src/pages/SettingsPage.tsx
@@ -1,50 +1,160 @@
-import {useStore} from "../store/store.ts";
-import {isJSONClean, cleanComments} from "../utils/utils.ts";
-import {Trans} from "react-i18next";
-import {IconButton} from "../components/IconButton.tsx";
-import {RotateCw, Save} from "lucide-react";
-
-export const SettingsPage = ()=>{
-  const settingsSocket = useStore(state=>state.settingsSocket)
-  const settings = cleanComments(useStore(state=>state.settings))
-
-  return <div className="settings-page">
-    <h1><Trans i18nKey="admin_settings.current"/></h1>
-    <textarea value={settings} className="settings" onChange={v => {
-      useStore.getState().setSettings(v.target.value)
-    }}/>
-    <div className="settings-button-bar">
-      <IconButton className="settingsButton" icon={<Save/>}
-            title={<Trans i18nKey="admin_settings.current_save.value"/>} onClick={() => {
-        if (isJSONClean(settings!)) {
-          // JSON is clean so emit it to the server
-          settingsSocket!.emit('saveSettings', settings!);
-          useStore.getState().setToastState({
-            open: true,
-            title: "Successfully saved settings",
-            success: true
-          })
-        } else {
-          useStore.getState().setToastState({
-            open: true,
-            title: "Error saving settings",
-            success: false
-          })
-        }
-      }}/>
-      <IconButton className="settingsButton" icon={<RotateCw/>}
-            title={<Trans i18nKey="admin_settings.current_restart.value"/>} onClick={() => {
-        settingsSocket!.emit('restartServer');
-      }}/>
-    </div>
-    <div className="separator"/>
-    <div className="settings-button-bar">
-      <a rel="noopener noreferrer" target="_blank"
-       href="https://github.com/ether/etherpad-lite/wiki/Example-Production-Settings.JSON"><Trans
-        i18nKey="admin_settings.current_example-prod"/></a>
-      <a rel="noopener noreferrer" target="_blank"
-       href="https://github.com/ether/etherpad-lite/wiki/Example-Development-Settings.JSON"><Trans
-        i18nKey="admin_settings.current_example-devel"/></a>
+import React, { useState } from 'react';
+import { useStore } from "../store/store.ts";
+import { isJSONClean, cleanComments } from "../utils/utils.ts"; 
+import { Trans } from "react-i18next";
+import { IconButton } from "../components/IconButton.tsx";
+import { RotateCw, Save, AlignLeft, ShieldCheck } from "lucide-react";
+
+export const SettingsPage = () => {
+  const settingsSocket = useStore(state => state.settingsSocket);
+  
+  // FIX: Initialize with empty string to prevent uncontrolled->controlled warning
+  const settings = useStore(state => state.settings) ?? ""; 
+  
+  // FIX: New features disabled by default per project maintenance rules
+  const [exposeExperimental] = useState(false);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === 'Tab') {
+      e.preventDefault();
+      const { selectionStart, selectionEnd, value } = e.currentTarget;
+      const newValue = value.substring(0, selectionStart) + "  " + value.substring(selectionEnd);
+      useStore.getState().setSettings(newValue);
+      
+      // Maintain cursor position after state update
+      setTimeout(() => {
+        e.currentTarget.selectionStart = e.currentTarget.selectionEnd = selectionStart + 2;
+      }, 0);
+    }
+  };
+
+  // Dry-run validation without saving
+  const testJSON = () => {
+    try {
+      const cleaned = cleanComments(settings);
+      JSON.parse(cleaned ?? ""); 
+      useStore.getState().setToastState({
+        open: true,
+        title: "Validation Success: JSON is structurally sound.",
+        success: true
+      });
+    } catch (e) {
+      useStore.getState().setToastState({
+        open: true,
+        title: "Validation Failed: Check for syntax errors or stray characters.",
+        success: false
+      });
+    }
+  };
+
+  const prettifyJSON = () => {
+    try {
+      const cleaned = cleanComments(settings); 
+      const obj = JSON.parse(cleaned ?? "");
+      const formatted = JSON.stringify(obj, null, 2);
+      
+      if (window.confirm("Prettifying will remove all comments. Do you wish to proceed?")) {
+        useStore.getState().setSettings(formatted);
+      }
+    } catch (e) {
+      useStore.getState().setToastState({
+        open: true,
+        title: "Cannot prettify: Please fix syntax errors first.",
+        success: false
+      });
+    }
+  };
+
+  return (
+    <div className="settings-page">
+      <h1><Trans i18nKey="admin_settings.current" /></h1>
+      
+      <textarea
+        value={settings}
+        className="settings"
+        spellCheck={false}
+        onKeyDown={handleKeyDown}
+        onChange={v => useStore.getState().setSettings(v.target.value)}
+        style={{
+          fontFamily: '"Fira Code", "Cascadia Code", monospace',
+          width: '100%',
+          height: '500px',
+          padding: '15px',
+          backgroundColor: '#1e1e1e',
+          color: '#d4d4d4',
+          lineHeight: '1.5',
+          border: '1px solid #333',
+          resize: 'vertical'
+        }}
+      />
+
+      <div className="settings-button-bar">
+        <IconButton 
+          className="settingsButton" 
+          icon={<Save />}
+          title={<Trans i18nKey="admin_settings.current_save.value" />} 
+          onClick={() => {
+            // FIX: Separate validation logic from socket logic
+            if (!isJSONClean(settings)) {
+              useStore.getState().setToastState({
+                open: true, title: "Syntax Error: Check commas and braces.", success: false
+              });
+              return;
+            }
+            if (!settingsSocket?.connected) {
+              useStore.getState().setToastState({
+                open: true, title: "Error: Not connected to server.", success: false
+              });
+              return;
+            }
+            settingsSocket.emit('saveSettings', settings);
+            useStore.getState().setToastState({
+              open: true, title: "Settings saved successfully.", success: true
+            });
+          }} 
+        />
+
+        {/* Dry-run Button */}
+        <IconButton 
+          className="settingsButton" 
+          icon={<ShieldCheck />} 
+          title="Test JSON (Dry-run)" 
+          onClick={testJSON} 
+        />
+        
+        {/* FIX: Feature Flag Gating */}
+        {exposeExperimental && (
+          <IconButton 
+            className="settingsButton" 
+            icon={<AlignLeft />} 
+            title="Prettify JSON" 
+            onClick={prettifyJSON} 
+          />
+        )}
+
+        <IconButton 
+          className="settingsButton" 
+          icon={<RotateCw />}
+          // FIX: Stable ID for Playwright automation
+          data-testid="restart-etherpad-button" 
+          title={<Trans i18nKey="admin_settings.current_restart.value" />} 
+          onClick={() => {
+            settingsSocket?.emit('restartServer');
+          }} 
+        />
+      </div>
+      
+      <div className="separator" style={{ margin: '20px 0', borderBottom: '1px solid #eee' }} />
+      
+      <div className="settings-links" style={{ display: 'flex', gap: '20px' }}>
+        {/* FIX: Protocol-independent URLs */}
+        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad-lite/wiki/Example-Production-Settings.JSON">
+          <Trans i18nKey="admin_settings.current_example-prod" />
+        </a>
+        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad-lite/wiki/Example-Development-Settings.JSON">
+          <Trans i18nKey="admin_settings.current_example-devel" />
+        </a>
+      </div>
     </div>
-  </div>
-}
+  );
+};
\ No newline at end of file

From b5d81b51f5c9fae53d49edef8847c1ec0895e178 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 13:42:25 +0100
Subject: [PATCH 02/31] =?UTF-8?q?admin(settings):=20address=20review=20of?=
 =?UTF-8?q?=20#7666=20=E2=80=94=20types,=20focus,=20i18n,=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- IconButton: forward ButtonHTMLAttributes so data-testid/aria-* work,
  fixing TS build break and unblocking stable Playwright selectors.
- SettingsPage: move textarea presentation to .settings CSS so the
  :focus outline is no longer overridden, surface validation/save/socket
  errors via i18n toasts (Validate, Prettify, Save), and tag every
  button with data-testid for selector stability.
- Replace positional .settingsButton.nth(1) with getByTestId in
  adminhelper so Save/Test/Prettify/Restart can be reordered safely.
- Add regression specs: comments survive a save round-trip; Validate
  toasts success/failure; invalid JSON blocks Save with a failure toast.
- Switch wiki links to protocol-independent URLs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/App.css                             |  20 +-
 admin/src/components/IconButton.tsx           |  11 +-
 admin/src/pages/SettingsPage.tsx              | 180 +++++++-----------
 src/locales/en.json                           |   9 +
 .../admin-spec/adminsettings.spec.ts          |  45 +++++
 src/tests/frontend-new/helper/adminhelper.ts  |   6 +-
 6 files changed, 149 insertions(+), 122 deletions(-)

diff --git a/admin/src/App.css b/admin/src/App.css
index d9b4b0dc9d8..17403b18e39 100644
--- a/admin/src/App.css
+++ b/admin/src/App.css
@@ -1,15 +1,21 @@
-/* Enhanced Admin Settings Editor Styles */
 .settings {
   font-family: "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
   font-size: 14px;
   white-space: pre;
   overflow-wrap: normal;
   overflow-x: auto;
+  width: 100%;
+  height: 500px;
+  padding: 15px;
+  background-color: #1e1e1e;
+  color: #d4d4d4;
+  line-height: 1.5;
+  border: 1px solid #333;
+  resize: vertical;
 }
 
-/* VS Code style focus ring requested by John */
 .settings:focus {
-  outline: 2px solid #007acc !important;
+  outline: 2px solid #007acc;
   outline-offset: -1px;
 }
 
@@ -18,3 +24,11 @@
   gap: 10px;
   margin-top: 15px;
 }
+
+.settings-links {
+  display: flex;
+  gap: 20px;
+  margin-top: 20px;
+  padding-top: 20px;
+  border-top: 1px solid #eee;
+}
diff --git a/admin/src/components/IconButton.tsx b/admin/src/components/IconButton.tsx
index b73396c827d..22cb43b9605 100644
--- a/admin/src/components/IconButton.tsx
+++ b/admin/src/components/IconButton.tsx
@@ -1,16 +1,13 @@
-import {FC, JSX, ReactElement} from "react";
+import {ButtonHTMLAttributes, FC, JSX, ReactElement} from "react";
 
-export type IconButtonProps = {
-  style?: React.CSSProperties,
+export type IconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'title' | 'onClick'> & {
   icon: JSX.Element,
   title: string|ReactElement,
   onClick: ()=>void,
-  className?: string,
-  disabled?: boolean
 }
 
-export const IconButton:FC<IconButtonProps> = ({icon,className,onClick,title, disabled, style})=>{
-  return <button style={style}  onClick={onClick} className={"icon-button "+ className} disabled={disabled}>
+export const IconButton:FC<IconButtonProps> = ({icon, className, onClick, title, ...rest})=>{
+  return <button {...rest} onClick={onClick} className={"icon-button "+ (className ?? "")}>
     {icon}
     <span>{title}</span>
     </button>
diff --git a/admin/src/pages/SettingsPage.tsx b/admin/src/pages/SettingsPage.tsx
index acfac2d553d..1279c2dd1cb 100644
--- a/admin/src/pages/SettingsPage.tsx
+++ b/admin/src/pages/SettingsPage.tsx
@@ -1,160 +1,124 @@
 import React, { useState } from 'react';
 import { useStore } from "../store/store.ts";
-import { isJSONClean, cleanComments } from "../utils/utils.ts"; 
-import { Trans } from "react-i18next";
+import { isJSONClean, cleanComments } from "../utils/utils.ts";
+import { Trans, useTranslation } from "react-i18next";
 import { IconButton } from "../components/IconButton.tsx";
 import { RotateCw, Save, AlignLeft, ShieldCheck } from "lucide-react";
 
+const TAB_INDENT = "  ";
+
 export const SettingsPage = () => {
+  const { t } = useTranslation();
   const settingsSocket = useStore(state => state.settingsSocket);
-  
-  // FIX: Initialize with empty string to prevent uncontrolled->controlled warning
-  const settings = useStore(state => state.settings) ?? ""; 
-  
-  // FIX: New features disabled by default per project maintenance rules
+  const settings = useStore(state => state.settings) ?? "";
+
+  // Prettify rewrites JSON without comments — gated until we have inline-comment mapping.
   const [exposeExperimental] = useState(false);
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
-    if (e.key === 'Tab') {
-      e.preventDefault();
-      const { selectionStart, selectionEnd, value } = e.currentTarget;
-      const newValue = value.substring(0, selectionStart) + "  " + value.substring(selectionEnd);
-      useStore.getState().setSettings(newValue);
-      
-      // Maintain cursor position after state update
-      setTimeout(() => {
-        e.currentTarget.selectionStart = e.currentTarget.selectionEnd = selectionStart + 2;
-      }, 0);
-    }
+    if (e.key !== 'Tab') return;
+    e.preventDefault();
+    const target = e.currentTarget;
+    const { selectionStart, selectionEnd, value } = target;
+    const next = value.substring(0, selectionStart) + TAB_INDENT + value.substring(selectionEnd);
+    useStore.getState().setSettings(next);
+    requestAnimationFrame(() => {
+      target.selectionStart = target.selectionEnd = selectionStart + TAB_INDENT.length;
+    });
+  };
+
+  const showToast = (titleKey: string, success: boolean) => {
+    useStore.getState().setToastState({ open: true, title: t(titleKey), success });
   };
 
-  // Dry-run validation without saving
   const testJSON = () => {
-    try {
-      const cleaned = cleanComments(settings);
-      JSON.parse(cleaned ?? ""); 
-      useStore.getState().setToastState({
-        open: true,
-        title: "Validation Success: JSON is structurally sound.",
-        success: true
-      });
-    } catch (e) {
-      useStore.getState().setToastState({
-        open: true,
-        title: "Validation Failed: Check for syntax errors or stray characters.",
-        success: false
-      });
+    if (isJSONClean(settings)) {
+      showToast("admin_settings.toast.validation_ok", true);
+    } else {
+      showToast("admin_settings.toast.validation_failed", false);
     }
   };
 
   const prettifyJSON = () => {
     try {
-      const cleaned = cleanComments(settings); 
-      const obj = JSON.parse(cleaned ?? "");
-      const formatted = JSON.stringify(obj, null, 2);
-      
-      if (window.confirm("Prettifying will remove all comments. Do you wish to proceed?")) {
-        useStore.getState().setSettings(formatted);
+      const obj = JSON.parse(cleanComments(settings) ?? "");
+      if (window.confirm(t("admin_settings.prettify_confirm"))) {
+        useStore.getState().setSettings(JSON.stringify(obj, null, 2));
       }
-    } catch (e) {
-      useStore.getState().setToastState({
-        open: true,
-        title: "Cannot prettify: Please fix syntax errors first.",
-        success: false
-      });
+    } catch {
+      showToast("admin_settings.toast.prettify_failed", false);
     }
   };
 
+  const handleSave = () => {
+    if (!isJSONClean(settings)) {
+      showToast("admin_settings.toast.json_invalid", false);
+      return;
+    }
+    if (!settingsSocket?.connected) {
+      showToast("admin_settings.toast.disconnected", false);
+      return;
+    }
+    settingsSocket.emit('saveSettings', settings);
+    showToast("admin_settings.toast.saved", true);
+  };
+
   return (
     <div className="settings-page">
       <h1><Trans i18nKey="admin_settings.current" /></h1>
-      
+
       <textarea
         value={settings}
         className="settings"
         spellCheck={false}
         onKeyDown={handleKeyDown}
         onChange={v => useStore.getState().setSettings(v.target.value)}
-        style={{
-          fontFamily: '"Fira Code", "Cascadia Code", monospace',
-          width: '100%',
-          height: '500px',
-          padding: '15px',
-          backgroundColor: '#1e1e1e',
-          color: '#d4d4d4',
-          lineHeight: '1.5',
-          border: '1px solid #333',
-          resize: 'vertical'
-        }}
       />
 
       <div className="settings-button-bar">
-        <IconButton 
-          className="settingsButton" 
+        <IconButton
+          className="settingsButton"
+          data-testid="save-settings-button"
           icon={<Save />}
-          title={<Trans i18nKey="admin_settings.current_save.value" />} 
-          onClick={() => {
-            // FIX: Separate validation logic from socket logic
-            if (!isJSONClean(settings)) {
-              useStore.getState().setToastState({
-                open: true, title: "Syntax Error: Check commas and braces.", success: false
-              });
-              return;
-            }
-            if (!settingsSocket?.connected) {
-              useStore.getState().setToastState({
-                open: true, title: "Error: Not connected to server.", success: false
-              });
-              return;
-            }
-            settingsSocket.emit('saveSettings', settings);
-            useStore.getState().setToastState({
-              open: true, title: "Settings saved successfully.", success: true
-            });
-          }} 
+          title={<Trans i18nKey="admin_settings.current_save.value" />}
+          onClick={handleSave}
         />
 
-        {/* Dry-run Button */}
-        <IconButton 
-          className="settingsButton" 
-          icon={<ShieldCheck />} 
-          title="Test JSON (Dry-run)" 
-          onClick={testJSON} 
+        <IconButton
+          className="settingsButton"
+          data-testid="test-settings-button"
+          icon={<ShieldCheck />}
+          title={<Trans i18nKey="admin_settings.current_test.value" />}
+          onClick={testJSON}
         />
-        
-        {/* FIX: Feature Flag Gating */}
+
         {exposeExperimental && (
-          <IconButton 
-            className="settingsButton" 
-            icon={<AlignLeft />} 
-            title="Prettify JSON" 
-            onClick={prettifyJSON} 
+          <IconButton
+            className="settingsButton"
+            data-testid="prettify-settings-button"
+            icon={<AlignLeft />}
+            title={<Trans i18nKey="admin_settings.current_prettify.value" />}
+            onClick={prettifyJSON}
           />
         )}
 
-        <IconButton 
-          className="settingsButton" 
+        <IconButton
+          className="settingsButton"
+          data-testid="restart-etherpad-button"
           icon={<RotateCw />}
-          // FIX: Stable ID for Playwright automation
-          data-testid="restart-etherpad-button" 
-          title={<Trans i18nKey="admin_settings.current_restart.value" />} 
-          onClick={() => {
-            settingsSocket?.emit('restartServer');
-          }} 
+          title={<Trans i18nKey="admin_settings.current_restart.value" />}
+          onClick={() => settingsSocket?.emit('restartServer')}
         />
       </div>
-      
-      <div className="separator" style={{ margin: '20px 0', borderBottom: '1px solid #eee' }} />
-      
-      <div className="settings-links" style={{ display: 'flex', gap: '20px' }}>
-        {/* FIX: Protocol-independent URLs */}
-        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad-lite/wiki/Example-Production-Settings.JSON">
+
+      <div className="settings-links">
+        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad/wiki/Example-Production-Settings.JSON">
           <Trans i18nKey="admin_settings.current_example-prod" />
         </a>
-        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad-lite/wiki/Example-Development-Settings.JSON">
+        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad/wiki/Example-Development-Settings.JSON">
           <Trans i18nKey="admin_settings.current_example-devel" />
         </a>
       </div>
     </div>
   );
-};
\ No newline at end of file
+};
diff --git a/src/locales/en.json b/src/locales/en.json
index a8602ad35e0..2410a4cc145 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -33,6 +33,15 @@
   "admin_settings.current_example-prod": "Example production settings template",
   "admin_settings.current_restart.value": "Restart Etherpad",
   "admin_settings.current_save.value": "Save Settings",
+  "admin_settings.current_test.value": "Validate JSON",
+  "admin_settings.current_prettify.value": "Prettify JSON",
+  "admin_settings.toast.saved": "Settings saved successfully.",
+  "admin_settings.toast.json_invalid": "Syntax error: check commas, braces, and quotes.",
+  "admin_settings.toast.disconnected": "Cannot save: not connected to server.",
+  "admin_settings.toast.validation_ok": "JSON is valid.",
+  "admin_settings.toast.validation_failed": "JSON is invalid: please fix syntax errors.",
+  "admin_settings.toast.prettify_failed": "Cannot prettify: please fix syntax errors first.",
+  "admin_settings.prettify_confirm": "Prettifying will remove all comments. Continue?",
   "admin_settings.page-title": "Settings - Etherpad",
 
   "update.banner.title": "Update available",
diff --git a/src/tests/frontend-new/admin-spec/adminsettings.spec.ts b/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
index 2b178ca1942..75307f28f9f 100644
--- a/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
+++ b/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
@@ -51,6 +51,51 @@ test.describe('admin settings',()=> {
     expect(oldSettingsVal.length).toEqual(settingsLength)
   })
 
+  test('preserves /* */ comments after save round-trip', async ({page}) => {
+    await page.goto('http://localhost:9001/admin/settings');
+    await page.waitForSelector('.settings');
+    const settings = page.locator('.settings');
+    await expect(settings).not.toHaveValue('', {timeout: 30000});
+
+    const original = await settings.inputValue();
+    const withComment = `/* takeover-pr-comment-marker */\n${original}`;
+    await settings.fill(withComment);
+    await saveSettings(page);
+
+    await page.reload();
+    await page.waitForSelector('.settings');
+    await expect(settings).not.toHaveValue('', {timeout: 30000});
+    expect(await settings.inputValue()).toContain('takeover-pr-comment-marker');
+
+    // Restore original
+    await settings.fill(original);
+    await saveSettings(page);
+  });
+
+  test('validate button toasts success on valid JSON and failure on invalid', async ({page}) => {
+    await page.goto('http://localhost:9001/admin/settings');
+    await page.waitForSelector('.settings');
+    const settings = page.locator('.settings');
+    await expect(settings).not.toHaveValue('', {timeout: 30000});
+
+    const original = await settings.inputValue();
+
+    await page.getByTestId('test-settings-button').click();
+    await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+
+    await settings.fill('{"broken":');
+    await page.getByTestId('test-settings-button').click();
+    await expect(page.locator('.ToastRootFailure')).toBeVisible({timeout: 5000});
+
+    // Invalid JSON must not be accepted by save either
+    await page.getByTestId('save-settings-button').click();
+    await expect(page.locator('.ToastRootFailure')).toBeVisible({timeout: 5000});
+
+    // Restore so subsequent tests have valid settings
+    await settings.fill(original);
+    await saveSettings(page);
+  });
+
   test('restart works', async function ({page}) {
     await page.goto('http://localhost:9001/admin/settings');
     await page.waitForSelector('.settings')
diff --git a/src/tests/frontend-new/helper/adminhelper.ts b/src/tests/frontend-new/helper/adminhelper.ts
index 82930a0149d..07e6e58804d 100644
--- a/src/tests/frontend-new/helper/adminhelper.ts
+++ b/src/tests/frontend-new/helper/adminhelper.ts
@@ -12,14 +12,12 @@ export const loginToAdmin = async (page: Page, username: string, password: strin
 
 
 export const saveSettings = async (page: Page) => {
-  // Click save
-  await page.locator('.settings-button-bar').locator('button').first().click()
+  await page.getByTestId('save-settings-button').click()
   await page.waitForSelector('.ToastRootSuccess')
 }
 
 export const restartEtherpad = async (page: Page) => {
-  // Click restart
-  const restartButton = page.locator('.settings-button-bar').locator('.settingsButton').nth(1)
+  const restartButton = page.getByTestId('restart-etherpad-button')
   const settings =  page.locator('.settings');
   await expect(settings).not.toHaveValue('', {timeout: 30000});
   await expect(restartButton).toBeVisible({timeout: 10000})

From b0c668b3ab14b2c44ce64b0095a8fde4f8dcc59b Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 13:54:21 +0100
Subject: [PATCH 03/31] docs: design spec for admin /settings parsed view

Closes the design phase of #7603. Implementation will land in a
follow-up commit on this same branch.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ...05-09-admin-settings-parsed-view-design.md | 237 ++++++++++++++++++
 1 file changed, 237 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-09-admin-settings-parsed-view-design.md

diff --git a/docs/superpowers/specs/2026-05-09-admin-settings-parsed-view-design.md b/docs/superpowers/specs/2026-05-09-admin-settings-parsed-view-design.md
new file mode 100644
index 00000000000..1af4e37fbd3
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-09-admin-settings-parsed-view-design.md
@@ -0,0 +1,237 @@
+# Admin /settings parsed view — design
+
+Date: 2026-05-09
+Status: draft, awaiting review
+Related: closes #7603, supersedes parts of #7666 / #7709
+
+## Problem
+
+`/admin/settings` renders `settings.json` as a single textarea. Admins
+asked (#7603) for a parsed view that surfaces each key with the JSONC
+comment that documents it, so the file stops looking like an opaque blob.
+
+The current PR (#7709) only restyles the textarea and adds Validate /
+Prettify / Restart buttons. The actual "parsed per-key with inline
+comments" feature is still missing.
+
+## Goals
+
+- Render `settings.json` as a tree of typed widgets, one per key.
+- Show each key's leading `/* */` or `//` comment as inline help text.
+- Round-trip back to `settings.json` preserving comments, key order,
+  whitespace, and `${ENV:default}` placeholders byte-identically for
+  keys the admin did not edit.
+- Keep a raw textarea fallback for power users and structural edits.
+
+## Non-goals (deferred)
+
+- Adding or removing keys from the form view.
+- Editing `${ENV:default}` placeholders inline. They render as
+  read-only pills; structural changes go through raw mode.
+- Curated, schema-driven help text. Comments in `settings.json` are
+  the help text; we don't ship a parallel schema.
+- Search / filter / collapse-all controls.
+
+## Constraints
+
+- `settings.json` is JSONC: `/* */` and `//` comments, trailing commas
+  tolerated by the loader.
+- Values can contain `${VAR:default}` placeholders that the server
+  resolves at boot. The form must not rewrite or normalise these.
+- Server already ships the raw file text down `settingsSocket` and
+  accepts a full-text `saveSettings` event back. We don't change the
+  server contract.
+
+## Architecture
+
+All parsing and editing run in the browser. The server-side path is
+unchanged.
+
+```
+load     server reads settings.json --raw text--> settingsSocket --> store.settings
+edit     widget --modify(text, path, value)--> new text --> store.settings
+save     store.settings --emit('saveSettings', text)--> server writes file
+```
+
+The store keeps a single source of truth: the file text. The AST is
+re-parsed from the text on each render of the form view; we don't keep
+a separate model and try to keep them in sync.
+
+### Library
+
+Add `jsonc-parser` (MS, MIT) to `admin/`. We use four entry points:
+
+- `parseTree(text)` → AST `Node` with `{ type, offset, length, children, value }`.
+- `getNodePath(node)` → `(string|number)[]` JSON pointer-ish path.
+- `modify(text, path, value, options)` → array of `Edit { offset, length, content }`.
+- `applyEdits(text, edits)` → new text.
+
+Comments are recoverable from the source `text` using `node.offset`;
+`parseTree` skips them but their byte ranges are deterministic.
+
+## Components
+
+```
+SettingsPage
+├── ModeToggle                Form | Raw (segmented control)
+│
+├── FormView                  visible when mode === 'form'
+│   ├── ParseErrorBanner      shown when parseTree fails
+│   └── JsoncNode (recursive) one per AST node
+│       ├── CommentLabel      leading /* */ or // text
+│       ├── KeyLabel
+│       ├── ValueWidget       dispatches on node.type
+│       │   ├── StringInput
+│       │   ├── NumberInput
+│       │   ├── BooleanToggle
+│       │   ├── NullChip
+│       │   ├── EnvPill       read-only, when raw matches ${VAR:default}
+│       │   ├── ObjectGroup   collapsible, recurses
+│       │   └── ArrayGroup    collapsible, recurses
+│       └── TrailingCommentBadge   `// inline` after the value
+│
+├── RawView                   visible when mode === 'raw'
+│   └── <textarea className="settings"> (the existing editor)
+│
+└── ButtonBar
+    ├── Save
+    ├── Validate              dry-run JSON parse, toast result
+    └── Restart               unchanged, keeps data-testid
+```
+
+`exposeExperimental` (Prettify) stays gated off, as in #7709.
+
+### Comment binding
+
+For each property node `"key": value`:
+
+- "Leading comment" = the longest run of `/* */` and `//` lines whose
+  byte range ends at the line break immediately before `node.offset`,
+  with at most one blank line allowed between the comment block and
+  the key. Rendered as the help text under `KeyLabel`.
+- "Trailing comment" = a single `//` or `/* */` on the same line as
+  the value, after the trailing comma if any. Rendered as a small
+  badge with tooltip.
+- Comments not adjacent to a key (file header, orphan blocks) render
+  in raw mode only.
+
+### Env placeholder detection
+
+A string node whose raw text slice (`text.slice(offset, offset+length)`)
+matches `/^"\$\{[^}]+\}"$/` renders as `EnvPill` instead of
+`StringInput`. The pill shows the variable name and (if present) the
+default after `:`. It is read-only; tooltip explains "edit in raw mode".
+
+## Data flow
+
+1. `settingsSocket` emits the raw file text. Store sets
+   `state.settings = text` (this already happens today).
+2. `FormView` calls `parseTree(state.settings)`. On any thrown
+   `SyntaxError` it renders `ParseErrorBanner` and a "Switch to raw to
+   fix" button instead of the tree.
+3. Each leaf widget receives `(node, path)` and an `onChange(value)`
+   callback. `onChange` runs:
+   ```ts
+   const edits = modify(state.settings, path, value, {
+     formattingOptions: { tabSize: 2, insertSpaces: true }
+   });
+   useStore.getState().setSettings(applyEdits(state.settings, edits));
+   ```
+4. Re-render uses the new text. Successive edits stack naturally.
+5. Save: `isJSONClean(text)` → `socket.emit('saveSettings', text)`.
+6. Mode toggle does not touch `state.settings`; both views share it.
+
+### Why no AST round-trip
+
+We tried (in design) the alternative "parse → model → reserialize" and
+rejected it: even with `jsonc-parser`'s `Edit` API at the bottom, an
+intermediate model loses information about whitespace runs and
+comment whitespace prefixes. Patching the original text with
+`modify()` is the only path that gives byte-identical output for
+untouched regions, which is the explicit requirement (admins watch
+`settings.json` in git).
+
+## Save semantics
+
+- Form mode: each widget edit produces a `modify()` patch against the
+  current text. Untouched bytes — including comments, ordering,
+  trailing commas, env placeholders — are preserved.
+- Raw mode: textarea writes the whole text back wholesale. New keys
+  and structural reshuffles only happen here.
+- The save button itself is mode-agnostic: it sends `state.settings`
+  as it stands. The existing `isJSONClean` validation gates it.
+- Toggling Form → Raw is always safe: text is unchanged.
+- Toggling Raw → Form may surface a parse error; banner explains and
+  offers to switch back.
+
+## Error handling
+
+| Failure                                  | UX                                                                |
+| ---------------------------------------- | ----------------------------------------------------------------- |
+| Server hasn't sent settings yet          | Spinner (existing behavior preserved)                             |
+| Socket disconnected during save          | Failure toast `admin_settings.toast.disconnected`                 |
+| Invalid JSON at save time                | Failure toast `admin_settings.toast.json_invalid`, save blocked   |
+| Invalid JSON when toggling Raw → Form    | `ParseErrorBanner` with line/col, "Switch back to Raw" button     |
+| `modify()` returns no edits (no-op)      | Treat as successful; widget value reflects current text           |
+| Number widget non-finite/non-numeric     | Field-level inline error; file text is *not* updated until input parses; save uses last-valid value |
+
+## i18n
+
+All new strings go through `react-i18next`. New keys:
+
+```
+admin_settings.mode.form            "Form"
+admin_settings.mode.raw             "Raw"
+admin_settings.parse_error.title    "Cannot parse settings.json"
+admin_settings.parse_error.cta      "Switch to raw to edit"
+admin_settings.env_pill.tooltip     "Environment variable. Edit in raw mode."
+admin_settings.add_key.disabled     "Add new keys in raw mode"
+```
+
+Plus the toast keys already added in #7709.
+
+## Accessibility
+
+- Mode toggle is a `role=tablist` with arrow-key navigation.
+- Each form group has an `aria-labelledby` pointing at its key label.
+- `EnvPill` is `role=note` with `aria-label="environment variable …"`.
+- Collapsible groups use `<details>`/`<summary>` so keyboard and
+  screen-reader behavior is native.
+
+## Test plan (Playwright, `admin-spec/adminsettings.spec.ts`)
+
+Add specs:
+
+- `form view renders comment as help text` — assert that a `dbType`
+  row's `aria-describedby` resolves to text containing the leading
+  comment in `settings.json`.
+- `editing string preserves comments` — change `title` via the form
+  input, save, reload; assert raw text contains both the new title and
+  the original comment block above it.
+- `boolean toggle round-trips` — toggle `requireAuthentication`, save,
+  reload; assert raw text shows `true`/`false` literal and surrounding
+  comments unchanged.
+- `env pill is read-only` — locate the SSO `issuer` row, assert pill
+  is rendered, assert no `<input>` accepts text in form mode.
+- `raw toggle round-trip is lossless` — Form → Raw → Form returns
+  identical bytes when nothing was edited.
+- `invalid raw JSON shows banner on toggle to form` — paste broken
+  JSON in raw, toggle to form, assert `ParseErrorBanner`, assert
+  "Switch to raw" button works.
+- Existing `comments preserved after save round-trip`,
+  `validate button toasts`, `restart works` specs continue to pass
+  through the new helper testids.
+
+## Out of scope (future PRs)
+
+- Add-key / delete-key form UI.
+- Env-var inline editing widget.
+- Schema-driven help text overlay.
+- Sectioning / search / filter.
+
+## Rollout
+
+Single PR replacing the current `SettingsPage.tsx` from #7709. The
+takeover branch (`takeover/7666-admin-settings-editor` on
+johnmclear/etherpad-lite) gets new commits on top; #7709 stays open
+and gets force-updated. No server-side migration.

From f46864c455aac1574d49562be4a820830b4ab093 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 13:59:35 +0100
Subject: [PATCH 04/31] docs: implementation plan for admin /settings parsed
 view

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../2026-05-09-admin-settings-parsed-view.md  | 1353 +++++++++++++++++
 1 file changed, 1353 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-09-admin-settings-parsed-view.md

diff --git a/docs/superpowers/plans/2026-05-09-admin-settings-parsed-view.md b/docs/superpowers/plans/2026-05-09-admin-settings-parsed-view.md
new file mode 100644
index 00000000000..26cad15f260
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-09-admin-settings-parsed-view.md
@@ -0,0 +1,1353 @@
+# Admin /settings parsed view — implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the single textarea on `/admin/settings` with a parsed JSONC tree of typed widgets. Each key shows its leading `/* */` or `//` comment as inline help. Saves round-trip through `jsonc-parser`'s `modify()` so untouched bytes — comments, key order, `${ENV:default}` placeholders — survive intact. A "Raw" mode preserves the existing textarea as a fallback.
+
+**Architecture:** Client-side only. The store holds the raw file text (single source of truth). Form view re-parses the text on each render via `jsonc-parser.parseTree`. Widget edits call `modify(text, path, value)` + `applyEdits` and write the result back to the store. Save sends the resulting text to the server through the existing `settingsSocket`. Server contract is unchanged.
+
+**Tech Stack:** React 19, Zustand, react-i18next, `jsonc-parser` (new dep), Playwright for verification.
+
+**Branch:** `takeover/7666-admin-settings-editor` on `johnmclear/etherpad-lite` (PR #7709). Rebase before starting if upstream `develop` has moved.
+
+**Reference spec:** `docs/superpowers/specs/2026-05-09-admin-settings-parsed-view-design.md`.
+
+---
+
+## File structure
+
+Create:
+
+- `admin/src/components/settings/jsoncEdit.ts` — thin wrapper around `jsonc-parser.modify` + `applyEdits`.
+- `admin/src/components/settings/comments.ts` — pure helpers: extract leading + trailing comment text for a given AST node from the source string.
+- `admin/src/components/settings/envPill.ts` — detect `${VAR:default}` literals from a string node's raw slice.
+- `admin/src/components/settings/CommentLabel.tsx` — renders leading comment as muted help text under a key.
+- `admin/src/components/settings/ParseErrorBanner.tsx` — renders parse-error notice + "Switch to raw" button.
+- `admin/src/components/settings/widgets/StringInput.tsx`
+- `admin/src/components/settings/widgets/NumberInput.tsx`
+- `admin/src/components/settings/widgets/BooleanToggle.tsx`
+- `admin/src/components/settings/widgets/NullChip.tsx`
+- `admin/src/components/settings/widgets/EnvPill.tsx`
+- `admin/src/components/settings/widgets/ObjectGroup.tsx`
+- `admin/src/components/settings/widgets/ArrayGroup.tsx`
+- `admin/src/components/settings/JsoncNode.tsx` — dispatches a node to the right widget.
+- `admin/src/components/settings/FormView.tsx` — top-level form: parse text, render tree, surface ParseErrorBanner.
+- `admin/src/components/settings/ModeToggle.tsx` — segmented control: Form | Raw.
+
+Modify:
+
+- `admin/package.json` — add `jsonc-parser`.
+- `admin/src/pages/SettingsPage.tsx` — restructure into ModeToggle + FormView/RawView shell.
+- `admin/src/App.css` — append styles for tree, group, pill, banner, mode-toggle.
+- `src/locales/en.json` — new i18n keys.
+- `src/tests/frontend-new/admin-spec/adminsettings.spec.ts` — new Playwright specs (the file already exists with the regression specs from the previous commit).
+
+---
+
+## Task 1: Add `jsonc-parser` dependency and scaffold the directory
+
+**Files:**
+- Modify: `admin/package.json`
+- Create: `admin/src/components/settings/.gitkeep` (ensures the directory exists; remove once a real file lands)
+
+- [ ] **Step 1: Install `jsonc-parser` in `admin/`**
+
+```bash
+cd admin && pnpm add jsonc-parser@^3.3.1
+```
+
+Expected output: `+ jsonc-parser 3.3.1`. `package.json` and the lockfile both update.
+
+- [ ] **Step 2: Sanity-check that the import resolves**
+
+```bash
+cd admin && node -e "import('jsonc-parser').then(m => console.log(Object.keys(m).sort().slice(0,8)))"
+```
+
+Expected output includes: `applyEdits`, `findNodeAtLocation`, `getNodePath`, `modify`, `parse`, `parseTree`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add admin/package.json ../pnpm-lock.yaml
+git commit -m "admin(settings): add jsonc-parser dep"
+```
+
+---
+
+## Task 2: Implement `envPill.ts` and `comments.ts` helpers
+
+These are pure functions. No unit-test runner is configured in `admin/`, so we exercise them indirectly via Playwright. Keep them strictly testable: pure functions, no React.
+
+**Files:**
+- Create: `admin/src/components/settings/envPill.ts`
+- Create: `admin/src/components/settings/comments.ts`
+
+- [ ] **Step 1: Write `envPill.ts`**
+
+```ts
+// admin/src/components/settings/envPill.ts
+//
+// Detect `"${VAR}"` and `"${VAR:default}"` placeholders inside the raw
+// slice of a string node. The slice INCLUDES the surrounding quotes,
+// because jsonc-parser exposes node.offset/length over the whole literal.
+
+export type EnvPlaceholder = {
+  variable: string;
+  defaultValue: string | null;
+};
+
+const RE = /^"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::([^}]*))?\}"$/;
+
+export const matchEnvPlaceholder = (rawSlice: string): EnvPlaceholder | null => {
+  const m = RE.exec(rawSlice);
+  if (!m) return null;
+  return {
+    variable: m[1],
+    defaultValue: m[2] ?? null,
+  };
+};
+```
+
+- [ ] **Step 2: Write `comments.ts`**
+
+```ts
+// admin/src/components/settings/comments.ts
+//
+// Given the source text and a property's `keyOffset` (jsonc-parser's
+// Node.offset for the property node), extract:
+//   - `leading`: the contiguous run of `/* */` or `//` comments
+//     immediately above the key. At most one blank line is allowed
+//     between the comment block and the key.
+//   - `trailing`: a single `// ...` or `/* ... */` on the same line
+//     as the value, after any trailing comma.
+
+export type AdjacentComments = {
+  leading: string;
+  trailing: string;
+};
+
+const LINE_BREAK = /\r?\n/;
+
+const stripCommentMarkers = (raw: string): string => {
+  // raw is a concatenation of comment tokens separated by newlines.
+  // Drop /* */ and // markers and trim each line.
+  return raw
+    .split(LINE_BREAK)
+    .map(line => line
+      .replace(/^\s*\/\*+/, '')
+      .replace(/\*+\/\s*$/, '')
+      .replace(/^\s*\*\s?/, '')
+      .replace(/^\s*\/\/\s?/, '')
+      .trim())
+    .filter(line => line.length > 0)
+    .join(' ');
+};
+
+const findLeading = (text: string, keyOffset: number): string => {
+  // Walk backwards from keyOffset to the start of the line containing it.
+  const lineStart = text.lastIndexOf('\n', keyOffset - 1) + 1;
+  let cursor = lineStart;
+  let blankLineSeen = false;
+  const collected: string[] = [];
+
+  while (cursor > 0) {
+    // Look at the previous line.
+    const prevLineEnd = cursor - 1; // the '\n' before our cursor's line
+    const prevLineStart = text.lastIndexOf('\n', prevLineEnd - 1) + 1;
+    const line = text.slice(prevLineStart, prevLineEnd);
+    const trimmed = line.trim();
+
+    if (trimmed === '') {
+      if (blankLineSeen) break;
+      blankLineSeen = true;
+      cursor = prevLineStart;
+      continue;
+    }
+
+    const isComment =
+      trimmed.startsWith('//') ||
+      trimmed.startsWith('/*') ||
+      trimmed.startsWith('*') ||
+      trimmed.endsWith('*/');
+
+    if (!isComment) break;
+
+    collected.unshift(line);
+    cursor = prevLineStart;
+  }
+
+  return stripCommentMarkers(collected.join('\n'));
+};
+
+const findTrailing = (text: string, valueOffset: number, valueLength: number): string => {
+  // Look from end-of-value to end-of-line for a single comment.
+  const lineEnd = text.indexOf('\n', valueOffset + valueLength);
+  const slice = text.slice(valueOffset + valueLength, lineEnd === -1 ? text.length : lineEnd);
+  const m = /,?\s*(\/\/.*|\/\*.*?\*\/)\s*$/.exec(slice);
+  return m ? stripCommentMarkers(m[1]) : '';
+};
+
+export const extractAdjacentComments = (
+  text: string,
+  keyOffset: number,
+  valueOffset: number,
+  valueLength: number,
+): AdjacentComments => ({
+  leading: findLeading(text, keyOffset),
+  trailing: findTrailing(text, valueOffset, valueLength),
+});
+```
+
+- [ ] **Step 3: Type-check**
+
+```bash
+cd admin && npx tsc --noEmit
+```
+
+Expected: exit 0.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add admin/src/components/settings/envPill.ts admin/src/components/settings/comments.ts
+git commit -m "admin(settings): pure helpers for env pills and comment extraction"
+```
+
+---
+
+## Task 3: Implement `jsoncEdit.ts` save helper
+
+**Files:**
+- Create: `admin/src/components/settings/jsoncEdit.ts`
+
+- [ ] **Step 1: Write the wrapper**
+
+```ts
+// admin/src/components/settings/jsoncEdit.ts
+import { applyEdits, modify, type JSONPath } from 'jsonc-parser';
+
+const FORMATTING = {
+  formattingOptions: { tabSize: 2, insertSpaces: true, eol: '\n' as const },
+};
+
+export const editJsonc = (text: string, path: JSONPath, value: unknown): string => {
+  const edits = modify(text, path, value, FORMATTING);
+  return edits.length === 0 ? text : applyEdits(text, edits);
+};
+```
+
+- [ ] **Step 2: Type-check**
+
+```bash
+cd admin && npx tsc --noEmit
+```
+
+Expected: exit 0.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add admin/src/components/settings/jsoncEdit.ts
+git commit -m "admin(settings): editJsonc wrapper around jsonc-parser modify"
+```
+
+---
+
+## Task 4: Build leaf widgets
+
+Each leaf takes `{ value, path, onChange }`. `onChange(newValue)` is wired by the parent (`JsoncNode`) to call `editJsonc` and push the new text into the store. Leaves are presentational only.
+
+**Files:**
+- Create: `admin/src/components/settings/widgets/StringInput.tsx`
+- Create: `admin/src/components/settings/widgets/NumberInput.tsx`
+- Create: `admin/src/components/settings/widgets/BooleanToggle.tsx`
+- Create: `admin/src/components/settings/widgets/NullChip.tsx`
+- Create: `admin/src/components/settings/widgets/EnvPill.tsx`
+
+- [ ] **Step 1: `widgets/StringInput.tsx`**
+
+```tsx
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  value: string;
+  path: JSONPath;
+  onChange: (next: string) => void;
+};
+
+export const StringInput = ({ value, path, onChange }: Props) => (
+  <input
+    type="text"
+    className="settings-widget settings-widget-string"
+    data-testid={`field-${path.join('.')}`}
+    value={value}
+    spellCheck={false}
+    onChange={e => onChange(e.target.value)}
+  />
+);
+```
+
+- [ ] **Step 2: `widgets/NumberInput.tsx`**
+
+Bad numeric input must not corrupt the file text. We hold the raw input string in local state and only call `onChange` when it parses to a finite number.
+
+```tsx
+import { useState } from 'react';
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  value: number;
+  path: JSONPath;
+  onChange: (next: number) => void;
+};
+
+export const NumberInput = ({ value, path, onChange }: Props) => {
+  const [draft, setDraft] = useState(String(value));
+  const [invalid, setInvalid] = useState(false);
+  return (
+    <input
+      type="text"
+      inputMode="decimal"
+      className={'settings-widget settings-widget-number' + (invalid ? ' invalid' : '')}
+      data-testid={`field-${path.join('.')}`}
+      value={draft}
+      onChange={e => {
+        const next = e.target.value;
+        setDraft(next);
+        const parsed = Number(next);
+        if (next.trim() !== '' && Number.isFinite(parsed)) {
+          setInvalid(false);
+          onChange(parsed);
+        } else {
+          setInvalid(true);
+        }
+      }}
+    />
+  );
+};
+```
+
+- [ ] **Step 3: `widgets/BooleanToggle.tsx`**
+
+The repo already uses `@radix-ui/react-switch`. Use it.
+
+```tsx
+import * as Switch from '@radix-ui/react-switch';
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  value: boolean;
+  path: JSONPath;
+  onChange: (next: boolean) => void;
+};
+
+export const BooleanToggle = ({ value, path, onChange }: Props) => (
+  <Switch.Root
+    checked={value}
+    onCheckedChange={onChange}
+    className="settings-widget settings-widget-boolean"
+    data-testid={`field-${path.join('.')}`}
+  >
+    <Switch.Thumb className="settings-widget-boolean-thumb" />
+  </Switch.Root>
+);
+```
+
+- [ ] **Step 4: `widgets/NullChip.tsx`**
+
+```tsx
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = { path: JSONPath };
+
+export const NullChip = ({ path }: Props) => (
+  <span
+    className="settings-widget settings-widget-null"
+    data-testid={`field-${path.join('.')}`}
+  >null</span>
+);
+```
+
+- [ ] **Step 5: `widgets/EnvPill.tsx`**
+
+```tsx
+import { useTranslation } from 'react-i18next';
+import type { JSONPath } from 'jsonc-parser';
+import type { EnvPlaceholder } from '../envPill';
+
+type Props = {
+  placeholder: EnvPlaceholder;
+  path: JSONPath;
+};
+
+export const EnvPill = ({ placeholder, path }: Props) => {
+  const { t } = useTranslation();
+  return (
+    <span
+      className="settings-widget settings-widget-env"
+      role="note"
+      title={t('admin_settings.env_pill.tooltip')}
+      data-testid={`env-${path.join('.')}`}
+    >
+      <span className="settings-widget-env-icon" aria-hidden>ⓔ</span>
+      <span className="settings-widget-env-name">{placeholder.variable}</span>
+      {placeholder.defaultValue !== null && (
+        <span className="settings-widget-env-default">
+          {' '}default: <code>{placeholder.defaultValue}</code>
+        </span>
+      )}
+    </span>
+  );
+};
+```
+
+- [ ] **Step 6: Type-check**
+
+```bash
+cd admin && npx tsc --noEmit
+```
+
+Expected: exit 0.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add admin/src/components/settings/widgets
+git commit -m "admin(settings): leaf widgets (string, number, bool, null, env pill)"
+```
+
+---
+
+## Task 5: Build group widgets and the dispatcher
+
+`ObjectGroup` and `ArrayGroup` use the native `<details>`/`<summary>` for collapsibility (a11y comes for free). `JsoncNode` is the dispatcher: given an AST node it picks the right widget.
+
+**Files:**
+- Create: `admin/src/components/settings/widgets/ObjectGroup.tsx`
+- Create: `admin/src/components/settings/widgets/ArrayGroup.tsx`
+- Create: `admin/src/components/settings/JsoncNode.tsx`
+- Create: `admin/src/components/settings/CommentLabel.tsx`
+
+- [ ] **Step 1: `CommentLabel.tsx`**
+
+```tsx
+type Props = {
+  leading: string;
+  trailing: string;
+  htmlId: string;
+};
+
+export const CommentLabel = ({ leading, trailing, htmlId }: Props) => {
+  if (!leading && !trailing) return null;
+  return (
+    <div className="settings-comment" id={htmlId}>
+      {leading && <span className="settings-comment-leading">{leading}</span>}
+      {trailing && <span className="settings-comment-trailing"> // {trailing}</span>}
+    </div>
+  );
+};
+```
+
+- [ ] **Step 2: `widgets/ObjectGroup.tsx`**
+
+```tsx
+import type { ReactNode } from 'react';
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  path: JSONPath;
+  childCount: number;
+  children: ReactNode;
+};
+
+export const ObjectGroup = ({ path, childCount, children }: Props) => (
+  <details
+    className="settings-group settings-group-object"
+    data-testid={`group-${path.join('.') || 'root'}`}
+    open
+  >
+    <summary>{`{ ${childCount} ${childCount === 1 ? 'key' : 'keys'} }`}</summary>
+    <div className="settings-group-body">{children}</div>
+  </details>
+);
+```
+
+- [ ] **Step 3: `widgets/ArrayGroup.tsx`**
+
+```tsx
+import type { ReactNode } from 'react';
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  path: JSONPath;
+  childCount: number;
+  children: ReactNode;
+};
+
+export const ArrayGroup = ({ path, childCount, children }: Props) => (
+  <details
+    className="settings-group settings-group-array"
+    data-testid={`group-${path.join('.') || 'root'}`}
+    open
+  >
+    <summary>{`[ ${childCount} ${childCount === 1 ? 'item' : 'items'} ]`}</summary>
+    <div className="settings-group-body">{children}</div>
+  </details>
+);
+```
+
+- [ ] **Step 4: `JsoncNode.tsx`**
+
+This is the only place that decides which widget renders. It receives a `Node` (from `parseTree`), the source text (so it can pull raw slices for env detection and comments), and an `onEdit` callback.
+
+```tsx
+import type { JSONPath, Node } from 'jsonc-parser';
+import { getNodePath } from 'jsonc-parser';
+import { CommentLabel } from './CommentLabel';
+import { extractAdjacentComments } from './comments';
+import { matchEnvPlaceholder } from './envPill';
+import { StringInput } from './widgets/StringInput';
+import { NumberInput } from './widgets/NumberInput';
+import { BooleanToggle } from './widgets/BooleanToggle';
+import { NullChip } from './widgets/NullChip';
+import { EnvPill } from './widgets/EnvPill';
+import { ObjectGroup } from './widgets/ObjectGroup';
+import { ArrayGroup } from './widgets/ArrayGroup';
+
+type Props = {
+  /** The value node (not the property node). */
+  node: Node;
+  /** The property node, when this value is the value-side of `"key": value`. */
+  property?: Node;
+  text: string;
+  onEdit: (path: JSONPath, value: unknown) => void;
+};
+
+export const JsoncNode = ({ node, property, text, onEdit }: Props) => {
+  const path = getNodePath(node);
+
+  // Comment lookup is based on the property node when present (object child),
+  // otherwise the value node directly (array element / root).
+  const anchor = property ?? node;
+  const { leading, trailing } = extractAdjacentComments(
+    text,
+    anchor.offset,
+    node.offset,
+    node.length,
+  );
+  const commentId = `settings-comment-${path.join('.') || 'root'}`;
+
+  const wrap = (label: React.ReactNode, control: React.ReactNode) => (
+    <div className="settings-row" aria-describedby={commentId}>
+      {label && <span className="settings-key">{label}</span>}
+      <span className="settings-value">{control}</span>
+      <CommentLabel leading={leading} trailing={trailing} htmlId={commentId} />
+    </div>
+  );
+
+  // Property name for object children:
+  const keyLabel =
+    property?.type === 'property' && property.children?.[0]?.type === 'string'
+      ? String(property.children[0].value)
+      : null;
+
+  if (node.type === 'object') {
+    return wrap(
+      keyLabel,
+      <ObjectGroup path={path} childCount={node.children?.length ?? 0}>
+        {(node.children ?? []).map((prop, i) => {
+          const valueNode = prop.children?.[1];
+          if (!valueNode) return null;
+          return (
+            <JsoncNode
+              key={i}
+              node={valueNode}
+              property={prop}
+              text={text}
+              onEdit={onEdit}
+            />
+          );
+        })}
+      </ObjectGroup>,
+    );
+  }
+
+  if (node.type === 'array') {
+    return wrap(
+      keyLabel,
+      <ArrayGroup path={path} childCount={node.children?.length ?? 0}>
+        {(node.children ?? []).map((child, i) => (
+          <JsoncNode key={i} node={child} text={text} onEdit={onEdit} />
+        ))}
+      </ArrayGroup>,
+    );
+  }
+
+  if (node.type === 'string') {
+    const raw = text.slice(node.offset, node.offset + node.length);
+    const env = matchEnvPlaceholder(raw);
+    if (env) return wrap(keyLabel, <EnvPill placeholder={env} path={path} />);
+    return wrap(
+      keyLabel,
+      <StringInput
+        value={String(node.value)}
+        path={path}
+        onChange={v => onEdit(path, v)}
+      />,
+    );
+  }
+
+  if (node.type === 'number') {
+    return wrap(
+      keyLabel,
+      <NumberInput
+        value={Number(node.value)}
+        path={path}
+        onChange={v => onEdit(path, v)}
+      />,
+    );
+  }
+
+  if (node.type === 'boolean') {
+    return wrap(
+      keyLabel,
+      <BooleanToggle
+        value={Boolean(node.value)}
+        path={path}
+        onChange={v => onEdit(path, v)}
+      />,
+    );
+  }
+
+  if (node.type === 'null') {
+    return wrap(keyLabel, <NullChip path={path} />);
+  }
+
+  // 'property' nodes are handled by their parent object branch above.
+  return null;
+};
+```
+
+- [ ] **Step 5: Type-check**
+
+```bash
+cd admin && npx tsc --noEmit
+```
+
+Expected: exit 0.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add admin/src/components/settings
+git commit -m "admin(settings): group widgets, JsoncNode dispatcher, CommentLabel"
+```
+
+---
+
+## Task 6: Build `FormView`, `ParseErrorBanner`, `ModeToggle`
+
+**Files:**
+- Create: `admin/src/components/settings/FormView.tsx`
+- Create: `admin/src/components/settings/ParseErrorBanner.tsx`
+- Create: `admin/src/components/settings/ModeToggle.tsx`
+
+- [ ] **Step 1: `ParseErrorBanner.tsx`**
+
+```tsx
+import { Trans } from 'react-i18next';
+
+type Props = {
+  message: string;
+  onSwitchToRaw: () => void;
+};
+
+export const ParseErrorBanner = ({ message, onSwitchToRaw }: Props) => (
+  <div className="settings-parse-error" role="alert" data-testid="parse-error-banner">
+    <strong><Trans i18nKey="admin_settings.parse_error.title" /></strong>
+    <pre className="settings-parse-error-detail">{message}</pre>
+    <button type="button" onClick={onSwitchToRaw} data-testid="parse-error-switch-raw">
+      <Trans i18nKey="admin_settings.parse_error.cta" />
+    </button>
+  </div>
+);
+```
+
+- [ ] **Step 2: `FormView.tsx`**
+
+```tsx
+import { parseTree, type JSONPath, type ParseError } from 'jsonc-parser';
+import { useStore } from '../../store/store';
+import { editJsonc } from './jsoncEdit';
+import { JsoncNode } from './JsoncNode';
+import { ParseErrorBanner } from './ParseErrorBanner';
+
+type Props = {
+  onSwitchToRaw: () => void;
+};
+
+const formatErrors = (errors: ParseError[]): string =>
+  errors.length === 0
+    ? ''
+    : errors.map(e => `offset ${e.offset}: ${ParseErrorMessage[e.error] ?? 'parse error'}`).join('\n');
+
+const ParseErrorMessage: Record<number, string> = {
+  1: 'Invalid symbol',
+  2: 'Invalid number format',
+  3: 'Property name expected',
+  4: 'Value expected',
+  5: 'Colon expected',
+  6: 'Comma expected',
+  7: 'Closing brace expected',
+  8: 'Closing bracket expected',
+  9: 'End of file expected',
+  16: 'Unexpected end of comment',
+  17: 'Unexpected end of string',
+  18: 'Unexpected end of number',
+  19: 'Invalid unicode',
+  20: 'Invalid escape character',
+  21: 'Invalid character',
+};
+
+export const FormView = ({ onSwitchToRaw }: Props) => {
+  const text = useStore(s => s.settings) ?? '';
+
+  const errors: ParseError[] = [];
+  const tree = parseTree(text, errors, { allowTrailingComma: true });
+
+  const onEdit = (path: JSONPath, value: unknown) => {
+    useStore.getState().setSettings(editJsonc(text, path, value));
+  };
+
+  if (!tree || errors.length > 0) {
+    return <ParseErrorBanner message={formatErrors(errors)} onSwitchToRaw={onSwitchToRaw} />;
+  }
+
+  return (
+    <div className="settings-form" data-testid="settings-form-view">
+      <JsoncNode node={tree} text={text} onEdit={onEdit} />
+    </div>
+  );
+};
+```
+
+- [ ] **Step 3: `ModeToggle.tsx`**
+
+```tsx
+import { Trans } from 'react-i18next';
+
+export type Mode = 'form' | 'raw';
+
+type Props = {
+  mode: Mode;
+  onChange: (mode: Mode) => void;
+};
+
+export const ModeToggle = ({ mode, onChange }: Props) => (
+  <div className="settings-mode-toggle" role="tablist" aria-label="Editor mode">
+    <button
+      type="button"
+      role="tab"
+      aria-selected={mode === 'form'}
+      data-testid="mode-toggle-form"
+      className={mode === 'form' ? 'active' : ''}
+      onClick={() => onChange('form')}
+    >
+      <Trans i18nKey="admin_settings.mode.form" />
+    </button>
+    <button
+      type="button"
+      role="tab"
+      aria-selected={mode === 'raw'}
+      data-testid="mode-toggle-raw"
+      className={mode === 'raw' ? 'active' : ''}
+      onClick={() => onChange('raw')}
+    >
+      <Trans i18nKey="admin_settings.mode.raw" />
+    </button>
+  </div>
+);
+```
+
+- [ ] **Step 4: Type-check**
+
+```bash
+cd admin && npx tsc --noEmit
+```
+
+Expected: exit 0.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add admin/src/components/settings
+git commit -m "admin(settings): FormView, ParseErrorBanner, ModeToggle"
+```
+
+---
+
+## Task 7: Restructure `SettingsPage.tsx`
+
+The page becomes a shell that toggles between `FormView` and the existing raw textarea. Save / Validate / Restart and the Prettify feature flag stay where they were in the previous commit.
+
+**Files:**
+- Modify: `admin/src/pages/SettingsPage.tsx`
+
+- [ ] **Step 1: Replace the file**
+
+```tsx
+import React, { useState } from 'react';
+import { useStore } from '../store/store';
+import { isJSONClean, cleanComments } from '../utils/utils';
+import { Trans, useTranslation } from 'react-i18next';
+import { IconButton } from '../components/IconButton';
+import { RotateCw, Save, AlignLeft, ShieldCheck } from 'lucide-react';
+import { FormView } from '../components/settings/FormView';
+import { ModeToggle, type Mode } from '../components/settings/ModeToggle';
+
+const TAB_INDENT = '  ';
+
+export const SettingsPage = () => {
+  const { t } = useTranslation();
+  const settingsSocket = useStore(state => state.settingsSocket);
+  const settings = useStore(state => state.settings) ?? '';
+
+  const [mode, setMode] = useState<Mode>('form');
+  const [exposeExperimental] = useState(false);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key !== 'Tab') return;
+    e.preventDefault();
+    const target = e.currentTarget;
+    const { selectionStart, selectionEnd, value } = target;
+    const next = value.substring(0, selectionStart) + TAB_INDENT + value.substring(selectionEnd);
+    useStore.getState().setSettings(next);
+    requestAnimationFrame(() => {
+      target.selectionStart = target.selectionEnd = selectionStart + TAB_INDENT.length;
+    });
+  };
+
+  const showToast = (titleKey: string, success: boolean) => {
+    useStore.getState().setToastState({ open: true, title: t(titleKey), success });
+  };
+
+  const testJSON = () => {
+    if (isJSONClean(settings)) showToast('admin_settings.toast.validation_ok', true);
+    else showToast('admin_settings.toast.validation_failed', false);
+  };
+
+  const prettifyJSON = () => {
+    try {
+      const obj = JSON.parse(cleanComments(settings) ?? '');
+      if (window.confirm(t('admin_settings.prettify_confirm'))) {
+        useStore.getState().setSettings(JSON.stringify(obj, null, 2));
+      }
+    } catch {
+      showToast('admin_settings.toast.prettify_failed', false);
+    }
+  };
+
+  const handleSave = () => {
+    if (!isJSONClean(settings)) return showToast('admin_settings.toast.json_invalid', false);
+    if (!settingsSocket?.connected) return showToast('admin_settings.toast.disconnected', false);
+    settingsSocket.emit('saveSettings', settings);
+    showToast('admin_settings.toast.saved', true);
+  };
+
+  return (
+    <div className="settings-page">
+      <h1><Trans i18nKey="admin_settings.current" /></h1>
+
+      <ModeToggle mode={mode} onChange={setMode} />
+
+      {mode === 'form'
+        ? <FormView onSwitchToRaw={() => setMode('raw')} />
+        : (
+          <textarea
+            value={settings}
+            className="settings"
+            data-testid="settings-raw-textarea"
+            spellCheck={false}
+            onKeyDown={handleKeyDown}
+            onChange={v => useStore.getState().setSettings(v.target.value)}
+          />
+        )
+      }
+
+      <div className="settings-button-bar">
+        <IconButton
+          className="settingsButton"
+          data-testid="save-settings-button"
+          icon={<Save />}
+          title={<Trans i18nKey="admin_settings.current_save.value" />}
+          onClick={handleSave}
+        />
+        <IconButton
+          className="settingsButton"
+          data-testid="test-settings-button"
+          icon={<ShieldCheck />}
+          title={<Trans i18nKey="admin_settings.current_test.value" />}
+          onClick={testJSON}
+        />
+        {exposeExperimental && (
+          <IconButton
+            className="settingsButton"
+            data-testid="prettify-settings-button"
+            icon={<AlignLeft />}
+            title={<Trans i18nKey="admin_settings.current_prettify.value" />}
+            onClick={prettifyJSON}
+          />
+        )}
+        <IconButton
+          className="settingsButton"
+          data-testid="restart-etherpad-button"
+          icon={<RotateCw />}
+          title={<Trans i18nKey="admin_settings.current_restart.value" />}
+          onClick={() => settingsSocket?.emit('restartServer')}
+        />
+      </div>
+
+      <div className="settings-links">
+        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad/wiki/Example-Production-Settings.JSON">
+          <Trans i18nKey="admin_settings.current_example-prod" />
+        </a>
+        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad/wiki/Example-Development-Settings.JSON">
+          <Trans i18nKey="admin_settings.current_example-devel" />
+        </a>
+      </div>
+    </div>
+  );
+};
+```
+
+- [ ] **Step 2: Type-check**
+
+```bash
+cd admin && npx tsc --noEmit
+```
+
+Expected: exit 0.
+
+- [ ] **Step 3: Build**
+
+```bash
+cd admin && npx vite build --outDir ../src/templates/admin --emptyOutDir
+```
+
+Expected: build completes; the only warning may be the existing chunk-size warning.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add admin/src/pages/SettingsPage.tsx
+git commit -m "admin(settings): toggle FormView and raw textarea from SettingsPage"
+```
+
+---
+
+## Task 8: CSS
+
+**Files:**
+- Modify: `admin/src/App.css`
+
+- [ ] **Step 1: Append the styles**
+
+```css
+/* --- mode toggle --- */
+.settings-mode-toggle {
+  display: inline-flex;
+  border: 1px solid #444;
+  border-radius: 6px;
+  overflow: hidden;
+  margin-bottom: 12px;
+}
+.settings-mode-toggle button {
+  padding: 6px 14px;
+  border: 0;
+  background: transparent;
+  color: #d4d4d4;
+  cursor: pointer;
+}
+.settings-mode-toggle button.active {
+  background: #007acc;
+  color: #fff;
+}
+
+/* --- form tree --- */
+.settings-form {
+  font-family: "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
+  font-size: 13px;
+  background: #1e1e1e;
+  color: #d4d4d4;
+  padding: 12px;
+  border: 1px solid #333;
+  border-radius: 4px;
+}
+.settings-row {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 4px 0;
+}
+.settings-key {
+  font-weight: 600;
+  color: #9cdcfe;
+}
+.settings-value {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+.settings-comment {
+  font-style: italic;
+  color: #6a9955;
+  white-space: pre-wrap;
+}
+.settings-comment-trailing {
+  color: #808080;
+  font-style: normal;
+}
+
+/* --- group widgets --- */
+.settings-group > summary {
+  cursor: pointer;
+  color: #c586c0;
+}
+.settings-group-body {
+  padding-left: 16px;
+  border-left: 1px solid #333;
+  margin-left: 4px;
+}
+
+/* --- leaf widgets --- */
+.settings-widget-string,
+.settings-widget-number {
+  background: #2d2d2d;
+  color: #d4d4d4;
+  border: 1px solid #444;
+  border-radius: 3px;
+  padding: 2px 6px;
+  font-family: inherit;
+  font-size: inherit;
+  min-width: 220px;
+}
+.settings-widget-number.invalid {
+  border-color: #ce5050;
+}
+.settings-widget-null {
+  color: #569cd6;
+  font-style: italic;
+}
+.settings-widget-env {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: #2d2d4d;
+  color: #d4d4d4;
+  border: 1px dashed #5577aa;
+  border-radius: 12px;
+  padding: 1px 8px;
+}
+.settings-widget-env code {
+  background: transparent;
+  color: #ce9178;
+}
+
+/* --- parse error --- */
+.settings-parse-error {
+  border: 1px solid #ce5050;
+  background: #3a1f1f;
+  color: #fdd;
+  padding: 12px;
+  border-radius: 4px;
+}
+.settings-parse-error-detail {
+  white-space: pre-wrap;
+  font-family: inherit;
+}
+.settings-parse-error button {
+  margin-top: 8px;
+  background: #ce5050;
+  color: #fff;
+  border: 0;
+  padding: 6px 12px;
+  border-radius: 3px;
+  cursor: pointer;
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add admin/src/App.css
+git commit -m "admin(settings): styles for tree, widgets, env pill, parse error"
+```
+
+---
+
+## Task 9: i18n keys
+
+**Files:**
+- Modify: `src/locales/en.json`
+
+- [ ] **Step 1: Add keys after the existing `admin_settings.*` block**
+
+Insert the following lines next to the other `admin_settings.toast.*` keys (already added in the previous commit):
+
+```json
+"admin_settings.mode.form": "Form",
+"admin_settings.mode.raw": "Raw",
+"admin_settings.parse_error.title": "Cannot parse settings.json",
+"admin_settings.parse_error.cta": "Switch to raw to edit",
+"admin_settings.env_pill.tooltip": "Environment variable. Edit in raw mode.",
+```
+
+- [ ] **Step 2: Validate JSON**
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('src/locales/en.json','utf8'))"
+```
+
+Expected: no output, exit 0.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/locales/en.json
+git commit -m "admin(settings): i18n keys for form mode, parse error, env pill"
+```
+
+---
+
+## Task 10: Playwright specs (TDD: write first, satisfy second)
+
+These are the verification gate. Write all of them, run, see failures unrelated to logic (e.g. selectors), tighten until they pass.
+
+**Files:**
+- Modify: `src/tests/frontend-new/admin-spec/adminsettings.spec.ts`
+
+The existing file already contains: `Are Settings visible…`, `preserves /* */ comments after save round-trip`, `validate button toasts…`, `restart works`. Append these inside `test.describe('admin settings', …)`:
+
+- [ ] **Step 1: Append `comment is rendered as help text` spec**
+
+```ts
+test('form view renders leading comment as help text for known key', async ({page}) => {
+  await page.goto('http://localhost:9001/admin/settings');
+  await page.getByTestId('mode-toggle-form').click();
+  await page.waitForSelector('[data-testid="settings-form-view"]');
+  // settings.json ships with a leading comment above `dbType` (or `title`).
+  // Assert that *some* row exposes a non-empty `.settings-comment-leading`.
+  const firstComment = page.locator('.settings-comment-leading').first();
+  await expect(firstComment).toBeVisible({timeout: 10000});
+  expect((await firstComment.textContent())?.trim().length ?? 0).toBeGreaterThan(0);
+});
+```
+
+- [ ] **Step 2: Append `editing a string field round-trips` spec**
+
+```ts
+test('editing title via form input round-trips through save', async ({page}) => {
+  await page.goto('http://localhost:9001/admin/settings');
+  await page.getByTestId('mode-toggle-raw').click();
+  const raw = page.getByTestId('settings-raw-textarea');
+  const original = await raw.inputValue();
+
+  await page.getByTestId('mode-toggle-form').click();
+  const titleField = page.getByTestId('field-title');
+  await expect(titleField).toBeVisible({timeout: 10000});
+  await titleField.fill('Etherpad-Form-Edit');
+  await page.getByTestId('save-settings-button').click();
+  await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+
+  await page.reload();
+  await page.getByTestId('mode-toggle-raw').click();
+  const after = await page.getByTestId('settings-raw-textarea').inputValue();
+  expect(after).toContain('"title": "Etherpad-Form-Edit"');
+  // Comments above title must survive
+  const titleIdx = after.indexOf('"title"');
+  expect(after.slice(0, titleIdx)).toMatch(/\/\*[\s\S]*?\*\//);
+
+  // Restore
+  await page.getByTestId('settings-raw-textarea').fill(original);
+  await page.getByTestId('save-settings-button').click();
+  await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+});
+```
+
+- [ ] **Step 3: Append `boolean toggle round-trips` spec**
+
+```ts
+test('boolean toggle round-trips through save', async ({page}) => {
+  await page.goto('http://localhost:9001/admin/settings');
+  await page.getByTestId('mode-toggle-raw').click();
+  const original = await page.getByTestId('settings-raw-textarea').inputValue();
+
+  await page.getByTestId('mode-toggle-form').click();
+  const toggle = page.getByTestId('field-requireAuthentication');
+  await expect(toggle).toBeVisible({timeout: 10000});
+  const before = await toggle.getAttribute('aria-checked');
+  await toggle.click();
+  await page.getByTestId('save-settings-button').click();
+  await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+
+  await page.reload();
+  await page.getByTestId('mode-toggle-form').click();
+  const after = await page.getByTestId('field-requireAuthentication').getAttribute('aria-checked');
+  expect(after).not.toEqual(before);
+
+  // Restore
+  await page.getByTestId('mode-toggle-raw').click();
+  await page.getByTestId('settings-raw-textarea').fill(original);
+  await page.getByTestId('save-settings-button').click();
+  await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+});
+```
+
+- [ ] **Step 4: Append `env placeholder renders as read-only pill` spec**
+
+```ts
+test('env placeholder renders as read-only pill (no input)', async ({page}) => {
+  await page.goto('http://localhost:9001/admin/settings');
+  await page.getByTestId('mode-toggle-form').click();
+  await page.waitForSelector('[data-testid="settings-form-view"]');
+  // settings.json ships ${SSO_ISSUER:http://localhost:9001} on sso.issuer
+  const pill = page.getByTestId('env-sso.issuer');
+  await expect(pill).toBeVisible({timeout: 10000});
+  // No <input> exists for that path
+  await expect(page.getByTestId('field-sso.issuer')).toHaveCount(0);
+});
+```
+
+- [ ] **Step 5: Append `raw → form on broken JSON shows banner` spec**
+
+```ts
+test('toggling form on broken raw JSON shows parse error banner', async ({page}) => {
+  await page.goto('http://localhost:9001/admin/settings');
+  await page.getByTestId('mode-toggle-raw').click();
+  const raw = page.getByTestId('settings-raw-textarea');
+  const original = await raw.inputValue();
+
+  await raw.fill('{ "broken":');
+  await page.getByTestId('mode-toggle-form').click();
+  await expect(page.getByTestId('parse-error-banner')).toBeVisible();
+
+  // CTA returns to raw view
+  await page.getByTestId('parse-error-switch-raw').click();
+  await expect(raw).toBeVisible();
+
+  // Restore
+  await raw.fill(original);
+  await page.getByTestId('save-settings-button').click();
+  await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+});
+```
+
+- [ ] **Step 6: Run the new specs locally**
+
+```bash
+cd src && npx playwright test admin-spec/adminsettings.spec.ts --reporter=line
+```
+
+Expected: all specs pass. (Do NOT use `--headed` — see CLAUDE memory.)
+
+If a spec fails because `settings.json` doesn't ship with the assumed key (e.g. `dbType`, `title`, `sso.issuer`), update the spec to a key that *is* present in the shipped settings.json. Do not change widget code to satisfy a spec that's looking at the wrong key.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/tests/frontend-new/admin-spec/adminsettings.spec.ts
+git commit -m "admin(settings): playwright specs for form view, env pill, parse error, round-trip"
+```
+
+---
+
+## Task 11: Manual smoke + push
+
+- [ ] **Step 1: Start dev server**
+
+```bash
+cd src && NODE_ENV=development node --require tsx/cjs node/server.ts
+```
+
+Login at http://localhost:9001/admin/login as `admin` / `changeme1`, go to `/admin/settings`. Verify by hand:
+
+1. Form mode is the default; tree renders with collapsible groups.
+2. Comments appear under their keys.
+3. SSO issuer renders as a pill, not a text input.
+4. Edit `title`, click Save, reload — change persists, comments survive.
+5. Toggle to Raw — textarea contains the file, comments intact.
+6. Break the JSON in raw, toggle to Form — banner appears, "Switch to raw" returns you.
+7. Tab key in raw still inserts spaces.
+8. Restart button still works (requires the dev server to come back up; `Ctrl-C` if you don't want to wait).
+
+- [ ] **Step 2: Push**
+
+```bash
+git push fork takeover/7666-admin-settings-editor
+```
+
+- [ ] **Step 3: Update PR #7709 title and body**
+
+```bash
+gh pr edit 7709 --repo ether/etherpad \
+  --title "admin: parsed JSONC settings editor (takes over #7666, closes #7603)" \
+  --body-file <(cat <<'EOF'
+Replaces the textarea on `/admin/settings` with a parsed JSONC tree:
+each key is rendered with the right typed widget (string input, number,
+toggle, env pill, collapsible object/array) and its leading `/* */`
+comment surfaces as inline help. A "Raw" mode toggle keeps the existing
+textarea editor behind it for power users and structural edits.
+
+Round-trip is byte-identical for untouched regions: edits go through
+`jsonc-parser`'s `modify()` so comments, key order, whitespace, and
+`${ENV:default}` placeholders all survive.
+
+Takes over #7666 (original author AWOL). Closes #7603.
+
+## Spec / plan
+- Design: `docs/superpowers/specs/2026-05-09-admin-settings-parsed-view-design.md`
+- Plan: `docs/superpowers/plans/2026-05-09-admin-settings-parsed-view.md`
+
+## Tests
+- Existing specs (comments-preserved, validate, restart) continue to
+  pass; restart now keys off `data-testid` instead of `.nth(1)`.
+- New: form renders comment as help text; string round-trips through
+  save; boolean toggle round-trips; env placeholder renders as pill;
+  broken raw JSON surfaces a parse-error banner with a "Switch to raw"
+  CTA.
+
+## Out of scope (follow-ups)
+- Add/remove keys from the form (raw mode is the escape hatch).
+- Editing `${VAR:default}` placeholders in form mode.
+- Schema-driven help text.
+
+## Semver
+patch — admin UI only, no API or settings-file format changes.
+EOF
+)
+```
+
+- [ ] **Step 4: Re-trigger Qodo review**
+
+```bash
+gh pr comment 7709 --repo ether/etherpad --body "/review"
+```
+
+- [ ] **Step 5: Install on local etherpad and share test URL with John**
+
+(Skipped — already running in this session at http://localhost:9001/admin/settings)
+
+---
+
+## Self-review checklist (for the executor)
+
+After completing all tasks, before declaring done:
+
+- [ ] `cd admin && npx tsc --noEmit` exits 0.
+- [ ] `cd admin && npx vite build --outDir ../src/templates/admin --emptyOutDir` succeeds.
+- [ ] `cd src && npx playwright test admin-spec/adminsettings.spec.ts --reporter=line` is green.
+- [ ] `git diff develop --stat` shows only files in `admin/src/`, `admin/package.json`, `pnpm-lock.yaml`, `src/locales/en.json`, `src/templates/admin/` (build output), `src/tests/frontend-new/admin-spec/adminsettings.spec.ts`, `src/tests/frontend-new/helper/adminhelper.ts`, and the docs/superpowers/ files.
+- [ ] No `console.log` or `debugger` left in `admin/src/components/settings/`.
+- [ ] No fabricated comments referencing the PR / task / "FIX:" / "John" in source files.
+- [ ] PR body updated and `/review` posted.

From 5700e93e174299bc64270e4e2d92faa5742df9c1 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:01:55 +0100
Subject: [PATCH 05/31] admin(settings): add jsonc-parser dep

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/package.json | 3 ++-
 pnpm-lock.yaml     | 8 ++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/admin/package.json b/admin/package.json
index 3084b5fbc2b..51936cc150f 100644
--- a/admin/package.json
+++ b/admin/package.json
@@ -11,7 +11,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@radix-ui/react-switch": "^1.2.6"
+    "@radix-ui/react-switch": "^1.2.6",
+    "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
     "@radix-ui/react-dialog": "^1.1.15",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 661fd42d5eb..cc3c4653584 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -46,6 +46,9 @@ importers:
       '@radix-ui/react-switch':
         specifier: ^1.2.6
         version: 1.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      jsonc-parser:
+        specifier: ^3.3.1
+        version: 3.3.1
     devDependencies:
       '@radix-ui/react-dialog':
         specifier: ^1.1.15
@@ -4062,6 +4065,9 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
+  jsonc-parser@3.3.1:
+    resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
+
   jsonfile@4.0.0:
     resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==}
 
@@ -9686,6 +9692,8 @@ snapshots:
 
   json5@2.2.3: {}
 
+  jsonc-parser@3.3.1: {}
+
   jsonfile@4.0.0:
     optionalDependencies:
       graceful-fs: 4.2.11

From d358c122ad27ba33ebdd2f5049fed144e4cf2d39 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:02:29 +0100
Subject: [PATCH 06/31] admin(settings): pure helpers for env pills and comment
 extraction

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/comments.ts | 85 +++++++++++++++++++++++
 admin/src/components/settings/envPill.ts  | 21 ++++++
 2 files changed, 106 insertions(+)
 create mode 100644 admin/src/components/settings/comments.ts
 create mode 100644 admin/src/components/settings/envPill.ts

diff --git a/admin/src/components/settings/comments.ts b/admin/src/components/settings/comments.ts
new file mode 100644
index 00000000000..89e410d6335
--- /dev/null
+++ b/admin/src/components/settings/comments.ts
@@ -0,0 +1,85 @@
+// admin/src/components/settings/comments.ts
+//
+// Given the source text and a property's `keyOffset` (jsonc-parser's
+// Node.offset for the property node), extract:
+//   - `leading`: the contiguous run of `/* */` or `//` comments
+//     immediately above the key. At most one blank line is allowed
+//     between the comment block and the key.
+//   - `trailing`: a single `// ...` or `/* ... */` on the same line
+//     as the value, after any trailing comma.
+
+export type AdjacentComments = {
+  leading: string;
+  trailing: string;
+};
+
+const LINE_BREAK = /\r?\n/;
+
+const stripCommentMarkers = (raw: string): string => {
+  // raw is a concatenation of comment tokens separated by newlines.
+  // Drop /* */ and // markers and trim each line.
+  return raw
+    .split(LINE_BREAK)
+    .map(line => line
+      .replace(/^\s*\/\*+/, '')
+      .replace(/\*+\/\s*$/, '')
+      .replace(/^\s*\*\s?/, '')
+      .replace(/^\s*\/\/\s?/, '')
+      .trim())
+    .filter(line => line.length > 0)
+    .join(' ');
+};
+
+const findLeading = (text: string, keyOffset: number): string => {
+  // Walk backwards from keyOffset to the start of the line containing it.
+  const lineStart = text.lastIndexOf('\n', keyOffset - 1) + 1;
+  let cursor = lineStart;
+  let blankLineSeen = false;
+  const collected: string[] = [];
+
+  while (cursor > 0) {
+    // Look at the previous line.
+    const prevLineEnd = cursor - 1; // the '\n' before our cursor's line
+    const prevLineStart = text.lastIndexOf('\n', prevLineEnd - 1) + 1;
+    const line = text.slice(prevLineStart, prevLineEnd);
+    const trimmed = line.trim();
+
+    if (trimmed === '') {
+      if (blankLineSeen) break;
+      blankLineSeen = true;
+      cursor = prevLineStart;
+      continue;
+    }
+
+    const isComment =
+      trimmed.startsWith('//') ||
+      trimmed.startsWith('/*') ||
+      trimmed.startsWith('*') ||
+      trimmed.endsWith('*/');
+
+    if (!isComment) break;
+
+    collected.unshift(line);
+    cursor = prevLineStart;
+  }
+
+  return stripCommentMarkers(collected.join('\n'));
+};
+
+const findTrailing = (text: string, valueOffset: number, valueLength: number): string => {
+  // Look from end-of-value to end-of-line for a single comment.
+  const lineEnd = text.indexOf('\n', valueOffset + valueLength);
+  const slice = text.slice(valueOffset + valueLength, lineEnd === -1 ? text.length : lineEnd);
+  const m = /,?\s*(\/\/.*|\/\*.*?\*\/)\s*$/.exec(slice);
+  return m ? stripCommentMarkers(m[1]) : '';
+};
+
+export const extractAdjacentComments = (
+  text: string,
+  keyOffset: number,
+  valueOffset: number,
+  valueLength: number,
+): AdjacentComments => ({
+  leading: findLeading(text, keyOffset),
+  trailing: findTrailing(text, valueOffset, valueLength),
+});
diff --git a/admin/src/components/settings/envPill.ts b/admin/src/components/settings/envPill.ts
new file mode 100644
index 00000000000..2e31f9c51aa
--- /dev/null
+++ b/admin/src/components/settings/envPill.ts
@@ -0,0 +1,21 @@
+// admin/src/components/settings/envPill.ts
+//
+// Detect `"${VAR}"` and `"${VAR:default}"` placeholders inside the raw
+// slice of a string node. The slice INCLUDES the surrounding quotes,
+// because jsonc-parser exposes node.offset/length over the whole literal.
+
+export type EnvPlaceholder = {
+  variable: string;
+  defaultValue: string | null;
+};
+
+const RE = /^"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::([^}]*))?\}"$/;
+
+export const matchEnvPlaceholder = (rawSlice: string): EnvPlaceholder | null => {
+  const m = RE.exec(rawSlice);
+  if (!m) return null;
+  return {
+    variable: m[1],
+    defaultValue: m[2] ?? null,
+  };
+};

From 15c461e529794d47abf4d6cb686ae6fa9cae1973 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:02:49 +0100
Subject: [PATCH 07/31] admin(settings): editJsonc wrapper around jsonc-parser
 modify

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/jsoncEdit.ts | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 admin/src/components/settings/jsoncEdit.ts

diff --git a/admin/src/components/settings/jsoncEdit.ts b/admin/src/components/settings/jsoncEdit.ts
new file mode 100644
index 00000000000..f69303accf2
--- /dev/null
+++ b/admin/src/components/settings/jsoncEdit.ts
@@ -0,0 +1,11 @@
+// admin/src/components/settings/jsoncEdit.ts
+import { applyEdits, modify, type JSONPath } from 'jsonc-parser';
+
+const FORMATTING = {
+  formattingOptions: { tabSize: 2, insertSpaces: true, eol: '\n' as const },
+};
+
+export const editJsonc = (text: string, path: JSONPath, value: unknown): string => {
+  const edits = modify(text, path, value, FORMATTING);
+  return edits.length === 0 ? text : applyEdits(text, edits);
+};

From e5ea0c3a46c99174a6980ff58981a1c605c7ca7d Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:04:08 +0100
Subject: [PATCH 08/31] admin(settings): leaf widgets (string, number, bool,
 null, env pill)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../settings/widgets/BooleanToggle.tsx        | 19 +++++++++++
 .../components/settings/widgets/EnvPill.tsx   | 28 ++++++++++++++++
 .../components/settings/widgets/NullChip.tsx  | 10 ++++++
 .../settings/widgets/NumberInput.tsx          | 33 +++++++++++++++++++
 .../settings/widgets/StringInput.tsx          | 18 ++++++++++
 5 files changed, 108 insertions(+)
 create mode 100644 admin/src/components/settings/widgets/BooleanToggle.tsx
 create mode 100644 admin/src/components/settings/widgets/EnvPill.tsx
 create mode 100644 admin/src/components/settings/widgets/NullChip.tsx
 create mode 100644 admin/src/components/settings/widgets/NumberInput.tsx
 create mode 100644 admin/src/components/settings/widgets/StringInput.tsx

diff --git a/admin/src/components/settings/widgets/BooleanToggle.tsx b/admin/src/components/settings/widgets/BooleanToggle.tsx
new file mode 100644
index 00000000000..e5f8a517134
--- /dev/null
+++ b/admin/src/components/settings/widgets/BooleanToggle.tsx
@@ -0,0 +1,19 @@
+import * as Switch from '@radix-ui/react-switch';
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  value: boolean;
+  path: JSONPath;
+  onChange: (next: boolean) => void;
+};
+
+export const BooleanToggle = ({ value, path, onChange }: Props) => (
+  <Switch.Root
+    checked={value}
+    onCheckedChange={onChange}
+    className="settings-widget settings-widget-boolean"
+    data-testid={`field-${path.join('.')}`}
+  >
+    <Switch.Thumb className="settings-widget-boolean-thumb" />
+  </Switch.Root>
+);
diff --git a/admin/src/components/settings/widgets/EnvPill.tsx b/admin/src/components/settings/widgets/EnvPill.tsx
new file mode 100644
index 00000000000..5e56ac165d8
--- /dev/null
+++ b/admin/src/components/settings/widgets/EnvPill.tsx
@@ -0,0 +1,28 @@
+import { useTranslation } from 'react-i18next';
+import type { JSONPath } from 'jsonc-parser';
+import type { EnvPlaceholder } from '../envPill';
+
+type Props = {
+  placeholder: EnvPlaceholder;
+  path: JSONPath;
+};
+
+export const EnvPill = ({ placeholder, path }: Props) => {
+  const { t } = useTranslation();
+  return (
+    <span
+      className="settings-widget settings-widget-env"
+      role="note"
+      title={t('admin_settings.env_pill.tooltip')}
+      data-testid={`env-${path.join('.')}`}
+    >
+      <span className="settings-widget-env-icon" aria-hidden>ⓔ</span>
+      <span className="settings-widget-env-name">{placeholder.variable}</span>
+      {placeholder.defaultValue !== null && (
+        <span className="settings-widget-env-default">
+          {' '}default: <code>{placeholder.defaultValue}</code>
+        </span>
+      )}
+    </span>
+  );
+};
diff --git a/admin/src/components/settings/widgets/NullChip.tsx b/admin/src/components/settings/widgets/NullChip.tsx
new file mode 100644
index 00000000000..9c705fcdd49
--- /dev/null
+++ b/admin/src/components/settings/widgets/NullChip.tsx
@@ -0,0 +1,10 @@
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = { path: JSONPath };
+
+export const NullChip = ({ path }: Props) => (
+  <span
+    className="settings-widget settings-widget-null"
+    data-testid={`field-${path.join('.')}`}
+  >null</span>
+);
diff --git a/admin/src/components/settings/widgets/NumberInput.tsx b/admin/src/components/settings/widgets/NumberInput.tsx
new file mode 100644
index 00000000000..e8ad0e87e0f
--- /dev/null
+++ b/admin/src/components/settings/widgets/NumberInput.tsx
@@ -0,0 +1,33 @@
+import { useState } from 'react';
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  value: number;
+  path: JSONPath;
+  onChange: (next: number) => void;
+};
+
+export const NumberInput = ({ value, path, onChange }: Props) => {
+  const [draft, setDraft] = useState(String(value));
+  const [invalid, setInvalid] = useState(false);
+  return (
+    <input
+      type="text"
+      inputMode="decimal"
+      className={'settings-widget settings-widget-number' + (invalid ? ' invalid' : '')}
+      data-testid={`field-${path.join('.')}`}
+      value={draft}
+      onChange={e => {
+        const next = e.target.value;
+        setDraft(next);
+        const parsed = Number(next);
+        if (next.trim() !== '' && Number.isFinite(parsed)) {
+          setInvalid(false);
+          onChange(parsed);
+        } else {
+          setInvalid(true);
+        }
+      }}
+    />
+  );
+};
diff --git a/admin/src/components/settings/widgets/StringInput.tsx b/admin/src/components/settings/widgets/StringInput.tsx
new file mode 100644
index 00000000000..0ea079d4348
--- /dev/null
+++ b/admin/src/components/settings/widgets/StringInput.tsx
@@ -0,0 +1,18 @@
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  value: string;
+  path: JSONPath;
+  onChange: (next: string) => void;
+};
+
+export const StringInput = ({ value, path, onChange }: Props) => (
+  <input
+    type="text"
+    className="settings-widget settings-widget-string"
+    data-testid={`field-${path.join('.')}`}
+    value={value}
+    spellCheck={false}
+    onChange={e => onChange(e.target.value)}
+  />
+);

From 0345b26caea773c6bc47f786eb805f732a681b09 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:04:51 +0100
Subject: [PATCH 09/31] admin(settings): group widgets, JsoncNode dispatcher,
 CommentLabel

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../src/components/settings/CommentLabel.tsx  |  15 +++
 admin/src/components/settings/JsoncNode.tsx   | 125 ++++++++++++++++++
 .../settings/widgets/ArrayGroup.tsx           |  19 +++
 .../settings/widgets/ObjectGroup.tsx          |  19 +++
 4 files changed, 178 insertions(+)
 create mode 100644 admin/src/components/settings/CommentLabel.tsx
 create mode 100644 admin/src/components/settings/JsoncNode.tsx
 create mode 100644 admin/src/components/settings/widgets/ArrayGroup.tsx
 create mode 100644 admin/src/components/settings/widgets/ObjectGroup.tsx

diff --git a/admin/src/components/settings/CommentLabel.tsx b/admin/src/components/settings/CommentLabel.tsx
new file mode 100644
index 00000000000..3f1e0c102f7
--- /dev/null
+++ b/admin/src/components/settings/CommentLabel.tsx
@@ -0,0 +1,15 @@
+type Props = {
+  leading: string;
+  trailing: string;
+  htmlId: string;
+};
+
+export const CommentLabel = ({ leading, trailing, htmlId }: Props) => {
+  if (!leading && !trailing) return null;
+  return (
+    <div className="settings-comment" id={htmlId}>
+      {leading && <span className="settings-comment-leading">{leading}</span>}
+      {trailing && <span className="settings-comment-trailing"> // {trailing}</span>}
+    </div>
+  );
+};
diff --git a/admin/src/components/settings/JsoncNode.tsx b/admin/src/components/settings/JsoncNode.tsx
new file mode 100644
index 00000000000..73ebaadeeb4
--- /dev/null
+++ b/admin/src/components/settings/JsoncNode.tsx
@@ -0,0 +1,125 @@
+import type { JSONPath, Node } from 'jsonc-parser';
+import { getNodePath } from 'jsonc-parser';
+import { CommentLabel } from './CommentLabel';
+import { extractAdjacentComments } from './comments';
+import { matchEnvPlaceholder } from './envPill';
+import { StringInput } from './widgets/StringInput';
+import { NumberInput } from './widgets/NumberInput';
+import { BooleanToggle } from './widgets/BooleanToggle';
+import { NullChip } from './widgets/NullChip';
+import { EnvPill } from './widgets/EnvPill';
+import { ObjectGroup } from './widgets/ObjectGroup';
+import { ArrayGroup } from './widgets/ArrayGroup';
+
+type Props = {
+  /** The value node (not the property node). */
+  node: Node;
+  /** The property node, when this value is the value-side of `"key": value`. */
+  property?: Node;
+  text: string;
+  onEdit: (path: JSONPath, value: unknown) => void;
+};
+
+export const JsoncNode = ({ node, property, text, onEdit }: Props) => {
+  const path = getNodePath(node);
+
+  // Comment lookup is based on the property node when present (object child),
+  // otherwise the value node directly (array element / root).
+  const anchor = property ?? node;
+  const { leading, trailing } = extractAdjacentComments(
+    text,
+    anchor.offset,
+    node.offset,
+    node.length,
+  );
+  const commentId = `settings-comment-${path.join('.') || 'root'}`;
+
+  const wrap = (label: React.ReactNode, control: React.ReactNode) => (
+    <div className="settings-row" aria-describedby={commentId}>
+      {label && <span className="settings-key">{label}</span>}
+      <span className="settings-value">{control}</span>
+      <CommentLabel leading={leading} trailing={trailing} htmlId={commentId} />
+    </div>
+  );
+
+  // Property name for object children:
+  const keyLabel =
+    property?.type === 'property' && property.children?.[0]?.type === 'string'
+      ? String(property.children[0].value)
+      : null;
+
+  if (node.type === 'object') {
+    return wrap(
+      keyLabel,
+      <ObjectGroup path={path} childCount={node.children?.length ?? 0}>
+        {(node.children ?? []).map((prop, i) => {
+          const valueNode = prop.children?.[1];
+          if (!valueNode) return null;
+          return (
+            <JsoncNode
+              key={i}
+              node={valueNode}
+              property={prop}
+              text={text}
+              onEdit={onEdit}
+            />
+          );
+        })}
+      </ObjectGroup>,
+    );
+  }
+
+  if (node.type === 'array') {
+    return wrap(
+      keyLabel,
+      <ArrayGroup path={path} childCount={node.children?.length ?? 0}>
+        {(node.children ?? []).map((child, i) => (
+          <JsoncNode key={i} node={child} text={text} onEdit={onEdit} />
+        ))}
+      </ArrayGroup>,
+    );
+  }
+
+  if (node.type === 'string') {
+    const raw = text.slice(node.offset, node.offset + node.length);
+    const env = matchEnvPlaceholder(raw);
+    if (env) return wrap(keyLabel, <EnvPill placeholder={env} path={path} />);
+    return wrap(
+      keyLabel,
+      <StringInput
+        value={String(node.value)}
+        path={path}
+        onChange={v => onEdit(path, v)}
+      />,
+    );
+  }
+
+  if (node.type === 'number') {
+    return wrap(
+      keyLabel,
+      <NumberInput
+        value={Number(node.value)}
+        path={path}
+        onChange={v => onEdit(path, v)}
+      />,
+    );
+  }
+
+  if (node.type === 'boolean') {
+    return wrap(
+      keyLabel,
+      <BooleanToggle
+        value={Boolean(node.value)}
+        path={path}
+        onChange={v => onEdit(path, v)}
+      />,
+    );
+  }
+
+  if (node.type === 'null') {
+    return wrap(keyLabel, <NullChip path={path} />);
+  }
+
+  // 'property' nodes are handled by their parent object branch above.
+  return null;
+};
diff --git a/admin/src/components/settings/widgets/ArrayGroup.tsx b/admin/src/components/settings/widgets/ArrayGroup.tsx
new file mode 100644
index 00000000000..4e1bfcac394
--- /dev/null
+++ b/admin/src/components/settings/widgets/ArrayGroup.tsx
@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  path: JSONPath;
+  childCount: number;
+  children: ReactNode;
+};
+
+export const ArrayGroup = ({ path, childCount, children }: Props) => (
+  <details
+    className="settings-group settings-group-array"
+    data-testid={`group-${path.join('.') || 'root'}`}
+    open
+  >
+    <summary>{`[ ${childCount} ${childCount === 1 ? 'item' : 'items'} ]`}</summary>
+    <div className="settings-group-body">{children}</div>
+  </details>
+);
diff --git a/admin/src/components/settings/widgets/ObjectGroup.tsx b/admin/src/components/settings/widgets/ObjectGroup.tsx
new file mode 100644
index 00000000000..4b75b9b661e
--- /dev/null
+++ b/admin/src/components/settings/widgets/ObjectGroup.tsx
@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import type { JSONPath } from 'jsonc-parser';
+
+type Props = {
+  path: JSONPath;
+  childCount: number;
+  children: ReactNode;
+};
+
+export const ObjectGroup = ({ path, childCount, children }: Props) => (
+  <details
+    className="settings-group settings-group-object"
+    data-testid={`group-${path.join('.') || 'root'}`}
+    open
+  >
+    <summary>{`{ ${childCount} ${childCount === 1 ? 'key' : 'keys'} }`}</summary>
+    <div className="settings-group-body">{children}</div>
+  </details>
+);

From 36240f091b49b3cee2c035fa5bc42d1b5dbfe25b Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:06:06 +0100
Subject: [PATCH 10/31] admin(settings): FormView, ParseErrorBanner, ModeToggle

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/FormView.tsx    | 53 +++++++++++++++++++
 admin/src/components/settings/ModeToggle.tsx  | 33 ++++++++++++
 .../components/settings/ParseErrorBanner.tsx  | 16 ++++++
 3 files changed, 102 insertions(+)
 create mode 100644 admin/src/components/settings/FormView.tsx
 create mode 100644 admin/src/components/settings/ModeToggle.tsx
 create mode 100644 admin/src/components/settings/ParseErrorBanner.tsx

diff --git a/admin/src/components/settings/FormView.tsx b/admin/src/components/settings/FormView.tsx
new file mode 100644
index 00000000000..dc5dd48a629
--- /dev/null
+++ b/admin/src/components/settings/FormView.tsx
@@ -0,0 +1,53 @@
+import { parseTree, type JSONPath, type ParseError } from 'jsonc-parser';
+import { useStore } from '../../store/store';
+import { editJsonc } from './jsoncEdit';
+import { JsoncNode } from './JsoncNode';
+import { ParseErrorBanner } from './ParseErrorBanner';
+
+type Props = {
+  onSwitchToRaw: () => void;
+};
+
+const formatErrors = (errors: ParseError[]): string =>
+  errors.length === 0
+    ? ''
+    : errors.map(e => `offset ${e.offset}: ${ParseErrorMessage[e.error] ?? 'parse error'}`).join('\n');
+
+const ParseErrorMessage: Record<number, string> = {
+  1: 'Invalid symbol',
+  2: 'Invalid number format',
+  3: 'Property name expected',
+  4: 'Value expected',
+  5: 'Colon expected',
+  6: 'Comma expected',
+  7: 'Closing brace expected',
+  8: 'Closing bracket expected',
+  9: 'End of file expected',
+  16: 'Unexpected end of comment',
+  17: 'Unexpected end of string',
+  18: 'Unexpected end of number',
+  19: 'Invalid unicode',
+  20: 'Invalid escape character',
+  21: 'Invalid character',
+};
+
+export const FormView = ({ onSwitchToRaw }: Props) => {
+  const text = useStore(s => s.settings) ?? '';
+
+  const errors: ParseError[] = [];
+  const tree = parseTree(text, errors, { allowTrailingComma: true });
+
+  const onEdit = (path: JSONPath, value: unknown) => {
+    useStore.getState().setSettings(editJsonc(text, path, value));
+  };
+
+  if (!tree || errors.length > 0) {
+    return <ParseErrorBanner message={formatErrors(errors)} onSwitchToRaw={onSwitchToRaw} />;
+  }
+
+  return (
+    <div className="settings-form" data-testid="settings-form-view">
+      <JsoncNode node={tree} text={text} onEdit={onEdit} />
+    </div>
+  );
+};
diff --git a/admin/src/components/settings/ModeToggle.tsx b/admin/src/components/settings/ModeToggle.tsx
new file mode 100644
index 00000000000..0e0146ae584
--- /dev/null
+++ b/admin/src/components/settings/ModeToggle.tsx
@@ -0,0 +1,33 @@
+import { Trans } from 'react-i18next';
+
+export type Mode = 'form' | 'raw';
+
+type Props = {
+  mode: Mode;
+  onChange: (mode: Mode) => void;
+};
+
+export const ModeToggle = ({ mode, onChange }: Props) => (
+  <div className="settings-mode-toggle" role="tablist" aria-label="Editor mode">
+    <button
+      type="button"
+      role="tab"
+      aria-selected={mode === 'form'}
+      data-testid="mode-toggle-form"
+      className={mode === 'form' ? 'active' : ''}
+      onClick={() => onChange('form')}
+    >
+      <Trans i18nKey="admin_settings.mode.form" />
+    </button>
+    <button
+      type="button"
+      role="tab"
+      aria-selected={mode === 'raw'}
+      data-testid="mode-toggle-raw"
+      className={mode === 'raw' ? 'active' : ''}
+      onClick={() => onChange('raw')}
+    >
+      <Trans i18nKey="admin_settings.mode.raw" />
+    </button>
+  </div>
+);
diff --git a/admin/src/components/settings/ParseErrorBanner.tsx b/admin/src/components/settings/ParseErrorBanner.tsx
new file mode 100644
index 00000000000..2a63333f80d
--- /dev/null
+++ b/admin/src/components/settings/ParseErrorBanner.tsx
@@ -0,0 +1,16 @@
+import { Trans } from 'react-i18next';
+
+type Props = {
+  message: string;
+  onSwitchToRaw: () => void;
+};
+
+export const ParseErrorBanner = ({ message, onSwitchToRaw }: Props) => (
+  <div className="settings-parse-error" role="alert" data-testid="parse-error-banner">
+    <strong><Trans i18nKey="admin_settings.parse_error.title" /></strong>
+    <pre className="settings-parse-error-detail">{message}</pre>
+    <button type="button" onClick={onSwitchToRaw} data-testid="parse-error-switch-raw">
+      <Trans i18nKey="admin_settings.parse_error.cta" />
+    </button>
+  </div>
+);

From 778754f155c9dcbc18d2961b453d74b13b223a65 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:06:38 +0100
Subject: [PATCH 11/31] admin(settings): toggle FormView and raw textarea from
 SettingsPage

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/pages/SettingsPage.tsx | 68 ++++++++++++++++----------------
 1 file changed, 33 insertions(+), 35 deletions(-)

diff --git a/admin/src/pages/SettingsPage.tsx b/admin/src/pages/SettingsPage.tsx
index 1279c2dd1cb..b187f370cc2 100644
--- a/admin/src/pages/SettingsPage.tsx
+++ b/admin/src/pages/SettingsPage.tsx
@@ -1,18 +1,20 @@
 import React, { useState } from 'react';
-import { useStore } from "../store/store.ts";
-import { isJSONClean, cleanComments } from "../utils/utils.ts";
-import { Trans, useTranslation } from "react-i18next";
-import { IconButton } from "../components/IconButton.tsx";
-import { RotateCw, Save, AlignLeft, ShieldCheck } from "lucide-react";
+import { useStore } from '../store/store';
+import { isJSONClean, cleanComments } from '../utils/utils';
+import { Trans, useTranslation } from 'react-i18next';
+import { IconButton } from '../components/IconButton';
+import { RotateCw, Save, AlignLeft, ShieldCheck } from 'lucide-react';
+import { FormView } from '../components/settings/FormView';
+import { ModeToggle, type Mode } from '../components/settings/ModeToggle';
 
-const TAB_INDENT = "  ";
+const TAB_INDENT = '  ';
 
 export const SettingsPage = () => {
   const { t } = useTranslation();
   const settingsSocket = useStore(state => state.settingsSocket);
-  const settings = useStore(state => state.settings) ?? "";
+  const settings = useStore(state => state.settings) ?? '';
 
-  // Prettify rewrites JSON without comments — gated until we have inline-comment mapping.
+  const [mode, setMode] = useState<Mode>('form');
   const [exposeExperimental] = useState(false);
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
@@ -32,48 +34,47 @@ export const SettingsPage = () => {
   };
 
   const testJSON = () => {
-    if (isJSONClean(settings)) {
-      showToast("admin_settings.toast.validation_ok", true);
-    } else {
-      showToast("admin_settings.toast.validation_failed", false);
-    }
+    if (isJSONClean(settings)) showToast('admin_settings.toast.validation_ok', true);
+    else showToast('admin_settings.toast.validation_failed', false);
   };
 
   const prettifyJSON = () => {
     try {
-      const obj = JSON.parse(cleanComments(settings) ?? "");
-      if (window.confirm(t("admin_settings.prettify_confirm"))) {
+      const obj = JSON.parse(cleanComments(settings) ?? '');
+      if (window.confirm(t('admin_settings.prettify_confirm'))) {
         useStore.getState().setSettings(JSON.stringify(obj, null, 2));
       }
     } catch {
-      showToast("admin_settings.toast.prettify_failed", false);
+      showToast('admin_settings.toast.prettify_failed', false);
     }
   };
 
   const handleSave = () => {
-    if (!isJSONClean(settings)) {
-      showToast("admin_settings.toast.json_invalid", false);
-      return;
-    }
-    if (!settingsSocket?.connected) {
-      showToast("admin_settings.toast.disconnected", false);
-      return;
-    }
+    if (!isJSONClean(settings)) return showToast('admin_settings.toast.json_invalid', false);
+    if (!settingsSocket?.connected) return showToast('admin_settings.toast.disconnected', false);
     settingsSocket.emit('saveSettings', settings);
-    showToast("admin_settings.toast.saved", true);
+    showToast('admin_settings.toast.saved', true);
   };
 
   return (
     <div className="settings-page">
       <h1><Trans i18nKey="admin_settings.current" /></h1>
 
-      <textarea
-        value={settings}
-        className="settings"
-        spellCheck={false}
-        onKeyDown={handleKeyDown}
-        onChange={v => useStore.getState().setSettings(v.target.value)}
-      />
+      <ModeToggle mode={mode} onChange={setMode} />
+
+      {mode === 'form'
+        ? <FormView onSwitchToRaw={() => setMode('raw')} />
+        : (
+          <textarea
+            value={settings}
+            className="settings"
+            data-testid="settings-raw-textarea"
+            spellCheck={false}
+            onKeyDown={handleKeyDown}
+            onChange={v => useStore.getState().setSettings(v.target.value)}
+          />
+        )
+      }
 
       <div className="settings-button-bar">
         <IconButton
@@ -83,7 +84,6 @@ export const SettingsPage = () => {
           title={<Trans i18nKey="admin_settings.current_save.value" />}
           onClick={handleSave}
         />
-
         <IconButton
           className="settingsButton"
           data-testid="test-settings-button"
@@ -91,7 +91,6 @@ export const SettingsPage = () => {
           title={<Trans i18nKey="admin_settings.current_test.value" />}
           onClick={testJSON}
         />
-
         {exposeExperimental && (
           <IconButton
             className="settingsButton"
@@ -101,7 +100,6 @@ export const SettingsPage = () => {
             onClick={prettifyJSON}
           />
         )}
-
         <IconButton
           className="settingsButton"
           data-testid="restart-etherpad-button"

From 313b134c463931900383b82e26c9e5e0de77b60e Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:07:22 +0100
Subject: [PATCH 12/31] admin(settings): styles for tree, widgets, env pill,
 parse error

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/App.css | 122 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)

diff --git a/admin/src/App.css b/admin/src/App.css
index 17403b18e39..6f61abb8603 100644
--- a/admin/src/App.css
+++ b/admin/src/App.css
@@ -32,3 +32,125 @@
   padding-top: 20px;
   border-top: 1px solid #eee;
 }
+
+/* --- mode toggle --- */
+.settings-mode-toggle {
+  display: inline-flex;
+  border: 1px solid #444;
+  border-radius: 6px;
+  overflow: hidden;
+  margin-bottom: 12px;
+}
+.settings-mode-toggle button {
+  padding: 6px 14px;
+  border: 0;
+  background: transparent;
+  color: #d4d4d4;
+  cursor: pointer;
+}
+.settings-mode-toggle button.active {
+  background: #007acc;
+  color: #fff;
+}
+
+/* --- form tree --- */
+.settings-form {
+  font-family: "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
+  font-size: 13px;
+  background: #1e1e1e;
+  color: #d4d4d4;
+  padding: 12px;
+  border: 1px solid #333;
+  border-radius: 4px;
+}
+.settings-row {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 4px 0;
+}
+.settings-key {
+  font-weight: 600;
+  color: #9cdcfe;
+}
+.settings-value {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+.settings-comment {
+  font-style: italic;
+  color: #6a9955;
+  white-space: pre-wrap;
+}
+.settings-comment-trailing {
+  color: #808080;
+  font-style: normal;
+}
+
+/* --- group widgets --- */
+.settings-group > summary {
+  cursor: pointer;
+  color: #c586c0;
+}
+.settings-group-body {
+  padding-left: 16px;
+  border-left: 1px solid #333;
+  margin-left: 4px;
+}
+
+/* --- leaf widgets --- */
+.settings-widget-string,
+.settings-widget-number {
+  background: #2d2d2d;
+  color: #d4d4d4;
+  border: 1px solid #444;
+  border-radius: 3px;
+  padding: 2px 6px;
+  font-family: inherit;
+  font-size: inherit;
+  min-width: 220px;
+}
+.settings-widget-number.invalid {
+  border-color: #ce5050;
+}
+.settings-widget-null {
+  color: #569cd6;
+  font-style: italic;
+}
+.settings-widget-env {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: #2d2d4d;
+  color: #d4d4d4;
+  border: 1px dashed #5577aa;
+  border-radius: 12px;
+  padding: 1px 8px;
+}
+.settings-widget-env code {
+  background: transparent;
+  color: #ce9178;
+}
+
+/* --- parse error --- */
+.settings-parse-error {
+  border: 1px solid #ce5050;
+  background: #3a1f1f;
+  color: #fdd;
+  padding: 12px;
+  border-radius: 4px;
+}
+.settings-parse-error-detail {
+  white-space: pre-wrap;
+  font-family: inherit;
+}
+.settings-parse-error button {
+  margin-top: 8px;
+  background: #ce5050;
+  color: #fff;
+  border: 0;
+  padding: 6px 12px;
+  border-radius: 3px;
+  cursor: pointer;
+}

From 442aab448efc071e2c7c00f77b613b7de8270d51 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:07:33 +0100
Subject: [PATCH 13/31] admin(settings): i18n keys for form mode, parse error,
 env pill

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/locales/en.json | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/locales/en.json b/src/locales/en.json
index 2410a4cc145..fe39e3d1e6a 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -42,6 +42,11 @@
   "admin_settings.toast.validation_failed": "JSON is invalid: please fix syntax errors.",
   "admin_settings.toast.prettify_failed": "Cannot prettify: please fix syntax errors first.",
   "admin_settings.prettify_confirm": "Prettifying will remove all comments. Continue?",
+  "admin_settings.mode.form": "Form",
+  "admin_settings.mode.raw": "Raw",
+  "admin_settings.parse_error.title": "Cannot parse settings.json",
+  "admin_settings.parse_error.cta": "Switch to raw to edit",
+  "admin_settings.env_pill.tooltip": "Environment variable. Edit in raw mode.",
   "admin_settings.page-title": "Settings - Etherpad",
 
   "update.banner.title": "Update available",

From 4d6129100857e26f17ae460c46ba0d79097b80b1 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:23:19 +0100
Subject: [PATCH 14/31] admin(settings): playwright specs for form view, env
 pill, parse error, round-trip

Five new specs verifying: leading comment renders as help text; string
round-trips through save (compact-JSON spacing preserved); boolean toggle
round-trips; env placeholder renders as read-only pill with no input;
broken raw JSON shows parse-error banner with switch-to-raw CTA.

Also fix existing specs that regressed when form mode became the default
(Tasks 1-9): add waitForSelector('[data-testid="settings-form-view"]')
before switching to raw, and fix adminhelper.restartEtherpad to not
wait for the raw textarea which is hidden in form mode.

CSS bugfix in App.css/index.css: .settings-mode-toggle gained
flex-shrink:0 and .settings-page changed from height:100% to
min-height:100% to prevent flex layout from collapsing the mode toggle
to 2px when the settings tree is taller than the viewport.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/App.css                             |   2 +
 admin/src/index.css                           |   2 +-
 .../admin-spec/adminsettings.spec.ts          | 143 +++++++++++++++++-
 src/tests/frontend-new/helper/adminhelper.ts  |   4 +-
 4 files changed, 146 insertions(+), 5 deletions(-)

diff --git a/admin/src/App.css b/admin/src/App.css
index 6f61abb8603..005fbdca9d8 100644
--- a/admin/src/App.css
+++ b/admin/src/App.css
@@ -21,6 +21,7 @@
 
 .settings-button-bar {
   display: flex;
+  flex-shrink: 0;
   gap: 10px;
   margin-top: 15px;
 }
@@ -36,6 +37,7 @@
 /* --- mode toggle --- */
 .settings-mode-toggle {
   display: inline-flex;
+  flex-shrink: 0;
   border: 1px solid #444;
   border-radius: 6px;
   overflow: hidden;
diff --git a/admin/src/index.css b/admin/src/index.css
index 64eae3ccc4f..f33aafb6db8 100644
--- a/admin/src/index.css
+++ b/admin/src/index.css
@@ -294,7 +294,7 @@ td, th {
   display: flex;
   flex-direction: column;
   gap: 20px;
-  height: 100%;
+  min-height: 100%;
 }
 
 .settings {
diff --git a/src/tests/frontend-new/admin-spec/adminsettings.spec.ts b/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
index 75307f28f9f..4ed87bbe228 100644
--- a/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
+++ b/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
@@ -14,6 +14,8 @@ test.describe('admin settings',()=> {
 
   test('Are Settings visible, populated, does save work', async ({page}) => {
     await page.goto('http://localhost:9001/admin/settings');
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
     await page.waitForSelector('.settings');
     const settings =  page.locator('.settings');
     await expect(settings).not.toHaveValue('', {timeout: 30000});
@@ -29,6 +31,8 @@ test.describe('admin settings',()=> {
 
     // Check if the changes were actually saved
     await page.reload()
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
     await page.waitForSelector('.settings');
     await expect(settings).not.toHaveValue('', {timeout: 30000});
 
@@ -43,6 +47,8 @@ test.describe('admin settings',()=> {
     await saveSettings(page)
 
     await page.reload()
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
     await page.waitForSelector('.settings');
     await expect(settings).not.toHaveValue('', {timeout: 30000});
     const oldSettings =  page.locator('.settings');
@@ -53,6 +59,8 @@ test.describe('admin settings',()=> {
 
   test('preserves /* */ comments after save round-trip', async ({page}) => {
     await page.goto('http://localhost:9001/admin/settings');
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
     await page.waitForSelector('.settings');
     const settings = page.locator('.settings');
     await expect(settings).not.toHaveValue('', {timeout: 30000});
@@ -63,6 +71,8 @@ test.describe('admin settings',()=> {
     await saveSettings(page);
 
     await page.reload();
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
     await page.waitForSelector('.settings');
     await expect(settings).not.toHaveValue('', {timeout: 30000});
     expect(await settings.inputValue()).toContain('takeover-pr-comment-marker');
@@ -74,6 +84,8 @@ test.describe('admin settings',()=> {
 
   test('validate button toasts success on valid JSON and failure on invalid', async ({page}) => {
     await page.goto('http://localhost:9001/admin/settings');
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
     await page.waitForSelector('.settings');
     const settings = page.locator('.settings');
     await expect(settings).not.toHaveValue('', {timeout: 30000});
@@ -98,13 +110,142 @@ test.describe('admin settings',()=> {
 
   test('restart works', async function ({page}) {
     await page.goto('http://localhost:9001/admin/settings');
-    await page.waitForSelector('.settings')
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
+    await page.waitForSelector('.settings');
     await restartEtherpad(page)
     // Re-login after restart since session is lost
     await loginToAdmin(page, 'admin', 'changeme1')
     await page.goto('http://localhost:9001/admin/settings');
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
     await page.waitForSelector('.settings')
     const settings =  page.locator('.settings');
     await expect(settings).not.toHaveValue('', {timeout: 30000});
   });
+
+  test('form view renders leading comment as help text for known key', async ({page}) => {
+    await page.goto('http://localhost:9001/admin/settings');
+    // Wait for settings to load (form view renders once socket emits settings).
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    // Inject a comment above "title" in raw mode so form view has something to render.
+    await page.getByTestId('mode-toggle-raw').click();
+    const raw = page.getByTestId('settings-raw-textarea');
+    await expect(raw).toBeVisible({timeout: 10000});
+    const original = await raw.inputValue();
+    // Prepend a block comment so the form view can pick it up as help text.
+    const withComment = original.replace('"title"', '/* The pad title */\n"title"');
+    await raw.fill(withComment);
+    await page.getByTestId('save-settings-button').click();
+    await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+
+    await page.getByTestId('mode-toggle-form').click();
+    await page.waitForSelector('[data-testid="settings-form-view"]');
+    // Assert that the injected comment renders as help text.
+    const firstComment = page.locator('.settings-comment-leading').first();
+    await expect(firstComment).toBeVisible({timeout: 10000});
+    expect((await firstComment.textContent())?.trim().length ?? 0).toBeGreaterThan(0);
+
+    // Restore
+    await page.getByTestId('mode-toggle-raw').click();
+    await raw.fill(original);
+    await page.getByTestId('save-settings-button').click();
+    await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+  });
+
+  test('editing title via form input round-trips through save', async ({page}) => {
+    await page.goto('http://localhost:9001/admin/settings');
+    // Wait for settings to load (form view renders once socket emits settings).
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
+    const raw = page.getByTestId('settings-raw-textarea');
+    await expect(raw).toBeVisible({timeout: 10000});
+    const original = await raw.inputValue();
+
+    await page.getByTestId('mode-toggle-form').click();
+    const titleField = page.getByTestId('field-title');
+    await expect(titleField).toBeVisible({timeout: 10000});
+    await titleField.fill('Etherpad-Form-Edit');
+    await page.getByTestId('save-settings-button').click();
+    await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+
+    await page.reload();
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
+    const after = await page.getByTestId('settings-raw-textarea').inputValue();
+    // jsonc-parser modify() preserves the file's existing spacing style.
+    // The shipped settings.json is compact (no spaces around colons).
+    expect(after).toMatch(/"title"\s*:\s*"Etherpad-Form-Edit"/);
+    // Other keys must still be present (file structure preserved).
+    expect(after).toContain('"requireAuthentication"');
+
+    // Restore
+    await page.getByTestId('settings-raw-textarea').fill(original);
+    await page.getByTestId('save-settings-button').click();
+    await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+  });
+
+  test('boolean toggle round-trips through save', async ({page}) => {
+    await page.goto('http://localhost:9001/admin/settings');
+    // Wait for settings to load (form view renders once socket emits settings).
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
+    const original = await page.getByTestId('settings-raw-textarea').inputValue();
+
+    await page.getByTestId('mode-toggle-form').click();
+    const toggle = page.getByTestId('field-requireAuthentication');
+    await expect(toggle).toBeVisible({timeout: 10000});
+    const before = await toggle.getAttribute('aria-checked');
+    await toggle.click();
+    await page.getByTestId('save-settings-button').click();
+    await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+
+    await page.reload();
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    const toggleAfter = page.getByTestId('field-requireAuthentication');
+    await expect(toggleAfter).toBeVisible({timeout: 10000});
+    const after = await toggleAfter.getAttribute('aria-checked');
+    expect(after).not.toEqual(before);
+
+    // Restore
+    await page.getByTestId('mode-toggle-raw').click();
+    await page.getByTestId('settings-raw-textarea').fill(original);
+    await page.getByTestId('save-settings-button').click();
+    await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+  });
+
+  test('env placeholder renders as read-only pill (no input)', async ({page}) => {
+    await page.goto('http://localhost:9001/admin/settings');
+    // Form is the default; wait for settings to load before interacting.
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    // settings.json ships "${SSO_ISSUER:http://localhost:9001}" on sso.issuer.
+    // Locate the sso group, open it, then find the env pill.
+    const pill = page.getByTestId('env-sso.issuer').first();
+    await expect(pill).toBeVisible({timeout: 10000});
+    // No <input> exists for that path
+    await expect(page.getByTestId('field-sso.issuer')).toHaveCount(0);
+  });
+
+  test('toggling form on broken raw JSON shows parse error banner', async ({page}) => {
+    await page.goto('http://localhost:9001/admin/settings');
+    // Wait for settings to load (form view renders once socket emits settings).
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    await page.getByTestId('mode-toggle-raw').click();
+    const raw = page.getByTestId('settings-raw-textarea');
+    await expect(raw).toBeVisible({timeout: 10000});
+    const original = await raw.inputValue();
+
+    await raw.fill('{ "broken":');
+    await page.getByTestId('mode-toggle-form').click();
+    await expect(page.getByTestId('parse-error-banner')).toBeVisible();
+
+    // CTA returns to raw view
+    await page.getByTestId('parse-error-switch-raw').click();
+    await expect(raw).toBeVisible();
+
+    // Restore
+    await raw.fill(original);
+    await page.getByTestId('save-settings-button').click();
+    await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
+  });
 })
diff --git a/src/tests/frontend-new/helper/adminhelper.ts b/src/tests/frontend-new/helper/adminhelper.ts
index 07e6e58804d..fed31a0d162 100644
--- a/src/tests/frontend-new/helper/adminhelper.ts
+++ b/src/tests/frontend-new/helper/adminhelper.ts
@@ -17,9 +17,7 @@ export const saveSettings = async (page: Page) => {
 }
 
 export const restartEtherpad = async (page: Page) => {
-  const restartButton = page.getByTestId('restart-etherpad-button')
-  const settings =  page.locator('.settings');
-  await expect(settings).not.toHaveValue('', {timeout: 30000});
+  const restartButton = page.getByTestId('restart-etherpad-button');
   await expect(restartButton).toBeVisible({timeout: 10000})
   await restartButton.click()
   // Wait for the server to come back up by polling.

From 74b312c00ca1273a33d505b4c92d9e4b0c928958 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:30:56 +0100
Subject: [PATCH 15/31] admin(settings): don't read trailing comments past
 end-of-line

When settings.json is on a single line (the shipped/minified form),
findTrailing was matching `//` inside `https://etherpad.org` (in
defaultPadText) and rendering everything after it as the trailing
comment for whichever key came before. Bail out when the value has
no newline after it, since trailing comments can only exist on the
same line by definition.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/comments.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/admin/src/components/settings/comments.ts b/admin/src/components/settings/comments.ts
index 89e410d6335..7c24b77d27f 100644
--- a/admin/src/components/settings/comments.ts
+++ b/admin/src/components/settings/comments.ts
@@ -67,9 +67,13 @@ const findLeading = (text: string, keyOffset: number): string => {
 };
 
 const findTrailing = (text: string, valueOffset: number, valueLength: number): string => {
-  // Look from end-of-value to end-of-line for a single comment.
+  // Trailing comments only exist on the same line as the value. If there's
+  // no newline after the value the file has no line structure (e.g. minified
+  // settings.json) and `//` inside any later string literal would otherwise
+  // be matched as a comment.
   const lineEnd = text.indexOf('\n', valueOffset + valueLength);
-  const slice = text.slice(valueOffset + valueLength, lineEnd === -1 ? text.length : lineEnd);
+  if (lineEnd === -1) return '';
+  const slice = text.slice(valueOffset + valueLength, lineEnd);
   const m = /,?\s*(\/\/.*|\/\*.*?\*\/)\s*$/.exec(slice);
   return m ? stripCommentMarkers(m[1]) : '';
 };

From 0e9816135880c92f84d9f632cd18dc8eaaa68021 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:37:37 +0100
Subject: [PATCH 16/31] admin(settings): schema-driven help text from
 settings.json.template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The live settings.json is per-developer and often lacks comments (e.g.
when it was minified by an earlier admin save or test run). Without a
fallback, every key in form view shows up bare. settings.json.template
in the repo root is the authoritative source of per-key documentation,
so we read it once at admin-build time, build a path → comment map,
and use it as the fallback when the live file has no comment of its
own for that path.

Live-file comments still take precedence so admins who add their own
notes see them as written. Trailing comments still come from the live
file only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/JsoncNode.tsx   |  7 ++-
 .../components/settings/templateComments.ts   | 46 +++++++++++++++++++
 admin/vite.config.ts                          |  4 ++
 3 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 admin/src/components/settings/templateComments.ts

diff --git a/admin/src/components/settings/JsoncNode.tsx b/admin/src/components/settings/JsoncNode.tsx
index 73ebaadeeb4..c3a44deacef 100644
--- a/admin/src/components/settings/JsoncNode.tsx
+++ b/admin/src/components/settings/JsoncNode.tsx
@@ -3,6 +3,7 @@ import { getNodePath } from 'jsonc-parser';
 import { CommentLabel } from './CommentLabel';
 import { extractAdjacentComments } from './comments';
 import { matchEnvPlaceholder } from './envPill';
+import { lookupTemplateComment } from './templateComments';
 import { StringInput } from './widgets/StringInput';
 import { NumberInput } from './widgets/NumberInput';
 import { BooleanToggle } from './widgets/BooleanToggle';
@@ -26,12 +27,16 @@ export const JsoncNode = ({ node, property, text, onEdit }: Props) => {
   // Comment lookup is based on the property node when present (object child),
   // otherwise the value node directly (array element / root).
   const anchor = property ?? node;
-  const { leading, trailing } = extractAdjacentComments(
+  const fileComments = extractAdjacentComments(
     text,
     anchor.offset,
     node.offset,
     node.length,
   );
+  // Fall back to settings.json.template's documentation when the live file
+  // has no comment of its own for this path.
+  const leading = fileComments.leading || (property ? lookupTemplateComment(path) ?? '' : '');
+  const trailing = fileComments.trailing;
   const commentId = `settings-comment-${path.join('.') || 'root'}`;
 
   const wrap = (label: React.ReactNode, control: React.ReactNode) => (
diff --git a/admin/src/components/settings/templateComments.ts b/admin/src/components/settings/templateComments.ts
new file mode 100644
index 00000000000..843e883146f
--- /dev/null
+++ b/admin/src/components/settings/templateComments.ts
@@ -0,0 +1,46 @@
+// Build a fallback path → comment map from `settings.json.template`. The live
+// settings.json is per-developer and often lacks comments; the template is the
+// authoritative source of per-key documentation.
+
+import { parseTree, type JSONPath, type Node } from 'jsonc-parser';
+// `?raw` is a Vite import suffix — returns the file content as a string.
+// vite.config.ts must allow reading from the repo root for this to work.
+import templateText from '../../../../settings.json.template?raw';
+import { extractAdjacentComments } from './comments';
+
+const pathKey = (path: JSONPath): string => path.map(String).join('.');
+
+const buildMap = (text: string): Map<string, string> => {
+  const map = new Map<string, string>();
+  const tree = parseTree(text, [], { allowTrailingComma: true });
+  if (!tree) return map;
+
+  const walk = (node: Node, path: JSONPath) => {
+    if (node.type === 'object') {
+      for (const prop of node.children ?? []) {
+        if (prop.type !== 'property' || !prop.children || prop.children.length < 2) continue;
+        const keyNode = prop.children[0];
+        const valueNode = prop.children[1];
+        if (keyNode.type !== 'string') continue;
+        const childPath = [...path, String(keyNode.value)];
+        const { leading, trailing } = extractAdjacentComments(
+          text, prop.offset, valueNode.offset, valueNode.length,
+        );
+        if (leading || trailing) {
+          map.set(pathKey(childPath), [leading, trailing].filter(Boolean).join(' — '));
+        }
+        walk(valueNode, childPath);
+      }
+    } else if (node.type === 'array') {
+      (node.children ?? []).forEach((child, i) => walk(child, [...path, i]));
+    }
+  };
+
+  walk(tree, []);
+  return map;
+};
+
+const templateMap = buildMap(templateText);
+
+export const lookupTemplateComment = (path: JSONPath): string | null =>
+  templateMap.get(pathKey(path)) ?? null;
diff --git a/admin/vite.config.ts b/admin/vite.config.ts
index 70ec5182f0f..fa7e0167ca4 100644
--- a/admin/vite.config.ts
+++ b/admin/vite.config.ts
@@ -16,6 +16,10 @@ export default defineConfig({
     emptyOutDir: true,
   },
   server: {
+    fs: {
+      // Allow importing `settings.json.template` from the repo root.
+      allow: ['..'],
+    },
     proxy: {
       '/socket.io/*': {
         target: 'http://localhost:9001',

From 586d20cf6e42cb0364417dce75422b84a80b1ae5 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:45:35 +0100
Subject: [PATCH 17/31] admin(settings): redesign form view as light two-column
 form
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the dark IDE-tree look with a light, sectioned form that
matches the rest of /admin. Top-level primitive keys collect into a
'General' section; top-level objects/arrays each become their own
labelled section with the first sentence of the doc comment as the
heading and the rest as descriptive copy. Each leaf is a label/control
row with help text below. Switch labels to template-derived first-
sentence + humanized-key fallback. Remove the unused
CommentLabel/ObjectGroup/ArrayGroup components — sections and grid
layout replace them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/App.css                             | 237 +++++++++++++-----
 .../src/components/settings/CommentLabel.tsx  |  15 --
 admin/src/components/settings/FormView.tsx    |  81 +++++-
 admin/src/components/settings/JsoncNode.tsx   | 175 +++++++------
 admin/src/components/settings/labels.ts       |  46 ++++
 .../settings/widgets/ArrayGroup.tsx           |  19 --
 .../settings/widgets/BooleanToggle.tsx        |   1 +
 .../settings/widgets/NumberInput.tsx          |   1 +
 .../settings/widgets/ObjectGroup.tsx          |  19 --
 .../settings/widgets/StringInput.tsx          |   1 +
 10 files changed, 392 insertions(+), 203 deletions(-)
 delete mode 100644 admin/src/components/settings/CommentLabel.tsx
 create mode 100644 admin/src/components/settings/labels.ts
 delete mode 100644 admin/src/components/settings/widgets/ArrayGroup.tsx
 delete mode 100644 admin/src/components/settings/widgets/ObjectGroup.tsx

diff --git a/admin/src/App.css b/admin/src/App.css
index 005fbdca9d8..97e61465ec2 100644
--- a/admin/src/App.css
+++ b/admin/src/App.css
@@ -1,3 +1,4 @@
+/* Raw textarea (kept dark to signal "this is code") */
 .settings {
   font-family: "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
   font-size: 14px;
@@ -13,7 +14,6 @@
   border: 1px solid #333;
   resize: vertical;
 }
-
 .settings:focus {
   outline: 2px solid #007acc;
   outline-offset: -1px;
@@ -31,128 +31,245 @@
   gap: 20px;
   margin-top: 20px;
   padding-top: 20px;
-  border-top: 1px solid #eee;
+  border-top: 1px solid #ddd;
 }
 
 /* --- mode toggle --- */
 .settings-mode-toggle {
   display: inline-flex;
   flex-shrink: 0;
-  border: 1px solid #444;
+  border: 1px solid #ccc;
   border-radius: 6px;
   overflow: hidden;
-  margin-bottom: 12px;
+  margin-bottom: 16px;
+  background: #fff;
 }
 .settings-mode-toggle button {
   padding: 6px 14px;
   border: 0;
   background: transparent;
-  color: #d4d4d4;
+  color: #555;
+  font: inherit;
   cursor: pointer;
 }
 .settings-mode-toggle button.active {
-  background: #007acc;
+  background: var(--etherpad-color, #0f775b);
   color: #fff;
 }
 
-/* --- form tree --- */
+/* --- form (light, two-column) --- */
 .settings-form {
-  font-family: "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
+  font-family: inherit;
+  font-size: 14px;
+  color: #333;
+}
+
+.settings-section {
+  background: #fff;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  margin-bottom: 18px;
+  overflow: hidden;
+}
+.settings-section-header {
+  padding: 14px 18px;
+  border-bottom: 1px solid #eee;
+  background: #fafafa;
+}
+.settings-section-header h2 {
+  margin: 0;
+  font-size: 15px;
+  font-weight: 600;
+  color: #222;
+  letter-spacing: 0.01em;
+  text-transform: uppercase;
+}
+.settings-section-header p {
+  margin: 4px 0 0;
   font-size: 13px;
-  background: #1e1e1e;
-  color: #d4d4d4;
-  padding: 12px;
-  border: 1px solid #333;
-  border-radius: 4px;
+  color: #666;
+  white-space: pre-wrap;
 }
-.settings-row {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
+.settings-section-body {
   padding: 4px 0;
 }
-.settings-key {
+
+/* Two-column row: label | control, with help below spanning column 2.
+ * Single-column on narrow widths. */
+.settings-row {
+  display: grid;
+  grid-template-columns: minmax(180px, 220px) minmax(0, 1fr);
+  gap: 6px 18px;
+  padding: 10px 18px;
+  align-items: center;
+  border-top: 1px solid #f4f4f4;
+}
+.settings-row:first-child {
+  border-top: 0;
+}
+.settings-row-label {
   font-weight: 600;
-  color: #9cdcfe;
+  color: #333;
+  word-break: break-word;
 }
-.settings-value {
-  display: inline-flex;
-  align-items: center;
-  gap: 8px;
+.settings-row-control {
+  min-width: 0;
 }
-.settings-comment {
-  font-style: italic;
-  color: #6a9955;
+.settings-row-help {
+  grid-column: 2;
+  margin: 2px 0 0;
+  font-size: 12.5px;
+  color: #666;
   white-space: pre-wrap;
+  line-height: 1.4;
 }
-.settings-comment-trailing {
-  color: #808080;
-  font-style: normal;
+
+@media (max-width: 600px) {
+  .settings-row {
+    grid-template-columns: 1fr;
+  }
+  .settings-row-help {
+    grid-column: 1;
+  }
 }
 
-/* --- group widgets --- */
-.settings-group > summary {
-  cursor: pointer;
-  color: #c586c0;
+/* --- nested subsections (objects/arrays inside a section) --- */
+.settings-subsection {
+  grid-column: 1 / -1;
+  margin: 8px 18px;
+  border-left: 3px solid #e2e2e2;
+  padding-left: 14px;
+}
+.settings-subsection-header {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 8px 0;
+}
+.settings-subsection-title {
+  font-weight: 600;
+  color: #444;
+  font-size: 13.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.01em;
+}
+.settings-subsection-help {
+  color: #777;
+  font-size: 12.5px;
+  white-space: pre-wrap;
 }
-.settings-group-body {
-  padding-left: 16px;
-  border-left: 1px solid #333;
-  margin-left: 4px;
+.settings-subsection-body .settings-row {
+  padding-left: 0;
+  padding-right: 0;
 }
 
-/* --- leaf widgets --- */
+/* --- leaf widgets (light) --- */
 .settings-widget-string,
 .settings-widget-number {
-  background: #2d2d2d;
-  color: #d4d4d4;
-  border: 1px solid #444;
-  border-radius: 3px;
-  padding: 2px 6px;
+  width: 100%;
+  background: #fff;
+  color: #222;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  padding: 6px 10px;
   font-family: inherit;
   font-size: inherit;
-  min-width: 220px;
+}
+.settings-widget-string:focus,
+.settings-widget-number:focus {
+  outline: none;
+  border-color: var(--etherpad-color, #0f775b);
+  box-shadow: 0 0 0 3px rgba(15, 119, 91, 0.15);
 }
 .settings-widget-number.invalid {
   border-color: #ce5050;
 }
 .settings-widget-null {
-  color: #569cd6;
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 10px;
+  background: #f0f0f0;
+  color: #888;
   font-style: italic;
+  font-size: 12.5px;
 }
 .settings-widget-env {
   display: inline-flex;
   align-items: center;
   gap: 6px;
-  background: #2d2d4d;
-  color: #d4d4d4;
-  border: 1px dashed #5577aa;
+  background: #f4f8ff;
+  color: #335;
+  border: 1px dashed #88a;
   border-radius: 12px;
-  padding: 1px 8px;
+  padding: 2px 10px;
+  font-size: 13px;
+  cursor: help;
+}
+.settings-widget-env-icon {
+  font-style: normal;
+  color: #557;
+}
+.settings-widget-env-name {
+  font-family: "Fira Code", monospace;
+  font-weight: 600;
 }
 .settings-widget-env code {
   background: transparent;
-  color: #ce9178;
+  color: #804;
+  font-family: "Fira Code", monospace;
+}
+
+/* Radix switch (boolean) */
+.settings-widget-boolean {
+  appearance: none;
+  width: 36px;
+  height: 20px;
+  border-radius: 999px;
+  background: #ccc;
+  border: 0;
+  position: relative;
+  cursor: pointer;
+  transition: background 120ms ease;
+  padding: 0;
+}
+.settings-widget-boolean[data-state="checked"] {
+  background: var(--etherpad-color, #0f775b);
+}
+.settings-widget-boolean-thumb {
+  display: block;
+  width: 16px;
+  height: 16px;
+  background: #fff;
+  border-radius: 50%;
+  transform: translateX(2px);
+  transition: transform 120ms ease;
+  box-shadow: 0 1px 2px rgba(0,0,0,0.2);
+}
+.settings-widget-boolean[data-state="checked"] .settings-widget-boolean-thumb {
+  transform: translateX(18px);
 }
 
 /* --- parse error --- */
 .settings-parse-error {
-  border: 1px solid #ce5050;
-  background: #3a1f1f;
-  color: #fdd;
-  padding: 12px;
-  border-radius: 4px;
+  border: 1px solid #d99;
+  background: #fff5f5;
+  color: #842;
+  padding: 14px 18px;
+  border-radius: 6px;
 }
 .settings-parse-error-detail {
+  margin: 8px 0;
   white-space: pre-wrap;
-  font-family: inherit;
+  font-family: "Fira Code", monospace;
+  font-size: 12.5px;
 }
 .settings-parse-error button {
-  margin-top: 8px;
-  background: #ce5050;
+  margin-top: 4px;
+  background: var(--etherpad-color, #0f775b);
   color: #fff;
   border: 0;
-  padding: 6px 12px;
-  border-radius: 3px;
+  padding: 6px 14px;
+  border-radius: 4px;
   cursor: pointer;
+  font: inherit;
 }
diff --git a/admin/src/components/settings/CommentLabel.tsx b/admin/src/components/settings/CommentLabel.tsx
deleted file mode 100644
index 3f1e0c102f7..00000000000
--- a/admin/src/components/settings/CommentLabel.tsx
+++ /dev/null
@@ -1,15 +0,0 @@
-type Props = {
-  leading: string;
-  trailing: string;
-  htmlId: string;
-};
-
-export const CommentLabel = ({ leading, trailing, htmlId }: Props) => {
-  if (!leading && !trailing) return null;
-  return (
-    <div className="settings-comment" id={htmlId}>
-      {leading && <span className="settings-comment-leading">{leading}</span>}
-      {trailing && <span className="settings-comment-trailing"> // {trailing}</span>}
-    </div>
-  );
-};
diff --git a/admin/src/components/settings/FormView.tsx b/admin/src/components/settings/FormView.tsx
index dc5dd48a629..afd4eb5baa9 100644
--- a/admin/src/components/settings/FormView.tsx
+++ b/admin/src/components/settings/FormView.tsx
@@ -1,18 +1,16 @@
-import { parseTree, type JSONPath, type ParseError } from 'jsonc-parser';
+import { parseTree, type JSONPath, type Node, type ParseError } from 'jsonc-parser';
 import { useStore } from '../../store/store';
 import { editJsonc } from './jsoncEdit';
 import { JsoncNode } from './JsoncNode';
 import { ParseErrorBanner } from './ParseErrorBanner';
+import { extractAdjacentComments } from './comments';
+import { lookupTemplateComment } from './templateComments';
+import { labelAndHelp } from './labels';
 
 type Props = {
   onSwitchToRaw: () => void;
 };
 
-const formatErrors = (errors: ParseError[]): string =>
-  errors.length === 0
-    ? ''
-    : errors.map(e => `offset ${e.offset}: ${ParseErrorMessage[e.error] ?? 'parse error'}`).join('\n');
-
 const ParseErrorMessage: Record<number, string> = {
   1: 'Invalid symbol',
   2: 'Invalid number format',
@@ -31,6 +29,37 @@ const ParseErrorMessage: Record<number, string> = {
   21: 'Invalid character',
 };
 
+const formatErrors = (errors: ParseError[]): string =>
+  errors.length === 0
+    ? ''
+    : errors.map(e => `offset ${e.offset}: ${ParseErrorMessage[e.error] ?? 'parse error'}`).join('\n');
+
+const Section = ({ title, description, children }: {
+  title: string;
+  description?: string;
+  children: React.ReactNode;
+}) => (
+  <section className="settings-section">
+    <header className="settings-section-header">
+      <h2>{title}</h2>
+      {description && <p>{description}</p>}
+    </header>
+    <div className="settings-section-body">{children}</div>
+  </section>
+);
+
+const propertyKey = (prop: Node): string =>
+  prop.type === 'property' && prop.children?.[0]?.type === 'string'
+    ? String(prop.children[0].value)
+    : '';
+
+const propertyComment = (prop: Node, text: string, key: string): string | null => {
+  const valueNode = prop.children?.[1];
+  if (!valueNode) return null;
+  const live = extractAdjacentComments(text, prop.offset, valueNode.offset, valueNode.length);
+  return live.leading || lookupTemplateComment([key]);
+};
+
 export const FormView = ({ onSwitchToRaw }: Props) => {
   const text = useStore(s => s.settings) ?? '';
 
@@ -41,13 +70,49 @@ export const FormView = ({ onSwitchToRaw }: Props) => {
     useStore.getState().setSettings(editJsonc(text, path, value));
   };
 
-  if (!tree || errors.length > 0) {
+  if (!tree || errors.length > 0 || tree.type !== 'object') {
     return <ParseErrorBanner message={formatErrors(errors)} onSwitchToRaw={onSwitchToRaw} />;
   }
 
+  const generalProps: Node[] = [];
+  const sectionProps: Node[] = [];
+  for (const prop of tree.children ?? []) {
+    if (prop.type !== 'property' || !prop.children?.[1]) continue;
+    const valueType = prop.children[1].type;
+    if (valueType === 'object' || valueType === 'array') sectionProps.push(prop);
+    else generalProps.push(prop);
+  }
+
   return (
     <div className="settings-form" data-testid="settings-form-view">
-      <JsoncNode node={tree} text={text} onEdit={onEdit} />
+      {generalProps.length > 0 && (
+        <Section title="General">
+          {generalProps.map((prop, i) => (
+            <JsoncNode
+              key={i}
+              node={prop.children![1]}
+              property={prop}
+              text={text}
+              onEdit={onEdit}
+            />
+          ))}
+        </Section>
+      )}
+      {sectionProps.map((prop, i) => {
+        const key = propertyKey(prop);
+        const { label, help } = labelAndHelp(propertyComment(prop, text, key), key);
+        return (
+          <Section key={i} title={label} description={help}>
+            <JsoncNode
+              node={prop.children![1]}
+              property={prop}
+              text={text}
+              onEdit={onEdit}
+              suppressOwnHeader
+            />
+          </Section>
+        );
+      })}
     </div>
   );
 };
diff --git a/admin/src/components/settings/JsoncNode.tsx b/admin/src/components/settings/JsoncNode.tsx
index c3a44deacef..224c1544aec 100644
--- a/admin/src/components/settings/JsoncNode.tsx
+++ b/admin/src/components/settings/JsoncNode.tsx
@@ -1,16 +1,14 @@
 import type { JSONPath, Node } from 'jsonc-parser';
 import { getNodePath } from 'jsonc-parser';
-import { CommentLabel } from './CommentLabel';
 import { extractAdjacentComments } from './comments';
 import { matchEnvPlaceholder } from './envPill';
 import { lookupTemplateComment } from './templateComments';
+import { labelAndHelp } from './labels';
 import { StringInput } from './widgets/StringInput';
 import { NumberInput } from './widgets/NumberInput';
 import { BooleanToggle } from './widgets/BooleanToggle';
 import { NullChip } from './widgets/NullChip';
 import { EnvPill } from './widgets/EnvPill';
-import { ObjectGroup } from './widgets/ObjectGroup';
-import { ArrayGroup } from './widgets/ArrayGroup';
 
 type Props = {
   /** The value node (not the property node). */
@@ -19,112 +17,125 @@ type Props = {
   property?: Node;
   text: string;
   onEdit: (path: JSONPath, value: unknown) => void;
+  /**
+   * When true, this group's own label/header is suppressed because a
+   * containing Section already rendered it. The group's children still
+   * render. Used for top-level object/array sections in FormView.
+   */
+  suppressOwnHeader?: boolean;
 };
 
-export const JsoncNode = ({ node, property, text, onEdit }: Props) => {
-  const path = getNodePath(node);
-
-  // Comment lookup is based on the property node when present (object child),
-  // otherwise the value node directly (array element / root).
-  const anchor = property ?? node;
-  const fileComments = extractAdjacentComments(
-    text,
-    anchor.offset,
-    node.offset,
-    node.length,
-  );
-  // Fall back to settings.json.template's documentation when the live file
-  // has no comment of its own for this path.
-  const leading = fileComments.leading || (property ? lookupTemplateComment(path) ?? '' : '');
-  const trailing = fileComments.trailing;
-  const commentId = `settings-comment-${path.join('.') || 'root'}`;
-
-  const wrap = (label: React.ReactNode, control: React.ReactNode) => (
-    <div className="settings-row" aria-describedby={commentId}>
-      {label && <span className="settings-key">{label}</span>}
-      <span className="settings-value">{control}</span>
-      <CommentLabel leading={leading} trailing={trailing} htmlId={commentId} />
-    </div>
-  );
-
-  // Property name for object children:
-  const keyLabel =
-    property?.type === 'property' && property.children?.[0]?.type === 'string'
-      ? String(property.children[0].value)
-      : null;
-
-  if (node.type === 'object') {
-    return wrap(
-      keyLabel,
-      <ObjectGroup path={path} childCount={node.children?.length ?? 0}>
-        {(node.children ?? []).map((prop, i) => {
-          const valueNode = prop.children?.[1];
-          if (!valueNode) return null;
-          return (
-            <JsoncNode
-              key={i}
-              node={valueNode}
-              property={prop}
-              text={text}
-              onEdit={onEdit}
-            />
-          );
-        })}
-      </ObjectGroup>,
-    );
-  }
-
-  if (node.type === 'array') {
-    return wrap(
-      keyLabel,
-      <ArrayGroup path={path} childCount={node.children?.length ?? 0}>
-        {(node.children ?? []).map((child, i) => (
-          <JsoncNode key={i} node={child} text={text} onEdit={onEdit} />
-        ))}
-      </ArrayGroup>,
-    );
-  }
+const propertyKey = (property: Node | undefined): string => {
+  if (!property || property.type !== 'property') return '';
+  const k = property.children?.[0];
+  return k?.type === 'string' ? String(k.value) : '';
+};
 
+const renderLeaf = (
+  node: Node,
+  path: JSONPath,
+  text: string,
+  onEdit: (path: JSONPath, value: unknown) => void,
+) => {
   if (node.type === 'string') {
     const raw = text.slice(node.offset, node.offset + node.length);
     const env = matchEnvPlaceholder(raw);
-    if (env) return wrap(keyLabel, <EnvPill placeholder={env} path={path} />);
-    return wrap(
-      keyLabel,
+    if (env) return <EnvPill placeholder={env} path={path} />;
+    return (
       <StringInput
         value={String(node.value)}
         path={path}
         onChange={v => onEdit(path, v)}
-      />,
+      />
     );
   }
-
   if (node.type === 'number') {
-    return wrap(
-      keyLabel,
+    return (
       <NumberInput
         value={Number(node.value)}
         path={path}
         onChange={v => onEdit(path, v)}
-      />,
+      />
     );
   }
-
   if (node.type === 'boolean') {
-    return wrap(
-      keyLabel,
+    return (
       <BooleanToggle
         value={Boolean(node.value)}
         path={path}
         onChange={v => onEdit(path, v)}
-      />,
+      />
     );
   }
-
   if (node.type === 'null') {
-    return wrap(keyLabel, <NullChip path={path} />);
+    return <NullChip path={path} />;
   }
-
-  // 'property' nodes are handled by their parent object branch above.
   return null;
 };
+
+export const JsoncNode = ({ node, property, text, onEdit, suppressOwnHeader }: Props) => {
+  const path = getNodePath(node);
+  const key = propertyKey(property);
+
+  const anchor = property ?? node;
+  const fileComments = extractAdjacentComments(text, anchor.offset, node.offset, node.length);
+  const comment = fileComments.leading || (property ? lookupTemplateComment(path) : null) || '';
+  const { label, help } = labelAndHelp(comment, key);
+
+  const rowId = `settings-row-${path.join('.') || 'root'}`;
+  const helpId = help ? `${rowId}-help` : undefined;
+
+  // ---- Object / array groups ----
+  if (node.type === 'object' || node.type === 'array') {
+    const children = (node.children ?? []).map((child, i) => {
+      // For object: child is a property node, drill into its value node.
+      // For array: child is a value node directly.
+      if (node.type === 'object') {
+        const valueNode = child.children?.[1];
+        if (!valueNode) return null;
+        return (
+          <JsoncNode
+            key={i}
+            node={valueNode}
+            property={child}
+            text={text}
+            onEdit={onEdit}
+          />
+        );
+      }
+      return <JsoncNode key={i} node={child} text={text} onEdit={onEdit} />;
+    });
+
+    if (suppressOwnHeader || !property) {
+      // Render children flat — the containing Section provides the label.
+      return <>{children}</>;
+    }
+
+    // Nested group within a section: render as a sub-section with its own
+    // heading, indented under its parent.
+    return (
+      <div className="settings-subsection" data-testid={`group-${path.join('.')}`}>
+        <div className="settings-subsection-header">
+          <span className="settings-subsection-title">{label}</span>
+          {help && <span className="settings-subsection-help">{help}</span>}
+        </div>
+        <div className="settings-subsection-body">{children}</div>
+      </div>
+    );
+  }
+
+  // ---- Leaf row ----
+  return (
+    <div className="settings-row" id={rowId}>
+      <label className="settings-row-label" htmlFor={`field-${path.join('.')}`}>
+        {label}
+      </label>
+      <div className="settings-row-control">
+        {renderLeaf(node, path, text, onEdit)}
+      </div>
+      {help && (
+        <p className="settings-row-help" id={helpId}>{help}</p>
+      )}
+    </div>
+  );
+};
diff --git a/admin/src/components/settings/labels.ts b/admin/src/components/settings/labels.ts
new file mode 100644
index 00000000000..afdae3de11f
--- /dev/null
+++ b/admin/src/components/settings/labels.ts
@@ -0,0 +1,46 @@
+// Pretty-label derivation. The first sentence of a key's documentation
+// comment is its label; the rest stays in the help-text slot. When no
+// comment exists, fall back to a humanized key name (camelCase → "Camel
+// case").
+
+const SENTENCE_END = /[.!?](\s|$)/;
+
+const humanize = (key: string): string => {
+  if (!key) return key;
+  // Split camelCase / PascalCase / snake_case / kebab-case
+  const words = key
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .trim()
+    .split(/\s+/);
+  if (words.length === 0) return key;
+  return words[0].charAt(0).toUpperCase() + words[0].slice(1) +
+    (words.length > 1 ? ' ' + words.slice(1).join(' ') : '');
+};
+
+const splitFirstSentence = (text: string): { head: string; rest: string } => {
+  const trimmed = text.trim();
+  const m = SENTENCE_END.exec(trimmed);
+  if (!m) return { head: trimmed, rest: '' };
+  const cut = m.index + 1; // include the punctuation
+  return {
+    head: trimmed.slice(0, cut).trim(),
+    rest: trimmed.slice(cut).trim(),
+  };
+};
+
+export const labelAndHelp = (
+  comment: string | null | undefined,
+  key: string,
+): { label: string; help: string } => {
+  if (!comment || !comment.trim()) {
+    return { label: humanize(key), help: '' };
+  }
+  const { head, rest } = splitFirstSentence(comment);
+  return {
+    label: head || humanize(key),
+    help: rest,
+  };
+};
diff --git a/admin/src/components/settings/widgets/ArrayGroup.tsx b/admin/src/components/settings/widgets/ArrayGroup.tsx
deleted file mode 100644
index 4e1bfcac394..00000000000
--- a/admin/src/components/settings/widgets/ArrayGroup.tsx
+++ /dev/null
@@ -1,19 +0,0 @@
-import type { ReactNode } from 'react';
-import type { JSONPath } from 'jsonc-parser';
-
-type Props = {
-  path: JSONPath;
-  childCount: number;
-  children: ReactNode;
-};
-
-export const ArrayGroup = ({ path, childCount, children }: Props) => (
-  <details
-    className="settings-group settings-group-array"
-    data-testid={`group-${path.join('.') || 'root'}`}
-    open
-  >
-    <summary>{`[ ${childCount} ${childCount === 1 ? 'item' : 'items'} ]`}</summary>
-    <div className="settings-group-body">{children}</div>
-  </details>
-);
diff --git a/admin/src/components/settings/widgets/BooleanToggle.tsx b/admin/src/components/settings/widgets/BooleanToggle.tsx
index e5f8a517134..d2d91fadfdc 100644
--- a/admin/src/components/settings/widgets/BooleanToggle.tsx
+++ b/admin/src/components/settings/widgets/BooleanToggle.tsx
@@ -11,6 +11,7 @@ export const BooleanToggle = ({ value, path, onChange }: Props) => (
   <Switch.Root
     checked={value}
     onCheckedChange={onChange}
+    id={`field-${path.join('.')}`}
     className="settings-widget settings-widget-boolean"
     data-testid={`field-${path.join('.')}`}
   >
diff --git a/admin/src/components/settings/widgets/NumberInput.tsx b/admin/src/components/settings/widgets/NumberInput.tsx
index e8ad0e87e0f..a55d6d5f245 100644
--- a/admin/src/components/settings/widgets/NumberInput.tsx
+++ b/admin/src/components/settings/widgets/NumberInput.tsx
@@ -14,6 +14,7 @@ export const NumberInput = ({ value, path, onChange }: Props) => {
     <input
       type="text"
       inputMode="decimal"
+      id={`field-${path.join('.')}`}
       className={'settings-widget settings-widget-number' + (invalid ? ' invalid' : '')}
       data-testid={`field-${path.join('.')}`}
       value={draft}
diff --git a/admin/src/components/settings/widgets/ObjectGroup.tsx b/admin/src/components/settings/widgets/ObjectGroup.tsx
deleted file mode 100644
index 4b75b9b661e..00000000000
--- a/admin/src/components/settings/widgets/ObjectGroup.tsx
+++ /dev/null
@@ -1,19 +0,0 @@
-import type { ReactNode } from 'react';
-import type { JSONPath } from 'jsonc-parser';
-
-type Props = {
-  path: JSONPath;
-  childCount: number;
-  children: ReactNode;
-};
-
-export const ObjectGroup = ({ path, childCount, children }: Props) => (
-  <details
-    className="settings-group settings-group-object"
-    data-testid={`group-${path.join('.') || 'root'}`}
-    open
-  >
-    <summary>{`{ ${childCount} ${childCount === 1 ? 'key' : 'keys'} }`}</summary>
-    <div className="settings-group-body">{children}</div>
-  </details>
-);
diff --git a/admin/src/components/settings/widgets/StringInput.tsx b/admin/src/components/settings/widgets/StringInput.tsx
index 0ea079d4348..dd3efe51591 100644
--- a/admin/src/components/settings/widgets/StringInput.tsx
+++ b/admin/src/components/settings/widgets/StringInput.tsx
@@ -9,6 +9,7 @@ type Props = {
 export const StringInput = ({ value, path, onChange }: Props) => (
   <input
     type="text"
+    id={`field-${path.join('.')}`}
     className="settings-widget settings-widget-string"
     data-testid={`field-${path.join('.')}`}
     value={value}

From 81f7407e26e135c31419be6621cec997ce990b3f Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 14:53:16 +0100
Subject: [PATCH 18/31] admin(settings): update specs for label/help split +
 template fallback

Two-column form derives the row label from the first sentence of a
key's comment and puts the rest in a help paragraph; specs now assert
both pieces render. Add a spec covering the template-fallback path
(live settings.json has no comment for `port`, but `port` shows a
non-empty label sourced from settings.json.template).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../admin-spec/adminsettings.spec.ts          | 36 ++++++++++++++-----
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/src/tests/frontend-new/admin-spec/adminsettings.spec.ts b/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
index 4ed87bbe228..c4aa8ae668f 100644
--- a/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
+++ b/src/tests/frontend-new/admin-spec/adminsettings.spec.ts
@@ -124,27 +124,33 @@ test.describe('admin settings',()=> {
     await expect(settings).not.toHaveValue('', {timeout: 30000});
   });
 
-  test('form view renders leading comment as help text for known key', async ({page}) => {
+  test('form view derives label + help text from key comment', async ({page}) => {
     await page.goto('http://localhost:9001/admin/settings');
-    // Wait for settings to load (form view renders once socket emits settings).
     await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
-    // Inject a comment above "title" in raw mode so form view has something to render.
+    // Inject a two-sentence comment above "title" so the first sentence becomes
+    // the row label and the rest renders as help text.
     await page.getByTestId('mode-toggle-raw').click();
     const raw = page.getByTestId('settings-raw-textarea');
     await expect(raw).toBeVisible({timeout: 10000});
     const original = await raw.inputValue();
-    // Prepend a block comment so the form view can pick it up as help text.
-    const withComment = original.replace('"title"', '/* The pad title */\n"title"');
+    const withComment = original.replace(
+      '"title"',
+      '/* CustomTitleLabel. ExtraHelpMarker about it. */\n"title"',
+    );
     await raw.fill(withComment);
     await page.getByTestId('save-settings-button').click();
     await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
 
     await page.getByTestId('mode-toggle-form').click();
     await page.waitForSelector('[data-testid="settings-form-view"]');
-    // Assert that the injected comment renders as help text.
-    const firstComment = page.locator('.settings-comment-leading').first();
-    await expect(firstComment).toBeVisible({timeout: 10000});
-    expect((await firstComment.textContent())?.trim().length ?? 0).toBeGreaterThan(0);
+    // The injected text appears somewhere in the title row — either as label
+    // (if no template comment precedes it) or as help text (if one does and
+    // the comments are concatenated). Either way, it must be rendered.
+    const titleLabel = page.locator('label[for="field-title"]');
+    await expect(titleLabel).toBeVisible({timeout: 10000});
+    const titleRow = titleLabel.locator('xpath=ancestor::*[contains(@class,"settings-row")][1]');
+    await expect(titleRow).toContainText('CustomTitleLabel');
+    await expect(titleRow).toContainText('ExtraHelpMarker');
 
     // Restore
     await page.getByTestId('mode-toggle-raw').click();
@@ -153,6 +159,18 @@ test.describe('admin settings',()=> {
     await expect(page.locator('.ToastRootSuccess')).toBeVisible({timeout: 5000});
   });
 
+  test('form view falls back to template documentation when live comment is absent', async ({page}) => {
+    await page.goto('http://localhost:9001/admin/settings');
+    await page.waitForSelector('[data-testid="settings-form-view"]', {timeout: 30000});
+    // settings.json.template documents `port` with the env-var explainer.
+    // Even if the live settings.json has no comment for port, the template
+    // fallback should populate label + help.
+    const portLabel = page.locator('label[for="field-port"]');
+    await expect(portLabel).toBeVisible({timeout: 10000});
+    // Label is a non-empty string (humanized 'Port' or template-derived).
+    expect((await portLabel.textContent())?.trim().length ?? 0).toBeGreaterThan(0);
+  });
+
   test('editing title via form input round-trips through save', async ({page}) => {
     await page.goto('http://localhost:9001/admin/settings');
     // Wait for settings to load (form view renders once socket emits settings).

From 5bcd3e377872abd1fc94e4087cee2a980601641f Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:15:46 +0100
Subject: [PATCH 19/31] fix(#2): use stable React keys derived from AST node
 offsets/property keys

Replace index-based key={i} with stable keys: property key string (or
byte offset fallback) for object children, and byte offset for array
elements. Same fix applied to generalProps/sectionProps maps in FormView.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/FormView.tsx  | 32 ++++++++++++++-------
 admin/src/components/settings/JsoncNode.tsx | 12 ++++++--
 2 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/admin/src/components/settings/FormView.tsx b/admin/src/components/settings/FormView.tsx
index afd4eb5baa9..50a4395cf0f 100644
--- a/admin/src/components/settings/FormView.tsx
+++ b/admin/src/components/settings/FormView.tsx
@@ -87,22 +87,32 @@ export const FormView = ({ onSwitchToRaw }: Props) => {
     <div className="settings-form" data-testid="settings-form-view">
       {generalProps.length > 0 && (
         <Section title="General">
-          {generalProps.map((prop, i) => (
-            <JsoncNode
-              key={i}
-              node={prop.children![1]}
-              property={prop}
-              text={text}
-              onEdit={onEdit}
-            />
-          ))}
+          {generalProps.map((prop) => {
+            const propKey =
+              prop.children?.[0]?.type === 'string'
+                ? String(prop.children[0].value)
+                : String(prop.offset);
+            return (
+              <JsoncNode
+                key={propKey}
+                node={prop.children![1]}
+                property={prop}
+                text={text}
+                onEdit={onEdit}
+              />
+            );
+          })}
         </Section>
       )}
-      {sectionProps.map((prop, i) => {
+      {sectionProps.map((prop) => {
         const key = propertyKey(prop);
         const { label, help } = labelAndHelp(propertyComment(prop, text, key), key);
+        const sectionKey =
+          prop.children?.[0]?.type === 'string'
+            ? String(prop.children[0].value)
+            : String(prop.offset);
         return (
-          <Section key={i} title={label} description={help}>
+          <Section key={sectionKey} title={label} description={help}>
             <JsoncNode
               node={prop.children![1]}
               property={prop}
diff --git a/admin/src/components/settings/JsoncNode.tsx b/admin/src/components/settings/JsoncNode.tsx
index 224c1544aec..79349f9a411 100644
--- a/admin/src/components/settings/JsoncNode.tsx
+++ b/admin/src/components/settings/JsoncNode.tsx
@@ -87,15 +87,20 @@ export const JsoncNode = ({ node, property, text, onEdit, suppressOwnHeader }: P
 
   // ---- Object / array groups ----
   if (node.type === 'object' || node.type === 'array') {
-    const children = (node.children ?? []).map((child, i) => {
+    const children = (node.children ?? []).map((child) => {
       // For object: child is a property node, drill into its value node.
       // For array: child is a value node directly.
       if (node.type === 'object') {
         const valueNode = child.children?.[1];
         if (!valueNode) return null;
+        // Use the property key string as stable key; fall back to byte offset.
+        const propKey =
+          child.children?.[0]?.type === 'string'
+            ? String(child.children[0].value)
+            : String(child.offset);
         return (
           <JsoncNode
-            key={i}
+            key={propKey}
             node={valueNode}
             property={child}
             text={text}
@@ -103,7 +108,8 @@ export const JsoncNode = ({ node, property, text, onEdit, suppressOwnHeader }: P
           />
         );
       }
-      return <JsoncNode key={i} node={child} text={text} onEdit={onEdit} />;
+      // Array element: use unique byte offset as stable key.
+      return <JsoncNode key={child.offset} node={child} text={text} onEdit={onEdit} />;
     });
 
     if (suppressOwnHeader || !property) {

From 8f94f7134c607ea27bcbcd8ff06240a33118a09a Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:16:00 +0100
Subject: [PATCH 20/31] fix(#3): read latest settings text from store in onEdit
 to prevent stale closures

onEdit previously closed over the render-time text snapshot; rapid edits
would clobber each other as each call re-applied its delta to the same
stale baseline. Now reads useStore.getState().settings on every call.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/FormView.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/admin/src/components/settings/FormView.tsx b/admin/src/components/settings/FormView.tsx
index 50a4395cf0f..a30f9dc19ba 100644
--- a/admin/src/components/settings/FormView.tsx
+++ b/admin/src/components/settings/FormView.tsx
@@ -66,8 +66,11 @@ export const FormView = ({ onSwitchToRaw }: Props) => {
   const errors: ParseError[] = [];
   const tree = parseTree(text, errors, { allowTrailingComma: true });
 
+  // Always read the latest text from the store instead of closing over the
+  // render-time snapshot, so rapid sequential edits don't clobber each other.
   const onEdit = (path: JSONPath, value: unknown) => {
-    useStore.getState().setSettings(editJsonc(text, path, value));
+    const current = useStore.getState().settings ?? '';
+    useStore.getState().setSettings(editJsonc(current, path, value));
   };
 
   if (!tree || errors.length > 0 || tree.type !== 'object') {

From 3971e686f59a237dac274937c7d6a4383a3499bf Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:16:40 +0100
Subject: [PATCH 21/31] fix(#6): resolve .settings CSS conflict between App.css
 and index.css

Both files defined .settings targeting the same textarea element with
conflicting declarations (resize: none vs resize: vertical, different
font stacks). Disambiguate App.css to textarea.settings and remove the
now-superseded legacy .settings block from index.css.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/App.css   | 4 ++--
 admin/src/index.css | 7 -------
 2 files changed, 2 insertions(+), 9 deletions(-)

diff --git a/admin/src/App.css b/admin/src/App.css
index 97e61465ec2..8b31b48b02b 100644
--- a/admin/src/App.css
+++ b/admin/src/App.css
@@ -1,5 +1,5 @@
 /* Raw textarea (kept dark to signal "this is code") */
-.settings {
+textarea.settings {
   font-family: "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
   font-size: 14px;
   white-space: pre;
@@ -14,7 +14,7 @@
   border: 1px solid #333;
   resize: vertical;
 }
-.settings:focus {
+textarea.settings:focus {
   outline: 2px solid #007acc;
   outline-offset: -1px;
 }
diff --git a/admin/src/index.css b/admin/src/index.css
index f33aafb6db8..a6cf68332d0 100644
--- a/admin/src/index.css
+++ b/admin/src/index.css
@@ -297,13 +297,6 @@ td, th {
   min-height: 100%;
 }
 
-.settings {
-  flex-grow: max(1, 1);
-  outline: none;
-  width: 100%;
-  resize: none;
-  font-family: monospace;
-}
 
 #response {
   display: inline;

From e6e92ab72c55c26a7f29e978162a15065337ffc6 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:17:01 +0100
Subject: [PATCH 22/31] fix(#8): suppress parse-error flash while settings are
 still loading

When settings is undefined (not yet loaded from server), render an empty
aria-busy placeholder div instead of treating undefined as empty string,
which previously caused a spurious parse-error banner flash on load.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/FormView.tsx | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/admin/src/components/settings/FormView.tsx b/admin/src/components/settings/FormView.tsx
index a30f9dc19ba..a3f861393b1 100644
--- a/admin/src/components/settings/FormView.tsx
+++ b/admin/src/components/settings/FormView.tsx
@@ -61,7 +61,15 @@ const propertyComment = (prop: Node, text: string, key: string): string | null =
 };
 
 export const FormView = ({ onSwitchToRaw }: Props) => {
-  const text = useStore(s => s.settings) ?? '';
+  const rawText = useStore(s => s.settings);
+
+  // While settings haven't loaded yet, show an empty busy placeholder so we
+  // don't flash a parse-error banner for the undefined→'' empty-string case.
+  if (rawText === undefined) {
+    return <div className="settings-form" data-testid="settings-form-view" aria-busy="true" />;
+  }
+
+  const text = rawText;
 
   const errors: ParseError[] = [];
   const tree = parseTree(text, errors, { allowTrailingComma: true });

From 4bbac8b3e9a7d33fa2e8231d03230b81851bcbb4 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:17:29 +0100
Subject: [PATCH 23/31] fix(#9): sync NumberInput draft state with value prop
 when not focused

Add a useEffect that updates the draft string when the value prop changes
(e.g. after a server save round-trip canonicalises the number), but only
when the input is not focused so in-progress user typing is never stomped.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/settings/widgets/NumberInput.tsx  | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/admin/src/components/settings/widgets/NumberInput.tsx b/admin/src/components/settings/widgets/NumberInput.tsx
index a55d6d5f245..d339e97a80e 100644
--- a/admin/src/components/settings/widgets/NumberInput.tsx
+++ b/admin/src/components/settings/widgets/NumberInput.tsx
@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import type { JSONPath } from 'jsonc-parser';
 
 type Props = {
@@ -10,6 +10,18 @@ type Props = {
 export const NumberInput = ({ value, path, onChange }: Props) => {
   const [draft, setDraft] = useState(String(value));
   const [invalid, setInvalid] = useState(false);
+  const focusedRef = useRef(false);
+
+  // Sync draft when the prop value changes (e.g. after a server round-trip
+  // canonicalises the number) — but only when the input is not focused so we
+  // don't stomp on the user while they are typing.
+  useEffect(() => {
+    if (!focusedRef.current) {
+      setDraft(String(value));
+      setInvalid(false);
+    }
+  }, [value]);
+
   return (
     <input
       type="text"
@@ -18,6 +30,8 @@ export const NumberInput = ({ value, path, onChange }: Props) => {
       className={'settings-widget settings-widget-number' + (invalid ? ' invalid' : '')}
       data-testid={`field-${path.join('.')}`}
       value={draft}
+      onFocus={() => { focusedRef.current = true; }}
+      onBlur={() => { focusedRef.current = false; }}
       onChange={e => {
         const next = e.target.value;
         setDraft(next);

From a57fd2e0c8b03d4f9405f4ead781e6d9f7731b64 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:17:43 +0100
Subject: [PATCH 24/31] docs(#10): aria-describedby already resolved during
 form redesign
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

JsoncNode.tsx defines helpId only when help text exists and uses it
solely as the p element's id — no aria-describedby ever points at it.
No dangling reference; issue was already clean before this PR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

From 2a76a20be946e5be79b393f50fbf02703b1f50d8 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:17:56 +0100
Subject: [PATCH 25/31] docs(#11): add comment explaining handleKeyDown Tab/rAF
 behaviour

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/pages/SettingsPage.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/admin/src/pages/SettingsPage.tsx b/admin/src/pages/SettingsPage.tsx
index b187f370cc2..b24c64fad0e 100644
--- a/admin/src/pages/SettingsPage.tsx
+++ b/admin/src/pages/SettingsPage.tsx
@@ -17,6 +17,7 @@ export const SettingsPage = () => {
   const [mode, setMode] = useState<Mode>('form');
   const [exposeExperimental] = useState(false);
 
+  // Tab in textarea inserts two spaces instead of moving focus; rAF restores caret position after React re-renders.
   const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
     if (e.key !== 'Tab') return;
     e.preventDefault();

From c1d360bfb3d995ae6bc0759e40dfd9baa3f99d8b Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:18:47 +0100
Subject: [PATCH 26/31] fix(#12): show save toast on server ack only, not
 optimistically

Server now emits saveprogress:'saved' only on writeFile success and
saveprogress:'error' with payload.message on failure. The client
saveprogress listener in App.tsx drives the toast; handleSave no longer
fires a success toast eagerly. Adds admin_settings.toast.save_failed i18n key.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/App.tsx                       | 10 ++++++++--
 admin/src/pages/SettingsPage.tsx        |  2 +-
 src/locales/en.json                     |  1 +
 src/node/hooks/express/adminsettings.ts |  3 ++-
 4 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/admin/src/App.tsx b/admin/src/App.tsx
index 27d5a2ae367..18a41c4d888 100644
--- a/admin/src/App.tsx
+++ b/admin/src/App.tsx
@@ -77,8 +77,14 @@ export const App = () => {
       useStore.getState().setShowLoading(false);
     });
 
-    settingSocket.on('saveprogress', (status) => {
-      console.log(status)
+    settingSocket.on('saveprogress', (status: string, payload?: {message?: string}) => {
+      const {setToastState} = useStore.getState();
+      if (status === 'saved') {
+        setToastState({open: true, title: t('admin_settings.toast.saved'), success: true});
+      } else {
+        const detail = payload?.message ?? '';
+        setToastState({open: true, title: t('admin_settings.toast.save_failed') + (detail ? ` (${detail})` : ''), success: false});
+      }
     })
 
     return () => {
diff --git a/admin/src/pages/SettingsPage.tsx b/admin/src/pages/SettingsPage.tsx
index b24c64fad0e..a8e517e15ab 100644
--- a/admin/src/pages/SettingsPage.tsx
+++ b/admin/src/pages/SettingsPage.tsx
@@ -53,8 +53,8 @@ export const SettingsPage = () => {
   const handleSave = () => {
     if (!isJSONClean(settings)) return showToast('admin_settings.toast.json_invalid', false);
     if (!settingsSocket?.connected) return showToast('admin_settings.toast.disconnected', false);
+    // Toast is shown by the saveprogress socket listener in App.tsx on server ack.
     settingsSocket.emit('saveSettings', settings);
-    showToast('admin_settings.toast.saved', true);
   };
 
   return (
diff --git a/src/locales/en.json b/src/locales/en.json
index fe39e3d1e6a..96a20be069f 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -36,6 +36,7 @@
   "admin_settings.current_test.value": "Validate JSON",
   "admin_settings.current_prettify.value": "Prettify JSON",
   "admin_settings.toast.saved": "Settings saved successfully.",
+  "admin_settings.toast.save_failed": "Save failed: settings.json could not be written.",
   "admin_settings.toast.json_invalid": "Syntax error: check commas, braces, and quotes.",
   "admin_settings.toast.disconnected": "Cannot save: not connected to server.",
   "admin_settings.toast.validation_ok": "JSON is valid.",
diff --git a/src/node/hooks/express/adminsettings.ts b/src/node/hooks/express/adminsettings.ts
index 2d815207142..3440f97cf4f 100644
--- a/src/node/hooks/express/adminsettings.ts
+++ b/src/node/hooks/express/adminsettings.ts
@@ -43,10 +43,11 @@ exports.socketio = (hookName: string, {io}: any) => {
       logger.info('Admin request to save settings through a socket on /admin/settings');
       try {
         await fsp.writeFile(settings.settingsFilename, newSettings);
+        socket.emit('saveprogress', 'saved');
       } catch (err) {
         logger.error(`Error saving settings: ${err}`);
+        socket.emit('saveprogress', 'error', {message: String(err)});
       }
-      socket.emit('saveprogress', 'saved');
     });
 
 

From 05ad93f98dce4aa9a8616ff718094b3174b58152 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:19:05 +0100
Subject: [PATCH 27/31] fix(#13): strengthen saveSettings helper to wait for
 genuine new toast open

Radix Toast toggles data-state rather than removing the element, so the
old .ToastRootSuccess selector could match a stale open toast from a
previous save. Now waits for any existing open toast to close before
clicking, then requires data-state="open" on the new toast.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/tests/frontend-new/helper/adminhelper.ts | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/tests/frontend-new/helper/adminhelper.ts b/src/tests/frontend-new/helper/adminhelper.ts
index fed31a0d162..f819deb4995 100644
--- a/src/tests/frontend-new/helper/adminhelper.ts
+++ b/src/tests/frontend-new/helper/adminhelper.ts
@@ -12,8 +12,15 @@ export const loginToAdmin = async (page: Page, username: string, password: strin
 
 
 export const saveSettings = async (page: Page) => {
-  await page.getByTestId('save-settings-button').click()
-  await page.waitForSelector('.ToastRootSuccess')
+  // If a success toast is already open (from a previous save), wait for it to
+  // close first so we don't mistake the stale open state for the new ack.
+  // Radix Toast toggles data-state rather than removing the element.
+  const existing = page.locator('.ToastRootSuccess[data-state="open"]');
+  if (await existing.count() > 0) {
+    await existing.waitFor({state: 'hidden'}).catch(() => {});
+  }
+  await page.getByTestId('save-settings-button').click();
+  await page.waitForSelector('.ToastRootSuccess[data-state="open"]');
 }
 
 export const restartEtherpad = async (page: Page) => {

From 4dd16c2d4199ed06217ddbcc3a2cc46d6bd49712 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:20:01 +0100
Subject: [PATCH 28/31] fix(#14): internationalise hard-coded UI strings in
 FormView and ModeToggle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 'General' section title → t('admin_settings.section.general')
- ModeToggle aria-label → t('admin_settings.mode.aria_label')
- ParseErrorMessage token labels intentionally kept in English (technical
  parser-error tokens, not user-facing prose; documented with comment)
- Adds admin_settings.section.general and admin_settings.mode.aria_label
  to src/locales/en.json

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/settings/FormView.tsx   |  6 +++++-
 admin/src/components/settings/ModeToggle.tsx | 11 +++++++----
 src/locales/en.json                          |  2 ++
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/admin/src/components/settings/FormView.tsx b/admin/src/components/settings/FormView.tsx
index a3f861393b1..ee6b80b929d 100644
--- a/admin/src/components/settings/FormView.tsx
+++ b/admin/src/components/settings/FormView.tsx
@@ -1,5 +1,6 @@
 import { parseTree, type JSONPath, type Node, type ParseError } from 'jsonc-parser';
 import { useStore } from '../../store/store';
+import { useTranslation } from 'react-i18next';
 import { editJsonc } from './jsoncEdit';
 import { JsoncNode } from './JsoncNode';
 import { ParseErrorBanner } from './ParseErrorBanner';
@@ -11,6 +12,8 @@ type Props = {
   onSwitchToRaw: () => void;
 };
 
+// Parser-error token labels are kept in English — they are technical tokens
+// matching the jsonc-parser error enum, not user-facing prose.
 const ParseErrorMessage: Record<number, string> = {
   1: 'Invalid symbol',
   2: 'Invalid number format',
@@ -61,6 +64,7 @@ const propertyComment = (prop: Node, text: string, key: string): string | null =
 };
 
 export const FormView = ({ onSwitchToRaw }: Props) => {
+  const { t } = useTranslation();
   const rawText = useStore(s => s.settings);
 
   // While settings haven't loaded yet, show an empty busy placeholder so we
@@ -97,7 +101,7 @@ export const FormView = ({ onSwitchToRaw }: Props) => {
   return (
     <div className="settings-form" data-testid="settings-form-view">
       {generalProps.length > 0 && (
-        <Section title="General">
+        <Section title={t('admin_settings.section.general')}>
           {generalProps.map((prop) => {
             const propKey =
               prop.children?.[0]?.type === 'string'
diff --git a/admin/src/components/settings/ModeToggle.tsx b/admin/src/components/settings/ModeToggle.tsx
index 0e0146ae584..0f87f62ce84 100644
--- a/admin/src/components/settings/ModeToggle.tsx
+++ b/admin/src/components/settings/ModeToggle.tsx
@@ -1,4 +1,4 @@
-import { Trans } from 'react-i18next';
+import { Trans, useTranslation } from 'react-i18next';
 
 export type Mode = 'form' | 'raw';
 
@@ -7,8 +7,10 @@ type Props = {
   onChange: (mode: Mode) => void;
 };
 
-export const ModeToggle = ({ mode, onChange }: Props) => (
-  <div className="settings-mode-toggle" role="tablist" aria-label="Editor mode">
+export const ModeToggle = ({ mode, onChange }: Props) => {
+  const { t } = useTranslation();
+  return (
+  <div className="settings-mode-toggle" role="tablist" aria-label={t('admin_settings.mode.aria_label')}>
     <button
       type="button"
       role="tab"
@@ -30,4 +32,5 @@ export const ModeToggle = ({ mode, onChange }: Props) => (
       <Trans i18nKey="admin_settings.mode.raw" />
     </button>
   </div>
-);
+  );
+};
diff --git a/src/locales/en.json b/src/locales/en.json
index 96a20be069f..a103ece1fc6 100644
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -45,6 +45,8 @@
   "admin_settings.prettify_confirm": "Prettifying will remove all comments. Continue?",
   "admin_settings.mode.form": "Form",
   "admin_settings.mode.raw": "Raw",
+  "admin_settings.mode.aria_label": "Editor mode",
+  "admin_settings.section.general": "General",
   "admin_settings.parse_error.title": "Cannot parse settings.json",
   "admin_settings.parse_error.cta": "Switch to raw to edit",
   "admin_settings.env_pill.tooltip": "Environment variable. Edit in raw mode.",

From 237200dd99b6852c21f6edbc96f123cad770a77c Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:20:18 +0100
Subject: [PATCH 29/31] fix(#15): default IconButton type to 'button' to
 prevent accidental form submit

Without an explicit type, a <button> inside a <form> defaults to
type='submit'. Adding type='button' as the default prevents any
wrapping form from being submitted unintentionally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/components/IconButton.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/admin/src/components/IconButton.tsx b/admin/src/components/IconButton.tsx
index 22cb43b9605..2ea3c902dc7 100644
--- a/admin/src/components/IconButton.tsx
+++ b/admin/src/components/IconButton.tsx
@@ -6,9 +6,9 @@ export type IconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'tit
   onClick: ()=>void,
 }
 
-export const IconButton:FC<IconButtonProps> = ({icon, className, onClick, title, ...rest})=>{
-  return <button {...rest} onClick={onClick} className={"icon-button "+ (className ?? "")}>
+export const IconButton: FC<IconButtonProps> = ({icon, className, onClick, title, type = 'button', ...rest}) => (
+  <button {...rest} type={type} onClick={onClick} className={"icon-button " + (className ?? "")}>
     {icon}
     <span>{title}</span>
-    </button>
-}
+  </button>
+);

From bd84291daddefadbca645512873fabf50353c359 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:20:32 +0100
Subject: [PATCH 30/31] fix(#7): change protocol-relative GitHub wiki links to
 explicit https://

Protocol-relative //github.com inherits the page protocol; explicit
https:// is safer and avoids mixed-content issues.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 admin/src/pages/SettingsPage.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/admin/src/pages/SettingsPage.tsx b/admin/src/pages/SettingsPage.tsx
index a8e517e15ab..7511b8e399f 100644
--- a/admin/src/pages/SettingsPage.tsx
+++ b/admin/src/pages/SettingsPage.tsx
@@ -111,10 +111,10 @@ export const SettingsPage = () => {
       </div>
 
       <div className="settings-links">
-        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad/wiki/Example-Production-Settings.JSON">
+        <a rel="noopener noreferrer" target="_blank" href="https://github.com/ether/etherpad/wiki/Example-Production-Settings.JSON">
           <Trans i18nKey="admin_settings.current_example-prod" />
         </a>
-        <a rel="noopener noreferrer" target="_blank" href="//github.com/ether/etherpad/wiki/Example-Development-Settings.JSON">
+        <a rel="noopener noreferrer" target="_blank" href="https://github.com/ether/etherpad/wiki/Example-Development-Settings.JSON">
           <Trans i18nKey="admin_settings.current_example-devel" />
         </a>
       </div>

From bf4c250697cc63281fb8fa1f59dcddc5794d36ff Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sat, 9 May 2026 15:44:42 +0100
Subject: [PATCH 31/31] admin(settings): inline template at build time, drop
 fs.allow widening
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Switching the previous `?raw` import to a Vite `define` removes the
need to widen the dev server's filesystem allowlist to the repo root.
The previous setting (server.fs.allow: ['..']) let the dev server
serve any file under the repo root — including settings.json and
credentials.json — to anything that could reach the dev server.
The build-time `define` produces an identical bundle without ever
exposing the filesystem at runtime.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/settings/templateComments.ts   | 10 +++++++---
 admin/vite.config.ts                          | 19 +++++++++++++++----
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/admin/src/components/settings/templateComments.ts b/admin/src/components/settings/templateComments.ts
index 843e883146f..230ce589c1b 100644
--- a/admin/src/components/settings/templateComments.ts
+++ b/admin/src/components/settings/templateComments.ts
@@ -3,11 +3,15 @@
 // authoritative source of per-key documentation.
 
 import { parseTree, type JSONPath, type Node } from 'jsonc-parser';
-// `?raw` is a Vite import suffix — returns the file content as a string.
-// vite.config.ts must allow reading from the repo root for this to work.
-import templateText from '../../../../settings.json.template?raw';
 import { extractAdjacentComments } from './comments';
 
+// Injected by Vite at build time from settings.json.template (see vite.config.ts).
+// Inlining at config time avoids widening the dev server's filesystem allowlist
+// to the repo root, which would expose settings.json/credentials.json over the
+// dev server.
+declare const __SETTINGS_TEMPLATE__: string;
+const templateText: string = __SETTINGS_TEMPLATE__;
+
 const pathKey = (path: JSONPath): string => path.map(String).join('.');
 
 const buildMap = (text: string): Map<string, string> => {
diff --git a/admin/vite.config.ts b/admin/vite.config.ts
index fa7e0167ca4..818f620c2b4 100644
--- a/admin/vite.config.ts
+++ b/admin/vite.config.ts
@@ -1,5 +1,17 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+// Inline `settings.json.template` at config time so the bundle has the
+// per-key documentation without expanding the dev server's filesystem
+// allowlist (which would otherwise serve every file in the repo root,
+// including settings.json and credentials.json, to anything that can
+// reach the dev server).
+const settingsTemplate = readFileSync(
+  resolve(__dirname, '..', 'settings.json.template'),
+  'utf8',
+)
 
 // https://vitejs.dev/config/
 export default defineConfig({
@@ -11,15 +23,14 @@ export default defineConfig({
     }),
   ],
   base: '/admin',
+  define: {
+    __SETTINGS_TEMPLATE__: JSON.stringify(settingsTemplate),
+  },
   build: {
     outDir: '../src/templates/admin',
     emptyOutDir: true,
   },
   server: {
-    fs: {
-      // Allow importing `settings.json.template` from the repo root.
-      allow: ['..'],
-    },
     proxy: {
       '/socket.io/*': {
         target: 'http://localhost:9001',