blume 1.4.2 → 1.5.0

package/src/cli/index.ts

@@ -15,6 +15,7 @@ import { previewCommand } from "./commands/preview.ts";
 import { syncCommand } from "./commands/sync.ts";
 import { translateCommand } from "./commands/translate.ts";
 import { validateCommand } from "./commands/validate.ts";
+import { versionCommand } from "./commands/version.ts";
 import { loadEnvFiles } from "./env.ts";
 import { reportInternalError } from "./internal-error.ts";
 
@@ -39,6 +40,7 @@ const main = defineCommand({
     sync: syncCommand,
     translate: translateCommand,
     validate: validateCommand,
+    version: versionCommand,
   },
 });
 

package/src/cli/init/questions.ts

@@ -52,7 +52,7 @@ export interface InitFlags {
   template?: Template;
 }
 
-const cancelled = (value: unknown): value is symbol =>
+const cancelled = (value: string | string[] | symbol): value is symbol =>
   typeof value === "symbol";
 
 /**

package/src/cli/init/scaffold.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 
+import { detect } from "package-manager-detector/detect";
 import { basename, dirname, isAbsolute, join, relative } from "pathe";
 
 import { blumePackageJson, toPackageName } from "../../core/package-json.ts";
@@ -53,7 +54,7 @@ interface Starter {
 const page = (title: string, description: string, body: string): string =>
   `---\ntitle: ${title}\ndescription: ${description}\n---\n\n${body}\n`;
 
-export const STARTERS: Record<Template, Starter> = {
+export const STARTERS = {
   api: {
     configExtra: `
   openapi: {
@@ -134,16 +135,14 @@ export const STARTERS: Record<Template, Starter> = {
       },
     ],
   },
-};
+} satisfies Record<Template, Starter>;
 
 /**
  * Install + dev commands to print for the chosen package manager, plus the
  * prefix that runs a locally installed bin (`exec`, e.g. `npx blume eject`) —
  * dependency bins aren't on PATH, so a bare `blume …` hint would not run.
  */
-export const commandsFor = (
-  pm: PackageManager
-): { build: string; dev: string; exec: string; install: string } => ({
+export const commandsFor = (pm: PackageManager) => ({
   // `bun build` invokes Bun's bundler, not the package.json `build` script —
   // unlike `bun dev`, the script name is shadowed by a builtin subcommand.
   build: pm === "npm" || pm === "bun" ? `${pm} run build` : `${pm} build`,
@@ -152,13 +151,36 @@ export const commandsFor = (
   install: `${pm} install`,
 });
 
+const isPackageManager = (value: string): value is PackageManager =>
+  PACKAGE_MANAGERS.some((pm) => pm === value);
+
 /**
  * Derive the package manager from an npm user-agent string (the first
  * `name/version` token of `npm_config_user_agent`), falling back to npm.
+ * Right for `init`, where the project doesn't exist yet and the invoking
+ * runner is the only signal.
  */
 export const detectPackageManager = (userAgent?: string): PackageManager => {
-  const name = userAgent?.split("/")[0] as PackageManager | undefined;
-  return name !== undefined && PACKAGE_MANAGERS.includes(name) ? name : "npm";
+  const name = userAgent?.split("/")[0];
+  return name !== undefined && isPackageManager(name) ? name : "npm";
+};
+
+/**
+ * Detect an existing project's package manager from its lockfile /
+ * `packageManager` field (package-manager-detector), falling back to the
+ * user agent. Right for `eject`: the CLI is often run directly (`npx blume
+ * eject`, a bare `blume eject`), where `npm_config_user_agent` is absent or
+ * names the runner rather than the project's manager, and the old
+ * user-agent-only detection silently printed npm hints for a pnpm project.
+ */
+export const detectProjectPackageManager = async (
+  root: string
+): Promise<PackageManager> => {
+  const detected = await detect({ cwd: root });
+  const name = detected?.name;
+  return name !== undefined && isPackageManager(name)
+    ? name
+    : detectPackageManager(process.env.npm_config_user_agent);
 };
 
 /**
@@ -195,7 +217,7 @@ const hasRemoteSource = (sources: SourceKind[]): boolean =>
  * Config snippets for each remote source kind, with placeholder values to
  * replace and comments naming the env var each source authenticates with.
  */
-const SOURCE_SNIPPETS: Record<Exclude<SourceKind, "filesystem">, string> = {
+const SOURCE_SNIPPETS = {
   "github-releases": `      // Changelog entries from GitHub Releases. Private repos read
       // GITHUB_TOKEN from the environment.
       {
@@ -226,7 +248,7 @@ const SOURCE_SNIPPETS: Record<Exclude<SourceKind, "filesystem">, string> = {
         query: \`*[_type == "doc"]\`,
         prefix: "sanity",
       },`,
-};
+} satisfies Record<Exclude<SourceKind, "filesystem">, string>;
 
 /**
  * The `content` block for the generated config, or an empty string when the
@@ -272,10 +294,16 @@ export default defineConfig({
 `;
 
 /** SDK dependencies required by the selected remote sources. */
-const extraDepsFor = (sources: SourceKind[]): Record<string, string> => ({
-  ...(sources.includes("notion") && { "@notionhq/client": "^2.2.15" }),
-  ...(sources.includes("sanity") && { "@sanity/client": "^7.25.0" }),
-});
+const extraDepsFor = (sources: SourceKind[]) => {
+  const deps: Record<string, string> = {};
+  if (sources.includes("notion")) {
+    deps["@notionhq/client"] = "^2.2.15";
+  }
+  if (sources.includes("sanity")) {
+    deps["@sanity/client"] = "^7.25.0";
+  }
+  return deps;
+};
 
 /** Every file `init` should write for the given answers, package.json first. */
 export const buildPlan = (

package/src/cli/internal-error.ts

@@ -33,6 +33,7 @@ export const remapBlumeStack = (stack: string): string =>
  * message, a trimmed stack, and an environment dump for bug reports. Callers
  * exit after this — it doesn't exit itself, so it's testable.
  */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- last-resort handler for whatever a catch clause caught; anything narrower would force casts at every call site
 export const reportInternalError = (error: unknown): void => {
   const err = error instanceof Error ? error : new Error(String(error));
   const lines = [

package/src/cli/report-format.ts

@@ -0,0 +1,22 @@
+/**
+ * Number formatting shared by the translate and eval report renderers. The
+ * `1.5s` / `4m 12s` shapes are asserted in both suites — change them in both
+ * minds at once.
+ */
+
+/** Milliseconds as `1.5s`. */
+export const seconds = (ms: number): string => `${(ms / 1000).toFixed(1)}s`;
+
+/** A dollar cost as `$1.23`, or nothing when the run reported none. */
+export const money = (cost: number | undefined): string =>
+  cost === undefined ? "" : `$${cost.toFixed(2)}`;
+
+/** Milliseconds as `12.3s` under a minute, `4m 12s` from there up. */
+export const duration = (ms: number): string => {
+  if (ms < 60_000) {
+    return seconds(ms);
+  }
+  const minutes = Math.floor(ms / 60_000);
+  const rest = Math.round((ms % 60_000) / 1000);
+  return `${minutes}m ${rest}s`;
+};

package/src/components/content/AccordionItem.astro

@@ -1,5 +1,6 @@
 ---
 import Icon from "../Icon.astro";
+import { componentSlug } from "../slug.ts";
 
 interface Props {
   title: string;
@@ -10,15 +11,7 @@ interface Props {
 }
 
 const { defaultOpen = false, description, icon, id, title } = Astro.props;
-const slugify = (value: string): string =>
-  value
-    .toLowerCase()
-    .trim()
-    .replaceAll(/[^\w\s-]/gu, "")
-    .replaceAll(/[\s_]+/gu, "-")
-    .replaceAll(/-+/gu, "-")
-    .replaceAll(/^-|-$/gu, "");
-const accordionId = id ?? slugify(title);
+const accordionId = id ?? componentSlug(title);
 ---
 
 <details

package/src/components/content/ColorItem.astro

@@ -53,6 +53,8 @@ const displayValue =
 </style>
 
 <script>
+  import { copyText, flashLabel } from "../copy-feedback.ts";
+
   const state = window as Window & { __blumeColorCopy?: boolean };
   if (!state.__blumeColorCopy) {
     state.__blumeColorCopy = true;
@@ -67,24 +69,14 @@ const displayValue =
         return;
       }
 
-      try {
-        await navigator.clipboard.writeText(button.dataset.blumeColorCopy ?? "");
-      } catch {
+      if (!(await copyText(button.dataset.blumeColorCopy ?? ""))) {
         return;
       }
 
       const status = button.querySelector<HTMLElement>("[data-blume-color-status]");
-      if (!status) {
-        return;
+      if (status) {
+        flashLabel(status, "Copied");
       }
-
-      // Remember the real value once — capturing at click time would capture
-      // "Copied" on a double-click and stick until reload.
-      status.dataset.blumeLabel ??= status.textContent ?? "";
-      status.textContent = "Copied";
-      window.setTimeout(() => {
-        status.textContent = status.dataset.blumeLabel ?? "";
-      }, 1500);
     });
   }
 </script>

package/src/components/content/Component.astro

@@ -165,12 +165,16 @@ const paneClass = "motion-safe:transition-[height] motion-safe:duration-200";
 
   // A pane capped by a small viewport would otherwise stay small after the
   // window grows: the frame's content stopped changing size, so its observer
-  // has nothing new to report.
-  window.addEventListener("resize", () => {
-    for (const frame of document.querySelectorAll<HTMLIFrameElement>(
-      "iframe[data-blume-example-frame][data-blume-reported-height]"
-    )) {
-      applyMeasuredHeight(frame);
-    }
-  });
+  // has nothing new to report. rAF-coalesced so a live resize drag runs the
+  // read-then-write pass once per frame, not once per event.
+  window.addEventListener(
+    "resize",
+    rafThrottle(() => {
+      for (const frame of document.querySelectorAll<HTMLIFrameElement>(
+        "iframe[data-blume-example-frame][data-blume-reported-height]"
+      )) {
+        applyMeasuredHeight(frame);
+      }
+    })
+  );
 </script>

package/src/components/content/Frame.astro

@@ -1,6 +1,8 @@
 ---
 import { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";
 
+import { escapeRawHtml, unwrapParagraph } from "./inline-markdown.ts";
+
 interface Props {
   caption?: string;
   hint?: string;
@@ -8,18 +10,6 @@ interface Props {
 
 const { caption, hint } = Astro.props;
 
-const escapeRawHtml = (value: string): string =>
-  value.replaceAll("<", "&lt;").replaceAll(">", "&gt;");
-
-const unwrapParagraph = (html: string): string => {
-  const trimmed = html.trim();
-  // Only a *single* paragraph is unwrapped: the content must not contain its
-  // own `</p>`, or `<p>a</p>\n<p>b</p>` would "unwrap" to `a</p>\n<p>b` —
-  // unbalanced HTML injected via set:html.
-  const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
-  return match?.groups?.content ?? trimmed;
-};
-
 const markdownProcessor = await createSatteriMarkdownProcessor();
 const captionHtml = caption
   ? unwrapParagraph((await markdownProcessor.render(escapeRawHtml(caption))).code)

package/src/components/content/Prompt.astro

@@ -1,6 +1,8 @@
 ---
 import { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";
 
+import { escapeRawHtml, unwrapParagraph } from "./inline-markdown.ts";
+
 interface Props {
   actions?: boolean | string | string[];
   description: string;
@@ -8,18 +10,6 @@ interface Props {
 
 const { actions = ["copy"], description } = Astro.props;
 
-const escapeRawHtml = (value: string): string =>
-  value.replaceAll("<", "&lt;").replaceAll(">", "&gt;");
-
-const unwrapParagraph = (html: string): string => {
-  const trimmed = html.trim();
-  // Only a *single* paragraph is unwrapped: the content must not contain its
-  // own `</p>`, or `<p>a</p>\n<p>b</p>` would "unwrap" to `a</p>\n<p>b` —
-  // unbalanced HTML injected via set:html.
-  const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
-  return match?.groups?.content ?? trimmed;
-};
-
 const normalizeActions = (value: Props["actions"]): string[] => {
   if (Array.isArray(value)) {
     return value;
@@ -93,6 +83,8 @@ const secondaryButton =
 </blume-prompt>
 
 <script>
+  import { copyText, createCopyFlash } from "../copy-feedback.ts";
+
   class BlumePrompt extends HTMLElement {
     connectedCallback() {
       const content = this.querySelector<HTMLElement>(
@@ -116,28 +108,17 @@ const secondaryButton =
       const done = copy?.querySelector<HTMLElement>(
         "[data-blume-prompt-copy-done]"
       );
-      let resetTimer: ReturnType<typeof setTimeout> | undefined;
+      // Toggle visibility rather than swapping text: both labels occupy the
+      // same grid cell, so the button width never changes.
+      const flash = createCopyFlash((copied) => {
+        idle?.classList.toggle("invisible", copied);
+        done?.classList.toggle("invisible", !copied);
+      }, "Copied");
       copy?.addEventListener("click", async () => {
         const text = promptText();
-        if (!text) {
-          return;
-        }
-        try {
-          await navigator.clipboard.writeText(text);
-        } catch {
-          return;
+        if (text && (await copyText(text))) {
+          flash();
         }
-
-        // Toggle visibility rather than swapping text: both labels occupy the
-        // same grid cell, so the button width never changes. Clearing the timer
-        // keeps the "Copied" state 1.5s past the last of several rapid clicks.
-        clearTimeout(resetTimer);
-        idle?.classList.add("invisible");
-        done?.classList.remove("invisible");
-        resetTimer = setTimeout(() => {
-          idle?.classList.remove("invisible");
-          done?.classList.add("invisible");
-        }, 1500);
       });
     }
   }

package/src/components/content/Tab.astro

@@ -1,5 +1,6 @@
 ---
 import Icon from "../Icon.astro";
+import { componentSlug } from "../slug.ts";
 
 interface Props {
   class?: string;
@@ -10,15 +11,7 @@ interface Props {
 }
 
 const { class: className, icon, id, style, title } = Astro.props;
-const slugify = (value: string): string =>
-  value
-    .toLowerCase()
-    .trim()
-    .replaceAll(/[^\w\s-]/gu, "")
-    .replaceAll(/[\s_]+/gu, "-")
-    .replaceAll(/-+/gu, "-")
-    .replaceAll(/^-|-$/gu, "");
-const tabId = id ?? slugify(title);
+const tabId = id ?? componentSlug(title);
 ---
 
 {/*

package/src/components/content/Tooltip.astro

@@ -2,6 +2,7 @@
 import { randomUUID } from "node:crypto";
 
 import { contentHref } from "./base-href.ts";
+import { unwrapParagraph } from "./inline-markdown.ts";
 
 interface Props {
   cta?: string;
@@ -14,15 +15,6 @@ const { cta, headline, href, tip } = Astro.props;
 const tooltipId = `blume-tooltip-${randomUUID()}`;
 const external = href?.startsWith("http");
 
-const unwrapParagraph = (html: string): string => {
-  const trimmed = html.trim();
-  // Only a *single* paragraph is unwrapped: the content must not contain its
-  // own `</p>`, or `<p>a</p>\n<p>b</p>` would "unwrap" to `a</p>\n<p>b` —
-  // unbalanced HTML injected via set:html.
-  const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
-  return match?.groups?.content ?? trimmed;
-};
-
 const labelHtml = Astro.slots.has("default")
   ? unwrapParagraph(await Astro.slots.render("default"))
   : "";

package/src/components/content/Update.astro

@@ -1,4 +1,5 @@
 ---
+import { componentSlug } from "../slug.ts";
 import { contentHref } from "./base-href.ts";
 
 interface RssMetadata {
@@ -31,16 +32,8 @@ const {
   tags,
   title,
 } = Astro.props;
-const slugify = (text: string): string =>
-  text
-    .toLowerCase()
-    .trim()
-    .replaceAll(/[^\w\s-]/gu, "")
-    .replaceAll(/[\s_]+/gu, "-")
-    .replaceAll(/-+/gu, "-")
-    .replaceAll(/^-|-$/gu, "");
 const updateLabel = label ?? title ?? "Update";
-const id = providedId ?? (slugify(updateLabel) || "update");
+const id = providedId ?? (componentSlug(updateLabel) || "update");
 const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
 ---
 

package/src/components/content/auto-type-table.ts

@@ -75,6 +75,9 @@ export const extractTypeTable = async (
 ): Promise<TypeTableProperty[]> => {
   const { name, path, root = process.cwd(), source } = options;
   const tsModule = await import("typescript");
+  // SAFETY: CJS/ESM interop — the typescript package exposes its API namespace
+  // either directly or under `default` depending on the loader; both are the
+  // same object, which TypeScriptApi models structurally.
   const ts = (tsModule.default ?? tsModule) as TypeScriptApi;
 
   const compilerOptions: CompilerOptions = {

package/src/components/content/diff.ts

@@ -62,8 +62,11 @@ const registeredDiffThemeNames = new Set<string>();
  * shared between both modes must not hand light mode the dark-typed
  * registration.
  */
+const isThemeName = (theme: CodeTheme): theme is string =>
+  typeof theme === "string";
+
 const diffThemeName = (theme: CodeTheme, mode: "dark" | "light"): string => {
-  if (typeof theme === "string") {
+  if (isThemeName(theme)) {
     return theme;
   }
   const type = theme.type ?? mode;
@@ -90,7 +93,7 @@ const diffThemeName = (theme: CodeTheme, mode: "dark" | "light"): string => {
   return name;
 };
 
-const diffThemes = (themes: CodeThemes): { dark: string; light: string } => ({
+const diffThemes = (themes: CodeThemes) => ({
   dark: diffThemeName(themes.dark, "dark"),
   light: diffThemeName(themes.light, "light"),
 });
@@ -113,11 +116,12 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     theme = DEFAULT_CODE_THEMES,
   } = options;
 
-  if (patch !== undefined || src !== undefined) {
-    const text = patch ?? (await readText(src as string, root));
+  const patchText =
+    patch ?? (src === undefined ? undefined : await readText(src, root));
+  if (patchText !== undefined) {
     const result = await preloadPatchDiff({
       options: { theme: diffThemes(theme) },
-      patch: text,
+      patch: patchText,
     });
     return result.prerenderedHTML;
   }

package/src/components/content/github-info.ts

@@ -41,6 +41,8 @@ const load = async (
     return null;
   }
 
+  // SAFETY: GitHub's `GET /repos/{owner}/{repo}` contract carries these three
+  // fields on every 2xx response; a malformed body rejects into `loadSafe`.
   const data = (await response.json()) as {
     description: string | null;
     forks_count: number;

package/src/components/content/inline-markdown.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared helpers for components that render a short Markdown prop (a caption,
+ * a description, a tooltip label) into inline HTML injected via `set:html`.
+ * Previously copied verbatim into Prompt, Frame, and Tooltip.
+ */
+
+/**
+ * Neutralize raw HTML in a Markdown-rendered text prop by escaping only
+ * `<`/`>`. `&` deliberately stays: CommonMark already renders a bare `&` as
+ * `&amp;` and resolves real entity references, so leaving it alone keeps
+ * `&copy;`-style authoring working — a full HTML escape would render it as
+ * the literal text `&copy;`.
+ */
+export const escapeRawHtml = (value: string): string =>
+  value.replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+
+/**
+ * Unwrap the `<p>` a block-level Markdown render wraps around single-line
+ * content, so it can sit inside inline markup. Only a *single* paragraph is
+ * unwrapped: the content must not contain its own `</p>`, or
+ * `<p>a</p>\n<p>b</p>` would "unwrap" to `a</p>\n<p>b` — unbalanced HTML
+ * injected via `set:html`.
+ */
+export const unwrapParagraph = (html: string): string => {
+  const trimmed = html.trim();
+  const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
+  return match?.groups?.content ?? trimmed;
+};

package/src/components/copy-feedback.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared clipboard + "Copied" feedback used by every copy affordance (code
+ * blocks, page actions, color swatches, prompts, API panels, Ask AI). One
+ * implementation owns the invariants each site used to hand-roll:
+ *
+ * - the clipboard write is guarded, and nothing flashes on failure — a
+ *   confirmation must never lie;
+ * - repeat copies restart the hold instead of stacking timers, so the copied
+ *   state never reverts early after a double-click;
+ * - every successful copy is announced to a shared polite live region, so the
+ *   confirmation is audible, not just visual (previously only the code-block
+ *   button announced).
+ */
+
+/** How long the copied confirmation holds before reverting. */
+const HOLD_MS = 1500;
+
+/** The shared visually-hidden live region, created on first announcement. */
+let region: HTMLElement | null = null;
+
+/**
+ * Announce `message` to screen readers. The region is re-created if a swap
+ * (view transition, client router) disconnected it.
+ */
+export const announceCopied = (message: string): void => {
+  if (!region?.isConnected) {
+    region = document.createElement("div");
+    region.setAttribute("role", "status");
+    region.className = "sr-only";
+    document.body.append(region);
+  }
+  // Clear first so repeating the same message is re-announced.
+  region.textContent = "";
+  region.textContent = message;
+};
+
+/**
+ * Copy `text` to the clipboard. Returns whether the write succeeded; failures
+ * (insecure context, permissions) are swallowed so callers can simply skip
+ * their confirmation.
+ */
+export const copyText = async (text: string): Promise<boolean> => {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * A per-affordance flash: `apply(true)` paints the copied state, `apply(false)`
+ * reverts it after the hold. Calling the returned function again restarts the
+ * hold. `announce` (the localized "Copied" label) is spoken on each flash.
+ */
+export const createCopyFlash = (
+  apply: (copied: boolean) => void,
+  announce?: string,
+  holdMs: number = HOLD_MS
+): (() => void) => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return () => {
+    clearTimeout(timer);
+    apply(true);
+    if (announce) {
+      announceCopied(announce);
+    }
+    timer = setTimeout(() => apply(false), holdMs);
+  };
+};
+
+/** Flash timers for {@link flashLabel}, keyed per element. */
+const labelTimers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>();
+
+/**
+ * The text-swap flash: show `message` in `el`, then restore its own (possibly
+ * localized) label after the hold. The original label is captured once, on the
+ * first flash — capturing at click time would capture the flash message itself
+ * on a double-click and stick until reload.
+ */
+export const flashLabel = (
+  el: HTMLElement,
+  message: string,
+  holdMs: number = HOLD_MS
+): void => {
+  el.dataset.blumeLabel ??= el.textContent ?? "";
+  el.textContent = message;
+  announceCopied(message);
+  clearTimeout(labelTimers.get(el));
+  labelTimers.set(
+    el,
+    setTimeout(() => {
+      el.textContent = el.dataset.blumeLabel ?? "";
+    }, holdMs)
+  );
+};