@writedocs/generator 0.7.2 → 0.7.3

package/src/layout/BaseLayout.astro

@@ -116,6 +116,9 @@ interface Props {
   // renders nothing, so this component only needs to know whether to
   // render the *column wrapper divs* at all).
   mode?: 'default' | 'wide' | 'frame' | 'custom' | 'blank';
+  // The page's language, for <html lang> - the `language` of the
+  // navigation level it belongs to (see [...slug].astro), or 'en'.
+  lang?: string;
 }
 const {
   config,
@@ -126,6 +129,7 @@ const {
   selectors = [],
   globalDropdowns = [],
   mode = 'default',
+  lang = 'en',
 } = Astro.props as Props;
 const showSidebarCol = mode === 'default' || mode === 'wide';
 const showTocCol = mode === 'default';
@@ -158,6 +162,13 @@ const lightPrimary = config.styles.colors.primary;
 const lightText = config.styles.colors.text ?? '#0f172a';
 const darkPrimary = config.styles.colors.dark?.primary ?? lightPrimary;
 const darkText = config.styles.colors.dark?.text ?? '#e2e8f0';
+// Text drawn on the primary color (step numbers, the info banner, the API
+// playground's buttons) - white, or black on a clearly light primary
+// (contrastTextColor(), lib/config.ts). It used to be white everywhere,
+// unreadable on a light primary - and a light dark-mode primary is exactly
+// what dark-mode links need.
+const lightOnPrimary = contrastTextColor(lightPrimary);
+const darkOnPrimary = contrastTextColor(darkPrimary);
 // styles.background.colors is now the single source for any background
 // color - both the flat --wd-background surface (dropdowns/modals/kbd
 // chips/footer/topbar-fallback/etc., every other `var(--wd-background)`
@@ -309,7 +320,7 @@ const footerLogoDark = footerLogoConfig
 // Zero-config custom CSS/JS - any `.css`/`.js` file anywhere in the
 // project (root, `docs/`, `snippets/`, `public/`, any subfolder -
 // `dist/`/`node_modules/`/etc. excluded, see findRootAssets() in
-// lib/config.ts) is auto-loaded on every page, no writedocs.json entry
+// lib/pages.js) is auto-loaded on every page, no writedocs.json entry
 // needed. Read fresh on every render (not cached at module scope) so an
 // edit to one of these files shows up on the next `writedocs dev` page
 // load without a server restart - same freshness `loadDocsConfig(contentDir)`
@@ -400,7 +411,7 @@ const fontWeightCss = [
 const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
 ---
 <!doctype html>
-<html lang="en">
+<html lang={lang}>
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@@ -509,6 +520,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
     <style
       define:vars={{
         wdPrimaryLight: lightPrimary,
+        wdOnPrimaryLight: lightOnPrimary,
         wdBackgroundLight: lightBackground,
         wdTextLight: lightText,
         wdNavbarLight: lightNavbarBg,
@@ -523,6 +535,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
         wdFontFamilyHeading,
         wdFontFamilyBody,
         wdPrimaryDark: darkPrimary,
+        wdOnPrimaryDark: darkOnPrimary,
         wdBackgroundDark: darkBackground,
         wdTextDark: darkText,
         wdNavbarDark: darkNavbarBg,
@@ -537,6 +550,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
     >
       :root {
         --wd-primary: var(--wdPrimaryLight);
+        --wd-on-primary: var(--wdOnPrimaryLight);
         --wd-background: var(--wdBackgroundLight);
         --wd-text: var(--wdTextLight);
         --wd-navbar-background: var(--wdNavbarLight);
@@ -564,6 +578,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
          (src/scripts/theme-toggle.ts). */
       :root[data-theme='dark'] {
         --wd-primary: var(--wdPrimaryDark);
+        --wd-on-primary: var(--wdOnPrimaryDark);
         --wd-background: var(--wdBackgroundDark);
         --wd-text: var(--wdTextDark);
         --wd-navbar-background: var(--wdNavbarDark);
@@ -603,7 +618,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
     {config.scripts.head.map((s) =>
       s.src ? <script is:inline src={s.src} /> : <script is:inline set:html={s.content} />
     )}
-    {/* Zero-config custom CSS - see findRootAssets() in lib/config.ts and
+    {/* Zero-config custom CSS - see findRootAssets() in lib/pages.js and
         rootCssContents above. Rendered last in <head>, so a project-owned
         file - anywhere in the project, not just the root - wins over
         everything else writedocs generates itself. Inlined as raw <style>
@@ -617,7 +632,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
       <style is:inline set:html={content} />
     ))}
     {/* Zero-config custom CSS living in public/ - see findRootAssets()'s
-        own comment in lib/config.ts for why these render as <link> tags
+        own comment in lib/pages.js for why these render as <link> tags
         pointing at their already-public URL instead of joining
         rootCssContents above as inlined content. */}
     {publicCssHrefs.map((href) => (
@@ -712,7 +727,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
     {config.scripts.body.map((s) =>
       s.src ? <script is:inline src={s.src} /> : <script is:inline set:html={s.content} />
     )}
-    {/* Zero-config custom JS - see findRootAssets() in lib/config.ts and
+    {/* Zero-config custom JS - see findRootAssets() in lib/pages.js and
         rootJsContents above. Rendered last, after writedocs.json's own
         `scripts.body`, same "most locally-owned override runs last"
         reasoning as the root CSS above. `is:inline` here isn't optional -
@@ -725,7 +740,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
       <script is:inline set:html={content} />
     ))}
     {/* Zero-config custom JS living in public/ - see this file's own CSS
-        equivalent above and findRootAssets()'s comment in lib/config.ts.
+        equivalent above and findRootAssets()'s comment in lib/pages.js.
         `<script src>`, not `is:inline set:html` - the file's already a
         fetchable URL, no reason to inline its content. Filtered against
         config.scripts.head's own `src` entries (publicJsHrefs) for the

package/src/layout/styles/banner.css

@@ -15,7 +15,7 @@
 .wd-banner {
   width: 100%;
 }
-.wd-banner-info { background: var(--wd-primary); color: #fff; }
+.wd-banner-info { background: var(--wd-primary); color: var(--wd-on-primary); }
 .wd-banner-warning { background: #b45309; color: #fff; }
 .wd-banner-critical { background: #b91c1c; color: #fff; }
 .wd-banner-inner {

package/src/lib/a11y-check.js

@@ -5,8 +5,8 @@
 //
 //   - contrast (WCAG 2 AA, 4.5:1 for text) of the colors writedocs.json sets:
 //     links (styles.colors.primary) on the light and dark backgrounds, body
-//     text (styles.colors.text) on them, white text on primary (step
-//     numbers, the info banner), and the navbar's text on its own color.
+//     text (styles.colors.text) on them, text on primary (step numbers, the
+//     info banner), and the navbar's text on its own color.
 //     Only colors the project sets are checked - writedocs' own defaults
 //     aren't something the author wrote.
 //   - images without alt text: a Markdown image with empty alt, an
@@ -27,6 +27,7 @@ import matter from 'gray-matter';
 import { visit } from 'unist-util-visit';
 import { findAllPages } from './pages.js';
 import { createJsonLocator } from './config-schema.js';
+import { contrastRatio, readableTextOn } from './color.js';
 
 const processors = {};
 async function parse(text, format) {
@@ -44,38 +45,9 @@ const DEFAULT_BACKGROUND = { light: '#ffffff', dark: '#0b1120' };
 const DEFAULT_TEXT = { light: '#0f172a', dark: '#e2e8f0' };
 const MIN_TEXT_CONTRAST = 4.5;
 
-function parseHex(value) {
-  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(value ?? '').trim());
-  if (!m) return null;
-  const hex = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1];
-  return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16));
-}
-
-function luminance(rgb) {
-  const [r, g, b] = rgb.map((v) => {
-    const c = v / 255;
-    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
-  });
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-
-/** WCAG contrast ratio of two hex colors, or null when either isn't hex. */
-export function contrastRatio(a, b) {
-  const x = parseHex(a);
-  const y = parseHex(b);
-  if (!x || !y) return null;
-  const [hi, lo] = [luminance(x), luminance(y)].sort((p, q) => q - p);
-  return (hi + 0.05) / (lo + 0.05);
-}
-
-/** Black or white - the same rule BaseLayout.astro uses for text on a
- *  configured navbar color (contrastTextColor() in lib/config.ts). */
-function navbarTextFor(hex) {
-  const rgb = parseHex(hex);
-  if (!rgb) return '#ffffff';
-  const [r, g, b] = rgb;
-  return (299 * r + 587 * g + 114 * b) / 1000 > 150 ? '#000000' : '#ffffff';
-}
+// contrastRatio() is re-exported: it was defined here, and tests import it
+// from this module.
+export { contrastRatio };
 
 function checkColors(config, locate) {
   const issues = [];
@@ -127,32 +99,37 @@ function checkColors(config, locate) {
     }
   }
 
-  // White text on the primary color (step numbers, the info banner).
+  // Text drawn on the primary color (step numbers, the info banner, the API
+  // playground's buttons) - the color the theme picks (readableTextOn() in
+  // lib/color.js): white, unless white falls below 3:1 and black takes over.
+  // So white between 3:1 and 4.5:1 - most mid-tone brand colors - is the
+  // one case left to report.
   const primaries = [...new Set([colors.primary, colors.dark?.primary].filter(Boolean))];
   for (const color of primaries) {
-    const r = low('#ffffff', color);
+    const fg = readableTextOn(color);
+    const r = low(fg, color);
     if (r) {
       push(
         color === colors.primary ? at('colors', 'primary') : at('colors', 'dark', 'primary'),
-        `White text on the primary color ${color} (step numbers, the info banner) has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
-        'Use a darker primary color.'
+        `${fg === '#ffffff' ? 'White' : 'Black'} text on the primary color ${color} (step numbers, the info banner) has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
+        'Use a darker primary color - or a much lighter one, which gets black text.'
       );
     }
   }
 
-  // The navbar's text on its own color - black or white, picked by a rough
-  // brightness rule that can land on the weaker of the two.
+  // The navbar's text on its own color - the same rule (contrastTextColor()
+  // in lib/config.ts), with the same gap for mid-tones.
   for (const mode of ['light', 'dark']) {
     const side = styles.navbar?.[mode];
     const bg = typeof side === 'string' ? side : side?.background;
     if (!bg) continue;
-    const fg = navbarTextFor(bg);
+    const fg = readableTextOn(bg);
     const r = low(fg, bg);
     if (r) {
       push(
         at('navbar', mode, ...(typeof side === 'string' ? [] : ['background'])),
         `The navbar's ${fg === '#ffffff' ? 'white' : 'black'} text on ${bg} (${mode} mode) has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
-        'Use a darker or a lighter navbar color - mid-tones can\'t reach 4.5:1 with either black or white text.'
+        'Use a darker navbar color - or a much lighter one, which gets black text.'
       );
     }
   }

package/src/lib/asset-path.js

@@ -0,0 +1,29 @@
+// Where a root-relative asset URL points inside a project - for
+// styles-asset-integration.js's dev-server middleware and build copy. Plain
+// JavaScript with no config.ts import, so it can be tested with plain Node.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Resolves a root-relative `urlPath` (e.g. "/images/hero.svg") against
+ *  `contentDir` directly - not `<contentDir>/public` - the fallback
+ *  location for one of the styles/footer/seo asset fields
+ *  (collectConfiguredAssetPaths()) when it isn't sitting under public/.
+ *  `urlPath` comes from an incoming request URL in the dev-server case, not
+ *  just trusted writedocs.json content, so it must never resolve outside
+ *  the project: no `..`/`.` segments, and the resolved path itself has to
+ *  stay inside contentDir - on Windows `\` is a separator too, and a raw
+ *  request for `/x\..\..\secret.png` has no `..` segment yet walked out of
+ *  the project. Returns an absolute path, or null if nothing real is there. */
+export function resolveOutsidePublic(urlPath, contentDir) {
+  const segments = urlPath.replace(/^\/+/, '').split('/');
+  if (segments.some((segment) => segment === '..' || segment === '.' || segment === '')) return null;
+  const root = path.resolve(contentDir);
+  const absolute = path.resolve(root, ...segments);
+  const inside = path.relative(root, absolute);
+  if (!inside || inside.startsWith('..') || path.isAbsolute(inside)) return null;
+  try {
+    return fs.statSync(absolute).isFile() ? absolute : null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/color.js

@@ -0,0 +1,49 @@
+// WCAG 2 color math - shared by the theme (BaseLayout.astro, through
+// contrastTextColor() in lib/config.ts), which picks the text color that
+// goes on a configured color, and by `writedocs a11y` (lib/a11y-check.js),
+// which checks that choice. One implementation, so the check always
+// measures what the site actually renders. Plain JavaScript, loaded by
+// plain Node from an installed package (see lib/icons.js's comment).
+
+/** [r, g, b] for `#rgb`/`#rrggbb` (the `#` optional), or null. */
+export function parseHex(value) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(value ?? '').trim());
+  if (!m) return null;
+  const hex = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1];
+  return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16));
+}
+
+/** WCAG relative luminance of an [r, g, b] triple. */
+export function luminance(rgb) {
+  const [r, g, b] = rgb.map((v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio of two hex colors, or null when either isn't hex. */
+export function contrastRatio(a, b) {
+  const x = parseHex(a);
+  const y = parseHex(b);
+  if (!x || !y) return null;
+  const [hi, lo] = [luminance(x), luminance(y)].sort((p, q) => q - p);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Below this contrast, white text on a color switches to black. */
+export const WHITE_TEXT_MIN_CONTRAST = 3;
+
+/** The text color the theme puts on `hex`: white, as brand colors are
+ *  designed for, unless white falls below 3:1 - a clearly light color
+ *  (amber, sky, a light dark-mode primary), which gets black instead, at
+ *  7:1 or more. Pure "whichever has more contrast" turned most mid-tone
+ *  brand colors (blue-500, indigo-500, Mintlify's green) black; with this,
+ *  white between 3:1 and 4.5:1 is kept and `writedocs a11y` reports it
+ *  (lib/a11y-check.js). White too when `hex` isn't a hex color (a CSS
+ *  variable, a named color). */
+export function readableTextOn(hex) {
+  const white = contrastRatio('#ffffff', hex);
+  if (white === null) return '#ffffff';
+  return white < WHITE_TEXT_MIN_CONTRAST ? '#000000' : '#ffffff';
+}

package/src/lib/config-file.js

@@ -0,0 +1,25 @@
+// Reading writedocs.json (and the other JSON configs `writedocs convert`
+// reads) as text. Plain JavaScript, not TypeScript, so the CLI can load it
+// with plain Node - see lib/icons.js's comment.
+//
+// Windows editors - Notepad, PowerShell 5.1's `Out-File`/`Set-Content
+// -Encoding utf8` - save UTF-8 with a byte order mark. JSON.parse rejects
+// it ("Unexpected token ''"), and the error then blames commas and
+// brackets the file doesn't have. Every reader strips it here instead.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** `text` without a leading UTF-8 byte order mark. */
+export function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/** A JSON config file's text, byte order mark removed. */
+export function readJsonText(file) {
+  return stripBom(fs.readFileSync(file, 'utf-8'));
+}
+
+/** `<contentDir>/writedocs.json`'s text, byte order mark removed. */
+export function readConfigText(contentDir) {
+  return readJsonText(path.join(contentDir, 'writedocs.json'));
+}

package/src/lib/config-schema.js

@@ -379,18 +379,15 @@ const pageFrontmatterSchema = z.object({
   }
 );
 const apiSchema = z.object({
-  // Whether the Try-it modal's Send button routes its request through
-  // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
-  // than calling the API directly from the browser. Almost no
-  // real-world API sends back Access-Control-Allow-Origin headers
-  // permitting an arbitrary docs site's origin, so a direct browser
-  // fetch() from the Try-it modal fails for most real APIs without
-  // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
-  // actual request-forwarding logic. Defaults to enabled; a site can
-  // set this to `false` to always call the API directly instead (the
-  // API is already CORS-permissive, same-origin in some deployments,
-  // or the site owner doesn't want requests routed through a third
-  // party at all).
+  // Whether a Try-it request the browser blocks is retried through
+  // writedocs' own CORS proxy (https://proxy.writechoice.io/). The
+  // request always goes to the API directly first, so a reader's key
+  // reaches the proxy only when the API itself refuses browser calls.
+  // Almost no real-world API sends back Access-Control-Allow-Origin
+  // headers permitting an arbitrary docs site's origin, so the direct
+  // call fails for most real APIs - see the send handler and
+  // PROXY_BASE_URL in ApiReferencePanel.astro. Defaults to enabled; a
+  // site can set this to `false` to never involve a third party.
   proxy: z.boolean().default(true)
 }).strict().default({ proxy: true });
 const contextMenuSchema = z.object({
@@ -628,6 +625,7 @@ function createJsonLocator(rawText) {
   return criarLocalizador(rawText);
 }
 function criarLocalizador(rawText) {
+  rawText = semBom(rawText);
   let arvore;
   try {
     arvore = parseTree(rawText);
@@ -745,6 +743,7 @@ function humanizar(issue, raiz) {
   }
 }
 function unknownRootKeyIssues(rawText) {
+  rawText = semBom(rawText);
   let raiz;
   try {
     raiz = JSON.parse(rawText);
@@ -773,7 +772,11 @@ function unknownRootKeyIssues(rawText) {
     };
   });
 }
+function semBom(texto) {
+  return texto.charCodeAt(0) === 65279 ? texto.slice(1) : texto;
+}
 function validateDocsConfig(rawText) {
+  rawText = semBom(rawText);
   let raw;
   try {
     raw = JSON.parse(rawText);

package/src/lib/config-schema.ts

@@ -713,18 +713,15 @@ export const pageFrontmatterSchema = z.object({
 // about the spec itself.
 const apiSchema = z
   .object({
-    // Whether the Try-it modal's Send button routes its request through
-    // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
-    // than calling the API directly from the browser. Almost no
-    // real-world API sends back Access-Control-Allow-Origin headers
-    // permitting an arbitrary docs site's origin, so a direct browser
-    // fetch() from the Try-it modal fails for most real APIs without
-    // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
-    // actual request-forwarding logic. Defaults to enabled; a site can
-    // set this to `false` to always call the API directly instead (the
-    // API is already CORS-permissive, same-origin in some deployments,
-    // or the site owner doesn't want requests routed through a third
-    // party at all).
+    // Whether a Try-it request the browser blocks is retried through
+    // writedocs' own CORS proxy (https://proxy.writechoice.io/). The
+    // request always goes to the API directly first, so a reader's key
+    // reaches the proxy only when the API itself refuses browser calls.
+    // Almost no real-world API sends back Access-Control-Allow-Origin
+    // headers permitting an arbitrary docs site's origin, so the direct
+    // call fails for most real APIs - see the send handler and
+    // PROXY_BASE_URL in ApiReferencePanel.astro. Defaults to enabled; a
+    // site can set this to `false` to never involve a third party.
     proxy: z.boolean().default(true),
   })
   .strict()
@@ -1322,6 +1319,7 @@ export function createJsonLocator(rawText: string): (path: (string | number)[])
  *  quando o no nao existe no texto (campo obrigatorio ausente e o caso comum):
  *  `line` ausente e melhor que `line` inventada. */
 function criarLocalizador(rawText: string): (caminho: (string | number)[]) => { line: number; column: number } | null {
+  rawText = semBom(rawText);
   let arvore: ReturnType<typeof parseTree> | undefined;
   try {
     arvore = parseTree(rawText);
@@ -1485,6 +1483,7 @@ function humanizar(issue: IssuePlano, raiz: unknown): { humanMessage?: string; s
  *  porque a plataforma repassa `issues` como `errors` e um aviso ali viraria
  *  erro. */
 export function unknownRootKeyIssues(rawText: string): ValidationIssue[] {
+  rawText = semBom(rawText);
   let raiz: unknown;
   try {
     raiz = JSON.parse(rawText);
@@ -1516,7 +1515,16 @@ export function unknownRootKeyIssues(rawText: string): ValidationIssue[] {
     });
 }
 
+/** Texto sem o BOM do UTF-8 no inicio. Editores do Windows (Bloco de Notas, o
+ *  `Out-File` do PowerShell 5.1) gravam um, e o JSON.parse o rejeita com uma
+ *  mensagem que culpa virgulas e colchetes. Copia local, e nao import de
+ *  lib/config-file.js: este modulo so importa zod e jsonc-parser (ver o topo). */
+function semBom(texto: string): string {
+  return texto.charCodeAt(0) === 0xfeff ? texto.slice(1) : texto;
+}
+
 export function validateDocsConfig(rawText: string): ValidationResult {
+  rawText = semBom(rawText);
   let raw: unknown;
   try {
     raw = JSON.parse(rawText);

package/src/lib/config.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { EXCLUDED_TOP_LEVEL_DIRS } from './pages.js';
 import matter from 'gray-matter';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
+import { readableTextOn } from './color.js';
 import {
   formatValidationIssues,
   validateDocsConfig,
@@ -208,13 +209,12 @@ export function resolveNavbarColor(
   return { background: value.background, accent: value.accent };
 }
 
-/** Picks black or white text for readable contrast against `hexColor`,
- *  via the standard relative-luminance formula (ITU-R BT.601 weights -
- *  the same "perceived brightness" approximation used all over the web
- *  for exactly this "what text color goes on this swatch" problem, not
- *  the more expensive WCAG relative-luminance formula, which isn't
- *  needed for a binary choose-the-less-bad-option decision like this
- *  one). Used two ways in BaseLayout.astro: for `--wd-navbar-accent-text`
+/** Picks black or white text for `hexColor` - white unless white falls
+ *  below 3:1 on it (readableTextOn() in lib/color.js), the same rule and
+ *  WCAG math `writedocs a11y` checks with, so the check measures what the
+ *  site renders. (This used a BT.601 brightness threshold.) Also
+ *  gives `--wd-on-primary`, the text on step numbers, the info banner and
+ *  the API playground's buttons. Used two ways in BaseLayout.astro: for `--wd-navbar-accent-text`
  *  (the active tab's own fill used to always be `var(--wd-primary)` with
  *  hardcoded `color: #fff`, which only actually read fine because every
  *  default/example primary color so far has been dark/saturated enough
@@ -224,19 +224,12 @@ export function resolveNavbarColor(
  *  hold unconditionally), and for `--wd-navbar-foreground` itself once
  *  `styles.navbar` is configured at all (the navbar's plain text/icon
  *  color - see `navbar`'s own schema comment for why that's always
- *  computed, never a writedocs.json value). Malformed input (not a 6-digit
- *  `#rrggbb` hex) falls back to white rather than throwing - same "don't
+ *  computed, never a writedocs.json value). Malformed input (not a
+ *  `#rgb`/`#rrggbb` hex) falls back to white rather than throwing - same "don't
  *  fail a build over a cosmetic color value" posture every other color
  *  field here takes (none of them validate hex syntax either). */
 export function contrastTextColor(hexColor: string): '#000000' | '#ffffff' {
-  const match = /^#?([0-9a-f]{6})$/i.exec(hexColor.trim());
-  if (!match) return '#ffffff';
-  const hex = match[1];
-  const r = parseInt(hex.slice(0, 2), 16);
-  const g = parseInt(hex.slice(2, 4), 16);
-  const b = parseInt(hex.slice(4, 6), 16);
-  const luminance = (299 * r + 587 * g + 114 * b) / 1000;
-  return luminance > 150 ? '#000000' : '#ffffff';
+  return readableTextOn(hexColor) as '#000000' | '#ffffff';
 }
 
 /** Whether an href points off-site - has an explicit scheme (`https:`,
@@ -481,122 +474,9 @@ export function loadDocsConfig(contentDir: string): DocsConfig {
 // JavaScript, so `writedocs validate` can find a site's pages with plain Node.
 export { findAllPages } from './pages.js';
 
-/** Any `.css`/`.js` file anywhere in the project - root or any subfolder,
- *  `public/` included - auto-loaded site-wide with zero `writedocs.json`
- *  config, on top of (not instead of) the explicit `scripts` field
- *  (bannerSchema and friends, above). Drop a file in, it loads;
- *  there's no field naming which ones to use, matching the same "just
- *  works" convention `docs/`'s own file discovery already follows (see
- *  findAllPages() above / `content-pipeline.mdx`) - a site author already
- *  drops content files in and expects them found, rather than also
- *  listing every one in writedocs.json.
- *
- *  Two separate walks, because `public/` needs different treatment than
- *  everywhere else:
- *
- *  - `css`/`js`: every `.css`/`.js` file outside `public/` (root, `docs/`,
- *    `snippets/`, any custom folder) - reused as the walk-with-exclusions
- *    shape from findAllPages() above, and its exact `EXCLUDED_TOP_LEVEL_DIRS`
- *    set (skipped only at the project root, same as there), so `dist/`,
- *    `node_modules/`, `.astro/`, `.writedocs/`, `.git/`, and (for this
- *    half only - see below) `public/` are never walked into. BaseLayout.astro
- *    reads each one's raw content and inlines it as a `<style>`/
- *    `<script is:inline>` tag.
- *  - `publicCss`/`publicJs`: every `.css`/`.js` file *inside* `public/`,
- *    walked separately (starting from `<contentDir>/public` rather than
- *    `contentDir` itself, so the same `EXCLUDED_TOP_LEVEL_DIRS` check
- *    doesn't apply here - there's no `public/public/` or `public/dist/`
- *    convention to guard against). Returned as public-URL-rooted hrefs
- *    (a leading `/`, no `public` segment - `public/custom.css` becomes
- *    `/custom.css`) rather than content-dir-relative paths, since these
- *    files are already served as static assets at exactly that URL once
- *    Astro copies `public/` into the build output. BaseLayout.astro
- *    renders these as ordinary `<link rel="stylesheet">`/`<script src>`
- *    tags pointing at that URL instead of inlining their content -
- *    inlining would duplicate every byte (once in the page's own HTML,
- *    once more as the independently-fetchable static file at that same
- *    URL) for no benefit, where a `<link>`/`<script src>` gets normal
- *    browser caching across pages instead of repeating the content on
- *    every single page's markup.
- *
- *  Both halves are broader than they might sound - a stray `.js` file
- *  kept in `docs/`, `snippets/`, or `public/` for an unrelated reason
- *  (a snippet's own local helper, an image gallery's lightbox script
- *  someone dropped in `public/` to reference from a raw `<script src>`
- *  in an .mdx file, say) gets auto-injected sitewide the same as a
- *  deliberate one; there's no separate "this one's just tooling" signal
- *  to opt out of the convention short of renaming its extension.
- *
- *  Both `css`/`js` and `publicCss`/`publicJs` are sorted alphabetically
- *  by their respective path for deterministic load order across rebuilds
- *  - same reasoning as llms.txt's own alphabetical-by-slug sort (see
- *  llms.txt.ts) - filesystem readdir order isn't guaranteed portable
- *  across OSes or directory-walk order otherwise.
- *
- *  `css`/`js` return POSIX-separated paths relative to `contentDir`, not
- *  absolute paths or file contents - BaseLayout.astro (the sole caller)
- *  resolves and reads each one's content itself, right before inlining
- *  it, so a file's content is always current as of that specific
- *  request/build rather than cached here across a `writedocs dev`
- *  session. `publicCss`/`publicJs` return the public-URL hrefs described
- *  above - nothing to read, Astro's own static-file serving/copy already
- *  handles those. */
-export function findRootAssets(
-  contentDir: string
-): { css: string[]; js: string[]; publicCss: string[]; publicJs: string[] } {
-  const css: string[] = [];
-  const js: string[] = [];
-  function walk(dir: string, relBase: string) {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
-        walk(abs, rel);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      if (/\.css$/i.test(entry.name)) css.push(rel);
-      else if (/\.js$/i.test(entry.name)) js.push(rel);
-    }
-  }
-  walk(contentDir, '');
-  css.sort();
-  js.sort();
-
-  const publicCss: string[] = [];
-  const publicJs: string[] = [];
-  function walkPublic(dir: string, relBase: string) {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walkPublic(abs, rel);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      if (/\.css$/i.test(entry.name)) publicCss.push(`/${rel}`);
-      else if (/\.js$/i.test(entry.name)) publicJs.push(`/${rel}`);
-    }
-  }
-  walkPublic(path.join(contentDir, 'public'), '');
-  publicCss.sort();
-  publicJs.sort();
-
-  return { css, js, publicCss, publicJs };
-}
+// findRootAssets() lives in lib/pages.js - plain JavaScript, so it can be
+// tested with plain Node, next to findAllPages() whose exclusions it shares.
+export { findRootAssets } from './pages.js';
 
 /** The root-relative URL paths (leading `/`, e.g. `/images/hero.svg`)
  *  referenced by the writedocs.json/styles fields that point at a static asset
@@ -615,7 +495,7 @@ export function findRootAssets(
  *  `public/` was the one place `styles.background.images` (etc.) had to
  *  live, since Astro's own `publicDir` copy is the only thing that ever
  *  served them; everywhere else in this codebase's own "drop a file
- *  anywhere, it's found" convention (`findRootAssets()` right above,
+ *  anywhere, it's found" convention (`findRootAssets()` in lib/pages.js,
  *  `findAllPages()` for content) already worked project-wide. See that
  *  integration's own comment for the actual resolution mechanism (a dev-time
  *  middleware plus a post-build copy step, not a duplicated `publicDir`)
@@ -733,7 +613,10 @@ export function fileIdForEntry(
   const absoluteContentDir = path.resolve(contentDir);
   const absoluteFilePath = path.resolve(packageRoot, entry.filePath);
   const relativeToContentDir = path.relative(absoluteContentDir, absoluteFilePath);
-  if (relativeToContentDir.startsWith('..')) return entry.id;
+  // Outside contentDir: `..`-prefixed, or - on Windows, when the file is on
+  // another drive (temp on C:, project on D:) - an absolute path, since
+  // path.relative() can't bridge drives.
+  if (relativeToContentDir.startsWith('..') || path.isAbsolute(relativeToContentDir)) return entry.id;
   const posixRelative = relativeToContentDir.split(path.sep).join('/');
   if (EXCLUDED_TOP_LEVEL_DIRS.has(posixRelative.split('/')[0])) return entry.id;
   return posixRelative.replace(/\.mdx?$/i, '').replace(/\/index$/, '');