@astryxdesign/cli 0.7.12-canary.f543ec7 → 0.7.12

package/foundation/render/render-page.mjs

@@ -18,13 +18,15 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {Worker} from 'node:worker_threads';
+import {fork, spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
 import postcss from 'postcss';
 import {assetDataUri, isAssetBytes, isAssetPath, RenderAssetError} from './assets.mjs';
 import {classesIn, cutCss, layerOrderOf} from './css-cut.mjs';
 import {sourceBlock} from './source-block.mjs';
 import {embeddedPathProblem} from './embedded-files.mjs';
 import {resolveServed} from './served-packages.mjs';
+import {CHART_CSS} from './charts.mjs';
 
 /** How long one page may take to render before it is stopped. */
 export const RENDER_TIMEOUT_MS = 60_000;
@@ -33,7 +35,7 @@ export {PAGE_EXTENSIONS} from './embedded-files.mjs';
 
 /**
  * @typedef {object} RenderWarning
- * @property {'dropped-children' | 'remote-asset' | 'missing-asset' | 'page-output' | 'page-script' | 'no-astryx-styles' | 'chart-size' | 'not-embedded'} code - What kind of problem.
+ * @property {'dropped-children' | 'remote-asset' | 'missing-asset' | 'page-output' | 'page-script' | 'no-astryx-styles' | 'chart-size' | 'not-embedded' | 'node-crash'} code - What kind of problem.
  * @property {string} message - What happened and what to do, in one sentence.
  */
 
@@ -220,65 +222,158 @@ function expandImports(file, css, ctx) {
 
 /** @typedef {{dir: string, integrations: readonly string[]}} ServedSet */
 
+/** Signals that Node itself or a native module raises when it fails. */
+const CRASH_SIGNALS = new Set(['SIGSEGV', 'SIGBUS', 'SIGILL', 'SIGFPE', 'SIGABRT', 'SIGTRAP']);
+
 /**
- * Run the page in a worker, stopping it after `timeoutMs`.
- * @param {string} entry
- * @param {string} root
+ * How a native crash ended a process, or null when it was not one. On
+ * Windows a crash arrives as an exit status of 0xC0000000 and above (such as
+ * 0xC0000005, an access violation), not as a signal.
+ * @param {number | null} code
+ * @param {NodeJS.Signals | null} signal
+ */
+function crashOf(code, signal) {
+  if (signal) return CRASH_SIGNALS.has(signal) ? signal : null;
+  if (code !== null && code >>> 0 >= 0xc0000000) return `0x${(code >>> 0).toString(16).toUpperCase()}`;
+  return null;
+}
+
+/**
+ * Whether this Node crashes when it splits text with Intl.Segmenter. Some
+ * Node builds do, and Astryx components such as Avatar split text with it.
+ */
+function segmenterCrashes() {
+  const probe = spawnSync(
+    process.execPath,
+    ['-e', "[...new Intl.Segmenter('en', {granularity: 'grapheme'}).segment('a b')]"],
+    {stdio: 'ignore', timeout: 10_000},
+  );
+  return crashOf(probe.status, probe.signal) !== null;
+}
+
+/**
+ * The error for a page process that a crash or a signal ended. A crash comes
+ * from Node itself or a native module, never from the page's JavaScript.
+ * Every message names this Node.
+ * @param {string} how the crash (a signal name or a Windows status) or the stopping signal
+ * @param {{crashed: boolean, withoutSegmenter: boolean}} state
+ */
+function crashError(how, {crashed, withoutSegmenter}) {
+  const node = `Node ${process.version} (${process.execPath})`;
+  const detail = {signal: how, node: process.version, nodePath: process.execPath};
+  if (!crashed) {
+    const memory = how === 'SIGKILL' ? ' The system stops a process this way when the machine runs out of memory.' : '';
+    return new RenderError('ERR_RENDER_FAILED', `${node} was stopped by a signal (${how}) while it rendered the page.${memory}`, detail);
+  }
+  const cause = withoutSegmenter ? ' It crashed again with Intl.Segmenter removed, so the fault is elsewhere in this Node or in a native module.' : '';
+  return new RenderError(
+    'ERR_RENDER_FAILED',
+    `${node} crashed (${how}) while it rendered the page. A fault in Node or in a native module causes this, not the page's code.${cause} Render with an official Node.js build of another version.`,
+    detail,
+  );
+}
+
+/**
+ * Run the page in a host process (page-host.mjs), stopping it after
+ * `timeoutMs`. The host runs the page in a worker thread, and it exits when
+ * this process goes away.
+ * @param {{entry: string, root: string, served: ServedSet | null, withoutSegmenter: boolean}} input
  * @param {number} timeoutMs
- * @param {ServedSet | null} served
- * @returns {Promise<any>}
+ * @returns {Promise<any>} the page's answer, or `{crashed: how}` when a
+ *   native crash ended the host
  */
-function runWorker(entry, root, timeoutMs, served) {
+function runWorker(input, timeoutMs) {
   return new Promise((resolve, reject) => {
-    const worker = new Worker(new URL('./page-worker.mjs', import.meta.url), {
-      workerData: {entry, root, served: served ? {dir: served.dir, integrations: [...served.integrations]} : null},
+    const data = {
+      ...input,
+      served: input.served ? {dir: input.served.dir, integrations: [...input.served.integrations]} : null,
+      timeoutMs,
+    };
+    const host = fork(fileURLToPath(new URL('./page-host.mjs', import.meta.url)), [JSON.stringify(data)], {
+      // Never the CLI's own flags (such as --input-type).
       execArgv: [],
-      stdout: true,
-      stderr: true,
-      resourceLimits: {maxOldGenerationSizeMb: 4096},
+      stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+      serialization: 'advanced',
     });
-    // The page's own writes to stdout/stderr never reach the CLI's output.
-    worker.stdout.resume();
-    worker.stderr.resume();
     let settled = false;
-    const timer = setTimeout(() => {
+    /** @param {() => void} settle */
+    const finish = settle => {
       if (settled) return;
       settled = true;
-      void worker.terminate();
-      reject(
-        new RenderError(
-          'ERR_RENDER_TIMEOUT',
-          `The page did not finish rendering within ${timeoutMs / 1000} seconds, so it was stopped. Look for a loop that never ends or a promise the page waits on.`,
-          {seconds: timeoutMs / 1000},
+      clearTimeout(timer);
+      host.kill('SIGKILL');
+      settle();
+    };
+    const timer = setTimeout(() => {
+      finish(() =>
+        reject(
+          new RenderError(
+            'ERR_RENDER_TIMEOUT',
+            `The page did not finish rendering within ${timeoutMs / 1000} seconds, so it was stopped. Look for a loop that never ends or a promise the page waits on.`,
+            {seconds: timeoutMs / 1000},
+          ),
         ),
       );
     }, timeoutMs);
-    worker.once('message', message => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      void worker.terminate();
-      resolve(message);
+    host.once('message', (/** @type {any} */ message) => {
+      finish(() => {
+        if (message?.hostError !== undefined) {
+          const text = String(message.hostError);
+          reject(
+            /ERR_WORKER_OUT_OF_MEMORY|heap out of memory/.test(text)
+              ? new RenderError('ERR_RENDER_FAILED', 'The page ran out of memory while rendering.')
+              : new RenderError('ERR_RENDER_FAILED', `The page could not be rendered: ${text.split('\n')[0]}`),
+          );
+        } else if (message?.hostExit !== undefined) {
+          reject(new RenderError('ERR_RENDER_FAILED', `The page stopped rendering without an answer (exit ${message.hostExit}).`));
+        } else {
+          resolve(message);
+        }
+      });
     });
-    worker.once('error', (/** @type {any} */ error) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      const out =
-        /ERR_WORKER_OUT_OF_MEMORY|heap out of memory/.test(String(error?.message ?? error))
-          ? new RenderError('ERR_RENDER_FAILED', 'The page ran out of memory while rendering.')
-          : new RenderError('ERR_RENDER_FAILED', `The page could not be rendered: ${String(error?.message ?? error).split('\n')[0]}`);
-      reject(out);
+    host.once('error', error => {
+      finish(() => reject(new RenderError('ERR_RENDER_FAILED', `The page could not be rendered: ${String(error?.message ?? error).split('\n')[0]}`)));
     });
-    worker.once('exit', code => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      reject(new RenderError('ERR_RENDER_FAILED', `The page stopped rendering without an answer (exit ${code}).`));
+    host.once('exit', (code, signal) => {
+      finish(() => {
+        const crash = crashOf(code, signal);
+        if (crash) resolve({crashed: crash});
+        else if (signal) reject(crashError(signal, {crashed: false, withoutSegmenter: input.withoutSegmenter}));
+        else reject(new RenderError('ERR_RENDER_FAILED', `The page stopped rendering without an answer (exit ${code}).`));
+      });
     });
   });
 }
 
+/**
+ * Run the page. When this Node crashes in Intl.Segmenter, run it once more
+ * without Intl.Segmenter and say so in a warning.
+ * @param {{entry: string, root: string, served: ServedSet | null}} input
+ * @param {number} timeoutMs
+ * @param {RenderWarning[]} warnings
+ */
+async function runPage(input, timeoutMs, warnings) {
+  const started = Date.now();
+  const first = await runWorker({...input, withoutSegmenter: false}, timeoutMs);
+  if (!first.crashed) return first;
+  if (!segmenterCrashes()) throw crashError(first.crashed, {crashed: true, withoutSegmenter: false});
+  const again = await runWorker({...input, withoutSegmenter: true}, Math.max(1000, timeoutMs - (Date.now() - started)));
+  if (again.crashed) throw crashError(again.crashed, {crashed: true, withoutSegmenter: true});
+  warnings.push(segmenterWarning());
+  return again;
+}
+
+/**
+ * The warning for a page rendered without Intl.Segmenter.
+ * @returns {RenderWarning}
+ */
+export function segmenterWarning() {
+  return {
+    code: 'node-crash',
+    message: `This Node build (${process.version} at ${process.execPath}) crashes in Intl.Segmenter, so the page rendered without it, and the output may differ slightly: initials and character counts (such as Avatar initials) can split a joined emoji, a flag, or a letter written with a separate accent mark. Render with an official Node.js build to remove the difference.`,
+  };
+}
+
 /**
  * Inline local images (src, srcset, poster and CSS url()) as data: URIs. A
  * link (`href`) loads nothing, so it is left alone.
@@ -370,9 +465,9 @@ export async function renderPage(entry, options = {}) {
   const dir = path.dirname(entry);
   const root = projectRootOf(dir);
   const served = options.served ?? null;
-  const message = await runWorker(entry, root, options.timeoutMs ?? RENDER_TIMEOUT_MS, served);
   /** @type {RenderWarning[]} */
   const warnings = [];
+  const message = await runPage({entry, root, served}, options.timeoutMs ?? RENDER_TIMEOUT_MS, warnings);
   if (!message.ok) {
     throw new RenderError(message.error.code, message.error.message, message.error.detail);
   }
@@ -522,15 +617,30 @@ export async function renderPage(entry, options = {}) {
       message: `<${t.component}> on line ${t.line} did not render the text "${t.text.length > 60 ? `${t.text.slice(0, 57)}...` : t.text}" it was given; it takes that text through a prop (often label=), so check its props.`,
     });
   }
-  for (const f of /** @type {string[]} */ (message.files ?? [])) {
-    const src = fs.readFileSync(f, 'utf8');
-    if (/\bResponsiveContainer\b/.test(src)) {
-      warnings.push({
-        code: 'chart-size',
-        message: `${path.basename(f)} sizes a chart with ResponsiveContainer, which has no size until a browser measures it, so the chart is empty here; give the chart a fixed width and height.`,
-      });
-      break;
-    }
+  // A chart the render did not draw is an empty box: a ResponsiveContainer
+  // holds only its sizing box, and a chart of fixed size an empty wrapper.
+  const blankCharts =
+    (markup.match(/<div class="recharts-responsive-container[" ][^>]*><div[^>]*><\/div><\/div>/g) ?? []).length +
+    (markup.match(/<div\b[^>]*\bclass="recharts-wrapper"[^>]*><\/div>/g) ?? []).length +
+    (message.chartsFailed ?? 0);
+  if (blankCharts > 0) {
+    warnings.push({
+      code: 'chart-size',
+      message: `${blankCharts === 1 ? 'A chart' : `${blankCharts} charts`} could not be drawn without a browser, so ${blankCharts === 1 ? 'it is' : 'they are'} empty here: the render draws a chart only when a module of the page (not an installed package) imports the chart, and its ResponsiveContainer, from recharts by name (\`import {LineChart} from 'recharts'\`).`,
+    });
+  }
+  if (message.chartsAlone) {
+    /** @type {Record<string, string>} */
+    const causes = {
+      changed: 'The page changed its charts once its effects ran (their data or props, or which charts it shows)',
+      rerendered: 'A component that makes a chart rendered again once the page\'s effects ran',
+      error: 'The page could not be drawn again without a browser',
+    };
+    const why = causes[message.chartsAlone] ?? causes.error;
+    warnings.push({
+      code: 'chart-size',
+      message: `${why}, so each chart was drawn by itself, as the first render gave it: a custom tick, label or shape in a chart sees React context defaults, not the values the page provides.`,
+    });
   }
   for (const sheet of /** @type {string[]} */ (message.skippedCss ?? [])) {
     warnings.push({
@@ -600,7 +710,7 @@ export async function renderPage(entry, options = {}) {
     '<meta name="color-scheme" content="light dark">' +
     `<meta name="generator" content="Astryx${options.version ? ` ${escapeHtml(options.version)}` : ''}">` +
     `<title>${escapeHtml(title)}</title>` +
-    `<style>${SCHEME_CSS}${css}</style></head><body>${markup}` +
+    `<style>${SCHEME_CSS}${markup.includes('class="recharts-responsive-container"') ? CHART_CSS : ''}${css}</style></head><body>${markup}` +
     `${sourceBlock(path.basename(entry), embedded)}</body></html>\n`;
   return {
     html,

package/foundation/render/ts-paths.d.mts

@@ -0,0 +1,63 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The path patterns of the config in `dir` (tsconfig.json, else
+ * jsconfig.json), or none. Comments and trailing commas are allowed.
+ * @param {string} dir
+ * @returns {PathPattern[] | null} null when neither file is there
+ */
+export function readPathsIn(dir: string): PathPattern[] | null;
+/**
+ * The pattern a specifier matches by TypeScript's rules, and what its `*`
+ * matched: an exact key first, else the wildcard key with the longest prefix.
+ * @param {PathPattern[]} patterns
+ * @param {string} spec
+ * @returns {{pattern: PathPattern, capture: string} | null}
+ */
+export function matchPath(patterns: PathPattern[], spec: string): {
+    pattern: PathPattern;
+    capture: string;
+} | null;
+/**
+ * The file a candidate path stands for: itself, with an extension, or its
+ * folder's index; null when none exists.
+ * @param {string} candidate
+ * @returns {string | null}
+ */
+export function existingFile(candidate: string): string | null;
+/**
+ * Resolve a specifier through path patterns: the first target that names an
+ * existing file wins.
+ * @param {PathPattern[]} patterns
+ * @param {string} spec
+ * @returns {string | null} the file, or null when the specifier matches no
+ *   pattern or no target exists
+ */
+export function resolvePath(patterns: PathPattern[], spec: string): string | null;
+export function candidatesOf(match: {
+    pattern: PathPattern;
+    capture: string;
+}): string[];
+export type PathPattern = {
+    /**
+     * - The key as written.
+     */
+    key: string;
+    /**
+     * - What comes before the key's `*` (all of it, for an exact key).
+     */
+    prefix: string;
+    /**
+     * - What comes after the key's `*`.
+     */
+    suffix: string;
+    /**
+     * - Whether the key holds a `*`.
+     */
+    wildcard: boolean;
+    /**
+     * - Absolute target patterns, in order.
+     */
+    targets: string[];
+};

package/foundation/render/ts-paths.mjs

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A project's `compilerOptions.paths` (tsconfig.json or jsconfig.json),
+ * read and matched by TypeScript's rules, for `astryx experimental render`:
+ * an exact key matches only itself; a key may hold one `*` anywhere, and the
+ * longest matching prefix wins; a target may hold one `*`, which takes what
+ * the key's `*` matched; targets are tried in order, and when none exists the
+ * import resolves as a package. Only bare specifiers are matched. Targets
+ * resolve from `baseUrl` (default: the config's folder).
+ *
+ * @position foundation/render — used by page-worker.mjs and embedded-imports.mjs
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * @typedef {object} PathPattern
+ * @property {string} key - The key as written.
+ * @property {string} prefix - What comes before the key's `*` (all of it, for an exact key).
+ * @property {string} suffix - What comes after the key's `*`.
+ * @property {boolean} wildcard - Whether the key holds a `*`.
+ * @property {string[]} targets - Absolute target patterns, in order.
+ */
+
+/** Extensions an extensionless candidate may stand for, in resolution order. */
+const EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs', '.mts', '.cts', '.json'];
+
+/**
+ * The path patterns of the config in `dir` (tsconfig.json, else
+ * jsconfig.json), or none. Comments and trailing commas are allowed.
+ * @param {string} dir
+ * @returns {PathPattern[] | null} null when neither file is there
+ */
+export function readPathsIn(dir) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) continue;
+    try {
+      const text = fs
+        .readFileSync(file, 'utf8')
+        .replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_, str) => str ?? '')
+        .replace(/,(\s*[}\]])/g, '$1');
+      const options = JSON.parse(text)?.compilerOptions ?? {};
+      const base = path.resolve(dir, typeof options.baseUrl === 'string' ? options.baseUrl : '.');
+      /** @type {PathPattern[]} */
+      const out = [];
+      for (const [key, targets] of Object.entries(options.paths ?? {})) {
+        if (!Array.isArray(targets)) continue;
+        const star = key.indexOf('*');
+        if (star !== key.lastIndexOf('*')) continue;
+        out.push({
+          key,
+          prefix: star === -1 ? key : key.slice(0, star),
+          suffix: star === -1 ? '' : key.slice(star + 1),
+          wildcard: star !== -1,
+          targets: targets
+            .filter(t => typeof t === 'string' && t.indexOf('*') === t.lastIndexOf('*'))
+            .map(t => path.resolve(base, t)),
+        });
+      }
+      return out;
+    } catch {
+      return [];
+    }
+  }
+  return null;
+}
+
+/**
+ * The pattern a specifier matches by TypeScript's rules, and what its `*`
+ * matched: an exact key first, else the wildcard key with the longest prefix.
+ * @param {PathPattern[]} patterns
+ * @param {string} spec
+ * @returns {{pattern: PathPattern, capture: string} | null}
+ */
+export function matchPath(patterns, spec) {
+  // TypeScript applies `paths` only to bare specifiers.
+  if (/^\.{1,2}(\/|$)|^\//.test(spec)) return null;
+  const exact = patterns.find(p => !p.wildcard && p.key === spec);
+  if (exact) return {pattern: exact, capture: ''};
+  /** @type {{pattern: PathPattern, capture: string} | null} */
+  let best = null;
+  for (const p of patterns) {
+    if (!p.wildcard) continue;
+    if (spec.length < p.prefix.length + p.suffix.length) continue;
+    if (!spec.startsWith(p.prefix) || !spec.endsWith(p.suffix)) continue;
+    if (best && best.pattern.prefix.length >= p.prefix.length) continue;
+    best = {pattern: p, capture: spec.slice(p.prefix.length, spec.length - p.suffix.length)};
+  }
+  return best;
+}
+
+/**
+ * The absolute paths a match names, one per target, in order.
+ * @param {{pattern: PathPattern, capture: string}} match
+ * @returns {string[]}
+ */
+export const candidatesOf = match => match.pattern.targets.map(t => t.replace('*', match.capture));
+
+/**
+ * The file a candidate path stands for: itself, with an extension, or its
+ * folder's index; null when none exists.
+ * @param {string} candidate
+ * @returns {string | null}
+ */
+export function existingFile(candidate) {
+  const isFile = (/** @type {string} */ f) => {
+    try {
+      return fs.statSync(f).isFile();
+    } catch {
+      return false;
+    }
+  };
+  if (isFile(candidate)) return candidate;
+  for (const ext of EXTENSIONS) if (isFile(candidate + ext)) return candidate + ext;
+  for (const ext of EXTENSIONS) if (isFile(path.join(candidate, `index${ext}`))) return path.join(candidate, `index${ext}`);
+  return null;
+}
+
+/**
+ * Resolve a specifier through path patterns: the first target that names an
+ * existing file wins.
+ * @param {PathPattern[]} patterns
+ * @param {string} spec
+ * @returns {string | null} the file, or null when the specifier matches no
+ *   pattern or no target exists
+ */
+export function resolvePath(patterns, spec) {
+  const match = matchPath(patterns, spec);
+  if (!match) return null;
+  for (const candidate of candidatesOf(match)) {
+    const file = existingFile(candidate);
+    if (file) return file;
+  }
+  return null;
+}

package/foundation/response/error-codes.doc.mjs

@@ -332,19 +332,19 @@ export const doc = {
       value: 'ERR_RENDER_FAILED',
       stability: 'experimental',
       description:
-        'The page threw while rendering. Nothing was written. Raised only by the experimental render command.',
+        'The page threw while rendering, or Node crashed while it rendered the page. Nothing was written. Raised only by the experimental render command.',
     },
     {
       value: 'ERR_RENDER_NOT_ASTRYX',
       stability: 'experimental',
       description:
-        '`render --reverse` was given a file with no embedded source and no Astryx markup. Nothing was written. Raised only by the experimental render command.',
+        '`render --reverse` was given a file that a render did not write, with no embedded source and no Astryx markup. Nothing was written. Raised only by the experimental render command.',
     },
     {
       value: 'ERR_RENDER_SOURCE_DAMAGED',
       stability: 'experimental',
       description:
-        '`render --reverse` refused the received file, and nothing was written: its embedded source is damaged (not valid, or a file does not match its checksum), lists a path twice, carries a module, stylesheet or JSON file the page does not reach through its own imports, or an image, font or media file whose bytes are not one, or carries a file a render never embeds: a dotfile or dot-folder, anything under node_modules, a package manifest, lockfile or tool configuration, a file a test, story or benchmark runner would run, or any kind but a page module, stylesheet, JSON file or image. Raised only by the experimental render command.',
+        '`render --reverse` refused the received file, and nothing was written: its embedded source was removed (a file a render wrote, with no Astryx components left to rebuild from) or is damaged (not valid, or a file does not match its checksum), lists a path twice, carries a module, stylesheet or JSON file the page does not reach through its own imports, or an image, font or media file whose bytes are not one, or carries a file a render never embeds: a dotfile or dot-folder, anything under node_modules, a package manifest, lockfile or tool configuration, a file a test, story or benchmark runner would run, or any kind but a page module, stylesheet, JSON file or image. Raised only by the experimental render command.',
     },
   ],
 };

package/foundation/response/error-codes.mjs

@@ -298,8 +298,9 @@ export const ERROR_CODES = Object.freeze({
    */
   ERR_RENDER_FAILED: 'ERR_RENDER_FAILED',
   /**
-   * `render --reverse` was given an HTML file that holds no Astryx markup and
-   * no embedded source, so there is nothing to rebuild. Nothing was written.
+   * `render --reverse` was given an HTML file that a render did not write and
+   * that holds no Astryx markup and no embedded source, so there is nothing
+   * to rebuild. Nothing was written.
    */
   ERR_RENDER_NOT_ASTRYX: 'ERR_RENDER_NOT_ASTRYX',
   /**

package/foundation/text/levenshtein.d.mts

@@ -19,6 +19,11 @@
  * @param {number} [max] - The largest distance the caller can use. When
  *   given, a larger distance answers `max + 1`, and only the cells within
  *   `max` of the diagonal are computed.
+ * @param {{swaps?: boolean}} [options] - With `swaps` and a `max`, two
+ *   adjacent letters swapped cost one edit, not two (the optimal string
+ *   alignment distance).
  * @returns {number}
  */
-export function levenshteinDistance(a: string, b: string, max?: number): number;
+export function levenshteinDistance(a: string, b: string, max?: number, { swaps }?: {
+    swaps?: boolean;
+}): number;

package/foundation/text/levenshtein.mjs

@@ -19,11 +19,15 @@
  * @param {number} [max] - The largest distance the caller can use. When
  *   given, a larger distance answers `max + 1`, and only the cells within
  *   `max` of the diagonal are computed.
+ * @param {{swaps?: boolean}} [options] - With `swaps` and a `max`, two
+ *   adjacent letters swapped cost one edit, not two (the optimal string
+ *   alignment distance).
  * @returns {number}
  */
-export function levenshteinDistance(a, b, max) {
-  if (max !== undefined) return distanceWithin(a, b, max);
-  const m = a.length, n = b.length;
+export function levenshteinDistance(a, b, max, {swaps = false} = {}) {
+  if (max !== undefined) return distanceWithin(a, b, max, swaps);
+  const m = a.length,
+    n = b.length;
   // Early exit: the distance is always ≥ |m − n|, so once the length gap
   // exceeds the loosest fuzzy-match threshold any caller uses (the hook
   // suggester keeps distance ≤ 5) the pair can never match — skip the O(m·n)
@@ -36,9 +40,10 @@ export function levenshteinDistance(a, b, max) {
   for (let j = 0; j <= n; j++) dp[0][j] = j;
   for (let i = 1; i <= m; i++) {
     for (let j = 1; j <= n; j++) {
-      dp[i][j] = a[i-1] === b[j-1]
-        ? dp[i-1][j-1]
-        : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
     }
   }
   return dp[m][n];
@@ -51,11 +56,13 @@ export function levenshteinDistance(a, b, max) {
  * @param {string} a
  * @param {string} b
  * @param {number} max
+ * @param {boolean} swaps - two adjacent letters swapped cost one edit
  * @returns {number}
  */
-function distanceWithin(a, b, max) {
+function distanceWithin(a, b, max, swaps) {
   const over = max + 1;
   if (Math.abs(a.length - b.length) > max) return over;
+  let before = new Array(b.length + 1).fill(over);
   let previous = new Array(b.length + 1).fill(over);
   let current = new Array(b.length + 1).fill(over);
   for (let j = 0; j <= Math.min(b.length, max); j++) previous[j] = j;
@@ -67,18 +74,27 @@ function distanceWithin(a, b, max) {
     let rowMin = current[0];
     for (let j = from; j <= to; j++) {
       const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      const value = Math.min(
+      let value = Math.min(
         previous[j - 1] + cost,
         previous[j] + 1,
         current[j - 1] + 1,
         over,
       );
+      if (
+        swaps &&
+        i > 1 &&
+        j > 1 &&
+        a[i - 1] === b[j - 2] &&
+        a[i - 2] === b[j - 1]
+      ) {
+        value = Math.min(value, before[j - 2] + 1);
+      }
       current[j] = value;
       if (value < rowMin) rowMin = value;
     }
     // Every later cell costs at least this row's least.
     if (rowMin >= over) return over;
-    [previous, current] = [current, previous];
+    [before, previous, current] = [previous, current, before];
   }
   return Math.min(previous[b.length], over);
 }

package/foundation/text/suggest-order.d.mts

@@ -18,15 +18,22 @@ export function nameWords(text: string): string[];
  * when it carries some of them, the items that carry none are left out. When
  * no item carries one, nothing is left out. The list only ever gets shorter,
  * and its order does not change.
+ *
+ * With `typos`, a near name (one or two slips from the typed name, as
+ * `ButonGroup` or `ButtonGorup` for ButtonGroup) ranks just below the names
+ * that carry every typed word and above the rest. With `closest` too, near
+ * names stay in the list whatever the cut leaves out, and the list is never
+ * longer than it is without `typos`.
  * @template T
  * @param {string} typedName
  * @param {T[]} items
  * @param {(item: T) => Array<string | undefined>} namesOf
- * @param {{closest?: boolean}} [options]
+ * @param {{closest?: boolean, typos?: boolean}} [options]
  * @returns {T[]}
  */
 export function orderByAffinity<T>(typedName: string, items: T[], namesOf: (item: T) => Array<string | undefined>, options?: {
     closest?: boolean;
+    typos?: boolean;
 }): T[];
 /**
  * Docs route suggestions, closest to the typed route first. When every