From 37a8c979d5cded8c94f5857f1edeaf77dc8b53cc Mon Sep 17 00:00:00 2001
From: River <river@shopify.com>
Date: Tue, 18 Aug 2026 20:05:29 +0000
Subject: [PATCH 1/3] feat: Add Prototype Banner settings panel

Banner content comes from the backend instead of a frontend deploy. Banners
are stored in user settings under the `system:web_ui/banners` key as a
newest-first list of `{iso_timestamp: banner_text}`.

Settings -> Prototype Banner (below AI Configuration) saves a new banner,
shows the latest one, and lists the full history. Writes go through
`PATCH /api/users/me/settings`, reads through `GET /api/users/me/settings`.

Prototype scope: `/api/users/me/settings` keys the row by the authenticated
caller, so a banner is visible only to the person who saved it. A
server-pinned route reading the same key for `system:web_ui` makes it global
without client changes beyond the URL.

Requested by Yue Chao Qin <yuechao.qin@shopify.com>

Co-authored-by: Yue Chao Qin <yuechao.qin@shopify.com>
---
 src/routes/Settings/SettingsLayout.tsx        |  16 +-
 .../sections/PrototypeBannerSettings.tsx      | 169 ++++++++++++++++++
 .../sections/prototypeBanners.test.ts         |  56 ++++++
 .../Settings/sections/prototypeBanners.ts     | 124 +++++++++++++
 src/routes/appRoutes.ts                       |   1 +
 src/routes/router.ts                          |   8 +
 src/utils/constants.ts                        |   4 +
 7 files changed, 374 insertions(+), 4 deletions(-)
 create mode 100644 src/routes/Settings/sections/PrototypeBannerSettings.tsx
 create mode 100644 src/routes/Settings/sections/prototypeBanners.test.ts
 create mode 100644 src/routes/Settings/sections/prototypeBanners.ts

diff --git a/src/routes/Settings/SettingsLayout.tsx b/src/routes/Settings/SettingsLayout.tsx
index db1e04704b..3697d2738e 100644
--- a/src/routes/Settings/SettingsLayout.tsx
+++ b/src/routes/Settings/SettingsLayout.tsx
@@ -50,14 +50,22 @@ const AGENT_ITEM: SidebarItem = {
   testId: "settings-nav-agent",
 };
 
+const PROTOTYPE_BANNER_ITEM: SidebarItem = {
+  to: "/settings/prototype-banner",
+  label: "Prototype Banner",
+  icon: "Megaphone",
+  testId: "settings-nav-prototype-banner",
+};
+
 export function SettingsLayout() {
   const router = useRouter();
   const componentSearchEnabled = useFlagValue("component-search-v2");
   const aiAssistantEnabled = useFlagValue("ai-assistant");
-  const sidebarItems =
-    componentSearchEnabled || aiAssistantEnabled
-      ? [...SIDEBAR_ITEMS, AGENT_ITEM]
-      : SIDEBAR_ITEMS;
+  const sidebarItems = [
+    ...SIDEBAR_ITEMS,
+    ...(componentSearchEnabled || aiAssistantEnabled ? [AGENT_ITEM] : []),
+    PROTOTYPE_BANNER_ITEM,
+  ];
 
   const handleGoBack = () => {
     router.history.back();
diff --git a/src/routes/Settings/sections/PrototypeBannerSettings.tsx b/src/routes/Settings/sections/PrototypeBannerSettings.tsx
new file mode 100644
index 0000000000..673fc2e20e
--- /dev/null
+++ b/src/routes/Settings/sections/PrototypeBannerSettings.tsx
@@ -0,0 +1,169 @@
+import { useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import { Icon } from "@/components/ui/icon";
+import { BlockStack, InlineStack } from "@/components/ui/layout";
+import { Separator } from "@/components/ui/separator";
+import { Textarea } from "@/components/ui/textarea";
+import { Heading, Paragraph, Text } from "@/components/ui/typography";
+import useToastNotification from "@/hooks/useToastNotification";
+import { useBackend } from "@/providers/BackendProvider";
+import { SYSTEM_UI_USER_ID } from "@/utils/constants";
+
+import {
+  bannerText,
+  bannerTimestamp,
+  latestBanner,
+  type PrototypeBanner,
+  usePrototypeBanners,
+  useSavePrototypeBanner,
+} from "./prototypeBanners";
+
+function formatTimestamp(timestamp: string): string {
+  const date = new Date(timestamp);
+  return Number.isNaN(date.getTime()) ? timestamp : date.toLocaleString();
+}
+
+function BannerRow({ banner }: { banner: PrototypeBanner }) {
+  return (
+    <BlockStack gap="1">
+      <Text size="xs" tone="subdued">
+        {formatTimestamp(bannerTimestamp(banner))}
+      </Text>
+      <Text size="sm">{bannerText(banner)}</Text>
+    </BlockStack>
+  );
+}
+
+/**
+ * Prototype panel for banner content served from the backend instead of a
+ * frontend deploy. Banners are stored as one JSON list in user settings under
+ * the `system:web_ui` namespace.
+ */
+export function PrototypeBannerSettings() {
+  const notify = useToastNotification();
+  const { available } = useBackend();
+  const [draft, setDraft] = useState("");
+
+  const {
+    data: banners = [],
+    isLoading,
+    isFetching,
+    error,
+    refetch,
+  } = usePrototypeBanners();
+  const { mutate: saveBanner, isPending } = useSavePrototypeBanner();
+
+  const latest = latestBanner(banners);
+  const trimmedDraft = draft.trim();
+
+  const handleSave = () => {
+    if (!trimmedDraft) return;
+
+    saveBanner(trimmedDraft, {
+      onSuccess: () => {
+        setDraft("");
+        notify("Banner saved", "success");
+      },
+      onError: (saveError) => {
+        notify(`Failed to save banner: ${saveError.message}`, "error");
+      },
+    });
+  };
+
+  return (
+    <BlockStack gap="4">
+      <BlockStack gap="2">
+        <Heading level={2}>Prototype Banner</Heading>
+        <Paragraph tone="subdued" size="sm">
+          Store banner text in the backend so it can change without a frontend
+          deploy. Banners are kept as a history list under the{" "}
+          <code>{SYSTEM_UI_USER_ID}</code> settings namespace.
+        </Paragraph>
+      </BlockStack>
+
+      <Separator />
+
+      {!available ? (
+        <Paragraph tone="subdued" size="sm">
+          Connect a backend to read and write banners.
+        </Paragraph>
+      ) : (
+        <BlockStack gap="4">
+          <BlockStack gap="2">
+            <InlineStack gap="2" blockAlign="center">
+              <Text weight="semibold">Latest banner</Text>
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => refetch()}
+                disabled={isFetching}
+                data-testid="prototype-banner-refresh"
+              >
+                <Icon name="RefreshCw" size="sm" />
+              </Button>
+            </InlineStack>
+            <div data-testid="prototype-banner-latest">
+              {isLoading ? (
+                <Text size="sm" tone="subdued">
+                  Loading…
+                </Text>
+              ) : error ? (
+                <Text size="sm" tone="critical">
+                  {error.message}
+                </Text>
+              ) : latest ? (
+                <BannerRow banner={latest} />
+              ) : (
+                <Text size="sm" tone="subdued">
+                  No banners yet.
+                </Text>
+              )}
+            </div>
+          </BlockStack>
+
+          <Separator />
+
+          <BlockStack gap="2">
+            <Text weight="semibold">New banner</Text>
+            <Textarea
+              value={draft}
+              onChange={(event) => setDraft(event.target.value)}
+              placeholder="Runs are delayed while we recover a cluster."
+              rows={3}
+              data-testid="prototype-banner-input"
+            />
+            <InlineStack>
+              <Button
+                onClick={handleSave}
+                disabled={!trimmedDraft || isPending}
+                data-testid="prototype-banner-save"
+              >
+                Save banner
+              </Button>
+            </InlineStack>
+          </BlockStack>
+
+          <Separator />
+
+          <BlockStack gap="2">
+            <Text weight="semibold">History ({banners.length})</Text>
+            <div className="w-full" data-testid="prototype-banner-history">
+              {banners.length === 0 ? (
+                <Text size="sm" tone="subdued">
+                  Saved banners appear here, newest first.
+                </Text>
+              ) : (
+                <BlockStack gap="3">
+                  {banners.map((banner) => (
+                    <BannerRow key={bannerTimestamp(banner)} banner={banner} />
+                  ))}
+                </BlockStack>
+              )}
+            </div>
+          </BlockStack>
+        </BlockStack>
+      )}
+    </BlockStack>
+  );
+}
diff --git a/src/routes/Settings/sections/prototypeBanners.test.ts b/src/routes/Settings/sections/prototypeBanners.test.ts
new file mode 100644
index 0000000000..0db62f1d4c
--- /dev/null
+++ b/src/routes/Settings/sections/prototypeBanners.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  bannerText,
+  bannerTimestamp,
+  latestBanner,
+  parseBanners,
+  withNewBanner,
+} from "./prototypeBanners";
+
+const OLD = { "2026-01-01T00:00:00.000Z": "old banner" };
+const NEW = { "2026-03-01T00:00:00.000Z": "new banner" };
+
+describe("parseBanners", () => {
+  it("sorts newest first", () => {
+    expect(parseBanners([OLD, NEW])).toEqual([NEW, OLD]);
+  });
+
+  it("drops entries that are not single-entry string maps", () => {
+    expect(
+      parseBanners([OLD, null, "text", [], {}, { a: "1", b: "2" }, { c: 3 }]),
+    ).toEqual([OLD]);
+  });
+
+  it("returns an empty list for anything that is not an array", () => {
+    expect(parseBanners(undefined)).toEqual([]);
+    expect(parseBanners({ "2026-01-01T00:00:00.000Z": "x" })).toEqual([]);
+  });
+});
+
+describe("withNewBanner", () => {
+  it("prepends the new banner", () => {
+    const now = new Date("2026-06-01T00:00:00.000Z");
+    const banners = withNewBanner([NEW, OLD], "latest banner", now);
+
+    expect(banners).toEqual([
+      { "2026-06-01T00:00:00.000Z": "latest banner" },
+      NEW,
+      OLD,
+    ]);
+  });
+});
+
+describe("latestBanner", () => {
+  it("returns the newest banner and its parts", () => {
+    const latest = latestBanner(parseBanners([OLD, NEW]));
+
+    expect(latest).toEqual(NEW);
+    expect(bannerTimestamp(latest!)).toBe("2026-03-01T00:00:00.000Z");
+    expect(bannerText(latest!)).toBe("new banner");
+  });
+
+  it("returns undefined when there are no banners", () => {
+    expect(latestBanner([])).toBeUndefined();
+  });
+});
diff --git a/src/routes/Settings/sections/prototypeBanners.ts b/src/routes/Settings/sections/prototypeBanners.ts
new file mode 100644
index 0000000000..d602acd880
--- /dev/null
+++ b/src/routes/Settings/sections/prototypeBanners.ts
@@ -0,0 +1,124 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import { useBackend } from "@/providers/BackendProvider";
+import {
+  PROTOTYPE_BANNERS_SETTING_NAME,
+  USER_SETTINGS_PATH,
+} from "@/utils/constants";
+import { fetchWithErrorHandling } from "@/utils/fetchWithErrorHandling";
+
+/**
+ * One banner is a single-entry map of ISO timestamp to banner text:
+ * `{ "2026-05-01T12:00:00.000Z": "Runs are delayed" }`.
+ *
+ * The stored setting is a list of those, newest first, so the whole banner
+ * history lives in one JSON value under the
+ * `PROTOTYPE_BANNERS_SETTING_NAME` key.
+ */
+export type PrototypeBanner = Record<string, string>;
+
+const QUERY_KEY = "prototypeBanners";
+
+export function bannerTimestamp(banner: PrototypeBanner): string {
+  return Object.keys(banner)[0] ?? "";
+}
+
+export function bannerText(banner: PrototypeBanner): string {
+  return Object.values(banner)[0] ?? "";
+}
+
+function sortNewestFirst(banners: PrototypeBanner[]): PrototypeBanner[] {
+  return [...banners].sort((a, b) =>
+    bannerTimestamp(b).localeCompare(bannerTimestamp(a)),
+  );
+}
+
+/** Keeps only single-entry string maps, sorted newest first. */
+export function parseBanners(value: unknown): PrototypeBanner[] {
+  if (!Array.isArray(value)) return [];
+
+  const banners: PrototypeBanner[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      continue;
+    }
+    const pairs = Object.entries(entry as Record<string, unknown>);
+    if (pairs.length !== 1) continue;
+    const [timestamp, text] = pairs[0];
+    if (!timestamp || typeof text !== "string") continue;
+    banners.push({ [timestamp]: text });
+  }
+  return sortNewestFirst(banners);
+}
+
+export function withNewBanner(
+  banners: PrototypeBanner[],
+  text: string,
+  now: Date = new Date(),
+): PrototypeBanner[] {
+  return sortNewestFirst([{ [now.toISOString()]: text }, ...banners]);
+}
+
+export function latestBanner(
+  banners: PrototypeBanner[],
+): PrototypeBanner | undefined {
+  return banners[0];
+}
+
+function extractBanners(payload: unknown): PrototypeBanner[] {
+  if (typeof payload !== "object" || payload === null) return [];
+  const record = payload as Record<string, unknown>;
+  const settings = record.settings as Record<string, unknown> | undefined;
+  return parseBanners(
+    record[PROTOTYPE_BANNERS_SETTING_NAME] ??
+      settings?.[PROTOTYPE_BANNERS_SETTING_NAME],
+  );
+}
+
+async function fetchBanners(backendUrl: string): Promise<PrototypeBanner[]> {
+  const url = new URL(USER_SETTINGS_PATH, backendUrl);
+  url.searchParams.set("setting_names", PROTOTYPE_BANNERS_SETTING_NAME);
+  return extractBanners(await fetchWithErrorHandling(url.toString()));
+}
+
+function queryKey(backendUrl: string) {
+  return [QUERY_KEY, backendUrl] as const;
+}
+
+export function usePrototypeBanners() {
+  const { available, backendUrl } = useBackend();
+
+  return useQuery({
+    queryKey: queryKey(backendUrl),
+    queryFn: () => fetchBanners(backendUrl),
+    enabled: available && Boolean(backendUrl),
+    refetchOnWindowFocus: false,
+  });
+}
+
+/**
+ * Appends a banner. The settings API merges top-level keys only, so the list
+ * is read, extended and written back as a whole value.
+ */
+export function useSavePrototypeBanner() {
+  const queryClient = useQueryClient();
+  const { backendUrl } = useBackend();
+
+  return useMutation({
+    mutationFn: async (text: string) => {
+      const next = withNewBanner(await fetchBanners(backendUrl), text);
+      const url = new URL(USER_SETTINGS_PATH, backendUrl);
+      await fetchWithErrorHandling(url.toString(), {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          settings: { [PROTOTYPE_BANNERS_SETTING_NAME]: next },
+        }),
+      });
+      return next;
+    },
+    onSuccess: (next) => {
+      queryClient.setQueryData(queryKey(backendUrl), next);
+    },
+  });
+}
diff --git a/src/routes/appRoutes.ts b/src/routes/appRoutes.ts
index f278ca6a10..3941f0d83d 100644
--- a/src/routes/appRoutes.ts
+++ b/src/routes/appRoutes.ts
@@ -36,6 +36,7 @@ export const APP_ROUTES = {
   SETTINGS_SECRETS: `${SETTINGS_PATH}/secrets`,
   SETTINGS_SECRETS_ADD: `${SETTINGS_PATH}/secrets/add`,
   SETTINGS_SECRETS_REPLACE: `${SETTINGS_PATH}/secrets/$secretId/replace`,
+  SETTINGS_PROTOTYPE_BANNER: `${SETTINGS_PATH}/prototype-banner`,
   GITHUB_AUTH_CALLBACK: "/authorize/github",
   HUGGINGFACE_AUTH_CALLBACK: "/authorize/huggingface",
   EDITOR_V2: EDITOR_V2_BASE_PATH,
diff --git a/src/routes/router.ts b/src/routes/router.ts
index e5c07d9c1e..879449aadf 100644
--- a/src/routes/router.ts
+++ b/src/routes/router.ts
@@ -42,6 +42,7 @@ import { AgentSettings } from "./Settings/sections/AgentSettings";
 import { BackendSettings } from "./Settings/sections/BackendSettings";
 import { BetaFeaturesSettings } from "./Settings/sections/BetaFeaturesSettings";
 import { PreferencesSettings } from "./Settings/sections/PreferencesSettings";
+import { PrototypeBannerSettings } from "./Settings/sections/PrototypeBannerSettings";
 import { SecretsSettings } from "./Settings/sections/SecretsSettings";
 import { SettingsLayout } from "./Settings/SettingsLayout";
 import { EditorV2 } from "./v2/pages/Editor/EditorV2";
@@ -232,6 +233,12 @@ const settingsSecretsRoute = createRoute({
   component: SecretsSettings,
 });
 
+const settingsPrototypeBannerRoute = createRoute({
+  getParentRoute: () => settingsLayoutRoute,
+  path: "/prototype-banner",
+  component: PrototypeBannerSettings,
+});
+
 const secretsIndexRoute = createRoute({
   getParentRoute: () => settingsSecretsRoute,
   path: "/",
@@ -302,6 +309,7 @@ const settingsRouteTree = settingsLayoutRoute.addChildren([
   settingsPreferencesRoute,
   settingsBetaFeaturesRoute,
   settingsAgentRoute,
+  settingsPrototypeBannerRoute,
   secretsRouteTree,
 ]);
 
diff --git a/src/utils/constants.ts b/src/utils/constants.ts
index d2cbe36dac..1008290020 100644
--- a/src/utils/constants.ts
+++ b/src/utils/constants.ts
@@ -22,6 +22,10 @@ export const API_URL = import.meta.env.VITE_BACKEND_API_URL || "";
 export const BASE_URL = import.meta.env.VITE_BASE_URL || "/";
 
 export const USER_SETTINGS_PATH = "/api/users/me/settings";
+
+/** Settings namespace for values owned by the UI rather than by a person. */
+export const SYSTEM_UI_USER_ID = "system:web_ui";
+export const PROTOTYPE_BANNERS_SETTING_NAME = `${SYSTEM_UI_USER_ID}/banners`;
 export const IS_GITHUB_PAGES = import.meta.env.VITE_GITHUB_PAGES === "true";
 
 export const GIT_REPO_URL =

From db3412cddf3996effcfa53ec89552700e73dbf63 Mon Sep 17 00:00:00 2001
From: Yue Chao Qin <yuechao.qin@shopify.com>
Date: Tue, 18 Aug 2026 13:25:56 -0700
Subject: [PATCH 2/3] test: cover banner settings round-trip and panel
 interactions

Adds hook-level tests for the settings read/write (query params, both
payload shapes, read-modify-write) and panel tests for latest/history
rendering, save, error and refresh. Keys history rows by index too, since
two banners can share a timestamp.

Assisted-By: devx/18a6bbd2-5972-4e08-ad51-c91f9713b20c
---
 .../sections/PrototypeBannerSettings.test.tsx | 198 ++++++++++++++++++
 .../sections/PrototypeBannerSettings.tsx      |   9 +-
 .../sections/prototypeBannersBackend.test.tsx | 176 ++++++++++++++++
 3 files changed, 381 insertions(+), 2 deletions(-)
 create mode 100644 src/routes/Settings/sections/PrototypeBannerSettings.test.tsx
 create mode 100644 src/routes/Settings/sections/prototypeBannersBackend.test.tsx

diff --git a/src/routes/Settings/sections/PrototypeBannerSettings.test.tsx b/src/routes/Settings/sections/PrototypeBannerSettings.test.tsx
new file mode 100644
index 0000000000..e8caa1f74b
--- /dev/null
+++ b/src/routes/Settings/sections/PrototypeBannerSettings.test.tsx
@@ -0,0 +1,198 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { PrototypeBannerSettings } from "./PrototypeBannerSettings";
+
+const SETTING_NAME = "system:web_ui/banners";
+
+const fetchWithErrorHandling = vi.hoisted(() =>
+  vi.fn<(url: string, options?: RequestInit) => Promise<unknown>>(() =>
+    Promise.resolve({}),
+  ),
+);
+const mockNotify = vi.hoisted(() => vi.fn());
+
+vi.mock("@/utils/fetchWithErrorHandling", () => ({
+  fetchWithErrorHandling: (url: string, options?: RequestInit) =>
+    fetchWithErrorHandling(url, options),
+}));
+
+vi.mock("@/hooks/useToastNotification", () => ({
+  default: () => mockNotify,
+}));
+
+let backend = { available: true, backendUrl: "https://backend.example" };
+
+vi.mock("@/providers/BackendProvider", () => ({
+  useBackend: () => backend,
+}));
+
+function renderPanel() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <PrototypeBannerSettings />
+    </QueryClientProvider>,
+  );
+}
+
+function typeDraft(text: string) {
+  fireEvent.change(screen.getByTestId("prototype-banner-input"), {
+    target: { value: text },
+  });
+}
+
+function patchCalls() {
+  return fetchWithErrorHandling.mock.calls.filter(
+    ([, options]) => options?.method === "PATCH",
+  );
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  fetchWithErrorHandling.mockResolvedValue({});
+  backend = { available: true, backendUrl: "https://backend.example" };
+});
+
+describe("PrototypeBannerSettings", () => {
+  it("shows the newest banner as the latest and the rest as history", async () => {
+    fetchWithErrorHandling.mockResolvedValue({
+      [SETTING_NAME]: [
+        { "2026-01-01T00:00:00.000Z": "older banner" },
+        { "2026-03-01T00:00:00.000Z": "newest banner" },
+      ],
+    });
+
+    renderPanel();
+
+    await waitFor(() =>
+      expect(screen.getByTestId("prototype-banner-latest")).toHaveTextContent(
+        "newest banner",
+      ),
+    );
+    expect(screen.getByTestId("prototype-banner-latest")).not.toHaveTextContent(
+      "older banner",
+    );
+
+    const history = screen.getByTestId("prototype-banner-history");
+    expect(history).toHaveTextContent("newest banner");
+    expect(history).toHaveTextContent("older banner");
+    expect(screen.getByText("History (2)")).toBeInTheDocument();
+  });
+
+  it("saves a trimmed banner, clears the draft and confirms", async () => {
+    renderPanel();
+    await waitFor(() =>
+      expect(screen.getByTestId("prototype-banner-latest")).toHaveTextContent(
+        "No banners yet.",
+      ),
+    );
+
+    typeDraft("  runs are delayed  ");
+    fireEvent.click(screen.getByTestId("prototype-banner-save"));
+
+    await waitFor(() => expect(patchCalls()).toHaveLength(1));
+    const saved = JSON.parse(patchCalls()[0][1]?.body as string).settings[
+      SETTING_NAME
+    ];
+    expect(Object.values(saved[0])).toEqual(["runs are delayed"]);
+
+    await waitFor(() =>
+      expect(screen.getByTestId("prototype-banner-input")).toHaveValue(""),
+    );
+    expect(mockNotify).toHaveBeenCalledWith("Banner saved", "success");
+    // The saved banner is the new latest without a reload.
+    expect(screen.getByTestId("prototype-banner-latest")).toHaveTextContent(
+      "runs are delayed",
+    );
+  });
+
+  it("does not save a whitespace-only draft", async () => {
+    renderPanel();
+    await waitFor(() =>
+      expect(screen.getByTestId("prototype-banner-save")).toBeDisabled(),
+    );
+
+    typeDraft("   ");
+
+    expect(screen.getByTestId("prototype-banner-save")).toBeDisabled();
+    expect(patchCalls()).toHaveLength(0);
+  });
+
+  it("reports a failed save instead of clearing the draft", async () => {
+    fetchWithErrorHandling.mockImplementation((_url, options) =>
+      options?.method === "PATCH"
+        ? Promise.reject(new Error("backend said no"))
+        : Promise.resolve({}),
+    );
+
+    renderPanel();
+    typeDraft("will fail");
+    fireEvent.click(screen.getByTestId("prototype-banner-save"));
+
+    await waitFor(() =>
+      expect(mockNotify).toHaveBeenCalledWith(
+        "Failed to save banner: backend said no",
+        "error",
+      ),
+    );
+    expect(screen.getByTestId("prototype-banner-input")).toHaveValue(
+      "will fail",
+    );
+  });
+
+  it("re-reads the banners when refreshed", async () => {
+    fetchWithErrorHandling.mockResolvedValueOnce({
+      [SETTING_NAME]: [{ "2026-03-01T00:00:00.000Z": "first read" }],
+    });
+    fetchWithErrorHandling.mockResolvedValueOnce({
+      [SETTING_NAME]: [{ "2026-04-01T00:00:00.000Z": "second read" }],
+    });
+
+    renderPanel();
+    await waitFor(() =>
+      expect(screen.getByTestId("prototype-banner-latest")).toHaveTextContent(
+        "first read",
+      ),
+    );
+
+    fireEvent.click(screen.getByTestId("prototype-banner-refresh"));
+
+    await waitFor(() =>
+      expect(screen.getByTestId("prototype-banner-latest")).toHaveTextContent(
+        "second read",
+      ),
+    );
+  });
+
+  it("renders every banner when two share a timestamp", async () => {
+    const sameTs = "2026-03-01T00:00:00.000Z";
+    fetchWithErrorHandling.mockResolvedValue({
+      [SETTING_NAME]: [{ [sameTs]: "banner A" }, { [sameTs]: "banner B" }],
+    });
+
+    renderPanel();
+
+    await waitFor(() =>
+      expect(screen.getByText("History (2)")).toBeInTheDocument(),
+    );
+    const history = screen.getByTestId("prototype-banner-history");
+    expect(history).toHaveTextContent("banner A");
+    expect(history).toHaveTextContent("banner B");
+  });
+
+  it("asks for a backend instead of reading settings when none is connected", () => {
+    backend = { available: false, backendUrl: "" };
+
+    renderPanel();
+
+    expect(
+      screen.getByText("Connect a backend to read and write banners."),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("prototype-banner-input")).toBeNull();
+    expect(fetchWithErrorHandling).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/routes/Settings/sections/PrototypeBannerSettings.tsx b/src/routes/Settings/sections/PrototypeBannerSettings.tsx
index 673fc2e20e..2f08a1ce98 100644
--- a/src/routes/Settings/sections/PrototypeBannerSettings.tsx
+++ b/src/routes/Settings/sections/PrototypeBannerSettings.tsx
@@ -155,8 +155,13 @@ export function PrototypeBannerSettings() {
                 </Text>
               ) : (
                 <BlockStack gap="3">
-                  {banners.map((banner) => (
-                    <BannerRow key={bannerTimestamp(banner)} banner={banner} />
+                  {banners.map((banner, index) => (
+                    // Two banners can share a timestamp, so the index keeps
+                    // the key unique.
+                    <BannerRow
+                      key={`${bannerTimestamp(banner)}-${index}`}
+                      banner={banner}
+                    />
                   ))}
                 </BlockStack>
               )}
diff --git a/src/routes/Settings/sections/prototypeBannersBackend.test.tsx b/src/routes/Settings/sections/prototypeBannersBackend.test.tsx
new file mode 100644
index 0000000000..a64f5df83d
--- /dev/null
+++ b/src/routes/Settings/sections/prototypeBannersBackend.test.tsx
@@ -0,0 +1,176 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  usePrototypeBanners,
+  useSavePrototypeBanner,
+} from "./prototypeBanners";
+
+const SETTING_NAME = "system:web_ui/banners";
+
+const fetchWithErrorHandling = vi.hoisted(() =>
+  vi.fn<(url: string, options?: RequestInit) => Promise<unknown>>(() =>
+    Promise.resolve({}),
+  ),
+);
+
+vi.mock("@/utils/fetchWithErrorHandling", () => ({
+  fetchWithErrorHandling: (url: string, options?: RequestInit) =>
+    fetchWithErrorHandling(url, options),
+}));
+
+let backend = { available: true, backendUrl: "https://backend.example" };
+
+vi.mock("@/providers/BackendProvider", () => ({
+  useBackend: () => backend,
+}));
+
+function makeWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+function renderBanners() {
+  return renderHook(
+    () => ({
+      query: usePrototypeBanners(),
+      save: useSavePrototypeBanner(),
+    }),
+    { wrapper: makeWrapper() },
+  );
+}
+
+function patchCalls() {
+  return fetchWithErrorHandling.mock.calls.filter(
+    ([, options]) => options?.method === "PATCH",
+  );
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  fetchWithErrorHandling.mockResolvedValue({});
+  backend = { available: true, backendUrl: "https://backend.example" };
+});
+
+describe("usePrototypeBanners", () => {
+  it("asks the settings endpoint for the banners key only", async () => {
+    const { result } = renderBanners();
+
+    await waitFor(() => expect(result.current.query.isSuccess).toBe(true));
+
+    const url = new URL(fetchWithErrorHandling.mock.calls[0][0]);
+    expect(url.origin + url.pathname).toBe(
+      "https://backend.example/api/users/me/settings",
+    );
+    expect(url.searchParams.get("setting_names")).toBe(SETTING_NAME);
+  });
+
+  it("reads banners newest-first from a top-level payload", async () => {
+    fetchWithErrorHandling.mockResolvedValueOnce({
+      [SETTING_NAME]: [
+        { "2026-01-01T00:00:00.000Z": "old" },
+        { "2026-03-01T00:00:00.000Z": "new" },
+      ],
+    });
+
+    const { result } = renderBanners();
+
+    await waitFor(() =>
+      expect(result.current.query.data).toEqual([
+        { "2026-03-01T00:00:00.000Z": "new" },
+        { "2026-01-01T00:00:00.000Z": "old" },
+      ]),
+    );
+  });
+
+  it("reads banners from a payload wrapped in `settings`", async () => {
+    fetchWithErrorHandling.mockResolvedValueOnce({
+      settings: { [SETTING_NAME]: [{ "2026-03-01T00:00:00.000Z": "new" }] },
+    });
+
+    const { result } = renderBanners();
+
+    await waitFor(() =>
+      expect(result.current.query.data).toEqual([
+        { "2026-03-01T00:00:00.000Z": "new" },
+      ]),
+    );
+  });
+
+  it("does not call the backend when none is available", async () => {
+    backend = { available: false, backendUrl: "" };
+
+    renderBanners();
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(fetchWithErrorHandling).not.toHaveBeenCalled();
+  });
+});
+
+describe("useSavePrototypeBanner", () => {
+  it("PATCHes the whole list with the new banner first", async () => {
+    fetchWithErrorHandling.mockResolvedValue({
+      [SETTING_NAME]: [{ "2026-01-01T00:00:00.000Z": "old" }],
+    });
+
+    const { result } = renderBanners();
+    await waitFor(() => expect(result.current.query.isSuccess).toBe(true));
+
+    act(() => result.current.save.mutate("fresh banner"));
+    await waitFor(() => expect(patchCalls()).toHaveLength(1));
+
+    const [url, options] = patchCalls()[0];
+    expect(url).toBe("https://backend.example/api/users/me/settings");
+    const saved = JSON.parse(options?.body as string).settings[SETTING_NAME];
+    expect(Object.values(saved[0])).toEqual(["fresh banner"]);
+    expect(saved[1]).toEqual({ "2026-01-01T00:00:00.000Z": "old" });
+  });
+
+  it("re-reads the server list before writing, so a concurrent banner survives", async () => {
+    // Cache is cold/stale: the server already holds a banner this client
+    // never read. A blind write would drop it.
+    fetchWithErrorHandling.mockImplementation((_url, options) => {
+      if (options?.method === "PATCH") return Promise.resolve({});
+      return Promise.resolve({
+        [SETTING_NAME]: [{ "2026-02-01T00:00:00.000Z": "saved elsewhere" }],
+      });
+    });
+
+    const { result } = renderHook(() => useSavePrototypeBanner(), {
+      wrapper: makeWrapper(),
+    });
+
+    act(() => result.current.mutate("mine"));
+    await waitFor(() => expect(patchCalls()).toHaveLength(1));
+
+    const saved = JSON.parse(patchCalls()[0][1]?.body as string).settings[
+      SETTING_NAME
+    ];
+    expect(saved).toHaveLength(2);
+    expect(saved[1]).toEqual({ "2026-02-01T00:00:00.000Z": "saved elsewhere" });
+  });
+
+  it("stores an ISO timestamp as the banner key", async () => {
+    const { result } = renderHook(() => useSavePrototypeBanner(), {
+      wrapper: makeWrapper(),
+    });
+
+    act(() => result.current.mutate("timestamped"));
+    await waitFor(() => expect(patchCalls()).toHaveLength(1));
+
+    const saved = JSON.parse(patchCalls()[0][1]?.body as string).settings[
+      SETTING_NAME
+    ];
+    expect(Object.keys(saved[0])[0]).toMatch(
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/,
+    );
+  });
+});

From ea76489e897e791b922ebfc6ee97ac9fddd9c3ab Mon Sep 17 00:00:00 2001
From: Yue Chao Qin <yuechao.qin@shopify.com>
Date: Tue, 18 Aug 2026 13:39:18 -0700
Subject: [PATCH 3/3] fix: parse banner settings returned as a JSON string

The settings endpoint can hand a value back as a JSON string; the tour and
onboarding readers already parse before validating. Without it the panel
shows no history and, worse, the read-modify-write save overwrites the
whole history with a single entry.

Assisted-By: devx/18a6bbd2-5972-4e08-ad51-c91f9713b20c
---
 .../sections/prototypeBanners.test.ts         |  8 ++++++
 .../Settings/sections/prototypeBanners.ts     | 21 +++++++++++++---
 .../sections/prototypeBannersBackend.test.tsx | 25 +++++++++++++++++++
 3 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/src/routes/Settings/sections/prototypeBanners.test.ts b/src/routes/Settings/sections/prototypeBanners.test.ts
index 0db62f1d4c..0e8c7423a7 100644
--- a/src/routes/Settings/sections/prototypeBanners.test.ts
+++ b/src/routes/Settings/sections/prototypeBanners.test.ts
@@ -26,6 +26,14 @@ describe("parseBanners", () => {
     expect(parseBanners(undefined)).toEqual([]);
     expect(parseBanners({ "2026-01-01T00:00:00.000Z": "x" })).toEqual([]);
   });
+
+  it("parses a value the settings endpoint stored as a JSON string", () => {
+    expect(parseBanners(JSON.stringify([OLD, NEW]))).toEqual([NEW, OLD]);
+  });
+
+  it("returns an empty list for a string that is not JSON", () => {
+    expect(parseBanners("not json")).toEqual([]);
+  });
 });
 
 describe("withNewBanner", () => {
diff --git a/src/routes/Settings/sections/prototypeBanners.ts b/src/routes/Settings/sections/prototypeBanners.ts
index d602acd880..92f115ceab 100644
--- a/src/routes/Settings/sections/prototypeBanners.ts
+++ b/src/routes/Settings/sections/prototypeBanners.ts
@@ -33,12 +33,27 @@ function sortNewestFirst(banners: PrototypeBanner[]): PrototypeBanner[] {
   );
 }
 
-/** Keeps only single-entry string maps, sorted newest first. */
+/**
+ * Keeps only single-entry string maps, sorted newest first.
+ *
+ * The settings endpoint can hand a value back as a JSON string, so a string
+ * is parsed before validation — same as the tour and onboarding readers.
+ * Treating a stringified list as "no banners" would make the save path
+ * overwrite the whole history with one entry.
+ */
 export function parseBanners(value: unknown): PrototypeBanner[] {
-  if (!Array.isArray(value)) return [];
+  let raw = value;
+  if (typeof raw === "string") {
+    try {
+      raw = JSON.parse(raw);
+    } catch {
+      return [];
+    }
+  }
+  if (!Array.isArray(raw)) return [];
 
   const banners: PrototypeBanner[] = [];
-  for (const entry of value) {
+  for (const entry of raw) {
     if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
       continue;
     }
diff --git a/src/routes/Settings/sections/prototypeBannersBackend.test.tsx b/src/routes/Settings/sections/prototypeBannersBackend.test.tsx
index a64f5df83d..6bae33d70a 100644
--- a/src/routes/Settings/sections/prototypeBannersBackend.test.tsx
+++ b/src/routes/Settings/sections/prototypeBannersBackend.test.tsx
@@ -158,6 +158,31 @@ describe("useSavePrototypeBanner", () => {
     expect(saved[1]).toEqual({ "2026-02-01T00:00:00.000Z": "saved elsewhere" });
   });
 
+  it("keeps history that the endpoint returned as a JSON string", async () => {
+    fetchWithErrorHandling.mockImplementation((_url, options) =>
+      options?.method === "PATCH"
+        ? Promise.resolve({})
+        : Promise.resolve({
+            [SETTING_NAME]: JSON.stringify([
+              { "2026-01-01T00:00:00.000Z": "old" },
+            ]),
+          }),
+    );
+
+    const { result } = renderHook(() => useSavePrototypeBanner(), {
+      wrapper: makeWrapper(),
+    });
+
+    act(() => result.current.mutate("fresh banner"));
+    await waitFor(() => expect(patchCalls()).toHaveLength(1));
+
+    const saved = JSON.parse(patchCalls()[0][1]?.body as string).settings[
+      SETTING_NAME
+    ];
+    expect(saved).toHaveLength(2);
+    expect(saved[1]).toEqual({ "2026-01-01T00:00:00.000Z": "old" });
+  });
+
   it("stores an ISO timestamp as the banner key", async () => {
     const { result } = renderHook(() => useSavePrototypeBanner(), {
       wrapper: makeWrapper(),