meno-core 1.1.1 → 1.1.3

package/lib/server/themeCssStore.ts

@@ -0,0 +1,210 @@
+/**
+ * theme.css store — the read/modify/write layer over a project's `src/styles/theme.css`,
+ * which is the single source of truth for design tokens (colors + variables). It replaces
+ * the old `colors.json` / `variables.json` pair for astro-format projects.
+ *
+ * Colors and variables share ONE file, so {@link saveColors} / {@link saveVariables} each
+ * re-read the current file and replace only their half (preserving the other half AND any
+ * `raw` passthrough), then re-serialize. All writes are funnelled through a single in-process
+ * queue so a colors save and a variables save can't clobber each other.
+ *
+ * On first access for a project that still carries legacy JSON, {@link migrateIfNeeded}
+ * regenerates theme.css from those JSON files (authoritative) and deletes them — a one-way,
+ * idempotent migration. Legacy JSON-format projects (no `src/pages`) are not handled here;
+ * the services keep their JSON path for those.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getProjectRoot } from './projectContext';
+import { writeFile, readTextFile, fileExists, ensureDir } from './runtime';
+import { configService } from './services/configService';
+import { parseThemeCss, serializeThemeCss, type ScaleConfig, type ThemeModel } from './themeCssCodec';
+import type { ThemeConfig } from '../shared/types/colors';
+import type { CSSVariable } from '../shared/types/variables';
+import { createLogger } from '../shared/logger';
+
+const log = createLogger('themeCssStore');
+
+/** Absolute path to a project's theme stylesheet. */
+export function themeCssPath(root: string = getProjectRoot()): string {
+  return join(root, 'src', 'styles', 'theme.css');
+}
+
+/**
+ * True when a project keeps its tokens in `theme.css` (astro-format). Detected by an
+ * existing theme.css, an `src/pages` layout, or an explicit `"format": "astro"`. Legacy
+ * JSON-format projects return false and keep reading colors.json / variables.json.
+ */
+export function isThemeCssProject(root: string = getProjectRoot()): boolean {
+  if (existsSync(themeCssPath(root))) return true;
+  if (existsSync(join(root, 'src', 'pages'))) return true;
+  try {
+    const cfg = JSON.parse(readFileSync(join(root, 'project.config.json'), 'utf8')) as { format?: string };
+    if (cfg.format === 'astro') return true;
+  } catch {
+    /* no/invalid config → not astro */
+  }
+  return false;
+}
+
+// All writes (and the migration) run serialized so concurrent color/variable saves
+// read-modify-write the shared file without races.
+let writeChain: Promise<unknown> = Promise.resolve();
+function enqueue<T>(fn: () => Promise<T>): Promise<T> {
+  const run = writeChain.then(fn, fn);
+  writeChain = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+async function readJsonSafe<T>(path: string): Promise<T | null> {
+  try {
+    return JSON.parse(await readTextFile(path)) as T;
+  } catch {
+    return null;
+  }
+}
+
+function scaleConfig(): ScaleConfig {
+  return { breakpoints: configService.getBreakpoints(), responsiveScales: configService.getResponsiveScales() };
+}
+
+/** Empty-but-valid model for a project with no theme.css yet. */
+function emptyModel(): ThemeModel {
+  return { themes: { default: 'default', themes: { default: { colors: {} } } }, variables: [], raw: [] };
+}
+
+/** Parse the on-disk theme.css (or an empty model if absent). Assumes config is loaded. */
+async function readModel(root: string): Promise<ThemeModel> {
+  const path = themeCssPath(root);
+  if (!(await fileExists(path))) return emptyModel();
+  return parseThemeCss(await readTextFile(path), configService.getBreakpoints());
+}
+
+/** Serialize + persist a model (creating `src/styles` as needed). Assumes config is loaded. */
+async function writeModel(root: string, model: ThemeModel): Promise<void> {
+  const css = serializeThemeCss(model, scaleConfig());
+  await ensureDir(join(root, 'src', 'styles'));
+  await writeFile(themeCssPath(root), css);
+}
+
+/** True when a theme has at least one color (i.e. theme.css already holds real tokens). */
+function hasColors(themes: ThemeConfig): boolean {
+  return Object.values(themes.themes ?? {}).some((t) => Object.keys(t.colors ?? {}).length > 0);
+}
+
+/** Union of two theme configs — `current` (theme.css) wins on conflict; incoming adds keys. */
+function mergeThemes(current: ThemeConfig, incoming: ThemeConfig | null): ThemeConfig {
+  if (!incoming?.themes) return current;
+  if (!hasColors(current)) return incoming; // empty theme.css → adopt the JSON wholesale
+  const out: ThemeConfig = { default: current.default, palette: current.palette, themes: { ...current.themes } };
+  for (const [name, theme] of Object.entries(incoming.themes)) {
+    const existing = out.themes[name];
+    out.themes[name] = existing ? { ...existing, colors: { ...theme.colors, ...existing.colors } } : theme;
+  }
+  return out;
+}
+
+/** Union of two variable lists by `cssVar` — `current` wins on conflict; incoming adds new. */
+function mergeVariables(current: CSSVariable[], incoming: CSSVariable[] | undefined): CSSVariable[] {
+  if (!incoming?.length) return current;
+  const seen = new Set(current.map((v) => v.cssVar));
+  return [...current, ...incoming.filter((v) => !seen.has(v.cssVar))];
+}
+
+/** Marker the serializer always stamps — distinguishes an authored theme.css from a derived one. */
+const AUTHORED_MARKER = 'Meno design tokens';
+
+/**
+ * Fold a project's `colors.json` + `variables.json` into theme.css, then delete the JSON.
+ * Serves two cases:
+ *   - Legacy migration — theme.css is absent or in the OLD derived format (the previous
+ *     converter's DO-NOT-EDIT output). The JSON is authoritative: theme.css is rebuilt from it
+ *     (we must NOT merge the derived file, whose unsectioned `:root` + duplicate `[theme]` blocks
+ *     would parse into a bogus extra theme).
+ *   - Overlay — theme.css is already authored (new format) and an external tool (e.g. the
+ *     style-guide applier) dropped JSON additions. A UNION merge (theme.css wins on key conflict,
+ *     JSON adds new keys) folds those in without clobbering anything.
+ * Foreign CSS (`raw`, e.g. @font-face) is preserved either way. No-op when no JSON is present, so
+ * it's safe to run on every load/save. Must be called inside {@link enqueue}.
+ */
+async function migrateIfNeeded(root: string): Promise<void> {
+  const colorsJson = join(root, 'colors.json');
+  const variablesJson = join(root, 'variables.json');
+  const hasColorsJson = existsSync(colorsJson);
+  const hasVarsJson = existsSync(variablesJson);
+  if (!hasColorsJson && !hasVarsJson) return;
+  try {
+    const jsonColors = hasColorsJson ? await readJsonSafe<ThemeConfig>(colorsJson) : null;
+    const jsonVars = hasVarsJson ? await readJsonSafe<{ variables: CSSVariable[] }>(variablesJson) : null;
+
+    let current = emptyModel();
+    let authored = false;
+    if (await fileExists(themeCssPath(root))) {
+      const text = await readTextFile(themeCssPath(root));
+      authored = text.includes(AUTHORED_MARKER);
+      current = parseThemeCss(text, configService.getBreakpoints());
+    }
+    // Authored → overlay-merge (theme.css wins). Derived/absent → JSON authoritative (base empty),
+    // but keep any foreign CSS the derived file happened to carry.
+    const base = authored ? current : emptyModel();
+    const merged: ThemeModel = {
+      themes: mergeThemes(base.themes, jsonColors?.themes ? jsonColors : null),
+      variables: mergeVariables(base.variables, jsonVars?.variables),
+      raw: current.raw,
+    };
+    await writeModel(root, merged);
+    await rm(colorsJson, { force: true });
+    await rm(variablesJson, { force: true });
+    log.info('Folded colors.json / variables.json into src/styles/theme.css');
+  } catch (err) {
+    // Leave the JSON in place so a later attempt can retry; surface but don't throw.
+    log.warn('theme.css migration failed; keeping JSON files:', err);
+  }
+}
+
+/** Load the full token model (runs the one-time JSON→theme.css migration first). */
+export async function loadThemeModel(root: string = getProjectRoot()): Promise<ThemeModel> {
+  await configService.load();
+  return enqueue(async () => {
+    await migrateIfNeeded(root);
+    return readModel(root);
+  });
+}
+
+/** Persist colors (themes) into theme.css, preserving the variables + raw already there. */
+export async function saveColors(themes: ThemeConfig, root: string = getProjectRoot()): Promise<void> {
+  await configService.load();
+  return enqueue(async () => {
+    await migrateIfNeeded(root);
+    const current = await readModel(root);
+    await writeModel(root, { themes, variables: current.variables, raw: current.raw });
+  });
+}
+
+/** Persist variables into theme.css, preserving the colors + raw already there. */
+export async function saveVariables(variables: CSSVariable[], root: string = getProjectRoot()): Promise<void> {
+  await configService.load();
+  return enqueue(async () => {
+    await migrateIfNeeded(root);
+    const current = await readModel(root);
+    await writeModel(root, { themes: current.themes, variables, raw: current.raw });
+  });
+}
+
+/**
+ * Re-serialize theme.css from its own current contents — used after a `project.config.json`
+ * scale-knob change to regenerate the AUTO `@media` region from the new config.
+ */
+export async function regenerateThemeCss(root: string = getProjectRoot()): Promise<void> {
+  await configService.load();
+  return enqueue(async () => {
+    await migrateIfNeeded(root);
+    if (!(await fileExists(themeCssPath(root)))) return;
+    await writeModel(root, await readModel(root));
+  });
+}

package/lib/shared/nodeUtils.ts

@@ -91,6 +91,24 @@ export function isHtmlNode(node: ComponentNode | null | undefined): node is Html
   return node?.type === NODE_TYPE.NODE;
 }
 
+/**
+ * Whether a node stores its utility-class styling on `attributes.class` — the class-styling system's
+ * `attributes.class` storage path. HTML elements plus the html-like content nodes (embed/link/markdown)
+ * qualify: each carries a `style` AND an `attributes` map, and the codec already round-trips a class on
+ * them. Component instances are NOT included here — they store on the `class` PROP (a separate
+ * eligibility path; see isClassEligible / migrateOneNode, the two callers that must agree). Excluded:
+ * list/island/slot/custom (`canHaveStyle:false` or no styling model) and locale-list (its root class is
+ * not codec-wired yet — joins in Phase 2). Single source of truth for "what can hold an `attributes.class`".
+ */
+export function isClassStylableNode(node: ComponentNode | null | undefined): boolean {
+  return (
+    node?.type === NODE_TYPE.NODE ||
+    node?.type === NODE_TYPE.EMBED ||
+    node?.type === NODE_TYPE.LINK ||
+    node?.type === NODE_TYPE.MARKDOWN
+  );
+}
+
 /**
  * Get the component name from a ComponentNode (for component instances)
  */

package/lib/shared/types/colors.ts

@@ -12,10 +12,14 @@ export interface ColorVariables {
 }
 
 /**
- * Theme configuration with color set and metadata
+ * Theme configuration with color set and metadata.
+ *
+ * `label` is an editor-only display string. The theme.css codec does not persist
+ * it (a theme is identified by its name — the `[theme="<name>"]` selector), so it
+ * is optional; consumers fall back to the (prettified) theme name.
  */
 export interface Theme {
-  label: string;
+  label?: string;
   colors: Record<string, string>;
 }
 

package/lib/shared/types/variables.ts

@@ -146,22 +146,29 @@ export function getGroupForProperty(prop: string): VariableGroup | null {
 }
 
 /**
- * A single CSS custom property definition
+ * A single CSS custom property definition.
+ *
+ * Source of truth is `src/styles/theme.css` (the `theme.css` codec), so the CSS
+ * variable name (`cssVar`) IS a token's identity — `name`/`prop_name` are
+ * editor-only labels that the codec no longer persists, and `group`/`type` are
+ * DERIVED on parse (from the var's comment-section header, falling back to a
+ * value heuristic), not stored. They stay on the in-memory object because the
+ * pickers and the responsive-scaling generator still consult them.
  */
 export interface CSSVariable {
-  /** Display name (e.g., "H1 Font Size") */
-  name: string;
-  /** Optional prop name alias for organizational purposes */
+  /** Optional display label. Not persisted by the theme.css codec — defaults to `cssVar`. */
+  name?: string;
+  /** Optional prop name alias for organizational purposes (legacy; not persisted). */
   prop_name?: string;
-  /** CSS custom property name (e.g., "--h1-fs") */
+  /** CSS custom property name (e.g., "--h1-fs") — the token's persistent identity. */
   cssVar: string;
   /** Base value (e.g., "48px") */
   value: string;
-  /** Category for responsive scaling */
+  /** Category for responsive scaling (derived from {@link group} via getDefaultScalingType). */
   type: VariableType;
   /** Optional per-variable breakpoint scale overrides */
   scales?: Record<string, string>;
-  /** Optional UI filtering group for the variable picker */
+  /** UI filtering group for the variable picker (derived from the theme.css comment section). */
   group?: VariableGroup;
 }
 

package/lib/shared/utilityClassMapper.test.ts

@@ -97,6 +97,16 @@ describe('utilityClassMapper', () => {
       expect(classToStyle('font-(--l-ff)')).toEqual({ prop: 'fontFamily', value: 'var(--l-ff)' });
     });
 
+    test('a color var whose token name can NOT be a bare token uses the arbitrary form + round-trips', () => {
+      // A CSS-color name (`--salmon`) or palette-shaped name (`--text-100`) can't be a bare token
+      // (`bg-salmon` would render the CSS color salmon), and the `bg-(--x)` shorthand reverses to the
+      // bare value — dropping var(). The arbitrary form keeps the variable exact and reverses cleanly,
+      // so the value can live in a class instead of the style object (static AND interactive styles).
+      expect(stylesToClasses({ backgroundColor: 'var(--salmon)' })).toContain('bg-[var(--salmon)]');
+      expect(stylesToClasses({ color: 'var(--text-100)' })).toContain('text-[var(--text-100)]');
+      expect(classToStyle('bg-[var(--salmon)]')).toEqual({ prop: 'backgroundColor', value: 'var(--salmon)' });
+    });
+
     test('border/outline shorthand var binding stays the shorthand (not the color longhand)', () => {
       // `border`/`outline` roots are shared by a shorthand and a color longhand. A `var(--x)` value
       // is opaque and reads as a color, so the bare `border-(--x)` form would round-trip to

package/lib/shared/utilityClassMapper.ts

@@ -243,9 +243,17 @@ function propertyValueToClass(prop: string, value: string | number): string | nu
       }
       // A `var(--token)` on a color-token prop IS a Meno token reference → emit the bare token
       // form (`bg-muted`), matching the bare-value path so `var(--muted)` and `muted` agree.
-      // (Token-aware inverse recovers it; palette-shaped names fall through to the var shorthand.)
+      // (Token-aware inverse recovers it; palette-shaped names fall through to the arbitrary form.)
       else if (colorTokenProps.has(prop) && isBareColorTokenName(varName)) {
         className = `${root}-${varName}`;
+      }
+      // A color var whose token name can't be a bare token — a CSS color name (`--salmon`) or a
+      // palette-shaped name (`--text-100`). The `root-(--x)` shorthand would reverse to the BARE
+      // value (classToStyle strips `var()` for color props), losing the variable — and a CSS-color
+      // name would then render as the literal color. The arbitrary form keeps `var(--x)` exact and
+      // round-trips losslessly (`bg-[var(--x)]` → `var(--x)`), so the value can live in a class.
+      else if (colorTokenProps.has(prop)) {
+        className = `${root}-[var(${varMatch[1]})]`;
       } else className = `${root}-(${varMatch[1]})`;
     }
   }

package/lib/shared/validation/schemas.test.ts

@@ -201,6 +201,84 @@ describe('Schema Validation', () => {
     });
   });
 
+  describe('list prop authoring mistakes surface a clear, prop-named error', () => {
+    // Collect every message in a zod error tree (union branches included), so
+    // assertions don't depend on which branch zod happens to surface.
+    const allMessages = (error: import('zod').ZodError): string[] => {
+      const out: string[] = [];
+      const walk = (issues: import('zod').ZodIssue[]) => {
+        for (const issue of issues) {
+          out.push(issue.message);
+          if (issue.code === 'invalid_union') {
+            for (const ue of (issue as import('zod').ZodInvalidUnionIssue).unionErrors) walk(ue.errors);
+          }
+        }
+      };
+      walk(error.issues);
+      return out;
+    };
+
+    test('a bare-string `default` with no `itemSchema` is rejected with the list-prop requirement', () => {
+      // The single most common first guess. The codec round-trips it and
+      // `astro build` renders it, so the editor load path is the only guard.
+      const propDef = { type: 'list', default: ['First', 'Second'] };
+
+      const result = PropDefinitionSchema.safeParse(propDef);
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(allMessages(result.error).some((m) => m.includes('list prop requires `itemSchema`'))).toBe(true);
+      }
+    });
+
+    test('an object-array `default` still requires `itemSchema`', () => {
+      const propDef = { type: 'list', default: [{ label: 'First' }] };
+      const result = PropDefinitionSchema.safeParse(propDef);
+      expect(result.success).toBe(false);
+    });
+
+    test('the correct form (itemSchema + object-array default) passes', () => {
+      const propDef = {
+        type: 'list',
+        itemSchema: { label: { type: 'string', default: 'Item' } },
+        default: [{ label: 'First' }, { label: 'Second' }],
+      };
+      expect(PropDefinitionSchema.safeParse(propDef).success).toBe(true);
+    });
+
+    test('a component file with a bad list prop reports the prop error, NOT the misleading JSONPage refine', () => {
+      // Regression for the union-dirty-branch bug: a `{ component }` payload
+      // whose list prop is malformed used to surface "JSONPage must have at
+      // least one of: meta, components, or root" (the page branch's refine),
+      // which names nothing useful. It must surface the list-prop error instead.
+      const componentFile = {
+        component: {
+          interface: { items: { type: 'list', default: ['a', 'b'] } },
+          structure: { type: 'node', tag: 'div', children: [] },
+        },
+      };
+
+      const result = PageDataSchema.safeParse(componentFile);
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        const messages = allMessages(result.error);
+        expect(messages.some((m) => m.includes('list prop requires `itemSchema`'))).toBe(true);
+        expect(messages.some((m) => m.includes('JSONPage must have'))).toBe(false);
+      }
+    });
+
+    test('an empty payload (a real page with no fields) still reports the JSONPage refine', () => {
+      // The guard only fires on a present `component` key — a genuinely empty
+      // page payload must keep its existing refine message.
+      const result = PageDataSchema.safeParse({});
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(allMessages(result.error).some((m) => m.includes('JSONPage must have'))).toBe(true);
+      }
+    });
+  });
+
   describe('Missing required fields handled', () => {
     test('prop definition without default', () => {
       const propDef = {

package/lib/shared/validation/schemas.ts

@@ -126,10 +126,47 @@ export const ListPropDefinitionSchema = z
   .passthrough();
 
 /**
- * Prop definition schema (union of base and list)
- * Validates prop definitions from component interfaces
+ * Prop definition schema — discriminates on `type` instead of a plain
+ * `z.union([List, Base])`.
+ *
+ * Why not a bare union: a `type: "list"` prop with a bad shape (the single most
+ * common authoring mistake — a bare-string `default` and/or a missing
+ * `itemSchema`, e.g. `{ type: "list", default: ["a", "b"] }`) matches NEITHER
+ * union branch (List wants `itemSchema` + an object-array `default`; Base's
+ * `type` enum has no `"list"`). The union then reports a noisy pile of
+ * cross-branch issues (`type` not in the base enum, `default[0]` expected object,
+ * …) — and, worse, when this prop sits inside a component file the outer
+ * `PageDataSchema` union surfaces the *page* branch's refine instead (see
+ * `JSONPageSchema` / `PageDataSchema` below), so the real error reads
+ * "JSONPage must have …root". The codec round-trips it and `astro build`
+ * renders it, so the only place it ever surfaces is here.
+ *
+ * Discriminating on `type` lets a list prop be validated by ONLY
+ * `ListPropDefinitionSchema` and collapses its failure into one actionable
+ * message that names the requirement, at the prop's own path.
  */
-export const PropDefinitionSchema = z.union([ListPropDefinitionSchema, BasePropDefinitionSchema]);
+export const PropDefinitionSchema = z
+  .object({ type: z.string() })
+  .passthrough()
+  .superRefine((val, ctx) => {
+    const branch = val.type === 'list' ? ListPropDefinitionSchema : BasePropDefinitionSchema;
+    const result = branch.safeParse(val);
+    if (result.success) return;
+    if (val.type === 'list') {
+      // Collapse the list-prop failure into one actionable message rather than
+      // replaying zod's per-field noise. `itemSchema` is required and `default`
+      // must be an array of OBJECTS (one `{ field: value }` record per item).
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          'list prop requires `itemSchema` and an object-array `default` ' +
+          '(each item is a `{ field: value }` object, not a bare string)',
+      });
+      return;
+    }
+    // Non-list props keep their precise per-field errors.
+    for (const issue of result.error.issues) ctx.addIssue(issue);
+  });
 
 /**
  * Style mapping schema
@@ -722,6 +759,14 @@ export const JSONPageSchema = z
     // Marks a page whose source is outside the meno-astro dialect (read-only in the editor).
     // Explicit (not just .passthrough()) so it survives a future tightening of this schema.
     _unsupported: z.object({ reason: z.string() }).passthrough().optional(),
+    // A component payload (`{ component: {...} }`) must NEVER validate as a page.
+    // Without this guard the page branch parses structurally (it's `.passthrough()`)
+    // and only trips the refine below — so when both branches of `PageDataSchema`
+    // fail, zod treats this branch as the "closest" (dirty) one and surfaces
+    // "JSONPage must have …root", masking the real component error (e.g. a malformed
+    // list prop). Rejecting a present `component` key makes this branch hard-fail on
+    // component payloads, so `PageDataSchema` reports the component branch instead.
+    component: z.undefined().optional(),
   })
   .passthrough()
   .refine(
@@ -752,8 +797,11 @@ export const PageDataWithComponentSchema = z
   .passthrough();
 
 /**
- * Page data schema - union of JSONPage and PageDataWithComponent
- * PageDataWithComponent checked first because it's more specific
+ * Page data schema - union of JSONPage and PageDataWithComponent.
+ * PageDataWithComponent is checked first because it's more specific; the
+ * `component: z.undefined()` guard on `JSONPageSchema` keeps a component payload
+ * from being mis-reported as a page (see that schema's comment), so a malformed
+ * prop surfaces its own error instead of the page-branch refine.
  */
 export const PageDataSchema = z.union([PageDataWithComponentSchema, JSONPageSchema]);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meno-core",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "type": "module",
   "bin": {
     "meno": "./dist/bin/cli.js"