blume 2.0.2 → 2.0.3

package/src/cli/commands/eval.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 
 import { defineCommand } from "citty";
-import { join } from "pathe";
+import { resolve } from "pathe";
 
 import { AGENTS, launchAgent } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
@@ -22,6 +22,7 @@ import {
 import { passFraction, runEval } from "../../eval/run.ts";
 import type { EvalResult } from "../../eval/run.ts";
 import { EvalsFileError, loadEvalsFile } from "../../eval/schema.ts";
+import { parseTimeoutSeconds } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger, reportDiagnostics } from "../log.ts";
@@ -88,16 +89,18 @@ const parseFlags = (args: EvalFlags) => {
     process.exit(1);
   }
   const threshold = args.threshold === undefined ? 1 : Number(args.threshold);
-  if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+  // A bare `--threshold` (or `--threshold $UNSET_VAR`) arrives as "", which
+  // `Number` reads as 0 — a gate that passes every run — so it's rejected.
+  if (
+    args.threshold?.trim() === "" ||
+    !Number.isFinite(threshold) ||
+    threshold < 0 ||
+    threshold > 1
+  ) {
     logger.error(`Invalid --threshold "${args.threshold}" (use 0..1).`);
     process.exit(1);
   }
-  const timeoutS =
-    args.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(args.timeout);
-  if (!Number.isInteger(timeoutS) || timeoutS <= 0) {
-    logger.error(`Invalid --timeout "${args.timeout}" (whole seconds).`);
-    process.exit(1);
-  }
+  const timeoutS = parseTimeoutSeconds(args.timeout, DEFAULT_TIMEOUT_S);
   return { agent: args.agent, threshold, timeoutS };
 };
 
@@ -125,7 +128,7 @@ const runFixHandoff = async (
 
 /** `blume eval init`: draft a starter evals file via the interactive agent. */
 const runInit = async (agent: AgentKind, file: string): Promise<void> => {
-  const path = join(process.cwd(), file);
+  const path = resolve(process.cwd(), file);
   if (existsSync(path)) {
     logger.error(
       `${file} already exists — edit it directly, or pass --file to draft elsewhere.`
@@ -193,7 +196,9 @@ export const evalCommand = defineCommand({
       // and never regenerates the runtime, so it doesn't contend with a
       // running dev server. Same reasoning as `blume audit`.
       const project = await scanProject(root, { mode: "build" });
-      const evalsPath = join(root, args.file);
+      // `resolve`, not `join`: an absolute `--file` (`/ci/evals.yaml`) is
+      // used as given instead of being nested under the project root.
+      const evalsPath = resolve(root, args.file);
       const { evals, raw } = await loadEvalsFile(evalsPath);
 
       process.stderr.write(`${headerLine(evals.questions.length, agent)}\n\n`);
@@ -270,7 +275,10 @@ export const evalCommand = defineCommand({
     }
 
     if (failed) {
-      process.exit(1);
+      // Set the code and return rather than `process.exit`, which doesn't wait
+      // for a piped stderr: a long `--verbose` report was cut off mid-write, in
+      // exactly the CI logs that need to show every failure.
+      process.exitCode = 1;
     }
   },
 });

package/src/cli/commands/translate.ts

@@ -28,9 +28,10 @@ import {
   computeWorkList,
   scanForTranslation,
 } from "../../translate/work-list.ts";
+import { parseTimeoutSeconds } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { flushStdout, logger, reportDiagnostics } from "../log.ts";
+import { logger, reportDiagnostics } from "../log.ts";
 
 /** Wall-clock ceiling per file, in seconds. */
 const DEFAULT_TIMEOUT_S = DEFAULT_TRANSLATE_TIMEOUT_MS / 1000;
@@ -80,12 +81,7 @@ const parseFlags = (args: TranslateFlags): ParsedTranslateFlags => {
     );
     process.exit(1);
   }
-  const timeoutS =
-    args.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(args.timeout);
-  if (!Number.isInteger(timeoutS) || timeoutS <= 0) {
-    logger.error(`Invalid --timeout "${args.timeout}" (whole seconds).`);
-    process.exit(1);
-  }
+  const timeoutS = parseTimeoutSeconds(args.timeout, DEFAULT_TIMEOUT_S);
   const concurrency =
     args.concurrency === undefined
       ? DEFAULT_CONCURRENCY
@@ -228,8 +224,9 @@ export const translateCommand = defineCommand({
           process.stdout.write(checkReportJson(workList));
         }
         if (hasDrift(workList)) {
-          await flushStdout();
-          process.exit(1);
+          // Set the code and return rather than `process.exit`, which waits for
+          // neither a piped stderr (the drift report) nor a piped stdout.
+          process.exitCode = 1;
         }
         return;
       }
@@ -290,9 +287,9 @@ export const translateCommand = defineCommand({
       }
       if (result.counts.failed > 0 || result.counts.partial > 0) {
         // The ledger write above already persisted every success, so a failed
-        // rerun only retries what actually failed.
-        await flushStdout();
-        process.exit(1);
+        // rerun only retries what actually failed. Set the code rather than
+        // `process.exit`, which would cut off a piped stderr summary.
+        process.exitCode = 1;
       }
     } catch (error) {
       if (error instanceof BlumeError) {

package/src/cli/commands/validate.ts

@@ -119,7 +119,9 @@ export const validateCommand = defineCommand({
       logger.success("No broken links found.");
     }
     if (hadErrors || strictFailure) {
-      process.exit(1);
+      // Set the code and return rather than `process.exit`, which doesn't wait
+      // for a piped stderr: a long diagnostic list would be cut off.
+      process.exitCode = 1;
     }
   },
 });

package/src/cli/dev-lock.ts

@@ -1,8 +1,11 @@
 import {
   existsSync,
+  linkSync,
   mkdirSync,
   readFileSync,
+  renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 
@@ -29,6 +32,83 @@ export interface DevLockInfo {
 
 const lockPath = (outDir: string): string => join(outDir, "dev.lock");
 
+/** The mutex a process holds while it clears a stale lock. */
+const reapPath = (outDir: string): string => join(outDir, "dev.lock.reap");
+
+/**
+ * How long a lock file that doesn't parse counts as one being written right
+ * now. Blume creates a lock with its whole content in place (see
+ * {@link createExclusive}), but one left empty or cut off — by a crash, or by
+ * an older Blume that opened the file before writing it — would otherwise
+ * read as stale the instant it appears. Past this age it's debris.
+ */
+const PARTIAL_LOCK_GRACE_MS = 2000;
+
+/** Pause between claim attempts while another process is mid-claim. */
+const RETRY_DELAY_MS = 5;
+
+const pause = (ms: number): void => {
+  // A synchronous sleep: the claim is synchronous, and what it waits on is
+  // another process, so there's nothing in this one to yield to.
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
+/** Per-process counter that keeps concurrent temp file names apart. */
+let tempSequence = 0;
+
+/** A private sibling of `path` to stage a write in. */
+const tempPath = (path: string): string => {
+  tempSequence += 1;
+  return `${path}.${process.pid}.${tempSequence}.tmp`;
+};
+
+/**
+ * Create `path` holding `payload`, atomically and exclusively. The payload
+ * goes to a private temp file first, which is then hard-linked into place:
+ * the link fails when `path` exists, exactly like a `wx` open, but the file
+ * appears with its whole content — no reader ever sees it empty or half
+ * written. Returns false when `path` already exists.
+ */
+const createExclusive = (path: string, payload: string): boolean => {
+  const temp = tempPath(path);
+  writeFileSync(temp, payload);
+  try {
+    linkSync(temp, path);
+    return true;
+  } catch (error) {
+    // SAFETY: `linkSync` failures are errno exceptions.
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+    return false;
+  } finally {
+    rmSync(temp, { force: true });
+  }
+};
+
+/** Replace `path` with `payload` in one step, so readers see old or new. */
+const replaceFile = (path: string, payload: string): void => {
+  const temp = tempPath(path);
+  writeFileSync(temp, payload);
+  renameSync(temp, path);
+};
+
+/** A file's text, or null when it doesn't exist (anymore). */
+const readIfExists = (
+  path: string
+): { raw: string; mtimeMs: number } | null => {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return { mtimeMs: statSync(path).mtimeMs, raw };
+  } catch (error) {
+    // SAFETY: `readFileSync`/`statSync` failures are errno exceptions.
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+    return null;
+  }
+};
+
 /** What `JSON.parse` can yield for a lock file body. */
 type LockFileValue =
   | string
@@ -85,17 +165,44 @@ const isProcessAlive = (pid: number): boolean => {
   }
 };
 
+/** What the lock file on a dir says, read once. */
+type LockState =
+  | { kind: "absent" }
+  /** Unparseable but brand new: another process is writing it right now. */
+  | { kind: "busy" }
+  | { kind: "live"; lock: DevLockInfo }
+  /** A dead holder's lock, or unparseable debris. */
+  | { kind: "stale" };
+
+const inspectLock = (outDir: string): LockState => {
+  const file = readIfExists(lockPath(outDir));
+  if (!file) {
+    return { kind: "absent" };
+  }
+  const lock = parseLock(file.raw);
+  if (!lock) {
+    return Date.now() - file.mtimeMs < PARTIAL_LOCK_GRACE_MS
+      ? { kind: "busy" }
+      : { kind: "stale" };
+  }
+  return isProcessAlive(lock.pid) ? { kind: "live", lock } : { kind: "stale" };
+};
+
+/**
+ * Whether this process may clear the lock to claim the dir: a dead holder's
+ * lock and debris, or this process's own leftover.
+ */
+const isClaimable = (state: LockState): boolean =>
+  state.kind === "stale" ||
+  (state.kind === "live" && state.lock.pid === process.pid);
+
 /**
  * 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;
+  const state = inspectLock(outDir);
+  return state.kind === "live" ? state.lock : null;
 };
 
 /** Whether another live `blume dev` holds the lock on `outDir`. */
@@ -110,10 +217,6 @@ const lockPayload = (port?: number): string => {
   return JSON.stringify(info);
 };
 
-const writeLock = (outDir: string, port?: number): void => {
-  writeFileSync(lockPath(outDir), lockPayload(port));
-};
-
 /** Thrown when another live `blume dev` already holds the lock. */
 export class DevLockHeldError extends Error {
   readonly lock: DevLockInfo;
@@ -138,43 +241,58 @@ const ownsLock = (outDir: string): boolean => {
 };
 
 /**
- * One atomic claim attempt. Returns `true` when this process wins the `wx`
- * write, `false` when the dir held a stale or our-own leftover lock (now
- * cleared, so the caller should retry). Throws {@link DevLockHeldError} when a
- * live foreign holder owns the dir.
+ * Clear a claimable lock without racing anyone else doing the same. Two
+ * processes can both read the same stale lock; if each simply deleted the
+ * file, the slower one could delete the lock the faster one had claimed in
+ * between, and both would win. So removing a lock takes the reap mutex
+ * (created the same atomic way), and whoever holds it reads the lock again
+ * first: a live lock claimed since is left alone. A mutex whose holder died
+ * mid-reap is cleared for the next attempt.
  */
-const tryClaimLock = (outDir: string, port?: number): boolean => {
-  try {
-    writeFileSync(lockPath(outDir), lockPayload(port), { flag: "wx" });
-    return true;
-  } catch (error) {
-    // SAFETY: `writeFileSync` failures are errno exceptions.
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-      throw error;
+const reapStaleLock = (outDir: string): void => {
+  const mutex = reapPath(outDir);
+  if (!createExclusive(mutex, lockPayload())) {
+    const holder = readIfExists(mutex);
+    const pid = holder ? parseLock(holder.raw)?.pid : undefined;
+    if (pid !== undefined && pid !== process.pid && isProcessAlive(pid)) {
+      pause(RETRY_DELAY_MS);
+    } else if (holder) {
+      rmSync(mutex, { force: true });
     }
-    const existing = readDevLock(outDir);
-    if (existing && existing.pid !== process.pid) {
-      throw new DevLockHeldError(existing);
+    return;
+  }
+  try {
+    if (isClaimable(inspectLock(outDir))) {
+      rmSync(lockPath(outDir), { force: true });
     }
-    // Stale or our own leftover: clear it and race for the claim again.
-    rmSync(lockPath(outDir), { force: true });
-    return false;
+  } finally {
+    rmSync(mutex, { force: true });
   }
 };
 
 /**
  * Write the current process's dev lock into `outDir` and return a release
- * function. The claim is atomic (`wx`): two `blume dev` processes racing the
- * same dir can't both pass a check-then-write — the loser gets a
- * {@link DevLockHeldError} naming the live holder. A stale lock (dead pid) or
- * this process's own leftover is cleared and re-claimed. The release only
- * removes the file if it's still ours, so a newer dev server's lock is never
- * clobbered.
+ * function. Two `blume dev` processes starting at the same moment can't both
+ * win: the lock appears whole and exclusively (a hard link, which fails when
+ * the file exists), a lock still being written is waited on rather than read
+ * as stale, and a stale lock (dead pid) or this process's own leftover is only
+ * cleared under the reap mutex — the loser gets a {@link DevLockHeldError}
+ * naming the live holder. 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, port?: number): (() => void) => {
   mkdirSync(outDir, { recursive: true });
-  while (!tryClaimLock(outDir, port)) {
-    // Retry until we win the claim or a live holder makes us throw.
+  const payload = lockPayload(port);
+  while (!createExclusive(lockPath(outDir), payload)) {
+    const state = inspectLock(outDir);
+    if (isClaimable(state)) {
+      reapStaleLock(outDir);
+    } else if (state.kind === "live") {
+      throw new DevLockHeldError(state.lock);
+    } else if (state.kind === "busy") {
+      pause(RETRY_DELAY_MS);
+    }
+    // "absent": the holder released it just now — race for the claim again.
   }
   let released = false;
   return () => {
@@ -199,7 +317,9 @@ export const acquireDevLock = (outDir: string, port?: number): (() => void) => {
  */
 export const updateDevLockPort = (outDir: string, port: number): void => {
   if (ownsLock(outDir)) {
-    writeLock(outDir, port);
+    // Replaced in one step: rewriting in place would leave a moment where a
+    // concurrent claim reads an empty lock.
+    replaceFile(lockPath(outDir), lockPayload(port));
   }
 };
 

package/src/cli/report-format.ts

@@ -11,12 +11,17 @@ export const seconds = (ms: number): string => `${(ms / 1000).toFixed(1)}s`;
 export const money = (cost: number | undefined): string =>
   cost === undefined ? "" : `$${cost.toFixed(2)}`;
 
-/** Milliseconds as `12.3s` under a minute, `4m 12s` from there up. */
+/**
+ * Milliseconds as `12.3s` under a minute, `4m 12s` from there up. Rounding
+ * happens before the split, so a value just under a boundary carries over
+ * (`59_990` → `1m 0s`, `119_700` → `2m 0s`) instead of printing `60.0s` or
+ * `1m 60s`.
+ */
 export const duration = (ms: number): string => {
-  if (ms < 60_000) {
-    return seconds(ms);
+  const tenths = Math.round(ms / 100);
+  if (tenths < 600) {
+    return `${(tenths / 10).toFixed(1)}s`;
   }
-  const minutes = Math.floor(ms / 60_000);
-  const rest = Math.round((ms % 60_000) / 1000);
-  return `${minutes}m ${rest}s`;
+  const total = Math.round(ms / 1000);
+  return `${Math.floor(total / 60)}m ${total % 60}s`;
 };

package/src/components/colors.ts

@@ -49,6 +49,25 @@ export const STROKE = {
   yellow: "border-yellow-500/40 text-yellow-800 dark:text-yellow-300",
 } satisfies Record<Hue, string>;
 
+/**
+ * The theme accent's label color: the accent mixed halfway toward the
+ * foreground. The accent is whatever the site configures (a preset, any CSS
+ * color, or the neutral black/white default), so no fixed shade can promise
+ * the contrast rule above, and the raw accent as text misses it (every preset
+ * sits under 3.5:1 over its tint in light mode). Pulling it toward the
+ * foreground darkens it in light mode and lightens it in dark, since the
+ * foreground contrasts with the page by construction: every preset clears
+ * 7:1 over its 15% tint in both modes.
+ */
+const ACCENT_LABEL =
+  "text-[color-mix(in_oklab,var(--blume-accent)_50%,var(--blume-foreground))]";
+
+/** `TINT` for the theme accent (`<Badge variant="accent">`). */
+export const ACCENT_TINT = `bg-accent/15 ${ACCENT_LABEL}`;
+
+/** `STROKE` for the theme accent. */
+export const ACCENT_STROKE = `border-accent/40 ${ACCENT_LABEL}`;
+
 /** The neutral fallback every table falls through to. */
 export const MUTED = "bg-muted text-muted-foreground";
 

package/src/components/content/Badge.astro

@@ -1,5 +1,5 @@
 ---
-import { STROKE, TINT } from "../colors.ts";
+import { ACCENT_STROKE, ACCENT_TINT, STROKE, TINT } from "../colors.ts";
 import Icon from "../Icon.astro";
 import { badgeColorName } from "./badge-color.ts";
 
@@ -38,10 +38,11 @@ const isDisabled = disabled === true || disabled === "true";
 const colorName = badgeColorName(variant, color);
 const customColor = colorName.startsWith("#") ? colorName : null;
 
-// The hue rows come from the shared table (see colors.ts for the contrast
-// rule); the neutral and surface rows are Badge's own.
+// The hue and theme-accent rows come from the shared table (see colors.ts for
+// the contrast rule); the neutral and surface rows are Badge's own.
 const filledColorClass: Record<string, string> = {
   ...TINT,
+  accent: ACCENT_TINT,
   gray: "bg-muted text-muted-foreground",
   surface: "bg-background text-muted-foreground ring-1 ring-border",
   "surface-destructive":
@@ -53,6 +54,7 @@ const filledColorClass: Record<string, string> = {
 
 const strokeColorClass: Record<string, string> = {
   ...STROKE,
+  accent: ACCENT_STROKE,
   gray: "border-border text-muted-foreground",
   surface: "border-border text-muted-foreground",
   "surface-destructive": "border-red-500/40 text-red-700 dark:text-red-300",

package/src/components/content/Component.astro

@@ -13,7 +13,7 @@ import data from "blume:data";
 import { CODE_PADDING_BLOCK_REM } from "../../theme/code-block-padding.ts";
 
 import { highlightCode } from "../../markdown/index.ts";
-import { withBase } from "../islands/base-path.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 import { contentStrings } from "./content-strings.ts";
 import { EXAMPLE_PANE_MIN_PX } from "./example-pane.ts";
 import Tab from "./Tab.astro";
@@ -35,7 +35,7 @@ const { content: strings } = contentStrings(data, Astro.currentLocale);
 // by their own design system (e.g. shadcn, via the configured `examples.css`).
 // The frame syncs its theme with this document before first paint.
 const previewSrc = entry
-  ? withBase(
+  ? withMountedBase(
       `${examplesBase}/${path.split("/").map(encodeURIComponent).join("/")}`
     )
   : undefined;

package/src/components/content/Tab.astro

@@ -44,7 +44,6 @@ const tabId = id ?? componentSlug(title);
   data-tab-id={tabId}
   data-title={title}
   id={id}
-  role="tabpanel"
 >
   <slot />
   {

package/src/components/content/Tabs.astro

@@ -237,6 +237,10 @@ const { content: strings } = contentStrings(data, Astro.currentLocale);
           }
           trigger.id = `blume-tab-${slug}-${instance}`;
           trigger.setAttribute("aria-controls", panel.id);
+          // The role rides with the labelling tab: adopted panels (CodeGroup
+          // fences, ts2js pairs, nested groups) have none of their own, and
+          // dropdown mode renders no tabs, so its panels take no role.
+          panel.setAttribute("role", "tabpanel");
           panel.setAttribute("aria-labelledby", trigger.id);
           trigger.setAttribute(
             "aria-selected",

package/src/components/content/badge-color.ts

@@ -1,6 +1,9 @@
-/** The named color each documented Badge `variant` paints with. */
+/**
+ * The named color each documented Badge `variant` paints with; `accent` is
+ * the site's theme accent rather than a fixed hue.
+ */
 const VARIANT_COLOR = new Map([
-  ["accent", "blue"],
+  ["accent", "accent"],
   ["danger", "red"],
   ["default", "gray"],
   ["success", "green"],

package/src/components/content/base-href.ts

@@ -1,48 +1,25 @@
 import data from "blume:data";
 
 import {
-  isInternalPath,
   normalizeBasePath,
-  withBasePath,
-  withComposedBasePath,
+  withAuthoredBasePath,
 } from "../../core/base-path.ts";
 import { routeSetFor, servesRoute } from "../../core/locale-links.ts";
 
-// Mirrors `markdown/base-links.ts`: a path whose final segment carries a file
-// extension is a `public/` asset, served at the site root and never moved
-// under `basePath` — unless a page is served there (a dotted route like
-// `/releases/v1.2`).
-const DOTTED_PATH = /\.[a-z0-9]+$/iu;
-
-/** Strip any `#fragment`/`?query` so only the path is extension-tested. */
-const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
-
-/** Whether an internal `href` links a page rather than a public asset. */
-const isPageHref = (href: string): boolean => {
-  const path = pathOf(href);
-  return (
-    !DOTTED_PATH.test(path) ||
-    servesRoute(
-      routeSetFor(data.routes),
-      withBasePath(data.config.basePath, path)
-    )
-  );
-};
-
 /**
  * Rebase a component-emitted `href` the way `markdown/base-links.ts` rebases
  * `[x](/guide)`: a root-relative internal page link gains the composed
- * `deployment.base` + `basePath` prefix, so authors write component links
- * (`<Card href="/guide">`) under the same "as if mounted at root" contract as
- * markdown links. Idempotent per layer (a hand-written `/docs/x` isn't
- * double-prefixed) and inert for external URLs, fragments, relative paths, and
- * asset links.
+ * `deployment.base` + `basePath` prefix, and a public asset (`/spec.pdf`, with
+ * no page served there) the deployment base alone, so authors write component
+ * links (`<Card href="/guide">`) under the same "as if mounted at root"
+ * contract as markdown links (see `withAuthoredBasePath`). Idempotent per
+ * layer (a hand-written `/docs/x` isn't double-prefixed) and inert for
+ * external URLs, fragments, and relative paths.
  */
 export const contentHref = (href: string): string =>
-  isInternalPath(href) && isPageHref(href)
-    ? withComposedBasePath(
-        normalizeBasePath(import.meta.env.BASE_URL),
-        data.config.basePath,
-        href
-      )
-    : href;
+  withAuthoredBasePath(
+    normalizeBasePath(import.meta.env.BASE_URL),
+    data.config.basePath,
+    href,
+    (route) => servesRoute(routeSetFor(data.routes), route)
+  );

package/src/components/islands/assistant.tsx

@@ -6,7 +6,7 @@ import { createPortal } from "react-dom";
 
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import { copyText } from "../copy-feedback.ts";
-import { joinBase, prefixBase } from "./base-path.ts";
+import { joinBase, mountBase } from "./base-path.ts";
 import { useAssistant } from "./hooks.ts";
 
 /** A resolved empty-state prompt; `icon` is ready-to-inline SVG (or null). */
@@ -65,11 +65,12 @@ const markdown = new Marked({
   breaks: true,
   gfm: true,
   // The model cites pages as base-less logical routes (`[Title](/route)`); rewrite
-  // link targets to served URLs so citations resolve under `deployment.base`.
-  // `prefixBase` leaves external URLs and fragments untouched and is idempotent.
+  // link targets to served URLs so citations resolve under `deployment.base`,
+  // even a route that starts with the base's own name. `mountBase` leaves
+  // external URLs and fragments untouched.
   walkTokens: (token) => {
     if (token.type === "link") {
-      token.href = prefixBase(import.meta.env.BASE_URL, token.href);
+      token.href = mountBase(import.meta.env.BASE_URL, token.href);
     }
   },
 });
@@ -262,6 +263,22 @@ const Assistant = ({
     };
   }, [open]);
 
+  // Stamp the incoming body before the swap installs it, as the theme and
+  // banner scripts do for <html>. Stamped only after the swap (below, in a
+  // passive effect), the new body would first paint without the push padding,
+  // replaying its transition on every navigation with the panel docked.
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const onBeforeSwap = (event: DocumentEventMap["astro:before-swap"]) => {
+      event.newDocument.body.dataset.blumeAssistant = "open";
+    };
+    document.addEventListener("astro:before-swap", onBeforeSwap);
+    return () =>
+      document.removeEventListener("astro:before-swap", onBeforeSwap);
+  }, [open]);
+
   // Re-stamp the push attribute after a swap while the panel is open — the new
   // body arrives without it. Deliberately separate from the effect above: a
   // navigation must not re-run the focus handling and yank focus out of the