blume 1.4.2 → 1.5.0

package/src/markdown/mdast.ts

@@ -5,15 +5,29 @@
  * Satteri's real `MdastPlugin` type at a single boundary in `index.ts`.
  */
 
+/**
+ * A property value on an MDAST node: primitives, nested nodes, and lists of
+ * either. Covers everything Blume's plugins read or build (positions, data
+ * flags, attribute lists) without admitting functions or class instances.
+ */
+export type MdastValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | MdastValue[]
+  | { [key: string]: MdastValue };
+
 /** The visitor context Blume's plugins use to mutate the tree. */
 export interface MdastVisitorContext {
-  replaceNode: (node: unknown, replacement: unknown) => void;
+  replaceNode: (node: MdastNode, replacement: MdastNode) => void;
 }
 
 /** Any MDAST node, keyed loosely since we build a small subset by hand. */
 export interface MdastNode {
   type: string;
-  [key: string]: unknown;
+  [key: string]: MdastValue;
 }
 
 /** Build an MDX JSX attribute. A `null` value renders as a boolean attribute. */
@@ -29,14 +43,14 @@ type JsxAttribute = ReturnType<typeof jsxAttribute>;
 export const jsxFlowElement = (
   name: string,
   attributes: JsxAttribute[],
-  children: unknown[]
+  children: MdastValue[]
 ) => ({ attributes, children, name, type: "mdxJsxFlowElement" });
 
 /** Build an inline MDX JSX element (phrasing context). */
 export const jsxTextElement = (
   name: string,
   attributes: JsxAttribute[],
-  children: unknown[] = []
+  children: MdastValue[] = []
 ) => ({ attributes, children, name, type: "mdxJsxTextElement" });
 
 /** Build a fenced code block node. */

package/src/markdown/package-commands.ts

@@ -1,8 +1,26 @@
+import type { Agent, Command } from "package-manager-detector";
+import { resolveCommand } from "package-manager-detector/commands";
+
 /** Supported package managers, in the order tabs are displayed. */
 export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
 
 export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 
+/**
+ * The agent each tab renders. The yarn tab is pinned to Berry (yarn 2+ — the
+ * only supported line): the pre-existing mix emitted Berry-only `yarn dlx` and
+ * `--immutable` next to Classic-only `yarn global add`, so no single yarn
+ * version could run every rendered command. Berry removed `global`
+ * (yarnpkg/berry#821), so global installs on the yarn tab honestly render
+ * npm's form, matching `ni`'s table.
+ */
+const AGENT_FOR = {
+  bun: "bun",
+  npm: "npm",
+  pnpm: "pnpm",
+  yarn: "yarn@berry",
+} satisfies Record<PackageManager, Agent>;
+
 /** Words that mark the input as an explicit command rather than a bare list. */
 const MANAGER_PREFIXES = new Set(["bun", "bunx", "npm", "npx", "pnpm", "yarn"]);
 
@@ -118,62 +136,51 @@ const parseIntent = (input: string): Intent => {
   return { args: normalizeFlags(verbArgs), operation };
 };
 
-/** Render one manager's command for the given intent. */
+/** The package-manager-detector command for each non-global operation. */
+const COMMAND_FOR = {
+  add: "add",
+  ci: "frozen",
+  exec: "execute",
+  install: "install",
+  remove: "uninstall",
+  run: "run",
+} satisfies Record<Exclude<Operation, "create">, Command>;
+
+/**
+ * Render one manager's command for the given intent, via
+ * package-manager-detector's maintained agent tables (the engine behind `ni`).
+ */
 const buildCommand = (manager: PackageManager, intent: Intent): string => {
-  const args = intent.args.join(" ");
-  switch (intent.operation) {
-    case "add": {
-      if (manager === "npm") {
-        return `npm install ${args}`;
-      }
-      if (manager === "yarn" && intent.args.some((a) => GLOBAL_FLAGS.has(a))) {
-        const pkgs = intent.args.filter((a) => !GLOBAL_FLAGS.has(a)).join(" ");
-        return `yarn global add ${pkgs}`;
-      }
-      return `${manager} add ${args}`;
-    }
-    case "create": {
-      return `${manager} create ${args}`;
-    }
-    case "exec": {
-      if (manager === "npm") {
-        return `npx ${args}`;
-      }
-      if (manager === "bun") {
-        return `bunx ${args}`;
-      }
-      return `${manager} dlx ${args}`;
-    }
-    case "ci": {
-      // `npm ci` maps to a frozen, lockfile-faithful install elsewhere. Yarn
-      // Berry's flag is `--immutable` (`--frozen-lockfile` was removed in
-      // Yarn 4), matching the Berry-only `yarn dlx` the `exec` case emits.
-      if (manager === "npm") {
-        return "npm ci";
-      }
-      if (manager === "yarn") {
-        return "yarn install --immutable";
-      }
-      return `${manager} install --frozen-lockfile`;
-    }
-    case "remove": {
-      if (manager === "npm") {
-        return `npm uninstall ${args}`;
-      }
-      // Yarn Classic has no `remove -g`; the global form is `yarn global remove`.
-      if (manager === "yarn" && intent.args.some((a) => GLOBAL_FLAGS.has(a))) {
-        const pkgs = intent.args.filter((a) => !GLOBAL_FLAGS.has(a)).join(" ");
-        return `yarn global remove ${pkgs}`;
-      }
-      return `${manager} remove ${args}`;
-    }
-    case "run": {
-      return `${manager} run ${args}`;
-    }
-    default: {
-      return `${manager} install`;
-    }
+  // The tables carry no `create`; every manager spells it the same way.
+  if (intent.operation === "create") {
+    return `${manager} create ${intent.args.join(" ")}`;
+  }
+  // A `-g`/`--global` flag selects the dedicated global command (the tables
+  // place the flag themselves, per manager).
+  const global =
+    (intent.operation === "add" || intent.operation === "remove") &&
+    intent.args.some((arg) => GLOBAL_FLAGS.has(arg));
+  const args = global
+    ? intent.args.filter((arg) => !GLOBAL_FLAGS.has(arg))
+    : intent.args;
+  const command: Command = global
+    ? (intent.operation === "add" && "global") || "global_uninstall"
+    : COMMAND_FOR[intent.operation];
+  // Non-null: every operation above maps to a command each supported agent's
+  // table defines (null is only possible for gaps like npm's
+  // upgrade-interactive, which no Operation reaches).
+  const resolved = resolveCommand(AGENT_FOR[manager], command, args);
+  const words = resolved
+    ? [resolved.command, ...resolved.args]
+    : [manager, ...args];
+  // Docs favor the explicit spellings over the tables' terse aliases.
+  if (words[1] === "i") {
+    words[1] = "install";
+  }
+  if (words[0] === "bun" && words[1] === "x") {
+    words.splice(0, 2, "bunx");
   }
+  return words.join(" ");
 };
 
 /**
@@ -181,9 +188,7 @@ const buildCommand = (manager: PackageManager, intent: Intent): string => {
  * manager. Accepts a bare package list (`react`) or a full command
  * (`npm i -D typescript`, `npx astro add react`).
  */
-export const toPackageCommands = (
-  input: string
-): Record<PackageManager, string> => {
+export const toPackageCommands = (input: string) => {
   const intent = parseIntent(input);
   const normalize = (command: string): string =>
     command.replaceAll(WHITESPACE_RUN, " ").trim();
@@ -192,5 +197,5 @@ export const toPackageCommands = (
     npm: normalize(buildCommand("npm", intent)),
     pnpm: normalize(buildCommand("pnpm", intent)),
     yarn: normalize(buildCommand("yarn", intent)),
-  };
+  } satisfies Record<PackageManager, string>;
 };

package/src/markdown/table-wrap.ts

@@ -15,10 +15,13 @@
  * containing any non-text content (an image, an icon) counts as non-empty.
  */
 
+/** The value shapes hast allows on an element's `properties`. */
+type HastPropertyValue = string | number | boolean | (string | number)[];
+
 /** A minimal hast node (avoids a hast type dependency). */
 interface HastNode {
   children?: HastNode[];
-  properties?: Record<string, unknown>;
+  properties?: Record<string, HastPropertyValue>;
   tagName?: string;
   type: string;
   value?: string;

package/src/markdown/twoslash.ts

@@ -38,6 +38,8 @@ const require = createRequire(import.meta.url);
  * never pays the TypeScript parse cost.
  */
 export const blumeTwoslashTransformer = (): ShikiTransformer => {
+  // SAFETY: this resolves Blume's own pinned `typescript` dependency, whose
+  // CJS entry exports exactly the API namespace `typeof TS` describes.
   const tsModule = require("typescript") as typeof TS;
   const twoslasher = createTwoslasher({
     // Match the stock transformer's default: fence snippets are authored

package/src/og/card.ts

@@ -1,10 +1,12 @@
 import { readFile } from "node:fs/promises";
 
+import { imageSize } from "image-size";
 import { render } from "takumi-js";
 import type { RenderOptions } from "takumi-js";
 import { container, googleFonts, image, text } from "takumi-js/helpers";
 import type { FontSubset, GoogleFontFamily, Node } from "takumi-js/helpers";
 
+import { ACCENTS, isAccentPreset } from "../theme/palette.ts";
 import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH } from "./dimensions.ts";
 
 /** A local font file registered with the OG card renderer, read at build. */
@@ -54,23 +56,15 @@ export interface OgFontFamilies {
   title?: string;
 }
 
-const ACCENT_HEX: Record<string, string> = {
-  blue: "#3b82f6",
-  green: "#22c55e",
-  orange: "#f97316",
-  pink: "#ec4899",
-  purple: "#8b5cf6",
-  red: "#ef4444",
-  teal: "#14b8a6",
-};
-
-// Named presets map to Blume's palette hex (the preset "blue" is not CSS
-// blue); anything else is handed to Takumi as-is — it parses the full CSS
-// color grammar, and a genuinely malformed value fails the build with a
-// parse error naming it. `hasOwn` keeps a preset name like "constructor"
-// from resolving up the prototype chain.
+// Named presets resolve from the theme's own OKLCH table — Takumi parses the
+// full CSS color grammar, so the card renders exactly the accent the site
+// shows (a separate hand-synced hex palette used to drift: the card's "blue"
+// was Tailwind's, not Blume's). Anything else is handed to Takumi as-is, and
+// a genuinely malformed value fails the build with a parse error naming it.
+// `isAccentPreset` keeps a preset name like "constructor" from resolving up
+// the prototype chain.
 const resolveAccent = (accent: string): string =>
-  Object.hasOwn(ACCENT_HEX, accent) ? (ACCENT_HEX[accent] as string) : accent;
+  isAccentPreset(accent) ? ACCENTS[accent] : accent;
 
 export interface OgCardPalette {
   accent?: string;
@@ -159,6 +153,9 @@ const loadFonts = (
   const key = JSON.stringify(fonts);
   let pending = fontSubsetCache.get(key);
   if (!pending) {
+    // SAFETY: OgFont's weight strings are documented as variable ranges like
+    // "100..900" (GoogleFontFamily's WeightRange); Takumi validates the value
+    // at fetch time and fails the build naming a malformed one.
     pending = googleFonts(fonts as GoogleFontFamily[]);
     fontSubsetCache.set(key, pending);
   }
@@ -171,13 +168,29 @@ const loadFonts = (
  * registers each file once across a build's per-page renders; a missing file
  * rejects at first use, failing the build with the path in the cause.
  */
-const localFontLoader = (font: OgLocalFont) => ({
-  data: () => readFile(font.src),
-  key: font.src,
-  name: font.name,
-  ...(font.weight === undefined ? {} : { weight: font.weight }),
-  ...(font.style === undefined ? {} : { style: font.style }),
-});
+/** A lazily-read local font file, in the shape `render` accepts for `fonts`. */
+interface LocalFontSource {
+  data: () => Promise<Buffer>;
+  key: string;
+  name: string;
+  weight?: number;
+  style?: "normal" | "italic";
+}
+
+const localFontLoader = (font: OgLocalFont): LocalFontSource => {
+  const loader: LocalFontSource = {
+    data: () => readFile(font.src),
+    key: font.src,
+    name: font.name,
+  };
+  if (font.weight !== undefined) {
+    loader.weight = font.weight;
+  }
+  if (font.style !== undefined) {
+    loader.style = font.style;
+  }
+  return loader;
+};
 
 // Light neutral scale mirrored from the docs homepage theme tokens:
 // FOREGROUND = --foreground, MUTED = --muted-foreground, FAINT = that lighter,
@@ -219,17 +232,21 @@ export const truncate = (value: string, max: number): string => {
 // at full height — it stands alone as the brand (no text label beside it).
 const MARK_HEIGHT = 32;
 const MARK_MAX_WIDTH = 240;
-// Accept either quote style and a non-zero min-x/min-y; only width/height
-// matter for the aspect ratio. A miss falls back to a square mark.
-const VIEW_BOX =
-  /viewBox=(?<q>["'])[\d.-]+[\s,]+[\d.-]+[\s,]+(?<w>[\d.]+)[\s,]+(?<h>[\d.]+)\k<q>/u;
-
-/** The SVG's viewBox aspect ratio (w/h), or null without a usable viewBox. */
+/**
+ * The SVG's aspect ratio (w/h), or null when no usable dimensions exist (the
+ * caller falls back to a square mark). image-size (already a dependency)
+ * reads explicit width/height and falls back to the viewBox, tolerating the
+ * quote/whitespace/attribute spellings the old regex silently missed —
+ * `viewBox = "…"`, newline-separated values — which shipped visibly-squashed
+ * marks instead of failing loudly.
+ */
 const logoAspect = (svg: string): number | null => {
-  const box = svg.match(VIEW_BOX);
-  const w = Number(box?.groups?.w);
-  const h = Number(box?.groups?.h);
-  return w && h ? w / h : null;
+  try {
+    const { height, width } = imageSize(Buffer.from(svg));
+    return width && height ? width / height : null;
+  } catch {
+    return null;
+  }
 };
 
 // Render the configured logo as the brand mark. A `currentColor` logo carries

package/src/og/derive.ts

@@ -13,7 +13,6 @@ import type {
   FontsConfig,
   FontValue,
   LocalFontConfig,
-  RemoteFontConfig,
 } from "../theme/fonts.ts";
 import { GOOGLE_FONTS, isFontSlug } from "../theme/fonts.ts";
 import type { OgFont, OgFontFamilies, OgLocalFont } from "./card.ts";
@@ -31,6 +30,23 @@ const CARD_WEIGHTS = [400, 600];
 const absoluteSrc = (root: string, src: string): string =>
   isAbsolute(src) ? src : join(root, src);
 
+/** A concrete numeric face weight (as opposed to a variable-range string). */
+const isNumericWeight = (
+  weight: number | string | undefined
+): weight is number => typeof weight === "number";
+
+/** A variable-range weight spec string, e.g. `"100..900"`. */
+const isRangeWeight = (weight: number | string | undefined): weight is string =>
+  typeof weight === "string";
+
+/** A theme role configured as a font slug / family-name string. */
+const isFontName = (value: FontValue): value is string =>
+  typeof value === "string";
+
+/** An OG font entry that reads a local file (as opposed to a Google family). */
+const isLocalOgFont = (font: OgFont): font is OgLocalFont =>
+  typeof font !== "string" && "src" in font;
+
 /**
  * The weight spec to fetch for a derived Google family: the declared weights
  * the card uses, the declared numeric weights otherwise, a lone variable
@@ -39,9 +55,7 @@ const absoluteSrc = (root: string, src: string): string =>
 const googleWeights = (
   weights: (number | string)[]
 ): number[] | string | undefined => {
-  const numbers = weights.filter(
-    (weight): weight is number => typeof weight === "number"
-  );
+  const numbers = weights.filter(isNumericWeight);
   const used = numbers.filter((weight) => CARD_WEIGHTS.includes(weight));
   if (used.length > 0) {
     return used;
@@ -50,7 +64,7 @@ const googleWeights = (
     return numbers;
   }
   const [first] = weights;
-  return weights.length === 1 && typeof first === "string" ? first : undefined;
+  return weights.length === 1 && isRangeWeight(first) ? first : undefined;
 };
 
 const googleOgFont = (name: string, weights: (number | string)[]): OgFont => {
@@ -60,15 +74,19 @@ const googleOgFont = (name: string, weights: (number | string)[]): OgFont => {
 
 /** Per-variant local entries for the renderer (paths made absolute). */
 const localOgFonts = (font: LocalFontConfig, root: string): OgLocalFont[] =>
-  font.variants.map((variant) => ({
-    name: font.name,
-    src: absoluteSrc(root, variant.src),
-    ...(typeof variant.weight === "number" ? { weight: variant.weight } : {}),
+  font.variants.map((variant) => {
+    const entry: OgLocalFont = {
+      name: font.name,
+      src: absoluteSrc(root, variant.src),
+    };
+    const withWeight: OgLocalFont = isNumericWeight(variant.weight)
+      ? { ...entry, weight: variant.weight }
+      : entry;
     // Takumi's per-face style is normal/italic; oblique falls back to the file.
-    ...(variant.style === "normal" || variant.style === "italic"
-      ? { style: variant.style }
-      : {}),
-  }));
+    return variant.style === "normal" || variant.style === "italic"
+      ? { ...withWeight, style: variant.style }
+      : withWeight;
+  });
 
 /**
  * The card fonts for one theme role, or null when the role can't flow into
@@ -76,7 +94,7 @@ const localOgFonts = (font: LocalFontConfig, root: string): OgLocalFont[] =>
  * `googleFonts` only speaks Google's css2 endpoint).
  */
 const roleFonts = (value: FontValue, root: string): OgFont[] | null => {
-  if (typeof value === "string") {
+  if (isFontName(value)) {
     if (!isFontSlug(value)) {
       return null;
     }
@@ -86,16 +104,15 @@ const roleFonts = (value: FontValue, root: string): OgFont[] | null => {
   if ("variants" in value) {
     return localOgFonts(value, root);
   }
-  const remote = value as RemoteFontConfig;
-  if ((remote.provider ?? "google") !== "google") {
+  if ((value.provider ?? "google") !== "google") {
     return null;
   }
-  return [googleOgFont(remote.name, remote.weights ?? CARD_WEIGHTS)];
+  return [googleOgFont(value.name, value.weights ?? CARD_WEIGHTS)];
 };
 
 /** The family name a theme role registers under. */
 const roleFamily = (value: FontValue): string | null => {
-  if (typeof value === "string") {
+  if (isFontName(value)) {
     return isFontSlug(value) ? GOOGLE_FONTS[value].family : null;
   }
   return value.name;
@@ -136,18 +153,17 @@ export const deriveOgFonts = (
     }
   }
 
-  return {
-    fonts: derived,
-    ...(families.title || families.body ? { families } : {}),
-  };
+  const result: DerivedOgFonts = { fonts: derived };
+  if (families.title || families.body) {
+    result.families = families;
+  }
+  return result;
 };
 
 /** Explicit `seo.og.fonts` with local `src` paths resolved to absolute. */
 export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
   fonts.map((font) =>
-    typeof font !== "string" && "src" in font
-      ? { ...font, src: absoluteSrc(root, font.src) }
-      : font
+    isLocalOgFont(font) ? { ...font, src: absoluteSrc(root, font.src) } : font
   );
 
 /**
@@ -185,14 +201,14 @@ export const missingFontFiles = (
 ): string[] => {
   const sources: string[] = [];
   for (const value of Object.values(options.themeFonts ?? {})) {
-    if (typeof value !== "string" && "variants" in value) {
+    if (!isFontName(value) && "variants" in value) {
       sources.push(
         ...value.variants.map((variant) => absoluteSrc(root, variant.src))
       );
     }
   }
   for (const font of options.ogFonts) {
-    if (typeof font !== "string" && "src" in font) {
+    if (isLocalOgFont(font)) {
       sources.push(absoluteSrc(root, font.src));
     }
   }