From 341d2413df4bed787e411ad8d29f1211c885789f Mon Sep 17 00:00:00 2001
From: Nico Ritschel <ritschel@gmail.com>
Date: Fri, 6 Nov 2026 10:19:44 -0800
Subject: [PATCH] Rebuild the Worker settings tab as one aligned column

Render Settings outside the source form so Secrets, Sharing and Library
can sit inside the panel instead of below its Save bar, and give each
section its own clear save. Show which declared secrets need a value and
which saved values never reach the Worker.
---
 e2e/gallery-native-apps.test.ts |  19 +-
 src/gallery/native-apps.tsx     | 361 +++++++++++++++++++-------------
 src/gallery/secrets.tsx         |  30 ++-
 src/gallery/styles.ts           |   3 +
 4 files changed, 257 insertions(+), 156 deletions(-)

diff --git a/e2e/gallery-native-apps.test.ts b/e2e/gallery-native-apps.test.ts
index fe605d3..437ed48 100644
--- a/e2e/gallery-native-apps.test.ts
+++ b/e2e/gallery-native-apps.test.ts
@@ -128,6 +128,7 @@ test("Worker gallery deploys drafts, manages revisions/secrets and preserves edi
   let failFirst = true;
   let failRestore = true;
   let failReconcile = true;
+  let secretNames: string[] = [];
   const server = Bun.serve({
     port: 0,
     hostname: "127.0.0.1",
@@ -204,7 +205,8 @@ test("Worker gallery deploys drafts, manages revisions/secrets and preserves edi
             saved!.status = "active";
             return result({ ...saved, ok: true });
           case "app_secrets":
-            return result({ names: ["TOKEN"] });
+            if (call.arguments.secrets) secretNames = ["TOKEN", "UNDECLARED"];
+            return result({ names: secretNames });
           case "app_move":
             saved = null;
             return result({ ok: true });
@@ -316,12 +318,25 @@ test("Worker gallery deploys drafts, manages revisions/secrets and preserves edi
     expect(new URL(page.url()).searchParams.get("app")).toBe("example");
     expect(new URL(page.url()).searchParams.get("appTab")).toBe("deployments");
     await panel.getByRole("tab", { name: "Settings", exact: true }).click();
-    await panel.getByLabel("Secret name", { exact: true }).fill("TOKEN");
+    const settings = panel.getByRole("tabpanel", { name: "Settings", exact: true });
+    const secretRows = settings.getByRole("list", { name: "Secret names", exact: true }).getByRole("listitem");
+    await secretRows.filter({ hasText: "TOKEN" }).getByText("Needs a value", { exact: true }).waitFor();
+    await secretRows.filter({ hasText: "TOKEN" }).getByRole("button", { name: "Set value", exact: true }).click();
+    expect(await panel.getByLabel("Secret name", { exact: true }).inputValue()).toBe("TOKEN");
+    expect(await panel.getByLabel("Secret value", { exact: true }).evaluate((input) => input === document.activeElement)).toBe(true);
+    // Sections that save on their own sit inside the panel, below the deploy action that does not cover them.
+    const deployBox = await settings.getByRole("button", { name: "Save and deploy Worker", exact: true }).boundingBox();
+    for (const heading of ["Secrets", "Sharing", "Library"]) {
+      const headingBox = await settings.getByRole("heading", { name: heading, exact: true }).boundingBox();
+      expect(headingBox!.y).toBeGreaterThan(deployBox!.y);
+    }
     await panel.getByLabel("Secret value", { exact: true }).fill("secret-fixture-value");
     const writesBeforeSecret = calls.filter((call) => call.name === "app_write").length;
     await panel.getByRole("button", { name: "Save secret", exact: true }).click();
     await panel.getByText("Secret saved", { exact: true }).waitFor();
     expect(await panel.getByLabel("Secret value", { exact: true }).inputValue()).toBe("");
+    expect(await settings.getByText("Needs a value", { exact: true }).count()).toBe(0);
+    await secretRows.filter({ hasText: "UNDECLARED" }).getByText("Not passed to the Worker", { exact: true }).waitFor();
     expect(calls.filter((call) => call.name === "app_write").length).toBe(writesBeforeSecret);
     expect(await panel.locator(".cm-content").innerText()).toContain("local edit");
     await panel.getByRole("button", { name: "Save and deploy Worker", exact: true }).click();
diff --git a/src/gallery/native-apps.tsx b/src/gallery/native-apps.tsx
index 372afab..8ea323f 100644
--- a/src/gallery/native-apps.tsx
+++ b/src/gallery/native-apps.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useImperativeHandle, useRef, useState, type Ref } from "react";
+import { useEffect, useImperativeHandle, useRef, useState, type FormEvent, type ReactNode, type Ref } from "react";
 import { GalleryToolError, LinkSettings, galleryTool } from "./hosted";
 import { ProjectEditor, editableProject, emptyEditableProject, type EditableProject } from "./project-editor";
 import { SecretControls } from "./secrets";
@@ -186,6 +186,34 @@ export function NativeAppEditor({ workspace, appName, providers, onNavigate, onS
   };
   const providerAvailable = providers.includes(provider);
   const detail = (!!selected || editingNew) && providerAvailable;
+  function deploy(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    void perform(async () => {
+      const result = decode<App & { ok: boolean }>(
+        await galleryTool(workspace, "app_write", {
+          name,
+          source,
+          manifest: JSON.parse(manifest),
+          project,
+          provider,
+          expected_revision: baseRevision,
+        }),
+      );
+      setDirty(false);
+      await onSaved();
+      await loadApp(name);
+      navigate(name);
+      setStatus(result.ok ? "Native Worker deployed" : "Native Worker needs reconciliation");
+    }, true);
+  }
+  const deployControls = (
+    <>
+      <button className="primary-action" disabled={busy || !valid || !provider || !parsed}>
+        Save and deploy Worker
+      </button>
+      {dirty ? <span>Unsaved changes</span> : null}
+    </>
+  );
   return (
     <Tabs.Root
       render={<section />}
@@ -206,7 +234,7 @@ export function NativeAppEditor({ workspace, appName, providers, onNavigate, onS
         .worker-workspace [role="tabpanel"][hidden] { display: none; }
         .worker-workspace .worker-source-panel { min-height: 300px; padding: 0; }
         .worker-workspace .worker-source-panel > .project-editor { height: 100%; }
-        .worker-workspace .worker-content > :is(p, .worker-empty, .script-fields, h3, button) { margin: 12px 16px; }
+        .worker-workspace .worker-content > :is(p, .worker-empty, .script-fields) { margin: 12px 16px; }
         .worker-workspace .source-actions { flex-wrap: wrap; }
         .worker-workspace input, .worker-workspace textarea { max-width: 100%; box-sizing: border-box; }
         .worker-workspace fieldset { min-width: 0; }
@@ -219,13 +247,38 @@ export function NativeAppEditor({ workspace, appName, providers, onNavigate, onS
         .worker-workspace [role="tabpanel"]:not(.worker-source-panel) { max-width: 760px; }
         .worker-workspace [role="tabpanel"] > h2 { margin: 0 0 6px; font-size: 14px; font-weight: 600; }
         .worker-workspace [role="tabpanel"] > h3 { margin: 24px 0 6px; font-size: 13px; font-weight: 600; }
-        .worker-workspace .worker-content > h3 { font-size: 13px; font-weight: 600; }
         .worker-workspace legend { padding: 0; margin-bottom: 8px; font-size: 12px; font-weight: 600; }
+        .worker-workspace [role="tabpanel"].worker-settings { padding-block: 0; }
+        .settings-section { padding-block: 24px; }
+        .settings-section + .settings-section { border-top: 1px solid var(--line); }
+        .settings-section > h2 { margin: 0 0 4px; font-size: 14px; font-weight: 600; }
+        .worker-settings .settings-description { margin-bottom: 16px; }
+        .worker-settings .secret-controls { max-width: none; padding: 0; }
+        .worker-settings .settings-feedback { margin-top: 8px; }
+        .worker-settings .settings-feedback:empty { min-height: 0; margin: 0; }
+        .worker-settings .link-settings { padding: 0; margin-top: 12px; }
+        .worker-settings .link-settings > label:has(input) { flex: 1; }
+        .worker-settings .link-settings > label input { width: 100%; }
+        .worker-settings :is(.settings-stack, .settings-section) > .settings-actions { margin-top: 0; }
+        .settings-stack { display: flex; flex-direction: column; gap: 20px; }
+        .settings-list { display: flex; flex-direction: column; align-items: flex-start; gap: 8px; min-width: 0; margin: 0; padding: 0; border: 0; }
+        .worker-workspace .settings-list legend { margin-bottom: 4px; }
+        .settings-hint { margin: 0; color: var(--muted); font-size: 12px; }
+        .settings-row { display: grid; grid-template-columns: minmax(0, 1fr) auto; align-self: stretch; gap: 8px; }
+        .settings-row.variable-row { grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) auto; }
+        .settings-row input { width: 100%; font-family: var(--font-mono); }
+        .settings-row :is(input, button), .settings-list > button { height: 36px; }
         .worker-manifest { display: block; width: 100%; min-height: 240px; margin-top: 6px; padding: 12px; border: 1px solid var(--line); border-radius: 8px; background: var(--panel); color: var(--text); font: 12px/1.6 var(--font-mono); }
         @media (max-width: 1100px) {
           .worker-workspace .detail-header { flex-wrap: wrap; gap: 8px; }
           .worker-workspace .view-control { order: 3; width: 100%; }
         }
+        @media (max-width: 760px) {
+          .settings-row.variable-row { grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); }
+          .settings-row.variable-row button { grid-column: 1 / -1; justify-self: end; }
+          .settings-row :is(input, button), .settings-list > button { height: 44px; }
+          .settings-row input { font-size: 16px; }
+        }
       `}</style>
       <header className="detail-header">
         <button className="back-library" type="button" onClick={onBack} aria-label="Back to library"><span aria-hidden="true">←</span></button>
@@ -342,29 +395,8 @@ export function NativeAppEditor({ workspace, appName, providers, onNavigate, onS
         {detail ? (
           <>
             {selected?.error ? <p role="alert">{selected.error}</p> : null}
-            <form
-              className="source-form"
-              onSubmit={(event) => {
-                event.preventDefault();
-                void perform(async () => {
-                  const result = decode<App & { ok: boolean }>(
-                    await galleryTool(workspace, "app_write", {
-                      name,
-                      source,
-                      manifest: JSON.parse(manifest),
-                      project,
-                      provider,
-                      expected_revision: baseRevision,
-                    }),
-                  );
-                  setDirty(false);
-                  await onSaved();
-                  await loadApp(name);
-                  navigate(name);
-                  setStatus(result.ok ? "Native Worker deployed" : "Native Worker needs reconciliation");
-                }, true);
-              }}
-            >
+            {/* Settings holds its own forms, so it cannot render inside this one. */}
+            <form className="source-form" hidden={section === "settings"} onSubmit={deploy}>
               <Tabs.Panel value="source" className="worker-source-panel" keepMounted hidden={section !== "source"}>
                 <ProjectEditor
                   key={editorKey}
@@ -405,9 +437,10 @@ export function NativeAppEditor({ workspace, appName, providers, onNavigate, onS
                   Cron triggers use UTC. Queue consumers refer to queue resource names configured in Resources.
                 </p>
                 {parsed ? (
-                  <>
+                  <div className="settings-stack">
                     <StringList
                       label="Cron schedule"
+                      placeholder="0 * * * *"
                       values={parsed.triggers?.crons ?? []}
                       disabled={busy}
                       onChange={(crons) =>
@@ -426,7 +459,7 @@ export function NativeAppEditor({ workspace, appName, providers, onNavigate, onS
                         })
                       }
                     />
-                  </>
+                  </div>
                 ) : (
                   <p>Fix the manifest JSON in Settings to edit triggers.</p>
                 )}
@@ -499,120 +532,133 @@ export function NativeAppEditor({ workspace, appName, providers, onNavigate, onS
                   <p>Save and deploy this Worker to create its first revision.</p>
                 )}
               </Tabs.Panel>
-              <Tabs.Panel value="settings">
-                <h2>Settings</h2>
-                {parsed ? (
-                  <>
-                    <div className="script-fields">
-                      <label>
-                        Entry point
-                        <input
-                          aria-label="Worker entry point"
-                          disabled={busy}
-                          value={parsed.main ?? ""}
-                          onChange={(event) => updateManifest({ main: event.target.value })}
-                        />
-                      </label>
-                      <label>
-                        Compatibility date
-                        <input
-                          aria-label="Compatibility date"
-                          type="date"
-                          disabled={busy}
-                          value={parsed.compatibility_date ?? ""}
-                          onChange={(event) => updateManifest({ compatibility_date: event.target.value })}
-                        />
-                      </label>
-                    </div>
-                    <StringList
-                      label="Compatibility flag"
-                      values={parsed.compatibility_flags ?? []}
-                      disabled={busy}
-                      onChange={(compatibility_flags) => updateManifest({ compatibility_flags })}
-                    />
-                    <VariableFields
-                      values={parsed.vars ?? {}}
-                      disabled={busy}
-                      onChange={(vars) => updateManifest({ vars })}
-                    />
-                    <StringList
-                      label="Required secret"
-                      values={parsed.secrets ?? []}
-                      disabled={busy}
-                      onChange={(secrets) => updateManifest({ secrets })}
+              {section !== "settings" ? <div className="source-actions">{deployControls}</div> : null}
+            </form>
+            <Tabs.Panel value="settings" className="worker-settings">
+              <SettingsSection title="Configuration" description="Saved with the Worker's source. Changes apply when you deploy.">
+                <form className="settings-stack" onSubmit={deploy}>
+                  {parsed ? (
+                    <>
+                      <div className="settings-fields">
+                        <label>
+                          Entry point
+                          <input
+                            aria-label="Worker entry point"
+                            disabled={busy}
+                            value={parsed.main ?? ""}
+                            onChange={(event) => updateManifest({ main: event.target.value })}
+                          />
+                        </label>
+                        <label>
+                          Compatibility date
+                          <input
+                            aria-label="Compatibility date"
+                            type="date"
+                            disabled={busy}
+                            value={parsed.compatibility_date ?? ""}
+                            onChange={(event) => updateManifest({ compatibility_date: event.target.value })}
+                          />
+                        </label>
+                      </div>
+                      <StringList
+                        label="Compatibility flag"
+                        placeholder="nodejs_compat"
+                        values={parsed.compatibility_flags ?? []}
+                        disabled={busy}
+                        onChange={(compatibility_flags) => updateManifest({ compatibility_flags })}
+                      />
+                      <VariableFields
+                        values={parsed.vars ?? {}}
+                        disabled={busy}
+                        onChange={(vars) => updateManifest({ vars })}
+                      />
+                      <StringList
+                        label="Required secret"
+                        hint={<>Names passed to the Worker on <code>env</code>. Deploying fails until each one has a value under Secrets.</>}
+                        placeholder="API_KEY"
+                        values={parsed.secrets ?? []}
+                        disabled={busy}
+                        onChange={(secrets) => updateManifest({ secrets })}
+                      />
+                    </>
+                  ) : (
+                    <p role="alert">Enter a valid manifest object below to use structured settings.</p>
+                  )}
+                  <details>
+                    <summary>Advanced manifest (JSON)</summary>
+                    <label>
+                      Manifest
+                      <textarea
+                        aria-label="Native Worker manifest"
+                        rows={16}
+                        value={manifest}
+                        disabled={busy}
+                        onChange={(event) => {
+                          setManifest(event.target.value);
+                          setDirty(true);
+                        }}
+                        className="worker-manifest"
+                      />
+                    </label>
+                  </details>
+                  <div className="settings-actions">{deployControls}</div>
+                </form>
+              </SettingsSection>
+              {selected ? (
+                <>
+                  <SettingsSection title="Secrets">
+                    <SecretControls
+                      key={selected.name}
+                      workspace={workspace}
+                      name={selected.name}
+                      kind="app"
+                      required={parsed ? (parsed.secrets ?? []).filter(Boolean) : undefined}
+                      onSaved={async () => {
+                        await onSaved();
+                        const saved = decode<Snapshot>(await galleryTool(workspace, "app_read", { name }));
+                        setSelected(saved);
+                      }}
                     />
-                  </>
-                ) : (
-                  <p role="alert">Enter a valid manifest object below to use structured settings.</p>
-                )}
-                <details>
-                  <summary>Advanced manifest (JSON)</summary>
-                  <label>
-                    Manifest
-                    <textarea
-                      aria-label="Native Worker manifest"
-                      rows={16}
-                      value={manifest}
-                      disabled={busy}
-                      onChange={(event) => {
-                        setManifest(event.target.value);
-                        setDirty(true);
+                  </SettingsSection>
+                  <SettingsSection title="Sharing">
+                    <LinkSettings
+                      key={`${selected.name}:link`}
+                      artifact={{ workspace, name: selected.name, kind: "app", slug: selected.slug, access: selected.access, url: selected.url }}
+                      onSaved={async () => {
+                        await onSaved();
+                        setSelected(decode<Snapshot>(await galleryTool(workspace, "app_read", { name })));
                       }}
-                      className="worker-manifest"
                     />
-                  </label>
-                </details>
-              </Tabs.Panel>
-              <div className="source-actions">
-                <button className="primary-action" disabled={busy || !valid || !provider || !parsed}>
-                  Save and deploy Worker
-                </button>
-                {dirty ? <span>Unsaved changes</span> : null}
-              </div>
-            </form>
-            {section === "settings" && selected ? (
-              <>
-                <h3>Secret values</h3>
-                <SecretControls
-                  key={selected.name}
-                  workspace={workspace}
-                  name={selected.name}
-                  kind="app"
-                  onSaved={async () => {
-                    await onSaved();
-                    const saved = decode<Snapshot>(await galleryTool(workspace, "app_read", { name }));
-                    setSelected(saved);
-                  }}
-                />
-                <h3>Link</h3>
-                <LinkSettings
-                  key={`${selected.name}:link`}
-                  artifact={{ workspace, name: selected.name, kind: "app", slug: selected.slug, access: selected.access, url: selected.url }}
-                  onSaved={async () => {
-                    await onSaved();
-                    setSelected(decode<Snapshot>(await galleryTool(workspace, "app_read", { name })));
-                  }}
-                />
-                <h3>Library</h3>
-                <button
-                  disabled={busy || dirty}
-                  onClick={() =>
-                    void perform(async () => {
-                      await galleryTool(workspace, "app_move", {
-                        name,
-                        library: library === "team" ? "private" : "team",
-                      });
-                      setSelected(null);
-                      setEditingNew(false);
-                      navigate(null);
-                      await onSaved();
-                    })
-                  }
-                >
-                  Move to {library === "team" ? "personal" : "team"} library
-                </button>
-              </>
-            ) : null}
+                  </SettingsSection>
+                  <SettingsSection
+                    title="Library"
+                    description={`In your ${library === "team" ? "team" : "personal"} library. Moving keeps its source history, resources, secrets and link, but this library loses access.`}
+                  >
+                    <div className="settings-actions">
+                      <button
+                        type="button"
+                        disabled={busy || dirty}
+                        onClick={() =>
+                          void perform(async () => {
+                            await galleryTool(workspace, "app_move", {
+                              name,
+                              library: library === "team" ? "private" : "team",
+                            });
+                            setSelected(null);
+                            setEditingNew(false);
+                            navigate(null);
+                            await onSaved();
+                          })
+                        }
+                      >
+                        Move to {library === "team" ? "personal" : "team"} library
+                      </button>
+                      {dirty ? <span className="muted">Deploy or discard your changes first.</span> : null}
+                    </div>
+                  </SettingsSection>
+                </>
+              ) : null}
+            </Tabs.Panel>
           </>
         ) : null}
       </div>
@@ -665,24 +711,40 @@ function isEditableManifest(value: unknown): value is AppManifest {
     (record(value.triggers) && strings(value.triggers.crons) && strings(value.triggers.queues))
   );
 }
+function SettingsSection({ title, description, children }: { title: string; description?: string; children: ReactNode }) {
+  return (
+    <section className="settings-section">
+      <h2>{title}</h2>
+      {description ? <p className="settings-description">{description}</p> : null}
+      {children}
+    </section>
+  );
+}
 function StringList({
   label,
+  hint,
+  placeholder,
   values,
   disabled,
   onChange,
 }: {
   label: string;
+  hint?: ReactNode;
+  placeholder?: string;
   values: string[];
   disabled: boolean;
   onChange: (values: string[]) => void;
 }) {
   return (
-    <fieldset disabled={disabled} style={{ border: 0, padding: "12px 0" }}>
+    <fieldset className="settings-list" disabled={disabled}>
       <legend>{label}s</legend>
+      {hint ? <p className="settings-hint">{hint}</p> : null}
       {values.map((value, index) => (
-        <div className="script-fields" key={index}>
+        <div className="settings-row" key={index}>
           <input
             aria-label={`${label} ${index + 1}`}
+            placeholder={placeholder}
+            spellCheck={false}
             value={value}
             onChange={(event) => onChange(values.map((item, i) => (i === index ? event.target.value : item)))}
           />
@@ -712,12 +774,15 @@ function VariableFields({
 }) {
   const rows = Object.entries(values);
   return (
-    <fieldset disabled={disabled} style={{ border: 0, padding: "12px 0" }}>
+    <fieldset className="settings-list" disabled={disabled}>
       <legend>Environment variables</legend>
+      <p className="settings-hint">Plain text, visible in the manifest. Use a secret for anything sensitive.</p>
       {rows.map(([name, value], index) => (
-        <div className="script-fields" key={index}>
+        <div className="settings-row variable-row" key={index}>
           <input
             aria-label={`Variable name ${index + 1}`}
+            placeholder="NAME"
+            spellCheck={false}
             value={name}
             onChange={(event) => {
               if (event.target.value !== name && Object.hasOwn(values, event.target.value)) return;
@@ -726,11 +791,17 @@ function VariableFields({
           />
           <input
             aria-label={`Variable value ${index + 1}`}
+            placeholder="value"
+            spellCheck={false}
             value={value}
             onChange={(event) => onChange({ ...values, [name]: event.target.value })}
           />
-          <button type="button" onClick={() => onChange(Object.fromEntries(rows.filter((_, i) => i !== index)))}>
-            Remove variable
+          <button
+            type="button"
+            aria-label={`Remove variable ${index + 1}`}
+            onClick={() => onChange(Object.fromEntries(rows.filter((_, i) => i !== index)))}
+          >
+            Remove
           </button>
         </div>
       ))}
diff --git a/src/gallery/secrets.tsx b/src/gallery/secrets.tsx
index 5f9aaff..20bf564 100644
--- a/src/gallery/secrets.tsx
+++ b/src/gallery/secrets.tsx
@@ -1,8 +1,9 @@
 import { useGalleryTransport } from "./transport";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { GalleryToolError } from "./hosted";
 
-export function SecretControls({ workspace, name, kind, onSaved, active = true }: { workspace: string; name: string; kind: "script" | "artifact" | "app"; onSaved?: () => Promise<void>; active?: boolean }) {
+// `required` lists declared secret names. Only those reach the runtime, so rows show which still need a value and which saved values go unused.
+export function SecretControls({ workspace, name, kind, required, onSaved, active = true }: { workspace: string; name: string; kind: "script" | "artifact" | "app"; required?: string[]; onSaved?: () => Promise<void>; active?: boolean }) {
   const { tool: galleryTool } = useGalleryTransport();
   const [secretName, setSecretName] = useState("");
   const [secretValue, setSecretValue] = useState("");
@@ -12,6 +13,8 @@ export function SecretControls({ workspace, name, kind, onSaved, active = true }
   const [busy, setBusy] = useState(false);
   const [loaded, setLoaded] = useState(false);
   const [confirmingRemove, setConfirmingRemove] = useState(false);
+  const valueInput = useRef<HTMLInputElement>(null);
+  const rows = loaded ? [...new Set([...(required ?? []), ...names])] : [];
   async function update(secrets?: Record<string, string | null>) {
     setBusy(true); setError(""); setStatus("");
     try {
@@ -21,7 +24,7 @@ export function SecretControls({ workspace, name, kind, onSaved, active = true }
       setLoaded(true);
       if (secrets) setSecretValue("");
       if (secrets && onSaved) await onSaved();
-      setStatus(secrets ? secrets[secretName] === null ? "Secret removed" : "Secret saved" : "Secret names loaded");
+      setStatus(!secrets ? "" : secrets[secretName] === null ? "Secret removed" : "Secret saved");
     } catch (error) {
       const result = error instanceof GalleryToolError ? error.result as { names?: string[] } | undefined : undefined;
       if (secrets && result?.names) {
@@ -34,18 +37,27 @@ export function SecretControls({ workspace, name, kind, onSaved, active = true }
   }
   useEffect(() => { if (active && !loaded) void update(); }, [active, workspace, name, kind]);
   return <section className="secret-controls" aria-label={kind === "script" ? "Script secrets" : kind === "app" ? "App secrets" : "Artifact secrets"}>
-    <p className="settings-description">Available to this {kind === "script" ? "script" : kind === "app" ? "native Worker" : "artifact server"} on the server. Saved values stay hidden.</p>
-    <div className="secret-list-header"><h3>Saved secrets</h3><button type="button" aria-label="Load secret names" disabled={busy} onClick={() => void update()}>Refresh</button></div>
+    <p className="settings-description">Available to this {kind === "script" ? "script" : kind === "app" ? "native Worker" : "artifact server"} on the server. Saved values stay hidden.{kind === "app" ? " Saving a secret redeploys the current revision." : ""}</p>
+    <div className="secret-list-header"><h3>{required ? "Secret values" : "Saved secrets"}</h3><button type="button" aria-label="Load secret names" disabled={busy} onClick={() => void update()}>Refresh</button></div>
     <ul className="secret-list" aria-label="Secret names" aria-busy={busy}>
-      {names.map(name => <li key={name}><code>{name}</code><button type="button" disabled={busy} onClick={() => { setSecretName(name); setSecretValue(""); setConfirmingRemove(false); }}>Replace</button></li>)}
-      {!names.length ? <li className="muted">{loaded ? "No secrets saved yet." : "Loading secrets…"}</li> : null}
+      {rows.map(name => {
+        const saved = names.includes(name);
+        return <li key={name}>
+          <span className="secret-name"><code>{name}</code>
+            {!saved ? <span className="secret-state"><span className="status-dot" data-tone="warning" aria-hidden="true" />Needs a value</span> : null}
+            {saved && required && !required.includes(name) ? <span className="secret-state">Not passed to the Worker</span> : null}
+          </span>
+          <button type="button" disabled={busy} onClick={() => { setSecretName(name); setSecretValue(""); setConfirmingRemove(false); valueInput.current?.focus(); }}>{saved ? "Replace" : "Set value"}</button>
+        </li>;
+      })}
+      {!rows.length ? <li className="muted">{loaded ? "No secrets saved yet." : "Loading secrets…"}</li> : null}
     </ul>
     <form onSubmit={event => { event.preventDefault(); void update({ [secretName]: secretValue }); }}>
       <fieldset disabled={busy}>
         <legend>{names.includes(secretName) ? "Replace secret" : "Add a secret"}</legend>
         <div className="settings-fields">
           <label>Name<input aria-label="Secret name" placeholder="API_KEY" required autoComplete="off" spellCheck={false} value={secretName} onChange={event => { setSecretName(event.target.value); setConfirmingRemove(false); }} /></label>
-          <label>Value<input aria-label="Secret value" placeholder="Enter a secret value" type="password" autoComplete="new-password" value={secretValue} onChange={event => setSecretValue(event.target.value)} /></label>
+          <label>Value<input ref={valueInput} aria-label="Secret value" placeholder="Enter a secret value" type="password" autoComplete="new-password" value={secretValue} onChange={event => setSecretValue(event.target.value)} /></label>
         </div>
         <div className="settings-actions">
           <button className="primary-action" disabled={busy}>Save secret</button>
@@ -53,7 +65,7 @@ export function SecretControls({ workspace, name, kind, onSaved, active = true }
             <span className="confirm-prompt">Remove {secretName}?</span>
             <button className="destructive-action confirm" type="button" disabled={busy} onClick={() => { setConfirmingRemove(false); void update({ [secretName]: null }); }}>Remove</button>
             <button type="button" disabled={busy} onClick={() => setConfirmingRemove(false)}>Cancel</button>
-          </> : <button className="destructive-action" type="button" disabled={busy || !names.includes(secretName)} onClick={() => setConfirmingRemove(true)}>Remove secret</button>}
+          </> : names.includes(secretName) ? <button className="destructive-action" type="button" disabled={busy} onClick={() => setConfirmingRemove(true)}>Remove secret</button> : null}
         </div>
       </fieldset>
     </form>
diff --git a/src/gallery/styles.ts b/src/gallery/styles.ts
index 143e858..547ae58 100644
--- a/src/gallery/styles.ts
+++ b/src/gallery/styles.ts
@@ -117,6 +117,7 @@ export const galleryStyles = `
   .link-note { flex-basis: 100%; margin: 0; color: var(--muted); font-size: 12px; }
   .link-settings [role="status"] { align-self: center; }
   .link-settings .muted { font-size: 12px; }
+  .link-settings > p { flex-basis: 100%; margin: 0; }
   .script-panel { display: flex; flex-direction: column; flex: 1; width: 100%; min-width: 0; min-height: 0; overflow: hidden; }
   .source-form { display: flex; flex-direction: column; flex: 1; min-width: 0; min-height: 0; }
   .source-form > .script-fields { padding: 12px 16px; border-bottom: 1px solid var(--line); flex-shrink: 0; }
@@ -299,6 +300,8 @@ export const galleryStyles = `
   .secret-list li { display: flex; align-items: center; justify-content: space-between; gap: 12px; min-height: 44px; padding: 8px 12px; }
   .secret-list li + li { border-top: 1px solid var(--line); }
   .secret-list code { min-width: 0; overflow-wrap: anywhere; font-size: 12px; }
+  .secret-name { display: flex; flex-wrap: wrap; align-items: center; gap: 2px 12px; min-width: 0; }
+  .secret-state { display: inline-flex; align-items: center; gap: 6px; color: var(--muted); font-size: 12px; }
   .secret-list button { height: 28px; min-height: 28px; font-size: 12px; }
   .secret-controls fieldset { margin: 0; padding: 0; border: 0; min-width: 0; }
   .secret-controls legend { padding: 0; margin-bottom: 12px; font-size: 12px; font-weight: 600; }