@writedocs/generator 0.7.2 → 0.7.4

package/astro.config.mjs

@@ -143,26 +143,33 @@ function walkMdFiles(baseDir) {
 function collectNoindexIds(rootContentDir) {
   const generatedDocsDir = path.join(writedocsTempDir(rootContentDir), 'generated-docs');
   const ids = new Set();
+  // Whether some page is served at "/" itself. When none is, "/" is the
+  // redirect-only route [...slug].astro synthesizes (noindex, pointing at
+  // the first page) - which doesn't belong in the sitemap either.
+  let rootIsPage = false;
 
   for (const relativeId of findAllPages(rootContentDir)) {
     const file = path.join(rootContentDir, relativeId);
     const { data } = matter(fs.readFileSync(file, 'utf-8'));
+    const pageId = normalizeEntryId(data?.slug ?? relativeId.replace(/\.mdx?$/i, '').replace(/\/index$/, ''));
+    if (pageId === 'index') rootIsPage = true;
     // Top-level `noindex` is Mintlify's spelling, and a Mintlify `hidden`
     // page is noindexed too - content.config.ts folds both into
     // `seo.noindex` the same way (an explicit value wins).
     // A frontmatter `url` page's route only redirects to that link, so it
     // doesn't belong in the sitemap either.
     if (!(data?.seo?.noindex ?? data?.noindex ?? data?.hidden === true) && !data?.url) continue;
-    const fallbackId = relativeId.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
-    ids.add(normalizeEntryId(data.slug ?? fallbackId));
+    ids.add(pageId);
   }
   // Generated OpenAPI stub pages always set an explicit `slug` (see
   // generate-api-pages.js) - there's no file-path-derived id to fall back
   // to the way there is for a hand-written page.
   for (const file of walkMdFiles(generatedDocsDir)) {
     const { data } = matter(fs.readFileSync(file, 'utf-8'));
+    if (data?.slug && normalizeEntryId(data.slug) === 'index') rootIsPage = true;
     if ((data?.seo?.noindex ?? data?.noindex ?? data?.hidden === true) && data.slug) ids.add(normalizeEntryId(data.slug));
   }
+  if (!rootIsPage) ids.add('index');
   return ids;
 }
 
@@ -513,8 +520,7 @@ export default defineConfig({
         // from such a file never finds a package.json named "writedocs",
         // so self-reference fails and Vite reports the bare specifier as
         // unresolvable ("Rolldown failed to resolve import
-        // 'writedocs/components'"). See BUG.md for the full writeup this
-        // fix comes from.
+        // 'writedocs/components'").
         // This alias bypasses self-reference resolution entirely for
         // that one specifier - Vite's alias matching is a plain string
         // match against the specifier itself, independent of which file

package/bin/writedocs.js

@@ -10,6 +10,7 @@ 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';
+import { readConfigText } from '../src/lib/config-file.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
@@ -45,6 +46,9 @@ program
   .name('writedocs')
   .description('Static site generator for writedocs.json + MDX')
   .version(version)
+  // The built-in `help <command>` prints any command's usage, hidden ones
+  // included - replaced by the `help` command at the bottom of this file.
+  .helpCommand(false)
   // 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) => {
@@ -72,6 +76,9 @@ program
   // src/cli/build-auth.js for the second layer: even someone who knows the
   // command exists still can't run it without the right key.
   .command('build', { hidden: true })
+  // `build --help` prints the general help, which doesn't list it: hidden
+  // means not described anywhere (see the `help` command at the bottom too).
+  .configureHelp({ formatHelp: () => program.helpInformation() })
   .description('Build a static site into <dir>/dist')
   .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
   .option('-k, --key <key>', 'build authorization key (or set WRITEDOCS_API_KEY)')
@@ -79,8 +86,8 @@ program
   .action(async (dir, opts) => {
     const contentDir = path.resolve(process.cwd(), dir);
     // Project-scoped, not global: a .env sitting next to this project's own
-    // writedocs.json (WRITEDOCS_KEY_SERVER_URL, WRITEDOCS_API_KEY) is picked
-    // up automatically, so build doesn't need those exported by hand every
+    // writedocs.json (WRITEDOCS_API_KEY) is picked up automatically, so
+    // build doesn't need it exported by hand every
     // session. dotenv never overwrites a var already set in the real
     // environment - an explicit `export`/CI secret still wins over the file.
     dotenv.config({ path: path.join(contentDir, '.env'), quiet: true });
@@ -106,7 +113,7 @@ program
       throw new CliExit(1);
     }
 
-    const rawText = fs.readFileSync(configPath, 'utf-8');
+    const rawText = readConfigText(contentDir);
     const result = validateDocsConfig(rawText);
     // Chave desconhecida na raiz e AVISO, nunca erro: a raiz nao e `.strict()`
     // de proposito (tornar strict quebraria configs existentes), entao o Zod
@@ -186,7 +193,7 @@ program
     const contentDir = path.resolve(process.cwd(), dir);
     const { preflightCheck } = await import('../src/cli/preflight.js');
     preflightCheck(contentDir);
-    const configText = fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8');
+    const configText = readConfigText(contentDir);
     const checking = step('Checking links');
     // Generated OpenAPI pages are link targets too - same step dev/build run.
     const { generateApiPages } = await import('../src/cli/generate-api-pages.js');
@@ -221,7 +228,7 @@ program
     const contentDir = path.resolve(process.cwd(), dir);
     const { preflightCheck } = await import('../src/cli/preflight.js');
     preflightCheck(contentDir);
-    const configText = fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8');
+    const configText = readConfigText(contentDir);
     const checking = step('Checking accessibility');
     const { checkAccessibility } = await import('../src/lib/a11y-check.js');
     const { formatContentIssues } = await import('../src/lib/content-check.js');
@@ -252,8 +259,10 @@ program
   .option('--force', 'overwrite an existing writedocs.json')
   .option('--dry-run', 'print the converted writedocs.json instead of writing it')
   .action(async (dir, options) => {
-    const mintlify = options.mintlify || options.docsJson;
-    const legacy = options.writedocs || options.configJson;
+    // Commander camel-cases only on hyphens: `--docs.json` is stored under
+    // the key "docs.json", not `docsJson`.
+    const mintlify = options.mintlify || options['docs.json'];
+    const legacy = options.writedocs || options['config.json'];
     if (mintlify === legacy) {
       log.error(
         mintlify
@@ -287,6 +296,18 @@ program
     await runInit({ targetDir: path.resolve(process.cwd(), dir) });
   });
 
+// `writedocs help [command]` - commander's own, except that a hidden command
+// (`build`) gets the general help, like a name that isn't a command at all.
+const HIDDEN_COMMANDS = new Set(['build']);
+program
+  .command('help')
+  .description('display help for command')
+  .argument('[command]')
+  .action((name) => {
+    const command = name && !HIDDEN_COMMANDS.has(name) ? program.commands.find((c) => c.name() === name) : undefined;
+    (command ?? program).help();
+  });
+
 program
   .parseAsync(process.argv)
   .then(showUpdateNotice)

package/package.json

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

package/src/cli/build-auth.js

@@ -1,8 +1,8 @@
 /**
  * `writedocs build` produces the artifact that actually gets deployed, so
  * unlike `dev`/`init` it isn't freely runnable by anyone who installs the
- * package - it's gated behind a key that a separate service (`key-server/`
- * in this repo) actually decides the validity of.
+ * package - it's gated behind a key that a separate service
+ * (writedocs-key-server, a sibling repo) actually decides the validity of.
  *
  * This deliberately isn't a local check. An earlier version compared the
  * supplied key against an env var set on the same machine
@@ -12,19 +12,26 @@
  * actually holds the set of issued keys means a key's validity is decided
  * by whoever runs that server, not by whoever is running `build`.
  *
- * See docs/dev/docs/deploy.mdx for how to deploy key-server/ and issue
- * keys, and key-server/README.md for the service's own endpoints.
+ * See docs/dev/docs/deploy.mdx for how to deploy writedocs-key-server and
+ * issue keys, and that repo's own README for the service's endpoints.
  */
 import { log } from './output.js';
 
 export const EX_TEMPFAIL = 75;
 
+/** The authorization server every `build` asks. Fixed in the code, with no
+ *  environment override: when the URL came from WRITEDOCS_KEY_SERVER_URL,
+ *  anyone could point it at a 3-line server that answers
+ *  `{ "valid": true }` and build without a key. Tests and CI use a real
+ *  key instead (the WRITEDOCS_API_KEY secret - see
+ *  scripts/smoke-installed-cli.sh). Honest limit: the source ships with the
+ *  package, so someone willing to edit it can still remove this check - it
+ *  raises the bar, it isn't a lock. Real protection is what the platform
+ *  does with the output. */
+export const KEY_SERVER_URL = 'https://proxy.writechoice.io:8787';
+
 export async function requireBuildKey(providedKey) {
-  const serverUrl = process.env.WRITEDOCS_KEY_SERVER_URL;
-  if (!serverUrl) {
-    log.error('build is not available.');
-    process.exit(1);
-  }
+  const serverUrl = KEY_SERVER_URL;
   if (!providedKey) {
     log.error('build requires a valid --key (or WRITEDOCS_API_KEY).');
     process.exit(1);

package/src/cli/build.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { runAstro } from './run-astro.js';
 import { runPagefind } from './run-pagefind.js';
-import { preflightCheck } from './preflight.js';
+import { preflightCheck, sameDriveCheck, writableInstallCheck } from './preflight.js';
 import { generateApiPages } from './generate-api-pages.js';
 import { writeRedirectsFile } from './write-redirects-file.js';
 import { writedocsBuildStagingDir } from '../lib/writedocs-temp-dir.js';
@@ -13,6 +13,7 @@ import { reportApiPages } from './api-pages-output.js';
 export async function runBuild({ contentDir, packageRoot, verbose = false }) {
   const started = Date.now();
   preflightCheck(contentDir);
+  writableInstallCheck(packageRoot);
 
   // Collected while building, printed together at the end - a warning in
   // the middle of a spinner is easy to miss.
@@ -27,6 +28,7 @@ export async function runBuild({ contentDir, packageRoot, verbose = false }) {
   };
 
   const api = await generateApiPages({ contentDir });
+  sameDriveCheck(contentDir, packageRoot, { generatedPages: api.groups.length > 0 });
   reportApiPages(api);
   api.warnings.forEach((message) => addWarning(null, message));
 

package/src/cli/convert.js

@@ -10,7 +10,7 @@ import { loadMintlifyConfig, convertMintlifyConfig, formatNotes } from '../lib/m
 import { loadLegacyConfig, convertLegacyConfig } from '../lib/writedocs-legacy-convert.js';
 import { validateDocsConfig, formatValidationIssuesDetailed } from '../lib/config-schema.js';
 import { checkContent, formatContentIssues } from '../lib/content-check.js';
-import { log, step, plural, color, displayPath, CliExit } from './output.js';
+import { log, step, plural, color, displayPath, CliExit, logToStderr } from './output.js';
 
 const SOURCES = {
   mintlify: {
@@ -39,6 +39,10 @@ const SOURCES = {
 };
 
 export async function runConvert({ source = 'mintlify', contentDir, force = false, dryRun = false }) {
+  // --dry-run's stdout is the converted writedocs.json and nothing else, so
+  // `writedocs convert --dry-run > writedocs.json` works; the notes and the
+  // page check go to stderr.
+  if (dryRun) logToStderr();
   const from = SOURCES[source];
   const inputPath = path.join(contentDir, from.file);
   if (!fs.existsSync(inputPath)) {
@@ -75,7 +79,7 @@ export async function runConvert({ source = 'mintlify', contentDir, force = fals
   }
 
   if (dryRun) {
-    log.line(text);
+    process.stdout.write(text);
   } else {
     fs.writeFileSync(outPath, text);
     log.success(`Converted ${from.file} to ${color.bold(displayPath(outPath))}`);

package/src/cli/dev.js

@@ -1,5 +1,5 @@
 import { runAstro } from './run-astro.js';
-import { preflightCheck } from './preflight.js';
+import { preflightCheck, sameDriveCheck, writableInstallCheck } from './preflight.js';
 import { generateApiPages } from './generate-api-pages.js';
 import { log, step, duration, formatProblems, color, CliExit } from './output.js';
 import { describeError, requestLog, authorWarning, verboseLine, stripAnsi } from './astro-output.js';
@@ -15,6 +15,7 @@ const REPEAT_WINDOW_MS = 2000;
 export async function runDev({ contentDir, packageRoot, port, verbose = false }) {
   const started = Date.now();
   preflightCheck(contentDir);
+  writableInstallCheck(packageRoot);
   const other = runningPreview(packageRoot);
   if (other) {
     log.error(`Another writedocs preview is already running${other.url ? ` at ${other.url}` : ''}.`);
@@ -29,6 +30,7 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
   process.on('exit', () => removeLock(packageRoot));
 
   const api = await generateApiPages({ contentDir });
+  sameDriveCheck(contentDir, packageRoot, { generatedPages: api.groups.length > 0 });
   reportApiPages(api);
   api.warnings.forEach((message) => log.warn(message));
 

package/src/cli/generate-api-pages.js

@@ -5,6 +5,7 @@ import matter from 'gray-matter';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
 import { parseOpenApiRef, openApiOperationKey, specDirName } from '../lib/openapi-ref.js';
 import { findAllPages } from '../lib/pages.js';
+import { readConfigText } from '../lib/config-file.js';
 import { HTTP_METHODS, collectOpenApiGroups } from '../lib/openapi-spec.js';
 
 
@@ -298,13 +299,12 @@ async function generateApiPagesForGroup({ contentDir, generatedDocsDir, group, o
  */
 export async function generateApiPages({ contentDir }) {
   const summary = { groups: [], pageSpecs: [], warnings: [] };
-  const writedocsJsonPath = path.join(contentDir, 'writedocs.json');
   const generatedDocsDir = path.join(writedocsTempDir(contentDir), 'generated-docs');
   const openapiOutDir = path.join(writedocsTempDir(contentDir), 'openapi');
 
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(writedocsJsonPath, 'utf-8'));
+    config = JSON.parse(readConfigText(contentDir));
   } catch {
     return summary; // preflightCheck() (run first, see dev.js/build.js) already reports this
   }

package/src/cli/init.js

@@ -6,7 +6,9 @@ const WRITEDOCS_JSON = {
   name: 'My Docs',
   description: 'Documentation site built with Writedocs',
   styles: {
-    colors: { primary: '#6366f1' },
+    // Readable as link text on both default backgrounds - a new project
+    // passes `writedocs a11y` (scripts/init.test.js).
+    colors: { primary: '#4f46e5', dark: { primary: '#a5b4fc' } },
   },
   navigation: [
     { group: 'Getting Started', pages: ['index', 'docs/getting-started'] },

package/src/cli/output.js

@@ -9,13 +9,20 @@
 // it finishes. NO_COLOR turns colors off; FORCE_COLOR turns them on.
 import path from 'node:path';
 
-const stream = process.stdout;
+let stream = process.stdout;
 // Output piped into something that stopped reading (`writedocs build | head`):
 // nothing more can be shown, so stop instead of crashing on EPIPE.
 stream.on('error', (err) => {
   if (err.code === 'EPIPE') process.exit(0);
   throw err;
 });
+
+/** Sends everything this module prints to stderr from here on - for a
+ *  command whose stdout is data: `convert --dry-run` prints the converted
+ *  writedocs.json there, so `> writedocs.json` gets exactly that. */
+export function logToStderr() {
+  stream = process.stderr;
+}
 const interactive = Boolean(stream.isTTY) && process.env.TERM !== 'dumb' && !process.env.CI;
 const useColor =
   process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '0'

package/src/cli/preflight.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { log, color, CliExit } from './output.js';
+import { readConfigText } from '../lib/config-file.js';
 
 /**
  * Fast, dependency-light sanity check that runs before handing off to
@@ -28,7 +30,7 @@ export function preflightCheck(contentDir) {
     throw new CliExit(1);
   }
   try {
-    JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    JSON.parse(readConfigText(contentDir));
   } catch (err) {
     log.error(`writedocs.json is not valid JSON: ${err.message}`);
     log.detail(color.dim('Run "writedocs validate" to see where.'));
@@ -41,3 +43,63 @@ export function preflightCheck(contentDir) {
   // later, with a more specific error naming the missing page - see
   // getStaticPaths() in src/pages/[...slug].astro.
 }
+
+/** The drive (`C:`) or UNC share a Windows path lives on, lowercased. */
+function volumeOf(p) {
+  return path.win32.parse(path.win32.resolve(p)).root.replace(/[\\/]+$/, '').toLowerCase();
+}
+
+/**
+ * Windows only, before `dev`/`build` start Astro: the project has to be on
+ * the same drive as writedocs itself. Astro is run with writedocs' own
+ * folder as its root (see run-astro.js) and records every page's path
+ * relative to it - across drives there is no relative path, the
+ * `D:/...` it gets instead reads as a URL scheme, and the build dies with
+ * "The URL must be of scheme file". The same holds for the temp folder
+ * when it holds generated OpenAPI pages (`generatedPages` - writedocsTempDir()
+ * is Astro content then; the cache and inline React components there build
+ * fine across drives). This stops with what to do instead of that message.
+ * `platform` and `tempDir` are parameters for tests.
+ */
+export function sameDriveCheck(contentDir, packageRoot, { generatedPages = false, platform = process.platform, tempDir = os.tmpdir() } = {}) {
+  if (platform !== 'win32') return;
+  const install = volumeOf(packageRoot);
+  const project = volumeOf(contentDir);
+  if (project !== install) {
+    log.error(`This project is on ${project.toUpperCase()}, and writedocs is installed on ${install.toUpperCase()} - Astro can't build across drives on Windows.`);
+    log.detail(color.dim('Install writedocs in the project instead (npm install --save-dev @writedocs/generator, then npx writedocs ...),'));
+    log.detail(color.dim(`or move the project to drive ${install.toUpperCase()}.`));
+    throw new CliExit(1);
+  }
+  const temp = volumeOf(tempDir);
+  if (generatedPages && temp !== install) {
+    log.error(`The temp folder (${tempDir}) is on ${temp.toUpperCase()}, and writedocs is installed on ${install.toUpperCase()} - Astro can't build the generated API pages across drives on Windows.`);
+    log.detail(color.dim(`Point TEMP and TMP at a folder on drive ${install.toUpperCase()}, or install writedocs on ${temp.toUpperCase()}.`));
+    throw new CliExit(1);
+  }
+}
+
+/**
+ * Before `dev`/`build` start Astro: writedocs has to be able to write inside
+ * its own folder - Astro runs with it as its root (run-astro.js), and keeps
+ * `.astro/`, Vite's `node_modules/.vite/` and the build's staging folder
+ * (writedocsBuildStagingDir()) there. A global install made with sudo is
+ * owned by root, and both commands then die on a bare EACCES/EPERM from
+ * deep inside Astro or Vite. A real write, not fs.accessSync(): on Windows
+ * that only looks at the read-only attribute, not at permissions.
+ */
+export function writableInstallCheck(packageRoot) {
+  const probe = path.join(packageRoot, '.astro', `.write-check-${process.pid}`);
+  try {
+    fs.mkdirSync(path.dirname(probe), { recursive: true });
+    fs.writeFileSync(probe, '');
+    fs.rmSync(probe, { force: true });
+  } catch (err) {
+    if (err.code !== 'EACCES' && err.code !== 'EPERM') throw err;
+    log.error(`writedocs can't write to its own folder (${packageRoot}), and dev and build need to.`);
+    log.detail(color.dim('This happens with a global install made with sudo. Install writedocs in the project instead'));
+    log.detail(color.dim('(npm install --save-dev @writedocs/generator, then npx writedocs ...), or set npm up to install'));
+    log.detail(color.dim('globally without sudo: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally'));
+    throw new CliExit(1);
+  }
+}

package/src/cli/update.js

@@ -34,7 +34,12 @@ export async function installation(packageRoot, name) {
   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}`);
+  // pnpm's default layout keeps the real package inside its store,
+  // <project>/node_modules/.pnpm/<name>@<version>/node_modules/<name>, and
+  // Node resolves the symlink to that path - so the project is what comes
+  // before .pnpm, not before the last node_modules/<name>.
+  const pnpmStore = posix.indexOf('/node_modules/.pnpm/');
+  const at = pnpmStore !== -1 ? pnpmStore : posix.lastIndexOf(`/node_modules/${name}`);
   if (at === -1) return { kind: 'unknown' };
   const container = posix.slice(0, at);
   const npmRoot = await run('npm', ['root', '-g']);

package/src/cli/write-redirects-file.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { readConfigText } from '../lib/config-file.js';
 
 // Astro's own `output: 'static'` redirects (both writedocs.json's `redirects`
 // feature and the automatic "/" -> first-nav-page redirect in
@@ -31,7 +32,7 @@ import path from 'node:path';
 // the one `redirects` array back out, nothing that needs zod's defaults
 // or transforms.
 export function writeRedirectsFile(distDir, contentDir) {
-  const writedocsJson = JSON.parse(fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf8'));
+  const writedocsJson = JSON.parse(readConfigText(contentDir));
   const redirects = writedocsJson.redirects ?? [];
   const lines = [];
 

package/src/components/ApiReferencePanel.astro

@@ -658,7 +658,7 @@ const securityJson = JSON.stringify(op?.security ?? []);
     border-radius: 0.5rem;
     border: none;
     background: var(--wd-primary);
-    color: #fff;
+    color: var(--wd-on-primary);
     font-size: 0.75rem;
     font-weight: 600;
     cursor: pointer;
@@ -931,7 +931,7 @@ const securityJson = JSON.stringify(op?.security ?? []);
     border-radius: 0.4rem;
     border: none;
     background: var(--wd-primary);
-    color: #fff;
+    color: var(--wd-on-primary);
     font-size: 0.85rem;
     font-weight: 600;
     cursor: pointer;
@@ -1123,6 +1123,8 @@ const securityJson = JSON.stringify(op?.security ?? []);
   // after the base (protocol required), preserving method/headers/body,
   // and returns CORS headers so the browser fetch() below succeeds even
   // when the target API itself doesn't send Access-Control-Allow-Origin.
+  // Only a fallback: a request goes straight to the API first, and through
+  // here only when the browser blocks that (see the send handler below).
   // Toggle via writedocs.json's `api.proxy` (see data-proxy on the tryit
   // section below); the displayed curl/fetch/python snippets deliberately
   // keep showing the real, non-proxied URL - only this in-browser request
@@ -1322,17 +1324,26 @@ const securityJson = JSON.stringify(op?.security ?? []);
       const responseBodyEl = section.querySelector<HTMLElement>('[data-role="response-body"] code');
       const modalLangPanels = Array.from(section.querySelectorAll<HTMLElement>('[data-modal-lang-panel]'));
 
+      // A reader's credentials last for the tab, not forever: sessionStorage
+      // carries them across the pages of one visit and forgets them when the
+      // tab closes. Older versions kept them in localStorage indefinitely -
+      // a key found there is moved over once and deleted.
       authInputs.forEach((input) => {
-        const name = input.dataset.authName ?? '';
+        const storageKey = `wd-api-auth:${input.dataset.authName ?? ''}`;
         try {
-          const saved = localStorage.getItem(`wd-api-auth:${name}`);
+          const legacy = localStorage.getItem(storageKey);
+          if (legacy !== null) {
+            if (sessionStorage.getItem(storageKey) === null) sessionStorage.setItem(storageKey, legacy);
+            localStorage.removeItem(storageKey);
+          }
+          const saved = sessionStorage.getItem(storageKey);
           if (saved) input.value = saved;
         } catch {
-          // localStorage unavailable - auth just won't persist across reloads
+          // storage unavailable - auth just won't carry across pages
         }
         input.addEventListener('input', () => {
           try {
-            localStorage.setItem(`wd-api-auth:${name}`, input.value);
+            sessionStorage.setItem(storageKey, input.value);
           } catch {
             // ignore
           }
@@ -1714,9 +1725,13 @@ const securityJson = JSON.stringify(op?.security ?? []);
         }
 
         const targetUrl = baseUrl + requestPath + (query.toString() ? `?${query.toString()}` : '');
-        // Route through writedocs' CORS proxy unless disabled via writedocs.json's
-        // `api.proxy: false` - see PROXY_BASE_URL above for the contract.
-        const url = proxyEnabled ? `${PROXY_BASE_URL}${targetUrl}` : targetUrl;
+        // A "simple" request (CORS spec: GET/HEAD/POST, no JSON body, no
+        // auth or custom headers) skips the preflight, so the server may
+        // already have run it when the browser blocks the response.
+        // Retrying one that changes something (a POST) through the proxy
+        // could run it twice - so that one case isn't retried.
+        const isSimple = ['GET', 'HEAD', 'POST'].includes(method) && Object.keys(headers).length === 0;
+        const mayHaveRun = isSimple && method === 'POST';
 
         if (sendBtn) {
           sendBtn.disabled = true;
@@ -1727,8 +1742,23 @@ const securityJson = JSON.stringify(op?.security ?? []);
         responseBodyEl.textContent = '';
 
         const startedAt = performance.now();
+        let viaProxy = false;
         try {
-          const res = await fetch(url, { method, headers, body });
+          // Straight to the API first, so a reader's key and body only reach
+          // the API itself. fetch() rejects when the browser blocks the
+          // response (CORS) or can't reach the host - only then, and only
+          // when writedocs.json's `api.proxy` allows it, the same request is
+          // retried through writedocs' proxy (PROXY_BASE_URL above), and the
+          // status line says so.
+          let res: Response;
+          try {
+            res = await fetch(targetUrl, { method, headers, body });
+          } catch (directErr) {
+            if (!proxyEnabled || mayHaveRun) throw directErr;
+            viaProxy = true;
+            responseStatusEl.textContent = 'Blocked by the browser (CORS) - retrying through the writedocs proxy...';
+            res = await fetch(`${PROXY_BASE_URL}${targetUrl}`, { method, headers, body });
+          }
           const elapsed = Math.round(performance.now() - startedAt);
           const text = await res.text();
           let pretty = text;
@@ -1737,11 +1767,15 @@ const securityJson = JSON.stringify(op?.security ?? []);
           } catch {
             // not JSON - show raw text as-is
           }
-          responseStatusEl.textContent = `${res.status} ${res.statusText} - ${elapsed}ms`;
+          responseStatusEl.textContent = `${res.status} ${res.statusText} - ${elapsed}ms${viaProxy ? ' - sent through the writedocs proxy (the API blocks direct browser requests)' : ''}`;
           responseStatusEl.className = `wd-api-response-status ${res.ok ? 'wd-api-status-ok' : 'wd-api-status-error'}`;
           responseBodyEl.textContent = pretty;
         } catch (err) {
-          responseStatusEl.textContent = 'Request failed - likely blocked by CORS, or the base URL is unreachable from your browser.';
+          responseStatusEl.textContent = viaProxy
+            ? 'Request failed through the writedocs proxy too - the base URL may be unreachable from the internet.'
+            : mayHaveRun && proxyEnabled
+              ? 'Blocked by the browser (CORS). Not retried through the proxy: this POST may already have reached the API.'
+              : 'Request failed - likely blocked by CORS, or the base URL is unreachable from your browser.';
           responseStatusEl.className = 'wd-api-response-status wd-api-status-error';
           responseBodyEl.textContent = err instanceof Error ? err.message : String(err);
         } finally {

package/src/components/Steps.astro

@@ -27,7 +27,7 @@ import { extraClasses } from './class-names';
     height: 1.8rem;
     padding: 0.45rem;
     box-sizing: border-box;
-    color: white;
+    color: var(--wd-on-primary);
     z-index: 1;
   }
   span.wd-step-icon {
@@ -47,7 +47,7 @@ import { extraClasses } from './class-names';
     height: 1.8rem;
     border-radius: 50%;
     background: var(--wd-primary);
-    color: white;
+    color: var(--wd-on-primary);
     font-size: 0.85rem;
     font-weight: 600;
     display: flex;