@writedocs/generator 0.7.0 → 0.7.2

package/bin/writedocs.js

@@ -9,6 +9,7 @@ import { runBuild } from '../src/cli/build.js';
 import { runInit } from '../src/cli/init.js';
 import { requireBuildKey } from '../src/cli/build-auth.js';
 import { log, step, plural, color, CliExit, errorText, stopActiveStep } from '../src/cli/output.js';
+import { startUpdateCheck, showUpdateNotice } from '../src/cli/update-check.js';
 // O MESMO modulo que o build usa (via loadDocsConfig, que reexporta daqui) e
 // que a plataforma importa por `@writedocs/generator/config-schema` - e o que
 // faz os tres reportarem os mesmos problemas com as mesmas palavras, em vez de
@@ -37,13 +38,18 @@ const packageRoot = path.resolve(__dirname, '..');
 // package.json). `writedocs --version` should always reflect what actually
 // got published, not whatever this string happened to say at the time this
 // line was last hand-edited.
-const { version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+const { name: packageName, version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
 
 const program = new Command();
 program
   .name('writedocs')
   .description('Static site generator for writedocs.json + MDX')
-  .version(version);
+  .version(version)
+  // Every command checks for a newer writedocs (from a cache - see
+  // src/cli/update-check.js); the notice prints after the command's output.
+  .hook('preAction', (_program, command) => {
+    startUpdateCheck({ command: command.name(), name: packageName, version, packageRoot });
+  });
 
 program
   .command('dev')
@@ -265,6 +271,14 @@ program
     });
   });
 
+program
+  .command('update')
+  .description('Update writedocs to the latest version')
+  .action(async () => {
+    const { runUpdate } = await import('../src/cli/update.js');
+    await runUpdate({ name: packageName, version, packageRoot });
+  });
+
 program
   .command('init')
   .description('Scaffold a writedocs.json and starter docs/ folder')
@@ -273,10 +287,13 @@ program
     await runInit({ targetDir: path.resolve(process.cwd(), dir) });
   });
 
-program.parseAsync(process.argv).catch((err) => {
-  // A command that already printed its own error throws CliExit.
-  stopActiveStep();
-  if (err instanceof CliExit) process.exit(err.code);
-  log.error(errorText(err));
-  process.exit(1);
-});
+program
+  .parseAsync(process.argv)
+  .then(showUpdateNotice)
+  .catch((err) => {
+    stopActiveStep();
+    // A command that already printed its own error throws CliExit.
+    if (!(err instanceof CliExit)) log.error(errorText(err));
+    showUpdateNotice();
+    process.exit(err instanceof CliExit ? err.code : 1);
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/cli/dev.js

@@ -5,6 +5,7 @@ import { log, step, duration, formatProblems, color, CliExit } from './output.js
 import { describeError, requestLog, authorWarning, verboseLine, stripAnsi } from './astro-output.js';
 import { reportApiPages } from './api-pages-output.js';
 import { runningPreview, writeLock, removeLock } from './dev-lock.js';
+import { showUpdateNotice } from './update-check.js';
 
 // The same problem tends to arrive more than once in a row - Vite and
 // Astro each log a failed page, and a page compiles for more than one
@@ -96,6 +97,9 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
           log.line();
           log.line(color.dim('  Edit any page and the preview updates. Press Ctrl+C to stop.'));
           log.line();
+          // `dev` runs until Ctrl+C - the notice goes under the ready screen,
+          // not after the command like everywhere else.
+          showUpdateNotice();
           return;
         }
         case 'fatal':

package/src/cli/update-check-refresh.js

@@ -0,0 +1,18 @@
+// Detached background process started by update-check.js: asks the npm
+// registry for the latest version of package `process.argv[2]` and caches
+// the answer for the next writedocs run. Prints nothing. A failure (offline,
+// registry down) keeps the last known version but still records the
+// attempt, so it's retried the next day, not on every command.
+import { fetchLatestVersion, readCache, writeCache } from './update-check.js';
+
+const name = process.argv[2];
+let latest = null;
+try {
+  latest = await fetchLatestVersion(name);
+} catch {
+  const previous = readCache();
+  latest = previous?.name === name ? previous.latest : null;
+}
+try {
+  writeCache({ name, latest, checkedAt: Date.now() });
+} catch {}

package/src/cli/update-check.js

@@ -0,0 +1,104 @@
+// "A newer writedocs is available" - shown after any command's output.
+//
+// Never slows a command down: the notice comes from a cached answer, and
+// when that's more than a day old, a detached background process
+// (update-check-refresh.js) asks the npm registry again and rewrites the
+// cache for the next run - the same approach as npm's own update notifier.
+//
+// Not shown for `build` (the WriteDocs platform runs it, not a person) or
+// `update` itself, in CI, when output isn't a terminal, when writedocs runs
+// from a source checkout (updated with git, not npm), or with
+// WRITEDOCS_NO_UPDATE_CHECK set.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { log, color } from './output.js';
+
+const DAY = 24 * 60 * 60 * 1000;
+const SILENT_COMMANDS = new Set(['build', 'update']);
+
+export function cacheFile() {
+  const base =
+    process.env.XDG_CACHE_HOME ||
+    (process.platform === 'win32' ? process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local') : path.join(os.homedir(), '.cache'));
+  return path.join(base, 'writedocs', 'update-check.json');
+}
+
+export function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeCache(data) {
+  const file = cacheFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data));
+}
+
+/** The registry the user's npm uses, or npm's own. */
+export function registryUrl() {
+  const configured = process.env.npm_config_registry || process.env.NPM_CONFIG_REGISTRY;
+  return (configured || 'https://registry.npmjs.org').replace(/\/+$/, '');
+}
+
+/** The version npm's `latest` tag points at. Throws on a network error. */
+export async function fetchLatestVersion(name, { timeoutMs = 5000 } = {}) {
+  const res = await fetch(`${registryUrl()}/-/package/${name.replace('/', '%2f')}/dist-tags`, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok) throw new Error(`the registry answered ${res.status}`);
+  const tags = await res.json();
+  if (typeof tags?.latest !== 'string') throw new Error('the registry has no "latest" version');
+  return tags.latest;
+}
+
+/** Whether `latest` is a newer release than `current` - x.y.z only; a
+ *  prerelease never counts as newer. */
+export function isNewer(latest, current) {
+  const parse = (v) => /^(\d+)\.(\d+)\.(\d+)$/.exec(String(v).trim())?.slice(1).map(Number);
+  const a = parse(latest);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] > b[i];
+  return false;
+}
+
+export function isSourceCheckout(packageRoot) {
+  return fs.existsSync(path.join(packageRoot, '.git'));
+}
+
+function enabled(command, packageRoot) {
+  if (SILENT_COMMANDS.has(command)) return false;
+  if (process.env.WRITEDOCS_NO_UPDATE_CHECK || process.env.CI) return false;
+  if (!process.stdout.isTTY) return false;
+  return !isSourceCheckout(packageRoot);
+}
+
+let state = null;
+
+/** Called once at startup: loads the cached answer, and refreshes it in the
+ *  background when it's old. */
+export function startUpdateCheck({ command, name, version, packageRoot }) {
+  if (!enabled(command, packageRoot)) return;
+  const cache = readCache();
+  state = { name, version, latest: cache?.name === name ? cache.latest : null, shown: false };
+  if (cache?.name === name && Date.now() - (cache.checkedAt ?? 0) < DAY) return;
+  try {
+    const worker = path.join(path.dirname(fileURLToPath(import.meta.url)), 'update-check-refresh.js');
+    const child = spawn(process.execPath, [worker, name], { detached: true, stdio: 'ignore', windowsHide: true });
+    child.unref();
+  } catch {
+    // No notice this time - not worth failing a command over.
+  }
+}
+
+/** Prints the notice, if there's a newer version - once per run. */
+export function showUpdateNotice() {
+  if (!state || state.shown || !state.latest || !isNewer(state.latest, state.version)) return;
+  state.shown = true;
+  log.line();
+  log.info(`writedocs ${color.bold(state.latest)} is available ${color.dim(`(you have ${state.version})`)}. Run ${color.cyan('writedocs update')} to update.`);
+}

package/src/cli/update.js

@@ -0,0 +1,107 @@
+// `writedocs update` - installs the latest writedocs, the same way the running
+// one was installed: globally with npm (the documented way), as a project
+// dependency (npm, pnpm or yarn, by the project's lockfile), or globally
+// with pnpm or yarn. npx and a source checkout get an explanation instead.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { log, step, color, CliExit } from './output.js';
+import { fetchLatestVersion, isNewer, isSourceCheckout, writeCache } from './update-check.js';
+
+/** Runs a command, capturing its output. Resolves { code, output }. */
+function run(command, args, cwd) {
+  return new Promise((resolve) => {
+    // npm/pnpm/yarn are .cmd scripts on Windows, which spawn() only runs
+    // through a shell - given as one string there (Node deprecates an
+    // argument list with `shell`). The arguments are fixed: flags and the
+    // package name, never user input.
+    const options = { cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true };
+    const child = process.platform === 'win32' ? spawn([command, ...args].join(' '), { ...options, shell: true }) : spawn(command, args, options);
+    let output = '';
+    child.stdout.on('data', (d) => (output += d));
+    child.stderr.on('data', (d) => (output += d));
+    child.on('error', (err) => resolve({ code: 1, output: err.message }));
+    child.on('close', (code) => resolve({ code: code ?? 1, output }));
+  });
+}
+
+/** How the running writedocs was installed:
+ *  { kind: 'checkout' | 'npx' | 'unknown' } or
+ *  { kind: 'global' | 'local', command, args, cwd }. */
+export async function installation(packageRoot, name) {
+  if (isSourceCheckout(packageRoot)) return { kind: 'checkout' };
+  const posix = packageRoot.split(path.sep).join('/');
+  if (/\/_npx\//.test(posix)) return { kind: 'npx' };
+  if (/\/pnpm\/global\//.test(posix)) return { kind: 'global', command: 'pnpm', args: ['add', '-g', `${name}@latest`] };
+  if (/\/yarn\/global\//.test(posix)) return { kind: 'global', command: 'yarn', args: ['global', 'add', `${name}@latest`] };
+  const at = posix.lastIndexOf(`/node_modules/${name}`);
+  if (at === -1) return { kind: 'unknown' };
+  const container = posix.slice(0, at);
+  const npmRoot = await run('npm', ['root', '-g']);
+  const globalRoot = npmRoot.code === 0 ? npmRoot.output.trim().split(/\r?\n/).pop() : null;
+  if (globalRoot && path.resolve(globalRoot) === path.resolve(`${container}/node_modules`)) {
+    return { kind: 'global', command: 'npm', args: ['install', '-g', `${name}@latest`] };
+  }
+  const cwd = path.resolve(container);
+  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return { kind: 'local', command: 'pnpm', args: ['add', `${name}@latest`], cwd };
+  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return { kind: 'local', command: 'yarn', args: ['add', `${name}@latest`], cwd };
+  return { kind: 'local', command: 'npm', args: ['install', `${name}@latest`], cwd };
+}
+
+export async function runUpdate({ name, version, packageRoot }) {
+  const checking = step('Checking for a new version');
+  let latest;
+  try {
+    latest = await fetchLatestVersion(name, { timeoutMs: 15000 });
+  } catch (err) {
+    checking.fail("Couldn't check for a new version");
+    log.detail(color.dim(`${err.message}. Check your connection, and try again.`));
+    throw new CliExit(1);
+  }
+  checking.stop();
+  try {
+    writeCache({ name, latest, checkedAt: Date.now() });
+  } catch {}
+  if (!isNewer(latest, version)) {
+    log.success(`writedocs is up to date ${color.dim(`(${version})`)}`);
+    return;
+  }
+
+  const install = await installation(packageRoot, name);
+  if (install.kind === 'checkout') {
+    log.info(`writedocs ${latest} is available, but this one runs from a source checkout (${packageRoot}).`);
+    log.detail(color.dim('Update it with git - `writedocs update` only updates installed copies.'));
+    return;
+  }
+  if (install.kind === 'npx') {
+    log.info(`writedocs ${latest} is available. You're running writedocs through npx - to use the latest, run:`);
+    log.detail(color.cyan(`npx ${name}@latest <command>`));
+    log.detail(color.dim(`Or install it once, and use \`writedocs\` directly: npm install -g ${name}`));
+    return;
+  }
+  if (install.kind === 'unknown') {
+    log.info(`writedocs ${latest} is available. Update it the way you installed it - for example:`);
+    log.detail(color.cyan(`npm install -g ${name}@latest`));
+    return;
+  }
+
+  const shown = `${install.command} ${install.args.join(' ')}`;
+  const updating = step(`Updating writedocs ${version} → ${latest} ${color.dim(`(${shown}${install.cwd ? ` in ${install.cwd}` : ''})`)}`);
+  const result = await run(install.command, install.args, install.cwd);
+  if (result.code !== 0) {
+    updating.fail(`Couldn't update writedocs - \`${shown}\` failed`);
+    const tail = result.output.trim().split(/\r?\n/).slice(-12).join('\n');
+    if (tail) {
+      log.line();
+      log.line(color.dim(tail));
+    }
+    if (/EACCES|permission denied/i.test(result.output)) {
+      log.line();
+      log.detail(
+        `npm needs permission to write to its global folder. Run ${color.cyan(`sudo ${shown}`)}, or set npm up to install without sudo: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally`
+      );
+    }
+    throw new CliExit(1);
+  }
+  updating.succeed(`Updated writedocs ${version} → ${color.bold(latest)}`);
+}

package/src/layout/BaseLayout.astro

@@ -220,19 +220,9 @@ const darkNavbarFgMuted = darkNavbarConfigured
 // design choice, unlike text color above), falling back to the sitewide
 // --wd-primary (today's exact behavior) when unset - a site that sets a
 // navbar background but no accent keeps its ordinary brand-colored
-// active-tab fill exactly as before.
+// active-tab underline.
 const lightNavbarAccent = navLight.accent ?? lightPrimary;
 const darkNavbarAccent = navDark.accent ?? darkPrimary;
-// --wd-navbar-accent-text: the active tab's own text color, painted on top
-// of --wd-navbar-accent above. Hardcoded to white before this feature
-// existed, which only ever looked right because every accent color in
-// practice (always --wd-primary until now) happened to be dark/saturated
-// enough for white text - contrastTextColor() (lib/config.ts) picks
-// black or white by actual luminance instead, so a light `accent` (e.g.
-// a pale one against a dark navbar) still gets legible active-tab text
-// rather than assuming white always works.
-const lightNavbarAccentText = contrastTextColor(lightNavbarAccent);
-const darkNavbarAccentText = contrastTextColor(darkNavbarAccent);
 // --wd-navbar-border: the switcher pills' (version/language/product) own
 // border. Never the flat --wd-border (a fixed neutral gray/slate tuned for
 // sitting on the page background) once navbar is configured - that reads
@@ -249,6 +239,14 @@ const lightNavbarBorder = lightNavbarConfigured
 const darkNavbarBorder = darkNavbarConfigured
   ? `color-mix(in srgb, ${darkNavbarFg} 25%, transparent)`
   : 'var(--wd-border)';
+// --wd-navbar-hover: a topbar tab's background on hover. On a navbar with
+// the page's own background, the sidebar's hover tint (NavTree.astro) -
+// the same 6% of --wd-primary. A configured navbar can *be* the primary
+// color, where that tint would vanish, so there it's a light tint of the
+// navbar's own contrast-correct text color instead, like --wd-navbar-border.
+const sidebarHover = 'color-mix(in srgb, var(--wd-primary) 6%, transparent)';
+const lightNavbarHover = lightNavbarConfigured ? `color-mix(in srgb, ${lightNavbarFg} 12%, transparent)` : sidebarHover;
+const darkNavbarHover = darkNavbarConfigured ? `color-mix(in srgb, ${darkNavbarFg} 12%, transparent)` : sidebarHover;
 // The <body> canvas's own paint - same color as --wd-background above
 // (there's only one background color to configure now), plus an optional
 // image layered on top. `images.light`/`.dark` are plain public/-relative
@@ -517,8 +515,8 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
         wdNavbarFgLight: lightNavbarFg,
         wdNavbarFgMutedLight: lightNavbarFgMuted,
         wdNavbarAccentLight: lightNavbarAccent,
-        wdNavbarAccentTextLight: lightNavbarAccentText,
         wdNavbarBorderLight: lightNavbarBorder,
+        wdNavbarHoverLight: lightNavbarHover,
         wdPageBgColorLight: lightPageBgColor,
         wdPageBgImageLight: lightPageBgImage,
         wdFontFamily,
@@ -531,8 +529,8 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
         wdNavbarFgDark: darkNavbarFg,
         wdNavbarFgMutedDark: darkNavbarFgMuted,
         wdNavbarAccentDark: darkNavbarAccent,
-        wdNavbarAccentTextDark: darkNavbarAccentText,
         wdNavbarBorderDark: darkNavbarBorder,
+        wdNavbarHoverDark: darkNavbarHover,
         wdPageBgColorDark: darkPageBgColor,
         wdPageBgImageDark: darkPageBgImage,
       }}
@@ -545,8 +543,8 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
         --wd-navbar-foreground: var(--wdNavbarFgLight);
         --wd-navbar-foreground-muted: var(--wdNavbarFgMutedLight);
         --wd-navbar-accent: var(--wdNavbarAccentLight);
-        --wd-navbar-accent-text: var(--wdNavbarAccentTextLight);
         --wd-navbar-border: var(--wdNavbarBorderLight);
+        --wd-navbar-hover: var(--wdNavbarHoverLight);
         --wd-page-bg-color: var(--wdPageBgColorLight);
         --wd-page-bg-image: var(--wdPageBgImageLight);
         --wd-text-muted: #64748b;
@@ -572,8 +570,8 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
         --wd-navbar-foreground: var(--wdNavbarFgDark);
         --wd-navbar-foreground-muted: var(--wdNavbarFgMutedDark);
         --wd-navbar-accent: var(--wdNavbarAccentDark);
-        --wd-navbar-accent-text: var(--wdNavbarAccentTextDark);
         --wd-navbar-border: var(--wdNavbarBorderDark);
+        --wd-navbar-hover: var(--wdNavbarHoverDark);
         --wd-page-bg-color: var(--wdPageBgColorDark);
         --wd-page-bg-image: var(--wdPageBgImageDark);
         --wd-text-muted: #94a3b8;

package/src/layout/styles/topbar.css

@@ -37,9 +37,8 @@
      (below) sits flush against this row's bottom edge (the outer
      .wd-topbar's own border-bottom, since this is the last row) rather
      than floating partway up inside a padded gap. That's what lets a
-     plain border-bottom color change read as a real underline on hover,
-     and what makes the active tab's own fill look like it's actually
-     attached to the row's bottom edge instead of a floating pill. */
+     plain border-bottom color change read as a real underline under the
+     active tab. */
   padding-bottom: 0;
 }
 .wd-topbar-brand {
@@ -139,47 +138,31 @@
   /* Rounded top corners, square bottom - reads as an actual "tab"
      attached to the row's bottom edge (see .wd-topbar-row-tabs
      .wd-topbar-inner's own comment) rather than a floating pill. Same
-     radius for every tab, active or not, so nothing needs to change
-     shape on top when a tab becomes active - only the fill/border-bottom
-     below do. */
+     radius for every tab, active or not - it also shapes the hover
+     background (below). */
   border-radius: 0.5rem 0.5rem 0 0;
-  /* Transparent by default - this is what a hover (below) or the active
-     state colors in, rather than a separate underline element. Sized to
-     land exactly on the row's own bottom edge now that this row's inner
-     wrapper has no bottom padding of its own. */
+  /* Transparent by default - the active state (below) colors it in,
+     rather than a separate underline element. Sized to land exactly on the
+     row's own bottom edge now that this row's inner wrapper has no bottom
+     padding of its own. */
   border-bottom: 2px solid transparent;
   text-decoration: none;
   color: var(--wd-navbar-foreground);
   font-size: 0.92rem;
   font-weight: 600;
 }
-/* The selected tab: a solid fill, not just a tinted background -
-   AppIcon's <svg> render mode already uses fill="currentColor" (astro-
-   icon's default), so its icon recolors along with the text; the
-   emoji/text <span> fallback inherits `color` the same way.
-   border-bottom-color matches the fill (rather than being reset to
-   transparent) so there's no 2px seam of the row's own background
-   showing between the fill and the row's bottom edge/border.
-   --wd-navbar-accent (falls back to --wd-primary - see BaseLayout.astro),
-   not a bare --wd-primary reference: without this, a site whose navbar
-   background *is* --wd-primary (a plausible "brand-colored navbar" choice
-   - the exact case that motivated this variable) would have its active
-   tab's own fill disappear into the row's background entirely. Text color
-   is --wd-navbar-accent-text (also BaseLayout.astro) rather than a
-   hardcoded #fff for the matching reason - a light accent color needs
-   dark text, not white, to stay legible on top of it. */
+/* The selected tab: just its border-bottom, in --wd-navbar-accent (falls
+   back to --wd-primary - see BaseLayout.astro), landing on the row's
+   bottom edge as an underline. No fill - the text keeps the navbar's own
+   color. */
 .wd-tab-link.active {
-  color: var(--wd-navbar-accent-text);
-  background: var(--wd-navbar-accent);
   border-bottom-color: var(--wd-navbar-accent);
 }
-/* Inactive tabs just get their border-bottom colored in on hover -
-   simpler than a separate underline element, and lines up naturally
-   with the active tab's own border-bottom above since both are the same
-   property. Text/icon color deliberately stays as-is on hover (only the
-   border appears), matching the reference this was built against. */
-.wd-tab-link:hover:not(.active) {
-  border-bottom-color: var(--wd-navbar-accent);
+/* Any tab on hover: a light background tint, the same as a sidebar item's
+   hover (see --wd-navbar-hover in BaseLayout.astro). The rounded top
+   corners above shape it. */
+.wd-tab-link:hover {
+  background: var(--wd-navbar-hover);
 }
 .wd-topbar-links {
   display: flex;

package/src/lib/config-schema.js

@@ -158,7 +158,7 @@ const stylesSchema = z.object({
   // Each side (`light`/`dark`) is either a bare string - just the
   // background color, exactly the original shape, kept for backwards
   // compatibility - or `{ background, accent? }`, for when a site also
-  // wants the navbar's own active-tab-fill/hover-underline color to
+  // wants the navbar's own active-tab underline color to
   // differ from the sitewide `styles.colors.primary` (`accent`'s only
   // job - see BaseLayout.astro's lightNavbarAccent). Deliberately no
   // text/icon color field here at all: BaseLayout.astro always resolves

package/src/lib/config-schema.ts

@@ -263,7 +263,7 @@ const logoSchema = z.union([
 // field's comment for what it now covers.
 // One side of `styles.navbar` (light or dark) - either a bare background
 // color (the original shape) or `{ background, accent? }` once a site
-// wants its own accent color (the active-tab fill / hover underline)
+// wants its own accent color (the active tab's underline)
 // inside the navbar specifically, independent of the sitewide
 // `styles.colors.primary`. Deliberately does NOT carry a text/icon color
 // field at all - see `navbar`'s own comment below (stylesSchema) for why
@@ -400,7 +400,7 @@ const stylesSchema = z
     // Each side (`light`/`dark`) is either a bare string - just the
     // background color, exactly the original shape, kept for backwards
     // compatibility - or `{ background, accent? }`, for when a site also
-    // wants the navbar's own active-tab-fill/hover-underline color to
+    // wants the navbar's own active-tab underline color to
     // differ from the sitewide `styles.colors.primary` (`accent`'s only
     // job - see BaseLayout.astro's lightNavbarAccent). Deliberately no
     // text/icon color field here at all: BaseLayout.astro always resolves

package/src/lib/json-schema-descriptions.js

@@ -111,10 +111,10 @@ export const DESCRIPTIONS = {
   'styles.navbar': 'The topbar\'s own background. Without it, the topbar matches the page background. Its text turns black or white automatically.',
   'styles.navbar.light': 'Topbar in light mode: a background color, or `{ background, accent }`.',
   'styles.navbar.light.background': 'Topbar background color in light mode.',
-  'styles.navbar.light.accent': 'Color of the active tab and hover states in the topbar, in place of `styles.colors.primary`.',
+  'styles.navbar.light.accent': 'Color of the underline under the active tab in the topbar, in place of `styles.colors.primary`.',
   'styles.navbar.dark': 'Topbar in dark mode: a background color, or `{ background, accent }`.',
   'styles.navbar.dark.background': 'Topbar background color in dark mode.',
-  'styles.navbar.dark.accent': 'Color of the active tab and hover states in the topbar, in dark mode.',
+  'styles.navbar.dark.accent': 'Color of the underline under the active tab in the topbar, in dark mode.',
   'styles.background': 'Background color of the site, and an optional background image.',
   'styles.background.colors': 'Background colors.',
   'styles.background.colors.light': 'Background color in light mode. Default "#ffffff".',

package/writedocs.schema.json

@@ -252,8 +252,8 @@
                     },
                     "accent": {
                       "type": "string",
-                      "description": "Color of the active tab and hover states in the topbar, in place of `styles.colors.primary`.",
-                      "markdownDescription": "Color of the active tab and hover states in the topbar, in place of `styles.colors.primary`."
+                      "description": "Color of the underline under the active tab in the topbar, in place of `styles.colors.primary`.",
+                      "markdownDescription": "Color of the underline under the active tab in the topbar, in place of `styles.colors.primary`."
                     }
                   },
                   "required": [
@@ -280,8 +280,8 @@
                     },
                     "accent": {
                       "type": "string",
-                      "description": "Color of the active tab and hover states in the topbar, in dark mode.",
-                      "markdownDescription": "Color of the active tab and hover states in the topbar, in dark mode."
+                      "description": "Color of the underline under the active tab in the topbar, in dark mode.",
+                      "markdownDescription": "Color of the underline under the active tab in the topbar, in dark mode."
                     }
                   },
                   "required": [