@upstart.gg/vite-plugins 0.1.83 → 0.1.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstart.gg/vite-plugins",
-  "version": "0.1.83",
+  "version": "0.1.84",
   "type": "module",
   "files": [
     "dist",
@@ -23,7 +23,7 @@
     "oxc-parser": "0.101.0",
     "unplugin": "^2.3.11",
     "zimmerframe": "^1.1.4",
-    "@upstart.gg/sdk": "^0.1.83"
+    "@upstart.gg/sdk": "^0.1.84"
   },
   "devDependencies": {
     "@rolldown/binding-linux-arm64-gnu": "1.0.0",
@@ -118,7 +118,7 @@
   },
   "peerDependencies": {
     "zod": "4.3.6",
-    "@upstart.gg/sdk": "^0.1.83"
+    "@upstart.gg/sdk": "^0.1.84"
   },
   "author": "Upstart",
   "publishConfig": {

package/src/site-theme.ts

@@ -0,0 +1,205 @@
+/**
+ * The site's colors, editable from the editor's "Colors" panel.
+ *
+ * A site's colors live in its theme file (`app/config/themes/<id>.json`, the one `site.json` names
+ * as the default), read by the theme plugin at build time. A new site also keeps the palettes the
+ * client was offered when choosing its look (`docs/mockups/<direction>/` and its `palettes/<n>/`
+ * variants, see the `PaletteVariants` tool): the panel offers them again, next to a free picker.
+ *
+ * Saving also records in `docs/DESIGN.md` that the user chose the colors themselves: agents read
+ * the brief before any UI work, and would otherwise bring the brief's palette back.
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import z from "zod";
+
+/** The theme colors the panel edits, in the theme file's naming. */
+export const EDITABLE_THEME_COLORS = [
+  "base100",
+  "base200",
+  "base300",
+  "baseContent",
+  "primary",
+  "primaryContent",
+  "secondary",
+  "secondaryContent",
+  "accent",
+  "accentContent",
+  "neutral",
+  "neutralContent",
+] as const;
+export type EditableThemeColor = (typeof EDITABLE_THEME_COLORS)[number];
+export type ThemeColors = Partial<Record<EditableThemeColor, string>>;
+
+/** A CSS color as theme files hold them: oklch(), hex, rgb() or hsl(). */
+const cssColor = z
+  .string()
+  .trim()
+  .max(80)
+  .regex(/^(#[0-9a-fA-F]{3,8}|(oklch|oklab|rgba?|hsla?)\([0-9.,%\s/+-]+\))$/, "Not a CSS color");
+
+export const payloadGetTheme = z.object({ action: z.literal("getTheme") });
+export type PayloadGetTheme = z.infer<typeof payloadGetTheme>;
+
+export const payloadSetTheme = z.object({
+  action: z.literal("setTheme"),
+  colors: z.partialRecord(z.enum(EDITABLE_THEME_COLORS), cssColor),
+});
+export type PayloadSetTheme = z.infer<typeof payloadSetTheme>;
+
+export interface ThemePalette {
+  /** Stable id: "current" for the chosen mockup, "palette-<n>" for its variants. */
+  id: string;
+  /** The catalog palette's description, when known (e.g. "Blush base, deep rose text…"). */
+  label: string;
+  colors: ThemeColors;
+}
+
+export type GetThemeResult =
+  | { success: true; themeId: string; colors: ThemeColors; palettes: ThemePalette[] }
+  | { success: false; error: string };
+
+export type SetThemeResult = { success: true; filePaths: string[] } | { success: false; error: string };
+
+/** Mockup token (Tailwind config of a mockup) → theme color. */
+const MOCKUP_TOKENS: Record<string, EditableThemeColor> = {
+  "base-100": "base100",
+  "base-200": "base200",
+  "base-300": "base300",
+  "base-content": "baseContent",
+  primary: "primary",
+  "primary-content": "primaryContent",
+  secondary: "secondary",
+  "secondary-content": "secondaryContent",
+  accent: "accent",
+  "accent-content": "accentContent",
+  neutral: "neutral",
+  "neutral-content": "neutralContent",
+};
+
+/** The colors a mockup sets in its Tailwind config, in the theme's naming. */
+export function mockupThemeColors(html: string): ThemeColors {
+  const script = [...html.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/g)].find((m) =>
+    m[1].includes("tailwind.config"),
+  )?.[1];
+  const colors: ThemeColors = {};
+  if (!script) return colors;
+  for (const [token, key] of Object.entries(MOCKUP_TOKENS)) {
+    const pattern = new RegExp(`['"]?${token.replace(/-/g, "\\-")}['"]?\\s*:\\s*(['"])([^'"]*)\\1`);
+    const value = pattern.exec(script)?.[2];
+    if (value && cssColor.safeParse(value).success) colors[key] = value.trim();
+  }
+  return colors;
+}
+
+/** The block `setTheme` keeps up to date at the end of the brief. */
+const BRIEF_START = "<!-- upstart:theme-colors -->";
+const BRIEF_END = "<!-- /upstart:theme-colors -->";
+
+export function briefWithUserColors(brief: string, themeFile: string): string {
+  const block = [
+    BRIEF_START,
+    "## Colors chosen by the user",
+    `The user set the site's colors themselves in the editor. \`${themeFile}\` is the source of truth for colors and wins over any palette above: keep its values, and use its tokens (bg-base-100, text-primary…) rather than new colors.`,
+    BRIEF_END,
+  ].join("\n");
+  const start = brief.indexOf(BRIEF_START);
+  const end = brief.indexOf(BRIEF_END);
+  if (start !== -1 && end > start) {
+    return `${brief.slice(0, start)}${block}${brief.slice(end + BRIEF_END.length)}`;
+  }
+  return `${brief.trimEnd()}\n\n${block}\n`;
+}
+
+/** The theme file the site uses by default, from `app/config/site.json`. */
+async function defaultThemeFile(projectRoot: string): Promise<{ themeId: string; filePath: string } | null> {
+  try {
+    const site = JSON.parse(
+      await fs.readFile(path.join(projectRoot, "app", "config", "site.json"), "utf-8"),
+    ) as {
+      themes?: { light?: string; dark?: string; default?: "light" | "dark" };
+    };
+    const themeId = site.themes?.[site.themes.default ?? "light"] ?? site.themes?.light;
+    if (!themeId || !/^[a-z0-9-]+$/.test(themeId)) return null;
+    return { themeId, filePath: path.join(projectRoot, "app", "config", "themes", `${themeId}.json`) };
+  } catch {
+    return null;
+  }
+}
+
+/** The mockup the brief names as its reference (`docs/mockups/<direction>/…`). */
+async function chosenMockup(projectRoot: string): Promise<string | null> {
+  const brief = await fs.readFile(path.join(projectRoot, "docs", "DESIGN.md"), "utf-8").catch(() => "");
+  return /docs\/mockups\/([a-z0-9-]+)\//.exec(brief)?.[1] ?? null;
+}
+
+/** The palettes the client was offered for the chosen mockup; none for an older site. */
+export async function offeredPalettes(projectRoot: string): Promise<ThemePalette[]> {
+  const direction = await chosenMockup(projectRoot);
+  if (!direction) return [];
+  const dir = path.join(projectRoot, "docs", "mockups", direction);
+  const readPalette = async (id: string, folder: string): Promise<ThemePalette | null> => {
+    const html = await fs.readFile(path.join(folder, "index.html"), "utf-8").catch(() => "");
+    const colors = mockupThemeColors(html);
+    if (Object.keys(colors).length < 3) return null;
+    const variant = await fs
+      .readFile(path.join(folder, "variant.json"), "utf-8")
+      .then((raw) => JSON.parse(raw) as { palette?: string })
+      .catch((): { palette?: string } => ({}));
+    return { id, label: variant.palette ?? "", colors };
+  };
+  const variants = await fs.readdir(path.join(dir, "palettes")).catch((): string[] => []);
+  const palettes = await Promise.all([
+    readPalette("current", dir),
+    ...variants
+      .filter((n) => /^\d+$/.test(n))
+      .sort((a, b) => Number(a) - Number(b))
+      .map((n) => readPalette(`palette-${n}`, path.join(dir, "palettes", n))),
+  ]);
+  return palettes.filter((p): p is ThemePalette => p !== null);
+}
+
+export async function getSiteTheme(projectRoot: string): Promise<GetThemeResult> {
+  const theme = await defaultThemeFile(projectRoot);
+  if (!theme) return { success: false, error: "This site has no theme in app/config/site.json" };
+  try {
+    const content = JSON.parse(await fs.readFile(theme.filePath, "utf-8")) as {
+      colors?: Record<string, string>;
+    };
+    const colors: ThemeColors = {};
+    for (const key of EDITABLE_THEME_COLORS) {
+      const value = content.colors?.[key];
+      if (typeof value === "string") colors[key] = value;
+    }
+    return { success: true, themeId: theme.themeId, colors, palettes: await offeredPalettes(projectRoot) };
+  } catch {
+    return { success: false, error: `The theme file app/config/themes/${theme.themeId}.json is missing` };
+  }
+}
+
+export async function setSiteTheme(projectRoot: string, params: PayloadSetTheme): Promise<SetThemeResult> {
+  const parsed = payloadSetTheme.safeParse(params);
+  if (!parsed.success) return { success: false, error: `Invalid payload: ${parsed.error.message}` };
+  if (Object.keys(parsed.data.colors).length === 0) return { success: true, filePaths: [] };
+  const theme = await defaultThemeFile(projectRoot);
+  if (!theme) return { success: false, error: "This site has no theme in app/config/site.json" };
+  try {
+    const content = JSON.parse(await fs.readFile(theme.filePath, "utf-8")) as {
+      colors?: Record<string, string>;
+    };
+    content.colors = { ...content.colors, ...parsed.data.colors };
+    await fs.writeFile(theme.filePath, `${JSON.stringify(content, null, 2)}\n`);
+    const filePaths = [theme.filePath];
+
+    const briefPath = path.join(projectRoot, "docs", "DESIGN.md");
+    const brief = await fs.readFile(briefPath, "utf-8").catch(() => null);
+    if (brief !== null) {
+      await fs.writeFile(briefPath, briefWithUserColors(brief, path.relative(projectRoot, theme.filePath)));
+      filePaths.push(briefPath);
+    }
+    return { success: true, filePaths };
+  } catch (err) {
+    return { success: false, error: String(err) };
+  }
+}

package/src/tests/site-theme.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  briefWithUserColors,
+  getSiteTheme,
+  mockupThemeColors,
+  offeredPalettes,
+  setSiteTheme,
+} from "../site-theme";
+
+let root: string;
+const write = (rel: string, content: string) => {
+  const file = join(root, rel);
+  mkdirSync(join(file, ".."), { recursive: true });
+  writeFileSync(file, content);
+};
+const mockup = (base: string, primary: string) => `<html><head><script>
+tailwind.config = { theme: { extend: { colors: {
+  'base-100': '${base}',
+  "base-content": "oklch(24% 0.03 50)",
+  primary: '${primary}',
+  'primary-content': 'oklch(98% 0.01 85)',
+} } } };
+</script></head><body></body></html>`;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "site-theme-"));
+  write("app/config/site.json", JSON.stringify({ themes: { light: "wedding", default: "light" } }));
+  write(
+    "app/config/themes/wedding.json",
+    JSON.stringify({
+      id: "wedding",
+      colors: { base100: "oklch(98% 0.01 85)", primary: "oklch(50% 0.1 300)", info: "#00f" },
+    }),
+  );
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+describe("mockupThemeColors", () => {
+  it("maps a mockup's Tailwind tokens to the theme's colors", () => {
+    expect(mockupThemeColors(mockup("oklch(97% 0.02 15)", "#a33"))).toEqual({
+      base100: "oklch(97% 0.02 15)",
+      baseContent: "oklch(24% 0.03 50)",
+      primary: "#a33",
+      primaryContent: "oklch(98% 0.01 85)",
+    });
+    expect(mockupThemeColors("<html></html>")).toEqual({});
+  });
+});
+
+describe("getSiteTheme", () => {
+  it("reads the editable colors of the site's default theme", async () => {
+    const theme = await getSiteTheme(root);
+    expect(theme).toEqual({
+      success: true,
+      themeId: "wedding",
+      colors: { base100: "oklch(98% 0.01 85)", primary: "oklch(50% 0.1 300)" },
+      palettes: [],
+    });
+  });
+
+  it("offers the palettes shown with the chosen mockup, the current one first", async () => {
+    write("docs/DESIGN.md", "Reference mockup: `docs/mockups/romantic-floral/palettes/2/index.html`");
+    write("docs/mockups/romantic-floral/index.html", mockup("oklch(98% 0.01 85)", "oklch(50% 0.1 300)"));
+    write("docs/mockups/romantic-floral/variant.json", JSON.stringify({ palette: "Lavender-mist base" }));
+    write(
+      "docs/mockups/romantic-floral/palettes/2/index.html",
+      mockup("oklch(97% 0.02 15)", "oklch(48% 0.14 10)"),
+    );
+    write(
+      "docs/mockups/romantic-floral/palettes/1/index.html",
+      mockup("oklch(98% 0.015 95)", "oklch(48% 0.09 235)"),
+    );
+    write("docs/mockups/romantic-floral/palettes/1/variant.json", JSON.stringify({ palette: "Ivory base" }));
+    const palettes = await offeredPalettes(root);
+    expect(palettes.map((p) => [p.id, p.label])).toEqual([
+      ["current", "Lavender-mist base"],
+      ["palette-1", "Ivory base"],
+      ["palette-2", ""],
+    ]);
+    expect(palettes[2].colors.primary).toBe("oklch(48% 0.14 10)");
+  });
+
+  it("offers no palette to a site without mockups", async () => {
+    write("docs/DESIGN.md", "# Design brief");
+    expect(await offeredPalettes(root)).toEqual([]);
+  });
+});
+
+describe("setSiteTheme", () => {
+  it("merges the colors into the theme file and tells the brief they are the user's", async () => {
+    write("docs/DESIGN.md", "# Design brief\n\nPalette: lavender.");
+    const result = await setSiteTheme(root, { action: "setTheme", colors: { primary: "#aa3355" } });
+    expect(result).toEqual({
+      success: true,
+      filePaths: [join(root, "app/config/themes/wedding.json"), join(root, "docs/DESIGN.md")],
+    });
+    const theme = JSON.parse(readFileSync(join(root, "app/config/themes/wedding.json"), "utf-8"));
+    expect(theme.colors).toEqual({ base100: "oklch(98% 0.01 85)", primary: "#aa3355", info: "#00f" });
+    expect(readFileSync(join(root, "docs/DESIGN.md"), "utf-8")).toContain("## Colors chosen by the user");
+  });
+
+  it("refuses what is not a CSS color", async () => {
+    const result = await setSiteTheme(root, {
+      action: "setTheme",
+      colors: { primary: "red; background: url(x)" },
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("briefWithUserColors", () => {
+  it("keeps a single block, updated in place", () => {
+    const once = briefWithUserColors("# Brief\n", "app/config/themes/a.json");
+    const twice = briefWithUserColors(`${once}\n## Later section\n`, "app/config/themes/b.json");
+    expect(twice.match(/Colors chosen by the user/g)).toHaveLength(1);
+    expect(twice).toContain("app/config/themes/b.json");
+    expect(twice).toContain("## Later section");
+  });
+});

package/src/upstart-editor-api.ts

@@ -6,6 +6,27 @@ import z from "zod";
 import type { EditableEntry } from "./vite-plugin-upstart-attrs";
 import { analyzeRouteMeta, type MetaElement, type MetaSegment, type ModuleLoader } from "./page-meta";
 import { ensureRootSiteMeta } from "./site-meta";
+import {
+  getSiteTheme,
+  setSiteTheme,
+  type GetThemeResult,
+  type PayloadGetTheme,
+  type PayloadSetTheme,
+  type SetThemeResult,
+} from "./site-theme";
+
+export {
+  EDITABLE_THEME_COLORS,
+  payloadGetTheme,
+  payloadSetTheme,
+  type EditableThemeColor,
+  type GetThemeResult,
+  type PayloadGetTheme,
+  type PayloadSetTheme,
+  type SetThemeResult,
+  type ThemeColors,
+  type ThemePalette,
+} from "./site-theme";
 
 /**
  * Escape user-typed text so it can be safely written as the BODY of a JS string
@@ -1236,6 +1257,16 @@ export class UpstartEditorAPI {
     }
   }
 
+  /** The site's colors and, for a new site, the palettes offered with its mockup (see site-theme.ts). */
+  async getTheme(_params: PayloadGetTheme): Promise<GetThemeResult> {
+    return getSiteTheme(this.projectRoot);
+  }
+
+  /** Write colors to the site's theme file, and record in the brief that the user chose them. */
+  async setTheme(params: PayloadSetTheme): Promise<SetThemeResult> {
+    return setSiteTheme(this.projectRoot, params);
+  }
+
   private async readSiteConfig(): Promise<Record<string, unknown> | null> {
     try {
       const raw = await fs.readFile(path.join(this.projectRoot, "app", "config", "site.json"), "utf-8");

package/src/vite-plugin-upstart-editor/runtime/index.ts

@@ -237,6 +237,21 @@ function handleParentMessage(event: MessageEvent): void {
     } else if (styleEl) {
       styleEl.remove();
     }
+  } else if (message.type === "preview-theme") {
+    // Appended last in <head> so it wins over the theme's own variables until it is cleared.
+    const STYLE_ID = "upstart-preview-theme";
+    let styleEl = document.getElementById(STYLE_ID) as HTMLStyleElement | null;
+    const css = typeof message.css === "string" ? message.css : "";
+    if (css) {
+      if (!styleEl) {
+        styleEl = document.createElement("style");
+        styleEl.id = STYLE_ID;
+      }
+      styleEl.textContent = css;
+      document.head.appendChild(styleEl);
+    } else if (styleEl) {
+      styleEl.remove();
+    }
   } else if (message.type === "request-scroll-position") {
     sendToParent({ type: "scroll-position", x: window.scrollX, y: window.scrollY });
   } else if (message.type === "restore-scroll-position") {

package/src/vite-plugin-upstart-editor/runtime/types.ts

@@ -152,6 +152,8 @@ export type ParentMessage =
   | { type: "preview-image"; imageId: string; src: string }
   /** Live-preview object-fit / position / zoom of one image via a dedicated <style> element. Empty css clears it. */
   | { type: "preview-image-style"; imageId: string; css: string }
+  /** Live-preview of the site's colors (theme CSS variables) before they are saved. Empty css clears it. */
+  | { type: "preview-theme"; css: string }
   | { type: "request-scroll-position" }
   | { type: "restore-scroll-position"; x: number; y: number }
   | { type: "clear-selection" }