blume 1.4.3 → 1.5.1

package/src/theme/chrome-icons.ts

@@ -12,11 +12,16 @@
  * Values are Lucide inner-SVG markup; the client `svg()` helpers wrap them in an
  * `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" …>`.
  */
-export const chromeIcons: Record<string, string> = {
+/** Inner-SVG markup keyed by the icon name a client script requests. */
+interface ChromeIconSet {
+  [name: string]: string;
+}
+
+export const chromeIcons: ChromeIconSet = {
   check: '<path d="M20 6 9 17l-5-5"/>',
   copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
   file: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>',
   search: '<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>',
   sparkles:
-    '<path d="m12 3-1.9 5.8a2 2 0 0 1-1.3 1.3L3 12l5.8 1.9a2 2 0 0 1 1.3 1.3L12 21l1.9-5.8a2 2 0 0 1 1.3-1.3L21 12l-5.8-1.9a2 2 0 0 1-1.3-1.3Z"/><path d="M5 3v4"/><path d="M3 5h4"/><path d="M19 17v4"/><path d="M17 19h4"/>',
+    '<path d="m12 3-1.9 5.8a2 2 0 0 1-1.3 1.3L3 12l5.8 1.9a2 2 0 0 1 1.3 1.3L12 21l1.9-5.8a2 2 0 0 1-1.3-1.3L21 12l-5.8-1.9a2 2 0 0 1-1.3-1.3Z"/><path d="M5 3v4"/><path d="M3 5h4"/><path d="M19 17v4"/><path d="M17 19h4"/>',
 };

package/src/theme/entry.ts

@@ -179,7 +179,11 @@ ${THEME_MAPPING}
     scroll-padding-top: 4.5rem;
     text-rendering: optimizeLegibility;
   }
-  /* Headings use the display font (defaults to the body font when unset). */
+  /* Headings use the display font (defaults to the body font when unset).
+     The tightened tracking is part of the theme, not the font: display-tuned
+     families bake it into their metrics, but a text family promoted to
+     headings (including the Inter default) reads loose without it. -0.05em
+     was matched visually against Inter Tight, the previous display default. */
   h1,
   h2,
   h3,
@@ -187,6 +191,7 @@ ${THEME_MAPPING}
   h5,
   h6 {
     font-family: var(--font-display);
+    letter-spacing: -0.05em;
   }
   :focus-visible {
     outline: 2px solid var(--blume-accent);
@@ -207,6 +212,22 @@ ${THEME_MAPPING}
   }
 }
 
+/* Same-origin navigations are full document loads (no client router); opting
+   into cross-document view transitions has the browser crossfade between the
+   old and new page instead of hard-swapping, in browsers that support it.
+   Pairs with the prefetch option in the generated Astro config. */
+@view-transition {
+  navigation: auto;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}
+
 /* Code reads left-to-right regardless of page direction; only the surrounding
    chrome mirrors for RTL. Inline code is isolated so LTR identifiers don't
    disturb the bidi flow of right-to-left prose. */
@@ -242,9 +263,10 @@ ${THEME_MAPPING}
   line-height: 1.7;
 }
 
+/* No letter-spacing here: prose headings inherit the base h1-h6 rule's
+   display tracking, same as headings outside the prose column. */
 .prose :where(h1, h2, h3, h4) {
   font-weight: 500;
-  letter-spacing: 0;
 }
 
 /* A heading can carry one long unbreakable token — an OpenAPI operation's title

package/src/theme/fonts.ts

@@ -82,11 +82,11 @@ export type FontEntry =
       variants: LocalFontVariant[];
     };
 
-const FALLBACKS: Record<FontCategory, string[]> = {
+const FALLBACKS = {
   mono: ["ui-monospace", "SF Mono", "Menlo", "monospace"],
   sans: ["ui-sans-serif", "system-ui", "sans-serif"],
   serif: ["ui-serif", "Georgia", "serif"],
-};
+} satisfies Record<FontCategory, string[]>;
 
 /** Slug -> Google family + weights + fallback category. Keep keys alphabetical. */
 export const GOOGLE_FONTS = {
@@ -223,12 +223,16 @@ const SLOTS: FontSlot[] = ["display", "body", "mono"];
 const slotCategory = (slot: FontSlot): FontCategory =>
   slot === "mono" ? "mono" : "sans";
 
+/** Whether a slot value is the slug-string form (vs a custom font object). */
+const isSlugValue = (value: FontValue): value is string =>
+  typeof value === "string";
+
 /** A slot value normalized into an entry, or null for an unknown slug string. */
 const resolveFontValue = (
   slot: FontSlot,
   value: FontValue
 ): FontEntry | null => {
-  if (typeof value === "string") {
+  if (isSlugValue(value)) {
     if (!isFontSlug(value)) {
       return null;
     }
@@ -320,7 +324,7 @@ export const buildFontEntries = (fonts: FontsConfig): FontEntry[] => {
 
 /** The slug backing a slot's CSS variable, or null for an unknown slug string. */
 const slotSlug = (value: FontValue): string | null => {
-  if (typeof value === "string") {
+  if (isSlugValue(value)) {
     return isFontSlug(value) ? value : null;
   }
   return slugifyFontName(value.name);
@@ -348,6 +352,78 @@ export const buildFontsCss = (fonts: FontsConfig): string => {
     : "";
 };
 
-/** The CSS variables to feed Astro's `<Font>` component in the document head. */
-export const configuredCssVars = (fonts: FontsConfig): string[] =>
-  buildFontEntries(fonts).map((entry) => entry.cssVariable);
+/**
+ * Weights worth preloading per role — the faces above-the-fold text actually
+ * renders in: body copy and UI chrome at 400/500, headings at 500/600, code at
+ * 400. Every other face still loads on demand through its `@font-face` rule
+ * (and `font-display: swap` never blocks text on it), so preloading the long
+ * tail only competes with the critical CSS for bandwidth and pushes LCP out.
+ */
+const PRELOAD_WEIGHTS = {
+  body: [400, 500],
+  display: [500, 600],
+  mono: [400],
+} satisfies Record<FontSlot, number[]>;
+
+/** One `<Font>` render in the head: its CSS variable + weights to preload. */
+export interface FontHead {
+  cssVariable: string;
+  preloadWeights: number[];
+}
+
+/** The weights an entry's faces declare (`undefined` = inferred from files). */
+const entryWeights = (entry: FontEntry): (number | string | undefined)[] =>
+  entry.kind === "remote"
+    ? entry.weights
+    : entry.variants.map((variant) => variant.weight);
+
+/**
+ * The role's preferred preload weights, narrowed to faces the family loads.
+ * Variable ranges (`"100..900"`) and weight-inferred local files can serve any
+ * weight, so they keep the preferred list; a family whose numeric weights miss
+ * the preferred ones entirely preloads all of its faces instead — those are
+ * what its text renders in.
+ */
+const preloadWeightsFor = (slot: FontSlot, entry: FontEntry): number[] => {
+  const preferred = PRELOAD_WEIGHTS[slot];
+  const weights = entryWeights(entry);
+  const numeric = weights.filter(
+    (weight): weight is number => typeof weight === "number"
+  );
+  const hits = preferred.filter((weight) => numeric.includes(weight));
+  if (hits.length > 0) {
+    return hits;
+  }
+  return numeric.length === weights.length ? numeric : preferred;
+};
+
+/**
+ * The fonts to feed Astro's `<Font>` component in the document head, deduped
+ * by CSS variable with preload weights unioned across the roles that share a
+ * family (so `display` and `body` both set to Inter preload 400/500/600 once).
+ */
+export const configuredFonts = (fonts: FontsConfig): FontHead[] => {
+  if (!fonts) {
+    return [];
+  }
+  const heads = new Map<string, Set<number>>();
+  for (const slot of SLOTS) {
+    const value = fonts[slot];
+    if (value === undefined) {
+      continue;
+    }
+    const entry = resolveFontValue(slot, value);
+    if (!entry) {
+      continue;
+    }
+    const weights = heads.get(entry.cssVariable) ?? new Set();
+    for (const weight of preloadWeightsFor(slot, entry)) {
+      weights.add(weight);
+    }
+    heads.set(entry.cssVariable, weights);
+  }
+  return [...heads].map(([cssVariable, weights]) => ({
+    cssVariable,
+    preloadWeights: [...weights].toSorted((a, b) => a - b),
+  }));
+};

package/src/theme/icons.ts

@@ -17,9 +17,11 @@ import { getIconData, iconToSVG } from "@iconify/utils";
 // strips it when externalizing) and then rejects the module, whereas `require`
 // of a JSON file needs no attribute and works under both Node and Bun.
 const requireJson = createRequire(import.meta.url);
+// SAFETY: the required file is the Iconify-published icon-set JSON, whose
+// shape is exactly `IconifyJSON`.
 const loadSet = (pkg: string): IconifyJSON => requireJson(pkg) as IconifyJSON;
 
-const SETS: Record<string, IconifyJSON> = {
+const SETS = {
   lucide: loadSet("@iconify-json/lucide/icons.json"),
 };
 
@@ -27,7 +29,7 @@ const SETS: Record<string, IconifyJSON> = {
 const DEFAULT_SET = "lucide";
 
 /** Explicit `prefix:name` prefixes. Lucide is the only bundled set. */
-const PREFIX_SETS: Record<string, string> = {
+const PREFIX_SETS = {
   lucide: "lucide",
 };
 

package/src/theme/palette.ts

@@ -7,7 +7,7 @@ const FALLBACK_ACCENT = "oklch(0.62 0.16 250)";
  * 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".
  */
-export const ACCENTS: Record<string, string> = {
+export const ACCENTS = {
   blue: FALLBACK_ACCENT,
   green: "oklch(0.6 0.16 150)",
   orange: "oklch(0.68 0.17 50)",
@@ -15,7 +15,16 @@ export const ACCENTS: Record<string, string> = {
   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>;
+
+/**
+ * Whether a raw config value names an accent preset. `hasOwn` keeps a value
+ * like "constructor" from resolving an Object.prototype member — which would
+ * stringify a function into the generated CSS, breaking the rule (the exact
+ * breakout {@link safeColor} exists to prevent).
+ */
+export const isAccentPreset = (value: string): value is keyof typeof ACCENTS =>
+  Object.hasOwn(ACCENTS, value);
 
 // Characters valid in a CSS color value (hex, rgb/hsl/oklch functions, named
 // colors). Anything else — notably `;`, `{`, `}` — could break out of the
@@ -26,27 +35,20 @@ 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}. `hasOwn` keeps a
- * value like "constructor" from resolving an Object.prototype member — which
- * would stringify a function into the generated CSS, breaking the rule (the
- * exact breakout safeColor exists to prevent).
- */
+/** Resolve a named preset or fall back to {@link safeColor}. */
 const presetOrColor = (value: string): string =>
-  Object.hasOwn(ACCENTS, value)
-    ? (ACCENTS[value] as string)
-    : safeColor(value, FALLBACK_ACCENT);
+  isAccentPreset(value) ? ACCENTS[value] : safeColor(value, FALLBACK_ACCENT);
 
 /** Like {@link safeColor} but drops an unsafe/absent value to `null`. */
 const safeColorOrNull = (value: string | undefined): string | null =>
   value && CSS_COLOR.test(value.trim()) ? value.trim() : null;
 
-const RADII: Record<ResolvedConfig["theme"]["radius"], string> = {
+const RADII = {
   lg: "0.75rem",
   md: "0.5rem",
   none: "0",
   sm: "0.25rem",
-};
+} satisfies Record<ResolvedConfig["theme"]["radius"], string>;
 
 const cssString = (value: string): string => JSON.stringify(value);
 
@@ -116,6 +118,12 @@ ${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
@@ -125,7 +133,7 @@ ${tokens.join("\n")}
  */
 export const resolveAccent = (
   theme: ResolvedConfig["theme"]
-): { dark: string; light: string } => ({
+): AccentColors => ({
   dark: presetOrColor(theme.accent.dark),
   light: presetOrColor(theme.accent.light),
 });

package/src/translate/meta.ts

@@ -39,6 +39,15 @@ export interface TranslatableMeta {
 
 const META_FILES = ["**/meta.ts", "**/meta.js", "**/meta.mjs"];
 
+/**
+ * Whether a loaded meta module default-exports a factory function. Generic so
+ * it can decode the loader's untyped module value at this boundary.
+ */
+const isFactoryModule = <T>(
+  value: T
+): value is T & ((...args: never[]) => FolderMeta) =>
+  typeof value === "function";
+
 /** Where a locale's generated meta module lives (always written as `meta.ts`). */
 export const metaTargetPath = (
   meta: TranslatableMeta,
@@ -92,7 +101,7 @@ export const discoverTranslatableMeta = async (
         readFile(file, "utf-8"),
         load(file),
       ]);
-      if (typeof mod === "function") {
+      if (isFactoryModule(mod)) {
         diagnostics.push({
           code: "BLUME_TRANSLATE_META_FACTORY",
           file,
@@ -130,14 +139,14 @@ export const generateMetaModule = (
   meta: FolderMeta,
   translatedTitle: string
 ): string => {
-  const data: Record<string, unknown> = {
+  const data = {
     ...meta,
     title: translatedTitle,
   };
-  const lines = Object.keys(data)
-    .toSorted()
-    .filter((key) => data[key] !== undefined)
-    .map((key) => `  ${key}: ${JSON.stringify(data[key])},`);
+  const lines = Object.entries(data)
+    .toSorted(([a], [b]) => (a < b ? -1 : 1))
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => `  ${key}: ${JSON.stringify(value)},`);
   return [
     "// Generated by `blume translate` — edit the default locale's meta file",
     "// and rerun the translation instead of editing this copy.",

package/src/translate/report.ts

@@ -29,17 +29,17 @@ import type {
 
 const ESC = String.fromCodePoint(27);
 
-const GLYPH: Record<TranslateItemStatus, string> = {
+const GLYPH = {
   failed: "✖",
   partial: "!",
   translated: "✔",
-};
+} satisfies Record<TranslateItemStatus, string>;
 
-const STATUS_COLOR: Record<TranslateItemStatus, ColorFunction> = {
+const STATUS_COLOR = {
   failed: colors.red,
   partial: colors.yellow,
   translated: colors.green,
-};
+} satisfies Record<TranslateItemStatus, ColorFunction>;
 
 export const SPINNER_FRAMES = [
   "⠋",
@@ -76,8 +76,12 @@ export const spinnerLine = (
   total: number,
   frame: number
 ): string => {
+  // SAFETY: the renderer only paints while at least one item is active, so the
+  // oldest active entry exists.
   const first = active[0] as WorkItem;
   const more = active.length > 1 ? ` (+${active.length - 1} more)` : "";
+  // SAFETY: `frame % SPINNER_FRAMES.length` is always an index into the
+  // non-empty frames array.
   return `  ${colors.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length] as string)} ${itemLabel(first)}${more} ${colors.dim(`${done}/${total}`)}`;
 };
 
@@ -216,7 +220,7 @@ export const checkReportJson = (workList: TranslateWorkList): string => {
 };
 
 /** One run result lowered to JSON-friendly, root-relative fields. */
-const resultJson = (result: TranslateItemResult): Record<string, unknown> => ({
+const resultJson = (result: TranslateItemResult) => ({
   costUsd: result.costUsd,
   detail: result.detail,
   durationMs: result.durationMs,

package/src/translate/run.ts

@@ -58,8 +58,9 @@ export interface TranslateRunOptions {
    * Called after each finished item to flush the ledger to disk, so an
    * interrupted run keeps everything already translated. Calls are serialized
    * here — concurrent workers finishing together never race the same file.
+   * The flush's result (`writeLedger`'s wrote-or-not boolean) is ignored.
    */
-  persistLedger?: () => Promise<unknown>;
+  persistLedger?: () => Promise<boolean | undefined>;
   project: BlumeProject;
   /** The spawn function — injectable so tests never launch a real agent. */
   run?: HeadlessRunner;
@@ -129,6 +130,8 @@ const runPageItem = async (
   });
 
   const sourceText = await readFile(item.sourcePath, "utf-8");
+  // 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
@@ -175,6 +178,8 @@ const runMetaItem = async (
   const titles = Object.fromEntries(
     item.entries.map((entry) => [metaDirKey(entry.meta.dir), entry.meta.title])
   );
+  // SAFETY: `targets` maps every configured locale, and work items only carry
+  // configured locale codes.
   const target = context.targets.get(item.locale) as LocaleConfig;
   const output = await invokeAgent(
     context,
@@ -257,6 +262,7 @@ export const runTranslate = async (
   if (!i18n) {
     throw new Error("blume translate requires i18n to be configured");
   }
+  // SAFETY: the config schema requires `defaultLocale` to be one of `locales`.
   const source = i18n.locales.find(
     (locale) => locale.code === i18n.defaultLocale
   ) as LocaleConfig;
@@ -280,7 +286,7 @@ export const runTranslate = async (
   // The persist mutex: ledger flushes from concurrent lanes are serialized so
   // two lanes never write the ledger file at the same time.
   const persistLimit = pLimit(1);
-  const persist = (): Promise<unknown> =>
+  const persist = (): Promise<boolean | undefined> =>
     persistLimit(() => options.persistLedger?.());
 
   const results = await pMap(
@@ -316,11 +322,11 @@ export const runTranslate = async (
     }
   }
 
-  const counts: Record<TranslateItemStatus, number> = {
+  const counts = {
     failed: 0,
     partial: 0,
     translated: 0,
-  };
+  } satisfies Record<TranslateItemStatus, number>;
   for (const result of results) {
     counts[result.status] += 1;
   }

package/src/translate/validate.ts

@@ -13,6 +13,24 @@ export type ValidationResult =
   | { ok: true; text: string }
   | { ok: false; reason: string };
 
+/**
+ * A parsed YAML frontmatter value (agent meta replies parse from JSON into the
+ * same shape). js-yaml can also mint Dates and other rich scalars; the
+ * traversal below only ever distinguishes "keyed object" from "string", so
+ * they ride along as the object arm.
+ */
+type FrontmatterValue =
+  | string
+  | number
+  | boolean
+  | null
+  | FrontmatterValue[]
+  | FrontmatterData;
+
+interface FrontmatterData {
+  [key: string]: FrontmatterValue;
+}
+
 const FRONTMATTER_OPEN = /^---\r?\n/u;
 const FENCE_LINE = /^\s*(?:```|~~~)/u;
 
@@ -33,27 +51,41 @@ export const stripOuterFence = (text: string): string => {
 const countFenceLines = (text: string): number =>
   text.split("\n").filter((line) => FENCE_LINE.test(line)).length;
 
-const getPath = (data: unknown, path: readonly string[]): unknown => {
-  let value: unknown = data;
+const isKeyedObject = (
+  value: FrontmatterValue | undefined
+): value is FrontmatterData => typeof value === "object" && value !== null;
+
+const isString = (value: FrontmatterValue | undefined): value is string =>
+  typeof value === "string";
+
+const getPath = (
+  data: FrontmatterValue,
+  path: readonly string[]
+): FrontmatterValue | undefined => {
+  let value: FrontmatterValue | undefined = data;
   for (const key of path) {
-    if (typeof value !== "object" || value === null) {
+    if (!isKeyedObject(value)) {
       return;
     }
-    value = (value as Record<string, unknown>)[key];
+    value = value[key];
   }
   return value;
 };
 
 /** Set `path` on `data`; only called for paths whose parents exist in `data`. */
 const setPath = (
-  data: Record<string, unknown>,
+  data: FrontmatterData,
   path: readonly string[],
   value: string
 ): void => {
   let parent = data;
   for (const key of path.slice(0, -1)) {
-    parent = parent[key] as Record<string, unknown>;
+    // SAFETY: callers only set paths that getPath already resolved to a string
+    // on this same (cloned) data, so every intermediate step is a keyed object.
+    parent = parent[key] as FrontmatterData;
   }
+  // SAFETY: every TRANSLATABLE_KEY_PATHS entry is a non-empty tuple, so the
+  // path always has a final key.
   parent[path.at(-1) as string] = value;
 };
 
@@ -84,7 +116,7 @@ export const validateTranslation = (
     };
   }
 
-  let parsed: { content: string; data: Record<string, unknown> };
+  let parsed: { content: string; data: FrontmatterData };
   try {
     parsed = matter(candidate);
   } catch {
@@ -114,13 +146,13 @@ export const validateTranslation = (
   // Reconciliation by reconstruction: start from the SOURCE data and overlay
   // only the translatable key paths where both sides hold a string and the
   // translation is non-empty.
-  const data = structuredClone(source.data) as Record<string, unknown>;
+  const data: FrontmatterData = structuredClone(source.data);
   for (const path of TRANSLATABLE_KEY_PATHS) {
     const original = getPath(source.data, path);
     const translated = getPath(parsed.data, path);
     if (
-      typeof original === "string" &&
-      typeof translated === "string" &&
+      isString(original) &&
+      isString(translated) &&
       translated.trim() !== ""
     ) {
       setPath(data, path, translated);
@@ -133,6 +165,12 @@ export const validateTranslation = (
   };
 };
 
+/** A meta-batch parse: recovered titles by key, plus the keys still missing. */
+export interface MetaTitlesResult {
+  titles: Record<string, string>;
+  missing: string[];
+}
+
 /**
  * Extract translated sidebar titles from a meta reply: tolerant first-`{`
  * to-last-`}` extraction (the eval `parseVerdict` idiom). Keys missing or
@@ -141,10 +179,10 @@ export const validateTranslation = (
 export const parseMetaTitles = (
   agentText: string,
   expectedKeys: readonly string[]
-): { titles: Record<string, string>; missing: string[] } => {
+): MetaTitlesResult => {
   const start = agentText.indexOf("{");
   const end = agentText.lastIndexOf("}");
-  let parsed: unknown;
+  let parsed: FrontmatterValue | undefined;
   if (start !== -1 && end > start) {
     try {
       parsed = JSON.parse(agentText.slice(start, end + 1));
@@ -152,16 +190,13 @@ export const parseMetaTitles = (
       parsed = undefined;
     }
   }
-  const record =
-    typeof parsed === "object" && parsed !== null
-      ? (parsed as Record<string, unknown>)
-      : {};
+  const record: FrontmatterData = isKeyedObject(parsed) ? parsed : {};
 
   const titles: Record<string, string> = {};
   const missing: string[] = [];
   for (const key of expectedKeys) {
     const value = record[key];
-    if (typeof value === "string" && value.trim() !== "") {
+    if (isString(value) && value.trim() !== "") {
       titles[key] = value;
     } else {
       missing.push(key);