blume 2.0.2 → 2.1.0

package/src/theme/palette.ts

@@ -1,21 +1,90 @@
 import type { ResolvedConfig } from "../core/schema.ts";
+import { composite, contrastRatio, parseColor } from "./color.ts";
+import type { Rgba } from "./color.ts";
 
-const FALLBACK_ACCENT = "oklch(0.62 0.16 250)";
+/** Per-mode CSS colors. */
+export interface AccentColors {
+  dark: string;
+  light: string;
+}
+
+/** A color mode. */
+export type ColorMode = keyof AccentColors;
 
 /**
- * Named accent presets mapped to OKLCH values. The single source of truth for
- * preset colors: the theme CSS and the OG card (og/card.ts) both resolve from
- * this table, so a site and its social cards can't disagree about "blue".
+ * Named accent presets mapped to OKLCH values, per mode. The single source of
+ * truth for preset colors: the theme CSS and the OG card (og/card.ts) both
+ * resolve from this table, so a site and its social cards can't disagree
+ * about "blue". Each clears WCAG AA (4.5:1) as text on its mode's page and
+ * under its button label ({@link readableOn}), with room to spare on the
+ * tinted surfaces accent text also sits on: the light shades are dark enough
+ * for white labels, the dark shades light enough to read on the dark page.
  */
 export const ACCENTS = {
-  blue: FALLBACK_ACCENT,
-  green: "oklch(0.6 0.16 150)",
-  orange: "oklch(0.68 0.17 50)",
-  pink: "oklch(0.65 0.2 350)",
-  purple: "oklch(0.58 0.2 290)",
-  red: "oklch(0.58 0.22 25)",
-  teal: "oklch(0.6 0.12 195)",
-} satisfies Record<string, string>;
+  blue: { dark: "oklch(0.62 0.16 250)", light: "oklch(0.55 0.16 250)" },
+  green: { dark: "oklch(0.6 0.16 150)", light: "oklch(0.53 0.16 150)" },
+  orange: { dark: "oklch(0.68 0.17 50)", light: "oklch(0.56 0.17 50)" },
+  pink: { dark: "oklch(0.65 0.2 350)", light: "oklch(0.58 0.2 350)" },
+  purple: { dark: "oklch(0.6 0.2 290)", light: "oklch(0.57 0.2 290)" },
+  red: { dark: "oklch(0.61 0.22 25)", light: "oklch(0.58 0.22 25)" },
+  teal: { dark: "oklch(0.6 0.12 195)", light: "oklch(0.53 0.12 195)" },
+} satisfies Record<string, AccentColors>;
+
+/** The contrast WCAG AA asks of body-size text. */
+export const MIN_TEXT_CONTRAST = 4.5;
+
+/**
+ * The theme's own colors a configured accent is drawn against: each mode's
+ * page background and text, and the dark ink a filled accent can carry.
+ * Mirrors the defaults in `entry.ts`.
+ */
+export const THEME_INKS = {
+  dark: {
+    background: "oklch(0.085 0 0)",
+    foreground: "oklch(0.96 0 0)",
+    ink: "oklch(0.085 0 0)",
+    mutedForeground: "oklch(0.68 0 0)",
+  },
+  light: {
+    background: "oklch(1 0 0)",
+    foreground: "oklch(0.145 0 0)",
+    ink: "oklch(0.145 0 0)",
+    mutedForeground: "oklch(0.53 0 0)",
+  },
+} satisfies Record<ColorMode, Record<string, string>>;
+
+const WHITE = "oklch(1 0 0)";
+
+/** A color this module writes itself, parsed (they all parse). */
+const own = (value: string): Rgba =>
+  parseColor(value) ?? { alpha: 1, blue: 0, green: 0, red: 0 };
+
+/** {@link THEME_INKS}, parsed, for contrast math. */
+export const themeInk = (
+  mode: ColorMode,
+  name: keyof (typeof THEME_INKS)[ColorMode]
+): Rgba => own(THEME_INKS[mode][name]);
+
+/**
+ * The label color for text on a filled `fill` (a button, a step number): white
+ * while it reaches AA, else the mode's dark ink when that reads better, so a
+ * light accent (every dark-mode preset) gets dark text instead of white text
+ * nobody can read.
+ */
+export const labelOn = (fill: Rgba, mode: ColorMode): string => {
+  const opaque = composite(fill, themeInk(mode, "background"));
+  const onWhite = contrastRatio(own(WHITE), opaque);
+  return onWhite >= MIN_TEXT_CONTRAST ||
+    onWhite >= contrastRatio(themeInk(mode, "ink"), opaque)
+    ? WHITE
+    : THEME_INKS[mode].ink;
+};
+
+/** {@link labelOn} for a CSS color; one this module can't parse keeps white. */
+export const readableOn = (fill: string, mode: ColorMode): string => {
+  const color = parseColor(fill);
+  return color ? labelOn(color, mode) : WHITE;
+};
 
 /**
  * Whether a raw config value names an accent preset. `hasOwn` keeps a value
@@ -35,9 +104,11 @@ const CSS_COLOR = /^[\w\s#%.,()/+-]+$/u;
 const safeColor = (value: string, fallback: string): string =>
   CSS_COLOR.test(value.trim()) ? value.trim() : fallback;
 
-/** Resolve a named preset or fall back to {@link safeColor}. */
-const presetOrColor = (value: string): string =>
-  isAccentPreset(value) ? ACCENTS[value] : safeColor(value, FALLBACK_ACCENT);
+/** Resolve a named preset in `mode`, or fall back to {@link safeColor}. */
+const presetOrColor = (value: string, mode: ColorMode): string =>
+  isAccentPreset(value)
+    ? ACCENTS[value][mode]
+    : safeColor(value, ACCENTS.blue[mode]);
 
 /** Like {@link safeColor} but drops an unsafe/absent value to `null`. */
 const safeColorOrNull = (value: string | undefined): string | null =>
@@ -58,20 +129,23 @@ const backgroundImageCss = (image: string): string =>
 const cssToken = (name: string, value?: string | null): string[] =>
   value ? [`  ${name}: ${value};`] : [];
 
+/** One mode's resolved accent and action fills. */
+interface ModeFills {
+  accent: string;
+  action: string | null;
+}
+
 const themeRootCss = (
   theme: ResolvedConfig["theme"],
-  options: {
-    accent: string;
-    action: string | null;
-    radius: string;
-  }
+  options: ModeFills & { radius: string }
 ): string =>
   [
     `  --blume-accent: ${options.accent};`,
+    `  --blume-accent-foreground: ${readableOn(options.accent, "light")};`,
     ...cssToken("--blume-action", options.action),
     ...cssToken(
       "--blume-action-foreground",
-      options.action ? "oklch(1 0 0)" : null
+      options.action ? readableOn(options.action, "light") : null
     ),
     ...cssToken("--blume-background", safeColorOrNull(theme.background?.light)),
     ...cssToken(
@@ -87,10 +161,7 @@ const themeRootCss = (
 
 const themeDarkCss = (
   theme: ResolvedConfig["theme"],
-  options: {
-    accent: string;
-    action: string | null;
-  }
+  options: ModeFills
 ): string => {
   // Mode-shared tokens (accent, action) must be re-declared here: the base
   // stylesheet's own `:root[data-theme="dark"]` block outranks the `:root`
@@ -98,11 +169,11 @@ const themeDarkCss = (
   // silently keep its neutral defaults and ignore the config.
   const tokens = [
     `  --blume-accent: ${options.accent};`,
-    "  --blume-accent-foreground: oklch(1 0 0);",
+    `  --blume-accent-foreground: ${readableOn(options.accent, "dark")};`,
     ...cssToken("--blume-action", options.action),
     ...cssToken(
       "--blume-action-foreground",
-      options.action ? "oklch(1 0 0)" : null
+      options.action ? readableOn(options.action, "dark") : null
     ),
     ...cssToken("--blume-background", safeColorOrNull(theme.background?.dark)),
     ...cssToken(
@@ -118,26 +189,31 @@ ${tokens.join("\n")}
 `;
 };
 
-/** Per-mode accent CSS colors. */
-export interface AccentColors {
-  dark: string;
-  light: string;
-}
-
 /**
  * Resolve the configured accent to per-mode CSS colors. A named accent
- * resolves to its preset; any other value is treated as a raw CSS color so
- * users can pass arbitrary colors without a config change. A string accent
- * has already been normalized by the config schema to the same color for
- * both modes.
+ * resolves to its preset's shade for each mode; any other value is treated as
+ * a raw CSS color so users can pass arbitrary colors without a config change.
+ * A string accent has already been normalized by the config schema to the
+ * same value for both modes.
  */
 export const resolveAccent = (
   theme: ResolvedConfig["theme"]
 ): AccentColors => ({
-  dark: presetOrColor(theme.accent.dark),
-  light: presetOrColor(theme.accent.light),
+  dark: presetOrColor(theme.accent.dark, "dark"),
+  light: presetOrColor(theme.accent.light, "light"),
 });
 
+/** Resolve the configured `action` fill per mode, or `null` when unset. */
+export const resolveAction = (
+  theme: ResolvedConfig["theme"]
+): AccentColors | null =>
+  theme.action
+    ? {
+        dark: presetOrColor(theme.action, "dark"),
+        light: presetOrColor(theme.action, "light"),
+      }
+    : null;
+
 /** Resolve the configured radius preset to a CSS length. */
 export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
   RADII[theme.radius];
@@ -145,20 +221,20 @@ export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
 /**
  * Compile theme config into CSS custom properties. A named accent resolves to
  * its preset; any other value is treated as a raw CSS color so users can pass
- * arbitrary colors without a config change.
+ * arbitrary colors without a config change. Labels on accent and action fills
+ * take whichever of white or dark ink reads ({@link readableOn}).
  */
 export const buildThemeCss = (theme: ResolvedConfig["theme"]): string => {
   const accent = resolveAccent(theme);
-  const action = theme.action ? presetOrColor(theme.action) : null;
-  const radius = RADII[theme.radius];
+  const action = resolveAction(theme);
   const root = themeRootCss(theme, {
     accent: accent.light,
-    action,
-    radius,
+    action: action?.light ?? null,
+    radius: RADII[theme.radius],
   });
   const dark = themeDarkCss(theme, {
     accent: accent.dark,
-    action,
+    action: action?.dark ?? null,
   });
 
   return `/* Generated by Blume from theme config. */

package/src/translate/meta.ts

@@ -1,12 +1,14 @@
+import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 import { dirname, join, relative } from "pathe";
-import { glob } from "tinyglobby";
 
+import { localeTargetPath } from "../core/i18n.ts";
 import { createModuleLoader } from "../core/load-module.ts";
+import { findFolderMetaFiles } from "../core/meta.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { folderMetaSchema } from "../core/schema.ts";
-import type { FolderMeta } from "../core/schema.ts";
+import type { FolderMeta, ResolvedI18nConfig } from "../core/schema.ts";
 import type { Diagnostic } from "../core/types.ts";
 
 /**
@@ -37,7 +39,10 @@ export interface TranslatableMeta {
   title: string;
 }
 
-const META_FILES = ["**/meta.ts", "**/meta.js", "**/meta.mjs"];
+/** A folder's meta module names, in the order a lookup prefers them. */
+const META_NAMES = ["meta.ts", "meta.js", "meta.mjs"];
+
+const META_FILES = META_NAMES.map((name) => `**/${name}`);
 
 /**
  * Whether a loaded meta module default-exports a factory function. Generic so
@@ -48,21 +53,44 @@ const isFactoryModule = <T>(
 ): value is T & ((...args: never[]) => FolderMeta) =>
   typeof value === "function";
 
-/** Where a locale's generated meta module lives (always written as `meta.ts`). */
+/**
+ * Where a locale's meta module lives. The locale folder is resolved the way
+ * pages resolve it (`localeTargetPath`): `folders` are the content root's
+ * existing top-level folders, and one naming the locale in another casing
+ * (`pt-br/` for a configured `pt-BR`) is the locale's folder already. In that
+ * folder, a `meta.js`/`meta.mjs` that already exists is the target — the
+ * generated module is plain JavaScript, and writing a `meta.ts` beside it
+ * would leave the folder with two meta files. Otherwise it's a new `meta.ts`.
+ */
 export const metaTargetPath = (
   meta: TranslatableMeta,
-  locale: string
-): string => join(meta.contentRoot, locale, meta.dir, "meta.ts");
+  locale: string,
+  i18n: ResolvedI18nConfig,
+  folders: readonly string[]
+): string => {
+  const dir = join(
+    meta.contentRoot,
+    dirname(
+      localeTargetPath(join(meta.dir, "meta.ts"), ".ts", locale, i18n, folders)
+    )
+  );
+  const existing = META_NAMES.find((name) => existsSync(join(dir, name)));
+  return join(dir, existing ?? "meta.ts");
+};
 
 /**
  * Discover the default-locale `meta.{ts,js,mjs}` files whose titles a
  * translation run covers. Skips (in order): non-`dir` i18n projects entirely,
- * files inside a configured locale directory (those ARE translations), files
- * inside an archived-version snapshot (frozen, with their own translations —
- * the same folders the navigation's meta lookup hoists as versions),
- * factory-form modules (a warning — the generator can't re-emit a function),
- * modules that fail meta validation (the scan already errors on those), and
- * modules with no `title` (nothing to translate).
+ * files the scan's own folder-meta discovery never reads either — those
+ * matching the source's `exclude` globs (application code) or in folders its
+ * `include` globs don't reach (see `findFolderMetaFiles`) — files inside a
+ * configured locale directory (those ARE translations), files inside an
+ * archived-version snapshot (frozen, with their own translations — the same
+ * folders the navigation's meta lookup hoists as versions), modules that fail
+ * to load (the scan already errors on those), factory-form modules (a warning
+ * — the generator can't re-emit a function), modules that fail meta
+ * validation (the scan already errors on those too), and modules with no
+ * `title` (nothing to translate).
  */
 export const discoverTranslatableMeta = async (
   project: BlumeProject
@@ -85,16 +113,26 @@ export const discoverTranslatableMeta = async (
   const diagnostics: Diagnostic[] = [];
 
   const roots = project.sources.flatMap((source) =>
-    source.staged || !source.contentRoot ? [] : [source.contentRoot]
+    source.staged || !source.contentRoot
+      ? []
+      : [
+          {
+            contentRoot: source.contentRoot,
+            exclude: source.exclude,
+            include: source.include,
+          },
+        ]
   );
-  for (const contentRoot of roots) {
+  for (const { contentRoot, exclude, include } of roots) {
+    // The scan's own file set (`discoverFolderMeta`): a `meta.ts` under an
+    // excluded folder (`src/lib/meta.ts` beside `exclude: ["src/**"]`) is
+    // application code, and one in a folder no `include` glob reaches
+    // configures no group the build renders.
     // oxlint-disable-next-line no-await-in-loop -- a project has O(1) sources
-    const files = await glob(META_FILES, {
-      absolute: true,
-      cwd: contentRoot,
-      ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
-      onlyFiles: true,
-    });
+    const files = await findFolderMetaFiles(
+      { exclude, include, root: contentRoot },
+      META_FILES
+    );
     for (const file of files.toSorted()) {
       const dir = relative(contentRoot, dirname(file));
       const [head] = dir.split("/");
@@ -104,11 +142,17 @@ export const discoverTranslatableMeta = async (
       ) {
         continue;
       }
+      let mod: Awaited<ReturnType<typeof load>>;
+      try {
+        // oxlint-disable-next-line no-await-in-loop -- sequential, ordered discovery
+        mod = await load(file);
+      } catch {
+        // Folder meta that fails to load is the scan's BLUME_META_LOAD_FAILED
+        // error, not a crash here; either way there's no title to read.
+        continue;
+      }
       // oxlint-disable-next-line no-await-in-loop -- sequential, ordered discovery
-      const [raw, mod] = await Promise.all([
-        readFile(file, "utf-8"),
-        load(file),
-      ]);
+      const raw = await readFile(file, "utf-8");
       if (isFactoryModule(mod)) {
         diagnostics.push({
           code: "BLUME_TRANSLATE_META_FACTORY",

package/src/translate/prompts.ts

@@ -64,6 +64,7 @@ ${previousTranslation}`;
 Rules:
 - Translate the prose: headings, paragraphs, list items, table cells, admonitions, and image alt text.
 - In the YAML frontmatter, translate ONLY the values of these keys: ${KEY_LIST}. Copy every other frontmatter key and value exactly as written.
+- Keep the frontmatter valid YAML: if a translated value contains a colon followed by a space (\`: \`) or a space followed by \`#\`, or starts with a quote, a backtick, or another YAML indicator character, write it as a double-quoted string and escape any double quotes inside it.
 - Never translate or alter: code blocks, inline code, import/export statements, JSX/MDX component names and their attributes, URLs, link targets, HTML tags, or frontmatter keys.
 - A heading may end with anchor markers: \`[#some-id]\`, \`{#some-id}\` (also written \`\\{#some-id\\}\`), \`[!toc]\`, or \`[toc]\`. Copy every marker exactly as written, in the same position at the end of the translated heading — never translate, reorder, or drop a marker, and never change the id inside \`[#...]\` or \`{#...}\` (anchors must stay identical across languages).
 

package/src/translate/run.ts

@@ -146,9 +146,9 @@ const runPageItem = async (
   // SAFETY: `targets` maps every configured locale, and work items only carry
   // configured locale codes.
   const target = context.targets.get(item.locale) as LocaleConfig;
-  // A hand-authored translation can live at a non-canonical name (see
-  // WorkStatus); the disk probe finds only canonical targets, and a miss just
-  // means the prompt goes out without a style precedent.
+  // A stale item's target is the existing translation's own file, even at a
+  // non-canonical name (see `PageWorkItem.targetPath`), so it's the style
+  // precedent and the file rewritten; a missing item has nothing to read.
   const previousTranslation = existsSync(item.targetPath)
     ? await readFile(item.targetPath, "utf-8")
     : undefined;

package/src/translate/validate.ts

@@ -32,7 +32,10 @@ interface FrontmatterData {
   [key: string]: FrontmatterValue;
 }
 
-const FRONTMATTER_OPEN = /^---\r?\n/u;
+// gray-matter strips a leading byte order mark before it looks for the fence,
+// so a BOM-prefixed file still has frontmatter — this test must agree, or the
+// reconstruction below writes the body alone and the metadata is lost.
+const FRONTMATTER_OPEN = /^?---\r?\n/u;
 const FENCE_LINE = /^\s*(?:```|~~~)/u;
 
 /**
@@ -129,8 +132,14 @@ export const validateTranslation = (
   let parsed: { content: string; data: FrontmatterData };
   try {
     parsed = matter(candidate);
-  } catch {
-    return { ok: false, reason: "frontmatter does not parse as YAML" };
+  } catch (error) {
+    // js-yaml's message leads with the problem and its line:column in the
+    // file, then a multi-line code frame; the first line is enough to act on.
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      reason: `frontmatter does not parse as YAML: ${message.replace(/\n[\s\S]*$/u, "")}`,
+    };
   }
 
   const rawBody = ensureTrailingNewline(parsed.content.replace(/^\r?\n/u, ""));

package/src/translate/work-list.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
-import { dirname, extname, join, relative } from "pathe";
+import { extname, join, relative } from "pathe";
 
 import { localeCodes, localeTargetPath } from "../core/i18n.ts";
 import { scanProject } from "../core/project-graph.ts";
@@ -35,7 +35,11 @@ export interface PageWorkItem {
   /** POSIX root-relative source path — the ledger key. */
   sourceRel: string;
   status: WorkStatus;
-  /** Absolute canonical target path (`localeTargetPath`). */
+  /**
+   * Absolute target path: an existing translation's own file (which can sit
+   * at a non-canonical name, like a hand-written `fr/guide.md` for
+   * `guide.mdx`), otherwise the canonical `localeTargetPath`.
+   */
   targetPath: string;
   /** POSIX root-relative target path, for display. */
   targetRel: string;
@@ -49,7 +53,7 @@ export interface PageWorkItem {
 export interface MetaWorkEntry {
   meta: TranslatableMeta;
   status: WorkStatus;
-  /** Absolute path of the generated per-locale `meta.ts`. */
+  /** Absolute path of the per-locale meta module (see `metaTargetPath`). */
   targetPath: string;
 }
 
@@ -283,6 +287,37 @@ const partialWorkItems = async (
   return work;
 };
 
+/**
+ * Every existing translation, keyed by `translationKey` and locale, with the
+ * file it was read from when that file is on disk in a filesystem source. A
+ * retranslation writes there: an adopted hand-written `fr/guide.md` for a
+ * `guide.mdx` source is replaced in place, never joined by a canonical
+ * `fr/guide.mdx` that would publish the route twice.
+ */
+const existingTranslations = (
+  project: BlumeProject
+): Map<string, string | undefined> => {
+  const writableSources = new Set(
+    project.sources.flatMap((source) =>
+      source.staged || !source.contentRoot ? [] : [source.name]
+    )
+  );
+  const translated = new Map<string, string | undefined>();
+  for (const page of project.graph.pages) {
+    const key = `${page.translationKey}\0${page.locale}`;
+    if (page.fallback || translated.has(key)) {
+      continue;
+    }
+    translated.set(
+      key,
+      page.sourcePath && writableSources.has(page.source.name)
+        ? page.sourcePath
+        : undefined
+    );
+  }
+  return translated;
+};
+
 /**
  * Compute the run's work: which (source, locale) pairs are missing or stale,
  * which existing translations to adopt, and what's already up to date.
@@ -310,11 +345,7 @@ export const computeWorkList = async (
       (options.locales === undefined || options.locales.includes(code))
   );
 
-  const translated = new Set(
-    project.graph.pages.flatMap((page) =>
-      page.fallback ? [] : [`${page.translationKey}${page.locale}`]
-    )
-  );
+  const translated = existingTranslations(project);
 
   const { root } = project.context;
   const knownSources = new Set<string>();
@@ -333,10 +364,13 @@ export const computeWorkList = async (
     const contentRel = relative(contentRoot, sourcePath);
 
     for (const locale of targetLocales) {
-      const targetPath = join(
-        contentRoot,
-        localeTargetPath(contentRel, ext, locale, i18n, folders(contentRoot))
-      );
+      const key = `${page.translationKey}\0${locale}`;
+      const targetPath =
+        translated.get(key) ??
+        join(
+          contentRoot,
+          localeTargetPath(contentRel, ext, locale, i18n, folders(contentRoot))
+        );
       const item = (status: WorkStatus): PageWorkItem => ({
         kind: "page",
         locale,
@@ -346,7 +380,7 @@ export const computeWorkList = async (
         targetPath,
         targetRel: relative(root, targetPath),
       });
-      const exists = translated.has(`${page.translationKey}${locale}`);
+      const exists = translated.has(key);
       const stamp = ledger.files[sourceRel]?.[locale];
       const outcome = classifyPair(exists, stamp, hash, options.force === true);
       if (outcome === "untracked") {
@@ -380,16 +414,21 @@ export const computeWorkList = async (
     const entries: MetaWorkEntry[] = [];
     for (const source of meta.metas) {
       knownSources.add(source.sourceRel);
-      const targetDir = dirname(metaTargetPath(source, locale));
-      const exists = ["meta.ts", "meta.js", "meta.mjs"].some((name) =>
-        existsSync(join(targetDir, name))
+      // The locale folder's existing meta module when there is one, so a
+      // retranslation rewrites it instead of adding a `meta.ts` beside it.
+      const targetPath = metaTargetPath(
+        source,
+        locale,
+        i18n,
+        folders(source.contentRoot)
       );
+      const exists = existsSync(targetPath);
       const hash = hashSource(source.raw);
       const stamp = ledger.files[source.sourceRel]?.[locale];
       const entry = (status: WorkStatus): MetaWorkEntry => ({
         meta: source,
         status,
-        targetPath: metaTargetPath(source, locale),
+        targetPath,
       });
       const outcome = classifyPair(exists, stamp, hash, options.force === true);
       if (outcome === "untracked") {