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

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
@@ -282,7 +282,7 @@ useOverlay useOverlay Overlay/useOverlay.doc.mjs Overlay/useOverlay.tsx
 useOwnScrollGesture useOwnScrollGesture DateInput/DateInput.doc.mjs DateInput/useOwnScrollGesture.ts
 usePager usePager hooks/useAnimatedLayout.doc.mjs hooks/usePager.ts
 usePointerDragScroll usePointerDragScroll DateInput/DateInput.doc.mjs DateInput/usePointerDragScroll.ts
-usePowerSearchConfig usePowerSearchConfig PowerSearch/PowerSearch.doc.mjs PowerSearch/usePowerSearchConfig.ts
+usePowerSearchConfig usePowerSearchConfig PowerSearch/usePowerSearchConfig.doc.mjs PowerSearch/usePowerSearchConfig.ts
 usePowerSearchSource usePowerSearchSource PowerSearch/PowerSearch.doc.mjs PowerSearch/usePowerSearchSource.ts
 useRenamedProp useRenamedProp hooks/useAnimatedLayout.doc.mjs hooks/useRenamedProp.ts
 useResolvedRequired useResolvedRequired hooks/useAnimatedLayout.doc.mjs hooks/useResolvedRequired.ts

package/assets/docs/styling-overview.doc.mjs

@@ -90,7 +90,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          label: 'Install (add to an existing Tailwind v4 app)',
+          label: 'Install',
           code: '{@pm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral}',
         },
         {
@@ -113,7 +113,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',
+          text: 'A project with Tailwind already set up needs a smaller change, which {@link generic:tailwind} shows. For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',
         },
       ],
     },
@@ -162,7 +162,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: '`{@command swizzle <Component>}` writes an `astryx-swizzle.json` marker into an output folder it owns (one the copy creates, an empty one, or one it marked before); every module under that folder then compiles as Astryx source, so keep copies in a folder of their own, such as the default `components/astryx`. For a folder that already holds other files it writes no marker and says how to add one by hand. With `@astryxdesign/build`\'s Babel, PostCSS and Vite integrations, or `withAstryx()` under webpack, a copy under that folder compiles into `astryx-base`, below `astryx-theme`, so theme component overrides reach it as they reach the package component. Under Turbopack, and with the stock StyleX plugins above, a copy\'s rules land in your own styles, above `astryx-theme`, and theme component overrides do not reach it.',
+          text: "`{@command swizzle <Component>}` writes an `astryx-swizzle.json` marker into an output folder it owns (one the copy creates, an empty one, or one it marked before); every module under that folder then compiles as Astryx source, so keep copies in a folder of their own, such as the default `components/astryx`. For a folder that already holds other files it writes no marker and says how to add one by hand. With `@astryxdesign/build`'s Babel, PostCSS and Vite integrations, or `withAstryx()` under webpack, a copy under that folder compiles into `astryx-base`, below `astryx-theme`, so theme component overrides reach it as they reach the package component. Under Turbopack, and with the stock StyleX plugins above, a copy's rules land in your own styles, above `astryx-theme`, and theme component overrides do not reach it.",
         },
       ],
     },

package/assets/docs/tree/tailwind.doc.mjs

@@ -19,6 +19,8 @@ export const docs = {
     'tailwind-theme.css',
     'utility classes',
     'preflight',
+    'existing Tailwind app',
+    'cascade layer order',
   ],
 
   sections: [
@@ -69,7 +71,45 @@ import {themes, defaultThemeSlug} from './astryx-themes';`,
         },
         {
           type: 'prose',
-          text: 'The Tailwind bridge is the concrete example of the general interop pattern: expose another library\'s semantic API, but point the values at system token variables.',
+          text: "The Tailwind bridge is the concrete example of the general interop pattern: expose another library's semantic API, but point the values at system token variables.",
+        },
+      ],
+    },
+    {
+      title: 'Add Astryx to an app that already uses Tailwind',
+      content: [
+        {
+          type: 'prose',
+          text: 'The recipe in the Tailwind section is a whole `globals.css` for a new app. An app that already uses Tailwind keeps its own file: its `@import "tailwindcss"`, its `@theme` mapping, and its `:root` variables stay as they are. Add one `@layer` line above the Tailwind import and the Astryx stylesheets below it.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'globals.css (existing Tailwind app)',
+          code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
+
+@import "tailwindcss"; /* the app's own entry, unchanged */
+@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
+@import "@astryxdesign/theme-neutral/theme.css";
+
+/* The app's own @theme and :root rules stay below, unchanged. */`,
+        },
+        {
+          type: 'prose',
+          text: "This recipe leaves out `tailwind-theme.css`. The bridge maps Tailwind theme names to system tokens, including Tailwind's own defaults such as `rounded-lg` and `shadow-md`, so in an existing app it changes what the app's own classes paint. Add it only when the app does not use the names it maps.",
+        },
+        {
+          type: 'prose',
+          text: "Astryx's theme defines its own CSS custom properties (color, spacing, radius, shadow, font, motion and more), and {@link namespace:tokens} has the full list. An app token with one of those names collides in one of two ways. An app `@theme` key takes Astryx's value, because `astryx.css` sets the tokens on `:root` above Tailwind's `theme` layer: with `@theme { --spacing-4: 1.5rem }`, the app's `gap-4` stays 16px. Marking the block `@theme inline` keeps the app's value in its utilities. An app `:root` variable replaces Astryx's value, so Astryx's own components change: `:root { --spacing-4: 1.5rem }` widens Astryx's spacing step 4 from 16px to 24px. Where the root Theme component sets a token again, such as `--color-warning`, the app's own rules inside it read Astryx's value instead. Rename any app token that shares a name.",
+        },
+        {
+          type: 'prose',
+          text: "Put the `@layer` line above the app's `@import \"tailwindcss\"`, never below it. A `@layer` statement orders only the layer names the page has not seen yet, and the Tailwind import names `theme`, `base`, `components`, and `utilities` as it loads. Below that import, the statement can only add `reset`, `astryx-base`, and `astryx-theme` after Tailwind's `utilities`. That inverts the cascade: the Astryx reset then outranks every utility class in the app, and, for example, removes the borders and padding the app's utilities give its controls. Nothing reports it: the build and the browser console stay clean, and the `@layer` line still looks right in the source, so only the rendered page shows the problem.",
+        },
+        {
+          type: 'prose',
+          text: 'The load-order rule from the Tailwind section still applies: `globals.css` must be the first stylesheet the page loads, so its `@layer` line names the layers first.',
         },
       ],
     },

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

@@ -152,7 +152,7 @@ const denseTheme = defineTheme({
       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 browsers without the keyword see no change. There is nothing to turn on: no theme option, prop or document attribute.",
+          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',

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/PowerSearch/usePowerSearchConfigHookUsage.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: 'usePowerSearchConfig',
+  name: 'usePowerSearchConfig — Filtered Directory Table',
+  displayName: 'usePowerSearchConfig — Filtered Directory Table',
+  description:
+    'A people directory with a PowerSearch bar over a Table: typed field definitions feed usePowerSearchConfig, returning the search config and an applyFilters helper that updates Table rows.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['PowerSearch', 'Table', 'Layout'],
+};

package/assets/templates/blocks/components/PowerSearch/usePowerSearchConfigHookUsage.tsx

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {VStack} from '@astryxdesign/core/Layout';
+import {
+  PowerSearch,
+  usePowerSearchConfig,
+} from '@astryxdesign/core/PowerSearch';
+import type {PowerSearchFilter} from '@astryxdesign/core/PowerSearch';
+import {Table} from '@astryxdesign/core/Table';
+import type {TableColumn} from '@astryxdesign/core/Table';
+
+const statusValues = [
+  {value: 'active', label: 'Active'},
+  {value: 'on-leave', label: 'On Leave'},
+  {value: 'contractor', label: 'Contractor'},
+];
+
+const fieldDefs = [
+  {key: 'name', type: 'string', label: 'Name'},
+  {key: 'status', type: 'enum', label: 'Status', enumValues: statusValues},
+  {key: 'startDate', type: 'date', label: 'Start date'},
+] as const;
+
+interface Person extends Record<string, unknown> {
+  id: string;
+  name: string;
+  status: string;
+  startDate: number;
+}
+
+const people: Person[] = [
+  {id: '1', name: 'Alice Chen', status: 'active', startDate: 1672531200},
+  {id: '2', name: 'Bob Dylan', status: 'on-leave', startDate: 1680307200},
+  {id: '3', name: 'Charlie Kim', status: 'active', startDate: 1688169600},
+  {id: '4', name: 'Dana Scully', status: 'contractor', startDate: 1696118400},
+  {id: '5', name: 'Evan Wright', status: 'active', startDate: 1704067200},
+];
+
+const columns: TableColumn<Person>[] = [
+  {key: 'name', header: 'Name'},
+  {
+    key: 'status',
+    header: 'Status',
+    renderCell: (person: Person) =>
+      statusValues.find(s => s.value === person.status)?.label ?? person.status,
+  },
+  {
+    key: 'startDate',
+    header: 'Start Date',
+    renderCell: (person: Person) =>
+      new Date(person.startDate * 1000).toLocaleDateString('en-US', {
+        timeZone: 'UTC',
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      }),
+  },
+];
+
+export default function UsePowerSearchConfigHookUsage() {
+  const [filters, setFilters] = useState<PowerSearchFilter[]>([]);
+  const {config, applyFilters} = usePowerSearchConfig(
+    fieldDefs,
+    'PeopleDirectory',
+  );
+  const filteredPeople = applyFilters(filters, people);
+
+  return (
+    <VStack gap={4}>
+      <PowerSearch
+        config={config}
+        filters={filters}
+        onChange={newFilters => setFilters([...newFilters])}
+        placeholder="Filter directory by name, status, start date..."
+        resultCount={filteredPeople.length}
+      />
+      <Table data={filteredPeople} columns={columns} idKey="id" hasHover />
+    </VStack>
+  );
+}

package/clients/cli/lib/resolve-theme.mjs

@@ -73,11 +73,22 @@ function extractTheme(mod) {
   return null;
 }
 
+/**
+ * Print a theme warning as one inert line. The configured theme value and the
+ * generated record come from the checkout, so a newline, an escape sequence or
+ * a bidi override in them must not rewrite the terminal. Control and format
+ * characters print as U+FFFD.
+ * @param {string} message
+ */
+function warnTheme(message) {
+  console.warn(message.replace(/[\p{Cc}\p{Cf}]/gu, '\uFFFD'));
+}
+
 /** @param {unknown} mod @param {string} specifier */
 function resolvedThemeData(mod, specifier) {
   const theme = extractTheme(mod);
   if (!theme) {
-    console.warn(
+    warnTheme(
       `⚠ theme: loaded "${specifier}" but could not find a theme object`,
     );
     return null;
@@ -100,7 +111,7 @@ export async function resolveTheme(cwd = process.cwd()) {
   const loaded = await resolveRecordedTheme(cwd);
   if (loaded.configured) {
     if (!loaded.module) {
-      console.warn(
+      warnTheme(
         `⚠ theme: ${loaded.problem ?? `could not resolve the generated default theme (${loaded.specifier})`}`,
       );
       return null;
@@ -130,15 +141,13 @@ export async function resolveTheme(cwd = process.cwd()) {
   if (specifier.startsWith('.') || specifier.startsWith('/')) {
     mod = tryLoadLegacyModule(specifier, cwd);
     if (!mod) {
-      console.warn(
-        `⚠ theme: could not resolve file "${specifier}" from ${cwd}`,
-      );
+      warnTheme(`⚠ theme: could not resolve file "${specifier}" from ${cwd}`);
       return null;
     }
   } else if (specifier.startsWith('@')) {
     mod = tryLoadLegacyModule(specifier, cwd);
     if (!mod) {
-      console.warn(`⚠ theme: could not resolve package "${specifier}"`);
+      warnTheme(`⚠ theme: could not resolve package "${specifier}"`);
       return null;
     }
   } else {
@@ -147,7 +156,7 @@ export async function resolveTheme(cwd = process.cwd()) {
       tryLoadLegacyModule(conventional, cwd) ??
       tryLoadLegacyModule(specifier, cwd);
     if (!mod) {
-      console.warn(
+      warnTheme(
         `⚠ theme: could not resolve "${specifier}" (tried ${conventional} and ${specifier})`,
       );
       return null;

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/package.json

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