@astryxdesign/cli 0.7.12-canary.c08de54 → 0.7.12-canary.c5cc8f4

package/api/component/__fixtures__/resolutions/modules.txt

@@ -271,7 +271,7 @@ useIsomorphicLayoutEffect useIsomorphicLayoutEffect hooks/useAnimatedLayout.doc.
 useLayerDismissal useLayerDismissal Layer/Layer.doc.mjs Layer/useLayerDismissal.ts
 useLightbox useLightbox Lightbox/useLightbox.doc.mjs Lightbox/useLightbox.tsx
 useLinkComponent useLinkComponent Link/useLinkComponent.doc.mjs Link/useLinkComponent.ts
-useLinkify useLinkify Link/Link.doc.mjs Link/useLinkify.tsx
+useLinkify useLinkify Link/useLinkify.doc.mjs Link/useLinkify.tsx
 useListFormatter useListFormatter i18n/InternationalizationProvider.doc.mjs i18n/useListFormatter.ts
 useMenuDrillIn useMenuDrillIn DropdownMenu/DropdownMenu.doc.mjs DropdownMenu/useMenuDrillIn.tsx
 useMenuHover useMenuHover hooks/useAnimatedLayout.doc.mjs hooks/useMenuHover.ts
@@ -298,7 +298,7 @@ useSpeechRecognition useSpeechRecognition Chat/Chat.doc.mjs Chat/useSpeechRecogn
 useSwipeAction useSwipeAction Item/Item.doc.mjs Item/useSwipeAction.ts
 useSwitchTouch useSwitchTouch Switch/Switch.doc.mjs Switch/useSwitchTouch.ts
 useTableCellStyles useTableCellStyles Table/Table.doc.mjs Table/useTableCellStyles.ts
-useTableColumnSettingsState useTableColumnSettingsState Table/Table.doc.mjs Table/plugins/columnSettings/useTableColumnSettingsState.tsx
+useTableColumnSettingsState useTableColumnSettingsState Table/plugins/columnSettings/useTableColumnSettingsState.doc.mjs Table/plugins/columnSettings/useTableColumnSettingsState.tsx
 useTableSortableState useTableSortableState Table/plugins/sortable/useTableSortableState.doc.mjs Table/plugins/sortable/useTableSortableState.tsx
 useToastGesture useToastGesture Toast/Toast.doc.mjs Toast/useToastGesture.ts
 useTouchTrigger useTouchTrigger Layer/Layer.doc.mjs Layer/useTouchTrigger.ts

package/api/template/template.mjs

@@ -193,6 +193,7 @@ export async function template(name, options = {}) {
       `Unknown template "${name}"`,
       orderByAffinity(name, templates, t => [t.dirName, t.name], {
         closest: true,
+        typos: true,
       }).map(t => ({
         name: t.dirName,
         reason: `${t.type} template`,

package/assets/discover/official-packages.json

@@ -260,6 +260,10 @@
           "kind": "template",
           "name": "CommentThreadShowcase"
         },
+        {
+          "kind": "template",
+          "name": "DialogHeroHeaderShowcase"
+        },
         {
           "kind": "template",
           "name": "DiffViewerShowcase"

package/assets/docs/tree/type-scale.doc.mjs

@@ -2,7 +2,8 @@
 
 /**
  * @file `astryx docs typography/type-scale`: line height, semantic type scale,
- * display text, headings and text components, and custom type scales.
+ * display text, headings and text components, custom type scales, and the
+ * reader's text size on iOS.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -14,13 +15,15 @@ export const docs = {
   placement: {parent: 'namespace:typography', slot: 'guides', order: 20},
   category: 'foundations',
   description:
-    'Line height, semantic type scale tokens, display text, Heading and Text components, and custom type scales via defineTheme.',
+    "Line height, semantic type scale tokens, display text, Heading and Text components, custom type scales via defineTheme, and following the reader's text size on iOS.",
   keywords: [
     'line height',
     'leading',
     'defineTheme',
     'base',
     'ratio',
+    'dynamic type',
+    'text size',
   ],
 
   sections: [
@@ -143,5 +146,19 @@ const denseTheme = defineTheme({
         },
       ],
     },
+    {
+      id: 'dynamic-type',
+      title: "Following the reader's text size on iOS",
+      content: [
+        {
+          type: 'prose',
+          text: "On iPhone, readers pick a text size in Settings (Display & Text Size, then Larger Text), and native apps grow or shrink their text with it. Every theme does the same in Safari on iPhone, which exposes that choice through `font: -apple-system-body`: each font size follows the reader's choice on the curve of the iOS text style it plays, so body text scales like Body, `heading-1` like Title 1 and display text like Large Title, and every role keeps its order. A size the theme fixes at a length, such as a 12px supporting size, scales on the curve of the step it reads by default; a size in `em` or `%` follows its parent, and one that reads a variable follows that variable. At the default size every font size is the theme's own. The family, spacing, radius and the root font size never change, line heights keep their ratios, text inputs keep their 16px floor on iOS, and on Android the system font scale grows every font size through `env(preferred-text-scale)` where the browser reports it; browsers with neither see no change. There is nothing to turn on: no theme option, prop or document attribute.",
+        },
+        {
+          type: 'prose',
+          text: 'Fixed-height controls such as the text inputs keep their height, so their text can overflow at the accessibility sizes. A labelled `Button` grows with its label.',
+        },
+      ],
+    },
   ],
 };

package/assets/templates/blocks/components/Hooks/useInteractiveRoleHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useInteractiveRole',
+  name: 'useInteractiveRole — One Tile, Four Roles',
+  displayName: 'useInteractiveRole — One Tile, Four Roles',
+  description:
+    'A polymorphic Tile used four ways: with an href it renders as a link, with an onClick as a button, with neither as plain content, and placed as a Popover trigger it becomes the trigger button through context — the resolution order in one place.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Popover', 'Card', 'Text', 'Layout', 'Link'],
+};

package/assets/templates/blocks/components/Hooks/useInteractiveRoleHookUsage.tsx

@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useInteractiveRole} from '@astryxdesign/core/hooks';
+import {Link} from '@astryxdesign/core/Link';
+import {Popover} from '@astryxdesign/core/Popover';
+import {Card} from '@astryxdesign/core/Card';
+import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
+
+// A polymorphic Tile: the hook alone decides what it renders as — href wins,
+// then onClick, then a trigger context (Popover), then inert.
+function Tile({
+  href,
+  onClick,
+  children,
+}: {
+  href?: string;
+  onClick?: () => void;
+  children: React.ReactNode;
+}) {
+  const role = useInteractiveRole({href, onClick});
+  const body = (
+    <Card padding={3} width={200}>
+      <Text type="body">{children}</Text>
+    </Card>
+  );
+  switch (role) {
+    case 'link':
+      return <Link href={href}>{body}</Link>;
+    case 'button':
+      return <button onClick={onClick}>{body}</button>;
+    default:
+      return body;
+  }
+}
+
+export default function UseInteractiveRoleHookUsage() {
+  return (
+    <VStack gap={3} hAlign="center" style={{width: '100%'}}>
+      <Tile href="https://example.com/docs">Renders as a link</Tile>
+      <Tile onClick={() => {}}>Renders as a button</Tile>
+      <Popover
+        label="Tile details"
+        content={
+          <Card padding={3}>
+            <Text type="body">Opened through the tile's context role</Text>
+          </Card>
+        }>
+        <Tile>Trigger via context</Tile>
+      </Popover>
+      <Tile>Plain content</Tile>
+    </VStack>
+  );
+}

package/assets/templates/blocks/components/Hooks/useStreamingTextHookUsage.doc.mjs

@@ -7,8 +7,8 @@ export const doc = {
   name: 'useStreamingText — Streaming Response',
   displayName: 'useStreamingText — Streaming Response',
   description:
-    'Smooth bursty generated text into a steady reveal with useStreamingText.',
+    'A chat-style reply card: while the response streams in bursts, useStreamingText reveals it steadily character by character; when streaming ends the full text snaps into place. Regenerate replays the stream.',
   isReady: true,
   aspectRatio: 4 / 3,
-  componentsUsed: ['Card', 'Text', 'Layout'],
+  componentsUsed: ['Button', 'Card', 'Text', 'Layout'],
 };

package/assets/templates/blocks/components/Hooks/useStreamingTextHookUsage.tsx

@@ -2,29 +2,85 @@
 
 'use client';
 
+import {useCallback, useEffect, useRef, useState} from 'react';
 import {useStreamingText} from '@astryxdesign/core/hooks';
+import {Button} from '@astryxdesign/core/Button';
 import {Card} from '@astryxdesign/core/Card';
-import {VStack} from '@astryxdesign/core/Layout';
 import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
+
+const CHUNKS = [
+  'Astryx hooks keep behavior reusable ',
+  'while components keep visuals consistent. ',
+  'Streaming text arrives in bursts; ',
+  'the hook smooths it into a steady reveal.',
+];
 
-const response =
-  'Astryx hooks keep behavior reusable while components keep visuals consistent.';
+// A fake stream: chunks land in bursts, the way a model streams tokens.
+// Starting again stops the stream in progress, and the last chunk ends it.
+function useFakeStream(onChunk: (chunk: string) => void, onEnd: () => void) {
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const start = useCallback(() => {
+    if (timer.current) {
+      clearTimeout(timer.current);
+    }
+    let index = 0;
+    const tick = () => {
+      onChunk(CHUNKS[index]);
+      index += 1;
+      if (index < CHUNKS.length) {
+        timer.current = setTimeout(tick, 350);
+      } else {
+        timer.current = null;
+        onEnd();
+      }
+    };
+    timer.current = setTimeout(tick, 350);
+  }, [onChunk, onEnd]);
+  useEffect(
+    () => () => {
+      if (timer.current) {
+        clearTimeout(timer.current);
+      }
+    },
+    [],
+  );
+  return start;
+}
 
 export default function UseStreamingTextHookUsage() {
-  const displayedText = useStreamingText(response, false, {
-    speed: 'fast',
-  });
+  const [target, setTarget] = useState('');
+  const [isStreaming, setIsStreaming] = useState(false);
+
+  const appendChunk = useCallback((chunk: string) => {
+    setTarget(previous => previous + chunk);
+  }, []);
+  // When the last chunk has landed, end the stream so the hook snaps to the
+  // full text.
+  const endStream = useCallback(() => setIsStreaming(false), []);
+  const startStream = useFakeStream(appendChunk, endStream);
+
+  const regenerate = useCallback(() => {
+    setTarget('');
+    setIsStreaming(true);
+    startStream();
+  }, [startStream]);
+
+  const displayedText = useStreamingText(target, isStreaming, {speed: 'fast'});
 
   return (
     <Card width={420} padding={4}>
-      <VStack gap={2}>
+      <VStack gap={3}>
         <Text type="body" weight="bold">
           Assistant response
         </Text>
         <Text type="body">{displayedText}</Text>
-        <Text type="supporting" color="secondary">
-          Complete
-        </Text>
+        <Button
+          label={isStreaming ? 'Streaming…' : 'Regenerate'}
+          variant="secondary"
+          size="sm"
+          onClick={regenerate}
+        />
       </VStack>
     </Card>
   );

package/assets/templates/blocks/components/Link/useLinkifyHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useLinkify',
+  name: 'useLinkify — Links in a Comment Thread',
+  displayName: 'useLinkify — Links in a Comment Thread',
+  description:
+    'Plain-text comments where useLinkify turns the URL and the email address into Links, and a custom pattern turns issue references like #123 into tracker links — the patterns option in action. The comment without matches stays plain text.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Link', 'Layout', 'Text'],
+};

package/assets/templates/blocks/components/Link/useLinkifyHookUsage.tsx

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useLinkify, type LinkifyPattern} from '@astryxdesign/core/Link';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+const COMMENTS = [
+  'See https://example.com/spec or email support@example.com.',
+  'Fixed by #123, tracking the regression in #456.',
+  'No links here, just a plain note.',
+];
+
+// Issue references like #123 link into the tracker; the capture group maps
+// onto its URL scheme, showing the patterns option.
+const ISSUE_PATTERN: LinkifyPattern = {
+  pattern: /#(\d+)/g,
+  href: match => `https://example.com/issues/${match[1]}`,
+};
+
+function Comment({children}: {children: string}) {
+  const nodes = useLinkify(children, {patterns: [ISSUE_PATTERN]});
+  return (
+    <Text type="body" color="secondary">
+      {nodes}
+    </Text>
+  );
+}
+
+export default function UseLinkifyHookUsage() {
+  return (
+    <VStack gap={3} style={{width: '100%', maxWidth: 360}}>
+      {COMMENTS.map(comment => (
+        <Comment key={comment}>{comment}</Comment>
+      ))}
+    </VStack>
+  );
+}

package/assets/templates/blocks/components/Table/RowsVirtualizationHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableRowsVirtualization',
+  name: 'useTableRowsVirtualization - Fixed Height Rows',
+  displayName: 'useTableRowsVirtualization - Fixed Height Rows',
+  description:
+    'A Table with 1,000 product rows in a fixed-height viewport. Scroll vertically to mount the visible rows. The caller keeps all data and columns; this hook does not virtualize columns.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Table'],
+};

package/assets/templates/blocks/components/Table/RowsVirtualizationHookUsage.tsx

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+  Table,
+  useTableRowsVirtualization,
+  type TableColumn,
+} from '@astryxdesign/core/Table';
+
+interface Product extends Record<string, unknown> {
+  id: string;
+  name: string;
+}
+
+const products: Product[] = Array.from({length: 1000}, (_, index) => ({
+  id: `product-${index}`,
+  name: `Product ${index + 1}`,
+}));
+const columns: TableColumn<Product>[] = [{key: 'name', header: 'Product'}];
+
+export default function RowsVirtualizationHookUsage() {
+  const virtualization = useTableRowsVirtualization({
+    rowHeight: 56,
+    viewportHeight: 320,
+  });
+  return (
+    <Table
+      data={products}
+      columns={columns}
+      idKey="id"
+      virtualization={virtualization}
+    />
+  );
+}

package/assets/templates/blocks/components/Table/useTableColumnSettingsStateHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableColumnSettingsState',
+  name: 'useTableColumnSettingsState — Column Visibility Picker',
+  displayName: 'useTableColumnSettingsState — Column Visibility Picker',
+  description:
+    'A Table toolbar with a Columns menu of checkboxes: toggling Email updates active columns, Reset restores defaults, and the config is passed directly to useTableColumnSettings.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Button', 'CheckboxInput', 'Popover', 'Table', 'Layout'],
+};

package/assets/templates/blocks/components/Table/useTableColumnSettingsStateHookUsage.tsx

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Popover} from '@astryxdesign/core/Popover';
+import {
+  Table,
+  useTableColumnSettings,
+  useTableColumnSettingsState,
+} from '@astryxdesign/core/Table';
+import type {TableColumn} from '@astryxdesign/core/Table';
+
+interface Member extends Record<string, unknown> {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+const members: Member[] = [
+  {id: '1', name: 'Alice', email: 'alice@example.com', role: 'Engineer'},
+  {id: '2', name: 'Bob', email: 'bob@example.com', role: 'Designer'},
+  {id: '3', name: 'Charlie', email: 'charlie@example.com', role: 'Manager'},
+];
+
+const allColumns: TableColumn<Member>[] = [
+  {key: 'name', header: 'Name'},
+  {key: 'email', header: 'Email'},
+  {key: 'role', header: 'Role'},
+];
+
+const columnOptions = [
+  {key: 'name' as const, label: 'Name', isAlwaysVisible: true},
+  {key: 'email' as const, label: 'Email'},
+  {key: 'role' as const, label: 'Role'},
+];
+
+const defaultKeys = ['name', 'email', 'role'];
+
+export default function UseTableColumnSettingsStateHookUsage() {
+  const [activeKeys, setActiveKeys] =
+    useState<ReadonlyArray<string>>(defaultKeys);
+
+  const state = useTableColumnSettingsState({
+    columns: columnOptions,
+    activeColumnKeys: activeKeys,
+    onChangeActiveColumnKeys: setActiveKeys,
+    defaultColumnKeys: defaultKeys,
+  });
+
+  const plugin = useTableColumnSettings<Member>(state.columnSettingsConfig);
+
+  return (
+    <VStack gap={3}>
+      <HStack hAlign="start">
+        <Popover
+          placement="below"
+          label="Column settings"
+          width={200}
+          content={
+            <VStack gap={2}>
+              {columnOptions.map(col => (
+                <CheckboxInput
+                  key={col.key}
+                  label={col.label}
+                  value={state.isColumnActive(col.key)}
+                  isDisabled={!state.isColumnToggleable(col.key)}
+                  onChange={() => state.toggleColumn(col.key)}
+                />
+              ))}
+              <Button
+                label="Reset"
+                size="sm"
+                variant="secondary"
+                onClick={state.resetToDefault}>
+                Reset
+              </Button>
+            </VStack>
+          }>
+          <Button label="Columns" size="sm">
+            Columns
+          </Button>
+        </Popover>
+      </HStack>
+      <Table
+        data={members}
+        columns={allColumns}
+        idKey="id"
+        plugins={{columnSettings: plugin}}
+      />
+    </VStack>
+  );
+}

package/assets/templates/themes/butter/butterTheme.ts

@@ -394,8 +394,7 @@ export const butterTheme = defineTheme({
       // Radius intentionally not pinned, so buttons keep core's
       // `var(--_button-radius, --radius-element)`: standalone buttons stay 8px,
       // while the chat composer (which sets --_button-radius) rounds them fully.
-      // Inline padding only: a labelled button's size is its minimum height,
-      // and block padding would add to it.
+      // Inline padding only. Button sets its own block padding and height.
       base: {
         paddingInline: 'var(--spacing-4)',
       },

package/foundation/discovery/hook-discovery.mjs

@@ -12,6 +12,13 @@ import {levenshteinDistance} from '../text/string-utils.mjs';
 
 const SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);
 
+// A hook's doc outside src/hooks/: a `use…` hook, or a `create…` factory
+// documented as one (its doc typed `HookDoc`, such as createReorderable).
+const HOOK_DOC_FILE_RE = /^(?:use|create)[A-Z]\w*\.doc\.mjs$/;
+
+// Matches the top-level `relatedHooks: [...]` field in a hook .doc.mjs file.
+const RELATED_HOOKS_RE = /(?:^|\n) {0,4}relatedHooks:\s*\[([^\]]*)\]/;
+
 // Matches the top-level `category: 'categoryName'` field in a hook .doc.mjs file.
 const CATEGORY_RE = /(?:^|\n) {0,4}category:\s*['"]([^'"]+)['"]/;
 
@@ -32,6 +39,25 @@ function readHookMeta(docPath) {
   }
 }
 
+/**
+ * Whether a `create…` factory's doc names its own `use…` hook in
+ * `relatedHooks`, as createAnimator's names useAnimator. Such a factory is
+ * listed beside that hook, not on its own.
+ * @param {string} docPath
+ * @param {string} hookName
+ * @returns {boolean}
+ */
+function isBesideOwnHook(docPath, hookName) {
+  if (!hookName.startsWith('create')) return false;
+  const ownHook = `use${hookName.slice('create'.length)}`;
+  try {
+    const related = RELATED_HOOKS_RE.exec(fs.readFileSync(docPath, 'utf-8'));
+    return related != null && related[1].includes(`'${ownHook}'`);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Extract the hook name from a doc filename.
  * e.g. 'useFocusTrap.doc.mjs' → 'useFocusTrap'
@@ -70,7 +96,8 @@ export function discoverHooks(coreDir) {
     }
   }
 
-  // 2. Scan ALL component directories for files matching use*.doc.mjs
+  // 2. Scan ALL component directories for hook docs: use*.doc.mjs, and
+  // create*.doc.mjs for a factory documented as a hook (createReorderable)
   if (pathExists(srcDir)) {
     const topEntries = listDirEntries(srcDir);
     for (const entry of topEntries) {
@@ -120,14 +147,10 @@ function scanDirForHookDocs(dirPath, hookCategories) {
   for (const entry of entries) {
     if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
       scanDirForHookDocs(path.join(dirPath, entry.name), hookCategories);
-    } else if (
-      entry.isFile() &&
-      entry.name.startsWith('use') &&
-      entry.name.endsWith('.doc.mjs')
-    ) {
+    } else if (entry.isFile() && HOOK_DOC_FILE_RE.test(entry.name)) {
       const hookName = hookNameFromFile(entry.name);
-      if (!hookCategories.has(hookName)) {
-        const docPath = path.join(dirPath, entry.name);
+      const docPath = path.join(dirPath, entry.name);
+      if (!hookCategories.has(hookName) && !isBesideOwnHook(docPath, hookName)) {
         const {category} = readHookMeta(docPath);
         hookCategories.set(hookName, category || 'Other');
       }

package/foundation/doc-compiler/import.mjs

@@ -24,6 +24,7 @@
 
 import {pathToFileURL} from 'node:url';
 import {createJiti} from 'jiti';
+import {importUrl} from '../fs/import-url.mjs';
 import {importUserModule} from '../fs/module-loader.mjs';
 import {fileStamp, recordContentRead} from '../fs/read-record.mjs';
 
@@ -105,14 +106,14 @@ export function importTemplateModule(file) {
         jsxJiti ??= createJiti(import.meta.url, {jsx: true});
         return jsxJiti.import(first);
       }
-      return import(`file://${first}`);
+      return importUrl(`file://${first}`);
     },
     changed =>
       changed.endsWith('.ts')
         ? createJiti(import.meta.url, {jsx: true, moduleCache: false}).import(
             changed,
           )
-        : import(freshUrl(changed)),
+        : importUrl(freshUrl(changed)),
   );
 }
 
@@ -126,7 +127,7 @@ export function importNativeModule(file) {
   return importCurrent(
     file,
     'native',
-    first => import(pathToFileURL(first).href),
-    changed => import(freshUrl(changed)),
+    first => importUrl(pathToFileURL(first).href),
+    changed => importUrl(freshUrl(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,17 @@ 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>;
 /**
  * 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,64 @@ 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 readInTurn(file, () => {
+    delete requireFromHere.cache[cacheKey(file)];
+    return 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;
 }
 
 

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

package/foundation/text/suggest-order.mjs

@@ -19,6 +19,12 @@
 
 import {levenshteinDistance} from './levenshtein.mjs';
 
+/**
+ * The score of a near name (nearNameSlips), less a little per slip: above any
+ * name that carries only some of the typed words, below one that carries all
+ * of them.
+ */
+const NEAR_NAME_SCORE = 19.6;
 /** The score a synonym match gets: an exact keyword's. */
 const SYNONYM_SCORE = 90;
 /** The score a name with exactly the typed words gets: an exact name's. */
@@ -59,17 +65,22 @@ export function nameWords(text) {
  * closer. Tiers, best first: the same words; every typed word present; some
  * typed word present; none. Within a tier, more of the typed words and more of
  * the candidate's own words matched rank higher, and a name that starts with
- * the typed name (or the reverse) gets a small lift.
+ * the typed name (or the reverse) gets a small lift. With `typos`, a near name
+ * (one or two slips from the typed name) ranks just below the names that
+ * carry every typed word.
  * @param {string[]} typed - {@link nameWords} of the typed name
  * @param {string} name
+ * @param {{typos?: boolean}} [options]
  * @returns {number}
  */
-function affinityOf(typed, name) {
+function affinityOf(typed, name, {typos = false} = {}) {
   const words = nameWords(name);
   if (typed.length === 0 || words.length === 0) return 0;
   const typedJoined = typed.join('');
   const joined = words.join('');
   if (joined === typedJoined) return 40;
+  const slips = typos ? nearNameSlips(typedJoined, joined) : 0;
+  const near = slips > 0 ? NEAR_NAME_SCORE - slips * 0.2 : 0;
   const have = new Set(words);
   const want = new Set(typed);
   const covered = typed.filter(w => have.has(w)).length / typed.length;
@@ -77,7 +88,29 @@ function affinityOf(typed, name) {
   const prefix =
     joined.startsWith(typedJoined) || typedJoined.startsWith(joined) ? 1 : 0;
   const tier = covered === 1 ? 2 : covered > 0 ? 1 : 0;
-  return tier * 10 + covered * 4 + precise * 2 + prefix + precise * 0.01;
+  // A near name keeps its word score when that is higher: a name that also
+  // carries every typed word ranks among the other full matches.
+  return Math.max(
+    near,
+    tier * 10 + covered * 4 + precise * 2 + prefix + precise * 0.01,
+  );
+}
+
+/**
+ * How many slips separate a typed name from a candidate, both with their
+ * words joined, when it is a near name: an edit or two adjacent letters
+ * swapped count as one slip, one slip is allowed from five letters and two from
+ * eight. Zero when it is not a near name.
+ * @param {string} typed
+ * @param {string} name
+ * @returns {number}
+ */
+function nearNameSlips(typed, name) {
+  const shorter = Math.min(typed.length, name.length);
+  const cap = shorter >= 8 ? 2 : shorter >= 5 ? 1 : 0;
+  if (cap === 0 || Math.abs(typed.length - name.length) > cap) return 0;
+  const slips = levenshteinDistance(typed, name, cap, {swaps: true});
+  return slips <= cap ? slips : 0;
 }
 
 /**
@@ -87,14 +120,15 @@ function affinityOf(typed, name) {
  * @param {string} typedName
  * @param {T[]} items
  * @param {(item: T) => Array<string | undefined>} namesOf
+ * @param {{typos?: boolean}} [options]
  * @returns {Array<{item: T, best: number}>}
  */
-function scoreByAffinity(typedName, items, namesOf) {
+function scoreByAffinity(typedName, items, namesOf, options = {}) {
   const typed = nameWords(typedName);
   const scored = items.map((item, index) => {
     let best = 0;
     for (const name of namesOf(item)) {
-      if (name) best = Math.max(best, affinityOf(typed, name));
+      if (name) best = Math.max(best, affinityOf(typed, name, options));
     }
     return {item, index, best};
   });
@@ -112,14 +146,46 @@ function scoreByAffinity(typedName, items, namesOf) {
  * 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(typedName, items, namesOf, options = {}) {
+  if (!options.typos) return orderByWords(typedName, items, namesOf, options);
+  const scored = scoreByAffinity(typedName, items, namesOf, {typos: true});
+  if (!options.closest) return scored.map(s => s.item);
+  const kept = new Set(orderByWords(typedName, items, namesOf, options));
+  return scored
+    .filter(s => kept.has(s.item) || isNearScore(s.best))
+    .slice(0, kept.size)
+    .map(s => s.item);
+}
+
+/**
+ * Whether a score is a near name's.
+ * @param {number} score
+ */
+const isNearScore = score => score < 20 && score > NEAR_NAME_SCORE - 1;
+
+/**
+ * {@link orderByAffinity} without `typos`.
+ * @template T
+ * @param {string} typedName
+ * @param {T[]} items
+ * @param {(item: T) => Array<string | undefined>} namesOf
+ * @param {{closest?: boolean}} options
+ * @returns {T[]}
+ */
+function orderByWords(typedName, items, namesOf, options) {
   const scored = scoreByAffinity(typedName, items, namesOf);
   if (!options.closest) return scored.map(s => s.item);
   // One-letter words (`a` in `a11y`, `use-a-theme`) say nothing about which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.7.12-canary.c08de54",
+  "version": "0.7.12-canary.c5cc8f4",
   "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.c08de54"
+    "@astryxdesign/core": "0.7.12-canary.c5cc8f4"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -133,10 +133,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.12-canary.c08de54",
-    "@astryxdesign/core": "0.7.12-canary.c08de54",
-    "@astryxdesign/lab": "0.7.12-canary.c08de54",
-    "@astryxdesign/theme-neutral": "0.7.12-canary.c08de54",
+    "@astryxdesign/charts": "0.7.12-canary.c5cc8f4",
+    "@astryxdesign/core": "0.7.12-canary.c5cc8f4",
+    "@astryxdesign/lab": "0.7.12-canary.c5cc8f4",
+    "@astryxdesign/theme-neutral": "0.7.12-canary.c5cc8f4",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",