@astryxdesign/cli 0.7.12-canary.f543ec7 → 0.7.12

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/discovery/template-adapter.mjs

@@ -2100,8 +2100,8 @@ export function extractComponents(pagePath) {
  */
 export function componentsInSource(src) {
   // Match JSX opening tags, e.g. `<Section` or the legacy `<XDSSection`.
-  // Templates author bare component names post un-prefix migration
-  // (P2380608025), so the `XDS` prefix is optional. Anchoring on the `<`
+  // Templates author bare component names post un-prefix migration,
+  // so the `XDS` prefix is optional. Anchoring on the `<`
   // JSX-tag boundary keeps this precise (avoids matching imports/comments/
   // identifiers) while remaining prefix-agnostic.
   //

package/foundation/doc-compiler/import.d.mts

@@ -17,7 +17,11 @@ export function importDocModule(file: string): Promise<any>;
 export function importTemplateModule(file: string): Promise<any>;
 /**
  * Import a module natively, by file URL: how the docs API, search, and the
- * unchecked component and hook readers have always imported docs.
+ * unchecked component and hook readers have always imported docs. A `.ts`
+ * file goes through jiti, as {@link importDocModule} imports it: Node cannot
+ * strip types from a file under node_modules, and below 22.18 it does not
+ * strip types at all, so a plain import of an installed or linked
+ * integration's `.doc.ts` fails.
  * @param {string} file
  * @returns {Promise<any>}
  */

package/foundation/doc-compiler/import.mjs

@@ -24,7 +24,12 @@
 
 import {pathToFileURL} from 'node:url';
 import {createJiti} from 'jiti';
-import {importUserModule} from '../fs/module-loader.mjs';
+import {importUrl} from '../fs/import-url.mjs';
+import {
+  importUserModule,
+  readFreshInTurn,
+  readInTurn,
+} from '../fs/module-loader.mjs';
 import {fileStamp, recordContentRead} from '../fs/read-record.mjs';
 
 /** @type {ReturnType<typeof createJiti> | undefined} */
@@ -78,6 +83,28 @@ function freshUrl(file) {
   return url.href;
 }
 
+/**
+ * Import `file` from `url`, in its turn with every other read of the file in
+ * this process (`readInTurn`, ../fs/module-loader.mjs).
+ * @param {string} file
+ * @param {string} url
+ * @returns {Promise<any>}
+ */
+function importInTurn(file, url) {
+  return readInTurn(file, () => importUrl(url));
+}
+
+/**
+ * Import `file` again, for a change, as a new module. Node chooses its format
+ * as for the first import. The read takes its turn without the file's
+ * CommonJS cache entry (`readFreshInTurn`, ../fs/module-loader.mjs).
+ * @param {string} file
+ * @returns {Promise<any>}
+ */
+function importFresh(file) {
+  return readFreshInTurn(file, () => importUrl(freshUrl(file)));
+}
+
 /**
  * Import a component, hook, topic, or self-doc module: `.ts` through jiti,
  * anything else natively.
@@ -105,28 +132,35 @@ export function importTemplateModule(file) {
         jsxJiti ??= createJiti(import.meta.url, {jsx: true});
         return jsxJiti.import(first);
       }
-      return import(`file://${first}`);
+      return importInTurn(first, `file://${first}`);
     },
     changed =>
       changed.endsWith('.ts')
         ? createJiti(import.meta.url, {jsx: true, moduleCache: false}).import(
             changed,
           )
-        : import(freshUrl(changed)),
+        : importFresh(changed),
   );
 }
 
 /**
  * Import a module natively, by file URL: how the docs API, search, and the
- * unchecked component and hook readers have always imported docs.
+ * unchecked component and hook readers have always imported docs. A `.ts`
+ * file goes through jiti, as {@link importDocModule} imports it: Node cannot
+ * strip types from a file under node_modules, and below 22.18 it does not
+ * strip types at all, so a plain import of an installed or linked
+ * integration's `.doc.ts` fails.
  * @param {string} file
  * @returns {Promise<any>}
  */
 export function importNativeModule(file) {
+  if (file.endsWith('.ts')) {
+    return importDocModule(file);
+  }
   return importCurrent(
     file,
     'native',
-    first => import(pathToFileURL(first).href),
-    changed => import(freshUrl(changed)),
+    first => importInTurn(first, pathToFileURL(first).href),
+    changed => importFresh(changed),
   );
 }

package/foundation/fs/import-url.d.mts

@@ -0,0 +1,20 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file The dynamic import of an authored module by its file URL.
+ *
+ * @input An absolute `file:` URL, with any query its caller adds to name a
+ *   fresh module.
+ * @output The module's namespace object, as a plain `import()` gives it.
+ * @position Called by the doc importers (../doc-compiler/import.mjs). The
+ *   node test project loads this file natively, as the CLI does
+ *   (vitest.config.ts). The doc files that a catalog command imports then load
+ *   natively as well, without a request to the test runner for each of them.
+ */
+/**
+ * Import the module at `url`.
+ * @param {string} url an absolute `file:` URL
+ * @returns {Promise<any>}
+ */
+export function importUrl(url: string): Promise<any>;

package/foundation/fs/import-url.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The dynamic import of an authored module by its file URL.
+ *
+ * @input An absolute `file:` URL, with any query its caller adds to name a
+ *   fresh module.
+ * @output The module's namespace object, as a plain `import()` gives it.
+ * @position Called by the doc importers (../doc-compiler/import.mjs). The
+ *   node test project loads this file natively, as the CLI does
+ *   (vitest.config.ts). The doc files that a catalog command imports then load
+ *   natively as well, without a request to the test runner for each of them.
+ */
+
+/**
+ * Import the module at `url`.
+ * @param {string} url an absolute `file:` URL
+ * @returns {Promise<any>}
+ */
+export function importUrl(url) {
+  return import(url);
+}

package/foundation/fs/module-loader.d.mts

@@ -4,9 +4,9 @@
 /**
  * Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` use
  * native dynamic import for ordinary cached reads. A fresh `.ts` read uses a
- * no-cache jiti instance. A fresh CommonJS `.js` read evicts and reloads through
- * `require`; an ESM `.js` or `.mjs` read uses a cache-busted file URL. The
- * nearest package.json `type` decides `.js`, matching Node's package scopes.
+ * no-cache jiti instance. Any other fresh read drops the module from the
+ * require cache and imports a cache-busted file URL. Node then chooses its
+ * format as for the first read, so a fresh read gives what a first read gives.
  * Normal loads retain module caching. `fresh` rereads a file that changed
  * during this process: one a codemod rewrote, or an edited doc file (the doc
  * importers in ../doc-compiler/import.mjs read each change once).
@@ -29,6 +29,27 @@ export function importUserModule(file: string, { fresh }?: {
  * @returns {Promise<Record<string, unknown>>}
  */
 export function importThemeArtifact(specifier: string, cwd: string): Promise<Record<string, unknown>>;
+/**
+ * Run `read`, an import of `file`, once the imports of `file` started before
+ * it have ended. Imports of other files do not wait. A fresh read removes the
+ * file from Node's CommonJS cache. A CommonJS import still in progress needs
+ * that entry until it ends.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readInTurn<T>(file: string, read: () => Promise<T>): Promise<T>;
+/**
+ * Run `read`, a fresh import of `file`, in the file's turn (`readInTurn`),
+ * once the file is gone from Node's CommonJS cache. A new URL names a new ES
+ * module only, so a CommonJS module also needs its cache entry gone.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readFreshInTurn<T>(file: string, read: () => Promise<T>): Promise<T>;
 /**
  * Import a user-authored module, take its default export, and validate it
  * through an authoring parser. This is the single load/validation boundary for

package/foundation/fs/module-loader.mjs

@@ -40,30 +40,6 @@ function getJiti() {
   return jitiInstance;
 }
 
-/**
- * Node treats `.js` as ESM only inside the nearest package scope whose
- * package.json declares `"type": "module"`; no package.json defaults to
- * CommonJS.
- * @param {string} file
- * @returns {boolean}
- */
-function isCommonJsFile(file) {
-  let dir = path.dirname(file);
-  for (;;) {
-    const packageJson = path.join(dir, 'package.json');
-    if (fs.existsSync(packageJson)) {
-      try {
-        return JSON.parse(fs.readFileSync(packageJson, 'utf-8')).type !== 'module';
-      } catch {
-        return true;
-      }
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) return true;
-    dir = parent;
-  }
-}
-
 let loadsInFlight = 0;
 /** @type {typeof process.stdout.write | undefined} */
 let realStdoutWrite;
@@ -104,9 +80,9 @@ async function withStdoutOnStderr(load) {
 /**
  * Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` use
  * native dynamic import for ordinary cached reads. A fresh `.ts` read uses a
- * no-cache jiti instance. A fresh CommonJS `.js` read evicts and reloads through
- * `require`; an ESM `.js` or `.mjs` read uses a cache-busted file URL. The
- * nearest package.json `type` decides `.js`, matching Node's package scopes.
+ * no-cache jiti instance. Any other fresh read drops the module from the
+ * require cache and imports a cache-busted file URL. Node then chooses its
+ * format as for the first read, so a fresh read gives what a first read gives.
  * Normal loads retain module caching. `fresh` rereads a file that changed
  * during this process: one a codemod rewrote, or an edited doc file (the doc
  * importers in ../doc-compiler/import.mjs read each change once).
@@ -251,31 +227,77 @@ async function importModule(file, fresh) {
   if (fresh && file.endsWith('.ts')) {
     return await createJiti(import.meta.url, {moduleCache: false}).import(file);
   }
-  if (fresh && file.endsWith('.js') && isCommonJsFile(file)) {
-    const resolved = requireFromHere.resolve(file);
-    delete requireFromHere.cache[resolved];
-    const value = requireFromHere(file);
-    if (
-      value != null &&
-      typeof value === 'object' &&
-      value.__esModule === true &&
-      Object.prototype.hasOwnProperty.call(value, 'default')
-    ) {
-      return value;
-    }
-    return {
-      ...(value != null && typeof value === 'object' ? value : {}),
-      default: value,
-    };
-  }
   if (file.endsWith('.ts')) {
     return await getJiti().import(file);
   }
   const url = pathToFileURL(file);
-  if (fresh) {
-    url.searchParams.set('astryx-fresh', String(++freshImportNonce));
+  if (!fresh) return await readInTurn(file, () => import(url.href));
+  // Node chooses the format again, as for the first import: a package's
+  // "type", the extension, or the source's syntax. The query names a new ES
+  // module. A CommonJS module also needs its cache entry gone.
+  url.searchParams.set('astryx-fresh', String(++freshImportNonce));
+  return await readFreshInTurn(file, () => import(url.href));
+}
+
+/**
+ * The name Node's CommonJS cache gives `file`: its real path, so a link and
+ * its target name one entry. A file that does not resolve keeps its path.
+ * @param {string} file absolute path
+ * @returns {string}
+ */
+function cacheKey(file) {
+  try {
+    return requireFromHere.resolve(file);
+  } catch {
+    return file;
   }
-  return await import(url.href);
+}
+
+/**
+ * Each file's latest read, by its cache name, settled once that read ends.
+ * @type {Map<string, Promise<void>>}
+ */
+const readsInProgress = new Map();
+
+/**
+ * Run `read`, an import of `file`, once the imports of `file` started before
+ * it have ended. Imports of other files do not wait. A fresh read removes the
+ * file from Node's CommonJS cache. A CommonJS import still in progress needs
+ * that entry until it ends.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readInTurn(file, read) {
+  const key = cacheKey(file);
+  const before = readsInProgress.get(key) ?? Promise.resolve();
+  const result = before.then(read);
+  const ended = result.then(
+    () => {},
+    () => {},
+  );
+  readsInProgress.set(key, ended);
+  void ended.then(() => {
+    if (readsInProgress.get(key) === ended) readsInProgress.delete(key);
+  });
+  return result;
+}
+
+/**
+ * Run `read`, a fresh import of `file`, in the file's turn (`readInTurn`),
+ * once the file is gone from Node's CommonJS cache. A new URL names a new ES
+ * module only, so a CommonJS module also needs its cache entry gone.
+ * @template T
+ * @param {string} file absolute path
+ * @param {() => Promise<T>} read
+ * @returns {Promise<T>}
+ */
+export function readFreshInTurn(file, read) {
+  return readInTurn(file, () => {
+    delete requireFromHere.cache[cacheKey(file)];
+    return read();
+  });
 }
 
 

package/foundation/render/charts.d.mts

@@ -0,0 +1,59 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The size a ResponsiveContainer starts at: its own numbers where it has
+ * them. Otherwise the width follows the height: six times it for a
+ * sparkline, which sits in a narrow card or a table cell, and two and a half
+ * times it for a taller chart. The drawing then scales to the width the
+ * page gives it, so its text stays near its own size in most layouts.
+ * @param {{width?: unknown, height?: unknown, aspect?: unknown}} props
+ * @returns {{width: number, height: number}}
+ */
+export function chartSize({ width, height, aspect }: {
+    width?: unknown;
+    height?: unknown;
+    aspect?: unknown;
+}): {
+    width: number;
+    height: number;
+};
+/**
+ * Mark each container chart whose legend is vertical and on one side with
+ * that side, and whether it sits at the bottom or the middle, for
+ * {@link CHART_CSS}. A vertically centered legend has a `top` near the
+ * middle (no room is kept for it in a container chart). A vertical legend
+ * centered across takes its own row, as a horizontal one does.
+ * @param {any} root the element the charts were drawn in
+ */
+export function markLegends(root: any): void;
+/**
+ * Give this thread the small document a chart draws in: no layout, no
+ * motion, and no frames to wait for.
+ * @returns {Promise<void>}
+ */
+export function chartDocument(): Promise<void>;
+/**
+ * @file Charts in a rendered page. A recharts chart draws only after its
+ * effects run, and a ResponsiveContainer measures its parent in a browser, so
+ * a server render leaves them empty. The render worker draws each one again
+ * in a small document, at the size the container starts at, and puts the
+ * drawing in its place.
+ *
+ * @input The chart elements the server render set aside.
+ * @output Their markup, and the CSS that lets a drawn chart fit its width.
+ * @position foundation/render — read by page-worker.mjs and render-page.mjs.
+ */
+/** The global the render worker installs to set charts aside. SYNC: page-worker.mjs assigns it by this name. */
+export const CHART_GLOBAL: "__astryxRenderChart";
+/** The recharts exports that draw a chart, besides ResponsiveContainer. */
+export const CHART_ROOTS: Set<string>;
+/**
+ * A chart drawn at its starting size scales to the width the page gives it
+ * and keeps its shape, so it never overflows its card. Its legend stays out
+ * of the scaled picture, so its text never covers the chart however narrow
+ * the page is. A horizontal legend takes its own row under the picture, or
+ * above it when it asks for the top. A vertical legend on one side sits
+ * beside the picture, on that side.
+ */
+export const CHART_CSS: string;