@astryxdesign/cli 0.7.12-canary.d84658f → 0.7.12-canary.dfd75a6

package/foundation/discovery/icon-set-writer.mjs

@@ -48,6 +48,7 @@ import {
   exportValueKind,
   followedExportNames,
   moduleExportOrigin,
+  staticExportBindings,
 } from './module-exports.mjs';
 
 /** @typedef {import('./icon-set-discovery.mjs').DiscoveredIconSet} DiscoveredIconSet */
@@ -100,10 +101,19 @@ export function iconIdOf(name) {
 
 /**
  * The name an icon set exports an icon as: PascalCase ending in `Icon`
- * (`Trash2` → `Trash2Icon`; `TrashIcon` stays).
+ * (`Trash2` → `Trash2Icon`; `TrashIcon` stays). A JavaScript name cannot
+ * start with a digit, so a name that starts with one is refused.
+ * {@link iconNaming} keeps a library prefix to prevent this (`fa0` →
+ * `Fa0Icon`).
  * @param {string} name
  */
 export function iconExportName(name) {
+  if (/^[0-9]/u.test(name)) {
+    throw new IconSetAuthoringError(
+      `The icon id "${iconIdOf(name)}" starts with a digit, and an export name cannot. Pass --id with an id that starts with a letter.`,
+      'ERR_INVALID_ARGUMENT',
+    );
+  }
   const pascal = name[0].toUpperCase() + name.slice(1);
   return pascal.endsWith('Icon') ? pascal : `${pascal}Icon`;
 }
@@ -146,7 +156,11 @@ function packageDirOf(cwd) {
  * `selector` names, else the only set.
  * @param {string} cwd
  * @param {string} [selector] a set name
- * @returns {Promise<{packageDir: string, pkg: Record<string, any>, root: string, set: DiscoveredIconSet, sets: DiscoveredIconSet[]}>}
+ * The set's `module` names the package as package.json names it now;
+ * `moduleRenamed` says the data file still names an old name, so a command
+ * writes the data file even when nothing else changes; `moduleUpdate` gives
+ * the old and the new name for the receipt, else null.
+ * @returns {Promise<{packageDir: string, pkg: Record<string, any>, root: string, set: DiscoveredIconSet, sets: DiscoveredIconSet[], moduleRenamed: boolean, moduleUpdate: {previous: string, module: string} | null}>}
  */
 export async function findLocalIconSet(cwd, selector) {
   const packageDir = packageDirOf(cwd);
@@ -190,12 +204,20 @@ export async function findLocalIconSet(cwd, selector) {
     ? found.sets.filter(set => set.name === selector)
     : found.sets;
   if (named.length === 1) {
+    const set = {...named[0], packageDir};
+    const module = moduleInPackage(set.data.module, pkg.name);
+    const moduleUpdate =
+      module !== set.data.module ? {previous: set.data.module, module} : null;
+    const moduleRenamed = moduleUpdate != null;
+    if (moduleRenamed) set.data = {...set.data, module};
     return {
       packageDir,
       pkg,
       root,
-      set: {...named[0], packageDir},
+      set,
       sets: found.sets,
+      moduleRenamed,
+      moduleUpdate,
     };
   }
   const broken = selector
@@ -229,6 +251,22 @@ export async function findLocalIconSet(cwd, selector) {
   );
 }
 
+/**
+ * The data file's `module` in the package as it is named now. The data file
+ * belongs to the CLI, so after a package rename the next write gives the new
+ * name (`@acme/old/solid` → `@acme/new/solid`). A ./ path, or a package
+ * with no name, is left as it is.
+ * @param {string} module
+ * @param {unknown} name the package.json `name`
+ */
+function moduleInPackage(module, name) {
+  if (typeof name !== 'string' || name === '' || module.startsWith('.')) {
+    return module;
+  }
+  const owner = iconModulePackage(module);
+  return owner === name ? module : `${name}${module.slice(owner.length)}`;
+}
+
 /** The data file's fields, in the order the file is written. */
 const DATA_KEYS = [
   'schemaVersion',
@@ -599,7 +637,7 @@ const SCREAMING_CASE_RE = /^[A-Z][A-Z0-9_]+$/u;
  * set declares an adapter, also data exports, camelCase included: objects,
  * and plain strings only in a library whose candidates are all strings.
  * Left out: `default`, `Icon`, `…Provider` and `…Context` components, SCREAMING_CASE constants, number and boolean
- * exports, and `exclude`.
+ * exports, packs of other exports ({@link isIconPack}), and `exclude`.
  * @param {string} file
  * @param {{adapter?: boolean, exclude?: string[]}} [options] `exclude`: export
  *   names that are not icons
@@ -609,7 +647,9 @@ function iconCandidates(file, {adapter = false, exclude = []} = {}) {
   const skipped = new Set(exclude);
   /** @type {Array<{name: string, adapt: boolean, scalar: string | null}>} */
   const out = [];
-  for (const name of followedExportNames(file)) {
+  const names = followedExportNames(file);
+  const exported = new Set(names);
+  for (const name of names) {
     if (name === 'default' || name === 'Icon' || skipped.has(name)) continue;
     // A context provider or context (`LucideProvider`) is a component that
     // draws nothing.
@@ -622,7 +662,8 @@ function iconCandidates(file, {adapter = false, exclude = []} = {}) {
     } else if (
       adapter &&
       kind === 'data' &&
-      /^[A-Za-z][A-Za-z0-9]*$/u.test(name)
+      /^[A-Za-z][A-Za-z0-9]*$/u.test(name) &&
+      !isIconPack(file, name, exported)
     ) {
       const scalar = exportScalarType(file, name);
       // A number or a boolean draws nothing; a string may be SVG markup.
@@ -637,6 +678,20 @@ function iconCandidates(file, {adapter = false, exclude = []} = {}) {
     : out;
 }
 
+/**
+ * Whether a data export is a pack: an object whose keys are all other
+ * exports of the module, such as `fas` in a library that also exports
+ * `faXmark` and `faHouse`. A pack holds icons but draws nothing.
+ * @param {string} file
+ * @param {string} name
+ * @param {Set<string>} exported every export name of the module
+ */
+function isIconPack(file, name, exported) {
+  const bindings = staticExportBindings(file, name);
+  if (bindings == null || bindings.size < 2) return false;
+  return [...bindings.keys()].every(key => key !== name && exported.has(key));
+}
+
 /**
  * The exports of a library that are not icons and that wrapping it leaves
  * out (`Icon`, `LucideProvider`, `createLucideIcon`, constants), so the
@@ -690,7 +745,9 @@ export function libraryPrefix(names) {
 
 /**
  * An export's id and the name the set exports it as, with the library prefix
- * left out: `featherEye` with prefix `feather` is id `eye`, `EyeIcon`.
+ * left out: `featherEye` with prefix `feather` is id `eye`, `EyeIcon`. A
+ * name that would start with a digit keeps the prefix (`fa500px` is
+ * `fa-500px`, `Fa500pxIcon`).
  * @param {string} name
  * @param {string[]} prefix
  * @returns {{id: string, name: string}}
@@ -698,9 +755,12 @@ export function libraryPrefix(names) {
 export function iconNaming(name, prefix) {
   const all = iconIdOf(name).split('-');
   // Only a name that starts with the prefix, and has more after it, loses it.
+  // A name that would then start with a digit keeps the prefix: `fa0` is
+  // `fa-0`, `Fa0Icon`.
   const strip =
     all.length > prefix.length &&
-    prefix.every((word, index) => all[index] === word);
+    prefix.every((word, index) => all[index] === word) &&
+    !/^[0-9]/u.test(all[prefix.length]);
   if (!strip) prefix = [];
   const words = all.slice(prefix.length);
   const id = words.join('-');
@@ -1423,10 +1483,39 @@ function terminated(statement) {
     : `${statement};`;
 }
 
+/** Syntax-tree fields that only say how a file is laid out. */
+const LAYOUT_KEYS = new Set([
+  'start',
+  'end',
+  'loc',
+  'range',
+  'extra',
+  'leadingComments',
+  'trailingComments',
+  'innerComments',
+]);
+
+/**
+ * The top-level statements of a module as syntax trees without positions,
+ * comments, or raw text, one string each. A formatter changes line breaks,
+ * quotes, semicolons, trailing commas, and the wrapping of long type
+ * arguments; none of these change the tree.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function statementTrees(text) {
+  const ast = parse(text, {sourceType: 'module', plugins: ['typescript']});
+  return ast.program.body.map(node =>
+    JSON.stringify(node, (key, value) =>
+      LAYOUT_KEYS.has(key) ? undefined : value,
+    ),
+  );
+}
+
 /**
  * Whether a generated declaration file declares what its generated module
  * gives, statement by statement however a formatter left either file
- * ({@link generatedStatements}); the header comment is ignored.
+ * ({@link statementTrees}); the header comment is ignored.
  * @param {string} actual the declaration file as it is
  * @param {string} expected {@link generatedTypesText} for the module
  * @param {string} label the declaration file's path, for a parse error
@@ -1434,11 +1523,19 @@ function terminated(statement) {
 export function generatedTypesMatch(actual, expected, label) {
   let have;
   try {
-    have = generatedStatements(actual, label);
+    have = statementTrees(actual);
   } catch {
     return false;
   }
-  const want = generatedStatements(expected, label);
+  let want;
+  try {
+    want = statementTrees(expected);
+  } catch (error) {
+    throw new IconSetAuthoringError(
+      `The declarations written for ${label} do not parse (${error instanceof Error ? error.message : String(error)}).`,
+      'ERR_INVALID_ARGUMENT',
+    );
+  }
   return have.length === want.length && have.every((s, i) => s === want[i]);
 }
 
@@ -1817,10 +1914,11 @@ export function generatedNamesOf(packageDir, generated, from, source) {
  * differently; and a refresh changes only the icons its module supplies.
  * @param {string} packageDir
  * @param {string} generated
- * @returns {Map<string, {module: string, source: string}>}
+ * @returns {Map<string, {module: string, source: string, adapt: boolean}>}
+ *   `adapt`: the set's adapter turns the export into a component
  */
 export function generatedOrigins(packageDir, generated) {
-  /** @type {Map<string, {module: string, source: string}>} */
+  /** @type {Map<string, {module: string, source: string, adapt: boolean}>} */
   const origins = new Map();
   const file = path.join(packageDir, generated);
   if (!fs.existsSync(file)) return origins;
@@ -1847,6 +1945,7 @@ export function generatedOrigins(packageDir, generated) {
       origins.set(reexport[2] ?? reexport[1], {
         module: fromRoot(reexport[3]),
         source: reexport[1],
+        adapt: false,
       });
       continue;
     }
@@ -1857,6 +1956,7 @@ export function generatedOrigins(packageDir, generated) {
       origins.set(adapted[2], {
         module: fromRoot(adapted[3]),
         source: adapted[1],
+        adapt: true,
       });
       continue;
     }
@@ -1867,6 +1967,7 @@ export function generatedOrigins(packageDir, generated) {
       origins.set(adaptedDefault[1], {
         module: fromRoot(adaptedDefault[2]),
         source: 'default',
+        adapt: true,
       });
     }
   }

package/foundation/render/page-host.d.mts

@@ -0,0 +1,4 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export {};

package/foundation/render/page-host.mjs

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Host process for `astryx experimental render`: runs page-worker.mjs
+ * in a worker thread and sends its one answer to the CLI.
+ *
+ * A crash of Node itself ends only this process, never the CLI. The page runs
+ * in a thread, so this process can still act while the page loops: it exits
+ * when the CLI goes away (the IPC channel closes) or when its own time limit
+ * passes, so a page that never finishes never outlives the CLI.
+ *
+ * @input argv[2]: JSON {entry, root, served, withoutSegmenter, timeoutMs}
+ * @output one IPC message: the worker's answer, or {hostError: message}, or
+ *   {hostExit: code}
+ * @position foundation/render — started by render-page.mjs
+ */
+
+import {Worker} from 'node:worker_threads';
+
+/** @type {{entry: string, root: string, served: {dir: string, integrations: string[]} | null, withoutSegmenter: boolean, timeoutMs: number}} */
+const input = JSON.parse(process.argv[2] ?? '{}');
+
+/** @param {unknown} message */
+function answer(message) {
+  if (!process.connected) process.exit(0);
+  process.send?.(message, () => process.exit(0));
+}
+
+process.once('disconnect', () => process.exit(0));
+// A margin past the CLI's own limit, so the CLI reports the timeout first.
+setTimeout(() => process.exit(0), input.timeoutMs + 5000);
+
+const worker = new Worker(new URL('./page-worker.mjs', import.meta.url), {
+  workerData: input,
+  execArgv: [],
+  stdout: true,
+  stderr: true,
+  resourceLimits: {maxOldGenerationSizeMb: 4096},
+});
+// The page's own writes to stdout/stderr never reach the CLI's output.
+worker.stdout.resume();
+worker.stderr.resume();
+worker.once('message', answer);
+worker.once('error', (/** @type {any} */ error) => answer({hostError: String(error?.message ?? error)}));
+worker.once('exit', code => answer({hostExit: code}));

package/foundation/render/page-worker.mjs

@@ -5,8 +5,10 @@
  * the project (TypeScript, JSX and StyleX compiled in memory) and renders its
  * default export to static markup with the project's own React.
  *
- * It runs in a worker thread so a page that never finishes rendering can be
- * stopped, and so nothing the page prints reaches the CLI's own output.
+ * It runs in a worker thread of a small host process (page-host.mjs), so a
+ * page that never finishes rendering can be stopped, nothing the page prints
+ * reaches the CLI's own output, and a crash of Node itself ends only the host,
+ * never the CLI.
  *
  * Outside a project, the Astryx packages the page's folder lacks resolve
  * from the package set the CLI runs from (served-packages.mjs), and React and
@@ -16,10 +18,10 @@
  * so the server render sets them aside and draws them after it with React
  * DOM in a small document (charts.mjs).
  *
- * @input workerData {entry, root, served}
+ * @input workerData {entry, root, served, withoutSegmenter}
  * @output one message: {ok: true, markup, css, files, texts, logs} or
  *   {ok: false, error: {code, message, detail?}}
- * @position foundation/render — started by render-page.mjs
+ * @position foundation/render — started by page-host.mjs
  */
 
 import * as fs from 'node:fs';
@@ -38,9 +40,13 @@ import {CHART_GLOBAL, CHART_ROOTS, chartDocument, chartSize, markLegends} from '
 
 /** @typedef {{level: string, text: string}} PageLog */
 
-/** @type {{entry: string, root: string, served: {dir: string, integrations: string[]} | null}} */
+/** @type {{entry: string, root: string, served: {dir: string, integrations: string[]} | null, withoutSegmenter?: boolean}} */
 const {entry, root} = workerData;
 
+// Some Node builds crash in Intl.Segmenter. Without it, Core splits text by
+// code points, so a joined emoji can count as several characters.
+if (workerData.withoutSegmenter) delete (/** @type {any} */ (Intl)).Segmenter;
+
 /** The package set, for a page outside a project whose folder has no Core of its own. */
 const served = workerData.served && findNodeModulesPackage(path.dirname(entry), '@astryxdesign/core') === null ? workerData.served : null;
 const ROOT_PREFIX = root.endsWith(path.sep) ? root : root + path.sep;

package/foundation/render/render-page.d.mts

@@ -1,6 +1,11 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * The warning for a page rendered without Intl.Segmenter.
+ * @returns {RenderWarning}
+ */
+export function segmenterWarning(): RenderWarning;
 /**
  * Render a page module to one self-contained HTML file.
  * @param {string} entry absolute path of the page module
@@ -20,7 +25,7 @@ export const RENDER_TIMEOUT_MS: 60000;
 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.
  */
 /**
@@ -46,15 +51,11 @@ export class RenderError extends Error {
     code: string;
     detail: Record<string, unknown> | undefined;
 }
-export type ServedSet = {
-    dir: string;
-    integrations: readonly string[];
-};
 export type RenderWarning = {
     /**
      * - What kind of problem.
      */
-    code: "dropped-children" | "remote-asset" | "missing-asset" | "page-output" | "page-script" | "no-astryx-styles" | "chart-size" | "not-embedded";
+    code: "dropped-children" | "remote-asset" | "missing-asset" | "page-output" | "page-script" | "no-astryx-styles" | "chart-size" | "not-embedded" | "node-crash";
     /**
      * - What happened and what to do, in one sentence.
      */
@@ -98,3 +99,7 @@ export type RenderedPage = {
         dir: string;
     }[];
 };
+export type ServedSet = {
+    dir: string;
+    integrations: readonly string[];
+};

package/foundation/render/render-page.mjs

@@ -18,7 +18,8 @@
 
 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';
@@ -34,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.
  */
 
@@ -221,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']);
+
+/**
+ * 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;
+}
+
 /**
- * Run the page in a worker, stopping it after `timeoutMs`.
- * @param {string} entry
- * @param {string} root
+ * 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.
@@ -371,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);
   }

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

@@ -332,7 +332,7 @@ 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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.7.12-canary.d84658f",
+  "version": "0.7.12-canary.dfd75a6",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -125,7 +125,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.7.12-canary.d84658f"
+    "@astryxdesign/core": "0.7.12-canary.dfd75a6"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -133,10 +133,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.12-canary.d84658f",
-    "@astryxdesign/core": "0.7.12-canary.d84658f",
-    "@astryxdesign/lab": "0.7.12-canary.d84658f",
-    "@astryxdesign/theme-neutral": "0.7.12-canary.d84658f",
+    "@astryxdesign/charts": "0.7.12-canary.dfd75a6",
+    "@astryxdesign/core": "0.7.12-canary.dfd75a6",
+    "@astryxdesign/lab": "0.7.12-canary.dfd75a6",
+    "@astryxdesign/theme-neutral": "0.7.12-canary.dfd75a6",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",