meno-core 1.1.1 → 1.1.2

package/lib/server/themeCssCodec.ts

@@ -0,0 +1,488 @@
+/**
+ * theme.css codec — the single source of truth for a project's design tokens.
+ *
+ * A Meno project's colors AND typography/layout variables both live in one native
+ * Astro stylesheet, `src/styles/theme.css`, imported by every page. This module is the
+ * bidirectional bridge between that file and the in-memory editor model:
+ *
+ *   parse:     theme.css ──▶ { themes: ThemeConfig, variables: CSSVariable[], raw[] }
+ *   serialize: that model ──▶ theme.css
+ *
+ * It replaces the old colors.json + variables.json pair. The CSS variable name IS a
+ * token's identity (no editor-only `name`/`prop_name` are persisted), grouping is the
+ * comment section a declaration sits under (`/* Font Size *​/`, `/* Colors: light *​/`),
+ * and the responsive `@media` blocks are an editor-managed, regenerated region — so the
+ * file stays readable and hand-editable while round-tripping losslessly.
+ *
+ * The parser is a small tolerant tokenizer (brace/string/comment aware) rather than a
+ * full CSS library: theme.css is a constrained grammar, and keeping this dependency-free
+ * matters because meno-core is published and bundled into the Astro play runtime (which
+ * never calls the codec — it consumes theme.css as a static file). Anything outside the
+ * known grammar (@font-face, @import, keyframes, foreign selectors) is captured verbatim
+ * into `raw` and re-emitted untouched, so user/AI additions are never dropped.
+ */
+
+import type { ThemeConfig, Theme } from '../shared/types/colors';
+import { resolvePaletteColor } from '../shared/types/colors';
+import type { CSSVariable, VariableGroup } from '../shared/types/variables';
+import { VARIABLE_GROUPS, getDefaultScalingType } from '../shared/types/variables';
+import type { BreakpointConfig } from '../shared/breakpoints';
+import type { ResponsiveScales, BreakpointScales } from '../shared/responsiveScaling';
+import { scalePropertyValue } from '../shared/responsiveScaling';
+
+/** Parsed/serializable representation of a project's `theme.css`. */
+export interface ThemeModel {
+  /** Colors as a multi-theme config (default theme on `:root`, others on `[theme="x"]`). */
+  themes: ThemeConfig;
+  /** Design-token variables (group/type derived; `scales` = explicit per-breakpoint overrides). */
+  variables: CSSVariable[];
+  /** Verbatim CSS the codec does not model (@font-face, @import, foreign rules) — re-emitted as-is. */
+  raw: string[];
+}
+
+/** Responsive-scaling inputs the serializer needs (from `project.config.json`). */
+export interface ScaleConfig {
+  breakpoints: BreakpointConfig;
+  responsiveScales: ResponsiveScales;
+}
+
+const COLORS_LABEL = 'Colors';
+const OTHER_LABEL = 'Other';
+
+const HEADER_BANNER = `/*
+ * Meno design tokens — theme.css is the source of truth for this project's colors and
+ * variables. Edit values here, or use the Studio color/variable panels. Variables are
+ * grouped by the comment sections below; the @media regions are regenerated on save
+ * (responsive scaling is configured in project.config.json).
+ */`;
+
+const AUTO_BANNER = '/* === Responsive scaling — auto-generated from project.config.json; regenerated on save === */';
+const OVERRIDES_BANNER = '/* === Responsive overrides — per-variable; preserved across regen === */';
+
+// ───────────────────────────── group ⇄ comment-section ─────────────────────────────
+
+/** Comment-section header for a variable's group (e.g. 'font-size' → 'Font Size'). */
+function sectionLabelForGroup(group?: VariableGroup): string {
+  if (!group || group === 'other') return OTHER_LABEL;
+  return VARIABLE_GROUPS.find((g) => g.value === group)?.label ?? OTHER_LABEL;
+}
+
+const LABEL_TO_GROUP = new Map<string, VariableGroup>(VARIABLE_GROUPS.map((g) => [g.label.toLowerCase(), g.value]));
+
+/** Reverse of {@link sectionLabelForGroup}: a section header back to its group, or null. */
+export function groupForSectionLabel(label: string): VariableGroup | null {
+  return LABEL_TO_GROUP.get(label.trim().toLowerCase()) ?? null;
+}
+
+/** True if a CSS value reads as a color (used to classify un-sectioned `:root` decls). */
+export function isColorValue(value: string): boolean {
+  const v = value.trim().toLowerCase();
+  if (/^#[0-9a-f]{3,8}$/.test(v)) return true;
+  if (/^(rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)\(/.test(v)) return true;
+  if (v === 'transparent' || v === 'currentcolor') return true;
+  return false;
+}
+
+/**
+ * Best-effort group for a variable that carries no comment section (hand-written or
+ * legacy theme.css). px/rem tokens are inherently ambiguous (font-size vs padding vs
+ * width) and fall back to 'other'; the section comment is the reliable signal.
+ */
+export function inferGroup(cssVar: string, value: string): VariableGroup {
+  const v = value.trim().toLowerCase();
+  if (/^\d+(\.\d+)?m?s$/.test(v)) return 'duration';
+  if (/^(normal|bold|lighter|bolder)$/.test(v)) return 'font-weight';
+  if (/^\d+$/.test(v)) {
+    const n = Number(v);
+    if (n >= 100 && n <= 900 && n % 100 === 0) return 'font-weight';
+  }
+  if (/^\d*\.\d+$/.test(v) || /^[1-9](\.\d+)?$/.test(v)) return 'line-height';
+  // Last-ditch: a hint embedded in the variable name.
+  const name = cssVar.replace(/^--/, '').toLowerCase();
+  for (const g of VARIABLE_GROUPS) {
+    if (g.value !== 'other' && name.includes(g.value)) return g.value;
+  }
+  return 'other';
+}
+
+// ───────────────────────────────── serialize ─────────────────────────────────
+
+/** Group variables into ordered comment sections (VARIABLE_GROUPS order, 'Other' last). */
+function groupVariables(variables: CSSVariable[]): { label: string; vars: CSSVariable[] }[] {
+  const buckets = new Map<string, CSSVariable[]>();
+  for (const v of variables) {
+    const label = sectionLabelForGroup(v.group);
+    (buckets.get(label) ?? buckets.set(label, []).get(label)!).push(v);
+  }
+  const ordered: { label: string; vars: CSSVariable[] }[] = [];
+  for (const g of VARIABLE_GROUPS) {
+    if (g.value === 'other') continue;
+    const vars = buckets.get(g.label);
+    if (vars?.length) {
+      ordered.push({ label: g.label, vars });
+      buckets.delete(g.label);
+    }
+  }
+  for (const [label, vars] of buckets) if (vars.length) ordered.push({ label, vars });
+  return ordered;
+}
+
+/** `@media` blocks for the globally-scaled values (vars without an explicit override). */
+function buildAutoMediaBlocks(scalable: CSSVariable[], cfg: ScaleConfig): string {
+  const { breakpoints, responsiveScales } = cfg;
+  const baseRef = responsiveScales.baseReference || 16;
+  const sorted = Object.entries(breakpoints).sort((a, b) => b[1].breakpoint - a[1].breakpoint);
+  const blocks: string[] = [];
+  for (const [bpName, bp] of sorted) {
+    const lines: string[] = [];
+    for (const v of scalable) {
+      if (v.scales?.[bpName] !== undefined) continue; // explicit override → handled in overrides region
+      const categoryScales = responsiveScales[v.type] as BreakpointScales | undefined;
+      const scale = categoryScales?.[bpName];
+      if (scale == null) continue;
+      const scaled = scalePropertyValue(v.value, baseRef, scale);
+      if (scaled !== null && scaled !== v.value) lines.push(`    ${v.cssVar}: ${scaled};`);
+    }
+    if (lines.length) blocks.push(`@media (max-width: ${bp.breakpoint}px) {\n  :root {\n${lines.join('\n')}\n  }\n}`);
+  }
+  return blocks.join('\n\n');
+}
+
+/** `@media` blocks for explicit per-variable overrides (always emitted; authored data). */
+function buildOverrideMediaBlocks(variables: CSSVariable[], breakpoints: BreakpointConfig): string {
+  const sorted = Object.entries(breakpoints).sort((a, b) => b[1].breakpoint - a[1].breakpoint);
+  const blocks: string[] = [];
+  for (const [bpName, bp] of sorted) {
+    const lines: string[] = [];
+    for (const v of variables) {
+      const override = v.scales?.[bpName];
+      if (override !== undefined && override !== v.value) lines.push(`    ${v.cssVar}: ${override};`);
+    }
+    if (lines.length) blocks.push(`@media (max-width: ${bp.breakpoint}px) {\n  :root {\n${lines.join('\n')}\n  }\n}`);
+  }
+  return blocks.join('\n\n');
+}
+
+/**
+ * Serialize a {@link ThemeModel} to a canonical `theme.css`. The base `:root` carries the
+ * authored values (colors under `/* Colors *​/`, variables under their group sections); the
+ * AUTO `@media` region is regenerated from `scaleConfig` and only emitted when responsive
+ * scaling is enabled; the OVERRIDES region is always emitted; `raw` is appended verbatim.
+ */
+export function serializeThemeCss(model: ThemeModel, scaleConfig: ScaleConfig): string {
+  const { themes, variables, raw = [] } = model;
+  const palette = themes?.palette;
+  const defaultName = themes?.default ?? 'default';
+  const defaultTheme = themes?.themes?.[defaultName];
+
+  const sections: string[] = [];
+  const colorEntries = Object.entries(defaultTheme?.colors ?? {});
+  if (colorEntries.length) {
+    sections.push(
+      [
+        `  /* ${COLORS_LABEL}: ${defaultName} */`,
+        ...colorEntries.map(([k, val]) => `  --${k}: ${resolvePaletteColor(val, palette)};`),
+      ].join('\n'),
+    );
+  }
+  for (const { label, vars } of groupVariables(variables)) {
+    sections.push([`  /* ${label} */`, ...vars.map((v) => `  ${v.cssVar}: ${v.value};`)].join('\n'));
+  }
+
+  const blocks: string[] = [HEADER_BANNER];
+  blocks.push(sections.length ? `:root {\n${sections.join('\n\n')}\n}` : ':root {}');
+
+  for (const [name, theme] of Object.entries(themes?.themes ?? {})) {
+    if (name === defaultName) continue; // default lives on :root
+    const lines = Object.entries(theme.colors ?? {}).map(
+      ([k, val]) => `  --${k}: ${resolvePaletteColor(val, palette)};`,
+    );
+    if (lines.length) blocks.push(`[theme="${name}"] {\n${lines.join('\n')}\n}`);
+  }
+
+  if (scaleConfig.responsiveScales?.enabled) {
+    const auto = buildAutoMediaBlocks(
+      variables.filter((v) => v.type && v.type !== 'none'),
+      scaleConfig,
+    );
+    if (auto) blocks.push(AUTO_BANNER, auto);
+  }
+  const overrides = buildOverrideMediaBlocks(variables, scaleConfig.breakpoints);
+  if (overrides) blocks.push(OVERRIDES_BANNER, overrides);
+
+  for (const r of raw) {
+    const t = r.trim();
+    if (t) blocks.push(t);
+  }
+
+  return `${blocks.join('\n\n')}\n`;
+}
+
+// ───────────────────────────────── tokenizer ─────────────────────────────────
+
+type TopNode =
+  | { kind: 'comment'; text: string; raw: string }
+  | { kind: 'block'; prelude: string; body: string; raw: string }
+  | { kind: 'statement'; raw: string };
+
+type DeclItem = { kind: 'comment'; text: string } | { kind: 'decl'; prop: string; value: string };
+
+/** Advance past a quoted string starting at `i` (handles backslash escapes). */
+function skipString(s: string, i: number): number {
+  const q = s[i];
+  i++;
+  while (i < s.length) {
+    if (s[i] === '\\') {
+      i += 2;
+      continue;
+    }
+    if (s[i] === q) return i + 1;
+    i++;
+  }
+  return i;
+}
+
+/** Read a balanced `{ … }` block starting at the `{` index; returns inner body + end index. */
+function readBlock(s: string, open: number): { body: string; end: number } {
+  let i = open + 1;
+  let depth = 1;
+  const bodyStart = i;
+  while (i < s.length && depth > 0) {
+    if (s[i] === '/' && s[i + 1] === '*') {
+      const e = s.indexOf('*/', i + 2);
+      i = e === -1 ? s.length : e + 2;
+      continue;
+    }
+    if (s[i] === '"' || s[i] === "'") {
+      i = skipString(s, i);
+      continue;
+    }
+    if (s[i] === '{') depth++;
+    else if (s[i] === '}') {
+      depth--;
+      if (depth === 0) break;
+    }
+    i++;
+  }
+  return { body: s.slice(bodyStart, i), end: i < s.length ? i + 1 : s.length };
+}
+
+/** Split CSS into ordered top-level nodes (comments, `selector { … }` blocks, statements). */
+function scanTopLevel(css: string): TopNode[] {
+  const nodes: TopNode[] = [];
+  let i = 0;
+  while (i < css.length) {
+    while (i < css.length && /\s/.test(css[i]!)) i++;
+    if (i >= css.length) break;
+    if (css[i] === '/' && css[i + 1] === '*') {
+      const e = css.indexOf('*/', i + 2);
+      const stop = e === -1 ? css.length : e + 2;
+      const text = css.slice(i, stop);
+      nodes.push({ kind: 'comment', text, raw: text });
+      i = stop;
+      continue;
+    }
+    const start = i;
+    while (i < css.length) {
+      const c = css[i]!;
+      if (c === '/' && css[i + 1] === '*') {
+        const e = css.indexOf('*/', i + 2);
+        i = e === -1 ? css.length : e + 2;
+        continue;
+      }
+      if (c === '"' || c === "'") {
+        i = skipString(css, i);
+        continue;
+      }
+      if (c === '{' || c === ';') break;
+      i++;
+    }
+    if (i < css.length && css[i] === '{') {
+      const prelude = css.slice(start, i).trim();
+      const { body, end } = readBlock(css, i);
+      nodes.push({ kind: 'block', prelude, body, raw: css.slice(start, end) });
+      i = end;
+    } else {
+      const stop = i < css.length ? i + 1 : css.length;
+      const raw = css.slice(start, stop).trim();
+      if (raw) nodes.push({ kind: 'statement', raw });
+      i = stop;
+    }
+  }
+  return nodes;
+}
+
+/** Parse a rule body into ordered declarations + inline comments (for section detection). */
+function scanDeclarations(body: string): DeclItem[] {
+  const items: DeclItem[] = [];
+  let i = 0;
+  while (i < body.length) {
+    while (i < body.length && /\s/.test(body[i]!)) i++;
+    if (i >= body.length) break;
+    if (body[i] === '/' && body[i + 1] === '*') {
+      const e = body.indexOf('*/', i + 2);
+      const stop = e === -1 ? body.length : e + 2;
+      items.push({ kind: 'comment', text: body.slice(i, stop) });
+      i = stop;
+      continue;
+    }
+    const start = i;
+    while (i < body.length) {
+      const c = body[i]!;
+      if (c === '/' && body[i + 1] === '*') {
+        const e = body.indexOf('*/', i + 2);
+        i = e === -1 ? body.length : e + 2;
+        continue;
+      }
+      if (c === '"' || c === "'") {
+        i = skipString(body, i);
+        continue;
+      }
+      if (c === ';') break;
+      i++;
+    }
+    const text = body.slice(start, i).trim();
+    i = i < body.length ? i + 1 : body.length;
+    const colon = text.indexOf(':');
+    if (colon > 0) {
+      items.push({ kind: 'decl', prop: text.slice(0, colon).trim(), value: text.slice(colon + 1).trim() });
+    }
+  }
+  return items;
+}
+
+// ───────────────────────────────── parse ─────────────────────────────────
+
+/** Inner text of a `/* … *​/` comment, trimmed. */
+function commentInner(text: string): string {
+  return text
+    .replace(/^\/\*+/, '')
+    .replace(/\*+\/$/, '')
+    .trim();
+}
+
+function isHeaderBanner(text: string): boolean {
+  const t = commentInner(text);
+  return /meno design tokens/i.test(t) || /AUTO-GENERATED by meno-astro/i.test(t);
+}
+
+function prettifyName(name: string): string {
+  return name
+    .replace(/[-_]/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function maxWidthPx(prelude: string): number | null {
+  const m = prelude.match(/max-width:\s*(\d+)px/i);
+  return m ? Number(m[1]) : null;
+}
+
+function bpNameForPx(px: number, breakpoints: BreakpointConfig): string | null {
+  for (const [name, entry] of Object.entries(breakpoints)) if (entry.breakpoint === px) return name;
+  return null;
+}
+
+/**
+ * Parse a `theme.css` into a {@link ThemeModel}. `breakpoints` (from project.config.json)
+ * maps the OVERRIDES `@media (max-width: Npx)` blocks back to breakpoint names; the AUTO
+ * region is discarded (it is regenerated on serialize) and any unmodeled CSS is preserved
+ * in `raw`.
+ */
+export function parseThemeCss(css: string, breakpoints?: BreakpointConfig): ThemeModel {
+  const themesMap: Record<string, Theme> = {};
+  const variables: CSSVariable[] = [];
+  const varByCssVar = new Map<string, CSSVariable>();
+  const raw: string[] = [];
+  let defaultName: string | null = null;
+  let region: 'auto' | 'overrides' | null = null;
+
+  for (const node of scanTopLevel(css)) {
+    if (node.kind === 'comment') {
+      if (isHeaderBanner(node.text)) continue;
+      const inner = commentInner(node.text);
+      if (/responsive overrides/i.test(inner)) {
+        region = 'overrides';
+        continue;
+      }
+      if (/responsive scaling|auto-generated from project\.config/i.test(inner)) {
+        region = 'auto';
+        continue;
+      }
+      raw.push(node.raw);
+      continue;
+    }
+    if (node.kind === 'statement') {
+      raw.push(node.raw);
+      continue;
+    }
+
+    const sel = node.prelude;
+
+    if (sel === ':root') {
+      let section: VariableGroup | 'colors' | null = null;
+      for (const it of scanDeclarations(node.body)) {
+        if (it.kind === 'comment') {
+          const inner = commentInner(it.text);
+          if (/^colors\b/i.test(inner)) {
+            section = 'colors';
+            const dn = inner.match(/^colors\s*:\s*([\w-]+)/i);
+            if (dn) defaultName = dn[1]!;
+          } else {
+            const g = groupForSectionLabel(inner);
+            if (g) section = g;
+          }
+          continue;
+        }
+        if (!it.prop.startsWith('--')) continue;
+        const name = it.prop.slice(2);
+        if (section === 'colors' || (section === null && isColorValue(it.value))) {
+          const dn = (defaultName ??= 'default');
+          (themesMap[dn] ??= { colors: {} }).colors[name] = it.value;
+        } else {
+          const group = section ?? inferGroup(it.prop, it.value);
+          const v: CSSVariable = { cssVar: it.prop, value: it.value, type: getDefaultScalingType(group), group };
+          variables.push(v);
+          varByCssVar.set(it.prop, v);
+        }
+      }
+      continue;
+    }
+
+    const themeMatch = sel.match(/^\[theme=["']?([^"'\]]+)["']?\]$/);
+    if (themeMatch) {
+      const theme = (themesMap[themeMatch[1]!] ??= { colors: {} });
+      for (const it of scanDeclarations(node.body)) {
+        if (it.kind === 'decl' && it.prop.startsWith('--')) theme.colors[it.prop.slice(2)] = it.value;
+      }
+      continue;
+    }
+
+    if (/^@media\b/i.test(sel)) {
+      const px = maxWidthPx(sel);
+      if (region === 'auto') continue; // regenerated on serialize
+      const bpName = px != null && breakpoints ? bpNameForPx(px, breakpoints) : null;
+      if (!bpName) {
+        raw.push(node.raw); // can't map to a breakpoint → preserve verbatim
+        continue;
+      }
+      for (const inner of scanTopLevel(node.body)) {
+        if (inner.kind !== 'block' || inner.prelude !== ':root') continue;
+        for (const it of scanDeclarations(inner.body)) {
+          if (it.kind !== 'decl' || !it.prop.startsWith('--')) continue;
+          const v = varByCssVar.get(it.prop);
+          if (v) (v.scales ??= {})[bpName] = it.value;
+        }
+      }
+      continue;
+    }
+
+    raw.push(node.raw); // foreign rule (@font-face, @keyframes, other selectors) — keep as-is
+  }
+
+  if (!defaultName) defaultName = Object.keys(themesMap)[0] ?? 'default';
+  (themesMap[defaultName] ??= { colors: {} }).label ??= prettifyName(defaultName);
+  for (const [name, t] of Object.entries(themesMap)) t.label ??= prettifyName(name);
+
+  return { themes: { default: defaultName, themes: themesMap }, variables, raw };
+}

package/lib/server/themeCssStore.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setProjectRoot } from './projectContext';
+import { loadThemeModel, saveColors, saveVariables, themeCssPath, isThemeCssProject } from './themeCssStore';
+import type { ThemeConfig } from '../shared/types/colors';
+
+const tmps: string[] = [];
+
+async function makeProject(opts?: { colors?: unknown; variables?: unknown }): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'meno-theme-'));
+  tmps.push(root);
+  await mkdir(join(root, 'src', 'pages'), { recursive: true });
+  await writeFile(
+    join(root, 'project.config.json'),
+    JSON.stringify({
+      format: 'astro',
+      breakpoints: { tablet: { breakpoint: 1024, previewPoint: 768 }, mobile: { breakpoint: 540, previewPoint: 375 } },
+    }),
+  );
+  if (opts?.colors) await writeFile(join(root, 'colors.json'), JSON.stringify(opts.colors));
+  if (opts?.variables) await writeFile(join(root, 'variables.json'), JSON.stringify(opts.variables));
+  setProjectRoot(root);
+  return root;
+}
+
+afterEach(async () => {
+  while (tmps.length) await rm(tmps.pop()!, { recursive: true, force: true });
+});
+
+describe('themeCssStore', () => {
+  test('detects astro projects', async () => {
+    const root = await makeProject();
+    expect(isThemeCssProject(root)).toBe(true);
+  });
+
+  test('migrates legacy colors.json + variables.json into theme.css, then deletes them', async () => {
+    const root = await makeProject({
+      colors: { default: 'light', themes: { light: { label: 'Light', colors: { text: '#111' } } } },
+      variables: { variables: [{ cssVar: '--h1', value: '48px', type: 'fontSize', group: 'font-size' }] },
+    });
+
+    const model = await loadThemeModel();
+    expect(model.themes.themes.light?.colors.text).toBe('#111');
+    expect(model.variables.find((v) => v.cssVar === '--h1')?.value).toBe('48px');
+
+    // theme.css written; JSON removed
+    expect(existsSync(themeCssPath(root))).toBe(true);
+    expect(existsSync(join(root, 'colors.json'))).toBe(false);
+    expect(existsSync(join(root, 'variables.json'))).toBe(false);
+
+    const css = await readFile(themeCssPath(root), 'utf8');
+    expect(css).toContain('--text: #111;');
+    expect(css).toContain('--h1: 48px;');
+  });
+
+  test('saveColors preserves variables; saveVariables preserves colors', async () => {
+    await makeProject({
+      colors: { default: 'light', themes: { light: { colors: { text: '#111' } } } },
+      variables: { variables: [{ cssVar: '--h1', value: '48px', type: 'fontSize', group: 'font-size' }] },
+    });
+    await loadThemeModel(); // trigger migration
+
+    const newColors: ThemeConfig = {
+      default: 'light',
+      themes: { light: { colors: { text: '#222', accent: '#f00' } } },
+    };
+    await saveColors(newColors);
+    let model = await loadThemeModel();
+    expect(model.themes.themes.light?.colors).toEqual({ text: '#222', accent: '#f00' });
+    expect(model.variables.find((v) => v.cssVar === '--h1')?.value).toBe('48px'); // variables preserved
+
+    await saveVariables([{ cssVar: '--h1', value: '40px', type: 'fontSize', group: 'font-size' }]);
+    model = await loadThemeModel();
+    expect(model.variables.find((v) => v.cssVar === '--h1')?.value).toBe('40px');
+    expect(model.themes.themes.light?.colors.accent).toBe('#f00'); // colors preserved
+  });
+
+  test('existing astro project (old DERIVED theme.css + JSON) migrates from JSON authoritatively', async () => {
+    const root = await makeProject({
+      colors: { default: 'light', themes: { light: { colors: { text: '#111' } }, dark: { colors: { text: '#fff' } } } },
+      variables: { variables: [{ cssVar: '--h1', value: '48px', type: 'fontSize', group: 'font-size' }] },
+    });
+    // Simulate the previous converter's old-format derived theme.css: no header, unsectioned
+    // :root default colors + a duplicate [theme="light"] block. This must NOT leak a bogus theme.
+    await mkdir(join(root, 'src', 'styles'), { recursive: true });
+    await writeFile(
+      themeCssPath(root),
+      ':root {\n  --text: #111;\n}\n\n[theme="light"] {\n  --text: #111;\n}\n\n[theme="dark"] {\n  --text: #fff;\n}\n',
+    );
+
+    const model = await loadThemeModel();
+    expect(model.themes.default).toBe('light');
+    expect(Object.keys(model.themes.themes).sort()).toEqual(['dark', 'light']); // no spurious 'default'
+    expect(model.variables.find((v) => v.cssVar === '--h1')?.value).toBe('48px');
+
+    const css = await readFile(themeCssPath(root), 'utf8');
+    expect(css).toContain('Meno design tokens'); // rebuilt in the new authored format
+    expect(css).toContain('/* Colors: light */');
+  });
+
+  test('a JSON overlay written after theme.css exists is folded in (union, theme.css wins)', async () => {
+    const root = await makeProject({
+      colors: { default: 'light', themes: { light: { colors: { text: '#111' } } } },
+      variables: { variables: [{ cssVar: '--h1', value: '48px', type: 'fontSize', group: 'font-size' }] },
+    });
+    await loadThemeModel(); // migrate → theme.css only
+
+    // Simulate an external tool (e.g. the style-guide applier) dropping JSON overlays.
+    await writeFile(
+      join(root, 'colors.json'),
+      JSON.stringify({ default: 'light', themes: { light: { colors: { text: '#999', accent: '#0f0' } } } }),
+    );
+    await writeFile(
+      join(root, 'variables.json'),
+      JSON.stringify({ variables: [{ cssVar: '--h2', value: '32px', type: 'fontSize', group: 'font-size' }] }),
+    );
+
+    const model = await loadThemeModel();
+    // existing theme.css value wins on conflict; overlay adds the new key
+    expect(model.themes.themes.light?.colors).toEqual({ text: '#111', accent: '#0f0' });
+    // existing variable kept; overlay variable appended
+    expect(model.variables.map((v) => v.cssVar).sort()).toEqual(['--h1', '--h2']);
+    // overlay JSON consumed
+    expect(existsSync(join(root, 'colors.json'))).toBe(false);
+    expect(existsSync(join(root, 'variables.json'))).toBe(false);
+  });
+
+  test('a project with no JSON loads as empty and accepts saves', async () => {
+    await makeProject();
+    const model = await loadThemeModel();
+    expect(model.variables).toEqual([]);
+    await saveVariables([{ cssVar: '--gap', value: '16px', type: 'gap', group: 'gap' }]);
+    const back = await loadThemeModel();
+    expect(back.variables.find((v) => v.cssVar === '--gap')?.value).toBe('16px');
+  });
+});