blume 0.5.4 → 0.6.1

package/src/cli/dev-lock.ts

@@ -14,26 +14,48 @@ import { logger } from "./log.ts";
 /**
  * A best-effort PID lock in the shared `.blume/` runtime dir. `blume dev`
  * regenerates and serves `.blume` continuously, so a concurrent `build`,
- * `eject`, or `sync --force` that regenerates or deletes it out from under the
+ * `eject`, or second `dev` that regenerates or deletes it out from under the
  * running Vite server corrupts the dev session. The lock lets those commands
- * detect a live dev server and refuse.
+ * detect a live dev server and refuse — and, because it records the server's
+ * port, point the caller (often an agent that just tried to start its own
+ * server) at the URL to reuse instead.
  */
 
+export interface DevLockInfo {
+  pid: number;
+  /** Port the dev server is bound to, when known. */
+  port?: number;
+}
+
 const lockPath = (outDir: string): string => join(outDir, "dev.lock");
 
+const isValidPid = (pid: unknown): pid is number =>
+  typeof pid === "number" && Number.isInteger(pid) && pid > 0;
+
 /**
- * Whether another live `blume dev` holds the lock on `outDir`. A lock left by a
- * process that has since exited (stale) is treated as absent.
+ * Parse a lock file body. Current locks are JSON (`{"pid":123,"port":3001}`);
+ * a bare integer (the pre-port format) still parses as a pid-only lock.
  */
-export const isDevLocked = (outDir: string): boolean => {
-  const path = lockPath(outDir);
-  if (!existsSync(path)) {
-    return false;
+const parseLock = (raw: string): DevLockInfo | null => {
+  let data: unknown;
+  try {
+    data = JSON.parse(raw.trim());
+  } catch {
+    return null;
   }
-  const pid = Number.parseInt(readFileSync(path, "utf-8").trim(), 10);
-  if (!(Number.isInteger(pid) && pid > 0)) {
-    return false;
+  if (isValidPid(data)) {
+    return { pid: data };
   }
+  if (typeof data === "object" && data !== null) {
+    const { pid, port } = data as { pid?: unknown; port?: unknown };
+    if (isValidPid(pid)) {
+      return typeof port === "number" ? { pid, port } : { pid };
+    }
+  }
+  return null;
+};
+
+const isProcessAlive = (pid: number): boolean => {
   try {
     // Signal 0 probes liveness without actually signaling the process.
     process.kill(pid, 0);
@@ -45,15 +67,53 @@ export const isDevLocked = (outDir: string): boolean => {
   }
 };
 
+/**
+ * Read the lock on `outDir` held by a live `blume dev`, or null. A lock left
+ * by a process that has since exited (stale) is treated as absent.
+ */
+export const readDevLock = (outDir: string): DevLockInfo | null => {
+  const path = lockPath(outDir);
+  if (!existsSync(path)) {
+    return null;
+  }
+  const lock = parseLock(readFileSync(path, "utf-8"));
+  return lock && isProcessAlive(lock.pid) ? lock : null;
+};
+
+/** Whether another live `blume dev` holds the lock on `outDir`. */
+export const isDevLocked = (outDir: string): boolean =>
+  readDevLock(outDir) !== null;
+
+const writeLock = (outDir: string, port?: number): void => {
+  writeFileSync(
+    lockPath(outDir),
+    JSON.stringify({
+      pid: process.pid,
+      ...(port === undefined ? {} : { port }),
+    })
+  );
+};
+
+const ownsLock = (outDir: string): boolean => {
+  const path = lockPath(outDir);
+  if (!existsSync(path)) {
+    return false;
+  }
+  try {
+    return parseLock(readFileSync(path, "utf-8"))?.pid === process.pid;
+  } catch {
+    return false;
+  }
+};
+
 /**
  * Write the current process's dev lock into `outDir` and return a release
  * function. The release only removes the file if it's still ours, so a newer
  * dev server's lock is never clobbered.
  */
-export const acquireDevLock = (outDir: string): (() => void) => {
-  const path = lockPath(outDir);
+export const acquireDevLock = (outDir: string, port?: number): (() => void) => {
   mkdirSync(outDir, { recursive: true });
-  writeFileSync(path, String(process.pid));
+  writeLock(outDir, port);
   let released = false;
   return () => {
     if (released) {
@@ -61,11 +121,8 @@ export const acquireDevLock = (outDir: string): (() => void) => {
     }
     released = true;
     try {
-      if (
-        existsSync(path) &&
-        readFileSync(path, "utf-8").trim() === String(process.pid)
-      ) {
-        rmSync(path, { force: true });
+      if (ownsLock(outDir)) {
+        rmSync(lockPath(outDir), { force: true });
       }
     } catch {
       // Best-effort cleanup; a stale lock is handled by the liveness check.
@@ -73,6 +130,21 @@ export const acquireDevLock = (outDir: string): (() => void) => {
   };
 };
 
+/**
+ * Rewrite this process's lock with the port the server actually bound (the
+ * lock is acquired before the server starts, and Vite may bump a busy port).
+ * A lock owned by another process is left alone.
+ */
+export const updateDevLockPort = (outDir: string, port: number): void => {
+  if (ownsLock(outDir)) {
+    writeLock(outDir, port);
+  }
+};
+
+/** Human-readable location of a locked dev server, e.g. " at http://localhost:3001". */
+export const describeDevLock = (lock: DevLockInfo): string =>
+  lock.port === undefined ? "" : ` at http://localhost:${lock.port}`;
+
 /**
  * Exit with an error when a live `blume dev` owns the runtime dir under `root`.
  * `action` names the operation being refused (e.g. "building"). `runtimeDir`
@@ -85,9 +157,10 @@ export const refuseIfDevRunning = (
   action: string,
   runtimeDir?: string
 ): void => {
-  if (isDevLocked(resolveRuntimeDir(root, runtimeDir))) {
+  const lock = readDevLock(resolveRuntimeDir(root, runtimeDir));
+  if (lock) {
     logger.error(
-      `A \`blume dev\` server is running against .blume; ${action} would corrupt it. Stop the dev server, or re-run with --isolated to build/verify against .blume-verify without touching it.`
+      `A \`blume dev\` server is running${describeDevLock(lock)}; ${action} would corrupt its .blume runtime. Reuse that server, stop it first, or re-run with --isolated to build/verify against .blume-verify without touching it.`
     );
     process.exit(1);
   }

package/src/components/content/GithubInfo.astro

@@ -3,10 +3,17 @@
 // at build time (no client JS). Pass `owner`/`repo`, or omit them to use the
 // repo from blume.config. A `GITHUB_TOKEN` env var lifts the API rate limit.
 // If the API is unreachable the card still renders, just without counts.
+import { resolveIcon } from "../../theme/icons.ts";
 import data from "blume:data";
 import { GITHUB_MARK } from "../github-mark.ts";
 import { fetchRepositoryInfo } from "./github-info.ts";
 
+// Star/fork glyphs resolve from Lucide at build time; the `<svg>` wrappers below
+// supply size and the shared `statIcon` class. (The GitHub octocat above is a
+// brand mark, not a Lucide icon, so it stays as GITHUB_MARK.)
+const starIcon = resolveIcon("star")?.body ?? "";
+const forkIcon = resolveIcon("git-fork")?.body ?? "";
+
 interface Props {
   owner?: string;
   repo?: string;
@@ -77,9 +84,8 @@ const statIcon =
               stroke-width="2"
               viewBox="0 0 24 24"
               width="14"
-            >
-              <path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z" />
-            </svg>
+              set:html={starIcon}
+            />
             <span>{numbers.format(info.stars)}</span>
           </span>
           <span class="flex items-center gap-1.5">
@@ -94,13 +100,8 @@ const statIcon =
               stroke-width="2"
               viewBox="0 0 24 24"
               width="14"
-            >
-              <circle cx="12" cy="18" r="3" />
-              <circle cx="6" cy="6" r="3" />
-              <circle cx="18" cy="6" r="3" />
-              <path d="M18 9v2c0 .6-.4 1-1 1H7c-.6 0-1-.4-1-1V9" />
-              <path d="M12 12v3" />
-            </svg>
+              set:html={forkIcon}
+            />
             <span>{numbers.format(info.forks)}</span>
           </span>
         </span>

package/src/components/content/TypeTable.astro

@@ -4,6 +4,12 @@
 // the accent-colored prop name (with a `?` suffix when optional) and its type;
 // expanded, the row lifts into a card showing the description and a Type/Default
 // detail grid. Uses native <details>/<summary> so the core stays React-free.
+import { resolveIcon } from "../../theme/icons.ts";
+
+// The row disclosure caret; resolved from Lucide at build time and injected into
+// the summary's `<svg>` (which supplies size and the rotate-on-open transition).
+const chevronDown = resolveIcon("chevron-down")?.body ?? "";
+
 interface TypeEntry {
   default?: string;
   description?: string;
@@ -64,9 +70,8 @@ const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
               stroke-width="2"
               viewBox="0 0 24 24"
               width="16"
-            >
-              <path d="m6 9 6 6 6-6" />
-            </svg>
+              set:html={chevronDown}
+            />
           </summary>
 
           <div class="border-border border-t px-3 py-3 text-xs">

package/src/components/content/Update.astro

@@ -6,6 +6,8 @@ interface RssMetadata {
 
 interface Props {
   description?: string;
+  /** Link the heading to a dedicated page; falls back to the in-page anchor. */
+  href?: string;
   id?: string;
   label?: string;
   rss?: RssMetadata;
@@ -13,7 +15,15 @@ interface Props {
   title?: string;
 }
 
-const { description, id: providedId, label, rss, tags, title } = Astro.props;
+const {
+  description,
+  href,
+  id: providedId,
+  label,
+  rss,
+  tags,
+  title,
+} = Astro.props;
 const slugify = (text: string): string =>
   text
     .toLowerCase()
@@ -37,7 +47,7 @@ const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
   <header class="md:border-border md:border-e md:pe-4">
     <a
       class="font-semibold text-foreground text-sm no-underline hover:text-accent"
-      href={`#${id}`}
+      href={href ?? `#${id}`}
     >
       {updateLabel}
     </a>

package/src/components/content/changelog-element.ts

@@ -0,0 +1,62 @@
+/**
+ * Client behaviour for the `<blume-changelog>` custom element wrapping the
+ * generated changelog timeline when its releases are semver-versioned. The
+ * newest major line stays visible; every older major is collapsed into a group
+ * revealed one major at a time by the "Show N.x releases" button at the bottom.
+ *
+ * Pure progressive enhancement: the server renders every release in document
+ * order, and this element hides the older-major groups on connect — so a no-JS
+ * visitor (or a crawler) still sees the complete history, and the button does
+ * nothing until the script upgrades it.
+ *
+ * Imported for its side effect (registers the element) from the changelog page.
+ */
+
+class BlumeChangelog extends HTMLElement {
+  connectedCallback() {
+    const groups = [
+      ...this.querySelectorAll<HTMLElement>("[data-changelog-major]"),
+    ];
+    const button = this.querySelector<HTMLButtonElement>(
+      "[data-changelog-more]"
+    );
+    if (groups.length === 0 || !button) {
+      return;
+    }
+
+    for (const group of groups) {
+      group.hidden = true;
+      // Focusable only programmatically, so revealing a group can move focus to
+      // it for keyboard and screen-reader users without adding a tab stop.
+      group.tabIndex = -1;
+    }
+
+    let revealed = 0;
+    const sync = () => {
+      const next = groups[revealed];
+      if (next) {
+        button.textContent = `Show ${next.dataset.changelogLabel} releases`;
+        button.hidden = false;
+      } else {
+        button.hidden = true;
+      }
+    };
+
+    button.addEventListener("click", () => {
+      const next = groups[revealed];
+      if (!next) {
+        return;
+      }
+      next.hidden = false;
+      revealed += 1;
+      sync();
+      next.focus();
+    });
+
+    sync();
+  }
+}
+
+if (!customElements.get("blume-changelog")) {
+  customElements.define("blume-changelog", BlumeChangelog);
+}

package/src/components/islands/AskAI.astro

@@ -1,12 +1,76 @@
 ---
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { resolveIcon } from "../../theme/icons.ts";
 import AskAI from "./ask-ai.tsx";
 
+interface Suggestion {
+  icon?: string;
+  label: string;
+}
+
 interface Props {
   strings?: UIStrings["ask"];
+  suggestions?: Suggestion[];
 }
 
-const { strings } = Astro.props;
+const { strings, suggestions = [] } = Astro.props;
+
+// Icons resolve to inline SVG here (server-only module), so the client island
+// gets ready-to-render markup rather than a name it can't resolve. Bare Lucide
+// bodies carry no styling, so wrap them in a stroke-styled root like Icon.astro.
+const svgFor = (name: string | undefined): string | null => {
+  const resolved = resolveIcon(name ?? "sparkles") ?? resolveIcon("sparkles");
+  return resolved
+    ? `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${resolved.viewBox}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${resolved.body}</svg>`
+    : null;
+};
+
+const items = suggestions.map((suggestion) => ({
+  icon: svgFor(suggestion.icon),
+  label: suggestion.label,
+}));
+
+// The panel's own chrome glyphs resolve here too, so the client island carries
+// no icon data. Each value is the bare Lucide body; the island's <Glyph> wraps
+// it in a sized, stroke-styled <svg>. Keyed by role → Lucide icon name.
+const bodyFor = (name: string): string => resolveIcon(name)?.body ?? "";
+const icons = {
+  arrowUp: bodyFor("arrow-up"),
+  chat: bodyFor("message-circle"),
+  clear: bodyFor("trash-2"),
+  close: bodyFor("chevrons-right"),
+  copy: bodyFor("copy"),
+};
 ---
 
-<AskAI client:load strings={strings} />
+<AskAI client:load icons={icons} strings={strings} suggestions={items} />
+
+<style is:global>
+  :root {
+    --blume-ask-width: min(30rem, 100vw);
+  }
+
+  /* Desktop docks the panel and shrinks the page to fit, like vercel.com/docs.
+     On smaller screens the panel is a full-width overlay (no push). */
+  @media (min-width: 1024px) {
+    body {
+      transition: padding-inline-end 0.2s ease-out;
+    }
+
+    body[data-blume-ask="open"] {
+      padding-inline-end: var(--blume-ask-width);
+    }
+  }
+
+  /* The table of contents only shows at xl; reclaim its column for the article
+     while the panel is open so the shrunken content still has room to breathe. */
+  @media (min-width: 1280px) {
+    body[data-blume-ask="open"] [data-blume-toc] {
+      display: none;
+    }
+
+    body[data-blume-ask="open"] [data-blume-doc-grid] {
+      grid-template-columns: 17.5rem minmax(0, 1fr);
+    }
+  }
+</style>