blume 1.4.1 → 1.4.3

package/src/cli/commands/eval.ts

@@ -3,11 +3,7 @@ import { existsSync } from "node:fs";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
-import {
-  AGENTS,
-  launchAgent,
-  WINDOWS_COMMAND_NOT_FOUND,
-} from "../../audit/agent.ts";
+import { AGENTS, launchAgent } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
@@ -37,32 +33,32 @@ const DEFAULT_TIMEOUT_S = 180;
 const isAgentKind = (value: string): value is AgentKind => value in AGENTS;
 
 /**
- * Launch the interactive agent CLI, translating a missing executable into the
- * Windows not-found sentinel. Only `ENOENT` means "not installed" — any other
- * spawn failure (`EACCES`, `EMFILE`, …) must surface as itself.
+ * Launch the interactive agent CLI, turning a missing executable into the
+ * install hint. Only `ENOENT` means "not installed" — any other spawn failure
+ * (`EACCES`, `EMFILE`, …) must surface as itself.
  */
+const notInstalled = (agent: AgentKind): never => {
+  const cli = AGENTS[agent];
+  logger.error(
+    `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+  );
+  return process.exit(1);
+};
+
 const launchAgentCode = async (
-  bin: string,
+  agent: AgentKind,
   prompt: string
 ): Promise<number> => {
   try {
-    return await launchAgent(bin, prompt);
+    return await launchAgent(AGENTS[agent].bin, prompt);
   } catch (error) {
     if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
       throw error;
     }
-    return WINDOWS_COMMAND_NOT_FOUND;
+    return notInstalled(agent);
   }
 };
 
-const notInstalled = (agent: AgentKind): never => {
-  const cli = AGENTS[agent];
-  logger.error(
-    `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
-  );
-  return process.exit(1);
-};
-
 /** The fraction of run (non-skipped) questions that passed. */
 export const passFraction = (result: EvalResult): number => {
   const ran = result.results.length - result.counts.skip;
@@ -125,10 +121,7 @@ const runFixHandoff = async (
   process.stderr.write(
     `  Handing ${count} failed question${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
   );
-  const code = await launchAgentCode(cli.bin, evalFixPrompt(report));
-  if (code === WINDOWS_COMMAND_NOT_FOUND) {
-    notInstalled(agent);
-  }
+  const code = await launchAgentCode(agent, evalFixPrompt(report));
   if (code !== 0) {
     process.exit(code);
   }
@@ -143,10 +136,7 @@ const runInit = async (agent: AgentKind, file: string): Promise<void> => {
     );
     process.exit(1);
   }
-  const code = await launchAgentCode(AGENTS[agent].bin, initPrompt(file));
-  if (code === WINDOWS_COMMAND_NOT_FOUND) {
-    notInstalled(agent);
-  }
+  const code = await launchAgentCode(agent, initPrompt(file));
   if (code !== 0) {
     process.exit(code);
   }

package/src/cli/env.ts

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 
-import { parse } from "dotenv";
+import { config } from "dotenv";
 import { dirname, join, resolve } from "pathe";
 
 // Blume's remote sources (GitHub Releases, mdx-remote, Sanity, Notion…) read
@@ -9,44 +9,27 @@ import { dirname, join, resolve } from "pathe";
 // that gap: it cascades `.env`/`.env.local` from the working dir up to the repo
 // root, so a monorepo can keep one `.env` at the root and every app picks it up.
 
-/** Apply parsed vars without clobbering anything already in `process.env`. */
-const applyEnv = (parsed: Record<string, string>): void => {
-  for (const [key, value] of Object.entries(parsed)) {
-    if (!(key in process.env)) {
-      process.env[key] = value;
-    }
-  }
-};
-
-const loadFile = (path: string): void => {
-  try {
-    if (existsSync(path)) {
-      // dotenv is the same parser Vite runs over these files at build time,
-      // so a value means the same thing to the pre-boot content scan and the
-      // built site — including multi-line double-quoted values (PEM keys),
-      // which a line-based parser silently truncates.
-      applyEnv(parse(readFileSync(path, "utf-8")));
-    }
-  } catch {
-    // Env files are best-effort; a read/parse failure must not abort a build.
-  }
-};
-
 /**
  * Load `.env`/`.env.local`, cascading from `startDir` up to the repository root
- * (the first ancestor containing a `.git`) or the filesystem root. Nearer files
- * and existing `process.env` values win, so shell/CI overrides are never lost
- * and `.env.local` layers over `.env`.
+ * (the first ancestor containing a `.git`) or the filesystem root. The ordered
+ * path list is handed to dotenv, whose `config` is first-wins, never clobbers
+ * existing `process.env` values, and treats unreadable files as best-effort —
+ * so shell/CI overrides are never lost, `.env.local` layers over `.env`, and a
+ * bad file never aborts a build. dotenv is also the parser Vite runs over
+ * these files at build time, so a value means the same thing to the pre-boot
+ * content scan and the built site — including multi-line double-quoted values
+ * (PEM keys), which a line-based parser silently truncates.
  */
 export const loadEnvFiles = (startDir: string): void => {
+  const paths: string[] = [];
   let dir = resolve(startDir);
   let done = false;
   while (!done) {
-    loadFile(join(dir, ".env.local"));
-    loadFile(join(dir, ".env"));
+    paths.push(join(dir, ".env.local"), join(dir, ".env"));
     const parent = dirname(dir);
     // Stop at the repo root (nearest `.git`) or the filesystem root.
     done = existsSync(join(dir, ".git")) || parent === dir;
     dir = parent;
   }
+  config({ path: paths, quiet: true });
 };

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";
@@ -155,12 +156,32 @@ export const commandsFor = (
 /**
  * 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";
 };
 
+/**
+ * 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 as PackageManager | undefined;
+  return name !== undefined && PACKAGE_MANAGERS.includes(name)
+    ? name
+    : detectPackageManager(process.env.npm_config_user_agent);
+};
+
 /**
  * The content dir is joined into every scaffolded file path, so an absolute or
  * `../`-escaping value would write outside the project. Returns an error

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/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)
+  );
+};