@desplega.ai/agent-swarm 2.7.6 → 2.7.7

package/src/tests/pages-http.test.ts

@@ -313,4 +313,334 @@ describe("Pages HTTP API", () => {
       expect(res.status).toBe(200);
     });
   });
+
+  describe("design fields (theme, themeTokens, designVersion)", () => {
+    const shadcnTokens = {
+      light: {
+        "--primary": "oklch(0.55 0.2 260)",
+        background: "oklch(1 0 0)",
+        radius: "0.5rem",
+        "--sidebar": "oklch(0.9 0 0)",
+      },
+      dark: { "--primary": "oklch(0.7 0.15 260)" },
+    };
+    const normalizedShadcnTokens = {
+      light: {
+        "--color-primary": "oklch(0.55 0.2 260)",
+        "--color-background": "oklch(1 0 0)",
+        "--radius-sm": "calc(0.5rem - 4px)",
+        "--radius-md": "calc(0.5rem - 2px)",
+        "--radius-lg": "0.5rem",
+        "--radius-xl": "calc(0.5rem + 4px)",
+      },
+      dark: { "--color-primary": "oklch(0.7 0.15 260)" },
+    };
+
+    function postDesignPage(extra: Record<string, unknown> = {}) {
+      return fetch(`${baseUrl}/api/pages`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          slug: `design-${crypto.randomUUID().slice(0, 8)}`,
+          title: "Design page",
+          contentType: "text/html",
+          authMode: "public",
+          body: "<h1>hi</h1>",
+          ...extra,
+        }),
+      });
+    }
+
+    function putPage(id: string, body: Record<string, unknown>) {
+      return fetch(`${baseUrl}/api/pages/${id}`, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(body),
+      });
+    }
+
+    async function getDesignPage(id: string): Promise<Page> {
+      const res = await fetch(`${baseUrl}/api/pages/${id}`, { headers });
+      expect(res.status).toBe(200);
+      return (await res.json()) as Page;
+    }
+
+    async function versionCount(id: string): Promise<number> {
+      const res = await fetch(`${baseUrl}/api/pages/${id}/versions`, { headers });
+      return ((await res.json()) as { versions: unknown[] }).versions.length;
+    }
+
+    test("a new page gets design version 2 with no theme and no tokens", async () => {
+      const res = await postDesignPage();
+      expect(res.status).toBe(201);
+      const created = (await res.json()) as {
+        id: string;
+        ignoredTokens?: string[];
+        designVersion?: number;
+      };
+      expect(created.ignoredTokens).toBeUndefined();
+      expect(created.designVersion).toBe(2);
+
+      const page = await getDesignPage(created.id);
+      expect(page.designVersion).toBe(2);
+      expect(page.theme).toBeNull();
+      expect(page.themeTokens).toBeNull();
+    });
+
+    test("POST stores a preset theme and an explicit design version", async () => {
+      const res = await postDesignPage({ theme: "paper", designVersion: 1 });
+      expect(res.status).toBe(201);
+      const { id, designVersion } = (await res.json()) as { id: string; designVersion?: number };
+      expect(designVersion).toBe(1);
+      const page = await getDesignPage(id);
+      expect(page.theme).toBe("paper");
+      expect(page.designVersion).toBe(1);
+    });
+
+    test("POST with a design version other than 1 or 2 → 400", async () => {
+      for (const designVersion of [0, 3, "2", null]) {
+        const res = await postDesignPage({ designVersion });
+        expect(res.status).toBe(400);
+      }
+    });
+
+    test("POST with an unknown theme → 400 that lists the presets, and no page is created", async () => {
+      const slug = `unknown-theme-${crypto.randomUUID().slice(0, 8)}`;
+      const res = await postDesignPage({ slug, theme: "neon" });
+      expect(res.status).toBe(400);
+      const { error } = (await res.json()) as { error: string };
+      expect(error).toContain('Unknown theme "neon"');
+      for (const id of ["hive", "paper", "github"]) expect(error).toContain(id);
+
+      const resolved = await fetch(`${baseUrl}/api/pages/resolve?slug=${slug}&agentId=${agentId}`, {
+        headers,
+      });
+      expect(resolved.status).toBe(404);
+    });
+
+    test("POST stores shadcn-style tokens normalized and reports the ignored names", async () => {
+      const res = await postDesignPage({ themeTokens: shadcnTokens });
+      expect(res.status).toBe(201);
+      const created = (await res.json()) as { id: string; ignoredTokens?: string[] };
+      expect(created.ignoredTokens).toEqual(["--sidebar"]);
+
+      const page = await getDesignPage(created.id);
+      expect(page.themeTokens).toEqual(normalizedShadcnTokens);
+    });
+
+    test("POST accepts the css format", async () => {
+      const css = `
+        :root { --primary: 222.2 47.4% 11.2%; --radius: 0.625rem; --shadow-2xs: 0 1px 2px #0000; }
+        .dark { --primary: 210 40% 98%; --sidebar-primary: red; }
+      `;
+      const res = await postDesignPage({ themeTokens: { format: "css", css } });
+      expect(res.status).toBe(201);
+      const created = (await res.json()) as { id: string; ignoredTokens?: string[] };
+      expect([...(created.ignoredTokens ?? [])].sort()).toEqual([
+        "--shadow-2xs",
+        "--sidebar-primary",
+      ]);
+
+      const page = await getDesignPage(created.id);
+      expect(page.themeTokens).toEqual({
+        light: {
+          "--color-primary": "hsl(222.2 47.4% 11.2%)",
+          "--radius-sm": "calc(0.625rem - 4px)",
+          "--radius-md": "calc(0.625rem - 2px)",
+          "--radius-lg": "0.625rem",
+          "--radius-xl": "calc(0.625rem + 4px)",
+        },
+        dark: { "--color-primary": "hsl(210 40% 98%)" },
+      });
+    });
+
+    test("POST with bad themeTokens → 400 that names the problem", async () => {
+      const unsafe = await postDesignPage({
+        themeTokens: { light: { "--color-primary": "red; } body { display: none" } },
+      });
+      expect(unsafe.status).toBe(400);
+      const unsafeError = ((await unsafe.json()) as { error: string }).error;
+      expect(unsafeError).toContain("Invalid themeTokens");
+      expect(unsafeError).toContain("--color-primary");
+
+      const missingCss = await postDesignPage({ themeTokens: { format: "css" } });
+      expect(missingCss.status).toBe(400);
+      expect(((await missingCss.json()) as { error: string }).error).toContain(
+        "Invalid themeTokens",
+      );
+
+      const noBlocks = await postDesignPage({ themeTokens: { format: "css", css: "body { }" } });
+      expect(noBlocks.status).toBe(400);
+      expect(((await noBlocks.json()) as { error: string }).error).toContain(
+        "no :root, .dark, or @theme block",
+      );
+    });
+
+    test("POST with an unknown themeTokens format or field → 400", async () => {
+      const format = await postDesignPage({ themeTokens: { format: "dtcg", light: {} } });
+      expect(format.status).toBe(400);
+      expect(((await format.json()) as { error: string }).error).toContain("themeTokens");
+
+      const field = await postDesignPage({ themeTokens: { lite: { "--color-primary": "red" } } });
+      expect(field.status).toBe(400);
+      expect(((await field.json()) as { error: string }).error).toContain("themeTokens");
+    });
+
+    test("PUT keeps the design fields it does not mention", async () => {
+      const created = await postDesignPage({ theme: "paper", themeTokens: shadcnTokens });
+      const { id } = (await created.json()) as { id: string };
+
+      const res = await putPage(id, { body: "<h1>v2</h1>" });
+      expect(res.status).toBe(200);
+      expect(((await res.json()) as { designVersion?: number }).designVersion).toBe(2);
+      const page = await getDesignPage(id);
+      expect(page.body).toBe("<h1>v2</h1>");
+      expect(page.theme).toBe("paper");
+      expect(page.themeTokens).toEqual(normalizedShadcnTokens);
+      expect(page.designVersion).toBe(2);
+    });
+
+    test("PUT sets a new theme, replaces the tokens, and moves the design version", async () => {
+      const created = await postDesignPage({ designVersion: 1, themeTokens: shadcnTokens });
+      const { id } = (await created.json()) as { id: string };
+
+      const res = await putPage(id, {
+        theme: "github",
+        designVersion: 2,
+        themeTokens: { light: { "--color-ring": "oklch(0.6 0.2 30)", "--spacing": "4px" } },
+      });
+      expect(res.status).toBe(200);
+      const updated = (await res.json()) as { ignoredTokens?: string[]; designVersion?: number };
+      expect(updated.ignoredTokens).toEqual(["--spacing"]);
+      expect(updated.designVersion).toBe(2);
+
+      const page = await getDesignPage(id);
+      expect(page.theme).toBe("github");
+      expect(page.designVersion).toBe(2);
+      // The new tokens replace the old set, they do not merge into it.
+      expect(page.themeTokens).toEqual({
+        light: { "--color-ring": "oklch(0.6 0.2 30)" },
+        dark: {},
+      });
+    });
+
+    test("PUT reports the design version the page keeps", async () => {
+      const created = await postDesignPage({ designVersion: 1 });
+      const { id } = (await created.json()) as { id: string };
+      const res = await putPage(id, { body: '<main class="swarm-page">v2</main>' });
+      expect(res.status).toBe(200);
+      expect(((await res.json()) as { designVersion?: number }).designVersion).toBe(1);
+    });
+
+    test("POST reports a reference outside the contract with the reference", async () => {
+      const res = await postDesignPage({
+        themeTokens: {
+          format: "css",
+          css: ":root { --font-sans: var(--font-geist-sans); --primary: red; } body { --ring: blue; }",
+        },
+      });
+      expect(res.status).toBe(201);
+      const created = (await res.json()) as { ignoredTokens?: string[] };
+      expect(created.ignoredTokens).toEqual([
+        "--font-sans (references --font-geist-sans)",
+        "--ring (in body)",
+      ]);
+    });
+
+    test("PUT with null clears the theme and the tokens", async () => {
+      const created = await postDesignPage({ theme: "paper", themeTokens: shadcnTokens });
+      const { id } = (await created.json()) as { id: string };
+
+      const res = await putPage(id, { theme: null, themeTokens: null });
+      expect(res.status).toBe(200);
+      const page = await getDesignPage(id);
+      expect(page.theme).toBeNull();
+      expect(page.themeTokens).toBeNull();
+      expect(page.designVersion).toBe(2);
+    });
+
+    test("PUT with a bad theme or bad tokens → 400, and the page and its history stay as they were", async () => {
+      const created = await postDesignPage({ theme: "paper" });
+      const { id } = (await created.json()) as { id: string };
+
+      const badTheme = await putPage(id, { theme: "neon", body: "<h1>changed</h1>" });
+      expect(badTheme.status).toBe(400);
+      expect(((await badTheme.json()) as { error: string }).error).toContain(
+        'Unknown theme "neon"',
+      );
+
+      const badTokens = await putPage(id, {
+        themeTokens: { light: { "--color-primary": "url(https://example.test/x)" } },
+        body: "<h1>changed</h1>",
+      });
+      expect(badTokens.status).toBe(400);
+      expect(((await badTokens.json()) as { error: string }).error).toContain(
+        "Invalid themeTokens",
+      );
+
+      const page = await getDesignPage(id);
+      expect(page.body).toBe("<h1>hi</h1>");
+      expect(page.theme).toBe("paper");
+      expect(await versionCount(id)).toBe(0);
+    });
+
+    test("PUT with a design version other than 1 or 2 → 400", async () => {
+      const created = await postDesignPage();
+      const { id } = (await created.json()) as { id: string };
+      const res = await putPage(id, { designVersion: 3 });
+      expect(res.status).toBe(400);
+    });
+
+    test("GET resolve returns the design fields", async () => {
+      const slug = `resolve-${crypto.randomUUID().slice(0, 8)}`;
+      const created = await postDesignPage({ slug, theme: "paper", designVersion: 1 });
+      expect(created.status).toBe(201);
+      const res = await fetch(`${baseUrl}/api/pages/resolve?slug=${slug}&agentId=${agentId}`, {
+        headers,
+      });
+      expect(res.status).toBe(200);
+      const page = (await res.json()) as Page;
+      expect(page.theme).toBe("paper");
+      expect(page.designVersion).toBe(1);
+      expect(page.themeTokens).toBeNull();
+    });
+
+    test("the list leaves the design fields out unless fields=full", async () => {
+      const ownerId = crypto.randomUUID();
+      const ownerHeaders = { "Content-Type": "application/json", "X-Agent-ID": ownerId };
+      const created = await fetch(`${baseUrl}/api/pages`, {
+        method: "POST",
+        headers: ownerHeaders,
+        body: JSON.stringify({
+          slug: "listed",
+          title: "Listed",
+          contentType: "text/html",
+          authMode: "public",
+          body: "<h1>hi</h1>",
+          theme: "paper",
+          themeTokens: shadcnTokens,
+        }),
+      });
+      expect(created.status).toBe(201);
+
+      const slimRes = await fetch(`${baseUrl}/api/pages?agentId=${ownerId}`, {
+        headers: ownerHeaders,
+      });
+      expect(slimRes.status).toBe(200);
+      const [slim] = ((await slimRes.json()) as { pages: Array<Record<string, unknown>> }).pages;
+      expect(slim?.slug).toBe("listed");
+      for (const field of ["body", "theme", "themeTokens", "designVersion"]) {
+        expect(field in slim!).toBe(false);
+      }
+
+      const fullRes = await fetch(`${baseUrl}/api/pages?agentId=${ownerId}&fields=full`, {
+        headers: ownerHeaders,
+      });
+      expect(fullRes.status).toBe(200);
+      const [full] = ((await fullRes.json()) as { pages: Page[] }).pages;
+      expect(full?.theme).toBe("paper");
+      expect(full?.themeTokens).toEqual(normalizedShadcnTokens);
+      expect(full?.designVersion).toBe(2);
+    });
+  });
 });

package/src/tests/pages-public-html.test.ts

@@ -5,6 +5,8 @@
  *     `class SwarmSDK` which is unique to the constant)
  *   - the response `Content-Type` is `text/html`
  *   - a `Content-Security-Policy` header is set
+ *   - a design version 1 page keeps the frozen original head, and a body
+ *     without `<head>` still gets it prepended, byte for byte
  */
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import crypto from "node:crypto";
@@ -19,6 +21,8 @@ import { closeDb, initDb } from "../be/db";
 import { handlePages } from "../http/pages";
 import { handlePagesPublic } from "../http/pages-public";
 import { getPathSegments, parseQueryParams } from "../http/utils";
+import { BROWSER_SDK_JS, SWARM_UI_JS } from "../pages/browser-sdk";
+import { PAGE_HEAD_V1 } from "../pages/page-head";
 import { listenOnFreePort } from "./test-net";
 
 const TEST_DB_PATH = "./test-pages-public-html.sqlite";
@@ -82,6 +86,9 @@ describe("GET /p/:id — HTML public path", () => {
         contentType: "text/html",
         authMode: "public",
         body: html,
+        // Design version 1 keeps the original head. Version 2 (the default)
+        // is covered by pages-head-v2.test.ts.
+        designVersion: 1,
       }),
     });
     expect(post.status).toBe(201);
@@ -109,9 +116,45 @@ describe("GET /p/:id — HTML public path", () => {
     const text = await res.text();
     expect(text).toContain("<h1>Hello</h1>");
     expect(text).toContain("class SwarmSDK"); // BROWSER_SDK_JS sentinel
+    // The frozen design version 1 head, verbatim, right after <head>.
+    expect(text).toContain(`<head>${PAGE_HEAD_V1}<script>`);
     expect(text).toContain("color-scheme: light");
     expect(text).toContain("--swarm-bg: #fbfbfa");
     expect(text).toContain("--swarm-text: #111827");
+    expect(text).toContain('<script src="https://cdn.tailwindcss.com"></script>');
+    expect(text).not.toContain("@tailwindcss/browser");
+    expect(text).not.toContain('id="swarm-theme"');
+
+    // Version 1 ignores the viewer theme and mode params.
+    const themed = await fetch(`${BASE}/p/${id}?__swarm-theme=github&__swarm-mode=dark`);
+    expect(themed.status).toBe(200);
+    expect(await themed.text()).toBe(text);
+  });
+
+  test("a version 1 body without a <head> still gets the injection prepended, byte for byte", async () => {
+    const injection = `${PAGE_HEAD_V1}<script>${BROWSER_SDK_JS}</script><script>${SWARM_UI_JS}</script>`;
+    // Version 2 adds a doctype and moves the head (pages-head-v2.test.ts).
+    // Version 1 never does.
+    const bodies = ["<h1>Fragment</h1>", "<!doctype html><html><body>x</body></html>"];
+    for (const [index, body] of bodies.entries()) {
+      const post = await fetch(`${BASE}/api/pages`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          slug: `v1-no-head-${index}`,
+          title: "No head",
+          contentType: "text/html",
+          authMode: "public",
+          body,
+          designVersion: 1,
+        }),
+      });
+      expect(post.status).toBe(201);
+      const { id } = (await post.json()) as { id: string };
+      const res = await fetch(`${BASE}/p/${id}`);
+      expect(res.status).toBe(200);
+      expect(await res.text()).toBe(injection + body);
+    }
   });
 
   for (const authMode of ["public", "authed", "password"]) {

package/src/tests/pages-storage.test.ts

@@ -219,3 +219,185 @@ describe("pages storage CRUD", () => {
     await expect(snapshotPage("0".repeat(32), "agent-x")).rejects.toThrow(/not found/);
   });
 });
+
+describe("pages design fields", () => {
+  const tokens = {
+    light: { "--color-primary": "oklch(0.55 0.2 260)", "--radius-lg": "0.5rem" },
+    dark: { "--color-primary": "oklch(0.7 0.15 260)" },
+  };
+
+  test("createPage defaults to design version 2 with no theme and no tokens", async () => {
+    const created = await createPage({
+      agentId: makeAgentId(),
+      slug: "design-default",
+      title: "Design default",
+      contentType: "text/html",
+      body: "<h1>hi</h1>",
+    });
+    expect(created.designVersion).toBe(2);
+    expect(created.theme).toBeNull();
+    expect(created.themeTokens).toBeNull();
+
+    const fetched = await getPage(created.id);
+    expect(fetched?.designVersion).toBe(2);
+    expect(fetched?.theme).toBeNull();
+    expect(fetched?.themeTokens).toBeNull();
+  });
+
+  test("createPage stores the theme, the tokens, and an explicit design version", async () => {
+    const created = await createPage({
+      agentId: makeAgentId(),
+      slug: "design-explicit",
+      title: "Design explicit",
+      contentType: "text/html",
+      body: "<h1>hi</h1>",
+      theme: "paper",
+      themeTokens: tokens,
+      designVersion: 1,
+    });
+    const fetched = await getPage(created.id);
+    expect(fetched?.theme).toBe("paper");
+    expect(fetched?.themeTokens).toEqual(tokens);
+    expect(fetched?.designVersion).toBe(1);
+  });
+
+  test("a row inserted without the design columns reads design version 1", async () => {
+    const row = await getDbClient().get<{ id: string }>(
+      `INSERT INTO pages (agentId, slug, title, contentType, body)
+         VALUES (?, ?, ?, ?, ?) RETURNING id`,
+      [makeAgentId(), "sql-design-default", "SQL design default", "text/html", "<h1>old</h1>"],
+    );
+    const page = await getPage(row!.id);
+    expect(page?.designVersion).toBe(1);
+    expect(page?.theme).toBeNull();
+    expect(page?.themeTokens).toBeNull();
+  });
+
+  test("updatePage keeps omitted design fields, sets new ones, and clears with null", async () => {
+    const page = await createPage({
+      agentId: makeAgentId(),
+      slug: "design-update",
+      title: "Design update",
+      contentType: "text/html",
+      body: "<h1>v1</h1>",
+      theme: "paper",
+      themeTokens: tokens,
+    });
+
+    // Omitted fields stay as they were.
+    const kept = await updatePage(page.id, { body: "<h1>v2</h1>" });
+    expect(kept?.theme).toBe("paper");
+    expect(kept?.themeTokens).toEqual(tokens);
+    expect(kept?.designVersion).toBe(2);
+
+    // New values replace the stored ones.
+    const replaced = await updatePage(page.id, {
+      theme: "github",
+      themeTokens: { light: { "--radius-lg": "1rem" }, dark: {} },
+      designVersion: 1,
+    });
+    expect(replaced?.theme).toBe("github");
+    expect(replaced?.themeTokens).toEqual({ light: { "--radius-lg": "1rem" }, dark: {} });
+    expect(replaced?.designVersion).toBe(1);
+
+    // null clears the theme and the tokens.
+    const cleared = await updatePage(page.id, { theme: null, themeTokens: null });
+    expect(cleared?.theme).toBeNull();
+    expect(cleared?.themeTokens).toBeNull();
+    expect(cleared?.designVersion).toBe(1);
+    const reread = await getPage(page.id);
+    expect(reread?.theme).toBeNull();
+    expect(reread?.themeTokens).toBeNull();
+  });
+
+  test("theme_tokens that is not valid tokens JSON reads as null", async () => {
+    const page = await createPage({
+      agentId: makeAgentId(),
+      slug: "design-bad-json",
+      title: "Design bad JSON",
+      contentType: "text/html",
+      body: "<h1>hi</h1>",
+      themeTokens: tokens,
+    });
+    for (const stored of ["{not json", '{"light": 1}', '["light"]', "null", ""]) {
+      await getDbClient().run("UPDATE pages SET theme_tokens = ? WHERE id = ?", [stored, page.id]);
+      expect((await getPage(page.id))?.themeTokens).toBeNull();
+    }
+  });
+
+  test("snapshotPage carries the design fields", async () => {
+    const agentId = makeAgentId();
+    const page = await createPage({
+      agentId,
+      slug: "design-snapshot",
+      title: "Design snapshot",
+      contentType: "text/html",
+      body: "<h1>v1</h1>",
+      theme: "paper",
+      themeTokens: tokens,
+      designVersion: 1,
+    });
+    await snapshotPage(page.id, agentId);
+    await updatePage(page.id, { theme: null, themeTokens: null, designVersion: 2 });
+
+    const version = await getPageVersion(page.id, 1);
+    expect(version?.snapshot.theme).toBe("paper");
+    expect(version?.snapshot.themeTokens).toEqual(tokens);
+    expect(version?.snapshot.designVersion).toBe(1);
+
+    // A page without a theme snapshots the nulls, not missing keys.
+    await snapshotPage(page.id, agentId);
+    const second = await getPageVersion(page.id, 2);
+    expect(second?.snapshot.theme).toBeNull();
+    expect(second?.snapshot.themeTokens).toBeNull();
+    expect(second?.snapshot.designVersion).toBe(2);
+  });
+
+  test("a snapshot stored before design version 2 still reads, without the design fields", async () => {
+    const page = await createPage({
+      agentId: makeAgentId(),
+      slug: "design-old-snapshot",
+      title: "Design old snapshot",
+      contentType: "text/html",
+      body: "<h1>old</h1>",
+    });
+    const oldSnapshot = JSON.stringify({
+      title: "Old",
+      contentType: "text/html",
+      authMode: "public",
+      body: "<h1>old</h1>",
+    });
+    await getDbClient().run(
+      "INSERT INTO page_versions (pageId, version, snapshot) VALUES (?, 1, ?)",
+      [page.id, oldSnapshot],
+    );
+    const version = await getPageVersion(page.id, 1);
+    expect(version?.snapshot.title).toBe("Old");
+    expect(version?.snapshot.theme).toBeUndefined();
+    expect(version?.snapshot.themeTokens).toBeUndefined();
+    expect(version?.snapshot.designVersion).toBeUndefined();
+  });
+
+  test("slim list rows leave out the design fields and full rows carry them", async () => {
+    const agentId = makeAgentId();
+    await createPage({
+      agentId,
+      slug: "design-list",
+      title: "Design list",
+      contentType: "text/html",
+      body: "<h1>hi</h1>",
+      theme: "paper",
+      themeTokens: tokens,
+    });
+    const [slim] = await listPagesByAgent(agentId, 10, 0, { slim: true });
+    expect(slim).toBeDefined();
+    expect("theme" in slim!).toBe(false);
+    expect("themeTokens" in slim!).toBe(false);
+    expect("designVersion" in slim!).toBe(false);
+
+    const [full] = await listPagesByAgent(agentId, 10, 0, { slim: false });
+    expect(full?.theme).toBe("paper");
+    expect(full?.themeTokens).toEqual(tokens);
+    expect(full?.designVersion).toBe(2);
+  });
+});

package/src/tests/pages-versioning.test.ts

@@ -229,4 +229,76 @@ describe("Pages versioning (PUT /api/pages/:id)", () => {
       expect(p.app_url).toContain(`/pages/${p.slug}`);
     }
   });
+
+  test("PUT snapshots the design fields as they stood before the update", async () => {
+    const created = await fetch(`${BASE}/api/pages`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        slug: "design-versions",
+        title: "Design versions",
+        contentType: "text/html",
+        authMode: "public",
+        body: "d0",
+        theme: "paper",
+        designVersion: 1,
+        themeTokens: { light: { "--primary": "oklch(0.55 0.2 260)" } },
+      }),
+    });
+    expect(created.status).toBe(201);
+    const { id } = (await created.json()) as { id: string };
+
+    // PUT #1 moves every design field. PUT #2 clears the theme and the tokens.
+    const first = await fetch(`${BASE}/api/pages/${id}`, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify({
+        theme: "github",
+        designVersion: 2,
+        themeTokens: { light: { "--color-ring": "oklch(0.6 0.2 30)" } },
+      }),
+    });
+    expect(first.status).toBe(200);
+    const second = await fetch(`${BASE}/api/pages/${id}`, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify({ theme: null, themeTokens: null }),
+    });
+    expect(second.status).toBe(200);
+
+    const versionsRes = await fetch(`${BASE}/api/pages/${id}/versions`, { headers });
+    expect(versionsRes.status).toBe(200);
+    const { versions } = (await versionsRes.json()) as { versions: PageVersion[] };
+    expect(versions.map((v) => v.version)).toEqual([2, 1]);
+
+    // v1 froze the state before PUT #1.
+    expect(versions[1]!.snapshot.theme).toBe("paper");
+    expect(versions[1]!.snapshot.designVersion).toBe(1);
+    expect(versions[1]!.snapshot.themeTokens).toEqual({
+      light: { "--color-primary": "oklch(0.55 0.2 260)" },
+      dark: {},
+    });
+    // v2 froze the state before PUT #2.
+    expect(versions[0]!.snapshot.theme).toBe("github");
+    expect(versions[0]!.snapshot.designVersion).toBe(2);
+    expect(versions[0]!.snapshot.themeTokens).toEqual({
+      light: { "--color-ring": "oklch(0.6 0.2 30)" },
+      dark: {},
+    });
+
+    // The head holds the cleared state.
+    const head = (await (await fetch(`${BASE}/api/pages/${id}`, { headers })).json()) as {
+      theme: string | null;
+      themeTokens: unknown;
+      designVersion: number;
+    };
+    expect(head.theme).toBeNull();
+    expect(head.themeTokens).toBeNull();
+    expect(head.designVersion).toBe(2);
+
+    // The single-version route serves the same snapshot.
+    const single = await fetch(`${BASE}/api/pages/${id}/versions/1`, { headers });
+    expect(single.status).toBe(200);
+    expect(((await single.json()) as PageVersion).snapshot.theme).toBe("paper");
+  });
 });